@m13v/s4l 1.7.4-rc.9 → 1.7.5-rc.1

package/README.md

@@ -1,143 +1,176 @@
-# social-autoposter
+# S4L
 
-Open-source repo behind **[S4L (s4lai)](https://s4l.ai)**: an automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Ships as a Claude Code skill plus a set of standalone Python helpers and macOS launchd jobs.
+S4L is a desktop plugin for running a Reddit and X reply-drafting workflow from
+your own machine.
 
-> The hosted managed version is **S4L** (written `s4lai`, domain `s4l.ai`): done-for-you Reddit and Twitter brand-awareness, $1/1K impressions, $50/1K site visits. See https://s4l.ai.
+It watches the conversations your buyers already read, finds threads with real
+momentum and fit, drafts contribution-first replies in your voice, and gives you
+a review queue before anything goes live. The product is positioned as a
+self-serve desktop plugin: subscribe, install, connect your accounts, review the
+drafts, and track the results.
 
-State (posts, replies, candidates, stats) is read and written through the hosted S4L HTTP API (`AUTOPOSTER_API_BASE` + an install key in `~/social-autoposter/.env`); no database to provision. Each platform drives its own persistent Playwright MCP browser profile, so logins survive across runs.
+- Website: https://s4l.ai
+- Pricing: https://s4l.ai/pricing
+- Source: https://github.com/m13v/social-autoposter
 
-## Prerequisites
+## What S4L does
 
-A new machine needs all of these before the pipeline can run end to end:
+Most social tools start after you already know what to post. S4L starts earlier:
+it looks for conversations worth entering.
 
-- **macOS** (the launchd plists are mac-only; Linux users can crib the cron snippets from `setup/SKILL.md` Step 7)
-- **Node.js 16+** (for `npx`, the installer, and `@playwright/mcp` at runtime)
-- **Python 3.9+** with `pip3` (helper scripts; deps auto-installed by the installer)
-- **Claude Code CLI** on `PATH` (the cron scripts shell out to `claude -p` with a per-platform MCP config)
-- One Chromium install per platform (created on first run by `@playwright/mcp` against the persistent profile dirs)
+- Finds high-traffic Reddit and X threads with enough context to join well.
+- Ranks opportunities by momentum, intent, community norms, and product fit.
+- Drafts replies that answer the thread first and mention your product only when
+  it belongs.
+- Keeps project-specific voice, claim language, competitors, sensitive topics,
+  and hard lines in the drafting context.
+- Presents drafts in a review workflow so you can approve, reject, or edit before
+  posting.
+- Tracks views, upvotes, clicks, deletions, and misses so each run learns from
+  the previous one.
 
-Optional:
+Nothing is posted automatically by default. Posting autopilot stays off until you
+explicitly turn it on.
 
-- `MOLTBOOK_API_KEY` in `.env` for Moltbook posting and scanning
-- `RESEND_API_KEY` and `NOTIFICATION_EMAIL` in `.env` for DM-escalation emails
+## Who it is for
 
-## Install
+S4L is for founders and small teams who want an AI-assisted social workflow
+without handing their accounts to an agency or living inside mention alerts all
+day.
 
-```bash
-npx social-autoposter init
-```
+You bring the accounts, product context, voice, and judgment. The plugin handles
+thread discovery, draft generation, review cards, scheduling, and result memory.
 
-`bin/cli.js` does all of the wiring in one shot:
+## How users install it
 
-1. Copies `scripts/`, `skill/`, `setup/`, `SKILL.md`, and `browser-agent-configs/` into `~/social-autoposter/`
-2. Creates `config.json` from `config.example.json` and writes a blank `.env` template (fill in your S4L API key and optional `MOLTBOOK_API_KEY`)
-3. Installs the Python helper deps via `pip3` if missing
-4. Generates launchd plists in `~/social-autoposter/launchd/` with the user's actual `HOME` and `PATH`
-5. Installs the Playwright MCP configs to `~/.claude/browser-agent-configs/` (twitter, reddit, linkedin) with `__HOME__` and `__NODE_BIN__` placeholders substituted. Existing files are left alone, so any window-position tweaks survive `npx social-autoposter update`.
-6. Creates empty persistent browser profile dirs at `~/.claude/browser-profiles/{twitter,reddit,linkedin}`
-7. Symlinks `~/.claude/skills/social-autoposter` and `~/.claude/skills/social-autoposter-setup` to the install dir
+The production path is the desktop plugin download from S4L.
 
-To refresh code without touching user files (`config.json`, `.env`, `SKILL.md`, or any browser config you customized):
+1. Subscribe at https://s4l.ai/pricing.
+2. Download the plugin link emailed after checkout.
+3. Install the plugin in Claude Desktop.
+4. Start a new Claude chat and send:
 
-```bash
-npx social-autoposter update
+```text
+Set me up on S4L plugin end to end
 ```
 
-## Configure
+The setup flow repairs the local runtime, connects your X browser session,
+discovers product and voice context, seeds search topics, schedules draft
+generation, and verifies that draft cards appear without posting.
 
-Tell your Claude agent: **"set me up on social-autoposter plugin end to end"**. The
-setup skill treats that as a terminal goal:
+## What is in this repo
 
-1. Inspect and repair the owned runtime.
-2. Auto-detect the best browser profile and connect X/Twitter. macOS may require
-   a Safe Storage approval; a logged-out account may require one manual sign-in.
-3. Scan the X profile, discover and research the user's product, and infer a
-   conservative project, ICP, voice, and search topics without an interview.
-4. Save the project and seed its topics into the backend.
-5. Run a draft-only cycle to verify the pipeline without posting.
+This repository contains the open-source runtime behind the S4L plugin:
 
-The agent pauses only for an unavoidable login or when no product can be
-identified. Autopilot remains off until explicitly requested.
+```text
+social-autoposter/
+|-- mcp/                    Desktop plugin / MCP server, panel UI, release bundle
+|-- scripts/                Discovery, drafting, stats, telemetry, and queue helpers
+|-- skill/                  Shell entrypoints used by scheduled jobs
+|-- setup/                  End-to-end setup skill used by Claude
+|-- browser-agent-configs/  Browser automation profile templates
+|-- launchd/                macOS LaunchAgent templates
+|-- mcp-servers/            Local MCP helpers used by the runtime
+|-- config.example.json     Example project/account configuration
+`-- SKILL.md                Legacy social-autoposter agent playbook
+```
 
-## How the runtime is wired
+The `mcp/` package is the plugin users interact with. The rest of the repo is the
+pipeline it bundles, installs, and drives.
 
-```
-launchd  ──▶  skill/run-{platform}.sh  ──▶  claude -p  --strict-mcp-config  --mcp-config ~/.claude/browser-agent-configs/{platform}-agent-mcp.json
-                       │                                        │
-                       │                                        └──▶  @playwright/mcp@latest
-                       │                                                       │
-                       │                                                       └──▶  ~/.claude/browser-profiles/{platform}/  (persistent userDataDir)
-                       │
-                       ├──▶  scripts/find_threads.py, top_twitter_queries.py  (no browser, API dedup)
-                       ├──▶  scripts/pick_project.py            (weighted project rotation)
-                       ├──▶  scripts/top_performers.py          (feedback report from past stats)
-                       └──▶  S4L HTTP API                       (AUTOPOSTER_API_BASE in .env)
+## Architecture
+
+```text
+Claude Desktop plugin
+  -> S4L MCP server
+  -> local runtime + menu bar review UI
+  -> scheduled queue worker
+  -> browser profiles you control
+  -> S4L API for install-scoped queues, stats, and configuration
 ```
 
-Each `skill/run-*.sh`:
+Important properties:
 
-1. Controlled by launchd (load/unload). Use the dashboard Pause All / Resume All button, or `launchctl unload/load` directly
-2. Acquires a per-platform lock from `skill/lock.sh` (waits up to 60 min for any prior run)
-3. Sources `~/social-autoposter/.env`
-4. Picks a project, builds a feedback report, fetches `llms.txt` for product context
-5. Calls `find_*.py` for API-side candidates already deduped against the DB
-6. Spawns a child Claude process with `--strict-mcp-config` so it only sees the one platform's browser MCP
+- Runs locally on macOS.
+- Uses the user's own logged-in browser profiles.
+- Stores install state locally and scopes API calls by install identity.
+- Keeps secrets such as `.env`, `config.json`, browser profiles, logs, and local
+  databases out of Git.
+- Uses approval-first drafting as the default operating mode.
 
-The launchd schedules generated by `bin/cli.js` on install:
+## Develop from source
 
-| Job | Cadence |
-|-----|---------|
-| `com.m13v.social-stats` (`stats.sh`) | every 21600 s (6 h) |
-| `com.m13v.social-engage` (`engage.sh`) | every 21600 s (6 h) |
+For normal users, use the plugin download from S4L. These steps are for working
+on the repo itself.
 
-All per-platform plists live in `launchd/` (reddit-search, reddit-threads, twitter-cycle, linkedin, moltbook, github, octolens, audit, dm-replies-*, link-edit-*, scan-reddit-replies, scan-moltbook-replies, etc.) and use either `StartInterval` or `StartCalendarInterval` for fixed wall-clock times. Activate any of them with:
+Prerequisites:
+
+- macOS
+- Node.js 16+
+- Python 3.9+
+- Claude Desktop or Claude Code for MCP testing
+
+Install dependencies:
 
 ```bash
-ln -sf ~/social-autoposter/launchd/com.m13v.social-twitter-cycle.plist ~/Library/LaunchAgents/
-launchctl load ~/Library/LaunchAgents/com.m13v.social-twitter-cycle.plist
+npm install
+cd mcp
+npm install
 ```
 
-## Skill commands
-
-| Command | What it does |
-|---------|-------------|
-| `/social-autoposter` | Comment run: find threads, draft, post, log (cron-safe) |
-| `/social-autoposter post` | Create an original post or thread (manual only) |
-| `/social-autoposter stats` | Update engagement stats via API |
-| `/social-autoposter engage` | Scan and reply to responses on our posts |
-| `/social-autoposter audit` | Full browser audit of all posts |
+Build the plugin server and panel:
 
-View live stats at `https://s4l.ai/stats/<your-handle>` once posts start landing.
+```bash
+cd mcp
+npm run build
+```
 
-## Repo layout
+Register this checkout with Claude Desktop and Claude Code for local testing:
 
-```
-social-autoposter/
-├── SKILL.md                  the playbook (locked, immutable)
-├── bin/cli.js                installer + dashboard launcher
-├── browser-agent-configs/    Playwright MCP templates (twitter/reddit/linkedin)
-├── config.example.json       config template
-├── setup/SKILL.md            autonomous end-to-end setup skill (locked)
-├── scripts/                  Python and JS helpers (no browser, no LLM)
-├── skill/                    shell wrappers invoked by launchd
-└── launchd/                  generated macOS LaunchAgent plists
+```bash
+cd mcp
+node install.mjs
 ```
 
-## For other AI agents
+Then fully quit and reopen Claude so MCP servers reload.
 
-The skill works with any agent that has shell access, browser automation, and an LLM. The Python and JS helpers in `scripts/` handle thread discovery, reply scanning, and stats updates without needing a browser. `SKILL.md` is the playbook; any agent can read it and execute the workflows with its own tools.
+Run the test suite:
 
-## Pause and resume
+```bash
+npm test
+```
 
-Use the dashboard at `localhost:3141` (Pause All / Resume All button), or manually:
+Build a local `.mcpb` artifact without publishing:
 
 ```bash
-# Pause: unload all jobs + kill running processes
-for plist in ~/Library/LaunchAgents/com.m13v.social-*.plist; do launchctl unload "$plist"; done
-
-# Resume: reload all jobs
-for plist in ~/social-autoposter/launchd/com.m13v.social-*.plist; do
-  ln -sf "$plist" ~/Library/LaunchAgents/
-  launchctl load ~/Library/LaunchAgents/$(basename "$plist")
-done
+bash scripts/release-mcpb.sh --no-bump --no-npm --no-release
 ```
+
+That command packs the current pipeline into `mcp/dist/pipeline.tgz`, builds the
+plugin, creates `mcp/social-autoposter.mcpb`, and runs the release checks without
+touching npm or GitHub releases.
+
+## Runtime commands
+
+The plugin exposes MCP tools for the user-facing workflow:
+
+- `project_config` configures projects, products, voice, topics, and X auth.
+- `engagement_mode` chooses personal-brand and product-promotion lanes.
+- `dashboard` opens the review dashboard.
+- `post_drafts` posts only the drafts the user selected.
+- `get_stats` reads X/Twitter stats.
+- `pause_s4l` pauses or resumes scheduled S4L jobs.
+- `runtime` installs, updates, and diagnoses the local runtime.
+- `report_diagnosis` sends a support report to the S4L team.
+
+The legacy `/social-autoposter` skill and npm package remain in the repo because
+the plugin bundles and reuses the same pipeline scripts.
+
+## Public-repo hygiene
+
+This repo is public. Do not commit local customer data, browser state, generated
+media, private automation experiments, `.mcpb` bundles, `.env` files, databases,
+or logs. The root `.gitignore` intentionally keeps those out of source control.
+
+If a workflow needs private scratch space, keep it outside the repo or under an
+ignored directory.

package/bin/cli.js

@@ -427,6 +427,29 @@ function installBrowserHarness() {
     if (reset.status !== 0) {
       console.warn('    WARNING: could not reset browser-harness clone to pinned commit; using existing checkout.');
     }
+    // Vendored fix on top of the pin (keep in sync with runtime.ts): loopback
+    // CDP requests must never route through a proxy — macOS system proxy
+    // settings leak into urllib's default opener and a box-wide forwarder
+    // 403s every 127.0.0.1 probe (2026-07-13). Applied at install time since
+    // we don't control the upstream repo. If it stops applying, upstream has
+    // either merged the fix (detected; fine) or refactored (warn); never fail
+    // the install over it.
+    const harnessPatch = path.join(PKG_ROOT, 'scripts', 'patches', 'browser-harness-loopback-cdp-proxy.patch');
+    if (fs.existsSync(harnessPatch)) {
+      const chk = spawnSync('git', ['-C', harnessDir, 'apply', '--check', harnessPatch], { stdio: 'pipe' });
+      if (chk.status === 0) {
+        spawnSync('git', ['-C', harnessDir, 'apply', harnessPatch], { stdio: 'inherit' });
+        console.log('    applied loopback-proxy patch to browser-harness');
+      } else {
+        let fixedUpstream = false;
+        try {
+          fixedUpstream = fs.readFileSync(path.join(harnessDir, 'src', 'browser_harness', 'admin.py'), 'utf-8').includes('cdp_urlopen');
+        } catch { /* file moved — fall through to the warning */ }
+        if (!fixedUpstream) {
+          console.warn('    WARNING: browser-harness loopback-proxy patch no longer applies and the fix is absent upstream; CDP probes may 403 behind a system proxy.');
+        }
+      }
+    }
   };
   if (!fs.existsSync(harnessDir)) {
     fs.mkdirSync(path.dirname(harnessDir), { recursive: true });

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, hasReadyProject, 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, retryProvisionIfStalled, } from "./runtime.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";
 import { initSentry, sendHeartbeat, sendStateSnapshot, captureError, captureMessage, flushSentry, startLogStreaming, flushLogs, logLine, checkVersionChange } from "./telemetry.js";
@@ -163,6 +163,9 @@ function plistXml(opts) {
     const schedule = opts.keepAlive
         ? `\t<key>KeepAlive</key>\n\t<true/>`
         : `\t<key>StartInterval</key>\n\t<integer>${opts.intervalSecs}</integer>`;
+    const abandon = opts.abandonProcessGroup
+        ? `\n\t<key>AbandonProcessGroup</key>\n\t<true/>`
+        : "";
     // Background (cron/autopilot) runs get the same Chrome the interactive cycle
     // uses, so a no-sudo ~/Applications install (which the shell's own resolver
     // doesn't scan) is still found off-screen. Omitted when Chrome resolves via
@@ -188,7 +191,7 @@ function plistXml(opts) {
 \t<array>
 ${args}
 \t</array>
-${schedule}
+${schedule}${abandon}
 \t<key>StandardOutPath</key>
 \t<string>${opts.stdoutLog}</string>
 \t<key>StandardErrorPath</key>
@@ -2673,6 +2676,53 @@ tool("restart_menubar", {
         menubar_running: running,
     });
 });
+// ---- posting_volume: per-install posting-volume mode (virality bar) --------
+// Server-side throttle (2026-07-13): installations.posting_mode maps to a
+// virality-bar percentile on the API (high~0.90, medium~0.97, low~0.995) and
+// OVERRIDES the cycle driver's hardcoded percentile, so a change applies on
+// the next cycle with no client update. 'get' also returns per-mode estimated
+// posts/day replayed from THIS install's trailing-7d candidate pool.
+tool("posting_volume", {
+    title: "Read or set posting volume (high / medium / low)",
+    description: "Read or set this install's posting-volume mode, the quality bar that decides how many drafts " +
+        "per day the twitter cycle produces. Three modes: high (~100+ posts/day), medium (~30/day), " +
+        "low (~5/day, only the very best candidates); 'default' clears the override so the cycle's " +
+        "built-in setting applies. action:'get' returns the current mode plus per-mode estimated " +
+        "posts/day computed from this install's own recent candidate pool (show those numbers when " +
+        "the user is choosing). Use when the user asks to post more, post less, slow down, raise the " +
+        "quality bar, or change posting volume. Takes effect on the next cycle; in draft-review mode " +
+        "it equally paces how many review cards appear.",
+    inputSchema: {
+        action: z.enum(["get", "set"]).default("get").describe("get = read mode + rates; set = change it"),
+        mode: z
+            .enum(["high", "medium", "low", "default"])
+            .optional()
+            .describe("Required for action:'set'. 'default' clears the override."),
+    },
+}, async (args) => {
+    const action = args.action || "get";
+    if (action === "set") {
+        if (!args.mode) {
+            return jsonContent({ error: "mode is required for action:'set' (high|medium|low|default)" });
+        }
+        const r = await runPython("scripts/s4l_posting_mode.py", ["set", String(args.mode)], {
+            timeoutMs: 30_000,
+        });
+        try {
+            return jsonContent(JSON.parse((r.stdout || "").trim()));
+        }
+        catch {
+            return jsonContent({ error: `posting-mode set failed: ${(r.stderr || r.stdout || "").slice(0, 300)}` });
+        }
+    }
+    const r = await runPython("scripts/s4l_posting_mode.py", ["get"], { timeoutMs: 30_000 });
+    try {
+        return jsonContent(JSON.parse((r.stdout || "").trim()));
+    }
+    catch {
+        return jsonContent({ error: `posting-mode get failed: ${(r.stderr || r.stdout || "").slice(0, 300)}` });
+    }
+});
 // ---- pause_s4l: temporarily stop drafting/posting, reversibly --------------
 // The lighter alternative to Quit: unloads only the launchd jobs that scan,
 // draft, and post (plus their support daemons), leaving Claude Desktop, the
@@ -2985,9 +3035,11 @@ function queueDir() {
 // routine is draining the queue — the worker would claim within a minute if it
 // were firing. This is the liveness signal that survives a Claude account switch
 // (which orphans the routines while their global SKILL.md files stay put, so the
-// SKILL.md-presence check in autopilotLoaded() reads a FALSE green). Mirrors the
-// menu bar's AUTOPILOT_STALL_SECONDS in mcp/menubar/s4l_menubar.py — keep in sync.
-const AUTOPILOT_STALL_MS = 180_000;
+// SKILL.md-presence check in autopilotLoaded() reads a FALSE green). Mirrors
+// HEALTHY_DRAIN_MAX_SECONDS in scripts/schedule_state.py, the single source of
+// truth every Python stall detector derives from; this TS constant can't import
+// it, so keep it in sync by hand when retuning there.
+const AUTOPILOT_STALL_MS = 1_200_000;
 // True when no scheduled-task routine is draining the draft queue. Two signals,
 // OR'd (keep in lockstep with mcp/menubar/s4l_menubar.py::_autopilot_stalled and
 // scripts/autopilot_stall_watch.py):
@@ -3500,6 +3552,9 @@ async function ensureQueueKickerInstalled() {
             stdoutLog: path.join(logDir, "launchd-twitter-cycle-stdout.log"),
             stderrLog: path.join(logDir, "launchd-twitter-cycle-stderr.log"),
             extraEnv: kickerEnv(),
+            // Don't let launchd reap the harness Chrome the cycle launches when the
+            // kicker shell exits (2026-07-12 foreground-steal loop).
+            abandonProcessGroup: true,
         });
         // Content-aware install: an existing box has the OLD kicker plist pointing at
         // run-twitter-cycle.sh (no merge step). ensurePlist won't overwrite, so detect
@@ -5101,6 +5156,17 @@ async function main() {
     if (ensureRuntimeProvisioned()) {
         console.error("[social-autoposter-mcp] owned runtime not ready; provisioning on boot");
     }
+    // Vendored harness patch for ALREADY-ready runtimes: provision() is skipped
+    // above when the runtime is ready, so a patch shipped in an rc would never
+    // reach an existing install's harness checkout without this. Idempotent
+    // (marker check) and best-effort; never blocks boot.
+    void ensureHarnessPatched()
+        .then((r) => {
+        if (!(r.ok && r.detail === "already patched")) {
+            console.error(`[social-autoposter-mcp] harness patch: ${r.ok ? "ok" : "skip"} (${r.detail})`);
+        }
+    })
+        .catch(() => { });
     // Queue-backed drafting (2026-06-23): keep the two worker-task prompts current,
     // pre-approve their tools EAGERLY (before onboarding even creates the tasks, so
     // the first unattended fire can't stall), and (re)install the launchd kicker