@m13v/s4l 1.7.4-rc.9 → 1.7.4

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>
@@ -2985,9 +2988,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 +3505,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 +5109,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

package/mcp/dist/runtime.js

@@ -239,6 +239,30 @@ function bundledVersion() {
         return null;
     }
 }
+// `ensurePipelineCurrent()` extracts updates over the existing materialized
+// repo so customer config and logs survive. That also means deleting a file
+// from the npm tarball does not delete an older copy already on disk. Keep
+// explicit tombstones for retired helpers long enough for the fleet to pass
+// through this release; new installs never receive these files.
+const RETIRED_MATERIALIZED_FILES = [
+    "scripts/saps_mode.py",
+    "scripts/saps_activity.py",
+    "scripts/_lock_preempt_test.py",
+];
+function removeRetiredMaterializedFiles() {
+    for (const rel of RETIRED_MATERIALIZED_FILES) {
+        const target = path.join(MATERIALIZED_REPO, rel);
+        try {
+            if (!fs.existsSync(target))
+                continue;
+            fs.rmSync(target, { force: true });
+            console.error(`[runtime] removed retired pipeline file ${rel}`);
+        }
+        catch (e) {
+            console.error(`[runtime] could not remove retired pipeline file ${rel}: ${e?.message || e}`);
+        }
+    }
+}
 // Re-materialize the pipeline source when a plugin UPDATE shipped a newer
 // pipeline.tgz than what's on disk. The .mcpb update refreshes dist/ (this
 // server) but does NOT re-extract the embedded tarball, so without this the box
@@ -269,6 +293,9 @@ export function ensurePipelineCurrent() {
         const bundled = bundledVersion();
         if (!bundled)
             return; // dev build, no stamp — leave the materialized repo alone.
+        // Run before the version early-return too: a prior package build may have
+        // accidentally included a retired file under this same version.
+        removeRetiredMaterializedFiles();
         const rt = readRuntime();
         if (rt?.pipeline_version === bundled)
             return; // already current.
@@ -283,6 +310,9 @@ export function ensurePipelineCurrent() {
             console.error(`[runtime] pipeline re-materialize failed (exit ${r.status}); keeping existing pipeline`);
             return;
         }
+        // Defense in depth: a stale/locally-built tarball cannot reintroduce a
+        // retired helper even if its package allowlist drifts.
+        removeRetiredMaterializedFiles();
         // Record the new version so we don't re-extract on every boot.
         const next = rt ?? readRuntime();
         if (next) {
@@ -589,6 +619,55 @@ export function ensureRuntimeProvisioned() {
         return false; // best-effort; a boot provision must never break startup
     }
 }
+// Boot hook closing the provisioning gap for ALREADY-ready runtimes: provision()
+// skips when runtimeReady(), so a vendored-patch update shipped in an rc never
+// reaches an existing install's harness checkout (proved on the QA box: rc.26
+// delivered scripts/patches/ but the checkout stayed unpatched, 2026-07-13).
+// This runs on every MCP boot: if the fix marker is absent and the patch
+// applies, apply it and reload the harness daemon so the running process picks
+// up the new source (the uv tool install is EDITABLE, so patched files are
+// live without a reinstall). Best-effort; never blocks startup.
+export async function ensureHarnessPatched() {
+    try {
+        // Version marker of the CURRENT vendored patch: a symbol that exists only
+        // in its newest revision (v2 added the daemon.py websocket-proxy
+        // neutralization after v1's cdp_urlopen alone proved insufficient — the
+        // WS dial still routed through the macOS system proxy and died with
+        // "proxy rejected connection: HTTP 503"). Bump this string whenever the
+        // patch gains a new hunk, or upgraded installs will silently keep the
+        // previous revision.
+        const daemonPy = path.join(HARNESS_DIR, "src", "browser_harness", "daemon.py");
+        if (!fs.existsSync(daemonPy))
+            return { ok: false, detail: "harness not installed yet" };
+        if (fs.readFileSync(daemonPy, "utf-8").includes("s4l_no_proxy_ws")) {
+            return { ok: true, detail: "already patched" };
+        }
+        const harnessPatch = path.join(MATERIALIZED_REPO, "scripts", "patches", "browser-harness-loopback-cdp-proxy.patch");
+        if (!fs.existsSync(harnessPatch))
+            return { ok: false, detail: "patch file missing from package" };
+        // Discard any PRIOR vendored-patch revision (e.g. v1) so the cumulative
+        // patch applies onto pristine pinned sources. Only src/ is touched; the
+        // checkout is a managed artifact, never a place for local edits.
+        await sh("git", ["-C", HARNESS_DIR, "checkout", "--", "src/browser_harness"], {
+            timeoutMs: 30000,
+        });
+        const chk = await sh("git", ["-C", HARNESS_DIR, "apply", "--check", harnessPatch], {
+            timeoutMs: 30000,
+        });
+        if (chk.code !== 0) {
+            return { ok: false, detail: "patch does not apply (dirty or diverged checkout)" };
+        }
+        const app = await sh("git", ["-C", HARNESS_DIR, "apply", harnessPatch], { timeoutMs: 30000 });
+        if (app.code !== 0)
+            return { ok: false, detail: `git apply failed (exit ${app.code})` };
+        // Reload the daemon so the long-lived process re-imports the patched source.
+        await sh(HARNESS_BIN, ["--reload"], { timeoutMs: 30000 });
+        return { ok: true, detail: "patched + daemon reloaded" };
+    }
+    catch (e) {
+        return { ok: false, detail: String(e?.message || e) };
+    }
+}
 async function provision(progress) {
     const setStep = (id, status, detail) => {
         const st = progress.steps.find((s) => s.id === id);
@@ -828,6 +907,37 @@ async function provision(progress) {
             timeoutMs: 120000,
         });
         await sh("git", ["-C", HARNESS_DIR, "reset", "--hard", "FETCH_HEAD"], { timeoutMs: 60000 });
+        // Vendored fix on top of the pin: 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, so Chrome
+        // reads as "wedged"/logged-out while it is actually fine (2026-07-13).
+        // Upstream doesn't carry the fix and we don't control that repo, so apply
+        // our patch at install time, on every machine. If it stops applying
+        // cleanly, upstream has either merged the fix (detected below; fine) or
+        // refactored the files (warn); never fail the install over it.
+        const harnessPatch = path.join(MATERIALIZED_REPO, "scripts", "patches", "browser-harness-loopback-cdp-proxy.patch");
+        if (fs.existsSync(harnessPatch)) {
+            const chk = await sh("git", ["-C", HARNESS_DIR, "apply", "--check", harnessPatch], {
+                timeoutMs: 30000,
+            });
+            if (chk.code === 0) {
+                await sh("git", ["-C", HARNESS_DIR, "apply", harnessPatch], { timeoutMs: 30000 });
+            }
+            else {
+                let fixedUpstream = false;
+                try {
+                    fixedUpstream = fs
+                        .readFileSync(path.join(HARNESS_DIR, "src", "browser_harness", "admin.py"), "utf-8")
+                        .includes("cdp_urlopen");
+                }
+                catch {
+                    /* file moved — fall through to the warning */
+                }
+                if (!fixedUpstream) {
+                    console.error("[runtime] browser-harness loopback-proxy patch no longer applies and the fix is absent upstream; CDP probes may 403 behind a system proxy");
+                }
+            }
+        }
         // Install the CLI via uv tool (lands at ~/.local/bin/browser-harness).
         // --force so a refreshed source / changed entry point is reinstalled.
         const inst = await sh(uv, ["tool", "install", "--force", "-e", HARNESS_DIR], {