Fix cross-platform auth prep and skill links

Switch ChatGPT-login provider auth prep to a proxy-managed provider-auth.json file while preserving the env-var compatibility path. Delegate skill link creation/removal to the manager so .codex install/update/uninstall flows work across Windows and POSIX shells.

Fixes #2

Fixes #3

Author: gaoguobin

.codex/INSTALL.md

@@ -12,56 +12,65 @@ Fetch and follow instructions from https://raw.githubusercontent.com/gaoguobin/c
 
 ## What this installs
 
-- Git repo: `%USERPROFILE%\.codex\codex-fast-proxy`
+- Git repo: `~/.codex/codex-fast-proxy`
 - Python package: editable user install of `codex-fast-proxy`
-- Skill namespace junction: `%USERPROFILE%\.agents\skills\codex-fast-proxy -> %USERPROFILE%\.codex\codex-fast-proxy\skills`
-- Runtime state after enable: `%USERPROFILE%\.codex\codex-fast-proxy-state`
-- Startup hook after enable: `%USERPROFILE%\.codex\hooks.json`
+- Skill namespace link: `~/.agents/skills/codex-fast-proxy -> ~/.codex/codex-fast-proxy/skills`
+- Runtime state after enable: `~/.codex/codex-fast-proxy-state`
+- Startup hook after enable: `~/.codex/hooks.json`
 
 ## Install steps
 
 This install only installs files and the skill. It must not switch Codex App to the proxy.
 The startup hook is installed later by `python -m codex_fast_proxy install --start`, not by this file-only install.
 
-If the Codex environment uses sandbox or approval controls, request approval/escalation for the install block because it clones from GitHub, installs a Python package, writes under `%USERPROFILE%\.codex`, and creates a junction under `%USERPROFILE%\.agents`.
+If the Codex environment uses sandbox or approval controls, request approval/escalation for the install block because it clones from GitHub, installs a Python package, writes under `~/.codex`, and creates a skill link under `~/.agents`.
 
-If any command fails because of network, permissions, sandbox write limits, or junction creation, do not try unrelated workarounds. Ask for approval and rerun the same intended install step.
+If any command fails because of network, permissions, sandbox write limits, or skill link creation, do not try unrelated workarounds. Ask for approval and rerun the same intended install step.
 
 Run this PowerShell block exactly:
 
 ```powershell
-$repoRoot = Join-Path $HOME '.codex\codex-fast-proxy'
-$skillsRoot = Join-Path $HOME '.agents\skills'
+$pythonCmd = if (Get-Command python -ErrorAction SilentlyContinue) {
+    'python'
+} elseif (Get-Command python3 -ErrorAction SilentlyContinue) {
+    'python3'
+} else {
+    throw 'Python 3 is required before installing codex-fast-proxy.'
+}
+$repoRoot = Join-Path (Join-Path $HOME '.codex') 'codex-fast-proxy'
+$skillsRoot = Join-Path (Join-Path $HOME '.agents') 'skills'
 $skillNamespace = Join-Path $skillsRoot 'codex-fast-proxy'
 
 if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
     throw 'git is required before installing codex-fast-proxy.'
 }
 
-if (-not (Get-Command python -ErrorAction SilentlyContinue)) {
-    throw 'python is required before installing codex-fast-proxy.'
-}
-
 if (Test-Path $repoRoot) {
     throw 'codex-fast-proxy is already installed. Follow UPDATE.md instead.'
 }
 
 if (Test-Path $skillNamespace) {
-    throw 'The skill namespace junction already exists. Remove it or follow UNINSTALL.md before reinstalling.'
+    throw 'The skill namespace link already exists. Remove it or follow UNINSTALL.md before reinstalling.'
 }
 
-New-Item -ItemType Directory -Force -Path $skillsRoot | Out-Null
 git clone https://github.com/gaoguobin/codex-fast-proxy.git $repoRoot
-python -m pip install --user -e $repoRoot
-cmd /d /c "mklink /J `"$skillNamespace`" `"$repoRoot\skills`""
+& $pythonCmd -m pip install --user -e $repoRoot
+& $pythonCmd -m codex_fast_proxy link-skill --repo-root $repoRoot
 ```
 
 ## After install
 
 Run this check in the same Codex turn:
 
 ```powershell
-python -m codex_fast_proxy doctor
+$pythonCmd = if (Get-Command python -ErrorAction SilentlyContinue) {
+    'python'
+} elseif (Get-Command python3 -ErrorAction SilentlyContinue) {
+    'python3'
+} else {
+    throw 'Python 3 is required before checking codex-fast-proxy.'
+}
+& $pythonCmd -m codex_fast_proxy doctor
 ```
 
 Report the JSON result in the reply. When `"ok": true`, explicitly tell the user:
@@ -86,22 +95,23 @@ Codex App/CLI Fast UI choices; in API-key mode it may inject the priority tier w
 `--service-tier-policy inject_missing` only when the user explicitly asks for global Fast injection,
 and `--service-tier-policy preserve` only when they explicitly want no proxy-side Fast injection. If
 the user wants ChatGPT login compatibility for plugins/GitHub/Apps/connectors while model requests
-still use a third-party provider, configure an upstream key environment variable with
-`--upstream-api-key-env <ENV_NAME>`; do not ask the user to paste API keys into chat and do not edit
-`auth.json` unless they explicitly request recovery. This auth override applies only to provider API
+still use a third-party provider, prepare the proxy provider auth file with
+`prepare-chatgpt-login`, then use `set-upstream --use-provider-auth-file`; do not ask the user to
+paste API keys into chat and do not edit `auth.json` unless they explicitly request recovery. This
+auth override applies only to provider API
 requests that already go through the local proxy; it must not intercept or modify ChatGPT
 plugin/GitHub/App connector traffic. In override mode, the proxy replaces provider `Authorization`
 and drops unexpected `Cookie` headers before forwarding upstream.
 
 If Codex currently works through a third-party provider and the user wants to prepare for ChatGPT
 login, run `python -m codex_fast_proxy prepare-chatgpt-login` first as a dry run. Report the
 non-secret JSON fields, then ask before running `python -m codex_fast_proxy prepare-chatgpt-login
---target-env <ENV_NAME> --apply`. The apply step writes the provider key through the Windows user
-environment API, does not print the key, does not change proxy settings, and does not edit
-`auth.json`. After apply, run `python -m codex_fast_proxy set-upstream --upstream-api-key-env
-<ENV_NAME>` so the manager verifies `POST /v1/responses` with `stream=true` before saving the auth
-split. Tell the user to restart Codex App or open a new CLI process after any user environment
-variable change.
+--apply`. The apply step copies the currently working provider key into
+`~/.codex/codex-fast-proxy-state/provider-auth.json`, does not print the key, does not change proxy
+settings, and does not edit `auth.json`. After apply, run
+`python -m codex_fast_proxy set-upstream --use-provider-auth-file` so the manager verifies
+`POST /v1/responses` with `stream=true` before saving the auth split. Tell the user to restart Codex
+App or open a new CLI process if the result reports `needs_restart=true`.
 
 After a successful `install --start`, report the non-secret top-level `next_user_action` and
 `chatgpt_login_hint` fields. When `chatgpt_login_hint.status=optional_setup_available`, tell the

.codex/SET_UPSTREAM.md

@@ -12,22 +12,34 @@ not required. If they want to change provider URL and did not provide the new up
 it. Do not guess provider URLs.
 
 If the Codex environment uses sandbox or approval controls, request approval/escalation because this
-flow may write under `%USERPROFILE%\.codex`, edit `%USERPROFILE%\.codex\hooks.json`, restart the
+flow may write under `~/.codex`, edit `~/.codex/hooks.json`, restart the
 background proxy, and update the uninstall recovery baseline.
 
+Every PowerShell block below assumes this resolver has already run in the same shell:
+
+```powershell
+$pythonCmd = if (Get-Command python -ErrorAction SilentlyContinue) {
+    'python'
+} elseif (Get-Command python3 -ErrorAction SilentlyContinue) {
+    'python3'
+} else {
+    throw 'Python 3 is required before changing codex-fast-proxy settings.'
+}
+```
+
 Run this block after replacing `<UPSTREAM_BASE_URL>` with the user-provided URL:
 
 ```powershell
-$statusJson = python -m codex_fast_proxy status
+$statusJson = & $pythonCmd -m codex_fast_proxy status
 $status = $statusJson | ConvertFrom-Json
 if ($status.config_matches -ne $true) {
     $statusJson
     throw 'Codex config no longer points to the recorded local proxy. Review ~/.codex/config.toml before changing upstream.'
 }
 
-$resultJson = python -m codex_fast_proxy set-upstream --upstream-base '<UPSTREAM_BASE_URL>'
+$resultJson = & $pythonCmd -m codex_fast_proxy set-upstream --upstream-base '<UPSTREAM_BASE_URL>'
 $resultJson
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy status
 ```
 
 `set-upstream` verifies the candidate route before writing settings by sending one side-path
@@ -39,78 +51,79 @@ may be unable to reach the model.
 If the user asks to verify first without changing local state, run:
 
 ```powershell
-python -m codex_fast_proxy verify-upstream --upstream-base '<UPSTREAM_BASE_URL>'
+& $pythonCmd -m codex_fast_proxy verify-upstream --upstream-base '<UPSTREAM_BASE_URL>'
 ```
 
 Report the JSON result and stop. `verify-upstream` must not write settings, edit Codex config,
 install hooks, or restart the proxy.
 
-For ChatGPT login compatibility without changing the upstream URL, ask for the environment variable
-name that already contains the third-party provider API key. Do not ask the user to paste the key
-value into chat. This affects only provider API requests that already go through the local proxy; it
+For ChatGPT login compatibility without changing the upstream URL, prepare the proxy provider auth
+file. Do not ask the user to paste the key value into chat. This affects only provider API requests
+that already go through the local proxy; it
 must not intercept ChatGPT plugin/GitHub/App connector traffic. In override mode, the proxy replaces
 provider `Authorization` and drops unexpected `Cookie` headers before forwarding upstream.
 
-If the user does not already have a provider key environment variable, run a dry run first:
+Run a dry run first:
 
 ```powershell
-python -m codex_fast_proxy prepare-chatgpt-login
+& $pythonCmd -m codex_fast_proxy prepare-chatgpt-login
 ```
 
 Report only the non-secret JSON fields. If the dry run found the current working provider key in
 `auth.json` or the environment, ask before applying:
 
 ```powershell
-python -m codex_fast_proxy prepare-chatgpt-login --target-env '<ENV_NAME>' --apply
+& $pythonCmd -m codex_fast_proxy prepare-chatgpt-login --apply
 ```
 
-The apply step writes a Windows user environment variable through the manager, does not print the
-key, and does not change proxy settings. After it succeeds, continue with `set-upstream` so the
-manager verifies a streaming `/v1/responses` request before saving the auth override.
+The apply step copies the current working provider key into
+`~/.codex/codex-fast-proxy-state/provider-auth.json`, does not print the key, and does not change
+proxy settings. After it succeeds, continue with `set-upstream` so the manager verifies a streaming
+`/v1/responses` request before saving the auth override.
 
 ```powershell
-$statusJson = python -m codex_fast_proxy status
+$statusJson = & $pythonCmd -m codex_fast_proxy status
 $status = $statusJson | ConvertFrom-Json
 if ($status.config_matches -ne $true) {
     $statusJson
     throw 'Codex config no longer points to the recorded local proxy. Review ~/.codex/config.toml before changing upstream auth.'
 }
 
-$resultJson = python -m codex_fast_proxy set-upstream --upstream-api-key-env '<ENV_NAME>'
+$resultJson = & $pythonCmd -m codex_fast_proxy set-upstream --use-provider-auth-file
 $resultJson
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy status
 ```
 
-To clear a previously configured upstream auth environment override and return to preserving Codex's
-original provider `Authorization` header, run:
+To clear a previously configured upstream auth override and return to preserving Codex's original
+provider `Authorization` header, run:
 
 ```powershell
-python -m codex_fast_proxy set-upstream --clear-upstream-api-key-env
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy set-upstream --clear-upstream-auth
+& $pythonCmd -m codex_fast_proxy status
 ```
 
 For explicit global Fast injection without changing the upstream URL, confirm that the user accepts
 that Codex App's Fast UI toggle will no longer control requests whose `service_tier` is missing, then
 run:
 
 ```powershell
-python -m codex_fast_proxy set-upstream --service-tier-policy inject_missing
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy set-upstream --service-tier-policy inject_missing
+& $pythonCmd -m codex_fast_proxy status
 ```
 
 To return to UI-controlled Fast behavior, run:
 
 ```powershell
-python -m codex_fast_proxy set-upstream --service-tier-policy preserve
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy set-upstream --service-tier-policy preserve
+& $pythonCmd -m codex_fast_proxy status
 ```
 
 For the default automatic behavior, where API-key mode can use global priority but ChatGPT-login or
 unclear states preserve the App/CLI choice, run:
 
 ```powershell
-python -m codex_fast_proxy set-upstream --service-tier-policy auto
-python -m codex_fast_proxy status
+& $pythonCmd -m codex_fast_proxy set-upstream --service-tier-policy auto
+& $pythonCmd -m codex_fast_proxy status
 ```
 
 Report the set-upstream JSON and the final status JSON. The key fields are `provider`, `base_url`,
@@ -139,7 +152,6 @@ net start winnat
 netsh interface ipv4 show excludedportrange protocol=tcp
 ```
 
-If the user changed API key environment variables, model, reasoning, or other Codex config, tell
-them to restart Codex App or open a new CLI process so Codex reloads those settings. The proxy can
-read Windows user environment variables directly when possible, but already-running Codex processes
+If the user changed provider auth, model, reasoning, or other Codex config, tell them to restart
+Codex App or open a new CLI process so Codex reloads those settings. Already-running Codex processes
 still may need a restart to reload their own config and environment.

.codex/UNINSTALL.md

@@ -16,15 +16,21 @@ If the user changed `~/.codex/config.toml` after enabling the proxy, the manager
 
 Uninstall removes only the `codex-fast-proxy` entry from `~/.codex/hooks.json`; unrelated user hooks must be preserved.
 
-If the Codex environment uses sandbox or approval controls, request approval/escalation for uninstall because it may restore `~/.codex/config.toml`, edit `~/.codex/hooks.json`, stop a background proxy, uninstall a Python package, remove a junction under `%USERPROFILE%\.agents`, and delete `%USERPROFILE%\.codex\codex-fast-proxy`.
+If the Codex environment uses sandbox or approval controls, request approval/escalation for uninstall because it may restore `~/.codex/config.toml`, edit `~/.codex/hooks.json`, stop a background proxy, uninstall a Python package, remove a skill link under `~/.agents`, and delete `~/.codex/codex-fast-proxy`.
 
-If any command fails because of permissions, sandbox write limits, process locks, or junction removal, do not try unrelated workarounds. Ask for approval and rerun the same intended uninstall step.
+If any command fails because of permissions, sandbox write limits, process locks, or skill link removal, do not try unrelated workarounds. Ask for approval and rerun the same intended uninstall step.
 
 Run this PowerShell block exactly:
 
 ```powershell
-$repoRoot = Join-Path $HOME '.codex\codex-fast-proxy'
-$skillNamespace = Join-Path $HOME '.agents\skills\codex-fast-proxy'
+$pythonCmd = if (Get-Command python -ErrorAction SilentlyContinue) {
+    'python'
+} elseif (Get-Command python3 -ErrorAction SilentlyContinue) {
+    'python3'
+} else {
+    throw 'Python 3 is required before uninstalling codex-fast-proxy.'
+}
+$repoRoot = Join-Path (Join-Path $HOME '.codex') 'codex-fast-proxy'
 $uninstallJson = $null
 $uninstallResult = $null
 $status = $null
@@ -33,10 +39,10 @@ $confirmationRequired = $false
 
 if (Test-Path $repoRoot) {
     $env:PYTHONPATH = Join-Path $repoRoot 'src'
-    $statusJson = python -m codex_fast_proxy status
+    $statusJson = & $pythonCmd -m codex_fast_proxy status
     $status = $statusJson | ConvertFrom-Json
     if ($status.config_matches -eq $true) {
-        $uninstallJson = python -m codex_fast_proxy uninstall --defer-stop
+        $uninstallJson = & $pythonCmd -m codex_fast_proxy uninstall --defer-stop
         $uninstallResult = $uninstallJson | ConvertFrom-Json
         $uninstallJson
         if ($uninstallResult.status -eq 'confirmation_required') {
@@ -47,7 +53,7 @@ if (Test-Path $repoRoot) {
             $deferred = $true
         }
     } else {
-        $uninstallJson = python -m codex_fast_proxy uninstall
+        $uninstallJson = & $pythonCmd -m codex_fast_proxy uninstall
         $uninstallResult = $uninstallJson | ConvertFrom-Json
         $uninstallJson
         if ($uninstallResult.status -eq 'confirmation_required') {
@@ -60,12 +66,13 @@ if (Test-Path $repoRoot) {
 }
 
 if ((-not $deferred) -and (-not $confirmationRequired)) {
-    python -m pip uninstall -y codex-fast-proxy
-
-    if (Test-Path $skillNamespace) {
-        cmd /d /c "rmdir `"$skillNamespace`""
+    if (Test-Path $repoRoot) {
+        $env:PYTHONPATH = Join-Path $repoRoot 'src'
+        & $pythonCmd -m codex_fast_proxy unlink-skill --repo-root $repoRoot
     }
 
+    & $pythonCmd -m pip uninstall -y codex-fast-proxy
+
     if (Test-Path $repoRoot) {
         Remove-Item -LiteralPath $repoRoot -Recurse -Force
     }