Omniscio

Idle session release

Omniscio periodically releases the CLI process of a session that finished its turn and has been waiting on you past a threshold, reclaiming all of its memory. The conversation stays on screen; your next message brings it back transparently.

On this page

What it is

What: A cross-platform feature that periodically releases (kills) the persistent claude CLI process of a session that finished its turn and has been waiting on you past a threshold — reclaiming all of its RAM (~250–450 MB each), not just trimming the working set. The conversation stays on screen (it's stored by Omniscio, not the process); your next message transparently re-spawns the session via --resume, so the only difference is a slightly longer first reply after a long idle. On by default.

Setting: idleSessionReleaseMinutes (number, default 15, 0 = disabled) — Settings → Performance, "Release idle sessions to reclaim more RAM". Hard kill switch: AMC_DISABLE_IDLE_RELEASE=1.

A persistent Claude CLI child stays resident across turns (so MCP servers and instant follow-ups survive). A session you got a reply from and walked away from can hold 250–450 MB indefinitely; with many such sessions that is gigabytes of pure waste. Releasing the process reclaims all of it, and the next message brings it right back.

This is the harder/later sibling of the Windows-only working-set trim (wsTrimIdleMinutes): trim de-faults pages but keeps the process alive; release frees the whole process. Releasing after 15 min costs nothing extra — a session idle that long has already lost its short-lived prompt cache, so its next reply would reload regardless.

Two things make a release happen sooner than your setting, and both stop at five minutes for the same reason — that is the point past which releasing costs nothing extra:

  • Memory is under pressure. When the computer's commit charge approaches its limit, idle sessions are released at five minutes instead of fifteen, because only a release frees that memory.
  • Sessions are waiting for a place. When the local session limit's line has anything waiting, a session that has finished its turn is released at five minutes too — a place is a live process, so the line cannot move until one goes. This one raises no notice: it is your queue draining, not a memory emergency.

Where to find it

There is nothing to open and nothing to switch on — it runs on its own. The only surface is the session pane itself, where a released session's next message takes a moment longer while it comes back.

How it behaves

How it works

A 60-second scheduler (idle-release-scheduler.ts) asks processManager.releaseIdleProcesses(thresholdMs, now) to kill the persistent process of every eligible session. The kill is UI-silent and leaves the session in the already-handled "dead-persistent" state (childProcess=null, receivedResult=true); the next user message hits the dead-persistent guard in user-message-router.ts → the auto-resume branch in session-service.ts, which re-spawns with --resume. No new resume code, no new visible session state.

If that re-spawn cannot start — most often because Omniscio is updating Claude Code and the install is briefly unavailable — the session is left exactly as it was: it stays tracked and readied for its next message, and it is never marked failed over a condition that clears on its own. The wake or message runs as soon as the CLI answers again.

Eligibility (the pure isEligibleForIdleRelease predicate) releases a session ONLY when ALL hold: it has a live process · the current turn has completed (receivedResult — turn completeness, not the running status string) · no recovery is in flight · it has not armed its own wait · no subagent is inside its live patience window · no background command is still live · the DB row has NO pending action · it's been idle ≥ the threshold by lastAgentMessageAt · and, on Windows, the session's process tree holds nothing beyond what was running when the process first started (checked last, only for a session that passed everything else).

What is never released

  • A supervised run's link (supervised-run, 2026-10-30) — a cloud or own-box session whose agent runs on its box under the supervisor. Its local process is only an ssh client; ending it freed almost nothing and left the run working with nobody listening, so the final message never arrived. The account-switch kill skips these links too.
  • A session waiting on a question or a plan-approval (pendingAction set) — its answer is delivered to the live process's stdio control channel, so it keeps its process.
  • A session that is mid-turn — judged by turn completeness (receivedResult), never by the running status string, and including a turn the CLI opened on its own (cliOpenedTurnAt, set at its system/init after a background task finished, cleared by that turn's result) — recovering (auth / rate-limit / respawn / mid-turn-disconnect), holding a genuine prose wait or ScheduleWakeup (deferredWork of any kind other than a [[OMNISCIO_HIBERNATE]] hold), with a subagent inside its live patience window (hasLiveSubagentWindow + SUBAGENT_PATIENCE_MS), or with a background command still live.
  • On Windows, a session whose process tree (its job object) holds a process that was not there at the process's first system/init — a test run, a detached shell, a Monitor command — or whose tree the app cannot read (no job, no recorded starting set, an empty or failed read). Doubt keeps the process. Both show in GET /diag/idle-release as live-child-tree / tree-unreadable, and each new deferral writes one [idle-release] deferred sid=… reason=… line. macOS / Linux have no job object, so there this check does not run (T-390). The session's own background shell (its host, driver and parked spare process, started after the first message) is not counted as a leftover, as long as no command is running in it (T-14).
  • A [[OMNISCIO_HIBERNATE]] hold is NOT a refusal (2026-09-27). It shares kind: 'agent_prose_wait' with a genuine prose wait, but its timer is a main-process setTimeout, so killing the process does not lose it — the gate now tells the two apart by pattern id (isHibernationHold) and admits the hibernation hold. A genuine prose wait is admitted too, once the HOLD is ten minutes old (T-163, 2026-10-07) — see "A wait that was released still reads as Live".

A background task finishing wakes the session at once (2026-11-20)

When an agent ends its turn with "Waiting on a background process to finish" and the background command later finishes, the Claude CLI starts a new turn by itself. That turn has no assistant output for the first seconds — on a large context, often longer than the sweep's one-minute interval — and receivedResult still reads true from the last turn. The sweep used to read that as idle: the prose-wait hold was over ten minutes old and the finished task no longer counted as live, so it killed the process about a second after the turn began. The wake was lost and the session sat until the ETA check-in — measured on 2026-11-20 at 12:15:54 UTC (turn opened) → 12:15:55 (process released) → 12:40:42 (re-driven by the check-in), 25 minutes for a wake that should take seconds. A turn the CLI opened now counts as mid-turn until its result arrives.

A wait that was released still reads as Live, not interrupted (2026-10-24)

Releasing an agent's process must never make that agent look broken to you.

A session that closed its turn on a genuine wait — "Waiting on a background process to finish … ETA 180 minutes" — gives up its process once the hold is ten minutes old, and its wake is re-driven later through --resume. The problem was what the app did in between: the "has this agent stopped doing real work?" clock only advances when a turn actually runs a tool, and the release had removed the only thing that could run one. So on a long wait the clock was guaranteed to run out, and the session was pulled out of Live and reported to you as interrupted with "it hasn't made progress in the last 120 minutes — it may be stuck" — while its last message plainly said it was waiting. Reported by the owner 2026-10-24 11:40 about a session that had done exactly what it was told.

Now a wait the app freed is exempt from that judgement. At its deadline the app checks in with the agent instead, the check-in finds the process gone, and the session resumes itself. The exemption cannot hide a real stall, because it keys on the release mark the app itself set — a session the app never released (including one whose process simply ended, and a cloud run between turns) is judged exactly as before, and a chain that genuinely ran no tool for two hours still reaches you with "may be stuck". It also cannot loop: the resumed session clears the mark the moment it re-spawns, and the six-hour absolute ceiling still bounds the whole wait.

What you see when the app cannot reach the agent: the session still comes to you, but with the plain "Auto-wait timed out — no new activity for N minutes" line, never the "may be stuck" claim, because the app knows it was the one that stopped the clock.

Scope / no-op paths

  • idleSessionReleaseMinutes <= 0 OR AMC_DISABLE_IDLE_RELEASE=1 → the scheduler tick returns early (feature off).
  • Cross-platform — process kill works everywhere (unlike the Windows-only trim).
  • No pre-warm on focus (yet): the reload happens on your next message ("a little longer in the background"), not when you open the session.
  • session-memory-paging.md — the Windows working-set CAP (a different lever: pages a busy session to disk instead of releasing an idle one's process).
  • local-session-limit.md — the cap on how many sessions run at once; releasing an idle session's process is one of the ways a place in it frees up.
  • Contract: idle-session-release-contract.md.

Last verified 2026-11-06