@m13v/s4l 1.6.197-rc.10

package/scripts/s4l_box_update.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# Programmatic equivalent of the menu-bar "Update now & restart Claude Desktop" button
+# (mcp/menubar/s4l_menubar.py::_mcpb_update_work). Pulls the latest .mcpb from
+# GitHub releases, unzips it over the Claude Desktop extension dir in place, and
+# restarts Claude so the new MCP server loads. Designed to be run over SSH on a
+# .mcpb box (e.g. `ssh macstadium 'bash -s' < scripts/s4l_box_update.sh`), where
+# npm/npx is absent so the `runtime action:update` (npx) path is dead.
+#
+# Flags:
+#   --check        Print installed vs latest and exit (no download, no restart).
+#   --no-restart   Download + unpack the new .mcpb but do NOT restart Claude.
+#   (default)      Download + unpack + restart Claude.
+#
+# Exits: 0 ok / already current, 2 download failed, 3 unpack failed, 4 no install.
+set -euo pipefail
+
+# Resolve the Claude Desktop extension dir. Claude derives its name from the
+# manifest author, so the id changed `local.mcpb.m13v.social-autoposter` ->
+# `local.mcpb.s4l.ai.social-autoposter` when the author became "S4L.ai". A
+# hardcoded id silently breaks the updater on every fresh install (the box
+# reported "no .mcpb install" for exactly this reason). Glob for any
+# `*social-autoposter` extension dir that actually has a manifest.json, newest
+# first, so this keeps working across future renames.
+# Scan EVERY "Claude*/Claude Extensions" root, not just plain "Claude/": a box
+# whose Desktop build is renamed (e.g. the account-rotator's "Claude-mediar" /
+# "Claude-m13vduck" variants) keeps its extension under that suffixed dir, and a
+# plain-"Claude/" glob misses it entirely (the "no .mcpb install" exit-4 bug on
+# those boxes). Mirrors the menu bar's _ext_dir glob. Pick the newest matching
+# `*social-autoposter` dir that actually carries a manifest.json.
+APP_SUPPORT="$HOME/Library/Application Support"
+EXT_DIR=""
+for d in "$APP_SUPPORT"/Claude*/"Claude Extensions"/*social-autoposter; do
+  [ -f "$d/manifest.json" ] || continue
+  if [ -z "$EXT_DIR" ] || [ "$d" -nt "$EXT_DIR" ]; then EXT_DIR="$d"; fi
+done
+# Last-resort fallback to the historical path so behavior is unchanged on old boxes.
+[ -n "$EXT_DIR" ] || EXT_DIR="$APP_SUPPORT/Claude/Claude Extensions/local.mcpb.m13v.social-autoposter"
+PY="/usr/bin/python3"
+
+mode="run"
+case "${1:-}" in
+  --check)      mode="check" ;;
+  --no-restart) mode="no-restart" ;;
+  "")           mode="run" ;;
+  *) echo "unknown flag: $1" >&2; exit 64 ;;
+esac
+
+[ -f "$EXT_DIR/manifest.json" ] || { echo "no .mcpb install at $EXT_DIR" >&2; exit 4; }
+
+# CHANNEL (2026-07-02): a box on the `staging` channel tracks the newest release
+# OVERALL (prereleases included), resolved from the releases LIST endpoint;
+# `stable` keeps the exact historical releases/latest behavior. This script is
+# often piped over SSH (`ssh box 'bash -s' < s4l_box_update.sh`) with no repo on
+# PATH, so channel + latest resolution is a self-contained python block reading
+# the same <state dir>/channel.json marker every other surface uses. It prints
+# four space-separated tokens: "<channel> <tag> <version> <mcpb_url>".
+STATE_DIR="${S4L_STATE_DIR:-$HOME/.social-autoposter-mcp}"
+RESOLVED="$(S4L_STATE_DIR="$STATE_DIR" "$PY" - <<'PYEOF' 2>/dev/null || true
+import json, os, re, subprocess
+
+state = os.environ.get("S4L_STATE_DIR") or os.path.join(os.path.expanduser("~"), ".social-autoposter-mcp")
+try:
+    ch = (json.load(open(os.path.join(state, "channel.json"))) or {}).get("channel")
+except Exception:
+    ch = None
+channel = ch if ch in ("stable", "staging") else "stable"
+
+REPO = "m13v/s4l"
+LATEST_DL = "https://github.com/%s/releases/latest/download/social-autoposter.mcpb" % REPO
+TAG_DL = "https://github.com/%s/releases/download/%s/social-autoposter.mcpb"
+
+def curl(url):
+    r = subprocess.run(["/usr/bin/curl", "-fsSL", "-m", "15",
+                        "-H", "Accept: application/vnd.github+json", url],
+                       capture_output=True, text=True, timeout=20)
+    return r.stdout
+
+def ver_key(v):
+    s = str(v).strip().lstrip("v")
+    core, _, pre = s.partition("-")
+    nums = [int(x) if x.isdigit() else 0 for x in core.split("+")[0].split(".")]
+    while len(nums) < 3:
+        nums.append(0)
+    if not pre:
+        return (nums[0], nums[1], nums[2], 1, 0)
+    m = re.findall(r"\d+", pre)
+    return (nums[0], nums[1], nums[2], 0, int(m[-1]) if m else 0)
+
+tag = ""
+if channel == "staging":
+    try:
+        rels = json.loads(curl("https://api.github.com/repos/%s/releases?per_page=30" % REPO) or "[]")
+        best = None
+        for r in (rels if isinstance(rels, list) else []):
+            if not isinstance(r, dict) or r.get("draft"):
+                continue
+            t = r.get("tag_name")
+            if not isinstance(t, str) or not t.lstrip("v")[:1].isdigit():
+                continue
+            k = ver_key(t)
+            if best is None or k > best[0]:
+                best = (k, t)
+        if best:
+            tag = best[1]
+    except Exception:
+        tag = ""
+if not tag:
+    # stable, or staging fallback when the list endpoint failed -> track stable
+    try:
+        tag = (json.loads(curl("https://api.github.com/repos/%s/releases/latest" % REPO) or "{}") or {}).get("tag_name") or ""
+    except Exception:
+        tag = ""
+    if channel == "staging":
+        channel = "stable"
+
+version = tag.lstrip("v")
+url = LATEST_DL if channel == "stable" else (TAG_DL % (REPO, tag))
+print("%s %s %s %s" % (channel, tag, version, url))
+PYEOF
+)"
+CHANNEL="$(printf '%s' "$RESOLVED" | awk '{print $1}')"; [ -n "$CHANNEL" ] || CHANNEL="stable"
+latest_tag="$(printf '%s' "$RESOLVED" | awk '{print $2}')"
+latest="$(printf '%s' "$RESOLVED" | awk '{print $3}')"
+MCPB_URL="$(printf '%s' "$RESOLVED" | awk '{print $4}')"
+[ -n "$MCPB_URL" ] || MCPB_URL="https://github.com/m13v/s4l/releases/latest/download/social-autoposter.mcpb"
+
+installed="$("$PY" -c "import json,sys;print((json.load(open(sys.argv[1])) or {}).get('version',''))" "$EXT_DIR/manifest.json" 2>/dev/null || true)"
+echo "channel=$CHANNEL installed=$installed latest=$latest"
+
+if [ "$mode" = "check" ]; then
+  [ -n "$latest" ] && [ "$installed" != "$latest" ] && echo "update_available=true" || echo "update_available=false"
+  exit 0
+fi
+
+if [ -n "$latest" ] && [ "$installed" = "$latest" ]; then
+  echo "already on latest ($installed); re-applying anyway would just restart Claude. skipping."
+  # Comment the next line out if you want a forced re-unpack even when current.
+  exit 0
+fi
+
+tmpd="$(mktemp -d -t s4l-update-XXXXXX)"
+trap 'rm -rf "$tmpd"' EXIT
+mcpb="$tmpd/social-autoposter.mcpb"
+
+echo "downloading $MCPB_URL ..."
+# Retry: a freshly-cut GitHub release's asset download endpoint 404s for up to a
+# couple minutes while the CDN propagates (the release API shows the tag/asset as
+# "uploaded" before the download URL serves it). A single curl loses that race and
+# the update silently "fails." Retry with backoff so the standard pipeline is
+# robust to that window.
+sz=0
+for attempt in 1 2 3 4 5 6 7 8 9 10; do
+  if curl -fLs -m 300 "$MCPB_URL" -o "$mcpb" 2>/dev/null; then
+    sz=$(stat -f%z "$mcpb" 2>/dev/null || echo 0)
+    [ "$sz" -ge 100000 ] && break
+  fi
+  echo "  download attempt $attempt not ready yet (asset propagating); retrying in 15s..." >&2
+  sz=0
+  sleep 15
+done
+[ "$sz" -ge 100000 ] || { echo "download failed after retries (asset never became available)" >&2; exit 2; }
+
+echo "unpacking into extension dir ..."
+unzip -oq "$mcpb" -d "$EXT_DIR" || { echo "unpack failed" >&2; exit 3; }
+new_ver="$("$PY" -c "import json,sys;print((json.load(open(sys.argv[1])) or {}).get('version',''))" "$EXT_DIR/manifest.json" 2>/dev/null || true)"
+echo "unpacked version=$new_ver"
+
+if [ "$mode" = "no-restart" ]; then
+  echo "done (no restart requested); restart Claude to load v$new_ver."
+  exit 0
+fi
+
+# Restart Claude. From an SSH session we skip the osascript graceful-quit the
+# menu bar uses (it can trip an Automation TCC prompt for sshd and block
+# unattended); killall sends SIGTERM and needs no automation grant.
+echo "restarting Claude ..."
+killall Claude 2>/dev/null || true
+sleep 4
+killall -9 Claude 2>/dev/null || true
+sleep 1
+# Relocate the autopilot scheduled tasks' working dir to ~/.s4l-worker so their
+# once-a-minute runs stop flooding the user's interactive `claude --resume`
+# history (Claude buckets sessions by cwd). MUST run while Claude is DOWN — the
+# running app caches the scheduled-tasks registry in memory and clobbers a live
+# edit on the next fire. Kept in sync with the menu-bar updater's
+# _rewrite_scheduled_task_cwd() and queueWorkerCwd() in mcp/src/index.ts.
+echo "relocating worker task cwd -> ~/.s4l-worker + removing deprecated autopilot ..."
+/usr/bin/python3 - <<'PYCWD' 2>/dev/null || true
+import json, os, glob, tempfile, shutil
+home = os.path.expanduser("~")
+worker = os.path.join(home, ".s4l-worker")
+os.makedirs(worker, exist_ok=True)
+# s4l-worker is the universal type-blind worker (2026-07-02); saps-worker
+# (staging rc.2/rc.3) and the phase pair are legacy. This script only heals cwd
+# here — the legacy->s4l-worker consolidation runs via the menubar's
+# _rewrite_scheduled_task_cwd() self-heal.
+WORKERS = {"s4l-worker", "saps-worker", "saps-phase1-query", "saps-phase2b-draft"}
+DEPRECATED = {"social-autoposter-autopilot"}
+pat = os.path.join(home, "Library/Application Support/Claude/claude-code-sessions/*/*/scheduled-tasks.json")
+for f in glob.glob(pat):
+    try:
+        d = json.load(open(f))
+    except Exception:
+        continue
+    out, dirty = [], False
+    for t in d.get("scheduledTasks", []) or []:
+        tid = t.get("id")
+        if tid in DEPRECATED:
+            dirty = True; continue           # drop deprecated autopilot
+        if tid in WORKERS and t.get("cwd") != worker:
+            t["cwd"] = worker; dirty = True
+        out.append(t)
+    if dirty:
+        d["scheduledTasks"] = out
+        try:
+            fd, tmp = tempfile.mkstemp(dir=os.path.dirname(f))
+            with os.fdopen(fd, "w") as fh: json.dump(d, fh, indent=2)
+            os.replace(tmp, f)
+            print("  cwd-fix: updated", os.path.basename(os.path.dirname(f)))
+        except Exception as e:
+            print("  cwd-fix: write failed:", e)
+for tid in DEPRECATED:
+    shutil.rmtree(os.path.join(home, ".claude", "scheduled-tasks", tid), ignore_errors=True)
+PYCWD
+open -a Claude 2>/dev/null || true
+echo "done; Claude restarting on v$new_ver."

package/scripts/s4l_channel.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""Release-channel knob for a single S4L box (stable vs staging).
+
+ONE tiny file that every update surface reads so a box can opt into pre-release
+(`staging`) builds without affecting any other box:
+
+- `stable` (default): the box tracks GitHub `releases/latest`, i.e. the newest
+  NON-prerelease release. This is the historical behavior and what every box
+  gets when this file / the channel marker is absent.
+- `staging`: the box tracks the newest release OVERALL (prerelease RCs included).
+  A staging box is therefore always >= stable: it picks up each `-rc.N` first,
+  and once an RC is promoted to a full release it stays current on that too.
+
+The channel lives in a single JSON marker in the state dir so the TypeScript MCP
+server (mcp/src/version.ts), the menu-bar snapshot (scripts/snapshot.py), the
+menu bar itself (mcp/menubar/s4l_menubar.py), and the SSH updater
+(scripts/s4l_box_update.sh) all resolve the SAME value. Keep the filename and the
+semantics in lockstep across those four surfaces.
+
+CLI (SSH-drivable, zero deps beyond stdlib):
+    python3 scripts/s4l_channel.py get                 # -> stable | staging
+    python3 scripts/s4l_channel.py set staging         # opt in
+    python3 scripts/s4l_channel.py set stable          # opt back out
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+VALID_CHANNELS = ("stable", "staging")
+DEFAULT_CHANNEL = "stable"
+CHANNEL_FILE = "channel.json"
+
+
+def state_dir() -> str:
+    return os.environ.get("S4L_STATE_DIR") or os.path.join(
+        os.path.expanduser("~"), ".social-autoposter-mcp"
+    )
+
+
+def channel_path() -> str:
+    return os.path.join(state_dir(), CHANNEL_FILE)
+
+
+def read_channel() -> str:
+    """Current channel for this box. Any read error or unknown value falls back
+    to `stable` (fail-safe: a corrupt marker must never silently push a box onto
+    pre-release builds)."""
+    try:
+        with open(channel_path()) as f:
+            v = (json.load(f) or {}).get("channel")
+        if isinstance(v, str) and v.strip().lower() in VALID_CHANNELS:
+            return v.strip().lower()
+    except Exception:
+        pass
+    return DEFAULT_CHANNEL
+
+
+def is_staging() -> bool:
+    return read_channel() == "staging"
+
+
+def set_channel(channel: str) -> str:
+    channel = (channel or "").strip().lower()
+    if channel not in VALID_CHANNELS:
+        raise ValueError(
+            "invalid channel %r (want one of %s)" % (channel, ", ".join(VALID_CHANNELS))
+        )
+    d = state_dir()
+    os.makedirs(d, exist_ok=True)
+    tmp = channel_path() + ".tmp"
+    with open(tmp, "w") as f:
+        json.dump({"channel": channel}, f)
+        f.write("\n")
+    os.replace(tmp, channel_path())
+    return channel
+
+
+def _main(argv) -> int:
+    if not argv or argv[0] in ("-h", "--help"):
+        print(__doc__.strip())
+        return 0
+    cmd = argv[0]
+    if cmd == "get":
+        print(read_channel())
+        return 0
+    if cmd == "set":
+        if len(argv) < 2:
+            print("usage: s4l_channel.py set <stable|staging>", file=sys.stderr)
+            return 2
+        try:
+            print(set_channel(argv[1]))
+        except ValueError as e:
+            print(str(e), file=sys.stderr)
+            return 2
+        return 0
+    print("unknown command: %s (want get|set)" % cmd, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main(sys.argv[1:]))

package/scripts/s4l_ctl.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# s4l-ctl: programmatic control of the running social-autoposter (S4L) plugin via
+# its loopback tool server, for QA. Runs the same handlers as the in-chat MCP
+# tools (POST /tool/<name>). MUST run ON the box (the loopback is 127.0.0.1-only),
+# so over SSH use:  ssh macstadium 'bash -s -- <subcommand> [args]' < scripts/s4l_ctl.sh
+#
+# Subcommands:
+#   status                 Dashboard snapshot (read-only).
+#   count                  Number of pending (unposted) drafts (read-only).
+#   drafts                 List pending drafts with their 1-based numbers (read-only).
+#   approve <n> [n...]     Post the given card numbers. DESTRUCTIVE — requires --yes.
+#   approve-all            Post EVERY pending card. DESTRUCTIVE — requires --yes.
+#
+# DESTRUCTIVE note: "approve" really posts replies to live X/Twitter threads. The
+# write subcommands refuse to run unless --yes is present (no interactive prompt,
+# because over piped SSH there is no tty). For host-level plugin UPDATE use the
+# separate scripts/s4l_box_update.sh (different mechanism: works even when the
+# loopback is down, and it restarts Claude).
+set -euo pipefail
+
+BATCH="review-queue"
+PLAN="/tmp/twitter_cycle_plan_${BATCH}.json"
+EP="$HOME/.social-autoposter-mcp/panel-endpoint.json"
+PY="/usr/bin/python3"
+
+YES=0; ARGS=()
+for a in "$@"; do
+  case "$a" in --yes|-y) YES=1 ;; *) ARGS+=("$a") ;; esac
+done
+set -- ${ARGS[@]+"${ARGS[@]}"}
+cmd="${1:-}"; [ $# -gt 0 ] && shift || true
+
+[ -f "$EP" ] || { echo "no panel-endpoint.json — is Claude Desktop / the MCP running?" >&2; exit 1; }
+URL="$("$PY" -c "import json;print(json.load(open('$EP'))['url'])")"
+curl -s -m 3 "${URL}health" >/dev/null || { echo "loopback unreachable at $URL" >&2; exit 1; }
+
+tool() { curl -s -m "${2:-900}" -X POST "${URL}tool/$1" -H 'Content-Type: application/json' -d "${3:-{}}"; }
+
+pending_count() {
+  [ -f "$PLAN" ] || { echo 0; return; }
+  "$PY" -c "import json;d=json.load(open('$PLAN'));print(sum(1 for c in d.get('candidates',[]) if not c.get('posted')))"
+}
+
+case "$cmd" in
+  status)
+    tool dashboard 20 ; echo ;;
+  count)
+    echo "pending=$(pending_count)" ;;
+  drafts)
+    if [ ! -f "$PLAN" ]; then echo "no review-queue plan on box (0 drafts)"; exit 0; fi
+    "$PY" - "$PLAN" <<'PYEOF'
+import json,sys
+d=json.load(open(sys.argv[1]))
+for i,c in enumerate(d.get("candidates",[]),1):
+    if c.get("posted"): continue
+    txt=(c.get("reply_text") or "").replace("\n"," ")
+    print(f"#{i:<4} @{(c.get('thread_author') or '?'):<18} {txt[:90]}")
+PYEOF
+    echo "pending=$(pending_count)" ;;
+  approve)
+    [ $# -ge 1 ] || { echo "usage: approve <n> [n...] --yes" >&2; exit 64; }
+    nums="$(printf '%s\n' "$@" | paste -sd, -)"
+    if [ "$YES" != "1" ]; then
+      echo "REFUSING: 'approve $*' will POST those cards to live X. Re-run with --yes to confirm." >&2; exit 3; fi
+    echo "posting cards [$nums] ..."
+    tool post_drafts 900 "{\"batch_id\":\"$BATCH\",\"post\":[$nums]}" ; echo ;;
+  approve-all)
+    n="$(pending_count)"
+    if [ "$YES" != "1" ]; then
+      echo "REFUSING: approve-all will POST all $n pending cards to live X. Re-run with --yes to confirm." >&2; exit 3; fi
+    echo "posting all $n pending cards ..."
+    tool post_drafts 1800 "{\"batch_id\":\"$BATCH\",\"post_all\":true}" ; echo ;;
+  *)
+    echo "usage: s4l_ctl.sh {status|count|drafts|approve <n...>|approve-all} [--yes]" >&2; exit 64 ;;
+esac

package/scripts/s4l_env.py

@@ -0,0 +1,47 @@
+"""SAPS_ -> S4L_ environment mirror (brand rename 2026-07-03).
+
+The internal env-var prefix moved from SAPS_ to S4L_, but launchd plists,
+Claude Desktop scheduled-task prompts, and cron entries on customer machines
+were written before the rename and still export SAPS_* names. They cannot all
+be regenerated instantly (plists are only rewritten on re-registration), so
+every python entrypoint that launchd / scheduled tasks invoke directly calls
+mirror() right after imports. It copies each SAPS_FOO to S4L_FOO when the new
+name is unset, and (defensively, for old code launched by NEW plists that emit
+only S4L_*) the reverse direction too. Existing values always win: mirror()
+never overwrites a name that is already set.
+
+Stdlib-only, safe under /usr/bin/python3. Usage:
+
+    import s4l_env
+    s4l_env.mirror()
+"""
+
+from __future__ import annotations
+
+import os
+
+_OLD = "SAPS_"
+_NEW = "S4L_"
+
+
+def mirror(environ=None) -> int:
+    """Copy SAPS_* -> S4L_* (and S4L_* -> SAPS_*) for any name whose twin is
+    unset. Returns the number of variables copied. Never overwrites."""
+    env = environ if environ is not None else os.environ
+    copied = 0
+    # Snapshot keys first: we mutate env while iterating.
+    for key in list(env.keys()):
+        if key.startswith(_OLD):
+            twin = _NEW + key[len(_OLD):]
+        elif key.startswith(_NEW):
+            twin = _OLD + key[len(_NEW):]
+        else:
+            continue
+        if twin not in env:
+            env[twin] = env[key]
+            copied += 1
+    return copied
+
+
+if __name__ == "__main__":
+    print(f"mirrored {mirror()} env var(s)")

package/scripts/saps_activity.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""saps_activity.py — shared writer for the menu-bar activity.json signal.
+
+The S4L menu bar polls ``<state_dir>/activity.json`` every second and shows a
+spinner + label while work is happening (scanning / drafting / posting / …).
+Several lanes do work the menu bar should narrate, but historically only two of
+them wrote this file:
+
+  - the MCP server (TypeScript ``writeActivity``) — for IN-CHAT tool calls only,
+  - ``twitter_post_plan.py`` — for per-post posting progress.
+
+The unattended draft autopilot was invisible: the launchd kicker's scan phase
+runs inside the (locked) ``run-twitter-cycle.sh`` with no writer, and Phase-2b
+drafting is done by the queue provider (which only blocks) and the Claude Desktop
+scheduled-task worker (which never wrote anything). So "scanning" and "drafting"
+never showed on the box.
+
+This module is the single Python writer those lanes share, keeping the JSON shape
+and the state-dir resolution byte-identical to the TS + poster writers so the menu
+bar reads one consistent signal regardless of who produced the work.
+
+Purely cosmetic and fully best-effort: a failure here MUST never affect the work
+it narrates. Every public call swallows its own exceptions.
+
+State-dir resolution matches everything else: ``$S4L_STATE_DIR`` or
+``~/.social-autoposter-mcp``. The scheduled-task worker sets ``S4L_STATE_DIR``
+in the env before calling in (see ``claude_job.py::_apply_state_dir_override``),
+so the worker lane lands in the same dir the launchd kicker and menu bar use.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+
+
+def state_dir() -> str:
+    return os.environ.get("S4L_STATE_DIR") or os.path.join(
+        os.path.expanduser("~"), ".social-autoposter-mcp"
+    )
+
+
+def _path() -> str:
+    return os.path.join(state_dir(), "activity.json")
+
+
+def write(state: str, label: str) -> None:
+    """Mirror the Node server's writeActivity shape: {state, label, since}.
+
+    Written atomically (tmp + os.replace) so the menu bar's 1s poll never reads a
+    half-written file. Best-effort: any failure is swallowed.
+    """
+    try:
+        sd = state_dir()
+        os.makedirs(sd, exist_ok=True)
+        payload = {
+            "state": state,
+            "label": label,
+            "since": datetime.now(timezone.utc).isoformat(),
+        }
+        target = _path()
+        tmp = f"{target}.tmp.{os.getpid()}"
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write(json.dumps(payload) + "\n")
+        os.replace(tmp, target)
+    except Exception:
+        pass
+
+
+def read() -> dict | None:
+    """Current signal as a dict, or None when absent/unreadable. Best-effort."""
+    try:
+        with open(_path(), encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def heartbeat(state: str, label: str) -> None:
+    """Refresh `since` for a phase that's still ongoing, but ONLY if the current
+    signal is still that same phase (or there is none). This lets a shell lane
+    keep a long 'scanning' phase fresh against the menu bar's staleness TTL
+    WITHOUT fighting a later writer that has already advanced the phase: once the
+    queue provider flips the label to 'finding threads'/'drafting replies', the
+    state no longer matches and this goes quiet (no flicker between the two)."""
+    try:
+        cur = read()
+        if cur is None or cur.get("state") == state:
+            write(state, label)
+    except Exception:
+        pass
+
+
+def clear() -> None:
+    """Remove the activity signal so no stuck 'scanning/drafting' lingers after a
+    cycle, a worker turn, or an early exit. Idempotent; safe to double-clear."""
+    try:
+        p = _path()
+        if os.path.exists(p):
+            os.remove(p)
+    except Exception:
+        pass
+
+
+def _main(argv: list[str]) -> int:
+    # CLI used by shell lanes (run-draft-and-publish.sh):
+    #   saps_activity.py write <state> <label words...>
+    #   saps_activity.py heartbeat <state> <label words...>   (conditional refresh)
+    #   saps_activity.py clear
+    if not argv:
+        return 0
+    cmd = argv[0]
+    if cmd == "clear":
+        clear()
+    elif cmd in ("write", "heartbeat"):
+        state = argv[1] if len(argv) > 1 else "working"
+        label = " ".join(argv[2:]) if len(argv) > 2 else ""
+        (heartbeat if cmd == "heartbeat" else write)(state, label)
+    return 0
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(_main(sys.argv[1:]))