# Runtime Hygiene

Runtime hygiene keeps long-running Omnius instances from accumulating stale state, stuck child processes, or leaked project artifacts.

## `.omnius/`

`.omnius/` is runtime state and should not be committed. Omnius automatically adds it to `.gitignore` for repositories that have or later create a `.gitignore`.

## Ollama Pool Cleanup

Ollama servers spawned by the pool should run as process-group leaders. Cleanup must account for:

- direct `ollama serve` children
- orphaned `ollama runner` children
- stale pool records
- protected base services
- active runners that should not be killed

Use dry-run first:

```text
/ollama cleanup
```

Execute only when the cleanup decision looks correct:

```text
/ollama cleanup --execute
```

## Model Broker

```text
/broker
/broker evict <host>:<name>
/broker threshold <ram|vram|idle> <value>
```

The broker reports loaded models, in-flight loads, RAM/VRAM headroom, GPU slots, idle eviction thresholds, and manual eviction actions.

## Installer Elevation

Installers that need elevation should temporarily suspend the TUI, present the password prompt directly in the terminal, consume it through the system elevation path, and restore TUI state after completion.

## Raw Failure Capture

Shell, installer, Telegram, sponsor, and API failures should be captured as observed output and fed back to the agent loop. Avoid hardcoded string-specific reward or routing hacks.

## Update And Install Triage

`/update full` may touch npm packages, Python virtualenvs, cloudflared, voice dependencies, media backends, and system packages. The updater should classify failure by the command that failed and the raw process result, then try the next safe remediation:

| Failure Surface | First Remediation |
| --- | --- |
| npm cache permission | rerun with the configured local npm cache |
| missing Python wheel | prefer binary wheels, then surface the package and Python version |
| system dependency missing | request elevation and run the documented package install |
| password prompt needed over SSH | suspend the TUI, clear the terminal, read the system prompt, then restore |
| model backend install failed | record backend, command, exit code, stderr, and next suggested command |

The runtime should never hide installer output behind a generic spinner. Dynamic output should stream into the bounded shell block, preserving the last visible lines and a clean overflow indicator.

## TUI State During Elevation

When an elevated install is required:

1. save the current TUI render state and input buffer
2. stop alternate-screen drawing if active
3. show the real password request in the terminal
4. run only the requested elevated command
5. clear sensitive prompt residue
6. restore the TUI frame and input buffer
7. add the raw command result to the agent trajectory

This path is required for SSH sessions where a desktop password modal cannot appear.