gitflash 0.6.0 → 0.7.0.beta1

data/lib/gitflash/hook/branch_marker.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Marks the branches an agent just created as agent work (see Ownership), so
+    # `gitflash clean --agent` can find them. Runs in the PostToolUse hook, after the command:
+    # the branch exists then, and Claude Code only runs it when the command succeeded.
+    #
+    # A branch is marked only when it is unmarked and its reflog says it was created a moment
+    # ago ("branch: Created from ..."), so a branch that was already there is never claimed.
+    class BranchMarker
+      CREATED = 'branch: Created from'
+      RECENT_SECONDS = 120
+
+      def initialize(clock: -> { Time.now })
+        @clock = clock
+      end
+
+      # Branch names marked as agent work, in the directories the command ran in
+      def call(command, cwd)
+        created = CommandParser.new(cwd).creations(command)
+        created.select { |creation| mark(creation[:dir], creation[:branch]) }
+               .map { |creation| creation[:branch] }.uniq
+      end
+
+      private
+
+      def mark(dir, branch)
+        return false unless Dir.exist?(dir)
+
+        Dir.chdir(dir) do
+          ownership = Ownership.new
+          next false unless created_recently?(branch) && !ownership.all.key?(branch)
+
+          ownership.mark(branch, 'agent')
+          true
+        end
+      end
+
+      # The oldest reflog entry of the branch is its creation, and it is recent
+      def created_recently?(branch)
+        stdout, _stderr, success = Git::BashCommand.capture(
+          'git', 'log', '-g', '--format=%ct%x1f%gs', "#{Repo::HEADS}#{branch}", '--'
+        )
+        return false unless success
+
+        created, subject = stdout.lines(chomp: true).last.to_s.split("\x1f", 2)
+        subject.to_s.start_with?(CREATED) && @clock.call.to_i - created.to_i <= RECENT_SECONDS
+      end
+    end
+  end
+end

data/lib/gitflash/hook/claude.rb

@@ -4,7 +4,8 @@ require 'json'
 
 module Gitflash
   module Hook
-    # Claude Code PreToolUse hook for the Bash tool.
+    # Claude Code hook for the Bash tool. PostToolUse input marks the branches the command
+    # created as agent work (BranchMarker); everything below describes PreToolUse.
     #
     # Reads the hook input (JSON on stdin) and, when the command can lose work git cannot
     # restore, acts according to the mode:
@@ -15,14 +16,20 @@ module Gitflash
     class Claude
       MODES = %w[snapshot ask deny].freeze
       EVENT = 'PreToolUse'
+      POST_EVENT = 'PostToolUse'
 
-      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new })
+      def initialize(mode: 'snapshot', snapshots: -> { Gitflash::Snapshots.new },
+                     marker: BranchMarker.new)
         @mode = mode
         @snapshots = snapshots
+        @marker = marker
       end
 
       def call(input)
-        targets = targets(JSON.parse(input))
+        data = JSON.parse(input)
+        return after_command(data) if data['hook_event_name'] == POST_EVENT
+
+        targets = targets(data)
         return nil if targets.empty?
         return deny(targets) if @mode == 'deny'
 
@@ -32,6 +39,19 @@ module Gitflash
 
       private
 
+      # PostToolUse: mark the branches the command created, and tell Claude
+      def after_command(data)
+        return nil unless data['tool_name'] == 'Bash'
+
+        marked = @marker.call(data.dig('tool_input', 'command').to_s, data['cwd'] || Dir.pwd)
+        return nil if marked.empty?
+
+        context = "gitflash marked #{marked.join(', ')} as agent work, so " \
+                  '`gitflash clean --agent` can find it. Change it with ' \
+                  '`gitflash mark BRANCH --owner human`.'
+        { hookSpecificOutput: { hookEventName: POST_EVENT, additionalContext: context } }
+      end
+
       def targets(data)
         return [] unless data['tool_name'] == 'Bash'
 

data/lib/gitflash/hook/command_parser.rb

@@ -23,7 +23,32 @@ module Gitflash
         @cwd = cwd
       end
 
+      # Git commands that can lose work, with what to save before them
       def targets(command_line)
+        git_commands(command_line).filter_map do |git|
+          rule = Rules.for(git.subcommand, git.args, git.dir)
+          next unless rule
+
+          Target.new(dir: rule.fetch(:dir, git.dir), command: git.command, scope: rule[:scope],
+                     branches: rule[:branches] || [])
+        end
+      end
+
+      # Branches that git commands in the line create, as { dir:, branch: }
+      def creations(command_line)
+        git_commands(command_line).filter_map do |git|
+          branch = Creations.for(git.subcommand, git.args)
+          { dir: git.dir, branch: branch } if branch
+        end
+      end
+
+      private
+
+      # A git command found in the line: the directory it runs in (after `cd` and `-C`), the
+      # subcommand and its arguments
+      GitCommand = Data.define(:dir, :command, :subcommand, :args)
+
+      def git_commands(command_line)
         dir = @cwd
         segments(command_line).filter_map do |segment|
           words = words(segment)
@@ -33,12 +58,10 @@ module Gitflash
             dir = File.expand_path(words[1] || Dir.home, dir)
             next
           end
-          git_target(words, dir, segment.strip) if File.basename(words.first) == 'git'
+          git_command(words, dir, segment.strip) if File.basename(words.first) == 'git'
         end
       end
 
-      private
-
       # Splits on unquoted ; & | and newlines
       def segments(line)
         parts = [+'']
@@ -78,13 +101,10 @@ module Gitflash
         word.delete_prefix('(').delete_prefix('{').delete_suffix(')').delete_suffix('}')
       end
 
-      def git_target(words, dir, command)
+      def git_command(words, dir, command)
         index, dir = skip_git_options(words, dir)
-        rule = Rules.for(words[index], words[(index + 1)..] || [], dir)
-        return nil unless rule
-
-        Target.new(dir: rule.fetch(:dir, dir), command: command, scope: rule[:scope],
-                   branches: rule[:branches] || [])
+        GitCommand.new(dir: dir, command: command, subcommand: words[index],
+                       args: words[(index + 1)..] || [])
       end
 
       # Index of the subcommand, and the directory after any -C options

data/lib/gitflash/hook/creations.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Gitflash
+  module Hook
+    # Which git commands create a branch, and the name of it: `checkout -b`, `switch -c`,
+    # `branch NAME` and `worktree add -b` (or a path without a commit, which names the branch
+    # after the directory). Returns the name, or nil when the command creates no branch.
+    module Creations
+      NOT_CREATING = %w[
+        -d -D --delete -m -M --move -c -C --copy -u --set-upstream-to --unset-upstream
+        --edit-description --list -a --all -r --remotes -v -vv --verbose --show-current --contains
+        --no-contains --merged --no-merged --points-at
+      ].freeze
+      WORKTREE_VALUE_OPTIONS = %w[-b -B --reason --orphan].freeze
+
+      module_function
+
+      def for(subcommand, args)
+        case subcommand
+        when 'checkout' then flagged(args, %w[-b -B])
+        when 'switch' then flagged(args, %w[-c -C --create --force-create])
+        when 'branch' then plain_branch(args)
+        when 'worktree' then worktree(args)
+        end
+      end
+
+      # The value of the first of `flags`: `-b NAME`, `-bNAME` or `--create=NAME`
+      def flagged(args, flags)
+        args.each_with_index do |arg, index|
+          return args[index + 1] if flags.include?(arg) && args[index + 1]
+
+          value = attached_value(arg, flags)
+          return value if value
+        end
+        nil
+      end
+
+      def attached_value(arg, flags)
+        flags.each do |flag|
+          if flag.start_with?('--')
+            return arg.delete_prefix("#{flag}=") if arg.start_with?("#{flag}=")
+          elsif arg.start_with?(flag) && arg.length > flag.length && !arg.start_with?('--')
+            return arg.delete_prefix(flag)
+          end
+        end
+        nil
+      end
+
+      # `git branch NAME [START]` creates NAME; listing, deleting or renaming flags mean it does not
+      def plain_branch(args)
+        return nil if args.intersect?(NOT_CREATING)
+
+        args.find { |arg| !arg.start_with?('-') }
+      end
+
+      def worktree(args)
+        return nil unless args.first == 'add'
+
+        rest = args.drop(1)
+        named = flagged(rest, %w[-b -B])
+        return named if named
+        return nil if rest.include?('--detach') || rest.include?('--orphan')
+
+        path = positional(rest)
+        path.size == 1 ? File.basename(path.first) : nil
+      end
+
+      # Arguments that are not options or the values of options that take one
+      def positional(args)
+        result = []
+        skip = false
+        args.each do |arg|
+          if skip
+            skip = false
+          elsif WORKTREE_VALUE_OPTIONS.include?(arg)
+            skip = true
+          elsif !arg.start_with?('-')
+            result << arg
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gitflash/hook/settings.rb

@@ -49,11 +49,24 @@ module Gitflash
         raise Error.new("#{path} is not valid JSON: #{e.message}", code: 'invalid_settings')
       end
 
-      # The gitflash hook entry in parsed settings, or nil
-      def entry(settings)
-        groups = Array(settings.dig('hooks', 'PreToolUse'))
-        groups.flat_map { |group| Array(group['hooks']) }
-              .find { |hook| hook['command'].to_s.match?(PATTERN) }
+      # The gitflash hook entry for an event (PreToolUse by default) in parsed settings, or nil.
+      # Only groups whose matcher covers the Bash tool count: a gitflash command under another
+      # matcher (Edit, say) never runs for Bash commands.
+      def entry(settings, event = 'PreToolUse')
+        groups = Array(settings.dig('hooks', event))
+        bash = groups.select { |group| bash_matcher?(group['matcher']) }
+        bash.flat_map { |group| Array(group['hooks']) }
+            .find { |hook| hook['command'].to_s.match?(PATTERN) }
+      end
+
+      # Claude Code matches `matcher` against the tool name: empty or `*` is every tool, anything
+      # else is a pattern such as `Bash` or `Bash|Edit`
+      def bash_matcher?(matcher)
+        return true if matcher.to_s.empty? || matcher == '*'
+
+        'Bash'.match?(/\A(?:#{matcher})\z/)
+      rescue RegexpError
+        false
       end
     end
   end

data/lib/gitflash/hook_cli.rb

@@ -14,7 +14,8 @@ module Gitflash
       true
     end
 
-    desc 'claude', 'Run as a Claude Code PreToolUse hook (reads the hook input on stdin)'
+    desc 'claude',
+         'Run as a Claude Code hook (PreToolUse and PostToolUse; reads the input on stdin)'
     long_desc <<~TEXT
       Reads the Claude Code hook input on stdin. When the Bash command can discard work git
       cannot restore (for example reset --hard, clean -f, checkout -- ., branch -D, stash drop),
@@ -24,6 +25,10 @@ module Gitflash
       --mode ask       save a snapshot and ask the user to approve the command
       --mode deny      block the command and point to the gitflash equivalent
 
+      As a PostToolUse hook it marks the branches the command created (git checkout -b, switch -c,
+      branch NAME, worktree add) as agent work, so `gitflash clean --agent` can find them. A branch
+      is only marked when it is new (its reflog says it was created a moment ago) and unmarked.
+
       Errors never block the command: they are printed to stderr and the hook exits with 0.
     TEXT
     option :mode, type: :string, default: 'snapshot', enum: Hook::Claude::MODES
@@ -36,8 +41,10 @@ module Gitflash
 
     desc 'install', 'Register the gitflash hook in Claude Code settings'
     long_desc <<~TEXT
-      Adds `gitflash hook claude` as a PreToolUse hook for Bash commands. Keeps the rest of the
-      settings file unchanged and does nothing when the hook is already installed.
+      Adds `gitflash hook claude` as a PreToolUse hook (snapshots before destructive commands) and
+      as a PostToolUse hook (marks branches an agent creates) for Bash commands. Keeps the rest of
+      the settings file unchanged and does nothing when both are already installed. Run it again
+      to add the PostToolUse hook to an older install.
 
       --scope local    .claude/settings.local.json at the repository root (default, not
                        committed); applies to sessions anywhere in the repository and its worktrees
@@ -59,7 +66,8 @@ module Gitflash
     desc 'status', 'Show whether the gitflash hook protects Claude Code sessions here'
     long_desc <<~TEXT
       Lists the Claude Code settings files that apply to the current directory, whether each
-      holds the gitflash hook and which sessions it applies to, and whether the gitflash
+      holds the gitflash hooks (and whether branch marking is on) and which sessions it applies to,
+      and whether the gitflash
       executable the hook runs is on PATH. Works outside a git repository (user scope only).
     TEXT
     def status

data/lib/gitflash/ownership.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Who created a branch: `agent` or `human`. Stored in git config as
+  # `branch.<name>.gitflash-owner`, which git removes together with the branch.
+  # A branch without a mark counts as human work and is never selected for automatic cleanup.
+  class Ownership
+    OWNERS = %w[agent human].freeze
+    SUFFIX = '.gitflash-owner'
+    PREFIX = 'branch.'
+
+    def initialize(bash: Git::BashCommand)
+      @bash = bash
+    end
+
+    # { branch name => owner } for every marked branch
+    def all
+      stdout, _stderr, success = @bash.capture('git', 'config', '--local', '-z', '--get-regexp',
+                                               '^branch\..+\.gitflash-owner$')
+      return {} unless success
+
+      stdout.split("\0").filter_map { |entry| parse(entry) }.to_h
+    end
+
+    # The branches with their `owner` set from the marks
+    def annotate(branches)
+      owners = all
+      branches.map { |branch| branch.with(owner: owners[branch.name]) }
+    end
+
+    def mark(branch, owner)
+      unless OWNERS.include?(owner)
+        raise UsageError.new("Unknown owner '#{owner}' (use #{OWNERS.join(' or ')})",
+                             code: 'invalid_usage')
+      end
+
+      @bash.exec('git', 'config', '--local', key(branch), owner)
+    end
+
+    # Removes the mark; a branch without a mark is already unmarked
+    def clear(branch)
+      @bash.capture('git', 'config', '--local', '--unset', key(branch))
+    end
+
+    private
+
+    def key(branch)
+      "#{PREFIX}#{branch}#{SUFFIX}"
+    end
+
+    # Entry from `-z`: "branch.<name>.gitflash-owner\nvalue". Branch names may contain dots.
+    def parse(entry)
+      full_key, value = entry.split("\n", 2)
+      return nil unless full_key.start_with?(PREFIX) && full_key.end_with?(SUFFIX)
+
+      [full_key.delete_prefix(PREFIX).delete_suffix(SUFFIX), value.to_s.strip]
+    end
+  end
+end

data/lib/gitflash/protection.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Branches gitflash never deletes: the current and default branch, `main`, `master`, names
+  # matching `protected` in the settings, and any branch checked out in a worktree.
+  class Protection
+    NAMES = %w[main master].freeze
+
+    def initialize(config:, checked_out: [])
+      @config = config
+      @checked_out = checked_out
+    end
+
+    def protected?(branch)
+      branch.current? || branch.default? || NAMES.include?(branch.name) ||
+        @config.protected?(branch.name) || @checked_out.include?(branch.name)
+    end
+  end
+end

data/lib/gitflash/repo.rb

@@ -30,9 +30,8 @@ module Gitflash
     # merged into the default branch (one extra git call).
     def branches(merged_status: false)
       merged_names = merged_status ? merged_branch_names : nil
-      branch_lines.map do |line|
-        Branch.parse(line, default_branch: default_branch, merged_names: merged_names)
-      end
+      list = branch_lines.map { |line| Branch.parse(line, default_branch:, merged_names:) }
+      Ownership.new(bash: @bash).annotate(list)
     end
 
     def current_branch

data/lib/gitflash/restore.rb

@@ -20,17 +20,18 @@ module Gitflash
       }
     end
 
+    # Parts of the state this restore changes; the state before an undo is saved with the same
+    def scope = @snapshot.scope
+
     def empty?
       plan[:branches].empty? && plan[:head].nil? && !plan[:worktree] && plan[:stashes].empty?
     end
 
-    # Applies the plan; returns nil on success or the failed step's Result
-    def apply
-      steps.each do |args|
-        result = run(*args)
-        return result unless result.success?
-      end
-      nil
+    # Applies the plan (`only: :branches` just the branch tips); returns nil on success or the
+    # failed step's Result
+    def apply(only: nil)
+      (only == :branches ? branch_steps : steps).lazy.map { |args| run(*args) }
+                                                .find { |result| !result.success? }
     end
 
     private

data/lib/gitflash/state_capture.rb

@@ -93,9 +93,9 @@ module Gitflash
     # Tree of the working tree, built in a temporary copy of the index so the real one is untouched
     def worktree_tree
       top = git('rev-parse', '--show-toplevel')
-      Tempfile.create('gitflash-index', File.expand_path(git('rev-parse', '--git-dir'))) do |file|
+      Tempfile.create('gitflash-index', git('rev-parse', '--absolute-git-dir')) do |file|
         file.close
-        real_index = File.expand_path(git('rev-parse', '--git-path', 'index'))
+        real_index = git('rev-parse', '--path-format=absolute', '--git-path', 'index')
         FileUtils.cp(real_index, file.path) if File.exist?(real_index)
         env = { 'GIT_INDEX_FILE' => file.path }
 

data/lib/gitflash/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gitflash
-  VERSION = '0.6.0'
+  VERSION = '0.7.0.beta1'
 end

data/lib/gitflash/worktree.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # A checkout of the repository as reported by `git worktree list --porcelain`.
+  # `branch` is nil for a detached HEAD. `missing` means the directory is gone (git calls it
+  # prunable). `dirty` is nil when it cannot be known (missing directory or bare repository).
+  # ahead, behind, merged and owner are those of the branch, nil without a branch.
+  Worktree = Data.define(
+    :path, :head, :branch, :main, :bare, :locked, :lock_reason, :missing,
+    :dirty, :ahead, :behind, :merged, :owner
+  ) do
+    alias_method :main?, :main
+    alias_method :locked?, :locked
+    alias_method :missing?, :missing
+    alias_method :dirty?, :dirty
+
+    # Why this worktree must not be removed, nil when it can go. `current` is true for the
+    # worktree gitflash runs in. The main checkout and the current one are never removable.
+    def removal_blocker(force:, current:)
+      return "#{path} is the main checkout" if main?
+      return "#{path} is the current worktree" if current
+
+      in_use_blocker unless force || (missing? && !locked?)
+    end
+
+    def in_use_blocker
+      return "#{path} is locked (use --force)" if locked?
+
+      "#{path} has uncommitted changes (use --force)" if dirty? != false
+    end
+  end
+end

data/lib/gitflash/worktree_cli.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Gitflash
+  # `gitflash worktree ...` (alias `wt`): worktrees for parallel agent work
+  class WorktreeCli < Thor
+    extend Configuration::Descriptions
+    include CommandRunner
+
+    namespace 'worktree'
+
+    def self.exit_on_failure?
+      true
+    end
+
+    desc 'list', 'List worktrees with branch, dirty and merge state'
+    long_desc <<~TEXT
+      Lists every worktree of the repository: absolute path, branch, HEAD, whether it has
+      uncommitted changes, ahead/behind counts, whether its branch is merged into the default
+      branch, lock state and whether its directory is missing.
+
+      Agents use the absolute paths from `--json`; no directory switching is needed.
+
+      Accepts the global --json option after the subcommand: gitflash wt list --json
+    TEXT
+    def list
+      run_command('worktree list', Commands::WorktreeList)
+    end
+
+    desc 'add BRANCH', 'Add a worktree for a branch (existing, remote or new)'
+    long_desc <<~TEXT
+      Adds a worktree for BRANCH. An existing local branch is checked out; a branch that exists
+      only on origin is created to track it; any other name creates a new branch from HEAD
+      (or from --from). New branches are marked as agent work so `gitflash clean` can find them.
+
+      The directory defaults to ../<repo>.worktrees/<branch> (setting `worktree_dir` in
+      .gitflash.yml changes it). The result lists the absolute path: use it, no directory
+      switching is needed.
+
+      Needs no confirmation. Accepts the global --json and --dry-run options after the
+      subcommand: gitflash wt add feature --json
+    TEXT
+    option :path, type: :string, banner: 'DIR', desc: 'Directory for the worktree'
+    option :from, type: :string, banner: 'REF', desc: 'Start a new branch from REF (default HEAD)'
+    option :owner, type: :string, enum: Ownership::OWNERS,
+                   desc: 'Mark a new branch as agent (default) or human work'
+    def add(branch = nil)
+      run_command('worktree add', Commands::WorktreeAdd, *[branch].compact)
+    end
+
+    desc 'lock WORKTREE', 'Lock a worktree so prune, remove and clean leave it alone'
+    long_desc 'Locks the worktree given as a path or branch. Add --reason to say why.'
+    option :reason, type: :string, desc: 'Why the worktree is locked'
+    def lock(worktree = nil)
+      run_command('worktree lock', Commands::WorktreeLock, *[worktree].compact)
+    end
+
+    desc 'unlock WORKTREE', 'Unlock a worktree'
+    def unlock(worktree = nil)
+      run_command('worktree unlock', Commands::WorktreeUnlock, *[worktree].compact)
+    end
+
+    desc 'move WORKTREE PATH', 'Move a worktree to another directory'
+    long_desc <<~TEXT
+      Moves the worktree (a path or branch) to PATH. The main checkout and the current worktree
+      cannot be moved; a locked worktree needs --force.
+    TEXT
+    option :force, type: :boolean, default: false, desc: 'Also move a locked worktree'
+    def move(worktree = nil, destination = nil)
+      run_command('worktree move', Commands::WorktreeMove, *[worktree, destination].compact)
+    end
+
+    desc 'prune', 'Forget worktrees whose directory is gone'
+    long_desc <<~TEXT
+      Removes git's record of worktrees whose directory no longer exists. Locked worktrees stay.
+      Branches are not touched. Asks for confirmation; pass --yes to skip it, or --dry-run.
+    TEXT
+    def prune
+      run_command('worktree prune', Commands::WorktreePrune)
+    end
+
+    desc 'clean', 'Remove worktrees whose branch is merged, gone, stale or agent-created'
+    long_desc <<~TEXT
+      Removes worktrees whose branch matches the criteria of `gitflash clean`: merged into the
+      default branch or upstream gone by default, plus --stale [DAYS] and --agent. The main
+      checkout, the current worktree and worktrees on protected branches are never removed;
+      locked worktrees and worktrees with uncommitted changes are skipped (and listed with the
+      reason) unless --force is given.
+
+      Each removal saves a snapshot first, as `wt remove` does. Branches are kept: run
+      `gitflash clean` afterwards to delete them. Missing directories are handled by `wt prune`.
+
+      Asks for confirmation; pass --yes to skip it, or --dry-run.
+    TEXT
+    option :merged, type: :boolean, desc: 'Branches merged into the default branch'
+    option :gone, type: :boolean, desc: 'Branches whose upstream branch was deleted'
+    option :stale, type: :string, banner: 'DAYS', lazy_default: '',
+                   desc: 'Branches without commits for DAYS days (default: stale_days setting)'
+    option :agent, type: :boolean, desc: 'Branches created by an agent'
+    option :force, type: :boolean, default: false,
+                   desc: 'Also remove locked worktrees and worktrees with uncommitted changes'
+    def clean
+      run_command('worktree clean', Commands::WorktreeClean)
+    end
+
+    desc 'remove [WORKTREE...]', 'Remove worktrees (paths or branch names), saving a snapshot first'
+    long_desc descriptions.worktree_remove.long
+    option :force, type: :boolean, default: false,
+                   desc: 'Remove locked worktrees and worktrees with uncommitted changes'
+    def remove(*worktrees)
+      run_command('worktree remove', Commands::WorktreeRemove, *worktrees)
+    end
+  end
+end

data/lib/gitflash/worktree_revival.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Gitflash
+  # Brings back a worktree that was removed after a snapshot of it: adds the worktree again on
+  # its branch (or detached HEAD) and restores its files. Branch tips are restored before the
+  # worktree is added, so a branch deleted or moved since is checked out at its saved tip and its
+  # files always match it.
+  class WorktreeRevival
+    def initialize(snapshot, repo:)
+      @snapshot = snapshot
+      @repo = repo
+    end
+
+    # Same shape as an undo plan, plus `recreate_worktree`
+    def plan
+      head = @snapshot.head
+      { branches: Restore.new(@snapshot).plan[:branches],
+        head: { from: nil, to: head[:branch] || head[:sha] },
+        worktree: !@snapshot.worktree.nil?, stashes: [], snapshot: @snapshot.id,
+        recreate_worktree: @snapshot.worktree_path }
+    end
+
+    def scope
+      %w[branches]
+    end
+
+    def empty?
+      false
+    end
+
+    # Returns nil on success or the failed step's Result
+    def apply
+      failure = Restore.new(@snapshot).apply(only: :branches)
+      return failure if failure
+
+      result = attach
+      return result unless result.success?
+
+      restore = Restore.new(@snapshot, bash: Git::InDirectory.new(@snapshot.worktree_path))
+      restore.apply
+    end
+
+    private
+
+    def attach
+      worktrees = Worktrees.new(repo: @repo)
+      path = @snapshot.worktree_path
+      branch = @snapshot.head[:branch]
+      sha = @snapshot.head[:sha]
+      return worktrees.attach(path, detach_at: sha) unless branch
+
+      worktrees.attach(path, branch: branch, create_at: sha)
+    end
+  end
+end