claude-code-session-manager 0.75.3 → 0.77.0

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

@@ -0,0 +1,103 @@
+/**
+ * prdAgentType.test.cjs — the PRD `agentType` FK (lib/prdAgentType.cjs):
+ * throw on write, report on read, mirroring agentModelResolve.cjs's/
+ * epicMint.cjs's established convention for the Epic-level agentType FK.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdAgentType.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const {
+  DEFAULT_PRD_AGENT_TYPE,
+  assertAgentTypeWritable,
+  reportDanglingAgentTypeOnce,
+} = require('../lib/prdAgentType.cjs');
+const { todayFile } = require('../lib/opsErrorLog.cjs');
+
+async function mkTmpDir(prefix) {
+  return fsp.mkdtemp(path.join(os.tmpdir(), prefix));
+}
+
+test('DEFAULT_PRD_AGENT_TYPE is dev-lead', () => {
+  expect(DEFAULT_PRD_AGENT_TYPE).toBe('dev-lead');
+});
+
+test('assertAgentTypeWritable is a no-op when agentType is omitted', async () => {
+  await expect(assertAgentTypeWritable('/some/cwd', null)).resolves.toBeUndefined();
+  await expect(assertAgentTypeWritable('/some/cwd', undefined)).resolves.toBeUndefined();
+  await expect(assertAgentTypeWritable('/some/cwd', '')).resolves.toBeUndefined();
+});
+
+test('assertAgentTypeWritable resolves without throwing when a project-overlay persona file exists', async () => {
+  const cwd = await mkTmpDir('sm-prd-agenttype-');
+  try {
+    const agentsDir = path.join(cwd, '.claude', 'agents');
+    await fsp.mkdir(agentsDir, { recursive: true });
+    await fsp.writeFile(path.join(agentsDir, 'my-persona.md'), '---\nname: my-persona\n---\nbody\n', 'utf8');
+    await expect(assertAgentTypeWritable(cwd, 'my-persona')).resolves.toBeUndefined();
+  } finally {
+    await fsp.rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('assertAgentTypeWritable rejects an unknown persona name, naming available personas in the error', async () => {
+  const cwd = await mkTmpDir('sm-prd-agenttype-');
+  try {
+    await expect(
+      assertAgentTypeWritable(cwd, 'zzz-definitely-not-a-real-persona-12345'),
+    ).rejects.toThrow(/does not resolve to a readable persona file/);
+    await expect(
+      assertAgentTypeWritable(cwd, 'zzz-definitely-not-a-real-persona-12345'),
+    ).rejects.toThrow(/Available personas/);
+  } finally {
+    await fsp.rm(cwd, { recursive: true, force: true });
+  }
+});
+
+// READ side of the FK, mirroring agentModelResolve.test.cjs's sibling test
+// for the Epic-level FK: verify against the REAL opsErrorLog write path
+// (todayFile), not a mock — a plain mkdtemp() cwd is not "ephemeral"
+// (ephemeralCwd.cjs only refuses os.tmpdir() itself / managed worktree
+// roots), so appendError writes a real line here.
+test('reportDanglingAgentTypeOnce logs once via opsErrorLog when the persona does not resolve, and never throws', async () => {
+  const cwd = await mkTmpDir('sm-prd-agenttype-log-');
+  try {
+    expect(() => {
+      reportDanglingAgentTypeOnce(cwd, 'ghost-persona-xyz', { personaExists: () => false });
+      reportDanglingAgentTypeOnce(cwd, 'ghost-persona-xyz', { personaExists: () => false });
+    }).not.toThrow();
+
+    const lines = fs.readFileSync(todayFile(cwd), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    const matches = lines.filter((l) => l.message.includes('ghost-persona-xyz'));
+    // Logged once despite two calls above — dedup key is (cwd, agentType).
+    expect(matches).toHaveLength(1);
+    expect(matches[0].level).toBe('warn');
+    expect(matches[0].scope).toBe('prdAgentType');
+  } finally {
+    await fsp.rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reportDanglingAgentTypeOnce is a no-op when the persona resolves', async () => {
+  const cwd = await mkTmpDir('sm-prd-agenttype-log-');
+  try {
+    reportDanglingAgentTypeOnce(cwd, 'real-persona', { personaExists: () => true });
+    expect(fs.existsSync(todayFile(cwd))).toBe(false);
+  } finally {
+    await fsp.rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test('reportDanglingAgentTypeOnce is a no-op when cwd or agentType is missing', () => {
+  expect(() => {
+    reportDanglingAgentTypeOnce(null, 'x', { personaExists: () => false });
+    reportDanglingAgentTypeOnce('/some/cwd-missing-agenttype', null, { personaExists: () => false });
+  }).not.toThrow();
+});

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

@@ -15,6 +15,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const http = require('node:http');
+const { execFileSync } = require('node:child_process');
 const {
   deriveSlugFromTitle,
   buildPrdBody,
@@ -79,6 +80,23 @@ test('buildPrdBody emits required frontmatter keys and body sections in order',
   expect(body.includes('Lay out hot data contiguously')).toBeFalsy();
 });
 
+test('buildPrdBody emits agentType: dev-lead by default when omitted (PRD 1114)', () => {
+  const body = buildPrdBody({
+    title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
+    acceptanceCriteria: ['a'], implementationNotes: 'n',
+  });
+  expect(body).toMatch(/^agentType: dev-lead$/m);
+});
+
+test('buildPrdBody emits the supplied agentType instead of the default', () => {
+  const body = buildPrdBody({
+    title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
+    acceptanceCriteria: ['a'], implementationNotes: 'n',
+    agentType: 'architect',
+  });
+  expect(body).toMatch(/^agentType: architect$/m);
+});
+
 test('buildPrdBody omits parallelGroup frontmatter key when not supplied', () => {
   const body = buildPrdBody({
     title: 't', cwd: '~/x', estimateMinutes: 5, goal: 'g',
@@ -529,6 +547,56 @@ test('POST /admin/scheduler/create-prd with tag writes it into the created PRD f
   }
 });
 
+// ──────────────────────────────────────────── PRD 1114: agentType (WHO
+// executes a PRD) — throw on write for an unresolvable persona, default to
+// dev-lead when omitted.
+
+test('createPrd rejects an unknown agentType at write time, naming available personas, and writes no file', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+  const writePrdSpy = vi.fn(remote.writePrd);
+  remote.writePrd = writePrdSpy;
+
+  const result = await createPrd(
+    validCreateBody({ agentType: 'zzz-definitely-not-a-real-persona-12345' }),
+    remote,
+  );
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(400);
+  expect(result.error).toMatch(/does not resolve to a readable persona file/);
+  expect(result.error).toMatch(/Available personas/);
+  expect(writePrdSpy).not.toHaveBeenCalled();
+  const entries = await fsp.readdir(prdsDir);
+  expect(entries.filter((f) => f.endsWith('.md')).length).toBe(0);
+});
+
+test('createPrd accepts a caller-supplied agentType that resolves to a project-overlay persona file', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const cwd = path.dirname(path.dirname(prdsDir)); // mkTmpPrdsDir's root (prdsDir = root/.claude/prds)
+  const agentsDir = path.join(cwd, '.claude', 'agents');
+  await fsp.mkdir(agentsDir, { recursive: true });
+  await fsp.writeFile(path.join(agentsDir, 'my-persona.md'), '---\nname: my-persona\n---\nbody\n', 'utf8');
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody({ cwd, slug: 'with-agent-type', agentType: 'my-persona' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^agentType: my-persona$/m);
+});
+
+test('createPrd defaults agentType to dev-lead when omitted, without any persona-existence check', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody({ slug: 'no-agent-type-supplied' }), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/^agentType: dev-lead$/m);
+});
+
 // ──────────────────────────────────────────── originClaudeSessionId fallback
 // (2026-08-01 fix: a PRD queued via the scheduler_create_prd MCP tool from
 // inside an Epic's own chat session, without an explicit sourcePromptId,
@@ -583,6 +651,185 @@ test('createPrd resolves sourcePromptId from originClaudeSessionId when the call
 });
 
 // Same real-homedir rationale as the two tests above.
+// ──────────────────────────────────────────── worktree-cwd Epic-lookup
+// hazard (PRD: projectRootResolve.cjs) — reproduces the live starry-night-
+// ships shape: main's active-index.json has the Epic, a linked worktree's
+// own (git-tracked, frozen-at-branch-time) copy does not. Passing the
+// worktree's pwd as `cwd` must still resolve to main and join the Epic there.
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8' });
+}
+
+function initRepo(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  git(['init', '-q'], dir);
+  git(['config', 'user.email', 'test@example.com'], dir);
+  git(['config', 'user.name', 'Test'], dir);
+  fs.writeFileSync(path.join(dir, 'README.md'), 'hello\n', 'utf8');
+  git(['add', '-A'], dir);
+  git(['commit', '-q', '-m', 'initial'], dir);
+}
+
+test('createPrd resolves a worktree cwd to the main tree and joins the Epic whose row only exists in main\'s active-index (live starry-night-ships shape)', async () => {
+  const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'sm-worktree-cwd-hazard-'));
+  const mainRepo = path.join(tmpRoot, 'main');
+  const worktreeDir = path.join(tmpRoot, 'worktree', 'epic-1');
+  config.addAllowedRoot(mainRepo);
+  try {
+    initRepo(mainRepo);
+    fs.mkdirSync(path.dirname(worktreeDir), { recursive: true });
+    git(['worktree', 'add', '-b', 'sm-epic/epic-1', worktreeDir, 'HEAD'], mainRepo);
+
+    // Main's index has the Epic; the worktree's own copy (as checked out at
+    // branch time) does not — the exact live-repro shape.
+    await writeActiveIndexFixture(mainRepo, {
+      'epic-1': { id: 'epic-1', claudeSessionId: 'claude-sess-epic-1', status: 'active' },
+    });
+
+    const prdsDir = path.join(mainRepo, 'session-manager-operations', 'scheduler', 'epics', 'epic-1', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+    const receivedCwds = [];
+    const realAllocate = remote.allocateParallelGroup.bind(remote);
+    remote.allocateParallelGroup = async (cwd) => { receivedCwds.push(cwd); return realAllocate(cwd); };
+
+    const result = await createPrd(
+      validCreateBody({ cwd: worktreeDir, slug: 'joins-from-worktree', sourcePromptId: 'epic-1' }),
+      remote,
+    );
+
+    expect(result.ok).toBe(true);
+    // Resolved and passed to the remote as the MAIN tree, never the worktree.
+    expect(receivedCwds.every((c) => c === mainRepo)).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(written).toMatch(/sourcePromptId: epic-1/);
+    expect(written).toMatch(new RegExp(`cwd: ${mainRepo.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+  } finally {
+    await fsp.rm(tmpRoot, { recursive: true, force: true });
+  }
+});
+
+test('createPrd omits cwd entirely and resolves the project purely from sourcePromptId (cwd optional inside an Epic session)', async () => {
+  const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-cwd-optional-epic-'));
+  config.addAllowedRoot(root);
+  // resolveProjectContext's cross-project scan (used when cwd is omitted
+  // entirely) is built on activeSessions.allProjectCwds — a scan of REAL
+  // ~/.claude/projects transcripts. In production this is always populated
+  // (the calling session itself opened `root` as a project), so seed a
+  // matching transcript here rather than the fixture root being invisible to
+  // the scan. Cleaned up in `finally`.
+  const transcriptDir = path.join(os.homedir(), '.claude', 'projects', `sm-cwd-optional-test-${Date.now()}`);
+  try {
+    await writeActiveIndexFixture(root, {
+      'epic-cwd-optional': { id: 'epic-cwd-optional', claudeSessionId: 'claude-sess-cwd-optional', status: 'active' },
+    });
+    await fsp.mkdir(transcriptDir, { recursive: true });
+    await fsp.writeFile(path.join(transcriptDir, 'a.jsonl'), `${JSON.stringify({ cwd: root })}\n`, 'utf8');
+
+    const prdsDir = path.join(root, 'session-manager-operations', 'scheduler', 'epics', 'epic-cwd-optional', 'prds');
+    const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+    const body = validCreateBody({ slug: 'no-cwd-supplied', sourcePromptId: 'epic-cwd-optional' });
+    delete body.cwd;
+
+    const result = await createPrd(body, remote);
+
+    expect(result.ok).toBe(true);
+    const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+    expect(written).toMatch(/sourcePromptId: epic-cwd-optional/);
+  } finally {
+    await fsp.rm(transcriptDir, { recursive: true, force: true });
+    await fsp.rm(root, { recursive: true, force: true });
+  }
+});
+
+test('createPrd with neither cwd nor a resolvable Epic fails with a clear cwd-required error', async () => {
+  const remote = {
+    async allocateParallelGroup() { throw new Error('must not be called'); },
+    async readPrd() { throw new Error('must not be called'); },
+    async writePrd() { throw new Error('must not be called'); },
+  };
+  const body = validCreateBody();
+  delete body.cwd;
+
+  const result = await createPrd(body, remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(400);
+  expect(result.error).toMatch(/cwd is required/);
+});
+
+// ──────────────────────────────────────────── PRD 1113: fix-chain depth guard
+// at the authoring boundary. lib/prdCreate.cjs's createPrd() is the shared
+// write path behind both scheduler_create_prd (MCP) and chat:create-prd
+// (IPC) — enforcing here covers both callers with one check.
+
+test('createPrd refuses a depth-2 fix-chain slug (fix-of-a-fix) with a distinct, human-escalation error and writes no file', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+  const writePrdSpy = vi.fn(remote.writePrd);
+  remote.writePrd = writePrdSpy;
+
+  const result = await createPrd(validCreateBody({ slug: 'fix-fix-widget-frobnication' }), remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(409);
+  // Distinct from the provenance/validation error text elsewhere in this
+  // file ('cwd rejected', 'invalid PRD payload', 'already exists') and
+  // explicitly states escalation, not another attempt, is correct.
+  expect(result.error).toMatch(/fix-chain depth cap/i);
+  expect(result.error).toMatch(/not the correct response/i);
+  expect(result.error).toMatch(/human/i);
+  expect(writePrdSpy).not.toHaveBeenCalled();
+  const entries = await fsp.readdir(prdsDir);
+  expect(entries.filter((f) => f.endsWith('.md')).length).toBe(0);
+});
+
+test('createPrd refuses a depth-3 fix-chain slug the same way as depth-2', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody({ slug: 'fix-fix-fix-widget-frobnication' }), remote);
+
+  expect(result.ok).toBe(false);
+  expect(result.status).toBe(409);
+  const entries = await fsp.readdir(prdsDir);
+  expect(entries.filter((f) => f.endsWith('.md')).length).toBe(0);
+});
+
+test('createPrd allows a depth-1 fix slug through the same code path that rejects depth 2 (matches MAX_INVESTIGATION_DEPTH=1)', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody({ slug: 'fix-widget-frobnication' }), remote);
+
+  expect(result.ok).toBe(true);
+  expect(result.filename).toMatch(/^\d+-fix-widget-frobnication\.md$/);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/title: Add widget frobnication/);
+});
+
+test('createPrd is unaffected by the fix-chain guard for an ordinary slug with no fix chain at all', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody(), remote);
+
+  expect(result.ok).toBe(true);
+  const written = await fsp.readFile(path.join(prdsDir, result.filename), 'utf8');
+  expect(written).toMatch(/title: Add widget frobnication/);
+});
+
+test('createPrd is not fooled by a slug where a later segment merely reads "fix" (false-positive bait)', async () => {
+  const prdsDir = await mkTmpPrdsDir();
+  const remote = makeFakeRemoteWithPrdsDir(prdsDir);
+
+  const result = await createPrd(validCreateBody({ slug: 'fix-loop-extraction-and-round-trip' }), remote);
+
+  expect(result.ok).toBe(true);
+  expect(result.filename).toMatch(/^\d+-fix-loop-extraction-and-round-trip\.md$/);
+});
+
 test('createPrd leaves sourcePromptId unset when originClaudeSessionId matches no known Epic (plain SessionTab chat)', async () => {
   const root = await fsp.mkdtemp(path.join(os.homedir(), '.sm-origin-session-no-match-'));
   config.addAllowedRoot(root);

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

@@ -0,0 +1,117 @@
+/**
+ * prdFrontmatterAgentType.test.cjs — PRD 1114: `agentType` (WHO executes a
+ * PRD, distinct from `tag` — the WORK TYPE) is a recognized PRD frontmatter
+ * key, round-tripped byte-identically by prdFrontmatter.cjs's
+ * parsePrdFile/serializePrdFile pair, and surfaced (with read-time tolerance
+ * for a dangling persona) by scheduler/prdParser.cjs's parsePrdRaw.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdFrontmatterAgentType.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { parsePrdFile, serializePrdFile } = require('../lib/prdFrontmatter.cjs');
+const { parsePrdRaw, _resetCache } = require('../scheduler/prdParser.cjs');
+const { todayFile } = require('../lib/opsErrorLog.cjs');
+
+function mkTmpPrdsDir() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-agenttype-fm-'));
+}
+
+test('parsePrdFile recognizes agentType and serializePrdFile round-trips it byte-identically', () => {
+  const raw = [
+    '---',
+    'title: A PRD with a persona',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 30',
+    'tag: bug',
+    'agentType: dev-lead',
+    '---',
+    '# Goal',
+    '',
+    'Fix the thing.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.agentType).toBe('dev-lead');
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('parsePrdFile leaves agentType undefined when omitted — additive-only, no regression for old PRDs', () => {
+  const raw = [
+    '---',
+    'title: An older PRD authored before this field existed',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 30',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.agentType).toBeUndefined();
+});
+
+// Real opsErrorLog write path (not a mock) — see prdAgentType.test.cjs's
+// header for why a plain mkdtemp() cwd is safe to use here (not "ephemeral").
+test('scheduler/prdParser.cjs parsePrdRaw exposes agentType, and tolerates a dangling persona by logging once instead of throwing', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+
+  const danglingPath = path.join(dir, '1-dangling.md');
+  await fsp.writeFile(danglingPath, [
+    '---',
+    'title: A PRD whose persona was later deleted',
+    `cwd: ${dir}`,
+    'estimateMinutes: 10',
+    'agentType: ghost-persona-that-does-not-exist-anywhere',
+    '---',
+    '# Goal',
+    '',
+    'Still loads.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(danglingPath);
+  expect(parsed.agentType).toBe('ghost-persona-that-does-not-exist-anywhere');
+
+  const lines = fs.readFileSync(todayFile(dir), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  const matches = lines.filter((l) => l.message.includes('ghost-persona-that-does-not-exist-anywhere'));
+  expect(matches).toHaveLength(1);
+  expect(matches[0].scope).toBe('prdAgentType');
+  expect(matches[0].level).toBe('warn');
+
+  // A second parse of the SAME (cwd, agentType) pair must not log again.
+  _resetCache();
+  await parsePrdRaw(danglingPath);
+  const linesAfter = fs.readFileSync(todayFile(dir), 'utf8').split('\n').filter(Boolean);
+  expect(linesAfter).toHaveLength(1);
+});
+
+test('scheduler/prdParser.cjs parsePrdRaw leaves agentType null when omitted', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+
+  const ordinaryPath = path.join(dir, '2-ordinary.md');
+  await fsp.writeFile(ordinaryPath, [
+    '---',
+    'title: Ordinary job',
+    `cwd: ${dir}`,
+    'estimateMinutes: 10',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+
+  const parsed = await parsePrdRaw(ordinaryPath);
+  expect(parsed.agentType).toBeNull();
+});

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

@@ -0,0 +1,108 @@
+/**
+ * prdFrontmatterQuietMachine.test.cjs — PRD 1107: `quietMachine: true` is an
+ * optional PRD frontmatter field, recognized by prdFrontmatter.cjs's
+ * parsePrdFile/serializePrdFile round-trip AND by scheduler/prdParser.cjs's
+ * dispatch-time parsePrdRaw. Only a literal `true` opts in; omitted or any
+ * other value behaves exactly like today (additive-only, no required-field
+ * regression for the thousands of PRDs written before this field existed).
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/prdFrontmatterQuietMachine.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+
+const { parsePrdFile, serializePrdFile } = require('../lib/prdFrontmatter.cjs');
+const { parsePrdRaw, _resetCache } = require('../scheduler/prdParser.cjs');
+
+function mkTmpPrdsDir() {
+  return fsp.mkdtemp(path.join(os.tmpdir(), 'sm-prd-quietmachine-'));
+}
+
+test('parsePrdFile recognizes quietMachine: true and serializePrdFile round-trips it byte-identically', () => {
+  const raw = [
+    '---',
+    'title: A timing-sensitive PRD',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 30',
+    'quietMachine: true',
+    '---',
+    '# Goal',
+    '',
+    'Measure frame time without contention.',
+    '',
+  ].join('\n');
+
+  const { frontmatter, body } = parsePrdFile(raw);
+  expect(frontmatter.quietMachine).toBe(true);
+  expect(serializePrdFile(frontmatter, body)).toBe(raw);
+});
+
+test('parsePrdFile ignores quietMachine: false — only a literal true opts in', () => {
+  const raw = [
+    '---',
+    'title: Not opted in',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 30',
+    'quietMachine: false',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.quietMachine).toBeUndefined();
+});
+
+test('parsePrdFile leaves quietMachine undefined when omitted — additive-only, no regression for old PRDs', () => {
+  const raw = [
+    '---',
+    'title: An older PRD authored before this field existed',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 30',
+    '---',
+    'body',
+    '',
+  ].join('\n');
+  const { frontmatter } = parsePrdFile(raw);
+  expect(frontmatter.quietMachine).toBeUndefined();
+});
+
+test('scheduler/prdParser.cjs parsePrdRaw exposes quietMachine as a typed boolean, true only when the frontmatter literally says true', async () => {
+  const dir = await mkTmpPrdsDir();
+  _resetCache();
+
+  const quietPath = path.join(dir, '1-quiet.md');
+  await fsp.writeFile(quietPath, [
+    '---',
+    'title: Quiet job',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 10',
+    'quietMachine: true',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing quietly.',
+    '',
+  ].join('\n'));
+  const quiet = await parsePrdRaw(quietPath);
+  expect(quiet.quietMachine).toBe(true);
+
+  const ordinaryPath = path.join(dir, '2-ordinary.md');
+  await fsp.writeFile(ordinaryPath, [
+    '---',
+    'title: Ordinary job',
+    'cwd: ~/Projects/session-manager',
+    'estimateMinutes: 10',
+    '---',
+    '# Goal',
+    '',
+    'Do the thing.',
+    '',
+  ].join('\n'));
+  const ordinary = await parsePrdRaw(ordinaryPath);
+  expect(ordinary.quietMachine).toBe(false);
+});