claude-code-session-manager 0.86.0 → 0.88.0

package/src/main/lib/bootSelfHeal.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+/**
+ * bootSelfHeal.cjs — the epic-index self-heal scan, split out of
+ * app.whenReady() so it can run off the boot critical path.
+ *
+ * A project whose active-index.json is MISSING or fails to parse has lost
+ * every open Epic's status unless the per-Epic status mirror
+ * (epicStatusMirror.cjs) can rebuild it. `allProjectCwds()` is a synchronous
+ * ~270ms directory scan; looping it straight through every project inside
+ * app.whenReady()'s synchronous body blocked the event loop long enough that
+ * the renderer's first IPC round trips (schedule.state, billing.fetch,
+ * teams.list) hit their 5s deadlines before any handler could dispatch.
+ *
+ * `scheduleBootSelfHeal` defers `runEpicIndexSelfHeal` until the main window
+ * has painted (`did-finish-load`), with an unconditional `setImmediate`
+ * fallback for the window-destroyed-before-load and no-window (headless)
+ * cases, so the scan still runs exactly once per boot either way. It yields
+ * to the event loop between projects so a machine with thousands of
+ * projects can't stall it for a second straight.
+ */
+
+async function runEpicIndexSelfHeal(deps) {
+  const { fs, allProjectCwds, promptSessionsActiveIndexPath, rebuildActiveIndex, logs } = deps;
+  try {
+    for (const projectCwd of allProjectCwds()) {
+      const indexPath = promptSessionsActiveIndexPath(projectCwd);
+      let unclean = false;
+      let parseError = null;
+      if (!fs.existsSync(indexPath)) {
+        unclean = true;
+      } else {
+        try {
+          JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+        } catch (e) {
+          unclean = true;
+          parseError = e.message;
+        }
+      }
+      if (unclean) {
+        try {
+          const { rows, skipped } = rebuildActiveIndex(projectCwd);
+          logs.writeLine({
+            scope: 'active-index-rebuild',
+            level: 'info',
+            message: 'rebuilt active-index.json from status mirrors',
+            meta: { cwd: projectCwd, parseError, restored: rows.length, skipped: skipped.length },
+          });
+        } catch (e) {
+          logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'rebuild failed', meta: { cwd: projectCwd, error: e?.message } });
+        }
+      }
+      // Yield between projects so a multi-thousand-project machine can't
+      // stall the event loop for a second at a time.
+      await new Promise((resolve) => { setImmediate(resolve); });
+    }
+  } catch (e) {
+    logs.writeLine({ scope: 'active-index-rebuild', level: 'error', message: 'boot sweep failed', meta: { error: e?.message } });
+  }
+}
+
+function scheduleBootSelfHeal(mainWindow, deps) {
+  let ran = false;
+  const runOnce = () => {
+    if (ran) return;
+    ran = true;
+    runEpicIndexSelfHeal(deps);
+  };
+
+  const webContents = mainWindow && typeof mainWindow.isDestroyed === 'function' && !mainWindow.isDestroyed()
+    ? mainWindow.webContents
+    : null;
+
+  if (webContents && !webContents.isDestroyed()) {
+    webContents.once('did-finish-load', runOnce);
+    // Edge case: the window can be destroyed before it ever finishes
+    // loading (closed during boot, crashed renderer). did-finish-load would
+    // then never fire and the self-heal would silently never run — fall
+    // back to an unconditional setImmediate so it still runs exactly once.
+    webContents.once('destroyed', () => setImmediate(runOnce));
+  } else {
+    // Headless / no-visible-window boot — nothing will ever emit
+    // did-finish-load, so run on the very next event-loop turn instead.
+    setImmediate(runOnce);
+  }
+}
+
+module.exports = { scheduleBootSelfHeal, runEpicIndexSelfHeal };

package/src/main/lib/buildIdentity.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+/**
+ * buildIdentity.cjs — answers "which code produced this run" for both a
+ * published npx install (no .git shipped) and a dev checkout / job worktree
+ * (a real .git, but never the source of truth once a build has been baked).
+ *
+ * Resolution order, memoized after first call:
+ *   1. src/main/build-info.json (written by scripts/write-build-info.cjs at
+ *      `prepack`/`prepublishOnly` time, from the PUBLISHING checkout) — the
+ *      only artifact that is honest in production, since the npx cache the
+ *      app actually runs from ships no .git directory at all.
+ *   2. `git rev-parse` against the package root, but ONLY when a .git
+ *      directory exists AT that exact root — never git's own upward walk.
+ *      Without this guard, a relocated/nested install whose npm cache
+ *      happens to sit under an ancestor .git would silently stamp a FOREIGN
+ *      sha (git -C only sets the starting point; it still searches upward
+ *      for the nearest .git by default). Checking existence at the package
+ *      root ourselves, and only then invoking git, means the first (and
+ *      only) .git git can find IS the one we already verified.
+ *   3. null.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { resolveInstallChannel } = require('./machineProfile.cjs');
+
+// src/main/lib -> src/main -> src -> package root (repo root in dev, or the
+// npx-cached package dir in production).
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function loadBuildInfoJson(packageRoot) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(packageRoot, 'src', 'main', 'build-info.json'), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolvePackageVersion(packageRoot) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveGitCodeSha(packageRoot) {
+  if (!fs.existsSync(path.join(packageRoot, '.git'))) return null;
+  try {
+    return execFileSync('git', ['-C', packageRoot, 'rev-parse', '--short', 'HEAD'], {
+      timeout: 5000,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function computeBuildIdentity(packageRoot) {
+  const buildInfo = loadBuildInfoJson(packageRoot);
+  const version = (buildInfo && typeof buildInfo.version === 'string') ? buildInfo.version : resolvePackageVersion(packageRoot);
+  const codeSha = buildInfo
+    ? ((typeof buildInfo.gitShortSha === 'string') ? buildInfo.gitShortSha : null)
+    : resolveGitCodeSha(packageRoot);
+  const builtAt = (buildInfo && typeof buildInfo.builtAt === 'string') ? buildInfo.builtAt : null;
+  return {
+    version,
+    codeSha,
+    builtAt,
+    appPath: packageRoot,
+    installChannel: resolveInstallChannel({ appPath: packageRoot, devFlag: !!process.env.SM_DEV }),
+  };
+}
+
+// Keyed by resolved root: a real process only ever resolves ONE root (this
+// module's own package root), so in production/dev this behaves as a plain
+// singleton memo — the Map only grows past size 1 under test, where each
+// case injects a distinct fixture packageRoot.
+const identityCache = new Map();
+
+/**
+ * @param {object} [opts]
+ * @param {string|null} [opts.bootedAt] - the caller's OWN already-captured
+ *   process-boot timestamp (e.g. scheduler.cjs's SCHEDULER_BOOTED_AT). Never
+ *   re-captured here — a memoized resolver that stamped its own "now" would
+ *   drift from what SCHEDULER_BOOTED_AT was introduced to expose (PRD 812:
+ *   process staleness relative to on-disk source).
+ * @param {string} [opts.packageRoot] - test-only override; production/dev
+ *   callers never pass this, so it always resolves to this module's own
+ *   package root.
+ */
+function resolveBuildIdentity(opts = {}) {
+  const packageRoot = opts.packageRoot || PACKAGE_ROOT;
+  if (!identityCache.has(packageRoot)) identityCache.set(packageRoot, computeBuildIdentity(packageRoot));
+  return { ...identityCache.get(packageRoot), bootedAt: opts.bootedAt ?? null };
+}
+
+/**
+ * readInstalledBuildInfo() → the build-info.json currently ON DISK at this
+ * package root (fresh read, never the boot-time memo), or null. Compared with
+ * the running identity's codeSha to detect that an install/update already
+ * replaced the files under a live process.
+ */
+function readInstalledBuildInfo(packageRoot = PACKAGE_ROOT) {
+  return loadBuildInfoJson(packageRoot);
+}
+
+module.exports = { resolveBuildIdentity, readInstalledBuildInfo };

package/src/main/lib/classifyPromptTicket.cjs

@@ -16,7 +16,7 @@
  */
 
 const { spawn } = require('node:child_process');
-const { resolveClaudeBin } = require('./claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
 const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
 
 const CLASSIFY_TIMEOUT_MS = 30_000;
@@ -78,7 +78,8 @@ function classifyPromptTicket(text) {
 
     try {
       // stdin closed — `claude -p` otherwise blocks waiting for piped stdin.
-      child = spawnImpl(claudeBin, args, { env: childEnv, stdio: ['ignore', 'pipe', 'pipe'] });
+      const target = claudeSpawnTarget('aux', 'classify', claudeBin);
+      child = spawnImpl(target.command, args, { env: childEnv, stdio: ['ignore', 'pipe', 'pipe'], ...(target.argv0 ? { argv0: target.argv0 } : {}) });
     } catch {
       finish('inline');
       return;

package/src/main/lib/claudeBin.cjs

@@ -39,6 +39,40 @@ function resolveClaudeBin() {
   return cached;
 }
 
+// ---------- process naming ----------
+//
+// 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:
+//  - 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
+//    fallback is byte-identical to the pre-naming spawn.
+//  - Every alias and argv0 label contains the word `claude`, which the four
+//    /\bclaude\b/ cmdline gates (killOrphanClaudePid, claudePidAlive,
+//    findLiveProcessForJob x2) depend on.
+const ROLE_ALIASES = { job: 'sm-claude-job', chat: 'sm-claude-chat', aux: 'sm-claude-aux' };
+
+/**
+ * @param {'job'|'chat'|'aux'} role
+ * @param {string} [detail] argv0 label detail (job slug / epic session id)
+ * @param {string} [realBin] defaults to resolveClaudeBin()
+ * @returns {{ command: string, argv0?: string }} spread `argv0` into spawn options
+ */
+function claudeSpawnTarget(role, detail, realBin = resolveClaudeBin()) {
+  if (process.env.SM_CLAUDE_BIN) return { command: realBin };
+  const alias = ROLE_ALIASES[role];
+  if (!alias) return { command: realBin };
+  try {
+    const { aliasBinFor, smArgv0 } = require('./procName.cjs');
+    const command = aliasBinFor(realBin, alias);
+    if (command === realBin) return { command: realBin };
+    return { command, argv0: smArgv0(role, detail) };
+  } catch {
+    return { command: realBin };
+  }
+}
+
 // ---------- version probe ----------
 //
 // `claude --version`, cached. The scheduler's launch circuit breaker
@@ -75,7 +109,8 @@ function probeClaudeVersion({ now = Date.now(), execFileImpl } = {}) {
       // it, and the binary must never be handed the caller's working tree —
       // a stub `claude` (tests point SM_CLAUDE_BIN at one) that writes
       // markers or commits into process.cwd() once did so in the real repo.
-      execFile(bin, ['--version'], { timeout: VERSION_PROBE_TIMEOUT_MS, windowsHide: true, cwd: os.tmpdir() }, (err, stdout) => {
+      const target = claudeSpawnTarget('aux', 'version', bin);
+      execFile(target.command, ['--version'], { timeout: VERSION_PROBE_TIMEOUT_MS, windowsHide: true, cwd: os.tmpdir(), ...(target.argv0 ? { argv0: target.argv0 } : {}) }, (err, stdout) => {
         if (err) return done(null);
         const m = /(\d+\.\d+\.\d+[^\s]*)/.exec(String(stdout || ''));
         done(m ? m[1] : (String(stdout || '').trim() || null));
@@ -92,4 +127,4 @@ function resetClaudeVersionCache() {
   versionCache = { at: 0, value: null, inflight: null };
 }
 
-module.exports = { resolveClaudeBin, probeClaudeVersion, resetClaudeVersionCache };
+module.exports = { resolveClaudeBin, claudeSpawnTarget, probeClaudeVersion, resetClaudeVersionCache };

package/src/main/lib/cleanEnv.cjs

@@ -35,8 +35,34 @@ function pathWithUserBins() {
   return base ? `${base}:${userBinDirs().join(':')}` : userBinDirs().join(':');
 }
 
+/**
+ * SM_PROC_ROLE attributes a child (and, by inheritance, every MCP server the
+ * `claude` child spawns — we cannot rename those) via /proc/<pid>/environ.
+ * Read by scripts/sm-ps.cjs. NOT SM_PROC_ROOT (procIdentity.cjs's /proc-root
+ * test override) — unrelated variable.
+ */
+const PROC_ROLE_ENV = 'SM_PROC_ROLE';
+
+/** Explicit `SM_PROC_ROLE` in `extra` wins; else inferred from the attribution
+ *  vars each spawn site already sets (job slug → job, tab id → shell, chat
+ *  session → chat); else `aux`. Inference keeps role stamping in ONE place. */
+function inferProcRole(extra) {
+  if (extra[PROC_ROLE_ENV]) return String(extra[PROC_ROLE_ENV]);
+  if (extra.SM_SCHEDULER_JOB_SLUG) return 'job';
+  if (extra.SESSION_MANAGER_TAB_ID) return 'shell';
+  if (extra.SM_CHAT_SESSION_ID) return 'chat';
+  return 'aux';
+}
+
+/** Stamp SM_PROC_ROLE onto a raw env object (for sites that deliberately do not
+ *  use cleanChildEnv's secret stripping, e.g. runClaudeP/docEdit). Returns a copy. */
+function withProcRole(env, role) {
+  return { ...env, [PROC_ROLE_ENV]: role };
+}
+
 function cleanChildEnv(extra = {}) {
   const env = { ...process.env, ...extra };
+  env[PROC_ROLE_ENV] = inferProcRole(extra);
   for (const k of Object.keys(env)) {
     if (
       k === 'CLAUDE_EFFORT' ||
@@ -52,4 +78,4 @@ function cleanChildEnv(extra = {}) {
   return env;
 }
 
-module.exports = { cleanChildEnv, userBinDirs, pathWithUserBins };
+module.exports = { cleanChildEnv, withProcRole, inferProcRole, PROC_ROLE_ENV, userBinDirs, pathWithUserBins };

package/src/main/lib/credentials.cjs

@@ -6,7 +6,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { spawn, execFileSync } = require('node:child_process');
 const { cleanChildEnv, pathWithUserBins } = require('./cleanEnv.cjs');
-const { resolveClaudeBin } = require('./claudeBin.cjs');
+const { resolveClaudeBin, claudeSpawnTarget } = require('./claudeBin.cjs');
 
 const CREDS_PATH = path.join(os.homedir(), '.claude', '.credentials.json');
 
@@ -188,7 +188,9 @@ function tryCliFallback() {
     try {
       // Resolve the absolute binary + inject Homebrew/user bins so this works
       // even when Electron launched from Finder/Dock with a stripped PATH (mac).
-      child = spawn(resolveClaudeBin(), ['--version'], {
+      const target = claudeSpawnTarget('aux', 'credcheck');
+      child = spawn(target.command, ['--version'], {
+        ...(target.argv0 ? { argv0: target.argv0 } : {}),
         stdio: 'ignore',
         env: cleanChildEnv({ PATH: pathWithUserBins() }),
       });

package/src/main/lib/cwdClassify.cjs

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * cwdClassify.cjs — THE one answer to "what project is this path?".
+ *
+ * activeSessions.projectRootOf, ephemeralCwd.isEphemeralCwd and
+ * opsOwnership.resolveProjectRoot each used to re-derive that answer and each
+ * failed OPEN: when a worktree's `.git` FILE survives but its admin-dir
+ * back-reference is gone, worktreeMainRootOf returned null, projectRootOf
+ * handed the worktree path back unchanged, isLinkedWorktreeRoot said false, and
+ * resolveOpsRoot built `<worktree>/session-manager-operations` — the shape
+ * behind the lost-Epics incidents. classifyCwd reports BOTH facts (which
+ * project, and how sure we are) so a caller can refuse WRITES for the
+ * unprovable case (`unknown`) while dispatch and reads carry on.
+ *
+ * Kinds:
+ *   worktree  — `.git` is a FILE whose gitdir sits under `<main>/.git/worktrees/`
+ *               AND the main tree's admin dir back-references it (round trip).
+ *               projectRoot = <main>.
+ *   project   — `.git` is a directory, OR a FILE whose gitdir is NOT under a
+ *               worktrees/ dir (separate-git-dir / submodule), OR no `.git` at
+ *               all. projectRoot = the dir holding `.git` (else the cwd).
+ *   ephemeral — os.tmpdir() itself, or inside a managed job/epic worktree root,
+ *               and not provably a live worktree.
+ *   unknown   — a `.git` FILE we cannot resolve (garbled, unreadable, worktrees
+ *               gitdir with a missing/mismatched back-reference). projectRoot is
+ *               the (ops-truncated) cwd unchanged; ops WRITES must be refused.
+ *
+ * Two ops-root facts are returned and deliberately NOT unified:
+ *   outermostOpsRoot — first `session-manager-operations` segment (indexOf).
+ *       activeSessions truncates here: a stray nested ops root is itself the bug.
+ *   innermostOpsRoot — last segment (lastIndexOf). opsOwnership.assertOpsWrite
+ *       derives the project a write targets from here.
+ *   Both are null when the path is not inside an ops root.
+ *
+ * Pure fs, synchronous, never throws. Must stay light — required by
+ * scripts/hooks/guard-inline-implementation.cjs (via nearestGitEntry) and
+ * activeSessions.cjs; no gitWorktree/config requires.
+ */
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const schedulerPaths = require('./schedulerPaths.cjs');
+
+const OPS_DIRNAME = 'session-manager-operations';
+const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+// Bound on the ancestor walk — past any real fs depth, guarantees termination.
+const MAX_WALK = 40;
+
+/**
+ * nearestGitEntry(cwd) → { dir, isFile } for the nearest ancestor-or-self that
+ * has a `.git` entry (`isFile` true = linked worktree / submodule pointer file),
+ * or null. The tiny pure helper for callers that must not load git tooling.
+ */
+function nearestGitEntry(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < MAX_WALK; i++) {
+    let stat = null;
+    try { stat = fs.statSync(path.join(dir, '.git')); } catch { /* none here */ }
+    if (stat) return { dir, isFile: stat.isFile() };
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Classify the git shape at/above `start`. O(depth) stats + ≤2 small reads.
+ * → { shape: 'none' | 'gitdir' | 'worktree' | 'separate' | 'unknown', dir, mainRoot, reason }
+ */
+function inspectGit(start) {
+  const entry = nearestGitEntry(start);
+  if (!entry) return { shape: 'none', dir: null, mainRoot: null, reason: 'no .git found' };
+  if (!entry.isFile) return { shape: 'gitdir', dir: entry.dir, mainRoot: null, reason: '.git is a directory' };
+
+  const gitPath = path.join(entry.dir, '.git');
+  let body;
+  try {
+    body = fs.readFileSync(gitPath, 'utf8');
+  } catch (e) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `unreadable .git file: ${e?.code || e?.message}` };
+  }
+  const firstLine = body.split('\n', 1)[0].trim();
+  if (!firstLine.startsWith('gitdir:')) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: '.git file has no "gitdir:" line' };
+  }
+  const gitdirRaw = firstLine.slice('gitdir:'.length).trim();
+  if (!gitdirRaw) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: '.git file has an empty gitdir' };
+  }
+  // Submodules point at a RELATIVE gitdir; resolve against the file's own dir.
+  const gitdir = path.resolve(entry.dir, gitdirRaw);
+  const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
+  if (markerIdx === -1) {
+    // Not a linked worktree: separate-git-dir / submodule. Its own project.
+    return { shape: 'separate', dir: entry.dir, mainRoot: null, reason: 'gitdir is not under .git/worktrees/ (separate-git-dir or submodule)' };
+  }
+  if (markerIdx <= 0) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: 'gitdir worktrees marker has no main root above it' };
+  }
+  const candidateMain = gitdir.slice(0, markerIdx);
+  const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
+  if (!worktreeName) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: 'gitdir names no worktree' };
+  }
+  // Round-trip: the .git file is plain text anything could have written, so it
+  // must not redirect callers to an arbitrary path. The main tree's own admin
+  // dir must point back at THIS .git file.
+  const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
+  let backRef;
+  try {
+    backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
+  } catch {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `worktree admin back-reference missing (${adminGitdirFile})` };
+  }
+  if (path.resolve(backRef) !== path.resolve(gitPath)) {
+    return { shape: 'unknown', dir: entry.dir, mainRoot: null, reason: `worktree admin back-reference points elsewhere (${adminGitdirFile})` };
+  }
+  return { shape: 'worktree', dir: entry.dir, mainRoot: candidateMain, reason: 'linked worktree, back-reference verified' };
+}
+
+/**
+ * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
+ * verified linked worktree, the ancestor itself when `.git` is a directory,
+ * else null (no git, separate-git-dir, or anything unprovable).
+ */
+function worktreeMainRootOf(cwd) {
+  const g = inspectGit(cwd);
+  if (g.shape === 'worktree') return g.mainRoot;
+  if (g.shape === 'gitdir') return g.dir;
+  return null;
+}
+
+function isExactlyTmpdir(absCwd) {
+  return absCwd === path.resolve(os.tmpdir());
+}
+
+function isUnderManagedWorktreeRoot(absCwd) {
+  return ['job', 'epic'].map((k) => path.resolve(schedulerPaths.worktreeRoot(k))).some((root) => {
+    const rel = path.relative(root, absCwd);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  });
+}
+
+/**
+ * classifyCwd(cwd) → { kind, projectRoot, outermostOpsRoot, innermostOpsRoot, reason }
+ * See the file header. A non-string/empty cwd is `unknown` with a null root.
+ */
+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' };
+  }
+  const parts = cwd.split(path.sep);
+  const first = parts.indexOf(OPS_DIRNAME);
+  const last = parts.lastIndexOf(OPS_DIRNAME);
+  const opsAt = (i) => (i >= 0 ? (parts.slice(0, i + 1).join(path.sep) || path.sep) : null);
+  const outermostOpsRoot = opsAt(first);
+  const innermostOpsRoot = opsAt(last);
+  // Outermost truncation (the activeSessions law). i === 0 is a relative
+  // fragment, never truncated.
+  const truncated = first > 0 ? (parts.slice(0, first).join(path.sep) || path.sep) : cwd;
+
+  const g = inspectGit(truncated);
+  const facts = { outermostOpsRoot, innermostOpsRoot };
+  if (g.shape === 'worktree') {
+    return { kind: 'worktree', projectRoot: g.mainRoot, ...facts, reason: g.reason };
+  }
+  if (path.isAbsolute(cwd)) {
+    const abs = path.resolve(cwd);
+    if (isExactlyTmpdir(abs) || isUnderManagedWorktreeRoot(abs)) {
+      return { kind: 'ephemeral', projectRoot: truncated, ...facts, reason: 'tmpdir or managed job/epic worktree root' };
+    }
+  }
+  if (g.shape === 'unknown') {
+    return { kind: 'unknown', projectRoot: truncated, ...facts, reason: g.reason };
+  }
+  if (g.shape === 'none') {
+    return { kind: 'project', projectRoot: truncated, ...facts, reason: g.reason };
+  }
+  return { kind: 'project', projectRoot: g.dir, ...facts, reason: g.reason };
+}
+
+module.exports = { classifyCwd, nearestGitEntry, worktreeMainRootOf, OPS_DIRNAME };