Sol + Luna Ultra GUI Launcher

Windows quick start: install the Microsoft Store ChatGPT/Codex app, close it, and double-click Launch Luna Ultra.cmd. Luna supplies its x64 native boundary and can provision its pinned app-local Python runtime automatically. See WINDOWS_PORT.md.

This project adds two GUI aliases for Codex core's native Ultra/Proactive Multi-Agent V2 state in the normal ChatGPT desktop app. It is not a prompt-only imitation:

GUI selection	Codex core	Upstream inference effort	GUI display
Sol / High	Ultra / Proactive	High on managed Sol/High branches	Sol / High
Luna / Max	Ultra / Proactive	Max	Luna / Max
Sol / Ultra	Native Ultra / Proactive	Max	Sol / Ultra
Every other pair	Selected model/effort under the shared V2 profile	No inference-effort rewrite	Unchanged

Codex selects its built-in Proactive policy and all six V2 collaboration operations for the two aliases, and you choose the active spawned-agent concurrency cap at launch. Sol/High is deliberately split: Codex core sees Ultra, while its root and recursively correlated descendants use High at the provider boundary whenever their logical branch remains Sol/High. The bridge masks the internal Ultra value back to the GUI label that activated it. Native Sol/Ultra is never relabeled.

Windows quick start

Install the Microsoft Store ChatGPT/Codex app, close it, and double-click Launch Luna Ultra.cmd. No separate Python or Visual Studio installation is required for an ordinary launch. If no compatible x64 CPython is already available, the first launch downloads the official CPython 3.13.15 x64 embeddable archive from python.org, verifies its pinned SHA-256, and publishes it under the checkout's private runtime/python/ cache. It does not install Python system-wide, require administrator rights, or change PATH.

The launcher prompts for the maximum number of concurrently open spawned-agent threads, excluding the primary; pressing Return accepts the default of 3. After validation, the console remains open for the full Luna session. Press Return or Ctrl+C there to close only the ChatGPT process tree created by that launcher. Closing ChatGPT first ends the console session as well. The created GUI is bound to a private kill-on-close Windows Job before it begins running, so closing the launcher window or otherwise terminating its session cannot leave that modified GUI tree running without its launcher. For an explicit noninteractive selection, run Launch Luna Ultra.cmd --agents N from Command Prompt (or prefix the quoted path with & in PowerShell).

The .cmd entrypoint invokes the tracked bootstrap helper with a process-only PowerShell execution-policy override; it does not change the user or machine policy. An offline machine can be seeded with the pinned archive as documented in WINDOWS_PORT.md.

Each launch validates the installed OpenAI.Codex_2p2nqsd0c76g0 package, Store status, full-trust manifest, OpenAI Authenticode signer, PE architecture, and the hashes of the desktop and bundled runtime pair. It copies the signed Codex pair into a fresh private stage, validates and stages Luna's hash-pinned prebuilt PE x64 wrapper and launcher, and selects a PE x64 CPython bridge. It launches only the new packaged GUI with a process-scoped CODEX_CLI_PATH. An elevated invocation uses the normal Explorer token; an unelevated invocation uses CreateProcessW directly. It never enables package debugging and refuses to redirect an already-running ChatGPT GUI.

The external Store package is architecture-neutral input: its signed runtime may be x64 or ARM64, while Luna's wrapper, launcher, and Python bridge are x64. Package updates are accepted only after the live identity, signature, architecture, version, and hashes pass again; there is no stale ARM release pin. The bridge records a fresh owner-private audit under runtime/audit/; preflight binds that root to the exact desktop user even when staging runs elevated. Windows uses user-approved-untested compatibility with the exact Codex version observed during that launch.

For a read-only discovery check or an isolated marker smoke:

"Preflight Luna Ultra.cmd" --json
"Preflight Luna Ultra.cmd" --marker-smoke --json

The smoke closes only the GUI tree it created and fails if process exit cannot be proven. Close ChatGPT before a normal launch: Windows single-instance redirection cannot add an environment override to a process that is already running. See WINDOWS_PORT.md for cleanup, security details, and current limitations.

macOS quick start

This is tested and pinned to one exact Apple-silicon ChatGPT desktop release. An authentic OpenAI-signed but untested release can be tried through an explicit, default-No per-launch override. If your installation meets the macOS requirements:

git clone https://github.com/mapleroyal/luna-ultra-gui.git
cd luna-ultra-gui
/bin/zsh scripts/generate-command

Then double-click Launch Luna Ultra.command in Finder to run it.

The generator creates an executable, byte-for-byte .command copy locally and removes any quarantine attribute from that new file. The generated launcher is Git-ignored; it is intentionally not part of the repository.

The launcher asks for the maximum number of concurrently open spawned-agent threads, excluding the primary. Like Windows, it accepts 1 through 64, defaults to 3, and requests confirmation above 16. It keeps its Terminal window open for the full Luna session. Press Return or Ctrl+C there, or close the Terminal window, to close only the exact ChatGPT process tree created by that launcher. Closing ChatGPT first ends the launcher automatically. The launch lock and staged runtime remain owned by the launcher until that session cleanup completes.

macOS requirements

This repository is deliberately release- and platform-specific:

• macOS on arm64;
• ChatGPT desktop 26.818.41509 (build 6962) with bundled codex-cli 0.149.0-alpha.4.1 and its codex-code-mode-host companion;
• the app named ChatGPT.app or Codex.app under /Applications or ~/Applications;
• a signed-in account with access to GPT-5.6 Sol or Luna (the local preflight cannot verify account entitlement);
• for the tested path, the exact signed app and Codex identities recorded in evidence/release-manifest.json; an untested run still requires authentic OpenAI signatures and the other safeguards described below;
• /bin/zsh, /usr/bin/python3, and standard macOS tools such as codesign, git, lipo, lsappinfo, osascript, open, and shasum;
• a writable Git checkout kept in its original directory layout.

The runtime uses only the Python standard library. The committed tests are verified with Apple's Python 3.9.6. ChatGPT auto-updates normally. If a newer authentic app does not match the tested manifest, the launcher shows both versions and asks whether to run the local prompt/config compatibility preflight and try it once. Declining changes nothing.

Verify

From the repository root:

/usr/bin/python3 -m unittest discover -s tests -v

The unit/evidence suite covers protocol and outbound-effort rewriting, rollback, loopback routing and framing, wrapper dispatch, marker/lock safety, release-evidence schema, artifact attestations, and cross-file configuration parity.

The real app-server matrix is a separate, local-only check:

/usr/bin/python3 tests/integration_probe.py

It runs only when the installed app exactly matches the release manifest. Otherwise it emits a machine-readable skipped result and exits successfully. Use --strict-release when a mismatch should fail automation:

/usr/bin/python3 tests/integration_probe.py --strict-release

The probe uses an in-process deterministic HTTP Responses endpoint. It never sends a model request to OpenAI, and its output contains no captured prompts, protocol IDs, or credentials. It iterates all supported installation locations, strictly verifies the app, Codex, and the code-mode host, reports only mismatch field names, and executes owner-private sealed copies of the authenticated Codex runtime pair and current proxy bytes. It also executes a deterministic code-mode custom-tool call through the staged host. For Sol/High it verifies root-turn, compaction, inherited-child, and inherited-grandchild requests reach the deterministic upstream at High while the alias branch remains Proactive/Ultra. It also checks an explicit Medium branch, recursive Medium inheritance, model-only logical-effort inheritance, exact spawn-call-to-child-thread lineage, and allowlisted server acknowledgments. It includes repository-relative hashes of the hardened project artifacts in every ordinary result. The committed passing result is evidence/macos-26.818.41509-integration-summary.json. It is macOS ARM64 evidence bound to project commit cdb4da94306949d3d76f07fd10002611eca249d0, not a claim about current worktree bytes or Windows. See evidence/historical-integration-summary.json for the recovered, explicitly scoped earlier evidence.

Use

Double-click the locally generated Launch Luna Ultra.command in Finder.

After pulling a change to Launch Luna Ultra.zsh, remove the old generated copy and rerun /bin/zsh scripts/generate-command. The generator refuses to overwrite a different file or follow a symlink.

Enter the spawned-agent thread cap. The primary agent is not included, matching agents.max_concurrent_threads_per_session semantics. For example, entering 5 permits five spawned agents plus the primary.

If the installed app is authentic and OpenAI-signed but does not match the tested release, the launcher offers Launch this untested release anyway? [y/N]. Approval applies only to that run. It relaxes release-specific version/build, CDHash, and Codex hash/version pins, but still requires the expected bundle ID, OpenAI Team ID, architecture, strict signatures, a passing native-Ultra prompt comparison, and stable observed identities throughout the launch. There is no promise that an untested release will pass or behave correctly.

If ChatGPT is already running, the launcher asks permission to quit and relaunch it because an existing desktop process cannot retroactively adopt a different CODEX_CLI_PATH. It waits for the original processes to exit and never force-kills that pre-existing desktop. If a newly launched, still-unverified process fails attestation, cleanup is limited to marker/PID/start-identity-bound processes from that launch. The launcher freezes the bound process forest, tracks descendants that reparent within its owned process groups, requests termination, and uses SIGKILL only for survivors.

While the profile is active, Sol / High and Luna / Max requests are kept at native core Ultra across new, resumed, forked, settings-changed, and subsequent-turn flows. A Sol/High root additionally starts a launch-local managed descendant tree. Its root, compaction, and recursively correlated Sol/High descendants are lowered from core's serialized Max to upstream High. Luna/Max and native Ultra stay Max upstream. Changing either the model or effort away from a trigger pair stops the root alias rewrite. Failed and out-of-order changes roll back to the last accepted pair.

Inside that managed Sol/High tree, a spawn_agent call that omits reasoning_effort inherits its parent's logical effort, recursively. This also applies when the call supplies only a model. An explicit none, minimal, low, medium, high, xhigh, max, or ultra starts that child's branch at the requested effort: Sol/High remains the Ultra-core/High-wire alias, while native Ultra is serialized as Max. These inheritance rules are deliberately confined to the managed Sol/High tree; spawns under Luna/Max, native Sol/Ultra, and other roots retain ordinary Codex behavior.

Codex 0.149.0-alpha.4.1 reports a follow-up to an already-loaded child as subAgentActivity: interacted, rather than replaying its original started edge. When that child predates the current launcher process—or a started edge arrives after its spawn intent was lost during a restart—the bridge admits only the exact parent/turn/child activity and preserves the model and core effort it actually observes. It never guesses that an ambiguous Sol/serialized-Max child was the Sol/High alias, so this recovery path remains Max upstream. Proactive/serialized-Max is retained as core Ultra for nested work. A deterministic request or lineage rejection is returned as a non-retryable client error instead of a retryable 502 loop.

For a fresh resume, the request may reveal neither the persisted model nor effort. The bridge passes that resume through and learns from Codex's response. A returned Luna/Ultra can be recognized as the persisted Luna/Max alias because Luna does not advertise native Ultra; a returned Sol/Ultra remains visible as native Ultra. Explicit non-alias pairs are never inferred as aliases. The app-wide V2 and capacity fields are still canonicalized on every start, resume, and fork, including this flow.

What it changes

The launcher does not persistently edit ~/.codex/config.toml, the signed app bundle, or the model catalog.

It starts ChatGPT with a process-scoped wrapper. The wrapper runs an identity-bound JSONL bridge between the desktop and the original signed Codex app-server. That bridge canonicalizes the app-wide V2/capacity fields on start/resume/fork and rewrites the two exact GUI aliases into core Ultra.

The same process also runs an ephemeral HTTP provider bridge on a random loopback capability path. Codex's built-in OpenAI provider is routed through it with request compression disabled and WebSocket requests deliberately moved to HTTP. All provider traffic passes through this local bridge, but only an identified Sol/High root, its compaction, or a correlated Sol/High descendant has reasoning.effort changed from Max to High. The private alias marker is removed before forwarding. Other roots and non-Sol/High descendant branches receive no inference-effort rewrite, although every task shares the selected V2 orchestration/capacity settings and custom model providers are not preserved by this profile.

Quitting ChatGPT removes the process-scoped override. Starting ChatGPT normally restores ordinary behavior.

Each launcher run also creates:

• a verification marker under runtime/markers/;
• a token-bound pair containing the authenticated Codex executable and its codex-code-mode-host companion under runtime/staging/;
• an owner-private JSONL audit under runtime/audit/ containing rewrite metadata and, for managed Sol/High requests, allowlisted lineage and effort diagnostics.

Runtime directories are owner-only. Marker/audit files are private, and both staged runtime executables plus their token directory are sealed read/execute-only for the owner. Diagnostics may record raw thread, turn, parent, call, child, and response IDs; model/effort decisions; HTTP status; and the model/effort scalars reported by the response header or response.created. They never record prompts, full request or response bodies, full headers, environment dumps, Authorization or Cookie values, ChatGPT account identity, or attestation/routing secrets. Those credentials and provider bodies necessarily transit the loopback bridge in memory only.

Compatibility guard

Before asking to quit ChatGPT, the launcher:

1. Checks runtime-directory writability and acquires an owner-only launch lock.
2. Requires the manifest's bundle ID, app version/build, arm64 architecture, OpenAI Team ID, full app/Codex/code-mode-host CDHashes, Codex version, and both runtime-executable SHA-256 values. For a user-approved untested run, only the release-specific pins are relaxed; bundle ID, Team ID, architecture, and strict signature checks remain mandatory. Signature verification uses an explicit Apple-anchored Developer ID requirement for OpenAI, and the observed identities become the per-launch pins.
3. Verifies both signatures with codesign --strict.
4. Copies the exact no-follow Codex and code-mode-host source descriptors into a random private launch directory, verifies and seals that runtime closure, and never executes the mutable source-bundle pathnames.
5. Requires the installed catalog to advertise Sol/High, Sol/Ultra with V2, and Luna/Max, then renders Sol's native Ultra prompt in a clean temporary Codex home.
6. Renders Luna in native Ultra/V2 through the wrapper.
7. Requires the two selected multi-agent developer messages and dynamic capacity text to match.
8. Hash-binds both staged runtime executables, their source identities, release manifest, wrapper, bridge, control script, and instruction fingerprint to the launched process.

After launch, it verifies the exact ChatGPT → bridge → primary signed Codex app-server process chain. LaunchServices is also checked for every running instance of the bundle ID, including copies outside the supported install directories. The bridge retains descriptors for the staged root, token directory, and both executables; it rechecks their identities and hashes before the version probe, primary app-server, and every local configuration validator. It removes that stage only after all of its tracked private process groups are gone. A failed new launch is cleaned by its private marker, exact PID and process-start identity, and bound process groups rather than by application name. Before admitting a custom Sol/High or Luna/Max task, the bridge reads the effective local V2 configuration for that task's working directory. It tracks sticky working-directory changes, rolls state back when Codex rejects a request, and rejects dependent requests while a model, effort, or cwd change is unresolved. Conflicting alias fields, unsupported advanced V2 fields, or missing native-Ultra confirmation stop the bridge instead of silently downgrading. For exact recursive Sol/High inheritance, effective subagent model/effort defaults and user-defined agent roles are also rejected; only the verified built-in default, worker, and explorer roles are admitted.

The final historical observation run exercised direct Ultra, the GUI downgrade control, proxy start/settings/subsequent-turn behavior, durable resume and fork, wire-level Max, GUI-side Max masking, the built-in Proactive marker, and all six expected collaboration tools. Its project bytes were later preserved by commit fbc1a9c3e4f70de5d200b11eb79fa25a0a29304f; the release manifest records selected repository-state hashes. That private development history is not part of this public repository because it contained machine-local metadata. Only the proxy was directly executed by that historical matrix. The launcher, wrapper, control, and unit-test hashes establish repository state, not matrix coverage.

A narrow checker covering the principal control and proxy cases passed twice earlier in development, before the final proxy hardening patch. Those two passes are not bound to the commit above. No automated checker was applied to the final observation run, so its redacted values are labeled archived observations rather than checker assertions.

The recovered historical harness is not published because it predates output redaction and embedded machine-local metadata. The hardened replay harness is retained in tests/integration_probe.py. Its committed sanitized exact-release result is retained separately as evidence/macos-26.818.41509-integration-summary.json and remains explicitly bound to the older project bytes it exercised.

Runtime retention and cleanup

Each active audit is capped at 8 MiB and fails closed if that bound would be exceeded. Once no desktop instance remains and before opening the new one, the control script removes owner-managed marker, audit, and temporary files older than 30 days, plus stale token-bound staged executables. A token whose marker still binds any live exact process is preserved together with its stage. Quit ChatGPT before manual cleanup. To preview eligible files:

find runtime/audit runtime/markers -type f \
  \( -name '*.jsonl' -o -name '*.json' -o -name '*.tmp' \) \
  -mtime +30 -print
find runtime/staging -mindepth 1 -maxdepth 1 -type d -mtime +30 -print

After reviewing that list, invoke the same guarded cleanup used by the launcher:

/usr/bin/python3 scripts/control.py cleanup-runtime --days 30

See runtime/README.md for contents, permissions, and retention details.

Limits

• Luna is cataloged as V1/Max, not V2/Ultra. The Luna/Max alias uses real Codex core behavior in an unsupported combination; it is not an OpenAI product guarantee.
• Sol/High is split-mode: core is genuinely Ultra/Proactive, while its managed root, compaction, and recursively correlated Sol/High descendant requests reach the upstream provider at High. Native Sol/Ultra remains Max upstream.
• Luna is rewritten only when Max is selected. Lower Luna efforts pass through unchanged, and the GUI does not gain a Luna/Ultra picker label.
• Recursive effort guarantees are launch-local and apply only to the managed Sol/High lineage that the bridge correlates by parent turn, spawn call, and child thread. Omitted effort—including a model-only spawn—means logical inheritance inside that tree; an explicit supported effort begins a new branch. An exact interacted or unmatched-started activity under a live managed parent may conservatively recover an older/crash-window child, but historical Sol/High provenance is never inferred and its observed core request is not lowered. Other missing, conflicting, or timed-out lineage fails once without a retryable 5xx storm. A child reloaded directly, without an active managed parent activity, remains outside the managed policy. Other roots remain outside this policy.
• Multi-Agent V2 has no separate core nesting-depth ceiling in this pinned release. The launch-selected cap limits active spawned threads at every depth and applies to every model/effort combination. The bridge also retains at most 4,096 launch-local lineage records; an exceptionally large managed tree fails closed at that safety bound instead of losing effort provenance.
• This profile forces Codex's built-in OpenAI/ChatGPT model provider so a thread can safely switch into or out of Sol/High later. Custom provider selection is therefore not preserved. All provider traffic traverses the owner-process loopback bridge; only the identified Sol/High managed tree is modified.
• The launcher affects only the ChatGPT process it starts on this Mac. Opening the same task in an independently running app on another host does not carry this process-local bridge or its launch-local descendant records.
• Resuming preserves existing conversation history, including older developer messages. Start a new task when a completely clean current Ultra context matters.
• User or project advanced V2 policy/prompt overrides, including multi_agent_mode_hint_text, are rejected for custom alias tasks because they no longer match the verified profile.
• This release accepts wait_agent_enabled as a configuration override. The launcher pins it to true, and wait_agent exposure is covered by the exact-release integration matrix.
• The committed real app-server evidence applies only to the exact macOS ARM64 release and project commit named in evidence/macos-26.818.41509-integration-summary.json. It does not attest the current worktree or Windows. Any artifact change requires a new exact-release passed result before making the same evidence claim.
• The untested-release override carries no integration-evidence claim. It may be useful when only packaging identities changed, but protocol changes can still make startup fail or cause incorrect behavior.
• Runtime hardening assumes processes already running as the same macOS user are trusted. Owner-private staging prevents bundle updates and ordinary pathname replacement from changing the selected executable unnoticed, but macOS Python exposes no descriptor-bound Mach-O execution primitive: a malicious same-user process could race the final identity check and pathname execution, or deliberately escape a tracked process group with a new session.
• Agent swarms consume additional tokens and account usage. Proactive mode may still decline to delegate when parallel work would not help.

See TECHNICAL_NOTES.md for implementation evidence, release provenance, and source links. For sensitive reports, follow SECURITY.md instead of opening a public issue.

License

Released under the MIT License. The optional Windows CPython runtime keeps its upstream license; see Third-party notices.