[saucam]

Closes #451.

Summary

A session left idle for 30 minutes (configurable) now has its backend process, and everything that process started (MCP servers, commands still running), stopped. The next message starts it again and resumes the same conversation. Before, every session that had run a turn kept them for the daemon's whole lifetime.

What was wrong

codeoid only ever stopped a session's backend when its account changed. So the Claude CLI (or codex, pi, the Gemini CLI, Qwen) and every MCP server it launched (Jira, Confluence, Bitbucket, Teams, memory, …) stayed running for every session ever used. Memory grew with the number of sessions touched, not the number working.

Why it matters

On a 32 GB Mac, thirteen Claude processes, most idle for 12 hours to a day and a half, plus their MCP servers filled RAM and swap (58.7 of 59.4 GB) until macOS reported "out of application memory". The same pattern shows on Linux, at about 500 MB per idle session.

What changed

• New setting session.idleReleaseMinutes: default 30, 0 keeps the old behaviour. Also CODEOID_IDLE_RELEASE_MINUTES, and in the Settings tab.
• A session counts down while idle. Any activity resets it; a destroy cancels it.
• When it expires, the backend is released through the same path an account change already uses, so the next message resumes the conversation (and backends that can't resume their own get the history).
• Never released: a session with a turn running, agent background work, a pending approval, or a backend that never started. Backends that hold no process (the HTTP ones) are left alone. A session whose last turn failed is at rest and is released like an idle one.
• The process tree is snapshotted before the teardown, and whatever survives it is killed, as terminateBackend already does. codex and the Gemini CLI are stopped with a bare SIGKILL, so without this their MCP servers and commands would outlive them. An account-change release now reaps the same way.
• Limits longer than one timer allows (about 24.8 days) are waited out in steps, instead of firing after 1 ms.
• Note: the first message after a release starts the CLI again, so it re-reads the project's .mcp.json and hooks (documented in docs/mcp-backends.md). An agent that has kept a dev server running in the background past the limit, without the backend reporting it, has that server stopped.

Verification

• 10 tests: released after the limit and resumed on the same backing session; 0 keeps it; a just-idle session keeps it; HTTP backends untouched; live background work keeps it; a destroyed session's countdown never fires; a failed turn is released; a 100,000-minute limit doesn't fire; an ambient watcher doesn't hold it; a real child process left by the backend is killed.
• One audit round in a sandbox (correctness, plus security and robustness). Its two mediums (failed turns never released; codex and Gemini CLI children orphaned) and its lows (timer overflow, a sticky deferred release, ambient tasks, a test that always passed, the docs gap) are fixed in fe4c74d.
• Full suite (4,987 pass, 0 fail), typecheck and lint pass. The idle and session tests also pass on CI's Bun 1.3.13.
• Not done: a long-running check on a real daemon.

---

🤖 Implementation context (for agents / maintainers)

Files

• src/daemon/session.ts: #idleReleaseTimer, #armIdleRelease() / #clearIdleRelease() beside releaseIdleProvider(); armed in #setStatus on idle or error (AT_REST; cleared on any other status), re-armed in #reconcileDrainedBackground and when only ambient tasks remain, cleared in destroy(). The countdown is chained in MAX_TIMER_MS steps to a deadline. The callback re-checks the status, !#turnActive(), #hasAgentBackgroundWork() (ignores ambient), no #pendingApprovals, and provider.hasQueried, then calls releaseIdleProvider({ idle: true }), which skips (rather than defers) when busy. Both release paths reap with snapshotTree / killSurvivors, audited as session.release_backend.reaped. Only PROCESS_BACKENDS. The timer is unref'd.
• src/config.ts: SessionSchema.idleReleaseMinutes (z.number().min(0).default(30)), the session type, and the CODEOID_IDLE_RELEASE_MINUTES env mapping (float).
• src/daemon/settings/manifest.ts: the Settings entry.
• src/tests/idle-release.test.ts; docs/CONFIGURATION.md; CHANGELOG.

Follow-ups

• An optional cap on warm backends (least recently used), if 30 minutes isn't enough on a machine with many active sessions.
• opencode (Support opencode (2.x) as a backend, on par with Claude and Codex #447 / PR feat: opencode is a codeoid backend, with every tool call approved by codeoid #450) keeps one shared server; its per-session state should follow the same idle release once that merges.

🤖 Generated with Claude Code