claude-code-session-manager 0.95.0 → 0.97.0

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

package/src/main/lib/definitionOfDone.cjs

@@ -14,6 +14,7 @@ const path = require('node:path');
 const { spawn, spawnSync } = require('node:child_process');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolvePrdWriteDir } = require('./prdLocations.cjs');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 // Regex identifying meta/dod slugs that must NOT influence the batchKey.
 // This is the load-bearing loop-avoidance filter: when the gate job itself
@@ -21,11 +22,6 @@ const { resolvePrdWriteDir } = require('./prdLocations.cjs');
 // a no-op (idempotent) instead of re-firing forever.
 const DOD_SLUG_RE = /(^|-)dod(-|$)|definition-of-done/i;
 
-const RUNS_DIR = path.join(
-  os.homedir(),
-  '.claude', 'session-manager', 'scheduled-plans', 'runs'
-);
-
 /**
  * Compute a stable short hash for a completed job-set.
  *
@@ -62,7 +58,7 @@ function batchKey(jobs) {
 function reportPathFor(key) {
   if (!/^[0-9a-f]+$/.test(key)) throw new Error(`invalid batchKey: ${key}`);
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  return path.join(RUNS_DIR, ts, `definition-of-done-${key}.md`);
+  return path.join(schedulerPaths.runsDir(), ts, `definition-of-done-${key}.md`);
 }
 
 /**
@@ -70,10 +66,10 @@ function reportPathFor(key) {
  * run subdirectory. Scans runs/<ts>/ (shallow, one level).
  *
  * @param {string} key       Output of batchKey()
- * @param {string} [runsDir] Override for testing; defaults to RUNS_DIR
+ * @param {string} [runsDir] Override for testing; defaults to schedulerPaths.runsDir()
  * @returns {boolean}
  */
-function reportExists(key, runsDir = RUNS_DIR) {
+function reportExists(key, runsDir = schedulerPaths.runsDir()) {
   if (!/^[0-9a-f]+$/.test(key)) throw new Error(`invalid batchKey: ${key}`);
   let entries;
   try {
@@ -604,7 +600,7 @@ const STATUS_EMOJI = { pass: '✅', fail: '❌', unverifiable: '⚠️' };
 function writeReport(key, { acResults = [], riskFlags = [], runsDir } = {}) {
   if (!/^[0-9a-f]+$/.test(key)) throw new Error(`invalid batchKey: ${key}`);
 
-  const resolvedRunsDir = runsDir ?? RUNS_DIR;
+  const resolvedRunsDir = runsDir ?? schedulerPaths.runsDir();
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   const dir = path.join(resolvedRunsDir, ts);
   const reportPath = path.join(dir, `definition-of-done-${key}.md`);
@@ -781,10 +777,10 @@ const WATERMARK_FILENAME = '.dod-watermark.json';
  * sidecar means "beginning of time" (process everything), matching the
  * pre-watermark unbounded behavior on first-ever drain.
  *
- * @param {string} [runsDir] Override for testing; defaults to RUNS_DIR
+ * @param {string} [runsDir] Override for testing; defaults to schedulerPaths.runsDir()
  * @returns {string|null}  ISO8601 timestamp, or null if unset/unreadable.
  */
-function readWatermark(runsDir = RUNS_DIR) {
+function readWatermark(runsDir = schedulerPaths.runsDir()) {
   try {
     const raw = fs.readFileSync(path.join(runsDir, WATERMARK_FILENAME), 'utf8');
     const parsed = JSON.parse(raw);
@@ -799,9 +795,9 @@ function readWatermark(runsDir = RUNS_DIR) {
  * jobs that completed after it.
  *
  * @param {string} lastFinishedAt  ISO8601 timestamp.
- * @param {string} [runsDir]       Override for testing; defaults to RUNS_DIR
+ * @param {string} [runsDir]       Override for testing; defaults to schedulerPaths.runsDir()
  */
-function writeWatermark(lastFinishedAt, runsDir = RUNS_DIR) {
+function writeWatermark(lastFinishedAt, runsDir = schedulerPaths.runsDir()) {
   fs.mkdirSync(runsDir, { recursive: true });
   _writeFileAtomic(
     path.join(runsDir, WATERMARK_FILENAME),

package/src/main/lib/effectiveModelInfo.cjs

@@ -28,6 +28,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { splitFrontmatter } = require('./prdFrontmatter.cjs');
 const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
+const schedulerPaths = require('./schedulerPaths.cjs');
 
 // Deliberately stays a FIXED alias set (reviewed against the catalog-driven raw picker): it answers
 // "alias vs concrete id", not "which options to offer", so live catalog ids must not enter it.
@@ -51,13 +52,6 @@ const MAX_RUN_LOG_HEAD_BYTES = 64 * 1024;
 // pass over a transcript that can reach tens of MB. O(min(size, cap)).
 const MAX_TRANSCRIPT_TAIL_BYTES = 8 * 1024 * 1024;
 
-// Mirrors scheduler.cjs's own ROOT/RUNS_DIR constants (same convention as
-// queueStore.cjs's LEGACY_QUEUE_PATH, which duplicates this literal rather
-// than requiring scheduler.cjs's ~530KB module graph for one path).
-function runsDir(homeDir) {
-  return path.join(homeDir, '.claude', 'session-manager', 'scheduled-plans', 'runs');
-}
-
 function isConcreteModelId(modelAlias) {
   if (!modelAlias) return false;
   // 'opus[1m]' is an alias with a context suffix; 'claude-opus-4-7[1m]' keeps its id.
@@ -232,10 +226,9 @@ function findLatestSchedulerModel(cwd, agentType, deps) {
   const matches = jobs.filter((j) => j && j.agentType === agentType && j.runId && j.slug);
   matches.sort((a, b) => jobTimestampMs(b) - jobTimestampMs(a));
 
-  const homeDir = deps.homeDir || os.homedir();
   const re = /\[scheduler\] agentType=\S+ persona=.*? model=(\S+)/g;
   for (const job of matches) {
-    const logPath = path.join(runsDir(homeDir), job.runId, `${job.slug}.log`);
+    const logPath = path.join(schedulerPaths.runsDir(), job.runId, `${job.slug}.log`);
     const head = readHead(logPath, MAX_RUN_LOG_HEAD_BYTES, deps);
     if (!head) continue;
     let match;

package/src/main/lib/epicWorktreeProjectConfig.cjs

@@ -2,21 +2,30 @@
 
 /**
  * epicWorktreeProjectConfig.cjs — per-project UI toggle for Epic worktree
- * isolation (PRD 1035, final link of the epic-worktree-isolation chain).
+ * isolation (PRD 1035, final link of the epic-worktree-isolation chain;
+ * moved off the machine-wide global map onto the per-project ops root by
+ * PRD 1390).
  *
  * `SM_EPIC_WORKTREE_DISABLE` (gitWorktree.cjs) is an env var, checked once at
  * process start — there was previously no way to turn the feature off for
  * one project from the app itself. This module is that per-project knob:
- * a single JSON file mapping project cwd -> disabled, read by
+ * `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json`
+ * holding `{ disabled: boolean }` for that one project, read by
  * gitWorktree.cjs's `isWorktreeDisabled('epic', cwd)` on every worktree
  * creation attempt, and read/written by Settings.tsx's per-project toggle
  * over the two IPC handlers registered below.
  *
- * Lives under `~/.claude/session-manager/` — machine-runtime bookkeeping,
- * the same tier as scheduler-machine.json (see queueStore.cjs's header
- * comment) — NOT under any project's `session-manager-operations/`, so the
- * single-writer OWNERS law (opsOwnership.cjs) doesn't apply here; this file
- * only ever has one writer (this module) by construction.
+ * By shape the old single global file (`{ "<project-cwd>": true|false }` under
+ * `~/.claude/session-manager/`) was per-project config keyed by project path —
+ * the wrong tier. It now lives in the `prompt-sessions` ops namespace, already
+ * owned by writer 'epics' (opsOwnership.cjs), the same as every other Epic
+ * record. Migration is lossless and one-shot: on first read for a cwd whose
+ * new per-project file doesn't exist yet, the legacy global map is checked for
+ * that cwd's key; if present (the map only ever stores `true` — `false` is
+ * represented by key absence), the new file is seeded with it. The legacy file
+ * itself is left in place — untouched, never deleted — so any OTHER project's
+ * still-unmigrated key keeps resolving correctly until that project is itself
+ * touched.
  *
  * Plain Node (no Electron deps in the read/write helpers) so gitWorktree.cjs
  * — itself Electron-free — can require this lazily without pulling Electron
@@ -26,19 +35,22 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
+const { assertOpsWrite, opsPath } = require('./opsOwnership.cjs');
 
-const DEFAULT_CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'epic-worktree-project-config.json');
+// The old machine-wide map. Read-only from here on (migration source only) —
+// never written again, and deliberately never deleted so unmigrated projects
+// keep working. Resolved per-call (not a frozen const) so tests can point
+// this at a throwaway tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH
+// instead of touching the real machine-level file.
+const DEFAULT_LEGACY_CONFIG_PATH = path.join(os.homedir(), '.claude', 'session-manager', 'epic-worktree-project-config.json');
 
-// Resolved per-call (not a frozen const) so tests can point this at a
-// throwaway tmpdir file via SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH instead of
-// mutating the real machine-level file at DEFAULT_CONFIG_PATH.
-function configPath() {
-  return process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH || DEFAULT_CONFIG_PATH;
+function legacyConfigPath() {
+  return process.env.SM_EPIC_WORKTREE_PROJECT_CONFIG_PATH || DEFAULT_LEGACY_CONFIG_PATH;
 }
 
-function readConfig() {
+function readLegacyConfig() {
   try {
-    const raw = fs.readFileSync(configPath(), 'utf8');
+    const raw = fs.readFileSync(legacyConfigPath(), 'utf8');
     const parsed = JSON.parse(raw);
     return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
   } catch {
@@ -46,31 +58,62 @@ function readConfig() {
   }
 }
 
-function writeConfig(config) {
-  const file = configPath();
+/** `<cwd>/session-manager-operations/prompt-sessions/epic-worktree-config.json` */
+function perProjectConfigPath(cwd) {
+  return opsPath(cwd, 'prompt-sessions', 'epic-worktree-config.json');
+}
+
+function readPerProjectConfigFile(cwd) {
+  try {
+    const raw = fs.readFileSync(perProjectConfigPath(cwd), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function writePerProjectConfig(cwd, config, writer = 'epics') {
+  const file = perProjectConfigPath(cwd);
+  assertOpsWrite(file, writer);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tmp = `${file}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, JSON.stringify(config, null, 2));
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
   fs.renameSync(tmp, file);
 }
 
+/**
+ * One-shot migration: when the per-project file doesn't exist yet, seed it
+ * from the legacy global map's entry for this cwd (present only when it was
+ * explicitly disabled — the legacy map deletes the key on re-enable). Never
+ * touches the legacy file itself.
+ */
+function readOrMigratePerProjectConfig(cwd) {
+  const existing = readPerProjectConfigFile(cwd);
+  if (existing) return existing;
+  const legacyValue = readLegacyConfig()[cwd];
+  if (legacyValue !== true) return { disabled: false };
+  const seeded = { disabled: true };
+  writePerProjectConfig(cwd, seeded);
+  return seeded;
+}
+
 /** True when the project at `cwd` has explicitly turned Epic worktree isolation off. */
 function isEpicWorktreeDisabledForProject(cwd) {
   if (!cwd || typeof cwd !== 'string') return false;
-  return readConfig()[cwd] === true;
+  try {
+    return readOrMigratePerProjectConfig(cwd).disabled === true;
+  } catch {
+    return false;
+  }
 }
 
-/** Persists (or clears, when `disabled` is false) the per-project toggle. */
-function setEpicWorktreeDisabledForProject(cwd, disabled) {
+/** Persists the per-project toggle. */
+function setEpicWorktreeDisabledForProject(cwd, disabled, writer = 'epics') {
   if (!cwd || typeof cwd !== 'string') throw new Error('setEpicWorktreeDisabledForProject: cwd is required');
-  const config = readConfig();
-  if (disabled) {
-    config[cwd] = true;
-  } else {
-    delete config[cwd];
-  }
-  writeConfig(config);
-  return disabled;
+  const value = !!disabled;
+  writePerProjectConfig(cwd, { disabled: value }, writer);
+  return value;
 }
 
 function registerEpicWorktreeProjectConfigHandlers() {
@@ -94,8 +137,9 @@ function registerEpicWorktreeProjectConfigHandlers() {
 }
 
 module.exports = {
-  DEFAULT_CONFIG_PATH,
-  configPath,
+  DEFAULT_LEGACY_CONFIG_PATH,
+  legacyConfigPath,
+  perProjectConfigPath,
   isEpicWorktreeDisabledForProject,
   setEpicWorktreeDisabledForProject,
   registerEpicWorktreeProjectConfigHandlers,

package/src/main/lib/loadGate.cjs

@@ -57,12 +57,36 @@ function isLoadGated(loadavg1, cores, threshold) {
   return loadavg1 / cores > threshold;
 }
 
-/** Best-effort top-N CPU consumers (Linux only). Returns [] anywhere else or on error. */
-function topCpuConsumers(n = 3) {
-  if (process.platform !== 'linux') return [];
+/**
+ * Best-effort top-N CPU consumers, for the audit line the scheduler warn-logs
+ * when the load gate has held jobs past its escalation window. Diagnostic only
+ * — nothing downstream branches on the result, so it fails to [] rather than
+ * throwing. Supported on Linux AND macOS (the two platforms this app targets);
+ * [] anywhere else or on any error.
+ *
+ * The `ps` invocation is platform-specific and NOT interchangeable:
+ *  - Linux (GNU/procps): `ps -eo pid,pcpu,comm --sort=-pcpu`. `--sort` is a
+ *    GNU long option.
+ *  - macOS (BSD ps): has NO `--sort` (`ps: illegal option -- -`, which threw
+ *    and left the gate audit logging `top CPU: n/a` on every Mac). BSD sorts
+ *    with `-r` (by CPU usage) and takes `-A` for all processes, `-c` for the
+ *    executable comm without its path. `ps -Aco pid,pcpu,comm -r` is the
+ *    column-and-sort equivalent.
+ * Both print a `PID %CPU COMM` header we skip, so downstream parsing is shared.
+ * `execImpl` is injected only by the unit test; production uses execFileSync.
+ */
+function topCpuConsumers(n = 3, { execImpl = execFileSync, platform = process.platform } = {}) {
+  let args;
+  if (platform === 'linux') {
+    args = ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'];
+  } else if (platform === 'darwin') {
+    args = ['-Aco', 'pid,pcpu,comm', '-r'];
+  } else {
+    return [];
+  }
   try {
-    const out = execFileSync('ps', ['-eo', 'pid,pcpu,comm', '--sort=-pcpu'], { encoding: 'utf8', timeout: 2000 });
-    return out.split('\n').slice(1, 1 + n).map((l) => l.trim()).filter(Boolean);
+    const out = execImpl('ps', args, { encoding: 'utf8', timeout: 2000 });
+    return String(out).split('\n').slice(1, 1 + n).map((l) => l.trim()).filter(Boolean);
   } catch {
     return [];
   }

package/src/main/lib/opsOwnership.cjs

@@ -60,6 +60,15 @@ const OWNERS = Object.freeze({
   // bilko-host-publisher Epic authors beyond dist/ is agent-Write-tool
   // output, same unenforceable-by-construction class as project-pages/output.
   'bilko-host': 'bilko-host',
+  // Memory Clusters owns its own regenerable per-project cache (PRD 1389) —
+  // memoryAggregate.cjs's clustering result, rebuilt on any explicit
+  // refresh:true. See memory-clusters/README.md.
+  'memory-clusters': 'memory-clusters',
+  // Per-project UI state (PRD 1398) — small renderer prefs that used to live
+  // in cwd-scoped or (worse) global localStorage keys. Written directly by
+  // the renderer through the generic config:write-json IPC with writer:
+  // 'ui-prefs'; no dedicated main-process module. See ui-prefs/README.md.
+  'ui-prefs': 'ui-prefs',
 });
 
 /**
@@ -170,6 +179,20 @@ function assertOpsWrite(absPath, writer) {
   // worktree-cwd hazard (PRD 1082; incidents 2026-08-30, 2026-09-01).
   const { inOps } = parseOpsPath(absPath);
   if (inOps) {
+    // classifyCwd fails closed on a non-absolute absPath (returns
+    // innermostOpsRoot: null) — path.dirname(null) throws a raw, untagged
+    // TypeError, which would crash this "last line of defense" instead of
+    // producing the graceful, catchable refusal every other branch here
+    // gives. A caller that skips the absolute-path helpers (opsPath/
+    // resolveProjectRoot) and hands assertOpsWrite a relative fragment
+    // containing an OPS_ROOT_DIR segment must still fail closed, not crash.
+    if (typeof absPath !== 'string' || !path.isAbsolute(absPath)) {
+      const err = new Error(
+        `refusing to write ${OPS_ROOT_DIR}/ state: absPath must be absolute, got "${absPath}"`,
+      );
+      err.unknownCwd = true;
+      throw err;
+    }
     // innermostOpsRoot (lastIndexOf) is the fact THIS gate keys on; activeSessions
     // truncates at the outermost instead — cwdClassify returns both, unified in
     // neither direction.

package/src/main/lib/planValidator.cjs

@@ -0,0 +1,80 @@
+'use strict';
+
+/**
+ * planValidator.cjs — pure predicate telling a work-item's dispatch whether a
+ * plan-level `validator` job (PRD 1405/1407) will re-review its diff once the
+ * plan finishes, so the per-job finish protocol and per-PRD validation prompt
+ * (PRD 986) can both yield to it instead of duplicating the same review. No
+ * filesystem or scheduler knowledge — the caller supplies the queue rows.
+ */
+
+const { bareSlug } = require('./depSlugResolve.cjs');
+
+/**
+ * hasDownstreamValidator(job, jobs) → boolean
+ *
+ * True iff `jobs` contains a row with `agentType === 'validator'`, status
+ * `pending` or `running`, that reaches `job.slug` transitively by walking
+ * `dependsOn` edges through the supplied rows (e.g. validator -> sink ->
+ * job). A validator job itself never has a downstream validator (it IS the
+ * plan's validation pass). Plans over the `dependsOn` cap point the
+ * validator at only the plan's sink PRDs, so a direct-only check would
+ * wrongly say every non-sink work item has no downstream validator.
+ *
+ * `jobs` may be the machine-wide queue (every project's rows merged), so
+ * when `job.cwd` is known the walk excludes rows carrying a DIFFERENT
+ * explicit `cwd` — a same-bare-named PRD in an unrelated project can never
+ * satisfy this job's validator check. A row with no `cwd` recorded is kept
+ * (queue rows may omit it; `scheduleJobSchema.cjs` makes it optional) rather
+ * than guessed at, since a wrong exclusion (a real validator missed) is far
+ * worse than the narrow residual risk of an unstamped row colliding by bare
+ * name. Slug matching within that scope reuses the canonical
+ * `depSlugResolve.cjs` rule (exact slug, else bare-name with the leading
+ * `NN-` stripped) so this walk agrees with the scheduler's own dependency
+ * gate on what a `dependsOn` entry resolves to.
+ */
+function hasDownstreamValidator(job, jobs) {
+  if (!job || !Array.isArray(jobs)) return false;
+  if (job.agentType === 'validator') return false;
+
+  const projectJobs = job.cwd
+    ? jobs.filter((row) => row && (row.cwd == null || row.cwd === job.cwd))
+    : jobs.filter(Boolean);
+
+  const rowBySlug = new Map();
+  const rowsByBareSlug = new Map();
+  for (const row of projectJobs) {
+    rowBySlug.set(row.slug, row);
+    const bare = bareSlug(row.slug);
+    if (!rowsByBareSlug.has(bare)) rowsByBareSlug.set(bare, []);
+    rowsByBareSlug.get(bare).push(row);
+  }
+  const rowsForSlug = (slug) => {
+    const exact = rowBySlug.get(slug);
+    if (exact) return [exact];
+    return rowsByBareSlug.get(bareSlug(slug)) ?? [];
+  };
+  const matchesJob = (slug) => slug === job.slug || bareSlug(slug) === bareSlug(job.slug);
+
+  const validators = projectJobs.filter((row) => row.agentType === 'validator'
+    && (row.status === 'pending' || row.status === 'running'));
+
+  for (const validator of validators) {
+    const visited = new Set();
+    const queue = Array.isArray(validator.dependsOn) ? [...validator.dependsOn] : [];
+    while (queue.length) {
+      const slug = queue.shift();
+      if (visited.has(slug)) continue;
+      visited.add(slug);
+      if (matchesJob(slug)) return true;
+      for (const row of rowsForSlug(slug)) {
+        for (const depSlug of row.dependsOn ?? []) {
+          if (!visited.has(depSlug)) queue.push(depSlug);
+        }
+      }
+    }
+  }
+  return false;
+}
+
+module.exports = { hasDownstreamValidator };

package/src/main/lib/prdCreate.cjs

@@ -31,6 +31,7 @@ const { DEFAULT_PRD_AGENT_TYPE, assertAgentTypeWritable } = require('./prdAgentT
 const { resolveDepSlug, findNearMatches } = require('./depSlugResolve.cjs');
 const { isFixPlanSlug } = require('./fixPlanSlug.cjs');
 const { isIncomplete, resolveChainTerminals, isValidPlanId, mintPlanId, resolveInheritedPlanId } = require('./prdDisposition.cjs');
+const { sizingWarnings } = require('./prdSizing.cjs');
 
 // A caller-supplied slug that already starts with its own `NN-` (e.g.
 // "254-perf-x") used to silently become the double-prefixed row
@@ -133,10 +134,10 @@ function buildPrdBody(input) {
   const oosLines = oosSource.map((line) => `- ${line}`).join('\n');
 
   const standardsPointer = [
-    `Before writing any code, read \`${STANDARDS_PATH}\` — it has the Performance, Debugging,`,
-    'API-reuse, TDD, and Execution-discipline rules that apply to this PRD. Every rule in it is',
-    'mandatory, especially Execution discipline (bounded commands, verify before done, the',
-    'finish-protocol sentinel).',
+    'Your system prompt carries the ordered run contract.',
+    `\`${STANDARDS_PATH}\` holds the reasoning behind each contract line (Performance, Debugging,`,
+    'API reuse, TDD, Execution discipline) — read the section a line points at when it is unclear;',
+    'do not re-read the whole file every run.',
   ].join('\n');
 
   const bodyLines = [
@@ -496,6 +497,8 @@ async function createPrd(input, remote) {
     epicId: writeResult.epicId ?? null,
     enqueued: false,
     note: 'PRD file written; the queue row is derived by the next scheduler reconcile pass, not created here',
+    // Advisory only (PRD 1403) — never blocks the write. See prdSizing.cjs.
+    warnings: sizingWarnings(input),
   };
 }
 
@@ -541,6 +544,7 @@ function registerAdminRoute(adminHttp, remote) {
       epicId: result.epicId ?? null,
       enqueued: false,
       note: result.note,
+      warnings: result.warnings,
     });
   });
 }