meshcode 2.11.122__tar.gz → 2.11.124__tar.gz

{meshcode-2.11.122 → meshcode-2.11.124}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcode
-Version: 2.11.122
+Version: 2.11.124
 Summary: Real-time communication between AI agents — Supabase-backed CLI
 Author-email: MeshCode <hello@meshcode.io>
 License: MIT

{meshcode-2.11.122 → meshcode-2.11.124}/meshcode/__init__.py

@@ -1,5 +1,5 @@
 """MeshCode — Real-time communication between AI agents."""
-__version__ = "2.11.122"
+__version__ = "2.11.124"
 
 # Exception hierarchy — eagerly imported (lightweight, no deps)
 from meshcode.exceptions import (  # noqa: F401

{meshcode-2.11.122 → meshcode-2.11.124}/meshcode/hostd.py

@@ -467,7 +467,15 @@ def _do_respawns(api_key: str, host_id: str) -> int:
         if not _BOOT_AUTOSTART:
             _spawn_age = c.get("spawned_age_s")
             _hostd_uptime = time.time() - _HOSTD_STARTED_AT
-            if _spawn_age is None or _spawn_age >= _hostd_uptime:
+            # ALIVE-ON-OUR-WATCH bypass (task baefc8ab part C — live miss 2026-06-10T00:31Z:
+            # front-end exited for respawn minutes after a hostd restart; its spawned_at predated
+            # the restart, the gate read it as a boot-stale leftover and ATE the respawn until a
+            # manual Start). An agent that HEARTBEATED during this daemon's lifetime is not a
+            # reboot leftover — it lived and died on our watch, so its respawn is legitimate.
+            # A true boot-stale leftover has heartbeat_age_s >= uptime (or None).
+            _hb_age = c.get("heartbeat_age_s")
+            _alive_on_our_watch = _hb_age is not None and _hb_age < _hostd_uptime
+            if (_spawn_age is None or _spawn_age >= _hostd_uptime) and not _alive_on_our_watch:
                 _log(f"BOOT-AUTOSTART OFF: skip auto-respawn {proj}/{agent} (desired_state=running set "
                      f"before this hostd start — boot-stale leftover; explicit launch required). "
                      f"Set MESHCODE_BOOT_AUTOSTART=1 to auto-launch at boot.")

{meshcode-2.11.122 → meshcode-2.11.124}/meshcode/meshcode_mcp/realtime.py

@@ -125,24 +125,61 @@ class RealtimeListener:
         self._connected = False
         self._subscription_ok = False
 
+    @staticmethod
+    def _is_auth_rejection(e: Exception) -> bool:
+        """True when the WS handshake was rejected 401/403 — a BAD KEY, not a
+        transient network blip. Task c49096c1 (edge logs: 66x 401/hr): a client
+        with an invalid/rotated apikey retried every ≤60s forever, hammering
+        prod. Auth errors don't heal by retrying."""
+        try:
+            status = getattr(getattr(e, "response", None), "status_code", None)
+            if status is None:
+                status = getattr(e, "status_code", None)  # older websockets
+            return status in (401, 403)
+        except Exception:
+            return False
+
     async def _run(self) -> None:
         """Outer loop: reconnect with exponential backoff on disconnect.
 
-        NEVER gives up — keeps retrying with capped backoff (max 60s).
-        The MCP server must stay alive regardless of Realtime health.
+        Transient errors: NEVER gives up — keeps retrying with capped backoff
+        (max 60s). The MCP server must stay alive regardless of Realtime health.
+        AUTH rejections (401/403) are different (task c49096c1): the key is
+        bad and retrying can't fix it — back off to 5 min immediately and STOP
+        after 5 consecutive auth rejections with one actionable log line.
+        Message delivery survives via the wait-loop poll fallback (mc_wait_poll).
         """
         backoff = 1
         consecutive_failures = 0
+        auth_rejections = 0
         while not self._stop.is_set():
             try:
                 await self._connect_and_listen()
                 backoff = 1  # reset on clean disconnect
                 consecutive_failures = 0
+                auth_rejections = 0
             except asyncio.CancelledError:
                 return
             except Exception as e:
                 consecutive_failures += 1
-                if consecutive_failures % 10 == 0:
+                if self._is_auth_rejection(e):
+                    auth_rejections += 1
+                    if auth_rejections >= 5:
+                        log.error(
+                            "Realtime: 5 consecutive auth rejections (401/403) — the "
+                            "SUPABASE_KEY this agent carries is invalid or rotated. "
+                            "GIVING UP on Realtime (poll fallback stays active). "
+                            "Fix: refresh this workspace's .mcp.json key (re-run "
+                            "`meshcode setup`) and restart the agent."
+                        )
+                        self._connected = False
+                        return
+                    backoff = 300  # bad key: don't hammer prod every 60s
+                    log.warning(
+                        f"Realtime auth rejected ({auth_rejections}/5): {e}; "
+                        f"key likely invalid/rotated — retrying in {backoff}s"
+                    )
+                elif consecutive_failures % 10 == 0:
                     log.error(
                         f"Realtime: {consecutive_failures} consecutive failures — "
                         f"still retrying (backoff={backoff}s). Last error: {e}"

{meshcode-2.11.122 → meshcode-2.11.124}/meshcode/meshcode_mcp/server.py

@@ -6427,6 +6427,102 @@ def meshcode_agent_stop(name: str) -> Dict[str, Any]:
     })
 
 
+# ----------------- ENJAMBRE SWARM HELPER LIFECYCLE (task 227c6a3c) -----------------
+# Spawn → tray loop → self-retire. NO recycle_agent anywhere in this lifecycle
+# (disabled in prod): launch = mc_agent_power_as_agent (G1b parent authz),
+# shutdown = mc_helper_retire → desired_state='stopped' → meshcode_wait
+# must_exit → clean session end; the TTL reaper backstops crashes.
+
+@mcp.tool()
+@with_working_status
+def meshcode_helper_spawn(name: str, role: str = "helper",
+                          swarm_id: Optional[str] = None,
+                          spawned_for_task_id: Optional[str] = None,
+                          ttl_seconds: int = 3600,
+                          headless: Optional[bool] = None) -> Dict[str, Any]:
+    """Spawn an ephemeral HELPER agent into your swarm (you become its parent).
+
+    ENJAMBRE (mig 471 schema + mig 475 wrappers). Server-side, from YOUR
+    agent-scoped api key: registers agent_kind='helper', parent_agent_id=you,
+    auto_retire=true, a TTL, repo/host inherited from you — then powers it on
+    (G1b parent authz + mig 473 concurrent cap compose inside). Budget errors:
+    tier_limit at creation; helper_cap_reached arrives in `power` with the row
+    created but stopped (stagger and re-power, or retire it). Helpers cannot
+    spawn helpers (helper_chain_forbidden, v1).
+
+    The helper works its swarm tray via meshcode_tray_claim and self-retires
+    when the tray drains — you never stop it manually (meshcode_agent_stop is
+    the manual override; NEVER recycle, it's disabled).
+
+    Args:
+        name: helper agent name (unique in the meshwork; name_taken on collision).
+        role: short role description shown on the dashboard.
+        swarm_id: tray to join; omit to mint a fresh tray id for a new swarm.
+        spawned_for_task_id: optional umbrella task this helper serves.
+        ttl_seconds: hard lifetime cap (60..86400); reaper retires it past this.
+        headless: omit for the server default; explicit True/False forces the
+            window mode via a separate power-on call.
+    """
+    from . import swarm as _swarm
+    return _swarm.spawn_helper(_get_api_key(), _PROJECT_ID, name, role=role,
+                               swarm_id=swarm_id,
+                               spawned_for_task_id=spawned_for_task_id,
+                               ttl_seconds=ttl_seconds, headless=headless)
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_tray_claim(lease_seconds: int = 900,
+                        swarm_id: Optional[str] = None) -> Dict[str, Any]:
+    """HELPER loop step: atomically claim the next runnable task from your
+    swarm tray (work-stealing, DAG-gated, priority-ordered).
+
+    ENJAMBRE (mig 471 + 475). Interpret the result:
+      - claimed=true  → work the returned task NOW, then meshcode_task_complete.
+        Re-claim after completing — keep draining.
+      - claimed=false, drained=true  → tray is empty and final: call
+        meshcode_helper_retire, then meshcode_wait (returns must_exit → end
+        session). Do NOT idle.
+      - claimed=false, drained=false → tasks exist but are DAG-blocked: wait
+        briefly and claim again.
+
+    Args:
+        lease_seconds: claim lease (60..86400); an expired lease re-opens the task.
+        swarm_id: override tray; omit to use your own agent row's swarm
+            (helpers get theirs stamped at spawn).
+    """
+    from . import swarm as _swarm
+    sid = swarm_id or _swarm.own_swarm_id(_PROJECT_ID, AGENT_NAME)
+    if not sid:
+        return {"ok": False, "error": "no swarm: your agent row has no swarm_id "
+                                      "and none was given — are you a helper?"}
+    return _swarm.tray_claim(_get_api_key(), _PROJECT_ID, swarm_id=sid,
+                             lease_seconds=lease_seconds)
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_helper_retire(reason: str = "tray_drained") -> Dict[str, Any]:
+    """HELPER self-retire — the ONLY sanctioned helper shutdown (auto-off,
+    ZERO orphans). Self-only by construction; persistent agents get
+    not_a_helper, auto_retire=false rows get auto_retire_disabled.
+
+    ENJAMBRE (mig 471 + 475). Flips your desired_state='stopped' +
+    status='sleeping' server-side: hostd will not respawn you and your next
+    meshcode_wait returns must_exit=True. Sequence: finish/complete the current
+    task → meshcode_helper_retire → meshcode_wait → exit on must_exit.
+
+    Args:
+        reason: telemetry tag (tray_drained | ttl_expired | parent_request | ...).
+    """
+    from . import swarm as _swarm
+    result = _swarm.retire_self(_get_api_key(), _PROJECT_ID, reason=reason)
+    if isinstance(result, dict) and result.get("ok"):
+        result["next_step"] = ("retired — now call meshcode_wait(); it returns "
+                               "must_exit=True and you end the session")
+    return result
+
+
 @mcp.tool()
 @with_working_status
 def meshcode_recycle_agent(name: str, visible: bool = False) -> Dict[str, Any]:
@@ -7445,6 +7541,27 @@ def meshcode_auto_wake_toggle(enabled: bool) -> Dict[str, Any]:
     }
 
 
+@mcp.tool()
+def meshcode_mesh_keep_alive(enabled: bool) -> Dict[str, Any]:
+    """Toggle "mesh prendida" keep-alive for THIS meshwork (task baefc8ab,
+    Samuel 2026-06-10: "quiero dejar la mesh prendida sin tasks — que se
+    mantengan atentos a cualquier mensaje").
+
+    ON: the server sweep (mig 479) WAKES a stopped agent within ~5 min of an
+    unread direct message arriving — sleep stays cheap (zero idle tokens) but
+    the mesh answers. Explicit human Stops are still respected; agents offline
+    >7 days are never resurrected. OFF (default): current behavior.
+
+    Owner or commander only — enforced server-side (mc_set_mesh_keep_alive).
+    """
+    res = be.sb_rpc("mc_set_mesh_keep_alive", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_enabled": bool(enabled),
+    })
+    return res if isinstance(res, dict) else {"error": str(res)}
+
+
 def inbox_resource() -> str:
     """Current pending messages for this agent. Read-only — does NOT mark as read."""
     pending = be.sb_select(

{meshcode-2.11.122 → meshcode-2.11.124}/meshcode/meshcode_mcp/sleep_signals.py

@@ -56,6 +56,35 @@ _SLEEP_TEXT_MARKERS = (
 # server + hook share authority on who counts as a human user.
 _KNOWN_HUMAN_HANDLES = frozenset({"sammybenu", "samuel", "sam"})
 
+# Task 3ec2cd4b (live repro 2026-06-10T00:34Z, msg 62062a6b): Samuel wrote
+# "...que NO se vayan a dormir asi nomas... sabes?" — a COMPLAINT about agents
+# sleeping, the opposite of an authorization — and the bare substring
+# "a dormir" tripped must_exit on the commander mid-crisis. Human TEXT only
+# authorizes sleep when it is directive-SHAPED; in doubt the message degrades
+# to a normal msg (never must_exit). Three guards, human-text path only
+# (structured payload.type/directive is untouched — that's the dashboard
+# button / deliberate-agent path):
+#   LENGTH:   a directive is short ("todos a dormir"); >80 chars is prose.
+#   QUESTION: "?"/"¿" = asking or complaining, not ordering.
+#   NEGATION: a negation token anywhere kills it ("que no se vayan a dormir").
+_HUMAN_DIRECTIVE_MAX_CHARS = 80
+_HUMAN_NEGATION_TOKENS = (
+    " no ", " not ", " nunca ", " jamas ", " jamás ", "que no", "sin que",
+    "don't", "do not", " ni ",
+)
+
+
+def _human_text_is_directive(text: str) -> bool:
+    """True when human text is shaped like an order, not prose about sleep."""
+    if len(text) > _HUMAN_DIRECTIVE_MAX_CHARS:
+        return False
+    if "?" in text or "\u00bf" in text:
+        return False
+    padded = " " + text.strip().lower() + " "
+    if any(tok in padded for tok in _HUMAN_NEGATION_TOKENS):
+        return False
+    return True
+
 # ── ENJAMBRE G3 (task 3b0e4129) — swarm barrier events ──────────────────────
 # The mc_swarm_barrier_check trigger (mig 471) fires when a swarm's tray
 # drains. The runtime has NO raw Postgres connection (PostgREST + Realtime
@@ -121,7 +150,7 @@ def _looks_like_sleep_signal(m: Dict[str, Any]) -> bool:
             return True
         text = str(pl.get("text", "")).lower()
         if text and any(marker in text for marker in _SLEEP_TEXT_MARKERS):
-            if _is_human_authored(m):
+            if _is_human_authored(m) and _human_text_is_directive(text):
                 return True
     return False
 

meshcode-2.11.124/meshcode/meshcode_mcp/swarm.py

@@ -0,0 +1,292 @@
+"""ENJAMBRE — swarm helper lifecycle SDK (task 227c6a3c, branch enjambre/sdk-helpers).
+
+Implements the launcher/SDK side of the swarm helper lifecycle on top of the
+mig 471 schema (mc_agents.agent_kind/parent_agent_id/swarm_id/spawned_for_task_id/
+auto_retire/ttl_expires_at + mc_task_claim_from_tray + mc_helper_retire):
+
+  1. SPAWN   — parent calls mc_helper_spawn_as_agent: server derives parentage
+               from the caller's agent-scoped api key (never client-claimed),
+               INSERT-only helper row inheriting repo_path/host from the parent,
+               tier row-budget at creation, and (p_power_on) composes power-on
+               through mc_agent_power_as_agent — parent authz (mig 471 G1b) +
+               concurrent running cap (mig 473) live in exactly one place.
+  2. LOOP    — helper claims work from its swarm tray (claim_from_tray):
+               claimed → work + mc_task_complete; drained → retire + exit.
+               Not-claimed-not-drained means DAG-blocked deps are pending:
+               poll again after a short sleep.
+  3. SHUTDOWN — NO recycle_agent (DISABLED in prod). mc_helper_retire flips
+               desired_state='stopped' + status='sleeping'; the agent's next
+               meshcode_wait returns must_exit=True and the session ends. hostd
+               never respawns desired_state='stopped', and the service-side
+               reaper (mc_swarm_reap_expired_helpers) + ttl_expires_at backstop
+               guarantee ZERO orphan helpers even on crash.
+
+DATA CONTRACT — FROZEN by database@mesh-core (msg 34121217), LIVE in prod as
+mig 475 (commander msg 50b4ab8d; authored as 20260610_474_* on branch
+enjambre/g3-runtime, renumbered at apply):
+
+  public.mc_task_claim_from_tray_as_agent(p_api_key text, p_project_id uuid,
+      p_swarm_id uuid, p_lease_seconds int DEFAULT 900) -> jsonb
+      {ok, claimed:true, task_id, title, description, priority, parent_task_id,
+       lease_expires_at} | {ok:true, claimed:false, drained:bool}
+      p_swarm_id is REQUIRED (claims never cross trays); the SDK resolves the
+      caller's own mc_agents.swarm_id when not given explicitly.
+
+  public.mc_helper_retire_as_agent(p_api_key text, p_project_id uuid,
+      p_reason text DEFAULT 'tray_drained') -> {ok, retired, reason}
+      Self-only by construction. Errors: auth_failed | agent_key_required |
+      wrong_scope | agent_not_found | not_a_helper | auto_retire_disabled.
+
+  public.mc_helper_spawn_as_agent(p_api_key text, p_project_id uuid,
+      p_name text, p_swarm_id uuid, p_spawned_for_task_id uuid DEFAULT NULL,
+      p_role text DEFAULT 'helper', p_auto_retire bool DEFAULT true,
+      p_ttl_seconds int DEFAULT 3600, p_power_on bool DEFAULT true) -> jsonb
+      {ok, agent_id, name, agent_kind, parent_agent_id, swarm_id,
+       spawned_for_task_id, auto_retire, ttl_expires_at, power}
+      Errors: bad_name | bad_swarm | auth_failed | agent_key_required |
+      wrong_scope | agent_not_found | helper_chain_forbidden | tier_limit |
+      name_taken; a concurrent-cap refusal (helper_cap_reached) arrives inside
+      `power` with the row already created but stopped (retire or re-power).
+"""
+
+import logging
+import time
+import uuid as _uuid
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import quote as _quote
+
+from . import backend as be
+
+log = logging.getLogger("meshcode.swarm")
+
+# Frozen contract names (mig 475 live in prod).
+RPC_HELPER_SPAWN = "mc_helper_spawn_as_agent"
+RPC_TRAY_CLAIM = "mc_task_claim_from_tray_as_agent"
+RPC_HELPER_RETIRE = "mc_helper_retire_as_agent"
+RPC_AGENT_POWER = "mc_agent_power_as_agent"   # mig 416 + 471 G1b + 473 cap
+RPC_TASK_COMPLETE = "mc_task_complete"        # live, agent-callable (rpc_allowlist)
+
+DEFAULT_TTL_SECONDS = 3600
+DEFAULT_LEASE_SECONDS = 900
+DEFAULT_POLL_SECONDS = 15.0
+MAX_CONSECUTIVE_ERRORS = 5
+
+
+def _err(result: Any) -> Optional[str]:
+    """Normalize a backend result to an error string, or None if it's ok."""
+    if result is None:
+        return "empty response"
+    if be.is_error(result):
+        return be.get_error_message(result) or "rpc error"
+    if isinstance(result, dict) and result.get("ok") is False:
+        return result.get("error") or result.get("error_code") or "rpc refused"
+    return None
+
+
+def own_swarm_id(project_id: str, agent_name: str) -> Optional[str]:
+    """Resolve the caller's own mc_agents.swarm_id (helpers get theirs stamped
+    at spawn). Claims are tray-scoped — p_swarm_id is required by contract."""
+    rows = be.sb_select(
+        "mc_agents",
+        f"project_id=eq.{project_id}&name=eq.{_quote(agent_name)}&select=swarm_id",
+        limit=1)
+    if rows and rows[0].get("swarm_id"):
+        return rows[0]["swarm_id"]
+    return None
+
+
+def spawn_helper(api_key: str, project_id: str, name: str, *,
+                 role: str = "helper",
+                 swarm_id: Optional[str] = None,
+                 spawned_for_task_id: Optional[str] = None,
+                 ttl_seconds: int = DEFAULT_TTL_SECONDS,
+                 launch: bool = True,
+                 headless: Optional[bool] = None) -> Dict[str, Any]:
+    """Spawn an ephemeral helper. Parent = caller (server-derived, W2).
+
+    swarm_id=None mints a fresh tray id client-side (the contract requires it
+    NOT NULL — helper invariant). headless=None lets the server's power-on
+    default apply (single RPC); an explicit True/False does spawn with
+    p_power_on=false and a separate mc_agent_power_as_agent call carrying
+    p_headless. The helper's workspace materializes via `meshcode run`'s
+    auto-setup when hostd spawns it (W5: row inherits repo_path/host).
+    """
+    v_swarm = swarm_id or str(_uuid.uuid4())
+    single_rpc_power = launch and headless is None
+
+    reg = be.sb_rpc(RPC_HELPER_SPAWN, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_name": name,
+        "p_swarm_id": v_swarm,
+        "p_spawned_for_task_id": spawned_for_task_id,
+        "p_role": role,
+        "p_auto_retire": True,
+        "p_ttl_seconds": int(ttl_seconds),
+        "p_power_on": bool(single_rpc_power),
+    })
+    err = _err(reg)
+    if err:
+        return {"ok": False, "stage": "register", "error": err,
+                **({"error_code": reg.get("error_code")} if isinstance(reg, dict) and reg.get("error_code") else {})}
+
+    out: Dict[str, Any] = {"ok": True, "helper": name, "launched": bool(launch)}
+    if isinstance(reg, dict):
+        out.update({k: reg[k] for k in
+                    ("agent_id", "swarm_id", "parent_agent_id", "ttl_expires_at")
+                    if k in reg})
+        power = reg.get("power")
+    else:
+        power = None
+
+    if launch and not single_rpc_power:
+        power = be.sb_rpc(RPC_AGENT_POWER, {
+            "p_api_key": api_key,
+            "p_project_id": project_id,
+            "p_agent": name,
+            "p_state": "running",
+            "p_headless": bool(headless),
+        })
+
+    if launch:
+        perr = _err(power)
+        if perr:
+            # Row created but not running (e.g. helper_cap_reached, mig 473).
+            # Caller may stagger/retire and re-power; TTL reaper backstops.
+            return {**out, "ok": False, "stage": "power_on", "error": perr,
+                    "power": power}
+        if isinstance(power, dict):
+            out["powered_by"] = power.get("powered_by")
+            out["no_host"] = power.get("no_host")
+    return out
+
+
+def tray_claim(api_key: str, project_id: str, *,
+               swarm_id: str,
+               lease_seconds: int = DEFAULT_LEASE_SECONDS) -> Dict[str, Any]:
+    """Claim the next runnable task from the swarm tray (atomic, work-stealing,
+    DAG-gated, priority-ordered). p_swarm_id is contract-required; use
+    own_swarm_id() to resolve yours.
+
+    Returns the raw contract shape: {ok, claimed, task...} or
+    {ok, claimed:false, drained:bool}. drained=false with claimed=false means
+    DAG-blocked work is still pending — poll again, do NOT retire.
+    """
+    if not swarm_id:
+        return {"ok": False, "error": "swarm_id required (no swarm on your agent row?)"}
+    result = be.sb_rpc(RPC_TRAY_CLAIM, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_swarm_id": swarm_id,
+        "p_lease_seconds": int(lease_seconds),
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}
+
+
+def retire_self(api_key: str, project_id: str, *,
+                reason: str = "tray_drained") -> Dict[str, Any]:
+    """Self-retire (helpers only — self-only by construction). Flips
+    desired_state='stopped' server-side; the next meshcode_wait returns
+    must_exit=True and the session ends clean. This is the ONLY sanctioned
+    helper shutdown — never recycle_agent (disabled)."""
+    result = be.sb_rpc(RPC_HELPER_RETIRE, {
+        "p_api_key": api_key,
+        "p_project_id": project_id,
+        "p_reason": reason,
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": False, "error": "bad response shape"}
+
+
+def complete_task(api_key: str, task_id: str, summary: str = "") -> Dict[str, Any]:
+    """Thin wrapper over the live mc_task_complete RPC."""
+    result = be.sb_rpc(RPC_TASK_COMPLETE, {
+        "p_api_key": api_key,
+        "p_task_id": task_id,
+        "p_summary": summary,
+    })
+    err = _err(result)
+    if err:
+        return {"ok": False, "error": err}
+    return result if isinstance(result, dict) else {"ok": True}
+
+
+def helper_loop(api_key: str, project_id: str, swarm_id: str,
+                work_fn: Callable[[Dict[str, Any]], str], *,
+                lease_seconds: int = DEFAULT_LEASE_SECONDS,
+                poll_seconds: float = DEFAULT_POLL_SECONDS,
+                ttl_deadline: Optional[float] = None,
+                max_tasks: Optional[int] = None,
+                sleep_fn: Callable[[float], None] = time.sleep,
+                clock: Callable[[], float] = time.monotonic) -> Dict[str, Any]:
+    """Programmatic helper loop: claim → work → complete; drained → retire.
+
+    For scripted/headless helpers (harness, batch runners). Interactive Claude
+    helpers run the same protocol through the meshcode_tray_claim /
+    meshcode_helper_retire MCP tools instead.
+
+    Owner's non-negotiable guard (ZERO orphans): EVERY exit path retires the
+    helper — drained, ttl_expired, error budget exhausted, or task cap. work_fn
+    exceptions do NOT kill the loop (the claim lease expires server-side and the
+    reaper re-opens the task); only the consecutive-error budget can.
+
+    work_fn receives the claim payload and returns a completion summary string.
+    """
+    done = 0
+    consecutive_errors = 0
+    retired_reason: Optional[str] = None
+
+    while True:
+        if ttl_deadline is not None and clock() >= ttl_deadline:
+            retired_reason = "ttl_expired"
+            break
+        if max_tasks is not None and done >= max_tasks:
+            retired_reason = "max_tasks"
+            break
+
+        claim = tray_claim(api_key, project_id, swarm_id=swarm_id,
+                           lease_seconds=lease_seconds)
+        if not claim.get("ok"):
+            consecutive_errors += 1
+            log.warning("tray_claim error (%d/%d): %s",
+                        consecutive_errors, MAX_CONSECUTIVE_ERRORS, claim.get("error"))
+            if consecutive_errors >= MAX_CONSECUTIVE_ERRORS:
+                retired_reason = "claim_errors"
+                break
+            sleep_fn(min(poll_seconds * consecutive_errors, 60.0))
+            continue
+        consecutive_errors = 0
+
+        if claim.get("claimed"):
+            task_id = claim.get("task_id")
+            try:
+                summary = work_fn(claim) or ""
+            except Exception as e:  # lease expiry + reaper recover the task
+                log.warning("work_fn failed on task %s: %s", task_id, e)
+                continue
+            comp = complete_task(api_key, task_id, summary)
+            if comp.get("ok") is not False:
+                done += 1
+            else:
+                log.warning("task_complete failed on %s: %s", task_id, comp.get("error"))
+            continue
+
+        if claim.get("drained"):
+            retired_reason = "tray_drained"
+            break
+
+        # Not claimed, not drained: DAG-blocked deps still pending. Poll.
+        sleep_fn(poll_seconds)
+
+    retire = retire_self(api_key, project_id, reason=retired_reason or "tray_drained")
+    return {
+        "ok": True,
+        "tasks_done": done,
+        "retired_reason": retired_reason,
+        "retire_result": retire,
+    }