claude-code-session-manager 0.85.0 → 0.87.0

package/src/main/lib/__tests__/effectiveModelInfo.test.cjs

@@ -0,0 +1,239 @@
+/**
+ * effectiveModelInfo.test.cjs — the main-process half of "what will this
+ * Epic actually run as": overlay-aware persona alias resolution plus
+ * evidence-based concrete model id (scheduler run log, then session
+ * transcript), never fabricated when there's no evidence.
+ *
+ * All fixtures live under a per-test mkdtemp'd $HOME (never the real
+ * ~/.claude) so persona lookup (which reads os.homedir()), scheduler run
+ * logs, and transcripts all resolve consistently.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/effectiveModelInfo.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { encodeCwd } = require('../encodeCwd.cjs');
+const { resolveEffectiveModelInfo, isConcreteModelId, computeEffortReachable } = require('../effectiveModelInfo.cjs');
+// config.cjs's `allowedRoots` is a module-level singleton seeded from
+// os.homedir() at FIRST require — since this test's HOME changes every test
+// (fresh mkdtemp), a persona lookup (getPersonaBody -> validatePath) would
+// only pass for whichever tmpHome happened to be active the first time
+// config.cjs got lazily required. addAllowedRoot mutates the live Set
+// instead, so every test's own tmpHome is explicitly admitted.
+const { addAllowedRoot } = require('../../config.cjs');
+
+let tmpHome;
+let originalHome;
+let cwd;
+
+beforeEach(() => {
+  originalHome = process.env.HOME;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-effective-model-home-'));
+  process.env.HOME = tmpHome;
+  addAllowedRoot(tmpHome);
+  cwd = path.join(tmpHome, 'project');
+  fs.mkdirSync(cwd, { recursive: true });
+});
+
+afterEach(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function writePersona(dir, name, frontmatterLines) {
+  fs.mkdirSync(dir, { recursive: true });
+  const lines = ['---', ...frontmatterLines, '---', 'Body text.'];
+  fs.writeFileSync(path.join(dir, `${name}.md`), lines.join('\n'));
+}
+
+function writeGlobalPersona(name, frontmatterLines) {
+  writePersona(path.join(tmpHome, '.claude', 'agents'), name, frontmatterLines);
+}
+
+function writeOverlayPersona(name, frontmatterLines) {
+  writePersona(path.join(cwd, '.claude', 'agents'), name, frontmatterLines);
+}
+
+function writeActiveIndex(sessions) {
+  const dir = path.join(cwd, 'session-manager-operations', 'prompt-sessions');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'active-index.json'), JSON.stringify({ sessions, events: {} }, null, 2));
+}
+
+function writeQueueJobs(jobs) {
+  const dir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'queue.json'), JSON.stringify({ jobs }, null, 2));
+}
+
+function writeHistoryEntries(entries) {
+  const dir = path.join(cwd, 'session-manager-operations', 'scheduler', 'state');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'history.jsonl'), entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+}
+
+function writeRunLog(runId, slug, text) {
+  const dir = path.join(tmpHome, '.claude', 'session-manager', 'scheduled-plans', 'runs', runId);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${slug}.log`), text);
+}
+
+function writeTranscript(sessionId, lines) {
+  const dir = path.join(tmpHome, '.claude', 'projects', encodeCwd(cwd));
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, `${sessionId}.jsonl`), lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+}
+
+// ---------- persona alias resolution ----------
+
+test('resolves a global persona alias with modelSource "persona" and no fabricated evidence', async () => {
+  writeGlobalPersona('writer', ['model: sonnet']);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'writer' });
+  expect(info.modelAlias).toBe('sonnet');
+  expect(info.modelSource).toBe('persona');
+  expect(info.resolvedModelId).toBeNull();
+  expect(info.resolvedFrom).toBeNull();
+});
+
+test('a persona model of "inherit" reports modelAlias null and modelSource "inherit"', async () => {
+  writeGlobalPersona('inheriting', ['model: inherit']);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'inheriting' });
+  expect(info.modelAlias).toBeNull();
+  expect(info.modelSource).toBe('inherit');
+});
+
+test('a persona with no model field at all is treated the same as inherit', async () => {
+  writeGlobalPersona('bare', []);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'bare' });
+  expect(info.modelAlias).toBeNull();
+  expect(info.modelSource).toBe('inherit');
+});
+
+test('a persona pinned to an already-concrete model id echoes it back with resolvedFrom null, ignoring conflicting evidence', async () => {
+  writeGlobalPersona('pinned', ['model: claude-opus-5-2027']);
+  // Conflicting scheduler evidence exists but must never override an
+  // already-concrete alias — no evidence lookup should even be attempted.
+  writeQueueJobs([{ slug: 'x', runId: 'r1', agentType: 'pinned', finishedAt: new Date().toISOString() }]);
+  writeRunLog('r1', 'x', '[scheduler] agentType=pinned persona=/whatever model=claude-sonnet-1\n');
+
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'pinned' });
+  expect(info.modelAlias).toBe('claude-opus-5-2027');
+  expect(info.modelSource).toBe('persona');
+  expect(info.resolvedModelId).toBe('claude-opus-5-2027');
+  expect(info.resolvedFrom).toBeNull();
+});
+
+test('a project-overlay persona wins over the global definition and reports modelSource "persona-overlay"', async () => {
+  writeGlobalPersona('shared-name', ['model: sonnet']);
+  writeOverlayPersona('shared-name', ['model: opus']);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'shared-name' });
+  expect(info.modelAlias).toBe('opus');
+  expect(info.modelSource).toBe('persona-overlay');
+});
+
+test('a dangling agentType (no persona file anywhere) resolves modelSource "fallback" without throwing', async () => {
+  await expect(resolveEffectiveModelInfo({ cwd, agentType: 'ghost-persona' })).resolves.toBeTruthy();
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'ghost-persona' });
+  expect(info.modelAlias).toBeNull();
+  expect(info.modelSource).toBe('fallback');
+  expect(info.resolvedModelId).toBeNull();
+});
+
+// ---------- concrete-model-id evidence ----------
+
+test('evidence hit via the scheduler run record: reads the model logged in the most recent matching job\'s run log', async () => {
+  writeGlobalPersona('runner', ['model: sonnet']);
+  writeQueueJobs([
+    { slug: 'older', runId: 'run-older', agentType: 'runner', finishedAt: '2026-01-01T00:00:00.000Z' },
+    { slug: 'newer', runId: 'run-newer', agentType: 'runner', finishedAt: '2026-02-01T00:00:00.000Z' },
+  ]);
+  writeRunLog('run-older', 'older', '[scheduler] agentType=runner persona=/p/runner.md model=claude-old-1\n');
+  writeRunLog('run-newer', 'newer', '[scheduler] agentType=runner persona=/p/runner.md model=claude-sonnet-5\n');
+
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'runner' });
+  expect(info.resolvedModelId).toBe('claude-sonnet-5');
+  expect(info.resolvedFrom).toBe('scheduler-run');
+});
+
+test('scheduler-run evidence also matches jobs already archived into history.jsonl', async () => {
+  writeGlobalPersona('archived-runner', ['model: opus']);
+  writeHistoryEntries([
+    { slug: 'old-hist', runId: 'run-hist', agentType: 'archived-runner', finishedAt: '2026-01-01T00:00:00.000Z' },
+  ]);
+  writeRunLog('run-hist', 'old-hist', '[scheduler] agentType=archived-runner persona=/p/x.md model=claude-opus-5\n');
+
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'archived-runner' });
+  expect(info.resolvedModelId).toBe('claude-opus-5');
+  expect(info.resolvedFrom).toBe('scheduler-run');
+});
+
+test('evidence hit via transcript when no scheduler run exists: takes the LAST "model" occurrence', async () => {
+  writeGlobalPersona('chatty', ['model: opus']);
+  writeActiveIndex({
+    'epic-1': { id: 'epic-1', claudeSessionId: 'sess-1', agentType: 'chatty', createdAt: '2026-03-01T00:00:00.000Z' },
+  });
+  writeTranscript('sess-1', [
+    { type: 'assistant', message: { model: 'claude-opus-4' } },
+    { type: 'assistant', message: { model: 'claude-opus-5' } },
+  ]);
+
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'chatty' });
+  expect(info.resolvedModelId).toBe('claude-opus-5');
+  expect(info.resolvedFrom).toBe('transcript');
+});
+
+test('transcript evidence prefers the most recently created matching Epic', async () => {
+  writeGlobalPersona('multi-epic', ['model: haiku']);
+  writeActiveIndex({
+    'epic-old': { id: 'epic-old', claudeSessionId: 'sess-old', agentType: 'multi-epic', createdAt: '2026-01-01T00:00:00.000Z' },
+    'epic-new': { id: 'epic-new', claudeSessionId: 'sess-new', agentType: 'multi-epic', createdAt: '2026-05-01T00:00:00.000Z' },
+  });
+  writeTranscript('sess-old', [{ model: 'claude-haiku-old' }]);
+  writeTranscript('sess-new', [{ model: 'claude-haiku-new' }]);
+
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'multi-epic' });
+  expect(info.resolvedModelId).toBe('claude-haiku-new');
+  expect(info.resolvedFrom).toBe('transcript');
+});
+
+test('evidence miss (no scheduler run, no transcript) reports resolvedModelId/resolvedFrom as null — never a guessed pricing-key fallback', async () => {
+  writeGlobalPersona('unseen', ['model: haiku']);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'unseen' });
+  expect(info.resolvedModelId).toBeNull();
+  expect(info.resolvedFrom).toBeNull();
+});
+
+// ---------- edge cases ----------
+
+test('never throws for a missing cwd/agentType', async () => {
+  await expect(resolveEffectiveModelInfo({})).resolves.toMatchObject({
+    modelAlias: null,
+    modelSource: 'fallback',
+    resolvedModelId: null,
+    resolvedFrom: null,
+  });
+});
+
+test('isConcreteModelId treats known CLI aliases as non-concrete and everything else as concrete', () => {
+  expect(isConcreteModelId('opus')).toBe(false);
+  expect(isConcreteModelId('sonnet')).toBe(false);
+  expect(isConcreteModelId('haiku')).toBe(false);
+  expect(isConcreteModelId('fable')).toBe(false);
+  expect(isConcreteModelId(null)).toBe(false);
+  expect(isConcreteModelId('claude-opus-5')).toBe(true);
+});
+
+test('effortReachable is always false for an app-launched session — cleanChildEnv strips CLAUDE_EFFORT and CLAUDE_CODE_* before a child ever sees them', () => {
+  expect(computeEffortReachable({})).toBe(false);
+});
+
+test('resolveEffectiveModelInfo surfaces effortReachable alongside the model fields', async () => {
+  writeGlobalPersona('any', ['model: sonnet']);
+  const info = await resolveEffectiveModelInfo({ cwd, agentType: 'any' });
+  expect(info.effortReachable).toBe(false);
+});

package/src/main/lib/__tests__/gitWorktree.test.cjs

@@ -300,6 +300,95 @@ test('[job] carry-over failure (git apply cannot apply) degrades cleanly: worktr
   }
 });
 
+// ──────────────────────────────────────────── PRD: stream the base-WIP diff capture (job 1192)
+
+test('[job] a wide dirty tree (300+ changed paths incl. a multi-MB file) captures and carries over without a maxBuffer overflow', async () => {
+  const files = [];
+  for (let i = 0; i < 300; i++) {
+    const rel = `wide-${i}.txt`;
+    fs.writeFileSync(path.join(repoCwd, rel), `initial ${i}\n`, 'utf8');
+    files.push(rel);
+  }
+  const bigRel = 'big-file.bin';
+  fs.writeFileSync(path.join(repoCwd, bigRel), Buffer.alloc(1024, 1));
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'wide baseline'], repoCwd);
+
+  // Dirty every tracked file (uncommitted tracked edits) and grow the binary
+  // file well past Node's execFile default maxBuffer (1MB) — the exact shape
+  // that overflowed the old buffered capture (job 1192: ~240 dirty paths).
+  for (const rel of files) fs.appendFileSync(path.join(repoCwd, rel), 'dirtied\n', 'utf8');
+  const bigBuf = Buffer.alloc(3 * 1024 * 1024); // 3MB of NUL bytes — git detects this as binary
+  fs.writeFileSync(path.join(repoCwd, bigRel), bigBuf);
+
+  const result = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug: 'wide-tree' });
+  expect(result.ok).toBe(true);
+  expect(result.carriedPaths.length).toBe(files.length + 1);
+  expect(fs.readFileSync(path.join(result.dir, files[0]), 'utf8')).toContain('dirtied');
+  expect(Buffer.compare(fs.readFileSync(path.join(result.dir, bigRel)), bigBuf)).toBe(0);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: result.dir, branch: result.branch });
+}, 30_000);
+
+test('[job] a renamed file and a mutated binary file survive the capture/apply round trip using the same flags as production', async () => {
+  const binRel = 'asset.bin';
+  const binInitial = Buffer.from([0, 1, 2, 3, 4, 0, 255, 254]);
+  fs.writeFileSync(path.join(repoCwd, binRel), binInitial);
+  fs.writeFileSync(path.join(repoCwd, 'to-rename.txt'), 'original name content\n', 'utf8');
+  git(['add', '-A'], repoCwd);
+  git(['commit', '-q', '-m', 'binary + rename baseline'], repoCwd);
+
+  // Dirty tree: a tracked rename plus a mutated binary file, both uncommitted.
+  git(['mv', 'to-rename.txt', 'renamed.txt'], repoCwd);
+  const binChanged = Buffer.from([9, 8, 7, 0, 6, 5, 0, 4]);
+  fs.writeFileSync(path.join(repoCwd, binRel), binChanged);
+
+  const result = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug: 'rename-binary' });
+  expect(result.ok).toBe(true);
+  expect(fs.existsSync(path.join(result.dir, 'to-rename.txt'))).toBe(false);
+  expect(fs.readFileSync(path.join(result.dir, 'renamed.txt'), 'utf8')).toBe('original name content\n');
+  expect(Buffer.compare(fs.readFileSync(path.join(result.dir, binRel)), binChanged)).toBe(0);
+
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: result.dir, branch: result.branch });
+});
+
+test('[job] a capture that cannot write its diff file (target dir missing) falls back with a specific reason, never the old generic maxBuffer message', async () => {
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'uncommitted tracked edit\n', 'utf8');
+  const bogusDir = path.join(tmpRoot, 'does-not-exist');
+  const result = await gitWorktree.captureAndCarryBaseDiff({ cwd: repoCwd, dir: bogusDir });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/capturing base diff failed/);
+  expect(result.reason).not.toMatch(/maxBuffer/i);
+  expect(fs.existsSync(bogusDir)).toBe(false); // nothing leaked into a directory that never existed
+});
+
+test('[job] the temp diff file is removed after carry-over on both the success and the git-apply-failure paths', async () => {
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'uncommitted tracked edit\n', 'utf8');
+  const success = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cleanup-ok' });
+  expect(success.ok).toBe(true);
+  expect(fs.readdirSync(success.dir).filter((f) => f.startsWith('.sm-worktree-carry-'))).toEqual([]);
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: success.dir, branch: success.branch });
+
+  // Force a git-apply failure on a genuine clean-base worktree by making the
+  // target file read-only before the capture/apply call, so the patch writes
+  // fine but applying it fails — the finally block must still remove the temp
+  // patch file even though apply itself errored.
+  const clean = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cleanup-fail' });
+  expect(clean.ok).toBe(true);
+  fs.writeFileSync(path.join(repoCwd, 'README.md'), 'another uncommitted tracked edit\n', 'utf8');
+  const targetFile = path.join(clean.dir, 'README.md');
+  fs.chmodSync(targetFile, 0o444);
+  try {
+    const fail = await gitWorktree.captureAndCarryBaseDiff({ cwd: repoCwd, dir: clean.dir });
+    expect(fail.ok).toBe(false);
+    expect(fail.reason).toMatch(/git apply failed/);
+  } finally {
+    fs.chmodSync(targetFile, 0o644);
+  }
+  expect(fs.readdirSync(clean.dir).filter((f) => f.startsWith('.sm-worktree-carry-'))).toEqual([]);
+  await gitWorktree.cleanupJobWorktree({ cwd: repoCwd, dir: clean.dir, branch: clean.branch });
+}, 30_000);
+
 test('[job] falls back once the concurrency cap is reached, and recovers after cleanup', async () => {
   process.env.SM_JOB_WORKTREE_MAX = '1';
   const first = await gitWorktree.createJobWorktree({ cwd: repoCwd, slug: 'cap-1' });

package/src/main/lib/__tests__/guardShims.test.cjs

@@ -0,0 +1,151 @@
+/**
+ * guardShims.test.cjs — unit tests for the stable, app-upgrade-proof guard
+ * hook indirection (guardShims.cjs). Uses a temp "home" dir per test so the
+ * real ~/.claude is never touched.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/guardShims.test.cjs
+ */
+
+import { test, expect, afterEach } from 'vitest';
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const {
+  APP_ROOT,
+  GUARD_NAMES,
+  hooksDir,
+  pointerPath,
+  shimPath,
+  writeGuardShims,
+  guardShimsExist,
+} = require('../guardShims.cjs');
+
+const tmpDirs = [];
+afterEach(async () => {
+  while (tmpDirs.length) {
+    const d = tmpDirs.pop();
+    await fsp.rm(d, { recursive: true, force: true });
+  }
+});
+
+async function mkTmp(prefix) {
+  const d = await fsp.mkdtemp(path.join(os.tmpdir(), prefix));
+  tmpDirs.push(d);
+  return d;
+}
+
+/** Run a guard (by absolute path, e.g. a shim) as a child process, same
+ *  pattern delegationReadiness.test.cjs uses to exercise the real guards —
+ *  NEVER require() a guard/shim in-process, since its main() calls
+ *  process.exit(0) as a require-time side effect. */
+function runGuard(scriptPath, { toolName = 'Write', toolInput, cwd }) {
+  return JSON.parse(execFileSync('node', [scriptPath], {
+    input: JSON.stringify({ tool_name: toolName, tool_input: toolInput, cwd }),
+    encoding: 'utf8',
+  }));
+}
+
+test('writeGuardShims: writes the pointer file and all three shims under homeDir', async () => {
+  const homeDir = await mkTmp('sm-guard-shims-home-');
+  const r = await writeGuardShims({ homeDir });
+  expect(r.ok).toBe(true);
+
+  expect(fs.existsSync(pointerPath(homeDir))).toBe(true);
+  expect(JSON.parse(fs.readFileSync(pointerPath(homeDir), 'utf8'))).toEqual({ appRoot: APP_ROOT });
+  for (const name of GUARD_NAMES) {
+    expect(fs.existsSync(shimPath(name, homeDir))).toBe(true);
+  }
+  expect(guardShimsExist(homeDir)).toBe(true);
+});
+
+test('writeGuardShims: does NOT vendor guard logic — the shim body only references the guard by name, never copies its source', async () => {
+  const homeDir = await mkTmp('sm-guard-shims-home-');
+  await writeGuardShims({ homeDir });
+
+  const realSource = fs.readFileSync(path.join(APP_ROOT, 'scripts', 'hooks', 'guard-prd-writes.cjs'), 'utf8');
+  const shimSource = fs.readFileSync(shimPath('guard-prd-writes.cjs', homeDir), 'utf8');
+  expect(shimSource).not.toContain('SCHEDULER_SEGMENT'); // a guard-prd-writes-specific symbol
+  expect(shimSource.length).toBeLessThan(realSource.length / 2);
+  expect(shimSource).toContain("require(path.join(ptr.appRoot, 'scripts', 'hooks', 'guard-prd-writes.cjs'))");
+});
+
+test('writeGuardShims: idempotent — re-running with the same appRoot produces byte-identical files', async () => {
+  const homeDir = await mkTmp('sm-guard-shims-home-');
+  const r1 = await writeGuardShims({ homeDir });
+  expect(r1.ok).toBe(true);
+  const pointerBefore = fs.readFileSync(pointerPath(homeDir), 'utf8');
+  const shimsBefore = GUARD_NAMES.map((n) => fs.readFileSync(shimPath(n, homeDir), 'utf8'));
+
+  const r2 = await writeGuardShims({ homeDir });
+  expect(r2.ok).toBe(true);
+  expect(fs.readFileSync(pointerPath(homeDir), 'utf8')).toBe(pointerBefore);
+  GUARD_NAMES.forEach((n, i) => {
+    expect(fs.readFileSync(shimPath(n, homeDir), 'utf8')).toBe(shimsBefore[i]);
+  });
+});
+
+test('writeGuardShims: the installed shim actually resolves through the pointer and runs the real guard logic', async () => {
+  const homeDir = await mkTmp('sm-guard-shims-home-');
+  const cwd = await mkTmp('sm-guard-shims-cwd-');
+  await writeGuardShims({ homeDir });
+
+  const denied = runGuard(shimPath('guard-prd-writes.cjs', homeDir), {
+    toolInput: { file_path: path.join(cwd, 'session-manager-operations', 'scheduler', 'prds', '1234-x.md'), content: '# x' },
+    cwd,
+  });
+  expect(denied.hookSpecificOutput?.permissionDecision).toBe('deny');
+
+  const allowed = runGuard(shimPath('guard-prd-writes.cjs', homeDir), {
+    toolInput: { file_path: path.join(cwd, 'src', 'x.ts'), content: 'x' },
+    cwd,
+  });
+  expect(allowed.hookSpecificOutput?.permissionDecision).not.toBe('deny');
+});
+
+test('writeGuardShims: rewriting the pointer to a DIFFERENT app root lets an already-installed shim follow an app upgrade with no re-install', async () => {
+  const homeDir = await mkTmp('sm-guard-shims-home-');
+  const cwd = await mkTmp('sm-guard-shims-cwd-');
+  await writeGuardShims({ homeDir }); // "first install", points at the real APP_ROOT
+  const shimFile = shimPath('guard-prd-writes.cjs', homeDir);
+  const shimBytesBefore = fs.readFileSync(shimFile, 'utf8');
+
+  // Simulate an app upgrade: a second "app root" at a brand-new path, with
+  // its own copy of scripts/hooks/guard-prd-writes.cjs (this is the ONLY file
+  // guardShims ever reads through the pointer at invocation time).
+  const secondAppRoot = await mkTmp('sm-guard-shims-upgraded-app-');
+  await fsp.mkdir(path.join(secondAppRoot, 'scripts', 'hooks'), { recursive: true });
+  await fsp.copyFile(
+    path.join(APP_ROOT, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
+    path.join(secondAppRoot, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
+  );
+
+  const r = await writeGuardShims({ homeDir, appRoot: secondAppRoot });
+  expect(r.ok).toBe(true);
+  expect(JSON.parse(fs.readFileSync(pointerPath(homeDir), 'utf8')).appRoot).toBe(secondAppRoot);
+  // The shim FILE at the already-installed path never changed.
+  expect(fs.readFileSync(shimFile, 'utf8')).toBe(shimBytesBefore);
+
+  // A project hook that already references this exact shim path keeps working.
+  const denied = runGuard(shimFile, {
+    toolInput: { file_path: path.join(cwd, 'session-manager-operations', 'scheduler', 'prds', '1234-x.md'), content: '# x' },
+    cwd,
+  });
+  expect(denied.hookSpecificOutput?.permissionDecision).toBe('deny');
+});
+
+test('writeGuardShims: returns { ok:false, error } without throwing when homeDir cannot be written to', async () => {
+  const base = await mkTmp('sm-guard-shims-unwritable-');
+  const blocker = path.join(base, 'blocker-file');
+  await fsp.writeFile(blocker, 'x', 'utf8');
+  // A homeDir whose parent path segment is a plain FILE can never be mkdir'd
+  // into (ENOTDIR) — reproduces "unwritable ~/.claude" without relying on
+  // permission bits, which root would bypass.
+  const homeDir = path.join(blocker, 'home');
+
+  const r = await writeGuardShims({ homeDir });
+  expect(r.ok).toBe(false);
+  expect(r.error).toBeTruthy();
+  expect(guardShimsExist(homeDir)).toBe(false);
+});

package/src/main/lib/__tests__/loadGate.test.cjs

@@ -125,7 +125,7 @@ test('an ungated tick never audits', () => {
   assert.equal(g.evaluate().shouldAudit, false);
 });
 
-test('escalates once the gated stretch exceeds the escalation window, and the stretch resets when load drops', () => {
+test('escalates once the gated stretch exceeds the escalation window, and the stretch only resets once load has stayed sub-threshold past the release window', () => {
   let l1 = 12.95;
   let t = 0;
   const g = createLoadGate({
@@ -134,6 +134,7 @@ test('escalates once the gated stretch exceeds the escalation window, and the st
     now: () => t,
     threshold: 0.85,
     escalateAfterMs: 45 * 60_000,
+    releaseWindowMs: 2 * 60_000,
   });
   assert.equal(g.evaluate().escalate, false);
   t += 44 * 60_000;
@@ -142,12 +143,43 @@ test('escalates once the gated stretch exceeds the escalation window, and the st
   const r = g.evaluate();
   assert.equal(r.escalate, true, 'at 45m: escalates');
   assert.equal(r.gatedSinceMs, 45 * 60_000);
+  // A single sub-threshold sample must NOT reset the stretch (the boundary-
+  // hovering bug this PRD fixes) — gatedSinceMs keeps growing.
   l1 = 1; t += 60_000;
-  assert.equal(g.evaluate().gatedSinceMs, 0, 'load dropped: stretch resets');
+  const oneMinBelow = g.evaluate();
+  assert.equal(oneMinBelow.gated, false, 'gate decision is immediate');
+  assert.equal(oneMinBelow.gatedSinceMs, 46 * 60_000, 'stretch not yet released');
+  // Load climbs back above threshold before the release window elapses: the
+  // stretch was never actually cleared, so it just keeps accumulating.
+  l1 = 12.95; t += 30_000;
+  assert.equal(g.evaluate().gatedSinceMs, 46 * 60_000 + 30_000, 'stretch survived the brief dip');
+  // Now hold sub-threshold continuously past the release window (the window
+  // is measured from the first sub-threshold sample of this sustained drop,
+  // so it takes a tick to mark that start, then another once the window has
+  // actually elapsed).
+  l1 = 1; t += 1;
+  g.evaluate();
+  t += 2 * 60_000;
+  assert.equal(g.evaluate().gatedSinceMs, 0, 'sustained sub-threshold load past the release window clears the stretch');
   l1 = 12.95; t += 60_000;
   assert.equal(g.evaluate().gatedSinceMs, 0, 'a fresh stretch starts from zero');
 });
 
+test('the gate decision itself is unaffected by hysteresis: a sub-threshold tick is never gated, even mid-stretch', () => {
+  let l1 = 12.95;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    releaseWindowMs: 5 * 60_000,
+  });
+  assert.equal(g.evaluate().gated, true);
+  l1 = 1; t += 60_000;
+  assert.equal(g.evaluate().gated, false, 'below threshold: gated:false immediately, hysteresis notwithstanding');
+});
+
 test('snapshot() reflects the last evaluation and is null before any', () => {
   const { g } = gateWith({});
   assert.equal(g.snapshot(), null);
@@ -157,3 +189,72 @@ test('snapshot() reflects the last evaluation and is null before any', () => {
   assert.equal(typeof s.at, 'string');
   assert.equal('shouldAudit' in s, false, 'per-tick flags are not part of the persisted snapshot');
 });
+
+test('snapshot() exposes gated, ratio, threshold, loadavg1, cores and gatedSinceMs (what buildScheduleStatePayload surfaces as loadGate)', () => {
+  const { g } = gateWith({});
+  g.evaluate();
+  const s = g.snapshot();
+  assert.equal(typeof s.gated, 'boolean');
+  assert.equal(typeof s.ratio, 'number');
+  assert.equal(typeof s.threshold, 'number');
+  assert.equal(typeof s.loadavg1, 'number');
+  assert.equal(typeof s.cores, 'number');
+  assert.equal(typeof s.gatedSinceMs, 'number');
+});
+
+// ─── hysteresis: the real observed boundary-hovering sequence ──────────────
+
+test('a boundary-hovering box (real observed sequence, alternating above/below threshold) grows gatedSinceMs monotonically across 50 simulated minutes and eventually escalates', () => {
+  // 14 cores, 0.85/core = 11.9 threshold; loadavg1 observed 2026-09-12
+  // oscillating 11.07 - 13.31, straddling the threshold every tick. Before
+  // this PRD, the immediate reset on ANY sub-threshold sample meant every
+  // one of these ticks reset gatedSince to null and escalate never fired.
+  const CORES = 14;
+  const THRESHOLD = 0.85;
+  const SEQUENCE = [11.07, 13.31, 11.51, 12.8];
+  let l1 = SEQUENCE[0];
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => CORES,
+    now: () => t,
+    threshold: THRESHOLD,
+    escalateAfterMs: 20 * 60_000, // shorter than the 45m default so 50 sim-minutes crosses it
+  });
+
+  const TICK_MS = 60_000;
+  const TOTAL_MS = 50 * 60_000;
+  let prevGatedSinceMs = -1;
+  let sawEscalate = false;
+  let i = 0;
+  for (let elapsed = 0; elapsed < TOTAL_MS; elapsed += TICK_MS) {
+    l1 = SEQUENCE[i % SEQUENCE.length];
+    i += 1;
+    const r = g.evaluate();
+    assert.ok(r.gatedSinceMs >= prevGatedSinceMs, `gatedSinceMs must not shrink (was ${prevGatedSinceMs}, now ${r.gatedSinceMs})`);
+    prevGatedSinceMs = r.gatedSinceMs;
+    if (r.escalate) sawEscalate = true;
+    t += TICK_MS;
+  }
+  assert.equal(sawEscalate, true, 'escalate must fire once the (never-reset) stretch exceeds escalateAfterMs');
+});
+
+test('the release window actually releases: sustained sub-threshold load past the window reports gated:false and gatedSinceMs:0 on the next tick', () => {
+  let l1 = 13.31;
+  let t = 0;
+  const g = createLoadGate({
+    loadavg: () => [l1, 0, 0],
+    cores: () => 14,
+    now: () => t,
+    threshold: 0.85,
+    releaseWindowMs: 2 * 60_000,
+  });
+  assert.equal(g.evaluate().gated, true);
+  l1 = 5;
+  t += 1;
+  g.evaluate(); // marks the start of the sustained sub-threshold run
+  t += 2 * 60_000;
+  const r = g.evaluate();
+  assert.equal(r.gated, false);
+  assert.equal(r.gatedSinceMs, 0);
+});

package/src/main/lib/__tests__/opsRootAbsoluteCwd.test.cjs

@@ -29,7 +29,7 @@ const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
 const queueStore = require('../queueStore.cjs');
-const { activeProjectCwds } = require('../../../../scripts/lib/activeSessions.cjs');
+const { activeProjectCwds } = require('../activeSessions.cjs');
 
 const tmpDirs = [];
 
@@ -149,7 +149,7 @@ test('a transcript cwd inside an ops root is normalized to the project root, not
 });
 
 test('normalization keeps the active-project signal rather than dropping the row', () => {
-  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  const { projectRootOf } = require('../activeSessions.cjs');
   expect(projectRootOf('/p/session-manager-operations/prompt-sessions')).toBe('/p');
   expect(projectRootOf('/p/session-manager-operations')).toBe('/p');
   expect(projectRootOf('/p/session-manager-operations/scheduler/state')).toBe('/p');
@@ -185,7 +185,7 @@ test('projectStateDir fails closed on an ops-internal cwd, naming the offending
 // list at all. `worktreeMainRootOf` reverses a linked worktree's `.git` FILE
 // (`gitdir: <main>/.git/worktrees/<name>`) back to `<main>`.
 
-const { worktreeMainRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+const { worktreeMainRootOf } = require('../activeSessions.cjs');
 const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('../gitWorktree.cjs');
 
 // A worktree's MAIN tree root must live outside os.tmpdir() for these fixtures
@@ -285,13 +285,13 @@ test('worktreeMainRootOf returns null for a plain non-git directory', async () =
 
 test('projectRootOf resolves a worktree cwd to the main tree root', async () => {
   const { main, worktree } = await makeWorktreeFixture();
-  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  const { projectRootOf } = require('../activeSessions.cjs');
   expect(projectRootOf(worktree)).toBe(main);
 });
 
 test('projectRootOf resolves a cwd nested inside a worktree\'s OWN ops tree to the main root', async () => {
   const { main, worktree } = await makeWorktreeFixture();
-  const { projectRootOf } = require('../../../../scripts/lib/activeSessions.cjs');
+  const { projectRootOf } = require('../activeSessions.cjs');
   const nestedOps = path.join(worktree, 'session-manager-operations', 'scheduler', 'state');
   fs.mkdirSync(nestedOps, { recursive: true });
   expect(projectRootOf(nestedOps)).toBe(main);