update-codex

name	update-codex
description	Use when updating this codex-app Linux port from the latest upstream Codex Mac DMG, preserving local Linux patches, installing the refreshed desktop app, and publishing the tag-driven Linux release artifacts.

Update Codex

Use this skill only from /home/amwill/Applications/codex-app.

Contract

• Fetch the latest official upstream Mac artifact from the newest enclosure in https://persistent.oaistatic.com/codex-app-prod/appcast.xml; current feeds may provide a versioned Codex-darwin-arm64-<version>.zip rather than a DMG.
• Verify latest version/build against https://persistent.oaistatic.com/codex-app-prod/appcast.xml.
• Refresh desktop/recovered/app-asar-extracted from the downloaded artifact's Contents/Resources/app.asar using --app-asar, or from a DMG using --dmg when the feed/source provides one.
• Match the Linux codex helper to the CLI version bundled by that exact upstream desktop artifact. Replace desktop/resources/bin/linux-x64/codex from OpenAI's matching @openai/codex@<version>-linux-x64 npm artifact and keep desktop/package.json codexCliVersion equal to the executable's reported version. Never update only the metadata or only the binary.
• Preserve Linux behavior patches in desktop/scripts/assemble-codex-runtime.mjs, especially:
  • Linux hidden titlebar/titlebar overlay path.
  • Linux native menu hide/remove behavior.
  • Linux external browser routing for auth and plugin/app flows.
  • Linux open-in target registry and browser-session launcher.
  • Linux pet/avatar overlay stability patches, including the X11/XWayland desktop launch contract required for reliable dragging and always-on-top behavior under GNOME Wayland sessions. The top-enforcement timer must not call showInactive() while the pet window is focused, or the pet reply input can lose keyboard focus. On Linux the pet window must remain focusable and treat an active reply editor as keyboard-interactive, so keystrokes go to the pet instead of the previously focused app.
  • Linux pet/avatar overlay hit testing: drag must start only from the [data-avatar-mascot="true"] target. Do not use Linux pointer passthrough for the pet window; on this Electron/X11 path it prevents hover/click state from reaching the pet, hiding reply controls and breaking drag.
  • Linux pet/avatar activity bubble sizing: preserve the enlarged tray layout, padding, compact message wrapping, and taller compact body height in the current avatar-overlay-page-* bundle. Do not merge or replay old one-off PR bundle edits over the current recovered bundle; keep this as a first-class assembler patch.
• Install the rebuilt runtime to ~/.local/opt/codex-desktop/<version>-<build> and repoint ~/.local/opt/codex-desktop/current.
• If the user asks to ship/release, commit, push main, tag v<version>, and wait for .github/workflows/linux-release.yml to publish assets.

Workflow

1. Download and verify:

   • Download appcast.xml and use the first item as the newest arm64 release.
   • Download that item's full enclosure URL, usually a versioned Codex-darwin-arm64-<version>.zip.
   • Extract or inspect the artifact enough to confirm Info.plist CFBundleShortVersionString/CFBundleVersion and app.asar hash.

2. Refresh recovered bundle:

   • For current zip artifacts, extract Codex.app/Contents/Resources/app.asar and run desktop/scripts/refresh-recovered-from-dmg.mjs --app-asar <path-to-app.asar> --output ./recovered/app-asar-extracted from desktop.
   • For DMG artifacts, run desktop/scripts/refresh-recovered-from-dmg.mjs --dmg ../Codex.dmg --output ./recovered/app-asar-extracted from desktop.
   • Update desktop/package.json, desktop/package-lock.json, and tests that pin version/build metadata.
   • Determine the upstream bundled CLI version, fetch the exact official @openai/codex@<version>-linux-x64 npm artifact, replace desktop/resources/bin/linux-x64/codex, preserve executable mode, and confirm it prints codex-cli <version>.
   • Set desktop/package.json codexCliVersion to that verified version and refresh the lockfile. Do not infer the CLI version from the desktop app version.
   • If minified bundle shapes drift, add new patch alternatives without removing older supported shapes.

3. Verify patch preservation:

   • node --check desktop/scripts/assemble-codex-runtime.mjs
   • npm test -- --runInBand tests/linux/recovered-bundle.red.test.ts
   • npm run test:linux
   • npm run test:linux:codex-package
   • desktop/resources/bin/linux-x64/codex --version must exactly match desktop/package.json codexCliVersion.

4. Build and install:

   • Build with desktop/scripts/build-codex-linux-runtime.mjs into desktop/out/Codex-linux-x64-codex-<version>-<build>.
   • Run desktop/scripts/verify-linux-package-contract.mjs --package-root desktop/out/Codex-linux-x64-codex-<version>-<build> before installing; this must execute the packaged helper and validate the app-server protocol markers.
   • Copy that staged runtime to ~/.local/opt/codex-desktop/<version>-<build>.
   • Update ~/.local/opt/codex-desktop/current.
   • Validate desktop entries and refresh the desktop database.
   • Confirm ~/.local/share/applications/codex-desktop.desktop and ~/.config/autostart/codex-desktop.desktop launch through /usr/bin/env ELECTRON_OZONE_PLATFORM_HINT=x11 ... --ozone-platform=x11.
   • Confirm packaged Linux launchers keep that same X11 contract: desktop/assets/linux/codex-deb.desktop.ejs, desktop/assets/linux/codex-appimage.desktop, and the RPM maker's desktopTemplate setting in desktop/forge.config.ts.

5. Verify installed app:

   • readlink -f ~/.local/opt/codex-desktop/current
   • Read installed resources/app.asar package metadata and confirm version/build.
   • Search installed app.asar for preserved Linux patch markers.
   • After relaunch, inspect the live process and confirm the Codex command line includes --ozone-platform=x11; this is required before judging pet drag or z-order behavior.

6. Release when requested:

   • Commit with a Conventional Commit, usually chore: refresh linux port to <version>.
   • Push main.
   • Create and push annotated tag v<version>.
   • Watch the Linux release workflow to success.
   • Verify release assets include:
     • codex-app-linux-x64-v<version>.AppImage
     • codex-app-linux-x64-v<version>.deb
     • codex-app-linux-x64-v<version>.rpm
     • codex-app-linux-arm64-v<version>.deb

Notes

• The repo currently has no Arch-package release lane. Do not claim one shipped unless the workflow has been extended and verified.
• Downloaded upstream artifacts, desktop/tmp, and desktop/out are generated inputs/outputs; do not commit them unless the repo policy changes.
• If GitHub says release not found immediately after tag push, watch the workflow. The release is created by the tag-driven workflow after artifacts publish.