create-workframe 0.1.2 → 0.1.4

package/workframe-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workframe/workframe-api",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "scripts": {

package/workframe-api/server.py

@@ -46,6 +46,9 @@ import turn_credentials
 import llm_proxy
 import action_proxy
 import internal_proxy_auth
+import concierge
+import llm_error_glossary
+import openrouter_catalog
 import updates as stack_updates
 
 HERMES_DATA = Path(os.environ.get("HERMES_DATA", "/opt/data"))
@@ -548,12 +551,26 @@ def _admin_write_allowed(handler: BaseHTTPRequestHandler) -> bool:
 
 
 def _apply_stack_update(target: str) -> dict[str, Any]:
+    workframe_version = ""
+    if target in {"workframe", "all"}:
+        try:
+            workframe_version = str(
+                stack_updates.updates_available().get("workframe", {}).get("latest") or ""
+            ).strip()
+        except Exception:  # noqa: BLE001
+            workframe_version = ""
     try:
         return stack_updates.apply_update(target)
     except ValueError as exc:
-        if str(exc) != "docker_unavailable" or not _supervisor_ready():
+        err = str(exc)
+        if not _supervisor_ready():
+            raise
+        if err not in ("docker_unavailable", "admin_updates_disabled"):
             raise
-        status, data = _supervisor_request("POST", "/v1/stack.apply", {"target": target}, timeout=900.0)
+        body: dict[str, Any] = {"target": target}
+        if workframe_version:
+            body["workframe_version"] = workframe_version
+        status, data = _supervisor_request("POST", "/v1/stack.apply", body, timeout=900.0)
         if status >= 300 or not isinstance(data, dict) or not data.get("ok"):
             raise ValueError(str((data or {}).get("error") or "supervisor_apply_failed"))
         return data
@@ -2638,6 +2655,24 @@ def _spawn_hermes_device_oauth(user_id: str, hermes_auth_id: str, log_container:
     """Start long-running `hermes auth add` detached in gateway (survives exec return)."""
     home = _hermes_user_home_container(user_id)
     _user_hermes_home(user_id).mkdir(parents=True, exist_ok=True)
+    if SECURE_MODE and _supervisor_ready():
+        status, data = _supervisor_request(
+            "POST",
+            "/v1/hermes.device_oauth_start",
+            {"home": home, "hermes_auth_id": hermes_auth_id, "log_path": log_container},
+            timeout=30.0,
+        )
+        if status >= 300:
+            err = data.get("error") if isinstance(data, dict) else str(data)
+            raise ValueError(err or "device_oauth_start_failed")
+        if not isinstance(data, dict):
+            raise ValueError("device_oauth_start_invalid")
+        exit_code = data.get("exit_code")
+        try:
+            code = int(exit_code if exit_code is not None else 1)
+        except (TypeError, ValueError):
+            code = 1
+        return code, str(data.get("output") or "")
     auth_cmd = " ".join(shlex.quote(part) for part in ["auth", "add", hermes_auth_id])
     shell = (
         f"mkdir -p {shlex.quote(home)}; "
@@ -12302,8 +12337,9 @@ def _provider_pool_entry(provider: str, env_var: str, *, base_url: str = "") ->
 
 
 def _runtime_provider_pool_entry(provider: str, env_var: str) -> dict[str, Any]:
-    """Credential pool row for u-* profiles — keys live in .env leases, upstream via API proxy."""
-    return _provider_pool_entry(provider, env_var, base_url=_llm_proxy_base_url(provider))
+    """Credential pool row for u-* profiles — lease token lives in OPENAI_API_KEY."""
+    lease_env = "OPENAI_API_KEY"
+    return _provider_pool_entry(provider, lease_env, base_url=_llm_proxy_base_url(provider))
 
 
 def _provider_pool_has_entries(auth: dict[str, Any], provider: str) -> bool:
@@ -13313,23 +13349,75 @@ def _enrich_room_chat_payload(payload: dict[str, Any], user_id: str) -> dict[str
     return body
 
 
-def _emit_stream_chat_error(handler: BaseHTTPRequestHandler, message: str) -> None:
-    """SSE error frame — keeps UI stream parser on the happy path."""
-    text = str(message or "").strip() or "Chat failed."
-    payload = json.dumps({"error": text, "text": text, "message": text})
+def _emit_stream_chat_error(
+    handler: BaseHTTPRequestHandler,
+    message: str = "",
+    *,
+    entry: dict[str, Any] | None = None,
+) -> None:
+    """SSE error frame — structured playbook when entry supplied."""
+    payload = llm_error_glossary.notice_payload(entry) if entry else {}
+    if not payload:
+        text = str(message or "").strip() or "Chat failed."
+        payload = {"error": text, "text": text, "message": text}
     try:
         handler.send_response(200)
         handler.send_header("Content-Type", "text/event-stream; charset=utf-8")
         handler.send_header("Cache-Control", "no-cache")
         handler.send_header("Connection", "keep-alive")
         handler.end_headers()
-        handler.wfile.write(f"event: error\ndata: {payload}\n\n".encode("utf-8"))
+        body = json.dumps(payload)
+        handler.wfile.write(f"event: error\ndata: {body}\n\n".encode("utf-8"))
         handler.wfile.write(b"event: done\ndata: {}\n\n")
         handler.wfile.flush()
     except (BrokenPipeError, ConnectionResetError, OSError):
         return
 
 
+def _emit_stream_concierge(handler: BaseHTTPRequestHandler, entry: dict[str, Any]) -> None:
+    """Deterministic assistant reply when LLM path is unavailable."""
+    payload = llm_error_glossary.notice_payload(entry)
+    text = str(payload.get("message") or "")
+    hint = str(payload.get("hint") or "").strip()
+    if hint:
+        text = f"{text}\n\n{hint}"
+    try:
+        handler.send_response(200)
+        handler.send_header("Content-Type", "text/event-stream; charset=utf-8")
+        handler.send_header("Cache-Control", "no-cache")
+        handler.send_header("Connection", "keep-alive")
+        handler.end_headers()
+        handler.wfile.write(
+            f"event: concierge\ndata: {json.dumps(payload)}\n\n".encode("utf-8"),
+        )
+        handler.wfile.write(
+            f"event: message.complete\ndata: {json.dumps({'content': text, 'text': text})}\n\n".encode(
+                "utf-8",
+            ),
+        )
+        handler.wfile.write(b"event: done\ndata: {}\n\n")
+        handler.wfile.flush()
+    except (BrokenPipeError, ConnectionResetError, OSError):
+        return
+
+
+def _log_llm_failure(
+    handler: BaseHTTPRequestHandler,
+    code: str,
+    *,
+    provider: str = "",
+    model: str = "",
+    profile: str = "",
+) -> None:
+    if hasattr(handler, "_log_audit"):
+        handler._log_audit(  # type: ignore[attr-defined]
+            "llm_failure",
+            "llm",
+            profile or provider or "unknown",
+            f"code={code} provider={provider} model={model}",
+        )
+
+
 def stream_profile_chat(handler: BaseHTTPRequestHandler, profile: str, payload: dict[str, Any]) -> None:
     _triggering_user = str(payload.get("user_id", "") or "")
     _workspace_id = str(payload.get("workspace_id", "") or "")
@@ -13345,6 +13433,15 @@ def stream_profile_chat(handler: BaseHTTPRequestHandler, profile: str, payload:
     if not text:
         raise ValueError("text required")
     llm_provider = _llm_billing_provider(prof)
+    llm_ready = bool(
+        _triggering_user
+        and _user_can_use_llm(_triggering_user, _workspace_id, llm_provider)
+    )
+    if _triggering_user and not llm_ready:
+        entry = concierge.respond(text, situation="no_provider")
+        _log_llm_failure(handler, str(entry.get("code") or "no_llm_provider"), provider=llm_provider, profile=prof)
+        _emit_stream_concierge(handler, entry)
+        return
     try:
         lifecycle = ensure_profile_api(
             prof,
@@ -13358,7 +13455,15 @@ def stream_profile_chat(handler: BaseHTTPRequestHandler, profile: str, payload:
             )
             _overlay_turn_user_env(prof, _triggering_user, _workspace_id, _turn_run_id)
     except ValueError as exc:
-        _emit_stream_chat_error(handler, str(exc))
+        err_text = str(exc)
+        if "no_llm_provider_for_user" in err_text:
+            entry = concierge.respond(text, situation="no_provider")
+            _log_llm_failure(handler, "no_llm_provider", provider=llm_provider, profile=prof)
+            _emit_stream_concierge(handler, entry)
+            return
+        entry = llm_error_glossary.classify_exception_text(err_text)
+        _log_llm_failure(handler, str(entry.get("code") or ""), provider=llm_provider, profile=prof)
+        _emit_stream_chat_error(handler, entry=entry)
         return
     upstream_body = json.dumps(_profile_turn_payload(prof, text, _room_id)).encode("utf-8")
 
@@ -13487,34 +13592,21 @@ def stream_profile_chat(handler: BaseHTTPRequestHandler, profile: str, payload:
                 handler.wfile.flush()
         if not saw_complete or not complete_text:
             config_key = _read_config_model_api_key(prof)
+            _, model_name = _read_model_from_config(prof)
             if config_key.startswith(turn_credentials.LEASE_PREFIX) and not turn_credentials.validate_lease(
                 config_key,
             ):
-                err_text = (
-                    "Turn credential expired before the model replied. "
-                    "Send the message again."
-                )
-                err_code = "invalid_lease"
-            elif not saw_complete:
-                err_text = (
-                    "Model provider returned no reply. "
-                    "The request may have failed at the gateway or provider."
-                )
-                err_code = "provider_empty_reply"
+                entry = llm_error_glossary.playbook_entry("invalid_lease")
             else:
-                err_text = (
-                    "Model provider returned an empty reply. "
-                    "Check the model name in Settings or try again."
-                )
-                err_code = "provider_empty_reply"
-            err_payload = json.dumps(
-                {
-                    "error": err_text,
-                    "text": err_text,
-                    "message": err_text,
-                    "code": err_code,
-                },
+                entry = llm_error_glossary.playbook_entry("provider_empty_reply")
+            _log_llm_failure(
+                handler,
+                str(entry.get("code") or "provider_empty_reply"),
+                provider=llm_provider,
+                model=str(model_name or ""),
+                profile=prof,
             )
+            err_payload = json.dumps(llm_error_glossary.notice_payload(entry))
             handler.wfile.write(f"event: error\ndata: {err_payload}\n\n".encode("utf-8"))
             handler.wfile.flush()
         handler.wfile.write(b"event: done\ndata: {}\n\n")
@@ -14252,16 +14344,16 @@ def _resolve_command(token: str) -> dict[str, Any] | None:
 # overrides live in the profile's config.yaml under `model.default` and
 # `fallback_providers`; this constant is the install-wide default the
 # migration writes when a profile is missing either field.
-HERMES_DEFAULT_PRIMARY = "openrouter/owl-alpha"
+HERMES_DEFAULT_PRIMARY = "google/gemini-2.5-flash"
 HERMES_DEFAULT_FALLBACK_CHAIN: list[dict[str, str]] = [
-    {"provider": "openrouter", "model": "openrouter/nex-agi"},
-    {"provider": "openrouter", "model": "openrouter/nvidia/nemotron-3-ultra-550b-a55b:free"},
+    {"provider": "openrouter", "model": "anthropic/claude-sonnet-4.5"},
+    {"provider": "openrouter", "model": "meta-llama/llama-3.3-70b-instruct:free"},
 ]
 
 # ponytail: minimum-viable agentic models per LLM provider; user can escalate in settings.
 PROVIDER_MVP_MODELS: dict[str, dict[str, Any]] = {
     "openrouter": {
-        "primary": "openrouter/owl-alpha",
+        "primary": "google/gemini-2.5-flash",
         "fallbacks": list(HERMES_DEFAULT_FALLBACK_CHAIN),
     },
     "openai": {
@@ -14273,8 +14365,8 @@ PROVIDER_MVP_MODELS: dict[str, dict[str, Any]] = {
         "fallbacks": [{"provider": "anthropic", "model": "claude-3-5-haiku-20241022"}],
     },
     "google": {
-        "primary": "gemini-2.0-flash",
-        "fallbacks": [{"provider": "google", "model": "gemini-2.0-flash"}],
+        "primary": "gemini-2.5-flash",
+        "fallbacks": [{"provider": "google", "model": "gemini-2.5-flash-lite"}],
     },
     "deepseek": {
         "primary": "deepseek-chat",
@@ -14285,8 +14377,8 @@ PROVIDER_MVP_MODELS: dict[str, dict[str, Any]] = {
         "fallbacks": [{"provider": "openai-codex", "model": "gpt-5.4-medium"}],
     },
     "nous": {
-        "primary": "openrouter/owl-alpha",
-        "fallbacks": [{"provider": "nous", "model": "openrouter/owl-alpha"}],
+        "primary": "nousresearch/hermes-4-70b",
+        "fallbacks": [{"provider": "nous", "model": "nousresearch/hermes-4-70b"}],
     },
 }
 
@@ -14394,15 +14486,21 @@ HERMES_MODEL_CATALOG: list[dict[str, str]] = [
     {"provider": "OpenRouter", "model": "openrouter/auto",
      "label": "OpenRouter Auto",
      "description": "OpenRouter picks the best model per prompt."},
-    {"provider": "OpenRouter", "model": "openrouter/owl-alpha",
-     "label": "Owl Alpha",
-     "description": "Workframe default primary — strong general agent."},
-    {"provider": "OpenRouter", "model": "openrouter/nex-agi",
-     "label": "Nex AGI",
-     "description": "Fallback-tier reasoning model on OpenRouter."},
-    {"provider": "OpenRouter", "model": "openrouter/nvidia/nemotron-3-ultra-550b-a55b:free",
-     "label": "Nemotron 3 Ultra (free)",
-     "description": "OpenRouter free tier — long-context agentic fallback."},
+    {"provider": "OpenRouter", "model": "google/gemini-2.5-flash",
+     "label": "Gemini 2.5 Flash",
+     "description": "Fast, capable default for OpenRouter BYOK."},
+    {"provider": "OpenRouter", "model": "anthropic/claude-sonnet-4.5",
+     "label": "Claude Sonnet 4.5 (via OR)",
+     "description": "Strong agentic fallback on OpenRouter."},
+    {"provider": "OpenRouter", "model": "meta-llama/llama-3.3-70b-instruct:free",
+     "label": "Llama 3.3 70B (free)",
+     "description": "Free-tier OpenRouter fallback when available."},
+    {"provider": "OpenRouter", "model": "z-ai/glm-5.1",
+     "label": "GLM 5.1",
+     "description": "High-availability model on OpenRouter."},
+    {"provider": "OpenRouter", "model": "nousresearch/hermes-4-70b",
+     "label": "Hermes 4 70B",
+     "description": "Agent-tuned model on OpenRouter."},
     {"provider": "OpenRouter", "model": "openrouter/nvidia/llama-3.1-nemotron-70b-instruct",
      "label": "Nemotron 70B Instruct",
      "description": "NVIDIA Nemotron via OpenRouter."},
@@ -14780,6 +14878,17 @@ def hermes_models(profile: str = "", user_id: str = "", workspace_id: str = "")
         ] if (picker_llm or connected) else [],
         block,
     )
+    if user_id and "openrouter" in {n.lower() for n in (picker_llm or connected)}:
+        resolved = _resolve_credential(user_id, workspace_id, "openrouter", user_only=True)
+        secret = _credential_secret(resolved or {}, user_id) if resolved else ""
+        live = openrouter_catalog.live_suggestions(secret, limit=30)
+        if live:
+            seen = {str(r.get("model") or "") for r in suggestions}
+            suggestions = [
+                {**row, "label": f"Live · {row.get('label', row.get('model', ''))}"}
+                for row in live
+                if str(row.get("model") or "") not in seen
+            ] + suggestions
     return {
         "ok": True,
         "profile": primary_profile,
@@ -17391,11 +17500,29 @@ class Handler(BaseHTTPRequestHandler):
                                VALUES (?,?,?,?,?,?,?,?,?,?,?,?)""",
                             (cred_id, None, user_id, None, provider, credential_type, cred_ref, label, 1, user_id, now, now),
                         )
+                    conn.execute(
+                        """UPDATE credential_bindings
+                           SET is_active = 0, deleted_at = ?, updated_at = ?
+                           WHERE user_id = ? AND provider = ? AND deleted_at IS NULL AND id != ?""",
+                        (now, now, user_id, provider, cred_id),
+                    )
                     conn.commit()
                     conn.close()
                 except sqlite3.Error as exc:
                     return self._json(500, {"ok": False, "error": f"db_error: {exc}"})
                 self._log_audit("credential_stored", "credential_binding", cred_id, f"provider={provider}")
+                health: dict[str, Any] = {}
+                if provider == "openrouter":
+                    secret_probe = _credential_secret(
+                        {
+                            "credential_ref": cred_ref,
+                            "scope": "user",
+                            "user_id": user_id,
+                        },
+                        user_id,
+                    )
+                    if secret_probe:
+                        health = openrouter_catalog.probe_account(secret_probe)
                 _bootstrap_model_after_llm_connect(user_id, str(body.get("workspace_id") or ""), provider)
                 return self._json(200, {
                     "ok": True,
@@ -17407,6 +17534,7 @@ class Handler(BaseHTTPRequestHandler):
                     "user_id": user_id,
                     "created_at": now,
                     "updated_at": now,
+                    "health": health,
                     **payload,
                 })
 

package/workframe-api/updates.py

@@ -190,6 +190,38 @@ def _host_compose_ready() -> bool:
     return compose.joinpath("docker-compose.yml").is_file()
 
 
+def _supervisor_configured() -> bool:
+    return bool(os.environ.get("WORKFRAME_SUPERVISOR_URL", "").strip()) and bool(
+        os.environ.get("WORKFRAME_SUPERVISOR_TOKEN", "").strip()
+    )
+
+
+def _supervisor_gateway_image_digest() -> tuple[str, str]:
+    """Read gateway image digest via workframe-supervisor (SECURE_MODE API has no docker.sock)."""
+    base = str(os.environ.get("WORKFRAME_SUPERVISOR_URL", "")).rstrip("/")
+    token = str(os.environ.get("WORKFRAME_SUPERVISOR_TOKEN", "")).strip()
+    if not base or not token:
+        return "", ""
+    req = urllib.request.Request(
+        f"{base}/v1/gateway.image",
+        headers={"Authorization": f"Bearer {token}", "Accept": "application/json", "User-Agent": "workframe-api"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=15.0) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError):
+        return "", ""
+    if not isinstance(data, dict) or not data.get("ok"):
+        return "", ""
+    return str(data.get("digest") or "").strip(), str(data.get("ref") or "").strip()
+
+
+def _admin_stack_updates_enabled() -> bool:
+    if os.environ.get("WORKFRAME_ENABLE_ADMIN_UPDATES") == "1":
+        return True
+    return _supervisor_configured()
+
+
 def _docker_apply_ready() -> tuple[bool, str | None]:
     if not Path(DOCKER_SOCK).exists():
         return False, "Docker socket is not available to the API container."
@@ -202,6 +234,29 @@ def _docker_apply_ready() -> tuple[bool, str | None]:
     return True, None
 
 
+def _update_apply_channel() -> tuple[str, bool, str | None]:
+    """Returns (channel, ready, reason). channel: api_docker | supervisor | none."""
+    api_docker = Path(DOCKER_SOCK).exists()
+    if api_docker:
+        ok, reason = _docker_apply_ready()
+        if ok:
+            return "api_docker", True, None
+        if not _supervisor_configured():
+            return "none", False, reason
+    if _supervisor_configured():
+        if _script_path("apply-update-workframe.sh") is None and _script_path("apply-update-hermes.sh") is None:
+            return "supervisor", False, "Stack update scripts are missing from this install."
+        return "supervisor", True, None
+    if api_docker:
+        _, reason = _docker_apply_ready()
+        return "none", False, reason
+    return (
+        "none",
+        False,
+        "In-place updates need workframe-supervisor or Docker on the stack host.",
+    )
+
+
 def _product_state(*, update_available: bool, can_update: bool) -> str:
     if update_available and can_update:
         return "available"
@@ -238,7 +293,9 @@ def _releases_manifest() -> dict[str, Any]:
 def updates_available(*, desktop_version: str = "", hermes_agent_version: str = "") -> dict[str, Any]:
     compose_dir = _compose_dir()
     project_root = _project_root()
-    docker_ok = Path(DOCKER_SOCK).exists()
+    api_docker = Path(DOCKER_SOCK).exists()
+    supervisor_ok = _supervisor_configured()
+    apply_channel, apply_ready, apply_reason = _update_apply_channel()
     installed = _read_installed_workframe_version(project_root)
 
     npm_latest = ""
@@ -254,15 +311,20 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
     installed_pkg = installed.get("package") or installed.get("api") or ""
     workframe_update = bool(workframe_latest and _version_lt(installed_pkg, workframe_latest))
 
-    hermes_digest, hermes_ref = _container_image_digest(GATEWAY_CONTAINER)
+    hermes_digest, hermes_ref = ("", "")
+    if api_docker:
+        hermes_digest, hermes_ref = _container_image_digest(GATEWAY_CONTAINER)
+    elif supervisor_ok:
+        hermes_digest, hermes_ref = _supervisor_gateway_image_digest()
     hermes_tag = hermes_ref.rsplit(":", 1)[-1] if hermes_ref and ":" in hermes_ref else HERMES_TAG
     hermes_latest_digest = ""
     try:
         hermes_latest_digest = _docker_hub_digest(HERMES_IMAGE, HERMES_TAG)
     except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, KeyError):
         pass
+    hermes_image_known = bool(api_docker or supervisor_ok)
     hermes_update = bool(
-        docker_ok
+        hermes_image_known
         and hermes_latest_digest
         and hermes_digest
         and hermes_digest != hermes_latest_digest,
@@ -275,15 +337,14 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
     if len(digest_short) > 28:
         digest_short = digest_short[:28] + "…"
 
-    docker_apply_ok, docker_apply_reason = _docker_apply_ready()
     hermes_script_ok = _script_path("apply-update-hermes.sh") is not None
     workframe_script_ok = _script_path("apply-update-workframe.sh") is not None
-    hermes_can_update = bool(docker_apply_ok and hermes_script_ok)
-    workframe_can_update = bool(docker_apply_ok and workframe_script_ok)
-    hermes_reason = docker_apply_reason
+    hermes_can_update = bool(apply_ready and hermes_script_ok)
+    workframe_can_update = bool(apply_ready and workframe_script_ok)
+    hermes_reason = apply_reason
     if not hermes_reason and hermes_update and not hermes_script_ok:
         hermes_reason = "Hermes update script is missing from this install."
-    workframe_reason = docker_apply_reason
+    workframe_reason = apply_reason
     if not workframe_reason and workframe_update and not workframe_script_ok:
         workframe_reason = "Workframe update script is missing from this install."
     if not workframe_reason and workframe_update and not workframe_latest:
@@ -294,7 +355,11 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
 
     return {
         "ok": True,
-        "docker_available": docker_ok,
+        "docker_available": apply_ready,
+        "docker_sock_on_api": api_docker,
+        "supervisor_configured": supervisor_ok,
+        "update_apply_channel": apply_channel if apply_ready else None,
+        "update_apply_ready": apply_ready,
         "compose_dir": str(compose_dir),
         "project_root": str(project_root),
         "workframe": {
@@ -323,7 +388,7 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
             "reason": hermes_reason,
             "update_mode": "docker-compose-pull",
             "install_kind": "docker",
-            "can_restart_gateway": bool(docker_apply_ok and _script_path("restart-gateway-hermes.sh") is not None),
+            "can_restart_gateway": bool(apply_ready and _script_path("restart-gateway-hermes.sh") is not None),
         },
         "desktop": {
             "current": desktop_installed,
@@ -339,12 +404,33 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
     }
 
 
+def _apply_env_for_target(target: str) -> dict[str, str]:
+    env = os.environ.copy()
+    env.setdefault("WORKFRAME_COMPOSE_DIR", str(_compose_dir()))
+    env.setdefault("WORKFRAME_PROJECT_ROOT", str(_project_root()))
+    if target in {"workframe", "all"}:
+        latest = ""
+        try:
+            latest = str(updates_available().get("workframe", {}).get("latest") or "").strip()
+        except Exception:  # noqa: BLE001
+            latest = ""
+        if latest:
+            env["WORKFRAME_UPDATE_ALLOW_NPM"] = "1"
+            env["WORKFRAME_UPDATE_VERSION"] = latest
+    return env
+
+
 def apply_update(target: str) -> dict[str, Any]:
-    if os.environ.get("WORKFRAME_ENABLE_ADMIN_UPDATES") != "1":
+    if not _admin_stack_updates_enabled():
         raise ValueError("admin_updates_disabled")
     target = str(target or "all").strip().lower()
     if target not in {"hermes", "workframe", "all"}:
         raise ValueError("invalid_update_target")
+    _, apply_ready, apply_reason = _update_apply_channel()
+    if not apply_ready:
+        if not Path(DOCKER_SOCK).exists():
+            raise ValueError("docker_unavailable")
+        raise ValueError(str(apply_reason or "docker_apply_unavailable"))
     if not Path(DOCKER_SOCK).exists():
         raise ValueError("docker_unavailable")
 
@@ -360,9 +446,7 @@ def apply_update(target: str) -> dict[str, Any]:
             raise ValueError("update_script_missing:workframe")
         scripts.append(str(script))
 
-    env = os.environ.copy()
-    env.setdefault("WORKFRAME_COMPOSE_DIR", str(_compose_dir()))
-    env.setdefault("WORKFRAME_PROJECT_ROOT", str(_project_root()))
+    env = _apply_env_for_target(target)
 
     logs: list[str] = []
     for script in scripts:
@@ -382,13 +466,15 @@ def apply_update(target: str) -> dict[str, Any]:
 
 
 def restart_gateway() -> dict[str, Any]:
-    if os.environ.get("WORKFRAME_ENABLE_ADMIN_UPDATES") != "1":
+    if not _admin_stack_updates_enabled():
         raise ValueError("admin_updates_disabled")
+    _, apply_ready, apply_reason = _update_apply_channel()
+    if not apply_ready:
+        if not Path(DOCKER_SOCK).exists():
+            raise ValueError("docker_unavailable")
+        raise ValueError(str(apply_reason or "docker_apply_unavailable"))
     if not Path(DOCKER_SOCK).exists():
         raise ValueError("docker_unavailable")
-    docker_apply_ok, docker_apply_reason = _docker_apply_ready()
-    if not docker_apply_ok:
-        raise ValueError(str(docker_apply_reason or "docker_apply_unavailable"))
     script = _script_path("restart-gateway-hermes.sh")
     if not script:
         raise ValueError("restart_script_missing:gateway")
@@ -414,4 +500,7 @@ if __name__ == "__main__":
     assert _version_lt("0.1.0", "0.1.1")
     assert not _version_lt("0.1.0", "0.1.0")
     assert parse_hermes_version_output("Hermes Agent v0.17.0 (2026.6.19)") == "0.17.0"
+    ch, ready, _ = _update_apply_channel()
+    assert ch in {"api_docker", "supervisor", "none"}
+    assert ready is False or ch != "none"
     print("updates module ok")