[mrmans0n]

Why

The scheduled v2.5.0 codex sync (run 40929309607) failed closed with a cherry-pick conflict on 6b51376 ("docs(hooks): clarify whole-operation retry allowlist"). Nothing was pushed or published.

The cause is in the sync tooling, not in upstream v2.5.0. A ledger patch adapted by a stable sync keeps its original in alas history, retired, and its adaptation (appliedCommit) reaches alas later through the sync merge. The replay walks alas by commit date, so a ledger adaptation is replayed at the adaptation's date. Fork commits that build on the patch are replayed before it and conflict.

• neutral-codex-hook-review-execution was adapted in v2.4.0 as 78e7be6 (original 960f779, PR feat(hooks): add process-bound review for neutral clients #12, Oct 21).
• 6b51376 (same PR) edits lines of docs/codex-hook-review.md that 960f779 introduced. In the v2.5.0 replay it came before 78e7be6, so it conflicted.

PR #16 fixed the same problem for non-ledger adaptations recorded in downstreamTransitions. This PR applies the same rule to ledger patches.

What changes

• downstreamReplayOrder replays each ledger patch's appliedCommit at the position of its first retired original. This does not depend on patch ids, because an adaptation can keep its original's patch id (same change, same context).
• An appliedCommit that is not in protected alas fails the build, like a downstreamTransitions replacement.
• docs/ALAS_DOWNSTREAM.md documents the rule.

No workflow, verifier contract, ledger or KNOWN_PATCH_IDENTITIES change. verify-sync-source-review.mjs reconstructs through buildSyncCandidate, so the publication verifier uses the same order.

Verification

• New scripts/sync-ledger-replacement-order.test.mjs: a fixture with a ledger patch adapted in a v1.1.0 sync, merged into alas like a protected PR, and a fork commit that edits the patch's line. The v1.2.0 sync must replay the adaptation before the dependent commit, reproduce the same integration twice, and pass verifySyncSourceReview on a synthetic protected merge.
  • Variant 1: the adaptation keeps its original's patch id.
  • Variant 2: the adaptation has another patch id, as on the real fork.
  • Fail-closed case: an appliedCommit outside protected alas throws.
• Tests checked against the old code: with scripts/sync-candidate.mjs reverted, all three new tests fail; the two replay variants stop on the same kind: "downstream" conflict as the real run. With only the patch-id guard restored, the same-patch-id variant fails.
• vitest run scripts/: 15 files, 163 tests, all pass.
• Real v2.5.0 simulation, run on a synthetic merge of this branch into alas, with every ledger patch resolved as retain:
  • no conflicts and manualReviewReasons: [];
  • all 7 ledger patches applied;
  • redundantDownstreamCommits: [a37cd3f], the earlier-sync copy already handled by PR ci: replay non-ledger adaptations where their retired originals were #16;
  • no upstream workflow changes.
    The same simulation on current alas stops on 6b51376.

After merge

This PR is level 3 and needs the maintainer's merge. The v2.5.0 sync then runs as level 2: upstream touched src/CodexAcpServer.ts, so every ledger patch classifies as overlap and needs a reviewed resolution, which will be recorded on the sync/upstream-2.5.0 PR.

[mrmans0n]

Planned v2.5.0 sync (level 2, after this PR merges)

Simulated on a synthetic merge of this branch (023180d) into alas:

• Upstream v2.5.0 (34e0897) touches src/CodexAcpServer.ts, so all 7 ledger patches classify as overlap.
• Review result: every patch is retain. Each one replays cleanly. The contract checks covered:
  • feat: publish a predicted follow-up prompt as _meta.promptSuggestions agentclientprotocol/codex-acp#703: _meta.promptSuggestions is AIR-only and has its own key;
  • fix: update ACP SDK to 2.1 and align protocol behavior agentclientprotocol/codex-acp#704: assertPromptContentSupported, getSessionState throwing -32002, and invalidParams for auth and MCP transport errors.
    None of these reach a downstream call site.
• Exact candidate b396692, integration 7313e24. Two runs reproduced the same SHAs.
• Gates on the integration code:
  • typecheck passes;
  • npm test: 2464 passed, 40 skipped;
  • test:integration: 18 passed;
  • vitest run scripts/: 163 passed;
  • npm run build and npm pack --dry-run succeed.
  • bundle:all needs bun, so it runs only in CI.
• Publication preflight on a synthetic protected merge: the reconstructed exact and integration commits match.
• No upstream workflow changes.

The SHAs will change after the real merge, because the merge commit is new. Once that happens, the sync is rebuilt on the new alas with the same resolutions and the same checks are repeated before sync/upstream-2.5.0 is pushed.