#2057: design(worktree): define lifecycle, cleanup, and safety model

Background

Issue #1955 tracks the first WebUI equivalent of hermes -w: creating a new conversation in a Hermes Agent git worktree.

PR #2053 implements the first slice:

• WebUI can request worktree: true during new-session creation.
• The selected workspace is resolved to a git repo root.
• WebUI reuses the Hermes Agent worktree setup helper.
• The resulting session points at the new worktree path.
• Worktree metadata is persisted on the session.
• The sidebar shows a small worktree indicator.

That is enough to make worktree-backed development conversations usable, but it intentionally leaves the worktree lifecycle after creation unresolved.

Why this needs a separate tracking issue

CLI hermes -w is process-scoped: create a worktree, run the agent, clean up when the process exits.

WebUI sessions are not process-scoped. A WebUI-created worktree can outlive:

• the browser tab
• a server restart
• an active stream
• an embedded terminal
• a session archive/delete operation
• local uncommitted work inside the worktree

Because of that, copying the CLI atexit cleanup behavior would be unsafe. WebUI needs its own lifecycle and safety model.

Lifecycle questions to settle

1. What should happen when a user archives a worktree-backed session?

   • Likely answer: archive only hides the session; it must not remove the worktree.

2. What should happen when a user deletes a worktree-backed session?

   • Likely answer: session delete should not silently remove the worktree.
   • It may need a warning that the worktree remains on disk.

3. Should WebUI expose an explicit Remove worktree action?

   • Probably yes, but only as an explicit user action.
   • It should not be implied by archive/delete.

4. What safety checks are required before removing a worktree?

   • active stream still using the session
   • embedded terminal still attached to the session/worktree
   • dirty tracked files
   • untracked files
   • unpushed commits
   • invalid/stale metadata after server restart

5. Should WebUI reuse or clean up abandoned empty worktrees?

   • Useful later, but lower priority than safe explicit removal.

Suggested implementation slices

Slice 1: make archive/delete semantics explicit

• Show a warning or note when deleting a worktree-backed session.
• Make it clear that deleting the WebUI session does not remove the worktree directory.
• Keep archive as session-only behavior.
• No filesystem cleanup yet.

Slice 2: add read-only worktree status

• Add a backend helper/endpoint that reports worktree state from persisted session metadata.
• Include whether the path exists, whether it is a git worktree, dirty/untracked status, ahead/unpushed status if practical, and whether there is an active terminal or active stream.
• Use this status in the UI before any destructive action exists.

Slice 3: add explicit safe Remove worktree

• Add a deliberate user action to remove the worktree.
• Refuse or require extra confirmation when safety checks fail.
• Reuse Hermes Agent cleanup semantics where appropriate, but do not hide WebUI-specific session/terminal/stream checks behind the Agent helper.

Slice 4: optional reuse/prune policy

• Consider reuse or cleanup of empty abandoned worktrees only after explicit removal is safe.
• This should be treated as convenience, not a correctness prerequisite.

Non-goals

• Do not expand PR #2053 to include cleanup.
• Do not auto-remove worktrees on archive/delete.
• Do not remove worktrees while an active stream or embedded terminal may still be using them.
• Do not rely only on browser state; the safety model must survive server restarts.

References

• #1955 — original hermes -w WebUI feature request
• #2053 — first worktree-backed session creation slice