admin/.mappa/share/runbooks/session.md

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).
• Параллельные ветки → отдельные рабочие деревья:

  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