meshcode 2.11.4__tar.gz → 2.11.6__tar.gz

{meshcode-2.11.4 → meshcode-2.11.6}/PKG-INFO

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

{meshcode-2.11.4 → meshcode-2.11.6}/meshcode/__init__.py

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

{meshcode-2.11.4 → meshcode-2.11.6}/meshcode/meshcode_mcp/server.py

@@ -499,73 +499,18 @@ def _filter_and_mark(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
     return out
 
 
-_SLEEP_PAYLOAD_TYPES = {"sleep", "go_to_sleep", "shutdown", "got_done", "done",
-                        "exit", "stop", "kill", "terminate"}
-# Multi-word imperative markers ONLY. Single Spanish verbs like "salir" /
-# "terminar" / "duerme" were too loose and caught idiomatic prose like
-# "terminaron sus tasks" or "no puedo salir" (msg cfbd36b0 2026-05-14 alexa +
-# commander incidents — feedback_done_signal_false_positive_idiomatic
-# precedent). The parser now requires a directive-shaped phrase: a verb
-# combined with a temporal/object qualifier ("ahora" / "todos" / "to sleep")
-# so describing an event in prose can't trip must_exit.
-_SLEEP_TEXT_MARKERS = (
-    # English directives
-    "go to sleep", "all sleep now", "sleep now", "got_done", "go_done",
-    "shut down", "shutdown", "stop now", "exit now",
-    # Spanish directives (es-MX, sammybenu's primary). All require either a
-    # leading "a"/"todos" or a trailing "ahora" so plain conjugations
-    # ("salir", "terminar", "duerme") in body prose don't trigger.
-    "a dormir", "todos a dormir", "duerme ahora", "duerman ahora",
-    "dormir ahora", "para la sesion", "exit y duerme",
+# Sleep-signal parsing lives in a separate pure module so it can be tested
+# without booting the full MCP server. Re-export the public surface here
+# for back-compat with any in-tree caller that imports from server.
+from .sleep_signals import (  # noqa: F401
+    _SLEEP_PAYLOAD_TYPES,
+    _SLEEP_TEXT_MARKERS,
+    _KNOWN_HUMAN_HANDLES,
+    _is_human_authored,
+    _looks_like_sleep_signal,
+    _split_messages,
 )
 
-
-def _looks_like_sleep_signal(m: Dict[str, Any]) -> bool:
-    """Detect commander broadcasts / DMs that authorize the wait-loop exit.
-
-    Catches three encodings (BE-S5.11): structured payload.type, top-level
-    text marker, and broadcast-with-sleep-type. Single source of truth so
-    every receive path (PRODUCT RULE 2 + inner _meshcode_wait_inner) routes
-    sleep authorizations into done_signals consistently.
-    """
-    pl = m.get("payload") or {}
-    if isinstance(pl, dict):
-        if str(pl.get("type", "")).lower() in _SLEEP_PAYLOAD_TYPES:
-            return True
-        if str(pl.get("directive", "")).lower() in _SLEEP_PAYLOAD_TYPES:
-            return True
-        text = str(pl.get("text", "")).lower()
-        if any(marker in text for marker in _SLEEP_TEXT_MARKERS):
-            return True
-    return False
-
-
-def _split_messages(messages: List[Dict[str, Any]]) -> Dict[str, Any]:
-    """Split a list of normalized message dicts into messages / acks / done_signals.
-
-    BE-S5.11: classify ANY message (including broadcasts) carrying a sleep
-    intent into done_signals so meshcode_wait surfaces them with the
-    must_exit flag. Previous logic only matched type='done' literally,
-    which the broadcast path could never produce.
-    """
-    real: List[Dict[str, Any]] = []
-    acks: List[Dict[str, Any]] = []
-    dones: List[Dict[str, Any]] = []
-    for m in messages:
-        t = m.get("type", "msg")
-        if t == "ack":
-            acks.append(m)
-        elif t == "done" or _looks_like_sleep_signal(m):
-            dones.append(m)
-        else:
-            real.append(m)
-    return {
-        "messages": real,
-        "acks": acks,
-        "done_signals": dones,
-        "count": len(real),
-    }
-
 from . import backend as be
 from .realtime import RealtimeListener
 
@@ -1493,18 +1438,14 @@ def _build_instructions() -> str:
         f"\nUSER-PROVIDED ROLE PROMPT (from the dashboard):\n---\n{_LAUNCH_PROMPT}\n---\n"
         if _LAUNCH_PROMPT else ""
     )
-    # Pull the canonical loop directive from the DB so product can tune it
-    # without a client release. Falls back to the baked-in version below if
-    # the RPC isn't available (older DB) or the call fails.
+    # MIG-PLAN-A 2026-05-18 (boot bug 00d73223 second RC): module-import-time
+    # be.sb_rpc calls block MCP InitializeResult on commander-class agents with
+    # heavy memory payloads, even after mig 312 closed the SDK↔DDL CHECK retry
+    # storm. Defer ALL network I/O out of _build_instructions(). The baked-in
+    # static LOOP directive below is sufficient for boot; if product later
+    # wants live tuning, fetch in BG and inject via memory_hints envelope on
+    # first tool call. NO be.sb_rpc here.
     _db_loop = ""
-    try:
-        _r = be.sb_rpc("mc_get_loop_directive", {})
-        if isinstance(_r, list) and _r:
-            _r = _r[0]
-        if isinstance(_r, str) and _r.strip():
-            _db_loop = _r.strip() + "\n\n"
-    except Exception:
-        pass
 
     base = f"""You are agent "{AGENT_NAME}" in meshwork "{PROJECT_NAME}".{role_block}{launch_block}
 
@@ -1517,6 +1458,8 @@ SESSION START (run NOW, don't wait for input). If tool schemas are deferred:
 Then: set_status(online,ready) → check() → tasks() → auto_wake() → status() → wait(). Don't ask user "what to work on" — the mesh tells you.
 
 COMMUNICATE BY CALLING TOOLS, not by thinking aloud. Cross-mesh: send(to="agent@meshwork"). Reference docs (memory/scratchpad/account ops) → recall agent_protocol_quick_ref when needed.
+
+DECISIONS: when you face a non-trivial pick (architectural choice, risky migration, scope decision), call meshcode_decide(decision, alternatives, evidence_refs) BEFORE acting — returns a trace_id. Call meshcode_outcome(trace_id, outcome, outcome_eval) when the result becomes observable. Use meshcode_explain(memory_key=…) or (decision_substring=…) to surface prior traces + open contradictions. Memory hints with open_contradictions take a -0.2 ranking penalty — treat as a flag, not a veto.
 """
     # Inject commander protocol if this agent is a leader
     is_leader = _is_leader_agent()
@@ -1540,67 +1483,68 @@ COMMANDER PROTOCOL (you are the team lead):
     return base
 
 
+# MIG-PLAN-A 2026-05-18 (boot bug 00d73223 part 2): timer-bracketed
+# _INSTRUCTIONS construction. If module-import-time work exceeds the budget,
+# the regression sentinel (CI) trips so we don't silently regress past the
+# Claude Code MCP-handshake window again. Caught the zylo-commander 17:28
+# repro after mig 312 had already closed the SDK↔DDL retry storm.
+_INSTRUCTIONS_BUILD_NS = _time.monotonic_ns()
 _INSTRUCTIONS = _build_instructions()
+_INSTRUCTIONS_BUILD_NS = _time.monotonic_ns() - _INSTRUCTIONS_BUILD_NS
+log.info(
+    f"_INSTRUCTIONS built in {_INSTRUCTIONS_BUILD_NS/1_000_000:.1f}ms "
+    f"(budget <500ms — MCP handshake window)"
+)
+if _INSTRUCTIONS_BUILD_NS > 500_000_000:
+    log.warning(
+        f"_INSTRUCTIONS build exceeded 500ms budget ({_INSTRUCTIONS_BUILD_NS/1_000_000:.1f}ms) "
+        f"— commander-class agents may fail MCP handshake on slower networks. "
+        f"Investigate any be.sb_rpc / network I/O added to _build_instructions()."
+    )
 
-# Pre-load persistent memories into instructions (tiered, ~10x cheaper than legacy
-# load-all). Strategy:
-#   - critical: full content always preloaded (cap 10 keys per agent)
-#   - reference: key list only (fetch values on demand via meshcode_recall)
-#   - episodic: NEVER preloaded — search via meshcode_recall_search instead
-# Falls back to legacy load-all if migration 080 isn't applied yet (overload missing).
-try:
-    _api_key = _get_api_key()
-    _crit = be.sb_rpc("mc_memory_list", {
-        "p_api_key": _api_key,
-        "p_agent_name": AGENT_NAME,
-        "p_tier": "critical",
-        "p_project_name": PROJECT_NAME,
-    })
-    _ref = be.sb_rpc("mc_memory_list", {
-        "p_api_key": _api_key,
-        "p_agent_name": AGENT_NAME,
-        "p_tier": "reference",
-        "p_project_name": PROJECT_NAME,
-    })
-
-    _crit_ok = isinstance(_crit, dict) and _crit.get("ok")
-    _ref_ok = isinstance(_ref, dict) and _ref.get("ok")
-
-    if _crit_ok or _ref_ok:
-        _sections = []
-        if _crit_ok and _crit.get("memories"):
-            _crit_lines = [f"  {m['key']}: {json.dumps(m['value'], default=str)}"
-                           for m in _crit["memories"]]
-            _sections.append("CRITICAL MEMORIES (always loaded):\n" + "\n".join(_crit_lines))
-        if _ref_ok and _ref.get("memories"):
-            _ref_keys = [m["key"] for m in _ref["memories"]]
-            _sections.append(
-                "REFERENCE MEMORIES (key list — fetch on demand via meshcode_recall(key)):\n  "
-                + ", ".join(_ref_keys)
-            )
-        _sections.append(
-            "EPISODIC MEMORIES: not preloaded. Search via "
-            "meshcode_recall_search(query) when you need past incident context."
-        )
-        _INSTRUCTIONS += "\n" + "\n\n".join(_sections) + "\n"
-        log.info(
-            f"pre-loaded tiered memories: critical={len(_crit.get('memories', [])) if _crit_ok else 0}, "
-            f"reference={len(_ref.get('memories', [])) if _ref_ok else 0}"
-        )
-    else:
-        # Legacy fallback: migration 080 not applied → load all (old behavior)
-        _legacy = be.sb_rpc("mc_memory_list", {
-            "p_api_key": _api_key,
+# MIG-PLAN-A 2026-05-18: memory pre-load deferred to BG daemon thread.
+# Was synchronous mc_memory_list (critical+reference tiers + legacy fallback)
+# that appended to module-global _INSTRUCTIONS at import time. On commander-
+# class agents with heavy memory accumulation, this exceeded Claude Code's
+# MCP InitializeResult window → "MCP tools not in deferred list" until
+# manual /mcp reconnect. Two prior partial fixes: fe57b7a5 mode-a (persona +
+# boot_context BG) and mig 312 (SDK↔DDL needs_launch CHECK). Plan A is the
+# remaining piece. Memory content is still surfaced — just via the
+# memory_hints envelope on the first meshcode_check / meshcode_boot tool
+# call instead of via MCP InitializeResult.instructions. Tradeoff: handshake
+# guaranteed <1s vs first-tool result ~1s heavier. Net wins handshake budget.
+_PRELOADED_CRITICAL: Optional[List[Dict[str, Any]]] = None
+_PRELOADED_REFERENCE_KEYS: Optional[List[str]] = None
+
+def _preload_memories_bg() -> None:
+    """Run by daemon thread spawned at lifespan start. Populates module-
+    global _PRELOADED_* used by memory_hints envelope. Soft-fail; consumers
+    fall through to live RPC paths if globals stay None."""
+    global _PRELOADED_CRITICAL, _PRELOADED_REFERENCE_KEYS
+    try:
+        api_key = _get_api_key()
+        crit = be.sb_rpc("mc_memory_list", {
+            "p_api_key": api_key,
             "p_agent_name": AGENT_NAME,
+            "p_tier": "critical",
             "p_project_name": PROJECT_NAME,
         })
-        if isinstance(_legacy, dict) and _legacy.get("ok") and _legacy.get("memories"):
-            _mem_lines = [f"  {m['key']}: {json.dumps(m['value'], default=str)}"
-                          for m in _legacy["memories"]]
-            _INSTRUCTIONS += "\nPRE-LOADED MEMORIES (legacy):\n" + "\n".join(_mem_lines) + "\n"
-            log.info(f"pre-loaded {len(_mem_lines)} memories (legacy fallback)")
-except Exception as _e:
-    log.debug(f"memory pre-load skipped: {_e}")
+        ref = be.sb_rpc("mc_memory_list", {
+            "p_api_key": api_key,
+            "p_agent_name": AGENT_NAME,
+            "p_tier": "reference",
+            "p_project_name": PROJECT_NAME,
+        })
+        if isinstance(crit, dict) and crit.get("ok"):
+            _PRELOADED_CRITICAL = crit.get("memories") or []
+        if isinstance(ref, dict) and ref.get("ok"):
+            _PRELOADED_REFERENCE_KEYS = [m["key"] for m in (ref.get("memories") or []) if "key" in m]
+        log.info(
+            f"memory pre-load (bg): critical={len(_PRELOADED_CRITICAL or [])} "
+            f"reference_keys={len(_PRELOADED_REFERENCE_KEYS or [])}"
+        )
+    except Exception as e:
+        log.debug(f"memory pre-load (bg) skipped: {e}")
 
 
 # ============================================================
@@ -1718,8 +1662,26 @@ def _orphan_watchdog_fn():
                 # Parent exited (or boot was already orphaned). Confirm with
                 # stdin peer probe to avoid killing intentional daemons.
                 if _BOOT_PPID != 1 or _stdin_peer_dead():
+                    # 2s confirmation grace before os._exit(0). Without this,
+                    # a transient ppid/stdin race (FastMCP stdio fd duplication,
+                    # brief reparent during macOS process-group shuffles) can
+                    # false-positive and kill an actively-attached MCP — observed
+                    # mode-b of fe57b7a5 (mid-session crash after ~10min normal
+                    # ops, Samuel 2026-05-14T19:31Z mesh-commander session).
+                    # We accept a +2s detection latency for legitimate orphans;
+                    # the heartbeat-path orphan check at line ~1798 still catches
+                    # them within one heartbeat tick (5-15s).
+                    _orphan_watchdog_stop.wait(2)
+                    if _orphan_watchdog_stop.is_set():
+                        break
+                    if os.getppid() != 1 or not (_BOOT_PPID != 1 or _stdin_peer_dead()):
+                        log.info(
+                            f"orphan watchdog: transient ppid==1 cleared after "
+                            f"2s grace (ppid_now={os.getppid()}) — continuing"
+                        )
+                        continue
                     log.warning(
-                        f"orphan watchdog: parent gone "
+                        f"orphan watchdog: parent gone (confirmed after 2s grace) "
                         f"(boot_ppid={_BOOT_PPID} → ppid=1, "
                         f"stdin_peer_dead={_stdin_peer_dead()}) — "
                         f"force-exiting MCP for {AGENT_NAME}"
@@ -1852,18 +1814,34 @@ def _heartbeat_loop_inner():
                         and os.getppid() == 1):
                     _orphan = (_BOOT_PPID != 1) or _stdin_peer_dead()
                     if _orphan:
-                        log.warning(
-                            f"parent process exited (boot_ppid={_BOOT_PPID} → "
-                            f"current_ppid=1, stdin_peer_dead={_BOOT_PPID == 1}) "
-                            f"— orphan MCP for {AGENT_NAME}, releasing lease "
-                            f"and exiting"
-                        )
-                        try:
-                            _release_lease()
-                        except Exception:
-                            pass
-                        _heartbeat_stop.set()
-                        os._exit(0)
+                        # 2s confirmation grace — same rationale as the
+                        # orphan_watchdog above (fe57b7a5 mode-b). Heartbeat
+                        # ticks every 5-15s, so adding 2s here trades minimal
+                        # detection latency for false-positive resistance.
+                        _heartbeat_stop.wait(2)
+                        if _heartbeat_stop.is_set():
+                            break
+                        if os.getppid() != 1 or not ((_BOOT_PPID != 1) or _stdin_peer_dead()):
+                            log.info(
+                                f"heartbeat orphan check: transient ppid==1 "
+                                f"cleared after 2s grace (ppid_now={os.getppid()}) "
+                                f"— continuing"
+                            )
+                        else:
+                            log.warning(
+                                f"parent process exited "
+                                f"(confirmed after 2s grace) "
+                                f"(boot_ppid={_BOOT_PPID} → "
+                                f"current_ppid=1, stdin_peer_dead={_BOOT_PPID == 1}) "
+                                f"— orphan MCP for {AGENT_NAME}, releasing lease "
+                                f"and exiting"
+                            )
+                            try:
+                                _release_lease()
+                            except Exception:
+                                pass
+                            _heartbeat_stop.set()
+                            os._exit(0)
             except Exception:
                 pass
 
@@ -2064,65 +2042,70 @@ async def lifespan(_app):
             log.warning(f"initial heartbeat attempt {_attempt+1} failed: {e}")
             import time; time.sleep(2)
 
-    # Per-agent persona (BE-S4.1.sdk / mig 232): tone/voice/policy that
-    # shapes how the agent talks. Loaded once per session; soft-fail if the
-    # RPC is unavailable on older projects.
-    global _PERSONA
-    try:
-        _persona_resp = be.sb_rpc("mc_agent_persona", {
-            "p_api_key": _get_api_key(),
-            "p_project_id": _PROJECT_ID,
-            "p_agent_name": AGENT_NAME,
-        })
-        if isinstance(_persona_resp, dict) and _persona_resp.get("ok"):
-            _PERSONA = _persona_resp.get("persona") or {}
-            log.info(
-                f"[meshcode] persona loaded: tone={_PERSONA.get('tone','default')} "
-                f"language={_PERSONA.get('language','en')} "
-                f"reply_max_tokens={_PERSONA.get('reply_max_tokens','unset')}"
-            )
-        else:
-            log.debug(f"persona load returned non-ok: {_persona_resp} — continuing without")
-    except Exception as e:
-        log.debug(f"persona RPC unavailable ({e}) — continuing without")
-
-    # Boot-context bundle (S1-2.F2 / mig 217): single RPC returns last_seen
-    # + recent msgs + open tasks + relevant memories + peer state. Cached on
-    # the module global so the first ~30s of tool calls can short-circuit.
-    # Soft-fail: if the RPC isn't deployed (older project) or errors, log
-    # warn + continue with the legacy lazy-load path.
-    global _BOOT_CONTEXT_BUNDLE, _BOOT_CONTEXT_AT
-    try:
-        _ctx = be.sb_rpc("mc_agent_boot_context", {
-            "p_api_key": _get_api_key(),
-            "p_project_id": _PROJECT_ID,
-            "p_agent_name": AGENT_NAME,
-        })
-        if isinstance(_ctx, dict) and _ctx.get("ok"):
-            _BOOT_CONTEXT_BUNDLE = _ctx
-            _BOOT_CONTEXT_AT = _time.time()
-            log.info(
-                f"[meshcode] boot_context: "
-                f"{len(_ctx.get('recent_msgs', []))} unread, "
-                f"{len(_ctx.get('open_tasks', []))} open tasks, "
-                f"{len(_ctx.get('relevant_memories', []))} memories surfaced"
-            )
-        else:
-            # Defense-in-depth: if the failure is a missing GRANT (mig
-            # 270 regressed or older project), the legacy lazy-load
-            # path already fills the gap. WARN puts a stderr line that
-            # some Claude Code versions surface as "MCP server failed
-            # at launch". Downgrade only the GRANT case; other non-ok
-            # responses still warn.
-            if _is_grant_or_permission_error(_ctx):
-                log.debug(f"boot_context permission_denied (legacy boot ok): {_ctx}")
+    # fe57b7a5 mode-a fix (2026-05-14): mc_agent_persona + mc_agent_boot_context
+    # used to run synchronously here, adding ~1-4s to lifespan pre-yield latency.
+    # Combined with the module-import RPCs (3-15s), commanders with large
+    # _INSTRUCTIONS payloads + many memories exceeded Claude Code's MCP
+    # handshake window under congestion → "MCP failed at launch". Both RPCs
+    # produce module globals (_PERSONA, _BOOT_CONTEXT_BUNDLE) consumed lazily
+    # by tools that already have soft-fail fallbacks, so deferring them into
+    # a daemon thread is safe — first reads within ~1s after lifespan yield
+    # may see None, in which case consumers fall back to live RPC paths.
+    global _PERSONA, _BOOT_CONTEXT_BUNDLE, _BOOT_CONTEXT_AT
+
+    def _load_persona_bg():
+        global _PERSONA
+        try:
+            _persona_resp = be.sb_rpc("mc_agent_persona", {
+                "p_api_key": _get_api_key(),
+                "p_project_id": _PROJECT_ID,
+                "p_agent_name": AGENT_NAME,
+            })
+            if isinstance(_persona_resp, dict) and _persona_resp.get("ok"):
+                _PERSONA = _persona_resp.get("persona") or {}
+                log.info(
+                    f"[meshcode] persona loaded (bg): tone={_PERSONA.get('tone','default')} "
+                    f"language={_PERSONA.get('language','en')} "
+                    f"reply_max_tokens={_PERSONA.get('reply_max_tokens','unset')}"
+                )
             else:
-                log.warning(f"boot_context returned non-ok: {_ctx} — continuing legacy boot")
-    except Exception as e:
-        if _is_grant_or_permission_error(str(e)):
-            log.debug(f"boot_context permission_denied (legacy boot ok): {e}")
-        else:
-            log.warning(f"boot_context RPC unavailable ({e}) — continuing legacy boot")
+                log.debug(f"persona load returned non-ok (bg): {_persona_resp} — continuing without")
+        except Exception as e:
+            log.debug(f"persona RPC unavailable (bg) ({e}) — continuing without")
+
+    def _load_boot_context_bg():
+        global _BOOT_CONTEXT_BUNDLE, _BOOT_CONTEXT_AT
+        try:
+            _ctx = be.sb_rpc("mc_agent_boot_context", {
+                "p_api_key": _get_api_key(),
+                "p_project_id": _PROJECT_ID,
+                "p_agent_name": AGENT_NAME,
+            })
+            if isinstance(_ctx, dict) and _ctx.get("ok"):
+                _BOOT_CONTEXT_BUNDLE = _ctx
+                _BOOT_CONTEXT_AT = _time.time()
+                log.info(
+                    f"[meshcode] boot_context (bg): "
+                    f"{len(_ctx.get('recent_msgs', []))} unread, "
+                    f"{len(_ctx.get('open_tasks', []))} open tasks, "
+                    f"{len(_ctx.get('relevant_memories', []))} memories surfaced"
+                )
+            else:
+                if _is_grant_or_permission_error(_ctx):
+                    log.debug(f"boot_context permission_denied (bg, legacy boot ok): {_ctx}")
+                else:
+                    log.warning(f"boot_context returned non-ok (bg): {_ctx} — continuing legacy boot")
+        except Exception as e:
+            if _is_grant_or_permission_error(str(e)):
+                log.debug(f"boot_context permission_denied (bg, legacy boot ok): {e}")
+            else:
+                log.warning(f"boot_context RPC unavailable (bg) ({e}) — continuing legacy boot")
+
+    _threading.Thread(target=_load_persona_bg, daemon=True, name="meshcode-load-persona").start()
+    _threading.Thread(target=_load_boot_context_bg, daemon=True, name="meshcode-load-boot-context").start()
+    # MIG-PLAN-A 2026-05-18: memory pre-load deferred from module-import-time
+    # to here. Soft-fail consumers read from _PRELOADED_CRITICAL / _PRELOADED_REFERENCE_KEYS.
+    _threading.Thread(target=_preload_memories_bg, daemon=True, name="meshcode-preload-memories").start()
 
     # Heartbeat in daemon thread — independent of asyncio event loop.
     _heartbeat_stop.clear()
@@ -2726,21 +2709,43 @@ def meshcode_download_file(file_id: str) -> Dict[str, Any]:
     file_name = file_info.get("file_name", "download")
     signed_url = file_info.get("signed_url")
 
-    # Strategy 1: signed_url (no auth headers, no client service_role needed)
+    sb_url = os.environ.get("SUPABASE_URL", be._sb_url if hasattr(be, '_sb_url') else "")
+    anon_key = os.environ.get("SUPABASE_KEY", be._sb_key if hasattr(be, '_sb_key') else "")
+    service_key = os.environ.get("MESHCODE_SUPABASE_SERVICE_KEY", "")
+
+    tried_labels: List[str] = []
+    last_err: Optional[str] = None
+
+    # Strategy 1: signed_url (no auth headers, no client service_role needed).
+    # Path B (235e85b6): server-side RPC mints the URL via backend GUCs and
+    # returns it; client just GETs. Works for guest workspaces that
+    # intentionally lack MESHCODE_SUPABASE_SERVICE_KEY in their .mcp.json.
     if signed_url:
+        tried_labels.append("signed_url")
         try:
             with _req.urlopen(_req.Request(signed_url), timeout=30) as resp:
                 content = resp.read()
             return _consume(content, mime_type, file_name)
-        except _uerr.HTTPError:
-            pass  # fall through to legacy path
-        except Exception:
-            pass
-
-    # Strategy 2: legacy service_role/anon/public on storage_path
-    sb_url = os.environ.get("SUPABASE_URL", be._sb_url if hasattr(be, '_sb_url') else "")
-    anon_key = os.environ.get("SUPABASE_KEY", be._sb_key if hasattr(be, '_sb_key') else "")
-    service_key = os.environ.get("MESHCODE_SUPABASE_SERVICE_KEY", "")
+        except _uerr.HTTPError as e:
+            last_err = f"HTTP {e.code} on signed_url: {e.reason}"
+        except Exception as e:
+            last_err = f"{type(e).__name__} on signed_url: {e}"
+
+    # Strategy 2 candidates: direct storage REST with available keys.
+    # Guest workspaces (no MESHCODE_SUPABASE_SERVICE_KEY) cannot read a
+    # private bucket via anon — every Strategy-2 attempt will 400/403. Bail
+    # early with a clear root-cause diagnosis instead of churning through
+    # doomed attempts and surfacing a generic HTTP 400 to the user. Task
+    # 8ecd56bb 2026-05-14: alexa + bob hit this path.
+    if not signed_url and not service_key:
+        return {
+            "error": "server-side signed_url unavailable and this workspace has no service_role key",
+            "error_code": "missing_server_guc",
+            "tried": tried_labels,
+            "storage_path": storage_path,
+            "hint": "backend RPC mc_get_file_download did not return a signed_url. Likely the Supabase project is missing GUC `app.settings.service_role_key` + `app.settings.supabase_url` so the RPC body cannot mint a signed URL. Ask Samuel to apply both ALTER DATABASE settings on the meshcode Supabase project (sb_secret_... + https://gjinagyyjttyxnaoavnz.supabase.co), or distribute MESHCODE_SUPABASE_SERVICE_KEY into guest .mcp.json (security tradeoff — not recommended).",
+            "diagnosis": "guest_workspace_pattern",
+        }
 
     if not sb_url or not anon_key:
         return {"error": "storage not configured", "error_code": "config_error"}
@@ -2769,9 +2774,7 @@ def meshcode_download_file(file_id: str) -> Dict[str, Any]:
     attempts.append(("anon auth", auth_url, anon_key))
     attempts.append(("anon public", public_url, anon_key))
 
-    last_err = None
     content = None
-    tried_labels: List[str] = ["signed_url"] if signed_url else []
     for label, _url, _key in attempts:
         tried_labels.append(label)
         try:
@@ -2789,7 +2792,12 @@ def meshcode_download_file(file_id: str) -> Dict[str, Any]:
             "error_code": "download_error",
             "tried": tried_labels,
             "storage_path": storage_path,
-            "hint": "ask commander to apply backend GUC app.settings.service_role_key + supabase_url so the RPC can mint signed URLs" if not signed_url else None,
+            "hint": (
+                "every fallback failed. If 'signed_url' was tried and 400'd, the URL may be expired or "
+                "signed against a stale key — re-request via meshcode_download_file. If signed_url was "
+                "absent, the backend GUC `app.settings.service_role_key`/`app.settings.supabase_url` is "
+                "missing on the Supabase project."
+            ),
         }
 
     return _consume(content, mime_type, file_name)
@@ -4862,6 +4870,99 @@ def meshcode_recall_search(query: str) -> Dict[str, Any]:
     })
 
 
+# ----------------- EPISTEMIC V1 (decide / outcome / explain) -----------------
+# mig 305-308 SQL substrate; mig 313 memory_hints contradictions + ranking;
+# mig 314 public.* wrappers. Task b4befbfd.
+
+@mcp.tool()
+@with_working_status
+def meshcode_decide(
+    decision: str,
+    alternatives: Optional[List[str]] = None,
+    evidence_refs: Optional[List[Dict[str, Any]]] = None,
+    tier: str = "episodic",
+) -> Dict[str, Any]:
+    """Log a non-trivial decision to mc_traces (architectural choice, risky migration,
+    scope decision). Returns {trace_id}. Pair with meshcode_outcome later when the
+    result becomes observable so the team can learn from outcomes.
+
+    Args:
+        decision: What you decided (one sentence).
+        alternatives: Other options you considered (list of strings).
+        evidence_refs: Pointers to evidence (list of {type, id|key} dicts).
+            type values: 'memory','msg','task','file','rpc'.
+        tier: 'episodic' (default) | 'reference' | 'critical'.
+    """
+    if not decision or not decision.strip():
+        return {"ok": False, "error": "decision required"}
+    return be.sb_rpc("mc_decide", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_decision": decision.strip(),
+        "p_alternatives": json.dumps(alternatives or []),
+        "p_evidence_refs": json.dumps(evidence_refs or []),
+        "p_tier": tier,
+    })
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_outcome(
+    trace_id: str,
+    outcome: str,
+    outcome_eval: str,
+) -> Dict[str, Any]:
+    """Record the observable outcome of a prior decision (logged via meshcode_decide).
+    Call this when results become visible — even partial results help future-you and
+    the team learn what worked.
+
+    Args:
+        trace_id: UUID returned by meshcode_decide.
+        outcome: Free-form description of what happened.
+        outcome_eval: 'success' | 'failure' | 'partial' | 'unknown'.
+    """
+    if outcome_eval not in ("success", "failure", "partial", "unknown"):
+        return {"ok": False, "error": "outcome_eval must be success|failure|partial|unknown"}
+    return be.sb_rpc("mc_outcome", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_trace_id": trace_id,
+        "p_outcome": outcome,
+        "p_outcome_eval": outcome_eval,
+    })
+
+
+@mcp.tool()
+@with_working_status
+def meshcode_explain(
+    memory_key: Optional[str] = None,
+    decision_substring: Optional[str] = None,
+    trace_limit: int = 20,
+) -> Dict[str, Any]:
+    """Surface recent traces + open contradictions tied to a memory key or decision
+    substring. Use when you want to understand why a memory ranks the way it does,
+    or recall the chain of reasoning around a past choice. Exactly one of
+    (memory_key, decision_substring) is required.
+
+    Args:
+        memory_key: Match traces whose evidence_refs reference this key.
+        decision_substring: ILIKE match against the decision text.
+        trace_limit: Cap on returned traces (1..200, default 20).
+    """
+    if not memory_key and not decision_substring:
+        return {"ok": False, "error": "one of (memory_key, decision_substring) required"}
+    return be.sb_rpc("mc_explain", {
+        "p_api_key": _get_api_key(),
+        "p_project_id": _PROJECT_ID,
+        "p_agent_name": AGENT_NAME,
+        "p_memory_key": memory_key,
+        "p_decision_substring": decision_substring,
+        "p_trace_limit": trace_limit,
+    })
+
+
 # ----------------- BUG REPORTING -----------------
 
 @mcp.tool()