@narumitw/pi-sync 0.51.0 → 0.52.0

package/docs/settings-merge-audit.md

@@ -0,0 +1,153 @@
+# Settings merge audit
+
+Phase 2 extends [Phase 1 PR #1455](https://github.com/narumiruna/pi-extensions/pull/1455) with explicit opt-in settings merging, verified accepted ancestors and portable machine-local field rules. Existing defaults remain unchanged.
+
+## Touched areas and MUST verification
+
+| Area | Requirements | Verification |
+| --- | --- | --- |
+| Ancestors and journal | Private bounded atomic persistence, verified identity/hashes, preserve recovery evidence, revalidate ownership after awaits. | Cache/state/journal boundary Review; `merge-baseline-store.test.ts` and existing merged fault-injection tests. |
+| JSON and file mutation | Preserve parser semantics and unknown fields, whole-transfer barriers, secret scanning, queues and stale-byte guards. | Format table below; `settings-merge.test.ts`, `merged-sync.test.ts`, `local-fields.test.ts`; apply-boundary Review. |
+| Settings/migration | Explicit opt-in, ordered private writes, invalid-file protection, unknown-field preservation, no credential values in review. | `docs/extension-settings.md` Review; existing cross-process settings tests; new rule validation and cancellation/stale-review tests. |
+| UI/lifecycle | Observable supported modes, owned cancellation, no automatic activation or prefix changes. | `docs/extension-conventions.md` Review; Settings uses existing Kit settings screen and native input/confirm; lifecycle and remapped review tests retained. |
+| Packaging/docs | README warnings/sections, Changeset, both root gates, generated-loader smoke. | `docs/readme-conventions.md` Review; check/test/pack/Jiti/RPC evidence in PR handoff. |
+
+## Authoritative format table
+
+Installed Pi's `dist/core/settings-manager.js` loads `JSON.parse(stripBom(content))`, then migrates queue/steering, websocket/transport, old skill objects and retry delay fields. Public `SettingsManager.inMemory(...).getGlobalSettings()` exercises that migration path without private imports or filesystem writes. Inputs changed by migration are withheld, not repaired. Parser failures are sanitized without retaining raw payload causes.
+
+Installed `dist/core/keybindings.js` parses BOM-compatible JSON, filters invalid binding values, migrates legacy names with canonical-name precedence, orders known names then extras, and delegates matching to TUI. Those aliases and overlapping keys need their own semantic strategy: **keybindings.json remains file-level**.
+
+| Input/unit | Decision |
+| --- | --- |
+| Global settings.json, UTF-8 object JSON, optional BOM | Eligible only with a verified accepted ancestor and mergeSettings enabled. |
+| Comments, trailing comma, nonobject, invalid UTF-8, duplicate/prototype-sensitive keys, over 1 MiB/depth 64/16,384 nodes | Review; original bytes remain unchanged. |
+| Scalars, absence, null, unknown fields | Conservative presence-aware three-way decisions; accepted deletion preserves absence. |
+| Numeric literals | Safe integers and finite decimals whose mathematical value round-trips through JavaScript serialization; reject unsafe integers, overflow, underflow and rounded decimals at every nested leaf before comparison or projection. |
+| Objects/arrays | Atomic, including unknown nested objects; no array union or unproven recursive invariants. |
+| Provider/model, queue/steering, websocket/transport, skills/skill-command, analytics/tracking ID fields | Coupled root units; incompatible group edits conflict. |
+| Unaffected local members | Raw spelling, separators, ordering, BOM, line endings and trailing bytes retained; new members use local indentation. Output is parsed again. |
+| Missing/mismatched/corrupt ancestor | Review, never synthesize current data or rely on remote retention. |
+
+## Ancestors and crash boundaries
+
+Cache only eligible settings.json bytes under the denied private state root. Version-1 records bind ordered selection, local-field rules, setup/backend coordinates and the complete accepted-state fingerprint. Each fingerprint has a bounded private file in a checked private directory. Staging a candidate never replaces the previous state's ancestor. Every cache read validates schema, identity, canonical bytes and SHA; unknown/corrupted evidence is retained. Reader and pruning share private-regular-file, size, schema/identity and byte validation; reading additionally checks file hashes against the supplied accepted state. Nonprivate and nonregular records are never pruning candidates.
+
+| Durable boundary | Recovery |
+| --- | --- |
+| Cache staging fails before state | Existing state/ancestor survive; merge journal remains; directional accepted remote/apply is reported as persistence failure. |
+| Cache exists but state not advanced | Old ancestor remains; publication journal can reconcile known images and restage idempotently. |
+| State accepted but journal remains | Accepted fingerprint retires redundant journal without replaying old local bytes. |
+| Journal retired, pruning interrupted | Accepted ancestor retained; extra owned historical records are safe to prune later. Unknown records are never pruning candidates. |
+| Missing cache after restart/history removal | Field conflicts remain review; remote history is not an ancestor dependency. |
+
+Directional push, pull and rollback stage accepted logical snapshots before baseline acceptance, then prune only after successful acceptance/journal retirement. All critical continuations validate session ownership. Pull and rollback recheck reviewed local bytes/settings/head; full-byte guards conservatively refuse changes even if only excluded fields changed while a plan was pending.
+
+## Portable policy and compatibility
+
+mergeSettings defaults false and is independently toggleable without deleting evidence. localFields is an explicit sorted array of settings.json root names, with bounded safe names and whole coupled-group rules. Existing locked ordered settings persistence remains authoritative; saves preserve unknown fields and invalid files. UI input uses Pi's native editing/paste behavior, with signal and owner checks after every await.
+
+Saving rules explicitly upgrades settings to version 4, including after rule removal; portable snapshots use version 2. Old settings validators/decoders reject these versions. No new schema is inferred from absent fields: unrelated setups in the shared version-4 document retain absent policy and snapshot version 1. Explicit empty rules remain a portable opt-in and require migration from absence. Snapshot version 2 requires an explicit rule array across codecs, backend validators and journal images. Portable codec/transport/raw-remote/upload/accepted images also verify that declared root exclusions are absent, including case-normalized settings paths and escaped JSON keys. Physical journal before/after images intentionally retain local-only values; a portable journal requires an explicit accepted projection. Empty initial acceptance checks policy compatibility, and advisory inspection detects policy-only baseline changes. A setup without rules cannot accept a portable snapshot without explicit configuration. Returning to an older client requires a separately reviewed full copy into a distinct version-3 setup; pending evidence must not be downgraded.
+
+Portable JSON is deterministically canonicalized, excluding selected fields. Local overlay retains latest validated values/absence and unaffected semantic values' raw spelling. Complete settings deletion with any excluded root field present is refused, including null values; validated documents with no excluded fields may be deleted. State hashes and ancestors describe the portable common version; journal before/after describe physical local bytes, accepted describes portable bytes, and upload preserves unmanaged remote files. Journal validation checks the accepted projection against physical after-images. Journal identity preserves policy presence, and the upload policy must match before either candidate retirement or committed recovery. Older ambiguous absent-policy identities fail closed without deleting evidence; reviewed force directions remain the recovery route.
+
+Rule additions/removals and transitions from absent to explicit empty policy block ordinary/background merge. Explicit force directions require extra TUI/RPC migration confirmation even with --yes, warn about old history and removal risks, and validate the fresh setup/local/head before mutation. Push publishes the configured policy; pull only adopts already-matching authoritative remote rules and refuses a mismatch before review or mutation. A pull cannot manufacture a portable baseline against an unchanged nonportable remote. Cancelled/stale review changes neither files nor head. Remote bytes and newly merged/projected content remain subject to secret scanning. Excluding a value now does not erase prior remote history or private backups.
+
+## Review of commit `d0d3a44f` (PR #1456)
+
+| Feedback | Classification and evidence | Outcome |
+| --- | --- | --- |
+| [Couple analytics and tracking ID](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756573) | The installed Pi SettingsManager setter changes these fields as one operation. Independent acceptance can enable analytics with no tracking ID. | Actionable: treat both as one three-way decision unit; unilateral and divergent test cases exercise that invariant. |
+| [Finish rollback after cancellation](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756576) | The rollback publication uses its own bounded completion signal, but prior state persistence still used the aborted command signal. | Actionable: after the successful remote commit use cancellation-independent ownership validation to persist state and prune; retain session identity checks. A deterministic post-publication abort test asserts that accepted revision and local result agree. |
+| [Repair Phase 3 plan link](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756581) | The plan referenced a Phase 2 plan deleted by this PR. | Actionable: point `docs/plans/2026-10-05_pi-sync-content-merge-plan.md` to this package audit instead. |
+| [Coupled analytics exclusions](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191769392) | An exclusion of only one member of the analytics/tracking-ID pair could produce an enabled policy without its identifier or transfer another machine's identifier. The settings-merger pairing alone did not enforce portable policy. | Actionable: require both or neither in `normalizeLocalFields()`, shared by settings validation, snapshot validation, portable projection and overlay; tests cover one-sided refusal and the two-field local overlay. |
+| [Push post-commit bookkeeping](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191769400) | A backend can finish remote publication after the caller's abort, but `writeStateForConfig()` previously received the abort-bound owner guard. The same post-commit cancellation class applies after pull transaction installation; rollback was fixed in the prior follow-up. | Actionable: preserve abort-bound guards before commit and during apply; after successful publication or local installation, use cancellation-independent session ownership checks for state acceptance. Push and pull cancellation regressions verify accepted revisions and local bytes. |
+
+The three preceding threads have evidence-backed GitHub replies and were resolved after the signed `335579bd` push; reply to and resolve the two later threads only after their follow-up is committed and verified. Earlier inline feedback is already addressed by the code and regressions described above and by the PR's previous signed review commits (`c2dfbcff`, `48b9f46d`, `d192f85c`, `d0d3a44f`); the submitted reviews and conversation summaries are wrappers for those findings with no distinct unanswered technical request. This ledger does not assert that GitHub threads were resolved.
+
+## Stacked-branch conflict integration
+
+The merge from Phase 1 head `4a756001` retains Phase 2 portable settings and accepted-ancestor behavior while incorporating Phase 1 root pinning, active-file/physical-alias checks, post-journal preimage checks, additive apply-only recovery evidence, version-4 removal retirement, staged restoration, bounded indexed transaction planning and cancellation-aware preflight. Physical before/after images and applicability checks always use raw local bytes; accepted state and ancestors use the portable projection. No source-side conflict choice is treated as proof of correctness: every Phase 1-only module was compared with its upstream version, and both feature-specific test sets are retained.
+
+`stacked-merge-safety.test.ts` exercises portable session-root rejection, apply-only remote races, excluded-field edits during journal publication and single-download no-op acceptance. The complete upstream merged-sync tests run alongside the four retained Phase 2 ancestor/settings regressions. `npm run check` passes; root `npm test` ran 6,811 tests with 6,807 passing and four unrelated `pi-worktree` Git integration failures on host Git 2.34.1 (unsupported `git worktree list -z` and sparse-checkout inventory behavior). This is not a passing root test gate. Package build/pack, actual tarball inspection, all 36 README required-heading checks and an isolated offline Pi RPC package-directory readiness/registration/EOF smoke pass. Upstream main changes and package versions are inherited through the merge, not independent scope expansion. The completed Phase 2 plan remains deleted and the Phase 3 link points here. External writers, physical power loss, Windows and compiled runtime remain unverified or outside the claimed contract.
+
+## Review of head `c919d7d` (PR #1456)
+
+The complete paginated review evidence contains 29 substantive items. The 22 prior resolved items retain their published replies, code and regression evidence: initial acceptance/policy, early-exit pruning, version recovery advice, effective previews, v4 management, production backends, sibling policy absence, absent/empty distinction, refreshed force-push review, cancelled status, safe deletion, journal identity, forced pull restriction, unsafe cache pruning, policy inspection, portable content integrity, final matching acceptance, analytics merge coupling, rollback post-publication acceptance, Phase 3 link, analytics exclusions and push/pull post-commit acceptance. These remain **Already addressed**; no duplicate replies are required. Submitted-review wrappers and activity summaries add no substantive request.
+
+All seven pending items are P2 and directly concern Phase 2's portable-policy, accepted-ancestor or recovery goal; none is deferred or uncertain. Evidence was classified before implementation:
+
+| Thread | Evidence and relationship to goal | Disposition and verification |
+| --- | --- | --- |
+| [Rollback post-local commit](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870946) | Rollback alone still called the command-abort guard after successful local transaction retirement, before bounded publication. | Actionable: use cancellation-independent owner validation after local commit and before remote publication. `post-commit-cleanup.test.ts` injects abort at transaction retirement; session replacement still refuses publication. |
+| [Rollback pending journal](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870951) | Current head already invokes `requireNoMergeJournal(config)` without force; the `c919d7d` integration inherited the fix and both force variants' regressions. | Already addressed: `merged-sync.test.ts` verifies no publication, unchanged local/state/head/journal for ordinary and force rollback. |
+| [Unmanaged settings exclusions](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870954) | Nonempty rules with unmanaged settings preserved excluded remote values into v2 uploads rejected by all backends. | Actionable: reject nonempty rules unless normalized include selects settings.json. `local-fields.test.ts` covers absent/empty/nonempty rules, normalized casing, empty/session/custom selections and failed-save preservation. |
+| [Post-commit pruning](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192016163) | All three directions returned on caller abort before pruning fingerprint-specific ancestors despite completed acceptance/retirement. | Actionable: prune with owner-only validation before abort-only notification exit. Repeated push/pull/rollback regressions retain only accepted and unknown evidence. |
+| [Rollback authoritative policy](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192016170) | Historical policy alone missed an authoritative current-head rule change and allowed --yes overwrite without migration review. | Actionable: validate/read the current immutable head and authorize its policy before mutation; retain fresh-head/settings/byte guards. `rollback-field-policy.test.ts` covers accept, decline, abort and review races, plus unchanged control. |
+| [Newly portable rollback values](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192539160) | Reprojection cannot restore fields omitted by historical policy; overlay under removed rules drops current local values. | Actionable: adopt the proposed conservative restriction, refusing history whose policy differs from config before confirmation, backup, apply or publication. Presence/addition/removal/replacement tests preserve bytes/state/head and recommend authoritative push migration first. |
+| [Recorded journal projection](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192539164) | Structural validation used current rules, making intact old-policy after-images unreadable and blocking reviewed force recovery. | Actionable: validate projection with recorded upload rules and require accepted/upload policy agreement; current-policy enforcement remains in completeJournal. `local-field-recovery.test.ts` verifies intact readable evidence, ordinary recovery refusal and reviewed force-direction archival; corrupted images remain refused. |
+
+Touched-area MUST checks follow the table at the start of this audit and unchanged `docs/extension-conventions.md`, `docs/extension-settings.md` and `docs/readme-conventions.md`: deterministic command/RPC tests, cancellation/owner validation after awaits, private ordered atomic settings persistence, invalid-file and unknown-field preservation, root check/test gates and Changeset. No new settings store, background task, custom key, model-visible transition or automatic reload is introduced. Rollback now fails closed when current authoritative policy cannot be read instead of publishing an unreviewed policy over unreadable evidence. Post-local-commit publication remains bounded to 30 seconds; owner replacement still retains the existing backup for manual recovery rather than operating under a replaced session.
+
+### Integration and validation outcome
+
+The base advanced to `9e1c544a` during this review and GitHub reported conflicts. Signed merge `bdd5b946` integrates that base without rewriting history. The sole source conflict combines Phase 1's post-backup/root-resolution recovery freshness checks with Phase 2's physical overlay, settings fingerprint and full-byte guards. All inherited transaction completion, spelling-queue and canonical-target tests remain intact; no upstream plan is removed. The base's filesystem-sensitive test control fixes the initial case-sensitive-only failure on this native case-insensitive macOS host.
+
+`npm run check` passes (build, Biome, package boundaries and workspace typechecks). Twelve focused suites pass **237 tests**, with one inapplicable case-sensitive control skipped; native case-insensitive recovery runs and passes. The complete `npm test` invocation finished **6,936 passed / 18 failed / one skipped across 520 files**. Every failure is a five-second timeout in six subprocess-heavy suites, not a settings/recovery assertion failure. A single-worker rerun of all six failing files passes **87 / 91 tests**, including every portable Git round trip, the entire Git backend suite, attachment cancellation and worktree integration. Four older controls still exceed five seconds: the two generic Git head/revision/history/diagnostics contracts, root fresh-cache storage and the all-routes Git test. Their test bodies are unchanged from the base; the base's retained audit independently records the Git-route timing failure. Defer decomposition/investigation of these slow legacy controls to a separate PR; the timing cause is not established and no timeout override or unrelated Git change is adopted. The full local gate is **not green**. Earlier incomplete full attempts are not passing evidence.
+
+Package build, `npm run package:pack -- sync`, actual tarball inspection (generated entry, changed runtime sources and linked guides) and isolated package-directory RPC readiness/sync-registration/EOF shutdown pass without provider requests. Generated Jiti/lazy tests pass in the completed root run. `git diff --check` passes. Settings reads/writes continue through the existing locked/queued/private atomic protocol; the new invalid-selection save regression preserves exact bytes and unknown fields. Final semantic review covers all post-commit direction exits, recorded/current/historical policy roles, head/byte/settings races, journal validation versus recovery authorization, evidence retention/pruning and session replacement after commit. No npm publication, tag or release workflow dispatch is performed.
+
+## Review of remote head `9a03fffa` after base rebase
+
+Fetched every REST page for reviews, inline and conversation comments, and all 32 GraphQL threads (no additional thread/comment page remains). PR #1456 remains open on main; remote head is `9a03fffa`, local rebased head is `20b7afa6`, and current base is `d81f7aab`. The previous 29 original findings retain published replies and resolved threads; their unchanged evidence is reused, with affected behavior covered by the latest package/full test runs. Submitted reviews and conversation summaries are wrappers, not separate technical requests.
+
+| Feedback | Severity | Scope/evidence | Outcome |
+| --- | --- | --- | --- |
+| [Persist local-field policy during initial state acceptance](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736317) | P1 | Portable settings/accepted-state goal; local-fields.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Prune ancestors after early successful acceptance](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736344) | P2 | Portable settings/accepted-state goal; merged-sync.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Update the accepted-version recovery message](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736373) | P2 | Portable settings/accepted-state goal; local-fields.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Compare effective snapshots in diff and confirmation views](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736391) | P2 | Portable settings/accepted-state goal; local-fields.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Allow version 4 in every settings-management path](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736405) | P1 | Portable settings/accepted-state goal; settings-management.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Teach every backend to publish snapshot version 2](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4186736430) | P1 | Portable settings/accepted-state goal; backend-contract-suite.ts (production backend tests); prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Preserve absent policies on unrelated version-4 setups](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4187294448) | P1 | Portable settings/accepted-state goal; local-field-policy-presence.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Distinguish absent and explicitly empty field policies](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4187294455) | P2 | Portable settings/accepted-state goal; local-field-policy-presence.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Reconfirm policy after refreshing a force-push head](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4187294468) | P2 | Portable settings/accepted-state goal; local-field-migration.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Clear the sync status when migration is cancelled](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4187294480) | P2 | Portable settings/accepted-state goal; local-field-migration.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Allow safe deletion when no excluded value exists](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4187294490) | P2 | Portable settings/accepted-state goal; local-field-deletion.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Keep absent policies distinct in recovery journals](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190365558) | P2 | Portable settings/accepted-state goal; local-field-recovery.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Complete forced pull policy migrations](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190365563) | P2 | Portable settings/accepted-state goal; local-field-pull-policy.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Preserve unsafe ancestor records during pruning](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190365568) | P2 | Portable settings/accepted-state goal; merge-baseline-store.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Report local-field policy changes during inspection](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190585931) | P2 | Portable settings/accepted-state goal; local-field-inspection.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Reject snapshots that retain excluded fields](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190585937) | P2 | Portable settings/accepted-state goal; portable-snapshot-integrity.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Guard the final matching-state acceptance](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190585943) | P2 | Portable settings/accepted-state goal; empty-policy-acceptance.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Couple analytics opt-in with its tracking identifier](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756573) | P2 | Portable settings/accepted-state goal; settings-merge.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Finish rollback bookkeeping after the commit boundary](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756576) | P2 | Portable settings/accepted-state goal; backend-orchestration.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Preserve the Phase 2 plan link target](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4190756581) | P2 | Portable settings/accepted-state goal; Phase 3 plan link → existing audit; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Couple analytics fields in local exclusions](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191769392) | P2 | Portable settings/accepted-state goal; local-fields.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Persist push state after the publication boundary](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191769400) | P2 | Portable settings/accepted-state goal; backend-orchestration.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Continue rollback publication after local commit](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870946) | P2 | Portable settings/accepted-state goal; post-commit-cleanup.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Block rollback while a merge journal is pending](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870951) | P2 | Portable settings/accepted-state goal; merged-sync.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Reject local-field rules when settings are excluded](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4191870954) | P2 | Portable settings/accepted-state goal; local-fields.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Prune baselines before post-commit cancellation returns](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192016163) | P2 | Portable settings/accepted-state goal; post-commit-cleanup.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Confirm rollback migrations against the current head](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192016170) | P2 | Portable settings/accepted-state goal; rollback-field-policy.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Preserve newly portable fields during rollback](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192539160) | P2 | Portable settings/accepted-state goal; rollback-field-policy.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Validate journals with their recorded field policy](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4192539164) | P2 | Portable settings/accepted-state goal; local-field-recovery.test.ts; prior reply records branch evidence/corrections. | Already addressed; resolved, no duplicate reply. |
+| [Validate journal projections without rewriting JSON bytes](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4193737421) | P2 | In scope: portable settings integrity and local-value preservation. Canonicalize both recorded projections for intrinsic integrity, canonicalize newly accepted state/ancestors, and recognize legacy accepted raw-byte fingerprints without replay. `portable-merge-projection.test.ts` covers ordered/pretty/nested JSON, interruption, repeat sync, initial equality, advanced-head retirement and semantic corruption. | Already addressed by this fix; deterministic regressions and both final gates pass; resolution follows publication. |
+| [Distinguish integers that exceed JavaScript's safe range](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4193737429) | P2 | In scope: portable settings integrity and local-value preservation. Reject unsafe integers and nonfinite/underflow/rounded decimal tokens before JSON comparisons, canonicalization or overlay. `settings-number-safety.test.ts` covers signed/exponent/nested forms, the reported lost edit and supported spelling controls. | Already addressed by this fix; deterministic regressions and both final gates pass; resolution follows publication. |
+| [Refresh local-only values at the apply boundary](https://github.com/narumiruna/pi-extensions/pull/1456#discussion_r4193737434) | P1 | In scope: portable settings integrity and local-value preservation. Bind pull/rollback settings preimages to reviewed raw hashes or absence under Pi queues and compare captured backups before journal publication. `local-field-apply-preimage.test.ts` covers edits/deletions/creations at backup, apply entry, before/after transaction copy and journal publication; state/head remain unchanged. | Already addressed by this fix; deterministic regressions and both final gates pass; resolution follows publication. |
+
+The new items are independently consistent with the authoritative code: intrinsic journal integrity compares canonical projection hashes against noncanonical accepted bytes; JSON.parse and jsonEqual round numeric values before comparison and portable serialization; directional overlays are frozen before backup and transaction preparation captures a newer preimage without binding it to the reviewed settings hash. No severity upgrade or scope expansion is inferred from reviewer labels. Native filesystem, physical power loss, compiled runtime and live storage/provider claims remain outside verified evidence.
+
+### New failure-class audit and validation
+
+The three new suites initially reproduced 31 failures against rebased head `20b7afa6`; existing post-copy/post-journal guards and supported-number controls already passed. After fixes and added compatibility/spelling controls, all 67 new tests pass. The initial package run passed 1,819 tests with one native-filesystem skip; the six additional spelling controls pass in the final focused and full runs. The semantic audit follows `docs/extension-conventions.md`, `docs/extension-settings.md`, `docs/readme-conventions.md`, root and package instructions: every parser/canonicalization/overlay consumer; intrinsic recorded-policy validation versus current recovery authorization; all matching and merged acceptance sites and legacy completed states; pull/rollback raw preimages, queue acquisition, captured backups, later live-image checks, cancellation/owner changes and session-root transitions. No journal/schema version, UI component, settings store, model prefix, dependency or runtime-loading boundary changes. Unexpected preparation failures retain private evidence; no new cleanup path can restore stale bytes. Existing arbitrary-writer CAS limits remain, including the unavoidable final check-to-rename interval. Both physical case aliases and separate case-sensitive spelling replacements retain source/destination preimage guards.
+
+The rebase preserves the current base's path/terminal/root-transition and startup-safety fixes. Source changes from the previous published head are base updates plus portable-safety integration; the earlier 29 fixes remain verified by the complete package tests. The four ancestor/settings regressions moved back into `merged-sync.test.ts`, and legacy portable advanced-head cleanup is explicitly covered in the new projection suite. No duplicate review reply is needed for those already resolved items.
+
+Final verification: `npm run check` passes; `npm test` passes all 526 files with 7,170 tests and one native case-insensitive filesystem skip. Five focused parser/projection/preimage/case/root-recovery suites pass 124 tests with the same skip. Package pack dry run and actual tarball inspection pass: generated `dist/index.ts`, changed runtime sources and linked guides are present, and package tests are excluded. Isolated built-package RPC readiness, sync registration, lazy `/sync status` and EOF shutdown pass without a provider request. `git diff --check` passes. No timeout override, release dispatch, npm publication, visibility change or tag was performed. Native case-insensitive storage, Windows/compiled runtime, physical power loss and live storage/provider transfers remain unverified.
+
+## Limits and evidence
+
+Node cannot provide atomic content CAS against arbitrary external writers; pause those writers for stronger exclusion. Only this process's current session is protected. No resources, model prefix or active tools are changed by transfer. POSIX directory syncing is exercised; Windows and compiled-binary paths are not claimed verified. No live storage/provider transfer is required by deterministic tests.
+
+Root check and 492 files / 6,346 tests passed before the final documentation and additional rollback/parser hardening; final gate counts and packaging evidence belong in the PR handoff, not an inferred completion claim here.

package/docs/settings.md

@@ -202,6 +202,42 @@ Adding `sessions` requires a privacy acknowledgement in interactive flows.
 Session JSONL can contain prompts, tool output, file paths, images, and secrets.
 Pull protects the currently open session file; restart Pi or resume a pulled session to use newly synchronized conversations.
 
+### Automatic startup transfer
+
+`sync.automaticTransfer` is optional and accepts only a boolean; absent means `false`. Set it through **/sync → Settings → Automatic transfer at startup**. It is separate from `sync.automatic`: the legacy setting retains observation and selected-content shutdown behavior.
+
+When explicitly enabled, one startup transfer waits for an idle boundary in TUI/RPC. It requires an accepted baseline and a matching authoritative remote include list, retains all-or-nothing conflict review, checks secrets unless the global scan override is enabled, and never reloads resources. Git and verified conditional WebDAV support this automatic policy; R2/S3 require manual sync. Print/JSON skip automatic startup transfer. A settings save takes effect for subsequent authorization checks; enabling schedules the next session start, while foreground Settings cancels and drains any current work before saving. There is no polling.
+
+Turning it off does not revert transfers or remove backups/journals. For interrupted operations, follow [merge recovery](merge-implementation-audit.md). Unknown fields remain preserved and malformed/invalid files block saves, just as for the existing policy.
+
+### Settings field merge and machine-local fields
+
+`sync.mergeSettings` is experimental, defaults to `false`, and is available in the owning Settings screen. With a verified accepted ancestor, global `settings.json` root fields merge conservatively: absent differs from null, arrays/nested objects are atomic, and provider/model and other coupled fields form one unit. Unknown fields are preserved. Pi accepts plain UTF-8 JSON with an optional BOM, not JSONC; duplicate/prototype-sensitive keys, invalid encodings, migration-dependent syntax, and over-bound inputs require directional review. Field merging and nonempty portable projections also refuse unsafe integers, nonfinite numbers, and numeric literals that change mathematical value when serialized through JavaScript; they never round those values into an accepted edit. `keybindings.json` remains file-level because alias and matcher semantics need a separate strategy.
+
+`sync.localFields` is an explicit sorted string array of whole global `settings.json` root field names, not a heuristic or project override. Example: `"localFields": ["shellPath"]`. Coupled fields must be excluded together. Nonempty rules require `settings.json` in `sync.include`; absent or explicitly empty rules remain valid for other selections. Saving nonempty rules in Settings confirms an upgrade to settings version 4; manual edits must declare version 4 too. Absent rules keep a setup nonportable, including unrelated setups in a version-4 document. An explicit array opts that setup into snapshot version 2; `[]` after rule removal retains this reviewed opt-in and differs from absence. Older clients must refuse portable data rather than replace local-only values.
+
+Portable projections normalize remote JSON deterministically while local overlay preserves unaffected local member/value bytes and excluded values or absence. Accepted hashes and ancestors use that same projection; compatible noncanonical remote JSON does not create a false local change. Recovery verifies both recorded projections in canonical form while retaining the original physical bytes and exact checksums. Pull and rollback bind settings writes/deletions to the reviewed raw-file hash or absence under Pi's mutation queue, including transaction backup preparation; a newer excluded value causes refusal rather than overwrite. A portable whole-file deletion is allowed when no excluded root field is present; a present excluded value (including null) or unsupported local document blocks deletion for review. No override file is loaded and no resources are automatically activated. Portable remote snapshots must actually omit every declared excluded root field; inconsistent or unsupported settings documents fail closed before acceptance, without displaying payload values. Policy-only changes remain visible in status/startup inspection even when bytes are unchanged. Excluded data can remain in old remote versions and local backups; removing a rule can make it publishable or replaceable again.
+
+Changing rules blocks ordinary/background merge until a reviewed directional migration. To change the authoritative remote rules, use `push --force` from the authoritative machine first. `pull --force` may adopt a changed accepted policy only when the configured rules already match the remote; it never rewrites remote policy and refuses a mismatch before review or mutation. Rollback requires its historical snapshot to use the configured rules; it refuses mismatched history instead of deleting newly portable local values. Use authoritative `push --force` to migrate from current local bytes, then choose matching history. A rollback that overwrites a different current-head policy requires the same additional observable TUI/RPC migration confirmation even with `--yes`. Cancellation, changed bytes/settings/head, and invalid files prevent acceptance. Inspect `/sync diff` first. Configure the same portable rule set on every receiving machine; other local values may differ. Rule names, not credential values, appear in review.
+
+Accepted ancestors are private, hash/identity-bound, bounded records below the denied state directory. Capture occurs after accepted directions or journaled merge; cache staging precedes state acceptance, and previous ancestors survive failures until completed journal retirement permits pruning. Missing/corrupt cache never invents a baseline from current data or assumes remote retention. Preserve unknown/corrupted or nonprivate records and pending journals for manual review; pruning applies the same storage/schema/byte validation as reading. Journal identity distinguishes absent and explicit empty policies. Integrity validation uses the journal's recorded rules, so intact old-policy journals remain readable after a settings change; ordinary replay still rejects mismatched current rules, while reviewed force push/pull may archive that evidence. Older absence-conflating journal identities fail closed and remain available for an explicitly reviewed force direction; do not downgrade portable setups. To return to an older client, first use this version to review rule removal and publish a complete nonportable copy to a separate version-3 setup, with Pi closed during the change. Never reinterpret portable snapshots with an old binary.
+
+### Content merge and partial progress
+
+`sync.mergeContent` and `sync.partialSync` are independent experimental booleans, both default `false`. The owning **Content / partial sync** setting offers Off, Content only, Partial only, and Content & partial and confirms an explicit settings-version-5 upgrade. Manual configuration must also declare version 5. Settings version 5 retains the portable-policy behavior of version 4; moving from a legacy setup can require the existing separately confirmed directional policy migration. Disabling options retains the schema and recovery evidence.
+
+Content merge initially supports global `AGENTS.md` and `.md`/`.txt` prompt/skill resources. Strict UTF-8, 1 MiB/file and a four-million-cell complexity bound apply. BOM, CRLF/LF and final-newline bytes are not silently normalized; unsupported/binary/oversized input remains a file conflict. Output never includes conflict markers. JSON/keybindings/executable resources are not treated as generic text; settings has its separate strategy. A clean line merge is not proof of semantic correctness.
+
+Same-session content merge accepts only complete validated Pi v3 histories with exact immutable byte prefixes and comparable local/remote extensions. It rejects malformed/partial records, migrations, identity/header changes, duplicate ids, broken parent references, compaction rewrites and divergent appends. The current loaded session and its aliases remain protected; active sessions in other processes are not discoverable through this mechanism. Nothing resumes a pulled conversation.
+
+Partial progress stores per-path accepted hashes separately from the observed remote head. Withheld local versions remain local; the complete published snapshot retains the observed remote versions, never omission/deletion. Their previous verified ancestors survive staging and restart. Resource and collision groups defer together when independence cannot be proved; partially conflicted JSON and sessions remain atomic. Publication/apply/baseline is journaled, and a changed head replans only proven pre-commit attempts; unknown outcomes preserve evidence. Older codecs refuse version-3 partial snapshots and older settings readers refuse version 5, so do not collapse state for downgrade.
+
+`/sync conflicts` (also **History & recovery → Review unresolved conflicts**) shows private versions only when requested, in TUI or paginated RPC. It rejects confirmation/force bypass flags, reviews an entire group, then separately asks for local or remote authority. It revalidates the reviewed artifact fingerprint, group versions, baseline, configuration, ownership and current observed head before apply; stale/cancelled review performs no transfer. The manager always reports unresolved groups and the observed head separately from Last applied. Repeated unchanged conflicts retain one stable opaque identity rather than creating more evidence or modal reviews.
+
+Artifacts are private immutable records below denied state storage with a 192 MiB/record cap; accepted ancestor records use the same bound, and actual content strategies have smaller limits. Unresolved and unknown/corrupted evidence is never automatically removed. Completed cleanup retains the newest 32 **proven-common, unreferenced** artifacts; pinned files remain even if other groups in the same record completed. Total evidence can exceed those bounds across unresolved/unknown records: inspect it manually with Pi closed rather than deleting pending evidence. This is not remote-history erasure.
+
+Do not run older binaries against version-5 setups or pending journals. To downgrade, drain work, resolve/review every withheld group with this version, retain evidence, and create a separately reviewed complete copy in a distinct version-3 setup. Disabling partial sync with unresolved state blocks ordinary sync until it is re-enabled or an explicit force direction accepts a complete selected version. No watcher/debounce/polling optimization is enabled: content revalidation is preferred over treating revision equality as authority. See the [implementation and recovery audit](content-merge-audit.md).
+
 ### Unsupported old settings and recovery
 
 Version 1, version 2, and non-empty unversioned documents are unsupported after the version 3 schema reset.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-sync",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
   "type": "module",
   "license": "MIT",
@@ -40,19 +40,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@narumitw/pi-tui-kit": "^0.59.0",
-    "fast-xml-parser": "^5.11.1",
+    "@narumitw/pi-tui-kit": "^0.65.1",
+    "fast-xml-parser": "^5.11.2",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
+    "@earendil-works/pi-coding-agent": "1.0.2",
+    "@earendil-works/pi-tui": "1.0.2",
     "@types/proper-lockfile": "^4.1.4",
     "esbuild": "0.28.2",
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.0.2",
     "@earendil-works/pi-tui": "*"
   },
   "repository": {

package/src/backends/git/git-backend.ts

@@ -141,6 +141,7 @@ export class GitSyncBackend implements SyncBackend {
       profile: manifest.profile,
       ...(manifest.snapshotSyncSessions === undefined ? {} : { syncSessions: manifest.snapshotSyncSessions }),
       ...(manifest.selection === undefined ? {} : { selection: manifest.selection }),
+      ...(manifest.localFields === undefined ? {} : { localFields: manifest.localFields }),
       files,
     };
     validateGitSnapshot(snapshot, manifest, this.config.destination.namespace);
@@ -172,6 +173,7 @@ export class GitSyncBackend implements SyncBackend {
       syncSessions: snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/")),
       ...(snapshot.syncSessions === undefined ? {} : { snapshotSyncSessions: snapshot.syncSessions }),
       ...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
+      ...(snapshot.localFields === undefined ? {} : { localFields: snapshot.localFields }),
       files: files.map(({ path: filePath, sha256: fileSha, size }) => ({
         path: filePath,
         sha256: fileSha,

package/src/backends/git/git-storage.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import type { Snapshot, SnapshotSelection } from "../../snapshot/snapshot-types.js";
+import { sameLocalFields, validatePortableSnapshot, validateSnapshotFieldPolicy } from "../../sync/local-fields.js";
 import { portableSnapshotSelection, snapshotSelectionInclude } from "../../sync/sync-policy.js";
 
 export const GIT_MANIFEST_VERSION = 2;
@@ -7,7 +8,6 @@ export const MAX_GIT_MANIFEST_BYTES = 1024 * 1024;
 export const MAX_GIT_TREE_OUTPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_GIT_PAYLOAD_BYTES = 100 * 1024 * 1024;
 export const MAX_GIT_SNAPSHOT_BYTES = 512 * 1024 * 1024;
-const SNAPSHOT_VERSION = 1;
 
 export interface GitManifestFile {
   path: string;
@@ -25,6 +25,7 @@ export interface GitManifest {
   syncSessions: boolean;
   snapshotSyncSessions?: boolean;
   selection?: SnapshotSelection;
+  localFields?: string[];
   files: GitManifestFile[];
 }
 
@@ -55,7 +56,7 @@ export function requireGitManifest(value: unknown): GitManifest {
   }
   if (
     manifest.version !== GIT_MANIFEST_VERSION ||
-    manifest.snapshotVersion !== SNAPSHOT_VERSION ||
+    (manifest.snapshotVersion !== 1 && manifest.snapshotVersion !== 2 && manifest.snapshotVersion !== 3) ||
     typeof manifest.snapshotId !== "string" ||
     manifest.snapshotId.length > 512 ||
     !/^[A-Za-z0-9._-]+$/u.test(manifest.snapshotId) ||
@@ -83,11 +84,13 @@ export function requireGitManifest(value: unknown): GitManifest {
       "syncSessions",
       ...(manifest.snapshotSyncSessions === undefined ? [] : ["snapshotSyncSessions"]),
       ...(manifest.selection === undefined ? [] : ["selection"]),
+      ...(manifest.localFields === undefined ? [] : ["localFields"]),
       "files",
     ])
   ) {
     throw new Error("Git publication manifest is malformed.");
   }
+  validateSnapshotFieldPolicy({ version: manifest.snapshotVersion, localFields: manifest.localFields });
   if (manifest.selection !== undefined) portableSnapshotSelection(manifest.selection);
   let total = 0;
   const paths = new Set<string>();
@@ -122,6 +125,8 @@ export function validateGitSnapshot(snapshot: Snapshot, manifest: GitManifest, n
   const syncSessions =
     snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/"));
   if (
+    snapshot.version !== manifest.snapshotVersion ||
+    !sameLocalFields(snapshot.localFields, manifest.localFields) ||
     snapshot.id !== manifest.snapshotId ||
     snapshot.createdAt !== manifest.createdAt ||
     snapshot.machine !== manifest.machine ||
@@ -144,8 +149,8 @@ export function validateGitSnapshot(snapshot: Snapshot, manifest: GitManifest, n
 
 export function prepareGitSnapshot(snapshot: Snapshot, namespace: string) {
   snapshotSelectionInclude(snapshot);
+  validatePortableSnapshot(snapshot);
   if (
-    snapshot.version !== SNAPSHOT_VERSION ||
     typeof snapshot.id !== "string" ||
     !snapshot.id ||
     snapshot.id.length > 512 ||

package/src/backends/s3/s3-backend.ts

@@ -3,6 +3,7 @@ import { encodeKey, posixJoin } from "../../paths.js";
 import { sessionTokenWarnings } from "../../settings/config.js";
 import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
 import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { validatePortableSnapshot } from "../../sync/local-fields.js";
 import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
 import { portableSnapshotSelection } from "../../sync/sync-policy.js";
 import type { LatestPointer, RemoteObject, ResolvedS3Backend } from "../backend-types.js";
@@ -409,8 +410,8 @@ function requireHistory(value: { version: number; snapshots: LatestPointer[] } |
 }
 
 function assertSnapshotIdentity(snapshot: Snapshot, expectedProfile: string) {
+  validatePortableSnapshot(snapshot);
   if (
-    snapshot.version !== VERSION ||
     snapshot.profile !== expectedProfile ||
     !isSafeSnapshotReference(snapshot.id) ||
     !isSafeMetadata(snapshot.createdAt, 64) ||

package/src/backends/webdav/webdav-backend.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { decodeSnapshot, encodeSnapshot } from "../../snapshot/snapshot-codec.js";
 import type { Snapshot } from "../../snapshot/snapshot-types.js";
+import { validatePortableSnapshot } from "../../sync/local-fields.js";
 import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
 import { portableSnapshotSelection } from "../../sync/sync-policy.js";
 import type { LatestPointer, RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
@@ -500,8 +501,8 @@ function remoteHistoryEntry(pointer: LatestPointer): RemoteHistoryEntry {
 }
 
 function assertSnapshotIdentity(snapshot: Snapshot, namespace: string) {
+  validatePortableSnapshot(snapshot);
   if (
-    snapshot.version !== VERSION ||
     snapshot.profile !== namespace ||
     !isSafeReference(snapshot.id) ||
     !isSafeMetadata(snapshot.createdAt, 64) ||

package/src/commands/command-execution.ts

@@ -13,6 +13,7 @@ import { RemoteSelectionMismatchError } from "../sync/sync-policy.js";
 import { automaticSyncSummary } from "../ui/automatic-sync-summary.js";
 import type { RunRouteResult } from "../ui/cancellable-operation.js";
 import { setSyncStatus } from "../ui/sync-status.js";
+import { safeTerminalText } from "../ui/terminal-text.js";
 import { parseOptions, resolveSyncCommand, splitArgs, usage, validateCommandOptions } from "./command.js";
 import type { CommandOptions } from "./command-types.js";
 
@@ -124,6 +125,12 @@ export async function executeCommand(
         await operations.diff(ctx, options);
         return { kind: "completed" };
       }
+      case "conflicts": {
+        const { showConflicts } = await import("../sync/conflict-review.js");
+        throwIfAborted(options.signal);
+        await withLock("sync", () => showConflicts(ctx, options));
+        return { kind: "completed" };
+      }
       case "doctor": {
         const operations = await loaders.operations();
         throwIfAborted(options.signal);
@@ -244,6 +251,9 @@ async function showConfig(ctx: ExtensionCommandContext, options: CommandOptions)
       ...storageLines,
       `storage path: ${config.storagePath}`,
       `automatic sync: ${automaticSyncSummary(config.automatic)}`,
+      `settings field merge: ${config.mergeSettings ? "On (experimental)" : "Off"}`,
+      `machine-local settings.json fields: ${(config.localFields ?? []).map(safeTerminalText).join(", ") || "none"}`,
+      `automatic transfer at startup: ${config.automaticTransfer ? "On — selected-file upload/replace/delete; no reload" : "Off"}`,
       `included content: ${config.include.join(", ") || "none"}`,
       `sessions: ${config.include.includes("sessions") ? "included" : "not included"}`,
       `settings file: ${localConfigPath()}`,

package/src/commands/command.ts

@@ -13,6 +13,7 @@ export const SYNC_COMMANDS = [
   { name: "files", description: "Choose included content" },
   { name: "status", description: "Show sync status" },
   { name: "diff", description: "Show local/remote diff" },
+  { name: "conflicts", description: "Review private unresolved conflict groups" },
   { name: "doctor", description: "Check config, secrets, and lock state" },
   { name: "push", description: "Upload local settings" },
   { name: "pull", description: "Apply remote settings" },
@@ -45,6 +46,7 @@ const SYNC_FLAG_COMPLETIONS: Record<string, readonly CommandArgumentCompletion[]
   files: [SETUP_FLAG_COMPLETION],
   status: [SETUP_FLAG_COMPLETION],
   diff: [SETUP_FLAG_COMPLETION],
+  conflicts: [SETUP_FLAG_COMPLETION],
   doctor: [SETUP_FLAG_COMPLETION],
   push: [
     ...YES_FLAG_COMPLETIONS,
@@ -110,6 +112,7 @@ export function validateCommandOptions(command: string, options: CommandOptions)
     "files",
     "status",
     "diff",
+    "conflicts",
     "doctor",
     "push",
     "pull",
@@ -230,6 +233,7 @@ export function usage() {
     "Usage: /sync <command>",
     `Commands: ${commands}`,
     "Automatic sync: background startup checks only; use /sync to review and transfer. At shutdown, selected content is pushed automatically only when sessions are included. Startup checks run in TUI/RPC, not print/JSON.",
+    "Automatic transfer at startup is a separate opt-in: one conflict-free established-baseline transfer at idle in TUI/RPC, with conditional/lease publication and no resource reload.",
     "Settings: use /sync init or edit storage connections and sync setups in ~/.pi/agent/pi-sync.json (or the configured Pi agent directory). Version 1 and version 2 settings are unsupported and are never rewritten.",
   ].join("\n");
 }

package/src/settings/config.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { backendIdentityCoordinates } from "../backends/backend-identity.js";
 import { normalizeGitBranch, normalizeGitDirectory, normalizeGitRemote } from "../backends/git/git-config.js";
 import { normalizeWebDavPath, normalizeWebDavUrl } from "../backends/webdav/webdav-config.js";
+import { normalizeLocalFields } from "../sync/local-fields.js";
 import { normalizeSyncInclude } from "../sync/sync-policy.js";
 import { localConfigPath, readActiveLocalConfigDocumentForRepair } from "./config-file.js";
 import { requireSettings } from "./settings-store.js";
@@ -75,6 +76,7 @@ export async function loadPartialConfig(setupName?: string): Promise<PartialConf
     ...storageReviewFromConfig(config),
     include: [...config.include],
     automatic: config.automatic,
+    automaticTransfer: config.automaticTransfer ?? false,
     onSwitch: config.onSwitch,
     showStatus: config.showStatus,
   };
@@ -109,6 +111,11 @@ export function syncConfigReviewIdentity(config: AnySyncConfig) {
     backendIdentityCoordinates(config),
     config.include,
     config.automatic,
+    config.automaticTransfer ?? false,
+    config.localFields,
+    config.mergeSettings ?? false,
+    config.mergeContent ?? false,
+    config.partialSync ?? false,
   ]);
 }
 
@@ -155,6 +162,11 @@ function resolveSyncConfig(
     snapshotIdentity: namespace,
     include,
     automatic: setup.sync.automatic,
+    automaticTransfer: setup.sync.automaticTransfer ?? false,
+    localFields: setup.sync.localFields === undefined ? undefined : normalizeLocalFields(setup.sync.localFields),
+    mergeSettings: setup.sync.mergeSettings ?? false,
+    mergeContent: setup.sync.mergeContent ?? false,
+    partialSync: setup.sync.partialSync ?? false,
     onSwitch,
     skipSecretScan,
     showStatus,

package/src/settings/settings-management.ts

@@ -193,8 +193,8 @@ export async function removeStorageConnection(name: string, signal?: AbortSignal
 
 async function updateSettings(update: (settings: PiSyncSettingsV3) => PiSyncSettingsV3, signal?: AbortSignal) {
   return updateLocalConfig((settings) => {
-    if (settings.version !== 3) {
-      throw new Error("Storage connections and sync setups require version 3 pi-sync settings.");
+    if (settings.version !== 3 && settings.version !== 4 && settings.version !== 5) {
+      throw new Error("Storage connections and sync setups require version 3 or 4 or 5 pi-sync settings.");
     }
     return update(settings);
   }, signal);

package/src/settings/settings-types.ts

@@ -79,6 +79,13 @@ export type SyncSetupStorageSettings =
 export interface SyncPolicySettings {
   include: string[];
   automatic: boolean;
+  /** Explicit opt-in, separate from the legacy observe/shutdown policy. */
+  automaticTransfer?: boolean;
+  /** Version 4: settings.json root fields never uploaded. */
+  localFields?: string[];
+  mergeSettings?: boolean;
+  mergeContent?: boolean;
+  partialSync?: boolean;
   [key: string]: unknown;
 }
 
@@ -89,7 +96,7 @@ export interface SyncSetupSettings {
 }
 
 export interface PiSyncSettingsV3 {
-  version: 3;
+  version: 3 | 4 | 5;
   activeSyncSetup?: string;
   onSwitch: OnSwitchAction;
   skipSecretScan?: boolean;
@@ -107,6 +114,11 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
   snapshotIdentity: string;
   include: string[];
   automatic: boolean;
+  automaticTransfer?: boolean;
+  localFields?: string[];
+  mergeSettings?: boolean;
+  mergeContent?: boolean;
+  partialSync?: boolean;
   onSwitch: OnSwitchAction;
   skipSecretScan: boolean;
   showStatus: boolean;
@@ -124,6 +136,7 @@ export interface PartialConfig {
   storagePath: string;
   include: string[];
   automatic: boolean;
+  automaticTransfer?: boolean;
   onSwitch: OnSwitchAction;
   showStatus: boolean;
   bucket?: string;