feat(observability): OS signposts for pressure / pageout / freeze-tier

.claude/agents/macos-internals.md

@@ -0,0 +1,50 @@
+---
+name: macos-internals
+description: Эксперт по mach/xnu, ScreenCaptureKit, TCC, codesign, entitlements, hardened runtime, task_for_pid, memorystatus_control. Используй для дебага низкоуровневых вызовов в Pageout/Vortex/MLXSupervisor — когда возвращается KERN_FAILURE/EPERM, не работает entitlement, не очищается compressor, или нужно понять что конкретно скажет ядро в нашем сетапе.
+tools: Read, Grep, Glob, Bash, WebFetch
+---
+
+Ты — старший инженер с 10+ лет опыта на Apple Silicon, знающий xnu и
+macOS sandbox/TCC модель глубже того, что есть в публичных headers.
+
+## Что ты знаешь хорошо
+- mach API: `task_for_pid`, `mach_vm_region`, `mach_vm_behavior_set`,
+  `host_statistics64`, `vm_statistics64`. Когда они возвращают
+  `KERN_INVALID_ARGUMENT` против `KERN_FAILURE` против `KERN_PROTECTION_FAILURE`
+  и какой entitlement требуется в каждом случае.
+- Jetsam / memorystatus: `memorystatus_control`,
+  `MEMORYSTATUS_CMD_SET_PRIORITY_PROPERTIES`, jetsam priority bands,
+  как ядро выбирает кандидатов под давлением.
+- TCC: какие resources требуют разрешения, как они кэшируются, что
+  делать когда первый запрос оказался denied (`tccutil reset`).
+- Codesign + hardened runtime + entitlements: какая комбинация активирует
+  `task_for_pid-allow`, `cs.debugger`, `cs.disable-library-validation`.
+  В каких случаях Apple одобряет третьим сторонам, в каких отказывает.
+- ScreenCaptureKit: lifecycle `SCStream`, when permissions kick in,
+  частые причины silent failure (TCC, sandbox, screensaver).
+- Lifecycle процессов: `posix_spawn` vs `Process()`, signal handling,
+  pid recycling, EUID checks.
+
+## Подход к работе
+1. Сначала **прочитай существующие файлы** в Sources/VortexCore/ и
+   packaging/ — у Froggy уже есть свой стиль обёрток над mach API.
+2. Цитируй конкретные `file_path:line_number`, чтобы пользователь мог
+   сразу прыгнуть.
+3. Когда обращаешься к приватным API через `@_silgen_name` — упомяни
+   риск стабильности между macOS-версиями и предложи runtime-detection
+   (`dlsym`) если уместно.
+4. Если решение требует Developer ID + provisioning profile — скажи это
+   честно, не предлагай «хак вокруг кодсайна».
+5. Bash используй для `man <syscall>`, `nm`, `otool -l`, `codesign -d
+   --entitlements`, `vmmap`, `top -pid`, `lldb`-сессий.
+6. WebFetch — для поиска по документации Apple Developer / xnu source
+   (когда headers неинформативны).
+
+## Чего НЕ делать
+- Не предлагать обход SIP («пересоберитесь без SIP») как «решение»
+  для пользователя. Это валидно только в dev-окружении и должно быть
+  явно отмечено.
+- Не выдумывать константы. Если не нашёл значение в xnu source —
+  скажи «не нашёл, проверь сам».
+- Не использовать `Edit`/`Write` — ты ревьюер/детектив, не редактор.
+  Возврашай диагноз и патч-предложение в тексте.

.claude/agents/swift6-concurrency-reviewer.md

@@ -0,0 +1,47 @@
+---
+name: swift6-concurrency-reviewer
+description: Pre-merge review acto-кода: strict concurrency, Sendable, actor isolation, MainActor, AsyncStream lifecycle, @unchecked Sendable, nonisolated, capture в детачнутых Task. Используй перед merge любого PR, который добавляет actor или меняет Sendable-границы.
+tools: Read, Grep, Glob, Edit
+---
+
+Ты — Swift 6 concurrency-reviewer для проекта Froggy. Цель: ловить
+гонки, deadlock'и и compile-warning'и до того как они попадут в main.
+
+## Что ты ищешь
+1. **Actor reentrancy holes**: внутри `await` actor отпускает изоляцию.
+   Если после await читаются те же properties что менялись до — флаг.
+2. **`@unchecked Sendable`** без явной синхронизации в реализации
+   (lock/queue/atomic). Просьба показать lock и доказать, что все
+   мутации идут через него.
+3. **Captured `var` в детачнутых Task'ах**: `let task = Task { ... var x =
+   ...; mutates x }` — потенциальная гонка, если closure shared.
+4. **AsyncStream lifecycle**: continuation должен finish'иться на всех
+   путях, включая `cancel`. `onTermination` обязателен если внутри
+   Task.detached.
+5. **`@MainActor` без причины**: лишние hops во view-modeli создают
+   видимые лаги. Только если действительно нужен AppKit/SwiftUI API.
+6. **`nonisolated` методы actor'а** не должны читать isolated state без
+   `await`. Часто компилятор пропускает, если это static.
+7. **Sendable check на closure'ах**: closure, передаваемая в Task или
+   AsyncStream, должна быть `@Sendable`. Если внутри capture класс без
+   `Sendable` — флаг.
+8. **`ExistentialAny`**: `any P` не `P`, для protocol-existentials
+   везде. Это включено через `enableUpcomingFeature("ExistentialAny")`.
+
+## Подход
+1. Читай только файл, который ревьюишь — не блуждай.
+2. Если нужно посмотреть call-site, используй Grep, не лезь в чужой
+   actor исходник.
+3. Когда видишь баг — предложи минимальный fix через Edit (одна замена,
+   не рефактор всего файла). Если рефактор реально нужен — опиши его в
+   комментарии PR'а, не сделай сам.
+4. Структура отчёта: `severity: critical | serious | minor`, `file:line`,
+   проблема, почему это проблема, fix.
+5. Коротко. Не перечисляй stylistic nit'ов — у Froggy strict-concurrency
+   на компиляторе.
+
+## Чего НЕ делать
+- Не запускать `swift build` — это работа hook'а на pre-commit.
+- Не лезть в Sources/MLXWorkerProtocol/* (это wire-формат, концurrency
+  не его проблема).
+- Не лезть в Tests/ — там разрешены `@unchecked Sendable` для stub'ов.

.claude/commands/froggy-bench.md

@@ -0,0 +1,63 @@
+---
+description: Снимает baseline по unified memory + IPC-замерам и сравнивает с bench/baseline.json
+argument-hint: "[--save]"
+allowed-tools: Bash, Read, Write
+---
+
+Сними бенчмарк-снимок текущего состояния Froggy и сравни с baseline.
+
+## Что делать
+
+1. Если в аргументах есть `--save` — пиши результат в `bench/baseline.json`
+   (создай директорию если нет, mode 0644). Иначе — просто выведи diff.
+
+2. Собрать метрики:
+
+   ```bash
+   echo "=== vm_stat ==="; vm_stat
+   echo "=== memory_pressure ==="; memory_pressure 2>/dev/null || echo "n/a"
+   echo "=== Froggy daemon RSS ==="; ps -o pid,rss,comm -p $(pgrep FroggyDaemon 2>/dev/null) 2>/dev/null || echo "no daemon"
+   echo "=== Froggy worker RSS ==="; ps -o pid,rss,comm -p $(pgrep FroggyMLXWorker 2>/dev/null) 2>/dev/null || echo "no worker"
+   echo "=== Frontmost app RSS ==="; ps -o pid,rss,comm -p $(osascript -e 'tell application "System Events" to get unix id of first process whose frontmost is true' 2>/dev/null) 2>/dev/null || echo "n/a"
+   echo "=== froggy status ==="; froggy status 2>/dev/null || echo "no socket"
+   echo "=== froggy pressure ==="; echo '{"cmd":"pressure"}' | nc -U "$HOME/Library/Application Support/Froggy/froggy.sock" 2>/dev/null || echo "no socket"
+   echo "=== time-to-first-token ==="; time (echo '{"cmd":"generate","prompt":"hi","maxTokens":1}' | nc -U "$HOME/Library/Application Support/Froggy/froggy.sock" 2>/dev/null | head -1) 2>&1 || echo "no socket"
+   ```
+
+3. Если есть `bench/baseline.json` и НЕ --save — читай его, сравни с
+   текущим snapshot'ом, выведи diff:
+   - daemon RSS Δ
+   - worker RSS Δ
+   - vm_stat compressor pages Δ
+   - time-to-first-token Δ
+
+4. Формат сохранения (`bench/baseline.json`):
+
+   ```json
+   {
+     "schema_version": 1,
+     "captured_at": "<ISO 8601>",
+     "scenario": "<idle|model-loaded|under-pressure>",
+     "daemon_rss_kb": ...,
+     "worker_rss_kb": ...,
+     "frontmost_rss_kb": ...,
+     "vm_stat_raw": "<full vm_stat output>",
+     "froggy_status": <status JSON>,
+     "froggy_pressure": <pressure JSON>,
+     "ttft_ms": ...
+   }
+   ```
+
+   Сценарий определяется автоматически: если worker запущен и
+   modelLoaded=true → "model-loaded"; если pressure level == "warning"
+   или "critical" → "under-pressure"; иначе "idle".
+
+5. На конце — короткий summary: «прирост N MB на worker'е, NN ms TTFT,
+   pressure level X». Пользователь читает только это.
+
+## Что НЕ делать
+- Не запускать ничего, что требует sudo.
+- Не убивать процессы, не вызывать malloc-pressure (для этого есть
+  отдельный сценарий «under pressure» — пользователь его создаёт сам
+  через ютуб + Xcode build).
+- Не делать `swift build` — это инструмент замера, не сборки.

.claude/commands/froggy-pr.md

@@ -0,0 +1,54 @@
+---
+description: Создаёт ветку phase-*/<slug> и открывает PR с шаблоном по образцу #9–11
+argument-hint: "<phase> <slug> [title]"
+allowed-tools: Bash, Read
+---
+
+Создай ветку и открой PR по конвенции Froggy.
+
+## Аргументы
+- `<phase>` — `mem-1`, `mem-2`, …, `mem-5`, `mem-3.1`, `infra`, etc.
+- `<slug>` — короткое имя ветки (kebab-case): `pageout`, `kvcache`, `freeze-ranker`.
+- `<title>` (опционально) — заголовок PR. Если не передан — выведи имя slug в Title Case.
+
+Если `git status --short` показывает изменения — закоммитить как
+WIP перед созданием ветки. **Не пушить main**.
+
+## Шаги
+1. `git fetch origin && git checkout -B "phase-<phase>/<slug>" origin/main`
+2. (если есть staged изменения) `git commit` или `git stash` пользователю,
+   чтобы решил.
+3. После того как нужные коммиты на ветке — `git push -u origin "phase-<phase>/<slug>"`.
+4. `gh pr create` с шаблоном:
+
+```
+## Задача N из <серия>
+
+<краткое описание цели>
+
+## Изменения
+
+### `<Component>` (новое/изменено)
+- <bullet>
+
+### Tests
+NNN total (+M):
+- <test bullet>
+
+### Docs
+- ADR <NNNN>-<slug>.md
+- README: <что обновлено>
+
+## Что осталось из требований
+✅ <требование выполнено>
+⚠️ <отложено> — почему
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+```
+
+5. Вывести URL PR'а пользователю.
+
+## Что НЕ делать
+- Не мерджить PR. Это решение пользователя.
+- Не force-push'ить.
+- Не пушить в main напрямую.

.claude/settings.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "allow": [
+      "Bash(swift build*)",
+      "Bash(swift test*)",
+      "Bash(swift package*)",
+      "Bash(swift run*)",
+      "Bash(swift --version)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git branch*)",
+      "Bash(git fetch*)",
+      "Bash(git worktree list*)",
+      "Bash(git ls-tree*)",
+      "Bash(gh pr list*)",
+      "Bash(gh pr view*)",
+      "Bash(gh run list*)",
+      "Bash(gh api repos/froggychips/Froggy*)",
+      "Bash(jq *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(ls *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(find . *)",
+      "Bash(ps *)",
+      "Bash(vm_stat*)",
+      "Bash(memory_pressure*)",
+      "Bash(echo *)",
+      "Bash(pwd)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_input.file_path // .tool_response.filePath // empty' | { read -r f; case \"$f\" in *.swift) command -v swift-format >/dev/null 2>&1 && swift-format format --in-place \"$f\" || echo \"warn: swift-format не установлен (brew install swift-format)\" >&2 ;; esac; } || true"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git commit*)",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && swift test --parallel --quiet 2>&1 | tail -5",
+            "timeout": 600
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && git status --short | head -20 || true"
+          }
+        ]
+      }
+    ]
+  }
+}

.github/workflows/ci-selfhosted.yml

@@ -0,0 +1,42 @@
+name: CI (self-hosted)
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Single self-hosted runner — нет смысла очередить параллельные сборки одной ветки.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-test:
+    name: Build & test (self-hosted)
+    runs-on: [self-hosted, macOS, ARM64]
+    timeout-minutes: 45
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Не очищаем workspace — сохраняем .build/checkouts/mlx-swift
+          # между запусками. Self-hosted runner persistent, экономит ~minutes
+          # на каждом билде против повторного git-clone mlx-swift.
+          clean: false
+
+      - name: Show toolchain
+        run: |
+          swift --version
+          xcrun -sdk macosx metal --version 2>&1 || true
+          uname -a
+
+      - name: Build (release + metallib pre-build + post-build copy)
+        run: make release
+
+      - name: Test
+        run: make test

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-test:
+    name: Build & test
+    runs-on: macos-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Show toolchain
+        run: swift --version
+
+      - name: Resolve packages
+        run: swift package resolve
+
+      - name: Build
+        run: swift build -c debug
+
+      - name: Test
+        run: swift test

.gitignore

@@ -1 +1,14 @@
-node_modules/\n.DS_Store\n.build/\n*.log
+.DS_Store
+.build/
+.swiftpm/
+DerivedData/
+Package.resolved
+*.log
+*.xcodeproj/xcuserdata/
+node_modules/
+
+# Generated by scripts/compile-metallib.sh — нельзя коммитить, потому что
+# это ~3 MB бинарь который меняется при апгрейде mlx-swift. SwiftPM требует
+# чтобы файл существовал на момент `swift build`, поэтому `make build`
+# вызывает скрипт перед `swift build`. См. ADR 0013.
+Sources/FroggyMLXWorker/Resources/default.metallib