Omniscio

Job Object orphan-kill (Windows)

What happens to the helper processes a session spawns — its tools, its shell — when Omniscio itself dies badly instead of quitting cleanly. A crash, a force-kill or a power loss leaves no chance to clean up, so on Windows Omniscio asks the operating system to tie those processes to its own lifetime and end them with it.

On this page

What it is

What problem this solves

When Omniscio spawns a Claude CLI session, that CLI process spawns its own children — MCP servers (playwright, gcloud, mempalace), an OS shell, sometimes a network tool. If Omniscio dies cleanly, Omniscio's graceful-shutdown code uses taskkill /F /T to walk the tree and end each process. That works for a polite quit.

It does not work for the failure modes that matter:

  • Omniscio's main process crashes (uncaught exception, segfault in a native module).
  • The user force-kills Omniscio from Task Manager or Stop-Process -Force.
  • The machine BSODs or loses power.
  • A debugger detaches Omniscio's process tree.

In any of those, Omniscio has no chance to run its taskkill /F /T cleanup. Every Claude CLI process and every MCP grandchild is left behind as an orphan. The user opens Omniscio again the next morning and finds a dozen claude-code processes burning CPU, holding file locks, blocking ports.

The orphan reaper that runs on next Omniscio startup did clean these up eventually — but only when Omniscio was launched again. Until then, the machine kept paying.

Where to find it

There is nothing to switch on and nothing to see — it is a safety net under the sessions you already run, on Windows only. Its effect is what you don't find the next morning: a machine not left carrying a dozen stray processes from an app that died overnight.

How it behaves

What Omniscio does now (Windows only)

On startup, Omniscio asks the Windows kernel to create a single Job Object with the flag JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE set. A Job Object is a kernel construct — a named bag of process IDs the kernel manages on Omniscio's behalf. The flag means: when the last handle to this job is closed, the kernel terminates every PID in the job.

The only handle to that job is held by Omniscio's main process. So:

Omniscio exit path Handle state Kernel action
Clean quit taskkill already killed children, then handle closes KILL_ON_JOB_CLOSE has nothing to do
Crash Process death closes all handles Kernel terminates every assigned PID
Force-kill Process death closes all handles Kernel terminates every assigned PID
BSOD / power loss All handles invalidated On reboot, no orphans existed in the first place
Debugger detach Handle still owned by Omniscio No effect — same as running

After the job is created, every long-running spawn Omniscio issues calls assignToSessionJob(child.pid) immediately after spawn() returns. The new PID joins the job. Agents go one step further: a post-spawn assignment can land after cmd.exe has already started the real agent, so every agent launch goes through the job-gate launcher (amc-hidden-launch.exe), which cannot start the agent until Omniscio has put it inside the job and signalled a release event. If that can't be done, the launch is refused (backend-spawn-contract rule 4). Job membership is inherited transitively: if the assigned process spawns its own children (like an MCP server), those grandchildren are automatically in the job too — unless someone explicitly sets JOB_OBJECT_LIMIT_BREAKAWAY_OK, which Omniscio never does.

Which spawns are covered

The main long-running spawn surfaces (local agents are held until they are inside the job; the SSH wrapper for a remote agent is still assigned after it starts):

Spawn site What it spawns Held until in the job?
src/main/process/process-manager.ts (main path) The persistent Claude CLI for each session Yes
src/main/process/process-manager.ts (SSH path) The local SSH client wrapping a remote Claude CLI No (post-spawn)
src/main/services/engines/codex-app-server-client.ts The OpenAI Codex app-server child Yes
src/main/services/engines/pi-rpc-client.ts The pi --mode rpc child (one per session) Yes
src/main/services/engines/opencode-server-supervisor.ts The one shared opencode serve server Yes
src/main/process/gemini-acp-client.ts The long-lived gemini --acp ACP child (one per session) Yes
src/main/process/slim-acp-session-client.ts The Kimi / Hermes ACP child (one per session) Yes
Cursor / Grok / Antigravity turn runners One child per turn Yes
src/main/process/aside-runner.ts One-shot claude -p --resume <id> --fork-session per aside Yes
src/main/services/context-query.ts One-shot CLI run that asks the agent for a summary No (post-spawn)
src/main/services/contextdock/spawn.ts Vendored ContextDock CLI invocations (runCli / runCliRaw) No (post-spawn)

Out of scope (intentionally not assigned):

  • git clone, npm install, taskkill, and other short-lived utility spawns. They finish in seconds and don't survive Omniscio by definition.
  • User-launched bookmarks (Start-Process from the bookmarks popover). The user wants those to survive Omniscio closing; that's the whole point of a bookmark.
  • Anything spawned by the renderer (the renderer can't spawn).
  • The screen recorder's own ffmpeg and ffprobe (the live encoder, the Stop bake, the re-bake, the poster, export, stitch, and the probes a take waits on) — your work, not the agents': they stay out of the agents' job, so they are never pinned below normal or held to the slower cores, and run at normal priority on Windows. They still close with Omniscio, through the kill-on-close group Node gives every child it starts. Agent-driven media work (file conversion, PR screenshots, agent frame grabs) still joins the agents' job. The decision lives in one place, ffmpeg-process-placement.ts, keyed on the same work-class vocabulary.
  • Cron script children (cron/cron-script-executor.ts) — deliberately in a SEPARATE, non-killing job instead (2026-07-08 hang mitigation, explicit user decision): a cron background job with the CPU rate cap but no KILL_ON_JOB_CLOSE, so a mid-run cron script (e.g. an MP3 conversion) survives an Omniscio restart. The cron engine's own timeout + zombie-run machinery bounds them instead. The spawn audit reports these as inJob: false, backgroundJob: true.
    • Which of the two jobs a script joins is decided by its work class, the closed vocabulary in work-class.ts. A script that a user-harm verdict may stand down — maintenance (the default when a job declares no class, so every job written before the field behaves exactly as it always did) or speculative — joins the BELOW_NORMAL job, CPU-capped and IO-stamped, exactly as every cron script used to. A script that protects a live session (agent-background or above) joins its own sibling job instead: the same concurrent-process ceiling, the same non-killing semantics, and no priority class written at all, so its children are born NORMAL and a slow child tool is not starved out of the scheduler on a busy box. Its per-process BELOW_NORMAL and low-IO stamps are skipped for the same reason.
    • Measured 2026-10-24 on the owner's box: gog.exe --version took 92,223 ms as a BELOW_NORMAL cron child (its main thread sat Ready — runnable, never scheduled — for ~55 s of the run) and 2,084 ms as an AboveNormal process, while the network answered in 0.15 s. A provider-alert check (boat-alert-watch) had been timing out at 60 s for two hours, so the alerts it exists to deliver were never read.
    • Set the class on a script job with jobConfig.workClass — "agent-background" for anything whose result the owner is waiting on. It is validated against the same closed vocabulary (workClassSchema), so a typo is a 400, never an unrecognised class that quietly reads as the demoted default. PATCH /cron/jobs/:id rewrites jobConfig wholesale, so send the complete script config with the field added. The job editor does not render it, and a save from the editor carries it over untouched.
    • See the repo's backend-spawn-contract for the kill-net half of this split.

What happens if it fails

The wrapper is conservative. Any failure logs a warning and returns false; Omniscio continues normally. Possible failures:

  • CreateJobObjectW failed at startup — initSessionKillJob() returns false. Reaper-on-next-startup is the fallback. Logs [JobObject] Init returned false — orphan-on-crash safety net DISABLED.
  • AssignProcessToJobObject returned ERROR_ACCESS_DENIED — Windows refused the job's nesting (on 2026-09-24 this turned out to depend on which child joined the job first, so the job is now pinned with an anchor child before anything else can join it). Every local agent launch refuses to start rather than run an agent the app cannot end — a Claude session reports "Windows process-tree ownership could not be established before agent launch", and Codex, Pi, OpenCode, Gemini, Kimi/Hermes, Cursor, Grok, Antigravity and asides show "Failed to start <engine> session: Windows process-tree ownership …". Other children log the error code and continue unprotected; the reaper covers them.
  • koffi failed to load kernel32.dll — basically impossible on Windows but caught by try/catch. Same outcome: warn, continue, reaper covers.

The reaper is still wired and runs on every startup. It's no longer the primary defense, but it's the second line.

Non-Windows behavior

initSessionKillJob() returns null on macOS and Linux. Those platforms reparent orphaned children to init / launchd, which immediately reaps them. There's no orphan-burning-CPU class of bug to solve, so no analogue is needed.

Why not just rely on the reaper?

The reaper only runs when Omniscio is launched. If Omniscio crashes and the user doesn't reopen it for hours — or never reopens it on that machine — the orphans burn CPU, hold file locks, and rack up API token usage in the background until the user notices. Job Objects fix the leak at the kernel level so it can't happen at all.

If an agent survives anyway

Two backstops catch an agent that escaped the job (on 2026-09-24 one did: a since-reverted change let agents launch outside it, and a restart's shutdown ran out of time):

  • The orphan reaper reads the app's whole launch record — every rotated copy of spawn-audit.log, not just the newest two — so it can prove an agent is Omniscio's even when it was launched before the app died. How far back that reaches depends on how busy the machine is, because the tape rotates at a fixed size: hours on a quiet box, but only about 25 minutes at a fleet's ~650 child spawns a minute (measured 2026-10-28). It ends only what it can prove, and never a process that started under a reused process number after that app run had ended.
  • A resumed session ends its own leftover copy first. When a session starts again after a restart, it looks up its last launch from the previous app run and ends that copy (with its tools) before the new one takes over, so one session never runs two agents on one branch. If the old copy was still running real work, such as a build, the session is told what was ended.

Why a job per Omniscio instance, not per session?

Per-session jobs would require one job handle per running session, plus careful cleanup when sessions end normally. The shared single-job design has one handle for Omniscio's whole lifetime, which is exactly what we want: when Omniscio ends, every Claude process ends. We don't need finer-grained control because session-end already calls taskkill /F /T for that specific PID tree.

What a session stop ALSO ends: the agent's background work

Job membership is inherited and permanent. Every process a session's Claude CLI starts — the OS shell, and anything that shell runs — joins the session's job automatically, and nothing can leave a job it is already inside. Probed directly: a fresh node.exe started from a session shell reads IN-JOB.

That has a consequence worth stating plainly, because it cost a week of misdiagnosis in September 2026:

When a session's child is stopped, terminateScopedJob() calls the kernel's TerminateJobObject. That ends every process in the job — including a long-running command the agent deliberately started in the background (run_in_background) and is waiting on, such as a build or a test run.

A kernel job terminate is completely silent. There is no exception, no exit code, no signal handler, no crash event, and no surviving process. To the agent, a 15-minute build simply stops writing to its log — which reads exactly like a hung gate, and got diagnosed as one three times.

What Omniscio does about it. It cannot save that work once a stop happens: a process cannot be excluded from a job terminate it is already inside, and the alternative (skipping the job kill and the tree kill) would disable the orphan protections this whole page exists for. So it avoids the OPTIONAL stops, and makes the rest honest:

  • A per-session live-task ledger (live-background-tasks.ts) records each background command the agent launched, from the stream the app already reads, until the CLI reports it finished — a system/task_notification event on its stdout, sent whether the agent is mid-turn or idle.
  • Optional stops wait or skip. Idle release and the account-switch idle kill skip a session with a live command; a sign-in re-run on an automated turn waits for the command to finish — it goes ahead the moment the command is reported finished, and after 30 minutes at most, so a watcher that never ends cannot keep the session signed out (a message from a person, or from another agent that arrived while the command was already running, still goes through at once).
  • The app's own turns wait too. A check-in or wake-up the app opens itself never recycles a session's process for a rotated sign-in or a switched account while a command is running; it uses the process that is already there.
  • Every other stop announces what it ended, before the job kill — the commands the ledger holds, each with its own runtime and the stop's real reason (stop-reasons.ts). A stop that ended nothing says nothing.
  • reapEscapedSessionTree() reports the WORK processes it had to reap to the session, not only to main.log — never the leftover agent processes.
  • Both use the shared endedWorkNotice() line.

If you need a long build to survive a session restart, run it detached — a Windows Scheduled Task is outside the session's job and outside its process tree, so neither kill can reach it.

If sessions stop starting and your antivirus is involved

Every launch needs one file that ships beside the app: amc-hidden-launch.exe. It is what puts a session inside the process tree above, so while it is missing no session can start at all — Omniscio refuses rather than run an agent it could not stop.

Some antivirus programs remove that file as a false positive. McAfee's Real-Time Scanning has been seen doing it under the detection name ti!4B749D035640; a signed binary builds a publisher reputation an unsigned one never does, which is what makes the unsigned copies candidates. A released Windows build now ships both files signed by the app's own publisher and refuses to ship either one unsigned (the repo's windows-signing-contract records the rule), so the copies still exposed to this are an install older than that change, and — when you run Omniscio from a source checkout — the copy it makes in your user folder on every rebuild. When this happens, Omniscio tells you so in the session itself, in plain words, instead of leaving a session that is simply red.

To fix it:

  1. Open your antivirus's quarantine list and restore amc-hidden-launch.exe.
  2. Add that file — and its copy bash.exe in the trampoline folder beside it — to the antivirus's allowed or excluded files list.
  3. Restart Omniscio, then start the session again.

If the file is not in quarantine at all — a partial install, a policy that blocks it, or a failed update — reinstall Omniscio instead; that puts the file back.

The restart is not optional. Omniscio checks for the file once per app run, so a restored file is not noticed until the app starts again.

Where the two files live, and when that changes. When you run Omniscio from a source checkout, the helper runs from a copy in your user folder:

  • ~/.amc/launcher-run/hidden-launch-<id>/resources/amc-hidden-launch/amc-hidden-launch.exe
  • ~/.amc/launcher-run/hidden-launch-<id>/resources/amc-hidden-launch/trampoline/bash.exe

The copy inside your source checkout (resources/amc-hidden-launch/) is never run, so it needs no exclusion. The message in the session names the hidden-launch-<id> folder. That folder changes only when the helper itself (or the small script it reads) is rebuilt. Rebuilding Omniscio's other helper programs, which live in a separate helpers-<id> folder, leaves it where it is, so an exclusion keeps working across those updates. When the helper itself is rebuilt, add the two new files once more. Some antivirus programs, McAfee among them, drop an exclusion when the excluded file's contents change, so a new build needs adding again even at the same path.

What Omniscio does on a normal shutdown, and how a session is stopped by hand, is described on the Pause or stop a session page. Crash recovery after an unexpected exit is on Crash recovery.

Last verified 2026-11-14