@m13v/s4l 1.7.5-rc.9 → 1.7.5

package/mcp/dist/index.js

@@ -20,8 +20,9 @@ import os from "node:os";
 import path from "node:path";
 import fs from "node:fs";
 import { repoDir, runPython, run, readPlan, writePlan, planPath, } from "./repo.js";
-import { applySetup, resolveProject, hasReadyProject, personaReady, listManagedProjectStatus, listProjectSettings, ensureShortLinksDefault, ensurePersonaProject, findPersonaProject, REQUIRED_FIELDS, RECOMMENDED_FIELDS, configPath, normalizeStringList, } from "./setup.js";
+import { applySetup, resolveProject, hasReadyProject, personaReady, listManagedProjectStatus, listProjectSettings, ensureShortLinksDefault, ensurePersonaProject, findPersonaProject, REQUIRED_FIELDS, RECOMMENDED_FIELDS, configPath, ensureConfigInStateDir, normalizeStringList, recordRedditAccount, } from "./setup.js";
 import { xStatus, xConnect, xDetectSources, xScanProfile, summarizeXAuth } from "./twitterAuth.js";
+import { redditStatus, redditConnect, redditDetectSources, summarizeRedditAuth, } from "./redditAuth.js";
 import { startProvisioning, isProvisioning, readProgress, runtimeReady, readRuntime, resolvePython, resolveChrome, ensureMenubar, menubarRunning, clearMenubarStop, ensurePipelineCurrent, ensureRuntimeProvisioned, ensureHarnessPatched, retryProvisionIfStalled, } from "./runtime.js";
 import { blockOnboardingMilestone, completeOnboardingMilestone, ensureDoctorPhase, onboardingLedger, onboardingSnapshot, recordOnboardingAttempt, runDoctorPhase, } from "./onboarding.js";
 import { VERSION, versionStatus, latestPublishedVersion } from "./version.js";
@@ -68,6 +69,17 @@ const PHASE1_TASK_ID = "saps-phase1-query"; // legacy (was: "twitter-query" only
 const PHASE2B_TASK_ID = "saps-phase2b-draft"; // legacy (was: "twitter-prep" only)
 const TWITTER_AUTOPILOT_LABEL = "com.m13v.social-twitter-cycle";
 const TWITTER_AUTOPILOT_PLIST = path.join(os.homedir(), "Library", "LaunchAgents", `${TWITTER_AUTOPILOT_LABEL}.plist`);
+// Reddit discovery kicker (optional platform, 2026-07-15). Runs the SAME
+// launchd label the operator Mac has used by hand since May
+// (com.m13v.social-reddit-search) so there is one canonical name fleet-wide,
+// but ensureRedditKickerInstalled() refuses to touch a plist whose program
+// path points outside the managed package (the operator's hand-built plist
+// stays untouched). Installed only when reddit is connected AND a project is
+// configured; never part of onboarding completion.
+const REDDIT_SEARCH_LABEL = "com.m13v.social-reddit-search";
+const REDDIT_SEARCH_PLIST = path.join(os.homedir(), "Library", "LaunchAgents", `${REDDIT_SEARCH_LABEL}.plist`);
+const REDDIT_SEARCH_INTERVAL_SECS = 900;
+const REDDIT_CDP_URL_DEFAULT = "http://127.0.0.1:9557";
 // Self-healing reaper for leaked Claude agent-mode worker sessions. The queue
 // autopilot fires two scheduled tasks every ~1 min; each fire spawns a ~200 MB
 // `claude` agent-mode session that finishes its one queue turn but never exits
@@ -313,23 +325,29 @@ const server = new McpServer({
         "can run them hands-free on autopilot.\n\n" +
         "ONBOARDING IS A TERMINAL GOAL. When the user asks to set up, install, configure, or onboard " +
         "social-autoposter, keep taking the next safe action until the owned runtime is ready, a " +
-        "project is fully configured with seeded search topics, X is connected with its real handle, AND " +
+        "project is fully configured with seeded search topics, AT LEAST ONE platform is connected " +
+        "(ASK the user up front which platform(s) to connect — X, Reddit, or both — before connecting " +
+        "anything; X is a reasonable default to SUGGEST, but do not connect it, or any platform, without " +
+        "the user's answer. Connect exactly what they choose via project_config action:'connect_x' " +
+        "and/or action:'connect_reddit'), AND " +
         "the two draft-autopilot scheduled tasks have been created via queue_setup and are firing " +
         "(see SCHEDULE THE AUTOPILOT below). The owned runtime (private Python + Chromium) provisions " +
         "ITSELF automatically on boot — you do NOT install it. Just poll runtime action:'status' until it " +
         "reports ready; only call runtime action:'install' or action:'doctor' to TROUBLESHOOT if status " +
         "shows the boot provision failed or stalled. Do not ask whether to inspect " +
-        "status, repair a failed runtime, choose an auto-detected browser profile, connect " +
-        "X, scan the profile, research the product website, save conservative inferred fields, or seed " +
+        "status, repair a failed runtime, choose an auto-detected browser profile, scan the profile, " +
+        "research the product website, save conservative inferred fields, or seed " +
         "topics. Do those things. The " +
         "explicit setup request authorizes runtime repair and importing ONLY x.com/" +
         "twitter.com session cookies into the managed browser: warn that macOS keychain prompts may " +
-        "appear, then proceed without a separate yes/no turn. Ask at most one bundled question, only " +
+        "appear, then proceed without a separate yes/no turn. Besides the platform-choice question " +
+        "above, ask at most one MORE bundled question, only " +
         "when no product can be identified from config, context, the X profile, or public research, " +
         "or pause for an unavoidable interactive login or OS prompt. Never auto-POST during setup. " +
         "DO schedule the draft autopilot as the final step (once running it only queues drafts for " +
         "approval, it never posts on its own). When setup reaches done (" +
-        "runtime ready, a project configured with seeded topics, X connected, and the two scheduled tasks " +
+        "runtime ready, a project configured with seeded topics, at least one platform connected, and the " +
+        "two scheduled tasks " +
         "created and firing), call the `dashboard` tool so the user " +
         "sees the finished setup rendered, then give " +
         "the completion summary.\n\n" +
@@ -351,6 +369,16 @@ const server = new McpServer({
         "old 'social-autoposter-autopilot' task — it is deprecated. Do NOT ask the user to review drafts " +
         "or pause for input mid-onboarding; once the tasks are created and firing, setup is done. If the " +
         "host exposes no create_scheduled_task tool, tell the user the autopilot couldn't be scheduled here.\n\n" +
+        "REDDIT IS AN EQUAL PLATFORM CHOICE, ASKED ALONGSIDE X. Setup is complete with AT LEAST ONE " +
+        "platform connected: X-only, Reddit-only, or both — whichever the user picked when you asked " +
+        "up front. If they chose both, connect them one at a time (either order) in the same setup " +
+        "flow. `project_config` action:'connect_reddit' imports the user's reddit.com session into the " +
+        "autoposter's managed reddit browser, same confirm-first flow and keychain heads-up as " +
+        "connect_x. Once connected, reddit discovery and drafting run on the same draft-only queue and " +
+        "review cards as X; nothing posts without approval. If the result carries a `warning` (fresh or " +
+        "low-karma account), relay it so the user knows AutoMod may gate early replies. Never make " +
+        "either platform a requirement, and never nag a user who deliberately chose only one about the " +
+        "other.\n\n" +
         "BE PROACTIVE ABOUT MARKETING MOMENTS. Whenever the user ships, finishes, merges, or releases " +
         "something worth talking about in this session (a new feature, a launch, a long-awaited fix, a " +
         "milestone), don't wait to be asked: point it out to the user — the draft autopilot runs " +
@@ -361,7 +389,8 @@ const server = new McpServer({
         "release, call the `runtime` tool (action:'version'). If `update_available` is true, tell the " +
         "user and offer to run `runtime` with action:'update'. The `project_config` tool's status also " +
         "surfaces `update_available` and an `update_hint`.\n\n" +
-        "TYPICAL FLOW: `project_config` (connect X + scan the profile) -> `engagement_mode` (after the " +
+        "TYPICAL FLOW: ASK which platform(s) to connect (X, Reddit, or both) -> `project_config` " +
+        "(connect the chosen platform(s) + scan the profile) -> `engagement_mode` (after the " +
         "profile scan: personal-brand is ON by default, so ASK the user the ONE question — do they ALSO " +
         "want to promote a product? — and call action:'set' with personal_brand:true and " +
         "promotion:true|false; this provisions the persona) -> IF they wanted promotion, `project_config` " +
@@ -827,7 +856,7 @@ function readConfiguredTwitterHandle() {
     if (env)
         return env;
     try {
-        const cfg = JSON.parse(fs.readFileSync(path.join(repoDir(), "config.json"), "utf-8"));
+        const cfg = JSON.parse(fs.readFileSync(configPath(), "utf-8"));
         const h = cfg?.accounts?.twitter?.handle;
         const s = (typeof h === "string" ? h : "").trim().replace(/^@/, "");
         return s || null;
@@ -982,6 +1011,27 @@ async function postApproved(batchId, plan) {
                 plan = fresh;
         }
     }
+    // Arm the cross-instance posting flag HERE, before the Reddit drain, not just
+    // before the Twitter phase below. Root cause (found 2026-07-16): this flag
+    // used to get set only right before ensureTwitterBrowserForPost(), AFTER the
+    // whole Reddit drain loop above (one runPython("post_reddit.py") call per
+    // approved Reddit card, each with real CDP/browser overhead — a batch of a
+    // handful of cards routinely runs minutes). For that entire window this
+    // instance's isPeerDrainActive() reported false, so a SECOND MCP instance's
+    // postApproved() (e.g. a fresh one-shot worker boot running its own startup
+    // backlog drain) could pass the SAME gate check above and start its own
+    // drain concurrently. Both eventually reached their own Twitter phase and
+    // both spawned scripts/twitter_post_plan.py with S4L_LOCK_ROLE=post — the
+    // ONLY code path that ever sets that role. Two live "post" role holders
+    // can't preempt each other (browser_mutex.py case 6: correct, preempting a
+    // peer mid-post risks a double-post), so one always waited 45s and gave up
+    // — the "Twitter browser locked by session python:<pid> ... waited 45s,
+    // giving up" failures that silently killed 11 real approved drafts over
+    // 2026-07-15/16. Arming the flag for the FULL function closes that window:
+    // a peer's gate check now blocks for the entire drain, Reddit included, so
+    // only one instance ever reaches the Twitter phase at a time.
+    postingActive = true;
+    startPostingFlagHeartbeat();
     // Post every card the user APPROVED that hasn't already landed or been ruled out.
     // `approved` is now a DURABLE decision (sticky, never cleared by a later call), so
     // filtering out posted/terminal here makes this idempotent: re-running it only
@@ -1000,8 +1050,11 @@ async function postApproved(batchId, plan) {
             delete c.discard_reason;
         }
     }
-    if (approved.length === 0)
+    if (approved.length === 0) {
+        postingActive = false;
+        stopPostingFlagHeartbeat();
         return { attempted: 0, exit_code: 0, summary: "nothing approved" };
+    }
     // ---- Reddit cards (2026-07-14): drain them FIRST, independently ----------
     // A reddit card carries the verbatim draft decision (reddit_decision) plus
     // plan metadata (reddit_plan_meta), so approval reconstructs a one-decision
@@ -1014,84 +1067,179 @@ async function postApproved(batchId, plan) {
     const approvedTwitter = approved.filter((c) => c.platform !== "reddit");
     let redditPosted = 0;
     let redditFailed = 0;
+    let redditSkippedPeerDrain = false;
     if (approvedReddit.length) {
-        for (const c of approvedReddit) {
-            const cc = c;
-            const dec = cc.reddit_decision;
-            const meta = (cc.reddit_plan_meta || {});
-            if (!dec) {
-                c.terminal = true;
-                c.terminal_reason = "reddit_decision_missing";
-                redditFailed++;
-                continue;
-            }
-            const miniPlan = {
-                project_name: meta.project_name || cc.matched_project,
-                batch_id: cc.reddit_batch_id || meta.batch_id || "reddit-mcp-approval",
-                phase: "draft",
-                decisions: [dec],
-                style_assignment: meta.style_assignment || {},
-                generation_trace_path: meta.generation_trace_path,
-                session_id: meta.session_id || meta.draft_session_id,
-            };
-            const tmpPlan = path.join(process.env.S4L_TMP_DIR || "/tmp", `reddit_mcp_post_${Date.now()}_${Math.floor(Math.random() * 1e6)}.json`);
-            let r;
+        // Cross-instance drain gate (2026-07-14 drain storm): every one-shot MCP
+        // boot (the queue worker fires ~every minute; each boot runs the startup
+        // backlog drain) drained the SAME sticky approvals concurrently — 26
+        // drain plans in ~30 minutes, all fighting over the one reddit tab and
+        // false-positiving each other's posts. reddit-posting-active.json is the
+        // arbiter: post_reddit.py heartbeats it per row, and we stamp it around
+        // the whole drain here. A fresh flag (<120s) means a peer is mid-drain:
+        // leave the cards for it — approvals are sticky, nothing is lost.
+        const redditFlagPath = path.join(s4lStateDir(), "reddit-posting-active.json");
+        let redditPeerFresh = false;
+        try {
+            redditPeerFresh = Date.now() - fs.statSync(redditFlagPath).mtimeMs < 120_000;
+        }
+        catch {
+            redditPeerFresh = false;
+        }
+        const stampRedditFlag = () => {
             try {
-                fs.writeFileSync(tmpPlan, JSON.stringify(miniPlan));
-                r = await runPython("scripts/post_reddit.py", ["--phase", "post", "--in", tmpPlan], {
-                    timeoutMs: 900_000,
-                    env: {
-                        REDDIT_CDP_URL: process.env.REDDIT_CDP_URL || "http://127.0.0.1:9557",
-                        // Reviewed posts never get the active-campaign suffix (same rule
-                        // as the twitter manual-approval path below).
-                        S4L_SKIP_CAMPAIGN_SUFFIX: "1",
-                    },
-                    onLine: (line) => {
-                        const t = line.replace(/\s+$/, "");
-                        if (t.trim())
-                            console.error(`[post-reddit] ${t}`);
-                    },
-                });
+                fs.writeFileSync(redditFlagPath, JSON.stringify({ pid: process.pid, hb: Math.floor(Date.now() / 1000) }));
             }
-            catch (err) {
-                r = { code: -1, stdout: "", stderr: String(err) };
+            catch {
+                /* best effort */
+            }
+        };
+        if (redditPeerFresh) {
+            redditSkippedPeerDrain = true;
+            logPostEvent(`postApproved_reddit_skip batch=${batchId} reason=peer_drain_active cards=${approvedReddit.length}`);
+        }
+        else {
+            stampRedditFlag();
+            try {
+                for (const c of approvedReddit) {
+                    stampRedditFlag();
+                    const cc = c;
+                    const dec = cc.reddit_decision;
+                    const meta = (cc.reddit_plan_meta || {});
+                    if (!dec) {
+                        c.terminal = true;
+                        c.terminal_reason = "reddit_decision_missing";
+                        redditFailed++;
+                        continue;
+                    }
+                    // The card's reply_text is the CANONICAL text (post_drafts edits write
+                    // there); the embedded decision still carries the draft-time original.
+                    // Posting dec.text verbatim would silently discard a human edit.
+                    const decPost = {
+                        ...dec,
+                        text: (typeof cc.reply_text === "string" && cc.reply_text.trim())
+                            ? cc.reply_text
+                            : dec.text,
+                    };
+                    if (cc.engagement_style)
+                        decPost.engagement_style = cc.engagement_style;
+                    // Two-draft cards (2026-07-15): a human draft-switch (see the generic
+                    // edit-handling above, `if (e.variant && Array.isArray(c.drafts))`)
+                    // stamps the CHOSEN draft's assigned_style/assigned_mode onto the card
+                    // (cc). Forward both into decPost so post_reddit.py's _post_iteration
+                    // validates/logs against whichever draft is ACTUALLY posting, not
+                    // whichever was recommended at plan-write time — mirrors
+                    // twitter_post_plan.py's identical per-candidate override.
+                    if (cc.assigned_style !== undefined)
+                        decPost.assigned_style = cc.assigned_style;
+                    if (cc.assigned_mode !== undefined)
+                        decPost.assigned_mode = cc.assigned_mode;
+                    const miniPlan = {
+                        project_name: meta.project_name || cc.matched_project,
+                        batch_id: cc.reddit_batch_id || meta.batch_id || "reddit-mcp-approval",
+                        phase: "draft",
+                        decisions: [decPost],
+                        style_assignment: meta.style_assignment || {},
+                        generation_trace_path: meta.generation_trace_path,
+                        session_id: meta.session_id || meta.draft_session_id,
+                    };
+                    const tmpPlan = path.join(process.env.S4L_TMP_DIR || "/tmp", `reddit_mcp_post_${Date.now()}_${Math.floor(Math.random() * 1e6)}.json`);
+                    let r;
+                    try {
+                        fs.writeFileSync(tmpPlan, JSON.stringify(miniPlan));
+                        r = await runPython("scripts/post_reddit.py", ["--phase", "post", "--in", tmpPlan], {
+                            timeoutMs: 900_000,
+                            env: {
+                                REDDIT_CDP_URL: process.env.REDDIT_CDP_URL || "http://127.0.0.1:9557",
+                                // Reviewed posts never get the active-campaign suffix (same rule
+                                // as the twitter manual-approval path below).
+                                S4L_SKIP_CAMPAIGN_SUFFIX: "1",
+                            },
+                            onLine: (line) => {
+                                const t = line.replace(/\s+$/, "");
+                                if (t.trim())
+                                    console.error(`[post-reddit] ${t}`);
+                            },
+                        });
+                    }
+                    catch (err) {
+                        r = { code: -1, stdout: "", stderr: String(err) };
+                    }
+                    finally {
+                        try {
+                            fs.unlinkSync(tmpPlan);
+                        }
+                        catch {
+                            /* best effort */
+                        }
+                    }
+                    // post_reddit.py's summary marker: `[post_reddit] phase=post ... posted=N failed=M`
+                    const out = `${r.stdout}\n${r.stderr}`;
+                    const postedN = Number((/posted=(\d+)/.exec(out) || [])[1] || 0);
+                    if (r.code === 0 && postedN > 0) {
+                        c.posted = true;
+                        c.terminal = false;
+                        const urlMatch = /(https:\/\/(?:old\.|www\.)?reddit\.com\/r\/\S+)/.exec((/\[post_reddit\][^\n]*posted[^\n]*/i.exec(out) || [""])[0]);
+                        if (urlMatch)
+                            c.our_url = urlMatch[1];
+                        redditPosted++;
+                    }
+                    else {
+                        // Leave the approval sticky (approved && !posted && !terminal) so the
+                        // next post_drafts call retries, mirroring twitter's failed-drain
+                        // semantics; only stamp terminal on a conclusive CDP refusal. This
+                        // list MUST stay a superset of post_reddit.py's own
+                        // _PERMANENT_CDP_ERRORS (account_blocked_in_sub, no_permalink) —
+                        // otherwise post_reddit.py already gives up on the row (marks the DB
+                        // candidate permanently failed, e.g. adds the sub to
+                        // subreddit_bans.comment_blocked) while this card stays non-terminal
+                        // and the drain retries the same doomed post forever (found
+                        // 2026-07-16: an approved r/tifu card retried every cycle for over
+                        // an hour after the sub was already in subreddit_bans.comment_blocked).
+                        const cdpReason = (/\[post_reddit\] CDP FAILED: ([a-z_]+)/.exec(out) || [])[1];
+                        if (cdpReason &&
+                            [
+                                "thread_locked",
+                                "thread_archived",
+                                "thread_not_found",
+                                "blocked_by_author",
+                                "account_blocked_in_sub",
+                                "no_permalink",
+                            ].includes(cdpReason)) {
+                            c.terminal = true;
+                            c.terminal_reason = `reddit_${cdpReason}`;
+                        }
+                        redditFailed++;
+                    }
+                }
             }
             finally {
+                // Clear only OUR stamp; a peer that took over mid-drain keeps its own.
                 try {
-                    fs.unlinkSync(tmpPlan);
+                    const cur = JSON.parse(fs.readFileSync(redditFlagPath, "utf-8"));
+                    if (cur && cur.pid === process.pid)
+                        fs.unlinkSync(redditFlagPath);
                 }
                 catch {
                     /* best effort */
                 }
             }
-            // post_reddit.py's summary marker: `[post_reddit] phase=post ... posted=N failed=M`
-            const out = `${r.stdout}\n${r.stderr}`;
-            const postedN = Number((/posted=(\d+)/.exec(out) || [])[1] || 0);
-            if (r.code === 0 && postedN > 0) {
-                c.posted = true;
-                c.terminal = false;
-                const urlMatch = /(https:\/\/(?:old\.|www\.)?reddit\.com\/r\/\S+)/.exec((/\[post_reddit\][^\n]*posted[^\n]*/i.exec(out) || [""])[0]);
-                if (urlMatch)
-                    c.our_url = urlMatch[1];
-                redditPosted++;
-            }
-            else {
-                // Leave the approval sticky (approved && !posted && !terminal) so the
-                // next post_drafts call retries, mirroring twitter's failed-drain
-                // semantics; only stamp terminal on a conclusive CDP refusal.
-                const cdpReason = (/\[post_reddit\] CDP FAILED: ([a-z_]+)/.exec(out) || [])[1];
-                if (cdpReason && ["thread_locked", "thread_archived", "thread_not_found", "blocked_by_author"].includes(cdpReason)) {
-                    c.terminal = true;
-                    c.terminal_reason = `reddit_${cdpReason}`;
-                }
-                redditFailed++;
-            }
+            logPostEvent(`postApproved_reddit batch=${batchId} attempted=${approvedReddit.length} posted=${redditPosted} failed=${redditFailed}`);
         }
-        logPostEvent(`postApproved_reddit batch=${batchId} attempted=${approvedReddit.length} posted=${redditPosted} failed=${redditFailed}`);
     }
     if (approvedTwitter.length === 0) {
         // All-reddit batch: persist the stamps and return without touching the
-        // twitter preflight/lock path.
+        // twitter preflight/lock path. Must clear the flag armed above ourselves —
+        // this branch never reaches the Twitter phase's scheduleShellLockRelease().
+        postingActive = false;
+        stopPostingFlagHeartbeat();
+        if (redditSkippedPeerDrain) {
+            return {
+                attempted: 0,
+                posted: 0,
+                exit_code: 0,
+                summary: "reddit: skipped (peer drain active); cards stay approved for the next drain",
+            };
+        }
         if (approvedReddit.length)
             mergeApprovedStampsIntoStore(batchId, plan, approvedReddit);
         return {
@@ -1109,6 +1257,8 @@ async function postApproved(batchId, plan) {
     if (!readConfiguredTwitterHandle())
         await ensurePostingHandle();
     if (!readConfiguredTwitterHandle()) {
+        postingActive = false;
+        stopPostingFlagHeartbeat();
         return {
             attempted: 0,
             exit_code: 0,
@@ -1309,11 +1459,31 @@ async function postApproved(batchId, plan) {
                     c.our_url = r.our_url;
                 touchedPlan = true;
             }
-            else if (r.outcome === "skipped" || r.outcome === "failed") {
+            else if (r.outcome === "skipped") {
+                // twitter_post_plan.py only returns "skipped" for reasons it has
+                // already decided are conclusive (reply_restricted, tweet_unavailable,
+                // blocked_by_author, tweet_not_found, rate_limited, reply_box_not_found
+                // — see its own PERMANENT/skip comment) or a captured-URL edge case
+                // it explicitly doesn't want re-attempted (duplicate risk). Terminal
+                // is correct here.
                 c.terminal = true;
                 c.terminal_reason = r.reason || r.outcome;
                 touchedPlan = true;
             }
+            else if (r.outcome === "failed") {
+                // "failed" is twitter_post_plan.py's catch-all for everything it did
+                // NOT classify as conclusive — timeouts, parse errors, exceptions,
+                // and browser_mutex contention ("Twitter browser locked by session
+                // ... waited 45s, giving up."). None of those mean the draft is
+                // doomed, only that this attempt didn't get a turn with the shared
+                // browser. Leave the card sticky (approved && !posted && !terminal)
+                // so the next post_drafts call retries it, mirroring Reddit's
+                // _TRANSIENT_CDP_ERRORS handling. Unconditionally marking terminal
+                // here (found 2026-07-16) silently and permanently discarded 7 real
+                // approved drafts on nothing worse than lock contention — Reddit's
+                // equivalent transient failures self-healed on the very next drain.
+                touchedPlan = true;
+            }
         });
     }
     else if (realPosted > 0 || (res.code === 0 && !summObj)) {
@@ -1854,12 +2024,16 @@ tool("project_config", {
         "products (call once per product, identified by name); fill or edit a project's fields " +
         "INCREMENTALLY across several calls — pass whatever you have, it merges and tells you what's " +
         "still missing.\n" +
-        "2) Connect X/Twitter (action:'connect_x'): the autoposter posts through its OWN managed Chrome, " +
+        "2) Connect X/Twitter (action:'connect_x'), ONLY once the user has told you they want X connected " +
+        "(the top-level setup flow asks which platform(s) — X, Reddit, or both — before this tool is " +
+        "called for either): the autoposter posts through its OWN managed Chrome, " +
         "which needs your logged-in x.com session. This imports x.com/twitter.com cookies from your " +
         "everyday browser (Chrome/Arc/Brave/Edge, auto-detected) into that browser — nothing else is " +
-        "touched. An explicit setup/connect request is authorization: briefly warn that macOS Safe " +
-        "Storage prompts may appear, then call action:'connect_x', confirm:true immediately. Use " +
-        "action:'detect_x_sources' first and choose its recommendation instead of asking the user.\n" +
+        "touched. Once the user has said they want X, briefly warn that macOS Safe " +
+        "Storage prompts may appear, then call action:'connect_x', confirm:true immediately — no further " +
+        "round-trip needed for THIS decision, it was already made. Use " +
+        "action:'detect_x_sources' first and choose its recommendation instead of asking the user which " +
+        "browser profile to import from.\n" +
         "Call with status:true (or no name) to list every configured project, its remaining fields, AND " +
         "whether X is connected. Use config, conversation context, profile_scan, and website research " +
         "before asking for fields. Ask only if no product can be identified or an interactive login is " +
@@ -1868,7 +2042,14 @@ tool("project_config", {
     inputSchema: {
         status: z.boolean().optional(),
         action: z
-            .enum(["get", "connect_x", "detect_x_sources", "profile_scan"])
+            .enum([
+            "get",
+            "connect_x",
+            "detect_x_sources",
+            "profile_scan",
+            "connect_reddit",
+            "detect_reddit_sources",
+        ])
             .optional()
             .describe("get = read the CURRENT SAVED VALUES of every project's editable fields (website, " +
             "description, icp, voice, differentiator, search_topics, get_started_link, " +
@@ -1886,7 +2067,14 @@ tool("project_config", {
             "replies to build a 'grounding truth' corpus. Use it to draft voice/icp/search_topics in " +
             "the USER'S OWN register (their phrases, vibe, profession), then save a conservative best " +
             "draft without requiring a confirmation round-trip. Returns {profile, posts, comments, " +
-            "grounding_instructions}."),
+            "grounding_instructions}. " +
+            "connect_reddit = call ONLY once the user has said they want Reddit connected (setup " +
+            "completes with X-only, Reddit-only, or both — whichever they picked when asked up front; " +
+            "if X connection fails after they chose it, offer Reddit as a fallback): import/validate " +
+            "the user's reddit.com session in the " +
+            "autoposter's managed reddit browser, same confirm-first shape as connect_x. " +
+            "detect_reddit_sources = list the browsers/profiles the Reddit session can be imported " +
+            "from (read-only, no keychain prompt)."),
         confirm: z
             .boolean()
             .optional()
@@ -1903,6 +2091,17 @@ tool("project_config", {
             "X login window and waits for them to log in. By default (false), connect_x does NOT pop a " +
             "browser window on an auto-import miss; it returns needs_login and you offer manual login as " +
             "an opt-in. The login window still opens automatically if the user DENIED the keychain prompt."),
+        reddit_source: z
+            .string()
+            .optional()
+            .describe("Optional browser profile to import the Reddit session from, e.g. 'arc:Default', " +
+            "'chrome:Profile 1'. Default: auto-detect the browser that holds a reddit.com session."),
+        reddit_manual_login: z
+            .boolean()
+            .optional()
+            .describe("Set true ONLY when the user explicitly wants to sign into Reddit by hand. Opens a focused " +
+            "Reddit login window in the autoposter's reddit browser and waits. Same opt-in discipline " +
+            "as x_manual_login."),
         name: z
             .string()
             .optional()
@@ -2072,6 +2271,130 @@ tool("project_config", {
                     : "X is not connected yet. " + summarizeXAuth(r),
         });
     }
+    // ---- List Reddit import sources (read-only, no keychain prompt) --------
+    if (args.action === "detect_reddit_sources") {
+        const r = await redditDetectSources();
+        return jsonContent({
+            action: "detect_reddit_sources",
+            ok: r.ok,
+            sources: r.sources,
+            recommended: r.recommended,
+            error: r.error,
+        });
+    }
+    // ---- Connect Reddit: OPTIONAL platform, mirrors connect_x --------------
+    // Preview-or-run, same confirm-first shape as connect_x. Reddit is never
+    // required for onboarding completion; offer it only after X setup is done
+    // and the user wants it.
+    if (args.action === "connect_reddit") {
+        if (args.confirm !== true) {
+            // Cheap probe so the explanation reflects current state (no Chrome launch).
+            const cur = await redditStatus();
+            if (cur.connected) {
+                return jsonContent({
+                    action: "connect_reddit",
+                    already_connected: true,
+                    state: cur.state,
+                    username: cur.username,
+                    note: "Reddit is already connected in the autoposter's reddit browser. Nothing to import.",
+                });
+            }
+            return jsonContent({
+                action: "connect_reddit",
+                requires_confirmation: true,
+                current_state: cur.state,
+                what_will_happen: "To engage on Reddit for you, the autoposter uses its OWN managed Google Chrome (separate " +
+                    "from your everyday browser and from the X one). It needs your logged-in reddit.com " +
+                    "session. If you confirm, it will: (1) start that managed reddit browser if it isn't " +
+                    "running, (2) copy ONLY your reddit.com cookies (reddit_session, token_v2) from your " +
+                    "everyday browser (Chrome/Arc/Brave/Edge, auto-detected) into it, and (3) verify you're " +
+                    "logged in via Reddit's own me.json. No other site's cookies are read, and your passwords " +
+                    "are never seen. If it can't import a valid session, a Chrome window will open for you to " +
+                    "sign in once.",
+                keychain_prompt: "Reading the saved session requires macOS to unlock the browser's encrypted cookie store, so " +
+                    "one or more keychain prompts will appear (“... wants to use your confidential information " +
+                    "stored in '... Safe Storage' in your keychain”). This is expected. The user enters their Mac " +
+                    "login password and clicks Allow (or Always Allow to avoid repeats). If they use more than one " +
+                    "browser, the prompt can appear a few times, once per browser.",
+                say_to_user: "Heads up: your Mac will pop up a keychain prompt asking to use your browser's Safe Storage. " +
+                    "That's just us reading your saved Reddit login, nothing else. Type your Mac login password and " +
+                    "click Allow (or Always Allow). If you use more than one browser you may see it a couple of " +
+                    "times, once per browser.",
+                how_to_proceed: "If the user explicitly requested connecting Reddit, relay the say_to_user line as a brief " +
+                    "heads-up and immediately call project_config again with action:'connect_reddit', confirm:true; " +
+                    "do not wait for another yes/no reply. Optionally pass a reddit_source from " +
+                    "detect_reddit_sources. If the user only asked what connection would do, stop after this " +
+                    "preview. Reddit is OPTIONAL: never treat it as required for setup completion.",
+            });
+        }
+        recordOnboardingAttempt("reddit_connected", {
+            state: args.reddit_source ? "source_selected" : "auto_detect",
+        });
+        const r = await redditConnect(args.reddit_source, args.reddit_manual_login);
+        let verified = false;
+        let configNote;
+        if (r.connected) {
+            completeOnboardingMilestone("reddit_connected", { state: r.state });
+            // Persist the discovered username through the server's config-write
+            // path (accounts.reddit.username, the field account_resolver reads),
+            // never overwriting a deliberately-set value.
+            if (r.username) {
+                const w = recordRedditAccount(r.username);
+                configNote = w.detail;
+            }
+            // Doctor-style persistence re-check before reddit_verified: a fresh
+            // read-only status probe confirms the session actually persisted
+            // (live me.json or the on-disk profile cookie row) rather than
+            // trusting the connect call's own success.
+            const recheck = await redditStatus();
+            if (recheck.connected) {
+                completeOnboardingMilestone("reddit_verified", { state: recheck.state });
+                verified = true;
+            }
+            else {
+                recordOnboardingAttempt("reddit_verified", {
+                    state: recheck.state || "unverified",
+                });
+            }
+            // Reddit is live: install the discovery kicker (idempotent; gated on
+            // runtime + project readiness inside, and it never touches a
+            // hand-built plist pointing outside the managed package).
+            void ensureRedditKickerInstalled()
+                .then((res) => console.error(`[reddit-kicker] post-connect install: ${res.ok ? "ok" : "skip"} (${res.detail})`))
+                .catch((e) => console.error("[reddit-kicker] post-connect install failed:", e?.message || e));
+        }
+        else {
+            blockOnboardingMilestone("reddit_connected", `reddit_${r.state || "not_connected"}`, r.error || r.note || summarizeRedditAuth(r), { state: r.state || "not_connected" });
+        }
+        return jsonContent({
+            action: "connect_reddit",
+            connected: r.connected,
+            state: r.state,
+            username: r.username,
+            account_age_days: r.account_age_days,
+            comment_karma: r.comment_karma,
+            // Ready-to-relay expectation setter for fresh/low-karma accounts
+            // (AutoMod gates those in most subreddits). Advisory only; never a
+            // reason to block or undo the connect.
+            warning: r.warning,
+            verified,
+            config: configNote,
+            summary: summarizeRedditAuth(r),
+            note: r.note,
+            attempts: r.attempts,
+            onboarding: onboardingSnapshot(),
+            next_step: r.connected
+                ? "Reddit is connected. The reddit discovery job installs itself once a project is " +
+                    "configured; drafts flow into the same review cards as X and nothing posts without " +
+                    "approval." +
+                    (r.warning ? " Relay the `warning` field to the user so expectations are set." : "")
+                : r.state === "needs_login"
+                    ? "The user must finish signing in to reddit.com in the Chrome window that opened. Tell " +
+                        "them that single required action, then call project_config action:'connect_reddit', " +
+                        "confirm:true again."
+                    : "Reddit is not connected yet. " + summarizeRedditAuth(r),
+        });
+    }
     // ---- Profile scan: grounding-truth corpus from the connected account ----
     // Reuses the authenticated managed-Chrome session (so it must run AFTER a
     // successful connect_x) to read the user's bio + recent posts + recent
@@ -2177,6 +2500,9 @@ tool("project_config", {
         const projects = Array.isArray(snap.projects) ? snap.projects : [];
         const rtReady = !!snap.runtime_ready;
         const xConnected = !!snap.x_connected;
+        const redditConnected = !!snap.reddit_connected;
+        // Any-of platform completion: X or Reddit satisfies the platform leg.
+        const anyPlatform = xConnected || redditConnected;
         const configured = (snap.projects_ready || 0) > 0;
         return jsonContent({
             configured,
@@ -2185,6 +2511,9 @@ tool("project_config", {
             x_connected: xConnected,
             x_state: snap.x_state,
             x_handle: snap.x_handle ?? null,
+            reddit_connected: redditConnected,
+            reddit_state: snap.reddit_state,
+            reddit_username: snap.reddit_username ?? null,
             setup_complete: !!snap.setup_complete,
             mcp_version: snap.version,
             latest_version: snap.latest_version,
@@ -2206,14 +2535,15 @@ tool("project_config", {
                 ? "Runtime is not ready yet. It provisions automatically on boot — poll runtime action:'status' until ready (only call runtime action:'install' to retry if status shows the boot provision failed or stalled), then continue setup automatically."
                 : projects.length === 0
                     ? "No projects yet. Discover the product from conversation context and the connected X profile; research its website, infer a conservative complete project, and call project_config. Ask only if no product can be identified." +
-                        (xConnected ? "" : " X is not connected yet either — detect_x_sources, warn about keychain prompts, then run connect_x with confirm:true without a separate permission turn.")
+                        (anyPlatform ? "" : " No platform is connected yet either. X is the default: detect_x_sources, warn about keychain prompts, then run connect_x with confirm:true without a separate permission turn. If the user prefers Reddit (or X can't be connected), connect_reddit works standalone.")
                     : projects.every((p) => p.ready)
-                        ? (xConnected
-                            ? "All configured projects are ready and X is connected. SCHEDULE THE AUTOPILOT: (1) call queue_setup and create each returned task with create_scheduled_task (prompt and notifyOnCompletion verbatim — notifyOnCompletion must be false; 'already exists' is fine, but then call update_scheduled_task with notifyOnCompletion:false to silence per-run notifications); (2) the autopilot then runs on its own (launchd kicker + queue worker). Call the `dashboard` tool to confirm the schedule is firing (schedule_state 'ok') — that is the terminal step; do NOT wait for or verify a draft card. Do NOT pause to ask the user to review drafts."
-                            : "All configured projects are ready, but X is NOT connected — posting needs a logged-in " +
-                                "x.com session. Detect sources and run project_config action:'connect_x', confirm:true; do not ask whether to proceed.")
+                        ? (anyPlatform
+                            ? "All configured projects are ready and a platform is connected" +
+                                (xConnected ? "" : " (Reddit; X was skipped, which is fine)") +
+                                ". SCHEDULE THE AUTOPILOT: (1) call queue_setup and create each returned task with create_scheduled_task (prompt and notifyOnCompletion verbatim — notifyOnCompletion must be false; 'already exists' is fine, but then call update_scheduled_task with notifyOnCompletion:false to silence per-run notifications); (2) the autopilot then runs on its own (launchd kicker + queue worker). Call the `dashboard` tool to confirm the schedule is firing (schedule_state 'ok') — that is the terminal step; do NOT wait for or verify a draft card. Do NOT pause to ask the user to review drafts."
+                            : "All configured projects are ready, but NO platform is connected yet; posting needs a logged-in session. X is the default: detect sources and run project_config action:'connect_x', confirm:true; do not ask whether to proceed. If the user prefers Reddit or X can't be connected, run action:'connect_reddit' instead; ONE connected platform completes setup.")
                         : "Some projects are missing required fields (see each project's missing_required). Derive them from config, context, profile_scan, and website research, then call project_config again. Ask only if a required field is genuinely unknowable." +
-                            (xConnected ? "" : " X is also not connected yet; detect sources and run connect_x with confirm:true."),
+                            (anyPlatform ? "" : " No platform is connected yet either; X is the default (connect_x with confirm:true), or connect_reddit if the user prefers Reddit."),
         });
     }
     // Apply mode (incremental): merge whatever fields were supplied onto the
@@ -2562,7 +2892,22 @@ tool("post_drafts", {
             warnings,
         });
     }
-    const result = await postApproved(batch_id, plan);
+    // postApproved now arms the cross-instance posting flag before the Reddit
+    // drain (see its own comment), not just before the Twitter phase. Every
+    // op inside that drain is already individually best-effort try/caught, so
+    // this is belt-and-suspenders: if something still throws past all of
+    // that, clear the flag before it escapes rather than leave this MCP
+    // instance's posting permanently gated behind a flag nothing will ever
+    // reset.
+    let result;
+    try {
+        result = await postApproved(batch_id, plan);
+    }
+    catch (e) {
+        postingActive = false;
+        stopPostingFlagHeartbeat();
+        throw e;
+    }
     // Report the REAL posted count from the pipeline, not the approved count.
     // A run can approve N yet land 0 (browser/session failure); reporting
     // approve.size here told the agent "posted: N" on a total failure.
@@ -3748,6 +4093,101 @@ async function ensureQueueKickerInstalled() {
         return { ok: false, detail: e?.message || String(e) };
     }
 }
+// ---- Reddit discovery kicker (optional platform) ----------------------------
+// Mirrors ensureQueueKickerInstalled for the reddit lane: a 15-minute launchd
+// job that runs skill/run-reddit-search-launchd.sh (the detach wrapper; the
+// real cycle honors the global draft-only flag via s4l_mode.py, and its
+// drafting turn rides the same s4l-worker queue as X). Gates:
+//   - runtime ready
+//   - reddit connected (connected OR connected_idle; the profile persists)
+//   - a managed project is configured and ready
+// It is NEVER an onboarding requirement: installs that never connect reddit
+// simply never get this plist.
+//
+// OPERATOR-MAC SAFETY: a hand-built com.m13v.social-reddit-search plist
+// pointing at ~/social-autoposter (StartCalendarInterval, custom env) exists
+// on the dev box. If an existing plist's program path is not the managed
+// package's wrapper, we log and leave it completely alone: no rewrite, no
+// reload, no unload.
+async function ensureRedditKickerInstalled() {
+    try {
+        if (process.platform !== "darwin")
+            return { ok: false, detail: "not macOS" };
+        if (!runtimeReady())
+            return { ok: false, detail: "runtime not ready" };
+        const productReady = listManagedProjectStatus().some((p) => p.ready);
+        if (!productReady)
+            return { ok: false, detail: "no ready project yet" };
+        // Reddit session gate. status is read-only (never launches Chrome): a live
+        // me.json validation when the harness is up, the on-disk profile cookie
+        // check (connected_idle) when it isn't.
+        const rs = await redditStatus();
+        if (!rs.connected) {
+            return { ok: false, detail: `reddit not connected (${rs.state})` };
+        }
+        const managedWrapper = path.join(repoDir(), "skill", "run-reddit-search-launchd.sh");
+        // Foreign-plist guard BEFORE any write: if a plist already exists and its
+        // ProgramArguments do not point at the managed package's wrapper, it is a
+        // hand-built / operator arrangement. Leave it untouched.
+        let cur = null;
+        try {
+            cur = fs.readFileSync(REDDIT_SEARCH_PLIST, "utf-8");
+        }
+        catch {
+            cur = null;
+        }
+        if (cur !== null && !cur.includes(`<string>${managedWrapper}</string>`)) {
+            const msg = `existing ${REDDIT_SEARCH_LABEL} plist points outside the managed package; leaving it untouched`;
+            console.error(`[reddit-kicker] ${msg}`);
+            return { ok: true, detail: `skip: ${msg}` };
+        }
+        const logDir = path.join(repoDir(), "skill", "logs");
+        try {
+            fs.mkdirSync(logDir, { recursive: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        const xml = plistXml({
+            label: REDDIT_SEARCH_LABEL,
+            programArgs: ["bash", managedWrapper],
+            intervalSecs: REDDIT_SEARCH_INTERVAL_SECS,
+            runAtLoad: false, // never fire a discovery cycle the instant Claude launches
+            stdoutLog: path.join(logDir, "launchd-reddit-search-stdout.log"),
+            stderrLog: path.join(logDir, "launchd-reddit-search-stderr.log"),
+            // S4L_REPO_DIR + S4L_PYTHON are baked by plistXml. State dir + CDP url
+            // pin the wrapper's children to the managed state and the harness port.
+            extraEnv: {
+                S4L_STATE_DIR: s4lStateDir(),
+                REDDIT_CDP_URL: REDDIT_CDP_URL_DEFAULT,
+            },
+            // The wrapper double-forks the real cycle into its own session already,
+            // but keep launchd away from the harness Chrome all the same.
+            abandonProcessGroup: true,
+        });
+        const uid = process.getuid ? process.getuid() : 0;
+        if (cur === xml) {
+            const res = await loadPlist(REDDIT_SEARCH_LABEL, REDDIT_SEARCH_PLIST, uid);
+            return { ok: true, detail: `current (load rc=${res.code})` };
+        }
+        if (cur !== null) {
+            await unloadPlist(REDDIT_SEARCH_LABEL, REDDIT_SEARCH_PLIST, uid);
+        }
+        fs.mkdirSync(path.dirname(REDDIT_SEARCH_PLIST), { recursive: true });
+        fs.writeFileSync(REDDIT_SEARCH_PLIST, xml, "utf-8");
+        const res = await loadPlist(REDDIT_SEARCH_LABEL, REDDIT_SEARCH_PLIST, uid);
+        // No first-run kickstart on purpose: reddit discovery is a background
+        // add-on, and the connect flow just finished using the harness browser.
+        // The first StartInterval tick (≤15 min) is soon enough.
+        return {
+            ok: true,
+            detail: cur === null ? "installed + loaded" : `rewritten + reloaded (rc=${res.code})`,
+        };
+    }
+    catch (e) {
+        return { ok: false, detail: e?.message || String(e) };
+    }
+}
 // ---- launchd reaper: kill leaked agent-mode claude worker sessions ----------
 // Independent guardrail (NOT gated on a project being ready): the leak happens
 // whenever the scheduled-task workers fire, and a no-leak run is a cheap no-op.
@@ -4235,6 +4675,13 @@ async function buildSnapshot() {
         completeOnboardingMilestone("runtime_ready");
     if (snap.x_connected)
         completeOnboardingMilestone("x_connected", { state: snap.x_state || "connected" });
+    // Reddit (optional platform) heal: a live connected reading on a LATER poll
+    // is itself persistence evidence, so it may also complete reddit_verified
+    // for an install whose post-connect verify probe transiently failed.
+    if (snap.reddit_connected) {
+        completeOnboardingMilestone("reddit_connected", { state: snap.reddit_state || "connected" });
+        completeOnboardingMilestone("reddit_verified", { source: "live_snapshot" });
+    }
     if ((snap.projects_ready || 0) > 0)
         completeOnboardingMilestone("project_ready", { missing_count: 0 });
     if (snap.schedule_state === "ok")
@@ -5255,6 +5702,10 @@ async function drainApprovedBacklog() {
     }
     catch (e) {
         console.error("[post] drainApprovedBacklog error:", e?.message || e);
+        // Same reasoning as the other postApproved call site: don't let an
+        // escaped exception leave the cross-instance posting flag stuck true.
+        postingActive = false;
+        stopPostingFlagHeartbeat();
     }
 }
 async function main() {
@@ -5278,6 +5729,12 @@ async function main() {
     // disk, BEFORE serving, so the very first scan uses the shipped pipeline (not
     // the version first materialized at install). Synchronous + best-effort.
     ensurePipelineCurrent();
+    // Config's canonical home is the state dir (2026-07-13): migrate a legacy
+    // in-repo config.json up on first boot after update, keep the legacy path
+    // working via symlink, and self-heal a missing/wrong link on every boot.
+    // Must run AFTER ensurePipelineCurrent() so repoDir() points at the final
+    // materialized repo.
+    console.error(`[social-autoposter-mcp] config home: ${ensureConfigInStateDir()}`);
     // Deterministically provision the owned runtime on boot: whenever it isn't
     // ready (a fresh install, or one interrupted mid-way because a step failed or
     // Claude/the host died mid-install) kick the full install in the background
@@ -5333,6 +5790,17 @@ async function main() {
     else {
         console.error("[queue-worker] launchd kicker: skip (paused)");
     }
+    // Reddit discovery kicker (optional platform): installs only when reddit is
+    // connected AND a project is ready; a box that never connected reddit is a
+    // cheap no-op skip. Paused-gated like the X kicker (it produces drafts).
+    if (!isPaused()) {
+        void ensureRedditKickerInstalled()
+            .then((r) => console.error(`[reddit-kicker] launchd kicker: ${r.ok ? "ok" : "skip"} (${r.detail})`))
+            .catch((e) => console.error("[reddit-kicker] kicker install failed:", e?.message || e));
+    }
+    else {
+        console.error("[reddit-kicker] launchd kicker: skip (paused)");
+    }
     // Self-healing reaper for the agent-mode session leak the queue autopilot
     // produces (finished `claude` worker sessions Desktop never tears down). A
     // standalone guardrail; install unconditionally so it caps memory even on a
@@ -5509,17 +5977,22 @@ async function main() {
     void sendStateSnapshot("startup");
     const ss = setInterval(() => void sendStateSnapshot("interval"), 15 * 60_000);
     ss.unref();
-    // One-shot voice-exemplar catch-up for installs onboarded BEFORE the
-    // exemplar feature: if the persona has no voice.examples_scanned_at, rescan
-    // the connected X profile and store the top-performing replies as
-    // voice.examples + the persona_corpus.txt exemplar section. Additive only
-    // (regenerates just its own marked corpus section; respects hand-written
-    // examples) and self-limiting (no cooldown by design: success stamps
-    // examples_scanned_at which makes later boots a no-op, and until then it
-    // WAITS politely on the twitter-browser lock, polling while holding
-    // nothing, until cycles/DM runs free the browser, up to 12h before
-    // deferring to the next boot). Delayed so boot-time work (runtime
-    // provision, kicker install) settles first.
+    // Voice-exemplar catch-up + periodic refresh, checked on every boot
+    // (2026-07-16, extended from the original one-shot-for-legacy-installs
+    // version): rescans the connected X profile and re-stores voice.examples +
+    // the persona_corpus.txt exemplar section whenever
+    // scripts/voice_exemplars.py's _needs_rescan() says so -- never scanned,
+    // scanned by an older SCANNER_VERSION (so a scraper fix like the 2026-07-15
+    // stall-detection bug reaches already-scanned installs on their next boot
+    // instead of silently never re-running), or the last scan is more than
+    // RESCAN_MAX_AGE_DAYS (14) old. Additive only (regenerates just its own
+    // marked corpus section; respects hand-written examples). Each boot is
+    // cheap when nothing needs it (stamped examples_scanned_at +
+    // examples_scanner_version make it a no-op until either goes stale), and
+    // when something DOES need it, it WAITS politely on the twitter-browser
+    // lock, polling while holding nothing, until cycles/DM runs free the
+    // browser, up to 12h before deferring to the next boot. Delayed so
+    // boot-time work (runtime provision, kicker install) settles first.
     const backfill = setTimeout(() => {
         if (isPaused())
             return;