@ai-devkit/agent-manager 0.26.2 → 0.26.4

package/src/adapters/AgentAdapter.ts

@@ -59,7 +59,7 @@ export interface ProcessInfo {
     /** Process ID */
     pid: number;
 
-    /** Parent process ID, populated by listAgentProcesses when available */
+    /** Parent process ID, populated by process discovery when available */
     ppid?: number;
 
     /** Process command */
@@ -71,7 +71,7 @@ export interface ProcessInfo {
     /** Terminal TTY (e.g., "ttys030") */
     tty: string;
 
-    /** Process start time, populated by enrichProcesses */
+    /** Process start time, populated by process enrichment */
     startTime?: Date;
 }
 
@@ -148,6 +148,11 @@ export interface ListSessionsOptions {
     type?: AgentType;
 }
 
+export interface AgentDetectionContext {
+    /** One enriched process snapshot shared across this manager refresh. */
+    readonly processes: readonly ProcessInfo[];
+}
+
 /**
  * Agent Adapter Interface
  *
@@ -157,11 +162,14 @@ export interface AgentAdapter {
     /** Type of agent this adapter handles */
     readonly type: AgentType;
 
+    /** Executable basenames required for shared process discovery. */
+    readonly processNames?: readonly string[];
+
     /**
      * Detect running agents of this type
      * @returns List of detected agents
      */
-    detectAgents(): Promise<AgentInfo[]>;
+    detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]>;
 
     /**
      * Check if this adapter can handle the given process

package/src/adapters/ClaudeCodeAdapter.ts

@@ -7,9 +7,10 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
 import { batchGetSessionFileBirthtimes, isDirectory, listJsonl, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
@@ -60,14 +61,15 @@ const PID_FILE_STALENESS_MS = 60000;
  * Claude Code Adapter
  *
  * Detects Claude Code agents by:
- * 1. Finding running claude processes via shared listAgentProcesses()
- * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 1. Filtering Claude processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
  * 3. Attempting authoritative PID-file matching via ~/.claude/sessions/<pid>.json
  * 4. Falling back to CWD+birthtime heuristic (matchProcessesToSessions) for processes without a PID file
  * 5. Extracting summary from last user message in session JSONL
  */
 export class ClaudeCodeAdapter implements AgentAdapter {
     readonly type = 'claude' as const;
+    readonly processNames = ['claude'] as const;
 
     private projectsDir: string;
     private sessionsDir: string;
@@ -85,13 +87,14 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     }
 
     private isClaudeExecutable(command: string): boolean {
-        const executable = command.trim().split(/\s+/)[0] || '';
-        const base = path.basename(executable).toLowerCase();
+        const base = executableBasename(command);
         return base === 'claude' || base === 'claude.exe';
     }
 
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(listAgentProcesses('claude'));
+    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));
         if (processes.length === 0) {
             return [];
         }

package/src/adapters/CodexAdapter.ts

@@ -2,8 +2,8 @@
  * Codex Adapter
  *
  * Detects running Codex agents by:
- * 1. Finding running codex processes via shared listAgentProcesses()
- * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 1. Filtering Codex processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
  * 3. Matching exact PID-to-session metadata from ~/.codex/ai-devkit/sessions.json
  * 4. Discovering session files from ~/.codex/sessions/YYYY/MM/DD/ via shared batchGetSessionFileBirthtimes()
  * 5. Setting resolvedCwd from session_meta first line
@@ -20,9 +20,10 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
 import { batchGetSessionFileBirthtimes, isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
@@ -88,6 +89,7 @@ interface MappingMatchResult {
 
 export class CodexAdapter implements AgentAdapter {
     readonly type = 'codex' as const;
+    readonly processNames = ['codex'] as const;
 
     private static readonly IDLE_THRESHOLD_MINUTES = 5;
     /** Include session files around process start day to recover long-lived processes. */
@@ -111,8 +113,10 @@ export class CodexAdapter implements AgentAdapter {
     /**
      * Detect running Codex agents
      */
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(listAgentProcesses('codex'));
+    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));
         if (processes.length === 0) return [];
 
         const { cachedAgents, remaining } = this.tryRegistryCache(processes);
@@ -657,8 +661,7 @@ export class CodexAdapter implements AgentAdapter {
     }
 
     private isCodexExecutable(command: string): boolean {
-        const executable = command.trim().split(/\s+/)[0] || '';
-        const base = path.basename(executable).toLowerCase();
+        const base = executableBasename(command);
         return base === 'codex' || base === 'codex.exe';
     }
 

package/src/adapters/CopilotAdapter.ts

@@ -2,8 +2,8 @@
  * Copilot Adapter
  *
  * Detects running GitHub Copilot CLI agents by:
- * 1. Finding running copilot processes via shared listAgentProcesses()
- * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 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
  * 5. Reading workspace.yaml as a flat fallback metadata source
@@ -17,9 +17,16 @@ import type {
     ListSessionsOptions,
     ProcessInfo,
     SessionSummary,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { enrichProcesses, findWrapperProcess, findWrapperProcessPids, listAgentProcesses } from '../utils/process.js';
+import {
+    captureProcessSnapshot,
+    executableBasename,
+    filterByProcessNames,
+    findWrapperProcess,
+    findWrapperProcessPids,
+} from '../utils/process.js';
 import { generateAgentName } from '../utils/matching.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import { AgentRegistry, type RegistryEntry } from '../utils/AgentRegistry.js';
@@ -89,6 +96,7 @@ interface CopilotEventSummary {
 
 export class CopilotAdapter implements AgentAdapter {
     readonly type = 'copilot' as const;
+    readonly processNames = ['copilot'] as const;
 
     private static readonly IDLE_THRESHOLD_MINUTES = 5;
     private static readonly VERBOSE_SYSTEM_EVENTS = new Set([
@@ -120,8 +128,10 @@ export class CopilotAdapter implements AgentAdapter {
         return this.isCopilotExecutable(processInfo.command);
     }
 
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(listAgentProcesses('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));
         if (processes.length === 0) return [];
 
         const processByPid = new Map(processes.map((proc) => [proc.pid, proc]));
@@ -457,8 +467,7 @@ export class CopilotAdapter implements AgentAdapter {
     }
 
     private isCopilotExecutable(command: string): boolean {
-        const executable = command.trim().split(/\s+/)[0] || '';
-        const base = path.basename(executable).toLowerCase();
+        const base = executableBasename(command);
         return base === 'copilot' || base === 'copilot.exe';
     }
 }

package/src/adapters/GeminiCliAdapter.ts

@@ -2,8 +2,8 @@
  * Gemini CLI Adapter
  *
  * Detects running Gemini CLI agents by:
- * 1. Finding running gemini processes via shared listAgentProcesses()
- * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 1. Filtering Gemini Node processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
  * 3. Discovering session files from ~/.gemini/tmp/<shortId>/chats/session-*.json
  * 4. Matching sessions to processes via shared matchProcessesToSessions()
  *    using sha256(cwd) === session.projectHash as the resolvedCwd source
@@ -20,9 +20,16 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses, findWrapperProcess, findWrapperProcessPids } from '../utils/process.js';
+import {
+    captureProcessSnapshot,
+    executableBasename,
+    filterByProcessNames,
+    findWrapperProcess,
+    findWrapperProcessPids,
+} from '../utils/process.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
@@ -81,6 +88,7 @@ interface GeminiSession {
 
 export class GeminiCliAdapter implements AgentAdapter {
     readonly type = 'gemini_cli' as const;
+    readonly processNames = ['node'] as const;
 
     private static readonly IDLE_THRESHOLD_MINUTES = 5;
     private static readonly SESSION_FILE_PREFIX = 'session-';
@@ -109,12 +117,13 @@ export class GeminiCliAdapter implements AgentAdapter {
      * binary). The primary running process is therefore the Node runtime
      * itself, and `ps aux` lists it as `node /path/to/gemini ...` with
      * argv[0] = `node`. We scan the Node process pool via the shared
-     * helper and keep only those whose command line references the gemini
+     * snapshot and keep only those whose command line references the gemini
      * executable or script via isGeminiExecutable().
      */
-    async detectAgents(): Promise<AgentInfo[]> {
-        const nodeProcesses = enrichProcesses(listAgentProcesses('node'));
-        const processes = nodeProcesses.filter((proc) => this.isGeminiExecutable(proc.command));
+    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));
         if (processes.length === 0) return [];
 
         const wrapperPids = findWrapperProcessPids(processes);
@@ -541,7 +550,7 @@ export class GeminiCliAdapter implements AgentAdapter {
         // other adapters' argv[0]-only check because the Node-script
         // distribution puts the real gemini path in argv[1..], not argv[0].
         for (const token of command.trim().split(/\s+/)) {
-            const base = path.basename(token).toLowerCase();
+            const base = executableBasename(token);
             if (base === 'gemini' || base === 'gemini.exe' || base === 'gemini.js') {
                 return true;
             }

package/src/adapters/GrokCliAdapter.ts

@@ -6,9 +6,10 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import { generateAgentName } from '../utils/matching.js';
 
@@ -16,7 +17,7 @@ import { generateAgentName } from '../utils/matching.js';
  * Grok Build CLI Adapter
  *
  * Detects running Grok Build CLI agents by:
- * 1. Finding running `grok` processes via shared listAgentProcesses() — Grok is
+ * 1. Filtering `grok` processes from a shared asynchronous snapshot — Grok is
  *    a native binary at ~/.grok/bin/grok, so argv[0] basename is `grok`.
  * 2. Resolving each live process to its working directory via
  *    ~/.grok/active_sessions.json, which Grok maintains as a list of
@@ -69,6 +70,7 @@ interface GrokSession {
 
 export class GrokCliAdapter implements AgentAdapter {
     readonly type = 'grok_cli' as const;
+    readonly processNames = ['grok'] as const;
 
     private base: string;
     private sessionsDir: string;
@@ -87,13 +89,14 @@ export class GrokCliAdapter implements AgentAdapter {
     }
 
     private isGrokExecutable(command: string): boolean {
-        const executable = command.trim().split(/\s+/)[0] || '';
-        const base = path.basename(executable).toLowerCase();
+        const base = executableBasename(command);
         return base === 'grok' || base === 'grok.exe';
     }
 
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(listAgentProcesses('grok'));
+    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));
         if (processes.length === 0) {
             return [];
         }

package/src/adapters/OpenCodeAdapter.ts

@@ -2,8 +2,8 @@
  * OpenCode Adapter
  *
  * Detects running OpenCode agents by:
- * 1. Finding running opencode processes via shared listAgentProcesses()
- * 2. Enriching with CWD and start times via shared enrichProcesses()
+ * 1. Filtering OpenCode processes from a shared asynchronous process snapshot
+ * 2. Using snapshot CWD and start-time enrichment
  * 3. Querying OpenCode's SQLite DB (~/.local/share/opencode/opencode.db) to
  *    find the session matching each process's CWD and read status from message.time.completed
  *
@@ -21,9 +21,10 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
 import { generateAgentName } from '../utils/matching.js';
 
 const SESSION_REF_SEP = '::';
@@ -55,6 +56,7 @@ interface OpenCodeSessionStats {
 
 export class OpenCodeAdapter implements AgentAdapter {
     readonly type = 'opencode' as const;
+    readonly processNames = ['opencode'] as const;
 
     private static readonly IDLE_THRESHOLD_MINUTES = 5;
 
@@ -84,13 +86,14 @@ export class OpenCodeAdapter implements AgentAdapter {
     }
 
     canHandle(processInfo: ProcessInfo): boolean {
-        const exe = (processInfo.command.trim().split(/\s+/)[0] || '').toLowerCase();
-        const base = path.basename(exe);
+        const base = executableBasename(processInfo.command);
         return base === 'opencode' || base === 'opencode.exe';
     }
 
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(listAgentProcesses('opencode'));
+    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));
         if (processes.length === 0) return [];
 
         const db = this.openDb();

package/src/adapters/PiAdapter.ts

@@ -17,9 +17,10 @@ import type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './AgentAdapter.js';
 import { AgentStatus } from './AgentAdapter.js';
-import { listAgentProcesses, enrichProcesses } from '../utils/process.js';
+import { captureProcessSnapshot, executableBasename, filterByProcessNames } from '../utils/process.js';
 import { isDirectory, safeReadFile, safeReaddir, safeStat } from '../utils/session.js';
 import type { SessionFile } from '../utils/session.js';
 import { matchProcessesToSessions, generateAgentName } from '../utils/matching.js';
@@ -66,6 +67,7 @@ interface TrackerAgentResult {
 
 export class PiAdapter implements AgentAdapter {
     readonly type = 'pi' as const;
+    readonly processNames = ['pi', 'node'] as const;
 
     private static readonly IDLE_THRESHOLD_MINUTES = 5;
 
@@ -86,8 +88,10 @@ export class PiAdapter implements AgentAdapter {
         return this.isPiExecutable(processInfo.command);
     }
 
-    async detectAgents(): Promise<AgentInfo[]> {
-        const processes = enrichProcesses(this.listPiProcesses());
+    async detectAgents(context?: AgentDetectionContext): Promise<AgentInfo[]> {
+        const snapshot = context?.processes ?? await captureProcessSnapshot(this.processNames);
+        const relevant = filterByProcessNames(snapshot, this.processNames);
+        const processes = this.listPiProcesses(relevant);
         if (processes.length === 0) return [];
 
         const { cachedAgents, remaining } = this.tryRegistryCache(processes);
@@ -149,12 +153,9 @@ export class PiAdapter implements AgentAdapter {
         return agents;
     }
 
-    private listPiProcesses(): ProcessInfo[] {
+    private listPiProcesses(snapshot: readonly ProcessInfo[]): ProcessInfo[] {
         const byPid = new Map<number, ProcessInfo>();
-        for (const proc of listAgentProcesses('pi')) {
-            if (this.canHandle(proc)) byPid.set(proc.pid, proc);
-        }
-        for (const proc of listAgentProcesses('node')) {
+        for (const proc of snapshot) {
             if (this.canHandle(proc)) byPid.set(proc.pid, proc);
         }
         return Array.from(byPid.values());
@@ -547,7 +548,7 @@ export class PiAdapter implements AgentAdapter {
 
     private isPiExecutable(command: string): boolean {
         for (const token of command.trim().split(/\s+/)) {
-            const base = path.basename(token).toLowerCase();
+            const base = executableBasename(token);
             if (base === 'pi' || base === 'pi.exe' || base === 'pi.js') return true;
         }
         return false;

package/src/adapters/index.ts

@@ -6,4 +6,4 @@ export { GrokCliAdapter } from './GrokCliAdapter.js';
 export { OpenCodeAdapter } from './OpenCodeAdapter.js';
 export { PiAdapter } from './PiAdapter.js';
 export { AgentStatus } from './AgentAdapter.js';
-export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo } from './AgentAdapter.js';
+export type { AgentAdapter, AgentType, AgentInfo, ProcessInfo, AgentDetectionContext } from './AgentAdapter.js';

package/src/database/connection.ts

@@ -8,7 +8,7 @@ export const DEFAULT_AGENT_REGISTRY_DB_PATH = join(homedir(), '.ai-devkit', 'age
 
 export interface DatabaseOptions {
     dbPath?: string;
-    verbose?: boolean;
+    verbose?: boolean | ((message: string) => void);
     readonly?: boolean;
 }
 
@@ -27,7 +27,9 @@ export class DatabaseConnection {
 
         this.db = new Database(this.dbPath, {
             readonly: options.readonly ?? false,
-            verbose: options.verbose ? console.log : undefined,
+            verbose: typeof options.verbose === 'function'
+                ? options.verbose
+                : options.verbose ? console.log : undefined,
         });
 
         this.configure();

package/src/index.ts

@@ -16,6 +16,7 @@ export type {
     ConversationMessage,
     SessionSummary,
     ListSessionsOptions,
+    AgentDetectionContext,
 } from './adapters/AgentAdapter.js';
 
 export { TerminalFocusManager, TerminalType } from './terminal/TerminalFocusManager.js';
@@ -23,11 +24,12 @@ export type { TerminalLocation } from './terminal/TerminalFocusManager.js';
 export { TtyWriter } from './terminal/TtyWriter.js';
 
 export { getProcessTty } from './utils/process.js';
+export { captureProcessSnapshot, executableBasename, filterByProcessNames } from './utils/process.js';
 export type { AgentSortKey } from './utils/sortAgents.js';
 export type { ListAgentsOptions } from './AgentManager.js';
 
 export { AgentRegistry, RenameNotFoundError, RenameConflictError } from './utils/AgentRegistry.js';
-export type { RegistryEntry } from './utils/AgentRegistry.js';
+export type { AgentRegistryOptions, RegistryEntry } from './utils/AgentRegistry.js';
 export { TmuxManager } from './terminal/TmuxManager.js';
 export { AGENTS } from './utils/agents.js';
 export type { AgentConfig, StartableAgentType } from './utils/agents.js';

package/src/utils/AgentRegistry.ts

@@ -44,14 +44,29 @@ interface RegistryRow {
 }
 
 const DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');
+const DEFAULT_PRUNE_INTERVAL_MS = 30_000;
 
 let defaultInstance: AgentRegistry | null = null;
 
+export interface AgentRegistryOptions {
+    now?: () => Date;
+    pruneIntervalMs?: number;
+    onDatabaseOperation?: (sql: string) => void;
+}
+
 export class AgentRegistry {
     private db: DatabaseConnection;
+    private readonly now: () => Date;
+    private readonly pruneIntervalMs: number;
+    private lastPrunedAt: number | undefined;
 
-    constructor(filePath: string = DEFAULT_REGISTRY_PATH) {
-        this.db = new DatabaseConnection({ dbPath: resolveAgentRegistryDbPath(filePath) });
+    constructor(filePath: string = DEFAULT_REGISTRY_PATH, options: AgentRegistryOptions = {}) {
+        this.now = options.now ?? (() => new Date());
+        this.pruneIntervalMs = options.pruneIntervalMs ?? DEFAULT_PRUNE_INTERVAL_MS;
+        this.db = new DatabaseConnection({
+            dbPath: resolveAgentRegistryDbPath(filePath),
+            verbose: options.onDatabaseOperation,
+        });
     }
 
     static default(): AgentRegistry {
@@ -101,6 +116,24 @@ export class AgentRegistry {
         return row ? this.rowToEntry(row) : undefined;
     }
 
+    private findPidConflicts(type: AgentType, pid: number): RegistryEntry[] {
+        return this.db.query<RegistryRow>(
+            'SELECT * FROM agents WHERE pid = ? AND type <> ?',
+            [pid, type],
+        ).map((row) => this.rowToEntry(row));
+    }
+
+    private entriesEqual(left: RegistryEntry, right: RegistryEntry): boolean {
+        return left.name === right.name
+            && left.type === right.type
+            && left.pid === right.pid
+            && left.tmuxSession === right.tmuxSession
+            && left.cwd === right.cwd
+            && left.startedAt === right.startedAt
+            && left.sessionId === right.sessionId
+            && left.sessionFilePath === right.sessionFilePath;
+    }
+
     private deleteNameConflict(name: string, type: AgentType, pid: number): void {
         const conflict = this.findByName(name);
         if (!conflict) return;
@@ -126,31 +159,66 @@ export class AgentRegistry {
                 session_id = excluded.session_id,
                 session_file_path = excluded.session_file_path,
                 updated_at = excluded.updated_at
-        `).run({ ...entry, updatedAt: new Date().toISOString() });
+        `).run({ ...entry, updatedAt: this.now().toISOString() });
     }
 
-    private save(entry: RegistryEntry): void {
-        this.deleteNameConflict(entry.name, entry.type, entry.pid);
-        this.insertOrUpdate(entry);
+    private needsWrite(incoming: RegistryEntry): boolean {
+        const existing = this.findByIdentity(incoming.type, incoming.pid);
+        const merged = this.mergeEntry(incoming, existing);
+        return !existing
+            || !this.entriesEqual(merged, existing)
+            || this.findPidConflicts(incoming.type, incoming.pid).length > 0;
+    }
+
+    private save(incoming: RegistryEntry): void {
+        const existing = this.findByIdentity(incoming.type, incoming.pid);
+        const merged = this.mergeEntry(incoming, existing);
+        const pidConflicts = this.findPidConflicts(incoming.type, incoming.pid);
+        if (existing && this.entriesEqual(merged, existing) && pidConflicts.length === 0) return;
+
+        for (const conflict of pidConflicts) {
+            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);
+        }
+        if (existing && this.entriesEqual(merged, existing)) return;
+
+        this.deleteNameConflict(merged.name, merged.type, merged.pid);
+        this.insertOrUpdate(merged);
     }
 
     isAlive(entry: RegistryEntry): boolean {
         try {
             process.kill(entry.pid, 0);
             return true;
-        } catch {
-            return false;
+        } catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? error.code
+                : undefined;
+            return code !== 'ESRCH';
         }
     }
 
-    prune(): void {
+    private pruneAt(nowMs: number): void {
         const entries = this.list();
         const stale = entries.filter((e) => !this.isAlive(e));
-        this.db.transaction(() => {
-            for (const entry of stale) {
-                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);
-            }
-        });
+        if (stale.length > 0) {
+            this.db.transaction(() => {
+                for (const entry of stale) {
+                    this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);
+                }
+            });
+        }
+        this.lastPrunedAt = nowMs;
+    }
+
+    prune(): void {
+        this.pruneAt(this.now().getTime());
+    }
+
+    pruneIfDue(): void {
+        const nowMs = this.now().getTime();
+        const elapsed = this.lastPrunedAt === undefined ? undefined : nowMs - this.lastPrunedAt;
+        if (elapsed !== undefined && elapsed >= 0 && elapsed < this.pruneIntervalMs) return;
+        this.pruneAt(nowMs);
     }
 
     register(entry: RegistryEntry): void {
@@ -159,10 +227,10 @@ export class AgentRegistry {
 
     registerBatch(entries: RegistryEntry[]): void {
         if (entries.length === 0) return;
+        if (!entries.some((entry) => this.needsWrite(entry))) return;
         this.db.transaction(() => {
             for (const incoming of entries) {
-                const existing = this.findByIdentity(incoming.type, incoming.pid);
-                this.save(this.mergeEntry(incoming, existing));
+                this.save(incoming);
             }
         });
     }
@@ -183,7 +251,7 @@ export class AgentRegistry {
             }
             this.db.execute(
                 'UPDATE agents SET name = ?, updated_at = ? WHERE type = ? AND pid = ?',
-                [newName, new Date().toISOString(), existing.type, existing.pid],
+                [newName, this.now().toISOString(), existing.type, existing.pid],
             );
         });
     }

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { listAgentProcesses, batchGetProcessCwds, batchGetProcessStartTimes, enrichProcesses } from './process.js';
+export { listAgentProcesses, batchGetProcessCwds, batchGetProcessStartTimes, enrichProcesses, captureProcessSnapshot } from './process.js';
 export { getProcessTty } from './process.js';
 export { batchGetSessionFileBirthtimes } from './session.js';
 export type { SessionFile } from './session.js';