social-autoposter 1.6.142 → 1.6.144

package/mcp/dist/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.6.142",
-  "installedAt": "2026-06-29T20:58:06.674Z"
+  "version": "1.6.144",
+  "installedAt": "2026-06-29T21:04:01.505Z"
 }

package/mcp/manifest.json

@@ -2,7 +2,7 @@
   "dxt_version": "0.1",
   "name": "social-autoposter",
   "display_name": "S4L",
-  "version": "1.6.142",
+  "version": "1.6.144",
   "description": "Draft, review, approve, and autopilot X/Twitter posts.",
   "long_description": "The disclaimer above is generic Claude boilerplate. S4L is an open source product developed by Mediar.ai Incorporated, a VC-backed San Francisco-based startup.\n\nTo get started:\n\n1\\. Copy this prompt: **Set me up on S4L end to end**\n\n2\\. Quit fully with CMD+Q, restart Claude, and paste the prompt into a new chat.",
   "author": {

package/mcp/package.json

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

package/mcp/shared/doctor.cjs

@@ -0,0 +1,391 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const PHASES = new Set(["pre_connect", "full"]);
+
+function existsExecutable(file) {
+  if (!file || !fs.existsSync(file)) return false;
+  try {
+    fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findFirst(candidates) {
+  return candidates.find(existsExecutable) || "";
+}
+
+function findPython(home, preferred) {
+  return (
+    findFirst([
+      preferred,
+      process.env.SAPS_PYTHON,
+      path.join(home, ".social-autoposter-mcp", "runtime", ".venv", "bin", "python3"),
+      "/opt/homebrew/bin/python3",
+      "/usr/local/bin/python3",
+      "/usr/bin/python3",
+    ]) || "python3"
+  );
+}
+
+function findUv(home) {
+  return findFirst([
+    path.join(home, ".local", "bin", "uv"),
+    "/opt/homebrew/bin/uv",
+    "/usr/local/bin/uv",
+    "/usr/bin/uv",
+  ]);
+}
+
+function result(status, detail, fix) {
+  return { status, detail, ...(fix ? { fix } : {}) };
+}
+
+function runDoctorSync(options = {}) {
+  const phase = PHASES.has(options.phase) ? options.phase : "full";
+  const home = options.home || os.homedir();
+  const repoDir =
+    options.repoDir ||
+    process.env.SAPS_REPO_DIR ||
+    path.join(home, "social-autoposter");
+  const python = findPython(home, options.python);
+  const harness = path.join(home, ".local", "bin", "browser-harness");
+  const cookiesDb = path.join(
+    home,
+    ".claude",
+    "browser-profiles",
+    "browser-harness",
+    "Default",
+    "Cookies"
+  );
+  const mirrorPath = path.join(
+    home,
+    ".claude",
+    "browser-profiles",
+    "browser-harness.x-cookies.json"
+  );
+  const setupScript = path.join(repoDir, "scripts", "setup_twitter_auth.py");
+  const startedAt = new Date();
+  const checks = [];
+  const add = (id, name, runner) => checks.push({ id, name, runner });
+
+  const mirrorCount = () => {
+    try {
+      const data = JSON.parse(fs.readFileSync(mirrorPath, "utf8"));
+      return Array.isArray(data.cookies) ? data.cookies.length : 0;
+    } catch {
+      return -1;
+    }
+  };
+
+  add("node", "Node.js available", () =>
+    result("pass", process.version)
+  );
+
+  add("python", "Python 3 available", () => {
+    const r = spawnSync(python, ["--version"], {
+      encoding: "utf8",
+      timeout: 15000,
+    });
+    if (r.status === 0) {
+      return result("pass", `${(r.stdout || r.stderr).trim()} (${python})`);
+    }
+    return result(
+      "fail",
+      "python3 not found",
+      "run the owned runtime installer"
+    );
+  });
+
+  add("uv", "uv Python launcher installed", () => {
+    const uv = findUv(home);
+    return uv
+      ? result("pass", uv)
+      : result("fail", "uv not found", "run the owned runtime installer");
+  });
+
+  add("browser_harness", "browser-harness CLI installed", () =>
+    fs.existsSync(harness)
+      ? result("pass", harness)
+      : result(
+          "fail",
+          `not found at ${harness}`,
+          "run the owned runtime installer"
+        )
+  );
+
+  add("browser_harness_shape", "browser-harness CLI shape", () => {
+    if (!fs.existsSync(harness)) {
+      return result("fail", "binary missing", "run the owned runtime installer");
+    }
+    const probe = spawnSync(harness, [], {
+      encoding: "utf8",
+      timeout: 15000,
+    });
+    const usage = `${probe.stdout || ""}${probe.stderr || ""}`;
+    const dashC = /\b-c\b/.test(usage);
+    const stdin = /<<'PY'|<<"PY"|<<PY\b/.test(usage);
+    if (!dashC && !stdin) {
+      return result(
+        "fail",
+        "CLI advertises neither supported invocation shape",
+        "reinstall browser-harness with the owned runtime installer"
+      );
+    }
+    return result("pass", stdin ? "stdin heredoc" : "-c flag");
+  });
+
+  add("chrome_safe_storage", "Chrome Safe Storage readable", () => {
+    if (process.platform !== "darwin") {
+      return result("pass", "not applicable on this platform");
+    }
+    if (phase === "pre_connect") {
+      return result(
+        "expected",
+        "deferred until X connection to avoid an unexpected keychain prompt"
+      );
+    }
+    const r = spawnSync(
+      "security",
+      [
+        "find-generic-password",
+        "-s",
+        "Chrome Safe Storage",
+        "-a",
+        "Chrome",
+        "-w",
+      ],
+      { encoding: "utf8", timeout: 10000 }
+    );
+    if (r.status === 0) {
+      return result("pass", "accessible (cookie import can decrypt Chrome data)");
+    }
+    const tail =
+      (r.stderr || "").trim().split("\n").slice(-1)[0] || `exit ${r.status}`;
+    return result(
+      "fail",
+      tail,
+      "unlock the login keychain, then reconnect X"
+    );
+  });
+
+  add("chrome_cdp", "Managed Chrome CDP responding", () => {
+    const probe = spawnSync(
+      "curl",
+      [
+        "-sf",
+        "--max-time",
+        "2",
+        "-o",
+        "/dev/null",
+        "http://127.0.0.1:9555/json/version",
+      ],
+      { encoding: "utf8" }
+    );
+    if (probe.status === 0) return result("pass", "CDP responding on :9555");
+    if (phase === "pre_connect") {
+      return result(
+        "expected",
+        "managed Chrome is not running yet; connect_x launches it"
+      );
+    }
+    return result(
+      "fail",
+      "no CDP response on :9555",
+      "re-run connect_x to launch managed Chrome"
+    );
+  });
+
+  add("x_session", "X session valid in managed Chrome", () => {
+    if (!fs.existsSync(setupScript)) {
+      return phase === "pre_connect"
+        ? result("expected", "X status script becomes available after runtime installation")
+        : result("fail", `setup script missing at ${setupScript}`, "repair the runtime");
+    }
+    const r = spawnSync(python, [setupScript, "status"], {
+      encoding: "utf8",
+      timeout: 90000,
+    });
+    let out = null;
+    try {
+      out = JSON.parse((r.stdout || "").trim());
+    } catch {
+      out = null;
+    }
+    if (out && out.connected) {
+      return result(
+        "pass",
+        `state=${out.state}${out.handle ? ` handle=@${out.handle}` : ""}`
+      );
+    }
+    const state = out && out.state ? out.state : "unavailable";
+    return phase === "pre_connect"
+      ? result("expected", `state=${state}; X is connected later in onboarding`)
+      : result(
+          "fail",
+          `state=${state}`,
+          "run connect_x and finish any interactive X login"
+        );
+  });
+
+  add("x_cookie_sqlite", "X cookies persisted to Chrome SQLite", () => {
+    if (!fs.existsSync(cookiesDb)) {
+      return phase === "pre_connect"
+        ? result("expected", "Chrome Cookies database has not been created yet")
+        : result("fail", `${cookiesDb} missing`, "re-run connect_x");
+    }
+    const r = spawnSync(
+      python,
+      [
+        "-c",
+        `import sqlite3; c=sqlite3.connect(${JSON.stringify(
+          cookiesDb
+        )}); print(c.execute("SELECT COUNT(*) FROM cookies WHERE host_key LIKE '%x.com' OR host_key LIKE '%twitter.com'").fetchone()[0])`,
+      ],
+      { encoding: "utf8", timeout: 10000 }
+    );
+    const count = Number.parseInt((r.stdout || "0").trim(), 10);
+    if (count > 0) {
+      return result("pass", `${count} x.com/twitter.com rows persisted`);
+    }
+    return phase === "pre_connect"
+      ? result("expected", "no X cookie rows yet; connect_x imports them")
+      : result("fail", "0 x.com/twitter.com rows", "re-run connect_x");
+  });
+
+  add("x_cookie_mirror", "Durable X cookie mirror populated", () => {
+    const count = mirrorCount();
+    if (count > 0) return result("pass", `${count} cookies mirrored`);
+    if (phase === "pre_connect") {
+      return result(
+        "expected",
+        count === 0
+          ? "mirror exists but is empty until X is connected"
+          : "mirror is created during X connection"
+      );
+    }
+    return result(
+      "fail",
+      count === 0
+        ? "mirror file is empty"
+        : `no mirror at ${mirrorPath}`,
+      "re-run connect_x to populate the durable mirror"
+    );
+  });
+
+  add("keychain_autolock", "Login keychain auto-lock is covered", () => {
+    if (process.platform !== "darwin") {
+      return result("pass", "not applicable on this platform");
+    }
+    const keychain = path.join(
+      home,
+      "Library",
+      "Keychains",
+      "login.keychain-db"
+    );
+    const r = spawnSync("security", ["show-keychain-info", keychain], {
+      encoding: "utf8",
+      timeout: 10000,
+    });
+    const output = `${r.stdout || ""}${r.stderr || ""}`;
+    const match = output.match(/timeout=(\d+)s/);
+    if (!match) return result("pass", "no auto-lock timeout detected");
+    const seconds = Number.parseInt(match[1], 10);
+    if (mirrorCount() > 0) {
+      return result(
+        "pass",
+        `auto-locks after ${seconds}s; durable cookie mirror covers relaunches`
+      );
+    }
+    return phase === "pre_connect"
+      ? result(
+          "expected",
+          `auto-locks after ${seconds}s; connect_x will create the protective mirror`
+        )
+      : result(
+          "fail",
+          `auto-locks after ${seconds}s with no durable mirror`,
+          "re-run connect_x to create the mirror"
+        );
+  });
+
+  const completedChecks = checks.map((check) => {
+    const checkStarted = Date.now();
+    try {
+      return {
+        id: check.id,
+        name: check.name,
+        ...check.runner(),
+        duration_ms: Date.now() - checkStarted,
+      };
+    } catch (error) {
+      return {
+        id: check.id,
+        name: check.name,
+        status: "fail",
+        detail: error instanceof Error ? error.message : String(error),
+        duration_ms: Date.now() - checkStarted,
+      };
+    }
+  });
+  const summary = { pass: 0, fail: 0, expected: 0, warn: 0, total: checks.length };
+  for (const check of completedChecks) {
+    if (Object.prototype.hasOwnProperty.call(summary, check.status)) {
+      summary[check.status] += 1;
+    }
+  }
+  const completedAt = new Date();
+  return {
+    schema_version: 1,
+    phase,
+    ok: summary.fail === 0,
+    started_at: startedAt.toISOString(),
+    completed_at: completedAt.toISOString(),
+    duration_ms: completedAt.getTime() - startedAt.getTime(),
+    summary,
+    checks: completedChecks,
+  };
+}
+
+function formatDoctorReport(report) {
+  const glyph = {
+    pass: "OK",
+    fail: "FAIL",
+    expected: "WAIT",
+    warn: "WARN",
+  };
+  const lines = [
+    `social-autoposter doctor — ${report.phase.replace("_", " ")} phase`,
+    "",
+  ];
+  for (const check of report.checks) {
+    lines.push(
+      `  [${(glyph[check.status] || check.status.toUpperCase()).padEnd(4)}] ${
+        check.name
+      }: ${check.detail || ""}`
+    );
+    if (check.fix) lines.push(`         fix: ${check.fix}`);
+  }
+  lines.push(
+    "",
+    `${report.summary.pass}/${report.summary.total} passed, ` +
+      `${report.summary.expected} expected, ${report.summary.fail} failed.`
+  );
+  if (!report.ok) {
+    lines.push(
+      "Address the failures above and re-run `npx social-autoposter doctor`."
+    );
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  formatDoctorReport,
+  runDoctorSync,
+};

package/mcp/shared/onboarding-ledger.cjs

@@ -0,0 +1,324 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SCHEMA_VERSION = 1;
+const MILESTONES = [
+  "environment_checked",
+  "runtime_ready",
+  "x_connected",
+  "profile_scanned",
+  "mode_chosen",
+  "project_ready",
+  "topics_seeded",
+  "tasks_scheduled",
+];
+
+function stateDir(opts = {}) {
+  return (
+    opts.stateDir ||
+    process.env.SAPS_STATE_DIR ||
+    path.join(os.homedir(), ".social-autoposter-mcp")
+  );
+}
+
+function ledgerPath(opts = {}) {
+  return path.join(stateDir(opts), "onboarding-progress.json");
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function freshMilestone() {
+  return {
+    status: "pending",
+    attempts: 0,
+  };
+}
+
+function freshLedger() {
+  const at = now();
+  return {
+    schema_version: SCHEMA_VERSION,
+    started_at: at,
+    updated_at: at,
+    current_blocker: null,
+    milestones: Object.fromEntries(MILESTONES.map((id) => [id, freshMilestone()])),
+    doctor: {
+      latest: null,
+      runs: [],
+    },
+    events: [],
+  };
+}
+
+function normalizeLedger(value) {
+  const base = freshLedger();
+  if (!value || typeof value !== "object") return base;
+  const input = value;
+  base.started_at =
+    typeof input.started_at === "string" ? input.started_at : base.started_at;
+  base.updated_at =
+    typeof input.updated_at === "string" ? input.updated_at : base.updated_at;
+  base.current_blocker =
+    input.current_blocker && typeof input.current_blocker === "object"
+      ? input.current_blocker
+      : null;
+  for (const id of MILESTONES) {
+    const old =
+      input.milestones && typeof input.milestones === "object"
+        ? input.milestones[id]
+        : null;
+    if (!old || typeof old !== "object") continue;
+    base.milestones[id] = {
+      ...freshMilestone(),
+      ...old,
+      attempts: Number.isFinite(Number(old.attempts))
+        ? Math.max(0, Number(old.attempts))
+        : 0,
+    };
+  }
+  if (input.doctor && typeof input.doctor === "object") {
+    base.doctor.latest = input.doctor.latest || null;
+    base.doctor.runs = Array.isArray(input.doctor.runs)
+      ? input.doctor.runs
+      : [];
+  }
+  base.events = Array.isArray(input.events) ? input.events : [];
+  return base;
+}
+
+function readLedger(opts = {}) {
+  try {
+    const file = ledgerPath(opts);
+    if (!fs.existsSync(file)) return freshLedger();
+    return normalizeLedger(JSON.parse(fs.readFileSync(file, "utf8")));
+  } catch {
+    return freshLedger();
+  }
+}
+
+function writeLedger(ledger, opts = {}) {
+  const dir = stateDir(opts);
+  const file = ledgerPath(opts);
+  fs.mkdirSync(dir, { recursive: true });
+  ledger.schema_version = SCHEMA_VERSION;
+  ledger.updated_at = now();
+  const tmp = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(ledger, null, 2) + "\n", {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  fs.renameSync(tmp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // Best effort on filesystems that do not expose POSIX permissions.
+  }
+  return ledger;
+}
+
+function assertMilestone(id) {
+  if (!MILESTONES.includes(id)) {
+    throw new Error(`unknown onboarding milestone: ${id}`);
+  }
+}
+
+function appendEvent(ledger, event) {
+  const milestone = ledger.milestones[event.milestone];
+  ledger.events.push({
+    event_id: crypto.randomUUID(),
+    occurred_at: now(),
+    milestone: event.milestone,
+    type: event.type,
+    attempt: milestone ? milestone.attempts : 0,
+    status: milestone ? milestone.status : undefined,
+    code: event.code,
+    metadata: event.metadata || {},
+    backend_sent_at: null,
+  });
+}
+
+function mutate(opts, fn) {
+  const ledger = readLedger(opts);
+  fn(ledger);
+  return writeLedger(ledger, opts);
+}
+
+function recordAttempt(id, metadata = {}, opts = {}) {
+  assertMilestone(id);
+  return mutate(opts, (ledger) => {
+    const at = now();
+    const milestone = ledger.milestones[id];
+    milestone.attempts += 1;
+    milestone.last_attempt_at = at;
+    milestone.first_started_at = milestone.first_started_at || at;
+    if (milestone.status !== "complete") milestone.status = "in_progress";
+    if (ledger.current_blocker?.milestone === id) ledger.current_blocker = null;
+    appendEvent(ledger, { milestone: id, type: "attempt", metadata });
+  });
+}
+
+function completeMilestone(id, metadata = {}, opts = {}) {
+  assertMilestone(id);
+  return mutate(opts, (ledger) => {
+    const milestone = ledger.milestones[id];
+    if (milestone.status === "complete") return;
+    const at = now();
+    milestone.status = "complete";
+    milestone.completed_at = at;
+    milestone.last_attempt_at = milestone.last_attempt_at || at;
+    milestone.first_started_at = milestone.first_started_at || at;
+    if (milestone.attempts === 0) milestone.attempts = 1;
+    if (ledger.current_blocker?.milestone === id) ledger.current_blocker = null;
+    appendEvent(ledger, { milestone: id, type: "completed", metadata });
+  });
+}
+
+function blockMilestone(id, code, message, metadata = {}, opts = {}) {
+  assertMilestone(id);
+  return mutate(opts, (ledger) => {
+    const at = now();
+    const milestone = ledger.milestones[id];
+    if (milestone.attempts === 0) milestone.attempts = 1;
+    milestone.status = "blocked";
+    milestone.last_attempt_at = at;
+    milestone.first_started_at = milestone.first_started_at || at;
+    milestone.last_error_code = code;
+    milestone.last_error = message;
+    ledger.current_blocker = {
+      milestone: id,
+      code,
+      message,
+      at,
+      attempt: milestone.attempts,
+    };
+    appendEvent(ledger, {
+      milestone: id,
+      type: "blocked",
+      code,
+      metadata,
+    });
+  });
+}
+
+function recordDoctorReport(report, opts = {}) {
+  return mutate(opts, (ledger) => {
+    const milestone = ledger.milestones.environment_checked;
+    const at = now();
+    const fullFailure =
+      report && report.phase === "full" && report.ok === false;
+    const preserveFullFailure =
+      report &&
+      report.phase === "pre_connect" &&
+      ledger.current_blocker?.milestone === "environment_checked" &&
+      ledger.current_blocker?.code === "doctor_full_failed";
+    milestone.attempts += 1;
+    milestone.last_attempt_at = at;
+    milestone.first_started_at = milestone.first_started_at || at;
+    milestone.status = fullFailure || preserveFullFailure ? "blocked" : "complete";
+    milestone.completed_at = fullFailure || preserveFullFailure
+      ? milestone.completed_at
+      : milestone.completed_at || at;
+    milestone.last_doctor_ok = Boolean(report && report.ok);
+    milestone.last_doctor_phase = report && report.phase;
+    if (fullFailure) {
+      milestone.last_error_code = "doctor_full_failed";
+      milestone.last_error = `Full Doctor found ${report.summary?.fail ?? 1} failing check(s).`;
+      ledger.current_blocker = {
+        milestone: "environment_checked",
+        code: "doctor_full_failed",
+        message: milestone.last_error,
+        at,
+        attempt: milestone.attempts,
+      };
+    } else if (
+      !preserveFullFailure &&
+      ledger.current_blocker?.milestone === "environment_checked"
+    ) {
+      ledger.current_blocker = null;
+    }
+    ledger.doctor.latest = report;
+    ledger.doctor.runs.push(report);
+    appendEvent(ledger, {
+      milestone: "environment_checked",
+      type: "doctor",
+      code: report && report.ok ? "doctor_ok" : "doctor_issues",
+      metadata: {
+        phase: report && report.phase,
+        ok: Boolean(report && report.ok),
+        summary: report && report.summary,
+        check_statuses: Object.fromEntries(
+          Array.isArray(report && report.checks)
+            ? report.checks.map((check) => [check.id, check.status])
+            : []
+        ),
+      },
+    });
+  });
+}
+
+function pendingBackendEvents(opts = {}) {
+  return readLedger(opts).events.filter((event) => !event.backend_sent_at);
+}
+
+function markBackendEventsSent(eventIds, opts = {}) {
+  const ids = new Set(eventIds || []);
+  if (ids.size === 0) return readLedger(opts);
+  return mutate(opts, (ledger) => {
+    const sentAt = now();
+    for (const event of ledger.events) {
+      if (ids.has(event.event_id)) event.backend_sent_at = sentAt;
+    }
+  });
+}
+
+function publicSnapshot(opts = {}) {
+  const ledger = readLedger(opts);
+  return {
+    schema_version: ledger.schema_version,
+    started_at: ledger.started_at,
+    updated_at: ledger.updated_at,
+    complete: MILESTONES.every(
+      (id) => ledger.milestones[id].status === "complete"
+    ),
+    milestones: MILESTONES.map((id) => ({
+      id,
+      ...ledger.milestones[id],
+    })),
+    current_blocker: ledger.current_blocker,
+    doctor: ledger.doctor.latest
+      ? {
+          phase: ledger.doctor.latest.phase,
+          ok: ledger.doctor.latest.ok,
+          completed_at: ledger.doctor.latest.completed_at,
+          summary: ledger.doctor.latest.summary,
+          checks: (ledger.doctor.latest.checks || []).map((check) => ({
+            id: check.id,
+            name: check.name,
+            status: check.status,
+            detail: check.detail,
+            fix: check.fix,
+          })),
+        }
+      : null,
+  };
+}
+
+module.exports = {
+  MILESTONES,
+  blockMilestone,
+  completeMilestone,
+  ledgerPath,
+  markBackendEventsSent,
+  pendingBackendEvents,
+  publicSnapshot,
+  readLedger,
+  recordAttempt,
+  recordDoctorReport,
+  writeLedger,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "social-autoposter",
-  "version": "1.6.142",
+  "version": "1.6.144",
   "description": "Automated social posting pipeline for Reddit, X/Twitter, LinkedIn, and Moltbook. Install as a Claude Code agent skill.",
   "bin": {
     "social-autoposter": "bin/cli.js"
@@ -122,6 +122,7 @@
     "mcp-servers/",
     "mcp/dist/",
     "!mcp/dist/pipeline.tgz",
+    "mcp/shared/",
     "mcp/menubar/",
     "mcp/package.json",
     "mcp/manifest.json",

package/scripts/claude_job.py

@@ -164,6 +164,59 @@ DEFAULT_TIMEOUT_S = int(os.environ.get("SAPS_CLAUDE_QUEUE_TIMEOUT", "1800"))
 # it would feed a stale prompt to a worker much later. Default 2x the timeout.
 STALE_TTL_S = int(os.environ.get("SAPS_CLAUDE_QUEUE_STALE_TTL", str(DEFAULT_TIMEOUT_S * 2)))
 
+# ---------------------------------------------------------------------------
+# EXPERIMENT (2026-06-29, per user): hide the "Top Posts by Project" few-shot
+# block from the Phase-2b drafting prompt.
+#
+# WHY: that block is ~42% of the prompt — top_performers.py emits up to 5 curated
+# example posts for EVERY project (~20 projects = ~74 examples, ~16k tokens), and
+# it is NOT scoped to the projects in this cycle's candidates. On a `.mcpb` box the
+# drafting runs inside a Claude Desktop scheduled-task session that the app
+# SIGTERMs after ~120s; the 38k-token prompt pushed the worker past that window
+# before it could submit, so jobs never drained. Dropping this block shrinks the
+# prompt to ~22k tokens (one Read, faster turns) while KEEPING the "Best Example
+# Per Style" block (which is style-scoped and tiny).
+#
+# This is a DELIVERY-LAYER trim only: the generator (top_performers.py, locked) is
+# untouched — we strip the section from the prompt text right before it is queued.
+# A loud marker is left in its place and a provider.log line is emitted, so it is
+# obvious the section was intentionally hidden, not lost.
+#
+# DEFAULT: ON (hidden). Set SAPS_HIDE_TOP_BY_PROJECT=0 (or false/no) to restore the
+# full per-project example block.
+HIDE_TOP_BY_PROJECT = (
+    os.environ.get("SAPS_HIDE_TOP_BY_PROJECT", "1").strip().lower()
+    not in ("0", "false", "no", "off", "")
+)
+
+
+def _strip_top_by_project(prompt: str) -> str:
+    """Remove the '### Top Posts by Project' block from a drafting prompt.
+
+    Returns the prompt with that one section replaced by a clearly-labelled
+    HIDDEN marker (so anyone reading the prompt sees it was intentionally hidden
+    behind SAPS_HIDE_TOP_BY_PROJECT, not silently dropped). No-op if the block is
+    absent (e.g. query prompts, or a report that produced no per-project posts).
+    The section runs from its '### Top Posts by Project' header to the next '##'/
+    '###' header (normally '### Bottom N Posts').
+    """
+    start = "### Top Posts by Project"
+    i = prompt.find(start)
+    if i < 0:
+        return prompt
+    m = re.search(r"\n#{2,3} ", prompt[i + len(start):])
+    j = (i + len(start) + m.start() + 1) if m else len(prompt)
+    marker = (
+        "### Top Posts by Project — HIDDEN\n"
+        "[This per-project few-shot block (~16k tokens) was hidden at the delivery "
+        "layer by claude_job.py via SAPS_HIDE_TOP_BY_PROJECT (default ON, added "
+        "2026-06-29) so the drafting worker fits Claude Desktop's ~120s "
+        "scheduled-session window. Set SAPS_HIDE_TOP_BY_PROJECT=0 to restore it. "
+        "The 'Best Example Per Style' block above is kept.]\n\n"
+    )
+    return prompt[:i] + marker + prompt[j:]
+
+
 
 # --------------------------------------------------------------------------- #
 # Queue layout                                                                #
@@ -508,6 +561,19 @@ def cmd_provider(ns) -> int:
         except Exception:
             schema_text = None
 
+    # Delivery-layer trim: hide the "Top Posts by Project" block from drafting
+    # prompts so the worker fits the ~120s scheduled-session window. See
+    # HIDE_TOP_BY_PROJECT / _strip_top_by_project above. Drafting jobs only.
+    if qtype == "twitter-prep" and HIDE_TOP_BY_PROJECT:
+        _before_len = len(prompt)
+        prompt = _strip_top_by_project(prompt)
+        if len(prompt) != _before_len:
+            _plog(
+                "hid 'Top Posts by Project' block: -%d chars "
+                "(SAPS_HIDE_TOP_BY_PROJECT on; set =0 to restore)"
+                % (_before_len - len(prompt))
+            )
+
     job_id = uuid.uuid4().hex
     created = time.time()
     _ensure_dirs(qtype)