refactor: remove status from recordConfig, add design proposal

- recordConfig no longer writes lastStatus (handled by applySnapshot only)
- Add warning if recordConfig called before snapshot exists
- Update tests to reflect new separation of concerns
- Add AGENT_REFACTOR_PROPOSAL.md with comprehensive design plan

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

packages/server/src/server/agent/agent-registry.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, beforeEach, afterEach } from "vitest";
+import { describe, expect, test, beforeEach, afterEach, vi } from "vitest";
 import os from "node:os";
 import path from "node:path";
 import { mkdtempSync, rmSync, writeFileSync, readFileSync } from "node:fs";
@@ -50,6 +50,15 @@ describe("AgentRegistry", () => {
   });
 
   test("persists configs and snapshot metadata", async () => {
+    await registry.applySnapshot(
+      createSnapshot({
+        id: "agent-1",
+        cwd: "/tmp/project",
+        currentModeId: "coding",
+        status: "idle",
+      })
+    );
+
     await registry.recordConfig(
       "agent-1",
       "claude",
@@ -61,14 +70,6 @@ describe("AgentRegistry", () => {
       }
     );
 
-    await registry.applySnapshot(
-      createSnapshot({
-        id: "agent-1",
-        currentModeId: "coding",
-        status: "idle",
-      })
-    );
-
     const records = await registry.list();
     expect(records).toHaveLength(1);
     const [record] = records;
@@ -102,7 +103,8 @@ describe("AgentRegistry", () => {
     expect(persisted?.title).toBe("Fix Login Bug");
   });
 
-  test("recordConfig seeds lastModeId before snapshots", async () => {
+  test("recordConfig warns if no snapshot exists", async () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     await registry.recordConfig(
       "agent-3",
       "claude",
@@ -113,7 +115,9 @@ describe("AgentRegistry", () => {
     );
 
     const record = await registry.get("agent-3");
-    expect(record?.lastModeId).toBe("plan");
+    expect(record).toBeNull();
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
   });
 
   test("recovers from trailing garbage in agents.json", async () => {

packages/server/src/server/agent/agent-registry.ts

@@ -110,27 +110,26 @@ export class AgentRegistry {
     config?: SerializableAgentConfig
   ): Promise<void> {
     await this.load();
-    const now = new Date().toISOString();
     const existing = this.cache.get(agentId);
-    const sanitizedConfig = config ? sanitizeConfig(config) : existing?.config;
+    if (!existing) {
+      console.warn(
+        `[AgentRegistry] Cannot record config for ${agentId} because no snapshot has been persisted yet`
+      );
+      return;
+    }
+
+    const now = new Date().toISOString();
+    const sanitizedConfig = config ? sanitizeConfig(config) : existing.config;
     const nextModeId =
-      config?.modeId ??
-      existing?.lastModeId ??
-      sanitizedConfig?.modeId ??
-      null;
+      config?.modeId ?? existing.lastModeId ?? sanitizedConfig?.modeId ?? null;
+
     const updated: StoredAgentRecord = {
-      id: agentId,
+      ...existing,
       provider,
       cwd,
-      createdAt: existing?.createdAt ?? now,
       updatedAt: now,
-      lastActivityAt: existing?.lastActivityAt ?? existing?.updatedAt ?? now,
-      lastUserMessageAt: existing?.lastUserMessageAt ?? null,
-      title: existing?.title ?? null,
-      lastStatus: existing?.lastStatus ?? "closed",
       lastModeId: nextModeId,
       config: sanitizedConfig,
-      persistence: existing?.persistence ?? null,
     };
     this.cache.set(agentId, updated);
     await this.flush();