@oneciel-ai/ciel-runtime 0.2.29 → 0.2.30

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 This file records stable Ciel Runtime releases. Changes are grouped by user-visible
 capability, followed by the complete commit ledger merged into each release.
 
+## 0.2.30 — 2026-08-24
+
+- Enabled Z.AI Start Plan routed clients by acquiring a fresh request-scoped
+  verification value through the official Aliyun CAPTCHA browser SDK before
+  every upstream attempt; verification results return only to a state-bound
+  loopback receiver and are never persisted.
+- Refresh Start Plan CAPTCHA headers independently for retries, serialize
+  concurrent verification requests, and keep every other provider isolated
+  from the Start Plan-only headers.
+- Route Codex Responses through the Start Plan gateway's verified Anthropic
+  Messages endpoint; the advertised OpenAI base currently exposes no standard
+  Responses or Chat Completions route.
+- Accept both native Win32 and ConPTY/SSH VT arrow-key sequences in Windows
+  prelaunch menus, including the provider environment menu shown after OAuth.
+
 ## 0.2.29 — 2026-08-24
 
 - Split Z.AI general API, Coding Plan, and Start Plan into independent provider

package/ciel_runtime.py

@@ -170,6 +170,7 @@ from ciel_runtime_support.credentials import secret_fingerprint as project_secre
 from ciel_runtime_support.executable_discovery import ExecutableDiscovery
 from ciel_runtime_support.github_copilot_oauth_runtime import GitHubCopilotOAuthRuntime, GitHubCopilotOAuthRuntimePorts
 from ciel_runtime_support.zai_oauth import ZaiOAuthClient, ZaiOAuthHttp, ZaiOAuthRuntime, ZaiOAuthRuntimePorts, ZaiOAuthService
+from ciel_runtime_support.zai_start_plan_captcha import ZaiStartPlanRuntimeHeaderPreparer
 from ciel_runtime_support.headless_config import HeadlessConfigCommands, HeadlessConfigServices, HeadlessEnvFileLoader, apply_headless_config
 from ciel_runtime_support.http_response import ChannelDeliveryGuard, HttpResponseAdapter
 from ciel_runtime_support.kimi_runtime_context import KimiConfigurationPorts, KimiIdentityPorts, KimiLifecyclePorts, KimiProcessPorts, KimiRuntimeCompatibilityApi, KimiRuntimeContext
@@ -537,7 +538,6 @@ inject_pending_channel_context = channel_llm_context.inject_pending_channel_cont
 TERMINAL_INPUT_MODE_RESET = terminal_platform_io.TERMINAL_INPUT_MODE_RESET
 _terminal_winsize_from_fd = terminal_platform_io.terminal_winsize_from_fd
 _apply_pty_winsize = terminal_platform_io.apply_pty_winsize
-
 try:
     sys.stdout.reconfigure(encoding="utf-8")
     sys.stderr.reconfigure(encoding="utf-8")
@@ -1340,7 +1340,7 @@ provider_requires_streaming = _PROVIDER_REQUEST_ACCESS.requires_streaming
 key_from_request_headers = _PROVIDER_REQUEST_ACCESS.key_from_headers
 provider_headers = _PROVIDER_REQUEST_ACCESS.headers
 get_current_provider = _PROVIDER_REQUEST_ACCESS.current_provider
-
+prepare_provider_runtime_headers = ZaiStartPlanRuntimeHeaderPreparer(log=router_log)
 def materialize_runtime_command(
     runtime_name: str,
     executable: str,
@@ -2799,7 +2799,7 @@ def upstream_retry_context() -> UpstreamRetryContext:
         errors=UpstreamRetryErrorPorts(project_upstream_http_error_message, project_upstream_retry_message, first_header, parse_retry_after_seconds, format_duration_seconds),
         policy=UpstreamRetryPolicyPorts(project_configured_gateway_retries, retry_after_exceeds_request_timeout, project_retryable_upstream_exception,
                                         project_upstream_retry_wait_seconds, UPSTREAM_RETRY_HTTP_CODES, lambda: str(load_config().get("language") or "en")),
-        credentials=UpstreamRetryCredentialPorts(key_from_request_headers, provider_api_key_count, provider_has_live_api_key, provider_headers, register_api_key_cooldown),
+        credentials=UpstreamRetryCredentialPorts(key_from_request_headers, provider_api_key_count, provider_has_live_api_key, provider_headers, prepare_provider_runtime_headers, register_api_key_cooldown),
         rate_limit=UpstreamRetryRateLimitPorts(learn_router_rate_limit_headers, router_log, register_router_rate_limit_backoff, write_router_activity),
         transport=UpstreamRetryTransportPorts(estimate_tokens, provider_urlopen, set_upstream_stream_read_timeout, provider_stream_idle_timeout_seconds),
     )

package/ciel_runtime_support/prelaunch_terminal.py

@@ -171,6 +171,49 @@ def append_menu_key_debug_log(path: Path, line: str) -> None:
         pass
 
 
+def _windows_menu_key(
+    character: str,
+    *,
+    getwch: Callable[[], str],
+    kbhit: Callable[[], bool],
+) -> str:
+    """Decode both Win32 extended keys and ConPTY VT input sequences."""
+
+    if character in ("\x00", "\xe0"):
+        code = getwch()
+        return {"H": "up", "P": "down", "K": "left", "M": "right"}.get(code, "")
+    if character in ("\r", "\n"):
+        return "enter"
+    if character != "\x1b":
+        return character.lower()
+    # SSH/web terminals connected through Windows ConPTY can deliver arrows as
+    # ESC [ A instead of Win32's two-character extended-key representation.
+    time.sleep(0.01)
+    if not kbhit():
+        return "esc"
+    sequence = ""
+    while kbhit() and len(sequence) < 8:
+        sequence += getwch()
+        if sequence[-1:] in {"A", "B", "C", "D", "H", "F", "~"}:
+            break
+    return {
+        "[A": "up",
+        "[B": "down",
+        "[C": "right",
+        "[D": "left",
+        "[H": "home",
+        "[F": "end",
+        "[1~": "home",
+        "[4~": "end",
+        "[5~": "pageup",
+        "[6~": "pagedown",
+        "OA": "up",
+        "OB": "down",
+        "OC": "right",
+        "OD": "left",
+    }.get(sequence, "esc")
+
+
 def read_menu_key(
     fd: int | None = None,
     *,
@@ -179,15 +222,9 @@ def read_menu_key(
     if os.name == "nt":
         import msvcrt
 
-        character = msvcrt.getwch()
-        if character in ("\x00", "\xe0"):
-            code = msvcrt.getwch()
-            return {"H": "up", "P": "down", "K": "left", "M": "right"}.get(code, "")
-        if character in ("\r", "\n"):
-            return "enter"
-        if character == "\x1b":
-            return "esc"
-        return character.lower()
+        return _windows_menu_key(
+            msvcrt.getwch(), getwch=msvcrt.getwch, kbhit=msvcrt.kbhit
+        )
     descriptor = sys.stdin.fileno() if fd is None or fd < 0 else fd
     character = os.read(descriptor, 1)
     log = f"{time.time():.3f} first={character!r}"

package/ciel_runtime_support/providers/zai.py

@@ -289,6 +289,18 @@ class ZaiStartPlanProviderAdapter(ZaiCodingPlanProviderAdapter):
     name: str = "zai-start-plan"
     base_url: str = PROVIDER_DEFAULT_BASE_URLS["zai-start-plan"]
     include_x_api_key: bool = False
+    capabilities_value: ProviderCapabilities = field(
+        default_factory=lambda: ProviderCapabilities(
+            upstream_protocol="anthropic_messages",
+            supports_thinking=True,
+            requires_api_key=True,
+        )
+    )
+    request_policy_value: ProviderRequestPolicy = field(
+        default_factory=lambda: ProviderRequestPolicy(
+            chat_path="/v1/messages", models_path="/v1/models"
+        )
+    )
     configuration_defaults_value: dict = field(
         default_factory=lambda: {
             **ZaiProviderAdapter().configuration_defaults_value,
@@ -306,6 +318,21 @@ class ZaiStartPlanProviderAdapter(ZaiCodingPlanProviderAdapter):
         del config
         return "https://zcode.z.ai/api/v1/zcode-plan/anthropic"
 
+    def supported_protocols(
+        self, config: ProviderConfig, model: str | None = None
+    ) -> frozenset[MessageProtocol]:
+        del config, model
+        return frozenset({"anthropic_messages"})
+
+    def select_protocol(
+        self,
+        operation: MessageProtocol,
+        config: ProviderConfig,
+        model: str | None = None,
+    ) -> MessageProtocol:
+        del operation, config, model
+        return "anthropic_messages"
+
     def build_headers(
         self, config: ProviderConfig, api_key: str | None
     ) -> Mapping[str, str]:
@@ -330,12 +357,7 @@ class ZaiStartPlanProviderAdapter(ZaiCodingPlanProviderAdapter):
     def launch_api_key_error(self, config: ProviderConfig) -> str | None:
         if not config.api_keys:
             return self.api_key_launch_error_value
-        return (
-            "Launch blocked: Z.AI Start Plan requires a fresh Aliyun CAPTCHA "
-            "runtime header before each model request. The installed ZCode "
-            "runtime provides that private interactive flow; Ciel Runtime does "
-            "not bypass or fabricate it for routed clients."
-        )
+        return None
 
 
 __all__ = [

package/ciel_runtime_support/runtime_constants.py

@@ -87,7 +87,7 @@ OPENCODE_ENDPOINT_ALIASES = {
 }
 
 APP_NAME = "Ciel Runtime"
-VERSION = "0.2.29"
+VERSION = "0.2.30"
 CREDITS = "Credits: One Ciel LLC"
 PRELAUNCH_CANCEL = 10
 PRELAUNCH_LAUNCH_CODEX = 11

package/ciel_runtime_support/upstream_retry.py

@@ -124,6 +124,7 @@ class UpstreamRetryKeys:
     provider_api_key_count: Callable[..., Any]
     provider_has_live_api_key: Callable[..., Any]
     provider_headers: Callable[..., Any]
+    prepare_runtime_headers: Callable[..., dict[str, str]]
     register_api_key_cooldown: Callable[..., Any]
 
 
@@ -180,6 +181,7 @@ def post_json_with_rate_retry(
     provider_api_key_count = keys.provider_api_key_count
     provider_has_live_api_key = keys.provider_has_live_api_key
     provider_headers = keys.provider_headers
+    prepare_runtime_headers = keys.prepare_runtime_headers
     register_api_key_cooldown = keys.register_api_key_cooldown
     learn_router_rate_limit_headers = rate_limit.learn_headers
     register_router_rate_limit_backoff = rate_limit.register_backoff
@@ -194,6 +196,7 @@ def post_json_with_rate_retry(
     byte_estimate = len(json.dumps(req_body, ensure_ascii=False).encode("utf-8"))
     for attempt in range(rate_limit_max_attempts):
         try:
+            headers = prepare_runtime_headers(provider, pcfg, headers)
             write_router_activity(
                 "request",
                 provider,
@@ -318,6 +321,7 @@ def open_provider_request_with_key_retry(
     provider_api_key_count = keys.provider_api_key_count
     provider_has_live_api_key = keys.provider_has_live_api_key
     provider_headers = keys.provider_headers
+    prepare_runtime_headers = keys.prepare_runtime_headers
     register_api_key_cooldown = keys.register_api_key_cooldown
     learn_router_rate_limit_headers = rate_limit.learn_headers
     register_router_rate_limit_backoff = rate_limit.register_backoff
@@ -334,6 +338,7 @@ def open_provider_request_with_key_retry(
     data_bytes = json.dumps(req_body).encode("utf-8")
     for attempt in range(rate_limit_max_attempts):
         try:
+            headers = prepare_runtime_headers(provider, pcfg, headers)
             write_router_activity(
                 "request",
                 provider,
@@ -460,6 +465,7 @@ def open_openai_stream_with_rate_retry(
     provider_api_key_count = keys.provider_api_key_count
     provider_has_live_api_key = keys.provider_has_live_api_key
     provider_headers = keys.provider_headers
+    prepare_runtime_headers = keys.prepare_runtime_headers
     register_api_key_cooldown = keys.register_api_key_cooldown
     learn_router_rate_limit_headers = rate_limit.learn_headers
     register_router_rate_limit_backoff = rate_limit.register_backoff
@@ -477,6 +483,7 @@ def open_openai_stream_with_rate_retry(
     data_bytes = json.dumps(req_body).encode("utf-8")
     for attempt in range(rate_limit_max_attempts):
         try:
+            headers = prepare_runtime_headers(provider, pcfg, headers)
             write_router_activity(
                 "request",
                 provider,

package/ciel_runtime_support/upstream_retry_context.py

@@ -43,6 +43,7 @@ class UpstreamRetryCredentialPorts:
     api_key_count: Callable[..., int]
     has_live_api_key: Callable[..., bool]
     headers: Callable[..., dict[str, str]]
+    prepare_runtime_headers: Callable[..., dict[str, str]]
     register_cooldown: Callable[..., Any]
 
 
@@ -111,6 +112,7 @@ class UpstreamRetryContext:
                 provider_api_key_count=self.credentials.api_key_count,
                 provider_has_live_api_key=self.credentials.has_live_api_key,
                 provider_headers=self.credentials.headers,
+                prepare_runtime_headers=self.credentials.prepare_runtime_headers,
                 register_api_key_cooldown=self.credentials.register_cooldown,
             ),
             rate_limit=UpstreamRetryRateLimit(

package/ciel_runtime_support/zai_oauth.py

@@ -556,7 +556,7 @@ class ZaiOAuthRuntime:
         ]
         if profile == "start-plan":
             lines.append(
-                "Start Plan routed launch remains blocked because ZCode requires a fresh interactive CAPTCHA runtime header for model requests."
+                "Start Plan model requests will open the official Aliyun CAPTCHA verification page when a fresh runtime header is required."
             )
         return lines
 

package/ciel_runtime_support/zai_start_plan_captcha.py

@@ -0,0 +1,409 @@
+"""Interactive Aliyun CAPTCHA headers for the Z.AI Start Plan gateway.
+
+ZCode's Start Plan gateway consumes a fresh Aliyun CAPTCHA verification value
+for each model request.  This module hosts the official browser SDK on a
+loopback-only page, receives one state-bound result, and returns only the two
+request-scoped headers used by the gateway.
+"""
+
+from __future__ import annotations
+
+import hmac
+import html
+import json
+import os
+import platform
+import secrets
+import threading
+import urllib.parse
+import urllib.request
+import webbrowser
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable, Mapping
+
+
+ZCODE_CLIENT_CONFIG_URL = "https://zcode.z.ai/api/v1/client/configs"
+ALIYUN_CAPTCHA_SDK_URL = (
+    "https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js"
+)
+CAPTCHA_PARAM_HEADER = "X-Aliyun-Captcha-Verify-Param"
+CAPTCHA_REGION_HEADER = "X-Aliyun-Captcha-Verify-Region"
+_CAPTCHA_PATH = "/zai-start-plan-captcha"
+_CAPTCHA_RESULT_PATH = f"{_CAPTCHA_PATH}/result"
+_MAX_RESULT_BYTES = 64 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class ZaiStartPlanCaptchaConfig:
+    enabled: bool
+    region: str
+    prefix: str
+    scene_id: str
+
+    @classmethod
+    def from_envelope(cls, envelope: Any) -> "ZaiStartPlanCaptchaConfig":
+        if not isinstance(envelope, Mapping):
+            raise RuntimeError("ZCode client config returned an invalid envelope.")
+        if envelope.get("code") not in {None, 0, "0"}:
+            raise RuntimeError(
+                f"ZCode client config request failed (code {envelope.get('code')})."
+            )
+        data = envelope.get("data")
+        configs = data.get("configs") if isinstance(data, Mapping) else None
+        captcha = configs.get("captcha") if isinstance(configs, Mapping) else None
+        if not isinstance(captcha, Mapping):
+            raise RuntimeError("ZCode client config did not include CAPTCHA settings.")
+        config = cls(
+            enabled=captcha.get("enabled") is not False,
+            region=str(captcha.get("region") or "").strip(),
+            prefix=str(captcha.get("prefix") or "").strip(),
+            scene_id=str(captcha.get("sceneId") or "").strip(),
+        )
+        if not config.enabled:
+            raise RuntimeError("ZCode Start Plan CAPTCHA is disabled by server config.")
+        if not config.region or not config.prefix or not config.scene_id:
+            raise RuntimeError("ZCode client config returned incomplete CAPTCHA settings.")
+        return config
+
+
+class _LoopbackCaptchaServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = False
+
+
+@dataclass(slots=True)
+class _CaptchaResultReceiver:
+    config: ZaiStartPlanCaptchaConfig
+    state: str
+    timeout_seconds: float
+    host: str = "127.0.0.1"
+    port: int = 0
+    _server: _LoopbackCaptchaServer | None = field(default=None, init=False)
+    _thread: threading.Thread | None = field(default=None, init=False)
+    _ready: threading.Event = field(default_factory=threading.Event, init=False)
+    _result: str = field(default="", init=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+
+    @property
+    def url(self) -> str:
+        if self._server is None:
+            raise RuntimeError("Z.AI CAPTCHA receiver was not started.")
+        query = urllib.parse.urlencode({"state": self.state})
+        return f"http://localhost:{self._server.server_port}{_CAPTCHA_PATH}?{query}"
+
+    def __enter__(self) -> "_CaptchaResultReceiver":
+        receiver = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:  # noqa: N802
+                receiver._handle_get(self)
+
+            def do_POST(self) -> None:  # noqa: N802
+                receiver._handle_post(self)
+
+            def log_message(self, _format: str, *_args: object) -> None:
+                return
+
+        self._server = _LoopbackCaptchaServer((self.host, self.port), Handler)
+        self._thread = threading.Thread(
+            target=self._server.serve_forever,
+            kwargs={"poll_interval": 0.05},
+            name="ciel-zai-start-plan-captcha",
+            daemon=True,
+        )
+        self._thread.start()
+        return self
+
+    def __exit__(self, _exc_type: object, _exc: object, _traceback: object) -> None:
+        server, thread = self._server, self._thread
+        if server is not None:
+            server.shutdown()
+            server.server_close()
+        if thread is not None:
+            thread.join(timeout=2.0)
+        self._server = None
+        self._thread = None
+
+    def wait(self) -> str:
+        if not self._ready.wait(max(0.0, self.timeout_seconds)):
+            raise RuntimeError(
+                "Z.AI Start Plan CAPTCHA timed out after "
+                f"{int(self.timeout_seconds)} seconds."
+            )
+        with self._lock:
+            result = self._result
+        if not result:
+            raise RuntimeError("Z.AI Start Plan CAPTCHA returned an empty result.")
+        return result
+
+    def _valid_state(self, query: str) -> bool:
+        values = urllib.parse.parse_qs(query, keep_blank_values=True)
+        supplied = str((values.get("state") or [""])[0])
+        return bool(supplied) and hmac.compare_digest(supplied, self.state)
+
+    def _handle_get(self, handler: BaseHTTPRequestHandler) -> None:
+        parsed = urllib.parse.urlsplit(handler.path)
+        if parsed.path != _CAPTCHA_PATH:
+            self._respond(handler, 404, b"Not found", "text/plain; charset=utf-8")
+            return
+        if not self._valid_state(parsed.query):
+            self._respond(handler, 403, b"Invalid CAPTCHA state", "text/plain; charset=utf-8")
+            return
+        body = self._page().encode("utf-8")
+        self._respond(handler, 200, body, "text/html; charset=utf-8")
+
+    def _handle_post(self, handler: BaseHTTPRequestHandler) -> None:
+        parsed = urllib.parse.urlsplit(handler.path)
+        if parsed.path != _CAPTCHA_RESULT_PATH:
+            self._respond(handler, 404, b"Not found", "text/plain; charset=utf-8")
+            return
+        if not self._valid_state(parsed.query):
+            self._respond(handler, 403, b"Invalid CAPTCHA state", "text/plain; charset=utf-8")
+            return
+        try:
+            length = int(handler.headers.get("Content-Length") or "0")
+        except ValueError:
+            length = 0
+        if length <= 0 or length > _MAX_RESULT_BYTES:
+            self._respond(handler, 413, b"Invalid result size", "text/plain; charset=utf-8")
+            return
+        value = handler.rfile.read(length).decode("utf-8", errors="strict").strip()
+        if not value:
+            self._respond(handler, 400, b"Empty result", "text/plain; charset=utf-8")
+            return
+        with self._lock:
+            if self._result:
+                self._respond(handler, 409, b"Result already received", "text/plain; charset=utf-8")
+                return
+            self._result = value
+        self._respond(handler, 204, b"", "text/plain; charset=utf-8")
+        self._ready.set()
+
+    @staticmethod
+    def _respond(
+        handler: BaseHTTPRequestHandler,
+        status: int,
+        body: bytes,
+        content_type: str,
+    ) -> None:
+        handler.send_response(status)
+        handler.send_header("Content-Type", content_type)
+        handler.send_header("Content-Length", str(len(body)))
+        handler.send_header("Cache-Control", "no-store")
+        handler.send_header("Connection", "close")
+        handler.end_headers()
+        handler.close_connection = True
+        if body:
+            try:
+                handler.wfile.write(body)
+            except (BrokenPipeError, ConnectionResetError):
+                pass
+
+    def _page(self) -> str:
+        config_json = json.dumps(
+            {
+                "region": self.config.region,
+                "prefix": self.config.prefix,
+                "sceneId": self.config.scene_id,
+                "state": self.state,
+                "resultPath": _CAPTCHA_RESULT_PATH,
+            },
+            ensure_ascii=True,
+        ).replace("<", "\\u003c")
+        sdk_url = html.escape(ALIYUN_CAPTCHA_SDK_URL, quote=True)
+        return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Ciel Runtime · Z.AI Start Plan verification</title>
+<style>
+body{{font:16px system-ui,sans-serif;max-width:680px;margin:48px auto;padding:0 24px;color:#17202a}}
+#captcha-element{{min-height:1px}} button{{font:inherit;padding:10px 16px}}
+#status{{white-space:pre-wrap}} .muted{{color:#5f6b76}}
+</style></head><body>
+<h1>Z.AI Start Plan verification</h1>
+<p id="status">Preparing the official Aliyun CAPTCHA…</p>
+<p class="muted">This page sends the one-time verification result only to the local Ciel Runtime process.</p>
+<div id="captcha-element"></div><button id="captcha-button" type="button">Verify</button>
+<script>const CIEL_CAPTCHA={config_json};</script>
+<script src="{sdk_url}"></script>
+<script>
+(() => {{
+  const status = document.getElementById('status');
+  const button = document.getElementById('captcha-button');
+  let instance = null;
+  let interactiveShown = false;
+  const setStatus = value => {{ status.textContent = value; }};
+  const extractParam = value => value && typeof value === 'object'
+    ? String(value.captchaVerifyParam || value.CaptchaVerifyParam || '').trim() : '';
+  const submit = async value => {{
+    const param = String(value || '').trim();
+    if (!param) throw new Error('CAPTCHA returned an empty verification result.');
+    const query = new URLSearchParams({{state: CIEL_CAPTCHA.state}});
+    const response = await fetch(`${{CIEL_CAPTCHA.resultPath}}?${{query}}`, {{
+      method: 'POST', headers: {{'Content-Type': 'text/plain;charset=UTF-8'}}, body: param
+    }});
+    if (!response.ok) throw new Error(`Ciel Runtime rejected the result (${{response.status}}).`);
+    setStatus('Verification complete. Returning to Ciel Runtime…');
+    button.hidden = true;
+    window.setTimeout(() => window.close(), 700);
+  }};
+  const showInteractive = () => {{
+    interactiveShown = true;
+    setStatus('Complete the verification challenge to continue the model request.');
+    if (instance && typeof instance.show === 'function') instance.show(); else button.click();
+  }};
+  button.addEventListener('click', () => {{
+    if (instance && typeof instance.show === 'function') instance.show();
+  }});
+  window.AliyunCaptchaConfig = {{region: CIEL_CAPTCHA.region, prefix: CIEL_CAPTCHA.prefix}};
+  if (typeof window.initAliyunCaptcha !== 'function') {{
+    setStatus('The official Aliyun CAPTCHA SDK could not be loaded.');
+    return;
+  }}
+  window.initAliyunCaptcha({{
+    SceneId: CIEL_CAPTCHA.sceneId, mode: 'popup', language: 'en', showErrorTip: false,
+    element: '#captcha-element', button: '#captcha-button',
+    getInstance: value => {{
+      instance = value;
+      window.setTimeout(() => {{
+        setStatus('Running security verification…');
+        if (typeof value.startTracelessVerification === 'function') value.startTracelessVerification();
+        else showInteractive();
+      }}, 2000);
+    }},
+    success: value => submit(value).catch(error => setStatus(error.message)),
+    fail: value => {{
+      const param = extractParam(value);
+      if (param) {{ submit(param).catch(error => setStatus(error.message)); return; }}
+      if (!interactiveShown) showInteractive();
+      else setStatus('Verification was not accepted. Select Verify to try again.');
+    }},
+    onError: error => setStatus(`Verification error: ${{error && error.message ? error.message : String(error)}}`)
+  }});
+}})();
+</script></body></html>"""
+
+
+@dataclass(slots=True)
+class ZaiStartPlanCaptchaBroker:
+    """Acquire one official Aliyun CAPTCHA result for each upstream attempt."""
+
+    open_url: Callable[[str], bool] = webbrowser.open
+    urlopen: Callable[..., Any] = urllib.request.urlopen
+    random_state: Callable[[], str] = lambda: secrets.token_urlsafe(32)
+    receiver_factory: Callable[..., Any] = _CaptchaResultReceiver
+    log: Callable[[str, str], None] = lambda _level, _message: None
+    _request_lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+
+    def fetch_config(self, app_version: str) -> ZaiStartPlanCaptchaConfig:
+        query = urllib.parse.urlencode(
+            {
+                "app_version": app_version,
+                "platform": self._platform_key(),
+            }
+        )
+        request = urllib.request.Request(
+            f"{ZCODE_CLIENT_CONFIG_URL}?{query}",
+            headers={"Accept": "application/json", "User-Agent": f"ZCode/{app_version}"},
+        )
+        with self.urlopen(request, timeout=15.0) as response:
+            envelope = json.loads(response.read().decode("utf-8"))
+        return ZaiStartPlanCaptchaConfig.from_envelope(envelope)
+
+    def headers(self, options: Mapping[str, Any]) -> dict[str, str]:
+        app_version = str(options.get("zcode_app_version") or "3.8.1").strip()
+        timeout = self._timeout(options)
+        with self._request_lock:
+            config = self.fetch_config(app_version)
+            state = self.random_state()
+            with self.receiver_factory(config, state, timeout) as receiver:
+                url = receiver.url
+                self.log("INFO", f"zai_start_plan_captcha_waiting url={url}")
+                if not self.open_url(url):
+                    raise RuntimeError(
+                        "Could not open the Z.AI Start Plan verification page: " + url
+                    )
+                result = receiver.wait()
+        self.log(
+            "INFO",
+            "zai_start_plan_captcha_completed "
+            f"region={config.region} result_length={len(result)}",
+        )
+        return {
+            CAPTCHA_PARAM_HEADER: result,
+            CAPTCHA_REGION_HEADER: config.region,
+        }
+
+    @staticmethod
+    def _timeout(options: Mapping[str, Any]) -> float:
+        raw = options.get("zai_captcha_timeout_seconds") or os.environ.get(
+            "CIEL_RUNTIME_ZAI_CAPTCHA_TIMEOUT_SECONDS", "120"
+        )
+        try:
+            return max(15.0, min(600.0, float(raw)))
+        except (TypeError, ValueError):
+            return 120.0
+
+    @staticmethod
+    def _platform_key() -> str:
+        system = {"Windows": "win32", "Darwin": "darwin", "Linux": "linux"}.get(
+            platform.system(), platform.system().lower()
+        )
+        machine = platform.machine().lower()
+        arch = "arm64" if machine in {"arm64", "aarch64"} else "x64"
+        return f"{system}-{arch}"
+
+
+@dataclass(slots=True)
+class ZaiStartPlanRuntimeHeaderPreparer:
+    """Reusable upstream callback backed by one serialized CAPTCHA broker."""
+
+    log: Callable[[str, str], None] = lambda _level, _message: None
+    broker: ZaiStartPlanCaptchaBroker = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.broker = ZaiStartPlanCaptchaBroker(log=self.log)
+
+    def __call__(
+        self,
+        provider: str,
+        config: Mapping[str, Any],
+        headers: Mapping[str, str],
+    ) -> dict[str, str]:
+        return apply_zai_start_plan_runtime_headers(
+            provider, config, headers, broker=self.broker
+        )
+
+
+def apply_zai_start_plan_runtime_headers(
+    provider: str,
+    config: Mapping[str, Any],
+    headers: Mapping[str, str],
+    *,
+    broker: ZaiStartPlanCaptchaBroker,
+) -> dict[str, str]:
+    """Refresh request-scoped CAPTCHA headers without altering other providers."""
+
+    projected = {
+        name: value
+        for name, value in headers.items()
+        if name.casefold()
+        not in {CAPTCHA_PARAM_HEADER.casefold(), CAPTCHA_REGION_HEADER.casefold()}
+    }
+    if str(provider or "").casefold() != "zai-start-plan":
+        return projected
+    projected.update(broker.headers(config))
+    return projected
+
+
+__all__ = [
+    "ALIYUN_CAPTCHA_SDK_URL",
+    "CAPTCHA_PARAM_HEADER",
+    "CAPTCHA_REGION_HEADER",
+    "ZCODE_CLIENT_CONFIG_URL",
+    "ZaiStartPlanCaptchaBroker",
+    "ZaiStartPlanCaptchaConfig",
+    "ZaiStartPlanRuntimeHeaderPreparer",
+    "apply_zai_start_plan_runtime_headers",
+]

package/docs/journal/2026/08/24/zai-start-plan-codex-captcha-runtime.okf

@@ -0,0 +1,84 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: zai-start-plan-codex-captcha-runtime-20260824
+    date: "2026-08-24"
+    objective: >-
+      Make Z.AI Start Plan launchable through routed Codex while preserving the
+      provider's official per-request Aliyun CAPTCHA flow, and restore Windows
+      menu arrow input for both native console and ConPTY/SSH terminals.
+    status: validation-in-progress
+
+  evidence:
+    installed_zcode:
+      version: 3.8.1
+      sdk_url: https://o.alicdn.com/captcha-frontend/aliyunCaptcha/AliyunCaptcha.js
+      request_headers:
+        - X-Aliyun-Captcha-Verify-Param
+        - X-Aliyun-Captcha-Verify-Region
+      refresh_scope: every model request
+    official_client_config:
+      url: https://zcode.z.ai/api/v1/client/configs
+      observed_platform: win32-x64
+      captcha_enabled: true
+      region: sgp
+      prefix: no8xfe
+      scene_id: 11xygtvd
+    live_endpoint_probe:
+      openai_paths:
+        /responses: 404
+        /v1/responses: 404
+        /chat/completions: 404
+        /v1/chat/completions: 404
+      anthropic_path: /api/v1/zcode-plan/anthropic/v1/messages
+      anthropic_invalid_jwt_status_after_captcha: 401
+    browser_runtime:
+      loopback_host: 127.0.0.1
+      official_sdk_loaded: true
+      traceless_verification_completed: true
+      result_length: 280
+      screenshot_captured: true
+    remote_credential_audit:
+      host: mia@100.95.132.58
+      current_provider: zai-start-plan
+      persisted_start_plan_secret_count: 0
+
+  implementation:
+    captcha:
+      receiver: state-bound loopback-only HTTP server
+      persistence: none
+      maximum_result_bytes: 65536
+      timeout_range_seconds: 15-600
+      concurrency: serialized
+      retry_behavior: fresh verification for each upstream attempt
+      provider_scope: zai-start-plan only
+      codex_protocol: anthropic_messages
+    terminal_input:
+      native_win32_arrows: supported
+      conpty_vt_arrows: supported
+      standalone_escape: preserved
+
+  validation:
+    targeted:
+      architecture_budget: passed
+      main_module_line_count: 4980
+      captcha_tests: 4_passed
+      terminal_primitive_tests: 7_passed
+      ruff_changed_files: passed
+    full_suite:
+      unit:
+        passed: 1177
+        skipped: 44
+      router:
+        passed: 951
+      channel:
+        passed: 381
+        skipped: 80
+      runtime:
+        passed: 255
+        skipped: 12
+    authenticated_model_request:
+      status: blocked
+      reason: no Start Plan OAuth secret exists in either inspected workspace
+    release:
+      status: pending

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.29",
+  "version": "0.2.30",
   "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, ZCode, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",