[Tracking] #7648 follow-up: Windows updater availability findings and four review corrections #7872

Activity

1. coderabbitai commented on Oct 28, 2026

   

   coderabbitaiBot

   on Oct 28, 2026 – with coderabbitai

   Last edited by coderabbitai

   Contributor

   More actions

   🔗 Related PRs

   #7648 - feat(codex): apply Windows CLI updates with owned transactions [open]

   ---

   📝 Issue Planner

   _{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

   • Create Plan

   ---

   🧪 Issue enrichment is currently in open beta.

   To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

   issue_enrichment:
     auto_enrich:
       enabled: false

   💬 Have feedback or questions? Drop into our discord!
2. github-actions

   added

   platformOS/service/tray/ACL (Windows-heavy, not Windows-only)OS/service/tray/ACL (Windows-heavy, not Windows-only)

   on Oct 28, 2026
3. luvs01

   added a sub-issue on Oct 28, 2026

   • Feature: provenance-aware Codex CLI update manager #2811
4. luvs01

   removed a sub-issue on Oct 28, 2026

   • Feature: provenance-aware Codex CLI update manager #2811
5. luvs01

   added a parent issue on Oct 28, 2026

   • Feature: provenance-aware Codex CLI update manager #2811
6. luvs01 commented on Oct 28, 2026

   

   luvs01

   on Oct 28, 2026 – with ChatGPT Codex Connector

   Last edited by luvs01

   CollaboratorAuthor

   More actions

   Partial verified candidate published as Draft PR #7875: #7875

   Head 1a8c8c2aa7d3b9cf839d2b977aeeb3a0ed446606, based on dev@f9e7d939; the remote tree exactly matches the locally validated index. This addresses items 1, 3, 4, 5 and 6: ACL-only release cleanup with both identity checks and the existing token/handle fences retained; bigint directory identity; canonical private OS-temp retention fixtures; structure mappings; and the four Chinese reported-version clauses.

   Focused selection: 95 passed / 59 native-Windows skips / 0 failed. Final portable model: 3 passed / 4 native-Windows skips / 0 failed. Typecheck, structure, privacy, size ratchet and docs build passed (593 pages / 85,232 internal links). Native skips are not evidence of Windows installer acceptance or a second actual apply.

   Item 2 remains unmodified and open: synchronous parent-admission recovery ACL work. Runtime persist/clear and shim install/restore/uninstall have synchronous caller contracts; a safe correction requires coordinated async admission/caller migration or an explicitly accepted busy/retry contract, with exclusive generation ownership and fresh checks across awaits. A background cached verdict or a bare Promise conversion would not satisfy that contract. The PR records the concrete remaining implementation and native concurrency conditions.

   No issue checkbox is marked complete merely because a candidate is published. Current-head hosted CI, explicit maintainer/security review, native acceptance and item 2 remain. The candidate merges cleanly in a read-only integration check with dev@492c1a15.

   Implementation update at 05:28 UTC: a second caller-level trace found that even the existing async runtime resolver re-enters synchronous persistence. I am now preparing item 2 separately from #7875 on dev@492c1a15, preserving the synchronous compatibility exports while migrating the actual asynchronous parent paths and their callers. The management configuration critical section needs an explicit preflight/commit separation with the ownership gate held correctly. No completion or native acceptance is claimed; this investigation does not change #7875's five-item scope.
7. luvs01

   added

   bugSomething isn't workingSomething isn't working

   on Oct 28, 2026
8. coderabbitai commented on Oct 28, 2026

   

   coderabbitaiBot

   on Oct 28, 2026 – with coderabbitai

   Contributor

   More actions

   Coding Plan

   Summary

   • Lock release: after an ACL-only verification failure, delete the lock only through held handles. Require the identity proof to pass before and after the ACL check. Keep the current refusal for identity mismatch. Add native regressions for release failure, repeated release, and same-prefix reacquisition and apply.
   • Parent admission: move recovery inspection to the existing async ACL verifier. Keep pins held across awaits. Acquire the gate by CAS before inspection. Migrate every parent caller to async admission. Keep denial-before-mutation behavior.
   • Directory identity: serialize directory identity as exact bigint-derived strings. The downstream string and JSON comparisons need no change.
   • Fixture root: use one predicate for nested-temp private roots in both the session and worker. Check authorization separately.
   • Docs and structure: complete the structure map, update the contract prose, and restore the Chinese clause. Run the structure, privacy, and docs validation commands. Report Windows-native validation that did not run.

   Design Choices

   Design Choice 1: Use dev as the base revision

   Options Considered:

   1. Branch from dev, which the ticket states contains the merged #7648 blobs.
   2. Branch from the current main checkout.

   Chosen Option: 1

   Rationale: Option 1: the target files exist only on dev. Re-confirm the cited line numbers on dev before editing.

   Design Choice 2: Distinguish ACL-only failure from identity mismatch in release()

   Options Considered:

   1. Delete the lock on any verification failure.
   2. Leave closed unset on failure so that a later release() can retry. Pins stay open.
   3. Delete the lock through held handles only when the identity proof passes before and after the ACL check (ACL-only failure). Keep the current refusal for every identity mismatch.

   Chosen Option: 3

   Rationale: Option 3:

   • Option 1 weakens identity checks.
   • Option 2 leaves native handles open with no guaranteed later caller.
   • Option 3 deletes only objects that are re-proven as owned. The next acquisition runs its own ACL checks, so no admission becomes weaker.

   Design Choice 3: Use async admission to move parent recovery ACL work off the event loop

   Options Considered:

   1. Run the synchronous inspection in a Worker and block on it.
   2. Prefetch and cache the recovery result, then read the cache synchronously.
   3. Return "busy" while a background inspection is pending.
   4. Add an async admission API that uses the existing async ACL runner. Migrate all in-repo parent callers to it.

   Chosen Option: 4

   Rationale: Option 4:

   • Option 1 still blocks.
   • Option 2 weakens fail-closed freshness.
   • Option 3 changes admission semantics.
   • Option 4 keeps denial-before-mutation and uses the facilities in windows-owner-acl.ts:312–363 and cli-update-job-store-windows.ts:390–397.

   Design Choice 4: Acquire the parent gate before async recovery inspection

   Options Considered:

   1. Inspect recovery first, then do FREE → PARENT_WRITE (the current order). The order now has an await between the two steps.
   2. Do FREE → PARENT_WRITE first, then inspect recovery while the parent holds the gate. On denial, release with an exact-value CAS.

   Chosen Option: 2

   Rationale: Option 2:

   • During the awaited inspection, no in-process worker can arm.
   • Gate contention returns at once with no ACL work.
   • The window for cross-process changes is no wider than the window today.

   Design Choice 5: Define retention root validation in the shared fixture helper

   Options Considered:

   1. Change only the worker regex.
   2. Define one shared root predicate in the fixture helper. Use it in both the session and the worker, together with windows-temp-ancestry.ts containment.

   Chosen Option: 2

   Rationale: Option 2: one definition prevents the session and the worker from drifting apart again. Authorization checks stay separate from the predicate.

   💡 User Tips

   Regenerate the plan with different choices with @coderabbitai <feedback>.

   Implementation Steps

   Phase 1: Persistent-lock release after verification failure

   Objective: a transient ACL failure must not leave a persistent lock that blocks the same prefix permanently. A real identity mismatch must still fail closed.

   Failure mode in src/codex/cli-update-job-store-windows.ts:

   1. release() sets closed = true (:843–844). It then awaits verifyHeld() (:805–808).
   2. If verifyAcl() returns false, it maps the result to unsafe_store (:390–392). A PowerShell timeout also counts as false (windows-owner-acl.ts:367–373).
   3. When that error is thrown, releaseLock() (:659–674) is skipped.
   4. The finally block runs closeAll(). The lock directory and owner record stay on disk.
   5. Each later release() returns false at :843.
   6. Each later acquisition gets CodexCliJobStoreBusyError from mkdir (:618–623). There is no reclamation.

   As a result, one slow ACL subprocess can stop all future applies to that prefix. A failed verification can come from the ACL proof or the identity proof. These failures have different ownership consequences.

   Task 1: Separate ACL-only failure from identity mismatch in release()

   Allow lock removal after an ACL-only failure. Keep every identity and ownership check.

   • In src/codex/cli-update-job-store-windows.ts, restructure the release path. Do not reuse verifyHeld() as one throwing unit.
   • Keep closed = true as the first statement. This keeps re-entrancy protection and the false result for repeated release.
   • Run verifyIdentitySync(). If it throws, propagate the error. Do not call releaseLock(). This keeps the current identity-mismatch behavior.
   • Await verifyAcl(entries) inside a local try. Capture an ACL failure without throwing at once.
   • Run verifyIdentitySync() again. If it throws, propagate the identity error. Do not call releaseLock().
   • If both identity checks pass and held is set, call releaseLock(ctx, held) even after an ACL failure. releaseLock() re-proves owner identity, links === 1, the exact bounded record bytes, and directory identity. It then deletes only through held handles with markDelete() (:356–361). Never delete by path.
   • After the lock deletion attempt, rethrow the captured ACL error (unsafe_store). Keep the caller's existing error contract.
   • Keep ctx.pins.closeAll(kernel) in finally. Keep the existing WindowsApplyAuthorityPins failed-close retention (:167–182) unchanged.
   • Add a short code comment with the rationale. Removing our own lock reduces authority. The next acquisition re-runs the ancestry and prefix ACL checks.

   Task 2: Keep caller cleanup classification accurate

   Make the apply result describe the real lock state after an ACL-only failure.

   • In src/codex/cli-update-windows-apply.ts, inspect release and cleanup handling at approximately :235–287. Check how a rejected release() maps to leaseRetained and cleanup errors.
   • Keep the unsafe_store cleanup error recorded.
   • Set leaseRetained to true only when the persistent lock still exists or authority pins remain. A rejection alone must not set it.
   • If the current classification already uses the lock and pin state, make no change.

   Task 3: Add regressions for release failure paths

   Extend the Windows-x64-gated lifecycle block in tests/codex-integration/codex-cli-update-windows-apply.test.ts (:147–196). The current tests prove reacquisition only after a successful release.

   ACL-only failure:

   • Acquire with the real or true ACL runner.
   • Before release, switch the async runner seam (windows-owner-acl.ts:347–350) to return false. Add a second variant that returns a timeout.
   • Assert that release rejects with unsafe_store.
   • Assert that the lock path is absent and pins are clean.
   • Assert that a second release() resolves false and calls no extra CloseHandle.
   • Assert that same-prefix acquisition then succeeds.
   • Restore the seam in finally.

   Identity mismatch:

   • Change the owner record or captured identity between the ACL await and the second identity check.
   • Prefer a real write through a test-owned handle if the share mode allows it.
   • If the share mode denies the write, add one narrow test seam in the job-store module. Model it on the existing runner-replacement seam style.
   • Assert that release rejects, the lock persists, and pins are clean.
   • Assert that a second release returns false.
   • Assert that reacquisition throws CodexCliJobStoreBusyError. This is the documented fail-closed result.

   Full same-prefix apply:

   • Use the real-apply pattern at :385–391.
   • Inject an ACL-only failure only at the first apply's authority release.
   • Run a second apply to the same prefix.
   • Assert applied, no retained lease, empty cleanup errors, and no lock.

   🤖 Prompt for AI agents

   Implement persistent-lock cleanup after ACL-only verification failure. Keep
   identity mismatch fail-closed and preserve the existing error contract.
   
   - Work from `dev`. Re-confirm the cited `c655484…` references before editing. Do
   not reapply old refusal paths or touch the excluded #7815/#7869, #7834/#7843 or
   #7860 areas.
   - In `src/codex/cli-update-job-store-windows.ts`, split release verification
   instead of using `verifyHeld()` as one throwing unit. Keep `closed = true`
   first. Run `verifyIdentitySync()`, capture any failure from awaited
   `verifyAcl(entries)`, then run `verifyIdentitySync()` again.
   - If either identity check fails, propagate the identity error without calling
   `releaseLock()`. If both pass and `held` exists, call `releaseLock(ctx, held)`
   even after ACL failure. Keep all owner, link-count, record-byte and
   directory-identity proofs. Delete only through held handles with `markDelete()`.
   Rethrow the captured `unsafe_store` error after the deletion attempt.
   - Keep `ctx.pins.closeAll(kernel)` in `finally` and preserve failed-close
   retention. Add the comment that removing the owned lock reduces authority and
   that the next acquisition rechecks ancestry and prefix ACLs.
   - Inspect cleanup classification in `src/codex/cli-update-windows-apply.ts`.
   Preserve the cleanup error. Set `leaseRetained` from actual persistent-lock or
   authority-pin state, not rejection alone. Leave correct existing classification
   unchanged.
   - Extend the Windows-x64 lifecycle tests with false and timeout ACL failures,
   identity changes across the await, repeated release, same-prefix reacquisition,
   and a second full apply. Verify lock and pin state, error results, and no extra
   `CloseHandle`. Restore the runner seam in `finally`. Use a real test-owned write
   for identity mismatch when possible; otherwise add only the narrow seam
   specified in the task.
   

   Phase 2: Move recovery ACL work off the parent event loop

   Objective: parent admission must not block the event loop while PowerShell ACL subprocesses run. Keep gate and pin ownership, fail-closed denial, denial before any mutation, and the process-wide exclusion domain unchanged.

   All current parent callers use synchronous beginCodexCliSelectionParentWrite().

   Current blocking chain:

   1. beginCodexCliSelectionParentWrite() (cli-update-selection-gate.ts:115–131).
   2. codexCliUpdateRecoveryBlocksAdmission() (cli-update-recovery.ts:152–170).
   3. withWindowsCliRecoveryStore() (cli-update-job-store-windows.ts:687–754).
   4. verifyWindowsEntriesAcl().
   5. Bun.spawnSync (windows-owner-acl.ts:117–135).
   6. Only after these steps: the gate CAS.

   Each verifier call has a budget of up to 5,000 ms (:112). The calls cover the ancestry batch, the directory, and each record leaf. The total is not one 5-second deadline.

   Task 1: Add async recovery-store inspection

   Use the existing async ACL verifier. Keep native pins held across each await.

   • In src/codex/cli-update-job-store-windows.ts, add an async counterpart to withWindowsCliRecoveryStore(). Use async verifyAcl (:390–397) with the same policies:
     • "trusted-ancestry" for ancestors;
     • "write-private" for the final two components;
     • "private" for the directory and record leaves (:697–724).
   • Keep the native opens, pin chain (:406–427), no-reparse and canonical checks, single-link rule, and 1,024-byte limit.
   • After each awaited ACL call, re-verify the native identity of the pinned entries. Use the same verification sequence around the await as verifyHeld() (:797–808).
   • Close pins and FFI libraries in finally only after all awaited verifications settle.
   • Keep the per-call 5,000 ms budget.
   • Keep the sync function exported and unchanged for compatibility.
   • In src/codex/cli-update-recovery.ts, add codexCliUpdateRecoveryBlocksAdmissionAsync(). Keep these behaviors:
     • the synchronous ENOENT lstatSync fast path (:152–170);
     • the default config directory;
     • the cap of 256 filename-token prefixes (:172–224);
     • an inspection exception means the store fences admission.
   • Known limitation: windows-owner-acl.ts:331–343 does not wait for the post-timeout reap. A timed-out verifier can still hold transient handles. Admission denies on timeout. Do not treat async completion as proof that subprocess resources have settled.

   Task 2: Add async parent admission in the selection gate

   Make contention denial immediate. Keep exact ownership across the await.

   • In src/codex/cli-update-selection-gate.ts, add async parent admission next to beginCodexCliSelectionParentWrite(). Return the same { entered, exit() } shape.
   • Step 1: try the FREE → PARENT_WRITE CAS synchronously. If the gate is held, return the denied handle at once. Do not run recovery or ACL work.
   • Step 2: if the CAS succeeds, await codexCliUpdateRecoveryBlocksAdmissionAsync().
   • If recovery blocks or throws, release the exact PARENT_WRITE value with a CAS. Then return { entered: false, exit() {} }.
   • If recovery is clear, return the entered handle. Keep exit() idempotent.
   • Do not change the process-wide alias-safe domain (:17–26), worker generations (:73–86), cancel-versus-commit CASes (:89–102, :198–202), childStarting() sealing (:204–217), or retained-ownership retry after a failed durable terminal publication (:224–232).
   • Document these behaviors in comments:
     • While the parent awaits inspection, worker tryEnter() reports busy.
     • Worker waitEnter() yields until the parent exits or is denied. Its default contention deadline is 30 seconds.
   • Keep beginCodexCliSelectionParentWrite() exported. After the caller migration, no in-repo production parent caller uses it.

   Task 3: Migrate parent callers to async admission

   Keep each caller's denial result. Deny before any mutation.

   File	Lines	Required behavior
   src/codex/runtime.ts	:409–427, :437–461	Await admission. Throw CodexCliSelectionMutationBusyError before any mutation or cache invalidation. Release in finally.
   src/codex/shim.ts	:979–993, :1116–1122	Keep refused/busy for install and uninstall. Keep deferred for auto-restore.
   src/codex/shim-overlay.ts	:448–464, :481–508	Deny before namespace creation, restore-lock acquisition, or journal mutation.
   src/codex/desktop-app-restart.ts	:249–299	Return selection_mutation_busy before restart-lock acquisition.
   src/remote-control/workspace-codex-runtime.ts	:370–425	On denial, keep bridge and isolation cleanup. On success, keep holding the gate across trust validation.

   • If a caller's enclosing function is synchronous, propagate the async change through its callers. Use bun run typecheck to find every affected call site.
   • No awaited side effect may run before admission resolves.
   • If a call chain cannot become async, do not leave it on the sync API without notice. Report it as a residual item in the PR.

   Task 4: Add admission tests for event-loop progress, denial, cancellation, and concurrency

   Verify behavior that the current tests do not show.

   Gate unit tests: adapt tests/codex-integration/codex-cli-update-worker.test.ts:268–343 to async admission.

   • Contention denial is immediate and calls no recovery or ACL work.
   • Process-wide exclusion still holds.
   • The cancel-wins and commit-wins outcomes do not change.

   Windows-gated tests: use tests/codex-integration/codex-cli-update-windows-recovery.test.ts, an existing recovery directory, and a deferred async runner seam.

   • Event-loop progress: a parent timer heartbeat ticks while admission is pending.
   • Concurrency: worker tryEnter() is busy. waitEnter() enters after the parent exits.
   • Denial: resolving false or timing out denies admission, releases the gate, and causes no mutation.
   • Admission: resolving true admits the parent.
   • After denial: a later admission succeeds once recovery is cleared.

   Existing cases to adapt:

   • The durable-uncertainty and stale-proof cases (:111–192) must deny through the async path.
   • Cases where the old window commit() or tryEnter() is false must stay false.

   Native PowerShell test, with no seam:

   • Assert heartbeat progress during admission.
   • Spy on the sync runner seam (windows-owner-acl.ts:129–135). Assert that parent admission never calls it. This proves that spawnSync is no longer on the path.

   Other updates: update existing tests for migrated callers to await admission.

   🤖 Prompt for AI agents

   Move parent recovery inspection to the existing async ACL runner. Acquire the
   parent gate before inspection so that admission stays fail-closed and workers
   cannot enter during the await.
   
   - Add an async counterpart to `withWindowsCliRecoveryStore()` in
   `src/codex/cli-update-job-store-windows.ts`. Preserve native opens, pin
   ownership, identity checks, canonical and no-reparse checks, the single-link
   rule, and the 1,024-byte limit. Use the specified `trusted-ancestry`,
   `write-private`, and `private` policies with async `verifyAcl`. Re-verify pinned
   identity after each awaited ACL call. Close pins and FFI libraries in `finally`
   after awaited verification settles. Preserve each 5,000 ms call budget and the
   unchanged sync export.
   - Add `codexCliUpdateRecoveryBlocksAdmissionAsync()` in
   `src/codex/cli-update-recovery.ts`. Preserve the synchronous missing-store fast
   path, default config directory, 256-prefix cap, and denial on inspection
   exceptions. Preserve denial on timeout. Do not infer subprocess resource
   settlement from async completion because post-timeout reap is not awaited.
   - Add async admission in `src/codex/cli-update-selection-gate.ts`. Attempt `FREE
   → PARENT_WRITE` synchronously. On contention, deny without recovery or ACL work.
   After acquisition, await recovery inspection. On a blocking result or exception,
   release only the exact `PARENT_WRITE` value by CAS and return the denied handle.
   Otherwise return the entered handle with idempotent `exit()`.
   - Preserve the alias-safe process-wide domain, worker generations, cancel/commit
   CASes, `childStarting()` sealing, and retained-ownership retry. Document worker
   `tryEnter()` busy behavior and `waitEnter()` yielding with its default 30-second
   contention deadline. Keep the synchronous admission API exported.
   - Migrate all production parent callers listed in the task to await admission.
   Preserve each denial result, cleanup obligation, and gate lifetime. Allow no
   awaited side effect before admission resolves. Propagate async signatures
   through callers and use `bun run typecheck` to find affected sites. Report any
   call chain that cannot become async.
   - Adapt gate and caller tests. Add Windows-gated heartbeat, concurrency,
   admission, timeout/false denial, gate-release, no-mutation, and later-success
   tests. Preserve durable-uncertainty, stale-proof, cancel-wins, and commit-wins
   outcomes. Add native PowerShell coverage that demonstrates heartbeat progress
   and no sync runner calls.
   

   Phase 3: Directory identity precision and retention fixture root contract

   Objective: fix two review corrections.

   • Directory identity must not lose precision above Number.MAX_SAFE_INTEGER.
   • The retention session and worker must accept the same private nested-temp fixture root. Do not weaken execution authorization or unsafe-root refusal.

   Task 1: Use exact bigint-derived strings for directory identity

   NTFS file IDs are 64-bit. The current ${relative}:${st.dev}:${st.ino} (cli-update-windows-observation.ts:30–39) uses number-valued lstatSync. Two distinct directories can serialize to the same identity.

   • In src/codex/cli-update-windows-observation.ts, change the per-entry stat at :30 to lstatSync(path, { bigint: true }). Use one stat call. Do not introduce a race between two stats.
   • Change these checks explicitly:
     • Use st.nlink !== 1n.
     • Before size accumulation (:42–43), refuse sizes above BigInt(Number.MAX_SAFE_INTEGER). Then convert to number. This matches windows-installation-files.ts:35–41.
   • Serialize directory identity as ${relative}:${String(st.dev)}:${String(st.ino)}. Extract this serializer as a small exported pure function for direct tests.
   • Do not change the string format. The apply-side ":" split (cli-update-windows-apply.ts:38–47) and JSON snapshot equality (:82–91) need no change.
   • Do not change the maxBytes stat (:69–71). It is not an identity.
   • An old persisted snapshot will compare as changed. The result is a fail-closed refusal. Note this in the PR.

   Tests:

   • Follow tests/clients/aside-profile-identity.test.ts:12–13,68–106. Use 2n ** 53n and 2n ** 53n + 1n. Show that their Number values collide and the serialized identities differ.
   • Add a Windows-gated check that real observation directory entries equal bigint-stat strings.
   • Put the tests in the existing observation or apply test file if the file-size baseline allows it.

   Task 2: Align retention worker root validation with the session contract

   Failure mode: the session creates roots under canonical OS temp (windows-cli-apply-retention-session.ts:25–35). The worker accepts only /^[A-Z]:[\\/]ocx-actual-apply-[^\\/]+$/i (windows-cli-apply-retention-worker.ts:256–261). The worker therefore rejects every root that the session creates. The worker also accepts drive-root children that no privacy check covers.

   • In tests/helpers/windows-cli-apply-retention-fixture.ts, which the worker already imports, add one exported root predicate. A root is valid only when all conditions are true:
     • It is absolute and canonical. realpath equals the supplied path. There is no junction or short-name alias at the root.
     • Its basename starts with ocx-actual-apply-.
     • It is strictly below canonical OS temp. Use containment from tests/helpers/windows-temp-ancestry.ts:19–42.
     • It is on the same volume.
     • It is not temp itself.
   • Replace the worker regex with this predicate.
   • Keep these worker checks as separate conditions. Evaluate them independently: executionAuthorized, Windows x64, the 36-character nonce, and the 4-byte failure fence.
   • Make the session's containment check use the same predicate. Prevent the session and worker from diverging.
   • Confirm that the nested Worker gets the same temp anchor through preload propagation at windows-temp-ancestry.ts:44–55. Do not add a second anchor mechanism.
   • Do not change root hardening (…session.ts:158–162, …fixture.ts:31–35), native reparse/ACL checks at and below the fixture, or cleanup order (…worker.ts:187–219).

   Tests: create a focused Windows-x64-gated test file under tests/codex-integration/. Register it in scripts/test-layout/layout.json and a tests/fixtures/test-layout-expected*.json shard. Cover these cases:

   • Authorized + normal nested temp root → accepted.
   • Unauthorized + valid root → refused.
   • Authorized + C:\ocx-actual-apply-* drive-root child → refused.
   • Temp itself, an outside-temp path, a junction alias, and a wrong basename → refused.
   • No refusal starts the installer or deletes the root.

   🤖 Prompt for AI agents

   Use exact directory identity strings and align retention root validation between
   the session and worker. Preserve fail-closed snapshot comparison, root
   hardening, and separate execution authorization.
   
   - In `src/codex/cli-update-windows-observation.ts`, use one bigint `lstatSync`
   per entry. Compare `nlink` with `1n`. Before converting size to `number` and
   accumulating it, refuse values above `BigInt(Number.MAX_SAFE_INTEGER)`.
   - Export a small pure serializer that produces
   `${relative}:${String(st.dev)}:${String(st.ino)}`. Keep the existing string
   format, apply-side split, JSON comparisons, and non-identity `maxBytes` stat
   unchanged. Note in the PR that old persisted snapshots compare as changed and
   cause fail-closed refusal.
   - Test the serializer with `2n ** 53n` and `2n ** 53n + 1n`. Demonstrate the
   `Number` collision and distinct identity strings. Add Windows-gated
   real-observation comparison against bigint-stat strings. Use an existing
   observation or apply test file if the file-size baseline permits it.
   - Add one exported root predicate in
   `tests/helpers/windows-cli-apply-retention-fixture.ts`. Require an absolute
   canonical path, exact `realpath` equality, the `ocx-actual-apply-` basename
   prefix, strict containment below canonical OS temp, and the same volume. Reject
   temp itself and aliases.
   - Use that predicate in both the worker and session. Keep `executionAuthorized`,
   Windows x64, nonce length, and failure-fence length as independent checks.
   Confirm existing preload temp-anchor propagation without adding another anchor
   mechanism. Preserve root hardening, native reparse/ACL checks, and cleanup
   order.
   - Add and register the focused Windows-x64 root tests in both test-layout
   locations. Cover authorized nested-temp acceptance, unauthorized refusal,
   drive-root refusal, temp/outside-temp/junction/wrong-basename refusal, and the
   rule that refusal neither starts the installer nor deletes the root.
   

   Phase 4: Structure map, Chinese clause, and validation

   Objective: complete the structure source map. Update the contract prose for Phases 1–2 and exact directory identity. Restore the missing Chinese clause. Run the repository validation commands.

   Task 1: Complete the codex-cli-update.md manifest entry and review mapped prose

   • Before editing, confirm on dev that all four paths below are tracked by git.
   • In structure/manifest.json, add these four paths to the documents array of the codex-cli-update.md entry:

   Path	Described at
   src/codex/cli-windows-plan-provenance.ts	structure/codex-cli-update.md:67
   src/codex/windows-npm-execution.ts	:110
   src/lib/windows-owner-acl.ts	:454; keep its existing remote-link.md mapping
   src/codex/windows-installation-files.ts	:467

   • In structure/codex-cli-update.md, update the current-contract prose:
     • release semantics: ACL-only failure versus identity mismatch;
     • async parent admission and its CAS-first order;
     • exact directory identity strings.
   • Review every other doc that maps to the changed sources. Edit remote-link.md only if windows-owner-acl.ts behavior changed.
   • Run bun run structure:index, then bun run structure:check. Do not edit structure/INDEX.md by hand.

   Task 2: Restore the reported-version clause in four Chinese paragraphs

   • Edit these four paragraphs:
     • docs-site/src/content/docs/zh-cn/reference/cli/agents.md (approximately :225).
     • docs-site/src/content/docs/zh-cn/reference/cli.md (approximately :20).
     • docs-site/src/content/docs/zh-tw/reference/cli/agents.md (approximately :226).
     • docs-site/src/content/docs/zh-tw/reference/cli.md (approximately :31).
   • These line numbers come from the main checkout. Locate the paragraphs again on dev.
   • Source sentence: "...when it proves ownership and, if a candidate version is reported, that version matches the manifest" (reference/cli/agents.md:1162–1163, reference/cli.md:~151). Compare against this English sentence on dev.
   • Insert the clause after the ownership condition:
     • zh-cn: "且若报告了候选版本，该版本须与清单一致"
     • zh-tw: "且若回報了候選版本，該版本須與資訊清單一致"
   • Keep the existing ownership wording and selectionAttested wording unchanged.
   • Do not edit the Windows attest paragraphs (zh-cn …agents.md:238, zh-tw …agents.md:239) or the fr/ja pages.

   Task 3: Run validation and report unexecuted Windows scope

   • Run these commands and tests:
     • bun run typecheck
     • the focused test files from Phases 1–3
     • bun run test
     • bun run structure:check
     • bun run privacy:scan
     • cd docs-site && bun install --frozen-lockfile && bun run build
   • Windows-x64 native tests run only on manual dispatch or pushes to main/preview. Do not add Windows PR jobs.
   • In each PR, list the Windows-native tests that did not run.
   • Link each fix PR to its review thread: r4396883857, r4396932202, r4396883860, r4396883869, r4396932208, r4396883854.

   🤖 Prompt for AI agents

   Complete the structure mappings and contract documentation, then restore the
   reported-version condition in the four Chinese paragraphs. Run the specified
   validation and report Windows-native coverage that did not execute.
   
   - Confirm on `dev` that the four source paths are tracked. Add
   `src/codex/cli-windows-plan-provenance.ts`,
   `src/codex/windows-npm-execution.ts`, `src/lib/windows-owner-acl.ts`, and
   `src/codex/windows-installation-files.ts` to the `codex-cli-update.md` entry's
   `documents` array in `structure/manifest.json`. Preserve the ACL module's
   `remote-link.md` mapping.
   - Update `structure/codex-cli-update.md` for ACL-only versus identity-mismatch
   release, CAS-first async parent admission, and exact directory identity strings.
   Review other docs mapped to changed sources. Change `remote-link.md` only if ACL
   module behavior changed.
   - Run `bun run structure:index` and then `bun run structure:check`. Never edit
   `structure/INDEX.md` by hand.
   - Locate the four zh-cn/zh-tw CLI and agents paragraphs on `dev`. Compare them
   with the cited canonical English sentence. Insert the exact supplied simplified
   or traditional Chinese clause after ownership. Preserve ownership and
   `selectionAttested` wording. Do not edit Windows `attest` paragraphs or fr/ja
   pages.
   - Run `bun run typecheck`, focused Phase 1–3 tests, `bun run test`, `bun run
   structure:check`, `bun run privacy:scan`, and `cd docs-site && bun install
   --frozen-lockfile && bun run build`.
   - Do not add Windows PR jobs. Respect the manual-dispatch and `main`/`preview`
   Windows-x64 test conditions. List unexecuted Windows-native tests in each PR and
   link each fix PR to its specified review thread. Availability fixes and
   corrections may land as separate PRs.
   

   Research

   Ticket summary

   Resolve the six open review findings from #7648. The change landed as c655484d9cccf316f3da41047d508bf10d92070a. The reviewed head was 6618aadd6dd445001c433c86828cce8e90bee62c.

   • Availability defect 1: persistent-lock release after a failed verification.
   • Availability defect 2: synchronous recovery ACL work during parent admission.
   • Review corrections: exact directory identity, the retention fixture root contract, the structure source map, and the Chinese managed clause.

   Each fix must keep the integrated updater stack, its ownership and identity checks, and its fail-closed behavior. Do not reapply old refusal paths.

   Codebase summary

   Opencodex is a Bun-native strict TypeScript ES-module codebase. The #7648 Windows updater is in src/codex/.

   • cli-update-job-store-windows.ts: apply authority, persistent lock, pins, and the recovery store.
   • cli-update-selection-gate.ts: process-wide parent/worker exclusion and commit windows.
   • cli-update-recovery.ts: durable recovery inspection.
   • cli-update-windows-observation.ts: install snapshots.
   • cli-update-windows-apply.ts: the apply sequence.
   • windows-installation-files.ts: native handle-bound identity.
   • src/lib/windows-owner-acl.ts: ACL verification. It has a sync Bun.spawnSync runner, an async Bun.spawn runner, and test seams for both.

   The parent-write callers are in src/codex/runtime.ts, shim.ts, shim-overlay.ts, desktop-app-restart.ts, and src/remote-control/workspace-codex-runtime.ts.

   Windows-native tests are in tests/codex-integration/ and tests/windows/. They are Windows-x64-gated. Retention fixtures are in tests/helpers/windows-cli-apply-retention-*.ts. Temp-ancestry support is in tests/helpers/windows-temp-ancestry.ts.

   structure/manifest.json generates structure/INDEX.md. The structure:index and structure:check scripts enforce that mapping. Docs are in docs-site/src/content/docs/. English is canonical.

   Revision constraint: the inspected checkout (88aaa754…, detached main) does not contain the #7648 tree. All implementation line references are at c655484…, except where the plan identifies references from main. The ticket states that these blobs still match on dev.

   File-level change summary

   Source

   File	Change
   src/codex/cli-update-job-store-windows.ts	Split release verification (:842–848, :797–808). Add async recovery-store inspection next to :687–754.
   src/codex/cli-update-windows-apply.ts	Make the leaseRetained and cleanup classification follow the real lock and pin state.
   src/codex/cli-update-recovery.ts	Add codexCliUpdateRecoveryBlocksAdmissionAsync().
   src/codex/cli-update-selection-gate.ts	Add async parent admission with the CAS-first order. Keep the sync export.
   src/codex/runtime.ts, shim.ts, shim-overlay.ts, desktop-app-restart.ts, src/remote-control/workspace-codex-runtime.ts	Await admission. Keep the denial semantics.
   src/codex/cli-update-windows-observation.ts	Use a bigint lstatSync and an exported exact serializer.

   Tests and helpers

   File	Change
   tests/codex-integration/codex-cli-update-windows-apply.test.ts	Release failure, repeated release, and same-prefix reacquisition and apply.
   tests/codex-integration/codex-cli-update-windows-recovery.test.ts	Async admission, heartbeat, denial, and concurrency.
   tests/codex-integration/codex-cli-update-worker.test.ts	Gate contention and async admission.
   tests/helpers/windows-cli-apply-retention-fixture.ts	Shared root predicate.
   tests/helpers/windows-cli-apply-retention-worker.ts, …-session.ts	Use the shared predicate.
   New retention-root test under tests/codex-integration/	Add the test and register its test-layout entries.

   Docs and structure

   File	Change
   structure/manifest.json	Add the four mappings.
   structure/INDEX.md	Regenerate. Do not edit by hand.
   structure/codex-cli-update.md	Update the contract prose.
   Four zh-cn/zh-tw pages	Insert the clause.

   Follow-up agent instructions

   • Base and references: branch from dev, not the 88aaa754… checkout. Re-confirm each c655484… line reference before editing.
   • Scope: do not reapply the old refusal paths. Do not touch the #7815/fix(windows): admit local config writer phases after config-root ACL settlement #7869, #7834/fix(config): re-arm the atomic writer's ACL timeout memo #7843 or #7860 areas.
   • Phase 1: never call releaseLock() after an identity mismatch. Never delete by path. Keep closed = true first.
   • Phase 2: no awaited mutation may run before admission resolves. Release the gate only with an exact-value CAS. Keep the sync API exported. Report any caller that cannot become async.
   • Phase 3: keep root validity and execution authorization as separate checks. A valid basename alone must never admit a root.
   • Separate PRs: availability fixes (Phases 1–2) and corrections (Phases 3–4) may land as separate PRs.

   ---

   🚀 Next Steps

   🤖 All AI agent prompts combined

   Task: 1
   
   Implement persistent-lock cleanup after ACL-only verification failure. Keep
   identity mismatch fail-closed and preserve the existing error contract.
   
   - Work from `dev`. Re-confirm the cited `c655484…` references before editing. Do
   not reapply old refusal paths or touch the excluded #7815/#7869, #7834/#7843 or
   #7860 areas.
   - In `src/codex/cli-update-job-store-windows.ts`, split release verification
   instead of using `verifyHeld()` as one throwing unit. Keep `closed = true`
   first. Run `verifyIdentitySync()`, capture any failure from awaited
   `verifyAcl(entries)`, then run `verifyIdentitySync()` again.
   - If either identity check fails, propagate the identity error without calling
   `releaseLock()`. If both pass and `held` exists, call `releaseLock(ctx, held)`
   even after ACL failure. Keep all owner, link-count, record-byte and
   directory-identity proofs. Delete only through held handles with `markDelete()`.
   Rethrow the captured `unsafe_store` error after the deletion attempt.
   - Keep `ctx.pins.closeAll(kernel)` in `finally` and preserve failed-close
   retention. Add the comment that removing the owned lock reduces authority and
   that the next acquisition rechecks ancestry and prefix ACLs.
   - Inspect cleanup classification in `src/codex/cli-update-windows-apply.ts`.
   Preserve the cleanup error. Set `leaseRetained` from actual persistent-lock or
   authority-pin state, not rejection alone. Leave correct existing classification
   unchanged.
   - Extend the Windows-x64 lifecycle tests with false and timeout ACL failures,
   identity changes across the await, repeated release, same-prefix reacquisition,
   and a second full apply. Verify lock and pin state, error results, and no extra
   `CloseHandle`. Restore the runner seam in `finally`. Use a real test-owned write
   for identity mismatch when possible; otherwise add only the narrow seam
   specified in the task.
   ===============================================================================
   
   Task: 2
   
   Move parent recovery inspection to the existing async ACL runner. Acquire the
   parent gate before inspection so that admission stays fail-closed and workers
   cannot enter during the await.
   
   - Add an async counterpart to `withWindowsCliRecoveryStore()` in
   `src/codex/cli-update-job-store-windows.ts`. Preserve native opens, pin
   ownership, identity checks, canonical and no-reparse checks, the single-link
   rule, and the 1,024-byte limit. Use the specified `trusted-ancestry`,
   `write-private`, and `private` policies with async `verifyAcl`. Re-verify pinned
   identity after each awaited ACL call. Close pins and FFI libraries in `finally`
   after awaited verification settles. Preserve each 5,000 ms call budget and the
   unchanged sync export.
   - Add `codexCliUpdateRecoveryBlocksAdmissionAsync()` in
   `src/codex/cli-update-recovery.ts`. Preserve the synchronous missing-store fast
   path, default config directory, 256-prefix cap, and denial on inspection
   exceptions. Preserve denial on timeout. Do not infer subprocess resource
   settlement from async completion because post-timeout reap is not awaited.
   - Add async admission in `src/codex/cli-update-selection-gate.ts`. Attempt `FREE
   → PARENT_WRITE` synchronously. On contention, deny without recovery or ACL work.
   After acquisition, await recovery inspection. On a blocking result or exception,
   release only the exact `PARENT_WRITE` value by CAS and return the denied handle.
   Otherwise return the entered handle with idempotent `exit()`.
   - Preserve the alias-safe process-wide domain, worker generations, cancel/commit
   CASes, `childStarting()` sealing, and retained-ownership retry. Document worker
   `tryEnter()` busy behavior and `waitEnter()` yielding with its default 30-second
   contention deadline. Keep the synchronous admission API exported.
   - Migrate all production parent callers listed in the task to await admission.
   Preserve each denial result, cleanup obligation, and gate lifetime. Allow no
   awaited side effect before admission resolves. Propagate async signatures
   through callers and use `bun run typecheck` to find affected sites. Report any
   call chain that cannot become async.
   - Adapt gate and caller tests. Add Windows-gated heartbeat, concurrency,
   admission, timeout/false denial, gate-release, no-mutation, and later-success
   tests. Preserve durable-uncertainty, stale-proof, cancel-wins, and commit-wins
   outcomes. Add native PowerShell coverage that demonstrates heartbeat progress
   and no sync runner calls.
   ===============================================================================
   
   Task: 3
   
   Use exact directory identity strings and align retention root validation between
   the session and worker. Preserve fail-closed snapshot comparison, root
   hardening, and separate execution authorization.
   
   - In `src/codex/cli-update-windows-observation.ts`, use one bigint `lstatSync`
   per entry. Compare `nlink` with `1n`. Before converting size to `number` and
   accumulating it, refuse values above `BigInt(Number.MAX_SAFE_INTEGER)`.
   - Export a small pure serializer that produces
   `${relative}:${String(st.dev)}:${String(st.ino)}`. Keep the existing string
   format, apply-side split, JSON comparisons, and non-identity `maxBytes` stat
   unchanged. Note in the PR that old persisted snapshots compare as changed and
   cause fail-closed refusal.
   - Test the serializer with `2n ** 53n` and `2n ** 53n + 1n`. Demonstrate the
   `Number` collision and distinct identity strings. Add Windows-gated
   real-observation comparison against bigint-stat strings. Use an existing
   observation or apply test file if the file-size baseline permits it.
   - Add one exported root predicate in
   `tests/helpers/windows-cli-apply-retention-fixture.ts`. Require an absolute
   canonical path, exact `realpath` equality, the `ocx-actual-apply-` basename
   prefix, strict containment below canonical OS temp, and the same volume. Reject
   temp itself and aliases.
   - Use that predicate in both the worker and session. Keep `executionAuthorized`,
   Windows x64, nonce length, and failure-fence length as independent checks.
   Confirm existing preload temp-anchor propagation without adding another anchor
   mechanism. Preserve root hardening, native reparse/ACL checks, and cleanup
   order.
   - Add and register the focused Windows-x64 root tests in both test-layout
   locations. Cover authorized nested-temp acceptance, unauthorized refusal,
   drive-root refusal, temp/outside-temp/junction/wrong-basename refusal, and the
   rule that refusal neither starts the installer nor deletes the root.
   ===============================================================================
   
   Task: 4
   
   Complete the structure mappings and contract documentation, then restore the
   reported-version condition in the four Chinese paragraphs. Run the specified
   validation and report Windows-native coverage that did not execute.
   
   - Confirm on `dev` that the four source paths are tracked. Add
   `src/codex/cli-windows-plan-provenance.ts`,
   `src/codex/windows-npm-execution.ts`, `src/lib/windows-owner-acl.ts`, and
   `src/codex/windows-installation-files.ts` to the `codex-cli-update.md` entry's
   `documents` array in `structure/manifest.json`. Preserve the ACL module's
   `remote-link.md` mapping.
   - Update `structure/codex-cli-update.md` for ACL-only versus identity-mismatch
   release, CAS-first async parent admission, and exact directory identity strings.
   Review other docs mapped to changed sources. Change `remote-link.md` only if ACL
   module behavior changed.
   - Run `bun run structure:index` and then `bun run structure:check`. Never edit
   `structure/INDEX.md` by hand.
   - Locate the four zh-cn/zh-tw CLI and agents paragraphs on `dev`. Compare them
   with the cited canonical English sentence. Insert the exact supplied simplified
   or traditional Chinese clause after ownership. Preserve ownership and
   `selectionAttested` wording. Do not edit Windows `attest` paragraphs or fr/ja
   pages.
   - Run `bun run typecheck`, focused Phase 1–3 tests, `bun run test`, `bun run
   structure:check`, `bun run privacy:scan`, and `cd docs-site && bun install
   --frozen-lockfile && bun run build`.
   - Do not add Windows PR jobs. Respect the manual-dispatch and `main`/`preview`
   Windows-x64 test conditions. List unexecuted Windows-native tests in each PR and
   link each fix PR to its specified review thread. Availability fixes and
   corrections may land as separate PRs.
   

   💡 Iterate on the plan with: @coderabbitai <feedback>

   Example Feedback
   - @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
   - @coderabbitai For design choice 1 go ahead with option 3 and replan.
   

   ---

   Start Coding →
9. lidge-jun

   added a commit that references this issue on Oct 28, 2026

   fix(codex): address Windows updater release and observation reviews (#…

   ...

   53a98e9
10. lidge-jun commented on Oct 28, 2026

    

    lidge-jun

    on Oct 28, 2026

    Owner

    More actions

    Status after #7875 merged to dev (53a98e9f). Independent security review PASS (0 blocking); exact-head PR CI 30/30; native Windows updater suite 378 pass / 0 fail.

    • Lock release after verification failure: disposal follows the original identity-fenced objects; ACL-only failure still releases while keeping its diagnostic; repeated release cannot close reused handles; a second actual apply to the same prefix succeeds. Includes the replacement-lock Worker fix.
    • Synchronous recovery ACL/PowerShell work on parent admission: not done. src/codex/cli-update-selection-gate.ts still reaches synchronous ACL/PowerShell verification in src/codex/cli-update-job-store-windows.ts (each call bounded by ~5s). Kept open here for a follow-up.
    • Exact bigint directory identities; changes during ACL awaits are detected.
    • Canonical private nested-temp retention roots; unsafe-root refusal preserved.
    • Structure ownership mappings and generated index.
    • Version-matches-manifest condition restored in the four Chinese paragraphs.

    Leaving this issue open for the remaining synchronous-admission item.
11. github-actions commented on Oct 28, 2026

    

    github-actionsBot

    on Oct 28, 2026 – with GitHub Actions

    Contributor

    More actions

    _{Automated translation bookkeeping — detected language: English.}
12. luvs01 commented on Oct 29, 2026

    

    luvs01

    on Oct 29, 2026 – with ChatGPT Codex Connector

    CollaboratorAuthor

    More actions

    Item 2 follow-up published as Draft PR #7931: #7931

    Head 391f48b, based on dev 8eb970d; the latest dev 9c33e46 adds a disjoint CI-sharding change. The published 30-file tree matches the locally reviewed/tested blobs. No #7875 work is repeated and no issue checkbox is marked complete.

    The candidate reserves a unique gate owner before fresh async recovery ACL checks, holds and revalidates native pins across awaits, and migrates async runtime/shim/restart/remote/management callers through a root-bound synchronous commit scope. Denial-before-mutation, exact-owner release, original DACL policies and pending-child recovery remain. Independent review found and fixed stale results after refused admission and parent/worker diagnostic misclassification.

    Final Linux focus: 143 pass / 38 Windows-native skip / 0 fail, 494 assertions; layout/size regressions 11 pass; typecheck (2,228 files), structure, privacy and diff checks pass. Independent final-diff source review found no further blocking finding; it is separate from maintainer acceptance and hosted CI. An earlier 269-pass caller run is labeled historical, and interrupted test:changed is recorded as incomplete/exit 143.

    Still open: the 8 newly added Windows native cases (within the 38 skips) need exact-head execution; general atomic publication/native feature subprocesses and explicit synchronous compatibility catalog paths remain synchronous. This is not whole-process async conversion, native acceptance, subprocess-reap proof, or completion of item 2.

    New-head automatic checks: Cross-platform 40797643817 and Service lifecycle 40797643802 queued; Catalog 40797643886 started. No manual approval/dispatch/rerun, merge, force push, deployment or permission change.
13. lidge-jun

    added a commit that references this issue on Oct 30, 2026

    fix(codex): await recovery ACL checks in async parent admission (#7931)

    ...

    cb48362
14. lidge-jun commented on Oct 30, 2026

    

    lidge-jun

    on Oct 30, 2026

    Owner

    More actions

    Item 2, synchronous recovery ACL/PowerShell work on parent admission, landed with #7931, merged into dev as cb483626c8f6af0c0120642179d3336e42b68151. Parent selection admission now reserves its gate owner first and then awaits the recovery ACL checks off the event loop. Pins and identity checks are held across the awaits, and the async callers are migrated. Before merge, a dedicated security review passed, the Windows-native recovery/admission files passed (181/0), and exact-head CI run 41058615039 succeeded.

    With items 1 and 3–6 landed by #7875 (53a98e9f), all six tracked findings now have a merged fix, so I'm closing this tracking issue. The synchronous compatibility exports that #7931 documents as residual stay as they are, and are not regressions of these findings.
15. lidge-jun

    closed this as completedon Oct 30, 2026