claude-code-session-manager 0.110.0 → 0.112.0

package/src/main/lib/CLAUDE.md

@@ -0,0 +1,48 @@
+# src/main/lib/ — scoped context
+
+Shared main-process helpers (CommonJS `.cjs`). Layout source of truth: `scripts/lib-layout.json`.
+
+## What's here
+
+- `claude/` — claude CLI binary, caps, model/effort resolution.
+- `epic/` — Epic mint, worktrees, active index, spawn plan/cwd, transcripts.
+- `feedback-remote/` — cross-project and customer feedback conduits.
+- `git/` — git exec, worktrees, branch sweeps, job worktrees.
+- `persona-macro/` — agent persona schema/merge, macro library, builtin macros.
+- `prd/` — PRD parsing helpers, admin routes, dep-slug resolution, plan validation.
+- `process/` — child processes, kill tree, env cleaning, pid liveness, instance lock.
+- `scheduler/` — dispatch loop, session slots, gates, supervisors, queue helpers.
+- `telemetry/` — audit/ops error logs, crash and OTLP telemetry.
+- `util/` — generic pure helpers (atomic fs, kebab, home/cwd encoding, JSON extract, tail).
+- top-level files — cross-cutting modules that fit no domain (`opsOwnership`, `activeSessions`, `projectRootResolve`, `cwdClassify`).
+- `__tests__/` — tests for top-level modules; subfolders carry their own.
+
+## Where a new module goes
+
+Put it in the subfolder whose domain it serves; pure and domain-free goes in `util/`.
+A new top-level `lib/` module needs a stated reason (no domain fits) in its header comment,
+and a `scripts/lib-layout.json` entry. Never add a subfolder for one file.
+
+## Reuse before writing
+
+Each of these was found duplicated once. Grep first; extend the canonical one.
+
+| Need | Canonical | Function |
+| --- | --- | --- |
+| Atomic write (tmp+rename) | `util/atomicFs.cjs` | `writeTextAtomic[Sync]`, `writeJsonAtomic[Sync]` |
+| JSON read with fallback | `util/atomicFs.cjs` | `readJsonOr`, `readJsonOrSync` |
+| PID liveness | `process/pidAlive.cjs` | `pidAlive` |
+| Kebab / slug | `util/kebabCase.cjs` | `kebabCase` |
+| Project root, read-only/total (never throws) | `activeSessions.cjs` | `projectRootOf` |
+| Project root, validated; `opsInternal:'refuse'` for writers | `opsOwnership.cjs` | `resolveProjectRoot` |
+| Project root + Epic from session/epic hints | `projectRootResolve.cjs` | `resolveProjectContext` |
+| Ops-root path (single-writer law) | `opsOwnership.cjs` | `opsPath` |
+| Run git | `git/gitExec.cjs` | `execGit` |
+| Spawn `claude -p` (only machine-wide cap) | `scheduler/sessionSlots.cjs` | `acquire`, `release` |
+
+Pin `--model` on every `claude -p` spawn.
+
+## What must NOT be assumed
+
+- Never `path.join` an agent cwd to build an ops path — use `opsPath`.
+- No private process caps, no hand-rolled tmp+rename, no new `JSON.parse(readFileSync)` fallbacks.

package/src/main/lib/activeSessions.cjs

@@ -12,7 +12,7 @@ const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const os = require('node:os');
 const path = require('node:path');
-const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('./gitWorktree.cjs');
+const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('./git/gitWorktree.cjs');
 const { OPS_ROOT_DIR } = require('./opsOwnership.cjs');
 const { classifyCwd, worktreeMainRootOf } = require('./cwdClassify.cjs');
 

package/src/main/lib/classifyPromptTicket.cjs

@@ -16,8 +16,8 @@
  */
 
 const { spawn } = require('node:child_process');
-const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
-const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./claude/claudeBin.cjs');
+const { cleanChildEnv, pathWithUserBins } = require('./process/cleanEnv.cjs');
 
 const CLASSIFY_TIMEOUT_MS = 30_000;
 const CLASSIFY_MODEL = 'sonnet';

package/src/main/lib/{agentModelResolve.cjs → claude/agentModelResolve.cjs}

@@ -29,10 +29,10 @@
 
 const path = require('node:path');
 const os = require('node:os');
-const { splitFrontmatter } = require('./prdFrontmatter.cjs');
-const { readActiveIndex, resolvePersonaPaths } = require('./epicMint.cjs');
-const { resolveMergedPersona, PERSONA_NAME_RE } = require('./personaMerge.cjs');
-const configMgr = require('../config.cjs');
+const { splitFrontmatter } = require('../prd/prdFrontmatter.cjs');
+const { readActiveIndex, resolvePersonaPaths } = require('../epic/epicMint.cjs');
+const { resolveMergedPersona, PERSONA_NAME_RE } = require('../persona-macro/personaMerge.cjs');
+const configMgr = require('../../config.cjs');
 
 /** The hardcoded floor every branch of resolveEpicModel falls back to — --model must never be omitted (CLAUDE.md "Automation model pinning"). */
 const FALLBACK_MODEL = 'sonnet';
@@ -55,7 +55,7 @@ function logDanglingPersonaOnce(cwd, agentType) {
     // Required lazily: opsErrorLog.cjs is a leaf module with no Electron
     // dependency, but keeping this require inside the miss path avoids
     // paying for it on the (overwhelmingly common) hit path.
-    const { appendError } = require('./opsErrorLog.cjs');
+    const { appendError } = require('../telemetry/opsErrorLog.cjs');
     appendError({
       cwd,
       scope: 'agentModelResolve',
@@ -218,10 +218,10 @@ async function resolvePrdPersonaForSpawn({ cwd, agentType, fallbackModel = FALLB
   const miss = { model: fallbackModel, systemPrompt: null, personaPath: null };
   if (!agentType) return miss;
   try {
-    const getBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
+    const getBody = deps.getPersonaBody || require('../../agentLibrary.cjs').getPersonaBody;
     const persona = await getBody({ cwd, name: agentType });
     if (!persona) {
-      const reportOnce = deps.reportDanglingAgentTypeOnce || require('./prdAgentType.cjs').reportDanglingAgentTypeOnce;
+      const reportOnce = deps.reportDanglingAgentTypeOnce || require('../prd/prdAgentType.cjs').reportDanglingAgentTypeOnce;
       reportOnce(cwd, agentType, deps);
       return miss;
     }

package/src/main/lib/{claudeBin.cjs → claude/claudeBin.cjs}

@@ -68,7 +68,7 @@ function __resetForTests() { cached = null; }
 //
 // Every `claude` spawn goes through claudeSpawnTarget so GNOME System Monitor
 // shows a distinct comm per role (sm-claude-job / -chat / -aux) and a labelled
-// argv0. See lib/procName.cjs for the mechanics. Invariants:
+// argv0. See lib/process/procName.cjs for the mechanics. Invariants:
 //  - SM_CLAUDE_BIN set → aliasing SKIPPED, raw value used verbatim (tests point
 //    it at self-locating stubs; it must stay ONE binary, no path splitting).
 //  - aliasBinFor fails open (returns realBin) → no argv0 is set either, so the
@@ -92,7 +92,7 @@ function claudeSpawnTarget(role, detail, realBin = resolveClaudeBin(), args = []
   const platform = winOpts.platform || process.platform;
   if (platform !== 'win32' || !/\.(cmd|bat)$/i.test(base.command)) return base;
   // Node refuses to spawn a .cmd/.bat without a shell (EINVAL) — wrap in cmd.exe argv.
-  const { resolveSpawn } = require('./winSpawn.cjs');
+  const { resolveSpawn } = require('../process/winSpawn.cjs');
   const wrapped = resolveSpawn(base.command, args, { platform, ...(winOpts.env ? { env: winOpts.env } : {}), ...(winOpts.exists ? { exists: winOpts.exists } : {}) });
   return { ...base, ...wrapped };
 }
@@ -102,7 +102,7 @@ function baseSpawnTarget(role, detail, realBin) {
   const alias = ROLE_ALIASES[role];
   if (!alias) return { command: realBin };
   try {
-    const { aliasBinFor, smArgv0 } = require('./procName.cjs');
+    const { aliasBinFor, smArgv0 } = require('../process/procName.cjs');
     const command = aliasBinFor(realBin, alias);
     if (command === realBin) return { command: realBin };
     return { command, argv0: smArgv0(role, detail) };
@@ -114,7 +114,7 @@ function baseSpawnTarget(role, detail, realBin) {
 // ---------- version probe ----------
 //
 // `claude --version`, cached. The scheduler's launch circuit breaker
-// (lib/launchFailure.cjs) records the CLI version a launch block was armed
+// (lib/scheduler/launchFailure.cjs) records the CLI version a launch block was armed
 // under and drops the block the moment the version changes — the incident
 // behind it (issue #11: an outdated CLI sending a thinking parameter the
 // model rejects) is fixed by `claude update`, and the queue must notice

package/src/main/lib/{effectiveModelInfo.cjs → claude/effectiveModelInfo.cjs}

@@ -26,9 +26,9 @@
 const fs = require('node:fs');
 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');
+const { splitFrontmatter } = require('../prd/prdFrontmatter.cjs');
+const { resolveEpicTranscriptPath } = require('../epic/epicTranscriptPath.cjs');
+const schedulerPaths = require('../scheduler/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.
@@ -70,7 +70,7 @@ function isConcreteModelId(modelAlias) {
  */
 function computeEffortEnvReachable(deps) {
   try {
-    const { cleanChildEnv } = deps.cleanEnv || require('./cleanEnv.cjs');
+    const { cleanChildEnv } = deps.cleanEnv || require('../process/cleanEnv.cjs');
     const probe = cleanChildEnv({ CLAUDE_EFFORT: 'high', CLAUDE_CODE_EFFORT_LEVEL: 'high' });
     return Boolean(probe.CLAUDE_EFFORT || probe.CLAUDE_CODE_EFFORT_LEVEL);
   } catch {
@@ -93,7 +93,7 @@ function computeEffortEnvReachable(deps) {
  * for the same dangling reference.
  */
 async function resolvePersonaModelAlias(cwd, agentType, deps) {
-  const getPersonaBody = deps.getPersonaBody || require('../agentLibrary.cjs').getPersonaBody;
+  const getPersonaBody = deps.getPersonaBody || require('../../agentLibrary.cjs').getPersonaBody;
   // The overlay-vs-global provenance question itself ("which of
   // resolvePersonaPaths' two candidates won") is answered by
   // agentModelResolve.cjs's isProjectOverlayPersonaPath, not re-derived here
@@ -125,7 +125,7 @@ async function resolvePersonaModelAlias(cwd, agentType, deps) {
 
 /** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/queue.json`'s hot jobs[]. */
 function readHotJobsForCwd(cwd, deps) {
-  const { projectQueuePath } = deps.queueStore || require('./queueStore.cjs');
+  const { projectQueuePath } = deps.queueStore || require('../scheduler/queueStore.cjs');
   try {
     const data = JSON.parse(fs.readFileSync(projectQueuePath(cwd), 'utf8'));
     return Array.isArray(data.jobs) ? data.jobs : [];
@@ -136,7 +136,7 @@ function readHotJobsForCwd(cwd, deps) {
 
 /** Best-effort read of `<cwd>/session-manager-operations/scheduler/state/history.jsonl`'s archived rows. */
 function readHistoryEntriesForCwd(cwd, deps) {
-  const { projectHistoryPath } = deps.queueStore || require('./queueStore.cjs');
+  const { projectHistoryPath } = deps.queueStore || require('../scheduler/queueStore.cjs');
   let text;
   try {
     text = fs.readFileSync(projectHistoryPath(cwd), 'utf8');
@@ -246,7 +246,7 @@ function findLatestSchedulerModel(cwd, agentType, deps) {
  * O(min(transcriptSize, cap)) per transcript read.
  */
 function findLatestTranscriptModel(cwd, agentType, deps) {
-  const readActiveIndex = deps.readActiveIndex || require('./epicMint.cjs').readActiveIndex;
+  const readActiveIndex = deps.readActiveIndex || require('../epic/epicMint.cjs').readActiveIndex;
   let sessions;
   try {
     ({ sessions } = readActiveIndex(cwd));
@@ -296,7 +296,7 @@ async function resolveEffectiveModelInfo({ cwd, agentType, deps = {} } = {}) {
   if (!cwd || !agentType) return miss;
 
   try {
-    const { projectRootOf } = deps.activeSessions || require('./activeSessions.cjs');
+    const { projectRootOf } = deps.activeSessions || require('../activeSessions.cjs');
     const normalizedCwd = projectRootOf(path.resolve(cwd));
     if (!normalizedCwd) return miss;
 

package/src/main/lib/{modelCatalog.cjs → claude/modelCatalog.cjs}

@@ -29,7 +29,7 @@ const SCAN_OVERLAP_BYTES = 128;
 const MODEL_ID_RE = /claude-(?:opus|sonnet|haiku|fable)-[0-9][0-9-]*/g;
 // A real CLI binary is tens of MB; test stubs and launcher shims are tiny shell scripts.
 const MIN_SCAN_BYTES = 1024 * 1024;
-const SCHEMA_PATH = path.join(__dirname, '..', '..', 'renderer', 'data', 'claude-settings-schema.json');
+const SCHEMA_PATH = path.join(__dirname, '..', '..', '..', 'renderer', 'data', 'claude-settings-schema.json');
 
 const CATALOG_FLOOR = Object.freeze({
   aliases: Object.freeze(['haiku', 'sonnet', 'opus', 'fable']),
@@ -118,7 +118,7 @@ function readAvailableModels(cwd, d, fsImpl) {
   const home = d.homeDir ? d.homeDir() : os.homedir();
   let root = null;
   if (cwd) {
-    try { root = (d.projectRootOf || require('./activeSessions.cjs').projectRootOf)(path.resolve(cwd)); } catch { root = path.resolve(cwd); }
+    try { root = (d.projectRootOf || require('../activeSessions.cjs').projectRootOf)(path.resolve(cwd)); } catch { root = path.resolve(cwd); }
   }
   const files = [path.join(home, '.claude', 'settings.json')];
   if (root) files.push(path.join(root, '.claude', 'settings.json'), path.join(root, '.claude', 'settings.local.json'));
@@ -221,7 +221,7 @@ async function doResolve({ cwd, force, deps }) {
   };
   // Unknown version = unknown cache key: writing it would stamp `claudeVersion: null` over a real entry.
   if (!degraded && cacheFile && claudeVersion) {
-    try { await (d.writeJson || require('../config.cjs').writeJson)(cacheFile, catalog); } catch { /* cache is best-effort */ }
+    try { await (d.writeJson || require('../../config.cjs').writeJson)(cacheFile, catalog); } catch { /* cache is best-effort */ }
   }
   return catalog;
 }

package/src/main/lib/{rateLimitDetect.cjs → claude/rateLimitDetect.cjs}

@@ -11,7 +11,7 @@
  * never be a second, independently-drifting regex set at either call site.
  */
 
-const { readTail } = require('./fileTail.cjs');
+const { readTail } = require('../util/fileTail.cjs');
 
 /** Scan the tail of a job's log for the canonical rate-limit signal. We look
  *  at the last 16 KB — final result event always lands at the end. Covers

package/src/main/lib/{rateLimitWindow.cjs → claude/rateLimitWindow.cjs}

@@ -13,7 +13,7 @@
  * unit-testable without scheduler.cjs (mirrors reaperHelpers.cjs's split).
  */
 
-const { readTail } = require('./fileTail.cjs');
+const { readTail } = require('../util/fileTail.cjs');
 
 // Authoritative window block rides on the LAST rate_limit_event in the log
 // (often the one attached to the final result), so mirror classifyRunOutcome's

package/src/main/lib/{runClaudeP.cjs → claude/runClaudeP.cjs}

@@ -17,7 +17,7 @@
 const { spawn } = require('node:child_process');
 const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
 const { headlessPermissionArgs, ensureCliCapsProbed } = require('./claudeCliCaps.cjs');
-const { withProcRole } = require('./cleanEnv.cjs');
+const { withProcRole } = require('../process/cleanEnv.cjs');
 
 const MAX_OUT_BYTES = 8 * 1024 * 1024;
 

package/src/main/lib/credentials.cjs

@@ -5,9 +5,9 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { spawn, execFileSync } = require('node:child_process');
-const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
-const atomicFs = require('./atomicFs.cjs');
-const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
+const { cleanChildEnv, pathWithUserBins } = require('./process/cleanEnv.cjs');
+const atomicFs = require('./util/atomicFs.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./claude/claudeBin.cjs');
 
 const CREDS_PATH = path.join(os.homedir(), '.claude', '.credentials.json');
 

package/src/main/lib/cwdClassify.cjs

@@ -41,7 +41,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const schedulerPaths = require('./schedulerPaths.cjs');
+const schedulerPaths = require('./scheduler/schedulerPaths.cjs');
 
 const OPS_DIRNAME = 'session-manager-operations';
 const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;

package/src/main/lib/{activeIndexMerge.cjs → epic/activeIndexMerge.cjs}

@@ -35,7 +35,7 @@
 
 const path = require('path');
 const { activeIndexPath, withPathLock } = require('./epicMint.cjs');
-const config = require('../config.cjs');
+const config = require('../../config.cjs');
 const { mirrorEpicStatus } = require('./epicStatusMirror.cjs');
 
 function hasOwn(obj, key) {
@@ -73,7 +73,7 @@ async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events:
   if (!cwd || typeof cwd !== 'string') throw new Error('mergeActiveIndex: cwd is required');
   // Register this project's cwd as a write-allowed root (config.cjs's
   // validateWrite gate) — mirrors the precedent + comment in
-  // lib/prdCreate.cjs:152-155. A chat-only Epic (headless claude -p, no
+  // lib/prd/prdCreate.cjs:152-155. A chat-only Epic (headless claude -p, no
   // Terminal PTY ever spawned for this cwd) reaches this merge on a cold
   // boot before pty.cjs's addAllowedRoot call has ever run for it — without
   // this, every active-index.json write for such a project fails with
@@ -181,7 +181,7 @@ async function mergeActiveIndex(cwd, { sessions: rawMemorySessions = {}, events:
 
 function registerActiveIndexMergeHandlers() {
   const { ipcMain } = require('electron');
-  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  const { schemas: s, validated: v } = require('../../ipcSchemas.cjs');
   ipcMain.handle(
     'promptSessions:merge-active-index',
     v(s.promptSessionsMergeActiveIndex, ({ cwd, sessions, events, removedIds }) =>

package/src/main/lib/{activeIndexRebuild.cjs → epic/activeIndexRebuild.cjs}

@@ -20,7 +20,7 @@ const path = require('node:path');
 const { activeIndexPath, readActiveIndex, writeActiveIndex, withPathLock } = require('./epicMint.cjs');
 
 function promptSessionsDir(cwd) {
-  const { opsPath } = require('./opsOwnership.cjs');
+  const { opsPath } = require('../opsOwnership.cjs');
   return opsPath(cwd, 'prompt-sessions');
 }
 

package/src/main/lib/{delegationReadiness.cjs → epic/delegationReadiness.cjs}

@@ -20,36 +20,28 @@ const fs = require('node:fs');
 const path = require('node:path');
 const os = require('node:os');
 const { spawn } = require('node:child_process');
-const { writeJson, addAllowedRoot } = require('../config.cjs');
-const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
-const { shimPath: guardShimPath, resolveShimTarget, ensureGuardShimsOrError } = require('./guardShims.cjs');
-const { resolveProjectRoot } = require('./opsOwnership.cjs');
-const { nodeShellCommand } = require('./appRuntime.cjs');
+const { writeJson, addAllowedRoot } = require('../../config.cjs');
+const { cleanChildEnv, pathWithUserBins } = require('../process/cleanEnv.cjs');
+const { shimPath: guardShimPath, resolveShimTarget, ensureGuardShimsOrError } = require('../guardShims.cjs');
+const { resolveProjectRoot } = require('../opsOwnership.cjs');
+const { nodeShellCommand } = require('../appRuntime.cjs');
+const { readJsonOrSync } = require('../util/atomicFs.cjs');
 
 const SCHEDULER_MCP_NAME = 'session-manager-scheduler';
 const DEV_PLUGIN_ENABLED_KEY = 'session-manager-dev@session-manager';
-const SCHEDULER_MCP_SERVER_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'scheduler-mcp-server.cjs');
-const PRD_WRITE_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-prd-writes.cjs');
+const SCHEDULER_MCP_SERVER_SCRIPT = path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'scheduler-mcp-server.cjs');
+const PRD_WRITE_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'hooks', 'guard-prd-writes.cjs');
 const PRD_WRITE_GUARD_MATCHER = 'Write|Edit|NotebookEdit';
-const DESTRUCTIVE_GIT_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-destructive-git.cjs');
+const DESTRUCTIVE_GIT_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'hooks', 'guard-destructive-git.cjs');
 const DESTRUCTIVE_GIT_GUARD_MATCHER = 'Bash';
-const INLINE_IMPLEMENTATION_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-inline-implementation.cjs');
+const INLINE_IMPLEMENTATION_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'hooks', 'guard-inline-implementation.cjs');
 const INLINE_IMPLEMENTATION_GUARD_MATCHER = 'Write|Edit|NotebookEdit';
-const SELF_SCHEDULE_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', 'scripts', 'hooks', 'guard-self-schedule.cjs');
+const SELF_SCHEDULE_GUARD_SCRIPT = path.resolve(__dirname, '..', '..', '..', '..', 'scripts', 'hooks', 'guard-self-schedule.cjs');
 const SELF_SCHEDULE_GUARD_MATCHER = 'ScheduleWakeup|CronCreate|Task|Agent';
 const LIVE_PROBE_TIMEOUT_MS = 10_000;
 const LIVE_PROBE_TTL_MS = 60_000;
 const REQUIRED_LIVE_TOOLS = ['scheduler_create_prd', 'session_manager_help'];
 
-/** Read + JSON.parse a file, returning `fallback` on any read/parse failure. */
-function readJsonSafe(absPath, fallback) {
-  try {
-    return JSON.parse(fs.readFileSync(absPath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
 /** Lazy (not a module-load constant) so tests can toggle packaged mode. */
 function schedulerMcpFixCmd() {
   const cmd = nodeShellCommand(SCHEDULER_MCP_SERVER_SCRIPT);
@@ -68,10 +60,10 @@ function schedulerMcpFixCmd() {
  * which is the incident this PRD closes.
  */
 function checkSchedulerMcp({ cwd, homeDir }) {
-  const userConfig = readJsonSafe(path.join(homeDir, '.claude.json'), null);
+  const userConfig = readJsonOrSync(path.join(homeDir, '.claude.json'), null);
   const userEntry = userConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
 
-  const projectConfig = readJsonSafe(path.join(cwd, '.mcp.json'), null);
+  const projectConfig = readJsonOrSync(path.join(cwd, '.mcp.json'), null);
   const projectHas = !!projectConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
 
   if (userEntry) {
@@ -129,10 +121,10 @@ function checkSchedulerMcp({ cwd, homeDir }) {
  * (enableAllProjectMcpServers), not something this probe decides.
  */
 function checkSchedulerMcpProjectDuplicate({ cwd, homeDir }) {
-  const userConfig = readJsonSafe(path.join(homeDir, '.claude.json'), null);
+  const userConfig = readJsonOrSync(path.join(homeDir, '.claude.json'), null);
   const userHas = !!userConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
 
-  const projectConfig = readJsonSafe(path.join(cwd, '.mcp.json'), null);
+  const projectConfig = readJsonOrSync(path.join(cwd, '.mcp.json'), null);
   const projectHas = !!projectConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
 
   const warn = userHas && projectHas;
@@ -289,7 +281,7 @@ async function checkSchedulerMcpLive({ cwd, homeDir, schedulerMcpCheck }) {
   // executed the moment its cwd is merely probed, bypassing that approval
   // entirely. Auto-approving project-scope servers is explicitly out of
   // scope for this probe — see this PRD's "Out of scope".
-  const userConfig = readJsonSafe(path.join(homeDir, '.claude.json'), null);
+  const userConfig = readJsonOrSync(path.join(homeDir, '.claude.json'), null);
   const entry = userConfig?.mcpServers?.[SCHEDULER_MCP_NAME];
 
   if (!entry?.command) {
@@ -312,7 +304,7 @@ async function checkSchedulerMcpLive({ cwd, homeDir, schedulerMcpCheck }) {
 }
 
 function checkDevPlugin({ homeDir }) {
-  const settings = readJsonSafe(path.join(homeDir, '.claude', 'settings.json'), null);
+  const settings = readJsonOrSync(path.join(homeDir, '.claude', 'settings.json'), null);
   const ok = settings?.enabledPlugins?.[DEV_PLUGIN_ENABLED_KEY] === true;
 
   return {
@@ -444,7 +436,7 @@ const GUARD_DEFS = {
  * while reporting green" failure mode, one hop downstream of the hook command.
  */
 function checkGuard(def, { cwd, homeDir = os.homedir() }) {
-  const settings = readJsonSafe(path.join(cwd, '.claude', 'settings.json'), null);
+  const settings = readJsonOrSync(path.join(cwd, '.claude', 'settings.json'), null);
   const preToolUse = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
 
   let mentioned = false;
@@ -536,7 +528,7 @@ async function installGuard(def, { cwd, homeDir = os.homedir(), skipShimEnsure =
   // documents for PromptSession archive writes. `cwd` here IS a project root.
   addAllowedRoot(cwd);
 
-  const existing = fs.existsSync(settingsPath) ? readJsonSafe(settingsPath, undefined) : {};
+  const existing = fs.existsSync(settingsPath) ? readJsonOrSync(settingsPath, undefined) : {};
   if (existing === undefined) {
     // Unparseable settings — refuse rather than silently discarding whatever
     // the human has in there.
@@ -629,7 +621,7 @@ async function installSelfScheduleGuard({ cwd, homeDir = os.homedir(), skipShimE
 
 /**
  * Runs all eight delegation-readiness checks for `cwd`. Every filesystem read
- * is wrapped (readJsonSafe / try-catch) so a missing or unparseable file
+ * is wrapped (readJsonOrSync / try-catch) so a missing or unparseable file
  * yields ok:false with a detail, never a thrown exception. Async because
  * scheduler-mcp-live genuinely spawns a process and waits on it (bounded by
  * LIVE_PROBE_TIMEOUT_MS, and memoized per registration signature so repeat
@@ -673,7 +665,7 @@ function logAutoInstallEvent({ cwd, guard, action, error }) {
   // A no-op outcome is not an event worth an error-log row (24 rows/3 days of boot noise).
   if (action === 'already-installed') return;
   try {
-    const opsErrorLog = require('./opsErrorLog.cjs');
+    const opsErrorLog = require('../telemetry/opsErrorLog.cjs');
     opsErrorLog.appendError({
       cwd,
       scope: 'delegationReadiness',

package/src/main/lib/{epicContextDigest.cjs → epic/epicContextDigest.cjs}

@@ -13,7 +13,7 @@
  * scheduler.cjs.
  */
 
-const { readTurns } = require('../promptSessionTranscript.cjs');
+const { readTurns } = require('../../promptSessionTranscript.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 
 const DEFAULT_MAX_CHARS = 4000;

package/src/main/lib/{epicDelegationStats.cjs → epic/epicDelegationStats.cjs}

@@ -28,7 +28,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
-const { classifyLine } = require('./classifyTranscriptLine.cjs');
+const { classifyLine } = require('../classifyTranscriptLine.cjs');
 
 // Same cap transcripts.cjs's readDelta uses for a single pass — bounds
 // memory/time on a very large transcript instead of reading it whole.
@@ -40,7 +40,7 @@ const APPLICATION_SOURCE_PREFIXES = ['src/', 'scripts/', 'plugins/', 'bin/'];
 function countPrdsQueued(cwd, epicId, deps = {}) {
   const readdirSync = deps.readdirSync || fs.readdirSync;
   try {
-    const { opsPath } = require('./opsOwnership.cjs');
+    const { opsPath } = require('../opsOwnership.cjs');
     const dir = opsPath(cwd, 'scheduler', 'epics', epicId, 'prds');
     return readdirSync(dir).filter((name) => name.endsWith('.md')).length;
   } catch {

package/src/main/lib/{epicMint.cjs → epic/epicMint.cjs}

@@ -31,20 +31,20 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
-const { resolveEpicPrdWriteDir } = require('./prdLocations.cjs');
-const { assertOpsWrite } = require('./opsOwnership.cjs');
-const { appendAuditEvent } = require('./auditLog.cjs');
+const { resolveEpicPrdWriteDir } = require('../prd/prdLocations.cjs');
+const { assertOpsWrite } = require('../opsOwnership.cjs');
+const { appendAuditEvent } = require('../telemetry/auditLog.cjs');
 const { mirrorEpicStatus, removeEpicMirror } = require('./epicStatusMirror.cjs');
-const atomicFs = require('./atomicFs.cjs');
-const telemetryCounters = require('./telemetryCounters.cjs');
+const atomicFs = require('../util/atomicFs.cjs');
+const telemetryCounters = require('../telemetry/telemetryCounters.cjs');
 // Required as the module object (not destructured) so a test can
 // monkeypatch promptSessionSchema.assertValidPromptSession in place to
 // simulate a corrupted construction — the real construction below is
 // hardcoded and always valid.
-const promptSessionSchema = require('./promptSessionSchema.cjs');
+const promptSessionSchema = require('../promptSessionSchema.cjs');
 
 // The one token that unlocks ensureEpic's mint branch. Held by
-// lib/promptSessionsCreateEpic.cjs (the New Epic card's IPC handler) and
+// lib/epic/promptSessionsCreateEpic.cjs (the New Epic card's IPC handler) and
 // nothing else — grep for it before adding a second holder, that is a
 // deliberate domain-model change, not a convenience.
 const MINT_AUTHORITY_NEW_EPIC_UI = 'new-epic-ui';
@@ -56,7 +56,7 @@ const MINT_AUTHORITY_NEW_EPIC_UI = 'new-epic-ui';
 // the `feedback/` folder retired (2026-08-02) and the scheduler correctly
 // locked down to join-only, an agent working in Project-A had NO way to hand
 // a finding to Project-B — the finding either died in a transcript or the
-// human had to relay it by hand. `lib/crossProjectFeedback.cjs` restores that
+// human had to relay it by hand. `lib/feedback-remote/crossProjectFeedback.cjs` restores that
 // conduit, and it is the sole holder of this token.
 //
 // What makes it safe is the part of the SINGLE-CREATOR LAW that actually
@@ -79,7 +79,7 @@ const MINT_AUTHORITIES = Object.freeze([
 function activeIndexPath(cwd) {
   // Lazy: opsOwnership → ephemeralCwd → activeSessions; this module is
   // required early by several of those neighbours.
-  const { opsPath } = require('./opsOwnership.cjs');
+  const { opsPath } = require('../opsOwnership.cjs');
   return opsPath(cwd, 'prompt-sessions', 'active-index.json');
 }
 
@@ -93,7 +93,7 @@ function readActiveIndex(cwd) {
       // doesn't resurrect completed/deleted Epics on its own), but every
       // caller here does read-modify-write on the object this returns, so
       // dropping the field would silently erase the removal tombstones
-      // lib/activeIndexMerge.cjs's mergeActiveIndex records the next time any
+      // lib/epic/activeIndexMerge.cjs's mergeActiveIndex records the next time any
       // of ensureEpic/appendPrdCreatedEvent/removeEpic writes this file.
       tombstones: parsed && typeof parsed.tombstones === 'object' && parsed.tombstones ? parsed.tombstones : {},
     };
@@ -450,7 +450,7 @@ module.exports = {
   writeActiveIndex,
   personaFileExists,
   resolvePersonaPaths,
-  // Exported so lib/activeIndexMerge.cjs's renderer-facing merge IPC handler
+  // Exported so lib/epic/activeIndexMerge.cjs's renderer-facing merge IPC handler
   // serializes through the SAME lock instance as ensureEpic/
   // appendPrdCreatedEvent (module-level Map, shared via Node's require
   // cache) — one lock per active-index.json path across both callers, not

package/src/main/lib/{epicSpawnPlan.cjs → epic/epicSpawnPlan.cjs}

@@ -27,8 +27,8 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { encodeCwd } = require('./encodeCwd.cjs');
-const { projectRootOf } = require('./activeSessions.cjs');
+const { encodeCwd } = require('../util/encodeCwd.cjs');
+const { projectRootOf } = require('../activeSessions.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 const { resolveEpicSpawnCwd } = require('./epicSpawnCwd.cjs');
 const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
@@ -56,7 +56,7 @@ function findEpic(cwd, claudeSessionId, deps) {
     }
   } catch { /* unreadable index → try archives */ }
   try {
-    const { opsPath } = require('./opsOwnership.cjs');
+    const { opsPath } = require('../opsOwnership.cjs');
     const dir = opsPath(cwd, 'prompt-sessions');
     for (const name of fs.readdirSync(dir)) {
       if (!name.endsWith('.json') || name === 'active-index.json') continue;

package/src/main/lib/{epicStatusMirror.cjs → epic/epicStatusMirror.cjs}

@@ -26,8 +26,8 @@
  */
 
 const fs = require('node:fs');
-const { assertOpsWrite, opsPath } = require('./opsOwnership.cjs');
-const atomicFs = require('./atomicFs.cjs');
+const { assertOpsWrite, opsPath } = require('../opsOwnership.cjs');
+const atomicFs = require('../util/atomicFs.cjs');
 
 function epicMirrorPath(cwd, epicId) {
   return opsPath(cwd, 'prompt-sessions', `${epicId}.json`);

package/src/main/lib/{epicTranscriptDiagnostic.cjs → epic/epicTranscriptDiagnostic.cjs}

@@ -17,9 +17,9 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { encodeCwd } = require('../util/encodeCwd.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
-const { opsPath } = require('./opsOwnership.cjs');
+const { opsPath } = require('../opsOwnership.cjs');
 const { resolveEpicTranscriptPath } = require('./epicTranscriptPath.cjs');
 
 /** [epicId, session] pairs: active-index rows plus archived per-Epic `<id>.json` records. */

package/src/main/lib/{epicTranscriptPath.cjs → epic/epicTranscriptPath.cjs}

@@ -25,7 +25,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { encodeCwd } = require('./encodeCwd.cjs');
+const { encodeCwd } = require('../util/encodeCwd.cjs');
 const { readActiveIndex } = require('./epicMint.cjs');
 const { resolveEpicSpawnCwd } = require('./epicSpawnCwd.cjs');
 
@@ -53,7 +53,7 @@ function statKey(statSync, p) {
 }
 
 function opsFile(cwd, ...segments) {
-  const { opsPath } = require('./opsOwnership.cjs');
+  const { opsPath } = require('../opsOwnership.cjs');
   return opsPath(cwd, 'prompt-sessions', ...segments);
 }