frigatebird 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.0 - 2026-02-09
+
+### Added
+- Long-form article publishing command: `article <title> [body] [--body-file <path>]`.
+- Dedicated live mutation CI workflow: `.github/workflows/live-e2e.yml`.
+- Browser session identity hardening with multi-selector `whoami` fallback coverage.
+- Additional Playwright client method tests for retweet and mutation resilience.
+
+### Changed
+- Mutation `retweet` flow now uses bounded resilient click handling and explicit completion checks.
+- Read-only fixture e2e was optimized to run significantly faster while preserving command coverage.
+- CI and release verification workflows now include fixture e2e smoke runs.
+- Live mutation e2e now requires `FRIGATEBIRD_LIVE_LIST_NAME` and always validates list `add/remove/batch` paths.
+
+### Tests
+- Expanded unit coverage for session identity parsing and retweet mutation branches.
+- Verified end-to-end live mutation flow (tweet/reply/like/retweet/follow/list mutations) with Safari cookie source.
+
 ## 0.2.0 - 2026-02-08
 
 ### Added

package/README.md

@@ -1,28 +1,21 @@
-# frigatebird
+# frigatebird 🐦 — resilient X CLI for posting, articles, replies, reading, and list automation
 
-`frigatebird` is a Playwright-first X CLI that targets `bird` command parity and pulls in `x-list-manager` list automation.
+![Frigatebird logo](images/frigatebird_logo.jpeg)
 
-It keeps the `bird` UX, but replaces deprecated/non-open GraphQL internals with browser automation against X web UI.
+`frigatebird` is a Playwright-first X CLI that preserves the familiar `bird` command-line experience while running on browser automation instead of private GraphQL internals.
 
-## Intent
+## Why This Exists
 
-Frigatebird exists to keep the `bird` workflow alive after deprecation and closure:
+`bird` set a high bar for fast, scriptable X workflows. After deprecation and de-open-sourcing, teams still needed the same CLI ergonomics without depending on internal API behavior.
 
-- Preserve familiar command ergonomics from `bird`.
-- Keep zero-API-key operation via local browser session cookies.
-- Add first-class list management from `x-list-manager` (`add`, `remove`, `batch`, `refresh`).
-- Provide one CLI for read workflows, account actions, and list operations.
+`frigatebird` is the continuity path:
+- Keep the `bird`-style command surface.
+- Keep API-key-free operation via browser session cookies.
+- Keep practical day-to-day workflows for posting, reading, follows, lists, and timeline operations.
 
-## Frigatebird vs Bird
+## Disclaimer
 
-| Area | `bird` | `frigatebird` |
-|---|---|---|
-| Primary engine | X internal GraphQL + query IDs | Playwright web automation |
-| API keys | Not required | Not required |
-| Auth | Browser cookies / env tokens | Browser cookies / env tokens |
-| `query-ids` | Active GraphQL cache/refresh behavior | Compatibility command in Playwright mode |
-| List manager commands | External project (`x-list-manager`) | Built in (`refresh`, `add`, `remove`, `batch`) |
-| Selector/query fragility | Query ID churn | DOM selector churn |
+Frigatebird automates X’s web UI and relies on selectors/flows that X can change at any time. Expect occasional breakage when X ships UI changes.
 
 ## Install
 
@@ -31,63 +24,91 @@ npm install
 npx playwright install chromium
 ```
 
-## Usage
+When published to npm:
 
 ```bash
-# One-off
-npx tsx src/cli.ts whoami
+npm install -g frigatebird
+```
 
-# Built binary
-npm run build
-node dist/cli.js --help
+## Quickstart
+
+```bash
+# Show authenticated account
+frigatebird whoami
+
+# Read a tweet (URL or ID)
+frigatebird read https://x.com/user/status/1234567890123456789
+frigatebird 1234567890123456789 --json
+
+# Post and reply
+frigatebird tweet "hello from frigatebird"
+frigatebird reply 1234567890123456789 "thanks"
+
+# Publish a long-form article
+frigatebird article "Launch notes" "Today we shipped..."
+frigatebird article "Draft from file" --body-file ./article.md
+
+# Search and mentions
+frigatebird search "from:openai" -n 5
+frigatebird mentions -n 5
+
+# Lists and list timeline
+frigatebird lists --json
+frigatebird list-timeline 1234567890 -n 20
+
+# Follow graph
+frigatebird following -n 20 --json
+frigatebird followers -n 20 --json
+
+# List membership automation
+frigatebird add "AI News" @openai @anthropicai
+frigatebird remove @openai "AI News"
+frigatebird batch accounts.json
 ```
 
 ## Commands
 
-### bird-style parity commands
-
-- `tweet <text>`
-- `post <text>`
-- `reply <tweet-id-or-url> <text>`
-- `read <tweet-id-or-url> [--json] [--json-full]`
-- `replies <tweet-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `thread <tweet-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `search <query> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `mentions [-u @handle] [-n count] [--json] [--json-full]`
-- `user-tweets <@handle> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `home [-n count] [--following] [--all] [--max-pages n] [--delay ms] [--json] [--json-full]`
-- `bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor str] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--delay ms] [--json] [--json-full]`
-- `unbookmark <tweet-id-or-url...> [--json]`
-- `like <tweet-id-or-url>`
-- `retweet <tweet-id-or-url>`
-- `likes [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `follow <username-or-id>`
-- `unfollow <username-or-id>`
-- `following [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `followers [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `lists [--member-of] [-n count] [--json] [--json-full]`
-- `list` (alias for `lists`)
-- `list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]`
-- `news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json] [--json-full]`
-- `trending` (alias for `news`)
-- `about <@handle> [--json]`
-- `query-ids [--fresh] [--json]` (compatibility mode in Playwright engine)
-- `whoami [--json]`
-- `check`
-- `help [command]`
-
-### x-list-manager parity commands
-
-- `refresh [--json]`
-- `add <listName> <handles...> [--no-headless] [--json]`
-- `remove <handle> <listName> [--no-headless] [--json]`
-- `batch <file.json> [--no-headless] [--json]`
+- `frigatebird tweet "<text>"` — post a tweet.
+- `frigatebird post "<text>"` — alias for `tweet`.
+- `frigatebird article "<title>" [body] [--body-file path]` — publish a long-form article.
+- `frigatebird reply <tweet-id-or-url> "<text>"` — reply to a tweet.
+- `frigatebird read <tweet-id-or-url> [--json] [--json-full]` — read one tweet.
+- `frigatebird <tweet-id-or-url> [--json]` — shorthand for `read`.
+- `frigatebird replies <tweet-id-or-url> [--all] [--max-pages n] [--cursor str] [--delay ms] [-n count] [--json] [--json-full]` — list replies.
+- `frigatebird thread <tweet-id-or-url> [--all] [--max-pages n] [--cursor str] [--delay ms] [-n count] [--json] [--json-full]` — show thread/conversation tweets.
+- `frigatebird search "<query>" [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — search tweets.
+- `frigatebird mentions [--user @handle] [-n count] [--json] [--json-full]` — mention timeline/search.
+- `frigatebird user-tweets <@handle> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — profile tweets.
+- `frigatebird home [-n count] [--following] [--all] [--max-pages n] [--delay ms] [--json] [--json-full]` — home timeline.
+- `frigatebird bookmarks [-n count] [--folder-id id] [--all] [--max-pages n] [--cursor str] [--expand-root-only] [--author-chain] [--author-only] [--full-chain-only] [--include-ancestor-branches] [--include-parent] [--thread-meta] [--sort-chronological] [--delay ms] [--json] [--json-full]` — bookmarks + optional thread expansion.
+- `frigatebird unbookmark <tweet-id-or-url...> [--json]` — remove bookmark(s).
+- `frigatebird like <tweet-id-or-url>` — like a tweet.
+- `frigatebird retweet <tweet-id-or-url>` — repost a tweet.
+- `frigatebird likes [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — liked tweets.
+- `frigatebird follow <username-or-id>` — follow user.
+- `frigatebird unfollow <username-or-id>` — unfollow user.
+- `frigatebird following [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — accounts a user follows.
+- `frigatebird followers [--user userId] [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — accounts following a user.
+- `frigatebird lists [--member-of] [-n count] [--json] [--json-full]` — list your lists.
+- `frigatebird list [--member-of] [-n count] [--json] [--json-full]` — alias for `lists`.
+- `frigatebird list-timeline <list-id-or-url> [-n count] [--all] [--max-pages n] [--cursor str] [--delay ms] [--json] [--json-full]` — timeline for a list.
+- `frigatebird news [-n count] [--ai-only] [--with-tweets] [--tweets-per-item n] [--for-you] [--news-only] [--sports] [--entertainment] [--trending-only] [--json] [--json-full]` — explore/news aggregation.
+- `frigatebird trending` — alias for `news`.
+- `frigatebird about <@handle> [--json]` — profile origin/location metadata.
+- `frigatebird query-ids [--fresh] [--json]` — compatibility command (Playwright mode does not require GraphQL query IDs).
+- `frigatebird whoami [--json]` — active authenticated account.
+- `frigatebird check` — credential/session status.
+- `frigatebird refresh [--json]` — refresh local auth cookie cache.
+- `frigatebird add <listName> <handles...> [--no-headless] [--json]` — add handles to list.
+- `frigatebird remove <handle> <listName> [--no-headless] [--json]` — remove handle from list.
+- `frigatebird batch <file.json> [--no-headless] [--json]` — batch list updates from JSON.
+- `frigatebird help [command]` — command help.
 
 ## Global Options
 
 - `--auth-token <token>`
 - `--ct0 <token>`
-- `--base-url <url>` (testing override, default `https://x.com`)
+- `--base-url <url>` (default `https://x.com`, useful for fixture/e2e)
 - `--cookie-source <chrome|firefox|safari|edge>` (repeatable)
 - `--chrome-profile <name>`
 - `--chrome-profile-dir <path>`
@@ -102,85 +123,99 @@ node dist/cli.js --help
 - `--no-color`
 - `--no-headless`
 
-`tweet` and `reply` both consume `--media`/`--alt`.
-
-Media constraints:
+Media rules:
 - up to 4 attachments
-- only one video
+- one video maximum
 - video cannot be mixed with other media
-- supported extensions: `jpg`, `jpeg`, `png`, `webp`, `gif`, `mp4`, `m4v`, `mov`
+- supported: `jpg`, `jpeg`, `png`, `webp`, `gif`, `mp4`, `m4v`, `mov`
 
-## Config + Env
+## Authentication
+
+Frigatebird uses your existing X web session and cookie credentials. No X API key required.
+
+Resolution order:
+1. CLI flags (`--auth-token`, `--ct0`)
+2. env vars (`AUTH_TOKEN`, `CT0`, fallbacks below)
+3. browser cookie extraction via `@steipete/sweet-cookie`
+
+When `--cookie-source` is explicitly set and differs from cached auth source metadata, Frigatebird clears cached auth and re-resolves cookies from the requested source order.
+
+If auth fails:
+```bash
+frigatebird refresh
+frigatebird check
+frigatebird whoami
+```
+
+## Config (JSON5)
 
 Precedence: **CLI flags > env vars > project config > global config**.
 
 Config files:
-- Global (bird): `~/.config/bird/config.json5`
-- Global (frigatebird): `~/.config/frigatebird/config.json5`
-- Project (bird): `./.birdrc.json5`
-- Project (frigatebird): `./.frigatebirdrc.json5`
+- `~/.config/bird/config.json5`
+- `~/.config/frigatebird/config.json5`
+- `./.birdrc.json5`
+- `./.frigatebirdrc.json5`
 
-Supported config keys:
+Supported keys:
 - `authToken`, `ct0`, `baseUrl`
 - `cookieSource`
 - `chromeProfile`, `chromeProfileDir`, `firefoxProfile`
 - `cookieTimeoutMs`, `timeoutMs`, `quoteDepth`
 
-Supported env vars:
-- Auth: `AUTH_TOKEN`, `CT0`, `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`
-- Cookie source: `BIRD_COOKIE_SOURCE`, `FRIGATEBIRD_COOKIE_SOURCE`
-- Base URL: `BIRD_BASE_URL`, `FRIGATEBIRD_BASE_URL`
-- Profiles: `BIRD_CHROME_PROFILE`, `BIRD_CHROME_PROFILE_DIR`, `BIRD_FIREFOX_PROFILE` (plus `FRIGATEBIRD_*` variants)
-- Timeouts/depth: `BIRD_TIMEOUT_MS`, `BIRD_COOKIE_TIMEOUT_MS`, `BIRD_QUOTE_DEPTH` (plus `FRIGATEBIRD_*` variants)
-- Output: `NO_COLOR`, `BIRD_PLAIN`, `FRIGATEBIRD_PLAIN`
-
-## Shorthand Invocation
+Example:
 
-If first argument is a tweet URL or ID, Frigatebird rewrites to `read`:
-
-```bash
-npx tsx src/cli.ts 1891234567890123456 --json
+```json5
+{
+  cookieSource: ["chrome", "safari"],
+  chromeProfile: "Default",
+  timeoutMs: 20000,
+  quoteDepth: 1
+}
 ```
 
-## Architecture
-
-- `src/cli/`: commander program assembly and global option wiring
-- `src/commands/`: handler layer and output orchestration
-- `src/client/`: `FrigatebirdClient` interface and Playwright implementation
-- `src/browser/`: auth store, session lifecycle, scrape primitives
-- `src/lib/`: identifiers, option parsing, invocation normalization, config, output
-
-## Skills Files
+Environment vars:
+- auth: `AUTH_TOKEN`, `CT0`, `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`
+- cookie source: `BIRD_COOKIE_SOURCE`, `FRIGATEBIRD_COOKIE_SOURCE`
+- base URL: `BIRD_BASE_URL`, `FRIGATEBIRD_BASE_URL`
+- profiles: `BIRD_CHROME_PROFILE`, `BIRD_CHROME_PROFILE_DIR`, `BIRD_FIREFOX_PROFILE` and `FRIGATEBIRD_*` variants
+- timeouts/depth: `BIRD_TIMEOUT_MS`, `BIRD_COOKIE_TIMEOUT_MS`, `BIRD_QUOTE_DEPTH` and `FRIGATEBIRD_*` variants
+- output: `NO_COLOR`, `BIRD_PLAIN`, `FRIGATEBIRD_PLAIN`
 
-Frigatebird now includes skill-oriented project files (same ecosystem style used by `x-list-manager`):
+## Output
 
-- `SKILL.md`: AI-agent usage contract for this CLI
-- `SPEC.md`: technical architecture and command behavior
-- `TASKS.md`: parity/release checklist
+- `--json` gives machine-readable output for read/timeline/list commands.
+- `--json-full` includes raw compatibility payloads where available.
+- `--plain` disables emoji + color for stable scripts.
 
-## Release Readiness
-
-- `CHANGELOG.md` tracks release notes.
-- `RELEASE.md` contains the release checklist and publish flow.
-- GitHub workflows enforce CI + publish gates:
-  - `.github/workflows/ci.yml`
-  - `.github/workflows/release.yml`
-  - npm publish is triggered by GitHub Release `published` events using npm trusted publishing (OIDC, no npm token secret).
-- `npm run release:check` runs lint + build + full tests + coverage.
-- `npm run smoke:pack-install` validates clean install + binary entrypoint from a packed tarball.
-
-## Test
+## Development
 
 ```bash
-npm run test:run
-npm run test:coverage
-npm run test:e2e
+npm install
+npx playwright install chromium
+npm run build
+npm run lint
+npm run test:run        # unit/integration
+npm run test:coverage   # unit/integration + coverage
+npm run test:e2e        # e2e only
+npm run test:e2e:live   # opt-in live mutation e2e (requires env vars below)
+npm run smoke:pack-install
 ```
 
-`test:run` and `test:coverage` run unit/integration suites only.
-`test:e2e` runs end-to-end read-only tests against empty-account fixtures.
+Live mutation e2e env requirements:
+- `FRIGATEBIRD_AUTH_TOKEN`
+- `FRIGATEBIRD_CT0`
+- `FRIGATEBIRD_LIVE_LIST_NAME`
+- optional: `FRIGATEBIRD_LIVE_COOKIE_SOURCE`, `FRIGATEBIRD_LIVE_EXPECTED_HANDLE_PREFIX`, `FRIGATEBIRD_LIVE_TARGET_HANDLE`
+
+## Release
+
+- CI: `.github/workflows/ci.yml`
+- npm publish: `.github/workflows/release.yml` (triggered by GitHub Release `published`, trusted publishing/OIDC)
+- live mutation CI: `.github/workflows/live-e2e.yml` (manual trigger; validates `FRIGATEBIRD_LIVE_LIST_NAME` + auth secrets before running)
+- release checklist: `RELEASE.md`
 
 ## Notes
 
-- Frigatebird automates X web UI and depends on selectors that may change.
-- Some deep `bird` GraphQL-only semantics are represented as compatibility flags in Playwright mode.
+- Selector drift is the primary maintenance cost.
+- `query-ids` is intentionally kept for CLI compatibility with historical `bird` workflows.

package/TASKS.md

@@ -26,4 +26,4 @@
 - [x] Add `CHANGELOG.md`.
 - [x] Add `RELEASE.md` release checklist and publish flow.
 - [x] Add `SKILL.md` + `SPEC.md` + `TASKS.md` for agent-oriented usage.
-- [ ] Add mutation-focused e2e coverage against disposable test accounts (post-release hardening).
+- [x] Add mutation-focused e2e coverage against disposable test accounts, including list add/remove/batch checks.

package/dist/browser/auth-store.js

@@ -1,6 +1,18 @@
 import fs from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
 import { getCookies } from "@steipete/sweet-cookie";
+function parseBrowserSourceList(source) {
+    if (!source.startsWith("browser:"))
+        return null;
+    const suffix = source.slice("browser:".length).trim();
+    if (!suffix)
+        return null;
+    return suffix
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+}
 function normalizeDomain(domain) {
     if (!domain)
         return ".x.com";
@@ -21,10 +33,46 @@ function toPlaywrightCookie(cookie) {
 function mapSource(value) {
     return value;
 }
+function formatError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+const SAFARI_COOKIE_STORE_PATH = path.join(homedir(), "Library", "Containers", "com.apple.Safari", "Data", "Library", "Cookies", "Cookies.binarycookies");
 export class AuthStore {
     authFile;
-    constructor(authFile = path.join(process.cwd(), "auth.json")) {
+    cookieExtractor;
+    lastDiagnostics = [];
+    constructor(authFile = path.join(process.cwd(), "auth.json"), cookieExtractor = getCookies) {
         this.authFile = authFile;
+        this.cookieExtractor = cookieExtractor;
+    }
+    getLastDiagnostics() {
+        return [...this.lastDiagnostics];
+    }
+    setDiagnostics(messages) {
+        this.lastDiagnostics = Array.from(new Set(messages.filter(Boolean)));
+    }
+    diagnoseSafariCookieAccess() {
+        if (process.platform !== "darwin")
+            return [];
+        if (!fs.existsSync(SAFARI_COOKIE_STORE_PATH)) {
+            return [`Safari cookie store not found at ${SAFARI_COOKIE_STORE_PATH}.`];
+        }
+        try {
+            const fileDescriptor = fs.openSync(SAFARI_COOKIE_STORE_PATH, "r");
+            fs.closeSync(fileDescriptor);
+            return [];
+        }
+        catch (error) {
+            const nodeError = error;
+            if (nodeError.code === "EPERM" || nodeError.code === "EACCES") {
+                return [
+                    "Safari cookies are blocked by macOS privacy controls for this process. Grant Full Disk Access to your terminal/Codex app, then retry.",
+                ];
+            }
+            return [`Safari cookie store could not be read: ${formatError(error)}.`];
+        }
     }
     loadFromDisk() {
         if (!fs.existsSync(this.authFile))
@@ -55,21 +103,53 @@ export class AuthStore {
             fs.unlinkSync(this.authFile);
         }
     }
+    isSavedSourceCompatible(source, options) {
+        const savedBrowsers = parseBrowserSourceList(source);
+        if (!savedBrowsers)
+            return true;
+        const requested = options.cookieSource;
+        if (savedBrowsers.length !== requested.length)
+            return false;
+        return savedBrowsers.every((value, index) => value === requested[index]);
+    }
     async extractFromBrowser(options) {
         const browsers = options.cookieSource.map(mapSource);
-        const extraction = await getCookies({
-            url: "https://x.com",
-            browsers,
-            chromeProfile: options.chromeProfileDir ?? options.chromeProfile,
-            firefoxProfile: options.firefoxProfile,
-            timeoutMs: options.cookieTimeout,
-        }).catch(() => null);
+        let extraction = null;
+        try {
+            extraction = await this.cookieExtractor({
+                url: "https://x.com",
+                browsers,
+                chromeProfile: options.chromeProfileDir ?? options.chromeProfile,
+                firefoxProfile: options.firefoxProfile,
+                timeoutMs: options.cookieTimeout,
+            });
+        }
+        catch (error) {
+            const diagnostics = [
+                `Browser cookie extraction failed: ${formatError(error)}.`,
+            ];
+            if (options.cookieSource.includes("safari")) {
+                diagnostics.push(...this.diagnoseSafariCookieAccess());
+            }
+            this.setDiagnostics(diagnostics);
+            return null;
+        }
         if (!extraction || extraction.cookies.length === 0) {
+            const diagnostics = [
+                `No cookies were extracted from sources: ${options.cookieSource.join(", ")}.`,
+            ];
+            if (options.cookieSource.includes("safari")) {
+                diagnostics.push(...this.diagnoseSafariCookieAccess());
+            }
+            this.setDiagnostics(diagnostics);
             return null;
         }
         const authToken = extraction.cookies.find((cookie) => cookie.name === "auth_token");
         const ct0 = extraction.cookies.find((cookie) => cookie.name === "ct0");
         if (!authToken || !ct0) {
+            this.setDiagnostics([
+                `Cookies were extracted, but required auth cookies are missing (auth_token=${Boolean(authToken)}, ct0=${Boolean(ct0)}).`,
+            ]);
             return null;
         }
         const playwrightCookies = [
@@ -127,19 +207,34 @@ export class AuthStore {
         };
     }
     async resolve(options, forceRefresh = false) {
+        this.setDiagnostics([]);
         const manual = this.fromManualTokens(options);
         if (manual)
             return manual;
+        const sourceOverrideNotes = [];
         if (!forceRefresh) {
             const saved = this.loadFromDisk();
-            if (saved)
-                return saved;
+            if (saved) {
+                if (!options.cookieSourceExplicit ||
+                    this.isSavedSourceCompatible(saved.source, options)) {
+                    return saved;
+                }
+                sourceOverrideNotes.push(`Cached auth source "${saved.source}" was ignored because --cookie-source was explicitly set to "${options.cookieSource.join(",")}".`);
+                this.clear();
+            }
         }
         const extracted = await this.extractFromBrowser(options);
         if (extracted) {
+            this.setDiagnostics([]);
             this.save(extracted.cookies, extracted.source);
             return extracted;
         }
+        if (sourceOverrideNotes.length > 0) {
+            this.setDiagnostics([
+                ...sourceOverrideNotes,
+                ...this.getLastDiagnostics(),
+            ]);
+        }
         return null;
     }
 }

package/dist/browser/session-manager.js

@@ -1,5 +1,64 @@
 import { chromium, } from "playwright";
 import { AuthStore } from "./auth-store.js";
+const HANDLE_PATTERN = /^[A-Za-z0-9_]{1,15}$/;
+const RESERVED_HANDLE_SEGMENTS = new Set([
+    "compose",
+    "download",
+    "explore",
+    "hashtag",
+    "home",
+    "i",
+    "intent",
+    "login",
+    "logout",
+    "messages",
+    "notifications",
+    "search",
+    "settings",
+    "signup",
+    "tos",
+]);
+function normalizeHandleCandidate(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    const handleMatch = trimmed.match(/@([A-Za-z0-9_]{1,15})/);
+    if (handleMatch?.[1])
+        return handleMatch[1];
+    let segment = trimmed;
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+        try {
+            segment = new URL(trimmed).pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (segment.startsWith("/")) {
+        segment = segment.replace(/^\/+/, "").split("/")[0] ?? "";
+    }
+    segment = segment.split("?")[0]?.split("#")[0]?.trim() ?? "";
+    if (!segment)
+        return null;
+    if (segment.startsWith("@"))
+        segment = segment.slice(1);
+    if (!segment)
+        return null;
+    if (RESERVED_HANDLE_SEGMENTS.has(segment.toLowerCase()))
+        return null;
+    if (!HANDLE_PATTERN.test(segment))
+        return null;
+    return segment;
+}
+function extractNameFromAccountText(value) {
+    const parts = value
+        .split("\n")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return parts.find((item) => !item.startsWith("@"));
+}
 export class BrowserSessionManager {
     authStore;
     constructor(authStore = new AuthStore()) {
@@ -69,34 +128,55 @@ export class BrowserSessionManager {
         return url.includes("/home") && !url.includes("/login");
     }
     async whoAmI(page) {
-        const profileLink = await page
-            .getAttribute('[data-testid="AppTabBar_Profile_Link"]', "href")
-            .catch(() => null);
-        const handle = profileLink?.replace(/^\//, "").split("/")[0];
+        const profileSelectors = [
+            '[data-testid="AppTabBar_Profile_Link"]',
+            'a[data-testid$="_Profile_Link"]',
+            '[data-testid="SideNav_AccountSwitcher_Button"] a[href]',
+        ];
+        let handle;
+        for (const selector of profileSelectors) {
+            const href = await page.getAttribute(selector, "href").catch(() => null);
+            const candidate = normalizeHandleCandidate(href);
+            if (candidate) {
+                handle = candidate;
+                break;
+            }
+        }
+        const accountSwitcherSelector = '[data-testid="SideNav_AccountSwitcher_Button"]';
         const accountText = await page
-            .locator('[data-testid="SideNav_AccountSwitcher_Button"]')
+            .locator(accountSwitcherSelector)
             .first()
             .innerText()
             .catch(() => "");
-        const name = accountText
-            .split("\n")
-            .map((item) => item.trim())
-            .filter(Boolean)[0];
+        const accountAriaLabel = await page
+            .getAttribute(accountSwitcherSelector, "aria-label")
+            .catch(() => null);
+        if (!handle) {
+            handle =
+                normalizeHandleCandidate(accountText) ??
+                    normalizeHandleCandidate(accountAriaLabel ?? "") ??
+                    undefined;
+        }
+        const name = extractNameFromAccountText(accountText) ??
+            extractNameFromAccountText(accountAriaLabel ?? "");
         return { handle, name };
     }
     async createCookieProbe(options) {
         const resolved = await this.authStore.resolve(options);
+        const diagnostics = this.authStore.getLastDiagnostics();
         if (!resolved) {
             return {
                 hasAuthToken: false,
                 hasCt0: false,
                 source: "none",
+                diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
             };
         }
         return {
             hasAuthToken: resolved.cookies.some((cookie) => cookie.name === "auth_token"),
             hasCt0: resolved.cookies.some((cookie) => cookie.name === "ct0"),
             source: resolved.source,
+            diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
         };
     }
 }

package/dist/cli/program.js

@@ -47,6 +47,11 @@ export function createProgram(handlers, version = "0.2.0") {
         .command("post <text>")
         .description("Alias for tweet")
         .action(run((text) => handlers.tweet(text)));
+    program
+        .command("article <title> [body]")
+        .description("Publish a long-form article on X")
+        .option("--body-file <path>", "Read article body text from a UTF-8 file")
+        .action(run((title, body, options) => handlers.article(title, body, options)));
     program
         .command("reply <tweet-id-or-url> <text>")
         .description("Reply to a tweet")

package/dist/cli.js

@@ -30,6 +30,8 @@ function collectExplicitCliBooleans(args) {
         explicit.emoji = false;
     if (args.includes("--no-headless"))
         explicit.headless = false;
+    if (args.includes("--cookie-source"))
+        explicit.cookieSourceExplicit = true;
     return explicit;
 }
 function compactObject(input) {

package/dist/client/playwright-client.js

@@ -57,10 +57,15 @@ function resolveMediaSpecs(media, alt) {
     }
     return specs;
 }
+const HEADLESS_RETRY_MARKER = "[FRIGATEBIRD_HEADLESS_RETRY]";
+function markHeadlessRetry(message) {
+    return new Error(`${HEADLESS_RETRY_MARKER} ${message}`);
+}
 export class PlaywrightXClient {
     options;
     sessions;
     baseUrl;
+    currentSessionHeadless = null;
     constructor(options, sessions = new BrowserSessionManager()) {
         this.options = options;
         this.sessions = sessions;
@@ -74,10 +79,49 @@ export class PlaywrightXClient {
             return this.options;
         return { ...this.options, headless: headlessOverride };
     }
+    isHeadlessRetryError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.includes(HEADLESS_RETRY_MARKER);
+    }
+    normalizeError(error) {
+        if (error instanceof Error) {
+            if (this.isHeadlessRetryError(error)) {
+                return new Error(error.message.replace(`${HEADLESS_RETRY_MARKER} `, "").trim());
+            }
+            return error;
+        }
+        return new Error(String(error));
+    }
     async withPage(task, headlessOverride) {
-        return this.sessions.withSession(this.mergedOptions(headlessOverride), async ({ page }) => {
-            return task(page);
-        });
+        const effectiveOptions = this.mergedOptions(headlessOverride);
+        const runWithMode = async (headless) => {
+            return this.sessions.withSession({ ...effectiveOptions, headless }, async ({ page }) => {
+                const previous = this.currentSessionHeadless;
+                this.currentSessionHeadless = headless;
+                try {
+                    return await task(page);
+                }
+                finally {
+                    this.currentSessionHeadless = previous;
+                }
+            });
+        };
+        try {
+            return await runWithMode(effectiveOptions.headless);
+        }
+        catch (error) {
+            if (effectiveOptions.headless &&
+                headlessOverride === undefined &&
+                this.isHeadlessRetryError(error)) {
+                try {
+                    return await runWithMode(false);
+                }
+                catch (secondError) {
+                    throw this.normalizeError(secondError);
+                }
+            }
+            throw this.normalizeError(error);
+        }
     }
     async ensureAuth(page) {
         const loggedIn = await this.sessions.ensureLoggedIn(page, this.baseUrl);
@@ -96,7 +140,41 @@ export class PlaywrightXClient {
             throw new Error("Invalid tweet reference. Provide a tweet URL or numeric tweet ID.");
         }
         await page.goto(url, { waitUntil: "domcontentloaded" });
-        await page.waitForSelector('[data-testid="tweet"]', { timeout: 15000 });
+        try {
+            await page.waitForSelector('[data-testid="tweet"]', { timeout: 15000 });
+        }
+        catch (error) {
+            const isHeadlessSession = this.currentSessionHeadless ?? this.options.headless;
+            const hasTweet = (await page
+                .locator('[data-testid="tweet"]')
+                .count()
+                .catch(() => 0)) > 0;
+            const errorPageVisible = (await page
+                .locator("text=Something went wrong, but don’t fret")
+                .first()
+                .isVisible()
+                .catch(() => false)) ||
+                (await page
+                    .locator("text=Something went wrong, but don't fret")
+                    .first()
+                    .isVisible()
+                    .catch(() => false)) ||
+                (await page
+                    .locator("text=Something went wrong")
+                    .first()
+                    .isVisible()
+                    .catch(() => false));
+            if (!hasTweet && errorPageVisible && isHeadlessSession) {
+                throw markHeadlessRetry("X returned a temporary error page while loading the tweet in headless mode. Retrying in headed mode.");
+            }
+            if (!hasTweet && isHeadlessSession) {
+                throw markHeadlessRetry("Tweet content did not render in headless mode. Retrying in headed mode.");
+            }
+            if (!hasTweet) {
+                throw new Error("Tweet content did not render. X may be returning a transient error page or blocking this route right now.");
+            }
+            throw error;
+        }
         return url;
     }
     async openList(page, listRef) {
@@ -162,45 +240,157 @@ export class PlaywrightXClient {
         }
         return null;
     }
+    isPointerInterceptionError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return (message.includes("intercepts pointer events") ||
+            (message.includes("Timeout") && message.includes("locator.click")));
+    }
+    async dismissBlockingLayers(page) {
+        const mask = page.locator('[data-testid="twc-cc-mask"]').first();
+        if (!(await mask.isVisible().catch(() => false))) {
+            return;
+        }
+        const consentSelectors = [
+            '[role="dialog"] [role="button"]:has-text("Accept all cookies")',
+            '[role="dialog"] [role="button"]:has-text("Accept all")',
+            '[role="button"]:has-text("Accept all cookies")',
+            '[role="button"]:has-text("Accept all")',
+            '[role="button"]:has-text("Agree and continue")',
+            '[role="button"]:has-text("Close")',
+        ];
+        for (const selector of consentSelectors) {
+            const button = page.locator(selector).first();
+            if (!(await button.isVisible().catch(() => false)))
+                continue;
+            await button.click().catch(() => { });
+            await page.waitForTimeout(120);
+        }
+        if (await mask.isVisible().catch(() => false)) {
+            await page.keyboard.press("Escape").catch(() => { });
+            await page.waitForTimeout(120);
+        }
+        if (await mask.isVisible().catch(() => false)) {
+            await mask.click({ force: true }).catch(() => { });
+        }
+        const deadline = Date.now() + 3000;
+        while (Date.now() < deadline) {
+            if (!(await mask.isVisible().catch(() => false)))
+                break;
+            await page.waitForTimeout(120);
+        }
+    }
     async clickFirstVisible(page, selectors, timeoutMs = 5000) {
         const locator = await this.firstVisibleLocator(page, selectors, timeoutMs);
         if (!locator)
             return false;
-        await locator.click();
-        return true;
+        const clickTimeout = Math.max(800, Math.min(timeoutMs, 2500));
+        for (let attempt = 1; attempt <= 3; attempt += 1) {
+            await this.dismissBlockingLayers(page);
+            try {
+                await locator.click({ timeout: clickTimeout });
+                return true;
+            }
+            catch (error) {
+                if (!this.isPointerInterceptionError(error) || attempt === 3) {
+                    throw error;
+                }
+                const forced = await locator
+                    .click({ force: true, timeout: 2000 })
+                    .then(() => true)
+                    .catch(() => false);
+                if (forced) {
+                    return true;
+                }
+                await page.waitForTimeout(200 * attempt);
+            }
+        }
+        return false;
     }
     async waitForComposer(page, timeoutMs = 15000) {
-        const composer = await this.firstVisibleLocator(page, [
+        const composerSelectors = [
             '[data-testid="tweetTextarea_0"]',
             'div[role="textbox"][data-testid="tweetTextarea_0"]',
             'div[role="textbox"][aria-label*="Post text"]',
             'div[role="textbox"][aria-label*="What is happening"]',
             'div[role="textbox"][aria-label*="What’s happening"]',
-        ], timeoutMs);
+        ];
+        const composer = await this.firstVisibleLocator(page, composerSelectors, timeoutMs);
         if (!composer) {
             throw new Error("Composer text area not found. X may have changed selectors.");
         }
     }
     async fillComposer(page, text) {
-        const composer = await this.firstVisibleLocator(page, [
+        const composerSelectors = [
             '[data-testid="tweetTextarea_0"]',
             'div[role="textbox"][data-testid="tweetTextarea_0"]',
             'div[role="textbox"][aria-label*="Post text"]',
             'div[role="textbox"][aria-label*="What is happening"]',
             'div[role="textbox"][aria-label*="What’s happening"]',
-        ]);
-        if (!composer) {
+        ];
+        const candidateLocators = [];
+        for (const selector of composerSelectors) {
+            const locators = page.locator(selector);
+            const count = await locators.count().catch(() => 0);
+            for (let index = 0; index < count; index += 1) {
+                const candidate = locators.nth(index);
+                if (await candidate.isVisible().catch(() => false)) {
+                    candidateLocators.push(candidate);
+                }
+            }
+        }
+        if (candidateLocators.length === 0) {
             throw new Error("Composer text area not found.");
         }
-        await composer.fill(text);
+        const submitEnabledSelectors = [
+            '[data-testid="tweetButton"]:not([aria-disabled="true"])',
+            '[data-testid="tweetButtonInline"]:not([aria-disabled="true"])',
+            '[role="button"]:has-text("Post"):not([aria-disabled="true"])',
+            '[role="button"]:has-text("Reply"):not([aria-disabled="true"])',
+        ];
+        const isSubmitEnabled = async () => {
+            const enabled = await this.firstVisibleLocator(page, submitEnabledSelectors, 800, 100);
+            return Boolean(enabled);
+        };
+        for (const composer of candidateLocators) {
+            await composer.click().catch(() => { });
+            await composer.fill(text).catch(() => { });
+            const injected = await composer
+                .evaluate((node) => {
+                const element = node;
+                return (element.innerText ||
+                    element.textContent ||
+                    element.value ||
+                    "").trim();
+            })
+                .catch(() => "");
+            if (!injected || injected.length < Math.min(6, text.length)) {
+                await page.keyboard.type(text).catch(() => { });
+            }
+            if (await isSubmitEnabled()) {
+                return;
+            }
+        }
     }
     async submitComposer(page, action) {
+        await page.keyboard.press("Meta+Enter").catch(async () => {
+            await page.keyboard.press("Control+Enter").catch(() => { });
+        });
+        await page.waitForTimeout(500);
+        const sent = await this.firstVisibleLocator(page, [
+            '[role="alert"]:has-text("Your post was sent")',
+            '[role="alert"]:has-text("post was sent")',
+            '[role="alert"]:has-text("sent")',
+            '[data-testid="toast"]',
+        ], 1800, 100);
+        if (sent) {
+            return;
+        }
         const clicked = await this.clickFirstVisible(page, [
-            '[data-testid="tweetButton"]',
-            '[data-testid="tweetButtonInline"]',
-            'button[data-testid="tweetButton"]',
-            '[role="button"]:has-text("Post")',
-            '[role="button"]:has-text("Reply")',
+            '[data-testid="tweetButton"]:not([aria-disabled="true"])',
+            '[data-testid="tweetButtonInline"]:not([aria-disabled="true"])',
+            'button[data-testid="tweetButton"]:not([aria-disabled="true"])',
+            '[role="button"]:has-text("Post"):not([aria-disabled="true"])',
+            '[role="button"]:has-text("Reply"):not([aria-disabled="true"])',
         ]);
         if (!clicked) {
             throw new Error(`Could not locate ${action} submit button. X may have changed selectors.`);
@@ -368,26 +558,53 @@ export class PlaywrightXClient {
         await page.goto(this.absolute(`/${normalized}`), {
             waitUntil: "domcontentloaded",
         });
-        const actionsClicked = await this.clickFirstVisible(page, [
-            '[data-testid="userActions"]',
-            'button[aria-label*="More"]',
-            'button[aria-label*="more"]',
-        ], 15000);
-        if (!actionsClicked) {
-            throw new Error(`Could not open actions menu for @${normalized}. X may have changed selectors.`);
-        }
-        await page.waitForTimeout(300);
-        const menuClicked = await this.clickFirstVisible(page, [
+        const listMenuSelectors = [
             '[role="menuitem"]:has-text("Add/remove from Lists")',
+            '[role="menuitem"]:has-text("Add/remove")',
             '[role="menuitem"]:has-text("Lists")',
             'button:has-text("Add/remove from Lists")',
-            'button:has-text("Lists")',
+            'button:has-text("Add/remove")',
             'a:has-text("Add/remove from Lists")',
-        ], 5000);
+        ];
+        const openProfileMenuWithButton = async (button) => {
+            await button.click();
+            await page.waitForTimeout(250);
+            const menuItem = await this.firstVisibleLocator(page, listMenuSelectors, 1200, 100);
+            if (menuItem)
+                return true;
+            await page.keyboard.press("Escape").catch(() => { });
+            await page.waitForTimeout(120);
+            return false;
+        };
+        // Prefer the dedicated profile actions button when available.
+        const profileActions = await this.firstVisibleLocator(page, ['main [data-testid="userActions"]', '[data-testid="userActions"]'], 15000);
+        let openedListMenu = false;
+        if (profileActions) {
+            openedListMenu = await openProfileMenuWithButton(profileActions);
+        }
+        // Fallback for UI variants where userActions is late/missing.
+        if (!openedListMenu) {
+            const fallbackButtons = page.locator('main button[aria-haspopup="menu"][aria-label*="More"]');
+            const fallbackCount = await fallbackButtons.count();
+            const scanLimit = Math.min(fallbackCount, 8);
+            for (let index = 0; index < scanLimit; index += 1) {
+                const button = fallbackButtons.nth(index);
+                if (!(await button.isVisible().catch(() => false)))
+                    continue;
+                if (await openProfileMenuWithButton(button)) {
+                    openedListMenu = true;
+                    break;
+                }
+            }
+        }
+        if (!openedListMenu) {
+            throw new Error(`Could not locate profile list actions for @${normalized}. X may have changed selectors.`);
+        }
+        const menuClicked = await this.clickFirstVisible(page, listMenuSelectors, 5000);
         if (!menuClicked) {
             throw new Error(`Could not locate "Add/remove from Lists" menu item for @${normalized}.`);
         }
-        const dialogSelector = '[role="dialog"]:has(div[role="checkbox"])';
+        const dialogSelector = '[role="dialog"]:has([role="checkbox"]):visible';
         await page.waitForSelector(dialogSelector, { timeout: 15000 });
         return dialogSelector;
     }
@@ -395,16 +612,18 @@ export class PlaywrightXClient {
         try {
             const outcome = await this.retryWithBackoff(async () => {
                 const dialogSelector = await this.openListMembershipDialog(page, handle);
-                const listCheckboxes = page.locator(`${dialogSelector} div[role="checkbox"]`);
+                const listCheckboxes = page.locator(`${dialogSelector} [role="checkbox"]`);
                 const count = await listCheckboxes.count();
                 if (count === 0) {
                     throw new Error("List dialog opened without visible checkboxes.");
                 }
                 let checkbox = null;
+                const desiredName = listName.trim().toLowerCase();
                 for (let index = 0; index < count; index += 1) {
                     const candidate = listCheckboxes.nth(index);
                     const text = await candidate.innerText().catch(() => "");
-                    if (text.trim().toLowerCase() === listName.trim().toLowerCase()) {
+                    const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
+                    if (normalized === desiredName || normalized.includes(desiredName)) {
                         checkbox = candidate;
                         break;
                     }
@@ -447,6 +666,7 @@ export class PlaywrightXClient {
             hasAuthToken: probe.hasAuthToken,
             hasCt0: probe.hasCt0,
             authFile: this.sessions.getAuthStore().authFile,
+            diagnostics: probe.diagnostics,
         };
     }
     async whoami() {
@@ -485,6 +705,87 @@ export class PlaywrightXClient {
             return ok("Tweet posted.");
         });
     }
+    async publishArticle(title, body) {
+        const cleanTitle = title.trim();
+        const cleanBody = body.trim();
+        if (!cleanTitle) {
+            return fail("Article title cannot be empty.");
+        }
+        if (!cleanBody) {
+            return fail("Article body cannot be empty.");
+        }
+        return this.withPage(async (page) => {
+            await this.ensureAuth(page);
+            const composePaths = [
+                "/i/articles/new",
+                "/compose/article",
+                "/write",
+                "/i/write",
+                "/i/notes/new",
+                "/compose/post",
+            ];
+            const titleSelectors = [
+                'input[data-testid="articleTitleInput"]',
+                'textarea[data-testid="articleTitleInput"]',
+                '[data-testid="article-editor-title"] [contenteditable="true"]',
+                '[role="textbox"][aria-label*="Title"]',
+                'input[placeholder*="Title"]',
+                'textarea[placeholder*="Title"]',
+                '[contenteditable="true"][aria-label*="Title"]',
+            ];
+            const bodySelectors = [
+                '[data-testid="articleBodyInput"]',
+                '[data-testid="article-editor"] [contenteditable="true"]',
+                '.ProseMirror[contenteditable="true"]',
+                '[role="textbox"][aria-label*="Write"]',
+                '[contenteditable="true"][aria-label*="Write"]',
+                '[role="textbox"][aria-label*="Body"]',
+                'textarea[placeholder*="Write"]',
+            ];
+            let titleField = null;
+            let bodyField = null;
+            for (const path of composePaths) {
+                await page
+                    .goto(this.absolute(path), { waitUntil: "domcontentloaded" })
+                    .catch(() => { });
+                await this.dismissBlockingLayers(page);
+                await this.clickFirstVisible(page, [
+                    '[role="tab"]:has-text("Article")',
+                    '[role="button"]:has-text("Write article")',
+                    '[data-testid="articleComposerButton"]',
+                    'a[href*="/i/articles/new"]',
+                ], 1500).catch(() => false);
+                titleField = await this.firstVisibleLocator(page, titleSelectors, 3500, 120);
+                bodyField = await this.firstVisibleLocator(page, bodySelectors, 3500, 120);
+                if (titleField && bodyField) {
+                    break;
+                }
+            }
+            if (!titleField || !bodyField) {
+                return fail("Could not locate article composer. Articles may be unavailable for this account or X changed selectors.");
+            }
+            await titleField.click().catch(() => { });
+            await titleField.fill(cleanTitle);
+            await bodyField.click().catch(() => { });
+            await bodyField.fill(cleanBody);
+            const published = await this.clickFirstVisible(page, [
+                '[data-testid="articlePublishButton"]:not([aria-disabled="true"])',
+                '[data-testid="publishButton"]:not([aria-disabled="true"])',
+                '[role="button"]:has-text("Publish"):not([aria-disabled="true"])',
+                '[role="button"]:has-text("Post"):not([aria-disabled="true"])',
+            ], 12000).catch(() => false);
+            if (!published) {
+                return fail("Could not locate article publish button.");
+            }
+            await this.clickFirstVisible(page, [
+                '[data-testid="confirmationSheetConfirm"]',
+                '[role="button"]:has-text("Publish")',
+                '[role="button"]:has-text("Post")',
+            ], 3000).catch(() => false);
+            await page.waitForTimeout(1000);
+            return ok("Article published.");
+        });
+    }
     async reply(tweetRef, text) {
         let mediaSpecs = [];
         try {
@@ -537,26 +838,33 @@ export class PlaywrightXClient {
         return this.withPage(async (page) => {
             await this.ensureAuth(page);
             await this.openTweet(page, tweetRef);
-            const undo = page
-                .locator('[data-testid="unretweet"], button[aria-label*="Undo repost"], div[aria-label*="Undo repost"]')
-                .first();
-            if (await undo.isVisible().catch(() => false)) {
+            const undoSelectors = [
+                '[data-testid="unretweet"]',
+                'button[aria-label*="Undo repost"]',
+                'div[aria-label*="Undo repost"]',
+            ];
+            if (await this.firstVisibleLocator(page, undoSelectors, 1200, 150)) {
                 return ok("Tweet already reposted.");
             }
-            const button = page
-                .locator('[data-testid="retweet"], button[aria-label*="Repost"], div[aria-label*="Repost"]')
-                .first();
-            if (!(await button.isVisible().catch(() => false))) {
+            const repostClicked = await this.clickFirstVisible(page, [
+                '[data-testid="retweet"]',
+                'button[aria-label*="Repost"]',
+                'div[aria-label*="Repost"]',
+            ]).catch(() => false);
+            if (!repostClicked) {
                 return fail("Could not locate repost button.");
             }
-            await button.click();
-            const confirm = page
-                .locator('[data-testid="retweetConfirm"], [role="menuitem"]:has-text("Repost"), [role="button"]:has-text("Repost")')
-                .first();
-            if (await confirm.isVisible().catch(() => false)) {
-                await confirm.click();
+            await page.waitForTimeout(250);
+            const confirmClicked = await this.clickFirstVisible(page, [
+                '[data-testid="retweetConfirm"]',
+                '[role="menuitem"]:has-text("Repost")',
+                '[role="dialog"] [role="button"]:has-text("Repost")',
+            ], 2500).catch(() => false);
+            const nowReposted = await this.firstVisibleLocator(page, undoSelectors, 5000, 150);
+            if (nowReposted || confirmClicked) {
+                return ok("Tweet reposted.");
             }
-            return ok("Tweet reposted.");
+            return fail("Repost action did not complete. X may require additional confirmation.");
         });
     }
     async read(tweetRef) {
@@ -963,12 +1271,14 @@ export class PlaywrightXClient {
     async refresh() {
         const refreshed = await this.sessions.refreshAuth(this.options);
         const loggedIn = await this.withPage(async (page) => this.sessions.ensureLoggedIn(page, this.baseUrl));
+        const diagnostics = this.sessions.getAuthStore().getLastDiagnostics();
         return {
             loggedIn,
             source: refreshed?.source ?? "none",
             hasAuthToken: Boolean(refreshed?.cookies.some((cookie) => cookie.name === "auth_token")),
             hasCt0: Boolean(refreshed?.cookies.some((cookie) => cookie.name === "ct0")),
             authFile: this.sessions.getAuthStore().authFile,
+            diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
         };
     }
     async addToList(listName, handles, headlessOverride) {

package/dist/commands/handlers.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { parseBookmarkOptions, parseFollowListOptions, parseJsonFlag, parseListOptions, parseMentionOptions, parseNewsOptions, parsePaginationOptions, parseTimelineOptions, } from "../lib/options.js";
 function parseRawArgs(options) {
     if (options && typeof options === "object") {
@@ -84,6 +85,11 @@ export function createHandlers({ client, output }) {
             output.info(`auth_token: ${status.hasAuthToken ? "present" : "missing"}`);
             output.info(`ct0: ${status.hasCt0 ? "present" : "missing"}`);
             output.info(`Auth file: ${status.authFile}`);
+            if (status.diagnostics) {
+                for (const diagnostic of status.diagnostics) {
+                    output.warn(diagnostic);
+                }
+            }
         },
         whoami: async (options) => {
             const json = parseJsonFlag(parseRawArgs(options));
@@ -98,6 +104,22 @@ export function createHandlers({ client, output }) {
         tweet: async (text) => {
             output.mutation(await client.tweet(text));
         },
+        article: async (title, body, options) => {
+            const raw = parseRawArgs(options);
+            const bodyFile = typeof raw.bodyFile === "string" ? raw.bodyFile.trim() : "";
+            let content = body?.trim() ?? "";
+            if (bodyFile) {
+                const fromFile = fs.readFileSync(bodyFile, "utf8").trim();
+                if (!fromFile) {
+                    throw new Error(`Article body file is empty: ${bodyFile}`);
+                }
+                content = content ? `${content}\n\n${fromFile}` : fromFile;
+            }
+            if (!content) {
+                throw new Error("Article body is required. Provide [body] or --body-file <path>.");
+            }
+            output.mutation(await client.publishArticle(title, content));
+        },
         reply: async (tweetRef, text) => {
             output.mutation(await client.reply(tweetRef, text));
         },
@@ -268,6 +290,11 @@ export function createHandlers({ client, output }) {
                 output.info(`Source: ${result.source}`);
                 output.info(`auth_token: ${result.hasAuthToken ? "present" : "missing"}`);
                 output.info(`ct0: ${result.hasCt0 ? "present" : "missing"}`);
+                if (result.diagnostics) {
+                    for (const diagnostic of result.diagnostics) {
+                        output.warn(diagnostic);
+                    }
+                }
             }
         },
         add: async (listName, handles, options) => {

package/dist/lib/invocation.js

@@ -2,6 +2,7 @@ import { looksLikeTweetReference } from "./identifiers.js";
 export const KNOWN_COMMANDS = new Set([
     "tweet",
     "post",
+    "article",
     "reply",
     "read",
     "replies",

package/dist/lib/options.js

@@ -56,6 +56,7 @@ export function parseGlobalOptions(raw) {
         firefoxProfile: raw.firefoxProfile ? String(raw.firefoxProfile) : undefined,
         cookieTimeout: parseOptionalPositiveInt(raw.cookieTimeout),
         cookieSource: parseCookieSources(raw.cookieSource),
+        cookieSourceExplicit: Boolean(raw.cookieSourceExplicit),
         timeout: parseOptionalPositiveInt(raw.timeout),
         quoteDepth: parseOptionalPositiveInt(raw.quoteDepth),
         plain: Boolean(raw.plain),

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "frigatebird",
-	"version": "0.2.0",
-	"description": "Playwright-first X CLI with bird and x-list-manager parity",
+	"version": "0.3.0",
+	"description": "Playwright-first X CLI with bird-style parity and resilient web automation",
 	"type": "module",
 	"main": "./dist/cli.js",
 	"license": "MIT",
@@ -42,6 +42,7 @@
 		"test:run": "vitest run --config vitest.config.ts",
 		"test:coverage": "vitest run --config vitest.config.ts --coverage",
 		"test:e2e": "vitest run --config vitest.e2e.config.ts",
+		"test:e2e:live": "FRIGATEBIRD_LIVE_E2E=1 vitest run --config vitest.e2e.config.ts tests/e2e/live-mutation-account.e2e.test.ts",
 		"lint": "biome check .",
 		"lint:fix": "biome check --write .",
 		"release:check": "npm run lint && npm run build && npm run test:coverage",