@ai-devkit/agent-manager 0.35.0 → 0.37.0

package/src/{providers → harnesses}/codex/CodexSessionParser.ts

@@ -1,7 +1,19 @@
 import * as fs from "fs";
-import type { ConversationMessage, SessionSummary } from "../../adapters/AgentAdapter.js";
+import type {
+  ConversationMessage,
+  ConversationOptions,
+  SessionSummary,
+} from "../../adapters/AgentAdapter.js";
 import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { JsonlTailReader, normalizeTail, type JsonlTailSource } from "../../utils/jsonlTail.js";
 import { safeReadFile, safeStat } from "../../utils/session.js";
+import {
+  IncrementalJsonlSummary,
+  reduceJsonlContent,
+  type JsonlSummaryBounds,
+  type JsonlSummaryReducer,
+} from "../../utils/IncrementalJsonlSummary.js";
+import { isIdle, parseTimestamp, SUMMARY_MAX_LENGTH, truncate } from "../shared.js";
 
 export interface CodexEventEntry {
   timestamp?: string;
@@ -41,9 +53,43 @@ export interface CodexSession {
   lastPayloadType?: string;
 }
 
-const IDLE_THRESHOLD_MINUTES = 5;
+/** O(1) running summary folded from session entries; `toSession` builds a `CodexSession`. */
+interface CodexSummaryState {
+  seenFirstLine: boolean;
+  /** Set only when the first line is a valid `session_meta` entry. */
+  meta?: { id: string; cwd?: string; timestamp?: string };
+  lastEntryTimestamp?: string;
+  lastPayloadType?: string;
+  /** Truncated text of the last entry with displayable content. */
+  summary?: string;
+}
+
+/** A candidate conversation message plus what is needed to de-duplicate mirrors. */
+interface CodexConversationItem {
+  entryType?: string;
+  mirrorKey: string | null;
+  message: ConversationMessage;
+}
+
+const MIRROR_OVERSCAN = 8;
+
+export interface CodexSessionParserOptions {
+  /** Cold-start scan bounds for `readSessionIncremental` (see IncrementalJsonlSummary). */
+  summaryBounds?: JsonlSummaryBounds | false;
+}
 
 export class CodexSessionParser {
+  /** Incremental reader backing `getConversation({ tail })`. */
+  private readonly tailReader = new JsonlTailReader();
+
+  private readonly sessionCache: IncrementalJsonlSummary<CodexSummaryState>;
+
+  constructor(options: CodexSessionParserOptions = {}) {
+    this.sessionCache = new IncrementalJsonlSummary(this.summaryReducer, {
+      bounds: options.summaryBounds,
+    });
+  }
+
   readSession(filePath: string, cachedContent?: string): CodexSession | null {
     let content: string;
     if (cachedContent !== undefined) {
@@ -56,53 +102,93 @@ export class CodexSessionParser {
       }
     }
 
-    const allLines = content.trim().split("\n");
-    if (!allLines[0]) return null;
+    return this.toSession(
+      reduceJsonlContent(this.summaryReducer, content),
+      () => fs.statSync(filePath).mtime,
+    );
+  }
 
-    let metaEntry: CodexEventEntry;
-    try {
-      metaEntry = JSON.parse(allLines[0]);
-    } catch {
-      return null;
-    }
+  /**
+   * Same result as `readSession`, but backed by a per-instance incremental
+   * cache so repeated refreshes only parse bytes appended since the last call.
+   * Call `pruneSessionCache()` once per refresh to evict files no longer read.
+   *
+   * The first read of a large transcript is a bounded head + tail scan (see
+   * `summaryReducer.skip`); fields whose entries lie only in the skipped
+   * middle fall back to their defaults instead of forcing a full parse.
+   */
+  readSessionIncremental(filePath: string): CodexSession | null {
+    const result = this.sessionCache.read(filePath);
+    return result ? this.toSession(result.state, () => result.mtime) : null;
+  }
 
-    if (metaEntry.type !== "session_meta" || !metaEntry.payload?.id) {
-      return null;
-    }
+  /** Evict cached summaries for files not read since the previous prune. */
+  pruneSessionCache(): void {
+    this.sessionCache.prune();
+  }
 
-    const entries: CodexEventEntry[] = [];
-    for (const line of allLines) {
-      try {
-        entries.push(JSON.parse(line));
-      } catch {
-        continue;
+  /**
+   * Fold one JSONL entry into the O(1) session summary. The first line must
+   * be a `session_meta` entry; the rest track the last typed entry and the
+   * last entry with displayable text.
+   *
+   * `skip` (bounded cold start) keeps the head's `session_meta` and clears the
+   * "latest" fields, so those come from the tail only. Without a typed tail
+   * entry lastActive falls back to the meta timestamp, then the file mtime;
+   * without tail text the summary is the "Codex session active" default. A
+   * `session_meta` line longer than the head window yields no session (null).
+   */
+  private readonly summaryReducer: JsonlSummaryReducer<CodexSummaryState> = {
+    initial: () => ({ seenFirstLine: false }),
+    reduce: (state, value) => {
+      const entry = value && typeof value === "object" ? (value as CodexEventEntry) : undefined;
+      const next: CodexSummaryState = { ...state, seenFirstLine: true };
+
+      if (!state.seenFirstLine) {
+        if (entry?.type === "session_meta" && entry.payload?.id) {
+          next.meta = {
+            id: entry.payload.id,
+            cwd: entry.payload.cwd,
+            timestamp: entry.payload.timestamp,
+          };
+        }
+      }
+      // Without a leading session_meta the file is not a Codex session; skip the work
+      if (!entry || !next.meta) return next;
+
+      if (typeof entry.type === "string") {
+        next.lastEntryTimestamp = entry.timestamp;
+        next.lastPayloadType = this.normalizedPayloadType(entry);
       }
-    }
 
-    const lastEntry = this.findLastEventEntry(entries);
-    const lastPayloadType = lastEntry ? this.normalizedPayloadType(lastEntry) : undefined;
+      const text = this.extractEntryText(entry);
+      if (text) next.summary = truncate(text, SUMMARY_MAX_LENGTH);
+
+      return next;
+    },
+    skip: (state) => ({ seenFirstLine: true, meta: state.meta }),
+  };
+
+  private toSession(state: CodexSummaryState, fileMtime: () => Date): CodexSession | null {
+    const meta = state.meta;
+    if (!meta) return null;
 
     const lastActive =
-      this.parseTimestamp(lastEntry?.timestamp) ||
-      this.parseTimestamp(metaEntry.payload.timestamp) ||
-      fs.statSync(filePath).mtime;
-    const sessionStart = this.parseTimestamp(metaEntry.payload.timestamp) || lastActive;
+      parseTimestamp(state.lastEntryTimestamp) || parseTimestamp(meta.timestamp) || fileMtime();
+    const sessionStart = parseTimestamp(meta.timestamp) || lastActive;
 
     return {
-      sessionId: metaEntry.payload.id,
-      projectPath: metaEntry.payload.cwd || "",
-      summary: this.extractSummary(entries),
+      sessionId: meta.id,
+      projectPath: meta.cwd || "",
+      summary: state.summary ?? "Codex session active",
       sessionStart,
       lastActive,
-      lastPayloadType,
+      lastPayloadType: state.lastPayloadType,
     };
   }
 
   determineStatus(session: CodexSession): AgentStatus {
-    const diffMs = Date.now() - session.lastActive.getTime();
-    const diffMinutes = diffMs / 60000;
-
-    if (diffMinutes > IDLE_THRESHOLD_MINUTES) {
+    if (isIdle(session.lastActive)) {
       return AgentStatus.IDLE;
     }
 
@@ -117,45 +203,66 @@ export class CodexSessionParser {
     return AgentStatus.RUNNING;
   }
 
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
     const verbose = options?.verbose ?? false;
+    const source: JsonlTailSource<CodexConversationItem> = {
+      parseLine: (line) => this.lineToConversationItem(line, verbose),
+      finalize: (items) => this.dedupeMirroredMessages(items),
+    };
+
+    const tail = normalizeTail(options?.tail);
+    if (tail !== undefined) {
+      // Mirrored pairs sit next to each other, so a few extra messages of
+      // look-behind keep de-duplication exact for the returned tail.
+      return this.tailReader.read(sessionFilePath, tail, source, String(verbose), MIRROR_OVERSCAN);
+    }
 
     const content = safeReadFile(sessionFilePath);
     if (content === undefined) return [];
 
-    const lines = content.trim().split("\n");
-    const entries: CodexEventEntry[] = [];
-    const messages: ConversationMessage[] = [];
-
-    for (const line of lines) {
-      try {
-        entries.push(JSON.parse(line));
-      } catch {
-        continue;
-      }
+    const items: CodexConversationItem[] = [];
+    for (const line of content.trim().split("\n")) {
+      const item = source.parseLine(line);
+      if (item) items.push(item);
     }
 
-    const responseItemMirrorKeys = new Set<string>();
-    for (const entry of entries) {
-      if (entry.type !== "response_item") continue;
+    return this.dedupeMirroredMessages(items);
+  }
 
-      const message = this.toConversationMessage(entry, verbose);
-      const mirrorKey = message ? this.mirroredMessageKey(entry, message) : null;
-      if (mirrorKey) responseItemMirrorKeys.add(mirrorKey);
+  private lineToConversationItem(line: string, verbose: boolean): CodexConversationItem | null {
+    let entry: CodexEventEntry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return null;
     }
 
-    for (const entry of entries) {
-      const message = this.toConversationMessage(entry, verbose);
-      if (!message) continue;
+    const message = this.toConversationMessage(entry, verbose);
+    if (!message) return null;
 
-      const mirrorKey = this.mirroredMessageKey(entry, message);
-      if (entry.type === "event_msg" && mirrorKey && responseItemMirrorKeys.has(mirrorKey)) {
-        continue;
-      }
+    return { entryType: entry.type, mirrorKey: this.mirroredMessageKey(entry, message), message };
+  }
 
-      messages.push(message);
+  /** Drop event_msg messages mirrored by a response_item with the same turn/role/content. */
+  private dedupeMirroredMessages(items: CodexConversationItem[]): ConversationMessage[] {
+    const responseItemMirrorKeys = new Set<string>();
+    for (const item of items) {
+      if (item.entryType === "response_item" && item.mirrorKey) {
+        responseItemMirrorKeys.add(item.mirrorKey);
+      }
     }
 
+    const messages: ConversationMessage[] = [];
+    for (const item of items) {
+      if (
+        item.entryType === "event_msg" &&
+        item.mirrorKey &&
+        responseItemMirrorKeys.has(item.mirrorKey)
+      ) {
+        continue;
+      }
+      messages.push(item.message);
+    }
     return messages;
   }
 
@@ -188,7 +295,7 @@ export class CodexSessionParser {
         continue;
       }
 
-      const ts = this.parseTimestamp(entry.timestamp);
+      const ts = parseTimestamp(entry.timestamp);
       if (ts) lastTimestamp = ts;
 
       if (!firstUserMessage) {
@@ -207,7 +314,7 @@ export class CodexSessionParser {
     const stat = safeStat(filePath);
 
     const startedAt =
-      this.parseTimestamp(metaEntry.payload.timestamp) ||
+      parseTimestamp(metaEntry.payload.timestamp) ||
       lastTimestamp ||
       stat?.birthtime ||
       stat?.mtime ||
@@ -225,41 +332,16 @@ export class CodexSessionParser {
     };
   }
 
-  parseTimestamp(value?: string): Date | null {
-    if (!value) return null;
-    const timestamp = new Date(value);
-    return Number.isNaN(timestamp.getTime()) ? null : timestamp;
-  }
-
   parseMetaTimestampMs(value?: string): number | null {
     if (typeof value !== "string") return null;
 
-    const timestamp = this.parseTimestamp(value);
+    const timestamp = parseTimestamp(value);
     if (!timestamp) return null;
 
     const timestampMs = timestamp.getTime();
     return Number.isFinite(timestampMs) ? timestampMs : null;
   }
 
-  private findLastEventEntry(entries: CodexEventEntry[]): CodexEventEntry | undefined {
-    for (let i = entries.length - 1; i >= 0; i--) {
-      const entry = entries[i];
-      if (entry && typeof entry.type === "string") {
-        return entry;
-      }
-    }
-    return undefined;
-  }
-
-  private extractSummary(entries: CodexEventEntry[]): string {
-    for (let i = entries.length - 1; i >= 0; i--) {
-      const message = this.extractEntryText(entries[i]);
-      if (message) return this.truncate(message, 120);
-    }
-
-    return "Codex session active";
-  }
-
   private normalizedPayloadType(entry: CodexEventEntry): string | undefined {
     const payloadType = entry.payload?.type;
 
@@ -291,11 +373,6 @@ export class CodexSessionParser {
     return conversationMessage?.content.trim() ?? "";
   }
 
-  private truncate(value: string, maxLength: number): string {
-    if (value.length <= maxLength) return value;
-    return `${value.slice(0, maxLength - 3)}...`;
-  }
-
   private toConversationMessage(
     entry: CodexEventEntry,
     verbose: boolean,

package/src/{providers → harnesses}/copilot/CopilotAdapter.ts

@@ -5,7 +5,10 @@
  * 1. Filtering Copilot processes from a shared asynchronous process snapshot
  * 2. Using snapshot CWD and start-time enrichment
  * 3. Mapping active ~/.copilot/session-state/{sessionId}/inuse.{pid}.lock files to processes
- * 4. Reading events.jsonl as the primary session/conversation source
+ *    (only directories modified since the process started are listed, and a
+ *    known lock is re-validated with one stat on later refreshes)
+ * 4. Reading events.jsonl as the primary session/conversation source (incrementally
+ *    cached across refreshes, so unchanged files are not re-read)
  * 5. Reading workspace.yaml as a flat fallback metadata source
  */
 
@@ -14,22 +17,18 @@ import type {
   AgentAdapter,
   AgentInfo,
   ConversationMessage,
+  ConversationOptions,
   ListSessionsOptions,
   ProcessInfo,
   SessionSummary,
   AgentDetectionContext,
 } from "../../adapters/AgentAdapter.js";
-import {
-  captureProcessSnapshot,
-  executableBasename,
-  filterByProcessNames,
-  findWrapperProcess,
-  findWrapperProcessPids,
-} from "../../utils/process.js";
+import { findWrapperProcess, findWrapperProcessPids } from "../../utils/process.js";
 import { AgentRegistry, type RegistryEntry } from "../../utils/AgentRegistry.js";
 import { CopilotAgentMapper } from "./CopilotAgentMapper.js";
 import { CopilotSessionLocator } from "./CopilotSessionLocator.js";
 import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
+import { findHarnessProcesses, homeDir, matchesExecutable } from "../shared.js";
 
 export interface CopilotAdapterOptions {
   sessionStateDir?: string;
@@ -48,23 +47,29 @@ export class CopilotAdapter implements AgentAdapter {
     registry: AgentRegistry = AgentRegistry.default(),
     options: CopilotAdapterOptions = {},
   ) {
-    const homeDir = process.env.HOME || process.env.USERPROFILE || "";
     this.registry = registry;
     this.parser = new CopilotSessionParser();
     this.mapper = new CopilotAgentMapper(this.parser);
     this.locator = new CopilotSessionLocator({
-      sessionStateDir: options.sessionStateDir ?? path.join(homeDir, ".copilot", "session-state"),
+      sessionStateDir: options.sessionStateDir ?? path.join(homeDir(), ".copilot", "session-state"),
     });
   }
 
   canHandle(processInfo: ProcessInfo): boolean {
-    return this.isCopilotExecutable(processInfo.command);
+    return matchesExecutable(processInfo.command, "copilot");
   }
 
   async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
-    const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
-    const relevant = filterByProcessNames(snapshot, this.processNames);
-    const processes = relevant.filter((process) => this.canHandle(process));
+    try {
+      return await this.detectRunningAgents(context);
+    } finally {
+      // Drop cached event summaries for sessions that were not part of this refresh
+      this.parser.pruneSessionCache();
+    }
+  }
+
+  private async detectRunningAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+    const { processes } = await findHarnessProcesses(this, context);
     if (processes.length === 0) return [];
 
     const processByPid = new Map(processes.map((proc) => [proc.pid, proc]));
@@ -73,11 +78,11 @@ export class CopilotAdapter implements AgentAdapter {
     const matchedProcesses: ProcessInfo[] = [];
     const agents: AgentInfo[] = [];
 
-    for (const lock of this.locator.discoverActiveLocks()) {
+    for (const lock of this.locator.discoverActiveLocks(processes)) {
       const proc = processByPid.get(lock.pid);
       if (!proc) continue;
 
-      const session = this.parser.readSessionDir(lock.sessionDir, lock.sessionId);
+      const session = this.parser.readSessionDirIncremental(lock.sessionDir, lock.sessionId);
       if (!session) continue;
 
       const agent = this.mapper.mapSessionToAgent(session, proc);
@@ -99,7 +104,7 @@ export class CopilotAdapter implements AgentAdapter {
     return agents;
   }
 
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
     return this.parser.getConversation(sessionFilePath, options);
   }
 
@@ -153,9 +158,4 @@ export class CopilotAdapter implements AgentAdapter {
       agent.name = wrapperEntry.name;
     }
   }
-
-  private isCopilotExecutable(command: string): boolean {
-    const base = executableBasename(command);
-    return base === "copilot" || base === "copilot.exe";
-  }
 }

package/src/{providers → harnesses}/copilot/CopilotAgentMapper.ts

@@ -1,7 +1,7 @@
 import type { AgentInfo, ProcessInfo } from "../../adapters/AgentAdapter.js";
-import { AgentStatus } from "../../adapters/AgentAdapter.js";
 import { generateAgentName } from "../../utils/matching.js";
 import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
+import { processOnlyAgent } from "../shared.js";
 
 export class CopilotAgentMapper {
   constructor(private readonly parser: CopilotSessionParser = new CopilotSessionParser()) {}
@@ -22,15 +22,6 @@ export class CopilotAgentMapper {
   }
 
   mapProcessOnlyAgent(processInfo: ProcessInfo): AgentInfo {
-    return {
-      name: generateAgentName(processInfo.cwd || "", processInfo.pid),
-      type: "copilot",
-      status: AgentStatus.RUNNING,
-      summary: "Copilot process running",
-      pid: processInfo.pid,
-      projectPath: processInfo.cwd || "",
-      sessionId: `pid-${processInfo.pid}`,
-      lastActive: new Date(),
-    };
+    return processOnlyAgent("copilot", processInfo, { summary: "Copilot process running" });
   }
 }

package/src/harnesses/copilot/CopilotSessionLocator.ts

@@ -0,0 +1,161 @@
+import * as path from "path";
+import { isDirectory, isSafePathSegment, safeReaddir, safeStat } from "../../utils/session.js";
+import { homeDir } from "../shared.js";
+
+export interface CopilotLock {
+  sessionDir: string;
+  sessionId: string;
+  pid: number;
+}
+
+export interface CopilotSessionDir {
+  sessionDir: string;
+  sessionId: string;
+}
+
+/** A live Copilot process whose `inuse.<pid>.lock` file should be located. */
+export interface CopilotLockProcess {
+  pid: number;
+  startTime?: Date;
+}
+
+export interface CopilotSessionLocatorOptions {
+  sessionStateDir?: string;
+}
+
+interface KnownLock extends CopilotSessionDir {
+  startTimeMs: number;
+}
+
+/**
+ * Tolerance between a reported process start time and its lock directory's
+ * mtime: `ps lstart` has 1 s resolution, Linux start times derive from an
+ * estimated boot time, and some filesystems store coarse mtimes.
+ */
+const START_TIME_SLACK_MS = 5 * 60 * 1000;
+
+const LOCK_FILE_PATTERN = /^inuse\.(\d+)\.lock$/;
+
+export class CopilotSessionLocator {
+  private readonly sessionStateDir: string;
+  /** Lock location per PID, trusted only while that PID's start time is unchanged. */
+  private readonly knownLocks = new Map<number, KnownLock>();
+
+  constructor(options: CopilotSessionLocatorOptions = {}) {
+    this.sessionStateDir =
+      options.sessionStateDir ?? path.join(homeDir(), ".copilot", "session-state");
+  }
+
+  listSessionDirs(): CopilotSessionDir[] {
+    if (!isDirectory(this.sessionStateDir)) return [];
+
+    const sessionDirs: CopilotSessionDir[] = [];
+    for (const sessionId of safeReaddir(this.sessionStateDir)) {
+      const sessionDir = path.join(this.sessionStateDir, sessionId);
+      if (!isDirectory(sessionDir)) continue;
+
+      sessionDirs.push({ sessionDir, sessionId });
+    }
+
+    return sessionDirs;
+  }
+
+  findSessionDirById(sessionId: string): CopilotSessionDir | null {
+    if (!isSafePathSegment(sessionId)) return null;
+    const sessionDir = path.join(this.sessionStateDir, sessionId);
+    return isDirectory(sessionDir) ? { sessionDir, sessionId } : null;
+  }
+
+  /**
+   * Find `inuse.<pid>.lock` files.
+   *
+   * Without `processes`, every session directory is scanned and all locks are
+   * returned. With `processes`, only locks of those PIDs are returned and the
+   * search is bounded:
+   * - a lock found earlier for the same (pid, startTime) is re-validated with
+   *   a single `stat` (a reused PID has a different start time and misses);
+   * - otherwise only session directories whose mtime is at or after the
+   *   earliest unresolved process start time (minus slack) are listed, since
+   *   creating the lock file bumps its directory's mtime;
+   * - if an unresolved process has no start time, every directory is listed.
+   */
+  discoverActiveLocks(processes?: readonly CopilotLockProcess[]): CopilotLock[] {
+    if (!processes) {
+      return this.scanLocks(undefined, () => true);
+    }
+
+    const startTimes = new Map(processes.map((proc) => [proc.pid, proc.startTime?.getTime()]));
+    for (const [pid, known] of this.knownLocks) {
+      if (startTimes.get(pid) !== known.startTimeMs) {
+        this.knownLocks.delete(pid);
+      }
+    }
+
+    const locks: CopilotLock[] = [];
+    const unresolved = new Set<number>();
+    for (const pid of startTimes.keys()) {
+      const known = this.knownLocks.get(pid);
+      if (known && safeStat(path.join(known.sessionDir, lockFileName(pid)))?.isFile()) {
+        locks.push({ sessionDir: known.sessionDir, sessionId: known.sessionId, pid });
+        continue;
+      }
+      this.knownLocks.delete(pid);
+      unresolved.add(pid);
+    }
+    if (unresolved.size === 0) return locks;
+
+    const unresolvedStarts = [...unresolved].map((pid) => startTimes.get(pid));
+    const minMtimeMs = unresolvedStarts.every((start): start is number => start !== undefined)
+      ? Math.min(...unresolvedStarts) - START_TIME_SLACK_MS
+      : undefined;
+
+    const found = this.scanLocks(minMtimeMs, (pid) => unresolved.has(pid));
+
+    const lockCounts = new Map<number, number>();
+    for (const lock of found) {
+      lockCounts.set(lock.pid, (lockCounts.get(lock.pid) ?? 0) + 1);
+    }
+    for (const lock of found) {
+      const startTimeMs = startTimes.get(lock.pid);
+      // Only remember unambiguous locks of processes with a known start time
+      if (startTimeMs !== undefined && lockCounts.get(lock.pid) === 1) {
+        this.knownLocks.set(lock.pid, {
+          sessionDir: lock.sessionDir,
+          sessionId: lock.sessionId,
+          startTimeMs,
+        });
+      }
+    }
+
+    return locks.concat(found);
+  }
+
+  /** List lock files in session directories with mtime >= `minMtimeMs` (all when undefined). */
+  private scanLocks(
+    minMtimeMs: number | undefined,
+    includePid: (pid: number) => boolean,
+  ): CopilotLock[] {
+    const locks: CopilotLock[] = [];
+    for (const sessionId of safeReaddir(this.sessionStateDir)) {
+      const sessionDir = path.join(this.sessionStateDir, sessionId);
+      const stat = safeStat(sessionDir);
+      if (!stat?.isDirectory()) continue;
+      if (minMtimeMs !== undefined && stat.mtimeMs < minMtimeMs) continue;
+
+      for (const entry of safeReaddir(sessionDir)) {
+        const match = entry.match(LOCK_FILE_PATTERN);
+        if (!match) continue;
+
+        const pid = Number.parseInt(match[1], 10);
+        if (!Number.isFinite(pid) || !includePid(pid)) continue;
+        locks.push({ sessionDir, sessionId, pid });
+      }
+    }
+
+    return locks;
+  }
+}
+
+function lockFileName(pid: number): string {
+  return `inuse.${pid}.lock`;
+}