pi-session-join

A pi extension that merges forked sessions back into the parent session via summarization.

Languages: English · Русский · Esperanto

---

English

/fork in pi moves a branch of the conversation into a separate session file. /join from this extension brings the results back: the fork's work is summarized by the current model and merged into the parent session's context — like git merge, but for sessions.

Install

# one run only
pi --extension /path/to/pi-session-join/extensions/session-join/index.ts

# global install (loads the file in place, edits apply after restart)
pi install /path/to/pi-session-join

# one project only (writes .pi/settings.json, requires project trust)
pi install -l /path/to/pi-session-join

Remove: pi remove /path/to/pi-session-join.

Usage

In the parent session (the one you forked from):

/join [fork-name-or-id]

• Without an argument, /join shows a fork selector (name, first message, date, and a "merged up to …" note for forks merged before). An argument and autocomplete match by fork name or id.
• The delta (everything added to the fork after the fork point or after the previous merge) is summarized by the current session model in the same structured format pi uses for branch summaries. Large deltas are split into chunks; partial summaries are merged in a second pass.
• The summary is inserted as a separate [SESSION JOIN] message, visible to the model and in the TUI. Press Esc during summarization to cancel without writing anything.

Incremental merge

A fork can keep going after a merge: the next /join merges only the new entries. The merged boundary is stored in the details of join messages in the parent session — the fork file itself is never modified.

Deleting a fork

After a successful merge the extension offers to delete the fork file (to trash via the trash tool, if installed, otherwise permanently). If the fork has its own child sessions, deletion is forbidden — the extension offers a recursive join instead: descendants are merged deepest-first (each as its own message), then the fork itself, and every file that became a leaf can be deleted.

Limitations

• Pull direction only: run /join from the parent session.
• The active branch of the fork is merged as a whole; picking an arbitrary stop point is not supported.
• Only the summary is carried over; raw entries are not copied into the parent.
• Interactive mode (TUI) only.
• Forks are found via the parentSession field in their header: renaming or moving the parent session file breaks the link.

Development

bun install
bun run check    # tsc --noEmit
bun run lint     # eslint (strictTypeChecked + sonarjs + perfectionist + archispec)

# fixture sessions + discovery/delta spike (no LLM)
bun scripts/make-fixtures.ts /tmp/psj-fixtures
bun scripts/spike-discovery.ts /tmp/psj-fixtures

Layout:

• extensions/session-join/index.ts — /join command, renderer, UI flow
• extensions/session-join/discovery.ts — fork discovery and descendant tree
• extensions/session-join/delta.ts — delta computation and merge markers
• extensions/session-join/join.ts — summarization pipeline and context injection
• extensions/session-join/delete.ts — merged-file deletion
• extensions/session-join/util.ts — shared helpers

Design and requirements: openspec/changes/add-session-join/.

---

Русский

/fork в pi выносит ветку разговора в отдельный файл сессии. /join возвращает результаты обратно: работа форка саммаризируется текущей моделью и вливается в контекст родительской сессии — как git merge, только для сессий.

Установка

# разово, для текущего запуска
pi --extension /path/to/pi-session-join/extensions/session-join/index.ts

# глобально (файл грузится по месту, правки подхватываются после рестарта)
pi install /path/to/pi-session-join

# только в проект (пишет .pi/settings.json, нужен trust проекта)
pi install -l /path/to/pi-session-join

Удалить: pi remove /path/to/pi-session-join.

Использование

В родительской сессии (та, из которой делали форк):

/join [имя-или-id-форка]

• Без аргумента — селектор форков текущей сессии (имя, первое сообщение, дата, пометка «слит до …»). Аргумент и автодополнение — по имени или id форка.
• Дельта (всё, что появилось в форке после точки форка или прошлого слияния) саммаризируется текущей моделью сессии. Большие дельты режутся на чанки, частичные саммари склеиваются вторым проходом.
• Саммари вставляется отдельным сообщением [SESSION JOIN], видимым модели и в TUI. Esc во время саммаризации отменяет слияние без следов в сессии.

Инкрементальное слияние

Форк можно продолжать после слияния: повторный /join сливает только новые записи. Граница слитого хранится в details join-сообщений родителя — файл форка не изменяется.

Удаление форка

После слияния предлагается удалить файл форка (в корзину через trash, если установлен). Если у форка есть дочерние сессии, удаление запрещено — предлагается рекурсивный join: потомки сливаются снизу вверх, затем сам форк, после чего ставшие листьями файлы можно удалить.

Ограничения

• Только pull: слияние запускается из родительской сессии.
• Сливается активная ветка форка целиком, без выбора точки остановки.
• Переносится только саммари; исходные записи не копируются.
• Только интерактивный режим (TUI).
• Форк ищется по parentSession в заголовке: переименование или перемещение файла родителя разрывает связь.

Разработка

См. Development выше. Дизайн и требования: openspec/changes/add-session-join/.

---

Esperanto

/fork en pi movas branĉon de la konversacio al aparta sesia dosiero. /join el ĉi tiu etendo reportas la rezultojn: la laboro de la forko estas resumita de la aktuala modelo kaj enmetita en la kuntekston de la patra sesio — kiel git merge, sed por sesioj.

Instalado

# nur por unu rulo
pi --extension /path/to/pi-session-join/extensions/session-join/index.ts

# tutsisteme (la dosiero estas ŝargata surloke, redaktoj efikas post restarto)
pi install /path/to/pi-session-join

# nur en unu projekto (skribas .pi/settings.json, bezonas fidon de la projekto)
pi install -l /path/to/pi-session-join

Forigi: pi remove /path/to/pi-session-join.

Uzado

En la patra sesio (tiu, el kiu oni forkis):

/join [nomo-aŭ-id-de-forko]

• Sen argumento — elektilo de forkoj de la aktuala sesio (nomo, unua mesaĝo, dato, marko «merged up to …»). Argumento kaj aŭtokompletado funkcias per nomo aŭ id de la forko.
• La delto (ĉio aldonita al la forko post la fork-punkto aŭ post la antaŭa kunfando) estas resumita per la aktuala modelo de la sesio. Grandaj deltoj estas dividitaj en partojn; la partaj resumoj estas kunfanditaj en dua paŝo.
• La resumo estas enmetita kiel aparta mesaĝo [SESSION JOIN], videbla al la modelo kaj en la TUI. Esc dum la resumo nuligas la kunfandon sen spuroj en la sesio.

Plua kunfando

Oni povas daŭrigi labori en la forko post kunfando: la sekva /join kunfandas nur la novajn enskribojn. La limo de la kunfandita parto estas konservita en details de la join-mesaĝoj de la patro — la dosiero de la forko mem neniam estas ŝanĝata.

Forigo de la forko

Post sukcesa kunfando la etendo proponas forigi la fork-dosieron (en la rubujon per trash, se ĝi estas instalita, alie porĉiame). Se la forko havas proprajn infanajn sesiojn, forigo estas malpermesita — anstataŭe la etendo proponas rekursivan kunfandon: la posteuloj estas kunfanditaj de la plej profunda supren, poste la forko mem, kaj ĉiu dosiero kiu fariĝis folio povas esti forigita.

Limigoj

• Nur pull-direkto: oni lanĉas /join el la patra sesio.
• La aktiva branĉo de la forko estas kunfandita tute; elekto de propra halta punkto ne estas subtenata.
• Nur la resumo estas transportita; la krudaj enskriboj ne estas kopiitaj.
• Nur interaga reĝimo (TUI).
• Forkoj estas trovitaj per la kampo parentSession en ilia kaplinio: renomado aŭ movado de la patra sesia dosiero rompas la ligon.

Evoluigado

Vidu Development supre. Dezajno kaj postuloj: openspec/changes/add-session-join/.