# runtime

Runtime detection telemetry for Pi footer/status.

## Install / load

Loaded through the root `pi-ext` package.
See [root README](../../README.md).

## Commands / tools / settings

- Commands: none.
- Tools: none.
- Hooks: `session_start`, `agent_end`, `session_shutdown`.
- Settings: `runtime.versionTimeoutMs`.

## Settings

`runtime.versionTimeoutMs` sets the runtime version lookup timeout in milliseconds.
Environment variable: `PI_RUNTIME_VERSION_TIMEOUT_MS`.
Default: `2500`.
Valid range: integer from `1` to `2147483647`.
Precedence: environment variable, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings are ignored unless the project is trusted.
Settings files need a JSON number; the environment variable accepts a numeric string.
The value is resolved once per session start.
An invalid value from any source warns once and uses the default; lower sources are not consulted.

```json
{ "runtime": { "versionTimeoutMs": 5000 } }
```

## Behavior

Detects project runtime from marker entries in `cwd`, then parent dirs up to
`$HOME`. If `$HOME` is unset, or `cwd` is outside `$HOME`, only `cwd` is
checked.

Detection order:

- `bun`:
  `bun.lock`, `bun.lockb`
- `deno`:
  `deno.json`, `deno.jsonc`, `deno.lock`
- `lua`:
  `stylua.toml`, `.stylua.toml`, `.luarc.json`, `.luarc.jsonc`, `init.lua`,
  `lua`, `*.lua`
- `nodejs`:
  `package.json`, `.nvmrc`, `.node-version`
- `python`:
  `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg`, `Pipfile`,
  `.python-version`
- `golang`:
  `go.mod`
- `rust`:
  `Cargo.toml`
- `java`:
  `pom.xml`, `build.gradle`, `build.gradle.kts`
- `ruby`:
  `Gemfile`, `.ruby-version`
- `php`:
  `composer.json`

Reads runtime version with the matching runtime binary when available.
Version lookup times out after `runtime.versionTimeoutMs` (default 2500 ms).
Missing binaries leave the runtime name as text.

If `@bugabinga/pi-ext-footer` is loaded, emits `footer:segment`:

- id: `runtime`
- zone: `workspace`
- order: `3`

Without footer, writes Pi status text under id `runtime`.

Refreshes on session start and agent end.
UI output is skipped when the session has no UI.

Clears segment/status when no runtime is detected or session shuts down.

## Debug

Opt in through [debug configuration](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `runtime.detect.start`, `runtime.detect.finish`, `runtime.detect.error`.