@hienlh/ppm 0.23.8 → 0.23.10

package/src/services/agent-transcript/agent-transcript-session-hub.ts

@@ -0,0 +1,196 @@
+/**
+ * Transcript-subscription lifecycle for a session hub: subscribe → catch-up
+ * → live tick scheduling. The per-tick read-and-push mechanics (exact per-page
+ * cursors, dynamic file-set growth) live in `agent-transcript-session-hub-read.ts`.
+ */
+import { CODEX_THREAD_ID_RE, resolveCodexDescendantFile, resolveSources } from "./agent-transcript-sources.ts";
+import { statSizeSafe } from "./agent-transcript-fs-io.ts";
+import { agentTranscriptClock, agentTranscriptTimers } from "./agent-transcript-hub-clock.ts";
+import { createFileTailState } from "./agent-transcript-file-tail-state.ts";
+import { isIdle, safePushUpdate } from "./agent-transcript-session-hub-read.ts";
+import { mapSourceErrorCode } from "./agent-transcript-error-map.ts";
+import { sendWsMessage, type AgentTranscriptWsLike } from "./agent-transcript-ws-like.ts";
+import type { SessionHub, TranscriptSubscription } from "./agent-transcript-session-hub-types.ts";
+import {
+  IDLE_TICK_MS, LIVE_TICK_MS,
+  type AgentTranscriptCursor, type AgentTranscriptErrorCode,
+  type AgentTranscriptErrorMsg, type AgentTranscriptSourceKind,
+} from "../../shared/agent-transcript-protocol.ts";
+
+/**
+ * A client-supplied cursor offset, sanitized: only a safe non-negative
+ * integer is trusted, and the result is clamped to the file's current size
+ * either way. A fractional, negative, NaN or absurdly large value degrades
+ * to "start from the beginning" rather than ever reaching a raw file read —
+ * `fs.readSync`'s position argument throws on anything but a real integer.
+ */
+function sanitizeOffset(value: unknown, size: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) return 0;
+  return Math.min(value, size);
+}
+
+export interface SubscribeResult {
+  ok: boolean;
+  code?: AgentTranscriptErrorCode;
+  /** A push failed mid-catch-up (send returned 0 or threw) — caller drops the whole client. */
+  sendFailed?: boolean;
+}
+
+function ensureTicker(hub: SessionHub): void {
+  if (hub.tickHandle !== null) return;
+  hub.tickHandle = agentTranscriptTimers.setInterval(() => tickTranscripts(hub), LIVE_TICK_MS);
+}
+
+function stopTickerIfEmpty(hub: SessionHub): void {
+  if (hub.subscriptions.size > 0 || hub.tickHandle === null) return;
+  agentTranscriptTimers.clearInterval(hub.tickHandle);
+  hub.tickHandle = null;
+}
+
+/**
+ * Codex only: a cursor can name descendant thread ids the server derived for
+ * this same card in an EARLIER subscription — added live via a tail parser's
+ * own `links` after the initial subscribe — that a fresh `resolveSources`
+ * call has no way to rediscover on its own (it only ever returns the card's
+ * own thread). Each such key is re-validated through the exact same
+ * fail-closed descendant chain a directly-requested card goes through; a
+ * forged or unrelated key is simply ignored, never trusted just because the
+ * client echoed it back.
+ */
+function seedCodexDescendantsFromCursor(
+  hub: SessionHub,
+  sub: TranscriptSubscription,
+  source: AgentTranscriptSourceKind,
+  cursor: AgentTranscriptCursor | undefined,
+  now: number,
+): void {
+  if (hub.owned.providerId !== "codex" || source.kind !== "card" || !cursor) return;
+  for (const key of Object.keys(cursor)) {
+    if (sub.files.has(key) || !CODEX_THREAD_ID_RE.test(key)) continue;
+    const ref = resolveCodexDescendantFile(hub.owned, key);
+    if (!ref) continue;
+    const size = statSizeSafe(ref.path) ?? 0;
+    const start = sanitizeOffset(cursor[key], size);
+    sub.files.set(key, createFileTailState(ref, start, now));
+  }
+}
+
+/** How long until the next tick: the live cadence while idle-but-still-catching-up
+ *  on a read-budget-truncated backlog, else the usual idle/live split. */
+function nextCadence(sub: TranscriptSubscription, now: number, hasMoreBacklog: boolean): number {
+  return now + (hasMoreBacklog || !isIdle(sub, now) ? LIVE_TICK_MS : IDLE_TICK_MS);
+}
+
+export function addTranscriptSubscription(
+  hub: SessionHub,
+  ws: AgentTranscriptWsLike,
+  subId: string,
+  source: AgentTranscriptSourceKind,
+  cursor: AgentTranscriptCursor | undefined,
+): SubscribeResult {
+  const resolved = resolveSources(hub.owned, source);
+  if (!Array.isArray(resolved)) return { ok: false, code: mapSourceErrorCode(resolved.code) };
+
+  const now = agentTranscriptClock.now();
+  const sub: TranscriptSubscription = { subId, source, files: new Map(), nextTickAt: now + LIVE_TICK_MS };
+  for (const ref of resolved) {
+    const size = statSizeSafe(ref.path) ?? 0;
+    const start = sanitizeOffset(cursor?.[ref.key], size);
+    sub.files.set(ref.key, createFileTailState(ref, start, now));
+  }
+  seedCodexDescendantsFromCursor(hub, sub, source, cursor, now);
+
+  // Registered in the hub BEFORE the first push, so a throw from that push
+  // (caught below and treated as a failed send) still leaves the subscription
+  // reachable for cleanup — never an entry the registry never learns about
+  // and no unsubscribe or disconnect path can then find.
+  let bySubId = hub.subscriptions.get(ws);
+  if (!bySubId) {
+    bySubId = new Map();
+    hub.subscriptions.set(ws, bySubId);
+  }
+  bySubId.set(subId, sub);
+  ensureTicker(hub);
+
+  const result = safePushUpdate(hub, ws, sub, now, true);
+  if (result.outcome === "error") {
+    // The subscription never reached the top-level registry (that happens
+    // only once this function returns `ok: true`), so undoing the hub-local
+    // registration here is enough — nothing else has learned about it yet.
+    bySubId.delete(subId);
+    stopTickerIfEmpty(hub);
+    console.warn(`[agent-transcript] hub=${hub.key} subId=${subId} subscribe-time read failed`);
+    return { ok: false, code: "bad_request" };
+  }
+  sub.nextTickAt = nextCadence(sub, now, result.hasMoreBacklog);
+  return { ok: true, sendFailed: result.outcome === "send-failed" };
+}
+
+/** Remove one subscription. Returns whether it existed. */
+export function removeTranscriptSubscription(hub: SessionHub, ws: AgentTranscriptWsLike, subId: string): boolean {
+  const bySubId = hub.subscriptions.get(ws);
+  if (!bySubId?.delete(subId)) return false;
+  if (bySubId.size === 0) hub.subscriptions.delete(ws);
+  stopTickerIfEmpty(hub);
+  return true;
+}
+
+/** Drop every transcript subscription a socket holds on this hub. Returns how many existed. */
+export function dropAllTranscriptForWs(hub: SessionHub, ws: AgentTranscriptWsLike): number {
+  const bySubId = hub.subscriptions.get(ws);
+  if (!bySubId) return 0;
+  hub.subscriptions.delete(ws);
+  stopTickerIfEmpty(hub);
+  return bySubId.size;
+}
+
+export function transcriptSubIdsForWs(hub: SessionHub, ws: AgentTranscriptWsLike): string[] {
+  return [...(hub.subscriptions.get(ws)?.keys() ?? [])];
+}
+
+function sendSubscriptionError(ws: AgentTranscriptWsLike, subId: string): void {
+  sendWsMessage(ws, { type: "agent-transcript:error", subId, code: "bad_request" } satisfies AgentTranscriptErrorMsg);
+}
+
+/**
+ * One 250ms wake: push only the subscriptions whose own cadence is due (live
+ * or idle-slowed).
+ *
+ * A thrown read/parse error is scoped to the ONE subscription that threw —
+ * logged once, reported to the client as a normal `agent-transcript:error`,
+ * and dropped — never treated like a dead socket. `erroredSubs` mirrors
+ * `failedClients`'s defer-to-after-the-loop pattern: `onSubscriptionError`
+ * mutates `hub.subscriptions` (via the registry's `unregisterTranscriptSub`),
+ * which must not happen while this function is still iterating that same map.
+ */
+export function tickTranscripts(hub: SessionHub): void {
+  const now = agentTranscriptClock.now();
+  const failedClients = new Set<AgentTranscriptWsLike>();
+  const erroredSubs: { ws: AgentTranscriptWsLike; subId: string }[] = [];
+
+  for (const [ws, bySubId] of hub.subscriptions) {
+    if (failedClients.has(ws)) continue;
+    if (!hub.tokenStillValid(ws)) {
+      failedClients.add(ws);
+      continue;
+    }
+    for (const [subId, sub] of bySubId) {
+      if (now < sub.nextTickAt) continue;
+      const result = safePushUpdate(hub, ws, sub, now, false);
+      if (result.outcome === "send-failed") {
+        failedClients.add(ws);
+        break;
+      }
+      if (result.outcome === "error") {
+        console.warn(`[agent-transcript] hub=${hub.key} subId=${subId} tick failed, dropping this subscription`);
+        sendSubscriptionError(ws, subId);
+        erroredSubs.push({ ws, subId });
+        continue;
+      }
+      sub.nextTickAt = nextCadence(sub, now, result.hasMoreBacklog);
+    }
+  }
+
+  for (const ws of failedClients) hub.onSendFailure(ws);
+  for (const { ws, subId } of erroredSubs) hub.onSubscriptionError(ws, subId);
+}

package/src/services/agent-transcript/agent-transcript-sources.ts

@@ -0,0 +1,199 @@
+/**
+ * Given an already-owned session (see session-ownership.ts) and a requested
+ * card or teammate, return the exact transcript file(s) the server may read —
+ * never a client-supplied path.
+ *
+ * Claude card: `groupSubagentsByCard` keyed by the card's `toolUseId`, root
+ * agent first then its nested descendants (already depth-ordered).
+ * Codex card: the named thread's own rollout, accepted only when its
+ * `session_meta.parent_thread_id` chain reaches the owning session — a
+ * grandchild discovered later via the tail parser's own `links` is re-checked
+ * through the exact same chain walk (`resolveCodexDescendantFile`) before the
+ * hub ever starts tailing it.
+ * Member: a teammate's newest transcript, `teamName` pinned to the project the
+ * same way a Claude session id is (a team IS a session, see
+ * `resolveTeamSubagentsDir`).
+ *
+ * Every returned path is realpath-contained under the Claude root or a Codex
+ * sessions dir. Results — hits and misses alike — are cached for 2s per
+ * (session, card/member) so a polling subscriber costs one dir scan per tick
+ * at most, not one per subscriber.
+ */
+
+import { join } from "node:path";
+import { getCachedSubagentGroups } from "./agent-transcript-index-cache.ts";
+import { resolveMemberTranscript } from "../team-member-activity/member-activity.service.ts";
+import { findRolloutByThreadId, isCodexRolloutPath, readSessionMeta } from "../../providers/codex-app-server/codex-history.ts";
+import { claudeProjectsRoot } from "./claude-projects-root.ts";
+import { SESSION_ID_RE, pinClaudeSessionDir, realpathContained, type OwnedSession } from "./session-ownership.ts";
+
+export type AgentTranscriptSource =
+  | { kind: "card"; cardId: string }
+  | { kind: "member"; teamName: string; memberName: string };
+
+export interface TranscriptFileRef {
+  key: string;
+  path: string;
+  provider: "claude" | "codex";
+}
+
+export type SourceErrorCode =
+  | "invalid_card_id"
+  | "card_not_found"
+  | "invalid_team_name"
+  | "invalid_member_name"
+  | "member_not_found"
+  | "not_descendant";
+
+export interface SourceError {
+  ok: false;
+  code: SourceErrorCode;
+}
+
+const CLAUDE_CARD_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const CODEX_CARD_ID_RE = /^subagent-([0-9a-f-]{36})$/;
+const MEMBER_NAME_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** Shape of a raw Codex thread id (a `TranscriptFileRef.key`, not a `subagent-<id>`
+ *  CARD id) — reused by the hub to recognize a descendant key in a cursor. */
+export const CODEX_THREAD_ID_RE = /^[0-9a-f-]{36}$/i;
+
+/** How far up a chain of spawned Codex threads a card id is chased before giving up. */
+const MAX_CHAIN_DEPTH = 8;
+
+const CACHE_TTL_MS = 2000;
+/** Bounds a client cycling through novel card ids (subscribe, unsubscribe, repeat)
+ *  from growing this map forever — expired entries are swept first, and only a
+ *  still-live entry is evicted (oldest insertion) if that alone isn't enough. */
+const MAX_CACHE_ENTRIES = 500;
+interface CacheEntry {
+  expiresAt: number;
+  result: TranscriptFileRef[] | SourceError;
+}
+const cache = new Map<string, CacheEntry>();
+
+function evictForCapacity(now: number): void {
+  if (cache.size < MAX_CACHE_ENTRIES) return;
+  for (const [key, entry] of cache) {
+    if (entry.expiresAt <= now) cache.delete(key);
+  }
+  while (cache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    if (oldest === undefined) break;
+    cache.delete(oldest);
+  }
+}
+
+function err(code: SourceErrorCode): SourceError {
+  return { ok: false, code };
+}
+
+function sourceCacheKey(sessionId: string, source: AgentTranscriptSource): string {
+  return source.kind === "card"
+    ? `${sessionId}\0card\0${source.cardId}`
+    : `${sessionId}\0member\0${source.teamName}\0${source.memberName}`;
+}
+
+function resolveClaudeCard(owned: OwnedSession, cardId: string): TranscriptFileRef[] | SourceError {
+  if (!CLAUDE_CARD_ID_RE.test(cardId)) return err("invalid_card_id");
+  const subagentsDir = join(owned.claude!.sessionDir, "subagents");
+  const group = getCachedSubagentGroups(subagentsDir).get(cardId);
+  if (!group) return err("card_not_found");
+  const root = claudeProjectsRoot();
+  const files: TranscriptFileRef[] = [];
+  for (const entry of group) {
+    const real = realpathContained(entry.transcriptPath, root);
+    if (real) files.push({ key: entry.agentId, path: real, provider: "claude" });
+  }
+  return files;
+}
+
+/** First rollout matching `threadId`, searched filename-first across every dir the owning session was found in. */
+function findCodexFile(dirs: string[], threadId: string, projectPath: string): string | null {
+  for (const dir of dirs) {
+    const file = findRolloutByThreadId(dir, threadId, projectPath);
+    if (file && isCodexRolloutPath(file)) return file;
+  }
+  return null;
+}
+
+/** Walk `session_meta.parent_thread_id` from `threadId` up to `sessionId`. One header read per hop. */
+export function isCodexDescendant(dirs: string[], threadId: string, sessionId: string, projectPath: string): boolean {
+  let cur = threadId;
+  const seen = new Set<string>();
+  for (let depth = 0; depth < MAX_CHAIN_DEPTH; depth++) {
+    if (seen.has(cur)) return false; // cyclic session_meta — corrupt, refuse
+    seen.add(cur);
+    const file = findCodexFile(dirs, cur, projectPath);
+    if (!file) return false;
+    const parent = readSessionMeta(file)?.parentThreadId;
+    if (!parent) return false;
+    if (parent === sessionId) return true;
+    cur = parent;
+  }
+  return false;
+}
+
+function resolveCodexCard(owned: OwnedSession, cardId: string): TranscriptFileRef[] | SourceError {
+  const m = CODEX_CARD_ID_RE.exec(cardId);
+  if (!m) return err("invalid_card_id");
+  const threadId = m[1]!;
+  const ref = resolveCodexDescendantFile(owned, threadId);
+  if (!ref) {
+    // Distinguish "no such rollout" from "found but not a descendant" the same
+    // way the pre-refactor inline checks did, so the wire error code is unchanged.
+    const file = findCodexFile(owned.codex!.dirs, threadId, owned.projectPath);
+    return file ? err("not_descendant") : err("card_not_found");
+  }
+  return [ref];
+}
+
+/**
+ * A Codex thread id → its transcript file, but only once the same fail-closed
+ * chain walk used for a directly-requested card also accepts it. The hub's
+ * live-discovery path (a tail parser's own `links`, surfacing a grandchild
+ * spawned after a subscription started) reuses this rather than re-deriving
+ * the check, so a nested thread can never bypass the descendant guard just
+ * because it arrived through a different door.
+ */
+export function resolveCodexDescendantFile(owned: OwnedSession, threadId: string): TranscriptFileRef | null {
+  const { dirs } = owned.codex!;
+  const file = findCodexFile(dirs, threadId, owned.projectPath);
+  if (!file) return null;
+  if (!isCodexDescendant(dirs, threadId, owned.sessionId, owned.projectPath)) return null;
+  return { key: threadId, path: file, provider: "codex" };
+}
+
+function resolveMember(owned: OwnedSession, teamName: string, memberName: string): TranscriptFileRef[] | SourceError {
+  if (!SESSION_ID_RE.test(teamName)) return err("invalid_team_name");
+  if (!MEMBER_NAME_RE.test(memberName)) return err("invalid_member_name");
+  // A team is itself a session (resolveTeamSubagentsDir → resolveSessionDir): pin it to the
+  // project the same way the primary session id is, before trusting anything it names.
+  if (!pinClaudeSessionDir(teamName, owned.projectPath)) return err("member_not_found");
+  const path = resolveMemberTranscript(teamName, memberName, owned.projectPath);
+  if (!path) return err("member_not_found");
+  const real = realpathContained(path, claudeProjectsRoot());
+  if (!real) return err("member_not_found");
+  return [{ key: memberName, path: real, provider: "claude" }];
+}
+
+function computeSources(owned: OwnedSession, source: AgentTranscriptSource): TranscriptFileRef[] | SourceError {
+  if (source.kind === "member") return resolveMember(owned, source.teamName, source.memberName);
+  return owned.providerId === "claude" ? resolveClaudeCard(owned, source.cardId) : resolveCodexCard(owned, source.cardId);
+}
+
+export function resolveSources(owned: OwnedSession, source: AgentTranscriptSource): TranscriptFileRef[] | SourceError {
+  const key = sourceCacheKey(owned.sessionId, source);
+  const now = Date.now();
+  const hit = cache.get(key);
+  if (hit && hit.expiresAt > now) return hit.result;
+  evictForCapacity(now);
+  const result = computeSources(owned, source);
+  cache.set(key, { expiresAt: now + CACHE_TTL_MS, result });
+  return result;
+}
+
+/** Test-only: clear the 2s resolve cache between cases. */
+export function _resetSourcesCache(): void { cache.clear(); }
+
+/** Test-only: current cache size, to assert the capacity bound holds. */
+export function _sourcesCacheSizeForTest(): number { return cache.size; }

package/src/services/agent-transcript/agent-transcript-ws-like.ts

@@ -0,0 +1,19 @@
+/**
+ * The slice of a `/ws/global` socket the hub needs. `send` returns a number on
+ * a real Bun `ServerWebSocket` (-1 backpressure, 0 dropped, >0 bytes sent) —
+ * the hub checks it after every push and drops the socket's subscriptions on
+ * 0 or a throw, never on -1 (that just means try again later).
+ */
+export interface AgentTranscriptWsLike {
+  send(data: string): number;
+  data?: { token?: string | null };
+}
+
+/** Send one JSON message; false on a dropped send (0) or a throw — never on backpressure (-1). */
+export function sendWsMessage(ws: AgentTranscriptWsLike, payload: unknown): boolean {
+  try {
+    return ws.send(JSON.stringify(payload)) !== 0;
+  } catch {
+    return false;
+  }
+}

package/src/services/agent-transcript/claude-projects-root.ts

@@ -0,0 +1,21 @@
+/**
+ * Where Claude Code writes per-project session transcripts
+ * (`<root>/<slug(projectPath)>/<sessionId>.jsonl`).
+ *
+ * Real home by default; overridable so session-ownership and transcript-source
+ * tests never read or write the user's actual `~/.claude/projects`.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+let override: string | null = null;
+
+export function claudeProjectsRoot(): string {
+  return override ?? join(homedir(), ".claude", "projects");
+}
+
+/** Test-only: point claudeProjectsRoot() at a scratch directory. Pass null to reset. */
+export function _setClaudeProjectsRoot(root: string | null): void {
+  override = root;
+}

package/src/services/agent-transcript/session-ownership.ts

@@ -0,0 +1,152 @@
+/**
+ * Prove a session belongs to the requesting project before any transcript file
+ * is named. Everything an Agent card window reads is derived from this result
+ * — never from a client-supplied path.
+ *
+ * Claude: the session's own JSONL must sit under `<claudeRoot>/<slug(projectPath)>/`.
+ * A session started outside PPM (no DB row) is accepted on that basis alone; the
+ * cross-project fallback (DB `project_path`, drive-letter/case drift) is used
+ * only when it independently names the SAME project the caller asked for.
+ *
+ * Codex: the root rollout must be found by `findRolloutByThreadId`, which is
+ * itself fail-closed on `cwd` — a rollout whose recorded cwd does not match
+ * `projectPath` is never returned. `dirsFn` is injectable so tests never touch
+ * the real `~/.codex`.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { getSessionProjectPath } from "../db.service.ts";
+import { codexSessionsDirs as realCodexSessionsDirs } from "../../providers/codex-app-server/codex-provider.ts";
+import { findRolloutByThreadId, isCodexRolloutPath } from "../../providers/codex-app-server/codex-history.ts";
+import { claudeProjectsRoot } from "./claude-projects-root.ts";
+
+export const SESSION_ID_RE = /^[A-Za-z0-9_-]{8,64}$/;
+
+export type OwnershipErrorCode =
+  | "invalid_session_id"
+  | "invalid_provider"
+  | "invalid_project"
+  | "session_not_found";
+
+export interface OwnershipError {
+  ok: false;
+  code: OwnershipErrorCode;
+}
+
+export interface OwnedSession {
+  ok: true;
+  providerId: "claude" | "codex";
+  sessionId: string;
+  projectPath: string;
+  /** Claude only: the session's own directory, `<claudeRoot>/<slug>/<sessionId>`. */
+  claude?: { sessionDir: string };
+  /** Codex only: where the root rollout was found, plus every dir it was searched in
+   *  (reused by agent-transcript-sources so a descendant lookup need not re-derive it). */
+  codex?: { path: string; sessionsDir: string; dirs: string[] };
+}
+
+export interface AssertSessionParams {
+  providerId: string;
+  sessionId: string;
+  projectPath: string;
+  /** Test-only: override which directories Codex rollouts are searched under. */
+  codexSessionsDirs?: (sessionId?: string) => string[];
+}
+
+/**
+ * Test-only fallback for callers that cannot pass `codexSessionsDirs` per
+ * call (the `/ws/global` hub never accepts a client-supplied directory list,
+ * by design) but still need Codex fixtures to live outside the real
+ * `~/.codex`. `codex-provider.ts`'s real `codexSessionsDirs` freezes
+ * `homedir()` into a module-level constant at import time, so patching
+ * `HOME`/`USERPROFILE` in a `beforeEach` has no effect on it once any test in
+ * the same process has already imported that module.
+ */
+let testCodexSessionsDirsOverride: ((sessionId?: string) => string[]) | null = null;
+
+export function _setCodexSessionsDirsForTest(fn: ((sessionId?: string) => string[]) | null): void {
+  testCodexSessionsDirsOverride = fn;
+}
+
+/** Absolute path normalized for cross-platform / case-insensitive (win32) comparison. */
+function normalizeProjectPath(p: string): string {
+  const r = resolve(p);
+  return process.platform === "win32" ? r.toLowerCase() : r;
+}
+
+/** Same encoding `resolveSessionDir` (subagent-transcript-merger.ts) uses. */
+function encodeClaudeSlug(projectPath: string): string {
+  return projectPath.replace(/[/\\:.]/g, "-");
+}
+
+function isWithin(child: string, root: string): boolean {
+  const c = process.platform === "win32" ? child.toLowerCase() : child;
+  const r = process.platform === "win32" ? root.toLowerCase() : root;
+  return c === r || c.startsWith(r + sep);
+}
+
+/** Realpath `path` and confirm it stays under `root`'s realpath. Null on any failure. */
+export function realpathContained(path: string, root: string): string | null {
+  try {
+    const real = realpathSync(path);
+    const realRoot = realpathSync(root);
+    return isWithin(real, realRoot) ? real : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pin a Claude session id to a project: its JSONL must sit directly under
+ * `<claudeRoot>/<slug(projectPath)>/`, or — only when the DB independently
+ * names the SAME project (drive-letter/case drift) — under the slug the DB
+ * recorded. Returns the session's own directory (sibling of the JSONL),
+ * realpath-contained under `claudeRoot`. Shared by the primary-session check
+ * and the `member` source's `teamName` (a team is itself a session id).
+ */
+export function pinClaudeSessionDir(sessionId: string, projectPath: string): string | null {
+  const root = claudeProjectsRoot();
+  let jsonlFile = join(root, encodeClaudeSlug(projectPath), `${sessionId}.jsonl`);
+  if (!existsSync(jsonlFile)) {
+    const recorded = getSessionProjectPath(sessionId);
+    if (!recorded || normalizeProjectPath(recorded) !== normalizeProjectPath(projectPath)) return null;
+    jsonlFile = join(root, encodeClaudeSlug(recorded), `${sessionId}.jsonl`);
+    if (!existsSync(jsonlFile)) return null;
+  }
+  const real = realpathContained(jsonlFile, root);
+  if (!real) return null;
+  // sessionId is regex-validated (no separators, no "..") so this join cannot escape the slug dir.
+  return join(dirname(real), sessionId);
+}
+
+function assertClaudeSession(sessionId: string, projectPath: string): OwnedSession | OwnershipError {
+  const sessionDir = pinClaudeSessionDir(sessionId, projectPath);
+  if (!sessionDir) return { ok: false, code: "session_not_found" };
+  return { ok: true, providerId: "claude", sessionId, projectPath, claude: { sessionDir } };
+}
+
+function assertCodexSession(
+  sessionId: string,
+  projectPath: string,
+  dirsFn: (sessionId?: string) => string[],
+): OwnedSession | OwnershipError {
+  const dirs = dirsFn(sessionId);
+  for (const dir of dirs) {
+    const file = findRolloutByThreadId(dir, sessionId, projectPath);
+    if (!file || !isCodexRolloutPath(file)) continue;
+    return { ok: true, providerId: "codex", sessionId, projectPath, codex: { path: file, sessionsDir: dir, dirs } };
+  }
+  return { ok: false, code: "session_not_found" };
+}
+
+export function assertSessionInProject(params: AssertSessionParams): OwnedSession | OwnershipError {
+  const { providerId, sessionId, projectPath } = params;
+  if (!SESSION_ID_RE.test(sessionId)) return { ok: false, code: "invalid_session_id" };
+  if (!projectPath) return { ok: false, code: "invalid_project" };
+  if (providerId === "claude") return assertClaudeSession(sessionId, projectPath);
+  if (providerId === "codex") {
+    return assertCodexSession(sessionId, projectPath, params.codexSessionsDirs ?? testCodexSessionsDirsOverride ?? realCodexSessionsDirs);
+  }
+  return { ok: false, code: "invalid_provider" };
+}

package/src/services/nested-subagent-spy.ts

@@ -28,7 +28,7 @@ import { closeSync, openSync, readSync, statSync } from "node:fs";
 import { join } from "node:path";
 import type { ChatEvent } from "../types/chat.ts";
 import { createAgentTranscriptLineParser } from "./subagent-transcript-merger.ts";
-import { groupSubagentsByCard } from "./team-member-activity/subagent-transcript-index.ts";
+import { getCachedSubagentGroups } from "./agent-transcript/agent-transcript-index-cache.ts";
 
 const POLL_INTERVAL_MS = 1000;
 /** Repeated per-file read failures (locked/replaced file) log once per this window. */
@@ -97,9 +97,9 @@ function warnThrottled(spy: SessionSpy, message: string): void {
 
 /** One poll for a session: scan the dir once, then drain each open card's nested tails. */
 function tick(spy: SessionSpy): void {
-  let groups: ReturnType<typeof groupSubagentsByCard>;
+  let groups: ReturnType<typeof getCachedSubagentGroups>;
   try {
-    groups = groupSubagentsByCard(spy.subagentsDir);
+    groups = getCachedSubagentGroups(spy.subagentsDir);
   } catch (e) {
     warnThrottled(spy, `scan failed: ${(e as Error).message}`);
     return;