mighost 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8aff4752d4638c5822c2e81ff30f7b2fd2b5ddf7f38009cbd24faea539fa1c24
-  data.tar.gz: 3a8580ffebdc73e87ce3eac7f29c5a7a9b98a83f935925974729b01581436336
+  metadata.gz: 4e7ba2817e992323bc0bd578432f76c0e28d8e86dcb7207c7fbb0ab7aa6cb99f
+  data.tar.gz: 38a4ca5b14240b3430278c2b60ced6b6ec7c43165f0d2e03105401115c5760c3
 SHA512:
-  metadata.gz: 1e9bf5182859b684f2799edfcdd9be3025af0af5416f4748207ce3bb439b6c5252db037c75443388353284f964a6192d8d9ccafe5d241201015dbb757a333e6c
-  data.tar.gz: 2eb3deee0b4c7083b887187fcce41e7e53252eb12e08b8756a9ec1bbbccac5b142ef64cef9a39ec5996d3f3edb737e31be7bbceab3bb5d701d3b322f1beff401
+  metadata.gz: cc1f54500be9da4130310bee9d37f6d6df95e2539ad05308d389dac24732e4de8af4e1c40281c2111f389d06ac9ad4d034836e1be8742174374a47fd1515ad1f
+  data.tar.gz: 717e1ca3fc35d784e63ea7b2e00fd571d60dc4d6f84c7487846356e988b463e9d251a6a21b8594f8a9a8ccb3815a4cd831e8aabeb9621a5ce8e3eb32e9c22237

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-23
+
+### Added
+
+- Superseded-migration classification: a ghost whose migration name suffix is
+  owned by another applied version with a file on disk is labeled superseded
+  (new `Mighost::Supersession` module, `OrphanedMigration#superseded_by` /
+  `#superseded?`, `Mighost::API.superseded_by`, and a dedicated
+  "Superseded (safe to forget)" section in `mighost:status`).
+- `config.hide_superseded` (default `false`) to hide superseded orphans from
+  detection.
+- Deletion metadata for ghosts gone from every branch tip: `deleted_in_sha`,
+  `deleted_at`, `deleted_by` on snapshots and orphans, rendered as
+  `deleted in:<sha>` in status output.
+
+### Fixed
+
+- Branch attribution no longer guesses: the reported branch is one whose tip
+  still has the migration file (preferring current branch → default branch →
+  local → remote by recency), instead of the first alphabetical branch that
+  merely contains the commit. Remote-only matches keep their `origin/` prefix
+  instead of masquerading as local branches.
+
 ## [0.4.0] - 2026-07-08
 
 First public release.

data/README.md

@@ -14,6 +14,13 @@
 
 ---
 
+> [!TIP]
+> Mighost is the recovery engine behind the ghost-migration features of
+> [**railbow**](https://github.com/amberpixels/railbow), which wraps it in rich, colorful
+> `db:migrate:status` output. If you want beautiful Rails CLI output *and* ghost recovery
+> in one step, you probably want to install railbow directly — it detects mighost and
+> uses it automatically.
+
 ## The Problem
 
 When working with Rails migrations across git branches:
@@ -120,9 +127,35 @@ Mighost.configure do |config|
 
   # Enable/disable (disabled in production by default)
   config.enabled = !Rails.env.production?
+
+  # Hide superseded orphans from status/detection (off by default —
+  # supersession is a name-suffix heuristic, and silently dropping rows
+  # could mask genuine schema drift)
+  config.hide_superseded = false
 end
 ```
 
+## Superseded migrations
+
+Some ghosts aren't lost — they were *re-timestamped*. When a migration ships with a bad
+timestamp and gets renamed to a new version, restoring from a production dump leaves the old
+version row in `schema_migrations` forever, with no file anywhere.
+
+Mighost detects this: a ghost whose migration name suffix is owned by another **applied**
+version with a file on disk is classified as **superseded** and listed in its own calmer
+`Superseded (safe to forget)` section of `mighost:status`, showing the superseding version
+instead of the alarming ghost treatment. `OrphanedMigration#superseded_by` /
+`#superseded?` expose the classification programmatically.
+
+## Honest branch attribution
+
+When Mighost recovers a ghost from git history, the reported branch is one whose **tip still
+has the file** — preferring the current branch, then the default branch, then local over
+remote branches (remote-only matches keep their `origin/` prefix). If the file is gone from
+every tip, Mighost reports no branch at all and instead records where it went:
+`deleted_in_sha`, `deleted_at`, `deleted_by` — rendered as `deleted in:<sha>` in status
+output. No more pointing you at an unrelated branch that merely contains the commit.
+
 ## Rich Output with Railbow
 
 By default, Mighost outputs plain, uncolored text. For rich, colorized output with tables, emojis, and git enrichment, use the [railbow](https://github.com/amberpixels/railbow) gem:
@@ -150,6 +183,9 @@ Mighost::API.scan!(rescan: false)                  # => {captured:, git_recovere
 
 # Rollback
 Mighost::API.rollback_version!("20240115123456")   # raises on failure
+
+# Supersession check (read-only)
+Mighost::API.superseded_by("20240115123456")       # => superseding version or nil
 ```
 
 ### UI Adapter

data/lib/mighost/api.rb

@@ -7,6 +7,7 @@ require_relative "snapshot"
 require_relative "rollbacker"
 require_relative "capturer"
 require_relative "git_recovery"
+require_relative "supersession"
 require_relative "worktree_recovery"
 require_relative "git_metadata"
 require_relative "formatting"
@@ -96,9 +97,12 @@ module Mighost
           git_sha: git_data[:sha],
           source: "git",
           author_name: git_data[:author_name],
-          author_email: git_data[:author_email]
+          author_email: git_data[:author_email],
+          deleted_in_sha: git_data[:deleted_in_sha],
+          deleted_at: git_data[:deleted_at],
+          deleted_by: git_data[:deleted_by]
         )
-        details << {type: :git_recovered, filename: git_data[:filename], branch: git_data[:branch]}
+        details << {type: :git_recovered, filename: git_data[:filename], branch: git_data[:branch], deleted_in_sha: git_data[:deleted_in_sha]}
         git_recovered += 1
       end
 
@@ -140,6 +144,15 @@ module Mighost
       }
     end
 
+    # Returns the superseding version (string) for a ghost, or nil.
+    # Read-only: resolves the ghost's filename from its snapshot, no recovery side effects.
+    def superseded_by(version)
+      snapshot = Snapshot.find_by_version(version)
+      return nil unless snapshot&.filename.present?
+
+      Supersession.find_superseder(version, filename: snapshot.filename)
+    end
+
     def dismiss(version)
       Snapshot.dismiss(version)
     end

data/lib/mighost/configuration.rb

@@ -21,12 +21,17 @@ module Mighost
     # Threshold for suggesting dismissal of old unrecoverable migrations
     attr_accessor :dismiss_old_threshold
 
+    # Hide superseded orphans from detection (off by default: supersession is a
+    # name-suffix heuristic, and silently dropping rows could mask schema drift)
+    attr_accessor :hide_superseded
+
     def initialize
       @storage_path = ".mighost.sqlite3"
       @auto_capture = true
       @store_git_metadata = true
       @enabled = true
       @dismiss_old_threshold = 6.months
+      @hide_superseded = false
     end
 
     def enabled?

data/lib/mighost/git_recovery.rb

@@ -9,7 +9,9 @@ module Mighost
   module GitRecovery
     class << self
       # Find migration file content from git history
-      # Returns { content:, filename:, branch:, sha:, commit_date: } or nil
+      # Returns { content:, filename:, branch:, sha:, commit_date:, deleted_in_sha:, ... } or nil
+      # branch: is a ref whose tip still has the file (remote refs keep their origin/ prefix),
+      # or nil when the file is gone from every tip — then the deleted_* fields say where it went.
       def find_migration(version)
         return nil unless GitMetadata.git_available?
 
@@ -22,6 +24,8 @@ module Mighost
         content = get_file_content(result[:sha], result[:path])
         return nil unless content
 
+        deletion = result[:branch] ? {} : deletion_metadata(pattern)
+
         {
           content: content,
           filename: File.basename(result[:path]),
@@ -29,7 +33,10 @@ module Mighost
           sha: result[:sha][0, 12],
           commit_date: result[:date],
           author_name: result[:author_name],
-          author_email: result[:author_email]
+          author_email: result[:author_email],
+          deleted_in_sha: deletion[:deleted_in_sha],
+          deleted_at: deletion[:deleted_at],
+          deleted_by: deletion[:deleted_by]
         }
       end
 
@@ -37,12 +44,11 @@ module Mighost
 
       def find_latest_commit_with_file(pattern)
         # Use git log --all to search across ALL refs in a single command
-        # %D shows decorated refs (branches/tags pointing to commit)
         # --name-only includes the filename in output
         # --diff-filter=d excludes deletion commits: without it, a migration whose
         # last touch was a delete resolves to the deleting commit, where the file
         # no longer exists and `git show` fails
-        fmt = "%H\t%aI\t%D\t%aN\t%aE"
+        fmt = "%H\t%aI\t%aN\t%aE"
         cmd = "git log --all -1 --diff-filter=d --format='#{fmt}' --name-only -- #{Shellwords.escape(pattern)} 2>/dev/null"
         output = `#{cmd}`.strip
         return nil if output.empty?
@@ -50,9 +56,9 @@ module Mighost
         lines = output.split("\n").map(&:strip).reject(&:empty?)
         return nil if lines.empty?
 
-        # First non-empty line: commit info (sha\tdate\tdecorated_refs\tauthor_name\tauthor_email)
+        # First non-empty line: commit info (sha\tdate\tauthor_name\tauthor_email)
         commit_line = lines[0]
-        sha, date_str, decorated_refs, author_name, author_email = commit_line.split("\t", 5)
+        sha, date_str, author_name, author_email = commit_line.split("\t", 4)
         return nil unless sha && date_str
 
         # Second non-empty line: the file path
@@ -66,56 +72,77 @@ module Mighost
         end
         return nil unless date
 
-        # Extract branch name from decorated refs (may be empty if commit is not a branch tip)
-        branch = extract_branch_from_decorated_refs(decorated_refs)
-
-        # If no branch found from decoration, try to find which branch contains this commit
-        branch ||= find_branch_containing_commit(sha)
-
         {
           sha: sha,
           path: file_path,
-          branch: branch,
+          branch: resolve_branch(sha, file_path),
           date: date,
           author_name: author_name,
           author_email: author_email
         }
       end
 
-      def extract_branch_from_decorated_refs(refs)
-        return nil if refs.nil? || refs.strip.empty?
+      # A branch is only a valid answer if its tip still has the file — a branch
+      # that merely contains the commit sends the user somewhere the file isn't.
+      def resolve_branch(sha, path)
+        locals, remotes = branch_candidates(sha)
+        locals = locals.select { |ref| file_at_tip?(ref, path) }
+        remotes = remotes.select { |ref| file_at_tip?(ref, path) }
+        return nil if locals.empty? && remotes.empty?
 
-        # Decorated refs look like: "HEAD -> main, origin/main, feature-branch"
-        # Extract the first branch-like ref
-        refs.split(",").each do |ref|
-          ref = ref.strip
-          ref = ref.sub(/^HEAD -> /, "")
-          ref = ref.sub(%r{^origin/}, "")
-          next if ref.empty? || ref.start_with?("tag:")
+        current = GitMetadata.current_branch
+        return current if current && locals.include?(current)
 
-          return ref
-        end
-        nil
+        default = default_branch
+        return default if default && locals.include?(default)
+
+        return locals.first unless locals.empty?
+
+        return "origin/#{default}" if default && remotes.include?("origin/#{default}")
+
+        remotes.first
       end
 
-      def find_branch_containing_commit(sha)
-        # Find branches that contain this commit
-        output = `git branch -a --contains #{sha} 2>/dev/null`.strip
-        return nil if output.empty?
+      # Refs containing the commit, most recently committed first.
+      # Returns [local_names, remote_names] — remote names keep their origin/ prefix.
+      def branch_candidates(sha)
+        [contains_refs(sha, "refs/heads"), contains_refs(sha, "refs/remotes")]
+      end
 
-        # Parse output - each line is a branch name, * = current branch, + = worktree-checked-out
-        lines = output.split("\n").map { |l| l.sub(/^[*+]?\s*/, "").strip }
-        return nil if lines.empty?
+      def contains_refs(sha, namespace)
+        cmd = "git for-each-ref #{namespace} --contains #{Shellwords.escape(sha)} " \
+          "--sort=-committerdate --format='%(refname:short)' 2>/dev/null"
+        `#{cmd}`.split("\n").map(&:strip).reject { |r| r.empty? || r.end_with?("/HEAD") }
+      end
 
-        # Prefer local branches over remote, clean up names
-        lines.each do |branch|
-          next if branch.start_with?("remotes/")
-          return branch
+      def file_at_tip?(ref, path)
+        system("git cat-file -e #{Shellwords.escape("#{ref}:#{path}")} 2>/dev/null")
+      end
+
+      def default_branch
+        head = `git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null`.strip
+        return head.sub(%r{^origin/}, "") unless head.empty?
+
+        %w[main master].find do |name|
+          system("git show-ref --verify --quiet #{Shellwords.escape("refs/heads/#{name}")}")
+        end
+      end
+
+      # Where the file was deleted, for ghosts gone from every tip
+      def deletion_metadata(pattern)
+        fmt = "%H\t%aI\t%aN"
+        cmd = "git log --all --diff-filter=D -1 --format='#{fmt}' -- #{Shellwords.escape(pattern)} 2>/dev/null"
+        output = `#{cmd}`.strip
+        return {} if output.empty?
+
+        sha, date_str, author = output.split("\t", 3)
+        date = begin
+          Time.parse(date_str)
+        rescue
+          nil
         end
 
-        # Fall back to first remote branch, cleaned up
-        first = lines.first
-        first&.sub(%r{^remotes/origin/}, "")
+        {deleted_in_sha: sha && sha[0, 12], deleted_at: date, deleted_by: author}
       end
 
       def get_file_content(sha, path)

data/lib/mighost/orphan_detector.rb

@@ -5,13 +5,16 @@ require "active_support/core_ext/object/blank"
 require "active_support/core_ext/enumerable"
 require_relative "snapshot"
 require_relative "git_metadata"
+require_relative "supersession"
 
 module Mighost
   class OrphanDetector
     class OrphanedMigration
-      attr_reader :version, :filename, :branch_name, :git_sha, :migrated_at, :source, :dismissed, :author_name, :author_email
+      attr_reader :version, :filename, :branch_name, :git_sha, :migrated_at, :source, :dismissed, :author_name, :author_email,
+        :superseded_by, :deleted_in_sha, :deleted_at, :deleted_by
 
-      def initialize(version:, filename: nil, branch_name: nil, git_sha: nil, migrated_at: nil, source: nil, dismissed: false, author_name: nil, author_email: nil)
+      def initialize(version:, filename: nil, branch_name: nil, git_sha: nil, migrated_at: nil, source: nil, dismissed: false,
+        author_name: nil, author_email: nil, superseded_by: nil, deleted_in_sha: nil, deleted_at: nil, deleted_by: nil)
         @version = version
         @filename = filename
         @branch_name = branch_name
@@ -21,6 +24,15 @@ module Mighost
         @dismissed = dismissed
         @author_name = author_name
         @author_email = author_email
+        @superseded_by = superseded_by
+        @deleted_in_sha = deleted_in_sha
+        @deleted_at = deleted_at
+        @deleted_by = deleted_by
+      end
+
+      # Schema change lives on under a re-timestamped version — a stale row, not a lost migration
+      def superseded?
+        !superseded_by.nil?
       end
 
       def recoverable?
@@ -74,9 +86,11 @@ module Mighost
       def detect(include_dismissed: false)
         # Load everything upfront for performance
         versions = migrated_versions
-        file_versions = migration_file_versions
+        disk_files = migration_file_basenames
+        file_versions = disk_files.map { |basename| basename.split("_").first }.to_set
         dismissed_set = Snapshot.dismissed_versions.to_set
         snapshots_by_version = Snapshot.all_metadata.index_by(&:version)
+        hide_superseded = Mighost.configuration.hide_superseded
 
         log "Found #{versions.count} migrated versions, #{file_versions.count} files on disk"
 
@@ -92,6 +106,16 @@ module Mighost
           snapshot = snapshots_by_version[version]
           log "  #{version} - orphaned#{", has snapshot (#{snapshot.source})" if snapshot}"
 
+          superseded_by = if snapshot&.filename.present?
+            Supersession.find_superseder(
+              version,
+              filename: snapshot.filename,
+              applied_versions: versions,
+              disk_files: disk_files
+            )
+          end
+          next if superseded_by && hide_superseded
+
           orphaned << OrphanedMigration.new(
             version: version,
             filename: snapshot&.filename,
@@ -101,7 +125,11 @@ module Mighost
             source: snapshot&.source,
             dismissed: is_dismissed,
             author_name: snapshot&.author_name,
-            author_email: snapshot&.author_email
+            author_email: snapshot&.author_email,
+            superseded_by: superseded_by,
+            deleted_in_sha: snapshot&.deleted_in_sha,
+            deleted_at: snapshot&.deleted_at,
+            deleted_by: snapshot&.deleted_by
           )
         end
 
@@ -149,16 +177,11 @@ module Mighost
         Mighost::Base.connection.quote_table_name("schema_migrations")
       end
 
-      # Load all migration file versions at once (single glob per path)
-      def migration_file_versions
-        versions = Set.new
-        migration_paths.each do |path|
-          Dir.glob(File.join(path, "*.rb")).each do |file|
-            version = File.basename(file).split("_").first
-            versions << version
-          end
+      # Load all migration file basenames at once (single glob per path)
+      def migration_file_basenames
+        migration_paths.flat_map do |path|
+          Dir.glob(File.join(path, "*.rb")).map { |file| File.basename(file) }
         end
-        versions
       end
 
       def migration_paths

data/lib/mighost/plain_ui.rb

@@ -33,12 +33,14 @@ module Mighost
         return
       end
 
-      actionable, suggested = orphans.partition(&:actionable?)
+      superseded, rest = orphans.partition(&:superseded?)
+      actionable, suggested = rest.partition(&:actionable?)
 
       recoverable_count = orphans.count(&:recoverable?)
       suggested_count = suggested.count
 
       header_parts = ["#{orphans.count} total", "#{recoverable_count} recoverable"]
+      header_parts << "#{superseded.count} superseded" if superseded.any?
       header_parts << "#{suggested_count} suggested to dismiss" if suggested_count.positive?
       puts "\nOrphaned migrations (#{header_parts.join(", ")}):\n\n"
 
@@ -50,6 +52,11 @@ module Mighost
 
       suggested.each { |o| puts "  #{orphan_line(o)}" }
 
+      if superseded.any?
+        puts "\n  Superseded (safe to forget — schema is owned by a newer version):\n"
+        superseded.each { |o| puts "  #{orphan_line(o)}  superseded by #{o.superseded_by}" }
+      end
+
       if suggested_count.positive?
         puts "\nTip: Run 'rails mighost:dismiss OLD=1' to bulk-dismiss the #{suggested_count} old migrations."
       end
@@ -108,7 +115,14 @@ module Mighost
         when :captured
           info "Captured: #{detail[:filename]}"
         when :git_recovered
-          info "Git recovered: #{detail[:filename]} (from #{detail[:branch]})"
+          location = if detail[:branch]
+            "from #{detail[:branch]}"
+          elsif detail[:deleted_in_sha]
+            "deleted in #{detail[:deleted_in_sha]}"
+          else
+            "from history"
+          end
+          info "Git recovered: #{detail[:filename]} (#{location})"
         when :worktree_recovered
           info "Worktree recovered: #{detail[:filename]} (from #{detail[:branch]})"
         end
@@ -213,7 +227,14 @@ module Mighost
       version = orphan.version
       name = format_name(orphan.filename)
       recovery = orphan.recoverable? ? "recoverable (#{format_recovery(orphan.recovery_source)})" : "not recoverable"
-      branch = orphan.branch_name ? "branch:#{truncate(orphan.branch_name, 30)}" : ""
+      branch = if orphan.branch_name
+        "branch:#{truncate(orphan.branch_name, 30)}"
+      elsif orphan.deleted_in_sha
+        # File is gone from every branch tip — say where it was deleted instead of guessing a branch
+        "deleted in:#{orphan.deleted_in_sha}"
+      else
+        ""
+      end
       author = orphan.author_name ? "author:#{truncate(orphan.author_name, 20)}" : ""
 
       parts = [version, name.ljust(42), recovery.ljust(24)]

data/lib/mighost/snapshot.rb

@@ -8,7 +8,7 @@ require "active_support/core_ext/time"
 module Mighost
   class Snapshot
     attr_accessor :id, :version, :content, :filename, :branch_name, :git_sha, :content_hash, :migrated_at, :source,
-      :dismissed, :dismissed_at, :author_name, :author_email
+      :dismissed, :dismissed_at, :author_name, :author_email, :deleted_in_sha, :deleted_at, :deleted_by
 
     # Special version used to store scan metadata
     SCAN_METADATA_VERSION = "__scan_metadata__"
@@ -37,7 +37,10 @@ module Mighost
             dismissed INTEGER DEFAULT 0,
             dismissed_at TEXT,
             author_name TEXT,
-            author_email TEXT
+            author_email TEXT,
+            deleted_in_sha TEXT,
+            deleted_at TEXT,
+            deleted_by TEXT
           )
         SQL
         db.execute("CREATE UNIQUE INDEX IF NOT EXISTS idx_#{table_name}_version ON #{table_name}(version)")
@@ -70,7 +73,10 @@ module Mighost
             git_sha: git_data[:sha],
             source: "git",
             author_name: git_data[:author_name],
-            author_email: git_data[:author_email]
+            author_email: git_data[:author_email],
+            deleted_in_sha: git_data[:deleted_in_sha],
+            deleted_at: git_data[:deleted_at],
+            deleted_by: git_data[:deleted_by]
           )
         end
 
@@ -89,23 +95,25 @@ module Mighost
         )
       end
 
-      def store(version:, content:, filename:, branch_name: nil, git_sha: nil, source: "file", author_name: nil, author_email: nil)
+      def store(version:, content:, filename:, branch_name: nil, git_sha: nil, source: "file", author_name: nil, author_email: nil,
+        deleted_in_sha: nil, deleted_at: nil, deleted_by: nil)
         ensure_table_exists!
         content_hash = Digest::SHA256.hexdigest(content)
         migrated_at = Time.current.iso8601
+        deleted_at = deleted_at.iso8601 if deleted_at.respond_to?(:iso8601)
 
         existing = find_by_version(version)
         if existing
-          db.execute(<<~SQL, [content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email, version.to_s])
+          db.execute(<<~SQL, [content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email, deleted_in_sha, deleted_at, deleted_by, version.to_s])
             UPDATE #{table_name}
             SET content = ?, filename = ?, branch_name = ?, git_sha = ?, content_hash = ?, migrated_at = ?, source = ?,
-                author_name = ?, author_email = ?
+                author_name = ?, author_email = ?, deleted_in_sha = ?, deleted_at = ?, deleted_by = ?
             WHERE version = ?
           SQL
         else
-          db.execute(<<~SQL, [version.to_s, content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email])
-            INSERT INTO #{table_name} (version, content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+          db.execute(<<~SQL, [version.to_s, content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email, deleted_in_sha, deleted_at, deleted_by])
+            INSERT INTO #{table_name} (version, content, filename, branch_name, git_sha, content_hash, migrated_at, source, author_name, author_email, deleted_in_sha, deleted_at, deleted_by)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
           SQL
         end
 
@@ -196,9 +204,9 @@ module Mighost
       # Lightweight version - only metadata, no content (for status display)
       def all_metadata
         ensure_table_exists!
-        cols = %i[version filename branch_name git_sha migrated_at source dismissed author_name author_email]
+        cols = %i[version filename branch_name git_sha migrated_at source dismissed author_name author_email deleted_in_sha deleted_at deleted_by]
         db.execute(
-          "SELECT version, filename, branch_name, git_sha, migrated_at, source, dismissed, author_name, author_email FROM #{table_name} WHERE version != ?",
+          "SELECT version, filename, branch_name, git_sha, migrated_at, source, dismissed, author_name, author_email, deleted_in_sha, deleted_at, deleted_by FROM #{table_name} WHERE version != ?",
           [SCAN_METADATA_VERSION]
         ).map do |row|
           record = new(cols.zip(row).to_h)
@@ -249,9 +257,18 @@ module Mighost
         unless columns.include?("author_email")
           db.execute("ALTER TABLE #{table_name} ADD COLUMN author_email TEXT")
         end
+        unless columns.include?("deleted_in_sha")
+          db.execute("ALTER TABLE #{table_name} ADD COLUMN deleted_in_sha TEXT")
+        end
+        unless columns.include?("deleted_at")
+          db.execute("ALTER TABLE #{table_name} ADD COLUMN deleted_at TEXT")
+        end
+        unless columns.include?("deleted_by")
+          db.execute("ALTER TABLE #{table_name} ADD COLUMN deleted_by TEXT")
+        end
       end
 
-      SNAPSHOT_COLUMNS = %i[id version content filename branch_name git_sha content_hash migrated_at source dismissed dismissed_at author_name author_email].freeze
+      SNAPSHOT_COLUMNS = %i[id version content filename branch_name git_sha content_hash migrated_at source dismissed dismissed_at author_name author_email deleted_in_sha deleted_at deleted_by].freeze
       private_constant :SNAPSHOT_COLUMNS
 
       def row_to_snapshot(row)

data/lib/mighost/supersession.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Mighost
+  # Detects re-timestamped migrations: a ghost version whose name suffix is owned
+  # by another applied version with a file on disk is superseded, not lost.
+  module Supersession
+    module_function
+
+    # Returns the superseding version (string) for `version`, or nil.
+    # A superseder must be a different version, present in schema_migrations,
+    # and own an on-disk migration file with the same name suffix — an applied
+    # version whose own file is missing is itself a ghost, not a superseder.
+    #
+    # applied_versions and disk_files (migration file basenames) are injectable
+    # so batch callers like OrphanDetector can reuse data they already loaded.
+    def find_superseder(version, filename:, applied_versions: nil, disk_files: nil)
+      suffix = name_suffix(filename)
+      return nil unless suffix
+
+      applied = applied_versions || load_applied_versions
+      files = disk_files || load_disk_files
+
+      # Newest candidate wins if several versions share the suffix
+      files.sort.reverse_each do |basename|
+        candidate = basename.split("_").first
+        next if candidate == version.to_s
+        next unless applied.include?(candidate)
+
+        return candidate if name_suffix(basename) == suffix
+      end
+      nil
+    end
+
+    # "20260702110000_add_utility_belt_to_batcaves.rb" -> "add_utility_belt_to_batcaves"
+    def name_suffix(basename)
+      return nil if basename.nil? || basename.empty?
+
+      basename.sub(/\.rb\z/, "").split("_", 2)[1]
+    end
+
+    def load_applied_versions
+      Mighost::Base.connection
+        .select_values("SELECT version FROM schema_migrations")
+        .map(&:to_s)
+    end
+
+    def load_disk_files
+      paths = if defined?(Rails) && Rails.application
+        Rails.application.config.paths["db/migrate"].to_ary
+      else
+        ["db/migrate"]
+      end
+
+      paths.flat_map { |path| Dir.glob(File.join(path, "*.rb")).map { |f| File.basename(f) } }
+    end
+  end
+end

data/lib/mighost/tasks.rake

@@ -53,6 +53,10 @@ namespace :mighost do
       ui.hint "#{dismissed_count} dismissed migration(s) hidden. Use SHOW_DISMISSED=1 to show." if dismissed_count.positive?
     end
 
+    if Mighost.configuration.hide_superseded
+      ui.hint "Superseded migrations are hidden (config.hide_superseded)."
+    end
+
     non_recoverable = orphans.reject(&:recoverable?)
     if non_recoverable.any? && Mighost::OrphanDetector.branch_changed?
       ui.hint "Branch changed since last scan. Run 'rails mighost:scan' to update recovery info."

data/lib/mighost/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mighost
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mighost
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Eugene M
@@ -89,6 +89,7 @@ files:
 - lib/mighost/railtie.rb
 - lib/mighost/rollbacker.rb
 - lib/mighost/snapshot.rb
+- lib/mighost/supersession.rb
 - lib/mighost/tasks.rake
 - lib/mighost/version.rb
 - lib/mighost/worktree_recovery.rb