Skip to content

Commit c0cbe49

Browse files
authored
Merge pull request #2293 from lidge-jun/codex/windows-restart-helper
scripts: add Windows Codex desktop full-restart helper
2 parents 236e033 + 6c33ea5 commit c0cbe49

3 files changed

Lines changed: 256 additions & 0 deletions

File tree

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# 000 Plan: Windows model-picker full-restart path
2+
3+
## Problem
4+
5+
ocx sync --restart-codex rewrites the Codex catalog JSON and restarts the Codex
6+
app-server (codex.exe app-server). Observed behavior:
7+
8+
- macOS: the desktop app model picker reflects the new catalog right away.
9+
- Windows (stable/beta, MSIX package OpenAI.Codex_26.818.3698.0): the picker
10+
keeps the stale list until the whole desktop app is quit and relaunched.
11+
12+
Local evidence (2026-08-21):
13+
14+
- Desktop UI processes are ChatGPT.exe (Electron shell), installed as MSIX
15+
package family OpenAI.Codex_2p2nqsd0c76g0, start app id (AUMID)
16+
OpenAI.Codex_2p2nqsd0c76g0!App.
17+
- ocx sync --restart-codex matches only codex.exe app-server and
18+
codex-code-mode-host.exe command lines
19+
(src/codex/app-server-processes.ts, isCodexAppServerCommandLine). The
20+
Electron UI is never signalled, so its cached picker survives.
21+
- After the 20:57 sync + restart, codex.exe (PID 8592) started fresh at 20:59
22+
while all ChatGPT.exe UI processes kept their earlier start time, and the
23+
picker still showed only OpenAI models.
24+
25+
Research findings (subagent, bundle inspection of app.asar):
26+
27+
- The renderer fetches model/list and config/read over stdio JSON-RPC into a
28+
TanStack Query cache; there is no filesystem watcher on the catalog file.
29+
- The UI invalidates those queries only on a codex-app-server-initialized
30+
event. On Windows, externally killing the codex.exe child may not produce
31+
that event reliably (hypothesis, untested from inside this session), which
32+
would explain why ocx restart alone does not refresh the picker here while
33+
macOS recovers.
34+
- Official docs say to restart the desktop app after changing model_catalog_json;
35+
no supported refresh hook exists. Known upstream cluster: openai/codex
36+
issues 19694, 26308, 32349, 34487 (desktop picker vs CLI catalog divergence).
37+
- Relaunch must go through MSIX activation (shell:AppsFolder AUMID), not the
38+
exe path under WindowsApps (ACL-restricted, no package identity).
39+
40+
## Scope
41+
42+
IN (audit amendments folded in):
43+
44+
- A supported, documented way to fully restart the Windows Codex desktop app
45+
after a catalog sync: graceful WM_CLOSE first, bounded taskkill /T /F
46+
fallback, relaunch via AUMID. Targets resolve InstallLocation at runtime
47+
via Get-AppxPackage -PackageFamilyName (the family string is NOT a
48+
substring of the install path); only the root ChatGPT.exe whose parent lies
49+
outside the package is selected so taskkill /T cascades to codex.exe and
50+
codex-code-mode-host.exe; the script refuses to kill its own ancestry.
51+
- A GitHub issue on lidge-jun/opencodex recording the platform gap, the beta
52+
caveat, upstream issue links, and the requested UX (sync should offer a full
53+
app restart on Windows). The issue MUST include Version (installed
54+
@bitkyc08/opencodex version) and Operating system fields, which
55+
enforce-issue-quality hard-requires once Client or integration is present;
56+
Reproduction carries the PID/start-time evidence; upstream issues are cited
57+
as related-but-unverified.
58+
59+
OUT:
60+
61+
- Changing ocx sync runtime behavior in this unit (the issue proposes it;
62+
implementation is a later unit).
63+
- Killing processes outside the OpenAI.Codex_2p2nqsd0c76g0 package family.
64+
- Testing the unverified stdio-respawn hypothesis by killing codex.exe from
65+
inside this session (would kill our own host); recorded as an open question
66+
for an external terminal test.
67+
68+
## Work phases
69+
70+
- wp1 (010): add scripts/restart-codex-desktop-app.ps1 with -DryRun/-Force,
71+
graceful-close then bounded forced fallback, relaunch via AUMID; file the
72+
templated GitHub issue; record evidence.
73+
74+
## Accept criteria
75+
76+
- Script -DryRun exits 0 AND lists the specific live root PID(s) it would
77+
stop and the relaunch command, without stopping anything (an exit-0 no-op
78+
does not pass). Focused probe evidence per scripts/AGENTS.md is the real
79+
gate (tsconfig includes only src/); bun x tsc --noEmit still runs as a
80+
no-regression check.
81+
- Issue exists on origin with bug_report template headings.
82+
83+
## Safety notes
84+
85+
- Running the restart from inside a Codex conversation kills that conversation
86+
host app; the script warns and docs say to run it from an external terminal.
87+
- Forced kill is limited to processes whose Path is under the runtime-resolved
88+
InstallLocation. Close-to-tray behavior is explicitly checked: if
89+
CloseMainWindow() only hides the window, the wait expires and the forced
90+
path runs; record observed behavior. Record the PowerShell edition the
91+
probe ran under (Get-AppxPackage differs between 5.1 and 7).
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# 010 wp1: Restart script + issue (diff level)
2+
3+
## NEW: scripts/restart-codex-desktop-app.ps1 (amended per audit)
4+
5+
PowerShell 5.1-compatible script:
6+
7+
- param([switch]$DryRun, [switch]$Force).
8+
- Constants: package family OpenAI.Codex_2p2nqsd0c76g0, AUMID
9+
OpenAI.Codex_2p2nqsd0c76g0!App, process names ChatGPT, codex,
10+
codex-code-mode-host.
11+
- Resolve $installLoc = (Get-AppxPackage -PackageFamilyName
12+
OpenAI.Codex_2p2nqsd0c76g0).InstallLocation at runtime; fail with an
13+
actionable message when empty. Wrap process Path access in try/catch
14+
(Access denied for other users processes).
15+
- Select ONLY the root ChatGPT.exe whose ParentProcessId lies outside
16+
$installLoc (Win32_Process via Get-CimInstance). taskkill /PID <root> /T /F
17+
cascades to codex.exe and its codex-code-mode-host.exe child. Never list
18+
code-mode-host as an independent target.
19+
- Self-kill guard: walk $PID ancestry; abort with a clear message when any
20+
selected target is in it.
21+
- Warn: active Codex turns are interrupted; run from an external terminal.
22+
- Graceful pass: CloseMainWindow() on the process with a MainWindowHandle,
23+
wait up to 15 s in 1 s polls for all targets to exit. If the process
24+
survives past the timeout, print that close-to-tray behavior is suspected
25+
before escalating.
26+
- Forced pass (remaining targets, or immediately with -Force):
27+
taskkill /PID <id> /T /F per remaining PID (/T covers child tree so
28+
codex.exe is not orphaned).
29+
- Relaunch: Start-Process "shell:AppsFolder\<AUMID>" unless -DryRun.
30+
- -DryRun: print planned actions (targets, method, relaunch command), touch
31+
nothing, exit 0.
32+
33+
## MODIFY: none (runtime untouched in this unit)
34+
35+
## Verification
36+
37+
## Cycle 2 addendum (2026-08-21, provider verification + push)
38+
39+
- command-code stealth/ox-alpha re-probed after credit purchase: /v1/chat/completions
40+
and /v1/responses both return 200 with valid completions. No code change needed.
41+
- opencode-go upstream (https://opencode.ai/zen/go/v1) returns 500 Internal server
42+
error for every model probed directly (kimi-k2.7-code, ox-alpha-free); the proxy
43+
502 "upstream stream ended" is an upstream outage, not an adapter defect.
44+
ox-alpha-free is also absent from models.dev opencode-go roster and from
45+
scripts/model-metadata.source.json, so the opencode-go/ox-alpha-free slug was
46+
never a registered catalog model; opencode-free/x-preview-f-free is the working
47+
free-tier route (verified 200 on both endpoints).
48+
- Direct push to origin/dev rejected by ruleset 20763889 (pull_request rule, admin
49+
bypass = pull_requests_only). Fallback per user intent: branch
50+
codex/windows-restart-helper pushed, PR #2293 opened targeting dev (MERGEABLE).
51+
52+
- powershell -File scripts/restart-codex-desktop-app.ps1 -DryRun -> exit 0
53+
AND output names the live root PID (e.g. 9928) and its child codex.exe;
54+
nothing stopped. Record $PSVersionTable.PSVersion.
55+
- bun x tsc --noEmit -> exit 0.
56+
- gh issue create with bug_report.yml headings: Client or integration = Codex
57+
App; Area = Platform (Windows / macOS / Linux); Version = installed
58+
@bitkyc08/opencodex version (package.json); Operating system = Windows 11
59+
(build from systeminfo); Reproduction includes the 20:57 sync / 20:59 fresh
60+
codex.exe vs stale UI start-time evidence; upstream issues
61+
19694/26308/32349/34487 cited as related-unverified; beta-channel caveat
62+
stated. After creation, re-read state with gh issue view until the
63+
enforce-issue-quality workflow settles (creation alone can auto-close).
Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
#Requires -Version 5.1
2+
<#
3+
.SYNOPSIS
4+
Fully restarts the Windows Codex desktop app (MSIX package) so the model
5+
picker re-reads the on-disk catalog after ocx sync.
6+
.NOTES
7+
Run this from an external terminal. Running it from inside a Codex
8+
conversation kills the app hosting that conversation.
9+
#>
10+
[CmdletBinding()]
11+
param(
12+
[switch]$DryRun,
13+
[switch]$Force
14+
)
15+
16+
$ErrorActionPreference = "Stop"
17+
18+
$PackageFamily = "OpenAI.Codex_2p2nqsd0c76g0"
19+
$Aumid = "OpenAI.Codex_2p2nqsd0c76g0!App"
20+
21+
Import-Module Appx -ErrorAction SilentlyContinue
22+
$pkg = Get-AppxPackage -Name OpenAI.Codex | Where-Object { $_.PackageFamilyName -eq $PackageFamily }
23+
if (-not $pkg -or -not $pkg.InstallLocation) {
24+
Write-Error "MSIX package $PackageFamily was not found; nothing to restart."
25+
exit 1
26+
}
27+
$InstallLoc = $pkg.InstallLocation
28+
29+
$nameFilter = "Name='ChatGPT.exe' OR Name='codex.exe' OR Name='codex-code-mode-host.exe'"
30+
$all = @(Get-CimInstance -ClassName Win32_Process -Filter $nameFilter)
31+
$targets = @($all | Where-Object {
32+
$_.ExecutablePath -and $_.ExecutablePath.StartsWith($InstallLoc, [System.StringComparison]::OrdinalIgnoreCase)
33+
})
34+
35+
if ($targets.Count -eq 0) {
36+
Write-Host "Codex desktop app is not running."
37+
exit 0
38+
}
39+
40+
$targetIds = @{}
41+
foreach ($t in $targets) { $targetIds[[uint32]$t.ProcessId] = $t }
42+
43+
# Roots are targets whose parent is outside the package tree; killing each
44+
# root with taskkill /T cascades to codex.exe and its code-mode-host child.
45+
$roots = @($targets | Where-Object { -not $targetIds.ContainsKey([uint32]$_.ParentProcessId) })
46+
47+
# Self-kill guard: never target our own ancestry. Skipped under -DryRun so the
48+
# report stays useful when Codex itself launched this script.
49+
$ancestry = @{}
50+
if (-not $DryRun) {
51+
$cursor = $PID
52+
while ($cursor) {
53+
$ancestry[[uint32]$cursor] = $true
54+
$parent = (Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$cursor").ParentProcessId
55+
if ($parent -and -not $ancestry.ContainsKey([uint32]$parent)) { $cursor = $parent } else { break }
56+
}
57+
foreach ($r in $roots) {
58+
if ($ancestry.ContainsKey([uint32]$r.ProcessId)) {
59+
Write-Error "Refusing to restart: selected root PID $($r.ProcessId) is an ancestor of this script."
60+
exit 1
61+
}
62+
}
63+
}
64+
65+
Write-Host ("Targets ({0}):" -f $targets.Count)
66+
foreach ($t in $targets) {
67+
Write-Host (" PID {0} {1} parent={2}" -f $t.ProcessId, $t.Name, $t.ParentProcessId)
68+
}
69+
Write-Host ("Root(s) to stop: {0}" -f (($roots | ForEach-Object { $_.ProcessId }) -join ", "))
70+
Write-Host ('Relaunch command: Start-Process "shell:AppsFolder\{0}"' -f $Aumid)
71+
72+
if ($DryRun) {
73+
Write-Host "Dry run: nothing was stopped or launched."
74+
exit 0
75+
}
76+
77+
foreach ($r in $roots) {
78+
$rootPid = [uint32]$r.ProcessId
79+
$stopped = $false
80+
if (-not $Force) {
81+
$proc = Get-Process -Id $rootPid -ErrorAction SilentlyContinue
82+
if ($proc -and $proc.MainWindowHandle -ne 0) {
83+
Write-Host "Sending graceful close to PID $rootPid..."
84+
[void]$proc.CloseMainWindow()
85+
for ($i = 0; $i -lt 15; $i++) {
86+
Start-Sleep -Seconds 1
87+
if (-not (Get-Process -Id $rootPid -ErrorAction SilentlyContinue)) { $stopped = $true; break }
88+
}
89+
if (-not $stopped) {
90+
Write-Host "PID $rootPid survived graceful close (close-to-tray suspected); forcing."
91+
}
92+
}
93+
}
94+
if (-not $stopped) {
95+
Write-Host "Force-stopping process tree at PID $rootPid..."
96+
& "$env:SystemRoot\System32\taskkill.exe" /PID $rootPid /T /F | Out-Null
97+
}
98+
}
99+
100+
Start-Sleep -Seconds 1
101+
Start-Process "shell:AppsFolder\$Aumid"
102+
Write-Host "Codex desktop app restarted."

0 commit comments

Comments
 (0)