fix(session-log): walk ancestor PIDs to find Claude Code session metadata

When plannotator is invoked from a slash command's `!` bang, the direct
parent process is an intermediate bash shell spawned by the Bash tool —
not Claude Code itself. The old resolveSessionLogByPpid() only checked
process.ppid, so it always missed the session metadata file and fell back
to mtime-based selection, which picks the wrong log when multiple sessions
exist for the same project.

New resolution ladder (four tiers):
1. Ancestor-PID walk: call `ps -o ppid=` repeatedly from process.ppid up
   to 8 hops, checking ~/.claude/sessions/<pid>.json at each hop.
   Deterministic — no guessing, matches exact session every time.
2. Cwd-scan: read every ~/.claude/sessions/*.json, filter by cwd, pick
   most recent startedAt. Handles cases where ps is unavailable.
3. CWD slug mtime (legacy): existing behavior, fragile with multiple
   sessions.
4. Ancestor directory walk: handles cd-deeper-into-subdirectory cases.

Adds getAncestorPids (injectable getParent for testing), resolveSessionLogByAncestorPids,
and resolveSessionLogByCwdScan. Exports SessionMetadata and accepts
projectsDirOverride on findSessionLogsForCwd for test isolation.

17 new tests cover: edge cases for getAncestorPids (cycles, maxHops,
self-loops), resolveSessionLogByAncestorPids (finds correct session among
multiple, skips missing logs, falls back when no metadata matches), and
resolveSessionLogByCwdScan (picks newest startedAt, ignores mismatched
cwd, handles missing sessions dir).

Closes #458

Author: elithompson

apps/hook/server/index.ts

@@ -81,7 +81,7 @@ import { hostnameOrFallback } from "@plannotator/shared/project";
 import { planDenyFeedback } from "@plannotator/shared/feedback-templates";
 import { readImprovementHook } from "@plannotator/shared/improvement-hooks";
 import type { Origin } from "@plannotator/shared/agents";
-import { findSessionLogsForCwd, resolveSessionLogByPpid, findSessionLogsByAncestorWalk, getLastRenderedMessage, type RenderedMessage } from "./session-log";
+import { findSessionLogsForCwd, resolveSessionLogByAncestorPids, resolveSessionLogByCwdScan, findSessionLogsByAncestorWalk, getLastRenderedMessage, type RenderedMessage } from "./session-log";
 import { findCodexRolloutByThreadId, getLastCodexMessage } from "./codex-session";
 import { findCopilotPlanContent, findCopilotSessionForCwd, getLastCopilotMessage } from "./copilot-session";
 import {
@@ -641,12 +641,18 @@ if (args[0] === "sessions") {
     // Claude Code path: resolve session log
     //
     // Strategy (most precise → least precise):
-    // 1. PPID session metadata: ~/.claude/sessions/<ppid>.json gives us the
-    //    exact sessionId and original cwd. Deterministic, O(1), no scanning.
-    // 2. CWD slug match: existing behavior — works when the shell CWD hasn't
-    //    changed from the session's project directory.
-    // 3. Ancestor walk: walk up the directory tree trying parent slugs. Handles
-    //    the common case where the user `cd`'d deeper into a subdirectory.
+    // 1. Ancestor-PID session metadata: walk up the process tree checking
+    //    ~/.claude/sessions/<pid>.json at each hop. When invoked from a slash
+    //    command's `!` bang, the direct parent is a bash subshell — Claude's
+    //    session file is a few hops up. Deterministic when it matches.
+    // 2. Cwd-scan of session metadata: read every ~/.claude/sessions/*.json,
+    //    filter by cwd, pick the most recent startedAt. Better than mtime
+    //    guessing because it uses session-level metadata.
+    // 3. CWD slug match (mtime-based): legacy behavior — picks the most
+    //    recently modified jsonl in the project dir. Fragile when multiple
+    //    sessions exist for the same project.
+    // 4. Ancestor directory walk: handles the case where the user `cd`'d
+    //    deeper into a subdirectory after session start.
 
     if (process.env.PLANNOTATOR_DEBUG) {
       console.error(`[DEBUG] Project root: ${projectRoot}`);
@@ -666,15 +672,19 @@ if (args[0] === "sessions") {
       }
     }
 
-    // 1. Try PPID-based session metadata (most reliable)
-    const ppidLog = resolveSessionLogByPpid();
-    tryLogCandidates("PPID session metadata", () => ppidLog ? [ppidLog] : []);
+    // 1. Walk ancestor PIDs for a matching session metadata file
+    const ancestorLog = resolveSessionLogByAncestorPids();
+    tryLogCandidates("Ancestor PID session metadata", () => ancestorLog ? [ancestorLog] : []);
 
-    // 2. Fall back to CWD slug match
-    tryLogCandidates("CWD slug match", () => findSessionLogsForCwd(projectRoot));
+    // 2. Scan all session metadata files for one whose cwd matches
+    const cwdScanLog = resolveSessionLogByCwdScan({ cwd: projectRoot });
+    tryLogCandidates("Cwd-scan session metadata", () => cwdScanLog ? [cwdScanLog] : []);
 
-    // 3. Fall back to ancestor directory walk
-    tryLogCandidates("Ancestor walk", () => findSessionLogsByAncestorWalk(projectRoot));
+    // 3. Fall back to CWD slug match (mtime-based)
+    tryLogCandidates("CWD slug match (mtime)", () => findSessionLogsForCwd(projectRoot));
+
+    // 4. Fall back to ancestor directory walk
+    tryLogCandidates("Directory ancestor walk", () => findSessionLogsByAncestorWalk(projectRoot));
   }
 
   if (!lastMessage) {

apps/hook/server/session-log.test.ts

@@ -16,6 +16,9 @@ import {
   projectSlugFromCwd,
   findSessionLogsByAncestorWalk,
   findSessionLogsForCwd,
+  getAncestorPids,
+  resolveSessionLogByAncestorPids,
+  resolveSessionLogByCwdScan,
   type SessionLogEntry,
 } from "./session-log";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
@@ -635,3 +638,295 @@ describe("findSessionLogsByAncestorWalk", () => {
     }
   });
 });
+
+// --- Resolver Tests (new) ---
+
+describe("getAncestorPids", () => {
+  test("returns empty array for invalid startPid", () => {
+    expect(getAncestorPids(0, 5, () => null)).toEqual([]);
+    expect(getAncestorPids(1, 5, () => null)).toEqual([]);
+  });
+
+  test("returns startPid when there is no parent", () => {
+    expect(getAncestorPids(100, 5, () => null)).toEqual([100]);
+  });
+
+  test("walks up the PID chain until root", () => {
+    const parents: Record<number, number> = { 100: 200, 200: 300, 300: 1 };
+    expect(
+      getAncestorPids(100, 10, (p) => parents[p] ?? null)
+    ).toEqual([100, 200, 300]);
+  });
+
+  test("respects maxHops limit", () => {
+    const parents: Record<number, number> = { 100: 200, 200: 300, 300: 400 };
+    expect(
+      getAncestorPids(100, 2, (p) => parents[p] ?? null)
+    ).toEqual([100, 200]);
+  });
+
+  test("breaks on PID cycles", () => {
+    const parents: Record<number, number> = { 100: 200, 200: 100 };
+    const chain = getAncestorPids(100, 50, (p) => parents[p] ?? null);
+    expect(chain).toEqual([100, 200]);
+  });
+
+  test("breaks when getParent returns startPid (self-loop)", () => {
+    const chain = getAncestorPids(100, 50, () => 100);
+    expect(chain).toEqual([100]);
+  });
+});
+
+/** Build an isolated sessions + projects dir under tmpdir for a test. */
+function makeTempDirs(label: string): {
+  sessionsDir: string;
+  projectsDir: string;
+  cleanup: () => void;
+} {
+  const base = join(tmpdir(), `plannotator-resolver-${label}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const sessionsDir = join(base, "sessions");
+  const projectsDir = join(base, "projects");
+  mkdirSync(sessionsDir, { recursive: true });
+  mkdirSync(projectsDir, { recursive: true });
+  return {
+    sessionsDir,
+    projectsDir,
+    cleanup: () => rmSync(base, { recursive: true, force: true }),
+  };
+}
+
+/** Write a session metadata file for a PID. */
+function writeSessionMeta(
+  sessionsDir: string,
+  pid: number,
+  meta: { sessionId: string; cwd: string; startedAt?: number }
+): void {
+  writeFileSync(
+    join(sessionsDir, `${pid}.json`),
+    JSON.stringify({
+      pid,
+      sessionId: meta.sessionId,
+      cwd: meta.cwd,
+      startedAt: meta.startedAt ?? Date.now(),
+    })
+  );
+}
+
+/** Create a session jsonl for a given cwd + sessionId. */
+function writeSessionLog(
+  projectsDir: string,
+  cwd: string,
+  sessionId: string,
+  content = '{"type":"assistant","message":{"id":"m1","content":[{"type":"text","text":"hi"}]}}\n'
+): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9-]/g, "-");
+  const dir = join(projectsDir, slug);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, `${sessionId}.jsonl`);
+  writeFileSync(path, content);
+  return path;
+}
+
+describe("resolveSessionLogByAncestorPids", () => {
+  test("returns null when no ancestor PID has session metadata", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("no-ancestor");
+    try {
+      const result = resolveSessionLogByAncestorPids({
+        startPid: 100,
+        getParentPid: () => null,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("finds session at direct parent (1 hop)", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("direct-parent");
+    try {
+      const cwd = "/tmp/fake-project-direct";
+      const sessionId = "abcd-1234";
+      writeSessionMeta(sessionsDir, 999, { sessionId, cwd });
+      const logPath = writeSessionLog(projectsDir, cwd, sessionId);
+
+      const result = resolveSessionLogByAncestorPids({
+        startPid: 999,
+        getParentPid: () => null,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBe(logPath);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("walks past bash subshell to find Claude Code ancestor", () => {
+    // Simulates: plannotator (ppid=500 = sh) → sh (ppid=400 = claude)
+    // Claude Code's session file is at pid 400, NOT 500.
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("walks-past");
+    try {
+      const cwd = "/tmp/fake-project-walk";
+      const sessionId = "walk-1234";
+      writeSessionMeta(sessionsDir, 400, { sessionId, cwd });
+      const logPath = writeSessionLog(projectsDir, cwd, sessionId);
+
+      const parents: Record<number, number> = { 500: 400, 400: 1 };
+      const result = resolveSessionLogByAncestorPids({
+        startPid: 500,
+        getParentPid: (p) => parents[p] ?? null,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBe(logPath);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("skips metadata when matching jsonl does not exist", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("skip-missing");
+    try {
+      const cwd = "/tmp/fake-project-skip";
+      // Metadata exists but the log file does not
+      writeSessionMeta(sessionsDir, 400, { sessionId: "missing-id", cwd });
+
+      const result = resolveSessionLogByAncestorPids({
+        startPid: 400,
+        getParentPid: () => null,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("returns null when sessionsDir doesn't exist", () => {
+    const { projectsDir, cleanup } = makeTempDirs("no-sessions");
+    try {
+      const result = resolveSessionLogByAncestorPids({
+        startPid: 100,
+        getParentPid: () => null,
+        sessionsDir: "/nonexistent/sessions/dir/xyz",
+        projectsDir,
+      });
+      expect(result).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
+describe("resolveSessionLogByCwdScan", () => {
+  test("returns null when sessionsDir is empty", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("empty");
+    try {
+      const result = resolveSessionLogByCwdScan({
+        cwd: "/tmp/any",
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("returns null when no session metadata matches cwd", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("no-match");
+    try {
+      writeSessionMeta(sessionsDir, 100, {
+        sessionId: "other-id",
+        cwd: "/tmp/other-project",
+      });
+      const result = resolveSessionLogByCwdScan({
+        cwd: "/tmp/my-project",
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("picks most recent startedAt when multiple sessions match cwd", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("pick-recent");
+    try {
+      const cwd = "/tmp/multi-project";
+      // Two concurrent sessions with the same cwd
+      writeSessionMeta(sessionsDir, 111, {
+        sessionId: "old-session",
+        cwd,
+        startedAt: 1_000,
+      });
+      writeSessionMeta(sessionsDir, 222, {
+        sessionId: "new-session",
+        cwd,
+        startedAt: 2_000,
+      });
+      writeSessionLog(projectsDir, cwd, "old-session");
+      const newLog = writeSessionLog(projectsDir, cwd, "new-session");
+
+      const result = resolveSessionLogByCwdScan({
+        cwd,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBe(newLog);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("falls through to older session if newest has no matching jsonl", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("fallthrough");
+    try {
+      const cwd = "/tmp/fallthrough-project";
+      writeSessionMeta(sessionsDir, 111, {
+        sessionId: "old-session",
+        cwd,
+        startedAt: 1_000,
+      });
+      writeSessionMeta(sessionsDir, 222, {
+        sessionId: "new-session-no-log",
+        cwd,
+        startedAt: 2_000,
+      });
+      const oldLog = writeSessionLog(projectsDir, cwd, "old-session");
+      // Note: no jsonl for new-session-no-log
+
+      const result = resolveSessionLogByCwdScan({
+        cwd,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBe(oldLog);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("ignores malformed session metadata files", () => {
+    const { sessionsDir, projectsDir, cleanup } = makeTempDirs("malformed");
+    try {
+      const cwd = "/tmp/malformed-project";
+      writeFileSync(join(sessionsDir, "999.json"), "not valid json");
+      writeSessionMeta(sessionsDir, 111, { sessionId: "good", cwd });
+      const goodLog = writeSessionLog(projectsDir, cwd, "good");
+
+      const result = resolveSessionLogByCwdScan({
+        cwd,
+        sessionsDir,
+        projectsDir,
+      });
+      expect(result).toBe(goodLog);
+    } finally {
+      cleanup();
+    }
+  });
+});