diff --git a/.agents/fork-sync-policy.toml b/.agents/fork-sync-policy.toml index c718f90a..b219d84b 100644 --- a/.agents/fork-sync-policy.toml +++ b/.agents/fork-sync-policy.toml @@ -16,8 +16,12 @@ preserve_upstream_commit_identity = true canonical_inventory = "docs/maintainers/fork-divergences.md" rename_map = "docs/maintainers/fork-divergences.md#current-local-rename-and-compatibility-map" sync_procedure = "docs/maintainers/fork-sync-policy.md" +sync_ledger = "docs/maintainers/fork-sync-ledger/" uncertainty_destination = "operator escalation or durable discoverable follow-up" +# Any broad upstream sync must keep a sync ledger. sync_ledger_required = true +# The durable ledger must be tracked under sync_ledger; PR-body notes are only a summary. +in_tree_sync_ledger_required = true renamed_path_reconciliation_required = true policy_gap_closeout_required = true operator_escalation_required_for_uncertainty = true diff --git a/docs/README.md b/docs/README.md index 0889d43b..ccd0bb4c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -36,6 +36,8 @@ Use this index to choose the smallest document that matches your goal. - [Fork Sync Policy](maintainers/fork-sync-policy.md) defines the current upstream sync workflow, renamed-path reconciliation, sync ledger, local gates, and uncertainty triage. +- [Fork Sync Ledger](maintainers/fork-sync-ledger/) records durable summaries, + special-handling notes, and follow-up decisions for broad upstream syncs. - [Changelog](../CHANGELOG.md) tracks user-visible releases and packaging behavior changes. diff --git a/docs/maintainers/fork-sync-ledger/2026-06-03-pr-95-upstream-60c62e3.md b/docs/maintainers/fork-sync-ledger/2026-06-03-pr-95-upstream-60c62e3.md new file mode 100644 index 00000000..900544e2 --- /dev/null +++ b/docs/maintainers/fork-sync-ledger/2026-06-03-pr-95-upstream-60c62e3.md @@ -0,0 +1,113 @@ +# PR 95 Sync Ledger + +## Scope + +- PR: [#95](https://github.com/nisavid/codex-app-linux/pull/95) +- Merge commit: `d8d86a8bd532c8ced34e244737c916eba0264de3` +- Origin base before sync: `708e2b40b297d85be3503d873cf15389333fb56c` +- Previous divergence baseline: + `b771d3d89d8a002d559a443a09a1aa25a4e6702a` +- Synced Linux-port upstream commit: + `60c62e38bbd12a5d5ddd4e2bf1d513ff4892fe94` + +## Incoming Catalog + +### Remote Mobile Control + +- Keeps the outbound `Control other devices` settings path reachable on Linux. +- Hardens host, enrollment, and account compatibility matching against current + official app bundle shapes. +- Skips unsupported SSH status reads for Linux remote SSH hosts. +- Improves SSH install and update action handling, including release targeting. + +### AppShots + +- Bare modifier shortcuts now require distinct left and right modifier keycodes. +- A fast double-tap on one physical Alt or Shift key no longer opens AppShots. + +### Webview Patching + +- Adds a required Linux-safe monospace font stack patch for the official + webview font settings bundle. +- Adapts rate-limit footer patching to current official composer bundle shapes. +- Moves the fast-mode model guard to an extracted-app patch and hardens + detection so a missing relevant webview asset warns and fails the required + gate instead of being recorded as already applied. + +### Build And Package Metadata + +- Build metadata now records sanitized GitHub commit URLs. +- The generated app build-information dialog can show an `Open Commit` action + when a safe GitHub commit URL is available. +- Package staging recovers when the configured updater binary source points at a + deleted rebuilt artifact by using the rebuilt release binary path. + +### Nix And Updater Trust + +- Refreshed the official DMG Nix pin to app version `26.601.21317`. +- Updated `updater/trusted-dmg-manifest.json` to the matching official DMG + SHA-256. + +### Docs And Tests + +- Updated the fork divergence baseline to the synced Linux-port upstream commit. +- Added or expanded coverage for AppShots, remote mobile control, webview + patching, package-builder deleted-updater-source recovery, and script smoke + behavior. + +## Local Reconciliation + +- Upstream `linux-features/appshots/*` changes were ported into + `port-integrations/appshots/*`. +- Upstream `linux-features/remote-mobile-control/*` changes were ported into + `port-integrations/remote-mobile-control/*`. +- The descriptor prefix remains `integration:`. +- Durable docs keep `port integration` terminology. +- Local product and package names remain `codex-app` and + `codex-app-updater`. +- XDG/FHS package layout and the unprivileged updater boundary are preserved. +- Package versioning still follows the official OpenAI app bundle version. + +## Special Handling And Follow-Up + +- Remote mobile control remains experimental. Existing issue + [#59](https://github.com/nisavid/codex-app-linux/issues/59) covers the + human-assisted live account, mobile authorization, and host-state review, so + this sync did not need a new remote-control issue. +- AppShots same-key double-tap behavior changed intentionally. No follow-up + issue is warranted unless user reports show the distinct-left-right behavior + is too surprising. +- Fast-mode guard missing-candidate failures are now meaningful official bundle + drift signals. Treat future failures as patch compatibility work, not generic + CI flakiness. No separate issue is warranted from this sync. +- Nix DMG pins and updater trusted-DMG metadata must stay in lockstep on future + DMG refreshes. The policy and this ledger capture that expectation; no + separate issue is warranted. +- Linux monospace fallback changed. No issue is warranted without visual + regression evidence. +- Retroactive ledger coverage for earlier fork syncs is tracked in + [#96](https://github.com/nisavid/codex-app-linux/issues/96). + +## Verification + +- `node --test port-integrations/appshots/test.js` passed. +- `node --test port-integrations/remote-mobile-control/test.js` passed. +- `node --test scripts/patch-linux-window-ui.test.js` passed. +- `node --test --test-name-pattern "fast-mode" scripts/patch-linux-window-ui.test.js` + passed. +- `node --check scripts/patches/webview-assets.js` passed. +- `node --check scripts/patches/core/all-linux/webview/fast-mode-guard/patch.js` + passed. +- `bash -n tests/scripts_smoke.sh scripts/lib/package-common.sh` passed. +- `bash tests/scripts_smoke.sh` passed. +- `cargo test -p codex-app-updater trust` passed. +- `scripts/ci/validate-nix-pins.sh Codex.dmg` passed. +- `env CODEX_PATCH_REPORT_JSON=/tmp/codex-pr95-patch-report-current-shape-fix.json make build-app` + passed using cached `Codex.dmg` from `2026-06-02 20:09:09 -0400`, app + version `26.601.21317`. +- `node scripts/ci/validate-patch-report.js /tmp/codex-pr95-patch-report-current-shape-fix.json --profile official-dmg-build` + passed; `linux-fast-mode-model-guard` reported `already-applied`. +- `git diff --check` passed. +- Final PR checks passed, including Official DMG Build, Nix Package Builds, + Debian, RPM, pacman, updater, smoke tests, CodeQL, clippy, CodeRabbit, and + Greptile. diff --git a/docs/maintainers/fork-sync-ledger/README.md b/docs/maintainers/fork-sync-ledger/README.md new file mode 100644 index 00000000..eb300770 --- /dev/null +++ b/docs/maintainers/fork-sync-ledger/README.md @@ -0,0 +1,26 @@ +# Fork Sync Ledger + +This directory holds durable summaries for broad syncs from the Linux-port +upstream into this fork. Keep the PR body concise, but copy the final sync +ledger here before closeout so future syncs can review prior imported behavior, +special handling, and follow-up decisions without searching old PR text. + +Use one file per broad sync: + +```text +YYYY-MM-DD-pr-NN-upstream-SHORTSHA.md +``` + +Each entry should include: + +- sync scope: PR, merge commit, base commit, previous baseline, and synced + Linux-port upstream commit; +- upstream commit catalog grouped by behavior area; +- local reconciliation notes for renamed paths and fork contracts; +- user-facing or maintainer-facing highlights that may need special handling; +- follow-up decision for each special-handling item, including links to existing + issues or a note that no new issue is warranted; +- verification evidence from local gates and final PR checks. + +Do not record secrets, local-only credentials, or full generated artifacts in +the ledger. Link to PRs, issues, docs, and commands instead. diff --git a/docs/maintainers/fork-sync-policy.md b/docs/maintainers/fork-sync-policy.md index 905f2eff..0f5f8c6d 100644 --- a/docs/maintainers/fork-sync-policy.md +++ b/docs/maintainers/fork-sync-policy.md @@ -44,8 +44,9 @@ behavior into the user-global `syncing-forks-with-upstream` skill. 10. Close any reusable policy gap found during the sync. If the sync reveals a hazard that future agents could miss, update the narrowest durable policy surface before handoff. -11. Keep a sync ledger in the PR body or a temporary working note until it is - copied into the PR. +11. Create or update an in-tree sync ledger entry under + [Fork Sync Ledger](fork-sync-ledger/) before closeout. The PR body may carry + a concise summary, but the tracked ledger entry is the durable source. 12. Run the required local gates before the first push that contains code changes covered by [Local Gates](#local-gates). 13. On the first push of any task branch, create a draft PR in the same @@ -61,7 +62,8 @@ behavior into the user-global `syncing-forks-with-upstream` skill. ## Sync Ledger -Every broad upstream sync needs a ledger with: +Every broad upstream sync needs a tracked ledger entry under +[Fork Sync Ledger](fork-sync-ledger/) with: - upstream refs fetched and the baseline commit; - policy files read; @@ -77,6 +79,9 @@ Every broad upstream sync needs a ledger with: - classification for each affected area: preserved, upstream now implements it, obsolete by policy, intentionally changed, or uncertain; - exact local verification commands and results; +- special-handling highlights that future maintainers may need to review; +- follow-up decisions for each special-handling item, including links to + existing issues, newly created issues, or a note that no issue is warranted; - unresolved uncertainties escalated to the operator, or linked to a durable, discoverable follow-up when escalation is unavailable.