38 lines
4.1 KiB
Markdown
38 lines
4.1 KiB
Markdown
---
|
||
title: Runbook — session
|
||
summary: Сессии и handoff в mappa: live-ingest (session_upsert/heartbeat), ритуал старта (orient: pull → handoff → inbox → liveness), ритуал финиша (closing: handoff-write), ветки на диск (git worktree). Источник: brainstorm:173.
|
||
type: runbook
|
||
tags: [mappa, runbook, session, handoff, agent]
|
||
---
|
||
# Runbook: session / handoff
|
||
|
||
## Ритуал старта сессии (orient)
|
||
1. **Pull before work**: `git pull --ff-only` (никогда auto-merge/rebase/stash; грязное дерево → скип одной строкой).
|
||
2. **Handoff-чтение**: последняя handoff-сущность проекта (`entity_search type=handoff`) → summary/open_treks/ask_user/guards → «предыдущая сессия предложила X — делаем?» → ждать человека (не авто-исполнять).
|
||
3. **Инбокс**: inbox_monitor → обработать письма (Г2); письма в начале ближайшего хода.
|
||
4. **Liveness**: «alive/dead» одной строкой; deep-диагностика — вне ритуала (человеку/диагностической сессии).
|
||
5. Welcome-снапшот — по запросу, НЕ авто на первом ходу.
|
||
|
||
## Live-ingest (телесные хуки)
|
||
- Сессия = сущность (session:N): `session_upsert(sourceRef, project, runtime, machine, folder)` — create/update; `session_heartbeat(id, working_on)` — пульс; action=finalize → clean-завершение.
|
||
- Claim-гейт (repo,branch): `session_hold(repo, branch)` — свободно → работай; чужой клейм → НИЧЕГО не делать, сообщить человеку «кто держит», ждать (ревок — только оператор).
|
||
- Stale-active (обрыв) → crash-detect: сказать человеку, предложить (игнор/напоминание письмом/продолжить).
|
||
|
||
## Ветки на диск (git worktree)
|
||
- **Ветка = рабочее дерево (папка).** Одна ветка — одно извлечение; одну ветку нельзя выкатить в двух worktree одновременно (`fatal: already checked out`).
|
||
- **Параллельные ветки** → отдельные рабочие деревья:
|
||
```bash
|
||
git worktree add C:/Users/vitya/projects/.worktrees/mappa-<slug> worker/<slug>
|
||
git worktree list # карта: folder → branch → commit
|
||
git worktree remove C:/Users/vitya/projects/.worktrees/mappa-<slug>
|
||
```
|
||
- **Что на диске:** у worktree `.git` — это ФАЙЛ (`gitdir: <главный-репо>/.git/worktrees/<имя>`), не папка. Объекты/refs — ОБЩИЕ (главный `.git/objects`, у нас 51M); per-worktree — только HEAD/index/refs/logs в `<главный>/.git/worktrees/<имя>/`; `commondir` → на общий пул.
|
||
- **Имя папки ≠ маппинг проекта.** Клиент мапит `project=basename(folder)`: для параллельных кластеров либо слать явный `project="mappa"`, либо класть worktree под именем, не ломающим project-резолв. Каждый worktree = отдельная связка сессии (`sourceRef`/folder) → разные ветки = разные клеймы `(repo,branch)` → 409 нет.
|
||
|
||
## Ритуал финиша (closing)
|
||
- `handoff_write(project, session_id, status, summary, open_treks, ask_user, guards, recent_commits)` — по решению человека (не авто-sweep).
|
||
- PROPOSE wiki-ingest (важное знание → вики) + PROPOSE закрытия тасок. Мутации — после подтверждения.
|
||
|
||
## Связано
|
||
[[runbooks/index]] · [[runbooks/inbox]] · [[runbooks/tasks]] · [[canon/gates]] · контракт wiki:2660 · [[concepts/session-live-ingest]] (wiki:2604) · [[methodology/kzntsv/index]] (wiki:3404) · brainstorm:173
|