Archive & Retention

Archiving a session in Braide is a two-stage story:

Archive now — the worktree (often gigabytes of installed dependencies and build output) is removed from disk immediately, but the session's committed history and uncommitted changes are preserved so you can come back to it later.
Retention later — the background pruner permanently deletes archived sessions after a configurable number of days, unless you mark a session for retention.

The two stages are complementary: archive frees the big disk cost the moment you stop actively working on a session; the pruner finalises lightweight records once they've sat untouched long enough. This page covers both — and the unarchive path that brings an archived session back to a working state.

Archiving a Session

Open a session's context menu in the sidebar (the kebab menu) and choose Archive. The session moves to the archived list and three things happen on disk:

The agent connection is closed and the session's terminal stopped.
The worktree directory is removed — ~/.braide/projects/<project-id>/sessions/<session-id>/worktree/ is gone after archive completes. This is what frees the big disk: node_modules, build output, and the checked-out source tree are all reclaimed.
The session's committed history and uncommitted changes are preserved in git so the session can be restored later. See How Archive Preserves Your Work for the mechanics.

In the session view, the terminal, file browser, and prompt input panes are replaced by a small archived affordance panel — see The Archived Session Affordance below.

Unarchiving

From the archived session's context menu, choose Unarchive (or click Unarchive session in the affordance panel). Braide reverses the archive:

The session's branch is renamed back from acp-session-archived/<id> to acp-session/<id>.
The worktree directory is recreated at the original path, checked out to the session's last commit.
Any uncommitted changes captured at archive time are reapplied to the worktree.
The worktree setup command runs again — because ignored files like node_modules are not preserved (see Limitations below), the setup command needs to repopulate them.
The agent reconnects and the session is ready to use.

The first three steps complete in a few seconds; the setup command runs in parallel with the agent handshake, exactly as it does on a new session.

How Archive Preserves Your Work

This section is for users who want to understand what Braide is doing to git on their behalf, or who need to dig things out manually in a recovery scenario.

Committed history: the anchor branch

When a session is archived, its branch is renamed from acp-session/<id> to acp-session-archived/<id>. Git keeps every commit on that branch reachable, so nothing in the session's history is at risk of garbage collection.

The anchor branch is what unarchive uses to recreate the worktree — it renames the branch back and runs git worktree add against it. The session's recorded last-commit SHA is checked against the recreated worktree's HEAD as a defence-in-depth assertion that the right commit is checked out.

If you ever need to inspect an archived session's history without unarchiving it, the branch is available in your project's repository:

git log acp-session-archived/<session-id>
git diff main...acp-session-archived/<session-id>

Uncommitted changes: the wip ref

Uncommitted changes (anything git status would show — staged, unstaged, or untracked) are captured at archive time via git stash push -u and immediately moved off the shared stash stack into a session-scoped ref:

refs/braide/wip/<session-id>

This dedicated ref means your archived session's WIP is never visible in git stash list and cannot be accidentally popped by a git stash pop in your project root. The ref's existence is the source of truth for "this archived session had uncommitted changes" — there is no parallel metadata flag.

On unarchive, Braide applies the ref to the recreated worktree and deletes the ref:

git stash apply refs/braide/wip/<session-id>
git update-ref -d refs/braide/wip/<session-id>

Limitations

Ignored files are not preserved. Braide uses git stash push -u, which captures untracked files but not files matched by .gitignore. That means:
- node_modules, .venv, target/, dist/, and similar build output are lost — and re-created by the worktree setup command on unarchive.
- .env files and other ignored local-only configs are lost. Secrets you stored only in an ignored file must be re-entered after unarchive. This is a deliberate limitation — using git stash push -a (which would include ignored files) would bloat archive storage with regenerable build artefacts.
Stash-apply conflicts on unarchive are rare but possible. The same-commit invariant — restoring on top of the exact SHA you archived from — makes conflicts unusual, but if you manually moved the anchor branch between archive and unarchive, the stash apply can hit a conflict. See Recovering from a Stash-Apply Conflict below.
Pre-archive sessions (created before this behaviour was introduced) may not have a recorded last-commit SHA. Their unarchive path skips the SHA assertion and the stash-apply step, falling back to a fresh setup off the base branch if the worktree directory is also missing.

Recovering from a Stash-Apply Conflict

If the stash apply on unarchive hits a conflict, Braide does not roll back automatically. Instead:

The worktree is recreated with the conflict markers in place, so you can resolve them in the file editor or your own tools.
The refs/braide/wip/<session-id> ref is preserved — your uncommitted work is still recoverable as a git object even if the apply made a mess.
The session metadata is annotated with failureReason: "wip restore conflict", surfaced in the affordance with a resolve-and-drop instruction.

To finish recovery once you've resolved the conflict markers manually:

git update-ref -d refs/braide/wip/<session-id>

This deletes the now-redundant ref. The session is fully restored.

Retention and the Background Pruner

Archived sessions still consume some disk — the session record, transcripts, and the git refs that preserve history — but the per-session footprint is small. The background pruner permanently deletes archived sessions older than a configured number of days.

Two-tier disk reclaim

It helps to think of archive and retention as two distinct disk-reclaim tiers:

Stage	What it frees	Recoverable?
Archive	The worktree directory (often the dominant per-session cost)	Yes — via Unarchive
Pruner (permanent delete)	Session record, transcripts, and the `acp-session-archived/<id>` and `refs/braide/wip/<id>` git refs	No

Archive is reversible and runs the moment you stop working on a session. The pruner is irreversible and runs in the background after retention has elapsed. You can keep archived sessions indefinitely by enabling retention protection on individual sessions.

Configuring retention

Archive retention is a per-project setting.

Open the Settings modal by clicking the gear icon
Switch to the Project tab
Select Archive Retention in the sidebar under System

Settings

Auto-prune archived sessions — Toggle to enable or disable automatic pruning for this project. When disabled, no sessions are pruned automatically.
Remove after N days — The number of days after which an archived session becomes eligible for pruning. Minimum is 1 day. Default is 7 days.

Prune Now

Click the Prune now button to immediately run the pruning logic for the current project, rather than waiting for the next hourly sweep. While running, the button shows Pruning… alongside a progress bar and a checked/total counter (plus a running count of sessions pruned). When complete, a result message is shown:

Pruned N session(s) — The number of sessions that were removed
No sessions to prune — No archived sessions matched the retention criteria

Retention Protection

Individual archived sessions can be protected from automatic pruning regardless of their age. This is useful for sessions you want to keep as reference — for example, a session with an important architectural decision or a complex debugging investigation.

To protect a session, toggle its retention protection option from the session's context menu. Protected sessions are skipped during both the automatic hourly sweep and manual "Prune now" operations. Because archive already removed the worktree, retention protection is now a low-disk way to keep a session recoverable forever rather than the heavy frozen-worktree state it used to be.

The Archived Session Affordance

When you open an archived session, the usual terminal, file browser, and prompt input are replaced by a small panel that names the situation and offers the resolving action. The panel shows:

The base branch the session was created from
The short SHA of the session's last commit
An indicator if uncommitted work was captured at archive time
An Unarchive session button (primary)
A View committed diff button (secondary) that opens a read-only diff between the base branch and the anchor branch — no worktree required

The transcript above the affordance stays visible as read-only history. If a previous unarchive hit a stash-apply conflict (see Recovering from a Stash-Apply Conflict), the affordance shows the failure reason and the manual-recovery instruction instead of the Unarchive button.

Sessions — Session lifecycle and modes
Worktrees — How session worktrees work, including the setup command that re-runs on unarchive
Running a Session — Creating sessions, sending prompts, and the archived affordance UX
Settings & Preferences — Where archive retention sits in the settings model