claude-code-session-manager 0.71.0 → 0.73.0

package/src/main/lib/epicSpawnCwd.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * epicSpawnCwd.cjs — resolves the cwd a child process spawned FOR an Epic's
+ * session should actually launch in: the Epic's isolated `git worktree`
+ * checkout (`worktree.dir`) when one was created for it, else the Epic's
+ * real project cwd unchanged (PRD 1033, wiring the primitives PRD 1032
+ * built).
+ *
+ * Mirrors agentModelResolve.cjs's `findAgentTypeByClaudeSessionId` shape and
+ * reuses the same join: an Epic-backed pty.cjs tab / chatRunner.cjs run is
+ * keyed by `claudeSessionId` (Tab ID = claudeSessionId, CLAUDE.md), so the
+ * matching PromptSession record — and its `worktree` field, when present —
+ * is found by scanning `cwd`'s own active-index.json for that id. Plain sync
+ * fs (via epicMint.cjs's readActiveIndex), no Electron deps, so callers can
+ * use it from a synchronous spawn path without restructuring into async.
+ *
+ * ---------- the ops-root hazard (read before touching cwd plumbing) --------
+ *
+ * This resolves ONLY the value a caller hands to a child process's own `cwd`
+ * spawn option. `cwd` itself — used for every ops-root read/write
+ * (active-index.json, prompt-sessions, scheduler state, opsErrorLog, model
+ * resolution) — must keep flowing unchanged everywhere else; see
+ * gitWorktree.cjs's own header comment for the full incident history this
+ * invariant guards against. Never substitute this function's return value
+ * for `cwd` outside a literal spawn-cwd argument.
+ */
+
+const fs = require('node:fs');
+const { readActiveIndex } = require('./epicMint.cjs');
+
+/**
+ * True when `dir` is a directory that exists RIGHT NOW.
+ *
+ * `worktree.dir` is an absolute path under os.tmpdir() that gets PERSISTED
+ * onto the Epic record in active-index.json — a file this project tracks in
+ * git. It therefore outlives the checkout it names, in three ordinary ways:
+ *
+ *   1. Reboot / tmp sweep. Most Linux distros and macOS clear /tmp on boot
+ *      (this host: `D /tmp 1777 root root 30d` in tmpfiles.d — `D` clears at
+ *      boot AND ages entries out at 30d). Epics are deliberately long-lived
+ *      (that is exactly why the epic kind has no short-lived cap and why boot
+ *      reconciliation spares still-active Epics), so an active Epic routinely
+ *      outlives its own checkout.
+ *   2. Another machine. active-index.json is committed, so a clone carries a
+ *      worktree.dir naming a path built from the ORIGINAL machine's tmpdir and
+ *      a sha1 of the ORIGINAL machine's project cwd. It cannot exist here.
+ *   3. Manual cleanup — `git worktree prune`, an rm -rf, a disk-space sweep.
+ *
+ * Without this check the spawn path handed a vanished directory straight to
+ * node-pty / child_process as its cwd, which fails the spawn outright: the
+ * Epic's Terminal and Chat both break with an opaque ENOENT instead of simply
+ * falling back to the project's shared tree the way every other failure mode
+ * in this chain does.
+ */
+function isUsableDir(dir, statImpl) {
+  try {
+    return statImpl(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{ cwd: string, claudeSessionId: string, deps?: object }} opts
+ * @returns {string} `worktree.dir` when the matching Epic has one AND it still
+ *   exists on disk, else `cwd` unchanged.
+ */
+function resolveEpicSpawnCwd({ cwd, claudeSessionId, deps = {} } = {}) {
+  if (!cwd || !claudeSessionId) return cwd;
+  try {
+    const load = deps.readActiveIndex || readActiveIndex;
+    const statSync = deps.statSync || fs.statSync;
+    const { sessions } = load(cwd);
+    for (const session of Object.values(sessions)) {
+      if (session && session.claudeSessionId === claudeSessionId) {
+        const dir = session.worktree?.dir;
+        if (!dir) return cwd;
+        if (!isUsableDir(dir, statSync)) {
+          // Falling back is strictly better than failing the spawn: the
+          // session still runs, just un-isolated, which is the same degraded
+          // mode a project that never had a worktree runs in.
+          console.log(`[epicSpawnCwd] worktree dir gone (${dir}) — falling back to ${cwd}`);
+          return cwd;
+        }
+        return dir;
+      }
+    }
+  } catch {
+    return cwd;
+  }
+  return cwd;
+}
+
+module.exports = { resolveEpicSpawnCwd };

package/src/main/lib/epicWorktreeBoot.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+/**
+ * epicWorktreeBoot.cjs — boot reconciliation for Epic git worktrees (PRD
+ * 1033, wiring gitWorktree.cjs's `reconcileWorktreesOnBoot` isLive predicate
+ * that PRD 1032 built but left unwired).
+ *
+ * A worktree that survives an app crash/host reboot must not leak disk or a
+ * dangling branch forever — but unlike a scheduler job worktree (always safe
+ * to reap at boot; a job worktree found at boot is by definition from a run
+ * that didn't finish), an Epic worktree backs a session a human may still be
+ * mid-way through. Reaping it out from under a still-`active` Epic would
+ * silently drop that Epic's isolation (and, worse, any uncommitted work sat
+ * in the checkout) the moment the app restarts.
+ *
+ * Per project cwd, reads that project's own active-index.json (the same file
+ * gitWorktree.cjs's own header comment calls the "ops-root" — resolved here
+ * via epicMint.cjs's readActiveIndex, never a worktree path) and only reaps
+ * a worktree whose owning Epic is NOT `active` in it. At boot there is by
+ * definition no live attached PTY/chat process yet (the app process is
+ * fresh), so the AC's "no live attached process" half of the gate holds
+ * automatically — this predicate covers the other half.
+ */
+
+const gitWorktree = require('./gitWorktree.cjs');
+const { readActiveIndex } = require('./epicMint.cjs');
+
+/**
+ * @param {string[]} cwds - known project cwds to sweep.
+ * @param {{ readActiveIndex?: Function, reconcileWorktreesOnBoot?: Function }} [deps]
+ * @returns {Promise<void>}
+ */
+async function reconcileEpicWorktreesOnBoot(cwds, deps = {}) {
+  const load = deps.readActiveIndex || readActiveIndex;
+  const reconcile = deps.reconcileWorktreesOnBoot || gitWorktree.reconcileWorktreesOnBoot;
+  const list = Array.isArray(cwds) ? cwds.filter(Boolean) : [];
+  for (const cwd of list) {
+    let sessions = {};
+    try {
+      sessions = load(cwd).sessions || {};
+    } catch {
+      sessions = {}; // no active-index.json yet, or unreadable — nothing is "live"
+    }
+    const isLive = (epicId) => !!sessions[epicId] && sessions[epicId].status === 'active';
+    await reconcile([cwd], { kind: 'epic', isLive });
+  }
+}
+
+module.exports = { reconcileEpicWorktreesOnBoot };

package/src/main/lib/epicWorktreeMerge.cjs

@@ -0,0 +1,63 @@
+'use strict';
+
+/**
+ * epicWorktreeMerge.cjs — IPC entry point that folds an Epic's isolated git
+ * worktree branch (gitWorktree.cjs's `integrateEpicBranch`, kind: 'epic')
+ * back into its owning project's main tree (PRD 1034, third link of the
+ * epic-worktree-isolation chain started by PRD 1032/1033).
+ *
+ * This is the ONLY point where that per-Epic isolation resolves back into
+ * the shared tree — never mid-session (see gitWorktree.cjs's own header
+ * comment for the ff-only -> merge-commit -> abort-and-flag algorithm this
+ * reuses verbatim). Callers reach it two ways: an explicit "merge to main"
+ * action (renderer state's `mergeEpicToMain`), and `markCompleted`'s
+ * merge-before-archive checkpoint — both funnel through this one handler so
+ * the integration strategy is never duplicated.
+ *
+ * On success the worktree checkout is torn down (cleanupEpicWorktree) since
+ * its content now safely lives on the main tree. On a real conflict, the
+ * branch and worktree directory are left intact — never silently discarded
+ * — so a human can still open a Terminal into `worktree.dir` (PRD 1033's
+ * existing epicSpawnCwd.cjs wiring — it keys off `worktree.dir` alone, not
+ * `worktree.status`, so a conflicted Epic's Terminal spawn keeps landing
+ * there with no new code path needed) and resolve it manually before
+ * re-running this same action.
+ */
+
+const { integrateEpicBranch, cleanupEpicWorktree } = require('./gitWorktree.cjs');
+const { validatePath } = require('../config.cjs');
+
+/**
+ * mergeEpicToMainViaIpc(cwd, epicId, branch, dir) → Promise<MergeOutcome>
+ *
+ * `MergeOutcome` is `{ ok: true, status: 'merged', integrated: boolean }` on
+ * a clean merge (or a legitimate no-new-commits no-op — either way nothing
+ * is left to resolve, so the worktree is cleaned up), or
+ * `{ ok: false, status: 'needs_merge_resolution', reason: string }` on a
+ * real conflict — never throws (integrateEpicBranch/cleanupEpicWorktree
+ * never do either).
+ */
+async function mergeEpicToMainViaIpc(cwd, epicId, branch, dir) {
+  validatePath(cwd);
+  const outcome = await integrateEpicBranch({ cwd, branch, epicId });
+  if (!outcome.ok) {
+    console.log(`[epicWorktreeMerge] ${epicId}: needs manual resolution (${outcome.reason})`);
+    return { ok: false, status: 'needs_merge_resolution', reason: outcome.reason };
+  }
+  // Clean ff-only/merge-commit landing, or a legitimate no-new-commits
+  // no-op — either way the branch's content is safely reflected (or was
+  // never ahead), so the checkout has nothing left to guard.
+  await cleanupEpicWorktree({ cwd, dir, branch, keepBranch: false });
+  return { ok: true, status: 'merged', integrated: outcome.integrated };
+}
+
+function registerEpicWorktreeMergeHandlers() {
+  const { ipcMain } = require('electron');
+  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  ipcMain.handle(
+    'promptSessions:merge-to-main',
+    v(s.promptSessionsMergeToMain, ({ cwd, epicId, branch, dir }) => mergeEpicToMainViaIpc(cwd, epicId, branch, dir)),
+  );
+}
+
+module.exports = { mergeEpicToMainViaIpc, registerEpicWorktreeMergeHandlers };

package/src/main/lib/epicWorktreeMint.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+/**
+ * epicWorktreeMint.cjs — IPC entry point that creates an Epic's isolated git
+ * worktree (gitWorktree.cjs's createEpicWorktree, kind: 'epic') at the
+ * `proposed -> active` transition (PRD 1033, second link of the
+ * epic-worktree-isolation chain started by PRD 1032).
+ *
+ * That transition itself lives in the renderer (state/promptSessions.ts's
+ * approveProposed) and is synchronous — every caller relies on getting the
+ * approved session back immediately to start its chat send in the same tick
+ * (see that function's own comment). Worktree creation is real git/fs work
+ * that can only run main-process side, so approveProposed fires this IPC
+ * call fire-and-forget and patches `worktree` onto the session once it
+ * resolves — the transition itself is never blocked or delayed by it, and a
+ * failure (not a repo / dirty base tree / disabled / cap reached) simply
+ * leaves `worktree` unset, exactly as if this call had never been made.
+ *
+ * Mirrors promptSessionsCreateEpic.cjs's shape: `validatePath(cwd)` closes
+ * the same "arbitrary renderer-supplied cwd" gap that handler documents,
+ * since this is likewise reachable from the renderer over IPC.
+ */
+
+const { createEpicWorktree } = require('./gitWorktree.cjs');
+const { validatePath } = require('../config.cjs');
+
+/**
+ * createEpicWorktreeViaIpc(cwd, epicId) → Promise<EpicWorktree | null>
+ *
+ * Returns the `worktree` field shape (`{ dir, branch, baseCwd, status }`)
+ * ready to persist onto the Epic record on success, or `null` on any
+ * failure — createEpicWorktree/createWorktree never throw, so this never
+ * does either.
+ */
+async function createEpicWorktreeViaIpc(cwd, epicId) {
+  validatePath(cwd);
+  const result = await createEpicWorktree({ cwd, epicId });
+  if (!result.ok) {
+    console.log(`[epicWorktreeMint] ${epicId}: not isolated (${result.reason})`);
+    return null;
+  }
+  return { dir: result.dir, branch: result.branch, baseCwd: result.baseCwd, status: 'active' };
+}
+
+function registerEpicWorktreeMintHandlers() {
+  const { ipcMain } = require('electron');
+  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  ipcMain.handle(
+    'promptSessions:create-worktree',
+    v(s.promptSessionsCreateWorktree, ({ cwd, epicId }) => createEpicWorktreeViaIpc(cwd, epicId)),
+  );
+}
+
+module.exports = { createEpicWorktreeViaIpc, registerEpicWorktreeMintHandlers };

package/src/main/lib/epicWorktreeProjectConfig.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * epicWorktreeProjectConfig.cjs — per-project UI toggle for Epic worktree
+ * isolation (PRD 1035, final link of the epic-worktree-isolation chain).
+ *
+ * `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
+ * 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.
+ *
+ * Plain Node (no Electron deps in the read/write helpers) so gitWorktree.cjs
+ * — itself Electron-free — can require this lazily without pulling Electron
+ * into contexts (tests, watchdog scripts) that don't have it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const DEFAULT_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 readConfig() {
+  try {
+    const raw = fs.readFileSync(configPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  const file = configPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2));
+  fs.renameSync(tmp, file);
+}
+
+/** 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;
+}
+
+/** Persists (or clears, when `disabled` is false) the per-project toggle. */
+function setEpicWorktreeDisabledForProject(cwd, disabled) {
+  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;
+}
+
+function registerEpicWorktreeProjectConfigHandlers() {
+  const { ipcMain } = require('electron');
+  const { schemas: s, validated: v } = require('../ipcSchemas.cjs');
+  const { validatePath } = require('../config.cjs');
+  ipcMain.handle(
+    'promptSessions:get-worktree-disabled',
+    v(s.promptSessionsGetWorktreeDisabled, ({ cwd }) => {
+      validatePath(cwd);
+      return { disabled: isEpicWorktreeDisabledForProject(cwd) };
+    }),
+  );
+  ipcMain.handle(
+    'promptSessions:set-worktree-disabled',
+    v(s.promptSessionsSetWorktreeDisabled, ({ cwd, disabled }) => {
+      validatePath(cwd);
+      return { disabled: setEpicWorktreeDisabledForProject(cwd, disabled) };
+    }),
+  );
+}
+
+module.exports = {
+  DEFAULT_CONFIG_PATH,
+  configPath,
+  isEpicWorktreeDisabledForProject,
+  setEpicWorktreeDisabledForProject,
+  registerEpicWorktreeProjectConfigHandlers,
+};