OpenCodex
-Starting OpenCodex…
+
+
+
+
+ OpenCodex
+Starting OpenCodex…
-
+
+
+
-
+
+ Details
+A runtime is already listening. Take it over?
- Port @@ -63,7 +120,7 @@
OpenCodex
+
@@ -137,11 +194,25 @@ OpenCodex update
+
+
+
+
+
+
+
+
diff --git a/devlog/_fin/260923_release_2_64/000_plan.md b/devlog/_fin/260923_release_2_64/000_plan.md
new file mode 100644
index 00000000000..579ec410cb8
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/000_plan.md
@@ -0,0 +1,68 @@
+# 260923 release 2.64 — plan
+
+## Objective
+
+Ship the verified `dev` tree as preview `2.64.0-preview.20260923` and stable `2.64.0`
+after closing the two items that kept the previous readiness answer at "not yet":
+
+1. The critical Dependabot alert on `desktop/src-tauri` (GHSA-c9pr-q8gx-3mgp,
+ `tauri-plugin-shell` below 2.2.1).
+2. Missing security-review records for the CI, release and account-routing changes
+ merged by the parallel batch (#5471, #5456, #5653, #5469, #5024, #5654, #5655).
+
+The owner authorized PR creation, admin squash merges to `dev`, promotion merges to
+`main` and `preview`, and release dispatch for this round.
+
+## Starting state (2026-09-23 07:50Z)
+
+| Ref | Commit | Version | Evidence |
+|---|---|---|---|
+| `dev` | `fa81e5a2a7` | 2.64.0 in all four version sources | lane=all run 35828289232, every job success, privacy gate skipped by design |
+| `main` | `96b1406cb6` | 2.63.0 | npm `latest`, release v2.63.0 |
+| `preview` | `5bec58cdda` | 2.63.0-preview.20260923 | npm `preview` |
+| Dependabot #5525 | `d6dea8f246` (base `main`) | tauri-plugin-shell =2.2.1 | applies to `dev` cleanly, merge tree `11d41e0b70` |
+
+Open Dependabot alerts on `desktop/src-tauri/Cargo.lock`: critical `tauri-plugin-shell`,
+medium `serde_with`, `time`, `glib`. Only the critical one is in scope. `glib` 0.20
+needs a GTK binding upgrade that the pinned Tauri line does not take; `serde_with` and
+`time` are transitive and are recorded as residuals for a later dependency round.
+
+## Constraints
+
+- No local test, typecheck, build, install, cargo or ocx run. Hosted CI at the exact
+ head is the only execution evidence. Helper scripts that read state (version-source
+ check, merge-tree, gh reads) or rewrite the four version sources
+ (`release-version-sources.ts sync`) are allowed; neither executes the product.
+- Skipped, cancelled, missing or older-head results are not success. A Windows job that
+ fails once on a known runner stall is rerun once; a repeat is a defect.
+- No timeout increase, platform skip, weakened assertion, or ratchet cap raise.
+- Security analysis stays in scratch space outside this repository's tracked tree. This
+ unit records only that each review happened and how findings were dispositioned.
+- Pushes use `--no-verify`; merges use `--admin` with `--match-head-commit`.
+
+## Work-phase map (dependency order)
+
+| Phase | Doc | Consumes | Produces |
+|---|---|---|---|
+| wp1 | this unit | current state | locked roadmap |
+| wp2 | [010](010_wp2_prerelease_items.md), [011](011_wp2_privacy_gate_complement.md), [012](012_wp2_request_owned_main_cursor.md) | wp1 | `tauri-plugin-shell` 2.2.1 on `dev`; review records; fixes for the two confirmed findings |
+| wp3 | [020](020_wp3_dev_candidate.md) | wp2's final `dev` SHA | fixed candidate SHA with a fully green lane=all run |
+| wp4 | [030](030_wp4_release.md) | wp3's candidate | dev pre-move, promotions, both releases, channel verification |
+
+Each phase closes with something checkable from GitHub alone: a merged PR with its
+exact-head run, a dev run ID, release run IDs and registry state.
+
+## Verifiers
+
+| Script (scratch) | Reads | Proves |
+|---|---|---|
+| `check-wp1.sh` | this unit | numbered docs, no private review detail, no absolute user paths |
+| `check-wp2.sh` | PRs, `origin/dev`, Dependabot API | the three wp2 PRs merged at their verified heads with green exact-head runs, `Cargo.toml` pins `=2.2.1` on `dev`, review and second-review reports present |
+| `check-wp3.sh` | the candidate run | every job `success` except the privacy gate skip, run head equals candidate |
+| `check-wp4.sh` | npm registry, GitHub releases, `latest.json` | channel versions, release assets, updater signatures |
+
+## Terminal outcomes
+
+DONE when wp4's verification passes. BLOCKED on a confirmed security blocker that
+cannot be fixed inside this round or on a repeated CI defect. UNSAFE if a release gate
+would have to be bypassed. NEEDS_HUMAN on a policy decision this plan does not cover.
diff --git a/devlog/_fin/260923_release_2_64/010_wp2_prerelease_items.md b/devlog/_fin/260923_release_2_64/010_wp2_prerelease_items.md
new file mode 100644
index 00000000000..d5881da0d30
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/010_wp2_prerelease_items.md
@@ -0,0 +1,86 @@
+# 010 — wp2: pre-release items
+
+## A. tauri-plugin-shell 2.2.1 on dev
+
+Dependabot opened #5525 against `main`, the default branch. `dev` is the integration
+branch, so the same commit is carried to `dev` and reaches `main` through promotion.
+
+Branch `codex/260923-tauri-plugin-shell-2.2.1` from `origin/dev` in a scratch worktree:
+
+```bash
+git fetch origin pull/5525/head:refs/remotes/origin/pr-5525
+git switch -c codex/260923-tauri-plugin-shell-2.2.1 origin/dev
+git cherry-pick -x d6dea8f246944677c8ce80264c66095b562e3deb
+```
+
+Resulting diff (exactly two files, four lines):
+
+```diff
+--- a/desktop/src-tauri/Cargo.toml
++++ b/desktop/src-tauri/Cargo.toml
+-tauri-plugin-shell = "=2.2.0"
++tauri-plugin-shell = "=2.2.1"
+--- a/desktop/src-tauri/Cargo.lock
++++ b/desktop/src-tauri/Cargo.lock
+ name = "tauri-plugin-shell"
+-version = "2.2.0"
++version = "2.2.1"
+ source = "registry+https://github.com/rust-lang/crates.io-index"
+-checksum = "bb2c50a63e60fb8925956cc5b7569f4b750ac197a4d39f13b8dd46ea8e2bad79"
++checksum = "69d5eb3368b959937ad2aeaf6ef9a8f5d11e01ffe03629d3530707bbcb27ff5d"
+```
+
+The lock hunk was produced by the dependency tool, not by hand, and the dependency list
+of the package is unchanged, so no other lock entry moves.
+
+PR to `dev`, filled from the repository template, with a `Co-authored-by` trailer for
+the Dependabot author because the description names the carried PR. Push with
+`--no-verify`, then dispatch the full lane on the PR branch:
+
+```bash
+gh workflow run ci.yml --ref codex/260923-tauri-plugin-shell-2.2.1 -f lane=all
+```
+
+A pull-request event alone would also run `desktop shell` (`desktop/**` matches both the
+`ci` and `native` filters in `.github/workflows/ci.yml`), but the dispatched lane=all run
+also builds the macOS bundle and the widget, which link the same crate graph.
+
+Acceptance:
+
+- `desktop shell` (`cargo fmt --check`, `cargo clippy -D warnings`, `cargo test`),
+ `platform-macos` and `widget` jobs succeed at the exact PR head in the lane=all run,
+ and the `ci` aggregate succeeds.
+- Merge with `gh pr merge --admin --squash --match-head-commit ` after a clean
+ `git merge-tree` against the current `origin/dev`.
+- After merge, `git show origin/dev:desktop/src-tauri/Cargo.toml` pins `=2.2.1`.
+- #5525 is closed with a note once `main` carries the bump (wp4), because Dependabot
+ targets `main` and would otherwise stay open.
+
+## B. Security reviews of the unreviewed batch
+
+`MAINTAINERS.md` asks for explicit security review of changes to GitHub Actions workflows,
+release automation and credential handling. Seven merged PRs had no review record:
+
+| Review | PRs | Surface |
+|---|---|---|
+| S1 | #5471 | PR quality gate script run by a `pull_request_target` workflow |
+| S2 | #5456, #5653 | Bun batch runner; `ci.yml` and `release.yml`, release preflight |
+| S3 | #5469 | privacy-scan gating in `ci.yml` |
+| S4 | #5024, #5654, #5655 | request-owned account routing; remote workspace helper protocol |
+
+Each review is read-only against the merged code on `dev` and is written to scratch
+space, not to this unit. Disposition rules:
+
+- A blocker or major finding counts only after a second, independent reviewer reproduces
+ it from source (file and line, concrete trigger). A finding the second reviewer cannot
+ reproduce is rebutted with the reason recorded in scratch. The second reviewer also
+ states whether the batch introduced it and whether it reaches a release artifact.
+- A confirmed blocker or major gets a focused fix PR to `dev`, designed at diff level in
+ its own numbered doc (011, 012, ...), reviewed the same way and merged at a green exact
+ head before the candidate is fixed in wp3. If a fix cannot be made inside this round,
+ the round stops as BLOCKED rather than releasing. Once a fix has shipped, its doc is the
+ public record; until then the doc describes only the change and its tests.
+- Minor and informational findings are recorded for follow-up and do not gate the release.
+
+This unit's D summary states only which reviews ran and whether any finding gated the
+release; details of an unfixed weakness never enter the tracked tree.
diff --git a/devlog/_fin/260923_release_2_64/011_wp2_privacy_gate_complement.md b/devlog/_fin/260923_release_2_64/011_wp2_privacy_gate_complement.md
new file mode 100644
index 00000000000..1c8dd782d2e
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/011_wp2_privacy_gate_complement.md
@@ -0,0 +1,85 @@
+# 011 — wp2: privacy scan on every pull request that `gates` skips
+
+## Problem
+
+`privacy:scan` runs in two jobs of `.github/workflows/ci.yml`. `gates` runs it on every event
+it runs for, and `gates` is skipped on a pull request whose paths miss the `ci` filter.
+`privacy-gate` covers that gap only when the `privacy` filter matches, and that filter lists
+`devlog/**` and `ci.yml` alone. A pull request touching only paths outside both filters
+(for example `docs-site/**`, `structure/**`, `native/**`, `.github/actions/**`,
+`.github/release.yml`, `.github/CODEOWNERS`, the pull request template, or root markdown
+other than `README.md`) therefore runs no scan, and the `ci` aggregate still concludes
+success.
+
+The gap predates #5469, which closed it for `devlog/**` only. It does not reach an npm or
+GitHub release: `release.yml` requires a push-event `ci.yml` success on the exact release
+SHA, where `gates` scans the whole tree. It does reach GitHub Pages, because
+`deploy-docs.yml` publishes `docs-site` on a `main` push without waiting for that scan.
+
+## Change
+
+Make `privacy-gate` the exact complement of `gates` on pull requests, so the scan's coverage
+stops depending on an enumerated path list. The `privacy` filter then selects nothing and is
+removed with its plumbing.
+
+`.github/workflows/ci.yml`:
+
+```diff
+- privacy:
+- - 'devlog/**'
+- - '.github/workflows/ci.yml'
+```
+
+(with the comment block above it, which describes the removed filter), the `privacy` output of
+`changes`, the `PRIVACY_SCOPE` validation in the `scope` step, and the `CHANGES_PRIVACY` env
+of the aggregate.
+
+```diff
+ privacy-gate:
+ name: privacy gate
+ needs: changes
+- if: github.event_name == 'pull_request' && needs.changes.outputs.ci != 'true' && needs.changes.outputs.privacy == 'true'
++ if: github.event_name == 'pull_request' && needs.changes.outputs.ci != 'true'
+```
+
+```diff
+- privacy=not-requested
+- if [ "$scoped" = not-requested ] && [ "$CHANGES_PRIVACY" = "true" ]; then
+- privacy=requested
+- fi
++ privacy=not-requested
++ if [ "$scoped" = not-requested ]; then
++ privacy=requested
++ fi
+```
+
+The aggregate already sets `scoped=not-requested` exactly when the event is `pull_request`
+and `CHANGES_CI` is not `true`, which is the job's new condition, so both sides keep deriving
+the same expectation. Comments above `privacy-gate` and the aggregate derivation are reworded
+to state the complement rule.
+
+Tests (`tests/ci-workflows/`):
+
+- `ci-privacy-gate.test.ts`: the event × `ci` matrix expects exactly one scanner for every
+ combination: `gates` off pull requests or when `ci` is true, `privacy-gate` otherwise.
+ The executed-aggregate cases cover a docs-only and a no-filter pull request requiring
+ `privacy-gate` success, `skipped`/`failure`/`cancelled` failing by name, and a second
+ scan still rejected when `ci` is true. The filter and malformed-output cases for the removed
+ `privacy` output are replaced by an assertion that no job or step reads it.
+- `ci-review-lanes.test.ts` and any other test that executes the aggregate: a pull request
+ with `CHANGES_CI=false` now requires `privacy-gate`; fixtures are updated to include it,
+ never by loosening the aggregate.
+
+No file-size cap is raised; if a test file would exceed its cap, the new cases move to a
+sibling registered in `scripts/test-layout/layout.json` and
+`tests/fixtures/test-layout-expected.json`. `structure/ops/cross-platform-ci.md` is updated
+where it describes the privacy gate.
+
+## Acceptance
+
+- The PR changes `ci.yml`, so its own pull-request run sets `ci` true and scans in `gates`,
+ not in `privacy gate`. The complement is proven by the executed tests above, which run
+ the checked-in `if:` expressions and aggregate shell.
+- `gates`, `structure gate` (the PR edits `structure/ops/`), and the `ci-privacy-gate` and
+ `ci-review-lanes` tests pass at the exact PR head; the `ci` aggregate succeeds.
+- An independent reviewer confirms that no event loses a scan it had before.
diff --git a/devlog/_fin/260923_release_2_64/012_wp2_request_owned_main_cursor.md b/devlog/_fin/260923_release_2_64/012_wp2_request_owned_main_cursor.md
new file mode 100644
index 00000000000..1a7d29d36f6
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/012_wp2_request_owned_main_cursor.md
@@ -0,0 +1,97 @@
+# 012 — wp2: request-owned main stays out of shared active state
+
+## Problem
+
+Unreleased on `dev` since #5024: a request that carries its own main credential makes the
+stored `main` account an ordinary pool candidate for that request
+(`CodexAccountUsabilityOptions.requestOwnedMainCredential`). #5654 stopped three writes in
+`resolveCodexAccountForThreadDetailed` from recording such a pick as the shared active account,
+through a local `sharesActiveSelection` closure in `src/codex/routing.ts`. The same resolve still
+reaches other writers of shared active state with the request's `selectionOptions`:
+
+| Site | Writer | Path |
+|---|---|---|
+| `src/codex/routing/selection.ts` `pickUnboundStrategyAccount`, round-robin and fill-first/reset-first branches | `rememberActiveCodexAccount` | new unbound session under a non-quota strategy |
+| `src/codex/routing/selection.ts` `applyQuotaAutoSwitch` | shared active write inside the helper (persisted) | default `quota` strategy crossing the switch threshold |
+| `src/codex/routing/selection.ts` `applyFailureFailover` | shared active write inside the helper | failover streak on the active account |
+| `src/codex/routing.ts` priority preemption | `rememberActiveCodexAccount(preempted)` | a higher tier becomes selectable |
+| `src/codex/routing.ts` bound-thread quota re-evaluation | `promoteActiveCodexAccount(cooler)` | bound thread moves to a cooler account |
+| `src/codex/routing.ts` expired transient hold | `promoteActiveCodexAccount(expiredDetour)` | bound thread adopts its detour |
+
+When any of them picks `main` for a request that owns the main credential, later requests that
+do not carry that credential read `main` as the effective (or persisted) active account.
+No credential moves between callers: only the account id is recorded.
+
+## Change
+
+One rule, one helper, applied at every shared-state write reachable from a request-owned
+selection.
+
+`src/codex/routing/selection.ts` exports:
+
+```ts
+/**
+ * A main that is live only through this request's own credential serves this request alone.
+ * Recording it as the shared active account would route later requests through a credential
+ * they do not carry (see CodexAccountUsabilityOptions.requestOwnedMainCredential).
+ */
+export function sharesActiveSelection(
+ accountId: string,
+ selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+ return !(accountId === MAIN_CODEX_ACCOUNT_ID && selectionOptions?.requestOwnedMainCredential === true);
+}
+```
+
+and guards with it:
+
+- `pickUnboundStrategyAccount`: both `if (commitSharedActive)` blocks become
+ `if (commitSharedActive && sharesActiveSelection(picked, selectionOptions))`.
+- `applyQuotaAutoSwitch` and `applyFailureFailover`: every write of shared active state is
+ skipped when `sharesActiveSelection(target, selectionOptions)` is false. The returned account
+ is unchanged, so the request is still served by its own credential.
+
+`src/codex/routing.ts` (1618 lines against a 1626 cap; the change must not grow it past the cap):
+
+- Delete the local `sharesActiveSelection` closure and its comment; import the helper from
+ `./routing/selection`; the three existing call sites pass `selectionOptions`.
+- Add the same condition to the existing `if` guarding `promoteActiveCodexAccount(cooler)`,
+ `promoteActiveCodexAccount(expiredDetour)` and `rememberActiveCodexAccount(preempted)`,
+ editing the condition in place.
+
+Post-response failover (`recordCodexUpstreamOutcome` quota-refusal branches and the account
+exclusion path) promotes `meta.promoteAccountId` or `pickAlternateCodexAccount(...)` without
+request selection options. The implementation traces where `meta.promoteAccountId` is set; if a
+request-owned retry can place `main` there, the same rule is applied by carrying the request's
+ownership into that metadata, and if it cannot, the PR states the reason with file and line.
+
+Thread affinity, round-robin ring bookkeeping and the account that serves the request are
+unchanged.
+
+## Regression tests
+
+`tests/codex-integration/codex-pool-rotation.test.ts` (no file-size cap), next to the existing
+`getEffectiveActiveCodexAccountId` assertions, each resolving through
+`resolveCodexAccountForThreadDetailed` with
+`{ requestOwnedMainCredential: true, isMainAccountTokenLive: () => true }` on a pool whose
+operator-selected active account is a stored account:
+
+- default `quota` strategy with the active account over its switch threshold and `main` the
+ cooler candidate: the request resolves to `main`, while `config.activeCodexAccountId` and
+ `getEffectiveActiveCodexAccountId(config)` still name the operator's account;
+- round-robin and fill-first new sessions whose next pick is `main`: same assertions;
+- control: each scenario without `requestOwnedMainCredential` (stored main live) does move
+ the active account to `main`, proving the new cases are not passing because nothing moves.
+
+Preemption and the bound-thread paths get a case each when the fixture can reach them with a
+request-owned selection; otherwise the PR names why they are unreachable for such a request.
+
+## Acceptance
+
+- The PR's pull-request run executes this file (`src/**` and `tests/**` match the `ci` filter)
+ and every requested job succeeds at the exact head; `file-size ratchet` passes with no cap
+ change.
+- An independent reviewer enumerates every writer of `runtimeActiveCodexAccountId` and
+ `config.activeCodexAccountId` (`git grep -n -E 'rememberActiveCodexAccount|promoteActiveCodexAccount|setActiveCodexAccount|activeCodexAccountId =' -- src`)
+ and confirms each is guarded or unreachable from a request-owned main selection, and that
+ the new tests fail without the change.
diff --git a/devlog/_fin/260923_release_2_64/020_wp3_dev_candidate.md b/devlog/_fin/260923_release_2_64/020_wp3_dev_candidate.md
new file mode 100644
index 00000000000..994ea993d56
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/020_wp3_dev_candidate.md
@@ -0,0 +1,41 @@
+# 020 — wp3: dev candidate
+
+The candidate is the `dev` SHA after wp2's last merge. It is fixed before the version
+pre-move, so the pre-move PR never changes the tree that ships.
+
+Dispatch the full lane on `dev` and bind it to the exact SHA:
+
+```bash
+git fetch origin dev
+CAND=$(git rev-parse origin/dev)
+gh workflow run ci.yml --ref dev -f lane=all
+gh run list --workflow ci.yml --branch dev --event workflow_dispatch --limit 3 \
+ --json databaseId,headSha,status,conclusion
+```
+
+Take the run whose `headSha` equals `CAND`. If `dev` moves before the dispatch resolves,
+the candidate is the run's head, and every later step uses that SHA.
+
+Once the candidate is bound, dispatch the dev pre-move of [030](030_wp4_release.md) §1 so its
+pull request runs its own checks in parallel with the candidate run. The pre-move never changes
+the candidate: the candidate is a fixed SHA, and the pre-move PR is merged only after both its
+own exact-head checks and this run have finished green.
+
+Acceptance: every job of that run has conclusion `success`, except `privacy gate`,
+which is skipped by design on `workflow_dispatch`, and the `ci` aggregate is `success`.
+A job counts at its latest attempt only.
+
+Failure handling:
+
+- A Windows job failing once with a known runner-stall signature (`spawnSync ETIMEDOUT`,
+ a 480 s batch timeout where each file passes alone, `EPERM` on temp cleanup) is rerun
+ once with `gh run rerun --job ` after the run completes.
+- The same case failing twice is a defect: a focused fix PR to `dev`, reviewed, merged at
+ a green exact head, then a new lane=all dispatch on the new candidate.
+- Any non-Windows failure is a defect from the first occurrence.
+
+Runners: the owner's standing instruction for release rounds is that release-path runs get
+the runners and other runs are cancelled by hand, one at a time, never by script. While this
+run and the release runs are active, other queued or in-progress runs are cancelled
+individually after reading each run's workflow, branch and event; runs on `main`, `preview`,
+the candidate run, this round's own PR runs and `Release` runs are never cancelled.
diff --git a/devlog/_fin/260923_release_2_64/030_wp4_release.md b/devlog/_fin/260923_release_2_64/030_wp4_release.md
new file mode 100644
index 00000000000..ff81f5385e6
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/030_wp4_release.md
@@ -0,0 +1,116 @@
+# 030 — wp4: release
+
+Order is fixed by `scripts/version-line.ts` `assertReleasable`: a candidate must strictly
+outrank every existing tag, so the preview of core 2.64.0 is published before the stable
+2.64.0. This is a gate, not a convention: once `v2.64.0` exists, `2.64.0-preview.20260923`
+no longer outranks the tag set and its publish job refuses. Both channels ship the wp3
+candidate tree.
+
+The candidate is the `dev` SHA verified in wp3, taken before the pre-move below. Its four
+version sources already read 2.64.0, so the `main` promotion tree is byte-identical to the
+verified tree and needs no metadata commit (precedent: candidate `a077087b74` was taken
+before the 2.63.0 pre-move #5601).
+
+## 1. Dev pre-move
+
+`release.yml` refuses to publish unless `origin/dev` outranks the release version
+(`version-line.ts assert-ahead`). Move `dev` to 2.65.0 first:
+
+```bash
+gh workflow run dev-version-bump.yml --ref main -f intended-version=2.64.0 -f mode=pre-move
+```
+
+The workflow opens a PR changing only the four version sources to 2.65.0. It is dispatched
+as soon as wp3 binds the candidate, so its checks run alongside the candidate run. Confirm
+the diff is exactly `package.json`, `desktop/src-tauri/tauri.conf.json`,
+`desktop/src-tauri/Cargo.toml` and the `opencodex-desktop` entry of
+`desktop/src-tauri/Cargo.lock`, wait until every requested check at its exact head has
+succeeded, then admin squash merge it with `--match-head-commit`.
+
+## 2. Promotion PRs
+
+Both promotions start at the candidate and merge the branch tip with the `ours` strategy,
+so the promoted tree is exactly the candidate (precedent #5603 and #5602).
+
+```bash
+git switch -c codex/260923-release-preview-2.64.0 "$CAND"
+git merge -s ours --no-edit origin/preview -m "release: promote the verified 2.64.0 preview tree to preview"
+# the only writer of the four version sources (scripts/release-version-sources.ts):
+# package.json "version"
+# desktop/src-tauri/tauri.conf.json "version"
+# desktop/src-tauri/Cargo.toml [package] version
+# desktop/src-tauri/Cargo.lock [[package]] opencodex-desktop version
+bun scripts/release-version-sources.ts sync 2.64.0-preview.20260923
+git commit -am "release: prepare 2.64.0-preview.20260923 version metadata"
+bun scripts/release-version-sources.ts check 2.64.0-preview.20260923
+
+git switch -c codex/260923-release-main-2.64.0 "$CAND"
+git merge -s ours --no-edit origin/main -m "release: promote the verified 2.64.0 tree to main"
+bun scripts/release-version-sources.ts check 2.64.0
+```
+
+Checks before opening: `git diff --stat $CAND codex/260923-release-main-2.64.0` is empty,
+and the preview branch differs from `CAND` only in the four version lines. Push with
+`--no-verify`, open PRs to `preview` and `main` from the template, and merge each with
+`gh pr merge --merge --admin --match-head-commit ` (a merge commit, never squash,
+so the candidate stays an ancestor of both release branches).
+
+Owner steering for this round: merge these two promotion PRs immediately after confirming
+their head and base, while their PR checks are pending. This was done for #5670 and #5671.
+Their release-branch push CI and Service lifecycle runs still gate publication below.
+
+## 3. Release-branch CI
+
+`release.yml` requires, for the exact release SHA:
+
+- a successful `ci.yml` run with event `push` on that branch (a PR run does not qualify);
+- a successful Service lifecycle run, because `package.json` and `desktop/**` changed
+ since the previous tag.
+
+Read each run's jobs at the merge SHA. Failures follow wp3's rerun and defect rules.
+
+## 4. Dispatch
+
+```bash
+gh workflow run release.yml --ref preview -f version=2.64.0-preview.20260923 -f tag=preview \
+ -f expected-sha= -f dry-run=false
+# after the preview release run succeeds:
+gh workflow run release.yml --ref main -f version=2.64.0 -f tag=latest \
+ -f expected-sha= -f dry-run=false
+```
+
+The release preflight fails fast on a version-source mismatch, an existing tag or release,
+an npm version already present, or a tag-ordering violation. A job that fails after npm
+acknowledged publication is completed by re-dispatching with the same version and
+expected SHA plus `resume-after-npm-publish=true`; the version is never republished.
+Other failed jobs are rerun individually.
+
+Push-event CI on `main` and `preview` does not run the Windows shards; the wp3 lane=all
+run is the Windows evidence for this tree, which is why both promotions carry the
+candidate tree unchanged apart from the preview version line.
+
+## 5. Verification
+
+```bash
+curl -s https://registry.npmjs.org/@bitkyc08%2fopencodex # dist-tags.latest / .preview
+gh release view v2.64.0 --json assets,isPrerelease,targetCommitish
+gh release view v2.64.0-preview.20260923 --json assets,isPrerelease,targetCommitish
+curl -sL https://github.com/lidge-jun/opencodex/releases/latest/download/latest.json
+```
+
+Acceptance: `latest` = 2.64.0 and `preview` = 2.64.0-preview.20260923 on npm; both GitHub
+releases exist with the same asset count as v2.63.0 (25); `latest.json` reports 2.64.0
+with a signature for every platform entry. Registry propagation lag is waited out, not
+worked around.
+
+A green release run can still end with registry verification `pending` (the post-publish
+smoke retries six times and then reports pending rather than failing). The release-outcomes
+rows of each run and a direct registry read, not the run conclusion alone, decide the
+channel state.
+
+## 6. Close-out
+
+- Close #5525 with a note that `main` now carries `tauri-plugin-shell` 2.2.1 through the
+ 2.64.0 promotion.
+- Record residual medium alerts (`serde_with`, `time`, `glib`) for a dependency round.
+- D summary in `050_done.md`.
diff --git a/devlog/_fin/260923_release_2_64/050_done.md b/devlog/_fin/260923_release_2_64/050_done.md
new file mode 100644
index 00000000000..8ca96ac2aa7
--- /dev/null
+++ b/devlog/_fin/260923_release_2_64/050_done.md
@@ -0,0 +1,67 @@
+# 050 — 2.64.0 release outcome
+
+## Result
+
+The 2.64.0 release round is complete. The verified `dev` candidate
+`a1131f521b644c09f43c924a615ea48dfca5b607` shipped to both channels.
+
+| Channel | Version | Promotion merge | Release run | npm dist-tag |
+|---|---|---|---|---|
+| preview | 2.64.0-preview.20260923 | `836321b33e` (#5670) | [35843685057](https://github.com/lidge-jun/opencodex/actions/runs/35843685057) | `preview` |
+| stable | 2.64.0 | `4cb43cb0a8` (#5671) | [35847101363](https://github.com/lidge-jun/opencodex/actions/runs/35847101363) | `latest` |
+
+Both release runs completed successfully. Both GitHub releases are public, with 25
+assets each. `releases/latest/download/latest.json` serves `2.64.0` and has a
+signature for each of its five platform entries. Direct npm registry reads after
+propagation reported `latest=2.64.0` and
+`preview=2.64.0-preview.20260923`.
+
+## Pre-release close-out
+
+- Critical desktop dependency update: #5661 merged as `a1131f521b`.
+ `tauri-plugin-shell` is pinned to `=2.2.1` in Cargo.toml and Cargo.lock.
+ The [full-platform branch run](https://github.com/lidge-jun/opencodex/actions/runs/35835959962)
+ finished with 39 successful jobs; a privacy gate skip was expected for dispatch.
+ #5525 closed after the update reached `main`.
+- Privacy scan complement: #5662 merged as `da662a30ee`. A pull request skipped by
+ `gates` now runs the dedicated `privacy gate` job. The exact-head PR CI passed.
+- Request-owned main selection: #5663 merged as `f2e8045140`. A request's own
+ main credential no longer changes shared active-account state. The exact-head
+ PR CI passed after tests were moved to a registered sibling file to satisfy the
+ file-size ratchet.
+- Reviews of #5471, #5456/#5653, #5469 and #5024/#5654/#5655 were performed.
+ The two confirmed findings were fixed in #5662 and #5663 before the candidate
+ was selected. Unreleased review details were kept out of this tracked unit.
+
+## Verification and operations
+
+- The `dev` candidate passed [lane=all run 35840680817](https://github.com/lidge-jun/opencodex/actions/runs/35840680817):
+ 39 successful jobs and the dispatch-only privacy gate skipped as designed.
+- The dev pre-move #5666 merged as `685321e297`, taking `dev` to 2.65.0
+ before either publication. Its PR Cross-platform CI and Service lifecycle passed.
+- The preview promotion's push Cross-platform CI
+ [35843639351](https://github.com/lidge-jun/opencodex/actions/runs/35843639351)
+ and Service lifecycle [35843639372](https://github.com/lidge-jun/opencodex/actions/runs/35843639372)
+ passed on `836321b33e`. The Linux `test 1/4` batch timed out once only when
+ twelve files ran together; the one job passed on its second attempt. All other
+ requested jobs succeeded.
+- The stable promotion's push Cross-platform CI
+ [35843612570](https://github.com/lidge-jun/opencodex/actions/runs/35843612570)
+ and Service lifecycle [35843612468](https://github.com/lidge-jun/opencodex/actions/runs/35843612468)
+ passed on `4cb43cb0a8`.
+- The owner directed the two promotion PRs to merge before their PR checks
+ finished. Their release-branch push checks succeeded before publication,
+ as enforced by `release.yml`.
+- The first preview publish attempt reached its CI gate before the preview push
+ run passed; only the failed publish job was rerun. The stable packaging run
+ started before the preview retry, so it was cancelled to preserve the required
+ preview-before-stable version order, then the stable release was dispatched
+ again. Publication was not repeated for either version.
+- Local tests, typecheck and build: NOT RUN. Hosted CI above is the execution
+ evidence.
+
+## Residuals
+
+Three medium Dependabot alerts remain in the desktop lockfile:
+`serde_with`, `time` and `glib`. They are separate dependency work.
+No release blocker remains from this round.
diff --git a/devlog/_plan/260923_bundle_a_tests_hygiene/000_triage.md b/devlog/_plan/260923_bundle_a_tests_hygiene/000_triage.md
new file mode 100644
index 00000000000..aba50e41518
--- /dev/null
+++ b/devlog/_plan/260923_bundle_a_tests_hygiene/000_triage.md
@@ -0,0 +1,20 @@
+# Lane A — tests hygiene triage
+
+Bundle lane A of the 260923 PR-consolidation round. One branch (codex/260923-bundle-a-tests-hygiene) from origin/dev 685321e297, one commit per carried PR, one PR to dev. Each candidate got a read-only gpt-6-sol soundness review against current dev.
+
+| PR | Author | Verdict | Carry notes |
+|---|---|---|---|
+| #5607 | FredAmartey | CARRY | Translator budgets disposed per test via onTestFinished; module-level afterEach only fires for the first importing file in a shared process. |
+| #5605 | FredAmartey | CARRY-WITH-FIXES | Restore real modules after image-test mock.module overrides. Fix: capture each real module before its first override and restore only captured snapshots (a partial beforeAll must not install an empty module); z-handler-activation restores even if directory cleanup throws. |
+| #5570 | FredAmartey | CARRY | Every test file that pins OPENCODEX_HOME restores the inherited value; commit 2 already folded the CodeRabbit ordering finding. |
+| #5482 | FredAmartey | CARRY | Capture resolveAdapter before mock.module rewrites the live binding (three files). |
+| #5630 | sh940701 | CARRY-WITH-FIXES | Guard the real desktop restart adapter when OCX_TEST_HOME_GUARD=1 and no execFile is injected. Fix: document the armed-test skip and CLI outcome in structure/runtime.md. |
+| #5340 | codingbooo | CARRY-WITH-FIXES | README memory inventory counts derived from registries with a per-locale guard test. Fix: rebuild on dev after #5615 (keep its prose), retained stores are now 14 (native_control_replay is pinned, evictOldest returns 0, so the "all evicted" wording changes), recompute readme/i18n-manifest.json hash from the final README, register the new test in layout.json and test-layout-expected.json. |
+
+## Issue #5439
+
+Part 1 (batched runner cannot run on macOS: GNU timeout, mapfile) is already fixed on dev by #5456 (portable process-group timeout fallback, no mapfile). Part 2 (failure counts depend on batch size) is caused by the cross-file leaks that #5570, #5605 and #5607 fix; tests/server/config.test.ts already restores its cwd. The single-owner spend ledger errors are the intended owned-spend-home contract. The PR references the issue with the evidence; closing is the coordinator's call.
+
+## Verification plan
+
+Focused files per carry, including non-isolated same-process pairs that reproduce the leak (the reviewers' named orderings), then bun run typecheck, bun run structure:check, bun run privacy:scan, tests/test-layout*.test.ts and the file-size ratchet test. No full local suite.
diff --git a/devlog/_plan/260923_bundle_a_tests_hygiene/010_build.md b/devlog/_plan/260923_bundle_a_tests_hygiene/010_build.md
new file mode 100644
index 00000000000..442c4ba771a
--- /dev/null
+++ b/devlog/_plan/260923_bundle_a_tests_hygiene/010_build.md
@@ -0,0 +1,12 @@
+# Lane A — build order
+
+Commits on codex/260923-bundle-a-tests-hygiene, in order, each with the original author's Co-authored-by trailer:
+
+1. #5482 capture resolveAdapter before mocking — Fred Amartey <43480311+FredAmartey@users.noreply.github.com>. Applied as-is.
+2. #5607 per-test translator budget disposal — Fred Amartey. Applied as-is.
+3. #5570 restore inherited OPENCODEX_HOME in every test file — Fred Amartey. Both PR commits squashed into one carry.
+4. #5605 restore real modules after image mocks — Fred Amartey. Fold: snapshot each module before its first override, restore only captured snapshots, and restore in z-handler-activation before the throwable directory cleanup.
+5. #5630 guard the real desktop restart adapter in armed test processes — terin <100397903+sh940701@users.noreply.github.com>. Fold: structure/runtime.md documents the skipped outcome.
+6. #5340 derived README memory inventory counts — codingbo <9621077+codingbooo@users.noreply.github.com>. Rebuilt on dev after #5615: 14 retained stores, pinned-store eviction wording, recomputed readme/i18n-manifest.json hash, new test registered in layout.json and test-layout-expected.json.
+
+Focused proof per commit: the PR's named files plus a non-isolated same-process ordering that reproduced the leak on dev (run before and after where cheap).
diff --git a/devlog/_plan/260923_bundle_a_tests_hygiene/020_delivery.md b/devlog/_plan/260923_bundle_a_tests_hygiene/020_delivery.md
new file mode 100644
index 00000000000..277e294f0ef
--- /dev/null
+++ b/devlog/_plan/260923_bundle_a_tests_hygiene/020_delivery.md
@@ -0,0 +1,11 @@
+# Lane A — delivery
+
+1. gpt-6-sol adversarial review of origin/dev..codex/260923-bundle-a-tests-hygiene; fold or rebut every finding.
+2. Push the branch (no-verify), open one PR to dev from the repository template with Supersedes #5482 #5607 #5570 #5605 #5630 #5340, Refs #5439 with the findings, credit list, verification commands and the environment-only issue-914 note.
+3. Watch exact-head CI; a run cancelled by the 2.64 release coordinator is re-dispatched after the release, never read as a failure.
+4. Final report to the coordinator.
+## Delivery record
+
+- PR #5672 to dev from codex/260923-bundle-a-tests-hygiene; supersedes #5482, #5607, #5570, #5605, #5630 and #5340; refs #5439.
+- Adversarial review: P2 dashboard finding withdrawn (the gap predates this branch for every desktop skip reason, and test_environment only occurs under OCX_TEST_HOME_GUARD=1), P3 EOF nits fixed.
+- Exact-head CI is read from the PR head only; a run cancelled by the 2.64 release coordinator is re-dispatched after the release.
diff --git a/devlog/_plan/260923_bundle_f1_provider_registry/000_overview.md b/devlog/_plan/260923_bundle_f1_provider_registry/000_overview.md
new file mode 100644
index 00000000000..71a994d5109
--- /dev/null
+++ b/devlog/_plan/260923_bundle_f1_provider_registry/000_overview.md
@@ -0,0 +1,7 @@
+# 260923 bundle lane F1 — provider registry
+
+Lane of the 260923 PR lane bundle round (coordinator plan: devlog/_plan/260923_pr_lane_bundle/ in the coordinator worktree). One branch, codex/260923-bundle-f1-provider-registry, cut from origin/dev 685321e297, one PR to dev. Every carry was reviewed by a gpt-6-sol reviewer against current dev before it was rebuilt.
+
+Docs:
+
+- 010_carry_plan.md — per-PR verdicts, carry order, required fixes, exclusions.
diff --git a/devlog/_plan/260923_bundle_f1_provider_registry/010_carry_plan.md b/devlog/_plan/260923_bundle_f1_provider_registry/010_carry_plan.md
new file mode 100644
index 00000000000..1c91b4c0288
--- /dev/null
+++ b/devlog/_plan/260923_bundle_f1_provider_registry/010_carry_plan.md
@@ -0,0 +1,14 @@
+# Carry plan
+
+| Order | Item | Verdict | Commit contents |
+|---|---|---|---|
+| 1 | #5362 cursor composer-2.5-fast external tool continuation | carry with fixes | Route composer-2.5-fast through cursorNeedsExternalToolContinuation; rewrite the contradicting assertions in cursor-blob (at its line cap, so replace, never add), cursor-live-transport and cursor-tool-continuation tests; keep a native resumeAction counterexample (composer-1); cover the clipped-invocation case for fast; update structure/providers/cursor.md. |
+| 2 | #5314 Meta Muse web_search strip for every model id | carry with fixes | Dev already strips search_content_types and indexed_web_access for Contributor ids; extend it to every id on the direct Meta host, including a missing id and the muse-spark-1.3 default; document in structure/transports/responses-wire-shapes.md and correct the "unrelated models" wording; tests in muse-spark-web-search-compat.test.ts (openai-responses-passthrough.test.ts is at its cap). |
+| 3 | #5349 connect deadline for provider artifact downloads | carry with fixes | 10 s connect deadline on the connectPublicHttps production path and a per-call option on pinnedHttpsGet; correct the rationale (a 60 s first-byte timer already exists, the new deadline bounds TCP/TLS setup specifically); document in the owning transport contract; register the new test file in both layout manifests. |
+| 4 | #5188 Alibaba Token Plan Responses wire defaults (closes #5097) | carry with fixes | Default Responses pins for qwen3.8-flash, qwen3.7-plus and glm-5.3 on the Beijing preset for Responses inbound, keeping Chat/Anthropic routing and explicit modelAdapters overrides; fix the glm-5.3 test to assert the Responses default and assert the qwen3.7-plus reasoning.effort payload; rebuild the docs row and layout hunks; update responses-wire-shapes.md. |
+| 5 | #5000 kiro short-name executable fallback | PARTIAL | Security review failed the Unix part: ~/.local/bin, /usr/local/bin and /opt/homebrew/bin are shared directories where an unrelated kiro binary (for example the Kiro IDE launcher) could be run for credential commands. Carry only the Windows fallback to kiro.exe inside the dedicated Kiro-Cli install folders that dev already trusts for kiro-cli.exe, skip it when the base path is not absolute, and keep canonical-name-first order. Not superseded; the original PR stays open. |
+| — | #5147 CodeBuddy roster discovery (#5146) | excluded | codebuddy --help returns the home-logged-in account's roster regardless of the key passed, while the PR caches it under the configured key's hash, so it can advertise another account's models for a key. Needs a way to prove roster and request key belong to the same account first (owner design decision). #5146 stays open; its tool-bridge half is already on dev. |
+
+Residual for the owner: #5362 changes fast routing for every client; the maintainer review asked for one direct Cursor fast tool turn to confirm it still answers. This lane does not spend live Cursor calls.
+
+Verification per commit: focused test files for the touched area and their consumers, then bun run typecheck, bun run structure:check, bun run privacy:scan, layout guards (tests/test-layout.test.ts, tests/test-layout-tooling.test.ts) and the file-size ratchet test. No full local suite (reserved for the owner after all lanes land).
diff --git a/devlog/_plan/260923_bundle_f1_provider_registry/020_delivery.md b/devlog/_plan/260923_bundle_f1_provider_registry/020_delivery.md
new file mode 100644
index 00000000000..b404ae54a3b
--- /dev/null
+++ b/devlog/_plan/260923_bundle_f1_provider_registry/020_delivery.md
@@ -0,0 +1,6 @@
+# Delivery
+
+1. Adversarial gpt-6-sol review of the whole branch and a security re-review of the rebuilt #5000 commit. Fold every accepted finding as a follow-up commit; record rebuttals in the PR.
+2. Push codex/260923-bundle-f1-provider-registry and open one PR to dev with the repository template: Summary, Verification (exact focused commands and counts, full suite not run by owner instruction), Checklist, Closes #5097, Supersedes lines for the fully carried PRs (#5362, #5314, #5349, #5188), #5000 listed as partial (not superseded), #5147 and #5146 listed as excluded with the reason, and every Co-authored-by credit.
+3. Watch exact-head CI. A run cancelled by the 2.64 release coordinator is re-dispatched after the release; real failures are fixed on the branch.
+4. Final report to the coordinator.
diff --git a/devlog/_plan/260923_bundle_lane_e/000_overview.md b/devlog/_plan/260923_bundle_lane_e/000_overview.md
new file mode 100644
index 00000000000..b2582aaf0ae
--- /dev/null
+++ b/devlog/_plan/260923_bundle_lane_e/000_overview.md
@@ -0,0 +1,5 @@
+# 260923 bundle lane E — responses/combo
+
+Lane E of the coordinator round devlog/_plan/260923_pr_lane_bundle (coordinator task 01a0cda3-22de-7680-b771-f5338e65ec57). Task 01a0cdb0-b76c-7511-a70f-3bdee1788dc1, worktree .codex/worktrees/0ba7, branch codex/260923-bundle-e-responses-combo from origin/dev 685321e297. One branch, ordered commits, one PR to dev.
+
+Docs: 010_decisions.md (per-candidate verdict and carry order), 020_carry.md (commit plan with fixes folded from gpt-6-sol soundness reviews), 030_verify.md (focused tests and gates).
diff --git a/devlog/_plan/260923_bundle_lane_e/010_decisions.md b/devlog/_plan/260923_bundle_lane_e/010_decisions.md
new file mode 100644
index 00000000000..80f4f4c7eca
--- /dev/null
+++ b/devlog/_plan/260923_bundle_lane_e/010_decisions.md
@@ -0,0 +1,20 @@
+# Decisions
+
+Soundness reviews by gpt-6-sol reviewers, notes in the lane worktree .tmp/lane-e/review-*.md (scratch, not committed). Every PR merges cleanly into dev, and the cumulative stack simulates cleanly with git merge-tree. Carry order is 5629 -> 5659 -> 5646 -> 5633 -> 5489: #5646 first so the WebSocket row #5633 adds is never exposed to the 2xx third-send gap.
+
+| Item | Verdict | Decision |
+|---|---|---|
+| #5629 Devin approximate retry delays | SOUND-WITH-FIXES | Carry; fix the stale "~ prevents re-parsing" comment in src/adapters/devin/cloud-direct/chat.ts and reject a repeated approximation marker (retry after ~1 minute ~30 seconds) with a negative parser case. |
+| #5659 code-mode goal helpers | SOUND-WITH-FIXES | Carry; add the original guard-input assertion, an unrelated-name rejection and bare-goal precedence case; update stale authorization comments in src/types/tools.ts. Closes #5495. |
+| #5646 stop failover once the replacement is spent | SOUND-WITH-FIXES (pair) | Carry first of the pair. Closes the shared resend-safety gap (CodeRabbit's #5633 2xx finding). |
+| #5633 WebSocket retryOnReset replacement | SOUND-WITH-FIXES (pair); UNSOUND alone | Carry after #5646; drop the duplicate settleOperatorReplacement import in passthrough-dispatch.ts; rewrite structure/transports/responses-failover.md so the 2xx gap reads as settled. Partial for #4191 (not in this lane's list; not claimed). |
+| #5489 undeclared zero-output tool failover | UNSOUND as submitted, salvageable | Carry with fix: non-streaming classification must not hop after a replayUnsafe heartbeat; add a non-streaming E2E proving no second dispatch; sync structure/runtime.md, structure/transports/responses-failover.md. Covers only the Responses path of #5407, so #5407 stays open. |
+| #5221 sub-agent own-model identity | UNSOUND | Exclude. Routed raw-body repair never personalizes the neutral catalog line, native parent -> routed worker stays wrong, fenced identity sentences can be rewritten, new test is unregistered. |
+| #5217 | not fixable in bounded effort | Exclude; needs a destination-aware identity design across catalog, parser and passthrough. |
+| #5494 DeepSeek combo adapter_eof | NEEDS-REPRO | Exclude. Current dev already hops a zero-output adapter_eof; the final 502 and cooldown 503 follow existing rules; wire capture needed to separate upstream truncation from a relay/adapter terminal loss. |
+| #5369 responses-state spill growth | not a defect | Exclude. Reporter's own re-measure stays under the 1 GiB / 1000-entry / 24 h bounds; the remaining unreferenced-file footprint is a design question for snapshot-omitted in-memory owners. |
+
+
+## Closure claims (audit fold)
+
+The PR says Closes #5495 only. #5407 (Responses path covered, Claude Code/Anthropic path not), #5217 and #4191 are not claimed. Listed issues #5407 and #5217 are reported to the coordinator as unfixed with findings, as the lane packet allows ("fixed ... or excluded with findings"). Supersede claims: #5629, #5659, #5646, #5633 and #5489 are superseded only when their whole net contribution is on the branch; #5489 is carried whole (its issue coverage is what is partial). #5221 is excluded and not superseded.
diff --git a/devlog/_plan/260923_bundle_lane_e/020_carry.md b/devlog/_plan/260923_bundle_lane_e/020_carry.md
new file mode 100644
index 00000000000..7eed3c46010
--- /dev/null
+++ b/devlog/_plan/260923_bundle_lane_e/020_carry.md
@@ -0,0 +1,17 @@
+# Carry plan
+
+Commit order (one commit per item, Co-authored-by trailer for the original author):
+
+1. #5629 (luvs01) plus review fixes.
+2. #5659 (Ingwannu) plus review fixes; Closes #5495.
+3. #5646 (FredAmartey).
+4. #5633 (FredAmartey) with the import and structure-doc cleanup.
+5. #5489 (AaronZ345) net diff (its upstream/dev merge commit dropped) plus the replayUnsafe fix.
+
+Mechanism: cherry-pick each PR's own commits (squashed per PR) onto the lane branch, then apply the folded review fixes in the same commit. Registries (scripts/test-layout/layout.json, tests/fixtures/test-layout-expected.json) keep every dev entry.
+
+
+## Documentation folded from the audit
+
+- #5489: one new row in the hop/terminal table of docs-site/src/content/docs/guides/combos.md (an undeclared first tool call before any output and without a replay-unsafe side effect hops; after a replay-unsafe side effect it stays terminal), mirrored in every translated combos.md that carries the table; structure/runtime.md and structure/transports/responses-failover.md updated.
+- #5659: one sentence in the English code-mode section of docs-site/src/content/docs/guides/codex-integration.md, next to the existing shell/patch repairs. Locales do not describe these repairs, so they do not contradict it.
diff --git a/devlog/_plan/260923_bundle_lane_e/030_verify.md b/devlog/_plan/260923_bundle_lane_e/030_verify.md
new file mode 100644
index 00000000000..a1a5aac8d03
--- /dev/null
+++ b/devlog/_plan/260923_bundle_lane_e/030_verify.md
@@ -0,0 +1,12 @@
+# Verification
+
+Per item, after its commit:
+
+- #5629: bun test tests/server/retry-delay-hardening.test.ts tests/server/retry-after-429.test.ts tests/providers/devin-stated-reset-retry.test.ts tests/providers/devin-stated-reset-hardening.test.ts tests/providers/devin-hardening.test.ts tests/codex-integration/combo-authoritative-reset.test.ts (includes the new repeated-marker negative case).
+- #5659: bun test tests/responses/responses-code-mode-goal-helpers.test.ts tests/responses/responses-undeclared-tool-guard.test.ts tests/responses/responses-custom-tool-repair.test.ts tests/responses/responses-bare-echo-helper-fence.test.ts tests/responses/responses-default-namespace-emit-normalize.test.ts tests/responses/legacy-shell-compat.test.ts tests/responses/responses-code-mode-shell-compile.test.ts tests/responses/responses-code-mode-patch-compile.test.ts (includes the raw guard-input, unrelated-name and bare-goal precedence cases).
+- #5646 + #5633: bun test tests/responses/ws-ambiguous-resend.test.ts tests/responses/ws-failure-stage.test.ts tests/server/replay-refusal-parity.test.ts tests/lib/ambiguous-resend-composition.test.ts tests/routing/routing-policy-fallback.test.ts tests/lib/upstream-retry.test.ts tests/responses/responses-reset-replay.test.ts tests/responses/responses-opaque-blob-recovery.test.ts tests/server/server-combo-failover-e2e.test.ts.
+- #5489: bun test tests/adapters/run-turn-queue.test.ts tests/server/server-combo-zero-output-failover.test.ts tests/server/server-combo-failover-e2e.test.ts tests/responses/responses-stream-tool-events.test.ts tests/adapters/bridge.test.ts tests/responses/responses-undeclared-tool-guard.test.ts, including the new non-streaming case: heartbeat(replayUnsafe) then an undeclared tool call returns the refusal with exactly one target dispatch.
+
+Branch gates: tests/test-layout.test.ts tests/test-layout-tooling.test.ts tests/ci-workflows/file-size-ratchet.test.ts tests/ci-workflows/structure-ssot.test.ts, bun run typecheck, bun run structure:check, bun run privacy:scan, git diff --check. No full local suite (owner runs it after every lane lands).
+
+Evidence required before the final report: exact-head hosted CI with every required job completed success at the PR head SHA (run ids and per-job conclusions recorded), and a gpt-6-sol adversarial review of the final diff with verdict PASS and findings folded.
diff --git a/devlog/_plan/260923_claude_desktop_first_party_models/000_plan.md b/devlog/_plan/260923_claude_desktop_first_party_models/000_plan.md
new file mode 100644
index 00000000000..cfa6c6dfe72
--- /dev/null
+++ b/devlog/_plan/260923_claude_desktop_first_party_models/000_plan.md
@@ -0,0 +1,62 @@
+# Claude Desktop first-party: Code tab model bindings
+
+First-party mode keeps Claude Desktop signed in to claude.ai and routes only the Code tab's
+Claude Code through the local intercept. The routing works, but the Code tab picker is owned by
+claude.ai, so none of opencodex's models can appear there and the operator has no way to reach
+them from Desktop. This unit adds first-party model bindings: the operator binds a picker model
+id (for example `claude-sonnet-4-6`) to an opencodex route, and only requests that arrive
+through the intercept honour the binding. `ocx claude` sessions and the public Messages
+endpoint are unaffected. Evidence for the constraint is in [001_probe_evidence.md](001_probe_evidence.md);
+the decisions are in [010_roadmap.md](010_roadmap.md).
+
+## Loop spec
+
+- Loop archetype: satisfy-spec, three work-phases (docs-first, implementation, live proof + PR).
+- Trigger: the user reported that first-party still does not work in the Claude app and asked
+ for a live probe of the injection mechanism with Computer Use, a working Claude app, and a PR
+ with screenshots.
+- Goal: from the Desktop Code tab in first-party mode, the operator can pick a Desktop picker row
+ and be served by an opencodex route of their choice, with the binding visible in CLI, API,
+ dashboard and docs.
+- Non-goals: adding rows to the Desktop picker (claude.ai owns it), changing the OS trust store or
+ system proxy, modifying Claude.app, changing gateway mode, merging or releasing the PR,
+ restarting the user's live service.
+- Verifier: focused bun tests named in 020, `bun run typecheck`, `bun run structure:check`,
+ `bun run skill:surface:check`, `bun run lint:gui`, `bun run build:gui`, then the live
+ Desktop proof in 030 (usage.jsonl provider + app screenshot).
+- Stop condition: PR opened against `dev` with screenshots and exact-head CI reported; no merge.
+- Memory artifact: this unit directory; the goalplan at
+ `.codexclaw/goalplans/opencodex-claude-desktop-first-party-claude-code/`.
+- Expected terminal outcomes: DONE when C1-C4 hold; BLOCKED if Desktop needs a login only the
+ user can perform; NEEDS_HUMAN if claude.ai changes the picker ids mid-run.
+- Escalation condition: any need to touch the OS trust store, system proxy, Claude.app, or the
+ user's live service; any merge decision.
+- Resource bounds: local worktree writes only; push limited to the PR branch and screenshot
+ assets; one live Desktop session probe per proof; no token or time budget was set by the user.
+
+## Work-phase map
+
+| Work-phase | Doc | Closes with |
+| --- | --- | --- |
+| wp1 docs-first | this unit, 001, 010 | roadmap locked, no code |
+| wp2 bindings | [020_wp2_first_party_bindings.md](020_wp2_first_party_bindings.md) | focused tests, typecheck, structure/skill checks green |
+| wp3 live proof + PR | [030_wp3_live_proof_and_pr.md](030_wp3_live_proof_and_pr.md) | Desktop Code tab served by a bound route, screenshots, PR open |
+
+## Architect consultation
+
+- Handle: `01a0cda6-d2ab-73d2-95ea-ead02c2cd992` (devin/swe-2, CXC-ROLE architect, read-only).
+- Proposal decisions D1-D5 and main's dispositions are recorded in [010_roadmap.md](010_roadmap.md).
+- Reflection on revision r1 (000/010/020/030): ALIGNED. One minor gap: rename migrations rewrite
+ only `modelMap` values. Disposition: 020 now rewrites `intercept.modelMap` in the provider, routing-profile
+ and combo rename paths, and records why the legacy OpenAI-id migration is excluded.
+
+## Audit record
+
+- Reviewer `01a0cdae-0b0c-7840-a1f4-30fdc5398854` (devin/swe-2, CXC-ROLE reviewer), round 1:
+ GO-WITH-FIXES (blockers=1). Blocker 1 (native/ targets only normalized in the 3P-alias branch;
+ PUT validation source unspecified) folded into 020: read-side normalization in
+ `claudeCodeForIngress` and validation against the unfiltered Desktop route vocabulary. Notes folded:
+ CSS in a new file (styles.css is at cap), picker-id keys are not migrated on renames, `ocx-route`
+ precedence documented, scratch-server safety argument written into 030.
+- Round 2: reviewer PASS. Architect reflection on r2: ALIGNED with one residual (normalize only the
+ intercept entries, not merged global values), folded into 020.
diff --git a/devlog/_plan/260923_claude_desktop_first_party_models/001_probe_evidence.md b/devlog/_plan/260923_claude_desktop_first_party_models/001_probe_evidence.md
new file mode 100644
index 00000000000..44bef2708be
--- /dev/null
+++ b/devlog/_plan/260923_claude_desktop_first_party_models/001_probe_evidence.md
@@ -0,0 +1,51 @@
+# 001 — Probe evidence (2026-09-23)
+
+All observations were made on the maintainer machine with Claude.app 1.18286.0, Desktop's
+bundled Claude Code 2.1.197, standalone Claude Code 2.1.278 and the source-dogfooded proxy
+(`/Users/jun/Developer/new/700_projects/opencodex` at 206fbc6b3f) on port 10100, intercept on 10200.
+Screenshots and extracted bundles stay outside the repository under `/tmp/ocx-claude-probe/`.
+
+## Where the Desktop Code tab picker comes from
+
+- Desktop main process (`app.asar` `.vite/build/index.js`) exposes an IPC
+ `LocalSessions.setAvailableCodeModels(modelIds)` that the renderer calls; the renderer is the
+ claude.ai web app.
+- The claude.ai bundle (`shared-16-*.js`) calls `setAvailableCodeModels(ae.map(e=>e.id))` with
+ `{selectableModels:ae}=oy("code")`, and `oy` builds the catalog from `modelSelectorConfig`
+ (`shared-0-*.js` `function Zj`). Unknown ids only ever become an "Unsupported model" entry for
+ the current selection; `Yj` adds `[1m]` rows only for models already in the catalog.
+- The renderer reads Claude Code settings through `resolveLocalSettings` (`shared-4-*.js` `mN`):
+ `model`, `availableModels`, `fastMode`, effort and permission keys. `availableModels` only
+ disables rows; `model` does not add one. Claude Code 2.1.278 supports a `modelPicker` settings
+ key with labels and `behavesAs`, but Desktop does not read it.
+- Live check: with `~/.claude/settings.json` `model` set to `claude-ocx-xai--grok-4.7` and a new
+ Code session, the picker still listed only Opus 5.5, Sonnet 5, Fable 5.1, Haiku 4.5 and More
+ models (Opus 5, Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6). The setting was restored.
+
+Conclusion: in first-party mode no local file can add an opencodex row to the Desktop picker.
+The only lever is the request path: the Code tab sends the picker id and the intercept can route it.
+
+## The intercept path works
+
+- `ocx claude desktop apply --first-party` pivoted the Desktop library to the standard profile
+ and wrote only `HTTPS_PROXY`/`NODE_EXTRA_CA_CERTS` into `~/.claude/settings.json`.
+- Standalone CLI: `claude -p ... --model claude-ocx-xai--grok-4.7` returned `PROBE-OK`;
+ usage.jsonl recorded `xai xai/grok-4.7 200 loopback messages`.
+- Desktop Code tab, Haiku 4.5: reply `DESKTOP-1P-PROBE-HAIKU`; usage.jsonl recorded two
+ `anthropic-native claude-haiku-4-5-20251001 200 loopback` rows, so Desktop's Claude Code does go
+ through the intercept.
+- Desktop Code tab, Sonnet 4.6 after a temporary global `claudeCode.modelMap`
+ `{"claude-sonnet-4-6":"xai/grok-4.7"}`: usage.jsonl recorded `xai xai/grok-4.7 grok-4.7 200 loopback`.
+ The global map was the only way to do this, and it also reroutes `ocx claude` sessions.
+
+## Picker ids observed on the wire
+
+`claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-4-6`, `claude-haiku-4-5-20251001` (dated), plus the
+catalog rows Opus 4.8/4.7/4.6 and Fable 5/5.1. Dated ids reach an undated key through the existing
+date-suffix strip in `resolveInboundModel` (src/claude/inbound-model-options.ts).
+
+## Side observation, not in scope
+
+Before the probe the saved config said `desktopMode: first-party` while the Desktop library still
+applied the opencodex gateway profile, and status reported `first_party_residue`. The running
+proxy was 26 commits behind `dev`; this unit does not chase that state.
diff --git a/devlog/_plan/260923_claude_desktop_first_party_models/010_roadmap.md b/devlog/_plan/260923_claude_desktop_first_party_models/010_roadmap.md
new file mode 100644
index 00000000000..853bde6babc
--- /dev/null
+++ b/devlog/_plan/260923_claude_desktop_first_party_models/010_roadmap.md
@@ -0,0 +1,22 @@
+# 010 — Roadmap and decisions
+
+Status: locked at the end of wp1 (reviewer PASS, architect ALIGNED on revision r2).
+
+Order follows the build dependency: the binding has to resolve on the request path before any
+surface can edit it, and the live proof needs both.
+
+1. wp2 — storage, request-path resolution, API, CLI, dashboard, docs ([020](020_wp2_first_party_bindings.md)).
+2. wp3 — live Desktop proof with screenshots and the PR ([030](030_wp3_live_proof_and_pr.md)).
+
+## Architect proposal (handle 01a0cda6) and dispositions
+
+| ID | Proposal | Disposition |
+| --- | --- | --- |
+| D1 storage | New `claudeCode.intercept.modelMap`; global `modelMap` stays untouched | Accepted. |
+| D1 plumbing | Build a shallow `{...config, claudeCode: {...}}` copy in serve-options for intercept requests | Amended. A config copy can reach `saveConfig`/live-reconcile helpers keyed on the config object and would persist the merged map. Instead serve-options passes `claudeIntercept: true` to the two handlers, and the handlers derive a request-scoped `claudeCode` view (`claudeCodeForIngress`) that only the model-resolution calls read. |
+| D2 matching | Reuse `resolveInboundModel` unchanged (exact, date-stripped, `[1m]`, `--fast`) | Accepted; the view overlays `modelMap` so every existing rule applies. Amended after audit round 1: intercept targets written as `native/` are normalized to the bare slug inside the view, because `resolveInboundModel` returns map values verbatim; global `modelMap` values are not normalized. |
+| D3 surfaces | CLI `bind`/`unbind`, API, GUI first-party card, schema, docs | Accepted with a dedicated `PUT /api/claude-desktop/first-party-bindings` route instead of widening the gateway profile PUT, which carries conflict checks unrelated to bindings. The CLI drives that route so the running proxy adopts the change immediately. |
+| D4 constraints | No capped file touched; register any new test file in both layout maps; lab boundary untouched | Accepted. |
+| D5 honesty | Show "picker id → served route"; never claim the Desktop label changes | Accepted; docs and GUI copy say the picker keeps Anthropic's label. |
+| Risk (c) | A picker id that is also an alias resolves alias-first | Accepted as is; picker ids are genuine Anthropic ids. |
+| Risk (d) | Picker ids can change | Documented; the dashboard offers the observed ids as suggestions and accepts any `claude-` id. |
diff --git a/devlog/_plan/260923_claude_desktop_first_party_models/020_wp2_first_party_bindings.md b/devlog/_plan/260923_claude_desktop_first_party_models/020_wp2_first_party_bindings.md
new file mode 100644
index 00000000000..5f5c88ffe5b
--- /dev/null
+++ b/devlog/_plan/260923_claude_desktop_first_party_models/020_wp2_first_party_bindings.md
@@ -0,0 +1,79 @@
+# 020 — wp2: first-party model bindings
+
+## Scope
+
+IN: storage, request-path resolution for intercepted Messages and count_tokens, status/PUT API,
+CLI `bind`/`unbind`, dashboard first-party card, docs and structure.
+OUT: Desktop picker rows or labels, OS trust store/system proxy, Claude.app, gateway-mode
+behaviour, global `claudeCode.modelMap` semantics, the public `/v1/messages` path.
+
+## Contract
+
+- `claudeCode.intercept.modelMap?: Record` — key: a Desktop picker model id
+ (`claude-` prefix, e.g. `claude-sonnet-4-6`); value: an opencodex route in the Desktop route
+ vocabulary (`provider/model`, or `native/` for the native OpenAI pool).
+- A binding applies only to requests that arrive on the `claude-intercept` ingress. It is
+ overlaid on the global `modelMap` for that request (binding wins per key), so every existing
+ resolution rule applies unchanged: alias first, Desktop 3P alias, exact key, date-suffix-stripped
+ key, `[1m]` strip, `--fast` decode. A bound id is therefore never natively passed through.
+- `native/` targets resolve to the bare slug, matching how Desktop 3P aliases resolve
+ (src/claude/inbound-model-options.ts:48-53). Normalization runs read-side inside
+ `claudeCodeForIngress`, so a hand-written config, the CLI, the API and the GUI all converge;
+ the stored value keeps the Desktop route vocabulary (`native/`) for round trips. Only the
+ intercept entries are normalized before the merge; global `modelMap` values keep today's verbatim
+ semantics on every path.
+- An `ocx-route` body directive (src/server/claude-messages.ts:694-697) still wins over a binding,
+ because it rewrites the model before resolution. Bindings do not change that precedence.
+- PUT validates a target against the whole Desktop route vocabulary from `buildClaudeDesktopState`
+ (`state.models`, available entries, native routes included). The apply path's filtered `routed`
+ list (agent-settings-routes.ts:1174) is not used, because it drops `native/` routes.
+
+## File change map
+
+| File | Change |
+| --- | --- |
+| `src/types/config.ts` (~146) | `intercept?: { enabled?; port?; modelMap?: Record }` with doc comment. |
+| `src/config/schema/config-schema.ts` (~285) | Validate `intercept.modelMap`: plain object; keys match the picker-id shape; values non-empty strings without whitespace. |
+| `src/claude/intercept/model-bindings.ts` (new) | `INTERCEPT_BINDING_ID` shape, `normalizeBindingTarget(route)`, `claudeCodeForIngress(cc, claudeIntercept)` (request-scoped view, never persisted), `applyBindingPatch(current, {set, remove})` with validation errors. |
+| `src/server/index/serve-options.ts` (~1478, ~1509) | Pass `{ claudeIntercept: ingress === "claude-intercept" }` to `handleClaudeCountTokens` and `handleClaudeMessages`. |
+| `src/server/claude-messages.ts` (~96-210, ~634-790, ~1211-1270) | Derive `cc = claudeCodeForIngress(config.claudeCode, claudeIntercept)` once per request; use it in `decodeFablePickerAlias`, `decodeClaudeFastSelector`, capture, `wantsNativePassthrough` (new `cc` argument) and `anthropicToResponsesTranslation`. `config` itself is never copied. |
+| `src/server/management/agent-settings-routes.ts` (~1237-1310) | Status adds `firstParty.modelBindings`; new `PUT /api/claude-desktop/first-party-bindings` taking `{ set?, remove? }`, validating routes against the available Desktop routes, committing through `mutatePersistedConfig` and adopting the committed `claudeCode` into the live config. |
+| `src/server/management/route-registry.ts` | Declare the PUT route. |
+| `src/cli/claude-desktop.ts` | `ocx claude desktop bind ` and `unbind ` via `runtimeRequest`; help text. |
+| `src/cli/capabilities.ts` + `skills/ocx` surface map | Register `claude desktop bind` and `claude desktop unbind`; regenerate with `bun run skill:surface`. |
+| `gui/src/components/ClaudeFirstPartyBindings.tsx` (new) + `gui/src/pages/ClaudeDesktop.tsx` + `gui/src/i18n/*.ts` + `gui/src/styles/claude-first-party-bindings.css` (new; `gui/src/styles.css` is at its 2958-line cap and is not touched) | First-party card: rows "picker id → route", add/remove, suggestions of observed picker ids, route select from available Desktop routes, copy that the Desktop label stays Anthropic's. |
+| `docs-site/src/content/docs/guides/claude-code.md` + locales | Section "Use opencodex models from the Desktop Code tab"; the CLI-compatibility bullet names bindings next to `modelMap`. |
+| `structure/clients/claude-desktop.md`, `structure/runtime.md` | Contract above and the ingress-scoped overlay. |
+| `src/providers/provider-id-rewrite.ts` (~97), `src/server/management/routing-profile-routes.ts` (~200), `src/server/management/combo-routes.ts` (~273) | Rewrite `intercept.modelMap` values alongside `modelMap` on provider, routing-profile and combo renames so a binding cannot go stale silently. Keys are not migrated: they are Anthropic picker ids, never opencodex public ids, so a routing-profile rename cannot rename them. `src/providers/openai-tiers.ts` legacy-id migration is left alone: it rewrites pre-existing legacy ids, and bindings are written after it with current ids. |
+| Tests | `tests/claude-integration/claude-intercept-model-bindings.test.ts` (new, registered in both layout maps); an intercept-vs-public case in `tests/server/claude-intercept-integration.test.ts`; route/CLI cases next to the existing first-party tests. |
+
+Field chain for `intercept.modelMap`: creation — CLI `bind`, PUT route, GUI card, hand-written
+config; serialization — `mutatePersistedConfig`; deserialization — schema validation on load
+(invalid entries reported, never silently used); consumers — `claudeCodeForIngress` in both
+handlers, status route, GUI card, CLI output, and the three rename migrations above.
+
+## Activation scenarios (C-ACTIVATION-GROUNDING-01)
+
+1. Bound id via intercept: a Messages request for `claude-sonnet-4-6` through the CONNECT proxy
+ with binding `xai/…` reaches the fake provider, not the fake Anthropic upstream.
+2. Same request on the public listener: passes through to the fake Anthropic upstream.
+3. Dated id: `claude-haiku-4-5-20251001` reaches a `claude-haiku-4-5` binding.
+4. `native/` target resolves to ``.
+5. count_tokens on a bound id via intercept is not natively passed through.
+6. PUT rejects a non-`claude-` key, an unavailable route and a whitespace value with 400 and
+ leaves config unchanged; `remove` of an unknown id is a no-op.
+7. Schema rejects a non-object `intercept.modelMap` and non-string values.
+
+## Verifiers (run before writing, PLAN-VERIFIER-REAL-01)
+
+- `bun test tests/server/claude-intercept-integration.test.ts tests/claude-integration/claude-desktop-first-party.test.ts`
+ — exit 0, 33 pass on the base; both files import the intercept pair and first-party module directly.
+- New test file above, plus `bun run typecheck`, `bun run structure:check`, `bun run skill:surface:check`,
+ `bun run lint:gui`, `bun run build:gui`, `bun run test:changed` (run in B/C).
+
+## Delegation
+
+Main writes server, config, CLI, API, tests, structure and English/Korean docs. One devin/swe-2
+worker writes the GUI component, page wiring, CSS and all ten GUI locales against the API contract
+above (disjoint write scope: `gui/` only). A second devin/swe-2 worker translates the new docs
+section into fr, ja, ru, tr, zh-cn and zh-tw (write scope: those six files). Main reviews both diffs.
diff --git a/devlog/_plan/260923_claude_desktop_first_party_models/030_wp3_live_proof_and_pr.md b/devlog/_plan/260923_claude_desktop_first_party_models/030_wp3_live_proof_and_pr.md
new file mode 100644
index 00000000000..15c899159b8
--- /dev/null
+++ b/devlog/_plan/260923_claude_desktop_first_party_models/030_wp3_live_proof_and_pr.md
@@ -0,0 +1,52 @@
+# 030 — wp3: live Desktop proof and PR
+
+## Live proof
+
+The user's service runs from the main checkout; this worktree's code is proven without restarting
+or reconfiguring it. A scratch server starts from this worktree through `startServer` directly
+(the same entry the integration tests use, so no CLI ensure/sync step touches `~/.codex` or the
+service manager), with `OPENCODEX_HOME` pointing at a scratch directory outside the repository.
+Its config holds only one provider that authenticates with a static API key (`zai` or `aim`,
+copied from the user's config; OAuth providers are excluded because a refresh in the copy could
+rotate the user's token), `claudeCode.intercept.port` 10400 and public port 10300. The scratch
+server mints its own intercept CA. The scratch config carries no `openai`/Codex provider, so the
+Codex sync and quota paths stay inert (src/server/index.ts:276-287, src/codex/quota-auto-refresh.ts:279),
+and the service-ownership check reads the default-home records and fails closed to "foreign"
+(src/service/state.ts:156-157). The repointed `NODE_EXTRA_CA_CERTS` reads as foreign to the user's
+own proxy, so its ensure step does not rewrite it mid-probe (src/claude/intercept/settings.ts:88-99).
+
+1. Back up `~/.claude/settings.json` (already at `/tmp/ocx-claude-probe/backup/`), then point
+ `HTTPS_PROXY` at 10400 and `NODE_EXTRA_CA_CERTS` at the scratch CA for the probe.
+2. `ocx claude desktop bind claude-sonnet-4-6 /` against the scratch server
+ (CLI targets it through the scratch home), and the dashboard card for the GUI screenshot.
+3. Fully quit and reopen Claude Desktop (first-party), Code tab, pick Sonnet 4.6, send a probe;
+ pick Haiku 4.5 and send a second probe.
+4. Evidence: scratch `usage.jsonl` shows the bound provider for the Sonnet 4.6 probe and
+ `anthropic-native` for Haiku 4.5; the user's own proxy log shows no new Messages rows for the
+ probes; screenshots of the Desktop conversation, the picker and the dashboard card, cropped to
+ exclude account names.
+5. Restore: settings.json byte-for-byte from backup, stop the scratch server, delete the scratch
+ home, fully quit and reopen Desktop, confirm the user's proxy on 10100/10200 is untouched.
+
+## PR
+
+- Branch `codex/claude-desktop-first-party-models` → `dev`, repository template (Summary,
+ Verification, Checklist), screenshots uploaded to the `pr-assets` branch and linked by commit SHA.
+- Report exact-head CI; do not merge.
+
+## Result (2026-09-23)
+
+- Scratch server from this branch on 10300/10400 (zai only, `claudeCode.desktopMode: first-party`),
+ binding set with the new CLI: `ocx claude desktop bind claude-sonnet-4-6 zai/glm-5.3-flash`.
+ The CLI refused `gpt-6` (not a picker id) and `nope/missing` (route not available).
+- Claude Desktop 1.18286.0, first-party, Code tab, Sonnet 4.6 picked: the reply arrived, and the
+ scratch `usage.jsonl` recorded `zai zai/glm-5.3-flash glm-5.3-flash 200 loopback messages` for it
+ and `anthropic-native claude-haiku-4-5-20251001 200` for Desktop's own title call, so unbound ids
+ still pass through natively. The user's proxy recorded no Messages rows for the probes.
+- The bound model still described itself as Sonnet, because Claude Code's system prompt tells it so.
+ The docs say this and recommend binding rows the operator does not otherwise use.
+- Screenshots on `pr-assets` at 793b39d85d (`260923-claude-desktop-first-party-bindings/`).
+- Restored afterwards: `~/.claude/settings.json` byte-identical to the backup, scratch server stopped
+ and its home deleted, the temporary global `modelMap` used during the probe removed from the
+ user's proxy, Desktop reopened. Desktop was left in first-party mode, which is the saved
+ `desktopMode`; before the probe it was running the gateway profile.
diff --git a/devlog/_plan/260924_anthropic_fast_opt_in/010_plan.md b/devlog/_plan/260924_anthropic_fast_opt_in/010_plan.md
new file mode 100644
index 00000000000..58a8a63a87e
--- /dev/null
+++ b/devlog/_plan/260924_anthropic_fast_opt_in/010_plan.md
@@ -0,0 +1,68 @@
+# Anthropic Fast opt-in (default off) — plan (wp1)
+
+## Loop spec (HOTL wp1)
+
+- Request (2026-09-24): Anthropic fast mode spends usage credits, so keep it off by default; give the
+ Anthropic provider card on the dashboard Models page one row that turns it on and off; open a PR and
+ merge it. Push, PR, and merge are authorized for this change.
+- Previous unit: devlog/_plan/260923_anthropic_fast_speed (#5604) made `claude-opus-5-5`, `claude-opus-5`,
+ `claude-opus-4-8` Fast-eligible on `anthropic` and `anthropic-apikey` with no switch other than the
+ global `fastMode`. Its residual already named the cost: every turn on an account without credits pays a
+ refused round trip, and an account with credits is billed 2x without a per-provider choice.
+- Branch `codex/anthropic-fast-default-off` from `origin/dev` 6b7a91f575.
+
+## Design
+
+- D1 Registry: `ProviderRegistryEntry.fastOptIn?: boolean`. `true` means the provider's Fast lane is billed
+ beyond the plan and stays off until the operator enables it. Set on `anthropic` and `anthropic-apikey`.
+ The FastWire, model map, and tier description stay as they are, so enabling restores #5604 exactly.
+- D2 Config: `OcxProviderConfig.fastEnabled?: boolean`. `false` turns Fast off for any provider;
+ `true` satisfies an opt-in registry entry; absent means "registry default" (off for opt-in entries,
+ unchanged elsewhere). Zod provider schema accepts a boolean; auth-cors field policy classifies it `editor`.
+- D3 Policy: `buildFastPolicyAuthority` (src/providers/service-tier.ts) resolves the switch from the configured
+ provider, then the enriched provider, then `getProviderRegistryEntry(name)?.fastOptIn` (looked up by name
+ regardless of transport match, because it can only turn Fast off). An off switch sets the provider
+ capability to `false`, which `resolveFastPolicy` already treats as a global denial: eligibility becomes
+ `capability-unsupported`, catalog Fast toggles and `--fast` rows disappear, `decideTier` drops, and the
+ adapter never emits `speed`. No new policy branch in fastwire.ts.
+- D4 Management API: PATCH /api/providers accepts `fastEnabled` (boolean, or null to clear). GET /api/providers
+ adds `fastOptIn: { enabled }` only for opt-in registry entries so the dashboard knows where to draw the row.
+- D5 Dashboard: a small `ProviderFastRow` component (own file, Models.tsx is 8 lines under its ratchet cap)
+ with the same Off/On segmented control as the new-model policy row, label "Fast mode" and a hint that it
+ uses usage credits at 2x price. Rendered in the provider body for providers whose summary carries
+ `fastOptIn`. PATCH then reload. i18n keys in all ten locales.
+- D6 Docs/SoT: docs-site providers reference (Anthropic Fast section + field table row), structure
+ providers-and-adapters note.
+
+## Tests
+
+- New `tests/providers/anthropic-fast-opt-in.test.ts`: registry default ineligible for both entries;
+ `fastEnabled: true` restores eligible; `fastEnabled: false` denies an ordinary service-tier provider;
+ `catalogFastRowEligible` false by default; PATCH round-trip sets/clears the field and GET exposes
+ `fastOptIn`.
+- Rewrite fixtures that assumed default-on (responses-anthropic-fast-downgrade, fast pricing, fastwire roster
+ if affected) to set `fastEnabled: true` deliberately.
+
+## Acceptance
+
+- C1 default ineligible / opt-in eligible (c-1). C2 Models row renders and PATCHes (c-2, screenshot).
+- C3 typecheck, focused tests, test:changed, ratchet/layout, structure:check, privacy:scan, lint:gui, build:gui.
+- C4 PR to dev with template, exact-head CI green, merged (c-3).
+
+## Residuals
+
+- Claude Messages native passthrough forwards a caller's own `speed` field (Claude Code /fast); that is the
+ caller's explicit choice and stays outside this switch.
+## Audit fold (A, reviewer NEAR-PASS)
+
+- B1 folded: one helper `providerFastSwitchOff(name, provider)` (src/providers/fast-opt-in.ts) is applied in
+ three places: the FastPolicy authority (service-tier.ts), `resolveModelPolicy` (static supportsServiceTier
+ and fastTierDescription), and router registry enrichment, which writes `supportsServiceTier: false` on the
+ resolved runtime provider so nameless `fastPolicyForModel` callers also see the denial.
+- B2 folded by the same enrichment write.
+- B3: PATCH already clears the provider model cache and runs `convergeCodexCatalog` for any non-pacing
+ field; the policy test covers the PATCH round trip. Claude listings compute per request.
+- B4: flipped fixtures set `fastEnabled: true` deliberately; load-degrade's inherited-fastWire warning skips
+ providers whose switch is off.
+- Residual accepted: native Claude Messages passthrough forwards the caller's own `speed`; documented.
+- Scope confirmed by user: Cursor unchanged; only anthropic and anthropic-apikey default off.
diff --git a/devlog/_plan/260924_anthropic_forced_tool_choice/010_plan.md b/devlog/_plan/260924_anthropic_forced_tool_choice/010_plan.md
new file mode 100644
index 00000000000..d66a0b19b3a
--- /dev/null
+++ b/devlog/_plan/260924_anthropic_forced_tool_choice/010_plan.md
@@ -0,0 +1,43 @@
+# Anthropic forced tool choice and Opus 5.5
+
+## Scope
+One implementation unit: inspect adapter-generated body and live status for required/named/auto tool choices on Opus 5.5 and a control, with and without explicit reasoning. A current token is read only; no proxy starts and no token/body is printed.
+
+## Hypotheses
+H1: adaptive thinking and forced any/tool conflict; falsifier is a 2xx live response for the same adapter-produced body.
+H2: Opus 5.5 rejects forced any/tool regardless of thinking; falsifier is a 2xx response with thinking omitted or disabled.
+H3: proxy/router rather than upstream is responsible; falsifier is the same upstream error from the adapter-produced request.
+
+## Diff-level plan
+If live evidence confirms H1, change only src/adapters/anthropic.ts around its reasoning and tool_choice construction, retaining forced any/tool and suppressing or disabling thinking only when live evidence proves the wire shape works. Add a focused test in tests/adapters/anthropic/ proving required/named semantics and unaffected auto/none cases. Update owning structure document if required; test the focused file, typecheck, structure:check, privacy:scan. Obtain gpt-6-sol adversarial review, push one branch and open a template PR to dev. Do not run the full suite, merge, or touch main/preview.
+
+## Audit and outcome
+
+Live adapter-generated probe, 2026-09-24, using the active Anthropic OAuth access token read
+in memory from `~/.opencodex/auth.json` (token and response bodies were never printed). The
+probe sent 12 small Messages requests through `createAnthropicAdapter(...).buildRequest()`;
+the pre-fix wire fields and status were:
+
+| Model | Effort | Choice | Wire choice | Thinking | Status |
+|---|---|---|---|---|---:|
+| claude-opus-5-5 | medium / omitted | required | any | adaptive / omitted | 400 |
+| claude-opus-5-5 | medium / omitted | named | tool | adaptive / omitted | 400 |
+| claude-opus-5-5 | medium / omitted | auto | auto | adaptive / omitted | 200 |
+| claude-opus-5 | medium / omitted | required | any | adaptive / omitted | 200 |
+| claude-opus-5 | medium / omitted | named | tool | adaptive / omitted | 200 |
+| claude-opus-5 | medium / omitted | auto | auto | adaptive / omitted | 200 |
+
+After the fix, the same 12 requests returned 200. Opus 5.5 required/named choices are sent
+as `auto`; Opus 5 keeps `any`/`tool`. This agrees with Anthropic's published migration guide:
+https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5 (forced tool use is
+unsupported for Opus 5.5; `auto` and `none` are supported). The compatibility downgrade
+preserves a named or allowed tool's candidate set and preserves `disable_parallel_tool_use`,
+but it cannot preserve the upstream forced-call guarantee.
+
+For completeness, two supplementary requests manually overrode the adapter body to send
+`thinking:{type:"disabled"}` together with `tool_choice` `any` and `tool`. Both returned
+HTTP 400. The published guide also states that Opus 5.5 rejects disabled thinking, so there
+is no thinking-off wire shape that can retain forced tool use for this model.
+
+## Plan reflection after vendor source check
+Official Opus 5.5 change guide (https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5, read 2026-09-24) says thinking cannot be disabled and any/tool forced choices return 400; auto/none are supported. This falsifies a semantics-preserving repair for Opus 5.5. If the adapter-generated live probe agrees, change only Opus 5.5 forced choices to auto and explicitly document that required/named callers lose the guarantee; preserve the choice where upstream accepts it. The guide says the same restriction applies to Fable 5.1, but that model needs separate live or test evidence before expansion.
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/000_plan.md b/devlog/_plan/260924_claude_desktop_picker_mode/000_plan.md
new file mode 100644
index 00000000000..0d7b3b00549
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/000_plan.md
@@ -0,0 +1,170 @@
+# Claude Desktop: gateway by default, first-party with a risk warning, and a picker that lists opencodex models
+
+Claude Desktop reaches opencodex in two ways. Gateway (3P) switches the whole app to the local
+gateway and shows every opencodex model by name. First-party (1P) keeps the app on claude.ai and
+routes only the Code tab's Claude Code through a local interception proxy; until now its model
+picker could only show Anthropic's models, because claude.ai builds that list. This unit makes
+gateway the default for new installs, warns that first-party sends a Claude subscription through
+a local interception proxy and can get the account suspended, and adds a first-party **picker
+mode**, on by default, that shows opencodex routes by their real names in the Code tab picker.
+Picker mode points Desktop's own traffic at the opencodex CONNECT proxy through the
+`egressProxyUrl` config-library key (supported in 1P since Desktop 1.44121.1), trusts a local CA
+whose name constraints permit only `claude.ai` and its subdomains, and adds entries to the Code surface of the claude.ai
+bootstrap. Evidence is in [001_research.md](001_research.md). The threat model stays in scratch
+space (`.tmp/260924_claude_desktop_picker_mode/threat_model.md`, untracked) per AGENTS.md until the
+change ships; its controls are restated in the decade docs.
+
+## Loop spec
+
+- Loop archetype: satisfy-spec, five work-phases (docs-first, then four dependency-ordered cycles).
+- Trigger: the user asked for gateway as the default, a first-party account-suspension warning,
+ and first-party picker mode on by default, delivered through a merged PR.
+- Goal: a fresh install applies gateway; choosing first-party shows the risk everywhere it can be
+ chosen or seen; with first-party applied on macOS the Desktop Code tab picker lists opencodex
+ routes by name and a turn with one of them is served by opencodex.
+- Non-goals: Chat tab and other non-CLI surfaces; picker trust on Windows and Linux (reported as
+ unsupported); OS-wide proxy settings; changing `api.anthropic.com` interception; mentioning or
+ copying any third-party project.
+- Verifier: per-phase focused suites named in each decade doc, `bun run typecheck`,
+ `bun run structure:check`, `bun run skill:surface:check`, `bun run privacy:scan`,
+ `bun run lint:gui`, `bun run build:gui`, `bun run test:changed` on the merge result, then the
+ live Desktop proof in [040](040_wp5_live_proof_pr_merge.md).
+- Stop condition: PR merged to `dev` by squash after exact-head CI, merged tree verified.
+- Memory artifact: this unit; goalplan
+ `.codexclaw/goalplans/opencodex-claude-desktop-default-to-gateway-3p-w/`.
+- Expected terminal outcomes: DONE when every goalplan criterion has fresh evidence; NEEDS_HUMAN
+ only for the macOS keychain password dialog during the live proof; BLOCKED on repeated external
+ CI blockage; UNSAFE if picker mode could leave Desktop without connectivity.
+- Escalation condition: any change to the operator's live service beyond the documented restart,
+ any need to disable upstream TLS verification, or a live bootstrap shape that contradicts 001.
+- Resource bounds: writes limited to this worktree, `/private/tmp` scratch, the operator's
+ Desktop config library and login keychain during the live proof; pushes limited to the PR
+ branch and `pr-assets`; gpt-6-sol subagents for discovery, bounded slices and review; no token or
+ time budget was set by the user.
+
+## Work-phase map
+
+| Work-phase | Doc | Closes with |
+| --- | --- | --- |
+| wp1 docs-first | 000, 001 and the decade docs | roadmap locked, no code |
+| wp2 gateway default + 1P warning | [010](010_wp2_gateway_default_and_warning.md) | resolver/CLI/API/sync tests, typed locales, docs parity |
+| wp3 picker core | [020](020_wp3_picker_core.md) | CA/trust, CONNECT decision, claude.ai relay, bootstrap rewrite, route snapshot tests |
+| wp4 picker activation | [030](030_wp4_picker_activation.md) | egress profile, CLI/API/GUI controls, docs, default-on in 1P |
+| wp5 live proof + PR + merge | [040](040_wp5_live_proof_pr_merge.md) | Desktop screenshots, usage.jsonl proof, CI green, squash merge |
+
+The phases follow build order: the mode contract (wp2) is consumed by activation (wp4); the relay
+and CA (wp3) must exist before anything selects the egress profile (wp4); nothing is shown to a
+real Desktop before wp5. One branch, one PR, ordered commits.
+
+## Decisions
+
+Decision IDs come from the architect proposal; dispositions are main's.
+
+| ID | Decision | Disposition |
+| --- | --- | --- |
+| D1 | Default `gateway`; resolver takes observations (owned first-party settings applied/stale → legacy first-party) with precedence explicit → observed gateway → gateway fingerprint → owned first-party settings → gateway. Implicit applies persist the preserved mode. `/api/sync` stops writing a gateway profile when the resolved mode is first-party. | Accepted. Status stays read-only. Reflections r1/r2: the selected owned gateway row joins the observation; the intercept-disabled fallback is removed, so an observed first-party install keeps its mode and an apply with the intercept disabled is refused with `intercept_disabled`. |
+| D2 | One owner for the risk text (`src/claude/desktop-risk.ts`), `riskWarning` in status, CLI apply/status, native toggle response, dashboard selector + active card, 10 locales, 8 guides; default badge moves to gateway. | Accepted. |
+| D3 | Separate picker CA under `/claude-picker/`, critical nameConstraints permitting `claude.ai` and excluding every IP address, leaf SAN `claude.ai` only; macOS `security add-trusted-cert -r trustRoot -p ssl -k ` (the first build passed `-s claude.ai`; #5731 dropped it because Chromium skips host-scoped trust), trust checked with `security verify-cert -q -L -c -p ssl -n claude.ai`, removal with `security remove-trusted-cert`. | Accepted, amended: tests use a fake command runner; no real keychain in CI. Reflection r1 gap 4 folded: "trusted" also requires the login keychain to hold a certificate whose SHA-1 equals the current picker CA (`security find-certificate -a -Z -c `), and `verify-cert` searches that keychain (`-k`). Audit r1 blocker 1 folded: the claim is narrowed to "`claude.ai` and its subdomains" (an RFC 5280 dNSName subtree cannot be exact), and it is only claimed for verifiers shown to enforce it: a Bun/BoringSSL test rejects an off-host leaf issued by the picker CA, and wp5 runs Apple `verify-cert` on an ephemeral off-host leaf after trust; whatever that shows is what the PR states. The primary control stays the 0600 key that never leaves the machine. |
+| D4 | CONNECT decides per connection: `messages` (api.anthropic.com), `picker` (claude.ai, only when desired + first-party effective + listener ready + cached trust matches the CA fingerprint), else `blind`. Trust cache invalidated on toggle/rotation, rechecked on a bounded interval. | Accepted. |
+| D5 | Dedicated `node:https` HTTP/1.1 terminator for claude.ai with `request` and `upgrade` handlers, fixed upstream `claude.ai:443`, verified TLS, raw headers and bodies streamed. | Accepted after a spike on Bun 1.4.0 (`/private/tmp/ocx-picker-spike/spike.ts`): gzip bytes, two `Set-Cookie` headers and a WebSocket upgrade passed through unchanged. |
+| D6 | Rewrite only GET bootstrap responses (`/edge-api/bootstrap`, `/edge-api/bootstrap/{org}/app_start`, `/api/bootstrap…`) with a `code` surface; clone a selectable Claude entry per route; decode gzip/br/deflate under compressed and decompressed caps; fail open with the original bytes. | Accepted, amended: the bootstrap request's `accept-encoding` is narrowed to `gzip, deflate, br` so zstd never arrives. Reflection r1 gap 6 partly folded: clones drop `fast_mode` and every version-gate key (`/version/i`) with the presentation fields; `thinking` and `capabilities` stay because the intercept translates effort and handles images for routed models. |
+| D7 | Picker routes mirror the gateway's rendered Desktop profile, ids minted with `aliasForRoute`/`claudeCodeNativeAlias`, served from a snapshot so bootstrap never waits on provider discovery. | Accepted, amended: snapshot built at server start (when picker is desired), on picker on/apply, and refreshed stale-while-revalidate after 10 minutes. |
+| D8 | Picker egress profile is an owned standard row containing only `egressProxyUrl`; previous selection recorded in opencodex state (never in `_meta.json`); off/removal/gateway switch: stop terminating, reselect previous, delete owned row, untrust CA; partial cleanup reported. | Accepted. Config field is `claudeCode.intercept.picker?: boolean` (absent = on in 1P on macOS). Reflections r1–r3: every disable first calls the running runtime's `disarm()` (new claude.ai CONNECTs go blind at once, independent of the preference and of the cached mode), then removes the profile, then untrusts. Only an explicit `picker off` persists `false`; mode-transition cleanup leaves the preference unset so first-party turns the picker back on. |
+| D9 | `ocx claude desktop picker on|off|status|trust`, `GET/PUT /api/claude-desktop/picker` (standard management auth: CLI admin token and dashboard session), `firstParty.picker` in status with desired/effective/reason/hint/residual. | Accepted; reshaped by D11: `on`/`off` go through the server when one runs; `trust` is the only CLI-local mutation; `off` and transition cleanup run locally only when no server runs. |
+| D10 | Live mode propagation: the runtime's `refresh()` decides from a fresh persisted read (resolved mode, Desktop intent, picker preference); `selectTunnel` reads only the cached decision; a disarm latch that only a completed, verified enable clears; server paths adopt committed `claudeCode` for status. | Accepted with the architect's amendments; the POST disarm/refresh routes of earlier revisions are dropped under D11. |
+| D11 | While a server runs, every picker mutation (enable, disable, transition cleanup) runs in one server-side `DesktopPickerController`, serialized by one lock; CLI first-party apply delegates to `POST /api/claude-desktop/apply` like gateway apply already does; enable re-reads persisted state, commits an explicit preference first, checks mode/intent/preference/bound proxy before and after trust, and compensates trust it added on any later failure; startup never trusts or writes a profile. | Added at the second P re-entry after audit round 5 (ordering and race findings from rounds 4–5 all came from two mutation sites); architect reflection below. |
+
+## Field chains (PLAN-FIELD-CHAIN-01)
+
+| Field | Creation | Serialization | Deserialization | Consumers |
+| --- | --- | --- | --- | --- |
+| `claudeCode.intercept.picker?: boolean` | `DesktopPickerController.enable({ persist: true })` / `.disable({ persist: true })` (CLI `picker on|off` and the dashboard toggle through `PUT /api/claude-desktop/picker`); offline CLI `picker off` writes `false` locally before `removeDesktopPickerArtifacts`; first-party apply and transition cleanup never write it (absent = on) | `config.json` through the field-scoped config writer; `src/types/config.ts:151` type; `src/config/schema/config-schema.ts` boolean validation | `loadConfig` → `OcxClaudeCodeConfig.intercept.picker`; a non-boolean fails schema validation | `pickerDesired` (picker-runtime `refresh()`), `DesktopPickerController.enable` checks, `DesktopPickerController.status`, status payload |
+| `riskWarning: { code, message } \| null` | status builder (agent-settings-routes), first-party apply response | JSON response | GUI `DesktopStatus` (`gui/src/pages/ClaudeDesktop.tsx:62`); CLI `status` prints every key | GUI callout (localized by `claudeDesktop.mode.firstPartyRisk`, gated on presence), CLI status |
+| `firstParty.picker: DesktopPickerStatus` | `DesktopPickerController.status()` in the status builder (with no controller running: a static "proxy_unavailable" status); `GET/PUT /api/claude-desktop/picker` | JSON response | GUI `DesktopFirstPartyStatus` (`ClaudeDesktop.tsx:49`); CLI `picker status` | `ClaudeDesktopPicker` card, CLI output |
+| config-library row name `opencodex-picker` | `applyDesktopPickerProfile` | `_meta.json` `entries[].name` (Desktop's schema; no opencodex keys added) | `parseMetadata` (desktop-3p-library) | `isOwnedDesktopEntry` (owned, inspection kind `standard` because the profile has no `inferenceProvider`), `removeDesktopPickerProfile`; `isOwnedDesktopGatewayEntry` stays `name === "opencodex"`, so gateway writes and gateway cleanup never pick it |
+| `PUT /api/claude-desktop/picker` body `{ enabled, persist, trustedLocally?, callerAddedTrust? }` | CLI `picker on|off|trust`, dashboard toggle, CLI transition helpers | JSON request | route handler validation (booleans only; unknown keys rejected) | `DesktopPickerController.enable/disable`; `trustedLocally` only selects the trust-outcome wording (`trust_declined` vs `trust_pending`) and never skips a check; `callerAddedTrust` makes the server compensate that trust inside its lock on refusal or failure |
+| `ClaudeDesktopModeObservation` | `observeClaudeDesktopMode` | N/A — in-process value | N/A | `resolveClaudeDesktopMode`, `resolveClaudeDesktopApplyMode` callers listed in 010 |
+
+## Guard bypasses (PLAN-BYPASS-NAMED-01)
+
+The trust gate on claude.ai termination is a safety guard, not enforcement.
+
+- Tier: runtime check in process (no OS or build gate).
+- Executing surface: `PickerRuntime.selectTunnel` on every new CONNECT to `claude.ai:443`.
+- Known bypass: trust removed outside opencodex (Keychain Access) stays cached as trusted for up to
+ the 60 s refresh interval; connections opened in that window fail TLS in Desktop until the next
+ refresh. An operator who edits the config library by hand can point Desktop elsewhere. While a
+ server runs, enable and disable are serialized by the picker controller's lock, and the disarm
+ latch is cleared only at the end of an enable whose checks all passed; with no server running,
+ nothing can terminate claude.ai. A process that edits opencodex's config or the keychain
+ directly, outside these paths, is not constrained.
+- Residual risk: Desktop has no network while its pinned egress proxy is down; stated in CLI, GUI
+ and docs.
+- Wording downgrade: described as a guard everywhere; no document calls it enforcement.
+- Final layer: none.
+
+## Architect consultation
+
+- Handle: `01a0d104-9116-7d22-b92d-81bc155eab50` (gpt-6-sol, CXC-ROLE architect, read-only).
+- Proposal D1–D9 above; dispositions recorded in the table.
+- Reflection on revision r1: MISALIGNED with six gaps. Gap 1 (security working note tracked in
+ devlog) folded: the threat model moved to scratch. Gap 2 partly folded, gaps 3–5 folded, gap 6
+ partly folded; dispositions are in the decision table.
+- Reflection r2: MISALIGNED (3 gaps: intercept-disabled fallback, picker mode from config alone,
+ transition cleanup persisting false) — all folded into 010/020/030.
+- Reflection r3: MISALIGNED (cleanup could keep terminating while the cached mode was still
+ first-party; stale table wording) — folded: `disarm()` first, table updated.
+- Reflection r4: MISALIGNED (no server path to disarm without changing the preference; in-flight
+ `ensureStarted()` could re-arm) — folded: `POST /api/claude-desktop/picker/disarm`, arm
+ generation guard, route and race tests.
+- Reflection r5: **ALIGNED**, no remaining material gap.
+- After audit round 1 and round 2 amendments: rechecks MISALIGNED (overflow chunk, failed compensation;
+ grok-lifecycle source assertions) → folded → **ALIGNED**.
+- P re-entry after audit round 3 (LOOP-REPAIR-01): D10 proposed by main, amended by the architect
+ (disarm latch, integration intent, native adoption, OFF→ON test), reflection MISALIGNED once
+ (integration intent not visible to the runtime) → decision source changed to a fresh persisted
+ read → **ALIGNED**.
+- Second P re-entry after audit round 5: D11 (single server-side controller) proposed by main;
+ the architect amended it three times (transition lease, CLI trust compensation, preference commit
+ after independent checks; then restart_required and lost-response handling) → **ALIGNED**.
+
+## Audit record
+
+- Reviewer `01a0d114-541c-7d13-8277-ed9f711dad59` (gpt-6-sol, CXC-ROLE reviewer).
+- Round 1: FAIL (7 blockers: CA boundary claim, /api/sync race, durable-OFF cleanup, oversize
+ fail-open handoff, signature mismatches, trust compensation, trust_pending test) → all folded.
+- Round 2: FAIL (5: overflow triggering chunk, async ensure caller, stale mode passed to enable,
+ missing cap seam, hint/declined contract) → all folded.
+- Round 3: FAIL (1: committed mode not reaching the running runtime) → returned to P, D10 added.
+- Round 4: FAIL (4: stranding Desktop without a bound proxy, failed mode write, latch cleared by a
+ caller claim, CLI/route auth mismatch) → folded.
+- Round 5: FAIL (4: off→on refused by its own guard, stale intent in CLI apply, concurrent enable
+ during cleanup, second-guard compensation) → second P re-entry, D11.
+- Round 6: FAIL (4: /api/sync outside the lock, busy guard vs in-lock rearm, lost CLI response
+ racing server enable, live-proof rollback leaving picker state) → folded; architect rechecks added
+ early-refusal compensation.
+- Round 7: FAIL (2: startup refresh missing, config-routes.ts absent from the wp4 inventory) →
+ folded; architect recheck added the bounded first-CONNECT wait and the persisted route snapshot.
+- Round 8: **GO-WITH-FIXES (blockers=1)** — field-chain rows still named pre-D11 functions →
+ folded. Main's judgment: near-pass; no High/Critical blocker remains.
+
+## wp1 close (D)
+
+Roadmap locked at D1–D11; the next cycle is wp2 (gateway default and the first-party risk warning).
+
+- What changed: the unit's plan, research and four diff-level decade docs; the threat model stays in
+ scratch.
+- Hypotheses that died: "no local change can add a row to the first-party picker" (true only for
+ Desktop builds older than 1.44121.1, which lack `egressProxyUrl` in 1P); "Desktop filters
+ non-Anthropic model ids" (only the custom-3P provider does; 1P returns `{ok:true}`); "Cloudflare
+ in front of claude.ai rejects a re-originated TLS client" — a Bun `node:https` GET of
+ `/edge-api/bootstrap` and `/api/bootstrap` returned 200 JSON (brotli) with no `cf-mitigated`
+ header (`/private/tmp/ocx-picker-spike/cf.ts`, 2026-09-24).
+- What did not improve: the audit needed eight rounds and two returns to P; every late finding was
+ about ordering between two mutation sites, which D11 removed. The activation surface is still the
+ largest part of the change.
+- Evidence that would show the direction is wrong: a logged-in bootstrap without a `code` surface
+ in `model_selector_config` (the logged-out bootstrap has no `model_selector_config` at all, so
+ this is only checkable in wp5); Desktop's Chromium refusing a login-keychain-trusted root with
+ name constraints; the launchd service never able to raise the keychain dialog (then
+ `trust_pending` + `picker trust` is the only path, which the plan already supports).
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/001_research.md b/devlog/_plan/260924_claude_desktop_picker_mode/001_research.md
new file mode 100644
index 00000000000..1c3e3b2f88c
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/001_research.md
@@ -0,0 +1,83 @@
+# 001 — Research: how the Desktop Code tab picker can list opencodex models (2026-09-24)
+
+Evidence was read from Claude.app 2.7032.0 (`/Applications/Claude.app/Contents/Resources/app.asar`,
+byte offsets below), from claude.ai renderer bundles saved during the 2026-09-23 probe (kept outside
+the repository under `/tmp/ocx-claude-probe/web/`; they may be older than the live renderer), and
+from this repository at `37f93da6ac`. Nothing here was observed on the wire yet; the items marked
+**live** are verified in wp5.
+
+## Desktop app facts
+
+- `egressProxyUrl` is a config-library key supported in both deployment scopes:
+ `support:{enabled:{scopes:["3p","1p"],availableInVersion:"1.44121.1"}}`, `appBehaviorOnly:!0`
+ (app.asar ≈11009657). It is read once at launch and applied as Chromium `--proxy-server` with a
+ bypass list for loopback and `*.local`; PAC (`egressProxyPacUrl`) takes precedence
+ (≈20277302–20278073). Startup logs `[egress-proxy] pinned …; OS proxy settings ignored`
+ (≈20329028). Claude Code processes the app spawns receive `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY`.
+ The 1.18286.0 build probed for the previous unit predates this key, which is why that unit could
+ not reach the picker.
+- On macOS the app reads its config library from the user-data directory with a `-3p` suffix
+ (`~/Library/Application Support/Claude-3p/configLibrary/`) in both scopes; `_meta.json`
+ `appliedId` selects `.json` (≈11136500–11138403, ≈11158102). opencodex already owns this
+ writer (`src/claude/desktop-3p-library.ts`, `src/claude/desktop-3p-paths.ts:47`).
+- The model-list keys `modelCatalogUrl`, `modelCatalogEnabled` and `modelDiscoveryEnabled` are
+ 3P-only (`scopes:["3p"]`). No config key sets an app-level trusted CA, so Desktop's renderer
+ relies on the operating system trust store for claude.ai.
+- The first-party provider class (`hasClaudeAiProductFeatures(){return!0}`,
+ `managesProviderRouting(){return!1}`) implements `validateSessionModel(e,t){return{ok:!0}}`
+ (≈12961260). The non-Anthropic model regex (`…|gpt|grok|kimi|…`, ≈10697300) applies only to the
+ custom-3P provider's `validateSessionModel` (≈12952304). In 1P, a picked id reaches Claude Code
+ unchanged through `query.setModel`.
+
+## claude.ai renderer facts (saved bundles)
+
+- The picker catalog comes from the bootstrap response field `model_selector_config`: an array of
+ surfaces `{ id, models[], description?, presets?, featured?, auto_compact_window? }`. The Desktop
+ bridge takes the selectable models of the surface `"code"` and sends their ids to the app with
+ `setAvailableCodeModels`. `"cowork"` has its own catalog; `"ccr"`/`"ccd"` share Code-like
+ selection persistence but are not shown to feed this bridge.
+- A model entry carries `id`, `name`, `section`, `description`, `badge`, `tooltip`,
+ `disabled`, `disabled_reason`, `context_window`, `thinking`, `fast_mode`, `capabilities` and
+ optional version gates. It is listed when `section` is `"main"` or `"overflow"` and selectable when
+ it is not disabled, has no `disabled_reason` and is not `"deprecated"`. The default selection is a
+ separate `model_selector_state`; `contextWindowByModel` is derived from each entry's
+ `context_window`.
+- The bootstrap is fetched with credentials from `/edge-api/bootstrap/{org}/app_start` or
+ `/edge-api/bootstrap` with `statsig_hashing_algorithm=djb2&growthbook_format=sdk&cache_bust=1`
+ (another provider defaults to an `/api` prefix) and parsed with `response.json()`; no body
+ signature or integrity check exists on that path. A `bootstrap_push_revision` guard keeps a newer
+ catalog revision when an older network result arrives.
+- claude.ai also carries WebSockets (`/v1/sessions/ws/{id}/subscribe`, Code terminal
+ `/v1/code/sessions/{id}/terminal`, `/api/ws/…` voice) and streaming responses
+ (`/v1/code/sessions/{id}/events/stream`, `/v1/code/sessions/watch`, SSE chat, an MCP
+ `EventSource`). A terminating proxy has to pass all of them through.
+
+## opencodex facts
+
+- Mode: `DEFAULT_CLAUDE_DESKTOP_MODE = "first-party"` (src/claude/desktop-first-party.ts:36);
+ `resolveClaudeDesktopMode` returns an explicit `desktopMode`, then `gateway` for an applied
+ gateway fingerprint, then the default (:49–53). Every apply path persists the chosen mode through
+ `recordClaudeDesktopMode` (:62). An install that applied first-party before the field existed
+ would silently resolve to gateway if only the constant changed, and the next implicit apply would
+ retire its env. Five tests in tests/claude-integration/claude-desktop-first-party.test.ts assert
+ the current default (:64, :78, :86, :138, :182).
+- Intercept: the CONNECT proxy splices only `api.anthropic.com` (a startup snapshot,
+ src/claude/intercept/connect-proxy.ts:15, :121) and blind-tunnels the rest; loopback targets get
+ 403 and non-CONNECT requests 405. The TLS listener is one `Bun.serve` with one certificate
+ (listener.ts:106) and relays non-Messages paths through `fetch`, which decodes bodies and drops
+ `Upgrade` (listener.ts:19–29, :62–88), so it cannot carry claude.ai as is.
+- CA: `local-ca.ts` builds P-256 certificates with local DER helpers (`tlv`, `contextTag`,
+ `objectIdentifier`, `extension`, :48–109) and keeps the CA out of OS trust (:9); a
+ nameConstraints extension (OID 2.5.29.30) is expressible with the same helpers.
+- Routed ids: `aliasForRoute` mints `ocx-claude---` (src/claude/alias.ts:94) and the
+ Messages path already resolves it, so a picker entry with that id routes without a binding.
+- File-size ratchet: none of the touched intercept/desktop files has a cap; `src/server/index.ts` is
+ at 883 of 893, so no new wiring lands there.
+
+## Open questions verified live in wp5
+
+1. The live bootstrap still carries `model_selector_config` with a `"code"` surface, and a cloned
+ entry renders and is selectable.
+2. Chromium in Desktop accepts a claude.ai leaf chained to a login-keychain-trusted root that
+ carries nameConstraints.
+3. Desktop behaves with an HTTP/1.1-only terminator (ALPN) for claude.ai, including WebSockets.
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/010_wp2_gateway_default_and_warning.md b/devlog/_plan/260924_claude_desktop_picker_mode/010_wp2_gateway_default_and_warning.md
new file mode 100644
index 00000000000..950a89e8402
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/010_wp2_gateway_default_and_warning.md
@@ -0,0 +1,285 @@
+# 010 — wp2: gateway by default, first-party account-risk warning
+
+Consumes: D1, D2 in [000](000_plan.md). Produces the mode contract wp4 builds on.
+
+## Files
+
+| Path | Change |
+| --- | --- |
+| `src/claude/desktop-first-party.ts` | MODIFY: default constant, observation-aware resolver, observation helper, header comment |
+| `src/claude/desktop-risk.ts` | NEW: the single owner of the first-party account-risk text |
+| `src/cli/claude-desktop.ts` | MODIFY: help text, `defaultDesktopApplyMode` observes settings, apply prints the risk |
+| `src/cli/ensure-desired-integrations.ts` | MODIFY: resolve with observation |
+| `src/server/management/agent-settings-routes.ts` | MODIFY: apply default + status `riskWarning` |
+| `src/server/management/native-integration-routes.ts` | MODIFY: status/enable observe; enable message carries the risk |
+| `src/server/management/config-routes.ts` | MODIFY: `/api/sync` skips the gateway writer when the resolved mode is first-party |
+| `src/server/management/agent-settings-routes.ts` (also) | MODIFY: `autoApplyDesktopBestEffort` (:212, the roster-update gateway writer) returns early when the resolved mode is first-party, both before and after its model discovery await |
+| `src/types/config.ts` | MODIFY: the `desktopMode` doc comment (:183) names gateway as the default and first-party's risk |
+| `tests/claude-integration/claude-desktop-mode-explanation.test.ts` | MODIFY: explanation cases for the new default |
+| `structure/gui-and-management-api.md` | MODIFY: the Desktop apply default (:182) is gateway; `riskWarning` in the status payload |
+| `gui/src/styles/claude-desktop-mode-picker.css` | MODIFY: header comment (:1) — gateway is the default, first-party is the opt-in with the risk callout (plus the callout style if it fits here) |
+| `gui/src/pages/ClaudeDesktop.tsx` (also) | MODIFY: stale comments at :240 and :351 that call first-party the default |
+| `gui/src/pages/ClaudeDesktop.tsx` | MODIFY: default badge + fallback mode = gateway; first-party risk callout |
+| `gui/src/pages/ClaudeDesktop.tsx` (Desktop status type lives here) | MODIFY: `riskWarning` in the status type |
+| `gui/src/i18n/{en,de,fr,ko,zh,zh-TW,ru,ja,tr,vi}.ts` | MODIFY: `claudeDesktop.mode.firstPartyRisk`; hints no longer call first-party the default |
+| `docs-site/src/content/docs/{,fr/,ja/,ko/,ru/,tr/,zh-cn/,zh-tw/}guides/claude-code.md` | MODIFY: gateway is the default; caution block in the first-party section |
+| `structure/clients/claude-desktop.md` | MODIFY: mode contract (default, legacy observation, risk warning, sync guard) |
+| `tests/claude-integration/claude-desktop-first-party.test.ts` | MODIFY: the five default assertions + new cases |
+
+## Diff
+
+`src/claude/desktop-first-party.ts`
+
+```diff
+- * - `first-party` (default): the app keeps its ordinary claude.ai login, …
++ * - `gateway` (default): the third-party deployment profile (src/claude/desktop-3p.ts) …
++ * - `first-party`: the app keeps its claude.ai login … Carries an account-risk warning
++ * (src/claude/desktop-risk.ts).
+-export const DEFAULT_CLAUDE_DESKTOP_MODE: ClaudeDesktopMode = "first-party";
++export const DEFAULT_CLAUDE_DESKTOP_MODE: ClaudeDesktopMode = "gateway";
++
++/** What the resolver may learn from disk. Only owned rows and owned settings count. */
++export interface ClaudeDesktopModeObservation {
++ /** Desktop's selected config-library row is our gateway (current or drifted). */
++ ownedGatewaySelected?: boolean;
++ ownedFirstPartySettings?: boolean;
++}
++
++/** Observe owned first-party settings (applied or stale). Never throws; unreadable = none. */
++export function observeClaudeDesktopMode(
++ config: Pick,
++ options: DesktopFirstPartyOptions = {},
++): ClaudeDesktopModeObservation {
++ const observed: ClaudeDesktopModeObservation = {};
++ try {
++ const library = inspectDesktop3pConfigLibrary({ appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null });
++ observed.ownedGatewaySelected = library.kind === "gateway_ours" || library.kind === "gateway_drifted";
++ } catch { /* unreadable library: no gateway evidence */ }
++ try {
++ const kind = inspectDesktopFirstParty(config, options).settings.kind;
++ observed.ownedFirstPartySettings = kind === "applied" || kind === "stale";
++ } catch { /* unreadable settings: no first-party evidence */ }
++ return observed;
++}
+-export function resolveClaudeDesktopMode(config: DesktopModeConfig): ClaudeDesktopMode {
++export function resolveClaudeDesktopMode(
++ config: DesktopModeConfig,
++ observed: ClaudeDesktopModeObservation = {},
++): ClaudeDesktopMode {
+ const explicit = config.claudeCode?.desktopMode;
+ if (isClaudeDesktopMode(explicit)) return explicit;
++ if (observed.ownedGatewaySelected) return "gateway";
+ if (config.claudeCode?.desktopProfile?.appliedFingerprint) return "gateway";
++ // An install that applied first-party before the mode was persisted keeps first-party.
++ if (observed.ownedFirstPartySettings) return "first-party";
+ return DEFAULT_CLAUDE_DESKTOP_MODE;
+ }
+ export function resolveClaudeDesktopApplyMode(
+ config: Pick,
++ observed: ClaudeDesktopModeObservation = {},
+): ClaudeDesktopMode {
+- const resolved = resolveClaudeDesktopMode(config);
++ const resolved = resolveClaudeDesktopMode(config, observed);
+- if (resolved === "gateway" || isClaudeDesktopMode(config.claudeCode?.desktopMode)) return resolved;
+- return claudeInterceptEnabled(config) ? "first-party" : "gateway";
++ return resolved;
+```
+
+With gateway as the default, an implied first-party can only come from observed legacy settings,
+so the intercept-disabled fallback branch is removed: an observed first-party install keeps its
+mode, and an apply with the intercept disabled is refused with `intercept_disabled` exactly like an
+explicit first-party (reflection r2 gap 1). `resolveClaudeDesktopApplyMode` stays as the named
+entry point callers use; `claudeInterceptEnabled` is no longer imported by it.
+`observeClaudeDesktopMode` is placed after `inspectDesktopFirstParty` (it calls it) and reaches
+`inspectDesktop3pConfigLibrary` without a new static import cycle (confirm the import graph at P).
+Resolver stays pure; callers that decide an apply or a write pass `observeClaudeDesktopMode(config)`.
+
+`src/claude/desktop-risk.ts` (NEW)
+
+```ts
+/** Account-risk notice every first-party surface shows. One owner so the wording cannot drift. */
+export const FIRST_PARTY_ACCOUNT_RISK = {
+ code: "first_party_account_suspension_risk",
+ message: "First-party mode sends Claude subscription traffic through a local interception proxy. "
+ + "Anthropic may treat this as a violation of its terms and suspend the account. Use it at your own risk; "
+ + "gateway mode is the default.",
+} as const;
+export type FirstPartyAccountRisk = typeof FIRST_PARTY_ACCOUNT_RISK;
+```
+
+`src/cli/claude-desktop.ts`
+
+```diff
+- --first-party (default) keep Desktop on claude.ai; route only the Code tab's Claude Code
+- through the local intercept proxy via ~/.claude/settings.json env
+- --gateway install the third-party gateway profile for the whole app
++ --gateway (default) install the third-party gateway profile for the whole app
++ --first-party keep Desktop on claude.ai; route only the Code tab's Claude Code through the
++ local intercept proxy. Risk: Anthropic may suspend the account.
+-export function defaultDesktopApplyMode(
+- config: Pick,
++export function defaultDesktopApplyMode(
++ config: Pick,
+- const resolved = resolveClaudeDesktopApplyMode(config);
++ const resolved = resolveClaudeDesktopApplyMode(config, observeClaudeDesktopMode(config));
+ if (target.kind === "first-party") {
+ console.log(`Claude Desktop first-party 설정을 적용했습니다: ${result.path}`);
+ console.log("Desktop 앱 설정은 그대로이며, Code 탭의 Claude Code만 로컬 프록시를 거칩니다.");
++ console.warn(`⚠️ ${FIRST_PARTY_ACCOUNT_RISK.message}`);
+```
+
+`gatewayModeExplanation` (src/cli/claude-desktop.ts:212–247) is rewritten for the new default: when gateway
+was applied without an explicit flag and first-party can run here (not a connected client, intercept
+enabled), it prints "Gateway is the default.", the first-party alternative
+(`ocx claude desktop apply --first-party`) and `FIRST_PARTY_ACCOUNT_RISK.message`; explicit gateway
+requests and machines that cannot run first-party get nothing. Its doc comment drops the "help calls
+first-party the default" premise.
+
+The bindings gateway warning (`resolveClaudeDesktopMode(config) === "gateway"`) also passes the
+observation. `status` prints the payload, which now carries `riskWarning`. `parseDesktopApplyArgs`
+(the only caller of `defaultDesktopApplyMode`) widens its config type the same way; its callers
+already pass a loaded `OcxConfig`. The gateway-mode explanation that suggests
+`ocx claude desktop apply --first-party` (`gatewayModeExplanation`, src/cli/claude-desktop.ts:243)
+appends `FIRST_PARTY_ACCOUNT_RISK.message` under the suggestion.
+
+`src/cli/ensure-desired-integrations.ts`
+
+```diff
+- if (resolveClaudeDesktopMode(config) !== "first-party") return;
++ if (resolveClaudeDesktopMode(config, (deps.observeClaudeDesktopMode ?? observeClaudeDesktopMode)(config)) !== "first-party") return;
+```
+
+`src/server/management/agent-settings-routes.ts`
+
+```diff
+- let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config);
++ let desktopMode: "first-party" | "gateway" = resolveClaudeDesktopApplyMode(config, observeClaudeDesktopMode(config));
+ …status…
+- const mode = gatewayApplied ? "gateway" : resolveClaudeDesktopApplyMode(persisted);
++ const mode = gatewayApplied ? "gateway" : resolveClaudeDesktopApplyMode(persisted, observeClaudeDesktopMode(persisted));
++ const { FIRST_PARTY_ACCOUNT_RISK } = await import("../../claude/desktop-risk");
++ const riskWarning = mode === "first-party" || firstPartySeen.applied || firstPartySeen.stale
++ ? { ...FIRST_PARTY_ACCOUNT_RISK } : null;
+ return jsonResponse({
+ desiredEnabled,
+ mode,
++ riskWarning,
+ firstParty,
+```
+
+The first-party apply response adds `riskWarning: { ...FIRST_PARTY_ACCOUNT_RISK }`.
+
+`src/server/management/native-integration-routes.ts`: `desktopStatus` and the enable branch call
+`resolveClaudeDesktopApplyMode(config, observeClaudeDesktopMode(config))`; the first-party enable
+message appends `FIRST_PARTY_ACCOUNT_RISK.message`.
+
+`src/server/management/config-routes.ts` (`/api/sync` client integrations)
+
+```diff
+- if (claudeDesktopIntegrationEnabled(config)) {
++ if (claudeDesktopIntegrationEnabled(config)
++ && resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) !== "first-party") {
+ …
+ const latest = loadConfig();
+- if (claudeDesktopIntegrationEnabled(latest)) {
++ // Discovery awaited: the mode may have changed meanwhile. Re-resolve on the fresh read,
++ // immediately before the writer, so a first-party switch during fetchAllModels still wins.
++ if (claudeDesktopIntegrationEnabled(latest)
++ && resolveClaudeDesktopMode(latest, observeClaudeDesktopMode(latest)) !== "first-party") {
+```
+
+wp4 moves this post-discovery block (the re-read, the re-resolve and `writeDesktop3pConfig`)
+inside the picker controller's `transition` when a controller exists (030, D11), so a sync that
+resumes while a first-party apply is between gateway cleanup and its mode commit waits for the
+lock and then sees first-party. wp2 lands the re-resolve; wp4 adds the lock.
+
+A first-party Desktop no longer gets a gateway profile written and selected by a catalog sync.
+
+`autoApplyDesktopBestEffort` (agent-settings-routes.ts:212) gets the same guard twice: after
+`loadConfig()` into `admitted` and again after the `fetchAllModels` await on `current`:
+
+```diff
+ if (!claudeDesktopIntegrationEnabled(admitted)) return;
++ if (resolveClaudeDesktopMode(admitted, observeClaudeDesktopMode(admitted)) === "first-party") return;
+ …
+ if (!claudeDesktopIntegrationEnabled(current)) return;
++ if (resolveClaudeDesktopMode(current, observeClaudeDesktopMode(current)) === "first-party") return;
+```
+
+`gui/src/pages/ClaudeDesktop.tsx`
+
+```diff
+- const effectiveMode: DesktopMode = status?.mode ?? "first-party";
++ const effectiveMode: DesktopMode = status?.mode ?? "gateway";
+- {mode === "first-party" && {t("claudeDesktop.mode.defaultBadge")}}
++ {mode === "gateway" && {t("claudeDesktop.mode.defaultBadge")}}
+ …after the mode options…
++ {selectedMode === "first-party" && (
++ `, so a missing key fails),
+`cd gui && bun test tests/locale-parity.test.ts`, `bun run structure:check`.
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/020_wp3_picker_core.md b/devlog/_plan/260924_claude_desktop_picker_mode/020_wp3_picker_core.md
new file mode 100644
index 00000000000..2affdd4c9da
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/020_wp3_picker_core.md
@@ -0,0 +1,362 @@
+# 020 — wp3: picker core (CA, trust, CONNECT decision, claude.ai relay, bootstrap rewrite, routes)
+
+Consumes: D3–D7 in [000](000_plan.md) and facts in [001](001_research.md). Controls this phase
+carries: only claude.ai is terminated and only while trusted; the upstream leg always verifies
+certificates; exactly one response (the bootstrap) is rewritten and the rewrite fails open; no
+body, cookie or token is logged; every listener is loopback. Nothing here selects the Desktop
+egress profile; with no profile applied, none of this code sees Desktop traffic. wp4 turns it on.
+
+## Files
+
+| Path | Change |
+| --- | --- |
+| `src/claude/intercept/local-ca.ts` | MODIFY: export a generic authority/leaf issuer; add the nameConstraints OID and encoder; existing intercept CA unchanged |
+| `src/claude/intercept/picker-ca.ts` | NEW: picker CA (`/claude-picker/`), claude.ai leaf, persisted leaf PEM for trust checks |
+| `src/claude/intercept/picker-trust.ts` | NEW: macOS login-keychain trust/verify/untrust through an injectable `security` runner |
+| `src/claude/intercept/picker-bootstrap.ts` | NEW: bootstrap request match, accept-encoding narrowing, decode, JSON injection, header rewrite |
+| `src/claude/intercept/picker-models.ts` | NEW: picker entries from the rendered Desktop profile + snapshot holder |
+| `src/claude/intercept/picker-listener.ts` | NEW: `node:https` HTTP/1.1 terminator for claude.ai with request + upgrade relay |
+| `src/claude/intercept/picker-runtime.ts` | NEW: desired/trust/listener state, tunnel decision, lazy start/stop, trust cache |
+| `src/claude/intercept/connect-proxy.ts` | MODIFY: per-connection `selectTunnel`; header comment |
+| `src/claude/intercept/runtime.ts` | MODIFY: create the picker runtime, pass `selectTunnel`, stop it; expose picker state |
+| `src/server/index/claude-intercept-lifecycle.ts` | MODIFY: pass the picker route loader (dynamic imports; `src/server/index.ts` untouched) |
+| `src/claude/desktop-3p.ts` | MODIFY: export `displayModelId` (label parity) |
+| `src/types/config.ts`, `src/config/schema/config-schema.ts` | MODIFY: `claudeCode.intercept.picker?: boolean` |
+| `structure/runtime.md` | MODIFY: intercept pair gains the picker terminator; invariants |
+| tests (below) + `scripts/test-layout/layout.json`, `tests/fixtures/test-layout-expected.json` | NEW files registered in both |
+
+## local-ca.ts
+
+```diff
+ const OID = {
++ nameConstraints: "2.5.29.30",
+ …
++export interface AuthorityOptions {
++ commonName: string;
++ permittedDnsNames?: readonly string[];
++ excludeAllIpAddresses?: boolean; // default true (#5731)
++}
++
++/** iPAddress bases (address + mask, all zero) covering every IPv4 and every IPv6 address. */
++export const ALL_IP_ADDRESS_BASES: readonly Uint8Array[] = [new Uint8Array(8), new Uint8Array(32)];
++
++/** RFC 5280 NameConstraints: permittedSubtrees of dNSName bases, excludedSubtrees of every IP. */
++function nameConstraints(permitted: readonly string[], excludeAllIpAddresses: boolean): Uint8Array {
++ const subtrees = permitted.map(name => sequence(contextTag(2, new TextEncoder().encode(name), false)));
++ const excluded = ALL_IP_ADDRESS_BASES.map(base => sequence(contextTag(7, base, false)));
++ return sequence(
++ contextTag(0, concat(...subtrees)),
++ ...(excludeAllIpAddresses ? [contextTag(1, concat(...excluded))] : []),
++ );
++}
++
++export function createCertificateAuthority(options: AuthorityOptions): LocalInterceptCa { …same body as
++ createLocalInterceptCa, with commonName from options and, when permittedDnsNames is non-empty,
++ extension(OID.nameConstraints, true, nameConstraints(options.permittedDnsNames,
++ options.excludeAllIpAddresses !== false)) … }
++export function issueServerLeaf(ca: LocalInterceptCa, issuerCommonName: string, hosts: readonly string[]): PemKeyPair
+-export function createLocalInterceptCa(): LocalInterceptCa { …
++export function createLocalInterceptCa(): LocalInterceptCa {
++ return createCertificateAuthority({ commonName: CLAUDE_INTERCEPT_CA_COMMON_NAME });
++}
+-export function issueLocalInterceptLeaf(ca, hosts) { …
++export function issueLocalInterceptLeaf(ca: LocalInterceptCa, hosts: readonly string[]): PemKeyPair {
++ return issueServerLeaf(ca, CLAUDE_INTERCEPT_CA_COMMON_NAME, hosts);
++}
+```
+
+The persistence helpers become parameterized by directory and common name
+(`ensurePersistedAuthority(dir, options, lockName)`) so the picker CA reuses loading, validation,
+atomic 0600 key writes and the lifecycle lease without copying them.
+
+## picker-ca.ts
+
+```ts
+export const PICKER_HOST = "claude.ai";
+export const PICKER_CA_COMMON_NAME = "opencodex Claude Desktop Picker CA";
+export const PICKER_STATE_DIR = "claude-picker";
+export function pickerStateDir(configDir: string): string; // /claude-picker
+export function pickerCaCertPath(configDir: string): string; // …/ca.pem
+export function pickerLeafCertPath(configDir: string): string; // …/leaf.pem (public)
+export interface PickerCa extends LocalInterceptCa { fingerprint: string } // sha256 of the CA DER
+export function ensurePickerCa(configDir: string): PickerCa; // permittedDnsNames: [PICKER_HOST]
+export function issuePickerLeaf(ca: PickerCa, configDir: string): PemKeyPair; // SAN claude.ai; writes leaf.pem 0644
+```
+
+Reload validation (audit wp3 r1, High). The shared loader only checks CA status, key pairing and
+self-signature, so `ensurePersistedAuthority` gains `accept?: (cert: X509Certificate) => boolean`,
+and `ensurePickerCa` passes one that requires subject CN `PICKER_CA_COMMON_NAME` and a **critical**
+nameConstraints extension whose permittedSubtrees hold exactly one dNSName, `claude.ai`, and
+whose excludedSubtrees hold exactly two iPAddress bases, all-zero IPv4 (8 bytes) and all-zero IPv6
+(32 bytes), so no IP-address leaf chains to it (PR #5731 review: a DNS-only permitted list leaves the
+iPAddress form unconstrained). A persisted CA that fails it (for example a valid, key-matching CA
+without constraints, or the first claude.ai-only format) is regenerated under the lease. The new
+fingerprint makes trust `untrusted` until the operator trusts it again, so an unconstrained root is
+never loaded and trusted as the picker CA.
+
+## picker-trust.ts
+
+```ts
+export type PickerTrustState = "trusted" | "untrusted" | "unsupported" | "unknown";
+export interface SecurityResult { code: number | null; stdout: string; stderr: string }
+export type SecurityRunner = (args: readonly string[]) => Promise;
+export const defaultSecurityRunner: SecurityRunner; // Bun.spawn(["/usr/bin/security", …])
+export function loginKeychainPath(home?: string): string; // ~/Library/Keychains/login.keychain-db
+export async function inspectPickerTrust(leafPath: string, caSha1: string, run?: SecurityRunner, platform?: NodeJS.Platform): Promise;
+// darwin only; "trusted" needs both:
+// 1. ["find-certificate", "-a", "-Z", "-c", PICKER_CA_COMMON_NAME, loginKeychainPath()] lists caSha1 (the current CA)
+// 2. ["verify-cert", "-q", "-L", "-c", leafPath, "-p", "ssl", "-n", "claude.ai", "-k", loginKeychainPath()] exits 0
+// 3. ["trust-settings-export", ] does not show kSecTrustSettingsPolicyString in the
+// caSha1 entry (a host-scoped setting from an earlier build; Chromium skips it, so it counts
+// as untrusted and the trust step replaces it); an unreadable export → unknown, so the picker
+// never arms on a setting it could not inspect
+// missing record or exit 1 → untrusted; a runner failure → unknown
+export async function trustPickerCa(caPath: string, run?: SecurityRunner, platform?: NodeJS.Platform): Promise<{ ok: boolean; reason?: "unsupported" | "declined_or_failed" }>;
+// ["add-trusted-cert", "-r", "trustRoot", "-p", "ssl", "-k", loginKeychainPath(), caPath]
+// (no "-s claude.ai": found in the live proof, Chromium skips host-scoped trust settings and
+// Desktop failed with ERR_CERT_AUTHORITY_INVALID; the name constraints do the scoping)
+export async function untrustPickerCa(caPath: string, fingerprintSha1: string, run?: SecurityRunner, platform?: NodeJS.Platform): Promise<{ ok: boolean }>;
+// ["remove-trusted-cert", caPath] then ["delete-certificate", "-Z", fingerprintSha1, loginKeychainPath()]
+```
+
+Only stdout/stderr lengths are logged, never content.
+
+## picker-bootstrap.ts
+
+```ts
+export const BOOTSTRAP_MAX_ENCODED_BYTES = 4 * 1024 * 1024;
+export const BOOTSTRAP_MAX_DECODED_BYTES = 16 * 1024 * 1024;
+export const PICKER_SURFACE_ID = "code";
+const BOOTSTRAP_PATH = /^\/(?:edge-api|api)\/bootstrap(?:\/[A-Za-z0-9-]+\/app_start)?\/?$/;
+export function isPickerBootstrapRequest(method: string, pathname: string): boolean; // GET/HEAD-free: GET only
+export function narrowBootstrapAcceptEncoding(): string; // "gzip, deflate, br"
+export interface PickerModelEntry { id: string; name: string; contextWindow?: number }
+export function injectPickerModels(bootstrap: unknown, models: readonly PickerModelEntry[]): number;
+export function rewriteBootstrapBody(encoded: Buffer, contentEncoding: string | undefined, models: readonly PickerModelEntry[]): Buffer | null;
+export function rewrittenHeaders(raw: readonly string[], bodyLength: number): string[];
+```
+
+`injectPickerModels`: find `model_selector_config` (array) → surface `id === "code"` with array
+`models`; template = first entry whose id starts with `claude-`, not `disabled`, no
+`disabled_reason`, section not `deprecated`; for each model whose id is not already present:
+`structuredClone(template)`, set `id`, `name`, `section: "main"`, set or delete
+`context_window`, delete `disabled`, `disabled_reason`, `badge`, `tooltip`, `description`,
+`fast_mode` and every key matching `/version/i` (version gates); keep `thinking` and
+`capabilities`, which the intercept serves for routed models (effort translation, image
+handling); push. Returns the number added (0 = leave the body untouched). `rewriteBootstrapBody` decodes
+`gzip`/`x-gzip`/`deflate`/`br`/identity with `maxOutputLength` = the decoded cap, rejects
+anything else or oversize, parses JSON, injects, and returns identity-encoded UTF-8 or `null`.
+`rewrittenHeaders` drops `content-encoding`, `content-length`, `etag`, `digest`, `content-md5`,
+`transfer-encoding` and sets `content-length`.
+
+## picker-models.ts
+
+```ts
+export interface PickerRouteInput { nativeSlugs: string[]; routedModels: Desktop3pRoutedModel[]; profile?: OcxClaudeDesktopProfile; nativeContextCap?: NativeContextLimitsInput }
+export function buildPickerModels(input: PickerRouteInput): PickerModelEntry[];
+export interface PickerModelSnapshot { current(): { models: PickerModelEntry[]; builtAt: number } | null; refresh(): Promise; refreshIfStale(maxAgeMs: number): void }
+export function createPickerModelSnapshot(load: () => Promise, persistPath?: string): PickerModelSnapshot;
+// persistPath (/claude-picker/models.json, 0600): written after each successful build and
+// read synchronously at construction, so a bootstrap served right after a restart already injects
+// the last known routes while discovery refreshes in the background.
+```
+
+With a profile: `reconcileDesktopProfile` + `renderDesktopProfile` (src/claude/desktop-profile.ts:230,
+:296) in the gateway's order and labels; without one: every candidate, label
+`${displayModelId(id)} (${provider})`. Id: `native/` → `claudeCodeNativeAlias(slug)`,
+otherwise `aliasForRoute(provider, id)`; routes whose alias is `null` and real
+`anthropic/claude-*` routes are skipped (Anthropic's own rows already exist). Context window from
+the candidate. Refresh errors keep the previous snapshot.
+
+## picker-listener.ts
+
+```ts
+export interface PickerListenerOptions {
+ leaf: PemKeyPair;
+ models: () => readonly PickerModelEntry[];
+ upstream?: { host: string; port: number; servername: string; ca?: string }; // test seam; default claude.ai:443, system roots
+ /** Test seam: encoded bootstrap cap; production uses BOOTSTRAP_MAX_ENCODED_BYTES. */
+ maxEncodedBytes?: number;
+ log?: (line: string) => void;
+}
+export interface PickerListenerHandle { port: number; close(): Promise }
+export function startPickerListener(options: PickerListenerOptions): Promise;
+```
+
+`https.createServer({ cert, key, ALPNProtocols: ["http/1.1"] })` on 127.0.0.1:0.
+- `request`: build upstream headers from `req.rawHeaders` minus hop-by-hop
+ (`connection`, `keep-alive`, `proxy-connection`, `proxy-authorization`, `te`, `trailer`,
+ `transfer-encoding`, `upgrade`); `https.request` with `servername`,
+ `rejectUnauthorized: true`, `agent: false` or a dedicated keep-alive agent. Non-bootstrap:
+ `res.writeHead(status, filteredRawHeaders)` and `upRes.pipe(res)`; `req.pipe(upReq)`.
+ Bootstrap (`isPickerBootstrapRequest`, status 200, JSON content type): set accept-encoding to
+ `narrowBootstrapAcceptEncoding()` and hold the response head. Collect upstream chunks in order
+ while the running total stays within the encoded cap. When a chunk would push the total past
+ the cap, stop collecting: `writeHead` with the original filtered headers, write every collected
+ chunk and then that triggering chunk in order (each byte exactly once), and only then
+ `upRes.pipe(res)` for later data (the complete original body, unmodified). The collection
+ listener is removed before piping, and `upRes` is paused while the head and collected bytes are
+ written so no chunk is emitted between the switch; `pipe` then owns backpressure. If the
+ upstream ends within the cap, call `rewriteBootstrapBody`; on `null` or zero injections
+ `writeHead` the original headers and write the collected bytes; otherwise `writeHead` with
+ `rewrittenHeaders` and the rewritten body. An upstream error before `writeHead` → 502; after
+ it → destroy the client socket (the client sees a truncated response, never a spliced one).
+- `upgrade`: `tls.connect` to upstream with the same verification, write the request line and
+ raw headers, then `head`, and pipe both ways; destroy both on either error/close.
+- Errors: 502 with an empty body; log `picker ` only.
+
+## picker-runtime.ts
+
+```ts
+export type TunnelChoice = { kind: "intercept"; port: number } | { kind: "blind" };
+export interface PickerRuntime {
+ /** null → default behaviour. For claude.ai while the first refresh is pending, returns a promise that
+ * settles on `ready` or after PICKER_STARTUP_WAIT_MS (3 s), whichever is first; timeout or failure → blind. */
+ selectTunnel(host: string, port: number): TunnelChoice | null | Promise;
+ refreshTrust(): Promise;
+ /**
+ * Re-read the persisted config (options.readConfig, default loadConfig), recompute the mode
+ * (resolveClaudeDesktopMode(fresh, observeClaudeDesktopMode(fresh))) and pickerDesired(fresh, mode),
+ * refresh trust, then ensureStarted() when armable, else stop terminating. Never clears the
+ * disarm latch. The 60 s interval calls this. selectTunnel only reads the cached result.
+ */
+ refresh(): Promise;
+ /**
+ * Stop terminating claude.ai now, set the disarm latch and bump the arm generation. While latched,
+ * refresh() and ensureStarted() never arm. An ensureStarted() already in flight captured the old
+ * generation and must not arm when it completes.
+ */
+ disarm(): void;
+ /**
+ * Owner-only: called by the picker controller while it holds its lock, at the end of an enable
+ * whose checks passed. Clears the latch and recomputes the decision with the isBusy() check
+ * bypassed, so the next CONNECT is intercepted even before the lock is released.
+ */
+ rearm(): Promise;
+ ensureStarted(): Promise; // CA, leaf, listener, snapshot
+ /** First refresh() now, then the refresh interval; resolves with that first refresh. Called once after the CONNECT proxy binds. */
+ start(): Promise;
+ readonly ready: Promise;
+ status(): PickerRuntimeStatus; // desired, supported, trust, listenerReady, effective, reason, models, snapshotAt
+ stop(): Promise;
+}
+export function createPickerRuntime(options: { config: OcxConfig; readConfig?: () => OcxConfig; isBusy?: () => boolean; configDir: string; loadRoutes: () => Promise; security?: SecurityRunner; platform?: NodeJS.Platform; now?: () => number; trustTtlMs?: number }): PickerRuntime;
+export function pickerDesired(config: Pick, mode: ClaudeDesktopMode, platform?: NodeJS.Platform): boolean;
+// darwin && claudeDesktopIntegrationEnabled(config) (src/codex/desired-state.ts:214) && mode === "first-party"
+// && config.claudeCode?.intercept?.picker !== false
+// `mode` is the observation-aware resolved mode (010): the runtime computes
+// resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) at start and on every trust
+// refresh and caches it; status, apply wiring and the CLI pass the same resolved mode.
+```
+
+`selectTunnel` returns `{ kind: "intercept", port: listener.port }` for `claude.ai:443` only when
+the decision cached by the last `refresh()` says armed (desired from the persisted config, not
+latched), the listener
+is up, and the cached trust is `trusted` for the current CA fingerprint; `{ kind: "blind" }` for
+`claude.ai` otherwise; `null` for every other host. Trust is refreshed on `ensureStarted`, on
+`refreshTrust` and on a 60 s interval while desired; the interval never blocks the event loop.
+
+## connect-proxy.ts
+
+```diff
+ export interface ConnectProxyOptions {
+ interceptPort: number;
+ interceptHosts?: readonly string[];
++ /** Per-connection override, consulted before `interceptHosts`; `null` keeps the default. */
++ selectTunnel?: (host: string, port: number) => TunnelDecision | null | Promise;
++ // TunnelDecision = { kind: "intercept"; port: number } | { kind: "blind" }
+ dialUpstream?: (host: string, port: number) => Socket;
+ }
+- const intercept = target.port === 443 && options.interceptHosts.includes(target.host);
+- const upstream = intercept
+- ? connect({ host: "127.0.0.1", port: options.interceptPort })
+- : options.dialUpstream(target.host, target.port);
++ // The client socket is already paused; an async decision (only claude.ai during the picker's
++ // first refresh, bounded by the runtime) keeps it paused until it settles; a rejection → blind.
++ const selected = await Promise.resolve(options.selectTunnel?.(target.host, target.port) ?? null)
++ .catch(() => ({ kind: "blind" as const }));
++ const choice = selected
++ ?? (target.port === 443 && options.interceptHosts.includes(target.host)
++ ? { kind: "intercept" as const, port: options.interceptPort }
++ : { kind: "blind" as const });
++ const upstream = choice.kind === "intercept"
++ ? connect({ host: "127.0.0.1", port: choice.port })
++ : options.dialUpstream(target.host, target.port);
+```
+
+Loopback 403 and non-CONNECT 405 stay before the choice. The header comment names claude.ai as the
+only host that picker mode may terminate.
+
+Callback shape (audit wp3 r1, High). The diff above is the decision logic, not the literal code:
+`onData` stays synchronous. After the 405/403 checks it calls `dialFor(choice)` in the same tick
+when `selectTunnel` is absent or returns a non-promise, so the default path is unchanged; otherwise
+it runs `void Promise.resolve(decision).catch(() => blind).then(dialFor)`. `dialFor` returns
+without dialing when `socket.destroyed` (the client left while the decision was pending) and then
+runs today's dial, connect-timeout, error and splice block unchanged. `handleConnection` takes a
+`ResolvedConnectProxyOptions` type that adds the optional `selectTunnel`, and `startConnectProxy`
+copies `options.selectTunnel` into the resolved object.
+
+## runtime.ts / lifecycle
+
+`startClaudeIntercept` gains `loadPickerRoutes?: () => Promise`; it creates the
+picker runtime (`createPickerRuntime({ config: options.config, … })`), passes
+`selectTunnel: picker.selectTunnel` to `startConnectProxy`, and, once the CONNECT proxy has bound,
+starts the picker with `picker.start()`: an immediate `refresh()` (which calls `ensureStarted()`
+when armable and fills the cached decision) followed by the 60 s refresh interval. `start()`
+returns the first refresh's promise (`picker.ready`) so tests and status can await it. It stops the
+runtime in `stop()`. `getClaudePickerRuntime()` mirrors
+`getClaudeInterceptState()` for status and the wp4 routes. `claude-intercept-lifecycle.ts` passes a
+loader built from `fetchAllModels`, `filterCatalogVisibleModels`, `desktopVisibleNativeSlugs` and
+`nativeContextLimits` through dynamic imports (the same inputs `/api/sync` uses,
+src/server/management/config-routes.ts:213–231). `startServer` stays synchronous; no line is added
+to `src/server/index.ts`.
+
+Startup settlement (audit wp3 r1, High). `refresh()` catches its own failures (trust runner, CA,
+listener bind, snapshot load), records them as `status().reason` and leaves the decision blind, so
+`start()` resolves. `startClaudeIntercept` awaits `picker.start()` inside the same `try` that
+guards `startConnectProxy`. The picker handle is nullable (`let picker: PickerRuntime | null = null`). If creating the picker
+or `start()` still throws or rejects, it awaits `picker?.stop()` (picker listener and interval, only
+when construction returned), then always `proxy.close()` and `listener.stop(true)`, before
+rethrowing, so the lifecycle's catch never leaves a bound socket without a handle. `stop()` closes
+the picker, then the proxy, then the listener. A `createPicker` option on
+`StartClaudeInterceptOptions` is the test seam.
+
+## Tests (NEW unless noted; every new file registered in layout.json and test-layout-expected.json)
+
+| File | Cases (activation → observable) |
+| --- | --- |
+| `tests/claude-integration/claude-picker-ca.test.ts` | CA has critical nameConstraints permitting only claude.ai (parse extension bytes); leaf SAN is exactly claude.ai and chains (`X509Certificate.verify`); a TLS handshake through Bun (BoringSSL) with the picker CA as the only root accepts the claude.ai leaf and rejects a test-only leaf for `example.com` issued by the same CA; key file 0600; corrupt key regenerates; intercept CA has no nameConstraints (unchanged); a valid key-matching CA without the claude.ai constraint in the picker directory is regenerated with a new fingerprint |
+| `tests/claude-integration/claude-picker-trust.test.ts` | fake runner receives the exact argv for find/verify/trust/untrust; a verified leaf whose SHA-1 record is missing or different → untrusted; exit 0/1/other → trusted/untrusted/unknown; non-darwin → unsupported without spawning |
+| `tests/claude-integration/claude-picker-bootstrap.test.ts` | path matcher (both prefixes, org app_start, rejects others and POST); injection clones template, skips existing ids, drops fast_mode and version gates, leaves cowork and model_selector_state; gzip/br/deflate/identity round trip; malformed JSON, missing surface, unknown encoding and oversize → `null`; headers rewritten |
+| `tests/claude-integration/claude-picker-models.test.ts` | routed alias `ocx-claude-xai--grok-4.7` and native alias; profile order/labels match the gateway render; anthropic/claude routes skipped; snapshot keeps last good on loader failure |
+| `tests/claude-integration/claude-picker-listener.test.ts` | local https upstream (picker CA-issued fixture via the upstream seam): gzip body and two Set-Cookie headers pass byte-identical; SSE chunks arrive before the upstream ends; WebSocket upgrade echoes; bootstrap gets the injected entry with identity encoding; a bootstrap larger than the encoded cap (`maxEncodedBytes` seam set low, with the cap crossed in the middle of an upstream chunk) arrives byte-identical with its original headers; malformed bootstrap JSON arrives byte-identical; upstream with an untrusted cert → 502 |
+| `tests/claude-integration/claude-picker-runtime.test.ts` | startup: with a pre-existing selected picker profile, trusted current CA, persisted first-party and intent on, the first CONNECT to claude.ai after `start()` resolves (`await picker.ready`) is `intercept`, with no timer tick; |
+| (same file, continued) | a claude.ai CONNECT arriving while the first refresh is pending waits and is intercepted once `ready` resolves; with `ready` held past the 3 s bound it is blind; a snapshot persisted to `models.json` is injected into the first bootstrap after a restart before discovery completes; |
+| (same file, continued) | selectTunnel: claude.ai blind until desired+trusted+listening, intercept after; trust loss flips back on refresh; non-claude hosts → null; non-darwin never intercepts |
+| (same file, continued) | legacy install: owned first-party env in Claude Code settings, no saved `desktopMode`, picker intent unset → `pickerDesired` is true, so picker mode stays on by default across the upgrade; a `createPicker` that throws, and one whose `start()` rejects, each make `startClaudeIntercept` reject, and the proxy port binds again at once |
+| `tests/claude-integration/claude-intercept-proxy.test.ts` (MODIFY) | a selectTunnel override is consulted per connection; an async decision keeps the client socket paused and pipelined bytes are delivered after it settles; a rejected decision is blind; loopback/405 refusals unchanged; a client that closes while the decision is pending causes no upstream dial |
+
+Verifier: `bun test` on the files above plus `tests/claude-integration/claude-intercept*.test.ts`,
+`tests/server/claude-intercept-integration.test.ts`, `tests/lab/core-lab-boundary.test.ts`,
+`tests/test-layout.test.ts`, `tests/test-layout-tooling.test.ts`,
+`tests/ci-workflows/file-size-ratchet.test.ts`; `bun run typecheck`; `bun run structure:check`.
+
+
+## Desktop egress proxy (B-phase amendment)
+
+Found while wiring: one CONNECT proxy cannot serve both clients. The Code tab's Claude Code trusts
+only the intercept CA (`NODE_EXTRA_CA_CERTS`), so a claude.ai connection it opens through that proxy
+would fail against the picker terminator; Desktop trusts only the login keychain, so its own
+api.anthropic.com connections would fail against the intercept listener. Picker mode therefore gets
+its own CONNECT proxy on `claudePickerProxyPort` (the intercept proxy port + 1, or − 1 at 65535),
+started by `startClaudeIntercept` only when `loadPickerRoutes` is given (the server lifecycle always
+passes `loadPickerRoutes`), with `interceptHosts: []` and `selectTunnel` from the picker runtime. On
+it every host is blind except claude.ai while armed. The Claude Code proxy keeps its exact current
+behaviour and gets no `selectTunnel`. `ClaudeInterceptState.pickerProxyPort` (null when unwired or
+unbound) is what wp4 writes into `egressProxyUrl`. A bind failure on that port logs a warning, stops
+the picker and leaves the intercept pair running. Tests: the Claude Code proxy never consults the
+picker; the egress proxy blind-tunnels api.anthropic.com.
+
+## Audit record
+
+- wp3 round 1 (reviewer, FAIL, 3 High): persisted picker CA reload lacked constraint validation; the CONNECT diff awaited inside a synchronous callback and missed the options plumbing; picker startup failure could leave bound sockets. All three folded above. Round 2 GO-WITH-FIXES (1 High): a picker construction failure before assignment; folded as a nullable handle with a createPicker-throws test. Architect reflection ALIGNED, with the legacy first-party upgrade case added to the runtime tests.
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md b/devlog/_plan/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md
new file mode 100644
index 00000000000..bf25035e4f4
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/030_wp4_picker_activation.md
@@ -0,0 +1,194 @@
+# 030 — wp4: picker activation (egress profile, controls, default-on in first-party)
+
+Consumes: D8–D11 in [000](000_plan.md) and the wp3 runtime. After this phase a first-party apply
+on macOS turns picker mode on unless `claudeCode.intercept.picker === false`.
+
+The organising rule (D11): **while an opencodex server runs, every picker mutation — enable,
+disable, transition cleanup — runs inside that server, in one controller, serialized by one
+lock.** The CLI and the dashboard call its routes. The only thing a CLI does locally while a
+server runs is the keychain trust step, because the password dialog belongs to the operator's
+terminal session. With no server running, nothing can terminate claude.ai, so the CLI may remove
+picker artifacts locally, and enabling is refused.
+
+> B-phase amendment from wp3 (see 020, "Desktop egress proxy"): Desktop's `egressProxyUrl` names
+> `getClaudeInterceptState().pickerProxyPort`, the dedicated picker CONNECT proxy, never the Claude
+> Code proxy port. Every "proxy bound" check below means `pickerProxyPort !== null`, and
+> `applyDesktopPickerProfile({ proxyPort })` receives that port.
+
+## Files
+
+| Path | Change |
+| --- | --- |
+| `src/claude/desktop-3p-library.ts` | MODIFY: `DESKTOP_PICKER_ENTRY_NAME = "opencodex-picker"`; `isOwnedDesktopEntry` accepts it; gateway predicate does not |
+| `src/claude/desktop-picker-profile.ts` | NEW: apply/remove/inspect the owned egress profile; state in `/claude-picker/profile-state.json` |
+| `src/claude/desktop-picker.ts` | NEW: `DesktopPickerController` (server) with `enable`/`disable`/`status` under one async lock; `removeDesktopPickerArtifacts` (local cleanup when no server runs) |
+| `src/claude/desktop-first-party.ts` | MODIFY: nothing picker-specific beyond exports used by the controller |
+| `src/claude/intercept/runtime.ts` | MODIFY (audit wp4 pre-audit, Medium 5): create the controller next to the picker runtime (`isBusy: () => controller?.busy() ?? false`), expose `getClaudePickerController()`, clear it on stop and on a failed start |
+| `src/cli/claude-desktop.ts` | MODIFY: first-party apply delegates to the server when one runs; gateway apply and removal ask the server to clean up; `picker on|off|status|trust` subcommand; help |
+| `src/cli/ensure-desired-integrations.ts` | MODIFY: `ensureClaudeDesktopMatchesDesired` async and awaited by reconcile; durable-OFF picker cleanup |
+| `tests/providers/xai/grok-lifecycle.test.ts` | MODIFY: source-boundary assertions (:61, :79) expect the async declaration and (:86) the awaited call |
+| `src/server/management/agent-settings-routes.ts` | MODIFY: `GET/PUT /api/claude-desktop/picker`; status `firstParty.picker`; first-party apply/remove and gateway apply call the controller in process |
+| `src/server/management/native-integration-routes.ts` | MODIFY: first-party enable/disable call the controller; `persistDesktopModeMarker` returns the committed subtree and callers adopt it |
+| `src/server/management/config-routes.ts` | MODIFY: `/api/sync` Claude Desktop writer runs its post-discovery re-read, re-resolve and write inside `controller.transition` when a controller exists; race test in `claude-desktop-picker.test.ts` |
+| `src/server/management/route-registry.ts` | MODIFY: register GET and PUT `/api/claude-desktop/picker` as standard entries (like `/api/claude-desktop/first-party-bindings`, :155) |
+| `src/cli/capabilities.ts`, `skills/ocx/references/01_management_surface.md` (generated) | MODIFY: `claude-desktop.picker` capability for both routes; regenerate with `bun run skill:surface` |
+| `gui/src/components/ClaudeDesktopPicker.tsx` + `gui/src/styles/claude-desktop-picker.css` | NEW: picker card (toggle, state, offline and restart notes) mounted in first-party mode |
+| `gui/src/pages/ClaudeDesktop.tsx`, `gui/src/main.tsx` | MODIFY: mount the card; import CSS |
+| `gui/src/i18n/*.ts` (10) | MODIFY: `claudeDesktop.picker.*` keys |
+| `docs-site/src/content/docs/**/guides/claude-code.md` (8) | MODIFY: picker mode subsection (what it does, keychain prompt, offline dependency, how to turn off) |
+| `structure/clients/claude-desktop.md`, `structure/gui-and-management-api.md` | MODIFY: picker contract, controller, routes, card |
+
+## desktop-picker-profile.ts
+
+```ts
+export interface DesktopPickerProfileState { entryId: string; previousAppliedId: string | null }
+export type DesktopPickerProfileInspection =
+ | { kind: "absent" } | { kind: "applied"; entryId: string; proxyUrl: string }
+ | { kind: "not_selected"; entryId: string } | { kind: "unsafe"; reason: string };
+export function pickerEgressUrl(proxyPort: number): string; // http://127.0.0.1:
+export function applyDesktopPickerProfile(options: { proxyPort: number; configDir?: string } & Desktop3pConfigLibraryOptions):
+ { ok: true; changed: boolean; path: string } | { ok: false; reason: "gateway_selected" | "foreign_unreadable" | "write_failed" };
+export function removeDesktopPickerProfile(options: { configDir?: string } & Desktop3pConfigLibraryOptions):
+ { ok: true; changed: boolean } | { ok: false; reason: string; residualPaths?: string[] };
+export function inspectDesktopPickerProfile(options?: Desktop3pConfigLibraryOptions & { configDir?: string }): DesktopPickerProfileInspection;
+```
+
+Apply: refuse while an owned gateway row is selected; reuse the existing picker row or create one
+(`randomUUID`, name `opencodex-picker`); write exactly `{"egressProxyUrl":"http://127.0.0.1:"}\n`
+atomically; write `profile-state.json` with the current `appliedId` (unless it already is the picker
+row); then set `appliedId` to the picker row. Remove: if the picker row is selected, reselect
+`previousAppliedId` when that row still exists, else the owned standard row (created as `{}` like
+`removeDesktop3pStandardPivot`); delete the picker profile and its `.bak`; drop the metadata row;
+delete `profile-state.json`. Foreign rows and `_meta.json` keys other than `appliedId`/`entries` are
+preserved; `_meta.json` never carries opencodex keys.
+
+## desktop-picker.ts
+
+```ts
+export type DesktopPickerReason = "active" | "restart_required" | "unsupported_platform" | "not_first_party"
+ | "integration_off" | "disabled" | "proxy_unavailable" | "mode_not_committed" | "trust_pending"
+ | "trust_declined" | "profile_failed";
+export interface DesktopPickerStatus { desired: boolean; supported: boolean; trust: PickerTrustState;
+ profile: DesktopPickerProfileInspection["kind"]; listenerReady: boolean; effective: boolean;
+ reason: DesktopPickerReason; models: number; snapshotAt: number | null; lastBootstrapAt: number | null;
+ hint?: string; residual?: string[] }
+export interface DesktopPickerController {
+ enable(options: { persist: boolean; context: "cli-trusted" | "server"; callerAddedTrust?: boolean }): Promise;
+ disable(options: { persist: boolean }): Promise;
+ /**
+ * Run a whole Desktop mode transition under the controller lock: callers stage slow work
+ * (model discovery) first, then inside `fn` do cleanup → mode/profile commit → optional enable
+ * with the lock-free inner helpers `ops.disableLocked` / `ops.enableLocked`.
+ */
+ transition(fn: (ops: { disableLocked(o: { persist: boolean }): Promise;
+ enableLocked(o: { persist: boolean; context: "cli-trusted" | "server"; callerAddedTrust?: boolean }): Promise }) => Promise): Promise;
+ status(): Promise;
+ busy(): boolean;
+}
+export function createDesktopPickerController(deps: { runtime: PickerRuntime; readConfig: () => OcxConfig;
+ persistPreference: (value: boolean) => boolean; proxyPort: () => number | null; configDir: string; security?: SecurityRunner;
+ platform?: NodeJS.Platform }): DesktopPickerController;
+export function removeDesktopPickerArtifacts(options: { configDir?: string; security?: SecurityRunner }): Promise<{ ok: boolean; residual?: string[] }>;
+```
+
+One promise-chain lock serializes `enable`, `disable` and `transition`. The runtime's periodic and
+startup `refresh()` calls `isBusy()` and does not arm while the lock is held; the lock owner arms
+through `runtime.rearm()`, which is owner-only and bypasses that check (it is only ever called from
+inside the lock). Wiring in `src/claude/intercept/runtime.ts`: `let controller: DesktopPickerController
+| null = null; const picker = createPickerRuntime({ …, isBusy: () => controller?.busy() ?? false });
+controller = createDesktopPickerController({ runtime: picker, … });` and `getClaudePickerController()`
+exposes it to the management routes.
+
+**enable({ persist, context })**, inside the lock:
+1. Re-read the persisted config (`readConfig`) and check the conditions that do not depend on the
+ preference: macOS, persisted first-party mode, Desktop intent on, proxy bound. A failure returns
+ its reason and writes nothing. Then, if `persist`, commit `claudeCode.intercept.picker = true`
+ (an explicit `picker on` from a false preference is allowed).
+2. Re-read the persisted config again and check everything: macOS; persisted resolved mode is
+ first-party (`resolveClaudeDesktopMode(fresh, observeClaudeDesktopMode(fresh))`); Desktop
+ integration intent on; preference not false; the intercept proxy is bound
+ (`getClaudeInterceptState() !== null`). Failures → `unsupported_platform` / `mode_not_committed` /
+ `integration_off` / `disabled` / `proxy_unavailable`, nothing written.
+3. `ensurePickerCa`, `issuePickerLeaf`, `inspectPickerTrust`. If not trusted: `context: "server"` tries
+ `trustPickerCa` once and re-inspects; still untrusted → `trust_pending` with
+ `hint: "ocx claude desktop picker trust"`. `context: "cli-trusted"` means the CLI already ran the
+ trust step; untrusted then → `trust_declined`. Record whether this attempt added trust.
+4. Re-run the step-2 checks.
+5. `applyDesktopPickerProfile({ proxyPort })`.
+6. `runtime.rearm()` (clears the latch, refreshes, arms when everything holds) → `restart_required`
+ until a bootstrap has been served, then `active`.
+Any failure after step 3 that follows trust added by this attempt calls `untrustPickerCa`. For a request with `callerAddedTrust: true`, every refusal or failure at any step (including the step-1 and step-2 checks) compensates, but only when the trusted certificate is the current picker CA (SHA-1 match) and the owned picker profile is not selected — a selected profile means an earlier successful enable still depends on that trust; if that fails too the
+status carries `residual: ["trust"]`, `effective: false` and `hint: "ocx claude desktop picker off"`.
+
+**disable({ persist })**, inside the lock: `runtime.disarm()` (latch + generation bump) → if
+`persist`, commit `claudeCode.intercept.picker = false` → `removeDesktopPickerProfile` →
+`untrustPickerCa`. Failed steps are listed in `residual`; status is never "off" while the profile is
+selected or trust remains. `persist: true` only for an explicit `picker off`; mode-transition
+cleanup passes `false` and leaves the preference unset, so returning to first-party turns the
+picker back on.
+
+## Callers
+
+Every server-side Desktop mode change goes through `runDesktopTransition(fn)` (audit wp4 pre-audit, High 2): with a controller it is `controller.transition(fn)`; with none (intercept disabled, client role, failed intercept or picker proxy bind) it calls `fn` with offline ops, where `disableLocked` runs `removeDesktopPickerArtifacts` (no runtime exists, so nothing can terminate claude.ai) and `enableLocked` returns `proxy_unavailable` without writing anything. Gateway apply, first-party removal, native enable and disable, and `/api/sync` therefore keep today's behaviour when no controller exists, plus leftover-artifact cleanup. Tests: with the intercept disabled, gateway apply and native disable succeed and remove a leftover picker row; with the picker proxy unbound, first-party apply succeeds and reports the picker as `proxy_unavailable`.
+
+| Caller | Runs where | Picker call |
+| --- | --- | --- |
+| Management first-party apply (`POST /api/claude-desktop/apply`) | server | the whole transition inside `runDesktopTransition`, in today's order (audit wp4 pre-audit, High 1): env write with its rollback, then gateway cleanup with today's partial-cleanup reporting, then the committed and adopted mode, then `enableLocked({ persist: false, context: "server" })` when the preference is not false; a partial apply whose mode write failed does not enable |
+| `/api/sync` Claude Desktop writer (src/server/management/config-routes.ts:211–237) | server | discovery (`fetchAllModels`) staged first; then inside `runDesktopTransition`: re-read, re-resolve (010), and `writeDesktop3pConfig` only when the resolved mode is not first-party; no controller (intercept not running) → unchanged behaviour |
+| Management first-party removal / gateway apply | server | model discovery staged first; then inside `runDesktopTransition`: `disableLocked({ persist: false })`, the gateway write or env removal, and the mode commit |
+| Native enable (first-party branch) / native disable | server | inside `runDesktopTransition`: enable after `persistDesktopModeMarker` returns the committed subtree and it is adopted; disable before OFF cleanup and the intent commit |
+| `GET/PUT /api/claude-desktop/picker` | server | `PUT { enabled, persist }` → `enable({ persist, context })` with `context: "cli-trusted"` when the request carries `trustedLocally: true` (sent only by the CLI after its trust step), else `"server"`; or `disable({ persist })` |
+| CLI `ocx claude desktop apply --first-party` | CLI | on the local hub path with a live proxy, the same branch where gateway apply already delegates (src/cli/claude-desktop.ts:326), delegate to `POST /api/claude-desktop/apply { mode: "first-party" }` (audit wp4 pre-audit, High 3: the connected-client branch before it stays unchanged and never touches the picker); without one: apply locally as today and report the picker as `proxy_unavailable` |
+| CLI gateway apply / first-party removal | CLI | with a live proxy: the delegated server apply performs the disable; without one: `removeDesktopPickerArtifacts` locally |
+| CLI `picker on` | CLI | requires a live proxy (else `proxy_unavailable`); `PUT { enabled: true, persist: true }`; if the answer is `trust_pending`, run `picker trust` below and repeat the PUT with `trustedLocally: true` |
+| CLI `picker trust` | CLI | local `ensurePickerCa` read + `trustPickerCa` (operator's dialog), recording whether this run added trust; then `PUT { enabled: true, persist: false, trustedLocally: true, callerAddedTrust }`. Compensation for trust the CLI added is done by the server inside the lock: enable treats `callerAddedTrust: true` like trust added by the attempt itself, so any refusal or failure after its trust check untrusts it (residual reported if that fails), and success keeps it. The CLI compensates locally only when the PUT could not be delivered at all (connection refused: no server, so nothing can race). A timeout or lost response is ambiguous: the CLI does not touch trust and prints "state unknown — run `ocx claude desktop picker status`" |
+| CLI `picker off` | CLI | with a live proxy: `PUT { enabled: false, persist: true }`; without: persist false locally, then `removeDesktopPickerArtifacts`; prints "Fully quit and reopen Claude Desktop" |
+| `ensureClaudeDesktopMatchesDesired` durable OFF | CLI / update hook | becomes async and is awaited by `reconcileEnsureDesiredIntegrations` (:188, :199); with a live proxy `PUT { enabled: false, persist: false }`, else `removeDesktopPickerArtifacts` |
+
+Auth: GET and PUT `/api/claude-desktop/picker` are standard registry entries like
+`/api/claude-desktop/first-party-bindings` (route-registry.ts:155), so both the CLI admin token
+(`runtimeRequest`, src/cli/runtime-api.ts:140) and the dashboard gui-session are accepted; the
+`claude-desktop.picker` capability names both routes, as `tests/server/management-route-registry.test.ts`
+requires. `trustedLocally` is only a wording hint for the trust outcome; it never skips a check.
+
+Server startup: the runtime's first `refresh()` arms only when every piece already exists
+(persisted first-party, intent on, preference not false, trust for the current CA, profile selected
+with the current proxy URL, listener up). It never trusts or writes a profile; status reports what is
+missing with the `ocx claude desktop picker on` hint.
+
+Native persistence: `persistDesktopModeMarker` (native-integration-routes.ts:656) returns
+`{ ok: true; claudeCode } | { ok: false }`; callers adopt with `adoptPersistedClaudeCode`
+(src/config/live-reconcile.ts:123), fixing today's unadopted marker. The runtime itself decides from
+persisted reads, so adoption is for status and later whole-config saves.
+
+## GUI
+
+`ClaudeDesktopPicker` card (first-party only): title, one-line explanation, toggle
+(`PUT { enabled, persist: true }`), state line from `reason` (active / restart Desktop / waiting for
+the keychain step with the `hint` command / declined / proxy not running / unsupported on this OS),
+model count, and a fixed note: "While picker mode is on, Claude Desktop reaches the network through
+OpenCodex. If OpenCodex stops, Desktop is offline until it restarts or picker mode is turned off."
+Keys `claudeDesktop.picker.{title,hint,toggle,state.active,state.restart,state.trustPending,
+state.trustDeclined,state.proxyUnavailable,state.unsupported,state.notFirstParty,state.profileFailed,
+models,offlineNote}` in all ten catalogs.
+
+## Tests (NEW files registered in layout.json + test-layout-expected.json)
+
+| File | Cases |
+| --- | --- |
+| `tests/claude-integration/claude-desktop-picker-profile.test.ts` | apply creates the row, writes only egressProxyUrl, records previousAppliedId, selects it; re-apply idempotent; remove restores the previous selection, falls back to a standard row when it vanished, keeps foreign rows; gateway selected → refused; metadata write failure rolls back; gateway removal (`removeDesktop3pStandardPivot`) leaves the picker row alone |
+| `tests/claude-integration/claude-desktop-picker.test.ts` | enable order CA → trust → recheck → profile → rearm (recorded); preference false → `enable({ persist: true })` → armed; `enable({ persist: true })` with a failed independent condition (mode, intent, proxy, platform) leaves the preference unchanged; each failed precondition (mode not committed, intent off, proxy unbound, non-darwin) → its reason, nothing written; server-context trust failure → trust_pending + hint, no profile; cli-trusted but untrusted → trust_declined; newly added trust removed when the step-4 recheck fails or the profile write fails, pre-existing trust kept, failed untrust → residual ["trust"] and not effective; disable order disarm → persist (only when asked) → remove → untrust; **serialization**: an enable held pending, then a disable queued → after both, the runtime is disarmed and the profile absent; a disable held pending, then an enable queued → the enable runs after cleanup and re-arms only if its checks pass; an enable requested while a gateway `transition` is between cleanup and mode commit waits and then fails `mode_not_committed`; after a successful enable the CONNECT decision is `intercept` both while the lock is still held (owner `rearm()`) and after release, while a periodic `refresh()` during a pending disable does not arm; a `/api/sync` whose discovery resolves while a first-party `transition` holds the lock waits and then writes nothing; a server enable with `callerAddedTrust: true` that fails its recheck untrusts; one refused at the step-1 checks (for example `integration_off`) also untrusts; one refused while the owned profile is already selected from an earlier enable keeps the trust |
+| `tests/claude-integration/claude-picker-runtime.test.ts` (wp3 file, extended) | `disarm()` makes the next claude.ai CONNECT blind while the cached mode is still first-party; periodic `refresh()` never clears the latch and skips arming while the controller is busy; a disarm during an in-flight `ensureStarted()` stays disarmed; startup refresh arms only with every piece present |
+| `tests/claude-integration/claude-desktop-picker-routes.test.ts` | `PUT { enabled:false, persist:true }` disarms and persists false; `PUT { enabled:true, persist:true }` from a false preference re-arms; both routes accept the admin token; CONNECT decision (`selectTunnel("claude.ai", 443)`, trust and listener faked) is `intercept` after management and native first-party apply from an explicit `desktopMode: "gateway"` marker and after native OFF→ON on a server whose runtime started with the integration OFF, and `blind` after native OFF and after management gateway apply even when a periodic refresh runs |
+| `tests/claude-integration/claude-desktop-cli.test.ts` (MODIFY) | `picker on|off|status|trust` parsing and usage errors; `picker trust` sends `callerAddedTrust` truthfully; a refused PUT leaves compensation to the server (fake server untrusts under its lock); connection refused before sending → local untrust of trust this run added; a PUT timeout while the server enable is held before profile selection → the CLI leaves trust alone and the later successful enable keeps it; `on` without a live proxy → proxy_unavailable; `off` offline removes artifacts locally; CLI first-party apply with a live proxy delegates to `POST /api/claude-desktop/apply { mode: "first-party" }` (fake runtimeRequest), also from a durable-OFF start |
+| `tests/claude-integration/claude-desktop-first-party.test.ts` (MODIFY) | first-party apply (management, native) enables the picker by default and not when `intercept.picker === false` or when the mode write failed; gateway apply disables it without writing the preference; `ensureClaudeDesktopMatchesDesired` is awaited and its OFF branch removes a selected picker row (live: PUT; offline: local) |
+| `tests/server/management-route-registry.test.ts` (MODIFY) | picker routes registered as standard entries and named by the capability |
+| `tests/ci-workflows/skill-ocx.test.ts` | surface map current |
+
+Verifier: the files above plus `tests/providers/xai/grok-lifecycle.test.ts`, `bun run typecheck`,
+`bun run skill:surface:check`, `bun run structure:check`, `bun run lint:gui`, `bun run build:gui`,
+`cd gui && bun test --isolate tests`.
+
+## Audit record
+
+- wp4 pre-audit (reviewer, FAIL: 3 High, 2 Medium) folded: first-party apply keeps its env-first order inside the transition; runDesktopTransition defines the no-controller path; CLI delegation is limited to the local hub branch; callerAddedTrust is in the enable signatures and forwarded by the route (test in claude-desktop-picker-routes); runtime.ts is in the file inventory. Round 2 GO-WITH-FIXES (2): the controller gets a late-bound proxyPort accessor; DesktopPickerStatus carries lastBootstrapAt.
diff --git a/devlog/_plan/260924_claude_desktop_picker_mode/040_wp5_live_proof_pr_merge.md b/devlog/_plan/260924_claude_desktop_picker_mode/040_wp5_live_proof_pr_merge.md
new file mode 100644
index 00000000000..ec35fd1ed34
--- /dev/null
+++ b/devlog/_plan/260924_claude_desktop_picker_mode/040_wp5_live_proof_pr_merge.md
@@ -0,0 +1,61 @@
+# 040 — wp5: live proof, PR, CI, squash merge
+
+## Live proof (macOS, this machine)
+
+The operator's service runs the `dev` checkout. The proof runs this branch as that service only
+for the proof window, then returns it to `dev` if the PR does not merge.
+
+1. Commit everything; record the branch head.
+2. In `/Users/jun/Developer/new/700_projects/opencodex` (clean `dev`): `git fetch origin
+ codex/claude-desktop-picker-mode` and `git switch --detach FETCH_HEAD`; `bun run build:gui`;
+ `ocx service restart`; verify `/healthz`, PID path, listener.
+3. `ocx claude desktop apply --first-party` (the operator's saved mode is already first-party):
+ the CLI delegates to the running service; expect the risk warning and a picker status. If the
+ service could not raise the keychain dialog the status is `trust_pending`: run
+ `ocx claude desktop picker trust` in the terminal, where the macOS password dialog is the
+ operator's step (NEEDS_HUMAN). Record which path showed the dialog (service or CLI). Then
+ `ocx claude desktop picker status` → `active` or `restart_required`.
+3b. Name-constraint check on the Apple path: issue an ephemeral leaf for `example.com` from the
+ picker CA into `/private/tmp` (never into the config directory) and run
+ `security verify-cert -q -L -c -p ssl -n example.com -k `; record the
+ exit code. Non-zero → the PR may state that macOS enforces the constraint; zero → the PR states
+ that only the key's confidentiality protects other names on this OS. Delete the ephemeral leaf.
+4. Quit and reopen Claude Desktop (Computer Use). Check `main.log` for the egress pin line pointing
+ at the picker proxy port (`pickerProxyPort`, the intercept port + 1, never the Claude Code proxy
+ port), record the applied profile's exact `egressProxyUrl`, and find the picker log line
+ `picker GET bootstrap 200`.
+5. Code tab → model picker: screenshot showing opencodex models by name next to Anthropic's.
+6. Pick one (e.g. the xai Grok route), send "Reply with exactly: OCX-PICKER-PROBE. Do not use any
+ tools." Screenshot the reply; `usage.jsonl` must show the routed provider on the `messages`
+ ingress within the minute.
+7. Connectivity: Chat tab still loads (screenshot), a claude.ai WebSocket session (Code session
+ list refresh) still works.
+8. Dashboard screenshots: mode selector with the gateway default badge and the first-party risk
+ callout; picker card active.
+9. If the operator declines the dialog: record NEEDS_HUMAN for criterion c-8, keep the rest.
+10. After the proof, if the PR has not merged, roll back in this order while the branch service is
+ still running: `ocx claude desktop picker off` (branch CLI), verify the `opencodex-picker` row is
+ gone from `_meta.json`, `security find-certificate -a -Z -c "opencodex Claude Desktop Picker CA"`
+ finds nothing in the login keychain, and `claudeCode.intercept.picker` is false; fully quit and
+ reopen Desktop and confirm its log shows no egress pin; only then return the service checkout to
+ `dev` (`git switch dev`, rebuild GUI, restart). Record each result as rollback proof. If the PR
+ has merged, fast-forward `dev` and restart instead; picker stays under the new code's control.
+
+## PR
+
+- Title: `feat(claude): gateway by default, first-party risk warning, and Desktop picker mode`.
+- Body per `.github/PULL_REQUEST_TEMPLATE.md`: Summary (problem, behavior before/after), screenshots
+ uploaded to the `pr-assets` branch and linked by commit SHA, Verification (commands + results,
+ what was not run locally and why), Checklist. No mention of third-party projects.
+- Security review: an independent gpt-6-sol reviewer reads the full diff against the untracked
+ threat model at `.tmp/260924_claude_desktop_picker_mode/threat_model.md`; findings are folded
+ before merge and summarized in the PR.
+
+## CI and merge
+
+- Exact-head check-runs for the PR head (aggregate `ci` and its producers) must be completed and
+ successful; skipped path-gated jobs are listed as skipped, not as passed.
+- Merge-result preflight: `git merge-tree --write-tree origin/dev HEAD`, file-size preflight on that
+ tree (offenders 0), typecheck and focused suites on a worktree of the merge result.
+- `gh pr merge --squash --admin --match-head-commit ` (user authorized merge).
+- Verify `origin/dev` tip is the squash commit whose tree equals the verified merge-result tree.
diff --git a/devlog/_plan/260924_cursor_fast_pricing/000_plan.md b/devlog/_plan/260924_cursor_fast_pricing/000_plan.md
new file mode 100644
index 00000000000..f72d87d59db
--- /dev/null
+++ b/devlog/_plan/260924_cursor_fast_pricing/000_plan.md
@@ -0,0 +1,30 @@
+# Cursor Fast pricing correction
+
+## Objective
+
+Price Cursor Claude Opus Fast usage at Cursor's published Fast rates for Opus 4.8, 5 and 5.5.
+
+## Scope
+
+- Modify `src/usage/expected-prices.ts` to recognize explicit Cursor Claude `-fast` IDs and register Cursor Fast multipliers for base model selections.
+- Modify `src/usage/cost.ts` to apply the explicit-ID rate after user overlays have won and before the final expected-price result is returned.
+- Add focused usage tests covering explicit fast IDs, persisted `tierOutcome` from `computeEntryCost`, standard turns, and user overlay precedence.
+- Do not modify request logging: `src/adapters/cursor.ts:138-148` creates a `cursor-variant` tier outcome, `src/server/request-log.ts:767-790` stores it, and `src/usage/summary.ts:270-292` consumes it.
+
+## Rates
+
+Cursor's official model pages ([Opus 4.8](https://cursor.com/docs/models/claude-opus-4-8),
+[Opus 5](https://cursor.com/docs/models/claude-opus-5), [Opus 5.5](https://cursor.com/docs/models/claude-opus-5-5)) publish:
+
+- Opus 4.8: standard 5/25/0.5/6.25; Fast 10/50/1/12.5.
+- Opus 5: standard 5/25/0.5/6.25; Fast 10/50/1/12.5.
+- Opus 5.5: standard 4/20/0.2/5; Fast 8/40/0.4/10.
+
+Opus 4.7 Fast is excluded because Anthropic says Fast requests error for that model.
+
+## Acceptance
+
+- Explicit Cursor Claude `-fast` IDs resolve to an official Fast tuple through the cost resolver.
+- A persisted Cursor `tierOutcome` with `canonical:"priority", wireKind:"cursor-variant", wireValue:"fast", fastOutcome:"applied"` doubles the base rate for the three supported models.
+- Standard and user configured prices remain correct.
+- Focused usage tests and typecheck pass.
diff --git a/devlog/_plan/260924_cursor_fast_pricing/010_implementation.md b/devlog/_plan/260924_cursor_fast_pricing/010_implementation.md
new file mode 100644
index 00000000000..a2d5ed9f169
--- /dev/null
+++ b/devlog/_plan/260924_cursor_fast_pricing/010_implementation.md
@@ -0,0 +1,8 @@
+# Implementation
+
+1. Add a Cursor Claude Fast multiplier helper in `src/usage/expected-prices.ts` using the existing `normalizeCursorClaudeId` parser. It returns 2 only for fast Opus 4.8, 5 and 5.5 IDs.
+2. Add Cursor priority pricing rules for the canonical base IDs. These rules do not require a response echo because the Cursor adapter's variant serialization is the observed wire evidence.
+3. In `resolveMatchedPriceExact`, return user overlays first as today. For compiled Cursor expected or model-level prices, multiply only explicit fast IDs. Preserve `source`, `sourceRef`, and user overlay behavior.
+ Unsupported Fast spellings are fail-closed; supported explicit Fast rows carry Cursor's
+ direct source URL and `verified` provenance.
+4. Add a new usage test file in the usage domain and register it in both layout registries.
diff --git a/devlog/_plan/260924_cursor_fast_pricing/020_verification.md b/devlog/_plan/260924_cursor_fast_pricing/020_verification.md
new file mode 100644
index 00000000000..2901bb16da0
--- /dev/null
+++ b/devlog/_plan/260924_cursor_fast_pricing/020_verification.md
@@ -0,0 +1,8 @@
+# Verification
+
+- Run the new Cursor Fast usage test and the existing usage cost test.
+- Run `bun run typecheck`.
+- Run `bun run structure:check` after staging the plan files.
+- Run `bun run privacy:scan` because usage and pricing metadata are changed.
+- Run a gpt-6-sol read-only adversarial review of the final diff.
+- Push `codex/260924-cursor-fast-pricing` and open one PR to `dev`; the coordinator merges it.
diff --git a/devlog/_plan/260924_l3_provider_adapters/010_plan.md b/devlog/_plan/260924_l3_provider_adapters/010_plan.md
new file mode 100644
index 00000000000..960e278485f
--- /dev/null
+++ b/devlog/_plan/260924_l3_provider_adapters/010_plan.md
@@ -0,0 +1,122 @@
+# L3 provider adapters — diff-level plan (wp1)
+
+Lane L3 bundles seven independent provider-adapter fixes into one PR against `dev`
+(branch `codex/260924-l3-provider-adapters`, base `be0b5294e5`). Each item has its own
+writer scope, and the lane lead registers every new test file in
+`scripts/test-layout/layout.json` `explicit` and `tests/fixtures/test-layout-expected.json`.
+
+## Items and diffs
+
+### 1. #5692 DeepSeek quota currency symbol
+- `src/providers/quota/vendor-probes-key.ts` `fetchDeepSeekQuota`: read `preferred.currency`,
+ map USD→`$`, CNY→`¥`, anything else → `"
OpenCodex
const consentOwner = document.querySelector("#consentOwner"); const takeOver = document.querySelector("#takeOver"); const stayGuest = document.querySelector("#stayGuest"); +const surface = document.querySelector("main"); +const statusMark = document.querySelector("#statusMark"); +const progressBar = document.querySelector("#progressBar"); +const stepCount = document.querySelector("#stepCount"); +const steps = document.querySelector("#steps"); -const MARKS = { done: "✓", failed: "✕", active: "…", pending: "·" }; +const MARKS = { done: "✓", failed: "✕", active: "", pending: "" }; let phases = []; +// One surface state drives the spinner, the progress bar and the status mark together, so the +// spinner can never keep turning over a failure or a question the user has to answer. +function setSurface(state) { + surface.dataset.state = state; + surface.setAttribute("aria-busy", state === "running" ? "true" : "false"); + statusMark.textContent = state === "failed" ? "✕" : state === "consent" ? "?" : ""; + if (state === "failed") steps.open = true; +} + function render(progress) { const completed = new Set((progress && progress.completed) || []); const failedPhase = (progress && progress.failedPhase) || null; @@ -166,6 +237,12 @@OpenCodex
row.append(mark, label); phaseList.append(row); } + const total = phases.length; + const finished = phases.filter((phase) => completed.has(phase.id)).length; + const position = phases.findIndex((phase) => phase.id === current); + const step = position >= 0 ? position + 1 : finished; + progressBar.style.width = total ? Math.round((Math.max(finished, step - 0.5) / total) * 100) + "%" : "0"; + stepCount.textContent = total && step > 0 && !failedPhase ? step + " / " + total : ""; } function apply(progress) { @@ -181,6 +258,7 @@OpenCodex
stayGuest.disabled = false; } const failed = progress.phase === "failed"; + setSurface(failed ? "failed" : progress.consent ? "consent" : "running"); failure.hidden = !failed; retry.disabled = !progress.canRetry; if (failed) { @@ -192,6 +270,7 @@OpenCodex
function reportPageFailure(message, error) { const cause = error && error.message ? error.message : String(error); + setSurface("failed"); headline.textContent = "OpenCodex could not read its own startup state."; detail.textContent = message; failure.hidden = false; @@ -250,6 +329,7 @@OpenCodex
async function start() { if (!invoke || !listen) { + setSurface("idle"); headline.textContent = "This page is the OpenCodex desktop shell's startup surface."; detail.textContent = "Open it from the OpenCodex app."; return; diff --git a/desktop/ui/logo.png b/desktop/ui/logo.png new file mode 100644 index 00000000000..894ad8ca71e Binary files /dev/null and b/desktop/ui/logo.png differ diff --git a/desktop/ui/update.html b/desktop/ui/update.html new file mode 100644 index 00000000000..8d7ae61cc5e --- /dev/null +++ b/desktop/ui/update.html @@ -0,0 +1,123 @@ + + + + + +OpenCodex update
+Reading update status…
+ +
+
+
+
+
+ {t("claudeDesktop.mode.firstPartyRisk")}
++ )} +``` + +The callout also renders under the status bar when `status.riskWarning` is set and the picker +fieldset is not showing first-party (so an applied first-party install sees it after reload). +Styling goes in the existing Claude Desktop stylesheet only if it has room under the ratchet; +otherwise in a new `gui/src/styles/claude-desktop-risk.css` imported from `gui/src/main.tsx`. + +i18n: English source + +```ts +"claudeDesktop.mode.firstPartyRisk": "Account risk: first-party sends your Claude subscription traffic through a local interception proxy. Anthropic may treat this as a terms violation and suspend the account. Gateway is the default.", +``` + +plus the nine translations with the same three facts (proxy, possible suspension, gateway default). + +Docs (all eight guides): the mode section states gateway is the default; the first-party +subsection opens with + +```md +:::caution[Account risk] +First-party mode sends your Claude subscription traffic through a local interception proxy. +Anthropic may treat this as a violation of its terms and suspend the account. Gateway is the +default; choose first-party only if you accept that risk. +::: +``` + +and the dashboard recap line (`claude-code.md:760` in English) names gateway as the default. + +## Tests + +`tests/claude-integration/claude-desktop-first-party.test.ts` + +1. "mode resolution: explicit wins, applied gateway fingerprint keeps gateway, owned first-party + settings keep first-party, otherwise gateway" (replaces :64). +2. "implied apply mode is gateway; a legacy first-party install keeps first-party unless the + intercept is disabled" (replaces :78) → renamed "implied apply mode is gateway; a legacy + first-party install keeps first-party, and with the intercept disabled the apply is refused + with intercept_disabled instead of switching to gateway". +3. "CLI apply flags: default gateway, --first-party explicit, legacy shape flags imply gateway, + conflicts rejected" (replaces :86). +4. "POST /api/claude-desktop/apply defaults to gateway, first-party on request, and returns the + risk warning" (replaces :138). +5. "native toggle: enable applies gateway by default; a legacy first-party install keeps + first-party and its message carries the risk" (replaces :182). +6. NEW "status carries riskWarning for first-party and null for gateway". +7. NEW "/api/sync does not write a gateway profile while first-party is resolved" (fake + `writeDesktop3pConfig` dep asserts it is not called). Activation: config with explicit + `desktopMode: "first-party"` and `claudeDesktop` integration enabled. +7b. NEW "/api/sync re-resolves after discovery": a fake `fetchAllModels` resolves only after the + test persists `desktopMode: "first-party"`; the writer must not be called. +8. NEW "a foreign HTTPS_PROXY in settings.json is not first-party evidence" (settings kind + `foreign` → gateway). +9. NEW "a selected owned gateway row outranks legacy first-party settings" (both observed → + gateway). +10. NEW "a roster update does not write a gateway profile on an explicit first-party install" and + "… nor when the mode switches to first-party while its discovery is pending" (fake + `fetchAllModels` resolves after the switch; fake `writeDesktop3pConfig` must not be called). + +`tests/claude-integration/claude-desktop-mode-explanation.test.ts`: implicit gateway where +first-party can run → the default line, the first-party command and the risk text; explicit +`--gateway` → nothing; connected client or disabled intercept → nothing. + +Verifier (run at P of wp2, before writing it into the plan as proof): +`bun test tests/claude-integration/claude-desktop-first-party.test.ts tests/claude-integration/claude-desktop-cli.test.ts tests/claude-integration/claude-desktop-mode-explanation.test.ts`, +`bun run typecheck` (locale records are `Record "` prefix (trimmed, upper-cased; empty/missing → `$`
+ keeps legacy behaviour only when the row has no currency). Both label branches use it.
+- Test: new sibling `tests/providers/deepseek-quota-currency.test.ts` (provider-quota.test.ts sits at
+ its 3763-line cap): CNY-only row → `API balance (¥76.88)`; USD row → `$`; CNY with granted → both
+ amounts use `¥`; unknown currency (e.g. EUR) → code prefix.
+
+### 2. #5689 Google array without items
+- `src/adapters/google-tool-schema.ts` `sanitizeSchema`: after the `items` block, when
+ `out.type === "array"` and `out.items` is absent (source had no items, tuple items dropped, invalid
+ items widened, or budget ran out), set `out.items = { type: "string" }` and count a loss
+ (`invalid-schema-widened`) only when the source had no usable items. Valid `items` untouched;
+ nullable arrays keep `nullable`. Also covers `anyOf`-normalized arrays (apply after anyOf merge).
+- Tests in `tests/adapters/google/google-tool-schema.test.ts` (486 lines, uncapped): issue repro
+ `{type:object, required:[values], properties:{values:{type:array}}}`; nested array; tuple items;
+ existing valid items byte-identical; non-array unaffected.
+
+### 3. #5695 mimo token-plan capacity facts
+- `src/providers/registry/entries-extended.ts` `mimo` entry: add
+ `modelContextWindows` (all four ids 1_048_576), `modelMaxOutputTokens` (all four 131_072),
+ `modelInputModalities` (v2.6-pro, v2.6-flash, v2.5: `["text","image"]`; v2.5-pro: `["text"]`).
+ Source: mimo.mi.com/models/en-US/ (fetched 2026-09-24: 1M context, 128K output; v2.6-pro/flash
+ and v2.5 input Text/Image/Video/Audio, v2.5-pro Text). Video/audio are not representable in the
+ catalog's modality vocabulary, so only text/image are claimed. Keep `noVisionModels` and
+ `preserveCustomDestination`; update the comment.
+- Test: registry/catalog assertion in a sibling test file (e.g. `tests/providers/mimo-token-plan-capacity.test.ts`).
+
+### 4. Carry #5693 (Vadevious) on #5725
+- `src/adapters/openai-chat/serialized-tool-call-content.ts`: add `repeatedCallIn` built on the
+ current `callsIn`/`blockAt`; in `duplicatedSerializedToolCallRanges` suppress the adjacent identical
+ pair only when exactly one structured call matches (compare with `freeformBody`); in
+ `repairArgumentsDuplicatedBesideSerializedCall` reduce a doubled `input` (direct or newline joined)
+ when `input` is the only key.
+- Tests: port the PR's tests into `tests/adapters/openai/openai-chat-serialized-tool-call-content.test.ts`
+ and `tests/responses/responses-chat-tool-call-content.test.ts`; docs: adapters.md bullet,
+ `structure/providers/chat-compat.md` paragraph, ADR-5548 consequences line.
+- Commit trailer: `Co-authored-by: Vadevious `.
+
+### 5. #5698 command-code filter (marciodps)
+- `src/adapters/command-code-tool-text.ts` per the reporter's final patch, with fixes:
+ mid-prose marker split in `textDelta` (not when the prefix is only whitespace on a probing block
+ with an empty probe — the existing probe already holds `"\n"`); shared
+ `probeBlockText` / `queueProseDelta` helpers; `breakOpenBlocks` skips held blocks;
+ `isLooseEnvelope` (null-safe `exec` result) used in `matchNative` and `settle` to drop malformed
+ envelopes naming a declared tool.
+- Tests: new sibling `tests/providers/command-code-tool-text-prose-split.test.ts`: prose+markup in
+ one delta with native duplicate (dropped); prose+markup clean finish (restored); marker at index 0
+ after streaming prose; leading-whitespace markup still held; interleaved reasoning keeps held
+ block; captured malformed `junk ` does not throw; never-closing
+ partial markup released as text.
+- Commit trailer: `Co-authored-by: marciodps ` (or their commit email if public).
+
+### 6. #5096 remainder: `ocx effort model` slug resolution
+- `src/cli/effort.ts` `inspectModelEffort`: after splitting provider/model, when the model is not a
+ known id, decode it with `decodeRoutedModelId(model, knownModelIdsForProvider(provider, prov, config))`
+ (router.ts / slug-codec.ts). Report `model` as the resolved native id and add `requestedModel` when it
+ differs. Unresolvable ids keep today's behaviour.
+- Tests: new sibling `tests/cli/cli-effort-slug.test.ts`: `command-code/deepseek-deepseek-v4.1-flash`
+ and `command-code/deepseek/deepseek-v4.1-flash` report the same ladder as
+ `COMMAND_CODE_MODEL_REASONING_EFFORTS["deepseek/deepseek-v4.1-flash"]`; same for GLM 5.3 FlashX and
+ Gemini 3.8 Flash (the ids named in the latest issue comment). Ladders are read from the SSOT, not
+ restated, so no tier is invented.
+
+### 7. #5576 grok-4.7-build-fast
+- `src/providers/registry/entries-core.ts` xAI entry: add `grok-4.7-build-fast` to
+ `modelContextWindows` (500_000), `modelReasoningEfforts` (low..xhigh), `modelDefaultReasoningEfforts`
+ (high), `modelInputModalities` (text,image). Not added to `XAI_MODELS`: xAI documents Grok 4.7 Fast as
+ "the same model served on faster infrastructure… not available on the public xAI API"
+ (docs.x.ai/developers/grok-4-7, fetched 2026-09-24). No service-tier claim.
+- Test: new sibling `tests/providers/xai/grok-47-build-fast-metadata.test.ts` asserting the four facts
+ equal grok-4.7's.
+
+## Out of scope
+#5421; the "per-model maps lost on restart" half of #5576; the opencode-go `openai-chat` wiring from
+#5698 (reported against #5499 in the PR body).
+
+## Verification
+`bun run typecheck`; each focused test file above plus existing neighbours
+(`tests/providers/command-code-tool-text.test.ts`, `tests/providers/provider-quota.test.ts`,
+`tests/adapters/google/google-tool-schema*.test.ts`, `tests/cli/cli-effort.test.ts`, xAI and catalog
+parity suites); `bun run test:changed`; `bun run privacy:scan`; `bun run structure:check`.
+
+
+## Audit fold (A, round 1 verdict FAIL → amendments)
+
+1. Item 2 materializes `items: {type:"string"}` without adding a loss category (representation fix, keeps
+ `lossy:false` contracts). Budget-exhausted return stays untouched (`google-tool-schema.test.ts:479-481`).
+ Existing tests that pin an array output without items (contract test ~578-587, tuple case ~303-322) update
+ their expected `parameters` only; category sets stay. `structure/providers/google.md` gains one sentence.
+2. Item 1 also rewrites `tests/providers/provider-quota.test.ts:1131-1136` (CNY row) to `¥`, line-neutral
+ (file at its 3763 cap).
+3. Item 7: add `grok-4.7-build-fast` to `modelContextWindows`, `modelReasoningEfforts`,
+ `modelDefaultReasoningEfforts`, `modelInputModalities`, plus the reasoning-model parameter lists xAI documents
+ for reasoning models (`noStopModels`, `noPenaltyModels`, `preserveReasoningContentModels`). Not added:
+ `modelWireDefaults` and `modelSupportsServiceTier` (live-probed on grok-4.7 only), `XAI_MODELS`. Update exact
+ literals: `provider-registry-parity.test.ts:1319`, `xai-no-stop.test.ts:47`, `xai-transport.test.ts:634,844`.
+ `structure/providers/xai-grok.md` gains a line.
+4. Item 6: the decoded id replaces `modelId` before `modelInList` / `configuredReasoningEfforts` /
+ `reasoningEffortMapFor`.
+5. Item 4: compare with `freeformBody` on both sides, tail must be exactly one repetition, add a leading-newline
+ case. Rebuttal: the newline-joined doubled-input repair stays — #5693 commit 7854ac8 added it with its own
+ regression test and the PR body documents it.
+6. Item 5 source is marciodps' third follow-up comment on #5698 (2026-09-23T19:33Z), full patch vs 2.64.0.
+ Preserve the marker-free fast path (`command-code-tool-text.test.ts:388`), the queue-visit bound (`:324`),
+ and whitespace-probe salvage.
+7. Lead registers every new test file in both layout maps.
+
+
+Round 2 verdict PASS. Residuals: item 2 drops the original "budget ran out" clause, and the two contract
+tests assert only loss reports, so no expectation needs editing there; item 7 keeps grok-4.7-build-fast on
+the provider-default wire, to be re-checked on first live discovery.
diff --git a/devlog/_plan/260924_l4_codex_cli_service/000_roadmap.md b/devlog/_plan/260924_l4_codex_cli_service/000_roadmap.md
new file mode 100644
index 00000000000..ec3ed897289
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/000_roadmap.md
@@ -0,0 +1,14 @@
+# L4 roadmap — Codex integration, CLI and service
+
+Branch codex/260924-l4-codex-cli-service from origin/dev be0b5294e5. One PR to dev. Merge is the coordinator's.
+
+| Unit | Doc | Items | Method |
+|---|---|---|---|
+| wp1 | 010 | #5713, #5703, #5548 slice | squash-diff apply per PR, one commit each with Co-authored-by |
+| wp2 | 020 | #5221 | rebuild on dev by DeepSeek writer; sibling test files |
+| wp3 | 030 | #5009 | squash-diff apply, review sender/admission checks |
+| wp4 | 040 | #5694 | DeepSeek writers: default-on 98% hard lock |
+| wp5 | 050 | publish | rebase, validate, push, PR, checks |
+
+Ratchet: tests/fixtures/file-size-baseline.json caps only move down; every commit re-runs tests/test-layout.test.ts and the file-size test.
+
diff --git a/devlog/_plan/260924_l4_codex_cli_service/010_carry_ready_prs.md b/devlog/_plan/260924_l4_codex_cli_service/010_carry_ready_prs.md
new file mode 100644
index 00000000000..ca9be0de843
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/010_carry_ready_prs.md
@@ -0,0 +1,20 @@
+# 010 — carry #5713, #5703, #5548 slice
+
+## #5713 (fixes #5699) — author 정우철
+Files: src/client/connect.ts, src/client/state.ts (pending-connect fingerprint marker client-connect-pending), src/service/cli.ts (removeServiceTokenAfterUninstall under client lifecycle + config mutation locks: removed|absent|retained|unverified), structure/clients/claude-desktop.md, structure/runtime.md, docs-site guides/remote-hub.md (en+ko), tests/clients/client-connect.test.ts, tests/service/service-secrets.test.ts.
+Method: git diff merge-base..carry-5713 | git apply -3. Check other docs-site locales of remote-hub.md for consistency (PR touched en and ko only).
+Tests: bun test tests/service/service-secrets.test.ts tests/clients/client-connect.test.ts.
+Security: credential deletion boundary — uninstall deletes the service token only when client state is disconnected and no pending marker owns the fingerprint.
+
+## #5703 (fixes #5701) — Konstantinos <37538071+konstantinosbotonakis@users.noreply.github.com>
+Files: src/codex/native-residue.ts, structure/config.md, tests/codex-integration/codex-native-residue.test.ts. Check file-size caps for the test file.
+
+## #5548 slice — Vadevious
+Only src/codex/home.ts (import expandUserPath from ../config/paths), structure/codex-home.md line, tests/codex-integration/codex-home-wsl.test.ts (new: register in layout.json explicit + test-layout-expected.json if not matched by a seed). Excluded: tests/cli/cli-help.test.ts, tests/service/service-probe-docker.test.ts, tests/service/service.test.ts.
+Audit fold: codex-home-wsl.test.ts already exists on dev (from #5720) and is registered; carry only the PR's added fresh-process case into it. home.ts:4 currently imports from ../config (barrel) — the fix switches to ../config/paths.
+
+## wp1 P (executable)
+- All three squash diffs pass git apply --check -3 on 34fb6d649c (/tmp/l4-5713.diff, /tmp/l4-5703.diff, /tmp/l4-5548.diff limited to 3 files).
+- Commit order: #5713, #5703, #5548 slice; each commit carries Co-authored-by for the PR author.
+- #5713 docs: en/ko remote-hub.md updated by the PR; DeepSeek writer adds the same paragraph to fr, ja, ru, tr, zh-cn, zh-tw remote-hub.md next to the service-api-token paragraph.
+- Focused tests: tests/service/service-secrets.test.ts tests/clients/client-connect.test.ts tests/codex-integration/codex-native-residue.test.ts tests/codex-integration/codex-home-wsl.test.ts tests/test-layout.test.ts; plus the file-size ratchet test.
diff --git a/devlog/_plan/260924_l4_codex_cli_service/020_subagent_identity_5221.md b/devlog/_plan/260924_l4_codex_cli_service/020_subagent_identity_5221.md
new file mode 100644
index 00000000000..feed2618b98
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/020_subagent_identity_5221.md
@@ -0,0 +1,14 @@
+# 020 — rebuild #5221 (fixes #5217) — sbc1-code <207095575+sbc1-code@users.noreply.github.com>
+
+Change: src/adapters/identity.ts gains ROUTED_IDENTITY_RE, NEUTRAL_IDENTITY_RE, hasRoutedIdentity, repairRoutedIdentity, repairIdentityInResponsesBody, stripRoutedIdentity; identifyRoutedModel also rewrites neutral + routed lines. Catalog (src/codex/catalog/derive-entry.ts, metadata.ts) writes neutralizeIdentity instead of identifyRoutedModel. src/responses/parser.ts repairs developer items to data.model. src/adapters/openai-responses/passthrough.ts repairs raw body (routed rewrite, forward strip).
+Rebuild on current dev (221 commits drift): re-read current versions of those files; keep dev behaviour elsewhere.
+Tests: new tests/adapters/identity-subagent.test.ts (from PR). Catalog expectation edits: codex-catalog.test.ts is at cap, so changed expectations must not grow it; new catalog cases go to a sibling file (e.g. tests/codex-integration/codex-catalog-identity-neutral.test.ts) registered in both manifests.
+Check files at cap: parser.ts, passthrough.ts, identity.ts in file-size-baseline.
+Audit fold: neutralizeIdentity and NEUTRAL_IDENTITY_LINE already exist in identity.ts; the six routed-identity helpers do not. parser/passthrough/identity are uncapped (<2000 lines). codex-catalog.test.ts cap 7985 vs 7974 actual: expectation edits may not add net lines beyond headroom; new cases still go to a sibling file.
+
+## wp2 P (executable)
+- /tmp/l4-5221.diff (src, 5 files) passes git apply --check -3 on current HEAD. Current request-time callers of identifyRoutedModel: anthropic.ts:772, google.ts:300, kiro/payload.ts:145, command-code.ts:607, openai-chat/messages.ts:144 — all receive the extended rewrite (GPT line, neutral line, routed line), so a neutral catalog still names the wire model.
+- Writer applies the src diff, adds tests/adapters/identity-subagent.test.ts from carry-5221, and rewrites the catalog expectations the PR changed (codex-catalog.test.ts, codex-catalog-sync-hardening.test.ts) so codex-catalog.test.ts grows by 0 net lines; any added catalog assertion goes to new tests/codex-integration/codex-catalog-identity-neutral.test.ts registered in scripts/test-layout/layout.json explicit and tests/fixtures/test-layout-expected.json.
+- Writer also checks every other test that asserted a baked model id in base_instructions (rg 'powered by the' tests) and updates it.
+- structure: add a line to the structure doc owning src/adapters/identity.ts (find via structure/manifest.json) describing request-time identity repair.
+- Focused: bun test tests/adapters/identity-subagent.test.ts tests/adapters/identity-neutralize.test.ts tests/codex-integration/codex-catalog.test.ts tests/codex-integration/codex-catalog-sync-hardening.test.ts plus new sibling, tests/test-layout.test.ts, tests/ci-workflows/file-size-ratchet.test.ts.
diff --git a/devlog/_plan/260924_l4_codex_cli_service/030_agent_message_recovery_5009.md b/devlog/_plan/260924_l4_codex_cli_service/030_agent_message_recovery_5009.md
new file mode 100644
index 00000000000..62632fcbb5b
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/030_agent_message_recovery_5009.md
@@ -0,0 +1,10 @@
+# 030 — carry #5009 — Zhaofeng Li
+
+Files: src/server/responses/agent-task-recovery.ts (FOLLOWUP_TASK, FINAL_ANSWER with optional Task name; author===sender check kept; recipient cross-check when task name present; JSON tuple cache key including recipient; foreign-family echo rejected), src/server/responses/encrypted-payload.ts (guard regex covers four types), structure/subagents.md, docs-site subagent-v1-default.md, configuration/agents.md, providers.md (check locales), tests/server/agent-task-recovery.test.ts, server-agent-task-recovery-replay.test.ts, v2-agent-message-failfast.test.ts, tests/helpers/agent-task-recovery.ts.
+Method: squash diff from merge-base e9643875f0 applied with -3; check caps on test files (agent-task-recovery.test.ts +161).
+Keep: recoveryAdmission before cache; agentTaskRecovery.enabled default-off.
+
+## wp3 P (executable)
+- /tmp/l4-5009.diff (squash from merge-base e9643875f0, 10 files) passes git apply --check -3 on HEAD af0a3713ea. Test files are below the 2000-line ratchet threshold (1128/438/907 before +163/+33/+48).
+- DeepSeek writer updates item 4 of guides/subagent-v1-default.md in fr, ja, ko, ru, tr, zh-cn, zh-tw: they still say recovery loses message-type follow-ups, which contradicts the carried English text.
+- Focused: bun test tests/server/agent-task-recovery.test.ts tests/server/server-agent-task-recovery-replay.test.ts tests/server/v2-agent-message-failfast.test.ts tests/responses/*encrypted* (rg for encrypted-payload tests).
diff --git a/devlog/_plan/260924_l4_codex_cli_service/040_main_hard_lock_default_5694.md b/devlog/_plan/260924_l4_codex_cli_service/040_main_hard_lock_default_5694.md
new file mode 100644
index 00000000000..a35ecb810e2
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/040_main_hard_lock_default_5694.md
@@ -0,0 +1,35 @@
+# 040 — #5694 98% main-account hard lock by default
+
+Existing mechanism: codexMainAccountHardLock (src/types/config.ts, schema .catch(false)), MAIN_ACCOUNT_HARD_LOCK_PERCENT=99 in src/codex/quota-types.ts, getMainAccountHardLockStatus in src/codex/main-account-hard-lock.ts, consumers gate on === true in src/codex/auth-context.ts, src/codex/native-profile-startup.ts, src/server/management/config-routes.ts, gui/src/components/MainAccountHardLockSetting.tsx.
+Change:
+- MAIN_ACCOUNT_HARD_LOCK_PERCENT = 98.
+- New resolver isMainAccountHardLockEnabled(config) = config.codexMainAccountHardLock !== false; replace every === true gate.
+- Schema: invalid value -> undefined (default on), explicit false persists opt-out; management PUT false stores false (not delete), true deletes key or stores true — decide by reading config-routes semantics.
+- GUI: toggle shows on when unset; copy 99% -> 98% in all locales; confirmation dialog still shown when enabling.
+- Docs: providers-accounts.md (en, ko, others), configuration/providers.md, guides/providers.md, ru; structure/providers/openai-tiers.md.
+- Tests: default-on status, explicit false off, 98 threshold (97.9 ready, 98 blocked), config-route round trip.
+Trade-off for PR: default lock can keep main-account Luna Reserve from activating (Reserve needs exhausted normal window); opt-out by setting false.
+
+## Audit folds (wp0 A)
+- src/codex/main-account-hard-lock.ts:26 gates on !== true: switch to resolver.
+- config-schema.ts:152 .catch(false) -> .catch(undefined) so malformed values fall back to the default (on).
+- config-routes.ts:598 deletes the key on PUT false: must store false; PUT true deletes the key (default on). Projections at :351 and :706 become resolver-based, else GUI invariant at MainAccountHardLockSetting.tsx:14 fails.
+- quota.ts:262 and :388 also use MAIN_ACCOUNT_HARD_LOCK_PERCENT (blocking-evidence retention); they follow the constant.
+- auth-context.ts:512 hardcoded "99%" message -> derive from constant.
+
+## wp4 P (executable)
+Semantics: codexMainAccountHardLock absent or true = on; explicit false = off (persisted). Threshold 98 (MAIN_ACCOUNT_HARD_LOCK_PERCENT). Same convention as fastRows in config-routes.ts.
+Writer A (core, write scope: src/**, tests/**, structure/**, scripts/test-layout/layout.json):
+- src/codex/quota-types.ts: MAIN_ACCOUNT_HARD_LOCK_PERCENT = 98 (#5694).
+- src/codex/main-account-hard-lock.ts: export isMainAccountHardLockEnabled(config) = config.codexMainAccountHardLock !== false; getMainAccountHardLockStatus uses it.
+- Replace every === true gate: auth-context.ts 960/973/1017/1545/1623, native-profile-startup.ts 191/228/239/389/708, config-routes.ts projections 351/706.
+- config-routes.ts PUT: true deletes key, false stores false (mirror fastRows); rollback path unchanged.
+- config-schema.ts: .catch(undefined) so malformed values mean default-on.
+- types/config.ts doc comment; auth-context.ts:512 message uses the constant.
+- Tests: update existing hard-lock tests; add tests/codex-integration/main-account-hard-lock-default.test.ts (absent=on, false=off, malformed=on, 97.9 ready, 98 blocked, settings GET/PUT round trip) registered in layout.json explicit + test-layout-expected.json. codex-auth-api.test.ts cap 6549 (6514 now): no net growth beyond cap.
+- structure/providers/openai-tiers.md:291-315 rewrite (on by default, 98%, opt-out persists false, Reserve trade-off).
+Writer B (gui/src/i18n/*.ts only): 99 -> 98 in mainHardLock* strings in all locales; desc adds "On by default."
+Writer C (docs-site/** only): providers-accounts.md en + ko (and other locales mentioning it) -> 98%, on by default, opt-out; check configuration/providers.md:71 and guides/providers.md:377.
+Previous opt-outs deleted the key, so they cannot be distinguished; PR notes it.
+Focused: main-account-hard-lock-*.test.ts, settings-main-account-hard-lock, main-quota-*, reserve-*, reserve-claude-policy, codex-quota-auto-refresh-main-admission, codex-auth-api, codex-account-threshold-api; bun run lint:gui; GUI i18n tests.
+
diff --git a/devlog/_plan/260924_l4_codex_cli_service/050_publish.md b/devlog/_plan/260924_l4_codex_cli_service/050_publish.md
new file mode 100644
index 00000000000..89e1484903c
--- /dev/null
+++ b/devlog/_plan/260924_l4_codex_cli_service/050_publish.md
@@ -0,0 +1,9 @@
+# 050 — publish
+Rebase on origin/dev; bun run typecheck; focused tests for every item; bun run test:changed; bun run privacy:scan; bun run structure:check; bun run lint:gui; push branch; gh pr create --base dev with template + Security review + Carries/Closes; watch automatic checks; fix failures on head.
+
+## wp5 P (executable)
+- origin/dev moved to df61bcecd5 (#5737, #5738). Overlapping files: docs-site reference/configuration/providers.md, scripts/test-layout/layout.json, structure/config.md, structure/subagents.md, tests/fixtures/test-layout-expected.json. Resolve by keeping both sides' entries.
+- Before rebase: git mv devlog/_plan/260924_l4_codex_cli_service -> devlog/_fin/ is deferred until after merge (unit stays open while the PR is open).
+- Validation after rebase: bun run typecheck; focused union of all item tests; bun run test:changed (worktree under /Users/jun/.codex trips the test-home guard for some temp-dir tests — compare any failure with a pristine git archive copy); bun run privacy:scan; bun run structure:check; bun run lint:gui.
+- GUI screenshot: run the dashboard (bun run src/cli/index.ts start on a spare port with a throwaway OPENCODEX_HOME), open Codex settings > Multi-auth > Advanced, capture the 98% card to .tmp/. Hosting: pr-assets push only if the user authorizes; otherwise the coordinator uploads it.
+- PR body: Summary per item with Carries/Closes lines, Security review for #5713, Verification with commands, Checklist, coordinator decisions (Reserve trade-off, previous opt-outs re-enabled, stale connect marker retention, 64 MiB indeterminate).
diff --git a/devlog/_plan/260924_regression_risk_fixes/000_overview.md b/devlog/_plan/260924_regression_risk_fixes/000_overview.md
new file mode 100644
index 00000000000..f5ce3c3fd84
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/000_overview.md
@@ -0,0 +1,14 @@
+# 260924 regression-risk fixes
+
+The 260923 bundle round landed eight lane PRs (#5672-#5685). A post-merge review found four behaviour changes that can silently hurt existing users. The owner asked to fix them directly, merge to dev without waiting for PR CI, and then drive ci.yml lane=all on the dev tip to success.
+
+- 010_wsl_home.md — WSL Codex home switch (#5441 carry).
+- 020_windows_mise_node.md — Windows npm global under mise-managed Node refused (#5316 carry).
+- 030_echo_filter.md — tool-envelope echo filter truncates ordinary answers (#5098 carry).
+- 040_tool_call_hold.md — unbounded hold of an unmatched bare block (#5548 carry).
+- 050_delivery.md — branch, merge and dev CI.
+
+Accepted and out of scope: Claude Code <=2.1.222 picker filter (/^(claude|anthropic)/i) drops ocx-claude-* ids; other residual risks are documented in the round's landing log only.
+
+
+Cycle note: wp1's first close attempt failed on a malformed receipt command and the cycle was re-walked with the same artifacts.
diff --git a/devlog/_plan/260924_regression_risk_fixes/010_wsl_home.md b/devlog/_plan/260924_regression_risk_fixes/010_wsl_home.md
new file mode 100644
index 00000000000..09b49b6f7aa
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/010_wsl_home.md
@@ -0,0 +1,20 @@
+# WSL Codex home
+
+Defect: src/codex/home.ts defaultCodexHome now returns the local ~/.codex whenever it is a directory. Before #5441 a local home without config.toml let WSL discovery pick the Windows Codex home. A WSL user whose ~/.codex exists but holds no Codex state, and who ran against the Windows home, is moved to an empty local home on upgrade: auth and sessions disappear and sync writes a new local config.
+
+#5441's case is a fresh local install that Codex itself is using before config.toml exists. Codex writes auth.json on login and sessions/ plus history.jsonl on first use.
+
+Change (src/codex/home.ts):
+
+- keep localCodexHomeIsDirectory (stat, ENOENT/ENOTDIR = absent, other errors = present).
+- add localCodexHomeInUse(home, deps): true when any of config.toml, auth.json, sessions, history.jsonl is present by the same stat rule (unexpected stat error counts as present, never switch on doubt).
+- defaultCodexHome: not a directory -> discovery ?? local (unchanged); directory and in use -> local; directory with no Codex state -> findWslWindowsCodexHome ?? local (the pre-#5441 behaviour).
+
+Tests (new tests/codex-integration/codex-home-wsl-local-state.test.ts, registered in layout.json and test-layout-expected.json): bare local dir + Windows home -> Windows; local dir with auth.json -> local; local dir with sessions -> local; unexpected stat error on markers -> local; non-WSL unaffected. The existing codex-home-wsl.test.ts fresh-home case keeps passing (its statSync mock reports every path present).
+
+Docs: structure/codex-home.md and the Codex integration guide sentence that says directory presence decides.
+
+
+## Build note
+
+A local ~/.codex that exists but is empty, with a discoverable Windows home, resolves to the Windows home (the pre-#5441 behaviour). That is the accepted direction: moving an existing user off the Windows home loses their auth and sessions, while a fresh user who has not run Codex locally yet loses nothing and CODEX_HOME overrides. The existing fresh-home test now models a fresh install honestly (auth.json present, config.toml absent) instead of a mock that reported every path present.
diff --git a/devlog/_plan/260924_regression_risk_fixes/020_windows_mise_node.md b/devlog/_plan/260924_regression_risk_fixes/020_windows_mise_node.md
new file mode 100644
index 00000000000..2b4ef6e5a0d
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/020_windows_mise_node.md
@@ -0,0 +1,19 @@
+# Windows npm global under mise-managed Node
+
+Defect: src/update/install-detection.mjs detectMiseOwner walks /node_modules/ markers and reads /.mise.backend.toml. On Windows, npm -g under a mise-managed Node installs to /installs/node//node_modules/@bitkyc08/opencodex, so toolRoot is the Node tool root and its metadata (short = "node", full = "core:node") is read as contradictory OpenCodex ownership: ocx update is refused with metadata_inconsistent. POSIX is unaffected (lib/node_modules puts toolRoot one level deeper, where no metadata exists).
+
+Change: after parsing, if the metadata names a Node runtime (short is node or nodejs) and its backend is not an npm: backend, the package sits in that runtime's global node_modules and mise did not install OpenCodex: return { recognized: false }, so ordinary npm detection applies. Every other mismatch, including npm:some-other-package, stays metadata_inconsistent (fail closed).
+
+Tests (new tests/update/update-mise-node-runtime.test.ts): Windows and POSIX-shaped paths under a core:node tool root detect as npm with no mise error; short = "node" with an npm: backend stays inconsistent; the existing contradictory-metadata tests keep passing.
+
+Docs: structure owner of src/update (install detection section).
+
+
+## Audit fold (round 1 FAIL)
+
+The exemption is narrowed: only metadata that is exactly the mise core Node runtime (short = "node", full = "core:node") AND a package path that is that tool's /node_modules/ (the Windows npm global layout, installPath directly under toolRoot) is classified as not mise-owned. Every other backend for short node/nodejs, unreadable metadata and every OpenCodex mismatch stay fail-closed.
+
+
+## Residual
+
+detectMiseOwner treats a backslash UNC path (\\server\share) as Windows but a slash-form //server/share path as POSIX, as before this change; on such a path a case difference in the node tool directory misses the exemption and keeps the old metadata_inconsistent refusal.
diff --git a/devlog/_plan/260924_regression_risk_fixes/030_echo_filter.md b/devlog/_plan/260924_regression_risk_fixes/030_echo_filter.md
new file mode 100644
index 00000000000..d5142c4e031
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/030_echo_filter.md
@@ -0,0 +1,30 @@
+# Tool-envelope echo filter
+
+Defect: src/lib/tool-envelope-echo-filter.ts ToolEnvelopeEchoFilter.feed matches as soon as a line starts with a marker (probe === marker) and drops that line and everything after it. The filter arms on almost every Codex agentic turn (input carrying tool calls/outputs or previous_response_id), so a legitimate line such as "[Tool Result] shows the build passed." silently truncates the answer. The replayed envelope OpenCodex builds is always a marker alone on its line ("[Tool Result]\n", protobuf-request.ts), and the replay-side stripper in cursor/envelope-echo.ts already requires whole-line markers.
+
+Change (tool-envelope-echo-filter.ts only):
+
+- feed: a line that equals a marker is kept pending (candidate) instead of matching immediately; trailing spaces/CR after a marker stay candidates; a "[Tool call:" line stays pending up to a bounded length (MAX_CALL_LINE = 4096) and is released as prose beyond it.
+- completeLine decides: whole-line marker (exact after trimEnd) or a "[Tool call:" line ending with "]" is an echo (outside a fence: match; inside: hold as today). Anything else is prose.
+- finish applies the same whole-line rule to an unterminated last line; a truncated marker prefix ("[Tool Res") or an unterminated "[Tool call:" line at stream end still counts as an echo, as today.
+
+Tests (new tests/lib/tool-envelope-echo-whole-line.test.ts): prose starting with a marker survives whole and char-by-char; marker alone mid-answer still drops the tail; "[Tool call: x (call_id: 1) with args: {}]" line drops; final unterminated "[Tool Result] header text" survives; existing passthrough-grok-upstream-envelope-echo and cursor-envelope-echo-retry tests keep passing.
+
+
+## Audit fold (round 1 FAIL)
+
+Two Cursor paths share the marker vocabulary:
+
+- The replay-side stripper isEchoMarkerLine (src/adapters/cursor/envelope-echo.ts) was whole-line at 685321e297 (exact marker) and #5676 widened it to prefix matching, so assistant history prose such as "[Tool Result] shows ..." is now stripped with its following non-blank lines. Restore whole-line semantics: trimmed line equals a marker (with or without the closing bracket for the truncated forms), or a "[Tool call:" line that ends with "]". Test it.
+- The first-bytes prefix sniffer CursorEnvelopeEchoSniffer is unchanged since before the round (probe.startsWith(marker) at 685321e297) and triggers a remint retry rather than truncation. Not a regression of the round; left as is and recorded.
+
+finish() replaces the startsWith(truncated marker) rule with: exact truncated prefix of a marker, whole-line marker, or an unterminated "[Tool call:" line. Tests cover CRLF, trailing whitespace, fenced markers, streaming char-by-char and the buffered Responses JSON path (stripGrokUpstreamEnvelopeEchoFromResponsesJson).
+
+
+## Audit round 2 rebuttal
+
+The Cursor first-bytes sniffer stays out of scope: it predates the round (685321e297) and its false positive costs a remint retry, not a truncated answer. Narrowing a pre-existing echo guard is a separate decision; recorded as a residual.
+
+## Build note
+
+The "[Tool call:" line keeps its prefix rule instead of the planned completed-line rule. An existing Cursor replay test showed why: a call echo wraps when its arguments do ("[Tool call: Glob" then "args"), so a completed-line rule leaks it. Prose that opens with "[Tool call:" is rare, while "[Tool Result] ..." prose is common, so only the result/error markers move to the whole-line rule. The diff review flagged the prefix rule; this is the recorded reason for keeping it.
diff --git a/devlog/_plan/260924_regression_risk_fixes/040_tool_call_hold.md b/devlog/_plan/260924_regression_risk_fixes/040_tool_call_hold.md
new file mode 100644
index 00000000000..9432cc1da25
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/040_tool_call_hold.md
@@ -0,0 +1,23 @@
+# Bound the serialized tool-call hold
+
+Defect: src/adapters/openai-chat/serialized-tool-call-content.ts SerializedToolCallContentBuffer.ingest appends everything after a bare opening to the held text until the stream ends. An unmatched block followed by a long answer is delivered only at the end of the turn and can approach the translator budget.
+
+Change:
+
+- MAX_HELD_CHARS = 64 KiB: when the held text exceeds it, the buffer releases everything it holds (text and queued events, in order, nothing suppressed) and resumes scanning from the carried context.
+- MAX_TRAILING_CHARS = 4 KiB: once the held text contains a closed .
+
+
+## Audit fold (round 2)
+
+MAX_HELD_BYTES rises to 4 MiB: it is a runaway guard only, well under the translator budget, so a large duplicated write inside the block itself is still reconciled. The latency case is handled by the 8 KiB trailing-prose rule alone. A duplicated block is the tail of the content (#5548's observed shape), so a closed block followed by more than 8 KiB of prose before any structured call is treated as prose; that narrow residual is accepted.
diff --git a/devlog/_plan/260924_regression_risk_fixes/050_delivery.md b/devlog/_plan/260924_regression_risk_fixes/050_delivery.md
new file mode 100644
index 00000000000..d4b1012dee8
--- /dev/null
+++ b/devlog/_plan/260924_regression_risk_fixes/050_delivery.md
@@ -0,0 +1,4 @@
+# Delivery
+
+One branch codex/260924-regression-risk-fixes from origin/dev with one commit per fix plus this plan. Local gate: bun run typecheck, bun run structure:check, focused tests for each touched area, test-layout and file-size-ratchet tests. Open one PR to dev with the repository template and merge it immediately with gh pr merge --admin --squash (owner instruction: no PR CI wait). Then dispatch gh workflow run ci.yml --ref dev -F lane=all on the merged tip and require every job completed success; a multi-file timeout is rerun once, a repeat is a defect fixed by another PR merged the same way, followed by a fresh lane=all on the new tip.
+
diff --git a/devlog/_plan/260924_update_indicator/000_plan.md b/devlog/_plan/260924_update_indicator/000_plan.md
new file mode 100644
index 00000000000..97afd57d386
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/000_plan.md
@@ -0,0 +1,110 @@
+# 260924 update indicator
+
+Service installs of opencodex never learn that a new version exists: the sidebar's blue update orb reads `~/.opencodex/version.json`, and that cache is refreshed only by an interactive `ocx start`. The desktop app has the opposite gap: its Tauri updater knows about updates, but the GUI inside the app asks the compiled sidecar, which classifies itself as a source build and never lights the orb. This unit makes the package cache refresh itself inside the running proxy without blocking requests, lets the desktop app publish its own updater state to the GUI it hosts, and puts a blue dot on the tray icon itself on the macOS menu bar, the Windows and Linux Tauri trays, and the npm Windows PowerShell tray. Users on any install see one consistent signal, and in the desktop app the update button installs the app update instead of the npm package.
+
+Research input: [001_sol_plan_draft.md](001_sol_plan_draft.md) (first planning draft plus coordinator review). External survey of Codex, Claude Code, gemini-cli, Ollama, cloudflared, Tauri apps and UI badges was done with Aside and is summarised in the PR, not copied here.
+
+## Loop spec
+
+- **Loop archetype:** satisfy-spec, multi-cycle HOTL (one work-phase per PABCD cycle).
+- **Trigger:** the owner asked for tray and menu-bar blue update indicators on top of the update-signalling fixes, planned by sol and shipped as one PR ("그 가정으로 cxc-loop 해서 pr 날려놔").
+- **Goal:** the four behaviours in the work-phase map below, landed as ordered commits on `codex/update-indicator` with one PR to `dev`.
+- **Non-goals:** automatic installation policy; npx, Volta, Yarn and Homebrew install detection; a light/dark redesign of the Windows Tauri base tray glyph; merging, releasing or deploying; unrelated refactors.
+- **Verifier:** focused Bun tests named in each decade doc, `bun run typecheck`, `bun run structure:check`, `bun run privacy:scan`, `cd gui && bun run lint && bun run build` for GUI commits, `cargo test --manifest-path desktop/src-tauri/Cargo.toml` for desktop commits, then exact-head hosted CI on the PR. Visual tray rendering is human review (see Stop condition).
+- **Stop condition:** PR open against `dev` with every template section filled and exact-head CI inspected, branch-caused failures fixed. macOS menu-bar rendering is checked locally; Windows and Linux tray rendering cannot be observed on this Mac and is reported as NEEDS_HUMAN, not claimed.
+- **Memory artifact:** this unit directory, the codexclaw goalplan `ship-end-to-end-update-available-signalling-for`, and the PR description.
+- **Expected terminal outcomes:** DONE (PR open, gates green or branch-caused failures fixed); BLOCKED (push or PR creation rejected, CI unavailable after investigation); UNSAFE (a change would weaken management auth or updater signature verification); NEEDS_HUMAN (cross-platform visual QA).
+- **Escalation condition:** any change to management authentication semantics, updater signature checks, or the Lab boundary files stops for the owner. A worker that fails the same packet twice is reclaimed by main after its work is stopped (DISPATCH-RETIRE-01); moving a slice to a worker mid-B needs a P amendment.
+- **Resource bounds:** tools are the local shell, git, gh (push and PR creation authorised, merge not), Bun and Cargo; write scope is this worktree; gpt-6-sol subagents are authorised without a count limit; no token or wall-clock budget was set by the owner.
+
+## Work-phase map
+
+Dependency order follows the build order: the package cache is the foundation the badge and the npm tray read; the desktop snapshot and icons need the badge route shape from commit 1; the desktop update page consumes the desktop state from commit 2; the npm Windows tray only needs commit 1 and is last because it is independent.
+
+| Work-phase | Commit | Decade doc |
+| --- | --- | --- |
+| wp0 | none (this roadmap) | 000_plan.md |
+| wp1 | 1. package cache freshness and async checks | [010_phase1_package_cache.md](010_phase1_package_cache.md) |
+| wp2 | 2. desktop update snapshot and tray blue dot | [020_phase2_desktop_state_icons.md](020_phase2_desktop_state_icons.md) |
+| wp3 | 3. desktop GUI update page | [030_phase3_desktop_update_page.md](030_phase3_desktop_update_page.md) |
+| wp4 | 4. npm Windows tray indicator | [040_phase4_windows_npm_tray.md](040_phase4_windows_npm_tray.md) |
+| wp5 | none (verification, push, PR, CI) | recorded in 050_delivery.md at wp5 |
+
+## Decisions
+
+Architect proposal from McClintock (gpt-6-sol, read-only, agent 01a0d34a-4b14-7aa1-aca3-b42310f6b3d3), decisions D1-D7. Main dispositions:
+
+| ID | Proposal | Disposition |
+| --- | --- | --- |
+| D1 macOS | Keep the template glyph; draw the dot in a transparent NSView on the NSStatusBarButton via the Swift bridge (app/Sources/NativeTray), positioned against the image, removed when cleared. tray-icon 0.24.2 `set_icon` does not remove subviews. | **Accepted.** Keeps system tinting and highlight correct without guessing the menu-bar appearance. |
+| D2 Windows/Linux | Swap PNG variants with a haloed blue dot; also add light/dark Windows base glyphs. | **Amended.** Dotted variants accepted. The light/dark base glyph is out of scope (owner-fixed non-goal); recorded as a follow-up. |
+| D3 snapshot | `POST /api/update/desktop-snapshot`, admin-token principal only, bounded scalar payload keyed by a random desktop session id, in-memory with bounded entries, 60 s heartbeat, ~3 min expiry; `GET /api/update/badge?surface=desktop&session=` returns `installer: "desktop"` or `unknown: true`. Session id travels in the embedded dashboard URL. | **Accepted.** No installation authority, no persistence, no logging of the session id. |
+| D4 page | Bundled `desktop/ui/update.html` on the app origin with narrow Tauri commands; tray and page share one install function with a compare-and-swap claim. | **Accepted.** No updater IPC for the loopback dashboard. |
+| D5 refresh | Scheduler worker in `src/update/`, tiny start/stop hook in `src/server/index.ts`; async `child_process.spawn` through `registrySpawnTarget`, 12 s kill, bounded output; write-through; coalesce per channel; backoff; 40 h max cache age reports unknown; skipped for source and mise installs; `/api/update/run` awaits the async check and passes the result into `startUpdateJob`. | **Accepted.** Keeps the Lab boundary and the synchronous `startServer` window intact. |
+| D6 npm tray | Hidden read-only CLI command printing `readUpdateBadge()` JSON, probed every 60 s, bounded and non-overlapping; six icons (online, warning, offline × normal, dotted); update menu item opens the dashboard. | **Accepted.** Probe cost on Windows is measured in CI only; cadence stays 60 s with a timeout. |
+| D7 commits | Four ordered commits with the file scopes and docs owners listed. | **Accepted.** |
+
+Reflection by the same architect: recorded below after the decade docs are written.
+
+## Source-of-truth sync
+
+- `structure/runtime.md` and `structure/ops/service-and-sidecars.md` own `src/update/` and `src/tray/` (commits 1 and 4).
+- `structure/gui-and-management-api.md` owns the management routes (commits 1-3).
+- `structure/desktop-shell.md` and `structure/companion.md` own `desktop/` (commits 2-3).
+- docs-site: `reference/management-api.md`, `guides/desktop-app.md`, `guides/macos-menu-bar.md`, `guides/web-dashboard.md`, `reference/cli/lifecycle.md`, each with its existing locale siblings.
+
+### Main decisions raised by decade writers
+
+- 010: no update-check opt-out exists today. **Accepted** `OCX_DISABLE_UPDATE_CHECK=1` as a documented opt-out for automatic checks (the scheduler); explicit `/api/update/check` still runs. The Bun test preload must set it so test-started servers never spawn a registry lookup.
+- 040: the PowerShell source assertion stays in `tests/windows/tray-proxy.test.ts` next to the existing probe assertions.
+- 020: `structure/runtime.md` is at its 600-line budget. **Amendment for 010 and 040:** runtime.md edits must be net-zero (replace sentences, do not add); the new scheduler/probe prose goes to `structure/ops/service-and-sidecars.md`. Each B re-checks the structure line budgets with `bun run structure:check` before committing.
+- 020: `cargo test` needs the sidecar placeholder `desktop/src-tauri/binaries/ocx-`. wp2 B reuses whatever CI uses to satisfy `externalBin` for Rust tests (checked at wp2 P), and never commits a built binary.
+- 030 cites 020 line numbers that moved while 020 was written; symbol names are authoritative, line numbers are refreshed at each cycle's P.
+
+## Architect reflection
+
+McClintock (same agent) returned **MISALIGNED** with eight material and three minor gaps against revision 1 of the decade docs. Main accepted all eleven and assigned the fixes: 010 gets net-zero runtime.md edits, explicit-check write-through independent of a joined automatic flight (join-then-stop regression), a non-source injected route regression proving the event loop stays responsive, and an explicit one-server-per-process scheduler invariant; 020 separates heartbeat receipt age from `checkedAtMs`, adds a native check generation so only the latest completed check applies, and limits the post-title redraw to macOS; 030 refreshes phase-2 anchors by heading and consumes the phase-2 check generation; 040 makes the general-suite icon test renderer-independent (structural checks; byte-exact generator `--check` stays a local/desktop tool), caps probe output bytes, replaces the synchronous `WaitForExit` on the UI tick with a request-and-reap across ticks, and makes runtime.md edits net-zero. Revision 2 is sent back to the same architect before audit.
+
+Re-reflection on revision 2: all eleven gaps CLOSED; two new material gaps in the desktop check/install flow (install claim outside the check-application critical section; a superseded page check reporting "up to date"). Main accepted both; one writer revises 020 and 030 together into revision 3.
+
+Re-reflection on revision 3: both gaps CLOSED; one new material deadlock risk (tray setters that wait on the AppKit thread were called while the gate mutex was held, and a synchronous status command could wait on that mutex from the main thread). Main accepted it; revision 4 moves UI projection outside the gate with a generation re-check and makes gate-reading commands async.
+
+Re-reflection on revision 4: deadlock gap and both rev-3 gaps CLOSED; one new material gap (a no-pending install click committed the install flag and epoch before discovering there was nothing to install, orphaning an in-flight check). Main fixed it directly in 030 (revision 5): `claim_install` returns `InstallClaim::{Claimed,Busy,NoPending}`, reads the pending version under the gate before committing anything, and a new regression `install_click_without_pending_leaves_in_flight_check_valid` covers it; the tray install arm uses the same call.
+
+Re-reflection on revision 5: **ALIGNED** (McClintock). No material gap remains; all reported gaps are closed with regressions named in the decade docs. This completes architect consultation for wp0; the independent A audit follows.
+
+## Audit
+
+Independent reviewer Bohr (gpt-6-sol, agent 01a0d39a-32c8-7553-8d80-9b2fff2ef419). Round 1: FAIL with three High test-specification blockers (inherited commit-2 claim_install test breaks in commit 3; registry child failure paths untested; Windows stale-dot expiry untested) and two non-blocking notes; all accepted and folded (030 by main, 010 and 040 by fixers, 020 note by main). Round 2: FAIL with one High blocker (the new failure tests expected the retry timer after eight microtask turns; Bohr measured sixteen); main added a bounded `settle()` fixture wait in 010.
+Round 3: **PASS** — the reviewer re-executed the planned scheduler and lookup in memory with the settle helper; all five failure scenarios reach the retry timer and recover. No High or Critical blocker remains.
+
+## wp1 Check review
+
+Implementation reviewer Noether (gpt-6-sol, agent 01a0d3be-6826-71c1-9ceb-331b2db6b176) on commit 1:
+- **Medium, accepted and fixed:** an automatic tick after stop/start joined the stopped listener's pending flight, whose write the old generation suppressed, pushing the next check an hour out. Flights now carry their epoch and automatic ticks only join a same-generation flight; regression `restart does not join the stopped listener's pending lookup` fails on the pre-fix scheduler and passes after (red-green verified). Folded into commit 1.
+- **High, rebutted for this unit:** on Windows, `POST /api/update/run` still reaches `spawnGuiUpdateWorker`'s 15-second-bounded `spawnSync` of PowerShell `Start-Process` (src/update/job.ts). It predates this unit, runs once per user-initiated install immediately before the proxy restarts, and 010 scoped the detached installer worker OUT. Making it asynchronous changes `startUpdateJob`'s lock-then-launch contract in a file with seven lines of headroom. Recorded as a follow-up in the PR; this unit's claim is limited to the registry check path.
+- Round 2 (Noether): rebuttal accepted; GO-WITH-FIXES with 0 blockers. Medium (an older explicit flight could overwrite a newer generation's write after stop/start) fixed with per-channel flight sequencing and a red-green regression; Low (010's scheduler block no longer matched) fixed with an authoritative amendment note above that block.
+
+## wp1 Done
+
+Commit 1 (`feat(update): refresh the package update cache inside the running proxy`) shipped the scheduler, async registry lookup, write-through and 40 h unknown badge. Evidence: receipt 425 pass / 0 fail with typecheck, structure and privacy; reviewer PASS after two scheduler fixes (stop/start flight join, flight ordering) found in Check. What did not improve: Windows `/api/update/run` still launches the installer through a bounded synchronous PowerShell call (follow-up). What would show this direction wrong: a service install whose badge stays unknown for more than a day with network access. Next: wp2 per 020.
+
+## wp2 Check review
+
+Implementation reviewer Ohm (gpt-6-sol, agent 01a0d3d7-409a-7892-ad81-d0bdedc0fa41) round 1 on commit 2: FAIL. Accepted and being fixed in commit 2: (1) High, the snapshot POST accepted browser-origin requests — reject any `Origin`; (2) High, startup `wake()` could republish a stale snapshot — make notify atomic with publish; (4) Medium, the companion link lost `#/usage/companion` — preserve the validated fragment. (3) High, the tray install arm takes `PendingUpdate` outside `CheckGeneration::claim_install`: deferred to commit 3, whose plan (030) converts the tray arm to the gated three-way claim; wp3 Check must verify it is closed on the combined branch.
+
+macOS visual QA (commit 2): the real `UpdateDotView`/`UpdateDot` code from `app/Sources/NativeTray/Popover.swift` was compiled into a local harness, attached to real `NSStatusItem`s using `desktop/src-tauri/icons/tray/icon.png` as a template image, and rendered with `cacheDisplay` under aqua and darkAqua, with and without a title. The template glyph keeps its system tint in both appearances, the 7 pt blue dot sits at the glyph's lower right with a background-coloured halo, and a title does not overlap it. Limits: cached rendering does not reproduce the live menu-bar selection tint, and the live menu bar on this machine hid the harness items (crowded bar), so on-bar placement across displays remains human QA.
+Round 1 fixes folded into commit 2: the snapshot POST now refuses any `Origin` (403, fixed body, no store write; red-green verified); `wake()` notifies without replacing the current snapshot and the companion link keeps its validated fragment (both red-green verified; cargo 139 pass, clippy and fmt clean). A test demanding that the outer management CORS wrapper omit `Access-Control-Allow-Origin` on this 403 was dropped: the wrapper is shared by every management route, the refusal body is a fixed string, and the boundary (refusal plus no write) holds without changing that shared layer.
+
+## wp2 Done
+
+Commit 2 (`feat(desktop): publish updater state to the GUI and dot the tray icon`) shipped the desktop snapshot route, per-session desktop badge, native check generation and UI projection worker, the macOS NSView dot and the dotted Windows/Linux PNG. Evidence: receipt 478 Bun + 4 GUI + 139 cargo pass with clippy, icons, typecheck, structure and privacy; reviewer GO-WITH-FIXES with zero blockers. Carried into wp3: the tray install arm must move onto the gated `claim_install` (reviewer High, deferred by plan). What would show this direction wrong: a dotted tray icon that stays after the update installs, or a GUI orb that disagrees with the tray.
+
+## wp3 Done
+
+Commit 3 (`feat(desktop): route the desktop update button to a bundled update page`) shipped `desktop/ui/update.html` with four app-origin Tauri commands, the shared `InstallClaim` gate for tray and page (closing the wp2 High), the page checking state, and desktop-only GUI routing with ten catalogs. Evidence: receipt 485 Bun + 5 GUI + 147 cargo pass with lint, i18n lint, clippy, typecheck, structure and privacy; reviewer Mill PASS with no findings. A pending-state screenshot of the page (headless Chrome with a stubbed invoke) is kept outside the repository for the PR. Packaged cross-origin navigation on Windows and Linux remains human QA. Next: wp4 per 040.
+
+## wp4 Check notes
+
+Commit 4 builds the dotted Windows icons from the shipped base frames; a local contact sheet at 16 and 32 px on light and dark backgrounds shows the status colours unchanged (online cyan, warning yellow, offline grey) with a white-haloed blue dot at the lower right, and all nine frame sizes present. PowerShell child-process scenarios cannot run on this Mac (no pwsh) and are left to the Windows CI legs.
+Implementation reviewer Kierkegaard (gpt-6-sol, agent 01a0d417-79b9-7980-b94c-4d256aa5b24c) round 1: FAIL, one High — an install made before the dotted icons existed had only the three base icons, the ownership check required all six, so the tray was classified stale and the updater stopped it without reinstalling. Fixed in commit 4: `windowsTrayRequiredFilesPresent` requires only the base icons (the dotted ones stay in install/rollback/uninstall lists and the script falls back to the base icon); regression `an install from before the dotted icons still owns its registration` fails when all six are required and passes after.
diff --git a/devlog/_plan/260924_update_indicator/001_sol_plan_draft.md b/devlog/_plan/260924_update_indicator/001_sol_plan_draft.md
new file mode 100644
index 00000000000..a4e543665f3
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/001_sol_plan_draft.md
@@ -0,0 +1,64 @@
+# Update signalling plan
+
+This is a read-only plan. The current failure is a missing state producer: the sidebar reads `version.json`, but the refresh runs only after an interactive startup passes the TTY gate. A service startup skips it, so the badge can remain unknown indefinitely. The explicit check also runs a synchronous registry command in the request handler. [Badge reader](src/update/badge.ts:48), [refresh gate](src/update/notify.ts:238), [blocking lookup](src/update/index.ts:273), [check route](src/server/management/config-routes.ts:745).
+
+## Target behaviour
+
+| Installation | Update source and timing | Visible signal | Click path |
+| --- | --- | --- | --- |
+| npm, pnpm, Bun service on macOS/Linux | Registry result cached at startup and refreshed while the service runs; explicit check refreshes immediately | Existing blue sidebar orb and dot when newer | Sidebar opens the package update dialog; install uses the existing update job |
+| npm, pnpm, Bun with Windows PowerShell tray | Same package cache; tray reads the same badge calculation every minute | Blue dot on the existing online, warning, or offline icon; safety colour remains visible | Tray double-click still opens the dashboard; a labelled menu item opens it for updating, then the sidebar opens the update dialog |
+| Tauri desktop on macOS | Tauri updater check after 30 seconds, then every six hours; explicit check on demand | Blue dot on a colour-preserving menu bar icon, matching the sidebar’s blue signal | Icon retains the native usage popup; tray menu and the desktop update page offer **Install update** |
+| Tauri desktop on Windows | Same Tauri state | Blue dot on the Tauri tray icon | Existing icon behaviour; tray menu or desktop update page installs |
+| Tauri desktop on Linux with an AppIndicator host | Same Tauri state | Blue dot where the host renders the icon | Tray menu installs; the desktop update page also works |
+| Tauri desktop on Linux without a tray host | Same Tauri state | Desktop dashboard orb; no claimed tray icon | Desktop update page installs |
+| Source, mise, or unverified package ownership | No automatic package installation | No misleading “installable” signal; show manual guidance where available | No automatic install |
+
+The current sidebar polls `/api/update/badge` every ten minutes and paints the blue orb and 7 px dot. The desktop updater already owns `PendingUpdate`, the six-hour check, and the drain-before-install sequence. Linux can have no usable tray host. [Sidebar](gui/src/components/sidebar-github-row.tsx:70), [orb styling](gui/src/styles.css:370), [updater](desktop/src-tauri/src/updater.rs:81), [Linux tray contract](structure/desktop-shell.md:168).
+
+## Design decisions
+
+**A — macOS icon.** Keep the existing 44×44 template PNG for the normal state. A template image is recoloured by macOS, so a blue pixel cannot survive in it. Pre-render two 44×44 RGBA update variants from the existing tray SVG: a dark glyph for a light menu bar and a light glyph for a dark menu bar, each with a blue dot and a contrasting halo. Select by window theme and update on `ThemeChanged`; restore the template image when the update clears. Use `set_icon_with_as_template(image, false/true)` from the updater task, after releasing state locks. The pinned Tauri API performs this switch atomically; Linux/Windows use its ordinary icon setter. This avoids a new runtime image dependency and avoids the flicker from separate icon/template calls. A blue ring is an alternative, but it consumes more of the 22 pt mark; title-only or menu-only signalling misses the requested icon signal. The native macOS popup borrows the existing status item, so switching that item’s image does not change popup ownership. [Current icon](desktop/src-tauri/src/tray.rs:104), [popup status item](desktop/src-tauri/src/native_tray.rs:63), [Tauri API](https://docs.rs/tauri/latest/tauri/tray/struct.TrayIcon.html). Test normal and highlighted menu bars at 1× and Retina 2×.
+
+**B — Windows and Linux icons.** Tauri uses its `PendingUpdate` state to switch a pre-rendered PNG: 32 px for Windows taskbar scaling and 44 px for Linux AppIndicator scaling, with the same blue dot. Check Windows light/dark taskbars and Linux hosts for resampling or icon caching. The separate npm PowerShell tray uses `online-update.ico`, `warning-update.ico`, and `offline-update.ico`, each containing the existing nine sizes (16 through 256 px). It polls a bounded, read-only internal CLI badge command every 60 seconds, never on its three-second health tick; this calls the same `readUpdateBadge` logic as HTTP without copying semver rules into PowerShell or reading the admin token. Keep the existing health/safety icon as the base. Test that this hidden command performs no startup repair or cache refresh. The current PowerShell icon selection and owned asset list are at [windows-tray.ps1](src/tray/windows-tray.ps1:367) and [windows.ts](src/tray/windows.ts:18).
+
+**C — one authority per installation.** Package installs use `version.json`; desktop installs use Tauri’s signed updater result, never the compiled sidecar’s path-based `"source"` verdict. Tauri posts a scalar desktop snapshot—app version, latest version, availability, check time, and session ID—through its identity-bound `ProxyClient` to a management route. The proxy keeps it **in memory** with a short host heartbeat expiry. `/api/update/badge?surface=desktop` returns that snapshot; the default endpoint continues to represent the package installation. This works even when the app is a guest attached to an npm service: the embedded desktop dashboard asks for the desktop surface, while an ordinary browser sees the service’s package state. No desktop snapshot grants installation authority. The existing proxy client verifies PID, port, and binding generation before sending its management token. [Install detection](src/update/install-detection.mjs:248), [proxy binding](desktop/src-tauri/src/proxy.rs:191).
+
+In desktop mode, either GUI update button navigates the **main WebView** to a bundled `desktop/ui/update.html`. That app-origin page reads the native updater snapshot, checks again on request, and calls one shared native install function also used by the tray menu. It offers a return-to-dashboard action. The proxy-served dashboard receives no updater IPC permission; its current remote capability grants only zoom. On Linux without a tray host, this page supplies the missing install path. The GUI’s present update dialog calls the package `/api/update/check` and `/api/update/run`, so both sidebar and dashboard update entry points must make this desktop-specific navigation before entering that flow. [Current dashboard flow](gui/src/pages/use-dashboard-data.ts:812), [capability](desktop/src-tauri/capabilities/dashboard-zoom.json:1), [allowed app origin](desktop/src-tauri/src/window.rs:31).
+
+**D — cache freshness and event-loop safety.** Start one cancellable refresh scheduler after the proxy binds; stop it with the server. It attempts an immediate refresh if the package cache is missing/stale, then checks staleness hourly against the existing 20-hour interval. Coalesce concurrent background and explicit checks, bound the registry process and output, and back off after failures. Keep badge GET strictly read-only. Make `/api/update/check` await an asynchronous registry lookup and write a successful answer through to `version.json`; make `/api/update/run` await a fresh lookup before handing that checked result to the existing job starter. Keep synchronous installer work in the detached worker, outside the server event loop. An old cache beyond a defined expiry reports `unknown`, rather than silently asserting “current.” Preserve dismissal only for the exact dismissed version. The current job starter already accepts an injected check function, allowing the request path to change without growing its nearly 2,000-line file. [Job seam](src/update/job.ts:619), [cache writer](src/update/notify.ts:57).
+
+**E — automatic installation.** Defer `off/notify/download/auto` policy. This unit adds reliable notification and an explicit install path. Automatic installation would require a separate idle definition, in-flight request drain budget, service ownership checks, and recovery policy across npm and desktop. Existing desktop install already coordinates a drain after a user action. [Desktop install ordering](desktop/src-tauri/src/updater.rs:50).
+
+## Ordered commits in one branch and one PR to `dev`
+
+1. **Package cache and asynchronous checks.** Change `src/update/index.ts`, `notify.ts`, `badge.ts`, `src/server/management/config-routes.ts`, and `src/server/index.ts`; add `src/update/refresh-scheduler.ts` and `tests/update/update-refresh.test.ts`. Extend `tests/update/update-notify.test.ts`, `update-badge.test.ts`, and `update-job.test.ts`; register the new test in `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`. Update `structure/runtime.md`, `structure/ops/service-and-sidecars.md`, `structure/gui-and-management-api.md`, and the English plus existing translated `reference/management-api.md` pages. Verify `bun test` on these focused files, `bun run typecheck`, `bun run structure:check`, and `bun run privacy:scan`.
+
+2. **Desktop update state and icon.** Add `src/update/desktop-badge.ts`, `tests/update/update-desktop-badge.test.ts`, `desktop/src-tauri/src/update_status.rs`, `desktop/src-tauri/src/tray_icons.rs`, and generated update PNGs/SVG sources under `desktop/src-tauri/icons/tray/`. Change `src/server/management/sidebar-routes.ts`, `route-registry.ts`, `desktop/src-tauri/src/proxy.rs`, `updater.rs`, `tray.rs`, `lib.rs`, and `desktop/scripts/generate-icons.ts`. The new POST route accepts only bounded scalar state under normal management authentication; the registry declares it. Register the new test in both layout files. Update `structure/desktop-shell.md`, `companion.md`, `gui-and-management-api.md`, and the desktop guide and management API pages in English and their existing locale siblings. Test `tests/update/update-desktop-badge.test.ts`, `tests/server/sidebar-routes.test.ts`, `tests/server/management-route-registry.test.ts`, `tests/ci-workflows/build-desktop-icon-set.test.ts`, `bun --cwd desktop run icons:check`, and `cargo test --manifest-path desktop/src-tauri/Cargo.toml`.
+
+3. **Desktop GUI install route.** Add `desktop/ui/update.html` and `gui/src/lib/desktop-update.ts`; change `desktop/src-tauri/src/lib.rs`, `updater.rs`, `tray.rs`, `gui/src/App.tsx`, `gui/src/components/sidebar-github-row.tsx`, and `gui/src/pages/use-dashboard-data.ts`. Reuse the native updater’s pending/install lock and retry behaviour for tray and page actions. Add focused desktop-page and GUI tests under `tests/clients/` and `gui/tests/`, registering any new Bun test in both layout files. Add visible copy to all ten `gui/src/i18n/{en,de,fr,ja,ko,ru,tr,vi,zh,zh-TW}.ts` catalogs. Update `structure/desktop-shell.md`, `gui-and-management-api.md`, and the desktop guides in English and their existing locale siblings. Run focused tests, `bun run typecheck`, `cd gui && bun run lint:i18n && bun run build`, and desktop `cargo test`. Attach a desktop GUI screenshot to the PR description.
+
+4. **Windows npm tray indicator.** Add three update `.ico` files under `src/tray/assets/` and a deterministic generator/check script under `scripts/` for their nine-size contents. Change `src/tray/windows.ts`, `windows-tray.ps1`, `src/lib/config-ownership.ts`, `src/cli/registry.ts`, and `src/cli/dispatch.ts`; extend `tests/windows/windows-tray.test.ts`, `tests/windows/tray-proxy.test.ts`, and `tests/update/update-badge.test.ts`. Update `structure/runtime.md`, `structure/ops/service-and-sidecars.md`, and the English plus translated CLI lifecycle pages. Test the hidden command’s zero-side-effect path, icon asset install/rollback ownership, probe timeout and no-overlap behaviour, and online/warning/offline icon precedence. Run focused Bun tests, `bun run typecheck`, `bun run skill:surface:check`, `bun run structure:check`, and `bun run privacy:scan`.
+
+The current ratchet permits no growth in `gui/src/styles.css` (2,958/2,958); reuse its existing orb CSS. `src/server/index.ts` has **10 lines** of headroom (883/893), so only a small scheduler start/stop hook belongs there. `src/update/job.ts` has **6 lines** before the new-file 2,000-line threshold (1,993 lines), and `src/cli/index.ts` has **5** (1,994); the plan avoids growing either. Other planned TypeScript headroom at this HEAD: `notify.ts` +1,729, `badge.ts` +1,924, `index.ts` +1,116, `config-routes.ts` +892, `sidebar-routes.ts` +1,893, `route-registry.ts` +1,604, `windows.ts` +1,214, `config-ownership.ts` +1,615, CLI `registry.ts` +1,362 and `dispatch.ts` +890, GUI `App.tsx` +1,472, `sidebar-github-row.tsx` +1,838, and `use-dashboard-data.ts` +1,048. New TypeScript files must remain below 2,000 lines. Rust and `.ps1` files are outside this ratchet; current `tray.rs` is 620 lines, `updater.rs` 144, and `windows-tray.ps1` 522. Recalculate against the shared tree immediately before each commit. [Ratchet rule](scripts/file-size-ratchet.ts:114).
+
+Before review readiness, run the repository’s required broad gates or document the permitted focused-test exception in the PR template. Run `bun run structure:check`, `bun run privacy:scan`, `bun run typecheck`, GUI lint/build, desktop Cargo tests, and the relevant macOS and Windows CI legs at the **PR’s exact head**. The PR targets `dev`; the host retains merge authority.
+
+## Visual QA and failure cases
+
+Manually compare no-update, pending, check-failed, installing, install-failed, and post-restart states. On macOS check light/dark and highlighted menu bars at 1×/2×, icon switching without flicker, and the native popup/menu. On Windows check light/dark taskbars and 100%/200% scaling for both Tauri and npm trays, including safety-warning precedence. On Linux check at least one GNOME AppIndicator host, one KDE host, and a session without a host; verify the desktop update page remains reachable in the last case. Confirm a guest desktop app shows the **desktop** update in its embedded GUI while a normal browser attached to the same service shows the **package** update.
+
+The main risks are stale host state, process overlap during refresh, a tiny dot disappearing under tray scaling, and a check/install race. Expire the in-memory desktop heartbeat, coalesce registry work, verify the smallest icon sizes visually, and recheck availability in the shared native install action. A failed desktop download or drain keeps `PendingUpdate` and restores the indicator. Rollback is the single PR’s ordered commits; no persisted desktop update schema or automatic-install setting is introduced.
+
+**Open questions:** None blocks this design. Broader notify-only support for npx/bunx/Volta/Yarn/Homebrew and automatic installation are separate product decisions.
+
+---
+
+## Coordinator review (2026-09-24)
+
+Verified at dd7cb695a9: tauri 2.11.6 has `TrayIcon::set_icon_with_as_template` (tray/mod.rs:577); `gui/src/styles.css` 2958/2958 and `src/server/index.ts` 883/893 match the ratchet baseline.
+
+1. **macOS theme source.** The menu bar appearance is not the app window theme: the bar can be dark while the app is light (wallpaper tint, "Reduce transparency", a second display). Picking the light/dark variant from `ThemeChanged` can paint a dark glyph on a dark bar. Before committing to pre-rendered variants, evaluate a native overlay: keep the template image and add a small blue sublayer to the `NSStatusBarButton` through the existing ObjC bridge in `native_tray.rs`. That keeps automatic tinting and the highlighted state. If variants are kept, read `statusItem.button.effectiveAppearance` natively instead of the window theme.
+2. **Windows Tauri tray contrast.** `tray.rs` ships the same black template PNG on Windows, where `icon_as_template` is ignored. On a dark taskbar the base icon is already low contrast. Commit 2 should add light/dark base variants for Windows, not only the update variant.
+3. **Indicator shape** (dot vs ring) is pending the maintainer's answer; the plan assumes a dot.
+4. **Scope.** Four commits touch Rust, TS, PowerShell, ten locales, structure docs and docs-site. Commit 4 (npm Windows tray) is independent and can split out if review load is high.
diff --git a/devlog/_plan/260924_update_indicator/002_architect_proposal.md b/devlog/_plan/260924_update_indicator/002_architect_proposal.md
new file mode 100644
index 00000000000..544b1c698df
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/002_architect_proposal.md
@@ -0,0 +1,86 @@
+# Architect proposal (McClintock, gpt-6-sol)
+
+Read-only design proposal for this unit. Dispositions live in 000_plan.md.
+
+# D1 — macOS menu bar dot
+
+**Decision and recommendation.** Keep the current tray glyph as a macOS template image and draw the blue dot in a small transparent `NSView` attached to the `NSStatusBarButton`. Add a main-thread bridge call that obtains the status item through the tray handle each time the pending state changes. Position the dot relative to the image as the button lays out, because the tray also changes its title. Remove the view when no update is pending.
+
+**Alternatives.** Pre-rendered non-template RGBA icons can preserve blue, but their glyph color must follow the *status button’s* `effectiveAppearance`, including display and highlighted-state changes; the window theme is insufficient. Toggling `set_icon_with_as_template` alone cannot preserve a blue pixel while template mode is on. It is useful only for an icon-variant implementation.
+
+**Evidence.** The tray is created with `.icon_as_template(true)` at [tray.rs:104](desktop/src-tauri/src/tray.rs:104). The existing bridge already borrows `NSStatusItem` via `tray.ns_status_item()` at [native_tray.rs:63](desktop/src-tauri/src/native_tray.rs:63), and Swift obtains `item.button` at [Popover.swift:24](app/Sources/NativeTray/Popover.swift:24). There is no `.m`/`.h` bridge here: [build.rs:11](desktop/src-tauri/build.rs:11) compiles the Swift sources. The lockfile pins Tauri **2.11.6** and `tray-icon` **0.24.2** at [Cargo.lock:3796](desktop/src-tauri/Cargo.lock:3796) and [Cargo.lock:4459](desktop/src-tauri/Cargo.lock:4459). In the pinned crate, `set_icon` calls `button.setImage` and `setImagePosition`; it does not remove button subviews or layers ([tray-icon macOS source:283](~/.cargo/registry/src//tray-icon-0.24.2/src/platform_impl/macos/mod.rs:283)). Tauri’s combined setter avoids a two-render flicker but merely falls back to `set_icon` off macOS ([Tauri source:570](~/.cargo/registry/src//tauri-2.11.6/src/tray/mod.rs:570)).
+
+**Risk.** The overlay’s alignment under changing titles, highlighted menus, 1×/2× scaling, and status-item recreation needs native visual QA. Use a drawing view rather than making the button layer-backed solely for the dot.
+
+# D2 — Windows and Linux Tauri icons
+
+**Decision and recommendation.** Swap Tauri tray PNGs when pending changes. Generate normal and dotted variants from SVG sources under `desktop/src-tauri/icons/tray/`. Provide contrasting light and dark Windows base glyphs as well as their dotted variants; the present black template PNG receives no Windows template tint. Use a blue dot with a narrow contrasting halo and verify the result at the host’s rendered sizes. Linux should use a normal/dotted icon pair only when an AppIndicator host actually displays the tray.
+
+**Alternatives.** A title or menu label alone misses the required icon signal. Runtime compositing removes committed variants but introduces rendering and platform-scaling complexity.
+
+**Evidence.** The same `tray/icon.png` is currently loaded on every platform ([tray.rs:463](desktop/src-tauri/src/tray.rs:463)). The existing generator treats the menu bar asset as a 44 px SVG-derived image and checks generated output ([generate-icons.ts:62](desktop/scripts/generate-icons.ts:62)); [build-desktop-icon-set.test.ts:184](tests/ci-workflows/build-desktop-icon-set.test.ts:184) checks its size and generator wiring. Linux can have no registered tray host ([tray_availability.rs:60](desktop/src-tauri/src/tray_availability.rs:60)).
+
+**Risk.** Windows taskbar and Linux hosts resample or cache icons differently. Extend the icon generator and its existing test to check every declared variant, then inspect 16/20/24/32 px presentation on Windows and at least one AppIndicator host on Linux.
+
+# D3 — Desktop updater snapshot and badge
+
+**Decision and recommendation.** Let Tauri remain the desktop update authority. Add `POST /api/update/desktop-snapshot` to the management registry as a mutation, accepted only from the existing `admin-token` principal. The payload should contain bounded scalar fields: a random desktop session ID, app/current version, latest version or `null`, availability, and check time. Store it only in proxy memory, keyed by session ID, with a bounded entry count. Post after each updater state change and heartbeat about every 60 seconds; expire entries after roughly three minutes. `GET /api/update/badge?surface=desktop&session=` should return the badge shape with `installer: "desktop"` and `unknown: true` if the entry is absent or expired. The default badge URL retains package semantics. Carry the session ID in the embedded dashboard URL and preserve it on subsequent in-app navigation; a normal browser without it reads the package badge.
+
+**Alternatives.** Treating the compiled sidecar’s `source` result as a desktop result leaves the dot dark. One global “last desktop snapshot” would let two shells attached to the same service show each other’s update. Persisting desktop state in `version.json` would mix authorities and survive after the app exits.
+
+**Evidence.** Install detection returns `"source"` for a path without `node_modules` ([install-detection.mjs:248](src/update/install-detection.mjs:248)), and the package badge suppresses source updates ([badge.ts:48](src/update/badge.ts:48)). Tauri already owns `PendingUpdate` and six-hour checks ([updater.rs:6](desktop/src-tauri/src/updater.rs:6), [updater.rs:81](desktop/src-tauri/src/updater.rs:81)). Existing routes declare method, owner and mutation status in [route-registry.ts:81](src/server/management/route-registry.ts:81). `ProxyClient` checks the bound PID, port and generation before releasing the management token, and disables redirects and system proxies ([proxy.rs:82](desktop/src-tauri/src/proxy.rs:82), [proxy.rs:191](desktop/src-tauri/src/proxy.rs:191)). The auth model distinguishes raw admin tokens from GUI sessions ([management-auth.ts:310](src/server/management-auth.ts:310)).
+
+**Risk.** A local holder of the admin token can forge display state; that token already authorizes management operations. The snapshot must grant **no installation authority**. Require the principal explicitly, validate the bounded payload at ingress, avoid logging the session ID or raw request, and return `unknown` on expiry rather than falling back to a package update.
+
+# D4 — Desktop update page and install path
+
+**Decision and recommendation.** Add a bundled `desktop/ui/update.html` app-origin page. The embedded dashboard’s sidebar action and dashboard update entry should navigate the main WebView there when `isDesktopShell()` is true. The page reads native updater status and offers check, install, retry and return-to-dashboard actions through narrowly named Tauri commands. Both page and tray must call one native install function that atomically claims the install lock, takes `PendingUpdate`, downloads and verifies, drains the owned runtime, and restores pending state on failure.
+
+**Alternatives.** Granting updater IPC to the loopback dashboard would widen remote-origin permissions. Sending desktop users through `/api/update/run` invokes the package updater. A tray-only install path fails on Linux sessions without a tray host.
+
+**Evidence.** The dashboard currently sends its update action to `#dashboard/update` ([App.tsx:454](gui/src/App.tsx:454)), whose handler calls package `/api/update/check` ([use-dashboard-data.ts:812](gui/src/pages/use-dashboard-data.ts:812)). The sidebar already paints its blue dot from the badge GET ([sidebar-github-row.tsx:70](gui/src/components/sidebar-github-row.tsx:70), [sidebar-github-row.tsx:148](gui/src/components/sidebar-github-row.tsx:148)). The main window permits app-origin and bound `127.0.0.1` navigation ([window.rs:31](desktop/src-tauri/src/window.rs:31)); its current loopback capability grants only zoom ([dashboard-zoom.json:5](desktop/src-tauri/capabilities/dashboard-zoom.json:5)). The bundled app origin is served from `desktop/ui` ([tauri.conf.json:6](desktop/src-tauri/tauri.conf.json:6)). The tray’s current install arm takes pending state and calls `updater::install` ([tray.rs:198](desktop/src-tauri/src/tray.rs:198)); its Boolean installing flag uses `store`, so two new callers need one compare-and-swap claim ([tray.rs:303](desktop/src-tauri/src/tray.rs:303)). The updater’s download-before-drain order is already established ([updater.rs:50](desktop/src-tauri/src/updater.rs:50)).
+
+**Risk.** Cross-origin navigation from the dashboard to the bundled page needs packaged macOS, Windows and Linux verification. Test return navigation and reload, including a no-tray Linux session. Keep the updater command available only on the app-origin page.
+
+# D5 — Package cache refresh and nonblocking checks
+
+**Decision and recommendation.** Put a small scheduler start/stop hook in `src/server/index.ts`, with the worker in `src/update/`. It should run for eligible package installs on service and interactive startup, check immediately when the cache is missing or stale, recheck staleness hourly against the existing 20-hour interval, coalesce by channel, and use bounded retry backoff after failure. Do not start it for the desktop sidecar classified as `source` or for externally managed `mise`. Keep badge GET read-only. Use asynchronous `node:child_process.spawn` with the existing `registrySpawnTarget` (including pnpm owner binding and Windows argument options), a 12-second kill deadline, bounded stdout/stderr and no raw output in logs. On successful lookup, write through to `version.json`, preserving dismissal only for the same version. Treat a failed lookup as unknown after a defined maximum cache age; a suggested policy is 40 hours.
+
+Both `/api/update/check` **and** `/api/update/run` need the async path. For run, await a fresh result, then pass that already validated result into `startUpdateJob` through its existing synchronous check dependency, so its lock and worker creation remain together. The detached worker may retain synchronous checks because it does not run on the server event loop.
+
+**Alternatives.** `Bun.spawn` is viable, but adapting the current Node-style invocation options would be extra work. A detached `__refresh-version` helper handles interactive startup today but does not give the server an awaited, coalesced answer.
+
+**Evidence.** The package lookup calls `spawnSync` with a 12-second timeout ([update/index.ts:272](src/update/index.ts:272)); `/api/update/check` invokes it in the request handler ([config-routes.ts:750](src/server/management/config-routes.ts:750)). `/api/update/run` calls `startUpdateJob`, which invokes `checkForUpdateFn` synchronously ([config-routes.ts:759](src/server/management/config-routes.ts:759), [job.ts:619](src/update/job.ts:619)). The existing target preserves pnpm ownership and Windows options ([update/index.ts:188](src/update/index.ts:188), [update/index.ts:217](src/update/index.ts:217)). Cache refresh currently occurs only after the interactive gate ([notify.ts:125](src/update/notify.ts:125), [notify.ts:238](src/update/notify.ts:238)); successful writes are atomic and failures do not advance the timestamp ([notify.ts:57](src/update/notify.ts:57), [notify.ts:193](src/update/notify.ts:193)). `src/server/index.ts` is 883 lines against a 893-line cap ([index.ts:883](src/server/index.ts:883), [file-size-baseline.json:34](tests/fixtures/file-size-baseline.json:34)); its stop path already owns shutdown callbacks ([index.ts:749](src/server/index.ts:749)).
+
+**Risk.** A successful explicit preview check can temporarily replace the single-file latest-channel cache. Serialize writes and let the default-channel scheduler refresh on channel mismatch. Keep the scheduler out of `router.ts`, `server/lifecycle.ts` and `server/responses/core.ts` to preserve the optional Lab boundary; do not add an `await` between `Bun.serve` and synchronous Lab activation ([index.ts:858](src/server/index.ts:858)).
+
+# D6 — npm Windows PowerShell tray
+
+**Decision and recommendation.** Add a read-only hidden CLI command that prints the existing `readUpdateBadge()` scalar JSON, then probe it asynchronously from PowerShell about every 60 seconds. Bound its duration and output, prohibit overlap, and keep the last result only until its own expiry. Select among six icons: online, warning and offline, each with normal and blue-dot variants. Safety color has precedence as the base; the update dot overlays it. Keep the existing double-click dashboard action and add a labelled update menu action that opens the dashboard.
+
+**Alternatives.** Calling HTTP needs the admin token, fails while the proxy is offline, and couples the tray to listener availability. Reading `version.json` directly is cheaper but duplicates channel/version comparison and cache validity rules in PowerShell.
+
+**Evidence.** The tray currently loads three `.ico` assets ([windows-tray.ps1:30](src/tray/windows-tray.ps1:30)) and chooses warning before online, then offline when disconnected ([windows-tray.ps1:366](src/tray/windows-tray.ps1:366)). Its UI timer runs every three seconds ([windows-tray.ps1:473](src/tray/windows-tray.ps1:473)); the existing startup-health process probe shows a bounded, non-overlapping pattern ([windows-tray.ps1:254](src/tray/windows-tray.ps1:254)). Hidden commands already have registry and dispatch entries ([registry.ts:590](src/cli/registry.ts:590), [dispatch.ts:725](src/cli/dispatch.ts:725)). The installed asset list and owned config paths are explicit ([windows.ts:18](src/tray/windows.ts:18), [config-ownership.ts:63](src/lib/config-ownership.ts:63)).
+
+**Risk.** Prove the hidden command does not start/repair a service, refresh the registry, or write the cache. Extend the Windows tray ownership and icon-size tests; ensure timeout and shutdown dispose the badge probe.
+
+# D7 — ordered commits and proof
+
+The four-commit order in the draft is sound once D1, D4 and D5 are corrected. The structure ownership table assigns `src/update/` to `runtime.md` and `ops/service-and-sidecars.md`, `src/tray/` to `runtime.md`, and `desktop/` to `desktop-shell.md` and `companion.md` ([structure/INDEX.md:151](structure/INDEX.md:151), [structure/INDEX.md:105](structure/INDEX.md:105)).
+
+| Commit | File scope and required proof |
+|---|---|
+| **1. Package cache** | `src/update/{index,notify,badge,job}.ts`, new `refresh-scheduler.ts`, `src/server/management/config-routes.ts`, a small `src/server/index.ts` hook; extend `tests/update/{update-notify,update-badge,update-job}.test.ts`, add `tests/update/update-refresh.test.ts`. Update `structure/{runtime,gui-and-management-api}.md`, `structure/ops/service-and-sidecars.md`, and `docs-site/src/content/docs/reference/management-api.md` plus its existing `fr,ja,ko,ru,tr,zh-cn,zh-tw` siblings. Run focused Bun tests, `bun run typecheck`, `bun run structure:check`, `bun run privacy:scan`. |
+| **2. Desktop state and icons** | `desktop/src-tauri/src/{updater,tray,proxy,lib}.rs`, `app/Sources/NativeTray/Popover.swift`, `src/update/desktop-badge.ts`, `src/server/management/{sidebar-routes,route-registry}.ts`, tray SVG/PNG variants and `desktop/scripts/generate-icons.ts`; extend `tests/server/{sidebar-routes,management-route-registry}.test.ts` and `tests/ci-workflows/build-desktop-icon-set.test.ts`, add `tests/update/update-desktop-badge.test.ts`. Update `structure/{desktop-shell,gui-and-management-api}.md` and the management API and desktop guides. Run those focused tests, icon check and Cargo tests. |
+| **3. Desktop GUI route** | `desktop/ui/update.html`, `desktop/src-tauri/src/{lib,updater,tray,window,startup}.rs`, `gui/src/{App.tsx,components/sidebar-github-row.tsx,lib/desktop-shell.ts,pages/use-dashboard-data.ts}` and a small navigation helper; extend `gui/tests/desktop-shell.test.ts`, add focused desktop page tests such as `tests/clients/desktop-update-surface.test.ts`. Update the ten GUI i18n catalogs, `structure/desktop-shell.md`, `structure/gui-and-management-api.md`, and the desktop guides. Run focused tests, GUI lint/build, Cargo tests, and packaged navigation QA. |
+| **4. npm Windows tray** | Three dotted `.ico` assets, deterministic generator/check, `src/tray/{windows.ts,windows-tray.ps1}`, `src/lib/config-ownership.ts`, `src/cli/{registry,dispatch}.ts`; extend `tests/windows/{windows-tray,tray-proxy}.test.ts`. Update `structure/{runtime,ops/service-and-sidecars}.md` and `docs-site/src/content/docs/reference/cli/lifecycle.md` plus its existing `fr,ja,ko,ru,tr,zh-cn,zh-tw` siblings. Run focused Bun tests, `bun run skill:surface:check`, typecheck, structure and privacy gates. |
+
+Every **new Bun test** must be entered in both [scripts/test-layout/layout.json:1](scripts/test-layout/layout.json:1) and [tests/fixtures/test-layout-expected.json:1](tests/fixtures/test-layout-expected.json:1). Recalculate line headroom before edits: the draft’s `src/server/index.ts` figure is confirmed above, while the shared tree can move. The existing management, desktop guide and CLI lifecycle paths listed here exist under [docs-site/src/content/docs](docs-site/src/content/docs). Run the repository’s broad gate or record the allowed focused-test exception before review readiness; this read-only task ran no tests.
+
+# Unresolved assumptions
+
+- A transparent child `NSView` remains correctly positioned when AppKit changes status-button layout or highlighted appearance. The pinned crate does not remove it on `set_icon`, but packaged visual QA must settle alignment.
+- The loopback dashboard can navigate into `tauri://localhost/update.html` on macOS/Linux and `http://tauri.localhost/update.html` on Windows under each packaged WebView. The allowlist permits both origins, but that alone does not prove the page transition.
+- The desktop snapshot heartbeat interval and expiry (proposed 60 seconds and three minutes), package maximum cache age (proposed 40 hours), and exact dot dimensions need implementation tests and visual QA.
+- A hidden read-only CLI probe may still pay substantial CLI import cost on Windows. Measure its duration before fixing the 60-second cadence; keep the three-second UI timer independent.
+- Auto-install policy remains outside this unit, as specified.
diff --git a/devlog/_plan/260924_update_indicator/010_phase1_package_cache.md b/devlog/_plan/260924_update_indicator/010_phase1_package_cache.md
new file mode 100644
index 00000000000..b477e73fcaf
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/010_phase1_package_cache.md
@@ -0,0 +1,1038 @@
+# 010 — Package cache freshness and asynchronous checks
+
+## Commit contract
+
+Goal: a service-owned package install refreshes `version.json` after bind and while running; explicit management checks do not block the Bun request loop; a cache older than 40 hours cannot claim an available update. This is commit 1 / work-phase wp1 of `000_plan.md`, decision D5. It has no preceding implementation commit. Commits 2–4 may consume the unchanged package badge shape and its read-only GET.
+
+IN: npm, pnpm and Bun package installs; registry discovery; cache and dismissal; scheduler lifetime; `/api/update/check`, `/api/update/run`, package badge; focused tests; structure and public management API docs. OUT: desktop snapshot, native tray, GUI navigation, npm Windows tray, auto-install policy, Lab boundary modules, authentication semantics, updater signature/integrity checks, and change to detached installer worker. No GUI i18n key is introduced.
+
+The proposed opt-out is **new** `OCX_DISABLE_UPDATE_CHECK=1`, applying only to automatic scheduler startup. Search at this HEAD found no existing `OCX_DISABLE_UPDATE_CHECK`, `NO_UPDATE`, or `checkForUpdates` symbol under `src/config*`, `src/update`, or `src/server/index.ts`; `OCX_SERVICE` currently gates interactive prompting, not update checks (`src/update/notify.ts:125-132`). Explicit checks remain user-initiated. The source/mise guard is required regardless of the env var. Do not reinterpret `OCX_SERVICE` as an opt-out.
+
+## Existing contracts to preserve
+
+`registrySpawnTarget` rejects unowned pnpm queries and carries owner environment plus Windows invocation options (`src/update/index.ts:188-228`); `latestVersion` currently uses `spawnSync` and a 12-second timeout (`src/update/index.ts:272-290`). `resolveCurrentPnpmGlobalOwner` performs synchronous manager probes (`src/update/index.ts:97-123`), so an async registry child alone is insufficient on pnpm. `checkForUpdate` is the existing response builder, including source/mise guidance (`src/update/job.ts:486-524`); its injectable `latestVersion` dependency is declared in `src/update/check-types.ts:3-9`. `startUpdateJob` checks synchronously before creating a job (`src/update/job.ts:619-663`), and an injected `checkForUpdateFn` lets the request supply an already checked answer. The badge reader currently has no refresh dependency (`src/update/badge.ts:32-75`), and its GET only calls that reader (`src/server/management/sidebar-routes.ts:100-103`). The interactive prompt spawns `__refresh-version` (`src/update/notify.ts:174-206,238-247`), while the CLI invokes the prompt before server bind (`src/cli/index.ts:489`; test: `tests/update/update-notify.test.ts:127-139`). Server stop delegates cleanup through `runListenerShutdown` (`src/server/index.ts:749-793`); the synchronous Lab activation point is `src/server/index.ts:858-866`. Its specific structure owner is `structure/adapters/compatibility-lab.md:3-18`; this commit leaves that contract text accurate, so it is reviewed without editing it.
+
+Other existing symbols used by the proposed blocks: package/channel/install detection at `src/update/index.ts:58-80,173-185`; `registrySpawnTarget` at `src/update/index.ts:217-228`; pnpm owner lookup and running shim at `src/update/index.ts:87-123`; `unprivilegedOwnershipMutationEnvironment` import at `src/update/index.ts:14`; `VersionCache`, `readVersionCache`, `writeVersionCache`, and `isSourceBuildVersion` at `src/update/notify.ts:19-63,121-123`; `detectInstallOwnership` and `miseUpdateCommand` at `src/update/index.ts:70-80`; `UpdateCheckResult`, `checkForUpdate`, and `startUpdateJob` at `src/update/job.ts:82-92,486-524,619-663`; `normalizeUpdateChannel` at `src/update/job.ts:256`; `readUpdateBadge` at `src/update/badge.ts:48-75`; the GUI package consumers at `gui/src/pages/use-dashboard-data.ts:823,907`; the route handler at `src/server/management/config-routes.ts:290,750-777`. Runtime standard-library `spawn`, `Worker`, timers, and `Request` are platform APIs, not repository symbols.
+
+## File change map and executable edits
+
+| Path | Action | Edit anchor |
+| --- | --- | --- |
+| `src/update/index.ts` | MODIFY | Export the existing registry target builder/type only |
+| `src/update/pnpm-owner-worker.ts` | NEW | Complete worker source below |
+| `tests/fixtures/pnpm-owner-stall-worker.ts` | NEW | Worker deadline regression fixture below |
+| `src/update/async-check.ts` | NEW | Complete async lookup source below |
+| `src/update/notify.ts` | MODIFY | Export interval, add write-through, stop prompt launch |
+| `src/update/refresh-scheduler.ts` | NEW | Complete coordinator source below |
+| `src/update/badge.ts` | MODIFY | 40-hour validity and read-only state |
+| `src/server/management/config-routes.ts` | MODIFY | Await coordinated checks for check/run |
+| `src/server/management/context.ts` | MODIFY | Inject one delayed check at the management route boundary for regression proof |
+| `src/server/index.ts` | MODIFY | Paired, idempotent listener start/stop hook below |
+| `tests/update/update-refresh.test.ts` | NEW | Complete source below |
+| `tests/server/update-async-routes.test.ts` | NEW | Complete source below |
+| `tests/update/update-notify.test.ts`, `tests/update/update-badge.test.ts`, `tests/update/update-job.test.ts`, `tests/server/sidebar-routes.test.ts` | MODIFY | Cases and exact assertions below |
+| `tests/preload.ts` | MODIFY | Suppress automatic registry checks in all Bun test-started servers |
+| `scripts/test-layout/layout.json`, `tests/fixtures/test-layout-expected.json` | MODIFY | Two explicit registrations below |
+| `structure/runtime.md`, `structure/ops/service-and-sidecars.md`, `structure/gui-and-management-api.md` | MODIFY | Exact contract text below |
+| `docs-site/src/content/docs/reference/management-api.md` and existing `fr`, `ja`, `ko`, `ru`, `tr`, `zh-cn`, `zh-tw` siblings | MODIFY | Row replacements and locale instruction below |
+
+No DELETE path. No source, test, config, or other doc file is modified in this docs-only pass; this table is the later implementation commit's map.
+
+### `src/update/index.ts` — MODIFY
+
+Change the declaration `function registrySpawnTarget(` at line 217 to `export function registrySpawnTarget(`. Keep lines 218–228 byte-for-byte, as well as the synchronous `latestVersion` for the detached worker. Export its return type for the async module:
+
+```ts
+export type RegistrySpawnTarget = SpawnTarget;
+```
+
+Place that alias after `SpawnTarget` at line 193. The async module below uses exactly the same `registrySpawnTarget`, including `pnpmOwnerInvocation` (`src/update/index.ts:201-228`) and `unprivilegedOwnershipMutationEnvironment` (`src/update/index.ts:14,286`). Do not duplicate target construction. No other existing export changes.
+
+Preserve pnpm's running-shim proof across the Worker boundary. Replace the first line of `runningPnpmShimPath` (`src/update/index.ts:87-95`) and the signature/call in `resolveCurrentPnpmGlobalOwner` (`src/update/index.ts:114-123`) as follows; all other function lines stay unchanged:
+
+```ts
+function runningPnpmShimPath(invoked = process.argv[1]): string | undefined {
+ if (!invoked) return undefined;
+ const name = invoked.replaceAll("\\", "/").split("/").at(-1)?.toLowerCase();
+ if (!new Set(["ocx", "opencodex", "ocx.cmd", "opencodex.cmd", "ocx.ps1", "opencodex.ps1"]).has(name ?? "")) {
+ return undefined;
+ }
+ return resolve(invoked);
+}
+
+export function resolveCurrentPnpmGlobalOwner(invoked = process.argv[1]): PnpmGlobalOwnerResult {
+ return resolvePnpmGlobalOwner({
+ packageName: PKG,
+ packagePath: packageRoot(),
+ commandPaths: resolvePnpmCommands(),
+ runningShimPath: runningPnpmShimPath(invoked),
+ runPnpm: runPnpmCandidate,
+ });
+}
+```
+
+### `src/update/pnpm-owner-worker.ts` — NEW; complete file
+
+The worker is only used for pnpm. It runs the existing ownership proof off the request thread; it never serializes an owner to disk or a response. Bun's module worker loads this TypeScript source at runtime. A worker error/timeout yields null; it must not fall back to unowned `pnpm` on PATH.
+
+```ts
+import { resolveCurrentPnpmGlobalOwner } from "./index";
+
+onmessage = event => {
+ try {
+ const invoked = typeof event.data === "string" ? event.data : "";
+ if (!invoked) { postMessage(null); return; }
+ const result = resolveCurrentPnpmGlobalOwner(invoked);
+ postMessage(result.ok ? result.owner : null);
+ } catch {
+ postMessage(null);
+ }
+};
+```
+
+### `src/update/async-check.ts` — NEW; complete file
+
+This module owns bounded asynchronous package-manager lookup. Its `pnpmOwner` worker has an independent 12-second deadline because owner discovery may run several synchronous manager probes. The registry child has its own 12-second deadline. `spawn`'s `error` and `close` can both fire; `finish` settles once. Output is limited while streaming, so a noisy manager cannot grow memory indefinitely. No stderr/stdout is logged or returned. The worker is terminated on completion. Tests inject `spawnFn` and `ownerFn`, avoiding an installed registry or pnpm owner. The optional worker URL/deadline/invocation parameters below permit a real Bun Worker startup/deadline test without invoking a package manager; production retains the fixed source URL and 12-second deadline.
+
+```ts
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
+import { PKG, registrySpawnTarget, type Channel, type Installer } from "./index";
+import type { PnpmGlobalOwner } from "./pnpm-global-install.mjs";
+
+export const REGISTRY_DEADLINE_MS = 12_000;
+export const REGISTRY_OUTPUT_LIMIT = 4_096;
+
+export interface PnpmOwnerDeps {
+ workerUrl?: URL;
+ deadlineMs?: number;
+ invoked?: string;
+}
+
+export async function pnpmOwner(deps: PnpmOwnerDeps = {}): Promise {
+ return new Promise(resolve => {
+ let worker: Worker;
+ try {
+ worker = new Worker((deps.workerUrl ?? new URL("./pnpm-owner-worker.ts", import.meta.url)).href);
+ } catch {
+ resolve(null);
+ return;
+ }
+ let done = false;
+ const finish = (owner: PnpmGlobalOwner | null) => {
+ if (done) return;
+ done = true;
+ clearTimeout(timer);
+ void worker.terminate();
+ resolve(owner);
+ };
+ const timer = setTimeout(() => finish(null), deps.deadlineMs ?? REGISTRY_DEADLINE_MS);
+ worker.onmessage = event => finish(event.data as PnpmGlobalOwner | null);
+ worker.onerror = () => finish(null);
+ try { worker.postMessage(deps.invoked ?? process.argv[1] ?? ""); }
+ catch { finish(null); }
+ });
+}
+
+export interface AsyncLookupDeps {
+ ownerFn: () => Promise;
+ spawnFn: typeof spawn;
+ deadlineMs?: number;
+}
+
+const defaultDeps: AsyncLookupDeps = { ownerFn: pnpmOwner, spawnFn: spawn };
+
+export async function latestVersionAsync(
+ channel: Channel,
+ installer: Installer,
+ deps: AsyncLookupDeps = defaultDeps,
+): Promise {
+ if (installer === "source" || installer === "mise") return null;
+ let owner: PnpmGlobalOwner | null | undefined;
+ try { owner = installer === "pnpm" ? await deps.ownerFn() : undefined; }
+ catch { return null; }
+ if (installer === "pnpm" && !owner) return null;
+ const target = registrySpawnTarget(installer, ["view", `${PKG}@${channel}`, "version"], owner);
+ if (!target) return null;
+
+ return new Promise(resolve => {
+ let child: ChildProcessWithoutNullStreams;
+ try {
+ child = deps.spawnFn(target.bin, target.args, {
+ stdio: ["pipe", "pipe", "pipe"],
+ windowsHide: true,
+ env: unprivilegedOwnershipMutationEnvironment(target.env ?? process.env),
+ ...target.options,
+ }) as ChildProcessWithoutNullStreams;
+ } catch {
+ resolve(null);
+ return;
+ }
+ child.stdin.end();
+ let done = false;
+ let bytes = 0;
+ let stdout = "";
+ let failed = false;
+ const finish = (version: string | null) => {
+ if (done) return;
+ done = true;
+ clearTimeout(timer);
+ resolve(version);
+ };
+ const accept = (chunk: Buffer, capture: boolean) => {
+ bytes += chunk.length;
+ if (bytes > REGISTRY_OUTPUT_LIMIT) {
+ failed = true;
+ child.kill();
+ } else if (capture) {
+ stdout += chunk.toString("utf8");
+ }
+ };
+ child.stdout.on("data", (chunk: Buffer) => accept(chunk, true));
+ child.stderr.on("data", (chunk: Buffer) => accept(chunk, false));
+ child.once("error", () => finish(null));
+ child.once("close", code => {
+ const value = stdout.trim();
+ finish(!failed && code === 0 && (channel === "latest"
+ ? /^\d+\.\d+\.\d+$/.test(value)
+ : /^\d+\.\d+\.\d+(?:-preview\.\d+)?$/.test(value))
+ ? value : null);
+ });
+ const timer = setTimeout(() => {
+ child.kill();
+ finish(null);
+ }, deps.deadlineMs ?? REGISTRY_DEADLINE_MS);
+ });
+}
+```
+
+Implementation check: `ChildProcessWithoutNullStreams` is valid only with all three pipes; keep `stdio` as shown. If Bun's Worker constructor cannot load the TypeScript URL on a supported platform, the focused pnpm test must fail and B must replace it with a bundled Bun worker launch before shipping; never fall back to synchronous owner discovery in the handler.
+
+`tests/fixtures/pnpm-owner-stall-worker.ts` — NEW; complete file. It deliberately receives a message and never replies. It is loaded only by the deadline test; the empty-invocation production-worker test below proves the actual `pnpm-owner-worker.ts` can start and exchange a message without launching pnpm.
+
+```ts
+onmessage = () => {};
+```
+
+### `src/update/notify.ts` — MODIFY
+
+Export the existing interval (`src/update/notify.ts:20`) for the scheduler and add a single write-through function after `writeVersionCache` (`src/update/notify.ts:57-63`). The read occurs at commit time, after lookup completion. A dismissal follows only the exact same latest version; a different channel has no inherited dismissal. Atomic `writeVersionCache` remains the sole file writer. Since all new writes are synchronous and occur in one Bun event loop, their completion order is serialized; channel mismatch is rechecked by the next scheduler tick. No new persisted field is needed.
+
+```ts
+export const REFRESH_INTERVAL_MS = 20 * 60 * 60 * 1000;
+
+export function writeFreshVersionCache(channel: Channel, latest: string, nowMs = Date.now()): void {
+ const previous = readVersionCache(channel);
+ writeVersionCache({
+ latest_version: latest,
+ last_checked_at: new Date(nowMs).toISOString(),
+ dismissed_version: previous?.latest_version === latest && previous.dismissed_version === latest
+ ? latest : undefined,
+ tag: channel,
+ });
+}
+```
+
+Remove the original non-exported interval declaration, leaving exactly one. Replace lines 197–207 with the following compatibility body for the existing hidden CLI command, which is already detached and is not on the request loop:
+
+```ts
+export async function refreshVersionCache(channel: Channel): Promise {
+ const latest = latestVersion(channel);
+ if (latest) writeFreshVersionCache(channel, latest);
+}
+```
+
+Remove only `triggerBackgroundRefreshIfStale(channel, cache);` at line 245. Keep `triggerBackgroundRefreshIfStale`, its imports, and the hidden `__refresh-version` dispatch exported for compatibility, but `maybeShowUpdatePrompt` no longer launches it. A normal interactive `ocx start` gets the same scheduler after bind. This prevents two local writers on each new startup. Leave the pre-bind update prompt and its dismissal untouched.
+
+### `src/update/refresh-scheduler.ts` — NEW; complete file
+
+> **wp1 Check amendments (authoritative over the block below):** in-flight entries carry their `epoch`, and an automatic tick joins only a same-generation flight (a stopped listener's flight cannot write for the new one); every flight takes a per-channel sequence number and writes only when it is newer than the last flight that wrote that channel, so an explicit caller that kept an old flight writable across stop/start cannot overwrite a newer result. Regressions: `restart does not join the stopped listener's pending lookup` and `an older explicit flight cannot overwrite a newer generation's write` in `tests/update/update-refresh.test.ts`. The shipped file is `src/update/refresh-scheduler.ts` at commit 1.
+
+The same coordinator serves background and explicit checks. `check` coalesces per channel. Explicit checks bypass staleness/backoff, but join an in-flight lookup; a failed lookup returns the existing `latest_unavailable` response via `checkForUpdate`. The flight records explicit interest before awaiting. Its successful completion writes through when any caller explicitly requested the result, even if `stop()` changed the generation meanwhile; only a purely automatic late result is suppressed. This keeps one cache write for concurrent explicit callers. `start` is a synchronous timer registration and queues the first due lookup in a microtask; it does no filesystem or registry work between `Bun.serve` and Lab activation. The module singleton uses paired start/stop references: each successful `startServer` call registers one reference, and stopping one listener cannot disarm another. The scheduler has injected clock/timer/lookup dependencies for deterministic tests.
+
+```ts
+import { checkForUpdate, type UpdateCheckResult } from "./job";
+import { currentVersion, defaultUpdateTag, detectInstall, detectInstallOwnership, miseUpdateCommand, type Channel, type Installer } from "./index";
+import { isSourceBuildVersion, readVersionCache, REFRESH_INTERVAL_MS, writeFreshVersionCache } from "./notify";
+import { latestVersionAsync } from "./async-check";
+
+export const STALENESS_TICK_MS = 60 * 60 * 1000;
+export const RETRY_BASE_MS = 60_000;
+export const RETRY_CAP_MS = STALENESS_TICK_MS;
+
+export interface RefreshDeps {
+ now: () => number;
+ lookup: (channel: Channel, installer: Installer) => Promise;
+ current: () => string;
+ install: () => Installer;
+ ownership: typeof detectInstallOwnership;
+ guidance: typeof miseUpdateCommand;
+ read: typeof readVersionCache;
+ write: typeof writeFreshVersionCache;
+ setTimer: typeof setTimeout;
+ clearTimer: typeof clearTimeout;
+ disabled: () => boolean;
+}
+
+const defaults: RefreshDeps = {
+ now: Date.now,
+ lookup: latestVersionAsync,
+ current: currentVersion,
+ install: detectInstall,
+ ownership: detectInstallOwnership,
+ guidance: miseUpdateCommand,
+ read: readVersionCache,
+ write: writeFreshVersionCache,
+ setTimer: setTimeout,
+ clearTimer: clearTimeout,
+ disabled: () => process.env.OCX_DISABLE_UPDATE_CHECK === "1",
+};
+
+export function createRefreshScheduler(deps: RefreshDeps = defaults) {
+ const inFlight = new Map; markExplicit: () => void }>();
+ let timer: ReturnType | undefined;
+ let running = false;
+ let starts = 0;
+ let failures = 0;
+ let retryAt = 0;
+ let generation = 0;
+
+ const eligible = () => {
+ const version = deps.current();
+ const installer = deps.install();
+ return !deps.disabled() && version !== "?" && !isSourceBuildVersion(version)
+ && installer !== "source" && installer !== "mise";
+ };
+ const channel = () => defaultUpdateTag(deps.current());
+ const stale = (tag: Channel) => {
+ const checked = Date.parse(deps.read(tag)?.last_checked_at ?? "");
+ return !Number.isFinite(checked) || checked > deps.now() || deps.now() - checked >= REFRESH_INTERVAL_MS;
+ };
+ const schedule = (delay: number) => {
+ if (!running) return;
+ if (timer) deps.clearTimer(timer);
+ timer = deps.setTimer(() => { timer = undefined; void tick(); }, delay);
+ timer.unref?.();
+ };
+ const lookup = (tag: Channel, automatic: boolean): Promise => {
+ const existing = inFlight.get(tag);
+ if (existing) {
+ if (!automatic) existing.markExplicit();
+ return existing.task;
+ }
+ const epoch = generation;
+ let explicitInterest = !automatic;
+ const task = Promise.resolve().then(() => deps.lookup(tag, deps.install())).then(latest => {
+ if (latest && (explicitInterest || (automatic && running && epoch === generation))) {
+ deps.write(tag, latest, deps.now());
+ }
+ if (automatic && running && epoch === generation) {
+ failures = latest ? 0 : failures + 1;
+ retryAt = latest ? 0 : deps.now() + Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** Math.min(failures - 1, 6));
+ }
+ return latest;
+ }).catch(() => {
+ if (automatic && running && epoch === generation) {
+ failures += 1;
+ retryAt = deps.now() + Math.min(RETRY_CAP_MS, RETRY_BASE_MS * 2 ** Math.min(failures - 1, 6));
+ }
+ return null;
+ }).finally(() => { if (inFlight.get(tag)?.task === task) inFlight.delete(tag); });
+ inFlight.set(tag, { task, markExplicit: () => { explicitInterest = true; } });
+ return task;
+ };
+ const tick = async () => {
+ if (!running || !eligible()) return;
+ const tag = channel();
+ if (stale(tag) && deps.now() >= retryAt) await lookup(tag, true);
+ schedule(retryAt > deps.now() ? Math.min(STALENESS_TICK_MS, retryAt - deps.now()) : STALENESS_TICK_MS);
+ };
+ return {
+ start() {
+ starts += 1;
+ if (starts !== 1 || !eligible()) return;
+ running = true;
+ schedule(0);
+ },
+ stop() {
+ if (starts === 0) return;
+ starts -= 1;
+ if (starts !== 0) return;
+ running = false;
+ generation += 1;
+ if (timer) deps.clearTimer(timer);
+ timer = undefined;
+ },
+ async check(tag: Channel): Promise {
+ const installer = deps.install();
+ const latest = installer === "source" || installer === "mise" ? null : await lookup(tag, false);
+ return checkForUpdate(tag, {
+ currentVersion: deps.current,
+ detectInstall: deps.install,
+ detectInstallOwnership: deps.ownership,
+ miseUpdateCommand: deps.guidance,
+ latestVersion: () => latest,
+ });
+ },
+ };
+}
+
+export const packageRefresh = createRefreshScheduler();
+```
+
+The `detectInstallOwnership`/`miseUpdateCommand` inputs preserve the existing mise guidance (`src/update/index.ts:70-80`). An explicit caller marks an automatic flight before it settles, so the flight writes exactly once even after the final listener stops. A purely automatic flight retains the generation guard. `CACHE_MAX_AGE_MS` is defined once in `notify.ts` below; the badge imports it.
+
+### `src/update/badge.ts` — MODIFY
+
+Replace the stale top comment (`src/update/badge.ts:1-14`) with: “The badge reads the package cache only. The server scheduler and explicit checks produce it; GET never launches a lookup. A missing, wrong-channel or 40-hour-old cache reports unknown.” Define the constant in `notify.ts` beside `REFRESH_INTERVAL_MS` and import it from `./notify` to avoid a badge→scheduler→job→notify→badge runtime cycle. The final declaration is:
+
+```ts
+export const CACHE_MAX_AGE_MS = 40 * 60 * 60 * 1000;
+```
+
+Add optional `now?: () => number` to `UpdateBadgeDeps` (existing callers such as `tests/update/update-mise.test.ts:324-332` remain valid), `now: Date.now` to `defaultDeps`, and update the badge test fixture. Immediately after `if (!cache) return base;` insert:
+
+```ts
+ const checked = Date.parse(cache.last_checked_at);
+ const now = deps.now?.() ?? Date.now();
+ if (!Number.isFinite(checked) || checked > now || now - checked >= CACHE_MAX_AGE_MS) return base;
+```
+
+Import `CACHE_MAX_AGE_MS` from `./notify` and return `base` so stale `latestVersion` is not offered as installable. No route or JSON shape changes. `tests/update/update-badge.test.ts:58-64` pins the fixture's existing dependency keys; keep those keys unchanged because `now` is optional and defaults at the read site.
+
+### `src/server/management/config-routes.ts` — MODIFY
+
+In `src/server/management/context.ts`, add the two imports immediately after its existing `OcxConfig` type import (`:1`):
+
+```ts
+import type { Channel } from "../../update/index";
+import type { UpdateCheckResult } from "../../update/job";
+```
+
+Inside `ManagementApiDeps`, immediately after `requestMetrics?` (`:51`), add:
+
+```ts
+checkPackageUpdate?: (channel: Channel) => Promise;
+```
+
+Production passes no seam and always uses the coordinator; a route test injects a delayed package result without source-checkout detection or a real registry child. In the check branch (`src/server/management/config-routes.ts:750-757`), keep current invalid-tag validation and channel normalization, replace `checkForUpdate` import and final return:
+
+```ts
+const { normalizeUpdateChannel } = await import("../../update/job");
+const { packageRefresh } = await import("../../update/refresh-scheduler");
+// existing rawTag validation unchanged
+return jsonResponse(await (deps.checkPackageUpdate ?? packageRefresh.check)(normalizeUpdateChannel(rawTag)));
+```
+
+In the run branch (`src/server/management/config-routes.ts:759-777`), keep body parsing, validation and existing `UpdateJobError` catch. Inside its existing `try`, replace the return with:
+
+```ts
+const channel = normalizeUpdateChannel(body.tag as string | undefined);
+const { packageRefresh } = await import("../../update/refresh-scheduler");
+const checked = await (deps.checkPackageUpdate ?? packageRefresh.check)(channel);
+return jsonResponse({ ok: true, job: startUpdateJob(channel, body.restart !== false, {
+ checkForUpdateFn: () => checked,
+}) });
+```
+
+The checked result is already built by `checkForUpdate`, so `startUpdateJob` still owns its existing 409 lock and worker creation. The detached worker continues its own synchronous integrity/update logic (`src/update/job.ts:619-680`). A registry failure gives `latest_unavailable`; source and mise preserve their existing `UpdateJobError` codes. An explicit preview check may replace the single-file cache; the scheduler's default-channel `readVersionCache` mismatch causes a new lookup on its next hourly tick. Document that maximum mismatch window; if immediate repair is required, B may queue a default-channel tick after an explicit opposite-channel write without changing the badge GET.
+
+### `src/server/index.ts` — MODIFY
+
+Add one import near the existing startup lifecycle imports (`src/server/index.ts:63-64`):
+
+```ts
+import { packageRefresh } from "../update/refresh-scheduler";
+```
+
+Each `startServer` owns exactly one start reference. The existing `server.stop` wrapper can be called twice, so release that reference once. Immediately before `Object.defineProperty(server, "stop", {` (`src/server/index.ts:749`), insert:
+
+```ts
+let packageRefreshStopped = false;
+```
+
+Inside that wrapper before `packageTreeIntegrity.dispose()` (`src/server/index.ts:757`), insert:
+
+```ts
+if (!packageRefreshStopped) {
+ packageRefreshStopped = true;
+ packageRefresh.stop();
+}
+```
+
+Immediately before `return server;` (`src/server/index.ts:877`), after Lab activation and reset-credit activation, add `packageRefresh.start();`. Both methods are synchronous. Net growth is 7 lines including the import, below the 893-line source cap from the current 883 lines (10 lines headroom). Avoid any await between `Bun.serve` (`src/server/index.ts:690`) and Lab activation (`src/server/index.ts:864`); `tests/lab/core-lab-boundary.test.ts:1052` checks this boundary. On a bind or activation failure, no scheduler reference was registered; the return immediately follows the start call.
+
+### Tests and fixture map — MODIFY/NEW
+
+`tests/update/update-refresh.test.ts` — NEW; complete file. This virtual clock exercises startup, staleness, coalescing, backoff, cancellation, and the opt-out without a live registry. Windows invocation behavior is already covered by `tests/update/update-pnpm.test.ts:84-108` and its owner-binding tests; B also checks the same `registrySpawnTarget` is used.
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import { createRefreshScheduler, RETRY_BASE_MS, STALENESS_TICK_MS, type RefreshDeps } from "../../src/update/refresh-scheduler";
+import { latestVersionAsync, pnpmOwner, REGISTRY_DEADLINE_MS, REGISTRY_OUTPUT_LIMIT } from "../../src/update/async-check";
+import type { VersionCache } from "../../src/update/notify";
+import type { Channel, Installer } from "../../src/update/index";
+
+function fixture(installer: Installer = "npm", disabled = false, lookupFn?: RefreshDeps["lookup"]) {
+ let now = 1_700_000_000_000;
+ let nextId = 0;
+ const timers = new Map void }>();
+ const cache = new Map();
+ const calls: Channel[] = [];
+ const replies: Array> = [];
+ const writes: VersionCache[] = [];
+ const deps: RefreshDeps = {
+ now: () => now,
+ current: () => "2.7.43",
+ install: () => installer,
+ ownership: () => ({ installer, owner: null }) as ReturnType,
+ guidance: () => null,
+ disabled: () => disabled,
+ read: tag => cache.get(tag) ?? null,
+ write: (tag, latest, at) => {
+ const previous = cache.get(tag);
+ const value: VersionCache = {
+ tag, latest_version: latest, last_checked_at: new Date(at).toISOString(),
+ dismissed_version: previous?.latest_version === latest && previous.dismissed_version === latest
+ ? latest : undefined,
+ };
+ cache.set(tag, value);
+ writes.push(value);
+ },
+ lookup: async (tag, activeInstaller) => {
+ calls.push(tag);
+ return lookupFn ? lookupFn(tag, activeInstaller) : replies.length ? await replies.shift()! : "2.7.44";
+ },
+ setTimer: ((run: () => void, delay: number) => {
+ const id = ++nextId;
+ timers.set(id, { at: now + delay, run });
+ return { id, unref() {} } as ReturnType;
+ }) as typeof setTimeout,
+ clearTimer: ((timer: ReturnType) => {
+ timers.delete((timer as unknown as { id: number }).id);
+ }) as typeof clearTimeout,
+ };
+ async function advance(ms: number) {
+ now += ms;
+ for (const [id, timer] of [...timers]) {
+ if (timer.at <= now) { timers.delete(id); timer.run(); }
+ }
+ for (let index = 0; index < 8; index++) await Promise.resolve();
+ }
+ // Bounded condition wait for chains longer than advance()'s eight fixed turns (the real async
+ // lookup's fake child settles over ~16 microtask turns). Fails loudly instead of hanging.
+ async function settle(done: () => boolean, turns = 64) {
+ for (let index = 0; index < turns && !done(); index++) await Promise.resolve();
+ if (!done()) throw new Error(`condition not reached within ${turns} microtask turns`);
+ }
+ return { scheduler: createRefreshScheduler(deps), calls, replies, writes, cache, timers, advance, settle, now: () => now };
+}
+
+describe("package cache refresh", () => {
+ test("missing cache refreshes immediately and writes through", async () => {
+ const f = fixture();
+ f.scheduler.start();
+ await f.advance(0);
+ expect(f.calls).toEqual(["latest"]);
+ expect(f.cache.get("latest")?.latest_version).toBe("2.7.44");
+ f.scheduler.stop();
+ });
+
+ test("fresh cache is checked hourly and refreshed at 20 hours", async () => {
+ const f = fixture();
+ f.cache.set("latest", { tag: "latest", latest_version: "2.7.43", last_checked_at: new Date(f.now()).toISOString() });
+ f.scheduler.start();
+ await f.advance(0);
+ for (let hour = 0; hour < 19; hour++) await f.advance(STALENESS_TICK_MS);
+ expect(f.calls).toHaveLength(0);
+ await f.advance(STALENESS_TICK_MS);
+ expect(f.calls).toEqual(["latest"]);
+ f.scheduler.stop();
+ });
+
+ test("explicit checks coalesce per channel", async () => {
+ const f = fixture();
+ let release!: (value: string | null) => void;
+ f.replies.push(new Promise(resolve => { release = resolve; }));
+ const a = f.scheduler.check("latest");
+ const b = f.scheduler.check("latest");
+ await Promise.resolve();
+ expect(f.calls).toEqual(["latest"]);
+ release("2.7.44");
+ expect((await a).latestVersion).toBe("2.7.44");
+ expect((await b).latestVersion).toBe("2.7.44");
+ expect(f.writes).toHaveLength(1);
+ });
+
+ test("background and explicit checks join the same channel flight", async () => {
+ const f = fixture();
+ let release!: (value: string | null) => void;
+ f.replies.push(new Promise(resolve => { release = resolve; }));
+ f.scheduler.start();
+ await f.advance(0);
+ const explicit = f.scheduler.check("latest");
+ expect(f.calls).toEqual(["latest"]);
+ release("2.7.44");
+ expect((await explicit).latestVersion).toBe("2.7.44");
+ expect(f.writes).toHaveLength(1);
+ f.scheduler.stop();
+ });
+
+ test("explicit interest writes a joined automatic result after stop", async () => {
+ const f = fixture();
+ let release!: (value: string | null) => void;
+ f.replies.push(new Promise(resolve => { release = resolve; }));
+ f.scheduler.start();
+ await f.advance(0);
+ const explicit = f.scheduler.check("latest");
+ expect(f.calls).toEqual(["latest"]);
+ f.scheduler.stop();
+ release("2.7.44");
+ expect((await explicit).latestVersion).toBe("2.7.44");
+ expect(f.cache.get("latest")?.latest_version).toBe("2.7.44");
+ expect(f.writes).toHaveLength(1);
+ expect(f.timers.size).toBe(0);
+ });
+
+ test("one listener stopping leaves the other listener's refresh active", async () => {
+ const f = fixture();
+ f.scheduler.start();
+ f.scheduler.start();
+ f.scheduler.stop();
+ await f.advance(0);
+ expect(f.calls).toEqual(["latest"]);
+ expect(f.cache.get("latest")?.latest_version).toBe("2.7.44");
+ expect(f.timers.size).toBe(1);
+ f.scheduler.stop();
+ expect(f.timers.size).toBe(0);
+ });
+
+ test("different channels have separate flights", async () => {
+ const f = fixture();
+ await Promise.all([f.scheduler.check("latest"), f.scheduler.check("preview")]);
+ expect(f.calls).toEqual(["latest", "preview"]);
+ expect(f.writes.map(value => value.tag)).toEqual(["latest", "preview"]);
+ });
+
+ test("failed lookup does not stamp and retries with exponential delay", async () => {
+ const f = fixture();
+ f.replies.push(Promise.resolve(null), Promise.resolve(null), Promise.resolve("2.7.44"));
+ f.scheduler.start();
+ await f.advance(0);
+ expect(f.cache.size).toBe(0);
+ await f.advance(RETRY_BASE_MS);
+ expect(f.calls).toHaveLength(2);
+ await f.advance(RETRY_BASE_MS * 2);
+ expect(f.calls).toHaveLength(3);
+ expect(f.cache.get("latest")?.latest_version).toBe("2.7.44");
+ f.scheduler.stop();
+ });
+
+ test("repeated failure caps retry at one hour", async () => {
+ const f = fixture();
+ for (let n = 0; n < 9; n++) f.replies.push(Promise.resolve(null));
+ f.scheduler.start();
+ await f.advance(0);
+ for (const minutes of [1, 2, 4, 8, 16, 32, 60]) await f.advance(minutes * 60_000);
+ expect(f.calls).toHaveLength(8);
+ await f.advance(59 * 60_000);
+ expect(f.calls).toHaveLength(8);
+ await f.advance(60_000);
+ expect(f.calls).toHaveLength(9);
+ f.scheduler.stop();
+ });
+
+ test("invalid and wrong-channel caches refresh immediately", async () => {
+ const invalid = fixture();
+ invalid.cache.set("latest", { tag: "latest", latest_version: "2.7.44", last_checked_at: "bad" });
+ invalid.scheduler.start();
+ await invalid.advance(0);
+ expect(invalid.calls).toEqual(["latest"]);
+ invalid.scheduler.stop();
+ const mismatch = fixture();
+ mismatch.cache.set("preview", { tag: "preview", latest_version: "2.8.0-preview.1", last_checked_at: new Date(mismatch.now()).toISOString() });
+ mismatch.scheduler.start();
+ await mismatch.advance(0);
+ expect(mismatch.calls).toEqual(["latest"]);
+ mismatch.scheduler.stop();
+ });
+
+ test("stop cancels timer and suppresses a late automatic write", async () => {
+ const f = fixture();
+ let release!: (value: string | null) => void;
+ f.replies.push(new Promise(resolve => { release = resolve; }));
+ f.scheduler.start();
+ await f.advance(0);
+ f.scheduler.stop();
+ release("2.7.44");
+ await f.advance(STALENESS_TICK_MS);
+ expect(f.writes).toHaveLength(0);
+ expect(f.timers.size).toBe(0);
+ });
+
+ test.each(["source", "mise"] as Installer[])("%s never starts automatic lookup", async installer => {
+ const f = fixture(installer);
+ f.scheduler.start();
+ await f.advance(0);
+ expect(f.calls).toHaveLength(0);
+ expect(f.timers.size).toBe(0);
+ });
+
+ test("opt-out stops only automatic checks", async () => {
+ const f = fixture("npm", true);
+ f.scheduler.start();
+ await f.advance(0);
+ expect(f.calls).toHaveLength(0);
+ expect((await f.scheduler.check("latest")).latestVersion).toBe("2.7.44");
+ });
+});
+
+test("an absent pnpm owner cannot reach the registry child", async () => {
+ let spawned = false;
+ expect(await latestVersionAsync("latest", "pnpm", {
+ ownerFn: async () => null,
+ spawnFn: (() => { spawned = true; throw new Error("unexpected child"); }) as never,
+ })).toBeNull();
+ expect(spawned).toBe(false);
+});
+
+test("pnpm owner resolution failure is unavailable, not an unowned PATH lookup", async () => {
+ let spawned = false;
+ expect(await latestVersionAsync("latest", "pnpm", {
+ ownerFn: async () => { throw new Error("owner probe failed"); },
+ spawnFn: (() => { spawned = true; throw new Error("unexpected child"); }) as never,
+ })).toBeNull();
+ expect(spawned).toBe(false);
+});
+
+const CAN_RUN_BUN_WORKER = ["darwin", "linux", "win32"].includes(process.platform)
+ && typeof Worker === "function";
+
+test.skipIf(!CAN_RUN_BUN_WORKER)("production pnpm worker starts and answers an empty invocation", async () => {
+ const worker = new Worker(new URL("../../src/update/pnpm-owner-worker.ts", import.meta.url).href);
+ let timeout: ReturnType | undefined;
+ try {
+ const answer = new Promise((resolve, reject) => {
+ worker.onmessage = event => resolve(event.data);
+ worker.onerror = reject;
+ });
+ worker.postMessage("");
+ expect(await Promise.race([
+ answer,
+ new Promise((_, reject) => { timeout = setTimeout(() => reject(new Error("pnpm worker did not reply")), 2_000); }),
+ ])).toBeNull();
+ } finally {
+ if (timeout) clearTimeout(timeout);
+ await worker.terminate();
+ }
+});
+
+test.skipIf(!CAN_RUN_BUN_WORKER)("pnpm worker deadline terminates an unresponsive worker", async () => {
+ const started = performance.now();
+ const result = await pnpmOwner({
+ workerUrl: new URL("../fixtures/pnpm-owner-stall-worker.ts", import.meta.url),
+ deadlineMs: 25,
+ invoked: "held-shim",
+ });
+ expect(result).toBeNull();
+ expect(performance.now() - started).toBeLessThan(2_000);
+});
+
+function fakeChild() {
+ return Object.assign(new EventEmitter(), {
+ stdin: new PassThrough(), stdout: new PassThrough(), stderr: new PassThrough(),
+ killed: false,
+ kill() { this.killed = true; this.emit("close", null); return true; },
+ });
+}
+
+// Each named failure enters through the scheduler's actual lookup dependency.
+// The injected write seam is the version.json writer; empty writes/cache mean no stamp.
+for (const scenario of [
+ { name: "child error event", output: "", exitCode: 0, error: true },
+ { name: "nonzero child exit", output: "2.7.44\n", exitCode: 1, error: false },
+ { name: "malformed zero-exit output", output: "not-a-version\n", exitCode: 0, error: false },
+ { name: "empty zero-exit output", output: "", exitCode: 0, error: false },
+ { name: "multiline zero-exit output", output: "2.7.44\n2.7.45\n", exitCode: 0, error: false },
+]) {
+ test(`registry ${scenario.name} returns null and retries after backoff`, async () => {
+ const observed: Array = [];
+ let spawned = 0;
+ const f = fixture("npm", false, async (tag, installer) => {
+ const result = await latestVersionAsync(tag, installer, {
+ ownerFn: async () => null,
+ spawnFn: (() => {
+ const child = fakeChild();
+ const attempt = ++spawned;
+ queueMicrotask(() => {
+ if (attempt === 1) {
+ if (scenario.output) child.stdout.write(scenario.output);
+ if (scenario.error) child.emit("error", new Error("registry child failed"));
+ child.emit("close", scenario.exitCode);
+ } else {
+ child.stdout.write("2.7.44\n");
+ child.emit("close", 0);
+ }
+ });
+ return child;
+ }) as never,
+ });
+ observed.push(result);
+ return result;
+ });
+ f.scheduler.start();
+ await f.advance(0);
+ await f.settle(() => f.timers.size === 1);
+ expect(observed).toEqual([null]);
+ expect(f.calls).toEqual(["latest"]);
+ expect(f.writes).toHaveLength(0);
+ expect(f.cache.size).toBe(0);
+ expect(f.timers.size).toBe(1);
+ expect([...f.timers.values()].map(timer => timer.at)).toEqual([f.now() + RETRY_BASE_MS]);
+ await f.advance(RETRY_BASE_MS - 1);
+ expect(f.calls).toHaveLength(1);
+ await f.advance(1);
+ await f.settle(() => f.writes.length === 1);
+ expect(f.calls).toEqual(["latest", "latest"]);
+ expect(observed).toEqual([null, "2.7.44"]);
+ expect(f.writes).toHaveLength(1);
+ expect(f.cache.get("latest")?.latest_version).toBe("2.7.44");
+ f.scheduler.stop();
+ });
+}
+
+test("registry output is bounded and killed without leaking text", async () => {
+ const child = fakeChild();
+ const result = latestVersionAsync("latest", "npm", {
+ ownerFn: async () => null,
+ spawnFn: (() => child) as never,
+ });
+ child.stderr.write(Buffer.alloc(REGISTRY_OUTPUT_LIMIT + 1));
+ expect(await result).toBeNull();
+ expect(child.killed).toBe(true);
+});
+
+test("registry deadline kills an unresponsive child", async () => {
+ expect(REGISTRY_DEADLINE_MS).toBe(12_000);
+ const child = fakeChild();
+ const result = latestVersionAsync("latest", "npm", {
+ ownerFn: async () => null,
+ spawnFn: (() => child) as never,
+ deadlineMs: 1,
+ });
+ expect(await result).toBeNull();
+ expect(child.killed).toBe(true);
+});
+```
+
+`tests/update/update-notify.test.ts` — MODIFY: add a check that the pre-bind prompt still reads cache and no longer invokes `triggerBackgroundRefreshIfStale`, and add same-version/new-version/channel-mismatch dismissal persistence assertions.
+
+`tests/update/update-badge.test.ts` — MODIFY: add injected `now` to helper (`tests/update/update-badge.test.ts:6-20`), test 39h59m known, 40h unknown, invalid/future timestamp unknown, and assert repeated read has no lookup hook. The final guard is:
+
+```ts
+const now = deps.now?.() ?? Date.now();
+if (!Number.isFinite(checked) || checked > now || now - checked >= CACHE_MAX_AGE_MS) return base;
+```
+
+`tests/update/update-job.test.ts` — MODIFY: add `startUpdateJob uses injected prechecked result without a second registry call` using the existing `StartUpdateJobDeps` seam (`src/update/job.ts:126-130,619-642`). `tests/server/sidebar-routes.test.ts` — MODIFY: add repeated GET with an injected/controlled cache and assert no cache timestamp change; existing badge route test is `tests/server/sidebar-routes.test.ts:99-112`.
+
+`tests/preload.ts` — MODIFY: after `process.env.OCX_TEST_PRELOAD_PID = String(process.pid);` (`tests/preload.ts:82`), add exactly:
+
+```ts
+process.env.OCX_DISABLE_UPDATE_CHECK = "1";
+```
+
+This is the main plan's test-started-server guard. It must run before the lock and before tests start listeners. Tests of scheduler eligibility inject `disabled` into `createRefreshScheduler` rather than mutating the preload environment.
+
+`tests/server/update-async-routes.test.ts` — NEW; complete file. The delayed test traverses real management dispatch with an injected npm result, waits for the lookup to be entered, then proves a timer completes while that request is unresolved. The injected seam is the only source of the answer, so a regression that bypasses it or synchronously calls `checkForUpdate` fails. It proves request-loop responsiveness at the management dispatch boundary; it does not claim a live listener `/healthz` result. The source-checkout cases preserve existing guidance.
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { handleManagementAPI } from "../../src/server/management-api";
+import type { ManagementApiDeps } from "../../src/server/management/context";
+import type { OcxConfig } from "../../src/types";
+
+const config = { port: 10100, defaultProvider: "openai", providers: {} } as OcxConfig;
+
+async function call(method: string, path: string, body?: object, deps: ManagementApiDeps = {}) {
+ const url = new URL(`http://127.0.0.1:10100${path}`);
+ const request = new Request(url, {
+ method,
+ headers: { host: "127.0.0.1:10100", ...(body ? { "content-type": "application/json" } : {}) },
+ ...(body ? { body: JSON.stringify(body) } : {}),
+ });
+ return handleManagementAPI(request, url, config, deps, "admin-token");
+}
+
+describe("asynchronous package update routes", () => {
+ test("non-source check leaves the event loop responsive while lookup is pending", async () => {
+ let lookupEntered!: () => void;
+ const entered = new Promise(resolve => { lookupEntered = resolve; });
+ let release!: () => void;
+ const gate = new Promise(resolve => { release = resolve; });
+ let settled = false;
+ const pending = call("GET", "/api/update/check?tag=latest", undefined, {
+ checkPackageUpdate: async channel => {
+ expect(channel).toBe("latest");
+ lookupEntered();
+ await gate;
+ return {
+ currentVersion: "2.7.43", latestVersion: "2.7.44", channel,
+ installer: "npm", updateAvailable: true, canUpdate: true,
+ command: "npm install -g @bitkyc08/opencodex@2.7.44", releaseNotesUrl: "https://example.test/releases",
+ };
+ },
+ }).then(response => { settled = true; return response; });
+ try {
+ await entered;
+ await new Promise(resolve => setTimeout(resolve, 0));
+ expect(settled).toBe(false);
+ } finally {
+ release();
+ }
+ const response = await pending;
+ expect(response?.status).toBe(200);
+ const body = await response!.json() as Record;
+ expect(body.installer).toBe("npm");
+ expect(body.latestVersion).toBe("2.7.44");
+ });
+
+ test("source checkout check returns guidance without registry work", async () => {
+ const response = await call("GET", "/api/update/check?tag=latest");
+ expect(response?.status).toBe(200);
+ const body = await response!.json() as Record;
+ expect(body.installer).toBe("source");
+ expect(body.canUpdate).toBe(false);
+ });
+
+ test("source checkout run rejects a worker", async () => {
+ const response = await call("POST", "/api/update/run", { tag: "latest", restart: false });
+ expect(response?.status).toBe(409);
+ const body = await response!.json() as Record;
+ expect(body.code).toBe("source_checkout");
+ });
+});
+```
+
+Register both new tests:
+
+```json
+// scripts/test-layout/layout.json — explicit object, alphabetical neighbors
+"update-async-routes.test.ts": "server",
+"update-refresh.test.ts": "update",
+```
+
+```json
+// tests/fixtures/test-layout-expected.json — top-level object, alphabetical neighbors
+"update-async-routes.test.ts": "server",
+"update-refresh.test.ts": "update",
+```
+
+The snippets are JSON member edits, not standalone JSON documents; preserve commas/indentation as adjacent entries. `tests/test-layout-tooling.test.ts` checks both registries. No existing test must be moved to break the file-size ratchet.
+
+### Structure and docs-site — MODIFY
+
+`structure/runtime.md` is exactly 600/600 lines (`structure/manifest.json` sets `sizeBudgetLines: 600`). Make **one line for one line** replacement at its support row, and no other insertion or deletion in this file. Before (current `structure/runtime.md:159`):
+
+```md
+| Support | `src/lib/`, `src/storage/`, `src/usage/`, `src/update/`, `src/generated/` |
+```
+
+After (still one line; link the detailed owner contract rather than adding prose here):
+
+```md
+| Support | `src/lib/`, `src/storage/`, `src/usage/`, `src/update/` ([package refresh](ops/service-and-sidecars.md#package-cache-refresh)), `src/generated/` |
+```
+
+`structure/ops/service-and-sidecars.md`: append the following section after the existing mise updater paragraph (`structure/ops/service-and-sidecars.md:248`), which is its current final paragraph. All new scheduler prose belongs here:
+
+```md
+## Package cache refresh
+
+`src/update/refresh-scheduler.ts` owns the package cache timer and per-channel singleflight for the running proxy. Eligible npm, pnpm and Bun installs refresh missing or 20-hour-stale `version.json` after bind, check staleness hourly and retry failures with bounded backoff. Each server start owns one scheduler reference; the last matching stop disarms the timer. A stopped automatic lookup cannot write a late result, but an explicit check joining that lookup marks explicit interest and writes its successful result even if the last listener stops before it resolves. Source/mise installs and `OCX_DISABLE_UPDATE_CHECK=1` do not start automatic lookup; explicit requests remain available.
+
+`src/update/async-check.ts` uses the existing owner-bound registry target with a bounded asynchronous child; pnpm owner discovery runs in `src/update/pnpm-owner-worker.ts` off the request loop. `src/update/notify.ts` writes successful results atomically and preserves a dismissal only for the same channel and version. The interactive pre-bind prompt reads the cache and does not launch a second detached refresh. `src/update/badge.ts` only reads the cache and reports unknown at 40 hours.
+```
+
+Verify the runtime line delta is zero (`wc -l structure/runtime.md` remains 600), then run `bun run structure:check` after the implementation edits. wp4 may separately replace the `src/tray/` surfaces row, also one line for one line; it must preserve this support-row link.
+
+`structure/gui-and-management-api.md`: replace the Updates table cell (`structure/gui-and-management-api.md:168`) with its existing job/PID sentences plus: “`GET /api/update/check` and `POST /api/update/run` await one per-channel asynchronous registry lookup and write successful results through to the package cache; run passes that result to the job starter. `GET /api/update/badge` only reads the cache and reports unknown after 40 hours, on missing cache, or on channel mismatch.” Keep its existing `src/server/management/sidebar-routes.ts` owner row (`structure/gui-and-management-api.md:195`). These are present-tense changes for the implementation commit; do not land them ahead of source.
+
+`docs-site/src/content/docs/reference/management-api.md`: change the check row (`:268`) purpose to “Asynchronously check the `latest` or `preview` package channel and refresh the package cache on success”; change the run row (`:269`) purpose to “Asynchronously check a fresh package version, then start an update job, optionally followed by restart”; change the badge row (`:547`) purpose to “Read cached package badge state without a registry lookup; missing, wrong-channel or 40-hour-old cache returns `unknown: true`.” Add one short paragraph below that row: “The proxy checks an eligible package install after startup when its cache is missing or older than 20 hours, and checks freshness hourly. Set `OCX_DISABLE_UPDATE_CHECK=1` to disable automatic checks. Explicit check and run requests still work.”
+
+Apply semantically identical row and paragraph changes to the existing siblings `docs-site/src/content/docs/{fr,ja,ko,ru,tr,zh-cn,zh-tw}/reference/management-api.md`; translate “automatic checks only; explicit requests still work” and the 20-hour/40-hour values in each locale. Do not change absent de/vi siblings or any GUI catalog: no `gui/src/i18n/{en,de,fr,ja,ko,ru,tr,vi,zh,zh-TW}.ts` key is added. `docs-site/AGENTS.md` requires the docs build after implementation.
+
+## Field/value chains (PLAN-FIELD-CHAIN-01)
+
+| Value or state | Creation | Serialization | Deserialization | Every consumer |
+| --- | --- | --- | --- | --- |
+| `OCX_DISABLE_UPDATE_CHECK=1` | Operator environment; new guard in `src/update/refresh-scheduler.ts` | N/A, environment string | `process.env` equality in scheduler | Scheduler `start`/`tick`; explicit check intentionally ignores it |
+| Per-channel flight `{ task, markExplicit }`, failures, retryAt, generation, start references | `createRefreshScheduler` | N/A, process-local only | N/A | `lookup` marks explicit interest before awaiting; successful flight writes once despite a later stop; `tick`/`stop` gate purely automatic writes; paired `start`/`stop` retain the timer until the final server stops |
+| Fresh `latest_version`, `last_checked_at`, `dismissed_version`, `tag` | `writeFreshVersionCache` in `src/update/notify.ts` | Existing atomic JSON writer `src/update/notify.ts:57-63` | Existing `readVersionCache` at `src/update/notify.ts:40-55` | Prompt `src/update/notify.ts:152-160,244-247`; badge `src/update/badge.ts:66-75`; scheduler stale test; wp4 npm tray reads badge later |
+| `unknown: true` after 40 hours | Badge guard in `src/update/badge.ts` | Existing `jsonResponse` via `src/server/management/sidebar-routes.ts:100-103` | Dashboard's existing badge JSON consumer; wp2 desktop badge extends shape later | Sidebar indicator; wp4 tray uses same badge scalar. No new enum value or response field |
+| Async `UpdateCheckResult` | `checkForUpdate` with injected resolved latest in `src/update/refresh-scheduler.ts` | Existing check JSON and job-state JSON in `src/server/management/config-routes.ts:750-777`, `src/update/job.ts:649-663` | Existing management client/GUI request flow; no schema revision | `/api/update/check`, `startUpdateJob`, status polling, GUI package update dialog; wp3 desktop flow branches away |
+| Injected `checkPackageUpdate` function | Test supplies `ManagementApiDeps` in `src/server/management/context.ts`; production leaves it absent | N/A, process-local function only | N/A | Both check and run branches in `src/server/management/config-routes.ts`; production fallback is `packageRefresh.check` |
+| Worker pnpm owner | `resolveCurrentPnpmGlobalOwner` in `src/update/pnpm-owner-worker.ts` | Structured clone over worker message, no disk | `pnpmOwner` event handler in `src/update/async-check.ts` | `registrySpawnTarget` pnpm branch; no API response or persistent consumer |
+
+Search B must recheck all existing `VersionCache`, `UpdateBadge`, `UpdateCheckResult`, `latestVersion`, `readVersionCache`, and each channel literal consumer; the relevant current definitions are `src/update/notify.ts:23-29`, `src/update/badge.ts:19-36`, `src/update/job.ts:82-92`, and `src/update/index.ts:61-62`.
+
+## Conditional activation matrix (C-ACTIVATION-GROUNDING-01)
+
+| Guard/fallback | Test activation | Observable result |
+| --- | --- | --- |
+| source/mise/unknown version or opt-out | Inject each installer/version/env into scheduler | No timer or lookup; explicit check retains source/mise guidance |
+| missing, invalid timestamp, wrong channel, ≥20h stale | Seed temp cache for each | Immediate queued lookup; otherwise hourly timer |
+| concurrent same channel / different channels | Hold injected lookup promises | One call for same channel, two for distinct channels |
+| child `error` event | `registry child error event returns null and retries after backoff` emits `error` then `close` | First lookup null, no `version.json` write, retry at `RETRY_BASE_MS` and success on the next child |
+| nonzero child exit | `registry nonzero child exit returns null and retries after backoff` emits valid stdout then closes 1 | First lookup null, no `version.json` write, retry at `RETRY_BASE_MS` and success on the next child |
+| malformed, empty, multiline zero-exit output | `registry malformed zero-exit output returns null and retries after backoff`, `registry empty zero-exit output returns null and retries after backoff`, and `registry multiline zero-exit output returns null and retries after backoff` each close 0 | Each first lookup null with no `version.json` write, then retries at `RETRY_BASE_MS` and succeeds |
+| >4 KiB output / 12s deadline | `registry output is bounded and killed without leaking text`; `registry deadline kills an unresponsive child` | Null lookup; child killed on limit/deadline |
+| pnpm ownership absent/worker error/timeout | Fake worker or run worker with invalid owner | Null result; no unowned PATH query |
+| repeated failure / recovery | Resolve null 7 times then valid version | Delay 1,2,4,8,16,32,60m cap; success resets failure count |
+| stop during timer or lookup | Stop before timer, then while held lookup settles | No new automatic lookup and no late automatic cache write |
+| automatic lookup joined by explicit check, then stop | Start held automatic lookup, call explicit check, stop final listener, resolve version | Explicit result is returned and persisted once to `version.json` despite changed generation; no timer remains |
+| two server start references in one process | Start scheduler twice, stop once, advance due timer; stop second | Refresh still runs after first stop; final stop disarms timer; repeated stop cannot underflow references |
+| explicit lookup when scheduler stopped/opted out | Invoke `packageRefresh.check` with the scheduler fixture | User request succeeds and writes cache |
+| non-source route with delayed lookup | Inject npm `checkPackageUpdate` through `ManagementApiDeps`, call `/api/update/check`, run a timer before releasing the lookup | Timer fires and route remains pending; after release HTTP 200 includes npm version; no registry process |
+| Bun pnpm worker startup/deadline | On macOS/Linux/Windows with Worker, load production TS worker with empty invocation; load stall fixture with 25 ms deadline | Production worker answers null; stalled worker resolves null before 2 s and is terminated; unsupported platforms skip explicitly |
+| same version dismissal / new version / channel switch | Seed dismissed cache and resolve each version/channel | Dismissal kept only for identical version/channel; other result clears it |
+| fresh vs 40h badge boundary | Seed 39h59m and 40h timestamps | Known then `unknown: true`, `latestVersion: null`, no registry process |
+| `/api/update/run` unavailable/already running | Resolve null or hold existing running job | Existing 409 code; no worker launched |
+| no await before Lab activation | Run existing Lab source guard | `tests/lab/core-lab-boundary.test.ts` passes |
+
+## Ratchet and verification
+
+At this HEAD `src/server/index.ts` is 883/893 (`tests/fixtures/file-size-baseline.json:34`), leaving 10 lines; planned net +7 makes 890/893. Every other grown TS file is absent from the named baseline and uses the default 2,000-line ceiling: `src/update/index.ts` 883/2000, `notify.ts` 270/2000, `badge.ts` 75/2000, `src/server/management/config-routes.ts` 1112/2000, `src/server/management/context.ts` 153/2000, `tests/update/update-notify.test.ts` 165/2000, `update-badge.test.ts` 74/2000, `update-job.test.ts` 1943/2000, and `tests/server/sidebar-routes.test.ts` 304/2000. The new TS files start at 0/2000. `update-job.test.ts` has 57 lines to the default ceiling; if the new case exceeds it, place it in `update-refresh.test.ts`. The file-size ratchet scans `.json` and `.md` as well as TypeScript (`scripts/file-size-ratchet.ts:4-20`): `scripts/test-layout/layout.json` is 1813/2000 and `tests/fixtures/test-layout-expected.json` is 1620/2000, both absent from the named baseline and subject to the default ceiling. Structure and docs-site Markdown also remain subject to the ratchet and their separate checks; this `devlog/` plan is excluded from the ratchet. `structure/runtime.md` is 600/600 and must remain 600 after its one-line replacement; `structure/ops/service-and-sidecars.md` is 248/600 before its new section. Recount against the shared tree immediately before B. No cap is raised. `src/update/job.ts` remains unchanged at 1993 lines, preserving its six-line headroom.
+
+Run after B: `bun test tests/update/update-refresh.test.ts tests/update/update-notify.test.ts tests/update/update-badge.test.ts tests/update/update-job.test.ts tests/update/update-pnpm.test.ts tests/server/update-async-routes.test.ts tests/server/sidebar-routes.test.ts tests/lab/core-lab-boundary.test.ts tests/test-layout-tooling.test.ts`; `bun run typecheck`; `bun run structure:check`; `bun run privacy:scan`; `cd docs-site && bun install --frozen-lockfile && bun run build` (docs-site requirement). Test command directly names target tests; `typecheck` reads `src/**/*.ts` via `tsconfig.json`, not prose; structure checker reads `structure/**` through `scripts/structure-ssot.ts`; privacy scan reads tracked source and devlog; docs build reads docs-site pages. Exact-head hosted CI remains the PR gate. Do not claim unrun gates passed.
+
+Commands rerun during this docs-only revision, before B and after root dependencies were installed:
+
+| Command | Exit | Result and scope |
+| --- | ---: | --- |
+| `bun test tests/update/update-notify.test.ts tests/update/update-badge.test.ts tests/update/update-job.test.ts tests/update/update-pnpm.test.ts` | 0 | 124 pass, 0 fail; existing source behavior only |
+| `bun test tests/server/sidebar-routes.test.ts tests/lab/core-lab-boundary.test.ts` | 0 | 37 pass, 0 fail; existing route and Lab guards |
+| `bun test tests/test-layout-tooling.test.ts` | 0 | 16 pass, 0 fail; current test map only |
+| `bun run typecheck` | 0 | Current source typechecks; proposed new code does not exist yet |
+| `bun run structure:check` | 0 | Current structure files pass; this plan's future net-zero edit is not applied |
+| `bun run privacy:scan` | 0 | Current tracked paths pass; this document is still untracked and must be scanned after staging by main |
+
+Additional verification for the fake-child and ratchet correction in this docs-only pass:
+
+| Verifier | Exit | Result and scope |
+| --- | ---: | --- |
+| `Bun.Transpiler({ loader: "ts" }).transformSync` on the fenced `tests/update/update-refresh.test.ts` block | 0 | Proposed 350-line test block parses; future source and behavior are not yet executable |
+| `bun test tests/ci-workflows/file-size-ratchet.test.ts tests/test-layout-tooling.test.ts` | 0 | 25 pass, 0 fail; existing scanner and layout registries only, not this plan |
+| `wc -l scripts/test-layout/layout.json tests/fixtures/test-layout-expected.json` | 0 | 1813 and 1620 lines, both below the default 2000-line ceiling |
+
+The earlier pre-install test load errors and docs-site `astro` failure are superseded by the fresh results above for root tests and typecheck. `docs-site/node_modules` is still absent, so the docs build remains deferred until the implementation cycle installs its dependencies; it would also write outside this leaf's one-document scope. Tests naming `update-refresh.test.ts` and `update-async-routes.test.ts` run only after B creates them. No Bun behavior test reads this Markdown plan; review its code blocks and source anchors directly.
+
+## Risks and rollback
+
+The worker API and `spawn` event behavior must be tested under Bun on macOS and Windows. A spawned child can outlive `kill()` briefly; the 12-second timer settles the request even if `close` is late. A 12-second pnpm owner proof plus 12-second registry query can take up to 24 seconds end to end, yet neither blocks the request loop. Explicit preview cache writes can hide the default channel until its next hourly tick; route responses remain correct per channel. File writes remain atomic but are best-effort (`src/update/notify.ts:57-63`); write failure must not be reported as a successful persistent refresh in verification. An opt-out environment variable is a new public behavior and needs docs. Rollback commit 1 as one unit; legacy `version.json` schema is unchanged, so no migration or data deletion is needed. Do not weaken management auth, updater integrity checks, or the synchronous Lab activation boundary to make this work.
+
+## wp1 P revalidation (2026-09-24)
+
+Previous cycle (wp0) concluded: roadmap locked at ff8db308e6 after architect ALIGNED and audit PASS; next direction is to execute this document unchanged. Stale check at the start of wp1: `git diff 6c171aa5a6..HEAD` touches only this unit's devlog files, so every source anchor above is current; line counts match (src/server/index.ts 883/893, src/update/index.ts 883, notify.ts 270, badge.ts 75, config-routes.ts 1112, tests/update/update-job.test.ts 1943, structure/runtime.md 600/600, structure/ops/service-and-sidecars.md 248). No amendment. Architect consultation for this unit (000_plan.md) covers this document at revision 5; no design decision changes in this cycle.
diff --git a/devlog/_plan/260924_update_indicator/020_phase2_desktop_state_icons.md b/devlog/_plan/260924_update_indicator/020_phase2_desktop_state_icons.md
new file mode 100644
index 00000000000..be8a608e57b
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/020_phase2_desktop_state_icons.md
@@ -0,0 +1,1306 @@
+# Commit 2 — desktop snapshot and tray update dot
+
+Goal: make the Tauri updater the authority for a desktop-only badge and put its pending-update blue dot on each available native tray. This is work-phase wp2, ordered after commit 1 (the package badge/cache contract in 010_phase1_package_cache.md) and before commit 3 (the app-origin install page). The branch carries the four commits in 000_plan.md; this commit is not a separately releasable desktop update flow.
+
+**IN:** bounded admin-token-only POST; process-local session snapshot; desktop badge projection; 60-second native heartbeat; embedded dashboard session URL and GUI poll; macOS AppKit dot; generated dotted Windows/Linux Tauri PNG; focused Bun, Rust, and icon tests; structure and user docs. **OUT:** package cache logic owned by commit 1, install page/IPC and click routing owned by commit 3, npm PowerShell tray owned by commit 4, Windows glyph redesign, persistence, automatic install, signature policy changes, and Lab-boundary imports.
+
+This document specifies the diff to apply in B. All paths are repository-relative. Existing symbol anchors were checked against HEAD b429895f4a: the raw-token principal is assigned in src/server/management-auth.ts:541-564 and exposed in src/server/management/context.ts:136-151; route dispatch and origin/body gates are src/server/management-api.ts:187-205,276-306; the current badge route is src/server/management/sidebar-routes.ts:100-103 and registry row is src/server/management/route-registry.ts:350-353; package badge shape is src/update/badge.ts:6-67. On desktop, the bound credential gate is desktop/src-tauri/src/proxy.rs:181-228, updater transitions are desktop/src-tauri/src/updater.rs:81-114, tray transitions are desktop/src-tauri/src/tray.rs:198-222,284-325, dashboard construction is desktop/src-tauri/src/startup.rs:1407-1438, and the existing NSStatusItem borrow is desktop/src-tauri/src/native_tray.rs:58-75. The Swift status-button lookup is app/Sources/NativeTray/Popover.swift:24-32. These anchors name APIs that exist; the new symbols below are additions.
+
+Additional existing-symbol anchors used in patches: jsonResponse is src/server/auth-cors.ts:267; defaultUpdateTag is src/update/index.ts:176-178; detectInstall/Channel are src/update/index.ts:61-67; useKeyedClientResource is gui/src/client-resource.ts:616; the present sidebar poll is gui/src/components/sidebar-github-row.tsx:67-76; desktop-shell detection is gui/src/lib/desktop-shell.ts:7-13; the Tauri user agent is desktop/src-tauri/src/window.rs:4-14; app.package_info() is used at desktop/src-tauri/src/menu.rs:28; the Popup destination and matcher are desktop/src-tauri/src/popup.rs:256-263,313-320; and the icon generator's render/produced/check chain is desktop/scripts/generate-icons.ts:62-145,157-175. The pinned Tauri set_icon API is called through the existing tray handle at desktop/src-tauri/src/tray.rs:104-107,463-465; B also compiles it against the checked-in Cargo.lock. The AppKit NSButtonCell.imageRect(forBounds:) call was checked with the swift verifier below.
+
+## File change map and executable patches
+
+The following are the entire commit-2 file set. DELETE: none. Binary NEW output is generated, not hand-edited. MODIFY rows with an insertion block mean insert at the named existing anchor; replacement blocks name the exact old expression. Commit 1 changed src/update/badge.ts: its 40-hour cache-age guard and `unknown` result remain package-only. Change only the installer type line shown here; the desktop store supplies the same seven-field response independently.
+
+| Operation | Path | Change |
+| --- | --- | --- |
+| NEW | src/update/desktop-badge.ts | Strict snapshot DTO, bounded process store, desktop badge projection; full content below. |
+| MODIFY | src/update/badge.ts | Widen only UpdateBadge.installer to include desktop. |
+| MODIFY | src/server/management/sidebar-routes.ts | Desktop GET branch and admin-token POST with bounded stream read. |
+| MODIFY | src/server/management/route-registry.ts | Declare POST and truthful desktop-internal parity exemption. |
+| MODIFY | desktop/src-tauri/src/proxy.rs | Bound POST JSON through existing identity-checked client. |
+| MODIFY | desktop/src-tauri/src/updater.rs | Random session, serial snapshot publisher, state transitions and 60 s heartbeat. |
+| MODIFY | desktop/src-tauri/src/lib.rs | Manage and start the snapshot publisher. |
+| MODIFY | desktop/src-tauri/src/startup.rs | Carry session in embedded dashboard URL; wake publisher on bind. |
+| MODIFY | desktop/src-tauri/src/native_tray.rs | Borrow status button on main thread for dot bridge. |
+| MODIFY | app/Sources/NativeTray/Popover.swift | NSView dot, @_cdecl show/hide bridge, image-relative drawing. |
+| MODIFY | desktop/src-tauri/src/tray.rs | Apply native/PNG indicator on updater/tray state and title refresh. |
+| MODIFY | desktop/src-tauri/src/popup.rs | Preserve the session when the web tray opens the main dashboard. |
+| MODIFY | desktop/scripts/generate-icons.ts | Generate and check a dotted PNG from tray/icon.svg plus SVG halo/dot. |
+| NEW generated | desktop/src-tauri/icons/tray/icon-update.png | 44×44 RGBA, output of the generator; no hand-authored binary. |
+| MODIFY | gui/src/lib/desktop-shell.ts | Strict session query reader and badge URL helper. |
+| MODIFY | gui/src/components/sidebar-github-row.tsx | Desktop-session poll URL and 60 s cadence. |
+| NEW | tests/update/update-desktop-badge.test.ts | Full test content below. |
+| MODIFY | tests/server/sidebar-routes.test.ts | Principal, malformed ingress, absent/expiry/isolation route tests. |
+| MODIFY | tests/server/management-route-registry.test.ts | Registry row and exemption check. |
+| MODIFY | tests/cli/cli-capabilities.test.ts | Assert that the desktop-only POST is deliberately not a CLI capability. |
+| MODIFY | tests/ci-workflows/build-desktop-icon-set.test.ts | Generated dotted variant size/source/colour declaration. |
+| MODIFY | gui/tests/desktop-shell.test.ts | Desktop URL, missing session, browser isolation. |
+| MODIFY | scripts/test-layout/layout.json | Explicit owner for the new Bun test. |
+| MODIFY | tests/fixtures/test-layout-expected.json | Same explicit owner. |
+| MODIFY | structure/desktop-shell.md; structure/companion.md; structure/gui-and-management-api.md; structure/runtime.md; structure/ops/service-and-sidecars.md | Current-state contracts below; the last two own src/update/. |
+| MODIFY | docs-site/src/content/docs/reference/management-api.md; docs-site/src/content/docs/guides/desktop-app.md and their existing fr, ja, ko, ru, tr, zh-cn, zh-tw siblings | User-facing contract below. |
+
+### New src/update/desktop-badge.ts — full content
+
+The current UpdateBadge shape has currentVersion, latestVersion, channel, installer, canUpdate, updateAvailable and unknown (src/update/badge.ts:6-18). The commit-1 package reader returns `unknown: true` for missing, wrong-channel, invalid-time, future-time or 40-hour-stale cache; the desktop store must use its receipt TTL instead and must not read that cache. Keep precisely that response shape; do not include sessionId or phase in GET output. A session id is a routing nonce, not an install credential. The map is bounded even if clients continually change ids. Expiry is measured from *receipt*, so a six-hour updater check remains displayable while the heartbeat continues.
+
+~~~ts
+import type { UpdateBadge } from "./badge";
+import { defaultUpdateTag } from "./index";
+
+export type DesktopPhase =
+ | "idle" | "checking" | "available" | "current"
+ | "error" | "installing" | "install-failed";
+
+export interface DesktopSnapshot {
+ sessionId: string;
+ currentVersion: string;
+ latestVersion: string | null;
+ available: boolean;
+ checkedAtMs: number | null;
+ phase: DesktopPhase;
+}
+
+const SESSION = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,63}$/;
+const PHASES = new Set([
+ "idle", "checking", "available", "current", "error", "installing", "install-failed",
+]);
+export const DESKTOP_SNAPSHOT_TTL_MS = 180_000;
+export const DESKTOP_SNAPSHOT_MAX_SESSIONS = 32;
+const MIN_DESKTOP_CHECKED_AT_MS = 946_684_800_000; // 2000-01-01 UTC
+const MAX_DESKTOP_CLOCK_SKEW_MS = 60_000;
+
+export function validDesktopSession(value: unknown): value is string {
+ return typeof value === "string" && SESSION.test(value);
+}
+
+export function parseDesktopSnapshot(value: unknown, nowMs: number): DesktopSnapshot | null {
+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+ const body = value as Record;
+ const keys = Object.keys(body).sort();
+ if (keys.join(",") !== "available,checkedAtMs,currentVersion,latestVersion,phase,sessionId") return null;
+ if (!validDesktopSession(body.sessionId)
+ || typeof body.currentVersion !== "string" || !VERSION.test(body.currentVersion)
+ || (body.latestVersion !== null && (typeof body.latestVersion !== "string" || !VERSION.test(body.latestVersion)))
+ || typeof body.available !== "boolean"
+ || typeof body.phase !== "string" || !PHASES.has(body.phase as DesktopPhase)) return null;
+ const checked = body.checkedAtMs;
+ if (checked !== null && (typeof checked !== "number" || !Number.isSafeInteger(checked) || checked < 0
+ || checked < MIN_DESKTOP_CHECKED_AT_MS
+ || checked > nowMs + MAX_DESKTOP_CLOCK_SKEW_MS)) return null;
+ if (body.available !== (body.latestVersion !== null)) return null;
+ if (body.available && checked === null) return null;
+ if (body.phase === "available" && !body.available) return null;
+ if (body.phase === "current" && (body.available || checked === null)) return null;
+ if (body.phase === "idle" && (body.available || checked !== null)) return null;
+ if ((body.phase === "installing" || body.phase === "install-failed") && !body.available) return null;
+ return body as unknown as DesktopSnapshot;
+}
+
+export class DesktopBadgeStore {
+ private readonly entries = new Map();
+ constructor(
+ private readonly wallNowMs: () => number = Date.now,
+ private readonly elapsedNowMs: () => number = () => performance.now(),
+ ) {}
+
+ put(value: unknown): boolean {
+ const snapshot = parseDesktopSnapshot(value, this.wallNowMs());
+ if (!snapshot) return false;
+ const now = this.elapsedNowMs();
+ this.prune(now);
+ this.entries.delete(snapshot.sessionId);
+ while (this.entries.size >= DESKTOP_SNAPSHOT_MAX_SESSIONS) {
+ this.entries.delete(this.entries.keys().next().value!);
+ }
+ this.entries.set(snapshot.sessionId, { snapshot, receivedAtMs: now });
+ return true;
+ }
+
+ read(sessionId: string | null): UpdateBadge {
+ const now = this.elapsedNowMs();
+ this.prune(now);
+ const snapshot = sessionId && validDesktopSession(sessionId)
+ ? this.entries.get(sessionId)?.snapshot : undefined;
+ if (!snapshot) return {
+ updateAvailable: false, currentVersion: "?", latestVersion: null,
+ channel: "latest", installer: "desktop", canUpdate: true, unknown: true,
+ };
+ return {
+ updateAvailable: snapshot.available,
+ currentVersion: snapshot.currentVersion,
+ latestVersion: snapshot.latestVersion,
+ channel: defaultUpdateTag(snapshot.currentVersion),
+ installer: "desktop",
+ canUpdate: true,
+ unknown: snapshot.phase === "idle"
+ || ((snapshot.phase === "checking" || snapshot.phase === "error") && !snapshot.available),
+ };
+ }
+
+ private prune(now: number): void {
+ for (const [key, entry] of this.entries) {
+ if (now - entry.receivedAtMs >= DESKTOP_SNAPSHOT_TTL_MS) this.entries.delete(key);
+ }
+ }
+}
+
+export const desktopBadgeStore = new DesktopBadgeStore();
+~~~
+
+Before this parser edit, the last guard was `checked < nowMs - 24 * 60 * 60_000`; after, the two named bounds in the block above enforce only pre-2000 and >60-second-future rejection. `checkedAtMs` records when the native updater last settled; it is not a freshness lease. A 25-hour-old successful check remains valid if the living shell continues to send the same pending snapshot. `DesktopBadgeStore.put()` stamps each accepted POST with a new monotonic receipt time, and `read()` expires that receipt after 180 seconds without a heartbeat. The absolute lower bound rejects nonsensical timestamps without coupling display lifetime to check cadence. A null timestamp remains valid only for phases permitted by the schema.
+
+MODIFY src/update/badge.ts:12: replace only the installer declaration. Exact current before: `installer: ReturnType;`. Keep `UpdateBadgeDeps.now`, the cache-age guard, and every other field unchanged. After:
+
+~~~ts
+installer: ReturnType | "desktop";
+~~~
+
+MODIFY src/server/management/sidebar-routes.ts:100-103. Keep the existing package GET exactly for an absent surface; add the POST and desktop branch *before* it. Management authentication happens before handleManagementAPI in the listener, but this route must additionally use ctx.principal, not request headers: src/server/management-auth.ts:555-563 gives the raw token the exact "admin-token" principal, while a GUI session yields "gui-session". Direct-dispatch tests with undefined principal also fail closed. The outer 2 MiB Content-Length check at src/server/management-api.ts:198-205 is insufficient for this 1 KiB schema, so the route measures bytes as it reads. The following is the exact block to insert immediately before the old badge GET:
+
+~~~ts
+ if (url.pathname === "/api/update/desktop-snapshot" && req.method === "POST") {
+ if (ctx.principal !== "admin-token") {
+ return jsonResponse({ error: "desktop snapshot requires admin token" }, 403, req, ctx.config);
+ }
+ if (req.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() !== "application/json") {
+ return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);
+ }
+ const declared = Number(req.headers.get("content-length") ?? "0");
+ if (Number.isFinite(declared) && declared > 1024) {
+ return jsonResponse({ error: "desktop snapshot too large" }, 413, req, ctx.config);
+ }
+ const reader = req.body?.getReader();
+ if (!reader) return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);
+ const bytes = new Uint8Array(1024);
+ let used = 0;
+ try {
+ while (true) {
+ const part = await reader.read();
+ if (part.done) break;
+ if (used + part.value.length > bytes.length) {
+ await reader.cancel();
+ return jsonResponse({ error: "desktop snapshot too large" }, 413, req, ctx.config);
+ }
+ bytes.set(part.value, used);
+ used += part.value.length;
+ }
+ const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, used));
+ const { desktopBadgeStore } = await import("../../update/desktop-badge");
+ if (!desktopBadgeStore.put(JSON.parse(decoded))) {
+ return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);
+ }
+ } catch {
+ return jsonResponse({ error: "invalid desktop snapshot" }, 400, req, ctx.config);
+ }
+ return jsonResponse({ ok: true }, 200, req, ctx.config);
+ }
+
+ if (url.pathname === "/api/update/badge" && req.method === "GET"
+ && url.searchParams.get("surface") === "desktop") {
+ const { desktopBadgeStore } = await import("../../update/desktop-badge");
+ return jsonResponse(desktopBadgeStore.read(url.searchParams.get("session")), 200, req, ctx.config);
+ }
+~~~
+
+Immediately before the old package GET, also reject any other nonempty surface with a fixed 400; this prevents a misspelled desktop surface silently reading the package badge:
+
+~~~ts
+ if (url.pathname === "/api/update/badge" && req.method === "GET"
+ && url.searchParams.has("surface") && url.searchParams.get("surface") !== "desktop") {
+ return jsonResponse({ error: "invalid badge surface" }, 400, req, ctx.config);
+ }
+~~~
+
+Do not log request URLs, body, session id, or a parse exception. No body or session id is echoed. An authenticated ordinary browser can GET a known desktop session; the id is display routing, not an installation authorization.
+
+MODIFY src/server/management/route-registry.ts:28-60 and :350-353. Add to ExemptionReason, before "deferred-verb":
+
+~~~ts
+ /** Desktop shell's internal display-state POST; the CLI has no app updater state to publish. */
+ | "desktop-internal"
+~~~
+
+Add after the existing GET badge row:
+
+~~~ts
+ { method: "POST", path: "/api/update/desktop-snapshot",
+ module: "server/management/sidebar-routes", mutates: true,
+ exempt: { reason: "desktop-internal",
+ why: "Only the Tauri shell has signed-updater state to publish; a CLI verb could only forge that state and would not create an operator action." } },
+~~~
+
+The row is a process-state mutation, hence mutates: true. The CLI parity ratchet at tests/cli/cli-capabilities.test.ts:343-370 requires the exemption, and "local-transport" would be false because ProxyClient sends HTTP. The registry stays pure data.
+
+### Rust transport and state
+
+MODIFY desktop/src-tauri/src/proxy.rs:1-8,181-228. The new method goes immediately before request(). It uses the same authorised_token() identity/generation check (desktop/src-tauri/src/proxy.rs:191-209) and the same no-redirect/no-system-proxy client (desktop/src-tauri/src/proxy.rs:82-100). It never accepts a caller-supplied URL.
+
+~~~rust
+ pub async fn post_desktop_snapshot(&self, body: &Value) -> Result<(), ProxyError> {
+ let token = self.authorised_token().await?;
+ let response = self.client
+ .post(self.endpoint.url("/api/update/desktop-snapshot"))
+ .header("X-OpenCodex-API-Key", token)
+ .json(body)
+ .send().await.map_err(|error| {
+ if error.is_connect() { ProxyError::Unreachable } else { ProxyError::Decode(error) }
+ })?;
+ let _ = decode(response).await?;
+ Ok(())
+ }
+~~~
+
+MODIFY desktop/src-tauri/src/updater.rs:1-6,81-114 and :116-144. Add imports and the following exact definitions above PendingUpdate. No new dependency: uuid v4 is already pinned in desktop/src-tauri/Cargo.toml:21 and used in desktop/src-tauri/src/identity.rs:19,48; serde_json and tokio are already used by desktop/src-tauri/src/proxy.rs:2-8. The publisher is a single serial task, so a late heartbeat cannot overwrite a later updater transition at the proxy. Native checks also need their own ordering gate: serialization of POSTs cannot correct a stale result already applied to PendingUpdate, tray, and the snapshot.
+
+~~~rust
+use serde::Serialize;
+use serde_json::to_value;
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
+use tokio::sync::watch;
+use uuid::Uuid;
+
+#[derive(Clone)]
+pub enum UiProjection { Available(String), Current }
+
+#[derive(Clone)]
+struct UiUpdate { revision: u64, projection: UiProjection }
+
+pub struct CheckGeneration {
+ latest_started: AtomicU64,
+ install_epoch: AtomicU64,
+ application: Mutex<()>,
+ latest_ui_revision: AtomicU64,
+ ui: watch::Sender>,
+}
+
+impl Default for CheckGeneration {
+ fn default() -> Self {
+ let (ui, _) = watch::channel(None);
+ Self { latest_started: AtomicU64::new(0), install_epoch: AtomicU64::new(0),
+ application: Mutex::new(()), latest_ui_revision: AtomicU64::new(0), ui }
+ }
+}
+
+impl CheckGeneration {
+ pub fn begin_if_not_installing(
+ &self, installing: &std::sync::atomic::AtomicBool, publish_checking: impl FnOnce(),
+ ) -> Option<(u64, u64)> {
+ let _guard = self.application.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ if installing.load(Ordering::Acquire) { return None; }
+ let generation = self.latest_started.fetch_add(1, Ordering::AcqRel) + 1;
+ let epoch = self.install_epoch.load(Ordering::Acquire);
+ publish_checking();
+ Some((generation, epoch))
+ }
+
+ // Commit 3 uses this for both the tray and page install paths.
+ pub fn claim_install(&self, installing: &std::sync::atomic::AtomicBool) -> bool {
+ let _guard = self.application.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ if installing.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire).is_err() {
+ return false;
+ }
+ self.install_epoch.fetch_add(1, Ordering::AcqRel);
+ // Invalidate a queued check projection before the install can take PendingUpdate.
+ self.latest_ui_revision.fetch_add(1, Ordering::AcqRel);
+ true
+ }
+
+ pub fn epoch_is_current(&self, epoch: u64) -> bool {
+ self.install_epoch.load(Ordering::Acquire) == epoch
+ }
+
+ pub fn apply_if_current(&self, generation: u64, apply: impl FnOnce() -> T) -> Option {
+ let _guard = self.application.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ if self.latest_started.load(Ordering::Acquire) != generation { return None; }
+ Some(apply())
+ }
+
+ pub fn inspect(&self, read: impl FnOnce() -> T) -> T {
+ let _guard = self.application.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ read()
+ }
+
+ // Call only inside application/inspect. This is an in-memory send, never a Tauri setter.
+ fn queue_ui(&self, projection: UiProjection) {
+ let revision = self.latest_ui_revision.fetch_add(1, Ordering::AcqRel) + 1;
+ self.ui.send_replace(Some(UiUpdate { revision, projection }));
+ }
+
+ fn apply_ui_projection_if_current(
+ &self, update: UiUpdate, apply: impl FnOnce(UiProjection),
+ ) -> bool {
+ // A short atomic check only. In particular, never take application here.
+ if update.revision != self.latest_ui_revision.load(Ordering::Acquire) { return false; }
+ apply(update.projection);
+ true
+ }
+}
+
+pub fn start_ui_projection_worker(app: AppHandle) {
+ let mut receiver = app.state::().ui.subscribe();
+ tauri::async_runtime::spawn(async move {
+ while receiver.changed().await.is_ok() {
+ let Some(update) = receiver.borrow_and_update().clone() else { continue; };
+ // One worker serializes all updater menu/icon calls. A newer transition wins;
+ // if one setter is already waiting on AppKit, the latest queued state follows it.
+ app.state::().apply_ui_projection_if_current(update, |projection| {
+ match projection {
+ UiProjection::Available(version) => tray::show_update_available(&app, &version),
+ UiProjection::Current => tray::show_up_to_date(&app),
+ }
+ });
+ }
+ });
+}
+
+#[derive(Clone, Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct DesktopSnapshot {
+ session_id: String,
+ current_version: String,
+ latest_version: Option,
+ available: bool,
+ checked_at_ms: Option,
+ phase: &'static str,
+}
+
+pub struct DesktopUpdateState {
+ session_id: String,
+ tx: watch::Sender,
+}
+
+impl DesktopUpdateState {
+ pub fn new(current_version: String) -> Self {
+ let session_id = Uuid::new_v4().to_string();
+ let (tx, _) = watch::channel(DesktopSnapshot {
+ session_id: session_id.clone(), current_version, latest_version: None,
+ available: false, checked_at_ms: None, phase: "idle",
+ });
+ Self { session_id, tx }
+ }
+
+ pub fn session_id(&self) -> &str { &self.session_id }
+
+ pub fn publish(&self, phase: &'static str, latest: Option, checked: Option) {
+ let previous = self.tx.borrow().clone();
+ let next = DesktopSnapshot {
+ session_id: self.session_id.clone(),
+ current_version: previous.current_version,
+ available: latest.is_some(),
+ latest_version: latest,
+ checked_at_ms: checked,
+ phase,
+ };
+ self.tx.send_replace(next);
+ }
+
+ pub fn retain_phase(&self, phase: &'static str) {
+ let previous = self.tx.borrow().clone();
+ self.publish(phase, previous.latest_version, previous.checked_at_ms);
+ }
+
+ pub fn wake(&self) {
+ let snapshot = self.tx.borrow().clone();
+ self.tx.send_replace(snapshot);
+ }
+}
+
+fn now_ms() -> u64 {
+ SystemTime::now().duration_since(UNIX_EPOCH)
+ .unwrap_or_default().as_millis().min(u128::from(u64::MAX)) as u64
+}
+
+pub fn start_snapshot_publisher(app: AppHandle) {
+ let mut receiver = app.state::().tx.subscribe();
+ tauri::async_runtime::spawn(async move {
+ loop {
+ let snapshot = receiver.borrow_and_update().clone();
+ if let Some(proxy) = app.try_state::().and_then(|state| state.proxy()) {
+ if let Ok(body) = to_value(&snapshot) {
+ let _ = proxy.post_desktop_snapshot(&body).await;
+ }
+ }
+ tokio::select! {
+ changed = receiver.changed() => if changed.is_err() { break; },
+ _ = tokio::time::sleep(Duration::from_secs(60)) => {}
+ }
+ }
+ });
+}
+~~~
+
+The publisher swallows transport failures as best-effort display state. The next state change or 60 s tick retries. It does not log identifiers or errors. At most one POST is in flight from this shell. The 4 s client timeout is already set at desktop/src-tauri/src/proxy.rs:85-86. The sender lives for the app lifetime, so changed() normally stays open.
+
+Replace check_and_show() at desktop/src-tauri/src/updater.rs:91-114 with this complete body. Before, the function ran `match check(app).await` and applied each `Some`/`None` immediately; the complete after-body is below. `begin_if_not_installing` checks the install flag and publishes `"checking"` under the same short `application` mutex used by `claim_install` (commit 3) and `apply_if_current`. The result closure holds that mutex through the install guard, pending model, tray's pure `update_pending` flag, snapshot, and UI projection enqueue; an install claim cannot enter between its guard and those writes. The serialized projection worker applies menu, icon, and native overlay setters after the gate has been released. No mutex spans `check(app).await` or a Tauri setter. Every caller (the six-hour loop at updater.rs:81-89, tray manual action at tray.rs:192-196, and commit-3 page command) uses this one function.
+
+~~~rust
+pub async fn check_and_show(app: &AppHandle) {
+ let gate = app.state::();
+ let state = app.state::();
+ let Some((generation, _epoch)) = gate.begin_if_not_installing(&state.installing, || {
+ app.state::().retain_phase("checking");
+ }) else { return; };
+ let answer = check(app).await;
+ let applied_error = gate.apply_if_current(generation, || {
+ if tray::is_installing(app) { return None; }
+ match answer {
+ Ok(Some(update)) => {
+ let version = update.version.clone();
+ if let Ok(mut pending) = app.state::().0.lock() {
+ *pending = Some(update);
+ }
+ app.state::()
+ .publish("available", Some(version.clone()), Some(now_ms()));
+ state.update_pending.store(true, Ordering::Release);
+ gate.queue_ui(UiProjection::Available(version));
+ None
+ }
+ Ok(None) => {
+ if let Ok(mut pending) = app.state::().0.lock() {
+ *pending = None;
+ }
+ app.state::().publish("current", None, Some(now_ms()));
+ state.update_pending.store(false, Ordering::Release);
+ gate.queue_ui(UiProjection::Current);
+ None
+ }
+ Err(error) => {
+ app.state::().retain_phase("error");
+ Some(error)
+ }
+ }
+ }).flatten();
+ if let Some(error) = applied_error { logging::log_once("updater check failed", &error); }
+}
+~~~
+
+Commit 3 consumes `CheckGeneration::{begin_if_not_installing,claim_install,apply_if_current,epoch_is_current,inspect}` and the gate-private `queue_ui`. `begin_if_not_installing` returns the generation and epoch captured while it owns the gate, after rechecking the install flag and before publishing `"checking"`. `claim_install` takes the same gate for the flag CAS and epoch increment, invalidating queued check UI; commit 3 extends it to enqueue the install projection before release. `apply_if_current` returns `None` when another check started; `Some(T)` is the applied model result, and commit 3 compares the captured epoch inside its application closure before any state write. `inspect` lets the page read pending and checking status under the same gate. A stale result or error maps to `Ok(())` for the page without logging an obsolete failure. The UI worker checks `latest_ui_revision` immediately before each projection and serializes every updater menu/icon/overlay application; if a newer state arrives during a blocking setter, it applies afterward. The gate is managed once per app process immediately before the background checker can start. If a previous signed pending update exists, checking/error retains latestVersion and its blue dot; if not, error projects unknown. The Tauri updater still supplies the availability decision; the proxy never recomputes it.
+
+MODIFY desktop/src-tauri/src/lib.rs:1-35,223-270: immediately after managing PendingUpdate, insert:
+
+~~~rust
+ app.manage(updater::DesktopUpdateState::new(app.package_info().version.to_string()));
+ app.manage(updater::CheckGeneration::default());
+ updater::start_ui_projection_worker(app.handle().clone());
+ updater::start_snapshot_publisher(app.handle().clone());
+~~~
+
+Tauri's package_info() use already exists at desktop/src-tauri/src/menu.rs:28. Start the publisher independently of the release-build updater-check gate at lib.rs:268-270 so a debug shell can still produce an unknown desktop badge.
+
+MODIFY desktop/src-tauri/src/startup.rs:1407-1438: replace the old endpoint.url("/#/usage") line at :1414 with:
+
+~~~rust
+ let path = format!(
+ "/?desktop_session={}#/usage",
+ app.state::().session_id()
+ );
+ let dashboard = endpoint.url(&path);
+~~~
+
+After the existing if !emit(app, progress, None) { ... return; } block at startup.rs:1417-1421, add:
+
+~~~rust
+ app.state::().wake();
+~~~
+
+The state is managed before startup::begin (desktop/src-tauri/src/lib.rs:223-266). This wake immediately retries only after a successful Ready publication; before bind, the publisher has no ProxyClient and sends nothing. Existing startup navigation retains the complete URL through progress.dashboard (startup.rs:1415-1435,1448-1487).
+
+MODIFY desktop/src-tauri/src/popup.rs:256-263: the incoming web-tray link is still matched against DASHBOARD_PATH at :16 and :313-320. Replace main.navigate(url.clone()) with the following destination, leaving the source matcher unchanged:
+
+~~~rust
+ let session = app.state::().session_id().to_string();
+ let destination = endpoint.url(&format!("/?desktop=open&desktop_session={session}#/usage"));
+ if let Ok(destination) = destination.parse() { let _ = main.navigate(destination); }
+~~~
+
+The popup's link stays at gui/src/pages/Tray.tsx:141,176, which already emits /?desktop=open#/usage, and popup.rs:313-320 recognizes it. Only the main webview destination gains the session. The external Open in Browser action at desktop/src-tauri/src/tray.rs:170-177 remains a package-view browser on purpose.
+
+### Native and generated icon changes
+
+MODIFY desktop/src-tauri/src/native_tray.rs:17-22: add the declaration to the existing extern block:
+
+~~~rust
+ fn ocx_native_tray_update_dot(item: *mut c_void, show: i32);
+~~~
+
+Add this function after present() at native_tray.rs:58-76. It gets a fresh status-item pointer each time; no borrowed pointer survives the closure. run_on_main_thread is already used in native_tray.rs:78-80.
+
+~~~rust
+pub fn set_update_dot(app: &AppHandle, _show: bool) {
+ let app = app.clone();
+ let target = app.clone();
+ let _ = target.run_on_main_thread(move || {
+ let Some(tray) = app.tray_by_id("main") else { return; };
+ let pending = app.try_state::()
+ .is_some_and(|state| state.update_pending.load(Ordering::Acquire));
+ let _ = tray.with_inner_tray_icon(|inner| {
+ if let Some(item) = inner.ns_status_item() {
+ let pointer = (&*item as *const _ as *mut c_void).cast();
+ unsafe { ocx_native_tray_update_dot(pointer, i32::from(pending)); }
+ }
+ });
+ });
+}
+~~~
+
+The main-thread closure reads the latest atomic pending value when it executes. A queued title refresh cannot re-show an already cleared dot with an older captured Boolean.
+
+Also replace the static path selection in native_event() at native_tray.rs:95-102 so opening the main dashboard from the macOS panel retains the session:
+
+~~~rust
+ let session = app.state::().session_id().to_string();
+ let path = if event == 4 {
+ format!("/?desktop=open&desktop_session={session}#/usage/companion")
+ } else {
+ format!("/?desktop=open&desktop_session={session}#/usage")
+ };
+ if let Ok(url) = proxy.endpoint().url(&path).parse() {
+ let _ = main.navigate(url);
+ window::show(&main);
+ }
+~~~
+
+MODIFY app/Sources/NativeTray/Popover.swift:1-68. Insert this complete NSView implementation after the NativeTrayPopover class, before its existing @_cdecl exports:
+
+~~~swift
+@MainActor
+private final class UpdateDotView: NSView {
+ weak var statusButton: NSStatusBarButton?
+
+ init(button: NSStatusBarButton) {
+ statusButton = button
+ super.init(frame: button.bounds)
+ autoresizingMask = [.width, .height]
+ // AppKit keeps the template image and its highlighted tint. This view draws only
+ // the independent accent, without making the status button layer-backed.
+ wantsLayer = false
+ }
+
+ required init?(coder: NSCoder) { nil }
+ override var isOpaque: Bool { false }
+ override func hitTest(_ point: NSPoint) -> NSView? { nil }
+
+ override func layout() {
+ super.layout()
+ needsDisplay = true
+ }
+
+ override func draw(_ dirtyRect: NSRect) {
+ guard let button = statusButton else { return }
+ let imageRect = button.cell?.imageRect(forBounds: button.bounds) ?? button.bounds
+ let image = imageRect.isEmpty ? button.bounds : imageRect
+ let diameter: CGFloat = 7
+ let dot = NSRect(x: min(bounds.maxX - diameter, image.maxX - 4),
+ y: max(bounds.minY, image.minY + 1),
+ width: diameter, height: diameter)
+ NSColor.windowBackgroundColor.setFill()
+ NSBezierPath(ovalIn: dot.insetBy(dx: -1.25, dy: -1.25)).fill()
+ NSColor(calibratedRed: 0.18, green: 0.48, blue: 0.97, alpha: 1).setFill()
+ NSBezierPath(ovalIn: dot).fill()
+ }
+}
+
+@MainActor
+private enum UpdateDot {
+ static weak var button: NSStatusBarButton?
+ static var view: UpdateDotView?
+
+ static func set(_ item: NSStatusItem, visible: Bool) {
+ guard let next = item.button else { return }
+ if button !== next {
+ view?.removeFromSuperview()
+ view = nil
+ button = next
+ }
+ guard visible else {
+ view?.removeFromSuperview()
+ view = nil
+ return
+ }
+ if view == nil {
+ let overlay = UpdateDotView(button: next)
+ next.addSubview(overlay)
+ view = overlay
+ }
+ view?.frame = next.bounds
+ view?.needsDisplay = true
+ }
+}
+
+@_cdecl("ocx_native_tray_update_dot")
+@MainActor
+public func nativeTrayUpdateDot(_ item: UnsafeMutableRawPointer?, _ show: Int32) {
+ guard Thread.isMainThread, let item else { return }
+ let statusItem = Unmanaged.fromOpaque(item).takeUnretainedValue()
+ UpdateDot.set(statusItem, visible: show != 0)
+}
+~~~
+
+This uses the status button's imageRect, not the window theme. A title change calls the bridge again below; autoresizing/layout tracks button bounds. hitTest returning nil preserves status-button clicks and right-click menus. The overlay remains blue when AppKit highlights the template glyph; clearing removes the child view. A recreated status item replaces the weak button/view pair. The 7 pt dot and 1.25 pt halo are visual-QA values, not an API contract.
+
+MODIFY desktop/src-tauri/src/tray.rs:20-39: add update_pending: AtomicBool to TrayState and initialize it false. Add this exact helper after Default:
+
+~~~rust
+#[cfg(any(not(target_os = "macos"), test))]
+fn tray_icon_bytes(pending: bool) -> &'static [u8] {
+ if pending { include_bytes!("../icons/tray/icon-update.png") }
+ else { include_bytes!("../icons/tray/icon.png") }
+}
+
+fn apply_update_indicator(app: &AppHandle, pending: bool) {
+ #[cfg(target_os = "macos")]
+ popup::set_update_dot(app, pending);
+ #[cfg(not(target_os = "macos"))]
+ if let Some(tray) = app.tray_by_id("main") {
+ let image = tauri::image::Image::from_bytes(tray_icon_bytes(pending))
+ .expect("generated tray icon");
+ let _ = tray.set_icon(Some(image));
+ }
+}
+
+fn update_pending(app: &AppHandle) -> bool {
+ app.try_state::()
+ .is_some_and(|state| state.update_pending.load(Ordering::Acquire))
+}
+~~~
+
+For show_update_available() at tray.rs:284-291, after its existing menu block insert only the setter-side redraw; `check_and_show` owns the atomic model write under `CheckGeneration`:
+
+~~~rust
+ apply_update_indicator(app, true);
+~~~
+
+For show_up_to_date() at :293-301, after its existing menu block insert:
+
+~~~rust
+ apply_update_indicator(app, false);
+~~~
+
+In TrayState at :20-39 add the exact field and Default initializer:
+
+~~~rust
+pub update_pending: AtomicBool,
+// inside Default Self
+update_pending: AtomicBool::new(false),
+~~~
+
+Keep it true through set_installing() at :308-319 and set_install_failed() at :321-325; additionally publish updater phase at those two functions. In commit 3, move these phase writes into gate-owned pure transitions and leave the renamed `show_installing` as a setter-only function called by `start_ui_projection_worker`:
+
+~~~rust
+// At end of set_installing:
+app.state::().retain_phase("installing");
+// At end of set_install_failed:
+app.state::().retain_phase("install-failed");
+~~~
+
+Change both refresh_title call sites at tray.rs:244,261 to refresh_title(app, &tray, &proxy), and replace the function signature/body at :328-341 with:
+
+~~~rust
+fn refresh_title(app: &AppHandle, tray: &tauri::tray::TrayIcon, proxy: &ProxyClient) {
+ let app = app.clone();
+ let proxy = proxy.clone();
+ let tray = tray.clone();
+ tauri::async_runtime::spawn(async move {
+ let Ok(settings) = proxy.companion_settings().await else { return; };
+ let Ok(usage) = proxy.usage_today().await else { return; };
+ let quotas = proxy.quotas().await.unwrap_or(Value::Null);
+ let title = render_title(&settings, &usage, "as);
+ let _ = tray.set_title(title.as_deref());
+ #[cfg(target_os = "macos")]
+ apply_update_indicator(&app, update_pending(&app));
+ });
+}
+~~~
+
+Before this redraw edit, `apply_update_indicator(&app, update_pending(&app));` ran unconditionally after `tray.set_title`. The after-body above wraps that call in `#[cfg(target_os = "macos")]`: it repositions only the Swift dot against the image whenever the title changes. Windows/Linux do not call set_icon on the minute title refresh. Also insert apply_update_indicator(app, update_pending(app)); after tray construction at tray.rs:231 so late tray registration paints a pending state. Neither title refresh nor tray construction reads `CheckGeneration`, and neither holds its mutex across an AppKit call. On Windows/Linux set_icon only swaps RGBA PNGs at actual pending-state transitions or initial tray construction; the base glyph remains the existing 44 px image and is not redesigned.
+
+MODIFY desktop/scripts/generate-icons.ts:62-145. Add next to TRAY_OUTPUT/TRAY_SIZE:
+
+~~~ts
+const DOTTED_TRAY_OUTPUT = "tray/icon-update.png";
+const DOTTED_TRAY_SVG = '(badgeUrl, signal),
+ { pollMs: isDesktopShell() ? 60_000 : BADGE_POLL_MS },
+ );
+~~~
+
+Widen the local UpdateBadge.installer union to include "desktop" at sidebar-github-row.tsx:23-30. No new visible copy or i18n key is introduced here. Commit 3 routes the two desktop click actions to the app-origin update page; until then this commit only changes the signal. Keep normal-browser /api/update/badge unchanged.
+
+## Tests and exact additions
+
+NEW tests/update/update-desktop-badge.test.ts — full content:
+
+~~~ts
+import { describe, expect, test } from "bun:test";
+import {
+ DESKTOP_SNAPSHOT_MAX_SESSIONS,
+ DESKTOP_SNAPSHOT_TTL_MS,
+ DesktopBadgeStore,
+ parseDesktopSnapshot,
+} from "../../src/update/desktop-badge";
+
+const A = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+const B = "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb";
+const WALL_MS = 1_700_000_000_000;
+const snapshot = (sessionId: string) => ({
+ sessionId, currentVersion: "2.61.0", latestVersion: "2.62.0",
+ available: true, checkedAtMs: WALL_MS, phase: "available",
+});
+
+describe("desktop badge snapshot store", () => {
+ test("rejects extra fields, malformed values and forged availability", () => {
+ expect(parseDesktopSnapshot({ ...snapshot(A), token: "unwanted" }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), sessionId: "short" }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), currentVersion: "x".repeat(65) }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), latestVersion: null }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), phase: "installed" }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), checkedAtMs: WALL_MS + 60_001 }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), checkedAtMs: 946_684_799_999 }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), phase: "current" }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot({ ...snapshot(A), phase: "installing", available: false, latestVersion: null }, WALL_MS)).toBeNull();
+ expect(parseDesktopSnapshot(snapshot(A), WALL_MS)).not.toBeNull();
+ });
+
+ test("an absent session is unknown desktop state, never package state", () => {
+ const store = new DesktopBadgeStore(() => WALL_MS, () => 1_000);
+ expect(store.read(A)).toMatchObject({
+ installer: "desktop", unknown: true, updateAvailable: false,
+ latestVersion: null, currentVersion: "?",
+ });
+ expect(store.read(null).unknown).toBe(true);
+ });
+
+ test("two desktop sessions do not see one another", () => {
+ let now = 1_000;
+ const store = new DesktopBadgeStore(() => WALL_MS, () => now);
+ expect(store.put(snapshot(A))).toBe(true);
+ expect(store.read(A).updateAvailable).toBe(true);
+ expect(store.read(B).unknown).toBe(true);
+ now += 1_000;
+ expect(store.put({
+ ...snapshot(B), latestVersion: null, available: false,
+ phase: "current", checkedAtMs: WALL_MS,
+ })).toBe(true);
+ expect(store.read(A).updateAvailable).toBe(true);
+ expect(store.read(B)).toMatchObject({
+ installer: "desktop", updateAvailable: false, unknown: false,
+ });
+ });
+
+ test("a failed check is unknown without pending state but retains a known update", () => {
+ const store = new DesktopBadgeStore(() => WALL_MS, () => 1_000);
+ expect(store.put({
+ ...snapshot(A), latestVersion: null, available: false,
+ checkedAtMs: null, phase: "error",
+ })).toBe(true);
+ expect(store.read(A)).toMatchObject({ unknown: true, updateAvailable: false });
+ expect(store.put({ ...snapshot(A), phase: "error" })).toBe(true);
+ expect(store.read(A)).toMatchObject({ unknown: false, updateAvailable: true });
+ });
+
+ test("a heartbeat extends receipt expiry and stale state disappears", () => {
+ let now = 1_000;
+ const store = new DesktopBadgeStore(() => WALL_MS, () => now);
+ expect(store.put(snapshot(A))).toBe(true);
+ now += 60_000;
+ expect(store.put(snapshot(A))).toBe(true);
+ now += DESKTOP_SNAPSHOT_TTL_MS - 1;
+ expect(store.read(A).updateAvailable).toBe(true);
+ now += 1;
+ expect(store.read(A).unknown).toBe(true);
+ });
+
+ test("a 25-hour-old check remains visible while heartbeats renew receipt", () => {
+ let received = 1_000;
+ const store = new DesktopBadgeStore(() => WALL_MS + 25 * 60 * 60_000, () => received);
+ expect(store.put(snapshot(A))).toBe(true);
+ received += 60_000;
+ expect(store.put({ ...snapshot(A), phase: "error" })).toBe(true);
+ expect(store.read(A)).toMatchObject({ updateAvailable: true, unknown: false });
+ received += DESKTOP_SNAPSHOT_TTL_MS - 1;
+ expect(store.read(A).updateAvailable).toBe(true);
+ received += 1;
+ expect(store.read(A)).toMatchObject({ updateAvailable: false, unknown: true });
+ });
+
+ test("new sessions evict the oldest after the fixed entry limit", () => {
+ const store = new DesktopBadgeStore(() => WALL_MS, () => 1_000);
+ expect(store.put(snapshot(A))).toBe(true);
+ for (let index = 0; index < DESKTOP_SNAPSHOT_MAX_SESSIONS; index++) {
+ const id = "00000000-0000-4000-8000-" + index.toString(16).padStart(12, "0");
+ expect(store.put(snapshot(id))).toBe(true);
+ }
+ expect(store.read(A).unknown).toBe(true);
+ expect(store.read("00000000-0000-4000-8000-00000000001f").updateAvailable).toBe(true);
+ });
+});
+~~~
+
+MODIFY tests/server/sidebar-routes.test.ts:23-38. Keep its existing `call()` helper and add the following helper immediately after its closing brace at line 38, before `withStarDeps()`. Direct dispatch already models principal selection (lines 23-38); no real admin token is put into fixtures.
+
+~~~ts
+const DESKTOP_A = "cccccccc-cccc-4ccc-8ccc-cccccccccccc";
+const DESKTOP_B = "dddddddd-dddd-4ddd-8ddd-dddddddddddd";
+const desktopPayload = (sessionId = DESKTOP_A) => ({
+ sessionId, currentVersion: "2.61.0", latestVersion: "2.62.0",
+ available: true, checkedAtMs: Date.now(), phase: "available",
+});
+
+async function desktopPost(body: string | Uint8Array, principal?: "admin-token" | "gui-session",
+ contentType = "application/json") {
+ const url = new URL("http://127.0.0.1:10100/api/update/desktop-snapshot");
+ const req = new Request(url, {
+ method: "POST",
+ headers: { host: "127.0.0.1:10100", "content-type": contentType },
+ body,
+ });
+ const response = await handleManagementAPI(req, url, config, {}, principal);
+ expect(response).not.toBeNull();
+ return { status: response!.status, body: await response!.json() as Record };
+}
+~~~
+
+Add after the existing GET badge describe, which now includes commit 1's read-only cache test and closes at sidebar-routes.test.ts:139; insert before the `GET /api/github/star` describe at line 141:
+
+~~~ts
+describe("desktop snapshot route", () => {
+ test("requires the raw admin-token principal, not a GUI session or missing principal", async () => {
+ const body = JSON.stringify(desktopPayload());
+ expect((await desktopPost(body)).status).toBe(403);
+ expect((await desktopPost(body, "gui-session")).status).toBe(403);
+ expect((await desktopPost(body, "admin-token")).status).toBe(200);
+ });
+
+ test("rejects extra fields, malformed JSON and over-1KiB streams without echoing input", async () => {
+ expect((await desktopPost(JSON.stringify({ ...desktopPayload(), token: "sentinel" }), "admin-token")).status).toBe(400);
+ expect((await desktopPost("{", "admin-token")).status).toBe(400);
+ expect((await desktopPost("", "admin-token")).status).toBe(400);
+ expect((await desktopPost(new Uint8Array([0xff]), "admin-token")).status).toBe(400);
+ expect((await desktopPost(JSON.stringify(desktopPayload()), "admin-token", "text/plain")).status).toBe(400);
+ const oversized = await desktopPost("x".repeat(1025), "admin-token");
+ expect(oversized.status).toBe(413);
+ expect(JSON.stringify(oversized.body)).not.toContain("x".repeat(32));
+ });
+
+ test("desktop GET isolates sessions and never reads the package badge for an absent session", async () => {
+ expect((await desktopPost(JSON.stringify(desktopPayload()), "admin-token")).status).toBe(200);
+ const seen = await call("GET", "/api/update/badge?surface=desktop&session=" + DESKTOP_A);
+ expect(seen.body).toMatchObject({ installer: "desktop", updateAvailable: true, unknown: false });
+ expect(seen.raw).not.toContain(DESKTOP_A);
+ const other = await call("GET", "/api/update/badge?surface=desktop&session=" + DESKTOP_B);
+ expect(other.body).toMatchObject({ installer: "desktop", updateAvailable: false, unknown: true });
+ const missing = await call("GET", "/api/update/badge?surface=desktop");
+ expect(missing.body).toMatchObject({ installer: "desktop", unknown: true });
+ expect((await call("GET", "/api/update/badge")).body).not.toMatchObject({ installer: "desktop" });
+ expect((await call("GET", "/api/update/badge?surface=typo")).status).toBe(400);
+ });
+});
+~~~
+
+MODIFY tests/server/management-route-registry.test.ts:214-260: add this test inside the exemption describe:
+
+~~~ts
+ test("desktop snapshot is declared as a bounded internal shell mutation", () => {
+ const row = MANAGEMENT_ROUTES.find(r =>
+ r.method === "POST" && r.path === "/api/update/desktop-snapshot");
+ expect(row).toMatchObject({
+ module: "server/management/sidebar-routes", mutates: true,
+ exempt: { reason: "desktop-internal" },
+ });
+ });
+~~~
+
+MODIFY tests/cli/cli-capabilities.test.ts:342-371: add inside the capability/route parity describe:
+
+~~~ts
+ test("desktop snapshot has an explicit internal exemption, not an operator CLI verb", async () => {
+ const { MANAGEMENT_ROUTES } = await import("../../src/server/management/route-registry");
+ const row = MANAGEMENT_ROUTES.find(r => r.method === "POST"
+ && r.path === "/api/update/desktop-snapshot");
+ expect(row?.exempt?.reason).toBe("desktop-internal");
+ expect(capabilityRouteKeys().has("POST /api/update/desktop-snapshot")).toBe(false);
+ });
+~~~
+
+MODIFY tests/ci-workflows/build-desktop-icon-set.test.ts:175-251: add next to the menu bar size test. repoPath is already imported at :4-5; this test follows its source-oracle convention and requires no image renderer in CI.
+
+~~~ts
+ test("the generated dotted tray variant has the declared size and SVG halo", () => {
+ const generator = generatorSource();
+ expect(generator).toContain('const DOTTED_TRAY_OUTPUT = "tray/icon-update.png"');
+ expect(generator).toContain('renderDottedTray(target);');
+ expect(generator).toContain('produced.push(DOTTED_TRAY_OUTPUT);');
+ expect(generator).toContain('fill="#ffffff"');
+ expect(generator).toContain('fill="#2f81f7"');
+ const normal = readFileSync(join(ICONS_DIR, "tray", "icon.png"));
+ const dotted = readFileSync(join(ICONS_DIR, "tray", "icon-update.png"));
+ expect(pngDimensions(dotted)).toEqual({ width: 44, height: 44 });
+ expect(dotted[25]).toBe(RGBA);
+ expect(dotted.equals(normal)).toBe(false);
+ });
+~~~
+
+MODIFY gui/tests/desktop-shell.test.ts:1-37: import desktopSession and updateBadgeUrl from ../src/lib/desktop-shell; add:
+
+~~~ts
+ test("desktop session selects its badge, ordinary browser keeps package badge", () => {
+ const id = "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa";
+ expect(desktopSession("?desktop_session=" + id)).toBe(id);
+ expect(desktopSession("?desktop_session=not-a-uuid")).toBeNull();
+ expect(updateBadgeUrl("", tauriMac, "?desktop_session=" + id))
+ .toBe("/api/update/badge?surface=desktop&session=" + id);
+ expect(updateBadgeUrl("", tauriMac, ""))
+ .toBe("/api/update/badge?surface=desktop");
+ expect(updateBadgeUrl("", "Mozilla/5.0 Chrome/140.0", "?desktop_session=" + id))
+ .toBe("/api/update/badge");
+ });
+~~~
+
+MODIFY desktop/src-tauri/src/updater.rs:116-144: inside the existing tests module import `CheckGeneration` and `DesktopUpdateState`, plus `std::sync::atomic::AtomicBool`, and add:
+
+~~~rust
+ #[test]
+ fn desktop_snapshot_serializes_the_bounded_wire_fields() {
+ let state = DesktopUpdateState::new("2.61.0".into());
+ // A realistic epoch-millisecond value: the proxy parser rejects checkedAtMs before 2000-01-01.
+ state.publish("available", Some("2.62.0".into()), Some(1_790_000_000_000));
+ let value = serde_json::to_value(state.tx.borrow().clone()).unwrap();
+ assert!(uuid::Uuid::parse_str(state.session_id()).is_ok());
+ assert_eq!(value["sessionId"], state.session_id());
+ assert_eq!(value["currentVersion"], "2.61.0");
+ assert_eq!(value["latestVersion"], "2.62.0");
+ assert_eq!(value["available"], true);
+ assert_eq!(value["checkedAtMs"], 1_790_000_000_000u64);
+ assert!(value["checkedAtMs"].as_u64().unwrap() >= 946_684_800_000); // same lower bound as the proxy parser
+ assert_eq!(value["phase"], "available");
+ assert_eq!(value.as_object().unwrap().len(), 6);
+ }
+
+ #[test]
+ fn a_delayed_older_none_cannot_clear_a_newer_pending_update() {
+ let checks = CheckGeneration::default();
+ let installing = AtomicBool::new(false);
+ let (older, _) = checks.begin_if_not_installing(&installing, || {}).unwrap();
+ let (newer, _) = checks.begin_if_not_installing(&installing, || {}).unwrap();
+ let mut pending: Option<&str> = None;
+ let mut phase = "checking";
+ assert_eq!(checks.apply_if_current(newer, || {
+ pending = Some("2.62.0");
+ phase = "available";
+ }), Some(()));
+ // The first lookup completes after the second one; model its Ok(None) transition.
+ assert_eq!(checks.apply_if_current(older, || {
+ pending = None;
+ phase = "current";
+ }), None);
+ assert_eq!(pending, Some("2.62.0"));
+ assert_eq!(phase, "available");
+ let (third, _) = checks.begin_if_not_installing(&installing, || {}).unwrap();
+ assert_eq!(checks.apply_if_current(newer, || { pending = None; }), None);
+ assert_eq!(pending, Some("2.62.0"));
+ assert_eq!(checks.apply_if_current(third, || { pending = None; }), Some(()));
+ assert_eq!(pending, None);
+ }
+
+ #[test]
+ fn checking_publication_rechecks_install_claim_inside_the_gate() {
+ let checks = CheckGeneration::default();
+ let installing = AtomicBool::new(false);
+ assert!(checks.claim_install(&installing));
+ let mut published = false;
+ assert_eq!(checks.begin_if_not_installing(&installing, || { published = true; }), None);
+ assert!(!published);
+ }
+~~~
+
+MODIFY desktop/src-tauri/src/tray.rs:496-623: inside its existing tests module import tray_icon_bytes and add:
+
+~~~rust
+ #[test]
+ fn dotted_tray_variant_is_distinct_and_both_variants_are_png() {
+ let normal = tray_icon_bytes(false);
+ let dotted = tray_icon_bytes(true);
+ assert_eq!(&normal[..8], b"\x89PNG\r\n\x1a\n");
+ assert_eq!(&dotted[..8], b"\x89PNG\r\n\x1a\n");
+ assert_ne!(normal, dotted);
+ }
+~~~
+
+All three proposed Rust tests are pure and run on this Mac. The Windows/Linux set_icon path still needs hosted builds and human visual review at 16/20/24/32 px. The Swift overlay needs local highlighted, dark/light, title-width and 1×/2× QA; no unit assertion proves its final pixels.
+
+MODIFY scripts/test-layout/layout.json explicit object, alphabetical insertion between update-bun-ownership-lease and update-desktop-owner (layout.json:1655-1659):
+
+~~~json
+ "update-bun-ownership-lease.test.ts": "update",
+ "update-desktop-badge.test.ts": "update",
+ "update-desktop-owner.test.ts": "update",
+~~~
+
+MODIFY tests/fixtures/test-layout-expected.json similarly at :1481-1485:
+
+~~~json
+ "update-bun-ownership-lease.test.ts": "update",
+ "update-desktop-badge.test.ts": "update",
+ "update-desktop-owner.test.ts": "update",
+~~~
+
+The existing tests/test-layout-tooling.test.ts:248-250 asserts equality of both explicit maps. The new test imports source relatively as existing tests/update files do; any source-oracle path used by these additions goes through tests/helpers/repo-root.ts, as in the icon test.
+
+## Field/value chains — PLAN-FIELD-CHAIN-01
+
+| New value | Creation | Serialization | Deserialization | Consumers |
+| --- | --- | --- | --- | --- |
+| DesktopSnapshot.sessionId | UUID v4 at desktop/src-tauri/src/updater.rs DesktopUpdateState::new; one id per app process | serde_json in publisher, POST JSON via desktop/src-tauri/src/proxy.rs | strict UUID validation in src/update/desktop-badge.ts parseDesktopSnapshot | Map key there; embedded URL from desktop/src-tauri/src/startup.rs; gui/src/lib/desktop-shell.ts query; sidebar GET. No persistence. Never included in GET body. |
+| currentVersion | app.package_info().version in desktop/src-tauri/src/lib.rs | Same POST | 64-character version validation in src/update/desktop-badge.ts | Desktop GET currentVersion and channel (defaultUpdateTag); GUI's existing badge DTO. |
+| latestVersion | signed Tauri Update.version at desktop/src-tauri/src/updater.rs:100-104, or null on no update | Same POST | nullable validated version in src/update/desktop-badge.ts | Desktop GET latestVersion; gui/src/components/sidebar-github-row.tsx:89,138-140 label/dot; tray menu uses existing updater::update_label. |
+| available | Derived solely from latestVersion in DesktopUpdateState::publish | Same POST | strict boolean and equivalence validation in desktop-badge.ts | Desktop GET updateAvailable; GUI orb and tray indicator. It grants no install authority. |
+| checkedAtMs | now_ms() after an accepted settled Tauri check, null before first check | Same POST | finite safe integer, at or after 2000-01-01 UTC, no future over 60 s; no relative-age expiry | Stored for validation and future page status; not echoed by GET. A 25-hour-old check remains visible when heartbeat receipt is fresh. |
+| phase enum idle/checking/available/current/error/installing/install-failed | updater.rs constructor, check_and_show(), tray.rs installing/failure arms | String in serde JSON POST | fixed set in desktop-badge.ts | Badge unknown for idle or error without pending; available remains true through checking/error/install; future commit-3 page may read native state, not this HTTP enum. N/A in GET because no phase field is exposed. |
+| native check generation, install epoch, UI revision | CheckGeneration::begin_if_not_installing before each check() await; claim_install increments epoch and invalidates queued UI; accepted model transitions increment latest_ui_revision | Process-local atomics and in-memory watch projection; no wire representation | apply_if_current and claim_install share one mutex; inspect reads page status under it; one worker rechecks revision without taking that mutex | Only the latest-started check can change PendingUpdate, update_pending, or DesktopUpdateState; an install claim cannot interleave with model writes. Blocking Tauri setters run later on the serialized worker, so a superseded projection cannot be the final UI. |
+| receipt time and Map entry | performance.now at desktop-badge.ts put; wall Date.now is used only for checkedAt validation | N/A; process memory only | N/A | monotonic prune on GET/POST; expires at 180 s even if wall clock moves; oldest eviction at 32; no disk/cache/CLI consumer. |
+| surface=desktop and session query | URL from gui/src/lib/desktop-shell.ts only in Tauri UA; native Rust main URL carries desktop_session | HTTP GET query | sidebar-routes.ts URLSearchParams; validDesktopSession in store | desktop projection only; ordinary GET remains package badge; missing session yields unknown desktop. |
+| installer="desktop" | src/update/desktop-badge.ts read | jsonResponse in sidebar-routes.ts | gui/src/components/sidebar-github-row.tsx UpdateBadge union | Commit-3 desktop click routing is the next consumer. The value is never passed to src/update/job.ts. |
+| desktop-internal exemption | src/server/management/route-registry.ts declaration | N/A, static registry data | tests/server/management-route-registry.test.ts and tests/cli/cli-capabilities.test.ts import | Explains why no CLI capability maps the snapshot POST. |
+| macOS dot state | TrayState.update_pending at desktop/src-tauri/src/tray.rs | i32 over native_tray.rs @_cdecl ABI | app/Sources/NativeTray/Popover.swift: nativeTrayUpdateDot | NSView child of current NSStatusBarButton; N/A to HTTP. |
+| Windows/Linux dotted icon | desktop/scripts/generate-icons.ts SVG source composition | PNG at desktop/src-tauri/icons/tray/icon-update.png | tauri::image::Image::from_bytes in tray.rs | set_icon on available tray, normal PNG when cleared; Linux no host means no icon consumer. |
+
+No new GUI i18n catalog key: the orb and its existing aria label remain at gui/src/components/sidebar-github-row.tsx:137-159. All ten gui/src/i18n/{en,de,fr,ja,ko,ru,tr,vi,zh,zh-TW}.ts files remain unchanged in this commit; commit 3 owns update-page copy.
+
+## Conditional paths — C-ACTIVATION-GROUNDING-01
+
+| Guard / fallback / timeout / error | Test activation | Observable effect |
+| --- | --- | --- |
+| Raw admin-token principal only | sidebar-routes test posts identical valid JSON with undefined, gui-session, admin-token | 403/403/200; no store write until third call. Management-auth.ts:557-561 supplies principals at real ingress. |
+| Wrong Content-Type, malformed/extra JSON, version, UUID, phase, availability relation, future/pre-2000 check time | POST test includes text/plain and malformed JSON; parseDesktopSnapshot unit covers the schema and timestamp bounds | Fixed 400, no input echo, no update to previous valid snapshot. |
+| >1024 body with and without Content-Length | Route test's 1025-byte Request stream plus a declared length request in an ingress fixture | 413 before storage; stream cancel on overrun. Existing 2 MiB management cap is independent. |
+| No body / stream read failure / invalid UTF-8 | POST with empty body and Uint8Array invalid UTF-8; an aborting stream in a direct-dispatch route test at B | Fixed 400, never log parser text. |
+| Unknown surface | GET surface=typo | 400, no package fallback. |
+| Missing/malformed/foreign session | GET desktop without session, invalid UUID, and B while A is stored | Desktop installer, unknown true, updateAvailable false; package cache not read. |
+| Initial shell before bind; bind failure or later proxy replacement | Publisher starts before AppState has a proxy; failed ProxyClient identity; startup finish wake after valid bind | No token/body sent to foreign endpoint; first successful bound send after wake; 60 s retry after transient failure. ProxyClient's existing 4 s timeout bounds each attempt. |
+| Two checks settle in reverse order | Rust CheckGeneration state-transition test begins old then new, applies new Some, then attempts old None, followed by a third generation | Old None is rejected and leaves newer pending/phase intact; only the latest-started result changes native state. The separate serial publisher then sends that state in order. |
+| Check projection waits on an AppKit setter while status is read | Commit-3 Rust `status_read_completes_while_check_ui_setter_is_blocked`: fake setter waits for concurrent `inspect` result | Status read completes before setter release because the gate protects only pure model writes and projection enqueue; the serialized worker never holds it across Tauri setters. |
+| Check while installing | Rust `checking_publication_rechecks_install_claim_inside_the_gate` claims first, then tries `begin_if_not_installing` | No `"checking"` publication; pending state/dot stays. |
+| Failed update check with/without prior pending | Inject failed updater result in a focused Rust state test; unit store reads error with/without latest | Prior pending stays visible; no pending reports unknown. Existing fixed-context log remains. |
+| Install failed after PendingUpdate was taken | Existing tray.rs:198-222 failure arm with updater::install error | Pending restored, menu re-enabled, dot stays, phase install-failed. Signed download/install sequence unchanged. |
+| Snapshot TTL, heartbeat, bounded entries | New Bun store tests advance fake monotonic clock 60 s / 180 s and insert 33 sessions; the 25-hour-old checkedAtMs test re-POSTs an error phase with pending state | A fresh receipt keeps an old but still-pending check visible; after 180 s without receipt it becomes unknown; oldest entry is evicted. |
+| Minute title refresh on Windows/Linux | Review the cfg(target_os = "macos") line and platform build; title-refresh smoke on Windows/Linux | No set_icon call from title refresh; set_icon remains for pending transitions and first tray construction. |
+| macOS status item absent/recreated; title width; highlight | Native visual QA: check before tray exists, change title, recreate status item, open menu | No crash if absent; child moves relative to image and stays blue while glyph template tint changes; clear removes it. |
+| Windows/Linux tray host absent or set_icon failure | Linux session without AppIndicator; platform smoke with failing icon setter | No claimed tray signal, GUI badge still works; setter error cannot affect updater check. |
+| Desktop UA without valid URL nonce | GUI helper test | Requests surface=desktop with no session and sees unknown; ordinary browser keeps package URL. |
+
+## Structure and public documentation edits
+
+The source ownership table in structure/INDEX.md:154 maps src/update/ to *both* structure/runtime.md and structure/ops/service-and-sidecars.md. This corrects the shorter commit-2 doc list in 000_plan.md; it does not change a decision D1-D3. structure/manifest.json:3 caps each structure page at 600 lines. structure/runtime.md is exactly 600/600 now, so replace one existing line in place and do not append. No new structure document or manifest entry is necessary. The other source-area owners listed in structure/INDEX.md:118-154 were reviewed for consequences; their existing transport/adapter contracts do not change.
+
+MODIFY structure/runtime.md:159, exact one-line replacement. Preserve commit 1's package-refresh link and add the desktop state contract on the same line (600/600 stays 600/600). Current before:
+
+~~~md
+| Support | `src/lib/`, `src/storage/`, `src/usage/`, `src/update/` ([package refresh](ops/service-and-sidecars.md#package-cache-refresh)), `src/generated/` |
+~~~
+
+After:
+
+~~~md
+| Support | `src/lib/`, `src/storage/`, `src/usage/`, `src/update/` ([package refresh](ops/service-and-sidecars.md#package-cache-refresh); `desktop-badge.ts` holds bounded process-local display state, never install authority), `src/generated/` |
+~~~
+
+MODIFY structure/ops/service-and-sidecars.md:250-254, append the paragraph after the existing Package cache refresh text at line 254. That heading and its commit-1 scheduler/async-check paragraphs remain intact:
+
+~~~md
+The desktop badge snapshot in src/update/desktop-badge.ts is process-local display state keyed by a Tauri session id. A 60-second shell heartbeat renews receipt time; entries expire after 180 seconds and the store retains at most 32 sessions. It is separate from the package version cache and from the updater job/ownership transaction. A proxy restart reports unknown until a bound desktop shell republishes; no update installation can be authorized by this snapshot.
+~~~
+
+MODIFY structure/desktop-shell.md:149-164, insert after the existing in-app update paragraph:
+
+~~~md
+The Tauri updater also publishes a bounded desktop snapshot over its identity-bound ProxyClient. A random process-session id travels in the embedded dashboard URL, and the dashboard requests GET /api/update/badge?surface=desktop&session=. A normal browser keeps the package badge. The shell posts each updater-state change and a 60-second heartbeat; if the proxy loses the snapshot or the shell stops, the desktop badge becomes unknown after 180 seconds. This display path never installs an update or replaces the signed Tauri result. The tray shows the same pending state: macOS draws a blue child NSView dot over the template status-item image; Windows/Linux swap a generated dotted PNG when a tray host exists. The Windows base glyph is unchanged.
+~~~
+
+MODIFY structure/companion.md:50-56, insert after the Tauri title paragraph:
+
+~~~md
+The update dot is independent of companion usage and title filtering. A title refresh asks the macOS status-button overlay to redraw against the current image rectangle; update availability still comes only from the Tauri updater state in desktop/src-tauri/src/updater.rs.
+~~~
+
+MODIFY structure/gui-and-management-api.md:168 and :195. Keep the current Updates row's asynchronous check/run and 40-hour package-cache sentences verbatim. Replace only its final sentence `The badge links to the update surface rather than gating other actions.` with the three-sentence text below, keeping it in the same table row; replace the complete current Sidebar row (`GET/POST /api/github/star` and `GET /api/update/badge`; cosmetic failure) with the second block:
+
+~~~md
+The badge links to the update surface rather than gating other actions. `GET /api/update/badge?surface=desktop&session=` projects only that process-local Tauri session; missing or expired state is unknown and never falls back to the package cache. `POST /api/update/desktop-snapshot` is a 1 KiB bounded, admin-token-principal-only display-state mutation with no install permission.
+
+| Sidebar | `src/server/management/sidebar-routes.ts` — `GET/POST /api/github/star`, `GET /api/update/badge`, and `POST /api/update/desktop-snapshot`. The POST accepts only the raw admin-token principal; GUI sessions cannot publish desktop state. Badge state is cosmetic and a failed poll degrades silently. |
+~~~
+
+MODIFY docs-site/src/content/docs/reference/management-api.md:547. Exact current before:
+
+~~~md
+| `GET /api/update/badge` | Read cached package badge state without a registry lookup; missing, wrong-channel or 40-hour-old cache returns `unknown: true`. | — |
+~~~
+
+Replace that row with these exact two rows. Put the desktop paragraph after the table and before the existing automatic-check paragraph at line 549; preserve that paragraph and the async check/run rows at lines 268-269:
+
+~~~md
+| `GET /api/update/badge` | Read cached package badge without a registry lookup; missing, wrong-channel or 40-hour-old cache returns `unknown: true`. `surface=desktop&session=` reads only that desktop app session. | 400 invalid surface; missing or expired desktop session returns `unknown: true` |
+| `POST /api/update/desktop-snapshot` | Desktop shell publishes its Tauri-updater display state through the bound proxy client | 403 unless the raw `admin-token` principal; 400 invalid fields; 413 over 1 KiB |
+
+The desktop snapshot is temporary display state, not an install request. The proxy stores at most 32 sessions in memory and expires one 180 seconds after its last heartbeat. A normal browser without surface=desktop continues to read the package badge.
+~~~
+
+MODIFY docs-site/src/content/docs/guides/desktop-app.md: its existing "## Updates" section (currently below the tray usage section). Insert these exact sentences after the check cadence sentence:
+
+~~~md
+When the Tauri updater finds a newer app version, a blue dot appears on the macOS menu-bar icon or the Windows/Linux tray icon where a tray host is available. The embedded dashboard shows the same desktop update signal. A normal browser connected to the same proxy still shows the proxy package update state. If the shell stops reporting for about three minutes, the embedded badge becomes unknown until it reconnects. The dot reports availability; installation remains an explicit action.
+~~~
+
+MODIFY the existing sibling pages at:
+
+- docs-site/src/content/docs/{fr,ja,ko,ru,tr,zh-cn,zh-tw}/reference/management-api.md
+- docs-site/src/content/docs/{fr,ja,ko,ru,tr,zh-cn,zh-tw}/guides/desktop-app.md
+
+For each management API sibling, replace its existing commit-1 GET /api/update/badge row (which already says missing, wrong-channel or 40-hour-old cache returns `unknown: true`) with translations of the two English rows above. Add the 32-session/180-second paragraph after the table but before the existing translated automatic-check paragraph; preserve each sibling's async check/run rows. Keep literal route paths, surface=desktop, session=, status numbers, admin-token, unknown and 1 KiB unchanged. For each desktop guide sibling, insert a translation of the five English sentences above in its existing Updates section. Say explicitly that Linux shows a dot only with a tray host, an ordinary browser sees package state, expiry yields unknown, and installation is explicit. Do not claim the commit-3 update page exists yet. These seven locales are the exact existing siblings found in docs-site/src/content/docs; there are no de/vi guide siblings. English remains the source of truth.
+
+No GUI i18n catalog edits: no new visible string is introduced in commit 2. The existing sidebar.updateAvailable and sidebar.checkUpdate keys already cover the label (gui/src/components/sidebar-github-row.tsx:137-141); the ten catalogs named earlier stay unchanged. Commit 3 adds localized update-page copy.
+
+## Ratchets and merge-head check
+
+The 2026-09-24 HEAD b429895f4a counts below are physical lines before B. `tests/fixtures/file-size-baseline.json` has no explicit cap for any row here. The scanned-file default is **strictly under 2,000**, so the last allowed count is 1,999 and headroom is `1,999 − current`; `structure/manifest.json` independently caps structure pages at 600. New files show 0 before creation. Recount if HEAD moves. `devlog/` is excluded from the file-size ratchet. Rust, Swift and PNG are outside its scanned extensions. The replacement at `structure/runtime.md:159` must be one line for one line.
+
+| Growing path | Current | Last allowed | Headroom |
+| --- | ---: | ---: | ---: |
+| `src/update/badge.ts` | 67 | 1999 | 1932 |
+| `src/update/desktop-badge.ts` | 0 | 1999 | 1999 |
+| `src/server/management/sidebar-routes.ts` | 106 | 1999 | 1893 |
+| `src/server/management/route-registry.ts` | 395 | 1999 | 1604 |
+| `desktop/scripts/generate-icons.ts` | 178 | 1999 | 1821 |
+| `gui/src/lib/desktop-shell.ts` | 32 | 1999 | 1967 |
+| `gui/src/components/sidebar-github-row.tsx` | 161 | 1999 | 1838 |
+| `gui/tests/desktop-shell.test.ts` | 37 | 1999 | 1962 |
+| `tests/update/update-desktop-badge.test.ts` | 0 | 1999 | 1999 |
+| `tests/server/sidebar-routes.test.ts` | 327 | 1999 | 1672 |
+| `tests/server/management-route-registry.test.ts` | 274 | 1999 | 1725 |
+| `tests/cli/cli-capabilities.test.ts` | 372 | 1999 | 1627 |
+| `tests/ci-workflows/build-desktop-icon-set.test.ts` | 251 | 1999 | 1748 |
+| `scripts/test-layout/layout.json` | 1816 | 1999 | 183 |
+| `tests/fixtures/test-layout-expected.json` | 1622 | 1999 | 377 |
+| `structure/runtime.md` | 600 | 600 | 0 |
+| `structure/ops/service-and-sidecars.md` | 254 | 600 | 346 |
+| `structure/desktop-shell.md` | 388 | 600 | 212 |
+| `structure/companion.md` | 77 | 600 | 523 |
+| `structure/gui-and-management-api.md` | 395 | 600 | 205 |
+| `docs-site/src/content/docs/reference/management-api.md` | 651 | 1999 | 1348 |
+| `docs-site/src/content/docs/guides/desktop-app.md` | 122 | 1999 | 1877 |
+| `docs-site/src/content/docs/fr/reference/management-api.md` | 406 | 1999 | 1593 |
+| `docs-site/src/content/docs/fr/guides/desktop-app.md` | 79 | 1999 | 1920 |
+| `docs-site/src/content/docs/ja/reference/management-api.md` | 348 | 1999 | 1651 |
+| `docs-site/src/content/docs/ja/guides/desktop-app.md` | 79 | 1999 | 1920 |
+| `docs-site/src/content/docs/ko/reference/management-api.md` | 374 | 1999 | 1625 |
+| `docs-site/src/content/docs/ko/guides/desktop-app.md` | 79 | 1999 | 1920 |
+| `docs-site/src/content/docs/ru/reference/management-api.md` | 396 | 1999 | 1603 |
+| `docs-site/src/content/docs/ru/guides/desktop-app.md` | 124 | 1999 | 1875 |
+| `docs-site/src/content/docs/tr/reference/management-api.md` | 432 | 1999 | 1567 |
+| `docs-site/src/content/docs/tr/guides/desktop-app.md` | 79 | 1999 | 1920 |
+| `docs-site/src/content/docs/zh-cn/reference/management-api.md` | 342 | 1999 | 1657 |
+| `docs-site/src/content/docs/zh-cn/guides/desktop-app.md` | 79 | 1999 | 1920 |
+| `docs-site/src/content/docs/zh-tw/reference/management-api.md` | 324 | 1999 | 1675 |
+| `docs-site/src/content/docs/zh-tw/guides/desktop-app.md` | 79 | 1999 | 1920 |
+
+Outside the scanned extensions: `desktop/src-tauri/src/proxy.rs` 277, `updater.rs` 144, `lib.rs` 288, `startup.rs` 2161, `native_tray.rs` 273, `tray.rs` 620, `popup.rs` 390; `app/Sources/NativeTray/Popover.swift` 68; generated `desktop/src-tauri/icons/tray/icon-update.png` is binary. Their file-size-ratchet headroom is N/A.
+
+## Verifiers — PLAN-VERIFIER-REAL-01
+
+The commands below record the earlier *pre-B* runs on 2026-09-24 after root and GUI dependencies were installed; they are historical baseline evidence, not reruns against commit 1. This plan is now tracked in the shared worktree. The existing source tests do not read it except for the explicit transpiler command shown below. The privacy scanner uses git ls-files (scripts/privacy-scan.ts:60-69), so a fresh B run will include this tracked plan. `structure:check` reads `structure/` and its index, not this plan. The commands prove only the stated earlier baseline, not the future implementation.
+
+| Command, exact working directory | Exit | What ran / reads this plan? |
+| --- | --- | --- |
+| bun test tests/server/sidebar-routes.test.ts tests/server/management-route-registry.test.ts tests/ci-workflows/build-desktop-icon-set.test.ts tests/cli/cli-capabilities.test.ts (repository root) | 0 | 52 pass, 0 fail across four files; existing source only, no plan read. |
+| bun test tests/test-layout-tooling.test.ts (repository root) | 0 | 16 pass, 0 fail; reads existing layout JSON and fixture, not the plan. |
+| bun test tests/desktop-shell.test.ts (gui/) | 0 | 3 pass, 0 fail; reads existing GUI helper, not the plan. |
+| bun -e 'const text = require("node:fs").readFileSync("devlog/_plan/260924_update_indicator/020_phase2_desktop_state_icons.md", "utf8"); const transpiler = new Bun.Transpiler({ loader: "ts" }); for (const marker of ["### New src/update/desktop-badge.ts", "NEW tests/update/update-desktop-badge.test.ts"]) { const part = text.slice(text.indexOf(marker)); const match = part.match(/~~~ts\n([\s\S]*?)\n~~~/); if (!match) throw new Error("missing " + marker); transpiler.transformSync(match[1]); } console.log("2 complete new TypeScript blocks parse");' (repository root) | 0 | Both complete new TypeScript blocks parsed; this command reads this plan directly. It is syntax evidence, not typechecking or behavior. |
+| bun run icons:check (desktop/) | 0 | 18 generated icons match existing source; reads icon generator/assets, not the plan. The earlier trial spelling bun --cwd desktop run icons:check printed Bun usage with exit 0 and was not treated as a verifier. |
+| cargo test --manifest-path desktop/src-tauri/Cargo.toml (repository root) | 101 | The earlier run stopped before Rust tests because binaries/ocx-aarch64-apple-darwin was absent. This is environment setup, not a Rust test result. CI prepares an empty host-triple placeholder; B must do the same locally before retesting. |
+| swift -e 'import AppKit; let b = NSStatusBarButton(); print(b.cell?.imageRect(forBounds: b.bounds) as Any)' (repository root) | 0 | Confirmed the existing AppKit imageRect API resolves; this is not an overlay visual test and does not read plan. |
+| swift -e 'import AppKit; @MainActor enum Dot { static weak var button: NSStatusBarButton? }; @MainActor final class DotView: NSView { override func hitTest(_ point: NSPoint) -> NSView? { nil }; override func draw(_ dirtyRect: NSRect) { let b = NSStatusBarButton(); let r = b.cell?.imageRect(forBounds: b.bounds) ?? b.bounds; print(r.isEmpty) } }' (repository root) | 0 | Type-checked the proposed weak/button, hit-test and image-rect call shapes; it does not render the overlay or read plan. |
+| bun run privacy:scan (repository root) | 0 | Earlier tracked-file scan passed; this plan was untracked then, so the result did not cover it. Re-run in B now that the plan is tracked. |
+| bun run structure:check (repository root) | 0 | Structure SSOT checks passed on current docs; does not read plan or future source. |
+| bun run typecheck (repository root) | 0 | Existing TypeScript compiled with no diagnostics; no proposed source exists yet. Required again after B. |
+
+For local desktop Cargo tests, mirror `.github/workflows/ci.yml:1399-1415`: derive `triple` from `rustc -vV`, create `desktop/src-tauri/binaries/ocx-${triple}` as an empty executable placeholder, and create the ignored GUI resource placeholder if the Tauri build needs it. `.gitignore:85-86` ignores `desktop/src-tauri/binaries/` and `desktop/src-tauri/resources/`; B must not commit these test prerequisites. The empty file is for compilation/tests, not a runnable sidecar.
+
+Runs after B because the new implementation and test files do not exist today: bun test tests/update/update-desktop-badge.test.ts tests/server/sidebar-routes.test.ts tests/server/management-route-registry.test.ts tests/cli/cli-capabilities.test.ts tests/ci-workflows/build-desktop-icon-set.test.ts; bun test tests/test-layout-tooling.test.ts; cd gui && bun test tests/desktop-shell.test.ts && bun run lint && bun run build; cd desktop && bun run icons:check; cargo test --manifest-path desktop/src-tauri/Cargo.toml after making the same ignored empty host-triple sidecar placeholder as CI; bun run typecheck; bun run structure:check; bun run privacy:scan after staging any new B files; cd docs-site && bun install --frozen-lockfile && bun run build. These are future B/C gates, not pass claims. Host CI must be inspected at the final PR head; Windows and Linux Tauri builds and native visual QA remain distinct evidence.
+
+## Risks and rollback
+
+The in-memory snapshot is cosmetic and forged only by a process already holding the raw management token. It cannot invoke the package update job or weaken Tauri signature verification. A proxy restart, shell death, port rebind, missed heartbeat, or >32 active shells makes the affected desktop badge unknown rather than borrowing another session's state. A 60 s poll/heartbeat with 180 s expiry leaves two missed intervals before expiry. The 1 KiB streamed ingress bound and strict six-field allowlist prevent an oversized or nested payload from being retained or logged.
+
+The macOS overlay must be checked against changing title width, AppKit highlight, multiple displays and 1×/2× scaling. Windows and Linux generated icons need visual checking on their hosts; this Mac can validate image generation and Rust logic but cannot claim their rendered tray pixels. Linux without an AppIndicator host still has the embedded badge and no tray icon. If this commit must be backed out before commit 3, revert commit 2 as one unit: the default package badge and original template/PNG tray behavior resume, and no persisted desktop schema needs migration. Do not roll back the independent commit-1 package cache change.
+
+Cross-document handoff for main: structure/INDEX.md maps src/update/ to both runtime.md and ops/service-and-sidecars.md, so commit 2 edits both despite the abbreviated D7 row in 000_plan.md. The binding main decision is net-zero for runtime.md at its 600/600 structure budget: use the one-line replacement above, and coordinate any commit-1 or commit-4 replacements on their final merged text. Commit 3 must consume `CheckGeneration::{begin_if_not_installing,claim_install,apply_if_current,epoch_is_current,inspect}`, extend the UI projection for install state, put its install-epoch comparison inside the application closure, and return an explicit checking page status while a newer check remains active. No D1/D2/D3 disposition changes. Commit 3 still owns the desktop update click before the PR is marked ready.
+
+
+## wp2 P revalidation
+
+Revalidated against HEAD `b429895f4a` after commit 1; only this 020 plan was edited. Drifts and fixes:
+
+- `src/update/badge.ts`: the header and type moved from the former lines 19-29 to 6-18/12, and commit 1 added `UpdateBadgeDeps.now` plus the 40-hour unknown guard. The type-only replacement above uses the exact current installer declaration and leaves package cache semantics intact. The desktop projection keeps all seven `UpdateBadge` fields and uses its own heartbeat receipt TTL.
+- `src/update/index.ts` and `src/server/management/context.ts`: `defaultUpdateTag` now starts at 176, and `ManagementContext.principal` is at 151 after new package-check deps imports. The opening anchors were corrected; neither API shape forces a desktop design change.
+- `tests/server/sidebar-routes.test.ts`: commit 1 added the read-only package badge test, moving `call()` to 23-38 and the GET badge describe end to 139. The helper and new describe insertion points now target those exact boundaries and preserve the package test.
+- `scripts/test-layout/layout.json` and `tests/fixtures/test-layout-expected.json`: new update-async and update-refresh entries shifted the alphabetical insertion anchors to 1655-1659 and 1481-1485. The three-line before/after windows above still match HEAD and insert `update-desktop-badge.test.ts` between `update-bun-ownership-lease` and `update-desktop-owner` in both maps.
+- `structure/runtime.md`: commit 1 replaced the 600/600 Support row with a package-refresh link. The revised exact before/after block preserves that link and replaces one line with one line. `structure/ops/service-and-sidecars.md` gained a Package cache refresh section at 250-254; the desktop paragraph now appends there, preserving scheduler and async-check contracts.
+- `structure/gui-and-management-api.md`: the Updates row now specifies asynchronous check/run and package-cache age. Its revised replacement changes only the final sentence; the Sidebar row replacement uses the current row as its before text.
+- English and seven translated `docs-site` management API pages: commit 1 expanded the package badge row and added automatic-check paragraphs, and changed the check/run rows. The English exact-before row, the two replacement rows, and the sibling instructions now preserve those facts and insert the desktop paragraph before the existing automatic-check paragraph.
+- Ratchets: the old pre-wp1 counts were stale for the changed package badge, route test, layout maps, ops structure page, and all management API pages. The per-file current count/last-allowed/headroom table above is recalculated from HEAD and the baseline. `structure/runtime.md` has zero spare lines.
+- Desktop Cargo prerequisite: CI already creates an empty executable `ocx-${triple}` and GUI resource placeholder before `cargo test` (`.github/workflows/ci.yml:1399-1415`). B will prepare the same ignored local placeholders without committing them; `.gitignore:85-86` covers both directories.
+
+Fresh P checks: exact HEAD before-anchor assertions passed for the package badge, structure rows, layout neighbors, and all eight management API pages; all 36 headroom rows matched current file counts and absent baseline caps; both complete proposed TypeScript blocks parsed; `git diff --check` passed. These checks validate this plan, not the unimplemented B behavior.
+
+No D1/D2/D3 design decision changes.
diff --git a/devlog/_plan/260924_update_indicator/030_phase3_desktop_update_page.md b/devlog/_plan/260924_update_indicator/030_phase3_desktop_update_page.md
new file mode 100644
index 00000000000..2e555612b60
--- /dev/null
+++ b/devlog/_plan/260924_update_indicator/030_phase3_desktop_update_page.md
@@ -0,0 +1,993 @@
+# 030 — Desktop update page (wp3, commit 3)
+
+## Outcome and boundary
+
+Commit 3 makes both update entries in the *embedded* dashboard open a bundled desktop update page. The page can inspect, check, install, retry, and return to the dashboard through four native commands. Tray and page installation share one atomic claim and restore the pending signed update on failure. The browser dashboard retains its package update dialog. The dependency is commit 1's package badge freshness and commit 2's per-session desktop badge, updater-state publication, and tray icon state; rebase this diff on those commits and preserve their publication calls. This document proposes code; it does not implement it.
+
+IN: `desktop/ui/update.html`, the four commands, shared install claim, desktop GUI routing, tests, structure and public docs. OUT: `/api/update/run` changes, remote-origin updater IPC, updater key/signature policy, auto-install, tray icon art, package cache, npm PowerShell tray, and release/deployment. Commit 2 owns the `desktop_session` query key and the desktop badge request through `gui/src/lib/desktop-shell.ts::desktopSession`, `gui/src/lib/desktop-shell.ts::updateBadgeUrl`, and `gui/src/components/sidebar-github-row.tsx` ([020_phase2_desktop_state_icons.md](020_phase2_desktop_state_icons.md), “Embedded GUI poll”); wp3 leaves that code intact. That session is display identity only, never install authority (D3/D4 in `000_plan.md`).
+
+Current anchors at `9ffa2261ba`: `generate_handler!` and `WebviewUrl::App("index.html".into())` in `desktop/src-tauri/src/lib.rs:214-250`; `CheckGeneration`, `UiProjection`, `DesktopUpdateState`, `PendingUpdate`, and `check_and_show` in `desktop/src-tauri/src/updater.rs:12-238,329-378`; the still-ungated install arm, `TrayState`, and setter functions in `desktop/src-tauri/src/tray.rs:20-40,219-250,312-360`; `startup::open_dashboard`, `ready_dashboard`, and `navigate_dashboard` in `desktop/src-tauri/src/startup.rs:498-504,1454-1495`; app-origin policy in `desktop/src-tauri/src/window.rs:37-77`; `frontendDist`, `withGlobalTauri`, and CSP in `desktop/src-tauri/tauri.conf.json:6-15`; `window.__TAURI__.core.invoke` and nonce pattern in `desktop/ui/index.html:75-123`; GUI entry points in `gui/src/App.tsx:454-462`, `gui/src/components/sidebar-github-row.tsx:127-156`, and `gui/src/pages/use-dashboard-data.ts:861-901`. The maintenance anchor calls `openUpdateDialog` at `gui/src/pages/dashboard-overview-sections.tsx:219-229`; no edit there. `gui/src/lib/desktop-shell.ts:7-33` now owns desktop/session/OS detection and `updateBadgeUrl`.
+
+## File change map and executable edits
+
+No DELETE paths. Code blocks show the full new file or the exact replacement/addition at the named current-HEAD anchor. Preserve commit 2's snapshot publication and serialized UI projection worker when replacing check/install logic.
+
+### NEW `desktop/ui/update.html` — full file
+
+The page stays self-contained and English-only, matching `desktop/ui/index.html:1-74`. The inline script's Tauri nonce is required by the tested Linux CSP behavior at `desktop/ui/index.html:75-87` and `tests/clients/desktop-startup-surface.test.ts:313-323`. It does not call HTTP, parse a token, or use browser alert/confirm/prompt.
+
+```html
+
+
+
+
+
+ OpenCodex update
+
+
+
+
+ OpenCodex update
+ Reading update status…
+
+
+
+
+
+
+
+
+
+
+```
+
+### MODIFY `desktop/src-tauri/src/updater.rs`
+
+Before adding the page command, extend the current `#[derive(Clone)] pub enum UiProjection` at `updater.rs:12-16` with `Installing(String)`; keep the derive. Add `UiProjection::Installing(version) => tray::show_installing(&app, &version),` to `start_ui_projection_worker`'s match at `updater.rs:137-140`. Replace the full `CheckGeneration::claim_install` at `updater.rs:64-80` with this block and add `InstallClaim` at module level. `pending_version` runs under the gate **before** anything is committed: `NoPending` leaves the flag, `install_epoch`, and `latest_ui_revision` untouched, so an in-flight check remains valid. `on_claim` only publishes the in-memory snapshot under the gate; neither closure calls a Tauri setter. Remove the commit-2 `#[allow(dead_code)]` markers from `claim_install`, `epoch_is_current`, and `inspect` when wp3 wires them (`updater.rs:65,82,98`). Leave the unrelated `popup_nonmac_test` marker at `updater.rs:242` intact.
+
+```rust
+// Module level in updater.rs, next to CheckGeneration:
+#[derive(Debug, PartialEq, Eq)]
+pub enum InstallClaim { Claimed, Busy, NoPending }
+
+// Inside impl CheckGeneration, replacing commit 2's claim_install:
+pub fn claim_install(
+ &self, installing: &std::sync::atomic::AtomicBool,
+ pending_version: impl FnOnce() -> Option,
+ on_claim: impl FnOnce(),
+) -> InstallClaim {
+ let _guard = self.application.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ if installing.load(Ordering::Acquire) {
+ return InstallClaim::Busy;
+ }
+ // Verify pending under the gate before committing anything: a stale Install click with no
+ // pending update must not bump the epoch and orphan an in-flight check.
+ let Some(version) = pending_version() else { return InstallClaim::NoPending; };
+ if installing.compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire).is_err() {
+ return InstallClaim::Busy;
+ }
+ self.install_epoch.fetch_add(1, Ordering::AcqRel);
+ self.latest_ui_revision.fetch_add(1, Ordering::AcqRel); // invalidate queued check UI
+ on_claim();
+ self.queue_ui(UiProjection::Installing(version));
+ InstallClaim::Claimed
+}
+```
+
+The current tray install arm does **not** call commit 2's `claim_install(&installing) -> bool`: it still takes `PendingUpdate` directly at `tray.rs:228-233`. Replace that entire arm with `install_pending` below; the new three-way claim lives in that shared function and runs before either entry takes pending. The existing Rust test at `updater.rs:467-480` is the only live old-signature call site and must be changed as shown below.
+
+Reuse commit 2's `use serde::Serialize;` and `use std::sync::atomic::{AtomicU64, Ordering};` imports; do not add a second `Ordering` import ([020_phase2_desktop_state_icons.md](020_phase2_desktop_state_icons.md), “Rust transport and state”, `desktop/src-tauri/src/updater.rs`). Keep `PendingUpdate`'s single `Mutex>`; there is no second copy of signed `Update`. Add this after `PendingUpdate` and make all app-origin commands return the same projection. `PageUpdateStatus` is a new serialized type, not a new persisted schema.
+
+```rust
+#[derive(Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PageUpdateStatus {
+ current_version: String,
+ latest_version: Option,
+ available: bool,
+ installing: bool,
+ checking: bool,
+}
+
+pub fn page_status(app: &AppHandle) -> PageUpdateStatus {
+ app.state::().inspect(|| {
+ let pending = app.state::();
+ let pending = pending.0.lock().unwrap_or_else(std::sync::PoisonError::into_inner);
+ let latest_version = pending.as_ref().map(|update| update.version.clone());
+ let installing = tray::is_installing(app);
+ let checking = app.state::().tx.borrow().phase == "checking";
+ PageUpdateStatus {
+ current_version: env!("CARGO_PKG_VERSION").to_owned(),
+ available: latest_version.is_some(),
+ latest_version,
+ installing,
+ checking,
+ }
+ })
+}
+
+pub async fn install_pending(app: &AppHandle) -> Result {
+ let state = app.state::();
+ let gate = app.state::();
+ match gate.claim_install(
+ &state.installing,
+ || app.state::