@ai-devkit/agent-manager 0.26.3 → 0.26.4

package/dist/utils/AgentRegistry.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/AgentRegistry.ts"],"sourcesContent":["import os from 'os';\nimport path from 'path';\nimport type { AgentType } from '../adapters/AgentAdapter.js';\nimport {\n    DatabaseConnection,\n    resolveAgentRegistryDbPath,\n} from '../database/index.js';\n\nexport class RenameNotFoundError extends Error {\n    constructor(public agentName: string) {\n        super(`Agent \"${agentName}\" not found in registry.`);\n        this.name = 'RenameNotFoundError';\n    }\n}\n\nexport class RenameConflictError extends Error {\n    constructor(public agentName: string) {\n        super(`Agent \"${agentName}\" is already in use.`);\n        this.name = 'RenameConflictError';\n    }\n}\n\nexport interface RegistryEntry {\n    name: string;\n    type: AgentType;\n    pid: number;\n    tmuxSession: string;\n    cwd: string;\n    startedAt: string;  // ISO 8601\n    sessionId: string;\n    sessionFilePath: string;\n}\n\ninterface RegistryRow {\n    name: string;\n    type: AgentType;\n    pid: number;\n    tmux_session: string;\n    cwd: string;\n    started_at: string;\n    session_id: string;\n    session_file_path: string;\n    updated_at: string;\n}\n\nconst DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');\n\nlet defaultInstance: AgentRegistry | null = null;\n\nexport class AgentRegistry {\n    private db: DatabaseConnection;\n\n    constructor(filePath: string = DEFAULT_REGISTRY_PATH) {\n        this.db = new DatabaseConnection({ dbPath: resolveAgentRegistryDbPath(filePath) });\n    }\n\n    static default(): AgentRegistry {\n        if (!defaultInstance) {\n            defaultInstance = new AgentRegistry();\n        }\n        return defaultInstance;\n    }\n\n    private rowToEntry(row: RegistryRow): RegistryEntry {\n        return {\n            name: row.name,\n            type: row.type,\n            pid: row.pid,\n            tmuxSession: row.tmux_session,\n            cwd: row.cwd,\n            startedAt: row.started_at,\n            sessionId: row.session_id,\n            sessionFilePath: row.session_file_path,\n        };\n    }\n\n    private mergeEntry(incoming: RegistryEntry, existing: RegistryEntry | undefined): RegistryEntry {\n        if (!existing) return incoming;\n        const incomingIsManaged = Boolean(incoming.tmuxSession);\n        return {\n            ...existing,\n            name: incomingIsManaged ? incoming.name : existing.name,\n            tmuxSession: incoming.tmuxSession || existing.tmuxSession,\n            cwd: incoming.cwd || existing.cwd,\n            startedAt: existing.startedAt || incoming.startedAt,\n            sessionId: incoming.sessionId || existing.sessionId,\n            sessionFilePath: incoming.sessionFilePath || existing.sessionFilePath,\n        };\n    }\n\n    private findByIdentity(type: AgentType, pid: number): RegistryEntry | undefined {\n        const row = this.db.queryOne<RegistryRow>(\n            'SELECT * FROM agents WHERE type = ? AND pid = ?',\n            [type, pid],\n        );\n        return row ? this.rowToEntry(row) : undefined;\n    }\n\n    private findByName(name: string): RegistryEntry | undefined {\n        const row = this.db.queryOne<RegistryRow>('SELECT * FROM agents WHERE name = ?', [name]);\n        return row ? this.rowToEntry(row) : undefined;\n    }\n\n    private deleteNameConflict(name: string, type: AgentType, pid: number): void {\n        const conflict = this.findByName(name);\n        if (!conflict) return;\n        if (conflict.type === type && conflict.pid === pid) return;\n        if (!this.isAlive(conflict)) {\n            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);\n        }\n    }\n\n    private insertOrUpdate(entry: RegistryEntry): void {\n        this.db.instance.prepare(`\n            INSERT INTO agents (\n                type, pid, name, tmux_session, cwd, started_at, session_id, session_file_path, updated_at\n            )\n            VALUES (\n                @type, @pid, @name, @tmuxSession, @cwd, @startedAt, @sessionId, @sessionFilePath, @updatedAt\n            )\n            ON CONFLICT(type, pid) DO UPDATE SET\n                name = excluded.name,\n                tmux_session = excluded.tmux_session,\n                cwd = excluded.cwd,\n                started_at = agents.started_at,\n                session_id = excluded.session_id,\n                session_file_path = excluded.session_file_path,\n                updated_at = excluded.updated_at\n        `).run({ ...entry, updatedAt: new Date().toISOString() });\n    }\n\n    private save(entry: RegistryEntry): void {\n        this.deleteNameConflict(entry.name, entry.type, entry.pid);\n        this.insertOrUpdate(entry);\n    }\n\n    isAlive(entry: RegistryEntry): boolean {\n        try {\n            process.kill(entry.pid, 0);\n            return true;\n        } catch {\n            return false;\n        }\n    }\n\n    prune(): void {\n        const entries = this.list();\n        const stale = entries.filter((e) => !this.isAlive(e));\n        this.db.transaction(() => {\n            for (const entry of stale) {\n                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);\n            }\n        });\n    }\n\n    register(entry: RegistryEntry): void {\n        this.registerBatch([entry]);\n    }\n\n    registerBatch(entries: RegistryEntry[]): void {\n        if (entries.length === 0) return;\n        this.db.transaction(() => {\n            for (const incoming of entries) {\n                const existing = this.findByIdentity(incoming.type, incoming.pid);\n                this.save(this.mergeEntry(incoming, existing));\n            }\n        });\n    }\n\n    rename(currentName: string, newName: string): void {\n        const existing = this.findByName(currentName);\n        if (!existing) {\n            throw new RenameNotFoundError(currentName);\n        }\n        const conflict = this.findByName(newName);\n        if (conflict && this.isAlive(conflict)) {\n            throw new RenameConflictError(newName);\n        }\n\n        this.db.transaction(() => {\n            if (conflict) {\n                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);\n            }\n            this.db.execute(\n                'UPDATE agents SET name = ?, updated_at = ? WHERE type = ? AND pid = ?',\n                [newName, new Date().toISOString(), existing.type, existing.pid],\n            );\n        });\n    }\n\n    lookup(name: string): RegistryEntry | null {\n        return this.findByName(name) ?? null;\n    }\n\n    list(): RegistryEntry[] {\n        const rows = this.db.query<RegistryRow>('SELECT * FROM agents ORDER BY started_at ASC, name ASC');\n        return rows.map((row) => this.rowToEntry(row));\n    }\n}\n"],"names":["os","path","DatabaseConnection","resolveAgentRegistryDbPath","RenameNotFoundError","Error","agentName","name","RenameConflictError","DEFAULT_REGISTRY_PATH","join","homedir","defaultInstance","AgentRegistry","db","filePath","dbPath","default","rowToEntry","row","type","pid","tmuxSession","tmux_session","cwd","startedAt","started_at","sessionId","session_id","sessionFilePath","session_file_path","mergeEntry","incoming","existing","incomingIsManaged","Boolean","findByIdentity","queryOne","undefined","findByName","deleteNameConflict","conflict","isAlive","execute","insertOrUpdate","entry","instance","prepare","run","updatedAt","Date","toISOString","save","process","kill","prune","entries","list","stale","filter","e","transaction","register","registerBatch","length","rename","currentName","newName","lookup","rows","query","map"],"mappings":"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"}
+{"version":3,"sources":["../../src/utils/AgentRegistry.ts"],"sourcesContent":["import os from 'os';\nimport path from 'path';\nimport type { AgentType } from '../adapters/AgentAdapter.js';\nimport {\n    DatabaseConnection,\n    resolveAgentRegistryDbPath,\n} from '../database/index.js';\n\nexport class RenameNotFoundError extends Error {\n    constructor(public agentName: string) {\n        super(`Agent \"${agentName}\" not found in registry.`);\n        this.name = 'RenameNotFoundError';\n    }\n}\n\nexport class RenameConflictError extends Error {\n    constructor(public agentName: string) {\n        super(`Agent \"${agentName}\" is already in use.`);\n        this.name = 'RenameConflictError';\n    }\n}\n\nexport interface RegistryEntry {\n    name: string;\n    type: AgentType;\n    pid: number;\n    tmuxSession: string;\n    cwd: string;\n    startedAt: string;  // ISO 8601\n    sessionId: string;\n    sessionFilePath: string;\n}\n\ninterface RegistryRow {\n    name: string;\n    type: AgentType;\n    pid: number;\n    tmux_session: string;\n    cwd: string;\n    started_at: string;\n    session_id: string;\n    session_file_path: string;\n    updated_at: string;\n}\n\nconst DEFAULT_REGISTRY_PATH = path.join(os.homedir(), '.ai-devkit', 'agents.json');\nconst DEFAULT_PRUNE_INTERVAL_MS = 30_000;\n\nlet defaultInstance: AgentRegistry | null = null;\n\nexport interface AgentRegistryOptions {\n    now?: () => Date;\n    pruneIntervalMs?: number;\n    onDatabaseOperation?: (sql: string) => void;\n}\n\nexport class AgentRegistry {\n    private db: DatabaseConnection;\n    private readonly now: () => Date;\n    private readonly pruneIntervalMs: number;\n    private lastPrunedAt: number | undefined;\n\n    constructor(filePath: string = DEFAULT_REGISTRY_PATH, options: AgentRegistryOptions = {}) {\n        this.now = options.now ?? (() => new Date());\n        this.pruneIntervalMs = options.pruneIntervalMs ?? DEFAULT_PRUNE_INTERVAL_MS;\n        this.db = new DatabaseConnection({\n            dbPath: resolveAgentRegistryDbPath(filePath),\n            verbose: options.onDatabaseOperation,\n        });\n    }\n\n    static default(): AgentRegistry {\n        if (!defaultInstance) {\n            defaultInstance = new AgentRegistry();\n        }\n        return defaultInstance;\n    }\n\n    private rowToEntry(row: RegistryRow): RegistryEntry {\n        return {\n            name: row.name,\n            type: row.type,\n            pid: row.pid,\n            tmuxSession: row.tmux_session,\n            cwd: row.cwd,\n            startedAt: row.started_at,\n            sessionId: row.session_id,\n            sessionFilePath: row.session_file_path,\n        };\n    }\n\n    private mergeEntry(incoming: RegistryEntry, existing: RegistryEntry | undefined): RegistryEntry {\n        if (!existing) return incoming;\n        const incomingIsManaged = Boolean(incoming.tmuxSession);\n        return {\n            ...existing,\n            name: incomingIsManaged ? incoming.name : existing.name,\n            tmuxSession: incoming.tmuxSession || existing.tmuxSession,\n            cwd: incoming.cwd || existing.cwd,\n            startedAt: existing.startedAt || incoming.startedAt,\n            sessionId: incoming.sessionId || existing.sessionId,\n            sessionFilePath: incoming.sessionFilePath || existing.sessionFilePath,\n        };\n    }\n\n    private findByIdentity(type: AgentType, pid: number): RegistryEntry | undefined {\n        const row = this.db.queryOne<RegistryRow>(\n            'SELECT * FROM agents WHERE type = ? AND pid = ?',\n            [type, pid],\n        );\n        return row ? this.rowToEntry(row) : undefined;\n    }\n\n    private findByName(name: string): RegistryEntry | undefined {\n        const row = this.db.queryOne<RegistryRow>('SELECT * FROM agents WHERE name = ?', [name]);\n        return row ? this.rowToEntry(row) : undefined;\n    }\n\n    private findPidConflicts(type: AgentType, pid: number): RegistryEntry[] {\n        return this.db.query<RegistryRow>(\n            'SELECT * FROM agents WHERE pid = ? AND type <> ?',\n            [pid, type],\n        ).map((row) => this.rowToEntry(row));\n    }\n\n    private entriesEqual(left: RegistryEntry, right: RegistryEntry): boolean {\n        return left.name === right.name\n            && left.type === right.type\n            && left.pid === right.pid\n            && left.tmuxSession === right.tmuxSession\n            && left.cwd === right.cwd\n            && left.startedAt === right.startedAt\n            && left.sessionId === right.sessionId\n            && left.sessionFilePath === right.sessionFilePath;\n    }\n\n    private deleteNameConflict(name: string, type: AgentType, pid: number): void {\n        const conflict = this.findByName(name);\n        if (!conflict) return;\n        if (conflict.type === type && conflict.pid === pid) return;\n        if (!this.isAlive(conflict)) {\n            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);\n        }\n    }\n\n    private insertOrUpdate(entry: RegistryEntry): void {\n        this.db.instance.prepare(`\n            INSERT INTO agents (\n                type, pid, name, tmux_session, cwd, started_at, session_id, session_file_path, updated_at\n            )\n            VALUES (\n                @type, @pid, @name, @tmuxSession, @cwd, @startedAt, @sessionId, @sessionFilePath, @updatedAt\n            )\n            ON CONFLICT(type, pid) DO UPDATE SET\n                name = excluded.name,\n                tmux_session = excluded.tmux_session,\n                cwd = excluded.cwd,\n                started_at = agents.started_at,\n                session_id = excluded.session_id,\n                session_file_path = excluded.session_file_path,\n                updated_at = excluded.updated_at\n        `).run({ ...entry, updatedAt: this.now().toISOString() });\n    }\n\n    private needsWrite(incoming: RegistryEntry): boolean {\n        const existing = this.findByIdentity(incoming.type, incoming.pid);\n        const merged = this.mergeEntry(incoming, existing);\n        return !existing\n            || !this.entriesEqual(merged, existing)\n            || this.findPidConflicts(incoming.type, incoming.pid).length > 0;\n    }\n\n    private save(incoming: RegistryEntry): void {\n        const existing = this.findByIdentity(incoming.type, incoming.pid);\n        const merged = this.mergeEntry(incoming, existing);\n        const pidConflicts = this.findPidConflicts(incoming.type, incoming.pid);\n        if (existing && this.entriesEqual(merged, existing) && pidConflicts.length === 0) return;\n\n        for (const conflict of pidConflicts) {\n            this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);\n        }\n        if (existing && this.entriesEqual(merged, existing)) return;\n\n        this.deleteNameConflict(merged.name, merged.type, merged.pid);\n        this.insertOrUpdate(merged);\n    }\n\n    isAlive(entry: RegistryEntry): boolean {\n        try {\n            process.kill(entry.pid, 0);\n            return true;\n        } catch (error) {\n            const code = error && typeof error === 'object' && 'code' in error\n                ? error.code\n                : undefined;\n            return code !== 'ESRCH';\n        }\n    }\n\n    private pruneAt(nowMs: number): void {\n        const entries = this.list();\n        const stale = entries.filter((e) => !this.isAlive(e));\n        if (stale.length > 0) {\n            this.db.transaction(() => {\n                for (const entry of stale) {\n                    this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [entry.type, entry.pid]);\n                }\n            });\n        }\n        this.lastPrunedAt = nowMs;\n    }\n\n    prune(): void {\n        this.pruneAt(this.now().getTime());\n    }\n\n    pruneIfDue(): void {\n        const nowMs = this.now().getTime();\n        const elapsed = this.lastPrunedAt === undefined ? undefined : nowMs - this.lastPrunedAt;\n        if (elapsed !== undefined && elapsed >= 0 && elapsed < this.pruneIntervalMs) return;\n        this.pruneAt(nowMs);\n    }\n\n    register(entry: RegistryEntry): void {\n        this.registerBatch([entry]);\n    }\n\n    registerBatch(entries: RegistryEntry[]): void {\n        if (entries.length === 0) return;\n        if (!entries.some((entry) => this.needsWrite(entry))) return;\n        this.db.transaction(() => {\n            for (const incoming of entries) {\n                this.save(incoming);\n            }\n        });\n    }\n\n    rename(currentName: string, newName: string): void {\n        const existing = this.findByName(currentName);\n        if (!existing) {\n            throw new RenameNotFoundError(currentName);\n        }\n        const conflict = this.findByName(newName);\n        if (conflict && this.isAlive(conflict)) {\n            throw new RenameConflictError(newName);\n        }\n\n        this.db.transaction(() => {\n            if (conflict) {\n                this.db.execute('DELETE FROM agents WHERE type = ? AND pid = ?', [conflict.type, conflict.pid]);\n            }\n            this.db.execute(\n                'UPDATE agents SET name = ?, updated_at = ? WHERE type = ? AND pid = ?',\n                [newName, this.now().toISOString(), existing.type, existing.pid],\n            );\n        });\n    }\n\n    lookup(name: string): RegistryEntry | null {\n        return this.findByName(name) ?? null;\n    }\n\n    list(): RegistryEntry[] {\n        const rows = this.db.query<RegistryRow>('SELECT * FROM agents ORDER BY started_at ASC, name ASC');\n        return rows.map((row) => this.rowToEntry(row));\n    }\n}\n"],"names":["os","path","DatabaseConnection","resolveAgentRegistryDbPath","RenameNotFoundError","Error","agentName","name","RenameConflictError","DEFAULT_REGISTRY_PATH","join","homedir","DEFAULT_PRUNE_INTERVAL_MS","defaultInstance","AgentRegistry","db","now","pruneIntervalMs","lastPrunedAt","filePath","options","Date","dbPath","verbose","onDatabaseOperation","default","rowToEntry","row","type","pid","tmuxSession","tmux_session","cwd","startedAt","started_at","sessionId","session_id","sessionFilePath","session_file_path","mergeEntry","incoming","existing","incomingIsManaged","Boolean","findByIdentity","queryOne","undefined","findByName","findPidConflicts","query","map","entriesEqual","left","right","deleteNameConflict","conflict","isAlive","execute","insertOrUpdate","entry","instance","prepare","run","updatedAt","toISOString","needsWrite","merged","length","save","pidConflicts","process","kill","error","code","pruneAt","nowMs","entries","list","stale","filter","e","transaction","prune","getTime","pruneIfDue","elapsed","register","registerBatch","some","rename","currentName","newName","lookup","rows"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",

package/src/AgentManager.ts

@@ -180,15 +180,18 @@ export class AgentManager {
             });
         }
 
-        const preExistingByPid = new Map(this.registry.list().map((e) => [e.pid, e]));
+        const identityKey = (type: string, pid: number): string => `${type}:${pid}`;
+        const preExistingByIdentity = new Map(
+            this.registry.list().map((entry) => [identityKey(entry.type, entry.pid), entry]),
+        );
         const entries = allAgents.map((agent) =>
-            this.toRegistryEntry(agent, preExistingByPid.get(agent.pid)),
+            this.toRegistryEntry(agent, preExistingByIdentity.get(identityKey(agent.type, agent.pid))),
         );
         if (entries.length > 0) this.registry.registerBatch(entries);
-        this.registry.prune();
+        this.registry.pruneIfDue();
 
         for (const agent of allAgents) {
-            const entry = preExistingByPid.get(agent.pid);
+            const entry = preExistingByIdentity.get(identityKey(agent.type, agent.pid));
             if (entry) {
                 agent.name = entry.name;
             }

package/src/__tests__/AgentManager.test.ts

@@ -344,15 +344,25 @@ describe('AgentManager', () => {
         let regPath: string;
         let registry: AgentRegistry;
         let scopedManager: AgentManager;
+        let nowMs: number;
+        let databaseOperations: string[];
 
         beforeEach(() => {
             tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-manager-'));
             regPath = path.join(tmpDir, 'agents.json');
-            registry = new AgentRegistry(regPath);
+            nowMs = Date.parse('2026-08-14T10:00:00.000Z');
+            databaseOperations = [];
+            registry = new AgentRegistry(regPath, {
+                now: () => new Date(nowMs),
+                pruneIntervalMs: 30_000,
+                onDatabaseOperation: (sql) => databaseOperations.push(sql),
+            });
             scopedManager = new AgentManager(registry);
+            databaseOperations = [];
         });
 
         afterEach(() => {
+            vi.restoreAllMocks();
             fs.rmSync(tmpDir, { recursive: true, force: true });
         });
 
@@ -429,6 +439,35 @@ describe('AgentManager', () => {
             expect(registry.list()[0].startedAt).toBe('2026-05-30T00:00:00.000Z');
         });
 
+        it('preserves custom name and tmux session across two EPERM refresh cycles', async () => {
+            registry.register({
+                name: 'merry',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: 'merry-tmux',
+                cwd: '/cwd/merry',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'sid-merry',
+                sessionFilePath: '/path/merry.jsonl',
+            });
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({ name: `ai-devkit-${process.pid}`, pid: process.pid }),
+            ]));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            const firstRefresh = await scopedManager.listAgents();
+            const secondRefresh = await scopedManager.listAgents();
+
+            expect(firstRefresh[0].name).toBe('merry');
+            expect(secondRefresh[0].name).toBe('merry');
+            expect(registry.lookup('merry')).toMatchObject({
+                name: 'merry',
+                tmuxSession: 'merry-tmux',
+            });
+        });
+
         it('preserves a user-managed name when a fallback row was written later for the same pid', async () => {
             registry.register({
                 name: 'agent-list-debug',
@@ -495,15 +534,114 @@ describe('AgentManager', () => {
                 .toEqual(['a', 'b']);
         });
 
-        it('skips registerBatch when no agents detected (still calls prune)', async () => {
+        it('performs zero database writes on an unchanged refresh', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'stable',
+                    pid: process.pid,
+                    projectPath: '/cwd/stable',
+                    sessionId: 'stable-session',
+                    sessionFilePath: '/sessions/stable.jsonl',
+                }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            databaseOperations = [];
+
+            await scopedManager.listAgents();
+
+            const writes = databaseOperations.filter((sql) => /^\s*(BEGIN|COMMIT|INSERT|UPDATE|DELETE)/i.test(sql));
+            expect(writes).toEqual([]);
+        });
+
+        it('persists changed fields once in one write transaction', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({ name: 'changing', pid: process.pid, projectPath: '/cwd/before' }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            databaseOperations = [];
+            nowMs += 1_000;
+            adapter.setAgents([
+                createMockAgent({ name: 'changing', pid: process.pid, projectPath: '/cwd/after' }),
+            ]);
+
+            await scopedManager.listAgents();
+
+            const upserts = databaseOperations.filter((sql) => /^\s*INSERT INTO agents/i.test(sql));
+            const transactions = databaseOperations.filter((sql) => /^\s*(BEGIN|COMMIT)/i.test(sql));
+            expect(upserts).toHaveLength(1);
+            expect(upserts[0]).toContain("'2026-08-14T10:00:01.000Z'");
+            expect(transactions).toHaveLength(2);
+            expect(registry.lookup('changing')?.cwd).toBe('/cwd/after');
+        });
+
+        it('prunes newly dead entries only when the passive cadence is due', async () => {
+            registry.register({
+                name: 'cadenced',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: '',
+                cwd: '/cwd/cadenced',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'sid-cadenced',
+                sessionFilePath: '',
+            });
+            const alive = vi.spyOn(registry, 'isAlive').mockReturnValue(true);
+
+            await scopedManager.listAgents();
+            expect(alive).toHaveBeenCalledTimes(1);
+            alive.mockReturnValue(false);
+            nowMs += 29_999;
+
+            await scopedManager.listAgents();
+            expect(alive).toHaveBeenCalledTimes(1);
+            expect(registry.lookup('cadenced')).not.toBeNull();
+
+            nowMs += 1;
+            await scopedManager.listAgents();
+            expect(alive).toHaveBeenCalledTimes(2);
+            expect(registry.lookup('cadenced')).toBeNull();
+        });
+
+        it('does not inherit a name when the same pid is reused by another agent type', async () => {
+            registry.register({
+                name: 'old-claude',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: 'old-claude',
+                cwd: '/cwd/old',
+                startedAt: '2026-05-30T00:00:00.000Z',
+                sessionId: 'old-session',
+                sessionFilePath: '',
+            });
+            scopedManager.registerAdapter(new MockAdapter('codex', [
+                createMockAgent({
+                    name: 'new-codex',
+                    type: 'codex',
+                    pid: process.pid,
+                    projectPath: '/cwd/new',
+                    sessionId: 'new-session',
+                }),
+            ]));
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].name).toBe('new-codex');
+            expect(registry.lookup('old-claude')).toBeNull();
+            expect(registry.lookup('new-codex')).toMatchObject({ type: 'codex', pid: process.pid });
+        });
+
+        it('skips registerBatch when no agents are detected and prune is not due', async () => {
             const writeSpy = vi.spyOn(registry, 'registerBatch');
-            const pruneSpy = vi.spyOn(registry, 'prune');
+            const pruneSpy = vi.spyOn(registry, 'pruneIfDue');
 
             scopedManager.registerAdapter(new MockAdapter('claude', []));
             await scopedManager.listAgents();
+            await scopedManager.listAgents();
 
             expect(writeSpy).not.toHaveBeenCalled();
-            expect(pruneSpy).toHaveBeenCalledTimes(1);
+            expect(pruneSpy).toHaveBeenCalledTimes(2);
         });
     });
 

package/src/__tests__/utils/AgentRegistry.test.ts

@@ -29,6 +29,7 @@ describe('AgentRegistry', () => {
     });
 
     afterEach(() => {
+        vi.restoreAllMocks();
         fs.rmSync(tmpDir, { recursive: true, force: true });
     });
 
@@ -81,6 +82,19 @@ describe('AgentRegistry', () => {
             expect(registry.lookup(`ai-devkit-${process.pid}`)).toBeNull();
             expect(registry.list()).toHaveLength(1);
         });
+
+        it('preserves an existing name conflict when its probe fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'claimed-name', pid: process.pid }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(() => registry.register(makeEntry({
+                name: 'claimed-name',
+                pid: process.pid + 1,
+            }))).toThrow();
+            expect(registry.lookup('claimed-name')?.pid).toBe(process.pid);
+        });
     });
 
     describe('registerBatch', () => {
@@ -118,6 +132,33 @@ describe('AgentRegistry', () => {
             expect(registry.list()).toHaveLength(1);
             expect(registry.lookup('custom-name')?.pid).toBe(process.pid);
         });
+
+        it('cleans up a cross-type row when its pid has been reused', () => {
+            registry.register(makeEntry({ name: 'old-claude', type: 'claude', pid: process.pid }));
+
+            registry.register(makeEntry({
+                name: 'new-codex',
+                type: 'codex',
+                pid: process.pid,
+                tmuxSession: '',
+            }));
+
+            expect(registry.lookup('old-claude')).toBeNull();
+            expect(registry.lookup('new-codex')).toMatchObject({ type: 'codex', pid: process.pid });
+            expect(registry.list()).toHaveLength(1);
+        });
+
+        it('rolls back the whole batch when a live name conflict rejects one entry', () => {
+            registry.register(makeEntry({ name: 'taken', pid: process.pid }));
+
+            expect(() => registry.registerBatch([
+                makeEntry({ name: 'fresh', pid: 999998 }),
+                makeEntry({ name: 'taken', type: 'codex', pid: 999997 }),
+            ])).toThrow(/UNIQUE constraint failed/);
+
+            expect(registry.lookup('fresh')).toBeNull();
+            expect(registry.lookup('taken')?.pid).toBe(process.pid);
+        });
     });
 
     describe('lookup', () => {
@@ -157,6 +198,30 @@ describe('AgentRegistry', () => {
         it('returns false for a PID that does not exist', () => {
             expect(registry.isAlive(makeEntry({ pid: 999999 }))).toBe(false);
         });
+
+        it('returns true when the process probe is forbidden with EPERM', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(true);
+        });
+
+        it('returns false when the process probe reports ESRCH', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(false);
+        });
+
+        it('returns true when the process probe fails without a definitive error code', () => {
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw new Error('indeterminate probe failure');
+            });
+
+            expect(registry.isAlive(makeEntry())).toBe(true);
+        });
     });
 
     describe('prune', () => {
@@ -177,9 +242,52 @@ describe('AgentRegistry', () => {
             expect(after).toEqual(before);
         });
 
+        it('preserves entries when liveness probing fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'custom-name', tmuxSession: 'tmux-custom' }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            registry.prune();
+
+            expect(registry.lookup('custom-name')).toMatchObject({
+                name: 'custom-name',
+                tmuxSession: 'tmux-custom',
+            });
+        });
+
+        it('removes entries when liveness probing fails with ESRCH', () => {
+            registry.register(makeEntry({ name: 'dead' }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('no such process'), { code: 'ESRCH' });
+            });
+
+            registry.prune();
+
+            expect(registry.lookup('dead')).toBeNull();
+        });
+
         it('does nothing when file is missing', () => {
             expect(() => registry.prune()).not.toThrow();
         });
+
+        it('keeps forced prune available before the passive cadence is due', () => {
+            let nowMs = Date.parse('2026-08-14T10:00:00.000Z');
+            const clocked = new AgentRegistry(regPath, {
+                now: () => new Date(nowMs),
+                pruneIntervalMs: 30_000,
+            });
+            clocked.register(makeEntry({ name: 'forced', pid: process.pid }));
+            const alive = vi.spyOn(clocked, 'isAlive').mockReturnValue(true);
+            clocked.pruneIfDue();
+            alive.mockReturnValue(false);
+            nowMs += 1;
+
+            clocked.prune();
+
+            expect(alive).toHaveBeenCalledTimes(2);
+            expect(clocked.lookup('forced')).toBeNull();
+        });
     });
 
     describe('default()', () => {
@@ -215,6 +323,17 @@ describe('AgentRegistry', () => {
             expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
         });
 
+        it('throws RenameConflictError when the conflicting entry probe fails with EPERM', () => {
+            registry.register(makeEntry({ name: 'agent-a', pid: process.pid }));
+            registry.register(makeEntry({ name: 'agent-b', pid: process.ppid }));
+            vi.spyOn(process, 'kill').mockImplementation(() => {
+                throw Object.assign(new Error('operation not permitted'), { code: 'EPERM' });
+            });
+
+            expect(() => registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
+            expect(registry.lookup('agent-b')?.pid).toBe(process.ppid);
+        });
+
         it('succeeds when new name exists only as a stale (dead) entry', () => {
             registry.register(makeEntry({ name: 'agent-a', pid: process.pid }));
             registry.register(makeEntry({ name: 'agent-b', pid: 999999 }));

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

@@ -29,7 +29,7 @@ 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],
             );
         });
     }