fix(session): gate terminal session-end write behind an explicit final flag

README.md

@@ -1618,7 +1618,7 @@ Create `~/.agentmemory/.env`:
 |--------|------|-------------|
 | `GET` | `/agentmemory/health` | Health check (always public) |
 | `POST` | `/agentmemory/session/start` | Start session + get context |
-| `POST` | `/agentmemory/session/end` | End session |
+| `POST` | `/agentmemory/session/end` | End session (pass `final: true` for genuine termination — a per-turn call without it leaves the session marked active) |
 | `POST` | `/agentmemory/observe` | Capture observation |
 | `POST` | `/agentmemory/smart-search` | Hybrid search |
 | `POST` | `/agentmemory/context` | Generate context |

integrations/hermes/__init__.py

@@ -383,8 +383,14 @@ def sync_turn(self, user: str, assistant: str, **kwargs: Any) -> None:
         })
 
     def on_session_end(self, messages: list, **kwargs: Any) -> None:
+        # #745: this fires at genuine session end (not per-turn), so set
+        # final=True or the session would sit "active" forever and could
+        # trip the stale-session diagnostic - same fix already applied to
+        # every other first-party integration (src/hooks/session-end.ts,
+        # plugin/opencode/agentmemory-capture.ts, integrations/pi).
         _api(self._base, "session/end", {
             "sessionId": kwargs.get("session_id", self._session_id),
+            "final": True,
         })
 
     def on_pre_compress(self, messages: list, **kwargs: Any) -> None:

integrations/pi/index.ts

@@ -394,8 +394,11 @@ export default function agentmemoryExtension(pi: ExtensionAPI) {
     if (event.reason !== "quit") return;
     if (!lastHealthOk || !sessionId) return;
     // session/end already fans out the summary server-side (#1203).
+    // #745: this fires only on a genuine quit (guarded above), not per-turn,
+    // so set final:true or the session would sit "active" forever and could
+    // trip the stale-session diagnostic.
     await callAgentMemory("session/end", {
-      body: { sessionId },
+      body: { sessionId, final: true },
       timeoutMs: 5_000,
     });
     void callAgentMemory("consolidate", { body: {} });

plugin/opencode/agentmemory-capture.ts

@@ -330,7 +330,10 @@ export const AgentmemoryCapturePlugin: Plugin = async (ctx) => {
           if (DEBUG) console.error("[agentmemory] session.deleted with no session ID");
           return;
         }
-        await post("/session/end", { sessionId: sid });
+        // #745: session.deleted is a genuine one-shot session end (not a
+        // per-turn call), so set final:true or the session would sit
+        // "active" forever and could trip the stale-session diagnostic.
+        await post("/session/end", { sessionId: sid, final: true });
         post("/crystals/auto", { olderThanDays: 7 }, 30000);
         post("/consolidate-pipeline", { tier: "all", force: true }, 30000);
         if (sid === activeSessionId) activeSessionId = null;

plugin/scripts/session-end.mjs

@@ -108,7 +108,10 @@ async function main() {
 	fetch(`${REST_URL}/agentmemory/session/end`, {
 		method: "POST",
 		headers: authHeaders(),
-		body: JSON.stringify({ sessionId }),
+		body: JSON.stringify({
+			sessionId,
+			final: true
+		}),
 		signal: AbortSignal.timeout(3e4)
 	}).catch(() => {});
 	if (process.env["CLAUDE_MEMORY_BRIDGE"] === "true") fetch(`${REST_URL}/agentmemory/claude-bridge/sync`, {

src/cli.ts

@@ -2892,7 +2892,9 @@ async function seedDemoSession(
     }
   }
 
-  await postJsonStrict(`${base}/agentmemory/session/end`, { sessionId: session.id });
+  // One-shot end, not a per-turn Stop call, so the session does not sit
+  // "active" forever.
+  await postJsonStrict(`${base}/agentmemory/session/end`, { sessionId: session.id, final: true });
   return stored;
 }
 

src/hooks/session-end.ts

@@ -92,10 +92,12 @@ async function main() {
     );
   }
 
+  // Genuine session end, unlike the per-turn Stop hook which posts the
+  // same endpoint without the flag.
   fetch(`${REST_URL}/agentmemory/session/end`, {
     method: "POST",
     headers: authHeaders(),
-    body: JSON.stringify({ sessionId }),
+    body: JSON.stringify({ sessionId, final: true }),
     signal: AbortSignal.timeout(30000),
   }).catch(() => {});
 

src/hooks/stop.ts

@@ -41,6 +41,8 @@ async function main() {
   const sessionId = ((data.session_id || data.sessionId || data.conversation_id) as string) || "unknown";
 
   // session/end already fans out the summary server-side (#1203).
+  // No `final` flag: this fires every turn, so it must not mark the
+  // session completed.
   fetch(`${REST_URL}/agentmemory/session/end`, {
     method: "POST",
     headers: authHeaders(),

src/triggers/api.ts

@@ -657,19 +657,30 @@ export function registerApiTriggers(
   });
 
   sdk.registerFunction("api::session::end",
-    async (req: ApiRequest<{ sessionId: string }>): Promise<Response> => {
-      const sessionId = asNonEmptyString((req.body as Record<string, unknown>)?.sessionId);
+    async (req: ApiRequest<{ sessionId: string; final?: boolean }>): Promise<Response> => {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const sessionId = asNonEmptyString(body.sessionId);
       if (!sessionId) {
         return {
           status_code: 400,
           body: { error: "sessionId is required and must be a non-empty string" },
         };
       }
-      await kv.update(KV.sessions, sessionId, [
-        { type: "set", path: "endedAt", value: new Date().toISOString() },
-        { type: "set", path: "status", value: "completed" },
-      ]);
-      // Fan out session-stopped lifecycle (non-blocking).
+      // The per-turn Stop hook posts this endpoint with the same payload
+      // shape as the real SessionEnd hook, so only an explicit `final`
+      // marks the session completed. Strict `=== true` keeps a truthy
+      // non-boolean from being coerced into a terminal write. An older
+      // plugin that predates the flag simply never marks completed, which
+      // self-heals on update.
+      const final = body.final === true;
+      if (final) {
+        await kv.update(KV.sessions, sessionId, [
+          { type: "set", path: "endedAt", value: new Date().toISOString() },
+          { type: "set", path: "status", value: "completed" },
+        ]);
+      }
+      // Unconditional: summarize, graph extraction and consolidation run
+      // every turn, not only at genuine session end.
       try {
         sdk.trigger({
           function_id: "event::session::stopped",

src/viewer/index.html

@@ -3309,7 +3309,10 @@ <h1>agentmemory</h1>
     }
 
     async function endSession(id) {
-      await apiPost('session/end', { sessionId: id });
+      // #745: the viewer's "End Session" button is an explicit, one-shot
+      // session end, not a per-turn call, so set final:true or the session
+      // would sit "active" forever and could trip the stale-session diagnostic.
+      await apiPost('session/end', { sessionId: id, final: true });
       state.sessions.loaded = false;
       loadSessions();
     }

test/hermes-plugin.test.ts

@@ -68,4 +68,22 @@ describe("Hermes plugin manifest", () => {
       /os\.environ\.setdefault\(\s*["']AGENTMEMORY_URL["']\s*,\s*DEFAULT_BASE_URL\s*\)/,
     );
   });
+
+  // #745: on_session_end fires at genuine session end (not per-turn, unlike
+  // a Stop-hook-style call), so it must set final=True or the session sits
+  // "active" forever and can trip the stale-session diagnostic - the same
+  // fix already applied to every other first-party integration
+  // (src/hooks/session-end.ts, plugin/opencode/agentmemory-capture.ts,
+  // integrations/pi/index.ts). This is a structural (source-regex) test,
+  // not a behavioural one, matching the idiom test/evict.test.ts's
+  // "eviction scheduling" describe block uses for the same reason: no
+  // Python runtime is available to exercise the plugin directly here.
+  it("marks the session/end call final on genuine session end", () => {
+    const source = readFileSync("integrations/hermes/__init__.py", "utf8");
+    const match = source.match(
+      /def on_session_end\(self,[^)]*\)[^:]*:\n((?:.*\n)*?)\n {4}def /,
+    );
+    expect(match).not.toBeNull();
+    expect(match![1]).toMatch(/"final":\s*True/);
+  });
 });

test/integration.test.ts

@@ -82,10 +82,12 @@ describe("agentmemory integration", () => {
     });
 
     it("ends the session", async () => {
+      // #745: only final:true marks the session completed; a plain
+      // per-turn-shaped post no longer does.
       const res = await fetch(url("/agentmemory/session/end"), {
         method: "POST",
         headers: authHeaders(),
-        body: JSON.stringify({ sessionId: SESSION_ID }),
+        body: JSON.stringify({ sessionId: SESSION_ID, final: true }),
       });
       expect(res.status).toBe(200);
       const body = (await json(res)) as { success: boolean };
@@ -123,7 +125,7 @@ describe("agentmemory integration", () => {
       await fetch(url("/agentmemory/session/end"), {
         method: "POST",
         headers: authHeaders(),
-        body: JSON.stringify({ sessionId: OBS_SESSION }),
+        body: JSON.stringify({ sessionId: OBS_SESSION, final: true }),
       });
     });
 

test/session-end-final-flag.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+  logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { registerApiTriggers } from "../src/triggers/api.js";
+import { KV } from "../src/state/schema.js";
+import { mockKV, mockSdk } from "./helpers/mocks.js";
+import type { Session } from "../src/types.js";
+
+// #745: Claude Code fires Stop at the end of EVERY assistant turn, not only
+// at genuine session end, and the Stop hook posts to the same
+// /agentmemory/session/end endpoint as the real SessionEnd hook, with the
+// same payload shape. Writing endedAt + status:"completed" unconditionally
+// there marked every live session terminated on every turn, producing
+// phantom "abandoned session" diagnostics. The terminal write is now gated
+// on an explicit `final: true` flag that only the genuine SessionEnd hook
+// sends; the per-turn Stop hook does not, and event::session::stopped keeps
+// firing unconditionally on both so summarize/graph/consolidation still run
+// every turn.
+describe("api::session::end final flag (#745)", () => {
+  function seedSession(kv: ReturnType<typeof mockKV>, id = "s1") {
+    return kv.set(KV.sessions, id, {
+      id,
+      project: "p",
+      cwd: "/tmp",
+      startedAt: new Date().toISOString(),
+      status: "active",
+      observationCount: 3,
+    } satisfies Session);
+  }
+
+  it("a post without `final` does not write endedAt/status but still fans out event::session::stopped", async () => {
+    const kv = mockKV();
+    await seedSession(kv);
+    const sdk = mockSdk();
+    const stopped = vi.fn(async () => ({ success: true }));
+    sdk.registerFunction("event::session::stopped", stopped);
+    registerApiTriggers(sdk as never, kv as never);
+
+    const handler = sdk.fns.get("api::session::end")!;
+    const res = (await handler({ body: { sessionId: "s1" } } as never)) as {
+      status_code: number;
+    };
+    expect(res.status_code).toBe(200);
+
+    const session = await kv.get<Session>(KV.sessions, "s1");
+    expect(session?.status).toBe("active");
+    expect(session?.endedAt).toBeUndefined();
+
+    // Fan-out is fire-and-forget (not awaited by the handler); flush microtasks.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(stopped).toHaveBeenCalledWith({ sessionId: "s1" });
+  });
+
+  it("a post with final: true writes endedAt/status and still fans out event::session::stopped", async () => {
+    const kv = mockKV();
+    await seedSession(kv);
+    const sdk = mockSdk();
+    const stopped = vi.fn(async () => ({ success: true }));
+    sdk.registerFunction("event::session::stopped", stopped);
+    registerApiTriggers(sdk as never, kv as never);
+
+    const handler = sdk.fns.get("api::session::end")!;
+    const res = (await handler({
+      body: { sessionId: "s1", final: true },
+    } as never)) as { status_code: number };
+    expect(res.status_code).toBe(200);
+
+    const session = await kv.get<Session>(KV.sessions, "s1");
+    expect(session?.status).toBe("completed");
+    expect(session?.endedAt).toBeDefined();
+
+    await new Promise((r) => setTimeout(r, 0));
+    expect(stopped).toHaveBeenCalledWith({ sessionId: "s1" });
+  });
+
+  it.each([["true" /* string */], [1], [{}], [[]], [null]])(
+    "a non-boolean final (%j) does not trigger the terminal write",
+    async (finalValue) => {
+      const kv = mockKV();
+      await seedSession(kv);
+      const sdk = mockSdk();
+      sdk.registerFunction("event::session::stopped", async () => ({ success: true }));
+      registerApiTriggers(sdk as never, kv as never);
+
+      const handler = sdk.fns.get("api::session::end")!;
+      const res = (await handler({
+        body: { sessionId: "s1", final: finalValue },
+      } as never)) as { status_code: number };
+      expect(res.status_code).toBe(200);
+
+      const session = await kv.get<Session>(KV.sessions, "s1");
+      expect(session?.status).toBe("active");
+      expect(session?.endedAt).toBeUndefined();
+    },
+  );
+});

test/session-end-triggers-graph.test.ts

@@ -12,9 +12,14 @@ import { readFileSync } from "node:fs";
 describe("api::session::end → event::session::stopped (#666)", () => {
   const api = readFileSync("src/triggers/api.ts", "utf-8");
 
-  it("api::session::end fires event::session::stopped after kv.update", () => {
+  // #745: the kv.update(KV.sessions ...) terminal write is now conditional
+  // on `final === true` (see test/session-end-final-flag.test.ts), so this
+  // assertion no longer demands kv.update be unconditional -- only that
+  // api::session::end still fans out to event::session::stopped, which is
+  // the actual #666 intent this test encodes.
+  it("api::session::end fires event::session::stopped", () => {
     expect(api).toMatch(
-      /api::session::end[\s\S]*?kv\.update\(KV\.sessions[\s\S]*?function_id:\s*"event::session::stopped"/,
+      /api::session::end[\s\S]*?function_id:\s*"event::session::stopped"/,
     );
   });