fix: correctly detect rate-limit state for single-key API pools

IsAllRateLimited() short-circuited true for any pool with 0 or 1
keys, with minRetrySeconds left at 0 regardless of whether that key
was actually rate-limited. SleepUntilAnyAvailable() checks
"minRetry <= 0" to decide whether to skip sleeping, so with exactly
one key it always skipped the wait and let callers hammer the API
again immediately after a 429, even mid-cooldown.

The per-key loop already computes this correctly for any key count;
the special case only needs to cover the true no-keys edge case,
where there's nothing to wait on.

.github/copilot-instructions.md

@@ -22,18 +22,18 @@ This document provides essential context for AI agents working with URLNotesGrab
 ```powershell
 dotnet build
 dotnet run            # Process all files in input directory
-dotnet run -- -parse [blogname]  # Process specific blog
-dotnet run -- -test [blogname] [postID]  # Test API for specific post
+dotnet run -- --parse [blogname]  # Process specific blog
+dotnet run -- --test [blogname] [postID]  # Test API for specific post
 ```
 
 ### Command-Line Interface
-- `-parse [blogname]`: Parse text files for specific blog
-- `-test [blogname] [postID]`: Test API note collection
-- `-posts`: Export post blogs to file
-- `-blogs`: Export blog list to file
-- `-collect`: Collect notes for all posts in DB
-- `-blogsR`: Export reply blogs to file
-- `-blogsO [start] [stop]`: Export blogs within range
+- `--parse [blogname]`: Parse text files for specific blog
+- `--test [blogname] [postID]`: Test API note collection
+- `--posts`: Export post blogs to file
+- `--blogs`: Export blog list to file
+- `--collect`: Collect notes for all posts in DB
+- `--blogsR`: Export reply blogs to file
+- `--blogsO [start] [stop]`: Export blogs within range
 
 ## Project Conventions
 

URLNotesGrabberCORE/DataAccess.cs

@@ -139,7 +139,7 @@ namespace URLNotesGrabberCORE
                 if (_savedImportPragmas != null)
                     return;
 
-                SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+                using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
                 try
                 {
                     connection.Open();
@@ -175,10 +175,6 @@ namespace URLNotesGrabberCORE
                 {
                     Console.WriteLine($"[SQLite Import Mode] Failed to enable import pragmas: {ex.Message}");
                 }
-                finally
-                {
-                    connection.Close();
-                }
             }
         }
 
@@ -190,7 +186,7 @@ namespace URLNotesGrabberCORE
                 if (_savedImportPragmas == null)
                     return;
 
-                SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+                using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
                 try
                 {
                     connection.Open();
@@ -217,7 +213,6 @@ namespace URLNotesGrabberCORE
                 finally
                 {
                     _savedImportPragmas = null;
-                    connection.Close();
                 }
             }
         }
@@ -252,7 +247,7 @@ namespace URLNotesGrabberCORE
         public static void EnsureReplyTextColumnExists(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -296,16 +291,12 @@ namespace URLNotesGrabberCORE
                 // Breakpoint here
                 Console.WriteLine($"Error checking/creating replyText column: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         public static void EnsureBlogsLikesColumnsExist(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -391,10 +382,6 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error mapping Blogs likes columns: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         #region Adds
@@ -518,8 +505,12 @@ namespace URLNotesGrabberCORE
                         {
                             if (ownsConnection) connection.Open();
 
-                            string updateSql = "UPDATE Posts SET hasImage = " + (hasImage ? 1 : 0) + ", DateModified = '" + DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss") + "' WHERE blogName = '" + blogName + "' AND postID = '" + postID + "'";
-                            SQLiteCommand updateCommand = new SQLiteCommand(updateSql, connection);
+                            string updateSql = "UPDATE Posts SET hasImage = @hasImage, DateModified = @DateModified WHERE blogName = @blogName AND postID = @postID";
+                            using SQLiteCommand updateCommand = new SQLiteCommand(updateSql, connection);
+                            updateCommand.Parameters.AddWithValue("@hasImage", hasImage ? 1 : 0);
+                            updateCommand.Parameters.AddWithValue("@DateModified", DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"));
+                            updateCommand.Parameters.AddWithValue("@blogName", blogName);
+                            updateCommand.Parameters.AddWithValue("@postID", postID);
 
                             updateCommand.ExecuteNonQuery();
                         }
@@ -565,7 +556,7 @@ namespace URLNotesGrabberCORE
         public static void AddAPICount(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -586,10 +577,6 @@ namespace URLNotesGrabberCORE
                 // Breakpoint here
                 //Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         public static bool AddNote(string rootBlogName, string noteBlogName, long postID, long timestamp, string type, string? DBPath = null)
@@ -598,7 +585,7 @@ namespace URLNotesGrabberCORE
             //try { AddPost(rootBlogName, postID, DBPath); } catch { }
             try { AddBlog(noteBlogName, false, DBPath); } catch { }
 
-            SQLiteConnection connection2 = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection2 = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -657,10 +644,6 @@ namespace URLNotesGrabberCORE
                     Console.WriteLine("^^^^^ - SHORTCUT");
                 }
             }
-            finally
-            {
-                connection2.Close();
-            }
             return false;
         }
         #endregion Adds
@@ -676,7 +659,7 @@ namespace URLNotesGrabberCORE
         public static List<Tuple<string, long, long, long>> GetPosts(bool withoutNotesOnly = false, DateTime? beforeDate = null, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<Tuple<string, long, long, long>> posts = new List<Tuple<string, long, long, long>>();
 
             try
@@ -854,17 +837,13 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
             return posts;
         }
 
         public static List<Tuple<string, long>> GetReplies(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<Tuple<string, long>> posts = new List<Tuple<string, long>>();
 
             try
@@ -898,17 +877,13 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
             return posts;
         }
 
         public static List<Tuple<string, long>> GetRepliesWithMissingText(string? DBPath = null, int limit = 50)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<Tuple<string, long>> posts = new List<Tuple<string, long>>();
 
             try
@@ -949,17 +924,13 @@ namespace URLNotesGrabberCORE
                 // Breakpoint here
                 Console.WriteLine($"Error getting replies with missing text: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
             return posts;
         }
 
         public static List<Tuple<string, long, long>> GetRepliesWithFilledText(string? DBPath = null, int? limit = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<Tuple<string, long, long>> posts = new List<Tuple<string, long, long>>();
 
             try
@@ -1011,17 +982,13 @@ namespace URLNotesGrabberCORE
                 // Breakpoint here
                 Console.WriteLine($"Error getting replies with filled text: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
             return posts;
         }
 
         public static int GetAPICount(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             int count = 0;
 
             try { AddAPICount(); } catch { }
@@ -1050,17 +1017,13 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
             return count;
         }
 
         public static List<Tuple<string, int, long, long>> GetBlogsForLikes(string specificBlog = null, int cooldownDays = 7, bool ignoreCooldown = false, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<Tuple<string, int, long, long>> blogs = new List<Tuple<string, int, long, long>>();
 
             try
@@ -1136,17 +1099,13 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error fetching blogs for likes: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
             return blogs;
         }
 
         public static List<string> GetBlogs(bool reblogsOnly, int from, int to, int top, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<string> blogs = new List<string>();
 
             try
@@ -1181,17 +1140,13 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
             return blogs;
         }
 
         public static List<string> GetBlogsAll(bool reblogsOnly, int from, int to, int top, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             List<string> blogs = new List<string>();
 
             try
@@ -1226,51 +1181,39 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
             return blogs;
         }
         public static IEnumerable<List<string>> GetAllPostTextColumns(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             connection.Open();
-            try
+            string sql = "SELECT BlogName, reblogURL, PostURL, Slug, ReblogKey, ReblogName, Summary, Quote, Body, Tags, Link, PhotoURL, PhotoCaption, DownloadedFiles, AudioCaption, Question, Answer, Title, RootBlogName, RootURL FROM Posts WHERE IFNULL(DownloadedFiles, '.') = '.'";
+            using (SQLiteCommand command = new SQLiteCommand(sql, connection))
             {
-                string sql = "SELECT BlogName, reblogURL, PostURL, Slug, ReblogKey, ReblogName, Summary, Quote, Body, Tags, Link, PhotoURL, PhotoCaption, DownloadedFiles, AudioCaption, Question, Answer, Title, RootBlogName, RootURL FROM Posts WHERE IFNULL(DownloadedFiles, '.') = '.'";
-                using (SQLiteCommand command = new SQLiteCommand(sql, connection))
+                using (SQLiteDataReader reader = command.ExecuteReader())
                 {
-                    using (SQLiteDataReader reader = command.ExecuteReader())
+                    while (reader.Read())
                     {
-                        while (reader.Read())
+                        List<string> rowTexts = new List<string>();
+                        for (int i = 0; i < reader.FieldCount; i++)
                         {
-                            List<string> rowTexts = new List<string>();
-                            for (int i = 0; i < reader.FieldCount; i++)
+                            if (!reader.IsDBNull(i))
                             {
-                                if (!reader.IsDBNull(i))
+                                var val = reader.GetValue(i);
+                                if (val is string str && !string.IsNullOrWhiteSpace(str) && str != ".")
                                 {
-                                    var val = reader.GetValue(i);
-                                    if (val is string str && !string.IsNullOrWhiteSpace(str) && str != ".")
-                                    {
-                                        rowTexts.Add(str);
-                                    }
+                                    rowTexts.Add(str);
                                 }
                             }
-                            if (rowTexts.Count > 0)
-                            {
-                                yield return rowTexts;
-                            }
+                        }
+                        if (rowTexts.Count > 0)
+                        {
+                            yield return rowTexts;
                         }
                     }
                 }
             }
-            finally
-            {
-                connection.Close();
-                connection.Dispose();
-            }
         }
         #endregion Gets
 
@@ -1280,7 +1223,7 @@ namespace URLNotesGrabberCORE
         public static void UpdatePostMarkNotesCollected(string blogName, long postID, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1303,16 +1246,12 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         public static void UpdatePostMarkNotFound(string blogName, long postID, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1336,10 +1275,69 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
+        }
+
+        // ----- CollectRunState: tracks the frozen cutoff + completion flag for a managed "-collect 0" full re-check run -----
+        // Single-row table (Id = 1), mirroring the ApiKeyPoolMeta pattern. Lets an interrupted run resume against the
+        // same cutoff and lets a completed run stop instead of restarting on the next launch.
+
+        public static void EnsureCollectRunStateTableExists(string? DBPath = null)
+        {
+            DBPath ??= GetDefaultDbPath();
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            connection.Open();
+            string sql = "CREATE TABLE IF NOT EXISTS CollectRunState (" +
+                         "Id INTEGER PRIMARY KEY CHECK (Id = 1), " +
+                         "RunCutoff INTEGER DEFAULT 0, " +
+                         "RunComplete INTEGER DEFAULT 1, " +
+                         "RunStarted TEXT, " +
+                         "RunCompletedAt TEXT)";
+            using SQLiteCommand command = new SQLiteCommand(sql, connection);
+            command.ExecuteNonQuery();
+        }
+
+        // Returns (RunCutoff unix seconds, RunComplete) for the single run-state row, or null if no row exists yet.
+        public static (long cutoff, bool complete)? GetCollectRunState(string? DBPath = null)
+        {
+            DBPath ??= GetDefaultDbPath();
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            connection.Open();
+            using SQLiteCommand command = new SQLiteCommand("SELECT RunCutoff, RunComplete FROM CollectRunState WHERE Id = 1", connection);
+            using SQLiteDataReader reader = command.ExecuteReader();
+            if (reader.Read())
             {
-                connection.Close();
+                long cutoff = Convert.ToInt64(reader.GetValue(0));
+                bool complete = Convert.ToInt64(reader.GetValue(1)) != 0;
+                return (cutoff, complete);
             }
+            return null;
+        }
+
+        // Start (or restart) a managed run: freeze the cutoff and mark the run in progress.
+        public static void BeginCollectRun(long cutoffUnixSeconds, string? DBPath = null)
+        {
+            DBPath ??= GetDefaultDbPath();
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            connection.Open();
+            string sql = "INSERT INTO CollectRunState (Id, RunCutoff, RunComplete, RunStarted, RunCompletedAt) " +
+                         "VALUES (1, @cutoff, 0, @started, NULL) " +
+                         "ON CONFLICT(Id) DO UPDATE SET RunCutoff = @cutoff, RunComplete = 0, RunStarted = @started, RunCompletedAt = NULL";
+            using SQLiteCommand command = new SQLiteCommand(sql, connection);
+            command.Parameters.AddWithValue("@cutoff", cutoffUnixSeconds);
+            command.Parameters.AddWithValue("@started", DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"));
+            command.ExecuteNonQuery();
+        }
+
+        // Mark the active managed run complete so the next launch starts fresh instead of resuming.
+        public static void CompleteCollectRun(string? DBPath = null)
+        {
+            DBPath ??= GetDefaultDbPath();
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            connection.Open();
+            string sql = "UPDATE CollectRunState SET RunComplete = 1, RunCompletedAt = @completedAt WHERE Id = 1";
+            using SQLiteCommand command = new SQLiteCommand(sql, connection);
+            command.Parameters.AddWithValue("@completedAt", DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"));
+            command.ExecuteNonQuery();
         }
 
         public static void UpdatePostSetDate(string blogName, long postID, string postDate, string? DBPath = null)
@@ -1388,7 +1386,7 @@ namespace URLNotesGrabberCORE
 
             Console.WriteLine("{2}\t{0}\t{1}", UnixTimeStampToDateTime(timestamp), noteBlogName, type);
 
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1415,10 +1413,6 @@ namespace URLNotesGrabberCORE
                     return true;
                 }
             }
-            finally
-            {
-                connection.Close();
-            }
             return false;
         }
 
@@ -1534,7 +1528,7 @@ namespace URLNotesGrabberCORE
         public static void UpdateBlogOutput(string blogName, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1554,16 +1548,12 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         public static void UpdateBlogLikesStatus(string blogName, int likesPulled, long likesCursor, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             try
             {
                 connection.Open();
@@ -1581,10 +1571,6 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error updating blog likes status: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         // Bumps the high-water mark for a blog. Used during Branch A (initial backfill) when we
@@ -1594,7 +1580,7 @@ namespace URLNotesGrabberCORE
         {
             if (newestTimestamp <= 0) return;
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             try
             {
                 connection.Open();
@@ -1614,10 +1600,6 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error updating blog likes newest timestamp: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         // Called at the end of a refresh pass (Branch B). Bumps the high-water mark, stamps the
@@ -1625,7 +1607,7 @@ namespace URLNotesGrabberCORE
         public static void UpdateBlogLikesRefreshStatus(string blogName, long newestTimestamp, int newCount, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             try
             {
                 connection.Open();
@@ -1648,16 +1630,12 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error updating blog likes refresh status: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         public static int UpdateAPICount(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             int APICount = DataAccess.GetAPICount();
             APICount++;
@@ -1680,10 +1658,6 @@ namespace URLNotesGrabberCORE
                 if (ex.Message != "constraint failed\r\nUNIQUE constraint failed: Posts.BlogName, Posts.PostID")
                     Console.WriteLine(ex.Message);
             }
-            finally
-            {
-                connection.Close();
-            }
 
             return APICount;
         }
@@ -1691,7 +1665,7 @@ namespace URLNotesGrabberCORE
         public static int UpdateNoteReplyText(string rootBlogName, long postID, string noteBlogName, long timestamp, string replyText, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
             int rowsAffected = 0;
 
             // A bare "." collides with the "needs processing" sentinel in GetRepliesWithFilledText, which would loop the post forever. Store as ". " so the data is preserved but no longer matches the sentinel.
@@ -1734,17 +1708,13 @@ namespace URLNotesGrabberCORE
                 Console.WriteLine($"[UpdateNoteReplyText] Error updating reply text: {ex.Message}");
                 Console.WriteLine($"[UpdateNoteReplyText] StackTrace: {ex.StackTrace}");
             }
-            finally
-            {
-                connection.Close();
-            }
             return rowsAffected;
         }
 
         public static int UpdateAllNoteReplyTextForPost(string rootBlogName, long postID, string replyText, string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1780,10 +1750,6 @@ namespace URLNotesGrabberCORE
                 Console.WriteLine($"[UpdateAllNoteReplyTextForPost] StackTrace: {ex.StackTrace}");
                 return 0;
             }
-            finally
-            {
-                connection.Close();
-            }
         }
         #endregion Updates
 
@@ -1794,7 +1760,7 @@ namespace URLNotesGrabberCORE
         public static void EnsureTTFileHelperColumnsExist(string? DBPath = null)
         {
             DBPath ??= GetDefaultDbPath();
-            SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
+            using SQLiteConnection connection = new SQLiteConnection("Data Source=" + DBPath);
 
             try
             {
@@ -1840,10 +1806,6 @@ namespace URLNotesGrabberCORE
             {
                 Console.WriteLine($"Error ensuring TTFileHelper columns: {ex.Message}");
             }
-            finally
-            {
-                connection.Close();
-            }
         }
 
         // INSERT-or-UPDATE for a post arriving from a Tumblr text-file export.
@@ -2664,7 +2626,7 @@ namespace URLNotesGrabberCORE
         {
             minRetrySeconds = 0;
             if (!_usePool || _overrideKey != null) return false;
-            if (_keys.Count <= 1) return true;
+            if (_keys.Count == 0) return false;
 
             var now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
             bool all = true;

URLNotesGrabberCORE/Program.cs

@@ -5,7 +5,6 @@ using Microsoft.Extensions.Configuration;
 using System.Configuration;
 using System.Threading;
 using Microsoft.Extensions.Diagnostics.Latency;
-using static System.Runtime.InteropServices.JavaScript.JSType;
 using System.Text.RegularExpressions;
 
 namespace URLNotesGrabberCORE
@@ -13,12 +12,27 @@ namespace URLNotesGrabberCORE
     internal class Program
     {
 
-        static void Main(string[] args)
+        static int Main(string[] args)
         {
             // Reset console color on exit (including Ctrl+C)
             Console.CancelKeyPress += (s, e) => Console.ResetColor();
             AppDomain.CurrentDomain.ProcessExit += (s, e) => Console.ResetColor();
 
+            try
+            {
+                return Run(args);
+            }
+            catch (Exception ex)
+            {
+                // Turn configuration errors / unguarded indexers into a quiet, deterministic exit code.
+                Console.Error.WriteLine(ex.Message);
+                return 1;
+            }
+        }
+
+        static int Run(string[] args)
+        {
+            int exitCode = 0;
             IConfiguration config = new ConfigurationBuilder()
                                     .SetBasePath(Directory.GetCurrentDirectory())
                                     .AddJsonFile("appsettings.json", optional: true, reloadOnChange: false)
@@ -33,31 +47,34 @@ namespace URLNotesGrabberCORE
             List<string> filteredArgs = new List<string>();
             for (int i = 0; i < args.Length; i++)
             {
-                if (string.Equals(args[i], "-force", StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(args[i], "--force", StringComparison.OrdinalIgnoreCase))
+                if (args[i] == "--")
+                {
+                    // POSIX end-of-options: everything after is a literal operand.
+                    for (int j = i + 1; j < args.Length; j++) filteredArgs.Add(args[j]);
+                    break;
+                }
+
+                if (string.Equals(args[i], "--force", StringComparison.OrdinalIgnoreCase))
                 {
                     forceIgnoreCooldown = true;
                     continue;
                 }
 
-                if (string.Equals(args[i], "-api3", StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(args[i], "--api3", StringComparison.OrdinalIgnoreCase))
+                if (string.Equals(args[i], "--api3", StringComparison.OrdinalIgnoreCase))
                 {
                     apiSectionName = "TumblrApi3";
                     apiExplicitlySet = true;
                     continue;
                 }
 
-                if (string.Equals(args[i], "-api4", StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(args[i], "--api4", StringComparison.OrdinalIgnoreCase))
+                if (string.Equals(args[i], "--api4", StringComparison.OrdinalIgnoreCase))
                 {
                     apiSectionName = "TumblrApi4";
                     apiExplicitlySet = true;
                     continue;
                 }
 
-                if (string.Equals(args[i], "-api", StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(args[i], "--api", StringComparison.OrdinalIgnoreCase))
+                if (string.Equals(args[i], "--api", StringComparison.OrdinalIgnoreCase))
                 {
                     if (i + 1 < args.Length && !string.IsNullOrWhiteSpace(args[i + 1]))
                     {
@@ -67,13 +84,12 @@ namespace URLNotesGrabberCORE
                     }
                     else
                     {
-                        Console.WriteLine("--Missing API section after -api/--api. Using default TumblrApi.--");
+                        Console.WriteLine("--Missing API section after --api. Using default TumblrApi.--");
                     }
                     continue;
                 }
 
-                if (string.Equals(args[i], "-start", StringComparison.OrdinalIgnoreCase) ||
-                    string.Equals(args[i], "--start", StringComparison.OrdinalIgnoreCase))
+                if (string.Equals(args[i], "--start", StringComparison.OrdinalIgnoreCase))
                 {
                     if (i + 1 < args.Length && !string.IsNullOrWhiteSpace(args[i + 1]))
                     {
@@ -82,7 +98,7 @@ namespace URLNotesGrabberCORE
                     }
                     else
                     {
-                        Console.WriteLine("--Missing blog name after -start/--start. Ignoring.--");
+                        Console.WriteLine("--Missing blog name after --start. Ignoring.--");
                     }
                     continue;
                 }
@@ -123,7 +139,10 @@ namespace URLNotesGrabberCORE
                 Console.SetOut(dualLogger);
             }
 
-            List<string> contains = settings.GetValue<string>("ContainsList").Split(',').ToList();
+            string? containsListSetting = settings.GetValue<string>("ContainsList");
+            if (string.IsNullOrEmpty(containsListSetting))
+                throw new InvalidOperationException("ContainsList is not configured in appsettings.json");
+            List<string> contains = containsListSetting.Split(',').ToList();
             bool logTraversalRecordImports = settings.GetValue("LogTraversalRecordImports", false);
 
             if (args.Length == 0) //Traverse folder structure to add posts and thus blogs to DB
@@ -147,55 +166,23 @@ namespace URLNotesGrabberCORE
                 switch (args[0])
                 {
                     case "-?":
-                        Console.WriteLine("\t Parse .txt files to find blogs");
-
-                        Console.WriteLine("-?\t Usage help");
-
-                        Console.WriteLine("-parse\t Parse .txt files with specified blogname");
-
-                        Console.WriteLine("-test\t Calls API for given blogname and postID");
-
-                        Console.WriteLine("-posts\t For each Post in DB, write blogname to file");
-
-                        Console.WriteLine("-blogs\t For each Blog in DB, write blogname to file");
-
-                        Console.WriteLine("-collect\t For each Post in DB, hit API to collect Notes. Optional datetime parameter to filter by NotesGatheredDateTime");
-
-                        Console.WriteLine("-blogsR\t For each Note that is a REPLY, write blogname to file ");
-
-                        Console.WriteLine("-blogsO\t For each Blog in DB, write blogname to file, but limit via a passed start and stop range ");
-
-                        Console.WriteLine("-replies\t Fetch and update missing reply text for all replies in database");
-
-                        Console.WriteLine("-likes\t Fetch likes: initial backfill for new blogs, incremental refresh for blogs past cooldown. Optional blog name forces single-blog run.");
-
-                        Console.WriteLine("-force\t (with -likes) Ignore cooldown and refresh every fully-backfilled blog");
-
-                        Console.WriteLine("-urldump\t Scan all posts' text columns and extract suspected URLs to configured file");
-
-                        Console.WriteLine("-api3\t Use TumblrApi3 settings from appsettings.json");
-
-                        Console.WriteLine("-api4\t Use TumblrApi4 settings from appsettings.json");
-
-                        Console.WriteLine("-start [blogname]\t Start traversal alphabetically at this blog name");
-
-                        Console.WriteLine("-api [section]\t Use a specific API settings section from appsettings.json (e.g. TumblrApi3)");
-
-                        Console.WriteLine("-ingest [blogname]\t Ingest Tumblr .txt exports from appSettings:PathTTRoot into TL.db (all blogs, or single blog if name given)");
-
-                        Console.WriteLine("-output\t Export posts from TL.db back to .txt files in each blog's TTFolderPath");
-
-                        Console.WriteLine("-correct [bakPath]\t Dry-run: report multi-line field updates available from a BAK directory");
-
-                        Console.WriteLine("-correct -apply [bakPath]\t Apply BAK-file corrections to matching posts (prompts yes/no)");
-
-                        Console.WriteLine("-updatepaths [rootPath]\t Read .tumblr/.tmblrpriv metadata from <root>\\Index and set Blogs.TTFolderPath");
-
-                        Console.WriteLine("-importposts [path-to-posts.db]\t One-time migration: copy legacy ThreeTxtFileHelper posts.db rows into TL.db");
-
+                    case "-h":
+                    case "--help":
+                        PrintHelp();
                         break;
-                    
-                    case "-parse":
+
+                    case "-V":
+                    case "--version":
+                        Console.WriteLine(System.Reflection.Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "unknown");
+                        break;
+
+                    case "--parse":
+                        if (args.Length < 2)
+                        {
+                            Console.WriteLine("Usage: --parse <blogname>");
+                            exitCode = 2;
+                            break;
+                        }
                         string blogNameToParse = args[1];
                         int postsAdded = 0;
                         try
@@ -210,29 +197,31 @@ namespace URLNotesGrabberCORE
                         Console.WriteLine($"Total posts added: {postsAdded}");
                         break;
                     
-                    case "-test":
+                    case "--test":
                         Console.WriteLine("Test command not implemented");
                         break;
 
-                    case "-post":
+                    case "--post":
                         TraverseDirectoryForCorruption(settings.GetValue<string>("PathInput"), settings.GetValue<string>("PathOutputBlogs"), contains);
                         break;
 
-                    case "-posts": //write post's blogs to file
+                    case "--posts": //write post's blogs to file
                         WritePostBlogsToFile(settings.GetValue<string>("PathOutputPosts"));
                         break;
 
-                    case "-blogs": //write blogs to file
+                    case "--blogs": //write blogs to file
                         WriteBlogsToFile(settings.GetValue<string>("PathOutputBlogs"));
                         break;
 
-                    case "-collect": //collect notes from all posts
+                    case "--collect": //collect notes from all posts
                         bool withoutNotesOnly = true;
                         DateTime? beforeDate = DateTime.Now;
+                        bool explicitDateSupplied = false;
 
                         if (args.Length < 2)
                         {
                             Console.WriteLine("--Expected WITHOUTNOTESONLY (0, 1) [OPTIONAL: BEFOREDATE]--");
+                            exitCode = 2;
                             break;
                         }
 
@@ -259,26 +248,50 @@ namespace URLNotesGrabberCORE
                             if (DateTime.TryParse(args[2], out DateTime parsedDate))
                             {
                                 beforeDate = parsedDate;
+                                explicitDateSupplied = true;
                                 Console.WriteLine($"Filter: Collecting notes for posts with NotesGatheredDateTime < {beforeDate}");
                             }
                             else
                             {
                                 Console.WriteLine($"ERROR: Invalid date format '{args[2]}'");
+                                exitCode = 2;
                                 break;
                             }
                         }
 
-                        CollectNotes(settings.GetValue<string>("PathOutput"), withoutNotesOnly, beforeDate).GetAwaiter().GetResult();
+                        // Mode 0 (full re-check) with no explicit date is a *managed* run: freeze the cutoff and
+                        // persist it so an interrupted run resumes against the same cutoff and a completed run stops
+                        // instead of restarting. Mode 1 and explicit-date runs keep their existing behavior.
+                        bool managedCollectRun = false;
+                        if (!withoutNotesOnly && !explicitDateSupplied)
+                        {
+                            DataAccess.EnsureCollectRunStateTableExists();
+                            var runState = DataAccess.GetCollectRunState();
+                            if (runState != null && !runState.Value.complete)
+                            {
+                                beforeDate = DateTimeOffset.FromUnixTimeSeconds(runState.Value.cutoff).LocalDateTime;
+                                Console.WriteLine($"Resuming interrupted full re-check (cutoff = {beforeDate})");
+                            }
+                            else
+                            {
+                                beforeDate = DateTime.Now;
+                                DataAccess.BeginCollectRun(new DateTimeOffset(beforeDate.Value).ToUnixTimeSeconds());
+                                Console.WriteLine($"Starting new full re-check run (cutoff = {beforeDate})");
+                            }
+                            managedCollectRun = true;
+                        }
+
+                        CollectNotes(settings.GetValue<string>("PathOutput"), withoutNotesOnly, beforeDate, managedCollectRun).GetAwaiter().GetResult();
                         break;
 
-                    case "-blogsR": //collect notes from all posts
+                    case "--blogsR": //collect notes from all posts
                         WriteBlogsToFile(settings.GetValue<string>("PathOutputBlogs"), true);
                         break;
 
-                    case "-blogsO": //collect notes from all posts
+                    case "--blogsO": //collect notes from all posts
                         int from = 1, to = 999999, top = 100;
 
-                        if (args[1] is not null && args[2] is not null && args[3] is not null)
+                        if (args.Length >= 4 && args[1] is not null && args[2] is not null && args[3] is not null)
                         {
                             from = int.Parse(args[1]);
                             to = int.Parse(args[2]);
@@ -287,14 +300,16 @@ namespace URLNotesGrabberCORE
                         else
                         {
                             Console.WriteLine("--Expected FROM TO--");
+                            exitCode = 2;
+                            break;
                         }
                         WriteBlogsToFile(settings.GetValue<string>("PathOutputBlogs"), false, from, to, top);
                         break;
 
-                    case "-bop": //collect notes from all posts
+                    case "--bop": //collect notes from all posts
                         from = 1; to = 999999; top = 100;
 
-                        if (args[1] is not null && args[2] is not null && args[3] is not null)
+                        if (args.Length >= 4 && args[1] is not null && args[2] is not null && args[3] is not null)
                         {
                             from = int.Parse(args[1]);
                             to = int.Parse(args[2]);
@@ -303,62 +318,70 @@ namespace URLNotesGrabberCORE
                         else
                         {
                             Console.WriteLine("--Expected FROM TO--");
+                            exitCode = 2;
+                            break;
                         }
                         WriteBlogsToFileAll(settings.GetValue<string>("PathOutputBlogs"), false, from, to, top);
                         break;
 
-                    case "-replies": //update reply text
+                    case "--replies": //update reply text
                         CollectMissingReplyText().GetAwaiter().GetResult();
                         break;
 
-                    case "-likes":
+                    case "--likes":
                         string likeBlog = args.Length > 1 ? args[1] : null;
                         int cooldownDays = settings.GetValue("LikesRefreshCooldownDays", 7);
                         CollectLikes(likeBlog, contains, cooldownDays, forceIgnoreCooldown).GetAwaiter().GetResult();
                         break;
 
-                    case "-urldump":
+                    case "--urldump":
                         DumpUrls(settings.GetValue<string>("PathOutputUrls"));
                         break;
 
-                    case "-ingest":
-                        IngestMode.Run(config, args.Skip(1).ToArray());
+                    case "--ingest":
+                        exitCode = IngestMode.Run(config, args.Skip(1).ToArray());
                         break;
 
-                    case "-output":
-                        OutputMode.Run(config);
+                    case "--output":
+                        exitCode = OutputMode.Run(config);
                         break;
 
-                    case "-correct":
+                    case "--revert":
+                        exitCode = RevertMode.Run(config, args.Length > 1 ? args[1] : null);
+                        break;
+
+                    case "--correct":
                     {
-                        bool applyChanges = args.Skip(1).Any(a => string.Equals(a, "-apply", StringComparison.OrdinalIgnoreCase) || string.Equals(a, "--apply", StringComparison.OrdinalIgnoreCase));
+                        bool applyChanges = args.Skip(1).Any(a => string.Equals(a, "--apply", StringComparison.OrdinalIgnoreCase));
                         var correctArgs = args.Skip(1)
-                            .Where(a => !string.Equals(a, "-apply", StringComparison.OrdinalIgnoreCase) && !string.Equals(a, "--apply", StringComparison.OrdinalIgnoreCase))
+                            .Where(a => !string.Equals(a, "--apply", StringComparison.OrdinalIgnoreCase))
                             .ToArray();
-                        CorrectMode.Run(config, correctArgs, applyChanges);
+                        exitCode = CorrectMode.Run(config, correctArgs, applyChanges);
                         break;
                     }
 
-                    case "-updatepaths":
+                    case "--updatepaths":
                     {
                         string rootPath = args.Length > 1 ? args[1] : (settings.GetValue<string>("PathTTRoot") ?? settings.GetValue<string>("PathInput") ?? string.Empty);
-                        UpdateBlogPathsRunner.Run(rootPath);
+                        exitCode = UpdateBlogPathsRunner.Run(rootPath);
                         break;
                     }
 
-                    case "-importposts":
+                    case "--importposts":
                     {
                         if (args.Length < 2)
                         {
-                            Console.WriteLine("Usage: -importposts <path-to-legacy-posts.db>");
+                            Console.WriteLine("Usage: --importposts <path-to-legacy-posts.db>");
+                            exitCode = 2;
                             break;
                         }
-                        LegacyPostsDbImporter.Run(args[1]);
+                        exitCode = LegacyPostsDbImporter.Run(args[1]);
                         break;
                     }
 
                     default:
                         Console.WriteLine("** Unknown Command ** " + args[0]);
+                        exitCode = 2;
                         break;
                 }
             }
@@ -367,6 +390,69 @@ namespace URLNotesGrabberCORE
 
             System.Console.WriteLine("<fin>:/");
             //System.Console.ReadKey();
+            return exitCode;
+        }
+
+        static void PrintHelp()
+        {
+            Console.WriteLine("\t Parse .txt files to find blogs");
+
+            Console.WriteLine("-?, -h, --help\t Usage help");
+
+            Console.WriteLine("-V, --version\t Print the application version");
+
+            Console.WriteLine("--\t End of options: treat every following token as a literal operand");
+
+            Console.WriteLine("--parse\t Parse .txt files with specified blogname");
+
+            Console.WriteLine("--test\t Calls API for given blogname and postID");
+
+            Console.WriteLine("--post\t Traverse the input directory tree checking .txt files for corruption");
+
+            Console.WriteLine("--posts\t For each Post in DB, write blogname to file");
+
+            Console.WriteLine("--blogs\t For each Blog in DB, write blogname to file");
+
+            Console.WriteLine("--collect [0|1] [datetime]\t Collect Notes from API. 1=only posts without notes. 0=full re-check of all posts: a single resumable pass (interrupt & relaunch to resume; stops when complete, retrigger for a new pass). Optional datetime overrides the cutoff and runs as a one-off (bypasses resume tracking).");
+
+            Console.WriteLine("--blogsR\t For each Note that is a REPLY, write blogname to file ");
+
+            Console.WriteLine("--blogsO\t For each Blog in DB, write blogname to file, but limit via a passed start and stop range ");
+
+            Console.WriteLine("--bop [from] [to] [top]\t Write ALL blog names to file, limited by FROM TO TOP range arguments");
+
+            Console.WriteLine("--replies\t Fetch and update missing reply text for all replies in database");
+
+            Console.WriteLine("--likes\t Fetch likes: initial backfill for new blogs, incremental refresh for blogs past cooldown. Optional blog name forces single-blog run.");
+
+            Console.WriteLine("--force\t (with --likes) Ignore cooldown and refresh every fully-backfilled blog");
+
+            Console.WriteLine("--urldump\t Scan all posts' text columns and extract suspected URLs to configured file");
+
+            Console.WriteLine("--api3\t Use TumblrApi3 settings from appsettings.json");
+
+            Console.WriteLine("--api4\t Use TumblrApi4 settings from appsettings.json");
+
+            Console.WriteLine("--start [blogname]\t Start traversal alphabetically at this blog name");
+
+            Console.WriteLine("--api [section]\t Use a specific API settings section from appsettings.json (e.g. TumblrApi3)");
+
+            Console.WriteLine("--ingest [blogname]\t Ingest Tumblr .txt exports from appSettings:PathTTRoot into TL.db (all blogs, or single blog if name given)");
+
+            Console.WriteLine("--output\t Export posts from TL.db back to .txt files in each blog's TTFolderPath");
+
+            Console.WriteLine("--revert [blogname]\t Recursively scan the PathInput tree and restore *.bak back to *.txt (current .txt saved as next-free .bkN); optional blogname filters by path substring");
+
+            Console.WriteLine("--correct [bakPath]\t Dry-run: report multi-line field updates available from a BAK directory");
+
+            Console.WriteLine("--correct --apply [bakPath]\t Apply BAK-file corrections to matching posts (prompts yes/no)");
+
+            Console.WriteLine("--updatepaths [rootPath]\t Read .tumblr/.tmblrpriv metadata from <root>\\Index and set Blogs.TTFolderPath");
+
+            Console.WriteLine("--importposts [path-to-posts.db]\t One-time migration: copy legacy ThreeTxtFileHelper posts.db rows into TL.db");
+
+            Console.WriteLine();
+            Console.WriteLine("Exit status: 0 = success; 1 = unexpected error; 2 = usage error (unknown command or bad/missing arguments)");
         }
 
         static void WritePostBlogsToFile(string outPath)
@@ -1182,10 +1268,15 @@ if (shouldInsert)
             return "UNKNOWN";
         }
 
-        static async Task CollectNotes(string outPath, bool withoutNotesOnly = true, DateTime? beforeDate = null)
+        static async Task CollectNotes(string outPath, bool withoutNotesOnly = true, DateTime? beforeDate = null, bool managedRun = false)
         {
             List<Tuple<string, long, long, long>> posts = DataAccess.GetPosts(withoutNotesOnly, beforeDate);
 
+            // Posts attempted (with a definitive, non-throttle result) during *this* process. Guarantees a single
+            // attempt pass: once every remaining post has been attempted, the loop stops instead of spinning on a
+            // post that keeps returning FAILURE/UNKNOWN. Successful/NotFound posts drop out via the DB filter anyway.
+            HashSet<(string, long)> attempted = new HashSet<(string, long)>();
+
             RateLimiter limiter = new SlidingWindowRateLimiter(new SlidingWindowRateLimiterOptions
             {
                 PermitLimit = 300,
@@ -1202,9 +1293,17 @@ if (shouldInsert)
                 {
                     while (posts.Count > 0)
                     {
+                        // First post not yet attempted this process. If all remaining have been attempted, the pass
+                        // is done (the stragglers returned FAILURE/UNKNOWN) — stop rather than loop forever.
+                        var post = posts.FirstOrDefault(p => !attempted.Contains((p.Item1, p.Item2)));
+                        if (post == null)
+                        {
+                            Console.WriteLine("All remaining posts have been attempted this run; ending pass.");
+                            break;
+                        }
+
                         ApiKeyPool.SleepUntilAnyAvailable(30);
 
-                        var post = posts[0]; // Process the first post in the list
                         string status;
 
                         using RateLimitLease lease = limiter.AttemptAcquire(1);
@@ -1216,20 +1315,31 @@ if (shouldInsert)
                         else
                         {
                             Console.WriteLine("!@@@@@@@ - Rate Limited Exceeded: No Lease Available");
-                            return;
+                            return; // throttle: abort without completing the run so a later launch resumes
                         }
 
                         if (status == "Success")
                         {
+                            attempted.Add((post.Item1, post.Item2));
                             DataAccess.UpdatePostMarkNotesCollected(post.Item1, post.Item2);
                         }
                         else if (status == "NotFound")
                         {
+                            attempted.Add((post.Item1, post.Item2));
                             Console.WriteLine("GrabNotes Result: NotFound");
                             DataAccess.UpdatePostMarkNotFound(post.Item1, post.Item2);
                         }
+                        else if (status == "TooManyRequests")
+                        {
+                            // Throttle, not a real per-post failure: don't consume this post's single attempt.
+                            // Abort the pass without completing so a later launch resumes against the same cutoff.
+                            Console.WriteLine("GrabNotes Result: TooManyRequests - pausing run; relaunch to resume.");
+                            return;
+                        }
                         else
                         {
+                            // FAILURE / UNKNOWN: count as attempted so the pass can finish instead of retrying forever.
+                            attempted.Add((post.Item1, post.Item2));
                             Console.WriteLine("GrabNotes Result: " + status);
                         }
 
@@ -1237,6 +1347,13 @@ if (shouldInsert)
                         posts = DataAccess.GetPosts(withoutNotesOnly, beforeDate);
                     }
                 }
+
+                // Reached only when the pass finished naturally (worklist drained or all stragglers attempted).
+                if (managedRun)
+                {
+                    DataAccess.CompleteCollectRun();
+                    Console.WriteLine("Full re-check run complete.");
+                }
             }
             catch (Exception ex)
             {

URLNotesGrabberCORE/Properties/launchSettings.json

@@ -2,7 +2,7 @@
   "profiles": {
     "URLNotesGrabberCORE": {
       "commandName": "Project",
-      "commandLineArgs": "-collect 1 -api4"
+      "commandLineArgs": "--collect 1 --api4"
     }
   }
 }

URLNotesGrabberCORE/RevertMode.cs

@@ -0,0 +1,110 @@
+using Microsoft.Extensions.Configuration;
+
+namespace URLNotesGrabberCORE
+{
+    // Inverse of OutputMode. Recursively walks the PathInput tree (the same directory tree the
+    // no-parameter run uses) and restores every *.bak back to its *.txt, first preserving the
+    // current *.txt as the next-free *.bkN. Consumes the *.bak (File.Move). Filesystem-only;
+    // does not read the DB. An optional blogname argument filters by path substring.
+    public static class RevertMode
+    {
+        public static int Run(IConfiguration config, string? blogFilter = null)
+        {
+            string? root = config["appSettings:PathInput"];
+            if (string.IsNullOrWhiteSpace(root) || !Directory.Exists(root))
+            {
+                Console.WriteLine($"PathInput is not set or does not exist: '{root}'. Nothing to revert.");
+                return 0;
+            }
+
+            Console.WriteLine($"Searching for .bak files under: {root}");
+
+            // Recursively collect every *.bak, optionally filtered by path substring (blogname).
+            var bakFiles = EnumerateBakFiles(root)
+                .Where(f => string.IsNullOrWhiteSpace(blogFilter)
+                            || f.IndexOf(blogFilter, StringComparison.OrdinalIgnoreCase) >= 0)
+                .ToList();
+
+            if (bakFiles.Count == 0)
+            {
+                Console.WriteLine("No .bak files found. Nothing to revert.");
+                return 0;
+            }
+
+            Console.Write($"WARNING: This will restore {bakFiles.Count} .bak file(s) over their .txt files. " +
+                          $"Current .txt files are preserved as the next-free .bkN. Continue? (yes/no): ");
+            string? response = Console.ReadLine();
+            if (string.IsNullOrWhiteSpace(response) || !response.Equals("yes", StringComparison.OrdinalIgnoreCase))
+            {
+                Console.WriteLine("Operation cancelled.");
+                return 0;
+            }
+
+            int restored = 0, backedUp = 0;
+            foreach (var bakFile in bakFiles)
+            {
+                try
+                {
+                    string txtPath = Path.ChangeExtension(bakFile, ".txt");
+
+                    if (File.Exists(txtPath))
+                    {
+                        string bkPath = NextFreeBkPath(txtPath);
+                        File.Move(txtPath, bkPath);
+                        backedUp++;
+                        Console.WriteLine($"  Backed up {Path.GetFileName(txtPath)} -> {Path.GetFileName(bkPath)}");
+                    }
+
+                    File.Move(bakFile, txtPath);
+                    restored++;
+                    Console.WriteLine($"  Restored {bakFile} -> {Path.GetFileName(txtPath)}");
+                }
+                catch (Exception ex)
+                {
+                    Console.WriteLine($"  Error reverting {bakFile}: {ex.Message}");
+                }
+            }
+
+            Console.WriteLine($"\nRevert mode complete. Restored {restored} file(s); backed up {backedUp} current .txt file(s).");
+            return 0;
+        }
+
+        // Recursively yields every *.bak path under root. Per-directory try/catch so an
+        // inaccessible folder doesn't abort the whole walk (mirrors TraverseDirectory).
+        private static IEnumerable<string> EnumerateBakFiles(string path)
+        {
+            string[] subDirs;
+            try { subDirs = Directory.GetDirectories(path); }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"  Skipping '{path}': {ex.Message}");
+                yield break;
+            }
+
+            foreach (var dir in subDirs)
+                foreach (var bak in EnumerateBakFiles(dir))
+                    yield return bak;
+
+            string[] bakFiles;
+            try { bakFiles = Directory.GetFiles(path, "*.bak"); }
+            catch (Exception ex)
+            {
+                Console.WriteLine($"  Skipping files in '{path}': {ex.Message}");
+                yield break;
+            }
+
+            foreach (var bak in bakFiles)
+                yield return bak;
+        }
+
+        // Returns the lowest unused .bkN path for a given .txt file (.bk1, .bk2, ...).
+        private static string NextFreeBkPath(string txtFile)
+        {
+            for (int n = 1; ; n++)
+            {
+                string candidate = Path.ChangeExtension(txtFile, $".bk{n}");
+                if (!File.Exists(candidate)) return candidate;
+            }
+        }
+    }
+}

run_500_times.bat

@@ -1,52 +0,0 @@
-@echo off
-REM Batch file to run URLNotesGrabberCORE 500 times in a loop
-
-setlocal enabledelayedexpansion
-
-REM Set the path to the executable
-REM Update this path if your executable is in a different location
-set APP_PATH=URLNotesGrabberCORE.exe
-
-REM Check if the executable exists
-if not exist "%APP_PATH%" (
-    echo Error: %APP_PATH% not found in the current directory.
-    echo Please ensure the executable is in the same directory as this batch file,
-    echo or update the APP_PATH variable with the correct path.
-    pause
-    exit /b 1
-)
-
-REM Loop counter
-set ITERATIONS=500
-set COUNTER=0
-
-echo Starting to run %APP_PATH% %ITERATIONS% times...
-echo.
-
-:LOOP
-set /a COUNTER+=1
-echo [%COUNTER%/%ITERATIONS%] Running iteration %COUNTER%...
-echo Started at: %date% %time%
-
-REM Run the application with -replies option
-call "%APP_PATH%" -replies
-
-REM Check if the application ran successfully
-if errorlevel 1 (
-    echo Warning: Application exited with error code !ERRORLEVEL! on iteration %COUNTER%
-) else (
-    echo Iteration %COUNTER% completed successfully.
-)
-
-echo Completed at: %date% %time%
-echo.
-
-REM Check if we've reached 500 iterations
-if %COUNTER% lss %ITERATIONS% (
-    goto LOOP
-)
-
-echo.
-echo Completed all %ITERATIONS% iterations!
-echo.
-pause

verify-db-schema.sql

@@ -0,0 +1,199 @@
+-- ============================================================================
+-- verify-db-schema.sql
+--
+-- Purpose: Verify that a TL.db (e.g. a restored backup) has every column the
+--          current URLNotesGrabberCORE code expects. The app has NO startup
+--          migration: missing columns only get added when specific modes run,
+--          and a referenced-but-missing column causes a "no such column" crash.
+--
+-- How to use (DB Browser for SQLite):
+--   1. File > Open Database  ->  pick the restored backup.
+--   2. Execute SQL tab. Run SECTION 1 (it is read-only).
+--        * Zero rows from every query  = schema is fully aligned, you're done.
+--        * Rows in "MISSING COLUMNS"    = copy the run_this_to_fix text.
+--   3. If columns are missing: KEEP A COPY OF THE BACKUP FIRST, then go to
+--      SECTION 2, uncomment ONLY the ALTER lines that match the report, and run.
+--   4. Re-run SECTION 1 to confirm zero rows.
+--
+-- This script never UPDATEs/DELETEs/DROPs. In particular it deliberately does
+-- NOT replicate the likes-reset that the app's -likes migration performs
+-- (DataAccess.cs:375), so existing likes high-water marks are preserved.
+-- ============================================================================
+
+
+-- ============================================================================
+-- SECTION 1  --  VERIFICATION (read-only)
+-- ============================================================================
+
+-- Expected schema for the current code version.
+-- alter_stmt is a runnable ALTER for additively-fixable columns; for base
+-- columns it is a 'MANUAL REVIEW' note (a missing base column means the backup
+-- predates the table's creation or is damaged -- do not blindly auto-add).
+WITH expected(tbl, col, alter_stmt) AS (
+  VALUES
+    -- Posts (base columns: manual review if missing)
+    ('Posts','BlogName',              'MANUAL REVIEW - base/PK column missing'),
+    ('Posts','PostID',                'MANUAL REVIEW - base/PK column missing'),
+    ('Posts','HasNotesGathered',      'MANUAL REVIEW - base column missing'),
+    ('Posts','reblogURL',             'MANUAL REVIEW - base column missing'),
+    ('Posts','NotFound',              'MANUAL REVIEW - base column missing'),
+    ('Posts','PostDate',              'MANUAL REVIEW - base column missing'),
+    ('Posts','NotesGatheredDateTime', 'MANUAL REVIEW - base column missing'),
+    ('Posts','HasImage',              'MANUAL REVIEW - base column missing'),
+    ('Posts','PostURL',               'MANUAL REVIEW - base column missing'),
+    ('Posts','Slug',                  'MANUAL REVIEW - base column missing'),
+    ('Posts','ReblogKey',             'MANUAL REVIEW - base column missing'),
+    ('Posts','ReblogName',            'MANUAL REVIEW - base column missing'),
+    ('Posts','Summary',               'MANUAL REVIEW - base column missing'),
+    ('Posts','Quote',                 'MANUAL REVIEW - base column missing'),
+    ('Posts','Body',                  'MANUAL REVIEW - base column missing'),
+    ('Posts','Tags',                  'MANUAL REVIEW - base column missing'),
+    ('Posts','Link',                  'MANUAL REVIEW - base column missing'),
+    ('Posts','PhotoURL',              'MANUAL REVIEW - base column missing'),
+    ('Posts','PhotoCaption',          'MANUAL REVIEW - base column missing'),
+    ('Posts','DownloadedFiles',       'MANUAL REVIEW - base column missing'),
+    ('Posts','AudioCaption',          'MANUAL REVIEW - base column missing'),
+    ('Posts','Question',              'MANUAL REVIEW - base column missing'),
+    ('Posts','Answer',                'MANUAL REVIEW - base column missing'),
+    ('Posts','Title',                 'MANUAL REVIEW - base column missing'),
+    ('Posts','ByLikes',               'MANUAL REVIEW - base column missing'),
+    ('Posts','RootBlogName',          'MANUAL REVIEW - base column missing'),
+    ('Posts','RootURL',               'MANUAL REVIEW - base column missing'),
+    ('Posts','DateModified',          'MANUAL REVIEW - base column missing'),
+    ('Posts','DateCreated',           'MANUAL REVIEW - base column missing'),
+    -- Posts (additive migration column, auto-fixable)
+    ('Posts','PostType',              'ALTER TABLE Posts ADD COLUMN PostType TEXT;'),
+
+    -- Blogs (base columns: manual review if missing)
+    ('Blogs','BlogName',              'MANUAL REVIEW - base/PK column missing'),
+    ('Blogs','HasBeenOutput',         'MANUAL REVIEW - base column missing'),
+    ('Blogs','IsActive',              'MANUAL REVIEW - base column missing'),
+    ('Blogs','DateAdded',             'MANUAL REVIEW - base column missing'),
+    ('Blogs','ByLikes',               'MANUAL REVIEW - base column missing'),
+    ('Blogs','DateModified',          'MANUAL REVIEW - base column missing'),
+    ('Blogs','DateCreated',           'MANUAL REVIEW - base column missing'),
+    -- Blogs (additive migration columns, auto-fixable)
+    ('Blogs','LikesPulled',           'ALTER TABLE Blogs ADD COLUMN LikesPulled INTEGER DEFAULT 0;'),
+    ('Blogs','LikesCursor',           'ALTER TABLE Blogs ADD COLUMN LikesCursor INTEGER DEFAULT 0;'),
+    ('Blogs','LikesNewestTimestamp',  'ALTER TABLE Blogs ADD COLUMN LikesNewestTimestamp INTEGER DEFAULT 0;'),
+    ('Blogs','LikesLastRefreshed',    'ALTER TABLE Blogs ADD COLUMN LikesLastRefreshed INTEGER DEFAULT 0;'),
+    ('Blogs','LikesLastNewCount',     'ALTER TABLE Blogs ADD COLUMN LikesLastNewCount INTEGER DEFAULT 0;'),
+    ('Blogs','TTFolderPath',          'ALTER TABLE Blogs ADD COLUMN TTFolderPath TEXT;'),
+
+    -- Notes (base columns: manual review if missing)
+    ('Notes','RootBlogName',          'MANUAL REVIEW - base/PK column missing'),
+    ('Notes','PostID',                'MANUAL REVIEW - base/PK column missing'),
+    ('Notes','NoteBlogName',          'MANUAL REVIEW - base/PK column missing'),
+    ('Notes','TimeStamp',             'MANUAL REVIEW - base/PK column missing'),
+    ('Notes','Type',                  'MANUAL REVIEW - base/PK column missing'),
+    ('Notes','DatetimeCrawled',       'MANUAL REVIEW - base column missing'),
+    ('Notes','DateModified',          'MANUAL REVIEW - base column missing'),
+    ('Notes','DateCreated',           'MANUAL REVIEW - base column missing'),
+    -- Notes (additive migration column, auto-fixable)
+    ('Notes','replyText',             'ALTER TABLE Notes ADD COLUMN replyText TEXT DEFAULT ''.'';'),
+
+    -- DailyAPICount (base columns)
+    ('DailyAPICount','Date',          'MANUAL REVIEW - base/PK column missing'),
+    ('DailyAPICount','APICount',      'MANUAL REVIEW - base column missing'),
+
+    -- ApiKeyPoolState (created at runtime by EnsureApiKeyPoolTables; auto-fixable by re-running app, but safe to add)
+    ('ApiKeyPoolState','KeyName',     'MANUAL REVIEW - run app once to auto-create ApiKeyPool tables'),
+    ('ApiKeyPoolState','RetryUntil',  'MANUAL REVIEW - run app once to auto-create ApiKeyPool tables'),
+    ('ApiKeyPoolMeta','Id',           'MANUAL REVIEW - run app once to auto-create ApiKeyPool tables'),
+    ('ApiKeyPoolMeta','LastIndex',    'MANUAL REVIEW - run app once to auto-create ApiKeyPool tables')
+),
+actual(tbl, col) AS (
+  SELECT 'Posts',           name FROM pragma_table_info('Posts')
+  UNION ALL SELECT 'Blogs',           name FROM pragma_table_info('Blogs')
+  UNION ALL SELECT 'Notes',           name FROM pragma_table_info('Notes')
+  UNION ALL SELECT 'DailyAPICount',   name FROM pragma_table_info('DailyAPICount')
+  UNION ALL SELECT 'ApiKeyPoolState', name FROM pragma_table_info('ApiKeyPoolState')
+  UNION ALL SELECT 'ApiKeyPoolMeta',  name FROM pragma_table_info('ApiKeyPoolMeta')
+)
+
+-- 1a. MISSING COLUMNS: columns the code needs that the DB does not have.
+--     Zero rows = good. Otherwise copy run_this_to_fix into SECTION 2.
+SELECT
+  e.tbl              AS table_name,
+  e.col              AS missing_column,
+  e.alter_stmt       AS run_this_to_fix
+FROM expected e
+LEFT JOIN actual a
+  ON a.tbl = e.tbl AND lower(a.col) = lower(e.col)
+WHERE a.col IS NULL
+ORDER BY (e.alter_stmt LIKE 'ALTER%') DESC, e.tbl, e.col;
+
+
+-- 1b. MISSING TABLES: expected tables that don't exist at all in this DB.
+--     Zero rows = good.
+WITH expected_tables(tbl) AS (
+  VALUES ('Posts'),('Blogs'),('Notes'),('DailyAPICount'),
+         ('ApiKeyPoolState'),('ApiKeyPoolMeta')
+)
+SELECT et.tbl AS missing_table
+FROM expected_tables et
+WHERE NOT EXISTS (
+  SELECT 1 FROM sqlite_master
+  WHERE type = 'table' AND lower(name) = lower(et.tbl)
+)
+ORDER BY et.tbl;
+
+
+-- 1c. EXTRA / UNEXPECTED COLUMNS: present in the DB but not in the expected
+--     list above. Informational only -- e.g. a NEWER backup, or a column this
+--     script's expected-list hasn't been updated for. Not an error by itself.
+WITH expected(tbl, col) AS (
+  VALUES
+    ('Posts','BlogName'),('Posts','PostID'),('Posts','HasNotesGathered'),('Posts','reblogURL'),
+    ('Posts','NotFound'),('Posts','PostDate'),('Posts','NotesGatheredDateTime'),('Posts','HasImage'),
+    ('Posts','PostURL'),('Posts','Slug'),('Posts','ReblogKey'),('Posts','ReblogName'),('Posts','Summary'),
+    ('Posts','Quote'),('Posts','Body'),('Posts','Tags'),('Posts','Link'),('Posts','PhotoURL'),
+    ('Posts','PhotoCaption'),('Posts','DownloadedFiles'),('Posts','AudioCaption'),('Posts','Question'),
+    ('Posts','Answer'),('Posts','Title'),('Posts','ByLikes'),('Posts','RootBlogName'),('Posts','RootURL'),
+    ('Posts','DateModified'),('Posts','DateCreated'),('Posts','PostType'),
+    ('Blogs','BlogName'),('Blogs','HasBeenOutput'),('Blogs','IsActive'),('Blogs','DateAdded'),
+    ('Blogs','ByLikes'),('Blogs','DateModified'),('Blogs','DateCreated'),('Blogs','LikesPulled'),
+    ('Blogs','LikesCursor'),('Blogs','LikesNewestTimestamp'),('Blogs','LikesLastRefreshed'),
+    ('Blogs','LikesLastNewCount'),('Blogs','TTFolderPath'),
+    ('Notes','RootBlogName'),('Notes','PostID'),('Notes','NoteBlogName'),('Notes','TimeStamp'),
+    ('Notes','Type'),('Notes','DatetimeCrawled'),('Notes','DateModified'),('Notes','DateCreated'),
+    ('Notes','replyText'),
+    ('DailyAPICount','Date'),('DailyAPICount','APICount'),
+    ('ApiKeyPoolState','KeyName'),('ApiKeyPoolState','RetryUntil'),
+    ('ApiKeyPoolMeta','Id'),('ApiKeyPoolMeta','LastIndex')
+),
+actual(tbl, col) AS (
+  SELECT 'Posts',           name FROM pragma_table_info('Posts')
+  UNION ALL SELECT 'Blogs',           name FROM pragma_table_info('Blogs')
+  UNION ALL SELECT 'Notes',           name FROM pragma_table_info('Notes')
+  UNION ALL SELECT 'DailyAPICount',   name FROM pragma_table_info('DailyAPICount')
+  UNION ALL SELECT 'ApiKeyPoolState', name FROM pragma_table_info('ApiKeyPoolState')
+  UNION ALL SELECT 'ApiKeyPoolMeta',  name FROM pragma_table_info('ApiKeyPoolMeta')
+)
+SELECT a.tbl AS table_name, a.col AS unexpected_column
+FROM actual a
+LEFT JOIN expected e
+  ON e.tbl = a.tbl AND lower(e.col) = lower(a.col)
+WHERE e.col IS NULL
+ORDER BY a.tbl, a.col;
+
+
+-- ============================================================================
+-- SECTION 2  --  FIX (opt-in, additive only)
+--
+-- Run ONLY the lines that query 1a flagged with an ALTER statement.
+-- KEEP A COPY OF THE BACKUP FIRST. SQLite has no "ADD COLUMN IF NOT EXISTS",
+-- so running an ALTER for a column that already exists throws a harmless
+-- "duplicate column name" error and changes nothing -- just run the flagged
+-- subset. These are the 8 additive migration columns and nothing else; the
+-- likes high-water-mark reset is intentionally NOT included.
+-- ============================================================================
+
+-- ALTER TABLE Posts ADD COLUMN PostType TEXT;
+-- ALTER TABLE Blogs ADD COLUMN LikesPulled INTEGER DEFAULT 0;
+-- ALTER TABLE Blogs ADD COLUMN LikesCursor INTEGER DEFAULT 0;
+-- ALTER TABLE Blogs ADD COLUMN LikesNewestTimestamp INTEGER DEFAULT 0;
+-- ALTER TABLE Blogs ADD COLUMN LikesLastRefreshed INTEGER DEFAULT 0;
+-- ALTER TABLE Blogs ADD COLUMN LikesLastNewCount INTEGER DEFAULT 0;
+-- ALTER TABLE Blogs ADD COLUMN TTFolderPath TEXT;
+-- ALTER TABLE Notes ADD COLUMN replyText TEXT DEFAULT '.';