docs(sync): add fork sync ledger

.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

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.
 

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.

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.

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.