# Truf Runtime Cheatsheet

## Быстрый старт

Команды выполняются из `D:\truf` в PowerShell.

```powershell
# Запустить весь canonical runtime
.\start_runtime.ps1

# Запустить explicit core set с keychecks, без dashboard
.\start_core_runtime.ps1

# Подключиться к интерактивной консоли supervisor
.\attach_runtime.ps1

# Координированно остановить весь runtime и PostgreSQL
.\stop_runtime.ps1
```

Если PowerShell блокирует запуск скриптов:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\start_runtime.ps1
```

Для полного рестарта используй именно:

```powershell
.\stop_runtime.ps1
.\start_runtime.ps1
```

Для полного рестарта в core-only режиме:

```powershell
.\stop_runtime.ps1
.\start_core_runtime.ps1
```

Не используй `restart all` как замену полному рестарту: pipeline workers защищены от ручного рестарта, пока scanner sources работают.

## Что запускается

| Компонент | Назначение |
|---|---|
| PostgreSQL | Единственный authoritative storage |
| `result-ingester` | Переносит scan bundles в PostgreSQL |
| `jsonl-projector` | Создаёт compatibility JSONL projections |
| `janitor` | Обслуживает runtime queues и временные данные |
| `github` | GitHub scanner loop |
| `gitlab` | GitLab scanner loop |
| `huggingface` | Hugging Face scanner loop |
| `dockerhub` | Docker Hub scanner loop |
| `package_git` | Package/repository scanner loop |
| `keychecks` | Почасовой provider checker scheduler |

Одновременно выполняется максимум `3` scan workers. Dashboard при обычном запуске выключен.

## PowerShell-скрипты

| Скрипт | Что делает |
|---|---|
| `start_runtime.ps1` | Запускает freeze diagnostics, проверяет identity PostgreSQL и поднимает background supervisor |
| `start_core_runtime.ps1` | Поднимает PostgreSQL, pipeline, janitor и три discovery-only producer; dashboard выключен |
| `stop_runtime.ps1` | Выполняет authenticated coordinated shutdown supervisor, children и PostgreSQL |
| `attach_runtime.ps1` | Открывает интерактивную supervisor-консоль; `quit` только отключает консоль |
| `start_freeze_counters.ps1` | Запускает Windows performance counters в `H:\truf-diagnostics` |
| `monitor_runtime_lag.ps1` | Пишет CPU/RAM/disk/runtime lag в CSV |
| `cleanup_stale_agentui_vite.ps1` | Отдельная уборка старых AgentUI/Vite процессов; без `-Apply` только dry run |
| `runtime\check-openrouter-keys.ps1` | Retired; намеренно завершается ошибкой |

В проекте нет собственных `.bat`/`.cmd`. Найденные BAT внутри `runtime\postgres\pgsql\pgAdmin 4` принадлежат pgAdmin и для Truf не используются.

## Full и Core-only режимы

`start_runtime.ps1` использует allowlist `supervisor.enabled_sources` из `config.linux.yaml`. Сейчас этот allowlist уже равен distributed core set, поэтому оба start-скрипта запускают одинаковые discovery producer.

`start_core_runtime.ps1` фиксирует core set прямо в wrapper и не зависит от будущего расширения default allowlist:

```text
gitlab,dockerhub,huggingface
```

PostgreSQL, `result-ingester`, `jsonl-projector`, `janitor` и независимо включённый `keychecks` также запускаются. Dashboard не запускается.

Чтобы сменить режим, сначала останови текущий supervisor через `.\stop_runtime.ps1`, затем запусти нужный start-скрипт. `stop_runtime.ps1` одинаков для обоих режимов.

## Core Sources

| Source | Что производит на сервере |
|---|---|
| `gitlab` | Ищет недавно активные GitLab projects и ставит их в очередь remote workers |
| `dockerhub` | Ищет Docker Hub images и ставит в очередь только immutable `repo@sha256:...` targets |
| `huggingface` | Ищет новейшие Hugging Face Spaces и ставит их в очередь remote workers |

`result-ingester`, `jsonl-projector`, `janitor` и `keychecks` отображаются как отдельные system workers, но не являются discovery sources. GitHub и `package_git` остаются доступными legacy/manual source, однако в distributed core profile не входят.

## Janitor

Janitor обслуживает только scanner work area (`S:\scanner-work`), а не PostgreSQL и не provider status files.

- Каждые `60` секунд ищет временные каталоги разрешённых типов.
- Рассматривает только каталоги старше `7200` секунд.
- Требует приватный `.scanner-owner.json` с точным process identity.
- Удаляет каталог только если owner и parent гарантированно мертвы.
- Не следует по symlink, junction или другим reparse points.
- Один проход ограничен `50` каталогами, `10000` entries, `1 GiB`, `30` секундами и depth `64`.
- Не имеет PostgreSQL credentials и не удаляет findings, keycheck history, current state или найденные секреты.

Примеры диагностики:

```powershell
# Один диагностический замер
.\monitor_runtime_lag.ps1 -Once

# Свой файл и интервал
.\monitor_runtime_lag.ps1 -OutputPath H:\truf-diagnostics\lag.csv -IntervalSeconds 10

# Безопасный просмотр кандидатов на очистку Vite
.\cleanup_stale_agentui_vite.ps1

# Реальная очистка найденного точного набора
.\cleanup_stale_agentui_vite.ps1 -Apply
```

## Supervisor-команды

Сначала запусти `.\attach_runtime.ps1`, затем используй команды ниже.

| Команда | Назначение |
|---|---|
| `help` | Полная встроенная справка |
| `status` | Свежий status table |
| `watch` | Live status; `q` возвращает в prompt |
| `auth <source|all>` | Состояние auth pools |
| `logs <source> [N]` | Последние `N` строк bounded-лога |
| `command <source|all>` | Фактическая child-команда, log и state paths |
| `start <source|all>` | Запустить остановленный source |
| `stop <source|all>` | Остановить и оставить остановленным |
| `restart <source|all>` | Перезапустить отдельный source |
| `pause <source|all>` | Остановить и отметить paused |
| `resume <source|all>` | Снять pause и запустить |
| `once <source|all>` | Один проход source с `--once` |
| `mode <source|all> loop|once|repeat` | Изменить режим source |
| `set <source|all> interval <sec>` | Интервал repeat mode |
| `set <source|all> restart on|off` | Автоматический restart после сбоя |
| `set <source|all> restart_delay <sec>` | Начальная задержка restart |
| `dashboard status|start|stop|restart` | Управление dashboard |
| `shutdown` | Полный coordinated shutdown |
| `quit` | В attach-режиме только отсоединиться |

`reload` намеренно отключён. После изменения `config.yaml` или runtime-кода нужен полный `stop_runtime.ps1` + `start_runtime.ps1`.

Source alias: `docker` означает `dockerhub`.

## Статусы

| Статус | Значение |
|---|---|
| `running` | Child сейчас работает |
| `waiting` | Ожидает следующего запуска/retry |
| `blocked` | Ждёт стабильной готовности PostgreSQL |
| `paused` | Остановлен командой `pause` |
| `done` | Успешный one-shot завершён |
| `failed` | Child завершился с ошибкой, restart выключен |

`desired=running` показывает желаемое состояние. `rs` означает текущую серию ошибок / общее число automatic restarts. Старый `exit=1` рядом с уже `running` source относится к предыдущей попытке запуска.

## Keycheck Recheck

Формат:

```text
recheck <service|all> [type ...] [options]
```

Если type не указан, выполняется полный `--recheck-all` выбранного service.

### Типы

| Type | Что ставится в очередь |
|---|---|
| `network` | Текущие transient network statuses |
| `ratelimited` | Limited/rate-limited и связанные no-balance statuses |
| `unknown` | Unknown и no-context |
| `restricted` | Restricted |
| `nobalance` | No-balance/no-quota |
| `valid` или `alive` | Текущие alive credentials |
| `all` | Все известные credentials |
| `legacy-vertex` | Только GCP: импортировать и проверить отсутствующие legacy Vertex TXT credentials |

### Опции

| Опция | Значение |
|---|---|
| `--force` | Остановить уже работающий keycheck batch и начать этот |
| `--max-keys N` | Ограничить число credentials |
| `--proxy-file PATH` | Временно переопределить proxy file |
| `--no-resource-probe` | Отключить resource probe; сейчас используется Replicate |
| `--no-summary` | Не пересобирать summary/status projections после batch |

`--input PATH` является legacy/offline compatibility option и в canonical PostgreSQL runtime не используется.

### Примеры

```text
# Повторить только network failures у всех providers
recheck all network

# Перепроверить все текущие alive GCP credentials
recheck gcp valid

# Полностью перепроверить Qwen
recheck qwen all

# Проверить максимум 5 alive Replicate без resource probe
recheck replicate valid --max-keys 5 --no-resource-probe

# Импортировать/дедуплицировать старые GCP Vertex TXT записи и проверить только их
recheck gcp legacy-vertex

# Прервать текущий keycheck batch и запустить новый
recheck gcp valid --force
```

Scheduled keychecks запускаются раз в `3600` секунд. По умолчанию проверяются новые candidates и повторяются только `NETWORK`; alive/limited/unknown/restricted/no-balance автоматически каждый час не перепроверяются.

## Текущие GCP Vertex Probes

| Provider | Модели | Locations | Проверка |
|---|---|---|---|
| Google | `gemini-3.6-flash`, `gemini-3.1-pro-preview` | `global`, `us`, `eu` | `countTokens`, без генерации |
| Anthropic | `claude-opus-5`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-fable-5` | `global`, `us`, `eu`, `us-east5`, `europe-west1` | `rawPredict`, до 1 output token |

Anthropic probe является реальным минимальным inference-вызовом и может иметь небольшой расход.

## Куда идут данные

1. Scanner sources создают result bundles.
2. `result-ingester` пишет findings и keycheck candidates в PostgreSQL.
3. Provider checker арендует candidate и выполняет API probe через `runtime\proxy.txt`.
4. Новый результат добавляется в append-only `keycheck_results`.
5. `keycheck_current_state` переключается на последний результат.
6. `jsonl-projector` создаёт compatibility JSONL.
7. Summary projection атомарно обновляет status TXT.

PostgreSQL является source of truth. TXT/JSONL в `runtime\keychecks` являются compatibility projections, а не входом для обычного recheck.

## Полезные пути

| Путь | Назначение |
|---|---|
| `app\config.yaml` | Основная конфигурация runtime, sources и probes |
| `runtime\proxy.txt` | Proxy для provider checks |
| `runtime\logs\supervisor.status.txt` | Последний status snapshot |
| `runtime\logs\supervisor.log` | Supervisor log |
| `runtime\logs\keychecks.log` | Общий keycheck log |
| `runtime\keychecks\summary.tsv` | Текущий provider summary |
| `runtime\keychecks\alive_summary.tsv` | Краткий alive summary |
| `runtime\keychecks\<service>` | Compatibility status/results files provider-а |
| `runtime\control\supervisor.instance.json` | Private control metadata; вручную не редактировать |
| `S:\postgres-data` | Canonical PostgreSQL cluster |
| `S:\scanner-work` | Scanner scratch/work area |

## Безопасность

- Не запускай provider scripts напрямую.
- Не передавай raw credentials через CLI.
- Не редактируй `supervisor.instance.json`.
- Для управления используй только authenticated supervisor.
- Для полного рестарта используй canonical start/stop scripts.
- Не удаляй PostgreSQL cluster или runtime queues вручную.