Crash recovery (auto-resume sessions after a crash or restart)

What it is

What it does

When Omniscio starts and detects sessions that were running last time the app exited — whether you closed it cleanly or it crashed / the OS rebooted — it automatically brings them back. You launch the app, the sidebar paints with those sessions visible immediately, and one by one they reconnect to a fresh Claude CLI child and pick up where they left off. Each revived session receives a single operator turn so the agent knows to resume — normally "Please continue", but a session that was launched and never completed a turn is sent its own stored task text instead, because for that session the bare continue line is the whole turn and the agent would start against an empty conversation; the message renders in the chat with an auto-response badge so you can see this was an automated revival, not the agent volunteering work or you sending a duplicate. A non-blocking toast — "Resuming N session(s) from last shutdown" — fires once at the start to tell you what's happening.

You don't have to click anything. You don't have to remember which sessions were open. Omniscio's job is to make the crash invisible: log files survived, conversation history survived (it's all in the local SQLite DB), and the live processes that died get respawned and re-handed the conversation transcript.

Crash and restart recovery — two flavors under the hood (the postmortem distinguishes "crash" from "restart"), identical from your POV and controlled by the same setting — are the main way Omniscio brings sessions back. One narrower path joins them: a session interrupted mid-work when you closed the app that didn't get snapshotted for restart (covered in its own section below). All three are gated by the same setting and look identical to you.

Where to find it

Recovery has no panel of its own — it happens at launch, in the sidebar and in a toast, and the sessions it brings back are ordinary sessions you open like any other. There is nothing to set up before it runs: it is on the moment you install, and the single switch that governs it sits with the other session controls rather than in a screen of its own. The switch, and the toast button that stops a resume in progress, are described under How it behaves below.

How it behaves

When it triggers

A session qualifies for crash recovery on the next startup if all of these are true:

• It was in a running state when Omniscio last exited (or was preserved for restart via the graceful-shutdown snapshot — see tray and window).
• Its ended_at timestamp is NULL in the DB (no clean termination was recorded).
• It is a genuine app-crash victim — it was actively running when Omniscio died, so the startup reconciler flipped it to error and stamped it crash-reconciled (crash_reconciled=1). A session that errored on its own (a turn failure, a dead CLI process, a non-transient API error) is NOT a crash victim and is never silently revived — it stays error (red) across the restart, exactly as it ended. (A transient API 5xx that exhausts its silent retries is the exception — it auto-recovers via the recovery-failed re-arm, not dead red.) This stamp is the precise gate; the 120-second status_changed_at window is kept only as a freshness bound (a true crash victim is always inside it).
• The Auto-Resume Sessions on Restart setting is on (default on — see below).

Sessions that don't qualify stay in their last-known state (error, needs_you, paused, etc.) and surface normally in your inbox. In particular, a red errored session stays red across a close-and-reopen — it is not turned into an amber "your turn". (Before 2026-06-09 the crash path used the 120-second window alone as a proxy for "just crashed" and could resurrect a genuine error that happened shortly before you reopened — see the errored-sessions-resurrected-on-restart postmortem.)

What you see

Watch the launch sequence from the user's POV:

1. Second 0 — Omniscio's window opens. The sidebar paints with every recoverable session already visible, each showing the starting status (the grey dot, ringed) — deliberately grey, not green: a session that is still queued to launch is not working yet. The window is fully interactive: you can scroll, click, switch projects, open Settings, do anything. Nothing is blocking.
2. Toast (with a Stop button) — A blue info toast slides in: Resuming 13 sessions from last shutdown (or Resuming 1 session from last shutdown for a single session). It carries a Stop button and stays up the whole time sessions are coming back (the resume runs for minutes), so the button is there when you reach for it; it clears itself once the resume finishes. Use it as the cue "Omniscio noticed; sit tight" — or hit Stop to halt it (see Stopping the resume).
3. Trickle to running — Over the next minute or so, sessions transition from starting → running one at a time, with a gentle gap between each: at least 5 seconds, automatically stretching while your computer is still busy finishing the previous spawn's work — whether that's the CPU, the memory, the disk the previous revival is still hammering as it reloads its history, or Omniscio's own heartbeat reporting the app itself just stalled — in that case the next revival waits for a stall-free window (up to ~20 seconds) — and stretching more (up to ~45 seconds, held to a calmer level) around a heavyweight revival that has to replay a session's whole conversation history, since that's the most intensive kind of restart. So a big batch never slams the machine. Each revived session gets a fresh agent turn going as its revive message is delivered — "Please continue", or the session's own stored task when it never ran. You'll see the agent's reply stream in.
4. Auto-response badge — In the chat history, the "Please continue" message that Omniscio injected renders with an auto-response badge so it's visually marked as system-generated, not an action you took. You can click the badge to see the full metadata about why and when the auto-response fired.
5. "Restoring…" line in the conversation (with a "Restart / Continue" button) — If you open one of these sessions while it's still waiting its turn in the queue, the chat shows a small status line at its foot — "Restoring this session from your last app close — this is automatic and may take a moment." — so an idle-looking panel never reads as broken. Right beside it is a "Restart / Continue" button — also reachable from the keyboard with Shift+R or C (the same key you use to Continue a stalled session): click it or press the key and Omniscio pulls that one session to the front of the line and starts it immediately, instead of waiting for the queue to reach it (it briefly shows "Starting…" while it kicks off). The line clears itself the instant the session reconnects, and the usual "agent is typing" dots are held back during this window so you see only the one accurate message. The same "Restart / Continue" action also sits in the session's ⋯ (overflow) menu while it's waiting to relaunch — identical on phone and desktop — so it's easy to reach even if the inline line has scrolled out of view.

If you have one or two sessions to revive it'll feel instant. If you have a dozen or more, the trickle is visible but the app stays responsive the whole time — by design.

Who comes back first

Not the order they happened to be running in. Your Overseers come back ahead of everything else — an Overseer is the session answering its helpers and reporting on a mission, so every minute it spends waiting its turn is a minute the whole mission is stalled. That covers both kinds: the Overseers in the Overseers panel and a mission run by a crew lead (see Agent Crews).

After the Overseers, it's most-recently-active first — the sessions you were working in last come back in the first minute, and the ones you hadn't touched in a while wait their turn behind them. (Since 2026-10-01. Before that the wave ignored who a session was and went strictly most-recently-active, so an Overseer could be the very last thing back.)

Fixed 2026-10-05: crew-lead Overseers really do go first now. From 2026-10-01 until this fix, the list of crew leads finished loading a few seconds after the restart wave had already been put in order, so on almost every restart no crew lead was recognised and they came back in plain recency order. The list now loads the moment the app opens its database, well before the wave is ordered. To check a restart, the app's log line [recovery-queue] starting drain of N item(s) (M Overseer(s) go first) should show a non-zero M, and the line before it should read crew-index gate: index-loaded.

A note on what the revived agent sees. The badge on that "Please continue" is for you — it renders in the transcript, and the agent never receives it. So to the agent, a revival used to be indistinguishable from you typing "Please continue" yourself, and some would answer it as if it were a fresh instruction. If you turn on "Prevent mistaken 'nothing to do' replies" (see The woken no-op sentinel), the revival nudge now also says, in the message itself, that Omniscio sent it and not you. Leave the setting off and the text is exactly what it always was.

Don't want to wait? Act on it and it jumps the line

The trickle is for the background — it keeps a big mass-restart from freezing your machine. It is not a wall you have to wait behind. The moment you act on a specific session — click the "Restart / Continue" button (or press Shift+R / C) on its "Restoring…" line, pick "Restart / Continue" from the session's ⋯ (overflow) menu (right in the session view, on phone and desktop), send it a message, or hit Restart from the dashboard menu — Omniscio pulls that one session straight to the front of the line and starts it right then, instead of waiting for the queue to reach it on its own. The "Restart / Continue" button is the most direct: it sits right in the session you're looking at, so you don't have to guess at sending a message or hunting a menu. If you send a message instead, your message becomes its first turn (you skip the automatic "Please continue" entirely). So if you reopen Omniscio and want one session back now, just click in — the grey "Starting" dot is a session genuinely on its way back, and acting on it does exactly what you'd expect.

The one time you'll still briefly wait: if that session happens to be the one the queue is launching at that exact moment, Omniscio won't double-start it (a second start would replace the first, and anything riding the replaced one would be lost). Your message waits for that launch instead and goes in as soon as the session is up; only if the launch takes unusually long do you see "Restoring this session from your last app close — try again in a moment." Messages other agents queued for that session wait their turn the same way — they are kept and delivered, never dropped. Every other case starts immediately, however long the session has been waiting in line.

Stopping the resume: the Stop button and the auto-resume switch

Don't want the sessions back? You have two controls, for two different needs:

• Stop, right now (this restart only). The Stop button on the "Resuming N sessions" toast halts the resume the moment you see it happening. The sessions that hadn't come back yet are left stopped (grey "ended") — quiet, not running, and never turned into a pile of "Needs You" nags — so you get a clean slate. They're still there: bring any of them back later from Manage Sessions → Restart, or by sending a message. Until Omniscio next starts, nothing automatic brings a stopped session back — not a scheduled check-in, a test or merge notice, a queued message, or another agent's message; those are turned away (another agent's message is kept, never lost), and only you can restart the session. (Sessions that already came back before you clicked stay running; clicking Stop just halts the rest.) Stop does not change any setting — the next restart still auto-resumes unless you turn that off below.

• Turn auto-resume off (across restarts). To stop Omniscio bringing sessions back on every restart, flip the "Resume sessions when Omniscio restarts" switch off. It lives right in the Manage sessions modal (the footer), next to where you stop sessions — so you don't have to hunt through Settings. (It's the same switch as Settings → Workflow → "Auto-Resume Sessions on Restart" — one setting, shown in both places.) Turn it back on whenever you want resume again. With it off, nothing auto-resumes on restart — neither the graceful-shutdown snapshot nor genuine crash victims.

When something doesn't come back

• A launch hiccup because the machine is busy — if a revival can't even spawn because your computer is momentarily overloaded (a transient OS failure, not a real fault), Omniscio keeps relaunching it with a growing gap until it's back, instead of giving up after a few tries. This is the relentless relaunch behavior, on by default — it's exactly what stops a big mass-restart from stranding a pile of sessions as red errors when the burst overloads the OS. Only a genuine fault (next bullet) turns the session red.
• A revived session lands in error after a few seconds — The CLI child spawned but exited fast (binary missing, OAuth token rotated, project folder moved, disk full). Omniscio has a 5-second fail-fast watchdog that detects this case and retries once more with a forced transcript replay (replays your conversation history into the CLI so the new child has the same context). If the second attempt also fails, the session stays in error and you can reopen it manually to investigate.
• A big restart is slow to finish (lots of sessions) — A large batch comes back one at a time by design (the anti-freeze pacing), so dozens of sessions can take several minutes to all come back. They're still queued — watch them trickle; this is not a stall.
• The revival never started at all — Two safety nets bound the genuinely-stuck cases: a progress-aware stall backstop that gives up only if the queue stops making any forward progress for ~2 minutes (a genuine wedge), and a 10-minute "queue never started" net for the case where the launch sequence never began (e.g. the window failed to wire the queue up). Neither is a clock on how long a big restart may take: a queue that's healthily draining — even a 48-session restart that legitimately needs half an hour at the safe pacing — keeps re-arming the stall backstop and is never cut off mid-drain. If a session genuinely is abandoned (a true wedge, or the queue never started), it's parked as "your turn" — the orange recovery-failed dot in your inbox, one-click resumable — not a dead-end red error, and never left on the dim gray "starting" color, so a dropped session is always visible and recoverable, never silently missing. (Before 2026-06-12 this backstop was a blind 15-minute hard ceiling that guillotined the un-launched tail of a slow-but-healthy 48-session restart into dead error — see the recovery-ceiling-strands-slow-restart-tail postmortem; and before 2026-06-09 the 10-minute net couldn't tell "wedged" from "slow" — see the safety-net-abandons-slow-restart postmortem.)
• You see a session in starting long after the toast fired — Almost always means the per-session spawn hit the 30-second per-launch timeout and Omniscio moved on without it. The session lands in error on the next watchdog tick (~30s later).
• A restart-resumed external session (Codex, DeepSeek, …) reconnects but stays silent — a non-Claude session that resumes but produces no first output is force-recovered fast — within ~150 seconds (load-aware) — instead of waiting out the patient mid-turn stall threshold (up to ~30 min) or the 4-hour turn cap. It restarts the engine and re-drives the turn (bounded), then surfaces an honest error if it still won't respond, so a re-launched session can't sit running while emitting nothing for a long time (the 2026-08-12 phantom-running wedge, when 22 Codex sessions sat silent ~80 min after a restart). Power-user knobs: kill switch AMC_DISABLE_RESUME_FIRST_OUTPUT_CEILING=1, window override AMC_CODEX_RESUME_FIRST_OUTPUT_SECONDS. See the codex-restart-resume-phantom-running postmortem + restart-resume-first-output-ceiling in the codex-robustness contract.

A session that was mid-recovery survives the restart

There's one important refinement on top of the generic "Please continue" revival. If a session was in the middle of an automatic auth/rate-limit retry when the app exited — its last turn had hit a login (OAuth 401) error or a rate limit and Omniscio was already retrying it — that in-flight recovery is now durable. On the next launch Omniscio resumes that specific session with its real last instruction (your actual last message), not the generic "Please continue" nudge, and it remembers how many retry attempts were already used so it doesn't start the budget over. So a crash during a retry doesn't lose your place or quietly re-nudge the agent with a meaningless turn — it picks the failed turn back up exactly where it was.

If, at that point, every login is dead or out of capacity and there's genuinely no healthy account to run on, the session doesn't silently spin — it lands in a visible recovery-failed state (an orange dot in your inbox) so you can clearly see it needs you to re-authenticate or add capacity. See account pool for how dead logins are handled.

A session force-closed by a busy shutdown still resumes

When you close or restart Omniscio with many sessions running, the graceful shutdown gives itself a fixed 15-second budget to stop them all. If it runs out (a lot of busy sessions), it force-closes whatever's left so the app can exit — and a force-closed session is recorded as error (red), not a clean ended. Omniscio had already snapshotted those sessions as "alive at shutdown," so on the next launch they resume with the same "Please continue" nudge as any cleanly-closed session — regardless of how long the app was down — and each still passes the same finished-work check, so one that had genuinely finished isn't re-nudged.

Before this fix, a force-closed error session could fall through both recovery nets — the crash path's 120-second window had passed, and the restart path only accepted cleanly-ended sessions — and strand as a red error row until you reopened it by hand. See the please-continue-after-clean-shutdown postmortem (R6).

A session cut off in the last seconds of a close still resumes

Closing Omniscio marks each working session "paused — will resume on restart" first, and only a few seconds later shuts its agent down. An agent can start new work inside that gap — say its background build finishes and it begins reading the result. That step is cut off by the shutdown, and Omniscio now records it as interrupted, so the session comes back on reopen like any other paused session. The same holds when the agent had written a long, finished-looking report but never got to signal the end of its turn before being shut down.

Before this fix (2026-09-25), such a cut-off step could be recorded as a finished answer: the session then sat in Needs You looking done, its last message stopping mid-step, and it did not resume on its own. A step that genuinely finished before the shutdown still counts as finished and is never re-nudged. See the please-continue-after-clean-shutdown postmortem (R10).

The same gap covers two more cases (since 2026-09-26):

• A session that was waiting on you when you closed, but started work by itself in the gap — for example, the background job it was waiting on finished and it began reading the result. Its cut-off step is recorded as interrupted and the session is marked "paused — will resume on restart", so it comes back on reopen instead of sitting in Needs You. A session that genuinely needs you — a question, an approval, a stop you made — is left exactly as it was.
• A Dev Pipeline gate that finished in the gap. Omniscio approves a green gate by itself when that gate is set to auto-approve, but a step that finishes while the app is closing can't receive that "approved". On reopen the gate is now approved within a few minutes instead of first waiting out the usual safety delay (4 minutes, or 15 on a busy machine) — and still only when nothing else stops it: you haven't replied since, the gate is still set to auto-approve, and its report still reads ready.

A session interrupted on close shows up in your inbox — and comes back on reopen

There's a narrower gap the two paths above don't cover. When Omniscio closes and a session was genuinely mid-work but did not get snapshotted for restart — it wasn't an app-crash victim AND wasn't in the graceful-shutdown save-set (for example, a second app-close suspended it) — it used to be left ended and invisible: a dim gray row in your Live list, out of the Needs-You inbox entirely, so the only way it came back was you finding it and resuming it by hand.

Now such a session is handled two ways at once:

• It surfaces in the sidebar's Interrupted section. On close it's flipped to an Interrupted state (an ember/orange dot — the same family as paused / rate-limited), so it's always findable instead of a gray ghost in Live. This happens regardless of the Auto-Resume setting. (As of 2026-08-21 an interrupted-on-close session collects in Interrupted, not Needs You — Needs You is now reserved for sessions that delivered a real message and need your response; see interrupted-sessions-section.md.)
• It comes back on its own. On the next launch, if Auto-Resume is on, Omniscio resumes it with the same "Please continue" nudge as any other revived session and it returns to running. If Auto-Resume is off, it just waits for you in the Interrupted section as the safety net.

The guardrail is the same finished-work check the other paths use: only a session that was genuinely mid-work is surfaced or resumed this way — a session the agent had actually finished is never flipped to Interrupted and never re-nudged ("closed means closed"). See the please-continue-after-clean-shutdown postmortem for why re-nudging a finished session is the exact failure this guards against.

This covers your non-Claude engines too. A Codex, Gemini, Pi, OpenCode, Cursor, Antigravity, or Hermes session interrupted mid-work no longer strands as a dim gray "finished" row on restart — it surfaces in Needs You exactly like a Claude session and, with Auto-Resume on, comes back on its own through that engine's own resume path (it re-registers the session and replays its conversation / uses the engine's own --resume, never claude --resume). Only OpenClaw is deliberately left out — a remote gateway whose connection is gone once the app closes, so it genuinely can't reconnect. (The per-turn engines Cursor / Antigravity / Hermes used to be left out on the theory they "never strand gray" — but they did strand as finished on a normal restart, which is exactly the bug this now fixes.) Whatever the engine had streamed before the close is preserved.

You can also force one of these back immediately with Restart stuck sessions (bulk restart) — an Interrupted session is a valid Restart target.

A session Omniscio couldn't start comes back on the next restart

Sometimes a session goes red not because its agent hit a problem but because Omniscio itself couldn't start it — the launch failed before the agent ever ran. After the next restart Omniscio brings each of these back once, on its own, picking up where it left off. A session whose agent genuinely failed still stays red until you look at it, exactly as before.

• If that one attempt fails too, the session stays red with a note in its conversation — "This session couldn't be automatically resumed after Omniscio restarted" — and Omniscio stops trying, so it never loops. Send it a message to pick it back up.
• A session you closed, stopped, or paused is never brought back this way, and nothing is while you've pressed Stop on the "Resuming sessions" toast or turned auto-resume off (see below).

How to turn it off

Settings → Workflow → Auto-Resume Sessions on Restart is a toggle, default on. Helper text: "Automatically restart sessions that were active when the app was closed or crashed. Running sessions receive a continue nudge. Sessions waiting for your input are restored."

Turn it off if you'd rather every crashed session show up in your inbox as error for manual triage instead of being silently revived. Sessions that were waiting for your input (needs_you) are restored regardless of this toggle — only the auto-resume of running sessions is gated by it.

The setting key is autoResumeOnCrash (boolean). It's also available via the CLI control surface for external AI agents that manage Omniscio settings.

Related

This page is split across two parts: part 2 covers the crash-loop circuit breaker, the silent-death watchdog, the states that are deliberately never resumed and why the revival trickles, plus the code map. Two of the behaviours here have pages of their own — the relaunch that keeps trying while the machine is busy is relentless relaunch, and a session the app hands back to you is described in interrupted sessions. Restarting a batch by hand is on bulk stop and restart, and what survives a graceful close is on tray and window.