claude-code-session-manager 0.75.3 → 0.77.0

package/plugins/session-manager-dev/skills/develop/standards.md

@@ -83,7 +83,7 @@ Data-driven from 400+ scheduler runs: long hangs (not bad code) are the dominant
 - **Fail loud, fail fast.** On any step failure, print one diagnostic line and `exit 1`; don't swallow with `|| true` or spin in a silent retry. A `rateLimited` exit-1 is the scheduler's benign auto-pause (auto-resumes next window) — not a failure to engineer around.
 - **Stay in the AC.** Do not add work past the acceptance checklist ("while we're here" generators/fixtures are the post-AC-overrun incident). Body must be clean UTF-8 — no NUL/control bytes.
 - **You ARE the executor — never re-queue or self-schedule.** A headless PRD run must perform its own acceptance criteria directly. Do NOT invoke `/develop` or any queue-authoring skill from inside a run — those are interactive main-loop skills that author a *new* PRD and return, so the run exits 0 having done nothing (no commit, no sentinel → `needs_review` with `no_verdict_sentinel`). Do NOT call `ScheduleWakeup`/set a tracking loop either — the process exits when the run ends and nothing re-invokes it. This applies just as much to spawning your own review agents and waiting on them: do NOT invoke `/code-review`, `/security-review`, `requesting-code-review`, or any other skill/subagent as a background/async step and then end your turn with something like "I'll wait for the review agents to complete" — a headless run has no next turn, so that line is the run's last output, no verdict sentinel prints, and the job parks in `needs_review` even though the actual work already landed. If a PRD's acceptance criteria call for a second review pass, run it **synchronously, inline, before the finish protocol** — call the reviewer and read its result in the same turn, don't fire-and-wait. If the PRD's work looks large, decompose and execute it inline within this run; never delegate it back to the queue. (Incidents: PRD 460 invoked `/develop`, spawned a duplicate PRD 461, and exited 0 with no work. PRD 479 landed its commit correctly but then backgrounded `/code-review --fix` + `/security-review` and called `ScheduleWakeup` to "wait" for them — same class of failure, different entry point.)
-- **A shared-repo `cwd` can be occupied by a concurrent job — check before you touch shared state.** When a PRD's `cwd` is a repo other headless runs may also target (a shared team repo like sigma, not a private single-purpose project), a `git checkout`/`gh pr checkout` can land you in another job's live worktree with its own uncommitted WIP. Before running `git stash`, `git reset`, or any command that discards or hides working-tree state, check `git stash list` and `git status` first, and if you must set aside pre-existing uncommitted changes that aren't yours, **stash with a descriptive message** (`git stash push -m "pre-existing WIP found by PRD <NN>, not mine"`) and **restore it before your run ends** (or, if you can't safely restore because your own commit depends on that worktree state, leave it stashed with the message and say so explicitly in your finish output — never let the run end silently dropping someone else's stash). Never `git stash drop`/`git clean -fd` on state you didn't create. (Incident: PRD 477 stashed a concurrent job's rAF-throttle-revert WIP to get its own checkout, finished, and exited without restoring it — orphaning the other job's uncommitted work in `stash@{0}` with no record of whose it was.)
+- **Never `git stash`, `git reset`, `git checkout -- <path>`, or `git clean` against working-tree state you did not create — there is no polite version of this.** You are normally already isolated in your own `git worktree` on branch `sm-job/<slug>` (`src/main/lib/gitWorktree.cjs` — dirty base trees no longer disable this isolation, and the scheduler salvages any uncommitted diff on teardown, so you don't need to touch shared state to preserve your own work). Confirm you're isolated with `git rev-parse --git-common-dir` (a worktree's common-dir differs from its own `.git`) or by checking your cwd, before assuming otherwise. If you find yourself in a SHARED tree with pre-existing dirty tracked files anyway, work *around* them — scope `git add`/commits to only the paths you touched — or stop and report the conflict; never discard, stash, or revert someone else's uncommitted changes to get a clean checkout. A shared tree may be feeding a **running service** reading its config straight from the working tree (the trading repo's `data/spread_config.json` is live input, not a local scratch file) — reverting it is a production change, not a local inconvenience, and read-only inspection (`git diff`, `git status`) is always fine. The scheduler also runs a shared-tree stash guard as a backstop (`scheduler.cjs` `checkSharedTreeGuard`/`evaluateSharedTreeGuard`) that auto-restores a stash your run created and flags any baseline-dirty path that went clean with no commit — but that guard exists to catch a mistake, not to license one. (Incidents: PRD 477 stashed a concurrent job's rAF-throttle-revert WIP to get its own checkout and exited without restoring it, orphaning it in `stash@{0}` with no record of whose it was. 2026-09-01: a headless executor in the trader repo ran a blanket `git stash` against an operator's uncommitted LIVE TRADING CONFIG edit and exited without restoring it — `stash@{0}` "WIP on fix/trade-log-reconciliation-out-of-band-closes", `data/spread_config.json` — the third incident of this class.)
 - **`gh pr edit --body` can fail on repos with legacy GitHub Projects (classic) boards** — the underlying GraphQL query fetches `repository.pullRequest.projectCards`, a field GitHub is sunsetting, and errors with `GraphQL: Projects (classic) is being deprecated ... (repository.pullRequest.projectCards)` even though the edit itself would otherwise succeed. This is a known `gh` CLI quirk, not a defect in your work. Prefer `gh api -X PATCH repos/<owner>/<repo>/pulls/<n> -f body="$(cat body.md)"` for updating a PR description headlessly — it doesn't touch the deprecated field. If you do use `gh pr edit` and it fails this way, don't leave the bare GraphQL error as the last thing in that step (it reads as an unrecovered error in the final-20%-of-transcript verifier heuristic): immediately retry with the `gh api` form and print one line noting the known-bug fallback, so the recovery is adjacent to the error.
 - **`gh pr checks`/`gh run watch` exit non-zero while CI is merely *pending*, not failed — don't let that surface as a bare error.** Polling `gh pr checks <n>` before checks finish returns a non-zero exit (e.g. 8) with output like `check  pending  0  <url>` — this is normal, documented `gh` CLI behavior, not a failure. If you retry with a *differently-worded* command (e.g. dropping a `sleep N &&` prefix, or switching to `gh run watch <id> --exit-status`), the verifier's self-recovery detector pairs retries by exact command-description match and may not recognize the differently-worded retry as the same recovery, leaving the original pending-state error looking unrecovered in the transcript (incident: `745-pr188-ci-lint-docs-integrity`, a fully green, committed, pushed run flagged `needs_review` over exactly this). Prefer polling with the *same* command/description each time (e.g. loop `gh pr checks <n>` unchanged, or use `gh run watch <id> --exit-status` from the start rather than switching mid-poll) so a later success is recognized as recovering the earlier pending-state failure.
 - **Negative-assertion checks must exit 0 when clean.** A check that verifies the *absence* of something (a `grep` that should find nothing, "no leftover X", `diff` expecting no change) must return exit 0 on the clean case. A bare `grep` exits **1 on no-match** — so the *success* path surfaces as `is_error=true` and the verifier downgrades a perfect run to `needs_review`. Always invert: `if <detector>; then echo "HALT: <what was found>"; exit 1; fi; echo clean`. Never let the no-match/empty path carry the non-zero exit.

package/scripts/lib/activeSessions.cjs

@@ -11,8 +11,28 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const { KIND_CONFIG: WORKTREE_KIND_CONFIG } = require('../../src/main/lib/gitWorktree.cjs');
 
 const HOME = os.homedir();
+const TMPDIR = os.tmpdir();
+
+// The last-resort drop targets for addCwd's tmp guard.
+//   - exactDropCwds: dropped only on an EXACT match — os.tmpdir() itself
+//     (e.g. `/tmp`). NOT a prefix match: this codebase's own test suite
+//     routinely stubs HOME to a tmp dir and nests a fake project cwd
+//     underneath it, a legitimate, unrelated use of os.tmpdir() that a
+//     blanket prefix match would wrongly drop.
+//   - prefixDropRoots: dropped on an exact match OR any nested path — the two
+//     managed worktree roots (both live under os.tmpdir() per gitWorktree
+//     .cjs's KIND_CONFIG). Nothing but managed worktree checkouts is ever
+//     created under these roots, so a prefix match here is safe. A resolvable
+//     worktree (managed or user-made, anywhere on disk) is already handled by
+//     worktreeMainRootOf above; this guard only catches what that resolution
+//     could not — e.g. a bare, .git-less worktree-root directory.
+const TMP_DROP_ROOTS = {
+  exactDropCwds: [TMPDIR],
+  prefixDropRoots: [WORKTREE_KIND_CONFIG.job.root, WORKTREE_KIND_CONFIG.epic.root],
+};
 
 // Transcript reads only need the last line with a `cwd` field — a few dozen
 // lines is always enough. 64 KB keeps peak RSS proportionate.
@@ -37,16 +57,93 @@ const MAX_CWDS = 50;
 // signal survives instead of being silently lost.
 const OPS_DIRNAME = 'session-manager-operations';
 
+// Bound on the ancestor walk in worktreeMainRootOf — well past any real
+// filesystem depth, purely to guarantee termination without relying on
+// reaching '/' (e.g. a symlink loop or an unusually deep path).
+const MAX_WORKTREE_WALK = 40;
+
+const WORKTREES_MARKER = `${path.sep}.git${path.sep}worktrees${path.sep}`;
+
+/**
+ * worktreeMainRootOf(cwd) → the main tree's root when cwd sits inside a
+ * linked `git worktree` (job/epic worktrees under os.tmpdir(), or a
+ * user-made one anywhere). Walks UP from cwd looking for a `.git` entry:
+ *   - `.git` is a FILE (linked worktree) whose first line is
+ *     `gitdir: <main>/.git/worktrees/<name>` → returns <main>.
+ *   - `.git` is a DIRECTORY (already the main tree) → returns that ancestor.
+ *   - nothing found within MAX_WORKTREE_WALK levels → returns null.
+ * Pure fs, synchronous, never throws — any unexpected shape (garbled file,
+ * unreadable entry, gitdir path without the worktrees marker) yields null so
+ * the caller leaves the cwd unchanged rather than guessing.
+ */
+function worktreeMainRootOf(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < MAX_WORKTREE_WALK; i++) {
+    const gitPath = path.join(dir, '.git');
+    let stat;
+    try {
+      stat = fs.statSync(gitPath);
+    } catch {
+      stat = null;
+    }
+    if (stat) {
+      if (stat.isDirectory()) return dir;
+      if (stat.isFile()) {
+        let body;
+        try {
+          body = fs.readFileSync(gitPath, 'utf8');
+        } catch {
+          return null;
+        }
+        const firstLine = body.split('\n', 1)[0].trim();
+        const prefix = 'gitdir:';
+        if (!firstLine.startsWith(prefix)) return null;
+        const gitdir = firstLine.slice(prefix.length).trim();
+        const markerIdx = gitdir.indexOf(WORKTREES_MARKER);
+        if (markerIdx <= 0) return null;
+        const candidateMain = gitdir.slice(0, markerIdx);
+        const worktreeName = gitdir.slice(markerIdx + WORKTREES_MARKER.length).split(path.sep)[0];
+        // Round-trip verification: gitdir's content is a plain file that
+        // anything on disk could have written (e.g. a nested `.git` file
+        // tracked inside an untrusted repo), so it must not be trusted to
+        // redirect callers to an arbitrary attacker-chosen absolute path.
+        // A genuine linked worktree's admin dir back-references the exact
+        // `.git` FILE we are resolving via its own `gitdir` pointer file —
+        // require that round trip before accepting candidateMain.
+        if (!worktreeName) return null;
+        const adminGitdirFile = path.join(candidateMain, '.git', 'worktrees', worktreeName, 'gitdir');
+        let backRef;
+        try {
+          backRef = fs.readFileSync(adminGitdirFile, 'utf8').trim();
+        } catch {
+          return null;
+        }
+        if (path.resolve(backRef) !== path.resolve(gitPath)) return null;
+        return candidateMain;
+      }
+      return null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
 /**
  * projectRootOf(cwd) → the project root for a cwd that may sit inside an ops
- * tree. Returns cwd unchanged when it does not. Only the FIRST occurrence
- * matters — a nested stray ops root is itself the bug, never a project.
+ * tree and/or a linked git worktree. Returns cwd unchanged when neither
+ * applies. Only the FIRST ops-dir occurrence matters — a nested stray ops
+ * root is itself the bug, never a project. The ops-dir truncation runs
+ * first, then the worktree resolution, so a cwd deep inside a worktree's OWN
+ * ops tree still lands on the real project's main root.
  */
 function projectRootOf(cwd) {
   const parts = cwd.split(path.sep);
   const i = parts.indexOf(OPS_DIRNAME);
-  if (i <= 0) return cwd;
-  return parts.slice(0, i).join(path.sep) || path.sep;
+  const truncated = i > 0 ? (parts.slice(0, i).join(path.sep) || path.sep) : cwd;
+  const mainRoot = worktreeMainRootOf(truncated);
+  return mainRoot || truncated;
 }
 
 /**
@@ -85,11 +182,13 @@ function readTailLines(filePath, maxBytes) {
  *   Complexity: O(P × L) over P project dirs, each bounded-tail read (64 KB).
  *
  * opts (for testing):
- *   projectsDir  — override the default ~/.claude/projects path
+ *   projectsDir   — override the default ~/.claude/projects path
+ *   tmpDropRoots  — override the tmp guard's drop roots (default TMP_DROP_ROOTS)
  */
 function activeProjectCwds(maxAgeMin = 90, {
   projectsDir = path.join(HOME, '.claude', 'projects'),
   maxCwds = MAX_CWDS,
+  tmpDropRoots = TMP_DROP_ROOTS,
 } = {}) {
   // maxAgeMin === Infinity means "every project ever seen, no recency filter"
   // (allProjectCwds below). Date.now() - Infinity is -Infinity, which every
@@ -111,6 +210,17 @@ function activeProjectCwds(maxAgeMin = 90, {
     // whole per-project state off these strings — a project is a cwd, and a
     // cwd is an absolute path.
     if (!path.isAbsolute(cwd)) return;
+    // Drop-guard of last resort: a cwd that is (or sits inside) a known
+    // worktree-scratch root after projectRootOf's normalization is one
+    // worktreeMainRootOf could not resolve to a main tree — never a real
+    // project.
+    if (tmpDropRoots.exactDropCwds.includes(cwd)) return;
+    const isUnderPrefixDropRoot = tmpDropRoots.prefixDropRoots.some((root) => {
+      if (cwd === root) return true;
+      const rel = path.relative(root, cwd);
+      return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+    });
+    if (isUnderPrefixDropRoot) return;
     if (seen.has(cwd) || result.length >= maxCwds) return;
     // Must exist AND be a directory — a transcript naming a since-deleted
     // path, or a file, is not a project.
@@ -178,4 +288,4 @@ function allProjectCwds(opts = {}) {
   return activeProjectCwds(Infinity, { maxCwds: 500, ...opts });
 }
 
-module.exports = { activeProjectCwds, allProjectCwds, projectRootOf };
+module.exports = { activeProjectCwds, allProjectCwds, projectRootOf, worktreeMainRootOf };