@ai-devkit/agent-manager 0.31.0 → 0.33.0

package/dist/__tests__/utils/AgentRegistry.test.js

@@ -1,29 +1,32 @@
-import fs from 'fs';
-import os from 'os';
-import path from 'path';
-import Database from 'better-sqlite3';
-import { AgentRegistry, RenameNotFoundError, RenameConflictError } from '../../utils/AgentRegistry.js';
+import fs from "fs";
+import os from "os";
+import path from "path";
+import Database from "better-sqlite3";
+import { AgentRegistry, RenameNotFoundError, RenameConflictError } from "../../utils/AgentRegistry.js";
 function makeEntry(over = {}) {
     return {
-        name: 'agent1',
-        type: 'claude',
+        name: "agent1",
+        type: "claude",
         pid: process.pid,
-        tmuxSession: 'agent1',
-        cwd: '/tmp',
-        startedAt: '2026-05-30T00:00:00.000Z',
-        sessionId: 'sid-1',
-        sessionFilePath: '/tmp/session.jsonl',
+        cwd: "/tmp",
+        startedAt: "2026-05-30T00:00:00.000Z",
+        sessionId: "sid-1",
+        sessionFilePath: "/tmp/session.jsonl",
         pinned: false,
+        runtime: "tmux",
+        runtimeRef: {
+            session: "agent1"
+        },
         ...over
     };
 }
-describe('AgentRegistry', ()=>{
+describe("AgentRegistry", ()=>{
     let tmpDir;
     let regPath;
     let registry;
     beforeEach(()=>{
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-registry-'));
-        regPath = path.join(tmpDir, 'nested', 'agents.json');
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-registry-"));
+        regPath = path.join(tmpDir, "nested", "agents.json");
         registry = new AgentRegistry(regPath);
     });
     afterEach(()=>{
@@ -33,276 +36,338 @@ describe('AgentRegistry', ()=>{
             force: true
         });
     });
-    describe('register', ()=>{
-        it('creates the SQLite database and parent directory if missing', ()=>{
+    describe("register", ()=>{
+        it("creates the SQLite database and parent directory if missing", ()=>{
             registry.register(makeEntry());
-            expect(fs.existsSync(regPath.replace(/\.json$/, '.db'))).toBe(true);
-            expect(registry.list()[0].name).toBe('agent1');
+            expect(fs.existsSync(regPath.replace(/\.json$/, ".db"))).toBe(true);
+            expect(registry.list()[0].name).toBe("agent1");
         });
-        it('appends a new entry when name is unique', ()=>{
+        it("appends a new entry when name is unique", ()=>{
             registry.register(makeEntry({
-                name: 'a'
+                name: "a"
             }));
             registry.register(makeEntry({
-                name: 'b',
+                name: "b",
                 pid: process.ppid
             }));
             expect(registry.list()).toHaveLength(2);
         });
-        it('upserts in place when type and pid already exist', ()=>{
+        it("upserts in place when type and pid already exist", ()=>{
             registry.register(makeEntry({
-                name: 'a',
+                name: "a",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'fallback',
+                name: "fallback",
                 pid: process.pid,
-                tmuxSession: ''
+                runtimeRef: null
             }));
             const all = registry.list();
             expect(all).toHaveLength(1);
             expect(all[0].pid).toBe(process.pid);
-            expect(all[0].name).toBe('a');
+            expect(all[0].name).toBe("a");
         });
-        it('does not write through the legacy fixed .tmp path', ()=>{
+        it("does not write through the legacy fixed .tmp path", ()=>{
             registry.register(makeEntry());
             expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);
         });
-        it('persists session fields', ()=>{
+        it("persists session fields", ()=>{
             registry.register(makeEntry({
-                sessionId: 'sid-xyz',
-                sessionFilePath: '/foo/bar.jsonl'
+                sessionId: "sid-xyz",
+                sessionFilePath: "/foo/bar.jsonl"
             }));
             const saved = registry.list()[0];
-            expect(saved.sessionId).toBe('sid-xyz');
-            expect(saved.sessionFilePath).toBe('/foo/bar.jsonl');
+            expect(saved.sessionId).toBe("sid-xyz");
+            expect(saved.sessionFilePath).toBe("/foo/bar.jsonl");
+        });
+        it("persists runtime metadata for Herdr-backed entries", ()=>{
+            const runtimeRef = {
+                session: "default",
+                paneId: "w1:p2",
+                agentName: "reviewer"
+            };
+            registry.register(makeEntry({
+                name: "reviewer",
+                runtime: "herdr",
+                runtimeRef
+            }));
+            expect(registry.lookup("reviewer")).toMatchObject({
+                runtime: "herdr",
+                runtimeRef
+            });
         });
-        it('preserves existing tmuxSession when incoming is empty string', ()=>{
+        it("lets a Herdr managed start replace an existing same-pid name", ()=>{
+            const runtimeRef = {
+                session: "default",
+                paneId: "w1:p2",
+                agentName: "requested-name"
+            };
             registry.register(makeEntry({
-                name: 'a',
-                tmuxSession: 'pinned'
+                name: "old-name",
+                pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'fallback',
-                tmuxSession: '',
+                name: "requested-name",
+                pid: process.pid,
+                runtime: "herdr",
+                runtimeRef
+            }));
+            expect(registry.lookup("old-name")).toBeNull();
+            expect(registry.lookup("requested-name")).toMatchObject({
+                pid: process.pid,
+                runtime: "herdr",
+                runtimeRef
+            });
+        });
+        it("preserves existing runtime ref when incoming runtime ref is empty", ()=>{
+            registry.register(makeEntry({
+                name: "a",
+                runtimeRef: {
+                    session: "pinned"
+                }
+            }));
+            registry.register(makeEntry({
+                name: "fallback",
+                runtimeRef: null,
                 pid: process.pid
             }));
-            const saved = registry.lookup('a');
-            expect(saved?.tmuxSession).toBe('pinned');
+            const saved = registry.lookup("a");
+            expect(saved?.runtimeRef).toEqual({
+                session: "pinned"
+            });
             expect(saved?.pid).toBe(process.pid);
         });
-        it('lets a managed start entry replace a generated fallback for the same pid', ()=>{
+        it("defaults an empty tmux runtime ref from the tmux session", ()=>{
+            registry.register(makeEntry({
+                name: "a",
+                runtimeRef: null
+            }));
+            expect(registry.lookup("a")?.runtimeRef).toBeNull();
+        });
+        it("lets a managed start entry replace a generated fallback for the same pid", ()=>{
             registry.register(makeEntry({
                 name: `ai-devkit-${process.pid}`,
-                tmuxSession: ''
+                runtimeRef: null
             }));
             registry.register(makeEntry({
-                name: 'custom-name',
-                tmuxSession: 'custom-name'
+                name: "custom-name",
+                runtimeRef: {
+                    session: "custom-name"
+                }
             }));
-            expect(registry.lookup('custom-name')?.tmuxSession).toBe('custom-name');
+            expect(registry.lookup("custom-name")?.runtimeRef).toEqual({
+                session: "custom-name"
+            });
             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', ()=>{
+        it("preserves an existing name conflict when its probe fails with EPERM", ()=>{
             registry.register(makeEntry({
-                name: 'claimed-name',
+                name: "claimed-name",
                 pid: process.pid
             }));
-            vi.spyOn(process, 'kill').mockImplementation(()=>{
-                throw Object.assign(new Error('operation not permitted'), {
-                    code: 'EPERM'
+            vi.spyOn(process, "kill").mockImplementation(()=>{
+                throw Object.assign(new Error("operation not permitted"), {
+                    code: "EPERM"
                 });
             });
             expect(()=>registry.register(makeEntry({
-                    name: 'claimed-name',
+                    name: "claimed-name",
                     pid: process.pid + 1
                 }))).toThrow();
-            expect(registry.lookup('claimed-name')?.pid).toBe(process.pid);
+            expect(registry.lookup("claimed-name")?.pid).toBe(process.pid);
         });
     });
-    describe('registerBatch', ()=>{
-        it('is a no-op on empty array', ()=>{
+    describe("registerBatch", ()=>{
+        it("is a no-op on empty array", ()=>{
             registry.registerBatch([]);
             expect(fs.existsSync(regPath)).toBe(false);
         });
-        it('upserts multiple entries in a single batch', ()=>{
+        it("upserts multiple entries in a single batch", ()=>{
             registry.registerBatch([
                 makeEntry({
-                    name: 'a'
+                    name: "a"
                 }),
                 makeEntry({
-                    name: 'b',
+                    name: "b",
                     pid: process.pid + 1
                 }),
                 makeEntry({
-                    name: 'c',
+                    name: "c",
                     pid: process.pid + 2
                 })
             ]);
             expect(registry.list()).toHaveLength(3);
         });
-        it('applies the tmuxSession merge per entry', ()=>{
+        it("applies the tmux runtime ref merge per entry", ()=>{
             registry.register(makeEntry({
-                name: 'a',
-                tmuxSession: 'pinned'
+                name: "a",
+                runtimeRef: {
+                    session: "pinned"
+                }
             }));
             registry.registerBatch([
                 makeEntry({
-                    name: 'fallback',
-                    tmuxSession: '',
+                    name: "fallback",
+                    runtimeRef: null,
                     pid: process.pid
                 }),
                 makeEntry({
-                    name: 'b',
-                    tmuxSession: '',
+                    name: "b",
+                    runtimeRef: null,
                     pid: process.pid + 1
                 })
             ]);
-            expect(registry.lookup('a')?.tmuxSession).toBe('pinned');
-            expect(registry.lookup('a')?.pid).toBe(process.pid);
-            expect(registry.lookup('b')?.tmuxSession).toBe('');
+            expect(registry.lookup("a")?.runtimeRef).toEqual({
+                session: "pinned"
+            });
+            expect(registry.lookup("a")?.pid).toBe(process.pid);
+            expect(registry.lookup("b")?.runtimeRef).toBeNull();
         });
-        it('handles concurrent registry instances without duplicate pid rows', ()=>{
+        it("handles concurrent registry instances without duplicate pid rows", ()=>{
             const other = new AgentRegistry(regPath);
             registry.register(makeEntry({
                 name: `ai-devkit-${process.pid}`,
-                tmuxSession: ''
+                runtimeRef: null
             }));
             other.register(makeEntry({
-                name: 'custom-name',
-                tmuxSession: 'custom-name'
+                name: "custom-name",
+                runtimeRef: {
+                    session: "custom-name"
+                }
             }));
             registry.register(makeEntry({
                 name: `ai-devkit-${process.pid}`,
-                tmuxSession: ''
+                runtimeRef: null
             }));
             expect(registry.list()).toHaveLength(1);
-            expect(registry.lookup('custom-name')?.pid).toBe(process.pid);
+            expect(registry.lookup("custom-name")?.pid).toBe(process.pid);
         });
-        it('cleans up a cross-type row when its pid has been reused', ()=>{
+        it("cleans up a cross-type row when its pid has been reused", ()=>{
             registry.register(makeEntry({
-                name: 'old-claude',
-                type: 'claude',
+                name: "old-claude",
+                type: "claude",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'new-codex',
-                type: 'codex',
+                name: "new-codex",
+                type: "codex",
                 pid: process.pid,
-                tmuxSession: ''
+                runtimeRef: null
             }));
-            expect(registry.lookup('old-claude')).toBeNull();
-            expect(registry.lookup('new-codex')).toMatchObject({
-                type: 'codex',
+            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', ()=>{
+        it("rolls back the whole batch when a live name conflict rejects one entry", ()=>{
             registry.register(makeEntry({
-                name: 'taken',
+                name: "taken",
                 pid: process.pid
             }));
             expect(()=>registry.registerBatch([
                     makeEntry({
-                        name: 'fresh',
+                        name: "fresh",
                         pid: 999998
                     }),
                     makeEntry({
-                        name: 'taken',
-                        type: 'codex',
+                        name: "taken",
+                        type: "codex",
                         pid: 999997
                     })
                 ])).toThrow(/UNIQUE constraint failed/);
-            expect(registry.lookup('fresh')).toBeNull();
-            expect(registry.lookup('taken')?.pid).toBe(process.pid);
+            expect(registry.lookup("fresh")).toBeNull();
+            expect(registry.lookup("taken")?.pid).toBe(process.pid);
         });
     });
-    describe('lookup', ()=>{
-        it('returns null when name not found', ()=>{
-            expect(registry.lookup('missing')).toBeNull();
+    describe("lookup", ()=>{
+        it("returns null when name not found", ()=>{
+            expect(registry.lookup("missing")).toBeNull();
         });
-        it('returns the entry when name matches', ()=>{
+        it("returns the entry when name matches", ()=>{
             registry.register(makeEntry({
-                name: 'a'
+                name: "a"
             }));
-            expect(registry.lookup('a')?.name).toBe('a');
+            expect(registry.lookup("a")?.name).toBe("a");
         });
     });
-    describe('pinning', ()=>{
-        it('defaults new rows to unpinned and toggles the persisted state', ()=>{
+    describe("pinning", ()=>{
+        it("defaults new rows to unpinned and toggles the persisted state", ()=>{
             registry.register(makeEntry());
-            expect(registry.lookup('agent1')?.pinned).toBe(false);
-            expect(registry.togglePin('claude', process.pid)).toBe(true);
-            expect(registry.lookup('agent1')?.pinned).toBe(true);
-            expect(registry.togglePin('claude', process.pid)).toBe(false);
-            expect(registry.lookup('agent1')?.pinned).toBe(false);
-        });
-        it('updates existing recency when toggled', ()=>{
-            let now = new Date('2026-08-16T10:00:00.000Z');
+            expect(registry.lookup("agent1")?.pinned).toBe(false);
+            expect(registry.togglePin("claude", process.pid)).toBe(true);
+            expect(registry.lookup("agent1")?.pinned).toBe(true);
+            expect(registry.togglePin("claude", process.pid)).toBe(false);
+            expect(registry.lookup("agent1")?.pinned).toBe(false);
+        });
+        it("updates existing recency when toggled", ()=>{
+            let now = new Date("2026-08-16T10:00:00.000Z");
             const clocked = new AgentRegistry(regPath, {
                 now: ()=>now
             });
             clocked.register(makeEntry());
-            now = new Date('2026-08-16T10:01:00.000Z');
-            clocked.togglePin('claude', process.pid);
-            expect(clocked.lookup('agent1')?.updatedAt).toBe(now.toISOString());
-            const db = new Database(regPath.replace(/\.json$/, '.db'), {
+            now = new Date("2026-08-16T10:01:00.000Z");
+            clocked.togglePin("claude", process.pid);
+            expect(clocked.lookup("agent1")?.updatedAt).toBe(now.toISOString());
+            const db = new Database(regPath.replace(/\.json$/, ".db"), {
                 readonly: true
             });
-            const row = db.prepare('SELECT updated_at FROM agents WHERE type = ? AND pid = ?').get('claude', process.pid);
+            const row = db.prepare("SELECT updated_at FROM agents WHERE type = ? AND pid = ?").get("claude", process.pid);
             db.close();
             expect(row.updated_at).toBe(now.toISOString());
         });
-        it('returns null when the process row has disappeared', ()=>{
-            expect(registry.togglePin('claude', 999999)).toBeNull();
+        it("returns null when the process row has disappeared", ()=>{
+            expect(registry.togglePin("claude", 999999)).toBeNull();
         });
-        it('preserves a pin when poll registration updates the row', ()=>{
+        it("preserves a pin when poll registration updates the row", ()=>{
             registry.register(makeEntry({
-                sessionId: 'before'
+                sessionId: "before"
             }));
-            registry.togglePin('claude', process.pid);
+            registry.togglePin("claude", process.pid);
             registry.register(makeEntry({
-                sessionId: 'after'
+                sessionId: "after"
             }));
-            expect(registry.lookup('agent1')).toMatchObject({
-                sessionId: 'after',
+            expect(registry.lookup("agent1")).toMatchObject({
+                sessionId: "after",
                 pinned: true
             });
         });
-        it('preserves a pin through rename', ()=>{
+        it("preserves a pin through rename", ()=>{
             registry.register(makeEntry({
-                name: 'before'
+                name: "before"
             }));
-            registry.togglePin('claude', process.pid);
-            registry.rename('before', 'after');
-            expect(registry.lookup('after')?.pinned).toBe(true);
+            registry.togglePin("claude", process.pid);
+            registry.rename("before", "after");
+            expect(registry.lookup("after")?.pinned).toBe(true);
         });
-        it('removes the pin with a pruned process row', ()=>{
+        it("removes the pin with a pruned process row", ()=>{
             registry.register(makeEntry({
                 pid: 999999
             }));
-            registry.togglePin('claude', 999999);
+            registry.togglePin("claude", 999999);
             registry.prune();
-            expect(registry.lookup('agent1')).toBeNull();
+            expect(registry.lookup("agent1")).toBeNull();
         });
-        it('reports a clear error when a readonly registry toggles a pin', ()=>{
+        it("reports a clear error when a readonly registry toggles a pin", ()=>{
             registry.register(makeEntry());
             const readonlyRegistry = new AgentRegistry(regPath, {
                 readonly: true
             });
-            expect(()=>readonlyRegistry.togglePin('claude', process.pid)).toThrow(/readonly/i);
+            expect(()=>readonlyRegistry.togglePin("claude", process.pid)).toThrow(/readonly/i);
         });
     });
-    describe('list', ()=>{
-        it('returns empty array when database does not contain entries', ()=>{
+    describe("list", ()=>{
+        it("returns empty array when database does not contain entries", ()=>{
             expect(registry.list()).toEqual([]);
         });
-        it('ignores existing legacy agents.json entries', ()=>{
+        it("ignores existing legacy agents.json entries", ()=>{
             const legacyEntry = makeEntry({
-                name: 'legacy',
-                tmuxSession: 'legacy'
+                name: "legacy",
+                runtimeRef: {
+                    session: "legacy"
+                }
             });
             fs.mkdirSync(path.dirname(regPath), {
                 recursive: true
@@ -311,63 +376,108 @@ describe('AgentRegistry', ()=>{
                 entries: [
                     legacyEntry
                 ]
-            }), 'utf8');
+            }), "utf8");
             const legacyRegistry = new AgentRegistry(regPath);
-            expect(legacyRegistry.lookup('legacy')).toBeNull();
+            expect(legacyRegistry.lookup("legacy")).toBeNull();
             expect(legacyRegistry.list()).toEqual([]);
-            expect(fs.existsSync(regPath.replace(/\.json$/, '.db'))).toBe(true);
+            expect(fs.existsSync(regPath.replace(/\.json$/, ".db"))).toBe(true);
+        });
+        it("reads pre-runtime SQLite rows as tmux-backed records", ()=>{
+            const dbPath = regPath.replace(/\.json$/, ".db");
+            fs.mkdirSync(path.dirname(dbPath), {
+                recursive: true
+            });
+            fs.rmSync(dbPath, {
+                force: true
+            });
+            fs.rmSync(`${dbPath}-wal`, {
+                force: true
+            });
+            fs.rmSync(`${dbPath}-shm`, {
+                force: true
+            });
+            const db = new Database(dbPath);
+            db.exec(`
+                CREATE TABLE agents (
+                    type TEXT NOT NULL,
+                    pid INTEGER NOT NULL,
+                    name TEXT NOT NULL UNIQUE,
+                    tmux_session TEXT NOT NULL DEFAULT '',
+                    cwd TEXT NOT NULL DEFAULT '',
+                    started_at TEXT NOT NULL,
+                    session_id TEXT NOT NULL DEFAULT '',
+                    session_file_path TEXT NOT NULL DEFAULT '',
+                    updated_at TEXT NOT NULL,
+                    PRIMARY KEY (type, pid)
+                );
+                INSERT INTO agents (
+                    type, pid, name, tmux_session, cwd, started_at, session_id, session_file_path, updated_at
+                ) VALUES (
+                    'claude', ${process.pid}, 'legacy-sqlite', 'legacy-sqlite', '/tmp',
+                    '2026-05-30T00:00:00.000Z', 'sid-1', '/tmp/session.jsonl', '2026-05-30T00:00:00.000Z'
+                );
+                PRAGMA user_version = 1;
+            `);
+            db.close();
+            const migratedRegistry = new AgentRegistry(regPath);
+            expect(migratedRegistry.lookup("legacy-sqlite")).toMatchObject({
+                runtime: "tmux",
+                runtimeRef: {
+                    session: "legacy-sqlite"
+                }
+            });
         });
     });
-    describe('isAlive', ()=>{
-        it('returns true for the current process', ()=>{
+    describe("isAlive", ()=>{
+        it("returns true for the current process", ()=>{
             expect(registry.isAlive(makeEntry({
                 pid: process.pid
             }))).toBe(true);
         });
-        it('returns false for a PID that does not exist', ()=>{
+        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'
+        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'
+        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');
+        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', ()=>{
-        it('removes entries whose PIDs are dead', ()=>{
+    describe("prune", ()=>{
+        it("removes entries whose PIDs are dead", ()=>{
             registry.register(makeEntry({
-                name: 'alive',
+                name: "alive",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'dead',
+                name: "dead",
                 pid: 999999
             }));
             registry.prune();
             const remaining = registry.list();
             expect(remaining).toHaveLength(1);
-            expect(remaining[0].name).toBe('alive');
+            expect(remaining[0].name).toBe("alive");
         });
-        it('is a no-op when all entries are alive', ()=>{
+        it("is a no-op when all entries are alive", ()=>{
             registry.register(makeEntry({
                 pid: process.pid
             }));
@@ -376,133 +486,141 @@ describe('AgentRegistry', ()=>{
             const after = registry.list();
             expect(after).toEqual(before);
         });
-        it('preserves entries when liveness probing fails with EPERM', ()=>{
+        it("preserves entries when liveness probing fails with EPERM", ()=>{
             registry.register(makeEntry({
-                name: 'custom-name',
-                tmuxSession: 'tmux-custom'
+                name: "custom-name",
+                runtimeRef: {
+                    session: "tmux-custom"
+                }
             }));
-            vi.spyOn(process, 'kill').mockImplementation(()=>{
-                throw Object.assign(new Error('operation not permitted'), {
-                    code: 'EPERM'
+            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'
+            expect(registry.lookup("custom-name")).toMatchObject({
+                name: "custom-name",
+                runtimeRef: {
+                    session: "tmux-custom"
+                }
             });
         });
-        it('removes entries when liveness probing fails with ESRCH', ()=>{
+        it("removes entries when liveness probing fails with ESRCH", ()=>{
             registry.register(makeEntry({
-                name: 'dead'
+                name: "dead"
             }));
-            vi.spyOn(process, 'kill').mockImplementation(()=>{
-                throw Object.assign(new Error('no such process'), {
-                    code: 'ESRCH'
+            vi.spyOn(process, "kill").mockImplementation(()=>{
+                throw Object.assign(new Error("no such process"), {
+                    code: "ESRCH"
                 });
             });
             registry.prune();
-            expect(registry.lookup('dead')).toBeNull();
+            expect(registry.lookup("dead")).toBeNull();
         });
-        it('does nothing when file is missing', ()=>{
+        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');
+        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',
+                name: "forced",
                 pid: process.pid
             }));
-            const alive = vi.spyOn(clocked, 'isAlive').mockReturnValue(true);
+            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();
+            expect(clocked.lookup("forced")).toBeNull();
         });
     });
-    describe('default()', ()=>{
-        it('returns a singleton instance', ()=>{
+    describe("default()", ()=>{
+        it("returns a singleton instance", ()=>{
             expect(AgentRegistry.default()).toBe(AgentRegistry.default());
         });
     });
-    describe('rename', ()=>{
-        it('updates the name of an existing entry', ()=>{
+    describe("rename", ()=>{
+        it("updates the name of an existing entry", ()=>{
             registry.register(makeEntry({
-                name: 'old-name',
+                name: "old-name",
                 pid: process.pid
             }));
-            registry.rename('old-name', 'new-name');
-            expect(registry.lookup('new-name')?.name).toBe('new-name');
-            expect(registry.lookup('old-name')).toBeNull();
+            registry.rename("old-name", "new-name");
+            expect(registry.lookup("new-name")?.name).toBe("new-name");
+            expect(registry.lookup("old-name")).toBeNull();
         });
-        it('preserves all other fields on the renamed entry', ()=>{
+        it("preserves all other fields on the renamed entry", ()=>{
             registry.register(makeEntry({
-                name: 'old-name',
+                name: "old-name",
                 pid: process.pid,
-                tmuxSession: 'old-name',
-                cwd: '/my/cwd'
-            }));
-            registry.rename('old-name', 'new-name');
-            const entry = registry.lookup('new-name');
-            expect(entry?.tmuxSession).toBe('old-name');
-            expect(entry?.cwd).toBe('/my/cwd');
+                runtimeRef: {
+                    session: "old-name"
+                },
+                cwd: "/my/cwd"
+            }));
+            registry.rename("old-name", "new-name");
+            const entry = registry.lookup("new-name");
+            expect(entry?.runtimeRef).toEqual({
+                session: "old-name"
+            });
+            expect(entry?.cwd).toBe("/my/cwd");
             expect(entry?.pid).toBe(process.pid);
         });
-        it('throws RenameNotFoundError when current name does not exist', ()=>{
-            expect(()=>registry.rename('ghost', 'new-name')).toThrow(RenameNotFoundError);
+        it("throws RenameNotFoundError when current name does not exist", ()=>{
+            expect(()=>registry.rename("ghost", "new-name")).toThrow(RenameNotFoundError);
         });
-        it('throws RenameConflictError when new name is already in use by a live entry', ()=>{
+        it("throws RenameConflictError when new name is already in use by a live entry", ()=>{
             registry.register(makeEntry({
-                name: 'agent-a',
+                name: "agent-a",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'agent-b',
+                name: "agent-b",
                 pid: process.ppid
             }));
-            expect(()=>registry.rename('agent-a', 'agent-b')).toThrow(RenameConflictError);
+            expect(()=>registry.rename("agent-a", "agent-b")).toThrow(RenameConflictError);
         });
-        it('throws RenameConflictError when the conflicting entry probe fails with EPERM', ()=>{
+        it("throws RenameConflictError when the conflicting entry probe fails with EPERM", ()=>{
             registry.register(makeEntry({
-                name: 'agent-a',
+                name: "agent-a",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'agent-b',
+                name: "agent-b",
                 pid: process.ppid
             }));
-            vi.spyOn(process, 'kill').mockImplementation(()=>{
-                throw Object.assign(new Error('operation not permitted'), {
-                    code: 'EPERM'
+            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);
+            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', ()=>{
+        it("succeeds when new name exists only as a stale (dead) entry", ()=>{
             registry.register(makeEntry({
-                name: 'agent-a',
+                name: "agent-a",
                 pid: process.pid
             }));
             registry.register(makeEntry({
-                name: 'agent-b',
+                name: "agent-b",
                 pid: 999999
             }));
-            expect(()=>registry.rename('agent-a', 'agent-b')).not.toThrow();
-            expect(registry.lookup('agent-b')?.pid).toBe(process.pid);
+            expect(()=>registry.rename("agent-a", "agent-b")).not.toThrow();
+            expect(registry.lookup("agent-b")?.pid).toBe(process.pid);
         });
-        it('does not create the legacy fixed .tmp path on rename', ()=>{
+        it("does not create the legacy fixed .tmp path on rename", ()=>{
             registry.register(makeEntry({
-                name: 'old-name',
+                name: "old-name",
                 pid: process.pid
             }));
-            registry.rename('old-name', 'new-name');
+            registry.rename("old-name", "new-name");
             expect(fs.existsSync(`${regPath}.tmp`)).toBe(false);
         });
     });