bug(pi): gentle-engram session_shutdown never closes the store-side session — Pi rows leak ended_at NULL (1.1% closed)

[ElCaaarnal]

📝 Bug Description

The Pi adapter (plugin/pi/index.ts, published as gentle-engram) creates a sessions row on session_start but never closes it. Its session_shutdown handler clears three in-memory maps and returns; it never calls POST /sessions/{id}/end.

On main today (f60fd0b6):

// plugin/pi/index.ts:1331
pi.on("session_shutdown", async (_event: unknown, ctx: SessionContext) => {
  const sessionId = observeRuntimeSessionID(ctx);
  if (!sessionId) return;
  toolCounts.delete(sessionId);
  forgetKnownSession(sessionId);
  forgetSelfHealContext(sessionId);
});

Grepping /end across that file returns exactly one hit — line 1180, inside the mem_session_end tool handler. So closure is reachable only when the model voluntarily calls the tool; there is no lifecycle path.

This is the same defect class as #1083 (OpenCode), #1118 (Claude Code) and #48, and it produces the failure in #1101. Pi is the client that every one of those audits missed:

Issue	Clients in scope	Pi included?
#48	Claude Code, OpenCode, Gemini CLI, Codex	No — absent from the table
#1118	plugin/claude-code vs plugin/codex	No
#1131 (open)	OpenCode	No — Agent / Client: OpenCode

This repeats the pattern #1031 called out: a defect fixed for one client while another keeps reproducing it.

Pi's own extension documentation states the contract being violated: "Register an idempotent session_shutdown handler to close any session-scoped resources you start." The adapter registers the handler, so it is aware of the contract, and then closes nothing store-side.

Side note: this form's Agent / Client dropdown has no Pi option, which is arguably the same blind spot in reporting form.

🔄 Steps to Reproduce

1. Use Pi with the gentle-engram package (npm:gentle-engram@0.1.12, current latest).
2. Start a Pi session in a project directory, then exit it cleanly so session_shutdown fires.
3. Repeat at least twice in the same directory.
4. Query the store:

   SELECT id, started_at, ended_at FROM sessions
   WHERE directory = '<project-dir>' AND ended_at IS NULL;

5. Observe every Pi row still has ended_at IS NULL.
6. Call mem_save without an explicit session_id from that directory.

Pi session ids are UUIDv7 (01a0…), which makes them easy to separate from Claude Code's UUIDv4 rows when auditing.

✅ Expected Behavior

The session_shutdown handler should close the store-side session, mirroring what plugin/codex/scripts/session-end.sh does for Codex — i.e. POST /sessions/{id}/end for the shutting-down session id, idempotent as Pi's docs require, before the in-memory cleanup.

❌ Actual Behavior

Pi rows accumulate with ended_at = NULL indefinitely. Measured closure rate by client on one store, for sessions started after 2026-08-01, bucketed by session-id shape:

Client (id shape)	Sessions	Closed
Claude Code (UUIDv4)	196	61.2%
Manually named	195	45.1%
Pi / OpenCode (UUIDv7 01a0*)	176	1.1%
engram-generated (ses_*)	69	0%

Store-wide this reached 1996 of 2380 rows open (84%), and a single project directory accumulated 16 open rows, which made mem_save fail closed until the rows were closed manually via POST /sessions/{id}/end.

Operating System

macOS

Engram Version

2.0.0-rc.9

Agent / Client

Other

📋 Relevant Logs

multiple active runtime sessions match the current project and directory; provide session_id or end other active matching sessions before retrying

💡 Additional Context

Verified the defect is in the published package, not in one local install:

• Installed gentle-engram is 0.1.12, which is npm latest.
• The installed index.ts is byte-identical to a pristine npm pack gentle-engram@0.1.12 tarball — SHA256 96dc8896c4dbdc5433eacb8c4a519df63fcab14f21d6398b96bcb87f015b006a for both.
• The same handler is present in the pristine tarball, in plugin/pi/index.ts at ebf1228, and on main at f60fd0b6. It is not fixed upstream.
• gentle-pi (main) contains no reference to closing engram sessions, so nothing else compensates.

Two related observations, both consistent with #1131's expected-behavior points 1 and 2 rather than new claims:

• ActiveRuntimeSessions applies no recency bound and no live-process check, so a single unclosed row is permanent. That is documented intent ("rejects ambiguity rather than selecting by recency"), but it means any client that leaks one row eventually hard-fails mem_save for that directory.
• engram doctor does not flag orphaned ended_at IS NULL rows whose owning process is gone. During this investigation it reported the affected project as ok on every session check while mem_save was failing.

One further data point for whoever picks this up: two rows could not be closed through the HTTP route at all and still hold real observations (46 and 3). One has an empty id, the other has id manual-save-/ with project /; both break the /sessions/{id}/end path. These look like the residue of #630.

[emersonheto]

Second occurrence on a newer build, plus a verified fix

Same defect, different store, newer build than the report: engram 2.0.0-rc.11 (report used rc.9), gentle-engram@0.1.12 confirmed as npm latest, macOS arm64, client Pi. It still reproduces.

Observed: one project directory had accumulated 22 ended_at IS NULL rows, all Pi UUIDv7 (01a0…). mem_save_prompt with no explicit session binding failed closed with the message quoted in this report, while calls that carry an explicit session id kept working — which is what isolated the failure to the unbound selection rather than to the store.

The fix works — verified, and no published release contains it

Confirmed nothing to upgrade to: 0.1.12 is npm latest and the installed file is that version. Applied the change this issue proposes to the installed package, placed after the existing in-memory cleanup with the session id captured first (the ordering proposed here is equivalent), reusing the adapter's own best-effort helper:

await bestEffortEngramFetch(`/sessions/${encodeURIComponent(sessionId)}/end`, {
  method: "POST",
  body: { summary: "Closed by gentle-engram on Pi session shutdown." },
});

End-to-end evidence. With the patch applied, a headless pi -p "<prompt>" run in a pinned project directory produced a store row that was open at registration and closed six seconds later:

id	started_at	ended_at	summary
01a09bdb-…	17:41:21	17:41:26	Closed by gentle-engram on Pi session shutdown.

That also confirms Pi does await an async session_shutdown handler on a clean exit, so the closure actually reaches the server rather than being dropped at process teardown.

Suite. node --test test/*.test.mjs in the installed package: 108 pass / 2 fail. Both failures are environmental — test/package-contract.test.mjs and test/publish-workflow.test.mjs read .github/workflows/publish-pi.yml from a path that only exists in a source checkout. Verified A/B: restoring the pristine index.ts reproduces the identical two failures, so the patch adds none. test/native-tool-contract.test.mjs, which exercises the session hooks, passes.

Why closing on shutdown is safe (the resume question a maintainer will ask)

Two properties I checked before applying it, since "close on shutdown" invites a resume problem:

1. A closed session still accepts writes bound by an explicit session_id. POST /prompts against an already-closed session returned 201 {"status":"saved"} (probe row deleted after the check). ended_at only removes the row from the unbound candidate set; it does not lock the session.
2. There is no reopen route. POST /sessions with an existing closed id returns 201 {"status":"created"} but leaves ended_at unchanged, and the only session routes are GET /sessions, POST /sessions, POST /sessions/{id}/end, DELETE /sessions/{id}. A resumed Pi session therefore stays closed. Harmless per (1), but it means that session can never be selected by the unbound path again. Worth deciding on purpose rather than by omission — this may be the same surface as the closed bug(mcp): mem_session_start reports success on an already-ended session id without reopening it #972.

Operational counterpart

The reaper that this issue's Additional Context implies now exists as a small script, and it is how I cleared the backlog. It reads ended_at IS NULL rows read-only, enumerates live pi processes (ps -Ao pid=,comm=, then lsof -a -p <pid> -d cwd -Fn), and takes a process's current session to be the newest active row in that directory whose Pi session file was created at or after the process start.

Two liveness notes that may be useful if you build this into doctor:

• The Pi session file name embeds both the id and the UTC creation instant (<ISO>-<ms>Z_<session-id>.jsonl), which maps process → session more reliably than the row's own started_at: registration lags the process start by 40 seconds to 3 minutes.
• mtime is useless as a liveness signal, and so is lsof on the session file: Pi opens and closes the JSONL per turn, so an idle-but-live session holds no handle and writes nothing.

Result here: 110 orphan rows closed with no data loss (observations identical before and after, 10034 → 10034), active rows 177 → 67, and zero (project, directory) pairs left with more than one active row. Note POST /sessions/{id}/end returns 200 even for a nonexistent id, so the HTTP status alone does not prove the row existed — the verification has to read ended_at back.

Two smaller observations, both implied by this issue

• observeRuntimeSessionID sets runtimeSessionIdentityAmbiguous = true on seeing a second distinct session id and never clears it. A Pi process whose session id changes mid-process therefore keeps soleActiveRuntimeSessionID() undefined for the rest of its life. Observed: one process held two ids 40 minutes apart, and the earlier one is exactly one of the leaked rows — so the leak also happens without any process exit.
• engram doctor reported the affected store healthy on every session check while the unbound save was failing, matching what the report observed.

State preserved: read-only status and doctor calls, plus the POST /sessions/{id}/end closures described above. No review or SDD authority was touched, and no artifact was rewritten. No private project names, absolute paths, usernames, hostnames, credentials, diffs, or source contents are included.