Omniscio

Auto-restart stuck sessions

Auto-restart stuck sessions — the self-healer for a session whose underlying process freezes right after you send a message and spins on "thinking" forever: how the wedge is detected, the setting that turns the automatic restart on or off, and what you see in each case.

On this page

What it is

Very rarely, the agent's underlying process freezes right after you send a message. It stops producing any output but still looks like it's working — the session shows the "thinking…" spinner and never moves. Under the hood the CLI is alive but wedged: it silently queued your message and never actually ran the turn. To you it looks like the session is thinking forever.

Auto-restart stuck sessions makes that self-healing. When a session has produced no output for several minutes while it is the agent's turn to reply, Omniscio treats it as wedged, stops the fake "thinking," and cleanly restarts the stuck turn so it continues — you get a real reply instead of an endless spinner. When the setting is off, Omniscio still stops the fake "thinking," but hands the session to you as Needs You to restart yourself instead of restarting it automatically.

Before this existed, a wedged "thinking" session had only one backstop — a 4-hour absolute turn cap — so a hang could sit for the better part of an hour (or until you restarted the app). This catches it in minutes.

Where to find it

How to turn it on / off

On by default. Open Settings → Sessions → the When sessions stall group (its advanced controls) and look for Auto-Restart Stuck Sessions (autoRestartUnresponsiveSessions, default on).

  • On — a wedged "thinking" session is force-recovered and its turn restarts automatically, with a short "stopped responding — automatically restarting it" note.
  • Off — the wedge is still stopped (no more fake "thinking"), but the session lands in your inbox as Needs You with a "send a message to restart it" note; your next message respawns it.

How it behaves

Why the fast stall detectors missed it

Omniscio already force-kills a session that produces no output within its first-output window (2 minutes, or up to 6 on a busy machine). But to be patient with a genuinely slow first token, the watchdog folds the CLI's transcript-file activity into its "last output" clock. A wedged-but-alive CLI keeps its transcript file warm (it writes your queued message, flushes keepalives), so that clock keeps getting reset and the silence-based timeout never fires — the session shows "thinking" indefinitely with no detection. This feature adds a second clock the transcript can't reset.

How detection works

The per-session stall watchdog anchors an absolute ceiling on when the turn's watchdog started — a clock that transcript activity can never reset. A session is treated as wedged only when all of these line up at once:

  1. It's the agent's turn — the session is running and has not yet produced its first output for this turn.
  2. It's been older than the 6-minute ceiling since the turn's watchdog armed.
  3. Yet its silence timer is still under budget — i.e. something (the warm transcript) has been resetting it, which is the exact wedge signature. A genuinely silent session trips the ordinary first-output timeout first and never reaches here.

Because the trigger is the absolute age plus the "silence-timer-was-reset" signature, a genuinely slow-starting CLI (which trips the ordinary timeout on real silence) is never cut off early, and a session that is legitimately waiting on you (its last message is the agent's) or parked in a declared wait is never touched — those aren't the agent's turn.

Behaviour summary

Situation What happens
Alive CLI, no output for 6 min while it's the agent's turn, transcript warm Wedge detected → force-recovered
…with the setting on (default) Turn is restarted automatically (error + response_aborted → aborted-response recovery)
…with the setting off Session surfaced as Needs You; your next message respawns it
Genuinely slow first token (real silence, cold transcript) Handled by the ordinary first-output timeout, not this — never cut off early
Session is waiting on you (last message is the agent's) Not touched — it isn't the agent's turn
Session parked in a declared wait (ScheduleWakeup / background job) Not touched — the deliberate wait is respected
Setting off, wedge detected Fake "thinking" still stopped; lands in the inbox as Needs You

A session that hangs inside its own compaction

A related case, and not governed by this page's setting: a long-running session can hang inside the conversation compaction its CLI does when a chat gets very large. You see the "Compacting conversation…" note appear (usually a few times) and then nothing — no "Conversation compacted", no output, and the session does not move. Underneath, the CLI process is alive but doing nothing at all.

Omniscio now recognises that shape specifically — the CLI said it was compacting and never said it finished — and restarts the session for you (a clean restart that keeps the conversation). It will do that at most twice, and if the conversation still will not compact it stops trying, parks the session with a "send it a message to continue" note, and tells you it gave up rather than looping.

  • Separate from the setting above — this recovery is not switched off by Auto-Restart Stuck Sessions, which watches for a different shape (a session wedged right after you sent a message, in its first few minutes).
  • Why it restarted rather than nudge — a process hung inside a compaction is not reading its turn input, so nudging it does nothing; the measured cure is a restart (in practice the retried compaction then finishes in about two minutes).
  • Anything already waiting for that session (a queued message, a cloud test result) delivers once it is back, in the normal way.

A session that cannot be woken

Rarely, a session that was meant to come back after a restart never starts. It keeps reading starting, and every time Omniscio tries to wake it the attempt is refused because something else still claims its launch. Before this, that retry happened quietly and forever: the session sat there, and you were never told.

Omniscio now forgives such a refusal only briefly, for as long as the claim might still be honoured. Once that window has passed, each refused attempt counts, so a session that genuinely cannot start is handed to you as Needs You, with a note saying its last attempt at restarting it was refused — instead of being retried in silence.

  • One refusal is never held against a session — a single refused attempt costs nothing, and the session is tried again at the same point in the ladder.
  • A healthy slow launch is left alone — a session whose launch is still genuinely in progress is never surfaced early.

A session owned by a cloud controller

A cloud session belongs to its own controller, so the app is not allowed to move it to Needs You — the database quietly refuses that change. Omniscio now hands such a session over first and reads whether the hand-over actually took: if the row refused it, nothing is posted to the conversation, no further wake attempts are spent, and one line in the log names the real blocker. Before this the notice went out first and the result was discarded, so the same sentence came back on that session roughly every hour while its status never moved. Stop a session like that from its own controls.

When your computer has spent every attempt to reach a cloud machine and given up, the app now also remembers that give-up and hands it to the session's controller, so the session lands in Needs You marked as failed instead of reading Running (or a plain "your move") for hours while nothing is working. A later turn that genuinely finishes replaces it, and the session's next real turn clears it — so a session you revive is never held back by an old give-up. The moment the cloud machine reports the session finished (for instance because you stopped it), that verdict wins instead, so Stop still ends the session and any finished work still comes home. Omniscio re-reads this on every start, so restarting the app does not lose it. When that session started a Nighty Tidy audit, the run settles at the same moment: as Failed with the plain reason "The audit's session stopped and gave up its automatic retries, so the audit did not finish and no results came back." — or with its real findings when its report did come home. It no longer waits for the 24-hour reaper to fail it.

Out of scope (carry forward)

  • Tunable ceiling from the UI. The 6-minute ceiling is a code constant (the load-extended first-output wait's own top), exposed only as the on/off setting.
  • Recovering the exact queued input. Recovery restarts the turn (a clean --resume); the CLI's own dropped queue is not replayed byte-for-byte — the user's message is re-delivered on the respawn.

A session the app cannot start because its drive is short of free space now says so on its own row, and it starts by itself once the drive has room.

  • The row carries the No disk space state (ember, the same "parked and coming back" colour as a rate-limit park) instead of looking busy or finishing silently. The transcript line still names the drive and the figures: "there is not enough free disk space on the C: drive (59.9 GB free, 81.0 GB needed)".
  • Nothing spawns while the drive is full. A background lane asks the same free-space check the folder creation uses, once a minute, and only when that check says there is room does it nudge the session to continue.
  • It is bounded: six nudges per episode on a drive that has room and still refuses. A drive that stays full burns none, so a full drive is never a reason the app gives up — freeing space is enough.
  • Deleting or archiving the session stops it immediately: the lane's candidate set is read from the database, so a row that is gone is never nudged.
  • This replaced two worse outcomes from the same refusal: a bare "your turn" row that read as a finished turn nobody had run, and an error row parked as a permanent give-up that no automatic recovery would ever touch again (helpdesk 3c65c467: two sessions sat that way for four days).
  • aborted-response-recovery.md — the sibling self-healer for when the CLI drops a turn (process exit / stream end); this one handles a turn that never started producing output.
  • context-stall-recovery.md — the out-of-room self-healer for a turn that completes but had no space to reply.
  • stalled-session.md — the orange "Stalled?" state + Auto-Continue Mid-Task (the broader post-first-output nudge).

Last verified 2026-10-28