fix: use tmux metadata handle for reliable active session status (#449)

Treat persisted tmuxName as metadata-derived runtime identity when runtimeHandle is missing so active sessions are not misclassified as exited/unknown across agents.

Author: harsh-batheja

packages/core/src/__tests__/session-manager.test.ts

@@ -34,6 +34,7 @@ import {
   type Tracker,
   type SCM,
   type RuntimeHandle,
+  type Session,
 } from "../types.js";
 
 let tmpDir: string;
@@ -1387,6 +1388,89 @@ describe("list", () => {
     expect(sessions[0].activity).toBe("active");
   });
 
+  it.each(["claude-code", "codex", "aider", "opencode"])(
+    "uses tmuxName fallback handle for %s activity detection when runtimeHandle is missing",
+    async (agentName: string) => {
+      const expectedTmuxName = "hash-app-1";
+      const selectedAgent: Agent = {
+        ...mockAgent,
+        name: agentName,
+        getActivityState: vi.fn().mockImplementation(async (session: Session) => {
+          return {
+            state: session.runtimeHandle?.id === expectedTmuxName ? "active" : "exited",
+          };
+        }),
+      };
+      const registryWithNamedAgents: PluginRegistry = {
+        ...mockRegistry,
+        get: vi.fn().mockImplementation((slot: string, name: string) => {
+          if (slot === "runtime") return mockRuntime;
+          if (slot === "agent" && name === agentName) return selectedAgent;
+          if (slot === "workspace") return mockWorkspace;
+          return null;
+        }),
+      };
+
+      writeMetadata(sessionsDir, "app-1", {
+        worktree: "/tmp",
+        branch: "a",
+        status: "working",
+        project: "my-app",
+        agent: agentName,
+        tmuxName: expectedTmuxName,
+        ...(agentName === "opencode" ? { opencodeSessionId: "ses_existing_mapping" } : {}),
+      });
+
+      const sm = createSessionManager({ config, registry: registryWithNamedAgents });
+      const sessions = await sm.list("my-app");
+
+      expect(sessions).toHaveLength(1);
+      expect(sessions[0].runtimeHandle?.id).toBe(expectedTmuxName);
+      expect(sessions[0].activity).toBe("active");
+      expect(selectedAgent.getActivityState).toHaveBeenCalled();
+    },
+  );
+
+  it("uses tmuxName fallback handle for runtime liveness checks when runtimeHandle is missing", async () => {
+    const expectedTmuxName = "hash-app-1";
+    const deadRuntime: Runtime = {
+      ...mockRuntime,
+      isAlive: vi
+        .fn()
+        .mockImplementation(async (handle: RuntimeHandle) => handle.id !== expectedTmuxName),
+    };
+    const agentWithSpy: Agent = {
+      ...mockAgent,
+      getActivityState: vi.fn().mockResolvedValue({ state: "active" }),
+    };
+    const registryWithDeadRuntime: PluginRegistry = {
+      ...mockRegistry,
+      get: vi.fn().mockImplementation((slot: string) => {
+        if (slot === "runtime") return deadRuntime;
+        if (slot === "agent") return agentWithSpy;
+        if (slot === "workspace") return mockWorkspace;
+        return null;
+      }),
+    };
+
+    writeMetadata(sessionsDir, "app-1", {
+      worktree: "/tmp",
+      branch: "a",
+      status: "working",
+      project: "my-app",
+      tmuxName: expectedTmuxName,
+    });
+
+    const sm = createSessionManager({ config, registry: registryWithDeadRuntime });
+    const sessions = await sm.list("my-app");
+
+    expect(sessions).toHaveLength(1);
+    expect(sessions[0].runtimeHandle?.id).toBe(expectedTmuxName);
+    expect(sessions[0].status).toBe("killed");
+    expect(sessions[0].activity).toBe("exited");
+    expect(agentWithSpy.getActivityState).not.toHaveBeenCalled();
+  });
+
   it("keeps existing activity when getActivityState throws", async () => {
     const agentWithError: Agent = {
       ...mockAgent,

packages/core/src/session-manager.ts

@@ -794,13 +794,22 @@ export function createSessionManager(deps: SessionManagerDeps): OpenCodeSessionM
       sessionListPromise,
     );
 
-    const handleFromMetadata = session.runtimeHandle !== null;
+    const tmuxNameFromMetadata = session.metadata["tmuxName"]?.trim();
+    const hasTmuxNameFromMetadata =
+      typeof tmuxNameFromMetadata === "string" && tmuxNameFromMetadata.length > 0;
+    const handleFromMetadata = session.runtimeHandle !== null || hasTmuxNameFromMetadata;
     if (!handleFromMetadata) {
       session.runtimeHandle = {
         id: sessionName,
         runtimeName: project.runtime ?? config.defaults.runtime,
         data: {},
       };
+    } else if (!session.runtimeHandle && hasTmuxNameFromMetadata) {
+      session.runtimeHandle = {
+        id: tmuxNameFromMetadata,
+        runtimeName: project.runtime ?? config.defaults.runtime,
+        data: {},
+      };
     }
     await enrichSessionWithRuntimeState(session, plugins, handleFromMetadata);
   }