@oneciel-ai/ciel-runtime 0.2.25 → 0.2.26

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.26 — 2026-08-24
+
+- Added ZCode as a first-class launch client in the interactive menu,
+  `ciel-runtime zcode`, `ciel-runtimectl launch-zcode`, and `--ca-runtime zcode`.
+- Routes ZCode through the selected Ciel provider with a workspace-isolated
+  ZCode home and custom Anthropic-provider configuration, without overwriting
+  the user's normal ZCode configuration.
+- Shares Z.AI OAuth Coding Plan credentials across ZCode, Claude, Codex, AGY,
+  and other routed clients; ZCode TUI OAuth results are imported after exit.
+- Added Z.AI OAuth login/status/logout actions to the provider API-key panel.
+- Restores Windows bracketed-paste mode on runtime exit to prevent literal
+  `ESC[200~` / `ESC[201~` markers from leaking into the parent prompt.
+
 ## 0.2.25 — 2026-08-23
 
 - Added the ZCode wrapper's authorization-code contract as a cross-platform manual

package/README.md

@@ -5,7 +5,7 @@
 **Run the coding agent you want on the model provider you choose.**
 
 Ciel Runtime is a cross-platform launcher, local protocol router, and workspace
-control plane for Claude Code, Codex, Codex App Server, AGY, Grok Build, and
+control plane for Claude Code, Codex, Codex App Server, AGY, Grok Build, ZCode, and
 compatible AI coding-agent CLIs.
 
 [![npm](https://img.shields.io/npm/v/@oneciel-ai/ciel-runtime?label=npm)](https://www.npmjs.com/package/@oneciel-ai/ciel-runtime)
@@ -76,6 +76,7 @@ Launch another runtime while preserving its remaining CLI arguments:
 ciel-runtime codex
 ciel-runtime agy
 ciel-runtime grok
+ciel-runtime zcode
 ciel-runtime --ca-runtime codex-app-server
 ```
 
@@ -91,7 +92,7 @@ ciel-runtimectl test
 
 | Capability | What it provides |
 |---|---|
-| Runtime launch | Claude Code, Codex, Codex App Server, AGY, and Grok Build from one entrypoint |
+| Runtime launch | Claude Code, Codex, Codex App Server, AGY, Grok Build, and ZCode from one entrypoint |
 | Provider routing | Native connections where supported; otherwise a loopback HTTP router with provider-owned endpoint and authentication rules |
 | Protocol adaptation | Anthropic Messages, OpenAI Chat, OpenAI Responses, Ollama Chat, tool calls, thinking blocks, and SSE streams |
 | Model control | Provider catalogs, context/output limits, reasoning effort, sampling options, API-key rotation, and rate-limit handling |

package/ciel_runtime.py

@@ -23,6 +23,7 @@ from ciel_runtime_support import channel_cursor_repository as channel_cursor_sto
 from ciel_runtime_support import channel_llm_context, claude_launch_assembly, cli_assembly, cli_dispatch, cli_parser, codex_launch_configuration, codex_turn_recovery, kimi_identity, llm_option_config, llm_presets, native_context_recovery
 from ciel_runtime_support import ollama_catalog as ollama_catalog_policy
 from ciel_runtime_support import prelaunch, prelaunch_assembly, provider_catalog_sources, provider_models, provider_network, rate_limit_policy, router_request_assembly, router_server_runtime, runtime_asset_assembly, runtime_launch, runtime_primitives, terminal_platform_io, windows_console_mode
+from ciel_runtime_support.prelaunch_launch_panel import launch_panel_rows as project_launch_panel_rows
 from ciel_runtime_support.advisor_client import AdvisorClient, AdvisorClientIO, AdvisorClientPolicy, ProviderChatExecutor, ProviderChatIO, ProviderChatPolicy
 from ciel_runtime_support.advisor_policy import AdvisorDecisionServices, AdvisorServices, AdvisorShortcutController, AdvisorShortcutPorts, AdvisorTextServices
 from ciel_runtime_support.advisor_policy import advisor_focus_for_message as project_advisor_focus
@@ -172,6 +173,7 @@ from ciel_runtime_support.zai_oauth import ZaiOAuthClient, ZaiOAuthHttp, ZaiOAut
 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
+from ciel_runtime_support.zcode_runtime_context import ZcodeConfigurationPorts, ZcodeLifecyclePorts, ZcodeProcessPorts, ZcodeRuntimeCompatibilityApi, ZcodeRuntimeContext
 from ciel_runtime_support.launch_diagnostics import LaunchCommandDiagnostics, StderrCaptureAdapter
 from ciel_runtime_support.launch_state import LaunchStateRepository
 from ciel_runtime_support.launch_state import current_launch_cwd_key as project_current_launch_cwd_key
@@ -4006,6 +4008,21 @@ run_kimi_oauth_login = _KIMI_RUNTIME_API.oauth_login
 run_kimi_oauth_action = _KIMI_RUNTIME_API.oauth_action
 launch_kimi = _KIMI_RUNTIME_API.launch
 launch_kimi = SynchronizedLaunch(launch_kimi, sync_remote_launch_assets, "kimi")
+
+def zcode_runtime_context() -> ZcodeRuntimeContext:
+    return ZcodeRuntimeContext(
+        process=ZcodeProcessPorts(find_executable, subprocess.run, subprocess.call, print, os.environ, path_with_ciel_runtime_user_dirs),
+        config=ZcodeConfigurationPorts(load_config, get_current_provider, current_alias, claude_code_router_auth_token, ROUTER_BASE, ZAI_ANTHROPIC_BASE_URL,
+                                       WORKSPACE_STATE_DIR / "zcode-home" / ".zcode" / "cli" / "config.json",
+                                       lambda path, data, purpose: json_artifact_repository(path).save(data, purpose), lambda key: zai_oauth_runtime().import_api_key(key, source="zcode")),
+        lifecycle=ZcodeLifecyclePorts(run_zai_oauth_action, start_router_if_needed, run_with_router_lifetime, materialize_runtime_command,
+                                      lambda provider, model: record_launch_state_for_cwd(current_launch_cwd_key(), provider, "zcode-routed", model)),
+    )
+
+_ZCODE_RUNTIME_API = ZcodeRuntimeCompatibilityApi(zcode_runtime_context)
+def install_zcode_if_missing() -> str: return _ZCODE_RUNTIME_API.install_if_missing()
+def launch_zcode(passthrough: list[str] | None = None, **_kwargs: Any) -> int: return _ZCODE_RUNTIME_API.launch(list(passthrough or []))
+launch_zcode = SynchronizedLaunch(launch_zcode, sync_remote_launch_assets, "zcode")
 enable_ansi = enable_terminal_ansi
 ansi = render_ansi
 animated_ansi_text = render_animated_ansi_text
@@ -4064,25 +4081,7 @@ prompt_menu_value = _PRELAUNCH_SHELL_API.prompt_menu_value
 _prompt_menu_multiline_value_raw = _PRELAUNCH_SHELL_API.prompt_menu_multiline_value_raw
 prompt_menu_multiline_value = _PRELAUNCH_SHELL_API.prompt_menu_multiline_value
 
-def launch_panel_rows(cfg: dict[str, Any]) -> tuple[list[str], list[str]]:
-    provider, pcfg = get_current_provider(cfg)
-    family = provider_menu_label(provider, pcfg)
-    claude_suffix = "" if claude_launch_enabled_for_provider(provider) else f" [disabled: {family} provider selected]"
-    codex_suffix = "" if codex_launch_enabled_for_provider(provider) else f" [disabled: {family} provider selected]"
-    agy_suffix = "" if agy_launch_enabled_for_provider(provider) else " [disabled: select AGY provider]"
-    kimi_suffix = "" if provider == "kimi" else " [disabled: select Kimi provider]"
-    return (
-        [
-            f"Claude{claude_suffix}",
-            f"Codex{codex_suffix}",
-            f"AGY{agy_suffix}",
-            f"Kimi{kimi_suffix}",
-            "Grok Build",
-            f"Codex app server{codex_suffix}",
-            "Back",
-        ],
-        ["launch", "launch-codex", "launch-agy", "launch-kimi", "launch-grok", "launch-codex-app-server", "back"],
-    )
+def launch_panel_rows(cfg: dict[str, Any]) -> tuple[list[str], list[str]]: return project_launch_panel_rows(cfg, current_provider=get_current_provider, provider_label=provider_menu_label, claude_enabled=claude_launch_enabled_for_provider, codex_enabled=codex_launch_enabled_for_provider, agy_enabled=agy_launch_enabled_for_provider)
 
 def request_limits_menu_service() -> RequestLimitsMenuService:
     return RequestLimitsMenuService(load_config, save_config, ROUTER_WORKSPACE, os.environ)
@@ -4136,14 +4135,14 @@ def portable_prelaunch_menu(passthrough: list[str] | None = None) -> int:
             config=prelaunch.PrelaunchConfig(clear_model_cache, current_provider_panel_choice, default_base_url, get_current_provider, load_config, preflight_lines,
                                               provider_menu_label, save_config, settings_ready_except_api_key, read_model_list_cache),
             launch_policy=prelaunch.PrelaunchLaunchPolicy(agy_launch_enabled_for_provider, claude_launch_enabled_for_provider, codex_launch_enabled_for_provider,
-                                                          launch_blockers_require_api_key, launch_readiness_errors, launch_kimi, launch_grok),
+                                                          launch_blockers_require_api_key, launch_readiness_errors, launch_kimi, launch_grok, launch_zcode),
             panel_rows=prelaunch.PrelaunchPanelRows(advisor_model_panel_rows, api_key_panel_rows, base_url_panel_rows, context_setup_panel_rows, language_panel_rows,
                                                     llm_option_panel_rows, llm_preset_panel_rows, log_level_panel_rows, model_panel_rows, provider_panel_rows),
             mutations=prelaunch.PrelaunchMutations(apply_context_setup_config, apply_llm_preset_config, apply_timeout_profile_to_provider,
                                                     set_advisor_model_config, set_base_url_config, set_llm_option_config, set_log_level_config,
                                                     set_model_config, set_provider_choice_config, request_limits_menu_service()),
             secrets=prelaunch.PrelaunchSecrets(clear_api_key_config, mask_secret, parse_api_key_list, secret_fingerprint, store_api_key_input_config,
-                                                store_api_keys_config, run_copilot_oauth_action, run_kimi_oauth_action),
+                                                store_api_keys_config, run_copilot_oauth_action, run_kimi_oauth_action, run_zai_oauth_action),
             options=prelaunch.PrelaunchOptions(llm_option_current_bool, llm_option_prompt_default, timeout_profile_panel_rows, web_backend_panel_rows,
                                                set_web_backend_config, external_event_panel_rows, set_external_event_config,
                                                launch_panel_rows, remote_instruction_panel_rows, set_remote_instruction_config,
@@ -4939,7 +4938,7 @@ def cli_services() -> cli_dispatch.CliServices:
         core=cli_dispatch.CliCore(VERSION, cli_usage, find_executable, get_current_provider, load_config, pop_headless_env_file_args,
                                   portable_provider_menu, run_external_menu, run_quiet_upgrade_and_exit),
         runtime=cli_dispatch.CliRuntime(agy_passthrough_has_command, codex_passthrough_has_command, last_launch_runtime, launch_agy, launch_claude,
-                                        launch_codex, launch_codex_app_server, native_agy_enabled, native_codex_enabled, launch_grok),
+                                        launch_codex, launch_codex_app_server, native_agy_enabled, native_codex_enabled, launch_grok, launch_zcode),
         provider_commands=cli_dispatch.CliProviderCommands(cmd_advisor_model, cmd_api_key, cmd_base_url, cmd_language, cmd_log_level, cmd_model,
                                                            cmd_models, cmd_provider, cmd_provider_options, cmd_set_api_key),
         special_commands=cli_dispatch.CliSpecialCommands(cmd_ollama_catalog, cmd_ollama_native, cmd_ollama_options, cmd_web_fetch, cmd_web_search),
@@ -4949,7 +4948,7 @@ def cli_services() -> cli_dispatch.CliServices:
     ).services()
 def cli_parser_services() -> cli_parser.CliParserServices:
     return cli_assembly.CliParserAssembly(
-            launch=cli_parser.CliParserLaunch(cmd_cli, cmd_launch, cmd_launch_codex, cmd_launch_codex_app_server, cmd_launch_agy, serve, cmd_launch_grok),
+            launch=cli_parser.CliParserLaunch(cmd_cli, cmd_launch, cmd_launch_codex, cmd_launch_codex_app_server, cmd_launch_agy, serve, cmd_launch_grok, cmd_launch_zcode),
             runtime=cli_parser.CliParserRuntime(cmd_version, cmd_status, cmd_env, cmd_stop, cmd_test),
             settings=cli_parser.CliParserSettings(cmd_language, cmd_web_search, cmd_web_fetch, cmd_log_level, *event_settings_cli.handlers(event_settings_cli.EventSettingsCliPorts(load_config, save_config, external_event_receiver_service, lambda: set_remote_instruction_config('sync', ''), sync_all_remote_memories, print, lambda: USAGE_API_KEYS))),
             provider=cli_parser.CliParserProvider(cmd_ollama_native, cmd_ollama_options, cmd_provider_options, cmd_ollama_catalog, cmd_provider,
@@ -4960,7 +4959,7 @@ def cli_parser_services() -> cli_parser.CliParserServices:
 def cli_application_context() -> CliApplicationContext:
     return CliApplicationContext(
         dispatch=CliApplicationDispatchPorts(dispatch_cli, cli_services, launch_claude, launch_codex, launch_codex_app_server,
-                                             launch_agy, launch_kimi, run_kimi_oauth_login, launch_grok),
+                                             launch_agy, launch_kimi, run_kimi_oauth_login, launch_grok, launch_zcode),
         presentation=CliApplicationPresentationPorts(build_cli_parser, cli_parser_services, VERSION, print, lambda: sys.argv),
     )
 
@@ -4973,6 +4972,7 @@ cmd_launch_codex = _CLI_APPLICATION_API.cmd_launch_codex
 cmd_launch_codex_app_server = _CLI_APPLICATION_API.cmd_launch_codex_app_server
 cmd_launch_agy = _CLI_APPLICATION_API.cmd_launch_agy
 cmd_launch_grok = _CLI_APPLICATION_API.cmd_launch_grok
+cmd_launch_zcode = _CLI_APPLICATION_API.cmd_launch_zcode
 cmd_version = _CLI_APPLICATION_API.cmd_version
 main = _CLI_APPLICATION_API.main
 

package/ciel_runtime_support/cli_application_context.py

@@ -18,6 +18,7 @@ class CliApplicationDispatchPorts:
     launch_kimi: Callable[[list[str]], int]
     kimi_login: Callable[[], int]
     launch_grok: Callable[[list[str]], int] = lambda _argv: 127
+    launch_zcode: Callable[[list[str]], int] = lambda _argv: 127
 
 
 @dataclass(frozen=True, slots=True)
@@ -60,6 +61,9 @@ class CliApplicationContext:
     def cmd_launch_grok(self, args: argparse.Namespace) -> None:
         raise SystemExit(self.dispatch.launch_grok(args.argv))
 
+    def cmd_launch_zcode(self, args: argparse.Namespace) -> None:
+        raise SystemExit(self.dispatch.launch_zcode(args.argv))
+
     def cmd_version(self, _: argparse.Namespace) -> None:
         self.presentation.output(f"ciel-runtime {self.presentation.version}")
 
@@ -84,6 +88,8 @@ class CliApplicationContext:
             "grok": self.dispatch.launch_grok,
             "grok-build": self.dispatch.launch_grok,
             "launch-grok": self.dispatch.launch_grok,
+            "zcode": self.dispatch.launch_zcode,
+            "launch-zcode": self.dispatch.launch_zcode,
         }
         if len(arguments) >= 2 and arguments[1] in routes:
             raise SystemExit(routes[arguments[1]](arguments[2:]))
@@ -124,6 +130,9 @@ class CliApplicationCompatibilityApi:
     def cmd_launch_grok(self, args: argparse.Namespace) -> None:
         self.context().cmd_launch_grok(args)
 
+    def cmd_launch_zcode(self, args: argparse.Namespace) -> None:
+        self.context().cmd_launch_zcode(args)
+
     def cmd_version(self, args: argparse.Namespace) -> None:
         self.context().cmd_version(args)
 

package/ciel_runtime_support/cli_dispatch.py

@@ -34,6 +34,7 @@ class CliRuntime:
     native_agy_enabled: Any
     native_codex_enabled: Any
     launch_grok: Any = lambda *_args, **_kwargs: 127
+    launch_zcode: Any = lambda *_args, **_kwargs: 127
 
 
 @dataclass(frozen=True)
@@ -119,6 +120,7 @@ def dispatch_cli(argv: list[str], services: CliServices) -> int:
     launch_codex = services.runtime.launch_codex
     launch_codex_app_server = services.runtime.launch_codex_app_server
     launch_grok = services.runtime.launch_grok
+    launch_zcode = services.runtime.launch_zcode
     load_config = services.core.load_config
     native_agy_enabled = services.runtime.native_agy_enabled
     native_codex_enabled = services.runtime.native_codex_enabled
@@ -142,6 +144,8 @@ def dispatch_cli(argv: list[str], services: CliServices) -> int:
             return launch_codex(rest)
         if head in ("grok", "grok-build", "launch-grok"):
             return launch_grok(rest)
+        if head in ("zcode", "launch-zcode"):
+            return launch_zcode(rest)
         if head in ("version", "--version", "-v"):
             print(f"ciel-runtime {VERSION}")
             return 0
@@ -295,8 +299,8 @@ def dispatch_cli(argv: list[str], services: CliServices) -> int:
             runtime = str(value or "").strip().lower()
             if runtime in ("codex-app", "codex-appserver"):
                 runtime = "codex-app-server"
-            if runtime not in ("claude", "codex", "codex-app-server", "agy", "grok", "last"):
-                raise SystemExit("--ca-runtime must be claude, codex, codex-app-server, agy, grok, or last")
+            if runtime not in ("claude", "codex", "codex-app-server", "agy", "grok", "zcode", "last"):
+                raise SystemExit("--ca-runtime must be claude, codex, codex-app-server, agy, grok, zcode, or last")
         elif arg in ("--ca-no-launch", "--ca-configure-only", "--ca-setup-only"):
             configure_only = True
             skip_menu = True
@@ -667,7 +671,7 @@ def dispatch_cli(argv: list[str], services: CliServices) -> int:
         return 0
     if runtime == "last":
         remembered_runtime = str(last_launch_runtime() or "").strip().lower()
-        runtime = remembered_runtime if remembered_runtime in {"claude", "codex", "agy", "grok"} else "claude"
+        runtime = remembered_runtime if remembered_runtime in {"claude", "codex", "agy", "grok", "zcode"} else "claude"
     if runtime == "agy":
         return launch_agy(
             passthrough,
@@ -700,6 +704,14 @@ def dispatch_cli(argv: list[str], services: CliServices) -> int:
             update_check=update_check,
             self_update_check=self_update_check,
         )
+    if runtime == "zcode":
+        return launch_zcode(
+            passthrough,
+            skip_menu=skip_menu,
+            force_menu=force_menu,
+            update_check=update_check,
+            self_update_check=self_update_check,
+        )
     return launch_claude(
         passthrough,
         skip_menu=skip_menu,

package/ciel_runtime_support/cli_parser.py

@@ -16,6 +16,7 @@ class CliParserLaunch:
     launch_agy: CliHandler
     serve: CliHandler
     launch_grok: CliHandler = lambda _args: None
+    launch_zcode: CliHandler = lambda _args: None
 
 
 @dataclass(frozen=True)
@@ -84,6 +85,7 @@ def build_cli_parser(services: CliParserServices) -> argparse.ArgumentParser:
     )
     _add_remainder_command(commands, "launch-agy", services.launch.launch_agy)
     _add_remainder_command(commands, "launch-grok", services.launch.launch_grok)
+    _add_remainder_command(commands, "launch-zcode", services.launch.launch_zcode)
     commands.add_parser("serve").set_defaults(func=services.launch.serve)
     commands.add_parser("version").set_defaults(func=services.runtime.version)
     commands.add_parser("status").set_defaults(func=services.runtime.status)

package/ciel_runtime_support/cli_usage.py

@@ -7,6 +7,7 @@ def cli_usage_text() -> str:
   ciel-runtime codex-app-server [args...]  Launch Codex app-server through ciel-runtime
   ciel-runtime agy [args...]           Launch Google Antigravity CLI through ciel-runtime
   ciel-runtime grok [args...]          Launch the official Grok Build CLI
+  ciel-runtime zcode [args...]         Launch ZCode through ciel-runtime router
   ciel-runtime resume                  Resume Codex/AGY when that runtime provider is selected
 
 Control plane, runs before Claude Code and does not require LLM connectivity:
@@ -42,7 +43,7 @@ Headless setup flags, namespaced to avoid Claude CLI collisions:
                                       Publish localhost through Tailscale Serve HTTPS
   ciel-runtime --ca-provider PROVIDER  Set provider, then launch
   ciel-runtime --ca-env-file PATH      Load CIEL_RUNTIME_* values from a .env file
-  ciel-runtime --ca-runtime claude|codex|codex-app-server|agy|grok
+  ciel-runtime --ca-runtime claude|codex|codex-app-server|agy|grok|zcode
                                       Select Claude Code, Codex, Codex app-server, AGY, or Grok Build
   ciel-runtime --ca-menu               Apply setup values, then open the menu
   ciel-runtime --ca-language en|ko|ja|zh

package/ciel_runtime_support/prelaunch.py

@@ -81,6 +81,7 @@ class PrelaunchLaunchPolicy:
     launch_readiness_errors: Callable[..., Any]
     launch_kimi: Callable[..., Any]
     launch_grok: Callable[..., Any] = lambda *_args, **_kwargs: 0
+    launch_zcode: Callable[..., Any] = lambda *_args, **_kwargs: 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -135,6 +136,7 @@ class PrelaunchSecrets:
     store_api_keys_config: Callable[..., Any]
     copilot_oauth_action: Callable[..., Any]
     kimi_oauth_action: Callable[..., Any]
+    zai_oauth_action: Callable[..., Any] = lambda _action: []
 
 
 @dataclass(frozen=True, slots=True)
@@ -213,6 +215,7 @@ def run_prelaunch_menu(passthrough: list[str] | None = None,
     launch_readiness_errors = services.launch_policy.launch_readiness_errors
     launch_kimi = services.launch_policy.launch_kimi
     launch_grok = services.launch_policy.launch_grok
+    launch_zcode = services.launch_policy.launch_zcode
     llm_option_current_bool = services.options.llm_option_current_bool
     llm_option_panel_rows = services.panel_rows.llm_option_panel_rows
     llm_option_prompt_default = services.options.llm_option_prompt_default
@@ -247,6 +250,7 @@ def run_prelaunch_menu(passthrough: list[str] | None = None,
     store_api_keys_config = services.secrets.store_api_keys_config
     copilot_oauth_action = services.secrets.copilot_oauth_action
     kimi_oauth_action = services.secrets.kimi_oauth_action
+    zai_oauth_action = services.secrets.zai_oauth_action
     timeout_profile_panel_rows = services.options.timeout_profile_panel_rows
     web_backend_panel_rows = services.options.web_backend_panel_rows
     set_web_backend_config = services.options.set_web_backend_config
@@ -485,6 +489,10 @@ def run_prelaunch_menu(passthrough: list[str] | None = None,
                         persist_launch_action(action)
                         launch_grok([])
                         return PRELAUNCH_CANCEL
+                    if action == "launch-zcode":
+                        persist_launch_action(action)
+                        launch_zcode([])
+                        return PRELAUNCH_CANCEL
                     continue
                 if panel == "language" and value:
                     cfg["language"] = value
@@ -561,6 +569,15 @@ def run_prelaunch_menu(passthrough: list[str] | None = None,
                         provider, pcfg = get_current_provider(cfg)
                         panel_rows, panel_values = api_key_panel_rows(provider, pcfg)
                         panel_idx = 0
+                    elif value.startswith("zai-oauth-"):
+                        messages = zai_oauth_action(
+                            value.removeprefix("zai-oauth-")
+                        )
+                        refresh_checks()
+                        cfg = load_config()
+                        provider, pcfg = get_current_provider(cfg)
+                        panel_rows, panel_values = api_key_panel_rows(provider, pcfg)
+                        panel_idx = 0
                     elif value.startswith("oauth-"):
                         messages = copilot_oauth_action(
                             value.removeprefix("oauth-")

package/ciel_runtime_support/prelaunch_launch_panel.py

@@ -0,0 +1,38 @@
+"""Runtime launch chooser projection."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+def launch_panel_rows(
+    config: dict[str, Any],
+    *,
+    current_provider: Callable[..., tuple[str, dict[str, Any]]],
+    provider_label: Callable[..., str],
+    claude_enabled: Callable[[str], bool],
+    codex_enabled: Callable[[str], bool],
+    agy_enabled: Callable[[str], bool],
+) -> tuple[list[str], list[str]]:
+    provider, provider_config = current_provider(config)
+    family = provider_label(provider, provider_config)
+    claude_suffix = "" if claude_enabled(provider) else f" [disabled: {family} provider selected]"
+    codex_suffix = "" if codex_enabled(provider) else f" [disabled: {family} provider selected]"
+    agy_suffix = "" if agy_enabled(provider) else " [disabled: select AGY provider]"
+    kimi_suffix = "" if provider == "kimi" else " [disabled: select Kimi provider]"
+    return (
+        [
+            f"Claude{claude_suffix}",
+            f"Codex{codex_suffix}",
+            f"AGY{agy_suffix}",
+            f"Kimi{kimi_suffix}",
+            "Grok Build",
+            "ZCode",
+            f"Codex app server{codex_suffix}",
+            "Back",
+        ],
+        ["launch", "launch-codex", "launch-agy", "launch-kimi", "launch-grok", "launch-zcode", "launch-codex-app-server", "back"],
+    )
+
+
+__all__ = ["launch_panel_rows"]

package/ciel_runtime_support/prelaunch_launch_preference.py

@@ -15,6 +15,7 @@ REMEMBERED_LAUNCH_ACTIONS = frozenset(
         "launch-codex-app-server",
         "launch-kimi",
         "launch-grok",
+        "launch-zcode",
     }
 )
 
@@ -33,7 +34,7 @@ def preferred_launch_action(
         return remembered
     if remembered in {"launch-codex", "launch-codex-app-server"} and supports_codex(provider):
         return remembered
-    if remembered == "launch-grok":
+    if remembered in {"launch-grok", "launch-zcode"}:
         return remembered
     return fallback(provider)
 

package/ciel_runtime_support/prelaunch_panel_context.py

@@ -247,6 +247,32 @@ class PrelaunchPanelContext:
     def api_key_panel_rows(
         self, provider: str, provider_config: dict[str, Any] | None = None
     ) -> PanelRows:
+        if provider == "zai":
+            config = provider_config or {}
+            source = str(config.get("credential_source") or "").strip()
+            configured = bool(self.configuration.api_key_count(provider, config))
+            status = "connected" if configured and source == "zai-oauth" else (
+                "API key configured" if configured else "login required"
+            )
+            rows, values = self.configuration_panel_projection().api_key_rows(
+                provider, provider_config
+            )
+            return (
+                [
+                    f"Z.AI OAuth: {status}",
+                    "Login with Z.AI OAuth (shared by all runtimes)",
+                    "Refresh Z.AI OAuth status",
+                    "Logout shared Z.AI OAuth credential",
+                    *rows,
+                ],
+                [
+                    "__info__",
+                    "zai-oauth-login",
+                    "zai-oauth-status",
+                    "zai-oauth-logout",
+                    *values,
+                ],
+            )
         if provider == "kimi":
             status = (
                 "managed profile detected"

package/ciel_runtime_support/prelaunch_shell_context.py

@@ -151,8 +151,8 @@ class PrelaunchShellContext:
 
     def default_prelaunch_action(self, provider: str) -> str:
         config = self.provider.load_config()
-        if str(config.get("last_launch_action") or "").strip() == "launch-grok":
-            return "launch-grok"
+        if str(config.get("last_launch_action") or "").strip() in {"launch-grok", "launch-zcode"}:
+            return str(config.get("last_launch_action")).strip()
         if provider == "kimi":
             remembered = str(config.get("last_launch_action") or "").strip()
             if remembered in {"launch", "launch-kimi"}:
@@ -169,7 +169,7 @@ class PrelaunchShellContext:
         )
 
     def prelaunch_action_index(self, action: str) -> int:
-        if action in {"launch", "launch-codex", "launch-codex-app-server", "launch-agy", "launch-kimi", "launch-grok"}:
+        if action in {"launch", "launch-codex", "launch-codex-app-server", "launch-agy", "launch-kimi", "launch-grok", "launch-zcode"}:
             action = "launch-menu"
         try:
             return self.main_menu_actions.index(action)

package/ciel_runtime_support/remote_instructions.py

@@ -23,6 +23,8 @@ RUNTIME_FILES = {
     "kimi": "AGENTS.md",
     # Grok Build reads the AGENTS.md family, like Codex and Kimi.
     "grok": "AGENTS.md",
+    # ZCode discovers workspace instructions from AGENTS.md.
+    "zcode": "AGENTS.md",
 }
 URL_KEYS = {
     "claude": "claude_url",

package/ciel_runtime_support/runtime_adapters.py

@@ -107,11 +107,21 @@ class GrokRuntimeAdapter(CliRuntimeAdapter):
         return RuntimeCommand(argv=tuple(argv), env=dict(self.environment), cwd=spec.cwd)
 
 
+class ZcodeRuntimeAdapter(CliRuntimeAdapter):
+    """ZCode command materialization for a launch-scoped storage root."""
+
+    def build_command(self, spec: LaunchSpec) -> RuntimeCommand:
+        argv = [str(spec.runtime.executable or self.executable)]
+        argv.extend(spec.passthrough)
+        return RuntimeCommand(argv=tuple(argv), env=dict(self.environment), cwd=spec.cwd)
+
+
 RUNTIME_ADAPTERS: AdapterRegistry[RuntimeAdapter] = AdapterRegistry()
 RUNTIME_ADAPTERS.register("claude", lambda **kwargs: ClaudeRuntimeAdapter(name="claude", **kwargs))
 RUNTIME_ADAPTERS.register("codex", lambda **kwargs: CodexRuntimeAdapter(name="codex", **kwargs))
 RUNTIME_ADAPTERS.register("agy", lambda **kwargs: AgyRuntimeAdapter(name="agy", **kwargs))
 RUNTIME_ADAPTERS.register("grok", lambda **kwargs: GrokRuntimeAdapter(name="grok", **kwargs))
+RUNTIME_ADAPTERS.register("zcode", lambda **kwargs: ZcodeRuntimeAdapter(name="zcode", **kwargs))
 
 
 __all__ = [
@@ -121,4 +131,5 @@ __all__ = [
     "CliRuntimeAdapter",
     "CodexRuntimeAdapter",
     "GrokRuntimeAdapter",
+    "ZcodeRuntimeAdapter",
 ]

package/ciel_runtime_support/runtime_constants.py

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

package/ciel_runtime_support/terminal_platform_io.py

@@ -13,7 +13,7 @@ from typing import Any
 
 TERMINAL_INPUT_MODE_RESET = (
     "\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1004l"
-    "\x1b[?1005l\x1b[?1006l\x1b[?1015l"
+    "\x1b[?1005l\x1b[?1006l\x1b[?1015l\x1b[?2004l"
 )
 
 

package/ciel_runtime_support/zai_oauth.py

@@ -399,6 +399,30 @@ class ZaiOAuthRuntime:
             return ""
         return str(provider.get("api_key") or "").strip()
 
+    def import_api_key(self, api_key: str, *, source: str = "zcode") -> list[str]:
+        key = str(api_key or "").strip()
+        if not key:
+            return ["Z.AI OAuth import skipped: no Coding Plan API key was found."]
+        config = self.ports.load_config()
+        provider = config.setdefault("providers", {}).setdefault("zai", {})
+        if (
+            str(provider.get("api_key") or "").strip() == key
+            and provider.get("credential_source") == "zai-oauth"
+        ):
+            return ["Z.AI OAuth credential is already shared by all runtimes."]
+        provider["api_key"] = key
+        provider.pop("api_keys", None)
+        provider["credential_source"] = "zai-oauth"
+        provider["oauth_authenticated_at"] = datetime.now(timezone.utc).isoformat()
+        provider["oauth_import_source"] = str(source or "zcode")
+        config["current_provider"] = "zai"
+        self.ports.save_config(config)
+        self.ports.clear_model_cache()
+        return [
+            "Z.AI OAuth Coding Plan credential imported into Ciel Runtime for all clients.",
+            f"Credential: {self.ports.mask(key)}; fp {self.ports.fingerprint(key)}",
+        ]
+
     def action(self, action: str, *, no_browser: bool = False) -> list[str]:
         if action == "status":
             token = self.token()

package/ciel_runtime_support/zcode_runtime_context.py

@@ -0,0 +1,204 @@
+"""ZCode installation, shared Z.AI OAuth, and routed launch context."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+
+def zcode_settings(*, model: str, base_url: str, api_key: str) -> dict[str, Any]:
+    """Build the documented ZCode custom Anthropic-provider configuration."""
+
+    model_id = str(model or "model").strip() or "model"
+    return {
+        "provider": {
+            "zai": {
+                "kind": "anthropic",
+                "name": "Ciel Runtime",
+                "options": {
+                    "apiKey": str(api_key or "not-used"),
+                    "apiKeyRequired": True,
+                    "baseURL": str(base_url).rstrip("/"),
+                },
+                "headers": {},
+                "models": {model_id: {"name": model_id}},
+            }
+        },
+        "model": {"main": f"zai/{model_id}", "lite": f"zai/{model_id}"},
+    }
+
+
+@dataclass(frozen=True, slots=True)
+class ZcodeProcessPorts:
+    find_executable: Callable[[str], str | None]
+    run: Callable[..., Any]
+    call: Callable[..., int]
+    print_line: Callable[..., None]
+    environment: dict[str, str]
+    augment_path: Callable[[dict[str, str]], str]
+
+
+@dataclass(frozen=True, slots=True)
+class ZcodeConfigurationPorts:
+    load: Callable[[], dict[str, Any]]
+    current_provider: Callable[[dict[str, Any]], tuple[str, dict[str, Any]]]
+    current_alias: Callable[[dict[str, Any]], str]
+    router_auth_token: Callable[[str, dict[str, Any]], str]
+    router_base: str
+    zai_anthropic_base_url: str
+    settings_path: Path
+    save_json: Callable[[Path, dict[str, Any], str], None]
+    import_oauth_api_key: Callable[[str], list[str]]
+
+
+@dataclass(frozen=True, slots=True)
+class ZcodeLifecyclePorts:
+    oauth_action: Callable[..., list[str]]
+    start_router: Callable[[], Any]
+    run_with_router: Callable[[Callable[[], int], bool], int]
+    materialize_command: Callable[..., tuple[list[str], dict[str, str]]]
+    record_launch: Callable[[str, str], None]
+
+
+@dataclass(frozen=True, slots=True)
+class ZcodeRuntimeContext:
+    process: ZcodeProcessPorts
+    config: ZcodeConfigurationPorts
+    lifecycle: ZcodeLifecyclePorts
+
+    def install_if_missing(self) -> str:
+        executable = self.process.find_executable("zcode")
+        if executable:
+            return executable
+        npm = self.process.find_executable("npm")
+        if not npm:
+            raise RuntimeError(
+                "ZCode CLI is missing; install zcode-app-cli (Node.js 22.19+)."
+            )
+        self.process.print_line(
+            "Installing ZCode CLI (zcode-app-cli)...", flush=True
+        )
+        result = self.process.run(
+            [npm, "install", "-g", "zcode-app-cli"], check=False
+        )
+        if result.returncode:
+            raise RuntimeError(
+                f"ZCode CLI installation failed (exit {result.returncode})."
+            )
+        executable = self.process.find_executable("zcode")
+        if not executable:
+            raise RuntimeError(
+                "ZCode CLI installed but 'zcode' is not available on PATH."
+            )
+        return executable
+
+    @staticmethod
+    def _shared_oauth_action(argv: list[str]) -> str | None:
+        if not argv:
+            return None
+        if argv[0] == "login" and (len(argv) == 1 or "--oauth" in argv):
+            return "login"
+        if argv[0] == "logout":
+            return "logout"
+        return None
+
+    def _run_shared_oauth(self, action: str, argv: list[str]) -> int:
+        try:
+            lines = self.lifecycle.oauth_action(
+                action, no_browser="--no-browser" in argv
+            )
+        except RuntimeError as exc:
+            self.process.print_line(f"Z.AI OAuth failed: {exc}", flush=True)
+            return 1
+        for line in lines:
+            self.process.print_line(line, flush=True)
+        return 0
+
+    def write_settings(
+        self, config: dict[str, Any], provider: str, provider_config: dict[str, Any]
+    ) -> Path:
+        payload = zcode_settings(
+            model=self.config.current_alias(config),
+            base_url=self.config.router_base,
+            api_key=self.config.router_auth_token(provider, provider_config),
+        )
+        self.config.save_json(
+            self.config.settings_path, payload, "zcode routed settings"
+        )
+        return self.config.settings_path
+
+    def import_zcode_oauth_credential(self, settings_path: Path) -> list[str]:
+        try:
+            payload = json.loads(settings_path.read_text(encoding="utf-8"))
+            provider = payload.get("provider", {}).get("zai", {})
+            options = provider.get("options", {})
+            base_url = str(options.get("baseURL") or "").rstrip("/")
+            key = str(options.get("apiKey") or "").strip()
+        except (OSError, UnicodeError, json.JSONDecodeError, AttributeError):
+            return []
+        if base_url != self.config.zai_anthropic_base_url.rstrip("/") or not key:
+            return []
+        return self.config.import_oauth_api_key(key)
+
+    def launch(self, passthrough: list[str]) -> int:
+        argv = list(passthrough)
+        oauth_action = self._shared_oauth_action(argv)
+        if oauth_action:
+            return self._run_shared_oauth(oauth_action, argv)
+        executable = self.install_if_missing()
+        config = self.config.load()
+        provider, provider_config = self.config.current_provider(config)
+        settings_path = self.write_settings(config, provider, provider_config)
+        env = self.process.environment.copy()
+        env["PATH"] = self.process.augment_path(env)
+        launch_home = settings_path.parents[2]
+        env["USERPROFILE"] = str(launch_home)
+        env["HOME"] = str(launch_home)
+        env["ZCODE_HOME"] = str(launch_home / ".zcode")
+        env["ZCODE_STORAGE_DIR"] = str(launch_home / ".zcode")
+        command, child_env = self.lifecycle.materialize_command(
+            "zcode",
+            executable,
+            env,
+            provider,
+            provider_config,
+            mode="routed",
+            protocol="anthropic_messages",
+            cwd=Path.cwd(),
+            enable_channels=False,
+            passthrough=argv,
+            options={},
+        )
+        manage_router = bool(self.lifecycle.start_router())
+        if not argv or argv[0] not in {"--help", "-h", "--version", "-v", "version"}:
+            self.lifecycle.record_launch(provider, self.config.current_alias(config))
+        result = self.lifecycle.run_with_router(
+            lambda: self.process.call(command, env=child_env), manage_router
+        )
+        if result == 0:
+            for line in self.import_zcode_oauth_credential(settings_path):
+                self.process.print_line(line, flush=True)
+        return result
+
+
+@dataclass(frozen=True, slots=True)
+class ZcodeRuntimeCompatibilityApi:
+    context: Callable[[], ZcodeRuntimeContext]
+
+    def install_if_missing(self) -> str:
+        return self.context().install_if_missing()
+
+    def launch(self, passthrough: list[str]) -> int:
+        return self.context().launch(passthrough)
+
+
+__all__ = [
+    "ZcodeConfigurationPorts",
+    "ZcodeLifecyclePorts",
+    "ZcodeProcessPorts",
+    "ZcodeRuntimeCompatibilityApi",
+    "ZcodeRuntimeContext",
+    "zcode_settings",
+]

package/docs/CLI-Reference.md

@@ -7,11 +7,12 @@
 
 ## ciel-runtime
 
-기본값은 Claude Code를 Router를 통해 실행한다. Codex 런타임은 명시적으로 선택한다.
+기본값은 Claude Code를 Router를 통해 실행한다. 다른 런타임은 명시적으로 선택한다.
 
 ```bash
 ciel-runtime [OPTIONS] [-- RUNTIME_ARGS...]
 ciel-runtime codex [CODEX_ARGS...]
+ciel-runtime zcode [ZCODE_ARGS...]
 ciel-runtime --ca-runtime codex -- exec "hello"
 ```
 
@@ -23,7 +24,7 @@ ciel-runtime --ca-runtime codex -- exec "hello"
 | `--ca-model <id>` | 현재 제공자 모델 설정 후 실행 |
 | `--ca-base-url <url>` | 현재 제공자 기본 URL 설정 후 실행 |
 | `--ca-api-key <key>` | 현재 제공자 API 키 설정 후 실행 |
-| `--ca-runtime claude\|codex` | 실행 런타임 선택 |
+| `--ca-runtime claude\|codex\|codex-app-server\|agy\|grok\|zcode` | 실행 런타임 선택 |
 | `--ca-no-launch` | 설정만 적용하고 런타임 실행 생략 |
 | `--` | 이후 인자를 선택된 런타임에 그대로 전달 |
 
@@ -37,6 +38,20 @@ ciel-runtime --ca-provider ollama --ca-runtime codex -- exec "작업 내용"
 
 Codex 런처는 `~/.codex/config.toml`을 수정하지 않는다. 실행 시점에 `-c model_providers.ciel-runtime...` 오버라이드를 붙여 로컬 Router를 OpenAI Responses provider로 등록한다.
 
+### ZCode 실행
+
+```bash
+ciel-runtime zcode
+ciel-runtime --ca-runtime zcode -- --continue
+ciel-runtimectl launch-zcode --prompt "작업 내용"
+```
+
+ZCode는 워크스페이스별 Ciel 관리 홈과 `ZCODE_STORAGE_DIR`을 사용한다. 선택된
+provider/model은 로컬 Anthropic Router 설정으로 투영되며 사용자의 일반
+`%USERPROFILE%\.zcode` 또는 `~/.zcode` 설정은 덮어쓰지 않는다. `ciel-runtime
+zcode login --oauth`와 API-key 패널의 Z.AI OAuth는 Ciel 공용 credential store에
+Coding Plan 키를 저장하므로 다른 런타임도 같은 키를 사용한다.
+
 ---
 
 ## ciel-runtimectl

package/docs/Installation.md

@@ -118,6 +118,19 @@ Windows 설치 명령은 `irm https://x.ai/cli/install.ps1 | iex`이고 Linux/ma
 xAI API key, 선택 모델, reasoning effort를 launch process에만 투영한다. Grok의
 `~/.grok` 인증·세션·사용자 설정은 Ciel이 덮어쓰지 않는다.
 
+### ZCode 실행
+
+```bash
+ciel-runtime zcode
+ciel-runtime zcode --continue
+```
+
+ZCode가 없으면 `zcode-app-cli`를 npm으로 설치한다. 실행 시 워크스페이스별
+Ciel 관리 홈을 사용하고 선택된 provider/model을 로컬 Router로 연결한다.
+Z.AI OAuth는 `ciel-runtimectl zai-oauth login` 또는 `ciel-runtime zcode login
+--oauth`로 등록하며, 최종 Coding Plan API key만 Ciel의 공용 provider 설정에
+저장되어 Claude, Codex, AGY, ZCode 등 routed client가 함께 사용한다.
+
 ---
 
 ## Router 시작/중지

package/docs/journal/2026/08/24/zcode-runtime-oauth-windows-paste.okf

@@ -0,0 +1,68 @@
+okf_version: "1.0"
+knowledge:
+  task:
+    id: zcode-runtime-oauth-windows-paste-20260824
+    date: "2026-08-24"
+    objective: >-
+      Register ZCode as a supported Ciel runtime, share Z.AI OAuth credentials
+      across runtime clients, and repair leaked Windows bracketed-paste markers.
+    status: deployment-in-progress
+
+  evidence:
+    source_code:
+      terminal_reset:
+        file: ciel_runtime_support/terminal_platform_io.py
+        observation: >-
+          The reset sequence disabled mouse and focus modes but omitted DECSET
+          bracketed-paste disable ESC[?2004l.
+      runtime_registry:
+        file: ciel_runtime_support/runtime_adapters.py
+        observation: ZCode had no registered runtime adapter.
+      oauth_storage:
+        file: ciel_runtime_support/zai_oauth.py
+        observation: >-
+          The resolved Coding Plan API key is stored under providers.zai.api_key,
+          which is the shared provider credential consumed by routed clients.
+    upstream_runtime:
+      package: zcode-app-cli@3.8.1-15
+      runtime: zcode-runtime@0.16.3
+      observations:
+        - The help advertises --settings, but the bundled runtime rejected it as Unknown option.
+        - The bundled code resolves ZCODE_STORAGE_DIR and workspace AGENTS.md.
+        - A workspace-isolated USERPROFILE/HOME loaded the generated Ciel provider config.
+
+  implementation:
+    runtime:
+      registration:
+        commands: [ciel-runtime-zcode, launch-zcode, ca-runtime-zcode]
+      storage:
+        scope: workspace
+        config: zcode-home/.zcode/cli/config.json
+      routing:
+        protocol: anthropic_messages
+        provider_id: zai
+        endpoint: ciel-runtime-loopback-router
+    authentication:
+      shared_store: providers.zai.api_key
+      entrypoints: [provider-api-key-panel, zai-oauth-cli, zcode-login-oauth]
+      reverse_import: official-zcode-oauth-config-after-exit
+    terminal:
+      cleanup_sequence_added: ESC[?2004l
+
+  verification:
+    completed:
+      - Python compilation
+      - focused ZCode runtime tests
+      - focused Z.AI OAuth tests
+      - focused remote-memory tests
+      - actual zcode doctor execution
+      - actual ZCode TUI model-status rendering through the Ciel router
+      - full regression suite: 2739 passed and 136 skipped
+      - documentation validation: 23 Markdown files passed
+      - lint and architecture checks
+      - npm package dry run for version 0.2.26
+      - local install to C:/Users/djlov/.local/share/ciel-runtime
+      - local launcher reports ciel-runtime 0.2.26
+      - local ZCode launch reports zcode-runtime 0.16.3
+    pending:
+      - nightly publication

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oneciel-ai/ciel-runtime",
-  "version": "0.2.25",
-  "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, and compatible runtimes.",
+  "version": "0.2.26",
+  "description": "Universal AI coding-agent runtime and model-routing layer for Claude, Codex, AGY, ZCode, and compatible runtimes.",
   "license": "MIT",
   "author": "One Ciel LLC",
   "homepage": "https://github.com/OneCielAI/ciel-runtime#readme",