# Processes

A process is a long-running command — `tsc --watch`, `vitest --watch`, `npm run dev`, `php artisan serve`, `tail -f some.log` — declared in `cockpit.yaml` under `processes:`. The cockpit spawns each process once at boot and streams its stdout / stderr into the Output pane, tagged by source.

Distinct from:
- **Actions** (one-shot shell commands surfaced via the `:` palette and per-row keys)
- **Health checks** (state predicates with one-keystroke remediation)
- **Docker tailing** (`config.docker` — already managed by docker compose)

## Config shape

```yaml
processes:
  - id: typecheck                       # required, unique; used as the Output source tag and Targets row id
    label: tsc --watch                  # optional; shown in Repos + Output
    command: npx tsc --watch --noEmit   # shell command; runs via sh -c (cmd /c on Windows)
    cwd: ./apps/web                     # optional; relative to workspaceRoot
    env:                                # optional; merged on top of process.env
      DEBUG: '1'
```

`command` runs through the shell so pipes, redirects, env-prefixes, and properly-quoted arguments all work as expected.

## Built-in restart

Every process gets a Targets row of `kind: process` with a built-in action `[r] Restart <id>` (key: `r`, scope: `repos:<id>`). The implementation: SIGTERM the tagged child (via `killSpawnedByTag`), wait for it to exit, then re-spawn it with the same command + cwd + env.

You can shadow `r` with a custom action of the same scope + key — declared actions outrank built-ins in the dispatch precedence.

## Output + highlights

Each line from a process's stdout / stderr gets:
- The source label (or `id`) as a tag.
- Default severity: `info` for stdout, `warn` for stderr.
- Highlight matching against `config.highlights[]`. A matched pattern's `severity:` wins over the default — so a `pattern: 'boom', severity: error` highlight upgrades any line containing "boom" to `error`, which shows as `✗`-prefixed in Output and feeds the Recent Errors strip.

## Lifecycle

- Spawned on `dev-cockpit dev` boot.
- Tagged with the process's `id` so the per-row restart action can find the right child.
- Reaped on cockpit shutdown (`q` or SIGTERM) via `killAllSpawned` — SIGTERM with a 1.5s SIGKILL fallback.
- No fsevent-driven respawn — the process command itself (`tsc --watch`, etc.) is expected to handle re-runs internally.
