Skip to content

v0.9.5: session tree (append-only entry journal + /tree /branch /fork /resume) #5262

Description

@Hmbown

Depends on: I3
Folds in: #576 (fork UX).

Goal

Make sessions an append-only entry journal with an in-memory tree projection:
every non-header entry carries id + parentId, the active position is a leafId,
appending creates a child of the leaf, and branching only moves the leaf — it never
rewrites history
. Expose /tree, /branch, /fork, and /resume (including
foreign-session import) as user commands, with an in-TUI interactive fork picker.

Why

codewhale already has an append-only log (AppendLog) and prefix stability
(PrefixStabilityManager/frozen_prefix/messages_revision), but branching today
goes through /restore N / revert_turn / a side git-repo snapshot stack that
does rewrite-ish state and is CLI-only. A tree model makes branch/fork/resume
first-class, undoable, and usable from the TUI (#576). It is also the data model
compaction and branch summaries hang off of, so landing the entry shape now (even
with strategies deferred) avoids a second migration.

Current state (codewhale)

  • AppendLog, PrefixStabilityManager, frozen_prefix, messages_revision
    (prefix-stable, append-only — the right substrate).
  • crates/tui/src/session_manager.rs: JSON sessions in ~/.codewhale/sessions,
    atomic write + fsync + rename, MAX_SESSIONS = 50, crash checkpoints
    (write_session_checkpoint_if_absent), persistence_actor.
  • Branching via /restore N / revert_turn / snapshot side-repo.
  • Fork is CLI-only today (Feature Request: Improve Fork UX #576).

Target

  1. Add id/parentId on every entry and a leafId position; project an in-memory
    tree. Context rebuilds root→leaf.
  2. Tree operations as commands: /tree (interactive navigation), /branch,
    /fork (new session from any node, with the in-TUI picker from Feature Request: Improve Fork UX #576), /resume.
  3. branch_summary and compaction entries are first-class session entry types
    (data shape lands now; the summarization strategies are deferred).
  4. Fork/resume parity: spawn-depth tracking; define a foreign-session import/export
    container so /resume can ingest sessions from other agents.
  5. Replace the /restore N / revert_turn / snapshot-side-repo stack with the tree
    model.

Acceptance criteria

  • Every session entry has id/parentId; a leafId tracks the active position;
    the in-memory tree projects from the journal.
  • /tree, /branch, /fork, /resume work; branching moves the leaf only
    (history is never rewritten).
  • /fork has the in-TUI interactive session picker from Feature Request: Improve Fork UX #576.
  • Compaction and branch-summary entries fit the entry shape (even if the
    strategies are deferred).
  • /restore/revert_turn/snapshot-side-repo stack removed.
  • Atomic write, fsync, crash-checkpoint, and MAX_SESSIONS behavior preserved.
  • Suite green; just fmt clean.

Non-goals

  • Compaction strategies (summarize/streaming/elision/pruning) and image-bitmap
    archival — deferred (see BEYOND doc B1/B2).
  • Memory subsystem — deferred (B3).

Metadata

Metadata

Assignees

No one assigned

    Labels

    agent-readySelf-contained for a fresh-clone cloud agent; implement in a tested PR with no live credentialsenhancementNew feature or requestrustPull requests that update rust codetuiTerminal UI behavior, rendering, or interactionv0.9.5Targeting v0.9.5

    Projects

    Status
    Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions