cbusillo · cbusillo · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
diff --git a/.github/github.json b/.github/github.json
@@ -24,11 +24,13 @@
       "workspaceNextest": "cd code-rs && cargo nextest run --no-fail-fast --locked",
       "tuiFocused": "cd code-rs && cargo test -p code-tui --features test-helpers",
       "cloudTasksFocused": "cd code-rs && cargo test -p code-cloud-tasks --tests",
-      "mcpTypesFocused": "cd code-rs && cargo test -p mcp-types --tests"
+      "mcpTypesFocused": "cd code-rs && cargo test -p mcp-types --tests",
+      "releaseNotesCheck": "scripts/check-release-notes-version.sh"
     },
     "scripts": {
       "waitForGitHubRun": "scripts/wait-for-gh-run.sh --workflow Release --branch main",
-      "upstreamImport": "just local-upstream-import"
+      "upstreamImport": "just local-upstream-import",
+      "localReleaseNotes": "just local-release-notes"
     },
     "docsRequiredWhen": [
       "CLI behavior changes",

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,14 @@
 
 - (none)
 
+## [0.6.107] - 2026-05-29
+
+- Models: update Claude Opus selector aliases to Claude Opus 4.8 and add coverage for dynamic remote GPT model discovery. (d388ac4b, 7e250da)
+- Auth: refresh ChatGPT tokens before expiry and fix cache fallback plus shutdown completions to reduce stale-auth interruptions. (792bf10c, 4b4c4c9)
+- Core/TUI: keep archived agent activity, visibility, and status isolated across reconnects and same-repo sessions. (d5571d4, ed0ca21, 9c38860)
+- Release: split metadata preparation from final publishing so release PRs stay lightweight while publish runs the full gate. (d599d2f)
+- Docs/CLI: clarify Every Code naming and compatibility policy while cleaning stale package shim and release preflight behavior. (08910f6, 11ed140, f9f522d)
+
 ## [0.6.98] - 2026-05-08
 
 - TUI: add upstream-compatible slash commands, a redesigned session picker, raw scrollback mode, and broader key/input polish. (4b469854, 3b2ebb36, 5e0a4adb, 48402be6)

diff --git a/docs/release-notes/RELEASE_NOTES.md b/docs/release-notes/RELEASE_NOTES.md
@@ -1,21 +1,17 @@
 ## @just-every/code v0.6.107
 
-This release focuses on model freshness, session reliability, and getting the
-release path into better shape ahead of the next model drop.
+This release focuses on model freshness, session reliability, and a smoother release path.
 
-### Highlights
+### Changes
 
-- Updated the built-in Claude Opus selector to Claude Opus 4.8, including alias
-  upgrades for older Opus selector names.
-- Added regression coverage for dynamic remote GPT model discovery, so backend
-  model slugs such as a future GPT-5.6 can appear without requiring another
-  local selector release.
-- Fixed ChatGPT auth fallback behavior, shutdown completions, and token refresh
-  timing to reduce stale-auth interruptions.
-- Tightened session-scoped agent state so archived agent activity, visibility,
-  and status stay isolated across reconnects and same-repo sessions.
-- Split release metadata preparation from final publishing. Release PRs no
-  longer wait on the full preflight and platform matrix, while final publishing
-  still runs the full release gate and platform asset builds.
-- Cleaned up Every Code/CODEX compatibility docs, package shim behavior,
-  release preflight paths, and agent/skill configuration docs.
+- Updated the built-in Claude Opus selector to Claude Opus 4.8 and added coverage for dynamic remote GPT model discovery.
+- Fixed ChatGPT token refresh, auth fallback, and shutdown completions to reduce stale-auth interruptions.
+- Kept archived agent activity, visibility, and status isolated across reconnects and same-repo sessions.
+- Split release metadata preparation from final publishing so release PRs stay lightweight while publish runs the full gate.
+- Cleaned up Every Code/CODEX compatibility docs, package shim behavior, release preflight paths, and agent/skill configuration docs.
+
+### Install
+
+```bash
+gh release download v0.6.107 --repo cbusillo/code
+```
diff --git a/docs/upstream-import-policy.md b/docs/upstream-import-policy.md
@@ -116,10 +116,12 @@ outside the product branch and must be replayed.
 
 Cut an Every Code release after every successful upstream import or local hotfix
 that should be installed by dogfood users. The active Release workflow runs from
-`main`, opens a release metadata PR when the package version or notes need to be
-updated, and publishes GitHub Release assets after that metadata lands. Metadata
-preparation builds only the Linux x86_64 binary needed for changelog generation;
-the full preflight, macOS/Linux release matrix, and Windows asset build run on
+`main` and publishes GitHub Release assets only after release metadata has
+landed. Prepare that metadata locally with the Every Code harness before the
+publish run: the local command bumps `codex-cli/package.json`, updates
+`CHANGELOG.md`, and writes `docs/release-notes/RELEASE_NOTES.md`. The workflow
+validates those files and stops instead of generating fallback notes in CI.
+The full preflight, macOS/Linux release matrix, and Windows asset build run on
 the publish pass after the metadata PR has merged.
 
 Release tags use the plain `v<version>` format, for example `v0.6.101`.
@@ -143,6 +145,16 @@ Run `just local-code-rebuild` after any release-readiness `./build-fast.sh` run:
 the fast build creates dev-fast artifacts for validation, while the rebuild
 recipe owns the PATH-resolved release binary and embeds the package version.
 
+Generate and review release metadata before pushing the release PR:
+
+```sh
+just local-release-notes
+scripts/check-release-notes-version.sh
+```
+
+Commit the resulting `codex-cli/package.json`, `CHANGELOG.md`, and
+`docs/release-notes/RELEASE_NOTES.md` changes on a release metadata branch.
+
 If an old manual Homebrew link exists, remove it so PATH resolution stays
 repo-owned and predictable:
 
@@ -180,8 +192,8 @@ target cache buckets, and release dependency cache. It preserves
 Run without `--apply` to preview deletions. Use `--keep-release-cache` only when
 you intentionally want to preserve release dependency cache as well.
 
-Then push the product branch to `origin`, open or merge the release metadata PR,
-and monitor the `Release` workflow:
+Then push the product branch to `origin`, merge the release metadata PR, and
+monitor the `Release` workflow:
 
 ```sh
 git push origin HEAD

diff --git a/justfile b/justfile
@@ -75,6 +75,10 @@ local-remove-homebrew-code-link:
 local-upstream-import:
     ./scripts/local/update-from-upstream.sh
 
+[no-cd]
+local-release-notes:
+    ./scripts/local/release-notes.sh
+
 [no-cd]
 local-product-health:
     ./scripts/local/fork-health.sh

diff --git a/scripts/check-release-notes-version.sh b/scripts/check-release-notes-version.sh
@@ -4,34 +4,83 @@ set -euo pipefail
 SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
 REPO_ROOT="${SCRIPT_DIR}/.."
 
+expected_version=""
+while [ "$#" -gt 0 ]; do
+	case "$1" in
+	--version)
+		shift
+		expected_version="${1:-}"
+		;;
+	--version=*)
+		expected_version="${1#--version=}"
+		;;
+	-h | --help)
+		echo "Usage: scripts/check-release-notes-version.sh [--version X.Y.Z]"
+		exit 0
+		;;
+	*)
+		echo "unknown argument: $1" >&2
+		exit 2
+		;;
+	esac
+	shift || true
+done
+
 notes_file="${REPO_ROOT}/docs/release-notes/RELEASE_NOTES.md"
 pkg_json="${REPO_ROOT}/codex-cli/package.json"
 
 if [ ! -f "$notes_file" ]; then
-  echo "release notes file missing: $notes_file" >&2
-  exit 1
+	echo "release notes file missing: $notes_file" >&2
+	exit 1
 fi
 
 if [ ! -f "$pkg_json" ]; then
-  echo "package.json missing: $pkg_json" >&2
-  exit 1
+	echo "package.json missing: $pkg_json" >&2
+	exit 1
 fi
 
 package_version=$(jq -r '.version // empty' "$pkg_json")
 
 if [ -z "$package_version" ]; then
-  echo "Failed to read version from $pkg_json" >&2
-  exit 1
+	echo "Failed to read version from $pkg_json" >&2
+	exit 1
+fi
+
+if [ -n "$expected_version" ] && [ "$package_version" != "$expected_version" ]; then
+	echo "package version mismatch" >&2
+	echo "  expected: $expected_version" >&2
+	echo "  actual:   $package_version" >&2
+	echo "Run 'just local-release-notes' before publishing this release." >&2
+	exit 1
 fi
 
 expected_header="## @just-every/code v${package_version}"
 actual_header=$(grep -m1 '^## @just-every/code v' "$notes_file" || true)
 
 if [ "$actual_header" != "$expected_header" ]; then
-  echo "release notes header mismatch" >&2
-  echo "  expected: $expected_header" >&2
-  echo "  actual:   ${actual_header:-<none>}" >&2
-  exit 1
+	echo "release notes header mismatch" >&2
+	echo "  expected: $expected_header" >&2
+	echo "  actual:   ${actual_header:-<none>}" >&2
+	echo "Run 'just local-release-notes' before publishing this release." >&2
+	exit 1
+fi
+
+if grep -qF "See CHANGELOG.md for details." "$notes_file"; then
+	echo "release notes still contain the fallback stub" >&2
+	echo "Run 'just local-release-notes' to generate reviewed local notes." >&2
+	exit 1
+fi
+
+if ! grep -qF "## [${package_version}]" "${REPO_ROOT}/CHANGELOG.md"; then
+	echo "CHANGELOG.md is missing release entry ## [${package_version}]" >&2
+	echo "Run 'just local-release-notes' before publishing this release." >&2
+	exit 1
+fi
+
+if ! grep -qF "### Changes" "$notes_file"; then
+	echo "release notes are missing the required ### Changes section" >&2
+	echo "Run 'just local-release-notes' before publishing this release." >&2
+	exit 1
 fi
 
 exit 0
diff --git a/scripts/local/release-notes.sh b/scripts/local/release-notes.sh
@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" >/dev/null 2>&1 && pwd)"
+REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." >/dev/null 2>&1 && pwd)"
+
+cd "$REPO_ROOT"
+
+if ! command -v code >/dev/null 2>&1; then
+	echo "the 'code' command is required; run 'just local-code-rebuild' first" >&2
+	exit 1
+fi
+
+if ! git diff --quiet -- codex-cli/package.json CHANGELOG.md docs/release-notes/RELEASE_NOTES.md ||
+	! git diff --cached --quiet -- codex-cli/package.json CHANGELOG.md docs/release-notes/RELEASE_NOTES.md; then
+	echo "release metadata files have uncommitted changes; commit or stash them first" >&2
+	exit 1
+fi
+
+current_version=$(jq -r '.version // empty' codex-cli/package.json)
+latest_tag=$(git tag --list 'v*' --sort=-v:refname | head -n 1 | sed 's/^v//' || true)
+latest_tag="${latest_tag:-0.0.0}"
+new_version=$(printf '%s\n%s\n' "$current_version" "$latest_tag" | sort -V | tail -n1)
+
+if git rev-parse "v${new_version}" >/dev/null 2>&1; then
+	IFS='.' read -r major minor patch <<<"$new_version"
+	new_version="${major}.${minor}.$((patch + 1))"
+fi
+
+while git rev-parse "v${new_version}" >/dev/null 2>&1; do
+	IFS='.' read -r major minor patch <<<"$new_version"
+	new_version="${major}.${minor}.$((patch + 1))"
+done
+
+prev_tag="v${latest_tag}"
+if ! git rev-parse "$prev_tag" >/dev/null 2>&1; then
+	base=$(git rev-list --max-parents=0 HEAD | tail -n1)
+	range="$base..HEAD"
+	prev_tag="none"
+else
+	range="$prev_tag..HEAD"
+fi
+
+date_utc=$(date -u +%Y-%m-%d)
+mkdir -p docs/release-notes .code/release-notes
+context_file=".code/release-notes/context-v${new_version}.md"
+prompt_file=".code/release-notes/prompt-v${new_version}.md"
+
+{
+	echo "# Commit log (${range})"
+	git log --no-color --format='* %h %s (%an)' --abbrev=8 --no-merges "$range"
+} >"$context_file"
+
+cat >"$prompt_file" <<PROMPT
+You are the Every Code agent preparing local release metadata.
+
+Inputs
+- Version: v${new_version}
+- Date (UTC): ${date_utc}
+- Previous tag: ${prev_tag}
+- Commit range: ${range}
+- Working directory: ${REPO_ROOT}
+
+Primary Tasks
+1. Update codex-cli/package.json to version ${new_version}.
+2. Update CHANGELOG.md with a new entry for this version using the exact house style below.
+3. Generate GitHub release notes at docs/release-notes/RELEASE_NOTES.md.
+
+CHANGELOG.md House Style
+- File header stays as-is. Do not rewrite older sections.
+- Insert the new section at the top, above older released versions and below Unreleased, with this header exactly:
+  ## [${new_version}] - ${date_utc}
+- Synthesize the notable user-visible features, important fixes, UX improvements, performance/stability work, and release-operator changes.
+- Ignore internal chores, merge commits, and minor refactors unless they directly affect users, installation, or release operators.
+- Use judgment on length: keep the changelog compact and scannable, do not pad thin releases, and do not omit important distinct changes from busy releases.
+- Keep each bullet concise, single-line, and present tense.
+- Start bullets with a short scope label when helpful, such as "TUI:", "CLI:", "Core:", "Release:", or "Docs:".
+- End each bullet with abbreviated commit SHA(s) in parentheses, using 7-8 hex chars, comma-separated when multiple.
+- Map changes from the git log in ${range}; ignore pure chores/merges unless they affect users or release operators.
+- Do not add links, tables, code blocks, subheadings, or PR author attributions in the changelog.
+- Idempotent: if a section for ${new_version} already exists, replace only that section body and keep the header intact.
+
+Release Notes
+- Write exactly these sections in order:
+  1. Title: ## @just-every/code v${new_version}
+  2. One brief intro sentence.
+  3. Section header: ### Changes
+     - Curate the most interesting release highlights for readers of a GitHub release page.
+     - Prioritize notable features, important fixes, UX improvements, performance/stability wins, and release-operator changes.
+     - Right-size the list to the release: one or two bullets is fine for tiny releases, a normal release should usually fit in a handful, and a larger release can use more when each item is distinct and useful.
+     - Do not pad with chores or exhaustively restate the commit log.
+     - Rewrite for readability and impact; bullets do not need to match the changelog verbatim.
+     - Omit SHAs, links, tables, PR numbers, and author attributions.
+  4. Section header: ### Install
+     Code block with exactly:
+     gh release download v${new_version} --repo cbusillo/code
+- Optional final line only when a previous tag exists:
+  Compare: https://github.com/cbusillo/code/compare/${prev_tag}...v${new_version}
+- Do not include "See CHANGELOG.md for details.".
+- Keep notes concise. Do not add sections other than those listed above.
+
+Rules
+- Use the provided git log as source of truth and inspect the repo when commit messages are unclear.
+- Basic markdown only. No emojis.
+- Do not commit. Leave the working tree changes for review.
+- After editing, run scripts/check-release-notes-version.sh --version ${new_version} and fix any validation failures.
+
+Context follows:
+PROMPT
+cat "$context_file" >>"$prompt_file"
+
+echo "Preparing local release metadata for v${new_version} from ${range}"
+echo "Prompt: $prompt_file"
+code exec --cd "$REPO_ROOT" --full-auto --skip-git-repo-check <"$prompt_file"
+scripts/check-release-notes-version.sh --version "$new_version"
+
+echo "Local release metadata is ready for review:"
+echo "  codex-cli/package.json"
+echo "  CHANGELOG.md"
+echo "  docs/release-notes/RELEASE_NOTES.md"