@m13v/s4l 1.7.1-rc.4 → 1.7.1-rc.6

package/mcp/dist/index.js

@@ -22,7 +22,7 @@ import fs from "node:fs";
 import { repoDir, runPython, run, readPlan, writePlan, planPath, } from "./repo.js";
 import { applySetup, resolveProject, personaReady, listManagedProjectStatus, listProjectSettings, ensureShortLinksDefault, ensurePersonaProject, findPersonaProject, REQUIRED_FIELDS, RECOMMENDED_FIELDS, configPath, normalizeStringList, } from "./setup.js";
 import { xStatus, xConnect, xDetectSources, xScanProfile, summarizeXAuth } from "./twitterAuth.js";
-import { startProvisioning, isProvisioning, readProgress, runtimeReady, readRuntime, resolvePython, resolveChrome, ensureMenubar, menubarRunning, clearMenubarStop, ensurePipelineCurrent, ensureRuntimeProvisioned, } from "./runtime.js";
+import { startProvisioning, isProvisioning, readProgress, runtimeReady, readRuntime, resolvePython, resolveChrome, ensureMenubar, menubarRunning, clearMenubarStop, ensurePipelineCurrent, ensureRuntimeProvisioned, retryProvisionIfStalled, } from "./runtime.js";
 import { blockOnboardingMilestone, completeOnboardingMilestone, ensureDoctorPhase, onboardingLedger, onboardingSnapshot, recordOnboardingAttempt, runDoctorPhase, } from "./onboarding.js";
 import { VERSION, versionStatus, latestPublishedVersion } from "./version.js";
 import { initSentry, sendHeartbeat, sendStateSnapshot, captureError, flushSentry, startLogStreaming, flushLogs, logLine } from "./telemetry.js";
@@ -2465,12 +2465,21 @@ tool("runtime", {
         });
     }
     // ---- status (default): runtime install snapshot -----------------------
-    const snapshot = runtimeSnapshot();
+    let snapshot = runtimeSnapshot();
     if (snapshot.runtime_ready) {
         completeOnboardingMilestone("runtime_ready");
     }
     else if (snapshot.progress?.done && !snapshot.progress.ok) {
-        blockOnboardingMilestone("runtime_ready", "runtime_install_failed", snapshot.progress.error || "Runtime installation failed", { outcome: "failed" });
+        // A prior provision failed. Kick a bounded auto-retry so status polling
+        // self-heals a transient failure instead of parking until the next boot;
+        // the provisioner cleans its own partial artifacts, so a retry is safe.
+        // Only surface the failure to the onboarding ledger once retries are spent.
+        if (retryProvisionIfStalled()) {
+            snapshot = runtimeSnapshot(); // reflect the restarted, in-flight run
+        }
+        else {
+            blockOnboardingMilestone("runtime_ready", "runtime_install_failed", snapshot.progress.error || "Runtime installation failed", { outcome: "failed" });
+        }
     }
     return jsonContent({
         ...snapshot,

package/mcp/dist/runtime.js

@@ -509,12 +509,57 @@ export function startProvisioning() {
     if (!inFlight) {
         const progress = freshProgress();
         writeProgress(progress);
+        // Heartbeat: the long download steps (Chromium ~150MB, Google Chrome DMG)
+        // don't call setStep for minutes, so the progress file's updated_at froze
+        // and pollers couldn't tell "slow" from "hung." Re-stamp updated_at on a
+        // timer while the run is live so status always shows real motion.
+        const heartbeat = setInterval(() => {
+            try {
+                if (!progress.done)
+                    writeProgress(progress);
+            }
+            catch {
+                /* best effort; never let the heartbeat throw into the timer */
+            }
+        }, 15000);
+        if (typeof heartbeat.unref === "function")
+            heartbeat.unref();
         inFlight = provision(progress).finally(() => {
+            clearInterval(heartbeat);
             inFlight = null;
         });
     }
     return readProgress() ?? freshProgress();
 }
+// Bounded auto-retry for a provision that ended in failure. Called from the
+// runtime `status` handler on each poll: if the last run failed (done && !ok)
+// and nothing is in flight, kick a fresh run so a TRANSIENT failure (a dropped
+// Chromium download, a flaky DMG mount) self-heals during normal status polling
+// instead of parking until the next server boot. The venv/harness steps clean
+// their own partial artifacts, so a retry starts from a clean slate. Capped so a
+// genuinely broken environment (no network, no disk) surfaces the error instead
+// of looping forever. Returns true if it started a retry.
+let autoRetryCount = 0;
+const MAX_AUTO_RETRIES = 3;
+export function retryProvisionIfStalled() {
+    try {
+        if (runtimeReady())
+            return false;
+        if (isProvisioning())
+            return false;
+        const p = readProgress();
+        if (!(p && p.done && !p.ok))
+            return false; // only retry a real failure
+        if (autoRetryCount >= MAX_AUTO_RETRIES)
+            return false;
+        autoRetryCount += 1;
+        startProvisioning();
+        return true;
+    }
+    catch {
+        return false; // best-effort; must never break a status poll
+    }
+}
 // Boot-time deterministic provisioning: bring the owned runtime to ready on
 // every server start WITHOUT relying on the agent to call `runtime
 // action:'install'`. Called from main() on every server start, which the host
@@ -548,6 +593,9 @@ async function provision(progress) {
     const setStep = (id, status, detail) => {
         const st = progress.steps.find((s) => s.id === id);
         if (st) {
+            if (status === "running" && st.status !== "running") {
+                st.started_at = new Date().toISOString();
+            }
             st.status = status;
             if (detail !== undefined)
                 st.detail = detail;
@@ -658,9 +706,25 @@ async function provision(progress) {
     }
     setStep("python", "done");
     // --- Step 3: owned venv ---------------------------------------------------
+    // A prior aborted run can leave a PARTIAL .venv (dir created, but the
+    // interpreter symlink never landed because the standalone-Python download was
+    // cut off). `uv venv` refuses a non-empty target, so every retry then failed
+    // identically and the ONLY escape was a human `rm -rf .venv` — the single
+    // non-idempotent step that turned a 5-minute install into an hour. Treat a
+    // venv with no interpreter as garbage and clear it first (same defensive idiom
+    // Step 0 uses for a half-unpacked repo), and pass --clear so uv rebuilds
+    // cleanly. This makes re-provision fully self-healing.
     setStep("venv", "running");
     {
-        const r = await sh(uv, ["venv", "--python", PYTHON_VERSION, VENV_DIR], {
+        if (fs.existsSync(VENV_DIR) && !fs.existsSync(VENV_PYTHON)) {
+            try {
+                fs.rmSync(VENV_DIR, { recursive: true, force: true });
+            }
+            catch {
+                /* best effort; --clear below is the second line of defense */
+            }
+        }
+        const r = await sh(uv, ["venv", "--clear", "--python", PYTHON_VERSION, VENV_DIR], {
             env: uvEnv,
             timeoutMs: 120000,
         });
@@ -714,6 +778,19 @@ async function provision(progress) {
     // draft_cycle returned "no candidates". This brings .mcpb to parity with npm.
     setStep("harness", "running");
     {
+        // Retry-safety: a clone cut off mid-way leaves HARNESS_DIR present but with
+        // no .git, so the "clone if absent" check below skips it and the fetch/reset
+        // then fail forever against a broken checkout — the same partial-artifact
+        // deadlock the venv step had. Treat a non-git HARNESS_DIR as garbage and
+        // rebuild it.
+        if (fs.existsSync(HARNESS_DIR) && !fs.existsSync(path.join(HARNESS_DIR, ".git"))) {
+            try {
+                fs.rmSync(HARNESS_DIR, { recursive: true, force: true });
+            }
+            catch {
+                /* best effort */
+            }
+        }
         // Clone if absent (mkdir parent first), else reuse the checkout.
         if (!fs.existsSync(HARNESS_DIR)) {
             fs.mkdirSync(path.dirname(HARNESS_DIR), { recursive: true });

package/mcp/dist/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.7.1-rc.4",
-  "installedAt": "2026-07-07T21:09:29.839Z"
+  "version": "1.7.1-rc.6",
+  "installedAt": "2026-07-07T21:25:16.877Z"
 }

package/mcp/install.mjs

@@ -14,6 +14,8 @@ import path from "node:path";
 
 const SERVER_KEY = "social-autoposter";
 const UNINSTALL = process.argv.includes("--uninstall");
+const CHANNEL_STAGING = process.argv.includes("--channel-staging");
+const CHANNEL_STABLE = process.argv.includes("--channel-stable");
 
 // ---- resolve the absolute paths we want pinned into the spawn env ----------
 const here = path.dirname(new URL(import.meta.url).pathname);
@@ -135,6 +137,19 @@ for (const t of targets) {
   }
 }
 
+// Set release channel if requested
+if (!UNINSTALL && (CHANNEL_STAGING || CHANNEL_STABLE)) {
+  const stateDir = path.join(home, ".social-autoposter-mcp");
+  const channel = CHANNEL_STAGING ? "staging" : "stable";
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    writeJson(path.join(stateDir, "channel.json"), { channel });
+    console.log(`✓ Release channel set to: ${channel}`);
+  } catch (err) {
+    console.error(`✗ Failed to set channel: ${err.message}`);
+  }
+}
+
 console.log("");
 if (ok === targets.length) {
   if (UNINSTALL) {

package/mcp/manifest.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "social-autoposter",
   "display_name": "S4L",
-  "version": "1.7.1-rc.4",
+  "version": "1.7.1-rc.6",
   "description": "Draft, review, approve, and autopilot X/Twitter posts.",
   "long_description": "## **⚠️ The disclaimer above is generic Claude boilerplate.** Anthropic shows the same warning on every plugin regardless of what it does; any plugin has the same level of access as any app you download from the internet.\n\nS4L is an open source product developed by Mediar.ai Incorporated, a VC-backed San Francisco-based startup.\n\nTo get started:\n\n1\\. Copy this prompt: **Set me up on S4L plugin end to end**\n\n2\\. Quit with CMD+Q, reopen Claude, paste into a new chat.\n\nWhat happens next:\n\n* About every 5 minutes S4L scans X for posts that match your topics and drafts replies in your voice.\n* Drafts show up as review cards, usually the first within a few minutes. Nothing is posted automatically; you approve each one.\n* Posting autopilot stays off until you explicitly turn it on.",
   "author": {

package/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/s4l-mcp",
-  "version": "1.7.1-rc.4",
+  "version": "1.7.1-rc.6",
   "private": true,
   "description": "Desktop MCP client for social-autoposter (X/Twitter rail): manual draft/review/approve loop, autopilot control, and stats. Thin wrapper over the existing pipeline scripts.",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/s4l",
-  "version": "1.7.1-rc.4",
+  "version": "1.7.1-rc.6",
   "description": "Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Install as a Claude Code agent skill.",
   "bin": {
     "social-autoposter": "bin/cli.js",

package/scripts/get-latest-staging-mcpb.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Get the permanent download URL for the latest S4L staging release (.mcpb).
+# Usage:
+#   bash scripts/get-latest-staging-mcpb.sh [--download] [--channel] [--path]
+#
+# Options:
+#   --download    Download the .mcpb to current directory (instead of just printing URL)
+#   --channel     Also set the local channel to staging after download
+#   --path        Print the download path instead of the URL (for scripts)
+
+set -euo pipefail
+
+DO_DOWNLOAD=0
+DO_CHANNEL=0
+DO_PATH=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --download) DO_DOWNLOAD=1; shift ;;
+    --channel) DO_CHANNEL=1; shift ;;
+    --path) DO_PATH=1; shift ;;
+    *) echo "Unknown option: $1"; exit 1 ;;
+  esac
+done
+
+# Fetch the latest pre-release from GitHub API (first page, per_page=1 for speed)
+# Response is a JSON array; use python to extract the first object
+RELEASE_DATA=$(curl -fsS "https://api.github.com/repos/m13v/s4l/releases?per_page=1&pre_release=true" 2>/dev/null | python3 -c "import sys, json; data=json.load(sys.stdin); r=data[0] if data else {}; print(json.dumps(r))")
+
+# Extract version and download URL using python for reliable JSON parsing
+LATEST_TAG=$(echo "$RELEASE_DATA" | python3 -c "import sys, json; data=json.load(sys.stdin); print(data.get('tag_name', ''))" 2>/dev/null)
+MCPB_URL=$(echo "$RELEASE_DATA" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+for asset in data.get('assets', []):
+    if 'social-autoposter.mcpb' in asset.get('name', ''):
+        print(asset.get('browser_download_url', ''))
+        break
+" 2>/dev/null)
+
+if [ -z "$LATEST_TAG" ] || [ -z "$MCPB_URL" ]; then
+  echo "Error: Could not find latest staging release" >&2
+  exit 1
+fi
+
+if [ "$DO_PATH" -eq 1 ]; then
+  # Return the tag only (for scripting)
+  echo "$LATEST_TAG"
+  exit 0
+fi
+
+if [ "$DO_DOWNLOAD" -eq 1 ]; then
+  FILENAME="social-autoposter-${LATEST_TAG}.mcpb"
+  echo "Downloading $FILENAME from $MCPB_URL" >&2
+  curl -fL "$MCPB_URL" -o "$FILENAME"
+  echo "$FILENAME"
+
+  if [ "$DO_CHANNEL" -eq 1 ]; then
+    STATE_DIR="${S4L_STATE_DIR:-$HOME/.social-autoposter-mcp}"
+    mkdir -p "$STATE_DIR"
+    echo '{"channel":"staging"}' > "$STATE_DIR/channel.json"
+    echo "✓ Channel set to staging" >&2
+  fi
+else
+  # Just print the URL
+  echo "$MCPB_URL"
+fi

package/scripts/reset-test-machine.sh

@@ -17,9 +17,12 @@
 #              disturbing the rest of the environment.
 #   --deep     FULL NUKE — the plugin reset above PLUS the shared layer it touches:
 #              per-agent Chrome profiles + cookies (reddit/linkedin/twitter), the
-#              browser-harness backend, and the packaged toolchain (uv binary, uv
-#              cache, Chromium ~1.7G). Other tools that rely on uv/Chromium
-#              re-provision afterward. Use to reproduce a true bare-metal box.
+#              browser-harness backend, the packaged toolchain (uv binary + uv
+#              data/cache, Chromium ~1.7G), the uv PATH shim in your shell rc, the
+#              real Google Chrome.app the provisioner installs, and Google's
+#              Keystone updater. Reproduces a genuinely bare-metal box (as if S4L
+#              had never run). Other tools that rely on uv/Chrome/Chromium
+#              re-provision afterward — intended for DEDICATED test machines.
 #
 # Usage:
 #   scripts/reset-test-machine.sh            # dry run: print what the plugin reset WOULD remove
@@ -205,6 +208,27 @@ echo "[1] MCP state dir (uv-owned python, venv, materialized repo, runtime.json,
 rm_path "$HOME_DIR/.social-autoposter-mcp" "state"
 echo
 
+# ---- 1a. compat symlink ~/social-autoposter -> materialized repo -----------
+# The .mcpb provisioner plants ~/social-autoposter as a symlink INTO the state
+# dir (so the pipeline's hardcoded $HOME/social-autoposter paths resolve). The
+# state-dir wipe in [1] leaves it DANGLING. Remove it — but ONLY when it is a
+# symlink resolving into .social-autoposter-mcp, so a developer's real clone (or
+# their own ~/social-autoposter symlink to a working tree) is never touched.
+echo "[1a] compat symlink ~/social-autoposter (plugin-planted)"
+SA_LINK="$HOME_DIR/social-autoposter"
+if [ -L "$SA_LINK" ]; then
+  SA_TARGET="$(readlink "$SA_LINK" 2>/dev/null || true)"
+  case "$SA_TARGET" in
+    *.social-autoposter-mcp/*|*.social-autoposter-mcp) rm_path "$SA_LINK" "compat-symlink" ;;
+    *) echo "  (leaving $SA_LINK -> $SA_TARGET — not a plugin-planted symlink)" ;;
+  esac
+elif [ -e "$SA_LINK" ]; then
+  echo "  (leaving $SA_LINK — a real directory/clone, not a plugin-planted symlink)"
+else
+  echo "  (no ~/social-autoposter symlink)"
+fi
+echo
+
 # ---- 1b. Claude Desktop .mcpb extension -----------------------------------
 # A .mcpb (Desktop) install scatters THREE artifacts under ~/Library/Application
 # Support/Claude/, NONE of which live in the state dir removed in [1]: the
@@ -532,6 +556,23 @@ if [ "$DEEP" -eq 1 ]; then
   rm_path "$HOME_DIR/.local/bin/uv"                "uv-bin"
   rm_path "$HOME_DIR/.local/bin/uvx"               "uvx-bin"
   rm_path "$HOME_DIR/.cache/uv"                    "uv-cache"
+  # uv's DATA dir (installed standalone Pythons + tool venvs) and its PATH shim
+  # survive the bin removal — a bare box has neither. The uv installer also
+  # appends `. "$HOME/.local/bin/env"` to the shell rc files; strip that exact
+  # line so no uv PATH shim lingers.
+  rm_path "$HOME_DIR/.local/share/uv"             "uv-data"
+  rm_path "$HOME_DIR/.local/bin/env"              "uv-env-script"
+  for rc in "$HOME_DIR/.zshrc" "$HOME_DIR/.zprofile" "$HOME_DIR/.profile" \
+            "$HOME_DIR/.bash_profile" "$HOME_DIR/.bashrc"; do
+    [ -f "$rc" ] || continue
+    if grep -q '\.local/bin/env' "$rc" 2>/dev/null; then
+      echo "  edit    strip uv env-shim line from $rc"
+      if [ "$DRY" -eq 0 ]; then
+        cp "$rc" "$rc.bak" 2>/dev/null || true
+        grep -v '\.local/bin/env' "$rc" > "$rc.tmp" 2>/dev/null && mv "$rc.tmp" "$rc"
+      fi
+    fi
+  done
   echo "  WARN    --deep removed uv + ms-playwright; other tools on this machine that rely on them will re-provision."
 else
   echo "  (left uv + ~/Library/Caches/ms-playwright + ~/.cache/uv in place)"
@@ -539,6 +580,47 @@ fi
 fi
 echo
 
+# ---- 6b. DEEP: packaged Google Chrome + its Keystone updater ----------------
+# The provisioner installs a REAL Google Chrome.app (runtime.ts Step 7) — the
+# browser the scanner drives over CDP — that NO other reset step removes, plus
+# installing it drops Google's Keystone auto-updater (LaunchAgents + support
+# dirs). A bare box had none of this. --deep removes all of it so the Chrome
+# install step is exercised fresh. NOTE: this touches the machine's Google Chrome
+# globally, not just S4L — hence --deep / test-box only.
+if [ "$PLUGIN_ONLY" -eq 1 ]; then
+  echo "[6b] packaged Google Chrome + Keystone updater — skipped (plugin reset; pass --deep to remove)"
+else
+  echo "[6b] packaged Google Chrome + Keystone updater — $([ "$DEEP" -eq 1 ] && echo ENABLED || echo 'skipped (pass --deep)')"
+  if [ "$DEEP" -eq 1 ]; then
+    # Stop Chrome + unload the Keystone/updater agents before deleting their plists.
+    if [ "$DRY" -eq 0 ]; then
+      pkill -f 'Google Chrome' 2>/dev/null || true
+      for lbl in com.google.keystone.agent com.google.keystone.xpcservice com.google.GoogleUpdater.wake; do
+        launchctl bootout "gui/$(id -u)/$lbl" 2>/dev/null || true
+      done
+    fi
+    rm_path "/Applications/Google Chrome.app"            "google-chrome"
+    rm_path "$HOME_DIR/Applications/Google Chrome.app"   "google-chrome-user"
+    for p in \
+      "$HOME_DIR/Library/Application Support/Google" \
+      "$HOME_DIR/Library/Google" \
+      "$HOME_DIR/Library/Caches/Google" \
+      "$HOME_DIR/Library/Caches/com.google.Chrome" \
+      "$HOME_DIR/Library/Caches/com.google.Keystone" \
+      "$HOME_DIR/Library/LaunchAgents/com.google.keystone.agent.plist" \
+      "$HOME_DIR/Library/LaunchAgents/com.google.keystone.xpcservice.plist" \
+      "$HOME_DIR/Library/LaunchAgents/com.google.GoogleUpdater.wake.plist" \
+      "$HOME_DIR/Library/LaunchAgents/com.google.GoogleUpdater.plist"; do
+      rm_path "$p" "google"
+    done
+    for f in "$HOME_DIR"/Library/Preferences/com.google.Chrome*.plist; do
+      [ -e "$f" ] && rm_path "$f" "google-pref"
+    done
+    echo "  WARN    --deep removed Google Chrome + Keystone updater machine-wide."
+  fi
+fi
+echo
+
 # ---- 7. settle & verify (defeat Claude auto-relaunch resurrection) ---------
 # Claude Desktop can RELAUNCH after step [0] — on auto-update (ShipIt), a macOS
 # re-open, or a login item — and a relaunched host re-materializes a skeleton

package/scripts/set-channel.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Set the S4L release channel (stable or staging).
+# Usage:
+#   bash scripts/set-channel.sh stable   # track stable releases only (default)
+#   bash scripts/set-channel.sh staging  # track staging releases (pre-releases)
+
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "Usage: bash scripts/set-channel.sh <stable|staging>" >&2
+  exit 1
+fi
+
+CHANNEL="$1"
+if [ "$CHANNEL" != "stable" ] && [ "$CHANNEL" != "staging" ]; then
+  echo "Error: channel must be 'stable' or 'staging'" >&2
+  exit 1
+fi
+
+STATE_DIR="${S4L_STATE_DIR:-$HOME/.social-autoposter-mcp}"
+mkdir -p "$STATE_DIR"
+echo "{\"channel\":\"$CHANNEL\"}" > "$STATE_DIR/channel.json"
+
+echo "✓ Release channel set to: $CHANNEL"
+if [ "$CHANNEL" = "staging" ]; then
+  echo "  Will now track pre-releases (rc.N builds). Next update check pulls the latest staging release."
+else
+  echo "  Will now track stable releases only. Next update check pulls the latest stable release."
+fi

package/scripts/setup_twitter_auth.py

@@ -1027,17 +1027,50 @@ def cmd_connect(args) -> dict:
     except Exception as e:
         return {"ok": False, "connected": False, "state": "error", "error": str(e), "cdp": CDP}
 
-    # 1b. Headless + Keychain pre-flight (#3 + #4, added 2026-06-02).
-    # On macOS, copy_browser_cookies.py needs to read the per-browser Safe
-    # Storage entry from the OS keychain. SSH-invoked processes get
-    # errSecAuthFailed silently — no prompt, no warning. We probe up front so
-    # the user sees "your keychain is locked / run unlock-keychain" instead of
-    # the misleading "log in manually" cascade.
-    headless = _is_headless()
-    if headless:
-        # Probe with the first source's likely browser label. We don't know
-        # which source will succeed yet, so probe Chrome (the autoposter
-        # default); if that's denied, all the AUTO_SOURCES will be too.
+    # 1b. Choose the connection PATH before doing any keychain work. There are
+    #     two mutually exclusive paths, and only one of them touches the keychain:
+    #       - IMPORT: copy an existing x.com session out of the user's everyday
+    #         browser. This reads that browser's "Safe Storage" key from the macOS
+    #         Keychain, so it (and ONLY it) is gated by the headless keychain
+    #         preflight below.
+    #       - MANUAL LOGIN: open the managed Chrome's own login page and let the
+    #         user sign in by hand. Reads NO keychain and needs NO everyday-browser
+    #         session, so it must NEVER be blocked by the keychain preflight.
+    #     Auto-import is only possible when some installed browser actually holds
+    #     an x.com session. On a fresh or remote/headless box there is nothing to
+    #     import, so gating manual login behind the keychain check dead-ended setup
+    #     on "keychain locked" even though there was no session to copy anyway
+    #     (the exact wedge that stalled the macstadium test box). We now skip
+    #     straight to manual login whenever there's nothing to import.
+    #
+    #     Source selection:
+    #       - explicit --source X   -> just that one (one keychain prompt)
+    #       - --source all          -> the full chrome/arc/brave/edge sweep (legacy)
+    #       - no --source (default) -> the browser(s) that ACTUALLY hold an x.com
+    #         session, so we prompt the keychain for exactly the right one.
+    if args.source == "all":
+        sources = AUTO_SOURCES
+        has_importable = True
+    elif args.source:
+        sources = [args.source]
+        has_importable = True
+    else:
+        _srcs = _list_sources()
+        _with_session = [s["spec"] for s in _srcs if s.get("x_session")]
+        sources = _with_session or ["chrome:Default"]
+        has_importable = bool(_with_session)
+
+    manual_login = bool(getattr(args, "manual_login", False))
+    # Attempt an auto-import ONLY when the user didn't force manual login AND
+    # there is a real session to copy. Otherwise fall through to manual login.
+    will_import = has_importable and not manual_login
+
+    # 1c. Headless + Keychain pre-flight (#3 + #4, added 2026-06-02) — relevant
+    #     ONLY to the import path. copy_browser_cookies.py must read the per-browser
+    #     Safe Storage entry from the OS keychain; SSH/launchd-invoked processes get
+    #     errSecAuthFailed silently (no prompt). The manual-login path skips this.
+    if will_import and _is_headless():
+        # Probe Chrome (the autoposter default); if that's denied, the rest are too.
         kc_ok, kc_detail = _keychain_safe_storage_ok("Chrome")
         if not kc_ok:
             return {
@@ -1053,28 +1086,17 @@ def cmd_connect(args) -> dict:
                     "or another headless context). No GUI prompt is shown for this — macOS "
                     "denies access silently. To fix, run this once in the same session:\n"
                     "  security unlock-keychain ~/Library/Keychains/login.keychain-db\n"
-                    "Then re-run connect_x. If you're on the autoposter machine via SSH, you "
-                    "may also need to run it before every fresh shell, or persist with "
-                    "`security set-keychain-settings -lut 0`."
+                    "Then re-run connect_x. Or connect X with manual login instead — that "
+                    "signs in directly in the autoposter's own browser and needs no keychain."
                 ),
                 "remediation_cmd": "security unlock-keychain ~/Library/Keychains/login.keychain-db",
                 "cdp": CDP,
             }
 
-    # 2. Import from the user's everyday browser.
-    #    - explicit --source X        -> just that one (one keychain prompt)
-    #    - --source all               -> the full chrome/arc/brave/edge sweep (legacy)
-    #    - no --source (the default)  -> auto-pick the browser(s) that ACTUALLY
-    #      hold an x.com session, so we prompt the keychain for exactly the right
-    #      one instead of blindly walking all four and prompting per browser.
-    if args.source == "all":
-        sources = AUTO_SOURCES
-    elif args.source:
-        sources = [args.source]
-    else:
-        sources = _auto_pick_sources()
+    # 2. Import from the user's everyday browser (skipped entirely when we're on
+    #    the manual-login path — `will_import` False makes this loop a no-op).
     attempts = []
-    for src in sources:
+    for src in (sources if will_import else []):
         res = _import_from(src)
         copied = res.get("stdout", "")
         detail = copied or res.get("error") or res.get("stderr")
@@ -1139,8 +1161,15 @@ def cmd_connect(args) -> dict:
     rolled_up_error_type = (
         next(iter(distinct_error_types)) if len(distinct_error_types) == 1 else None
     )
-    manual_login = bool(getattr(args, "manual_login", False))
-    open_login = manual_login or rolled_up_error_type == "keychain_acl_denied"
+    # Open a focused login window when the user asked for manual login, when the
+    # keychain prompt was denied (import can't proceed), OR when there was nothing
+    # to import in the first place — in that last case manual login is the ONLY
+    # path that can work, so we must open the window rather than dead-end.
+    open_login = (
+        manual_login
+        or not will_import
+        or rolled_up_error_type == "keychain_acl_denied"
+    )
 
     shown = False
     if open_login:
@@ -1156,7 +1185,7 @@ def cmd_connect(args) -> dict:
         # That race is what made setup misreport the handle as "missing." If the
         # cookie appears, fall through to the same connected/persist/handle path the
         # auto-import success branch uses.
-        login_wait = getattr(args, "login_wait", 90.0)
+        login_wait = getattr(args, "login_wait", 300.0)
         if login_wait and login_wait > 0 and _poll_for_login(timeout=login_wait):
             try:
                 if _is_session_valid():
@@ -1197,16 +1226,23 @@ def cmd_connect(args) -> dict:
         )
         extra["remediation"] = "rerun_connect_x_and_click_allow"
     elif open_login:
-        # Explicit --manual-login: a window is open and we waited; they just
-        # haven't finished signing in yet.
+        # Manual login: either the caller asked for it (--manual-login) or there
+        # was no existing X session anywhere to import, so this is the only path.
+        # A focused login window is open and we waited; they just haven't finished
+        # signing in yet.
+        _why = (
+            "" if will_import
+            else "No existing X session was found in your everyday browser to import, so "
+        )
+        _tried = (" (Auto-import tried: " + ", ".join(sources) + ".)") if will_import else ""
         note = (
-            "A Chrome window for the autoposter is open at the X login page"
+            _why
+            + "a Chrome window for the autoposter is open at the X login page"
             + ("" if shown else " (if you don't see it, look for a 'Google Chrome' window)")
             + " and you are NOT logged in yet. Log in there yourself — username, password, "
             "and 2FA if prompted — in that window. When your X home timeline shows, ask me "
             "to confirm and I'll re-check (run connect_x again). The session is saved to the "
-            "autoposter's own profile, so this is a one-time step. "
-            "(Auto-import tried: " + ", ".join(sources) + ".)"
+            "autoposter's own profile, so this is a one-time step." + _tried
         )
     else:
         # Auto-import failed for a non-deny reason and the user did NOT ask for
@@ -1294,10 +1330,12 @@ def main() -> int:
                         "the login window only opens when the user DENIED the keychain "
                         "prompt; every other auto-import failure returns needs_login "
                         "without popping an unexpected browser window.")
-    c.add_argument("--login-wait", type=float, default=90.0,
+    c.add_argument("--login-wait", type=float, default=300.0,
                    help="Seconds to wait for a MANUAL login to complete before "
-                        "returning needs_login (default 90; 0 disables the wait). "
-                        "Prevents the detection race that misreports the handle as missing.")
+                        "returning needs_login (default 300; 0 disables the wait). "
+                        "A human finding the on-screen/VNC window plus password + 2FA "
+                        "routinely exceeds 90s, so the wait is generous. Prevents the "
+                        "detection race that misreports the handle as missing.")
     args = ap.parse_args()
 
     if args.cmd == "detect-sources":