@narumitw/pi-sync 0.54.2 → 0.56.0

package/docs/settings.md

@@ -6,6 +6,8 @@
 - [Required backend shapes](#required-backend-shapes)
 - [Status display](#status-display)
 - [Secret scanning](#secret-scanning)
+- [Experimental Agent mode](#experimental-agent-mode)
+- [Experimental Continuous sync](#experimental-continuous-sync)
 - [Included content](#included-content)
 - [Unsupported old settings and recovery](#unsupported-old-settings-and-recovery)
 
@@ -31,9 +33,11 @@ If both paths exist, `pi-sync.json` wins and the legacy file remains untouched.
 
 ### Editing in the manager
 
-Open `/sync` → **Settings** for one searchable list ordered by content, destination, automation, merge, and global preferences; these are task groups, not submenus. **Included content** and **Compare synced content** are adjacent. **Storage location** edits the current setup's coordinates, while **Manage sync setups** and **Manage storage connections** retain the catalog and affected-setup reviews. Returning from catalog management refreshes the rows; switching or removing the owning setup closes its old Settings screen.
+Open `/sync` → **Settings** and choose **Sync content**, **Sync behavior**, **Storage & setups**, or **Advanced**. **All settings (search)** provides cross-category typing-to-search over the same rows. **Included paths** and **Compare included paths** are adjacent in Sync content; the latter compares path policies, not file contents. **Storage location** edits the current setup's coordinates, while **Manage sync setups** and **Manage storage connections** retain the catalog and affected-setup reviews. Returning from catalog management refreshes the rows; switching or removing the owning setup closes its old Settings screen.
 
-Simple choices save immediately, preserve the selected row and search during refresh, and restore their previous value if saving fails. Escape closes the screen without undoing successful saves. Complex values retain their input/review flows. This navigation change does not alter schema, defaults, automatic-sync behavior, or experimental opt-ins.
+Descriptions identify the owner: this setup, all setups on this device, or shared connections. Simple choices report Saving and the durable Saved or failed/rejected result, preserve the selected row and search during refresh, and restore their previous value if saving fails. Escape closes the screen without undoing successful saves. Complex values retain their input/review flows. This navigation change does not alter schema, defaults, automatic-sync behavior, or experimental opt-ins.
+
+The manager separates current state from transfer, inspection, and management actions. **Check remote status** and **View differences** invoke the existing read/check routes only when selected. Last applied shows a compact snapshot ID with application time explicitly unavailable; full IDs remain in History. It never uses snapshot creation time as application time. See the [TUI behavior contract](tui-contract.md) for scopes and transfer branches.
 
 RPC reports the manual settings path and offers the existing setup/connection catalog dialogs, not the TUI preference or masked-credential editors. Print/JSON do not support `/sync`; use the private settings file directly. Main-menu summaries remain cached observations; `/sync status`, `/sync diff`, and `/sync help` remain available through the visible command hints.
 
@@ -132,7 +136,7 @@ This check does not contact the server or discover setups configured only on oth
 
 Every setup requires `sync.include` and explicit `sync.automatic`. Setup asks for automatic sync with Off first; existing values are not rewritten. When enabled, the current setup receives one background startup check in TUI/RPC, including reload/new/resume/fork. Startup no longer performs automatic transfers or opens dialogs; review changes through `/sync`. Print/JSON skip startup checks. Checks compare local hashes and remote metadata against the last sync baseline, so revision changes and missing baselines require review rather than proving a file conflict.
 
-The setting still permits automatic shutdown pushes of selected content when `sessions` is included, in all modes; this is not limited to uploading session files. Reload skips shutdown push. Settings changes apply to subsequent operations; changing this setting does not schedule another startup check until the next session start. Foreground `/sync` cancels a pending check before opening Settings. The check deadline is 30 seconds plus bounded cleanup, with manual retry through `/sync status`; there is no polling. See [Background startup checks](../README.md#background-startup-checks) for recovery and Git cache exceptions.
+The setting still permits automatic shutdown pushes of selected content when `sessions` is included, in all modes; this is not limited to uploading session files. Reload skips shutdown push. Settings changes apply to subsequent operations; changing this setting does not schedule another startup check until the next session start. Foreground `/sync` cancels a pending check before opening Settings. The check deadline is 30 seconds plus bounded cleanup, with manual retry through `/sync status`; this one-shot policy has no polling. Continuous sync is a separate opt-in. See [Background startup checks](../README.md#background-startup-checks) for recovery and Git cache exceptions.
 
 Recommended includes the nine non-session Pi roots listed below; Minimal includes `settings.json` and `AGENTS.md`. The save review lists every selected path and the full backend destination. R2/S3 requires an explicitly entered existing bucket and never creates one. Saving setup or connection settings does not contact remote storage.
 
@@ -144,7 +148,7 @@ A referenced connection cannot be removed.
 The current setup must be switched before removal when other setups exist. Removing the last setup is allowed; local removal never deletes remote history.
 Two setups cannot resolve to the same normalized backend location.
 
-The global **After switching setup (all setups)** setting persists as `onSwitch` and applies whenever any setup is made current. It accepts:
+The global **On setup switch** setting persists as `onSwitch` and applies whenever any setup is made current. It accepts:
 
 - `ask-before-pull` — switch, then ask in TUI whether to start a reviewed pull;
 - `pull-after-switch` — require observable UI and start the normal reviewed pull;
@@ -153,14 +157,37 @@ The global **After switching setup (all setups)** setting persists as `onSwitch`
 ### Status display
 
 The global `showStatus` setting accepts a boolean and defaults to `true` when omitted from an existing version 3 document.
-Set it through **/sync → Settings → Show status (all setups)**; changes are saved and applied immediately for every setup.
+Set it through **/sync → Settings → Advanced → Show sync status**; changes are saved and applied immediately for every setup.
 When `false`, pi-sync clears and suppresses status text for background checks, manual and automatic transfers, and review attention.
 TUI review widgets and TUI/RPC notifications remain available, and lifecycle cleanup still clears any stale status owned by pi-sync.
 
+### Debug startup timings
+
+The top-level user setting `debug` accepts only `true` or `false` and defaults to `false`.
+Edit `<getAgentDir()>/pi-sync.json` (normally `~/.pi/agent/pi-sync.json`) or use **/sync → Settings → Advanced → Debug startup timings**.
+UI changes save immediately through the existing ordered, atomic settings writer; both manual and UI changes take effect on the next session start, including `/reload`, new, resume, and fork.
+There is no project or environment override.
+
+With `debug: true`, TUI/RPC notifications report local initialization after recovery and settings resolution, then background work when it ends.
+Stages include transaction recovery, settings reads, inspection import, backend initialization, local snapshot, sync state read, remote head, operations import, and automatic transfer when those stages run.
+Automatic-transfer details separate authorization, journal recovery, state and local reads, remote-head reads, snapshot downloads, merge planning, backup, publication, local apply, baseline writes, and cleanup.
+Repeated stages aggregate elapsed time and show a call count. Stage output stays bounded during retries.
+Inspection-and-guards, automatic transfer, journal recovery, and unchanged verification include their nested stages; durations overlap and must not be summed.
+An eligible no-change transfer reports `transfer result: unchanged (fast path)`.
+Totals use a monotonic clock and include waits within each flow, not Pi's complete startup, the initial extension import/factory, or time queued for idle startup transfer.
+Recovery failures before valid settings can be read cannot enable a timing report.
+
+Interrupted stages are marked `interrupted`; cancelled or failed background work is marked `stopped`.
+Session replacement and shutdown suppress late reports from the old session.
+Labels and durations contain no credentials, paths, file contents, remote addresses, or error text.
+No log file or model message is created. Print/JSON produce no timing notifications.
+The setting does not enable automatic sync or transfer, change safety checks, or measure manual/shutdown operations.
+Set `debug` to `false` or remove it, then start a new session to disable reports.
+
 ### Secret scanning
 
 The global `skipSecretScan` setting accepts a boolean and defaults to `false`, including when omitted from an existing version 3 document.
-Set it through **/sync → Settings → Skip secret scan (all setups)**; changes are saved immediately and apply to subsequent pushes for every sync setup, including automatic pushes.
+Set it through **/sync → Settings → Advanced → Skip secret scan**; changes are saved immediately and apply to subsequent pushes for every sync setup, including automatic pushes.
 When `true`, pushes skip the local secret scan; other safety checks and confirmations remain unchanged.
 Enable it only after reviewing the destination and selected content because files containing secrets can be uploaded.
 `/sync doctor` still scans and reports possible secrets regardless of this setting.
@@ -194,7 +221,7 @@ RPC remains a read-only summary with the manual `sync.include` path.
 
 Every new snapshot stores the normalized included-content selection separately from the files that happened to exist.
 This preserves selected-but-missing paths without syncing `pi-sync.json`, storage credentials, automatic-sync preferences, or setup names.
-**Settings → Compare synced content** opens the same review-first flow as a manager operation when local and remote lists differ.
+**Settings → Sync content → Compare included paths** opens the same review-first flow as a manager operation when local and remote lists differ.
 Adoption revalidates the remote head, immutable snapshot, reviewed storage coordinates, and local include list before one atomic settings update.
 The saved state changes only `sync.include`, preserves unknown settings fields, and never pulls files or writes sync state.
 Its explicit Continue action starts a fresh **Sync now** route, while **Done** leaves the reviewed settings change saved without implying a file operation.
@@ -212,11 +239,104 @@ Pull protects the currently open session file; restart Pi or resume a pulled ses
 
 ### 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.
+`sync.automaticTransfer` is optional and accepts only a boolean; absent means `false`. Set it through **/sync → Settings → Sync behavior → Startup transfer**. 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, verified conditional WebDAV, and R2/S3 with verified conditional writes support this policy. A saved On preference is not proof of eligibility: baseline, remote policy, idle ownership, conflicts, secrets, and publication capability are checked again at execution. 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.
+
+#### Unchanged transfer fast path
+
+After pending merge journals are handled, automatic transfer reads a fresh remote head instead of trusting the earlier startup observation.
+It can return without downloading the remote snapshot or writing a baseline only when the head ID/revision and ordered selection match a complete clean merged baseline, local portable hashes match that baseline, and the current ancestor cache is valid and complete for the enabled merge policy.
+Local files, state, settings, idle authorization, and session ownership are rechecked after ancestor reads.
+This path makes no managed-file, remote, baseline, or ancestor-cache changes; it does not re-download and verify an already accepted immutable snapshot or run normal no-transfer retention cleanup.
+
+Manual sync retains the full path. Directional/legacy baselines, missing revisions or selection metadata, unresolved groups, changed policy or content, and missing/invalid/incomplete ancestors also retain the full path.
+Partial-sync setups keep the full path even with no unresolved groups, so snapshot-format upgrades and partial-state maintenance are not skipped.
+A baseline established by a directional push/pull may therefore need one full automatic sync before later starts use the fast path.
+Across startup inspection and transfer, an eligible unchanged setup makes two fresh head reads, with no snapshot download; a normal full no-transfer merge makes three head reads and one snapshot download in addition to inspection.
+
+Turning **Startup transfer** 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.
+
+### Experimental Agent mode
+
+`sync.agentMode` is an optional per-setup boolean, default `false`, in settings versions 3, 4, and 5. Open **Settings → Sync behavior → Agent mode (experimental)** and review the setup, destination, selected paths, model disclosure, costs, and autonomous writes before enabling. RPC users can explicitly set the same field in the private settings file. Setting it to `true` is authorization, not just a display preference.
+
+Agent mode authorizes one eligible merged sync at the next session start and the same autonomous flow from **Sync now** or `/sync sync`. It can publish and replace/delete selected content without another transfer confirmation. It is independent of `sync.automatic` and `sync.automaticTransfer`; neither existing preference is changed. Disabling Startup transfer alone does not disable Agent mode. Saving never starts a transfer from Settings. The atomic write cannot be cancelled after its final cancellation check. A completed save remains in effect after cancellation or session replacement; reopen Settings to read the saved value. TUI/RPC are supported; print/JSON and shutdown do not start a resolver. Agent mode alone adds no polling or daemon. Separately enabled Continuous sync provides recurring work while Pi remains open.
+
+An accepted baseline, matching included-content/local-field policies, and conditional or lease-protected publication remain required. First-source selection, policy migrations, explicit push/pull, and rollback keep their existing reviewed flows. `--yes` does not enable Agent mode or authorize model disclosure. Completed transfers never reload resources automatically.
+
+The resolver uses the initiating session's selected model through Pi's public provider/authentication registry. It has an independent in-memory SDK conversation, no tools, no parent conversation, and no discovered extensions, skills, project instructions, or MCP servers. Only conflict units are disclosed. Settings units contain only the conflicting root fields, with coupled fields kept together; the model selects a complete local or remote unit. Other fields are assembled by deterministic code. For text, the model can replace only overlapping edit hunks; code preserves the other bytes and independent edits. Parent model prompts and tools are not changed. This is configuration isolation, not an OS sandbox or proof of semantic correctness.
+
+Eligible text is global `AGENTS.md` and `.md`/`.txt` files under `prompts/` or `skills/`. Global `settings.json` uses the existing strict JSON, atomic-value, numeric, coupled-field, unknown-field, and machine-local-field policies. Code/scripts, keybindings, binaries, unknown formats, session histories, deletion/modification conflicts, path collisions, and session-root transitions are not model-resolved. Existing deterministic merges still follow their own explicit settings. Unsupported or refused groups remain unresolved; only an explicitly enabled `partialSync` policy permits progress around them. Preserving versions does not mean a conflict is resolved.
+
+A verified accepted ancestor is required. Enabling Agent mode cannot recover historical ancestor bytes that were never retained. If the original accepted bytes are still available on both sides, a conflict-free sync can seed the text ancestors for future runs; otherwise use the existing reviewed recovery flow rather than inventing a base from current edits.
+
+Bounds are 8 KiB per input file, 16 conflict paths/units, 24 KiB of serialized model evidence, 16 KiB of candidate output, 8,192 maximum output tokens (or the selected model's smaller positive output limit), and one provider request per candidate. An unknown model limit of zero retains the resolver cap; invalid limits pause before disclosure. Each resolver has a 20-second deadline; the existing overall startup deadline is 30 seconds. At most two candidate requests are made during one triggered flow when remote commit competition changes the plan. Provider retries are disabled. Invalid output, detected stale evidence, missing model/auth, or recovery uncertainty pauses the flow rather than forcing acceptance. These limits are not an exact currency spending cap; in-flight disclosure or charges cannot be undone by cancellation.
+
+The existing possible-secret scanner always checks model evidence, even when `skipSecretScan` permits uploads without scanning. It is a heuristic, not a guarantee that all secrets are detected. Do not enable Agent mode for content you cannot disclose to the selected provider. Provider errors and model reasoning are not copied into status or persistent records.
+
+Pi sessions sharing one agent directory use one local resolver claim. Other sessions can report deferred without another model request. Inference does not hold the normal sync operation lock; commit rechecks settings, claim ownership, model identity, local bytes, baseline and remote revision. Foreground work, replacement, reload and shutdown cancel/drain the owning task. Another process rechecks authorization before requests and commit; disabling in that process cannot recall an already submitted request. A dead owner's claim can be replaced on a later trigger; unreadable ownership is retained for review. No live claim is removed just because it is old. Claim creation and cleanup share a short-lived cross-process guard. Cleanup does not need the normal operation lock, so another long-running transfer does not retain a completed resolver's claim.
+
+Private claim and content-keyed candidate records reside under `<state-root>/agent-resolver/`, outside snapshots, with private permissions. Candidates can be reused only for matching evidence, policies and model identity, and are validated again. They can contain merged text; retain them as private data. Different candidates are retained without automatic retention pruning. Duplicate provider billing remains possible at crash boundaries. Corrupt or unsafe records block reuse rather than being overwritten blindly.
+
+Pi-sync's cross-process operation lock excludes other pi-sync transfers, not arbitrary writers. Pi file mutation queues coordinate participating writers only within one process. Checks near rename reduce stale writes but do not provide an atomic compare-and-swap against another Pi process or editor. Session JSONL is not rewritten by the model; other active session writers remain subject to the existing protection limitations. Do not use Agent mode as a guarantee of lossless live editing.
+
+Turn Agent mode Off to prevent subsequent requests and invalidate pending authorization. Keep backups, snapshots, conflicts and pending journals; disabling does not undo completed work or erase history. Unknown publication outcomes use the existing journal reconciliation and never authorize blind republishing. Pending journals can be reconciled on a read/check/write/verify backend because recovery does not publish. New autonomous transfers still require conditional or lease-protected publication; turn Agent mode Off before a reviewed manual transfer on a weaker backend. If recovery is blocked, retain evidence and use the existing reviewed recovery routes. Finish/reconcile pending merge journals before a downgrade. No Pi core changes or other extension are required.
+
+### Experimental Continuous sync
+
+`sync.continuous` is an optional per-setup boolean, default `false`, in settings versions 3, 4 and 5. Open **Settings → Sync behavior → Continuous sync (experimental)** after enabling Agent mode. RPC users can set the field explicitly in the private settings file. Existing Agent mode consent does not enable recurring requests.
+
+The separate review names the setup, storage connection, destination, included paths, recurring costs and automatic writes. An elected idle session uses its selected Pi model; a different session can use a different provider/model. The save uses the existing atomic settings writer. Cancellation after the final publication check cannot undo a committed save. Reopen Settings to read the saved value.
+
+#### Activation and ownership
+
+Monitoring starts at an eligible TUI/RPC session startup, after awaited local transaction recovery, or after a foreground `/sync` command or manager closes. It replaces the duplicate one-shot startup transfer, not the legacy shutdown policy. Turning Continuous sync off stops its work without disabling Agent mode. Turning Agent mode off also stops monitoring; a saved Continuous sync On value remains ineffective until Agent mode is enabled again.
+
+A control-file change during monitoring is detected by a watcher or the five-second local control check. If monitoring is already off, external enablement requires the next session start or a foreground `/sync` command. Print/JSON create no continuous resources. No daemon remains after Pi exits.
+
+Upgrade all Pi processes sharing an agent directory before enabling Continuous sync. Older releases do not implement its election or automatic accounting. One scheduler lease coordinates participating sessions/processes sharing the same canonical agent directory. Standbys only check local eligibility/ownership; they do not duplicate remote polling, watchers or inference. Each computer has a separate scheduler. Remote conditional publication and revision checks remain authoritative across computers. The lease does not exclude arbitrary editors or writers in other Pi processes.
+
+Agent work, foreground commands, replacement, reload and shutdown cancel and drain owned work before handoff. Idle work resumes through `agent_settled` or a later eligible check. A busy session does not retain leadership indefinitely. Completed atomic writes or remote commits remain committed even when cancellation occurs later.
+
+#### Detection, retries and safety blocks
+
+Local hints wait for one quiet second. Remote and local snapshots are checked every 60–66 seconds. Missing roots, atomic replacement, unsupported recursive watching and watcher errors retain periodic fallback. Only selected content and control settings generate hints; private caches, backups and scheduler state are excluded.
+
+Local changes and retries can cause extra remote requests between polls. Cycles do not overlap. Each cycle has a 30-second deadline plus underlying cleanup. Changes during a cycle coalesce into one later fresh inspection rather than a queue of stale commands.
+
+Known transient network/server errors and rate limits retry from five seconds with exponential backoff, bounded jitter and a five-minute cap. Valid server Retry-After delays are capped at five minutes. Backoff survives restart and is reset by successful work or relevant configuration changes, not every file event.
+
+Authentication, permissions, disk errors, invalid settings, unsafe evidence and unknown errors stop automatic transfer. Relevant repair, changed evidence or an explicit Sync now action can permit a fresh attempt. Corrupt private records are retained, not replaced with defaults. Local prerequisite checks can detect a repair without network/model work.
+
+Blocked conflicts are inspected for changed evidence, but unchanged refusal/invalid output does not spend another model request. Opaque Pi assistant errors and Git failures without structured transport evidence are not classified from text. Select an available model, repair access, or use the existing review routes as needed.
+
+Missing baselines, changed selection/local-field rules, unsupported conflicts and weak publication capability remain safety blocks. Code, session histories, deletion conflicts and path collisions are not model-resolved. Existing explicit partial-sync policy alone permits independent progress. No background confirmation dialog or automatic resource reload is added.
+
+#### Request limits and private records
+
+The existing per-flow candidate limit, 20-second resolver deadline, input/output bounds, tool/resource isolation and mandatory disclosure scan still apply. Cached candidates must pass current evidence checks before reuse.
+
+Before each automatic provider dispatch, Pi Sync reserves a request in private durable state. Timeouts, cancellation after reservation and uncertain dispatch outcomes consume that reservation. Automatic requests are limited to:
+
+- Two for the same candidate evidence/model contract, across process restart and ownership handoff.
+- Two per replica binding in a rolling 15-minute window, including requests for different candidate keys.
+
+A refusal or invalid output blocks unchanged evidence rather than requesting another completion each poll. When the rolling window is full, Status shows the next eligible attempt. Checks, conflict-free transfers and journal recovery can continue without another model request. When the candidate's two attempts are spent, use changed evidence or an explicit retry. The explicit **Sync now** / `/sync sync` path retains its existing per-flow limits; it does not erase automatic accounting. Opening Status never reserves requests or clears limits.
+
+These limits are not a currency spending cap or an exactly-once billing guarantee. Candidate accounting has a 128 KiB storage bound. A full record blocks work instead of pruning counts and silently granting more requests.
+
+Private records under `<state-root>/continuous/` hold versioned owner/binding metadata, coalesced intent, hashes, safe error categories, timestamps and request counts. They contain no raw credentials, provider errors, reasoning or duplicate conflict text. The binding uses the canonical agent root and setup/destination identity; state-directory migration does not reset accounting. POSIX records are private and use temporary-file-plus-rename publication. Keep the directory as private evidence; do not delete it to repair a transfer.
+
+#### Status, recovery and downgrade
+
+The existing status key shows waiting, checking/syncing, scheduled retry, another local owner, or a stable blocked reason. **Check remote status** and the manager show advisory ownership, the last successful background check/transfer and safe next actions. Notifications are deduplicated by error/evidence/configuration. Status may itself need network access for its existing remote check, but does not call the model.
+
+Pending journals are reconciled before new work, including a newly uncertain publication. Recovery never blindly republishes. An unchanged recovery block is not repeatedly applied. Preserve journals, backups and unresolved versions when proof is unavailable.
 
-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.
+Turn Continuous sync off and drain its owner before downgrade. Reconcile pending transfers with the current release. Existing Agent mode and shutdown preferences remain separately effective. Private scheduler records are separate from baseline/journal formats and remain retained; no automatic filesystem rollback or state migration is performed.
 
-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.
+For implementation evidence and test scope, see [Continuous sync verification](continuous-sync-verification.md).
 
 ### Settings field merge and machine-local fields
 
@@ -232,7 +352,7 @@ Accepted ancestors are private, hash/identity-bound, bounded records below the d
 
 ### 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.
+`sync.mergeContent` and `sync.partialSync` are independent experimental booleans, both default `false`. The owning **Advanced → Content merge / partial progress** setting offers Off, Merge only, Merge + partial, and Partial only 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.
 

package/docs/tui-contract.md

@@ -0,0 +1,61 @@
+# Sync TUI behavior contract
+
+This reference records the setting and transfer contracts used by the TUI. It does not add a settings format or change transfer authorization.
+
+## Settings
+
+All settings are private to this device. There are no project overrides. Defaults and validation are defined in `src/settings/settings-validation.ts` and `src/settings/config.ts`; mutation is owned by `settings-management.ts` and `settings-store.ts`.
+
+| Row | Persisted fields and default | Scope | Save and effective time |
+| --- | --- | --- | --- |
+| Included paths | `sync.include`, explicit array | Current setup | Draft, then exact Save/Discard review; subsequent operations |
+| Compare included paths | `sync.include` | Current setup | Review remote policy and fresh head before save; does not transfer files without explicit Continue |
+| Machine-local fields | `sync.localFields`, absent | Current setup | Input and compatibility review; subsequent snapshots exclude whole settings.json root fields; directional migration required |
+| Automatic sync | `sync.automatic`, explicit boolean; setup proposes Off | Current setup | Immediate save; next session start checks once; subsequent shutdown pushes all selected content only if sessions included; reload skips shutdown push |
+| Startup transfer | `sync.automaticTransfer`, false | Current setup | Immediate save; enabling schedules next session start; independent of Automatic sync |
+| On setup switch | `onSwitch`, `ask-before-pull` | All setups | Immediate save; subsequent switches |
+| Storage location | `storage.bucket`, `branch`, `path` as applicable | Current setup | Reviewed save; changes future destination without moving remote history |
+| Manage sync setups | `syncSetups`, `activeSyncSetup` | This device | Existing reviewed catalog flows; replacing/removing the current setup closes its old settings owner |
+| Manage storage connections | `storageConnections` | Shared by named setups | Existing affected-setup review; changes future operations |
+| Merge settings fields | `sync.mergeSettings`, false | Current setup | Immediate save; experimental merge on subsequent sync with a verified ancestor |
+| Content merge / partial progress | `sync.mergeContent`, `sync.partialSync`, false/false | Current setup | Explicit compatibility review and atomic save; Off, Merge only, Merge + partial, Partial only preserve all combinations |
+| Skip secret scan | `skipSecretScan`, false | All setups | Immediate save; subsequent manual/automatic pushes; Diagnostics still scans |
+| Show sync status | `showStatus`, true | All setups | Immediate save and immediate status visibility change; notifications/widgets remain |
+| Debug startup timings | `debug`, false | All setups | Immediate save; fixed-label duration notifications from the next session start; TUI/RPC only |
+
+Opening foreground Settings cancels and drains startup work. Back does not undo successful saves; cancelling a draft or compatibility review leaves that change unsaved. A failed save retains the previous document and effective/displayed value. Completed transfers are never undone by changing a preference.
+
+Writers queue the complete read-modify-write operation, hold the cross-process lock through validation and same-directory atomic replacement, preserve unknown fields and private permissions, and refuse invalid existing files. UI changes do not replace those writers.
+
+## Presentation decisions
+
+Settings opens four task categories: Sync content, Sync behavior, Storage & setups, and Advanced. All settings (search) exposes the same rows for cross-category native-style typing-to-search. Each category uses the same row definitions and action handlers; navigation headings are not fake settings. Back returns one level; hard Ctrl+C closes the flow. No `/ Search` hint is added because slash is ordinary search text.
+
+The existing public Kit settings adapter is retained rather than adding a second selector or accessing private Pi fields. Installed `SettingsList` provides `updateValue()` and `selectItem()`, but has no injected keybinding or awaited-save/rejection contract and does not expose search focus. Kit already owns ordered pending changes, rollback, retained search/selection, IME focus, bounded frames, and clipped mouse coordinates. This is an intentional existing deviation from the literal native-component convention. No new Kit API, dependency floor, or release is required. A package-owned public rendering boundary returns no lines at zero width and retains the selected row (or search when nothing matches) below five content rows; compact mouse events map back to the original rendered row. It does not access private component state or add key handlers. Search placeholder and position-footer relocation remain unsupported by that public API; the existing native-style hints and position indicator are retained rather than patched through private fields.
+
+Last applied shows a compact opaque snapshot ID and explicitly states that application time is unavailable. History retains the full recorded ID even when the remote history no longer lists that snapshot. Snapshot `createdAt` is not a local application time; opening the manager performs no remote timestamp fetch.
+
+Startup transfer summaries report the preference and prerequisites, not a claim that a transfer is eligible now. Runtime evidence in `merged-sync.ts` and `s3/s3-backend.ts` permits Git, conditional WebDAV, and R2/S3 with verified conditional writes. `read-check-write-verify` publication is refused for automatic operations. Baseline, matching authoritative include policy, idle ownership, and conflict/secret checks remain mandatory. This corrects the earlier settings reference's manual-only R2/S3 statement without expanding backend authorization.
+
+## Transfer review matrix
+
+| Branch | Review and effect | Freshness / acceptance evidence |
+| --- | --- | --- |
+| Sync now, empty selection | Warning; no useful transfer | `empty-policy-acceptance.test.ts` |
+| Sync now, first sync / empty remote | Existing decision or reviewed directional Pull/Push | `sync.test.ts`, `sync-decision.test.ts`; selection/policy checks remain |
+| Sync now, equal files | Existing no-op or baseline acceptance; not represented as file changes | `sync.test.ts`, `sync-inspection.test.ts` |
+| Pull | Remote → local counts and paths; protected loaded session excluded; backup before apply | `sync-mutations.ts`: settings, local hashes, head and baseline rechecked before commit; `recovery-pull-freshness.test.ts`, `local-field-pull-policy.test.ts` |
+| Push | Local → remote active snapshot counts and paths; preserve eligible unmanaged content; removals do not erase retained history | `sync-mutations.ts`: fresh interactive before-image, local hashes/settings/baseline rechecked, expected-head publication; `backend-orchestration.test.ts`, `review-feedback.test.ts` |
+| Forced Pull/Push | Same directional review, not a bypass of conditional publication | Refreshed force-push plan requires new approval; migration confirmation remains mandatory even with `--yes`; `sync-state-revision.test.ts`, `local-field-migration.test.ts` |
+| Merge / partial progress | Effective before/after snapshots, local/remote counts, conflicts/withheld groups, backups and publication | Existing scrollable review; recheck settings, hashes, state and remote before journal/apply; `merged-sync-confirmation.test.ts`, `partial-directional-progress.test.ts`, `merged-sync-summary.test.ts` |
+| Conflicts | Review complete dependency group and separately choose authority | Artifact fingerprint, group versions, baseline, config, owner and head checks; `conflict-confirmation.test.ts`, `conflict-preview.test.ts` |
+| Case-variant cleanup | Pull/rollback include the apply engine’s additional top-level alias removals, even when canonical snapshot bytes are unchanged | `apply-review.ts` uses the authoritative apply planner, streams file hashes, records symlink identity without following its target, and rechecks the complete alias set before commit; `transfer-preview.test.ts` covers changed, added, removed, cancelled and symlink aliases plus descriptor cleanup on cancellation. Merge preflight rejects noncanonical changed targets instead of deleting aliases. |
+| History rollback | Historical snapshot → local and active remote head; backup and protected-session summary | Settings, local bytes, current head, selected backend/setup and baseline rechecked; `history-confirmation-cancellation.test.ts`, `history-cancellation.test.ts`, `rollback-field-policy.test.ts` |
+| Explicit `--yes` | Existing documented review bypass only | Mandatory migration and operation safety remain; existing route suites |
+| Automatic startup / shutdown | No new modal; existing opt-in, capability, idle, all-or-nothing conflict and secret policies | `automatic-transfer.test.ts`, `startup-check.test.ts`, `backend-orchestration.test.ts` |
+
+TUI Pull and Push reviews reuse the existing scrollable safe-default confirmation and exact Details document; RPC and History rollback retain their observable confirmation protocols. The existing History dialog ownership/cancellation flow is not replaced. All changed counts come from effective snapshot differences rather than raw merge decisions. Protected paths, preserved remote files, merged bytes, and withheld paths must be accounted for before rendering. Cancellation performs no transfer; pre-commit preparation may retain recovery evidence. After the commit boundary, existing completion/recovery rules apply instead of promising undo.
+
+## Review boundaries
+
+This change does not touch model prompts, tool exposure, shared-terminal handoff, settings formats, credentials, or default sync policies. Existing startup/session signals and Kit/custom-interaction disposal own new UI calls. Any awaited review is followed by owner validation, and each mutating operation revalidates its mutable inputs before its existing commit boundary. Status and differences actions use existing routes; manager opening/refresh remains observational and does not contact the remote. Diagnostics discloses its WebDAV write/repair behavior before execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-sync",
-  "version": "0.54.2",
+  "version": "0.56.0",
   "description": "Pi extension that syncs Pi configuration through Git, WebDAV, Cloudflare R2, or S3-compatible storage.",
   "type": "module",
   "license": "MIT",
@@ -52,7 +52,8 @@
     "typescript": "7.0.2"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=1.0.2",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
     "@earendil-works/pi-tui": "*"
   },
   "repository": {

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

@@ -4,6 +4,7 @@ import path from "node:path";
 import { posixJoin } from "../../paths.js";
 import type { Snapshot, SnapshotFile } from "../../snapshot/snapshot-types.js";
 import { stateDir } from "../../state/state-directory.js";
+import { throwIfAborted } from "../../sync/signals.js";
 import { syncErrorGuidance } from "../../sync/sync-error-guidance.js";
 import type { ResolvedGitBackend } from "../backend-types.js";
 import {
@@ -781,7 +782,3 @@ function sha256(value: Buffer) {
 function abortReason(signal: AbortSignal) {
   return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
 }
-
-function throwIfAborted(signal?: AbortSignal) {
-  if (signal?.aborted) throw abortReason(signal);
-}

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

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import process from "node:process";
+import { throwIfAborted } from "../../sync/signals.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_OUTPUT_LIMIT = 1024 * 1024;
@@ -252,8 +253,3 @@ export async function readGitBlobs(
   });
   return parseGitBlobBatch(result.stdout, objects.length, options.maxOutputBytes);
 }
-
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}

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

@@ -4,9 +4,11 @@ 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 { throwIfAborted } from "../../sync/signals.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";
+import { createLatestPointer, remoteHistoryEntry } from "../snapshot-pointer.js";
 import {
   type BackendDiagnostic,
   type ExpectedRemoteHead,
@@ -318,16 +320,7 @@ export function storageRoot(config: ResolvedS3Backend) {
 }
 
 export function pointerFor(config: ResolvedS3Backend, snapshot: Snapshot, checksum: string): LatestPointer {
-  return {
-    version: VERSION,
-    profile: config.destination.namespace,
-    snapshot: snapshot.id,
-    sha256: checksum,
-    createdAt: snapshot.createdAt,
-    machine: snapshot.machine,
-    syncSessions: snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/")),
-    ...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
-  };
+  return createLatestPointer(config.destination.namespace, snapshot, checksum);
 }
 
 export function s3BackendIdentity(config: ResolvedS3Backend) {
@@ -365,16 +358,6 @@ function trimSlashes(value: string) {
   return value.replace(/^\/+|\/+$/g, "");
 }
 
-function remoteHistoryEntry(pointer: LatestPointer): RemoteHistoryEntry {
-  return {
-    snapshotRef: pointer.snapshot,
-    snapshotId: pointer.snapshot,
-    createdAt: pointer.createdAt,
-    machine: pointer.machine,
-    syncSessions: pointer.syncSessions === true,
-  };
-}
-
 function remoteHead(pointer: LatestPointer, identity: string, etag?: string): RemoteHead {
   return {
     snapshotRef: pointer.snapshot,
@@ -529,11 +512,6 @@ function hasControlCharacter(value: string) {
   });
 }
 
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}
-
 function sha256(value: Buffer) {
   return createHash("sha256").update(value).digest("hex");
 }

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

@@ -1,6 +1,7 @@
 import { createHash, createHmac } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
 import { encodeKey, posixJoin } from "../../paths.js";
+import { retryAfter } from "../../sync/continuous-errors.js";
 import type { RemoteObject, ResolvedS3Backend } from "../backend-types.js";
 
 const MAX_JSON_RESPONSE_BYTES = 1024 * 1024;
@@ -34,6 +35,7 @@ export class S3HttpError extends Error {
   constructor(
     message: string,
     readonly status: number,
+    readonly retryAfterMs?: number,
   ) {
     super(message);
     this.name = "S3HttpError";
@@ -81,7 +83,11 @@ export class S3Client {
       const object = await this.request("GET", key);
       if (object.status === 404) return { missing: true };
       if (!object.ok) {
-        throw new S3HttpError(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`, object.status);
+        throw new S3HttpError(
+          `S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+          object.status,
+          retryAfter(object),
+        );
       }
       const body = await readBoundedText(object, MAX_JSON_RESPONSE_BYTES, "S3 JSON response");
       // R2 can intermittently return an empty 200 body (read-after-write
@@ -111,7 +117,11 @@ export class S3Client {
       const object = await this.request("GET", key);
       if (object.status === 404) return { missing: true };
       if (!object.ok) {
-        throw new S3HttpError(`S3 GET failed (${object.status}): ${await this.readErrorText(object)}`, object.status);
+        throw new S3HttpError(
+          `S3 GET failed (${object.status}): ${await this.readErrorText(object)}`,
+          object.status,
+          retryAfter(object),
+        );
       }
       const buffer = await readBoundedBuffer(object, MAX_SNAPSHOT_RESPONSE_BYTES, "S3 snapshot response");
       // R2 can intermittently return an empty 200 body on a long-lived
@@ -158,6 +168,7 @@ export class S3Client {
       throw new S3HttpError(
         `S3 PUT failed (${response.status}): ${await this.readErrorText(response)}`,
         response.status,
+        retryAfter(response),
       );
     }
     await response.body?.cancel();
@@ -169,6 +180,7 @@ export class S3Client {
       throw new S3HttpError(
         `S3 DELETE failed (${response.status}): ${await this.readErrorText(response)}`,
         response.status,
+        retryAfter(response),
       );
     }
     await response.body?.cancel();

package/src/backends/snapshot-pointer.ts

@@ -0,0 +1,27 @@
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import type { LatestPointer } from "./backend-types.js";
+import type { RemoteHistoryEntry } from "./sync-backend.js";
+
+/** Shared latest/history metadata for the S3 and WebDAV object-store format. */
+export function createLatestPointer(namespace: string, snapshot: Snapshot, checksum: string): LatestPointer {
+  return {
+    version: 1,
+    profile: namespace,
+    snapshot: snapshot.id,
+    sha256: checksum,
+    createdAt: snapshot.createdAt,
+    machine: snapshot.machine,
+    syncSessions: snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/")),
+    ...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
+  };
+}
+
+export function remoteHistoryEntry(pointer: LatestPointer): RemoteHistoryEntry {
+  return {
+    snapshotRef: pointer.snapshot,
+    snapshotId: pointer.snapshot,
+    createdAt: pointer.createdAt,
+    machine: pointer.machine,
+    syncSessions: pointer.syncSessions === true,
+  };
+}

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

@@ -2,9 +2,11 @@ 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 { throwIfAborted } from "../../sync/signals.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";
+import { createLatestPointer, remoteHistoryEntry } from "../snapshot-pointer.js";
 import {
   type BackendDiagnostic,
   type ExpectedRemoteHead,
@@ -84,7 +86,7 @@ export class WebDavSyncBackend implements SyncBackend {
     await client.ensureCollection(snapshotsPath(this.config));
     const encoded = await encodeSnapshot(snapshot);
     throwIfAborted(options.signal);
-    const pointer = pointerFor(this.config, snapshot, sha256(encoded));
+    const pointer = createLatestPointer(this.config.destination.namespace, snapshot, sha256(encoded));
     const stagedPath = snapshotPath(this.config, snapshot.id);
     try {
       await client.putBuffer(stagedPath, encoded, "application/gzip", { ifAbsent: true });
@@ -392,19 +394,6 @@ function webDavStorageLocation(config: ResolvedWebDavBackend) {
   return `${url.host} · ${config.destination.path}`;
 }
 
-function pointerFor(config: ResolvedWebDavBackend, snapshot: Snapshot, checksum: string): LatestPointer {
-  return {
-    version: VERSION,
-    profile: config.destination.namespace,
-    snapshot: snapshot.id,
-    sha256: checksum,
-    createdAt: snapshot.createdAt,
-    machine: snapshot.machine,
-    syncSessions: snapshot.syncSessions === true || snapshot.files.some((file) => file.path.startsWith("sessions/")),
-    ...(snapshot.selection === undefined ? {} : { selection: snapshot.selection }),
-  };
-}
-
 function remoteHead(pointer: LatestPointer, identity: string, etag?: string): RemoteHead {
   return {
     snapshotRef: pointer.snapshot,
@@ -490,16 +479,6 @@ function requireHistory(value: { version: number; snapshots: LatestPointer[] } |
   return pointers;
 }
 
-function remoteHistoryEntry(pointer: LatestPointer): RemoteHistoryEntry {
-  return {
-    snapshotRef: pointer.snapshot,
-    snapshotId: pointer.snapshot,
-    createdAt: pointer.createdAt,
-    machine: pointer.machine,
-    syncSessions: pointer.syncSessions === true,
-  };
-}
-
 function assertSnapshotIdentity(snapshot: Snapshot, namespace: string) {
   validatePortableSnapshot(snapshot);
   if (
@@ -637,11 +616,6 @@ function sha256(value: Buffer) {
   return createHash("sha256").update(value).digest("hex");
 }
 
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}
-
 function errorMessage(error: unknown) {
   if (error instanceof WebDavHttpError) return error.message;
   return error instanceof Error ? error.message : String(error);

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

@@ -1,4 +1,6 @@
 import { XMLParser } from "fast-xml-parser";
+import { ContinuousError, continuousFailure, retryAfter } from "../../sync/continuous-errors.js";
+import { throwIfAborted } from "../../sync/signals.js";
 import type { RemoteObject, ResolvedWebDavBackend } from "../backend-types.js";
 
 const JSON_LIMIT = 1024 * 1024;
@@ -24,6 +26,7 @@ export class WebDavHttpError extends Error {
     message: string,
     readonly status: number,
     options?: ErrorOptions,
+    readonly retryAfterMs?: number,
   ) {
     super(message, options);
     this.name = "WebDavHttpError";
@@ -231,7 +234,12 @@ export class WebDavClient {
       .replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
       .trim();
     const detail = body ? `: ${redactText(body, this.config)}` : "";
-    throw new WebDavHttpError(`WebDAV ${action} failed with HTTP ${response.status}${detail}`, response.status);
+    throw new WebDavHttpError(
+      `WebDAV ${action} failed with HTTP ${response.status}${detail}`,
+      response.status,
+      undefined,
+      retryAfter(response),
+    );
   }
 }
 
@@ -342,7 +350,8 @@ function safeUrl(url: URL) {
 
 function redactError(error: unknown, config: ResolvedWebDavBackend) {
   const message = error instanceof Error ? error.message : String(error);
-  return new Error(redactText(message, config));
+  const failure = continuousFailure(error);
+  return new ContinuousError(failure.kind, redactText(message, config), failure.delay);
 }
 
 function redactText(value: string, config: ResolvedWebDavBackend) {
@@ -359,8 +368,3 @@ function redactText(value: string, config: ResolvedWebDavBackend) {
 function escapeRegExp(value: string) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
-
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}