claude-code-session-manager 0.95.0 → 0.96.0

package/src/main/lib/__tests__/credentials-futile-refresh.test.cjs

@@ -0,0 +1,115 @@
+/**
+ * credentials-futile-refresh.test.cjs — the 2026-09-23 credential-refresh
+ * storm. On this machine the OAuth creds were expired with NO refresh token
+ * (expiredAtMs 1775277875159). Every 15 s billing poll called refreshIfNeeded,
+ * which tried the OAuth grant (instant 'unsupported' — no refresh token),
+ * then spawned `claude --version` as a CLI fallback (which shares the same
+ * missing token, so it can't help either), then logged auth_failed_expired —
+ * the identical triple, forever, spawning a doomed child process each time.
+ *
+ * The fix: a futile-refresh short-circuit. When the token is expired AND has
+ * no refresh token, refreshIfNeeded re-reads once (to catch an out-of-band
+ * `claude login`) and otherwise returns the auth verdict WITHOUT the OAuth
+ * call or the CLI-fallback spawn, logging at most once per cooldown window.
+ *
+ * Run: timeout 120 npx vitest run src/main/lib/__tests__/credentials-futile-refresh.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterAll } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+// credentials.cjs freezes CREDS_PATH and REFRESH_LOG_PATH from os.homedir() at
+// require time. os.homedir() honors $HOME on POSIX, so point HOME at a temp
+// dir BEFORE the require (not in beforeEach — that runs too late) so both the
+// creds file we write and the log the code writes resolve under our sandbox.
+const originalHome = process.env.HOME;
+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-cred-futile-'));
+process.env.HOME = tmpHome;
+
+const credentials = require('../credentials.cjs');
+const { isRefreshFutile, refreshIfNeeded, __resetFutileRefreshThrottle } = credentials;
+
+const CREDS_FILE = path.join(tmpHome, '.claude', '.credentials.json');
+const LOG_FILE = path.join(tmpHome, '.claude', 'session-manager', 'credential-refresh.log');
+
+function writeCreds(oauth) {
+  fs.mkdirSync(path.dirname(CREDS_FILE), { recursive: true });
+  fs.writeFileSync(CREDS_FILE, JSON.stringify({ claudeAiOauth: oauth }), 'utf8');
+}
+
+function readLogLines() {
+  try {
+    return fs.readFileSync(LOG_FILE, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+  } catch {
+    return [];
+  }
+}
+
+beforeEach(() => {
+  // Clean slate per test: no stale creds file, no carried-over log or throttle.
+  try { fs.unlinkSync(CREDS_FILE); } catch { /* absent */ }
+  try { fs.unlinkSync(LOG_FILE); } catch { /* absent */ }
+  __resetFutileRefreshThrottle();
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+test('isRefreshFutile: expired + no refresh token is futile; anything else is not', () => {
+  const past = Date.now() - 60_000;
+  const future = Date.now() + 60 * 60_000;
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: past })).toBe(true);
+  // Has a refresh token → OAuth grant is worth attempting, not futile.
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: past, refreshToken: 'r' })).toBe(false);
+  // Not expired → not futile even without a refresh token.
+  expect(isRefreshFutile({ accessToken: 'a', expiresAt: future })).toBe(false);
+});
+
+test('a futile refresh returns an auth verdict without spawning the CLI fallback, and logs the no-refresh-token event once', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 }); // expired, no refreshToken
+
+  const res = await refreshIfNeeded();
+
+  expect(res.kind).toBe('auth');
+  expect(res.message).toMatch(/no refresh token/i);
+  expect(typeof res.expiredAt).toBe('number');
+
+  const events = readLogLines().map((e) => e.event);
+  // The distinctive no-refresh-token event fires...
+  expect(events).toContain('auth_failed_expired_no_refresh_token');
+  // ...and the storm's spawn/oauth triple never runs.
+  expect(events).not.toContain('cli_fallback_ok');
+  expect(events).not.toContain('cli_fallback_failed');
+  expect(events).not.toContain('oauth_refresh_unsupported');
+});
+
+test('repeated polls in the cooldown window do NOT re-log — the every-15s storm is suppressed', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 });
+
+  // Simulate several poll cycles back-to-back (as pollLoop would, every 15 s).
+  for (let i = 0; i < 5; i++) {
+    const res = await refreshIfNeeded();
+    expect(res.kind).toBe('auth');
+  }
+
+  const futileLogs = readLogLines().filter((e) => e.event === 'auth_failed_expired_no_refresh_token');
+  expect(futileLogs.length).toBe(1); // once, not five times
+});
+
+test('an out-of-band `claude login` (fresh creds on disk) is picked up on the next call', async () => {
+  writeCreds({ accessToken: 'expired', expiresAt: Date.now() - 60_000 });
+  expect((await refreshIfNeeded()).kind).toBe('auth');
+
+  // User runs `claude` in a terminal → fresh creds land on disk.
+  writeCreds({ accessToken: 'fresh', expiresAt: Date.now() + 60 * 60_000 });
+
+  const res = await refreshIfNeeded();
+  expect(res.kind).toBe('ok');
+  expect(res.creds.accessToken).toBe('fresh');
+});

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

@@ -1,9 +1,13 @@
 /**
- * epicWorktreeProjectConfig.test.cjs — PRD 1035: the per-project "disable
- * Epic worktree isolation" UI toggle. Points the module at a throwaway
- * tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH so it never touches
- * the real ~/.claude/session-manager/epic-worktree-project-config.json on
- * the machine running the tests.
+ * epicWorktreeProjectConfig.test.cjs — PRD 1035/1390: the per-project "disable
+ * Epic worktree isolation" UI toggle, now stored at
+ * `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json`
+ * instead of a single machine-wide map. Uses real mkdtemp'd project cwds (the
+ * same convention as epicStatusMirror.test.cjs) since the file location is
+ * now derived from `cwd` via opsPath(), not from a single overridable path.
+ * SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH still points the LEGACY global map (the
+ * one-shot migration source) at a throwaway tmpdir file, so tests never touch
+ * the real ~/.claude/session-manager/epic-worktree-project-config.json.
  *
  * Run: timeout 120 npx vitest run src/main/lib/__tests__/epicWorktreeProjectConfig.test.cjs
  */
@@ -16,60 +20,79 @@ const os = require('node:os');
 const path = require('node:path');
 
 let tmpRoot;
-let configFile;
+let legacyConfigFile;
 let originalOverride;
+const projectDirs = [];
 
 beforeEach(() => {
   tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-epic-worktree-project-config-'));
-  configFile = path.join(tmpRoot, 'config.json');
+  legacyConfigFile = path.join(tmpRoot, 'legacy-config.json');
   originalOverride = process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = configFile;
+  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = legacyConfigFile;
 });
 
 afterEach(() => {
   if (originalOverride === undefined) delete process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
   else process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = originalOverride;
   fs.rmSync(tmpRoot, { recursive: true, force: true });
+  while (projectDirs.length) fs.rmSync(projectDirs.pop(), { recursive: true, force: true });
 });
 
 function freshModule() {
   return require('../epicWorktreeProjectConfig.cjs');
 }
 
+function mkProjectCwd(name) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `sm-epic-worktree-project-${name}-`));
+  projectDirs.push(dir);
+  return dir;
+}
+
+function perProjectFile(m, cwd) {
+  return m.perProjectConfigPath(cwd);
+}
+
 test('defaults to not disabled for a project never touched', () => {
   const m = freshModule();
-  expect(m.isEpicWorktreeDisabledForProject('/some/project')).toBe(false);
+  const cwd = mkProjectCwd('a');
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
 });
 
-test('setEpicWorktreeDisabledForProject(true) persists across a fresh read', () => {
+test('setEpicWorktreeDisabledForProject(true) persists across a fresh read, in the per-project ops file', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(true);
-  expect(fs.existsSync(configFile)).toBe(true);
-  const onDisk = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  expect(onDisk).toEqual({ '/proj/a': true });
+  const cwd = mkProjectCwd('a');
+  m.setEpicWorktreeDisabledForProject(cwd, true);
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(true);
+  const file = perProjectFile(m, cwd);
+  expect(fs.existsSync(file)).toBe(true);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: true });
 });
 
 test('is scoped per cwd — a different project is unaffected', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/b')).toBe(false);
+  const cwdA = mkProjectCwd('a');
+  const cwdB = mkProjectCwd('b');
+  m.setEpicWorktreeDisabledForProject(cwdA, true);
+  expect(m.isEpicWorktreeDisabledForProject(cwdB)).toBe(false);
 });
 
-test('setEpicWorktreeDisabledForProject(false) clears the entry rather than writing false', () => {
+test('setEpicWorktreeDisabledForProject(false) writes disabled:false rather than deleting the file', () => {
   const m = freshModule();
-  m.setEpicWorktreeDisabledForProject('/proj/a', true);
-  m.setEpicWorktreeDisabledForProject('/proj/a', false);
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(false);
-  const onDisk = JSON.parse(fs.readFileSync(configFile, 'utf8'));
-  expect(onDisk).toEqual({});
+  const cwd = mkProjectCwd('a');
+  m.setEpicWorktreeDisabledForProject(cwd, true);
+  m.setEpicWorktreeDisabledForProject(cwd, false);
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
+  const file = perProjectFile(m, cwd);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: false });
 });
 
-test('a missing or corrupt config file reads as not-disabled rather than throwing', () => {
+test('a missing or corrupt per-project config file reads as not-disabled rather than throwing', () => {
   const m = freshModule();
-  fs.mkdirSync(path.dirname(configFile), { recursive: true });
-  fs.writeFileSync(configFile, '{ not valid json');
-  expect(m.isEpicWorktreeDisabledForProject('/proj/a')).toBe(false);
+  const cwd = mkProjectCwd('a');
+  const file = perProjectFile(m, cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, '{ not valid json');
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
 });
 
 test('isEpicWorktreeDisabledForProject rejects a non-string cwd instead of throwing', () => {
@@ -77,3 +100,38 @@ test('isEpicWorktreeDisabledForProject rejects a non-string cwd instead of throw
   expect(m.isEpicWorktreeDisabledForProject(null)).toBe(false);
   expect(m.isEpicWorktreeDisabledForProject(undefined)).toBe(false);
 });
+
+test('one-shot migration: a legacy global entry seeds the new per-project file on first read', () => {
+  const m = freshModule();
+  const cwd = mkProjectCwd('a');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ [cwd]: true }));
+
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(true);
+  const file = perProjectFile(m, cwd);
+  expect(fs.existsSync(file)).toBe(true);
+  expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({ disabled: true });
+
+  // The legacy file itself is left in place, untouched.
+  expect(JSON.parse(fs.readFileSync(legacyConfigFile, 'utf8'))).toEqual({ [cwd]: true });
+});
+
+test('migration leaves the legacy map intact for OTHER, still-unmigrated projects', () => {
+  const m = freshModule();
+  const cwdA = mkProjectCwd('a');
+  const cwdB = mkProjectCwd('b');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ [cwdA]: true, [cwdB]: true }));
+
+  // Touching cwdA migrates only cwdA's own per-project file.
+  expect(m.isEpicWorktreeDisabledForProject(cwdA)).toBe(true);
+  expect(fs.existsSync(perProjectFile(m, cwdB))).toBe(false);
+
+  // cwdB still resolves correctly straight from the untouched legacy map.
+  expect(m.isEpicWorktreeDisabledForProject(cwdB)).toBe(true);
+});
+
+test('a project with no legacy entry migrates to disabled:false without throwing', () => {
+  const m = freshModule();
+  const cwd = mkProjectCwd('a');
+  fs.writeFileSync(legacyConfigFile, JSON.stringify({ '/some/other/project': true }));
+  expect(m.isEpicWorktreeDisabledForProject(cwd)).toBe(false);
+});

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

@@ -847,34 +847,28 @@ test('[epic] SM_EPIC_WORKTREE_DISABLE=1 restores in-place behaviour independentl
 
 test('[epic] the per-project UI toggle (epicWorktreeProjectConfig.cjs) disables isolation for just that cwd', async () => {
   const projectConfig = require('../epicWorktreeProjectConfig.cjs');
-  const originalOverride = process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-  process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = path.join(tmpRoot, 'epic-worktree-project-config.json');
-  try {
-    projectConfig.setEpicWorktreeDisabledForProject(repoCwd, true);
-    expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(true);
+  projectConfig.setEpicWorktreeDisabledForProject(repoCwd, true);
+  expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(true);
 
-    const result = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-x' });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toMatch(/isolation toggle/);
-
-    // A different, untouched project cwd is unaffected — the toggle is
-    // per-project, not machine-wide like the env var.
-    const otherCwd = path.join(tmpRoot, 'other-repo');
-    initRepo(otherCwd);
-    const otherResult = await gitWorktree.createEpicWorktree({ cwd: otherCwd, epicId: 'toggle-y' });
-    expect(otherResult.ok).toBe(true);
-    await gitWorktree.cleanupEpicWorktree({ cwd: otherCwd, dir: otherResult.dir, branch: otherResult.branch });
-
-    // Turning it back off restores isolation for the original project.
-    projectConfig.setEpicWorktreeDisabledForProject(repoCwd, false);
-    expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(false);
-    const restored = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-z' });
-    expect(restored.ok).toBe(true);
-    await gitWorktree.cleanupEpicWorktree({ cwd: repoCwd, dir: restored.dir, branch: restored.branch });
-  } finally {
-    if (originalOverride === undefined) delete process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH;
-    else process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH = originalOverride;
-  }
+  const result = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-x' });
+  expect(result.ok).toBe(false);
+  expect(result.reason).toMatch(/isolation toggle/);
+
+  // A different, untouched project cwd is unaffected — the toggle is
+  // per-project (its own <cwd>/session-manager-operations/prompt-sessions/
+  // epic-worktree-config.json), not machine-wide like the env var.
+  const otherCwd = path.join(tmpRoot, 'other-repo');
+  initRepo(otherCwd);
+  const otherResult = await gitWorktree.createEpicWorktree({ cwd: otherCwd, epicId: 'toggle-y' });
+  expect(otherResult.ok).toBe(true);
+  await gitWorktree.cleanupEpicWorktree({ cwd: otherCwd, dir: otherResult.dir, branch: otherResult.branch });
+
+  // Turning it back off restores isolation for the original project.
+  projectConfig.setEpicWorktreeDisabledForProject(repoCwd, false);
+  expect(projectConfig.isEpicWorktreeDisabledForProject(repoCwd)).toBe(false);
+  const restored = await gitWorktree.createEpicWorktree({ cwd: repoCwd, epicId: 'toggle-z' });
+  expect(restored.ok).toBe(true);
+  await gitWorktree.cleanupEpicWorktree({ cwd: repoCwd, dir: restored.dir, branch: restored.branch });
 });
 
 test('[epic] reconcileWorktreesOnBoot removes a leaked epic worktree with no liveness predicate given', async () => {

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

@@ -112,14 +112,21 @@ test('writeGuardShims: rewriting the pointer to a DIFFERENT app root lets an alr
   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).
+  // its own copy of scripts/hooks/guard-prd-writes.cjs — the file guardShims
+  // reads through the pointer at invocation time — plus the sibling policy
+  // module it `require()`s at load time (guard-prd-writes-policy.cjs, PRD
+  // 1415); a real upgrade ships both since both are listed in package.json's
+  // "files".
   const secondAppRoot = await mkTmp('sm-guard-shims-upgraded-app-');
-  await fsp.mkdir(path.join(secondAppRoot, 'scripts', 'hooks'), { recursive: true });
+  await fsp.mkdir(path.join(secondAppRoot, 'scripts', 'hooks', 'lib'), { recursive: true });
   await fsp.copyFile(
     path.join(APP_ROOT, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
     path.join(secondAppRoot, 'scripts', 'hooks', 'guard-prd-writes.cjs'),
   );
+  await fsp.copyFile(
+    path.join(APP_ROOT, 'scripts', 'hooks', 'lib', 'guard-prd-writes-policy.cjs'),
+    path.join(secondAppRoot, 'scripts', 'hooks', 'lib', 'guard-prd-writes-policy.cjs'),
+  );
 
   const r = await writeGuardShims({ homeDir, appRoot: secondAppRoot });
   expect(r.ok).toBe(true);

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

@@ -9,7 +9,7 @@
 // batteries. These tests pin the pure decision, the audit rate-limit and the
 // escalation, with loadavg/cores/clock all injected.
 const assert = require('node:assert/strict');
-const { isLoadGated, createLoadGate, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
+const { isLoadGated, createLoadGate, topCpuConsumers, AUDIT_INTERVAL_MS } = require('../loadGate.cjs');
 const { loadGateThreshold, LOAD_GATE_PER_CORE } = require('../schedulerConfig.cjs');
 
 const ORIGINAL_ENV = process.env.SM_LOAD_GATE_PER_CORE;
@@ -65,6 +65,49 @@ test('SM_LOAD_GATE_PER_CORE is honored and clamped to [0.25, 4]; 0 disables; gar
   assert.equal(loadGateThreshold(), 0.85);
 });
 
+// ─── topCpuConsumers: platform-correct ps invocation ───────────────────────
+//
+// The audit line the scheduler warn-logs when the load gate escalates. Purely
+// diagnostic (nothing branches on it) but it was blank on macOS: the code only
+// ran the GNU `ps --sort` form, which BSD ps rejects with "illegal option",
+// so every Mac logged `top CPU: n/a` exactly when the operator needed to know
+// what was saturating the box.
+
+test('Linux uses the GNU ps form (-eo … --sort=-pcpu) and skips the header row', () => {
+  const calls = [];
+  const fakeExec = (bin, args) => {
+    calls.push({ bin, args });
+    return 'PID %CPU COMMAND\n  1 90.0 node\n  2 10.0 tsc\n';
+  };
+  const rows = topCpuConsumers(2, { execImpl: fakeExec, platform: 'linux' });
+  assert.deepEqual(calls[0], { bin: 'ps', args: ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'] });
+  assert.deepEqual(rows, ['1 90.0 node', '2 10.0 tsc']);
+});
+
+test('macOS uses the BSD ps form (-Aco … -r), NOT the GNU --sort that BSD ps rejects', () => {
+  const calls = [];
+  const fakeExec = (bin, args) => {
+    calls.push({ bin, args });
+    return '  PID %CPU COMM\n  847 94.4 suggestd\n  443 15.1 WindowServer\n';
+  };
+  const rows = topCpuConsumers(3, { execImpl: fakeExec, platform: 'darwin' });
+  assert.deepEqual(calls[0].args, ['-Aco', 'pid,pcpu,comm', '-r']);
+  assert.ok(!calls[0].args.some((a) => String(a).includes('--sort')), 'must not pass the GNU --sort to BSD ps');
+  assert.deepEqual(rows, ['847 94.4 suggestd', '443 15.1 WindowServer']);
+});
+
+test('an unsupported platform returns [] without ever spawning ps', () => {
+  let spawned = false;
+  const rows = topCpuConsumers(3, { execImpl: () => { spawned = true; return ''; }, platform: 'win32' });
+  assert.deepEqual(rows, []);
+  assert.equal(spawned, false);
+});
+
+test('a ps failure (throw) degrades to [] rather than propagating — the audit line is best-effort', () => {
+  const rows = topCpuConsumers(3, { execImpl: () => { throw new Error('boom'); }, platform: 'darwin' });
+  assert.deepEqual(rows, []);
+});
+
 // ─── createLoadGate: decision, 1-minute-only, bypass ───────────────────────
 
 function gateWith({ l1 = 12.95, l5 = 0, l15 = 0, cores = 14, threshold = 0.85, clock }) {

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

@@ -73,6 +73,20 @@ test('assertOpsWrite throws for a refused write and is silent for an allowed one
   assert.doesNotThrow(() => assertOpsWrite(`${P}/project-brief/brief.json`, 'project-home'));
 });
 
+test('assertOpsWrite fails closed (not a raw crash) on a relative path that looks like it is inside an ops root', () => {
+  // A caller that skips opsPath/resolveProjectRoot (which already throw on a
+  // relative cwd) and builds its own path string by hand must still get a
+  // graceful, catchable refusal here — this is the last line of defense
+  // (PRD 1082). Before this guard, classifyCwd's absolute-path check (added
+  // for the worktree-relative-cwd hazard) left innermostOpsRoot null for a
+  // relative path, and path.dirname(null) threw an untagged TypeError
+  // instead of the intended `unknownCwd`-tagged Error.
+  assert.throws(
+    () => assertOpsWrite('session-manager-operations/scheduler/state/queue.json', 'scheduler'),
+    (e) => e.unknownCwd === true && /absolute/.test(e.message),
+  );
+});
+
 test('every declared owner is a non-empty string (table sanity)', () => {
   for (const [ns, owner] of Object.entries(OWNERS)) {
     assert.equal(typeof owner, 'string', `${ns} owner must be a string`);

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

@@ -56,7 +56,7 @@ function freshTelemetry(home) {
   process.env.HOME = home;
   // Explicit opt-in: overrides the test-environment no-op guard so this
   // suite's real telemetryClient calls actually persist into an isolated dir.
-  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.claude', 'session-manager');
   for (const p of ['../telemetryClient.cjs', '../../config.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];
@@ -133,7 +133,7 @@ function makeDeps({ home, telemetryClient, config, tabCwds }) {
 }
 
 function watermarksFileFor(home) {
-  return path.join(home, '.config', 'session-manager', 'telemetry-watermarks.json');
+  return path.join(home, '.claude', 'session-manager', 'telemetry-watermarks.json');
 }
 
 async function readWatermarks(home) {
@@ -569,7 +569,7 @@ test('bootDrain always drains with reason "boot", and drains a second time with
 
 test('drainBacklog resolves (never rejects) when readdir fails, telemetryClient throws, and the watermarks file is corrupt', async () => {
   const home = await mkHome();
-  await fsp.mkdir(path.join(home, '.config', 'session-manager'), { recursive: true });
+  await fsp.mkdir(path.join(home, '.claude', 'session-manager'), { recursive: true });
   await fsp.writeFile(watermarksFileFor(home), 'not valid { json', 'utf8');
   const project = await mkProject('contained');
   writeErrorsFile(project, recentDateStr(), [errLine(1)]);
@@ -584,7 +584,7 @@ test('drainBacklog resolves (never rejects) when readdir fails, telemetryClient
     logLine: async () => { throw new Error('boom client'); },
     flush: async () => { throw new Error('boom flush'); },
     isPending: async () => { throw new Error('boom pending'); },
-    sentPath: () => path.join(home, '.config', 'session-manager', 'telemetry-sent.json'),
+    sentPath: () => path.join(home, '.claude', 'session-manager', 'telemetry-sent.json'),
   };
   const deps = {
     sessionsStore: { load: async () => ({ tabs: [{ cwd: project }] }) },

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

@@ -40,7 +40,7 @@ function freshModules(home) {
   process.env.HOME = home;
   // Explicit opt-in: overrides the test-environment no-op guard so this
   // suite's real telemetryClient calls actually persist into an isolated dir.
-  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.config', 'session-manager');
+  process.env.SM_TELEMETRY_SPOOL = path.join(home, '.claude', 'session-manager');
   for (const p of ['../telemetryConsent.cjs', '../telemetryClient.cjs', '../telemetrySettings.cjs', '../machineProfile.cjs', '../../config.cjs']) {
     const resolved = require.resolve(p);
     delete require.cache[resolved];
@@ -105,7 +105,7 @@ test('turning off does NOT clear telemetry-sent.json or the watermarks — re-en
   expect(JSON.parse(sentPathContent).ids.length).toBeGreaterThan(0);
 
   // Also seed a watermarks file to prove opt-out leaves it untouched.
-  const watermarksDir = path.join(home, '.config', 'session-manager');
+  const watermarksDir = path.join(home, '.claude', 'session-manager');
   await fsp.mkdir(watermarksDir, { recursive: true });
   const watermarksPath = path.join(watermarksDir, 'telemetry-watermarks.json');
   const watermarksBefore = { 'abc123/errors-2026-01-01.jsonl': { bytesEnqueued: 100, bytesConfirmed: 100 } };

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

@@ -37,7 +37,7 @@ async function mkHome() {
   process.env.HOME = dir;
   // Explicit opt-in: overrides the test-environment no-op guard so this
   // suite's real telemetryClient calls actually persist into an isolated dir.
-  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.config', 'session-manager');
+  process.env.SM_TELEMETRY_SPOOL = path.join(dir, '.claude', 'session-manager');
   return dir;
 }
 

package/src/main/lib/agentModelResolve.cjs

@@ -238,6 +238,7 @@ async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLB
 
 module.exports = {
   FALLBACK_MODEL,
+  AGENT_BODY_CHAR_CAP,
   resolveEpicModel,
   findAgentTypeByClaudeSessionId,
   findEpicByClaudeSessionId,

package/src/main/lib/credentials.cjs

@@ -120,6 +120,38 @@ function isExpiringSoon(creds, withinMs = 5 * 60_000) {
   return ms !== null && ms - Date.now() < withinMs;
 }
 
+/**
+ * isRefreshFutile(creds) → boolean
+ *
+ * True when the token is already expired AND there is no refresh token to
+ * present. In that state every refresh avenue is a dead end: tryOAuthRefresh
+ * short-circuits to 'unsupported' (it needs `creds.refreshToken`), and the
+ * `claude --version` CLI fallback performs its own silent OAuth refresh from
+ * that SAME missing refresh token, so it cannot help either. The only recovery
+ * is an out-of-band `claude login` — which refreshIfNeeded picks up on its very
+ * next call via the isExpiringSoon early-return, since fresh creds never reach
+ * this path. Left ungated, this state made pollLoop spawn a `claude --version`
+ * process and write the oauth_refresh_unsupported → cli_fallback_ok →
+ * auth_failed_expired triple on EVERY 15 s poll, forever (observed 2026-09-23:
+ * expiredAtMs 1775277875159, identical triple every ~15 min across the log).
+ */
+function isRefreshFutile(creds) {
+  return isExpired(creds) && !creds.refreshToken;
+}
+
+// Throttle for the futile-refresh state above: once seen, don't respawn the
+// CLI fallback or re-log the auth triple on every poll. Re-probe at most once
+// per this window (an external `claude login` is still caught immediately by
+// refreshIfNeeded's isExpiringSoon early-return, and by the cheap re-read
+// below — neither needs the storm). Mirrors loadGate.cjs's AUDIT_INTERVAL_MS.
+const FUTILE_REFRESH_COOLDOWN_MS = 15 * 60_000;
+let lastFutileRefreshLoggedAt = null;
+
+/** Test-only: reset the futile-refresh throttle so each test starts clean. */
+function __resetFutileRefreshThrottle() {
+  lastFutileRefreshLoggedAt = null;
+}
+
 async function writeCredentials(rawData, freshOauth, source = 'file') {
   const next = { ...rawData, claudeAiOauth: { ...rawData.claudeAiOauth, ...freshOauth } };
   if (source === 'keychain') {
@@ -222,6 +254,33 @@ async function refreshIfNeeded(forceRefresh = false) {
 
   const alreadyExpired = isExpired(creds);
 
+  // Futile-refresh short-circuit: token already expired AND no refresh token
+  // to present. Every downstream avenue (OAuth grant, `claude --version` CLI
+  // fallback) is a guaranteed dead end from the same missing token, so running
+  // them on every 15 s poll only spawns a doomed child process and re-logs the
+  // same triple forever (2026-09-23 storm). Re-read once — cheap, and the ONE
+  // real recovery (`claude login`) lands here — then, if still futile, return
+  // the auth verdict WITHOUT the OAuth call or the CLI-fallback spawn, logging
+  // at most once per FUTILE_REFRESH_COOLDOWN_MS instead of every poll.
+  if (isRefreshFutile(creds)) {
+    const recheckCr = await readCredentials();
+    if (recheckCr.kind === 'ok' && !isRefreshFutile(recheckCr.creds) && !isExpired(recheckCr.creds)) {
+      appendRefreshLog({ event: 'externally_refreshed_ok', recheckExpiresAt: recheckCr.creds.expiresAt ?? null });
+      lastFutileRefreshLoggedAt = null;
+      return { kind: 'ok', creds: recheckCr.creds };
+    }
+    const nowMs = Date.now();
+    if (lastFutileRefreshLoggedAt === null || nowMs - lastFutileRefreshLoggedAt >= FUTILE_REFRESH_COOLDOWN_MS) {
+      lastFutileRefreshLoggedAt = nowMs;
+      appendRefreshLog({ event: 'auth_failed_expired_no_refresh_token', expiredAtMs: expiresAtMs(creds) });
+    }
+    return {
+      kind: 'auth',
+      message: 'Credentials expired and cannot be auto-refreshed (no refresh token). Run `claude` in a terminal to log in.',
+      expiredAt: expiresAtMs(creds),
+    };
+  }
+
   // Stretch: try OAuth refresh endpoint first.
   const oauthResult = await tryOAuthRefresh(creds);
   appendRefreshLog({ event: `oauth_refresh_${oauthResult.kind}`, message: oauthResult.message ?? null });
@@ -277,8 +336,11 @@ module.exports = {
   expiresAtMs,
   isExpired,
   isExpiringSoon,
+  isRefreshFutile,
   refreshIfNeeded,
   parseCredsRaw,
+  __resetFutileRefreshThrottle,
+  FUTILE_REFRESH_COOLDOWN_MS,
   KEYCHAIN_SERVICE,
   CREDS_PATH,
 };

package/src/main/lib/cwdClassify.cjs

@@ -152,6 +152,21 @@ function classifyCwd(cwd) {
   if (!cwd || typeof cwd !== 'string') {
     return { kind: 'unknown', projectRoot: null, outermostOpsRoot: null, innermostOpsRoot: null, reason: 'cwd is not a non-empty string' };
   }
+  // Must run BEFORE inspectGit: nearestGitEntry walks ancestors via
+  // fs.statSync, which silently resolves a relative `dir` against
+  // process.cwd() — so a relative cwd that happens to be a real subpath of
+  // WHATEVER PROCESS IS RUNNING THIS CODE (not the transcript's actual
+  // project) can walk up into a real `.git`, including a linked worktree's
+  // `.git` FILE, and return that worktree's real main-tree root as if it
+  // were the relative fragment's own project. The 'worktree' branch below
+  // returns early on g.shape alone with no absolute check of its own, so
+  // this guard cannot be deferred to after inspectGit runs (confirmed via
+  // opsRootAbsoluteCwd.test.cjs: reproduces in every git worktree, not just
+  // job worktrees — process.cwd() there is a worktree whose .git FILE
+  // resolves back to the real main tree root).
+  if (!path.isAbsolute(cwd)) {
+    return { kind: 'unknown', projectRoot: null, outermostOpsRoot: null, innermostOpsRoot: null, reason: 'cwd is not an absolute path' };
+  }
   const parts = cwd.split(path.sep);
   const first = parts.indexOf(OPS_DIRNAME);
   const last = parts.lastIndexOf(OPS_DIRNAME);