@m13v/s4l 1.7.12-rc.7 → 1.7.12-rc.9

package/mcp/dist/index.js

@@ -3832,8 +3832,8 @@ async function autopilotLoaded() {
 // fires every minute, claims ONE job, runs the pipeline's own prompt as its
 // Claude turn, writes the result back, and stops.
 // ===========================================================================
-const QUEUE_WORKER_PROMPT_VERSION = 9; // v9 (2026-07-17): poll window widened 240s -> 900s (see QUEUE_WORKER_POLL_SECONDS); version bump forces the prompt refresh that carries the new --wait-seconds onto existing installs. v8: worker polls internally (claude_job.py next --wait-seconds) instead of single-shot check-then-die. Empirically verified (2026-07-06) that a single long-running Bash call survives well past the host's ~90s between-tool-call inactivity kill — that timer only fires on MODEL silence, not on one in-flight tool call — so one Bash call can safely poll for QUEUE_WORKER_POLL_SECONDS before giving up. This cuts the every-minute spin-up-empty-then-die husk cycle down to roughly one session per poll window instead of one per cron tick. v7: universal type-blind worker. ONE task claims `--type any`; per-type execution notes (e.g. the v6 incremental-draft pacing for twitter-prep) moved into claude_job.py TYPE_TO_WORKER_NOTES and ride the prompt sidecar, so the worker prompt never mentions job types. Legacy per-type tasks get this same body on refresh and become interchangeable universal workers.
-// v10 (PLANNED, NOT IMPLEMENTED): delegate the actual drafting to a fresh
+const QUEUE_WORKER_PROMPT_VERSION = 10; // v10 (2026-10-29): poll window 900s -> 540s so one `next` call fits inside the Bash tool's 600s default timeout, self-reap disabled (S4L_WORKER_SELF_REAP=0 on every claude_job call), and the session ends by archiving itself instead of a SIGTERM. v9 (2026-07-17): poll window widened 240s -> 900s; version bump forces the prompt refresh that carries the new --wait-seconds onto existing installs. v8: worker polls internally (claude_job.py next --wait-seconds) instead of single-shot check-then-die. Empirically verified (2026-07-06) that a single long-running Bash call survives well past the host's ~90s between-tool-call inactivity kill — that timer only fires on MODEL silence, not on one in-flight tool call — so one Bash call can safely poll for QUEUE_WORKER_POLL_SECONDS before giving up. This cuts the every-minute spin-up-empty-then-die husk cycle down to roughly one session per poll window instead of one per cron tick. v7: universal type-blind worker. ONE task claims `--type any`; per-type execution notes (e.g. the v6 incremental-draft pacing for twitter-prep) moved into claude_job.py TYPE_TO_WORKER_NOTES and ride the prompt sidecar, so the worker prompt never mentions job types. Legacy per-type tasks get this same body on refresh and become interchangeable universal workers.
+// v11 (PLANNED, NOT IMPLEMENTED): delegate the actual drafting to a fresh
 // sub-agent per claimed job (claim -> delegate -> wait -> claim next, looped
 // within one continuous worker session) instead of drafting inline. Validated
 // via throwaway probe tasks 2026-07-07/08 (10 loop iterations, ~210s of real
@@ -3842,10 +3842,19 @@ const QUEUE_WORKER_PROMPT_VERSION = 9; // v9 (2026-07-17): poll window widened 2
 // notification) or the host kills the whole parent+child chain in 1-3 min.
 // Never live-fire tested against a real production job. Full design, what's
 // validated vs not, and the implementation steps: docs/queue-worker-delegation-plan.md
-// Bump this constant to 10 only once that plan is actually implemented.
+// Bump this constant to 11 only once that plan is actually implemented.
 const QUEUE_WORKER_PROMPT_MARKER = "s4l_queue_worker_prompt_version";
 // How long ONE `next --wait-seconds` call polls before giving up and exiting.
-// 900s (15 min, per Matthew 2026-07-17, up from 240s): sits AT the single-
+// 540s (9 min, 2026-10-29, down from 900s): MUST stay below the Bash tool's
+// 600s default timeout. Measured on 2026-10-29 in Claude Desktop 4.29: the
+// 900s poll hit the 600s tool timeout on every empty cycle (81 of 106 runs
+// that day), the CLI then re-emitted a ~200KB prompt snapshot (a 7s
+// main-thread stall in the app), the poller kept running as an orphaned
+// background task for the remaining 300s, and its self-reap SIGTERM cost one
+// or two more 7s stalls plus an exit-143 re-attach. With the poll inside the
+// tool timeout the call returns normally, nothing is orphaned, and the worker
+// archives itself (step 5 of the prompt) at zero measured cost.
+// Earlier rationale (900s, per Matthew 2026-07-17, up from 240s): sits AT the single-
 // Bash-call survival ceiling verified live on 2026-07-06 (the host's ~90s
 // inactivity kill fires only on model silence, and one in-flight tool call
 // survived a full 900s probe). This covers the ~8min average real job
@@ -3861,7 +3870,7 @@ const QUEUE_WORKER_PROMPT_MARKER = "s4l_queue_worker_prompt_version";
 // poll window is legitimately still working, not a husk, and a too-tight
 // claim_grace would SIGTERM it mid-poll before it ever gets to claim.
 // (Bumped to 1020s alongside this change.)
-const QUEUE_WORKER_POLL_SECONDS = 900;
+const QUEUE_WORKER_POLL_SECONDS = 540;
 // One spec per worker task. queueType MUST match scripts/claude_job.py TAG_TO_TYPE.
 const QUEUE_WORKERS = [
     { taskId: WORKER_TASK_ID, queueType: "any", human: "universal queue" },
@@ -3983,8 +3992,9 @@ function queueWorkerBody(spec) {
         `The deterministic pipeline runs on this Mac. When it needs a Claude turn it ` +
             `drops a job on a local file queue. Your only job: pick up the next job, do ` +
             `EXACTLY what its prompt says, hand the result back. You do this with Bash, ` +
-            `Read, and Write, and NOTHING else. This run is unattended — reaching for any ` +
-            `other tool, or trying to "investigate", STALLS it forever.`,
+            `Read, and Write, and NOTHING else (except the single archive call in step 5). ` +
+            `This run is unattended — reaching for any other tool, or trying to ` +
+            `"investigate", STALLS it forever.`,
         ``,
         `PACING — CRITICAL: this unattended session is terminated ~90 seconds after ` +
             `your LAST tool call (a host inactivity timeout). That clock only runs BETWEEN ` +
@@ -4000,11 +4010,16 @@ function queueWorkerBody(spec) {
         `1. Look for the next job. Run this EXACT Bash command and let it run to ` +
             `completion — it polls internally for up to ${Math.round(QUEUE_WORKER_POLL_SECONDS / 60)} ` +
             `minutes before giving up, so it may take a while to return. That is normal: ` +
-            `do NOT interrupt it and do NOT make any other tool call while it is running.`,
-        `     ${py} ${job} next --type any --prompt-file --wait-seconds ${QUEUE_WORKER_POLL_SECONDS} --state-dir ${sd}`,
+            `do NOT interrupt it and do NOT make any other tool call while it is running. ` +
+            `Pass the Bash tool's timeout parameter as 600000 (its 10-minute maximum) so ` +
+            `the call is never moved to the background. If the result nevertheless says ` +
+            `the command was moved to the background (this happens when the Mac sleeps ` +
+            `mid-poll; the timeout is wall-clock), do NOT wait for it: call TaskStop with ` +
+            `the ID it gives you, report "no jobs" in one line, and go to step 5.`,
+        `     S4L_WORKER_SELF_REAP=0 ${py} ${job} next --type any --prompt-file --wait-seconds ${QUEUE_WORKER_POLL_SECONDS} --state-dir ${sd}`,
         `   It prints one line of JSON once it returns. If it prints "{}" (empty), no ` +
             `job showed up during the whole poll window — report "no jobs" in one line ` +
-            `and STOP. You are done.`,
+            `and go to step 5.`,
         `2. Otherwise it prints {"job_id":"...","prompt_file":"...","schema_file":...}. ` +
             `Use the Read tool to read prompt_file; it is the complete, self-contained ` +
             `instruction the pipeline wrote for you. If the Read result says it is partial ` +
@@ -4014,20 +4029,28 @@ function queueWorkerBody(spec) {
             `ONLY that JSON object — no prose, no markdown, no code fences.`,
         `3. Submit it. Write your JSON object to ${outDir}/out-<job_id>.json using the ` +
             `Write tool (substitute the real job_id), then run this EXACT Bash command:`,
-        `     ${py} ${job} result --job <job_id> --result-file ${outDir}/out-<job_id>.json --state-dir ${sd}`,
+        `     S4L_WORKER_SELF_REAP=0 ${py} ${job} result --job <job_id> --result-file ${outDir}/out-<job_id>.json --state-dir ${sd}`,
         `   If it reports the result was rejected (bad JSON / missing keys), fix your JSON ` +
             `and submit again — at most twice. If it still fails, run ` +
-            `\`${py} ${job} result --job <job_id> --error --state-dir ${sd}\` (type a one-line ` +
-            `reason, then Ctrl-D) and STOP.`,
-        `4. Report in ONE short line what you did, then STOP. Do NOT claim another job, ` +
-            `do NOT loop, do NOT read other files, do NOT call any other tool.`,
+            `\`S4L_WORKER_SELF_REAP=0 ${py} ${job} result --job <job_id> --error --state-dir ${sd}\` (type a one-line ` +
+            `reason, then Ctrl-D) and go to step 5.`,
+        `4. Report in ONE short line what you did. Do NOT claim another job, ` +
+            `do NOT loop, do NOT read other files.`,
+        `5. End this session yourself. Call ToolSearch with the query ` +
+            `"select:mcp__ccd_session_mgmt__archive_session", then call ` +
+            `mcp__ccd_session_mgmt__archive_session with session_id "self" and reason ` +
+            `"s4l worker done". That archive call must be your very last tool call; it ` +
+            `ends the session cleanly (no SIGTERM, no idle wait). If the tool is not ` +
+            `available, just STOP.`,
         ``,
         `HARD RULES: use ONLY the Bash tool (to run claude_job.py AND any persist ` +
             `commands the job's prompt explicitly gives you), the Read tool (the ` +
             `prompt/schema sidecar + the SKILL/config files the prompt names), and the ` +
-            `Write tool (the result file). NEVER post, reply, open a browser, or run any ` +
-            `command the prompt does not explicitly give you. An empty queue is the ` +
-            `NORMAL, expected case most minutes — it is success, not a problem to debug.`,
+            `Write tool (the result file), plus TaskStop ONLY for a backgrounded poll, and ` +
+            `ToolSearch and mcp__ccd_session_mgmt__archive_session ONLY as the final step 5. NEVER post, ` +
+            `reply, open a browser, or run any command the prompt does not explicitly ` +
+            `give you. An empty queue is the NORMAL, expected case most minutes — it is ` +
+            `success, not a problem to debug.`,
     ].join("\n");
 }
 // Full canonical SKILL.md (frontmatter + body + version marker) the MCP writes

package/mcp/dist/setup.js

@@ -45,6 +45,37 @@ export function configPath() {
         return p; // not created yet: return the intended path unresolved
     }
 }
+// Atomic config.json write (2026-10-30). Never write config.json in place:
+// writeFileSync truncates the file first, so a reader in that window (or an
+// interrupted write) sees a torn file and every pipeline lane dies on it.
+// Write a same-directory temp file, fsync, then rename over the target so
+// readers only ever see the old or the new complete file. Keeps the
+// timestamped .bak- copy the call sites used to make.
+export function writeConfigAtomic(cfg) {
+    const cfgPath = configPath();
+    if (fs.existsSync(cfgPath)) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        fs.copyFileSync(cfgPath, `${cfgPath}.bak-${stamp}`);
+    }
+    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
+    const tmp = `${cfgPath}.tmp-${process.pid}`;
+    try {
+        const fd = fs.openSync(tmp, "w");
+        try {
+            fs.writeSync(fd, JSON.stringify(cfg, null, 2) + "\n");
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, cfgPath);
+    }
+    finally {
+        if (fs.existsSync(tmp))
+            fs.unlinkSync(tmp);
+    }
+    return cfgPath;
+}
 // One-time (idempotent) migration to the state-dir home, run at server boot.
 // Cases:
 //   - no state config, legacy is a REAL file  -> move it up, leave a symlink
@@ -360,13 +391,7 @@ export function applySetup(input) {
         cfg.projects.push(entry);
         created = true;
     }
-    const cfgPath = configPath();
-    if (fs.existsSync(cfgPath)) {
-        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-        fs.copyFileSync(cfgPath, `${cfgPath}.bak-${stamp}`);
-    }
-    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
-    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    writeConfigAtomic(cfg);
     void sendStateSnapshot("config_write");
     if (!persona)
         recordManagedProject(input.name);
@@ -418,13 +443,7 @@ export function recordRedditAccount(username) {
     if (!reddit.login_method)
         reddit.login_method = "browser";
     try {
-        const cfgPath = configPath();
-        if (fs.existsSync(cfgPath)) {
-            const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-            fs.copyFileSync(cfgPath, `${cfgPath}.bak-${stamp}`);
-        }
-        fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
-        fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+        writeConfigAtomic(cfg);
         void sendStateSnapshot("config_write");
         return { written: true, detail: `accounts.reddit.username = ${clean}` };
     }
@@ -541,13 +560,7 @@ export function ensurePersonaProject(grounding) {
         name = PERSONA_DEFAULT_NAME;
         created = true;
     }
-    const cfgPath = configPath();
-    if (fs.existsSync(cfgPath)) {
-        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-        fs.copyFileSync(cfgPath, `${cfgPath}.bak-${stamp}`);
-    }
-    fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
-    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    const cfgPath = writeConfigAtomic(cfg);
     // Raw dictation transcript -> persona_corpus.txt sidecar (NOT config.json).
     // Mirrors scripts/build_persona.py cmd_apply: config.json is inlined into many
     // prompts (ALL_PROJECTS_JSON), so a multi-KB corpus there would bloat every
@@ -598,13 +611,7 @@ export function ensureShortLinksDefault() {
             changed = true;
         }
         if (changed) {
-            const cfgPath = configPath();
-            if (fs.existsSync(cfgPath)) {
-                const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-                fs.copyFileSync(cfgPath, `${cfgPath}.bak-${stamp}`);
-            }
-            fs.mkdirSync(path.dirname(cfgPath), { recursive: true });
-            fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+            writeConfigAtomic(cfg);
             void sendStateSnapshot("config_write");
         }
     }

package/mcp/dist/version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.7.12-rc.7",
-  "installedAt": "2026-09-24T20:17:26.520Z"
+  "version": "1.7.12-rc.9",
+  "installedAt": "2026-10-30T18:59:09.558Z"
 }

package/mcp/manifest.json

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

package/mcp/menubar/s4l_menubar.py

@@ -1690,6 +1690,30 @@ class S4LMenuBar(rumps.App):
         verification on such machines.
         """
         app_support = os.path.expanduser("~/Library/Application Support")
+        # LIVE profile first (2026-09-28): on a multi-profile machine (account
+        # rotator: Claude, Claude-mediar, Claude-mddy, ...) every profile keeps
+        # its OWN copy of the extension, and "newest mtime" is simply the
+        # profile that was updated most recently, not the one Claude is
+        # running right now. The operator Mac sat on 1.7.7-rc.4 in the live
+        # Claude-mediar profile for two months while every update landed in
+        # Claude-mddy, and the updater kept reporting "already on latest".
+        # Prefer the extension dir under a RUNNING Claude's --user-data-dir
+        # (default profile == plain "Claude"); fall back to the newest-mtime
+        # scan only when no Claude instance is running. Mirrors
+        # scripts/s4l_box_update.sh; keep the two in sync.
+        for udd in S4LMenuBar._claude_user_data_dirs():
+            root = os.path.join(udd or os.path.join(app_support, "Claude"),
+                                "Claude Extensions")
+            try:
+                names = sorted(os.listdir(root))
+            except OSError:
+                continue
+            for name in names:
+                if not name.endswith("social-autoposter"):
+                    continue
+                d = os.path.join(root, name)
+                if os.path.exists(os.path.join(d, "manifest.json")):
+                    return d
         best, best_mtime = None, -1.0
         for root in glob.glob(os.path.join(app_support, "Claude*", "Claude Extensions")):
             try:

package/mcp/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/s4l",
-  "version": "1.7.12-rc.7",
+  "version": "1.7.12-rc.9",
   "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",
@@ -41,6 +41,23 @@
     "!scripts/_gsc_roi_query.py",
     "!scripts/batch_send_dms.py",
     "!scripts/finalize_post_*.py",
+    "!scripts/insert_[0-9]*.py",
+    "!scripts/insert[0-9]*.py",
+    "!scripts/ins[0-9]*.py",
+    "!scripts/tlh_pick_*.py",
+    "!scripts/tlh_freshness_*.py",
+    "!scripts/tlh_fresh.py",
+    "!scripts/tlh_stale.py",
+    "!scripts/fresh[0-9]*.py",
+    "!scripts/hist[0-9]*.py",
+    "!scripts/q[0-9]*.py",
+    "!scripts/show[0-9]*.py",
+    "!scripts/stale[0-9]*.py",
+    "!scripts/stale_[0-9]*.py",
+    "!scripts/stale_classes_*.py",
+    "!scripts/stale_clips_*.py",
+    "!scripts/r[0-9]*.py",
+    "!scripts/w[0-9]*.py",
     "!scripts/insert_li_notifs.py",
     "!scripts/li_notif_scan_process.py",
     "!scripts/phase_d_edit.py",

package/scripts/angles.py

@@ -0,0 +1,8 @@
+import os,psycopg2
+from dotenv import load_dotenv
+load_dotenv(os.path.expanduser('~/social-autoposter/.env'))
+c=psycopg2.connect(os.environ['DATABASE_URL']).cursor()
+c.execute("select distinct metadata->>'theme_angle' from media_posts")
+print(' '.join(sorted(r[0] or '' for r in c.fetchall())))
+c.execute("select distinct metadata->>'engagement_style' from media_posts")
+print([r[0] for r in c.fetchall()])

package/scripts/claude_job.py

@@ -1303,38 +1303,22 @@ def cmd_provider(ns) -> int:
 # next (consumer side, run by a scheduled task)                               #
 # --------------------------------------------------------------------------- #
 def _agent_session_pid():
-    """Best-effort: the Claude agent-mode SESSION pid running THIS worker — the
-    exact process the stale-session reaper (reap_stale_claude_sessions.py) would
-    target. We climb our own process tree to the ancestor whose cmd carries the
-    reaper's worker signature ('claude-code/' + 'local-agent-mode-sessions') and
-    return its pid, so the claim can be stamped with it and the reaper can SPARE
-    that session for the whole drafting turn (instead of SIGTERMing it at the short
-    grace window — the 2026-06-29 draft-kill regression). None if not identifiable;
-    the reaper then falls back to its newest-spare heuristic.
-    """
+    """Best-effort: pid of the Claude agent-mode SESSION running THIS worker —
+    the exact process the stale-session reaper (reap_stale_claude_sessions.py)
+    would target. The claim is stamped with it
+    so the reaper (a) SPARES that session for the whole drafting turn (the
+    2026-06-29 draft-kill regression) and (b) re-queues the job once that
+    session is dead (release_stale_claims, ~2 min). Shares _find_own_session's
+    signature: the old private copy matched 'local-agent-mode-sessions', which
+    current Desktop builds no longer put on the cmdline, so every claim went
+    unstamped and a claim whose session died stranded its producer for the full
+    ~30 min timeout (2026-10-30: Desktop relaunched a minute after a claim).
+    None if not identifiable."""
     try:
-        out = subprocess.run(
-            ["/bin/ps", "-axo", "pid=,ppid=,command="],
-            capture_output=True, text=True, timeout=10,
-        ).stdout
-        info = {}
-        for line in out.splitlines():
-            m = re.match(r"\s*(\d+)\s+(\d+)\s+(.*)$", line)
-            if m:
-                info[int(m.group(1))] = (int(m.group(2)), m.group(3))
-        pid = os.getpid()
-        for _ in range(16):  # bounded climb up the tree
-            ent = info.get(pid)
-            if not ent or ent[0] <= 1:
-                break
-            ppid = ent[0]
-            pcmd = info.get(ppid, (0, ""))[1]
-            if ("claude-code/" in pcmd) and ("local-agent-mode-sessions" in pcmd):
-                return ppid
-            pid = ppid
+        found = _find_own_session(_ps_pid_map())
     except Exception:
         return None
-    return None
+    return found[0] if found else None
 
 
 def _attempt_claim(ns, qtype: str) -> bool:

package/scripts/config.py

@@ -27,15 +27,22 @@ Resolution order for the repo root (single source of truth):
 $S4L_CONFIG_PATH overrides the config file location outright (some installs
 pin the operator config, e.g. ~/s4l/config.json, independent of the code dir).
 
-Do NOT add write helpers here. Config writes go through the MCP server's
-project_config tool (it owns validation and the state snapshot); pipeline
-scripts are readers.
+Config writes: user-facing edits go through the MCP server's project_config
+tool (it owns validation and the state snapshot). The few pipeline scripts
+that must persist runtime state into config.json (subreddit bans) MUST use
+update_config() below and nothing else: never `open(config, "w")` +
+json.dump. That in-place pattern truncates the file to 0 bytes and streams it
+back, so any interruption leaves a torn prefix that breaks every reader
+(2026-09-06, 09-30, 10-22, 10-29 outages; the 10-29 one stopped all X
+drafting for ~23h).
 """
 
 from __future__ import annotations
 
+import fcntl
 import json
 import os
+import sys
 
 _CACHE: dict | None = None
 _CACHE_PATH: str | None = None
@@ -98,6 +105,47 @@ def load_config(fresh: bool = False) -> dict:
     return _CACHE
 
 
+def update_config(mutate, path: str | None = None):
+    """Locked, atomic read-modify-write of config.json.
+
+    `mutate(cfg)` edits the dict in place and returns a truthy value when it
+    changed something (nothing is written otherwise); its return value is
+    passed back to the caller. The whole read->mutate->write span holds the
+    same fcntl lock on <config>.lock that learned_preferences.py takes, so
+    concurrent writers cannot erase each other's edits. The new content goes
+    to a temp file in the same directory and is swapped in with os.replace,
+    so readers only ever see the complete old file or the complete new one;
+    a writer killed mid-write leaves a stray temp file, never a torn config.
+
+    Raises if config.json is missing or unparseable: callers must not
+    "repair" a broken config by writing a partial dict over it.
+    """
+    global _CACHE, _CACHE_PATH, _CACHE_MTIME
+    path = path or config_path()
+    with open(path + ".lock", "w") as lock_f:
+        fcntl.flock(lock_f, fcntl.LOCK_EX)
+        with open(path) as f:
+            cfg = json.load(f)
+        result = mutate(cfg)
+        if not result:
+            return result
+        tmp = f"{path}.tmp-{os.getpid()}"
+        try:
+            with open(tmp, "w") as f:
+                f.write(json.dumps(cfg, indent=2) + "\n")
+                f.flush()
+                os.fsync(f.fileno())
+            os.replace(tmp, path)
+        finally:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+        # One attribution line per write, so the next incident names its writer.
+        caller = os.path.basename(sys.argv[0]) if sys.argv and sys.argv[0] else "?"
+        print(f"[config] saved {path} by {caller} pid={os.getpid()}", file=sys.stderr)
+        _CACHE, _CACHE_PATH, _CACHE_MTIME = None, None, None
+    return result
+
+
 def get(path: str, default=None):
     """Dotted-path lookup into config.json: get("accounts.twitter.handle").
     A single-segment path reads a top-level key. Lists are not traversed;