swarph-cli 0.71.0__tar.gz → 0.72.1__tar.gz

{swarph_cli-0.71.0/src/swarph_cli.egg-info → swarph_cli-0.72.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swarph-cli
-Version: 0.71.0
+Version: 0.72.1
 Summary: The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`.
 Author: Pierre Samson, Claude Opus
 License: MIT

{swarph_cli-0.71.0 → swarph_cli-0.72.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swarph-cli"
-version = "0.71.0"
+version = "0.72.1"
 description = "The `swarph` binary — a multi-LLM CLI and mesh-gateway client + bundled server (`swarph gateway`): one-shot prompts across providers, interactive `chat`, multi-provider `spawn` (claude/codex/antigravity via a ProviderMembrane with subprocess billing-scrub), `mesh` send/inbox/register, `brain-ask` over the swarph-brain (gbrain) semantic memory, git-backed `assisted_memory`, per-invocation `gh` identity routing, a silent DM-wake hook, session `import`, and a stranded-session `watchdog`."
 readme = "README.md"
 license = { text = "MIT" }

{swarph_cli-0.71.0 → swarph_cli-0.72.1}/src/swarph_cli/__init__.py

@@ -16,6 +16,6 @@ The architecture splits CLI from substrate so:
 
 from __future__ import annotations
 
-__version__ = "0.71.0"
+__version__ = "0.72.1"
 
 __all__ = ["__version__"]

{swarph_cli-0.71.0 → swarph_cli-0.72.1}/src/swarph_cli/commands/mesh.py

@@ -1482,6 +1482,7 @@ class TmuxSink(Sink):
 
     def deliver(self, state: "MonitorState", dms: list, up_to_id: int) -> Optional[bool]:
         led = state.ledger(self.name)
+        self.failure_reason = None
         # #723: a rate-limit or usage-limit screen is not deliverable. An
         # empty composer beside "Retry failed: rate limit" used to inject
         # again, and the 1.0.44 upgrade modal (no Grok footer) used to
@@ -1619,6 +1620,7 @@ class TmuxSink(Sink):
                     # Human text shares the composer (possibly merged into our
                     # wake) — an Enter here submits THEIR line (#403's shape).
                     return None
+                self.failure_reason = _sink_failure_detail(self.target)
                 return False  # pane unreadable: keep the failure loud
         # Fresh path, gated on the OBSERVED composer (gpt-ops REVISE, #312):
         # "wake" — wake text already sits ALONE in the composer (a monitor
@@ -1647,6 +1649,7 @@ class TmuxSink(Sink):
         if composer == "busy":
             return None
         if composer != "clear":
+            self.failure_reason = _sink_failure_detail(self.target)
             return False
         # #619: never inject mid-turn. A wake into a RUNNING TUI lands in
         # cursor's follow-up queue, which is input-gated (measured live
@@ -1656,6 +1659,13 @@ class TmuxSink(Sink):
         # after the turn ends injects into an IDLE composer, where Enter
         # submits immediately. Cost: <= one poll interval of delay.
         if _agent_running(self.target):
+            seen = _capture_pane_lines(self.target)
+            if seen and _muse_running(seen):
+                print(
+                    f"[monitor] {self.name}: muse turn in progress — "
+                    "deferring, zero keys",
+                    flush=True,
+                )
             return None
         # Module-global lookup on purpose: the sidecar regression suites patch
         # `mesh._tmux_wake`, and a `from`-import here would silently bypass them.
@@ -1922,6 +1932,117 @@ class MuseSink(Sink):
         return f"{count} DM{plural} not yet delivered to {self.name}"
 
 
+_CODEX_SEND_TIMEOUT_S = 120.0
+
+
+def _codex_send(thread: str, text: str, *,
+                _run=subprocess.run,
+                _which=shutil.which,
+                _timeout: float = _CODEX_SEND_TIMEOUT_S,
+                ) -> tuple:
+    """One `codex queue --thread <thread> --message <text>`.
+
+    Returns (True, "") on a verified queue, else (False, NAMED reason).
+    Every refusal is named — non-zero exit, missing binary, launch/timeout
+    failure — so a dead wake path reads as a reason, never as silence.
+    `_run`/`_which` are injectable so the result mapping is testable without
+    a codex binary on PATH. Unlike `muse session-message send`, codex queue
+    is a same-box queue file write: no ingress gate, no peer approval.
+    """
+    prog = _which("codex")
+    if not prog:
+        return (False, "codex binary not found on PATH")
+    argv = [prog, "queue", "--thread", thread, "--message", text]
+    try:
+        proc = _run(argv, capture_output=True, text=True,
+                    timeout=_timeout)
+    except FileNotFoundError:
+        return (False, "codex binary not found on PATH")
+    except subprocess.TimeoutExpired:
+        return (False,
+                f"codex queue timed out after {_timeout:.0f}s")
+    except OSError as exc:
+        return (False, f"codex queue failed to launch: {exc}")
+    if getattr(proc, "returncode", 1) != 0:
+        out = ((getattr(proc, "stdout", None) or "")
+               + "\n" + (getattr(proc, "stderr", None) or ""))
+        snippet = out.strip().splitlines()
+        detail = snippet[-1][:200] if snippet else "no output"
+        return (False,
+                f"codex queue exited "
+                f"{getattr(proc, 'returncode', '?')}: {detail}")
+    return (True, "")
+
+
+class CodexSink(Sink):
+    """Wake the live gpt-ops session with `codex queue` instead of typing.
+
+    Edge-triggered on the drain like MuseSink: while `wake_outstanding`
+    stands (gateway unread > 0), further deliveries report delivered with NO
+    new send; the next delivery after the drain sends again. There is no
+    composer to read — codex queues into the session, it does not type —
+    so there is no politeness gate, only the outstanding flag plus the
+    gateway drain check. A refused or failed send returns False with a NAMED
+    reason printed loud; it never advances the cursor in silence.
+    """
+
+    is_push = True
+
+    def __init__(self, thread: str):
+        super().__init__(f"codex:{thread}")
+        self.thread = thread
+
+    def _prompt(self, dms: list) -> str:
+        # Full bodies cross: this prompt IS the delivery, and the cell must
+        # answer the message it actually received, not a 160-char preview.
+        lines = [
+            f"You have {len(dms)} new mesh DM(s). "
+            "Read each and act per your standing instructions.",
+            "",
+        ]
+        for dm in dms:
+            lines.append(
+                f"--- id={dm.get('id')} from={dm.get('from_node')} "
+                f"kind={dm.get('kind')} ---"
+            )
+            lines.append(dm.get("content") or "")
+            lines.append("")
+        return "\n".join(lines)
+
+    def deliver(self, state: "MonitorState", dms: list, up_to_id: int) -> Optional[bool]:
+        led = state.ledger(self.name)
+        if led.get("wake_outstanding"):
+            # Lazy: watchdog imports mesh module-level, so the reverse must
+            # not. None (gateway error) reads as NOT-drained — re-arming on
+            # an unreadable drain signal would re-open the stack.
+            from swarph_cli.commands.watchdog import _gateway_unread_count
+            if _gateway_unread_count(state.gateway, state.self_name,
+                                     state.token) != 0:
+                print(f"[monitor] {self.name}: delivery reported on a STANDING wake "
+                      f"(no send this poll)", flush=True)
+                return True
+            led["wake_outstanding"] = False  # drained since — re-arm
+        if not dms:
+            # Nothing recoverable to hand over (log rotated) — do NOT claim
+            # a delivery; the ledger stays and the gap stays visible.
+            print(f"[monitor] {self.name}: {up_to_id} observed but no body "
+                  f"recoverable from inbox.log for the owed range", flush=True)
+            return False
+        # Module-global lookup on purpose: the sidecar regression suites patch
+        # `mesh._codex_send`, and a `from`-import here would silently bypass them.
+        ok, reason = _codex_send(self.thread, self._prompt(dms))
+        if ok:
+            led["wake_outstanding"] = True
+            led["last_wake_injected_at"] = time.time()
+            return True
+        print(f"[monitor] {self.name}: codex send FAILED: {reason}", flush=True)
+        return False
+
+    def pending_label(self, count: int) -> str:
+        plural = "s" if count != 1 else ""
+        return f"{count} DM{plural} not yet delivered to {self.name}"
+
+
 def parse_sink(spec: str) -> Sink:
     """`--deliver SINK` -> Sink. Unknown or held specs RAISE; nothing no-ops."""
     if spec == "pull":
@@ -1956,6 +2077,13 @@ def parse_sink(spec: str) -> Sink:
                 "sink 'muse:' needs a session, e.g. muse:<session-uuid>"
             )
         return MuseSink(session)
+    if spec.startswith("codex:"):
+        thread = spec[len("codex:"):]
+        if not thread:
+            raise MonitorSinkError(
+                "sink 'codex:' needs a thread, e.g. codex:<session-uuid>"
+            )
+        return CodexSink(thread)
     if spec.startswith("webhook:"):
         # HELD by the commander: outward-facing egress, and a build greenlight
         # does not clear an egress gate. It must EXIT, not silently no-op — a
@@ -1968,7 +2096,8 @@ def parse_sink(spec: str) -> Sink:
         )
     raise MonitorSinkError(
         f"unknown sink {spec!r}; expected pull, none, stdout, tmux:<target>, "
-        "tmux-notify:<target>, cursor-print:<cell>, or muse:<session>"
+        "tmux-notify:<target>, cursor-print:<cell>, muse:<session>, "
+        "or codex:<thread>"
     )
 
 
@@ -2173,6 +2302,9 @@ _OPENCODE_WAKE_PROMPT = "check mesh: swarph_dm_unread"
 # Grok's TUI has the same shape (#715, grok 1.0.41): no push channel, so
 # the wake is one line naming the pull tool and no DM body.
 _GROK_WAKE_PROMPT = "check mesh: swarph_dm_unread"
+# Muse 1.4.1 has no push channel either. The wake names the pull tool,
+# same text the grok and opencode sinks inject.
+_MUSE_WAKE_PROMPT = "check mesh: swarph_dm_unread"
 # A finished turn keeps its ▣ header and adds a duration.
 # Short turns read `· 3.3s` (drop-on-meta-edge, 1.18.33, card #961 post
 # 54557). A longer idle turn reads `· 3m 4s` (opencode pane, 2026-09-29
@@ -2310,7 +2442,7 @@ def _only_wake_text(content: str) -> bool:
     human's line.
     """
     rest = content
-    for prompt in (_GROK_WAKE_PROMPT, _OPENCODE_WAKE_PROMPT, _WAKE_PROMPT):
+    for prompt in (_MUSE_WAKE_PROMPT, _GROK_WAKE_PROMPT, _OPENCODE_WAKE_PROMPT, _WAKE_PROMPT):
         rest = rest.replace(prompt, "")
     return rest.strip() == ""
 
@@ -2475,12 +2607,43 @@ def _is_cursor_composer_row(line: str) -> bool:
     return row.startswith("→") and not row.startswith("▎")
 
 
+def _is_muse_rule(line: str) -> bool:
+    """A muse composer rule is a run of ``─``, measured on 1.4.1."""
+    s = line.strip()
+    return len(s) >= 8 and "─" in s and set(s) <= {"─"}
+
+
+def _is_muse_status(line: str) -> bool:
+    """A status row under the lower rule.
+
+    Measured muse-spark is ``model · effort · path · YOLO``. An echo
+    provider is ``echo · ~/x · YOLO``. The anchor is two or more `` · ``
+    separators, not the model name. A model switch must not blind the sink.
+    """
+    return line.count(" · ") >= 2
+
+
+def _is_muse_composer_row(lines: list[str], index: int) -> bool:
+    """The live muse composer is a ``❯`` row between two rules, with the
+    model status under the lower rule. A transcript ``❯`` above that box
+    has no rule on both sides, so it is history."""
+    row = lines[index].strip()
+    if not row.startswith("❯"):
+        return False
+    if index == 0 or index + 1 >= len(lines):
+        return False
+    if not (_is_muse_rule(lines[index - 1]) and _is_muse_rule(lines[index + 1])):
+        return False
+    return any(_is_muse_status(ln) for ln in lines[index + 2:index + 6])
+
+
 def _bottom_tui(lines: list[str]) -> "str | None":
     """Who owns the bottom-most composer row in the non-empty tail.
 
-    ``"cursor"``, ``"grok"``, or ``"opencode"``. A match above that tail
-    is scrollback. The lower composer wins, so a quoted grok box or a
-    quoted ``┃ Build ·`` row above the cursor composer does not take the pane.
+    ``"cursor"``, ``"grok"``, ``"opencode"``, or ``"muse"``. A match above
+    that tail is scrollback. The lower composer wins, so a quoted grok box
+    or a quoted ``┃ Build ·`` row above the cursor composer does not take
+    the pane.
     """
     tail = _nonempty_tail(lines, _CURSOR_COMPOSER_TAIL)
     for i in range(len(tail) - 1, -1, -1):
@@ -2490,12 +2653,15 @@ def _bottom_tui(lines: list[str]) -> "str | None":
             return "grok"
         if _is_opencode_composer_row(tail[i]):
             return "opencode"
+        if _is_muse_composer_row(tail, i):
+            return "muse"
     # A permission dialog is taller than the composer tail. Look further
     # for that one row. A mode row or a cursor/grok composer in the same
     # stretch is a quote, not a reason to take the pane.
     wider = _nonempty_tail(lines, _OPENCODE_PERMISSION_TAIL)
     for i in range(len(wider) - 1, -1, -1):
-        if _is_cursor_composer_row(wider[i]) or _is_grok_composer_row(wider, i):
+        if (_is_cursor_composer_row(wider[i]) or _is_grok_composer_row(wider, i)
+                or _is_muse_composer_row(wider, i)):
             return None
         if not _is_opencode_composer_row(wider[i]):
             continue
@@ -2645,14 +2811,74 @@ def _grok_composer_state(lines: list[str]) -> Optional[str]:
     return "busy"
 
 
+def _is_muse_pane(lines: list[str]) -> bool:
+    """Muse 1.4.1: the ``❯`` row between two rules is the bottom composer."""
+    return bool(lines) and _bottom_tui(lines) == "muse"
+
+
+def _muse_input(lines: list[str]) -> Optional[str]:
+    """Text after the live ``❯``, '' when that row is empty, None if the
+    bottom composer is not muse. A transcript ``❯`` above the rules is not
+    this row."""
+    tail = _nonempty_tail(lines, _CURSOR_COMPOSER_TAIL)
+    for i in range(len(tail) - 1, -1, -1):
+        if (_is_cursor_composer_row(tail[i]) or _is_grok_composer_row(tail, i)
+                or _is_opencode_composer_row(tail[i])):
+            return None
+        if _is_muse_composer_row(tail, i):
+            return tail[i].strip()[1:].strip()
+    return None
+
+
+def _muse_composer_state(lines: list[str]) -> Optional[str]:
+    text = _muse_input(lines)
+    if text is None:
+        return None
+    if not text:
+        return "clear"
+    if _only_wake_text(text):
+        return "wake"
+    return "busy"
+
+
+def _muse_running(lines: list[str]) -> bool:
+    """A muse turn in progress. 1.4.1 draws ``esc to interrupt`` on the
+    status row above the composer (``Double checking (Ns · esc to interrupt)``).
+    The card also names a ``Thinking`` row; either one means a keystroke
+    would land in the turn, not the idle composer. The phrase leaves the
+    visible screen when the turn ends."""
+    if not _is_muse_pane(lines):
+        return False
+    for ln in lines:
+        s = ln.strip()
+        if "esc to interrupt" in s or s == "Thinking" or s.startswith("Thinking "):
+            return True
+    return False
+
+
 def _wake_prompt_for(lines: Optional[list[str]]) -> str:
     if lines and _is_grok_pane(lines):
         return _GROK_WAKE_PROMPT
     if lines and _is_opencode_pane(lines):
         return _OPENCODE_WAKE_PROMPT
+    if lines and _is_muse_pane(lines):
+        return _MUSE_WAKE_PROMPT
     return _WAKE_PROMPT
 
 
+def _sink_failure_detail(target: str) -> str:
+    """Why a delivery returned False.
+
+    A captured pane with no known composer is an unrecognised TUI. A missing
+    pane stays the old 'probably gone' line. Callers print this phrase as
+    the failure line.
+    """
+    lines = _capture_pane_lines(target)
+    if lines and _bottom_tui(lines) is None and _composer_line(lines) is None:
+        return "unrecognised TUI"
+    return "the sink is probably gone (session restart / renamed target)"
+
+
 def _agent_running(target: str) -> Optional[bool]:
     """True while a keystroke would miss the idle composer.
 
@@ -2673,6 +2899,8 @@ def _agent_running(target: str) -> Optional[bool]:
         return _opencode_running(lines)
     if _is_grok_pane(lines):
         return _grok_running(lines)
+    if _is_muse_pane(lines):
+        return _muse_running(lines)
     tail = _nonempty_tail(lines, _CURSOR_COMPOSER_TAIL)
     composer = _composer_line(tail)
     if composer is None or not composer.startswith("→"):
@@ -2721,6 +2949,8 @@ def _composer_state(target: str) -> Optional[str]:
         return _opencode_composer_state(lines)
     if _is_grok_pane(lines):
         return _grok_composer_state(lines)
+    if _is_muse_pane(lines):
+        return _muse_composer_state(lines)
     composer = _composer_line(lines)
     if composer is not None and composer.startswith("→"):
         # A cursor marker above the bottom tail is a quoted row. The
@@ -3125,10 +3355,12 @@ def _monitor_deliver(state: MonitorState) -> None:
             else:
                 # A dead sink is VISIBLE instead of silently freezing anything.
                 led["consecutive_failures"] = int(led["consecutive_failures"]) + 1
+                detail = getattr(sink, "failure_reason", None) or (
+                    "the sink is probably gone (session restart / renamed target)"
+                )
                 print(f"{state.log_prefix} DELIVERY FAILED to {sink.name} "
                       f"({led['consecutive_failures']} consecutive) -- DMs up to "
-                      f"id {observed} were still observed and archived; the sink "
-                      f"is probably gone (session restart / renamed target)",
+                      f"id {observed} were still observed and archived; {detail}",
                       file=sys.stderr, flush=True)
             changed = True
 

{swarph_cli-0.71.0 → swarph_cli-0.72.1}/src/swarph_cli/commands/monitor.py

@@ -64,7 +64,7 @@ def _build_parser() -> argparse.ArgumentParser:
         default=[],
         metavar="SINK",
         help="repeatable; pull (default) | tmux:<target> | tmux-notify:<target> "
-        "| stdout | none | cursor-print:<cell> | muse:<session>. "
+        "| stdout | none | cursor-print:<cell> | muse:<session> | codex:<thread>. "
         "Each sink gets its OWN delivery ledger.",
     )
     start.add_argument("--poll-s", type=int, default=mesh._DEFAULT_POLL_S)

{swarph_cli-0.71.0 → swarph_cli-0.72.1}/src/swarph_cli/commands/spawn.py

@@ -64,7 +64,7 @@ _BANNER = """\
 _USAGE = """\
 Usage:
   swarph spawn [<role-or-path>] [--onboarding PATH-OR-URL]
-               [--dry-run] [--no-starter] [--print-id]
+               [--dry-run] [--no-starter] [--print-id] [--print-resolved]
                [-- provider-extra-args...]
 
 Resolution (first match wins):
@@ -147,6 +147,15 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Print resolved session-id to stdout before exec.",
     )
+    p.add_argument(
+        "--print-resolved",
+        action="store_true",
+        help="Print the resolved provider argv + swarph-added env as JSON "
+        "and exit without exec (channel validation runs first; an invalid "
+        "channel exits non-zero naming the field). Named --print-resolved, "
+        "not --print, because argparse prefix-matching would route a bare "
+        "--print to --print-id and proceed to a REAL launch.",
+    )
     p.add_argument(
         "--new-instance",
         action="store_true",
@@ -377,6 +386,126 @@ def _set_live_pin_safe(role: str) -> None:
               file=sys.stderr)
 
 
+#: cell.yaml `channel:` values valid per provider. "off"/absent means no
+#: channel for every provider. Anything else on an unlisted provider fails
+#: closed (a channel the provider cannot consume would start a deaf cell).
+_CLAUDE_CHANNELS = frozenset({"allowlisted", "dev"})
+_MUSE_CHANNELS = frozenset({"ingress"})
+
+
+# Providers whose spawn consumes $SWARPH_CHANNEL. Anything else ignores an
+# inherited value (a Claude cell's shell carries allowlisted; spawning grok
+# from it must not refuse). Measured 2026-10-01: 0.72.0 blamed cell.yaml
+# for that env and exited on grok-researcher.yaml, which has no channel field.
+_ENV_CHANNEL_PROVIDERS = frozenset({"claude", "muse"})
+
+
+def _channel_where(source: str) -> str:
+    """Name the place the mode came from. An env value must not read as cell.yaml."""
+    if source == "env":
+        return "SWARPH_CHANNEL"
+    return "cell.yaml: 'channel'"
+
+
+def _field_channel(cell: Cell) -> str:
+    extra = getattr(cell, "extra", None) or {}
+    value = extra.get("channel", "") if isinstance(extra, dict) else ""
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise CellError(
+            f"cell.yaml: 'channel' must be a string; got "
+            f"{type(value).__name__}."
+        )
+    return value
+
+
+def _resolve_channel(cell: Cell) -> tuple[str, str]:
+    """Effective channel mode and where it came from.
+
+    ``$SWARPH_CHANNEL`` wins (incl. "off") only for providers that support
+    it: claude (allowlisted/dev/off) and muse (ingress/off). Other providers
+    ignore the inherited env, as before 0.72.0, and the cell.yaml field is
+    still read. Returns ``(mode, source)`` with source ``env``, ``cell.yaml``,
+    or ``""``. Never launches anything; callers validate.
+    """
+    env_mode = os.environ.get("SWARPH_CHANNEL") or ""
+    provider = getattr(cell, "provider", None)
+    # No provider attribute: the stamp probes construct a name-only cell.
+    # Those are claude-shaped; the env still applies.
+    if env_mode and (provider is None or provider in _ENV_CHANNEL_PROVIDERS):
+        return env_mode, "env"
+    field = _field_channel(cell)
+    return field, ("cell.yaml" if field else "")
+
+
+def _channel_marketplace_dir(source: str = "cell.yaml") -> Path:
+    """Install location of the `swarph` Claude marketplace (the allowlist).
+
+    Resolved through ~/.claude/plugins/known_marketplaces.json, the same
+    registry claude reads — never a second hardcoded copy that drifts.
+    ``source`` names env vs cell.yaml so a missing registry is not blamed
+    on the file when the mode came from ``$SWARPH_CHANNEL``.
+    """
+    where = _channel_where(source)
+    registry = Path.home() / ".claude" / "plugins" / "known_marketplaces.json"
+    try:
+        data = json.loads(registry.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise CellError(
+            f"{where} 'allowlisted' needs the swarph marketplace, "
+            f"but its registry is unreadable: {registry} ({exc})."
+        ) from exc
+    try:
+        location = data["swarph"]["installLocation"]
+    except (KeyError, TypeError) as exc:
+        raise CellError(
+            f"{where} 'allowlisted' needs the swarph marketplace, "
+            f"but it is not registered in {registry}."
+        ) from exc
+    path = Path(location)
+    if not path.is_dir():
+        raise CellError(
+            f"{where} 'allowlisted' needs the swarph marketplace "
+            f"at {path}, which is not a directory."
+        )
+    return path
+
+
+def _validate_channel(cell: Cell, mode: str, source: str = "cell.yaml") -> str:
+    """Fail closed on any channel mode the provider cannot consume.
+
+    Returns the mode unchanged. "" and "off" are valid everywhere (no-op).
+    Raises CellError naming the source (``SWARPH_CHANNEL`` or the cell.yaml
+    field) and the file, for a missing marketplace, so the operator fixes
+    config, never debugs a deaf cell.
+    """
+    if mode in ("", "off"):
+        return mode
+    where = _channel_where(source)
+    provider = cell.provider
+    if provider == "claude":
+        if mode not in _CLAUDE_CHANNELS:
+            raise CellError(
+                f"{where} {mode!r} is not valid for provider "
+                f"'claude'. Valid values: {sorted(_CLAUDE_CHANNELS | {'off'})}."
+            )
+        if mode == "allowlisted":
+            _channel_marketplace_dir(source)
+        return mode
+    if provider == "muse":
+        if mode not in _MUSE_CHANNELS:
+            raise CellError(
+                f"{where} {mode!r} is not valid for provider "
+                f"'muse'. Valid values: {sorted(_MUSE_CHANNELS | {'off'})}."
+            )
+        return mode
+    raise CellError(
+        f"{where} {mode!r} is only valid for providers "
+        f"'claude' and 'muse'; provider is {provider!r}."
+    )
+
+
 def _build_claude_argv(
     cell: Cell,
     session_id: str,
@@ -400,7 +529,8 @@ def _build_claude_argv(
             argv.extend(["--append-system-prompt", starter])
 
     argv.extend(passthrough)
-    mode = os.environ.get("SWARPH_CHANNEL") or ""
+    mode, source = _resolve_channel(cell)
+    mode = _validate_channel(cell, mode, source)
     if mode == "allowlisted":
         argv.extend(["--channels", "plugin:swarph@swarph"])
     elif mode == "dev":
@@ -447,7 +577,10 @@ def _spawn_env_base(cell: Cell) -> dict[str, str]:
     env = scrub_env_for_subprocess()
     env["SWARPH_SPAWN"] = "1"
     env["SWARPH_SELF"] = cell.name
-    mode = os.environ.get("SWARPH_CHANNEL") or ""
+    mode, _source = _resolve_channel(cell)
+    # NOTE: the marketplace/validity gate lives in _validate_channel, which
+    # _build_claude_argv (and the muse env builder) run. This base stays a
+    # pure reflection of the resolved mode so every provider's env agrees.
     if mode in {"allowlisted", "dev"}:
         env["SWARPH_CHANNEL_CELL"] = cell.name
     else:
@@ -475,6 +608,23 @@ def _claude_env(cell: Cell) -> dict[str, str]:
     return env
 
 
+def _muse_env(cell: Cell) -> dict[str, str]:
+    """Launch env for an interactive ``muse`` session.
+
+    Claude billing scrub + identity stamp (shared), plus the external-agent
+    ingress gate when the cell takes the `ingress` channel. The gate must be
+    in the environment AT SESSION LAUNCH — it cannot be enabled mid-session
+    (measured on card #961: list/send without it reads "external agent
+    ingress is unavailable"). `_validate_channel` already ran at the
+    run_spawn choke point; the mode read here agrees with it by construction.
+    """
+    env = _claude_env(cell)
+    mode, _source = _resolve_channel(cell)
+    if mode == "ingress":
+        env["MUSE_EXPERIMENTAL_EXTERNAL_AGENT_INGRESS"] = "on"
+    return env
+
+
 def _agy_env(cell: Cell) -> dict[str, str]:
     """Subscription-billing env for an ``agy`` (antigravity/Gemini) session.
 
@@ -2706,6 +2856,8 @@ class MuseMembrane(ClaudeMembrane):
 
     name = "muse"
 
+    env_builder = staticmethod(_muse_env)
+
     def apply_task_injection(self, cell: Cell, argv: list[str], text: str) -> None:
         # muse has no --append-system-prompt; the prompt is POSITIONAL. Appended
         # only when this is a FRESH session — `muse resume` takes no prompt, so
@@ -3184,6 +3336,17 @@ def run_spawn(argv: Optional[list[str]] = None) -> int:
     was_generated = False
     effective_role: Optional[str] = None
 
+    # Channel gate BEFORE session minting: an invalid channel mode must fail
+    # before load_or_create_session_id persists anything (a refused spawn
+    # must not leave a minted sidecar behind). One choke point for every
+    # provider; builders below see only validated modes.
+    try:
+        mode, source = _resolve_channel(cell)
+        _validate_channel(cell, mode, source)
+    except CellError as exc:
+        print(f"swarph spawn: {exc}", file=sys.stderr)
+        return 1
+
     if membrane.uses_pinned_session():
         # When user typed a slot-role (e.g. `swarph spawn drop-on-meta-edge-2`)
         # the cell.yaml resolved to the BASE file (drop-on-meta-edge.yaml) so
@@ -3265,6 +3428,18 @@ def run_spawn(argv: Optional[list[str]] = None) -> int:
         )
         return 0
 
+    if args.print_resolved:
+        # Resolved-launch capture: argv + the env keys swarph adds, as JSON
+        # on stdout, then exit BEFORE resolve_binary — no binary needed, no
+        # session started. Banner stays on stderr so stdout parses clean.
+        # env_added is a DIFF against the parent env (not the full env) so
+        # no secret the operator exported leaks into the capture.
+        built_env = membrane.spawn_env(cell)
+        added = {k: v for k, v in built_env.items()
+                 if os.environ.get(k) != v}
+        print(json.dumps({"argv": spawn_argv, "env_added": added}))
+        return 0
+
     provider_bin = membrane.resolve_binary()
     if provider_bin is None:
         print(membrane.binary_not_found_message(), file=sys.stderr)