Session shadows are leased and never released: 378 branches, 195 worktrees, 9.2 GB, and nothing reaps #1260

New issue

Closed

opened 2026-08-26 02:50:44 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-26 02:50:44 +00:00

Member

Surfaced by #1245 while looking at something else. This is not an aterm issue, it is an aos _native-shadow lifecycle issue, and it is the largest thing that pass turned up.

Measured, one host, one moment

session shadows under /tmp/aos/native        42
  holding a checked-out branch               18
  branches held by those shadows            193
  created in the last hour                    7
  oldest                                1.5 days
  disk                                    9.2 GB

canonical repos scanned                      20
  aos/* session branches, total             378
  linked worktrees registered               195

heaviest:
   95 branches   14 worktrees   coilyco-flight-deck/agentic-os
   59 branches   13 worktrees   coilyco-bridge/deploy
   36 branches   11 worktrees   coilyco-gaming/sirens-echo
   30 branches   12 worktrees   coilyco-flight-deck/infrastructure

Why it accumulates

docs/native-shadow.md already describes the mechanism without naming it as a leak. Session worktrees are linked from the canonical repository, so a commit is durable the moment it is written and branch refs outlive the session. That is the correct design for not losing work, and it means nothing about a session ending removes anything.

The only force that ever deletes is the OS temp purge, and it does the wrong half. macOS com.apple.bsd.dirhelper deletes files by access time and leaves the directory skeleton, so the working tree evaporates while the git worktree registration and the branch both survive. The doc names the resulting state: a worktree that is prunable with a missing gitdir.

So the steady state is one-directional. Directories, registrations, and refs only ever go up.

What is missing

aos _native-shadow has three flags, --harness, --probe, --assigned-role. There is no list, no release, no reap. A session cannot even declare itself finished.

Shape of the fix

A release path. A shadow whose branch is merged or whose worktree has no unpushed commits and no dirty state can be dropped: worktree removed, registration pruned, branch deleted if fully merged. Refuse on anything unpushed, since the whole durability asymmetry argument says that is the one thing worth keeping.
A reap verb that applies the release predicate across all shadows and reports what it skipped and why. Dry-run first.
Enumeration falls out of it, rather than being the goal. Once the lifecycle knows what a live shadow is, listing is free, and aterm and the picker can read it.

Care needed

The operating rules treat a shadow squatting the default branch as a real hazard, and docs/native-session-start.md already detaches a squatter at startup. Reaping touches the same territory, so the release predicate has to be conservative and auditable. Never force anything. An unpushed commit in a purged worktree is unrecoverable, so the predicate errs toward keeping.

aos-cli/native_shadow*.go, docs/native-shadow.md, docs/native-agent-workspaces.md.

Surfaced by #1245 while looking at something else. This is not an aterm issue, it is an `aos _native-shadow` lifecycle issue, and it is the largest thing that pass turned up. ## Measured, one host, one moment ``` session shadows under /tmp/aos/native 42 holding a checked-out branch 18 branches held by those shadows 193 created in the last hour 7 oldest 1.5 days disk 9.2 GB canonical repos scanned 20 aos/* session branches, total 378 linked worktrees registered 195 heaviest: 95 branches 14 worktrees coilyco-flight-deck/agentic-os 59 branches 13 worktrees coilyco-bridge/deploy 36 branches 11 worktrees coilyco-gaming/sirens-echo 30 branches 12 worktrees coilyco-flight-deck/infrastructure ``` ## Why it accumulates `docs/native-shadow.md` already describes the mechanism without naming it as a leak. Session worktrees are linked from the canonical repository, so **a commit is durable the moment it is written and branch refs outlive the session**. That is the correct design for not losing work, and it means nothing about a session ending removes anything. The only force that ever deletes is the OS temp purge, and it does the wrong half. macOS `com.apple.bsd.dirhelper` deletes files by access time and leaves the directory skeleton, so the working tree evaporates while the git worktree registration and the branch both survive. The doc names the resulting state: a worktree that is `prunable` with a missing gitdir. So the steady state is one-directional. Directories, registrations, and refs only ever go up. ## What is missing `aos _native-shadow` has three flags, `--harness`, `--probe`, `--assigned-role`. There is no list, no release, no reap. A session cannot even declare itself finished. ## Shape of the fix 1. **A release path.** A shadow whose branch is merged or whose worktree has no unpushed commits and no dirty state can be dropped: worktree removed, registration pruned, branch deleted if fully merged. Refuse on anything unpushed, since the whole durability asymmetry argument says that is the one thing worth keeping. 2. **A reap verb** that applies the release predicate across all shadows and reports what it skipped and why. Dry-run first. 3. **Enumeration falls out of it,** rather than being the goal. Once the lifecycle knows what a live shadow is, listing is free, and aterm and the picker can read it. ## Care needed The operating rules treat a shadow squatting the default branch as a real hazard, and `docs/native-session-start.md` already detaches a squatter at startup. Reaping touches the same territory, so the release predicate has to be conservative and auditable. Never force anything. An unpushed commit in a purged worktree is unrecoverable, so the predicate errs toward keeping. `aos-cli/native_shadow*.go`, `docs/native-shadow.md`, `docs/native-agent-workspaces.md`.

coilyco-ops referenced this issue

2026-08-26 02:53:23 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue

2026-08-26 05:22:57 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue

2026-08-26 06:08:00 +00:00

EPIC: aterm improvement pass, split into issues #1245

coilyco-ops referenced this issue from a commit

2026-08-26 07:30:27 +00:00

feat(aos): give the session shadow a lifecycle, and reap a squash-landed branch (#1260)