# Terminal tinting: the gate you can see

`gate tint` is the ambient layer of myGate.
Where the hook *says* no (deny) or taps you on the shoulder (notify), tint changes your
terminal's background color so the gate's state is visible at a glance — before you even
read anything.
It also does ambient duty for plain shell life: directories, places, and commands can
carry their own colors.

At every shell prompt, the shell invokes `gate tint` with the current directory and the
last command's name and exit status.
`tint` decides which color (if any) applies and emits an OSC 11 escape sequence to the
terminal.

```zsh
precmd() { gate tint -d "$PWD" -s "$?" &! }
```

Background + disown (`&!`) keeps the prompt fast: the tint process never blocks your
readline, and a slow or missing config costs you nothing.
Capturing the last command's *name* (`-n`) is optional — zsh users can pass e.g.
`${${(z)history[$HISTCMD]}[1]}` — without it, command triggers simply never fire.

The escape is written to `/dev/tty` directly by `my-basis` (`ut.emit_osc11`, the fleet
radix for OSC 11), so it still works when stdout is redirected or captured.

## Gate events

The hook records content-free event state (`state.json`, next to the telemetry
counters) as it works; `gate tint` turns that state into color.
Only events named in your `[events]` table can fire, and they evaluate in a fixed
severity order — first match wins:

| Predicate | Fires while | Default window |
| --- | --- | --- |
| `denied_recently` | a launch was denied in the last `denial_window` seconds | 600s |
| `heavy_active` | a superheavy subagent started in the last `activity_window` seconds (and hasn't stopped) | 3600s |
| `workflow_active` | a workflow launched in the last `activity_window` seconds (and hasn't stopped) | 3600s |
| `grant_active` | any unexpired grant with uses remaining exists | — |

A `SubagentStop` drops that session from the heavy/workflow maps, so the tint clears
when the fan-out actually finishes.
Session entries older than 24 hours are pruned on every write.

## Configuration

Config lives at `~/.config/gate/tint.toml` (override with `$GATE_TINT_CONFIG` or
`--config`).
Write a commented starter with `gate tint init` (add `--force` to overwrite).

```toml
base_color = "slate"        # revert color when leaving a triggered dir
denial_window = 600         # seconds a deny event keeps tinting
activity_window = 3600      # seconds heavy/workflow activity counts as active

[aliases]                   # name -> hex; overrides built-ins
jade = "#2B8A6E"

[events]                    # predicate -> color; severity order is fixed (above)
denied_recently = "red"
heavy_active = "orange"
workflow_active = "amber"
grant_active = "violet"

[directories]               # raw regex prefixes; nested tables compose
"~/my/apps" = { irix = "jade", "superheavy-gate" = "cyan" }

[commands]                  # raw regex matched against the last command name
"^git push" = "red"

[places]                    # literal path prefixes (escaped, match on boundary)
"~/vault" = "violet"
```

Colors resolve in this order: a verbatim `#rrggbb` → your `[aliases]` → the built-in
alias table (`slate`, `red`, `orange`, `amber`, `green`, `jade`, `cyan`, `blue`,
`violet`, `purple` — the irix-dark `sheet2` swatches) → the full irix palette, if
`irix` happens to be importable (optional; never required).
When several triggers match, the longest (most specific) pattern wins, so config order
is never load-bearing.

Full precedence in `decide()`:

1. `$GATE_TINT_COLOR` (one-shot shell override)
2. the persistent manual override (`gate tint set`)
3. an explicit `--color` flag
4. gate events, in severity order
5. command trigger
6. directory trigger
7. outward-reset to `base_color` when `$OLDPWD`'s subtree was left

## Overrides and kitty

```sh
gate tint set jade      # persistent manual override, beats every trigger
gate tint show          # current override + effective color
gate tint clear         # back to triggers
gate tint multiset cyan amber   # all kitty windows in the tab (CSS-style repeat)
```

The override persists in the gate state directory until cleared.

## Honest caveats

- Terminal-emulator OSC 11 support varies; some terminals ignore it outright.
- SSH, tmux, and some corporate/managed terminal setups strip OSC sequences in
  transit — tmux in particular needs `set -g allow-passthrough on` to forward OSC 11
  to the real terminal.
- When any of the above holds, tint degrades to "no visible tint" with no error
  surfaced anywhere; the gate's deny/notify mechanisms are the signals that always
  work and should be treated as primary. Tint is a nice-to-have on top.
- On Windows there is no `/dev/tty`; the escape falls back to stdout.