@ai-devkit/agent-manager 0.26.3 → 0.27.0

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    pinned: boolean;\n    updatedAt?: 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    pinned: number;\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    readonly?: boolean;\n}\n\nexport class AgentRegistry {\n    private db: DatabaseConnection;\n    private readonly now: () => Date;\n    private readonly pruneIntervalMs: number;\n    private readonly readonly: boolean;\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.readonly = options.readonly ?? false;\n        this.db = new DatabaseConnection({\n            dbPath: resolveAgentRegistryDbPath(filePath),\n            verbose: options.onDatabaseOperation,\n            readonly: this.readonly,\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            pinned: row.pinned !== 0,\n            updatedAt: row.updated_at,\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    togglePin(type: AgentType, pid: number): boolean | null {\n        if (this.readonly) {\n            throw new Error('Agent registry is readonly; cannot toggle pin.');\n        }\n        const result = this.db.execute(\n            'UPDATE agents SET pinned = NOT pinned, updated_at = ? WHERE type = ? AND pid = ?',\n            [this.now().toISOString(), type, pid],\n        );\n        if (result.changes === 0) return null;\n        return this.findByIdentity(type, pid)?.pinned ?? null;\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","readonly","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","pinned","updatedAt","updated_at","mergeEntry","incoming","existing","incomingIsManaged","Boolean","findByIdentity","queryOne","undefined","findByName","findPidConflicts","query","map","entriesEqual","left","right","deleteNameConflict","conflict","isAlive","execute","insertOrUpdate","entry","instance","prepare","run","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","togglePin","result","changes","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.27.0",
   "type": "module",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "main": "dist/index.js",

package/src/AgentManager.ts

@@ -26,6 +26,13 @@ export interface ListAgentsOptions {
     sortBy?: AgentSortKey;
 }
 
+export class AgentNotRunningError extends Error {
+    constructor(public agentName: string) {
+        super(`Agent "${agentName}" is no longer running.`);
+        this.name = 'AgentNotRunningError';
+    }
+}
+
 /**
  * Agent Manager Class
  * 
@@ -180,17 +187,22 @@ 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;
+                agent.pinned = entry.pinned;
+                if (entry.pinned && entry.updatedAt) agent.lastActive = new Date(entry.updatedAt);
             }
         }
 
@@ -208,9 +220,21 @@ export class AgentManager {
             startedAt: existing?.startedAt ?? new Date().toISOString(),
             sessionId: agent.sessionId,
             sessionFilePath: agent.sessionFilePath ?? '',
+            pinned: existing?.pinned ?? agent.pinned ?? false,
         };
     }
 
+    togglePin(agentName: string): boolean {
+        const entry = this.registry.lookup(agentName);
+        if (!entry || !this.registry.isAlive(entry)) {
+            if (entry) this.registry.prune();
+            throw new AgentNotRunningError(agentName);
+        }
+        const pinned = this.registry.togglePin(entry.type, entry.pid);
+        if (pinned === null) throw new AgentNotRunningError(agentName);
+        return pinned;
+    }
+
     /**
      * List historical sessions across every registered adapter.
      *

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,231 @@ 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('exposes a persisted pin and preserves it across a changed poll refresh', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({ name: 'pinned', pid: process.pid, sessionId: 'before' }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            registry.togglePin('claude', process.pid);
+            adapter.setAgents([
+                createMockAgent({ name: 'pinned', pid: process.pid, sessionId: 'after' }),
+            ]);
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(true);
+            expect(registry.lookup('pinned')).toMatchObject({ sessionId: 'after', pinned: true });
+        });
+
+        it('uses registry updated_at as lastActive for pinned recency ordering', async () => {
+            const adapter = new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'recently-pinned',
+                    pid: process.pid,
+                    lastActive: new Date('2026-01-01T00:00:00.000Z'),
+                }),
+            ]);
+            scopedManager.registerAdapter(adapter);
+            await scopedManager.listAgents();
+            nowMs += 60_000;
+            scopedManager.togglePin('recently-pinned');
+
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(true);
+            expect(agents[0].lastActive.toISOString()).toBe('2026-08-14T10:01:00.000Z');
+        });
+
+        it('preserves adapter lastActive for unpinned agents', async () => {
+            scopedManager.registerAdapter(new MockAdapter('claude', [
+                createMockAgent({
+                    name: 'unpinned',
+                    pid: process.pid,
+                    lastActive: new Date('2026-01-01T00:00:00.000Z'),
+                }),
+            ]));
+
+            await scopedManager.listAgents();
+            const agents = await scopedManager.listAgents();
+
+            expect(agents[0].pinned).toBe(false);
+            expect(agents[0].lastActive.toISOString()).toBe('2026-01-01T00:00:00.000Z');
+        });
+
+        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);
+        });
+    });
+
+    describe('togglePin', () => {
+        it('resolves the agent name to its process identity and toggles the pin', () => {
+            const registry = new AgentRegistry(path.join(tmpDir, 'toggle.json'));
+            const scopedManager = new AgentManager(registry);
+            registry.register({
+                name: 'renamed-agent',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+
+            expect(scopedManager.togglePin('renamed-agent')).toBe(true);
+            expect(registry.lookup('renamed-agent')?.pinned).toBe(true);
+        });
+
+        it('reports when the agent is no longer running', () => {
+            expect(() => manager.togglePin('missing')).toThrow(/no longer running/i);
+        });
+
+        it('rejects a dead process and prunes its row', () => {
+            const registry = new AgentRegistry(path.join(tmpDir, 'dead-toggle.json'));
+            const scopedManager = new AgentManager(registry);
+            registry.register({
+                name: 'dead',
+                type: 'claude',
+                pid: 999999,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+
+            expect(() => scopedManager.togglePin('dead')).toThrow(/no longer running/i);
+            expect(registry.lookup('dead')).toBeNull();
+        });
+
+        it('surfaces a clear readonly mutation error', () => {
+            const regPath = path.join(tmpDir, 'readonly-toggle.json');
+            const writable = new AgentRegistry(regPath);
+            writable.register({
+                name: 'readonly-agent',
+                type: 'claude',
+                pid: process.pid,
+                tmuxSession: '',
+                cwd: '/tmp',
+                startedAt: '2026-08-16T00:00:00.000Z',
+                sessionId: 'session',
+                sessionFilePath: '',
+                pinned: false,
+            });
+            const readonlyManager = new AgentManager(new AgentRegistry(regPath, { readonly: true }));
+
+            expect(() => readonlyManager.togglePin('readonly-agent')).toThrow(
+                'Agent registry is readonly; cannot toggle pin.',
+            );
         });
     });