@narumitw/pi-sync 0.54.3 → 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)
 
@@ -134,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.
 
@@ -255,6 +257,87 @@ Across startup inspection and transfer, an eligible unchanged setup makes two fr
 
 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.
+
+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.
+
+For implementation evidence and test scope, see [Continuous sync verification](continuous-sync-verification.md).
+
 ### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narumitw/pi-sync",
-  "version": "0.54.3",
+  "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");
-}

package/src/commands/command-execution.ts

@@ -5,6 +5,7 @@ import { localConfigTemplate, readLocalConfigObject } from "../settings/settings
 import type { AnySyncConfig } from "../settings/settings-types.js";
 import { unlock, withLock } from "../state/lock.js";
 import { migrateLegacyStateDirectory, stateDirectoryMigrationNotice } from "../state/state-directory.js";
+import { withAgentSyncLock } from "../sync/agent-sync.js";
 import { throwIfAborted } from "../sync/signals.js";
 import { syncErrorGuidance } from "../sync/sync-error-guidance.js";
 import { isSyncDecisionRequiredError, SetupPullRequiresUiError } from "../sync/sync-errors.js";
@@ -49,7 +50,7 @@ export async function executeRecoveryCommand(
       const outcome = await withLock("pull", () => operations.pull(ctx, options));
       return { kind: "completed", ...(outcome ? { outcome } : {}) };
     }
-    await withLock("sync", () => operations.syncBoth(ctx, options));
+    await withAgentSyncLock(ctx, options, (current) => operations.syncBoth(ctx, current));
     return { kind: "completed" };
   } catch (error) {
     if (signal?.aborted) return { kind: "failed" };
@@ -156,7 +157,7 @@ export async function executeCommand(
       case "sync": {
         const operations = await loaders.operations();
         throwIfAborted(options.signal);
-        await withLock("sync", () => operations.syncBoth(ctx, options));
+        await withAgentSyncLock(ctx, options, (current) => operations.syncBoth(ctx, current));
         return { kind: "completed" };
       }
       case "history": {
@@ -258,6 +259,8 @@ async function showConfig(ctx: ExtensionCommandContext, options: CommandOptions)
       `settings field merge: ${config.mergeSettings ? "On (experimental)" : "Off"}`,
       `machine-local settings.json fields: ${(config.localFields ?? []).map(safeTerminalText).join(", ") || "none"}`,
       `startup transfer: ${startupTransferSummary(config)}`,
+      `agent mode: ${config.agentMode ? "On (experimental)" : "Off"}`,
+      `continuous sync: ${config.continuous ? (config.agentMode ? "On (experimental)" : "paused; Agent mode is Off") : "Off"}`,
       `included content: ${config.include.join(", ") || "none"}`,
       `sessions: ${config.include.includes("sessions") ? "included" : "not included"}`,
       `settings file: ${localConfigPath()}`,

package/src/commands/command-handler.ts

@@ -13,7 +13,7 @@ import {
   syncAttentionMatchesConfig,
 } from "../ui/sync-attention.js";
 import { setSyncStatus } from "../ui/sync-status.js";
-import { parseOptions, splitArgs } from "./command.js";
+import { parseOptions, splitArgs, validateCommandOptions } from "./command.js";
 import { executeCommand, executeRecoveryCommand } from "./command-execution.js";
 
 export async function handleCommand(
@@ -22,6 +22,7 @@ export async function handleCommand(
   sessionSignal: AbortSignal,
   loaders: SyncLoaders,
   attention: SyncAttentionController,
+  onExplicitSync?: (setup?: string) => void,
 ) {
   await reconcileObservation(attention, sessionSignal);
   if (sessionSignal.aborted) return;
@@ -31,8 +32,18 @@ export async function handleCommand(
     onCommit?: () => void,
     target?: string,
     onDialog?: (active: boolean) => void,
-  ) =>
-    executeCommand(
+  ) => {
+    const [command, ...args] = splitArgs(route);
+    if (command === "sync") {
+      try {
+        const options = parseOptions(args);
+        validateCommandOptions("sync", options);
+        onExplicitSync?.(target ?? options.setup);
+      } catch {
+        /* Invalid routes do not request an automatic retry. */
+      }
+    }
+    return executeCommand(
       route,
       ctx,
       combineSignals(sessionSignal, signal),
@@ -41,6 +52,7 @@ export async function handleCommand(
       target,
       onDialog,
     );
+  };
   if (!rawArgs.trim()) {
     try {
       const { showSyncManager } = await import("../ui/manager-ui.js");

package/src/commands/command-types.ts

@@ -1,3 +1,5 @@
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { AgentAcceptance } from "../sync/agent-request.js";
 import type { StartupTimings } from "../sync/startup-timings.js";
 
 export interface CommandOptions {
@@ -12,6 +14,10 @@ export interface CommandOptions {
   onCommit?: () => void;
   /** In-memory startup diagnostics only; never persisted or sent to a backend. */
   startupTimings?: StartupTimings;
+  /** Internal validated resolver result; never parsed from command arguments. */
+  agentAcceptance?: AgentAcceptance;
+  /** Internal cycle authorization, ownership and durable request reservation; never command arguments. */
+  background?: { validate(config?: AnySyncConfig): void; reserve(key: string): Promise<void> };
   args: string[];
 }
 

package/src/commands/command.ts

@@ -236,6 +236,7 @@ export function usage() {
     `Automatic sync: ${AUTOMATIC_SYNC_DESCRIPTION}`,
     `Startup transfer: ${STARTUP_TRANSFER_DESCRIPTION}`,
     "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.",
+    "Experimental Continuous sync is a separate default-Off opt-in in Settings. It requires Agent mode, monitors while Pi is open, and can incur recurring network/model costs. Safety blocks and durable automatic request limits remain.",
     "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

@@ -80,6 +80,8 @@ export async function loadPartialConfig(setupName?: string): Promise<PartialConf
     include: [...config.include],
     automatic: config.automatic,
     automaticTransfer: config.automaticTransfer ?? false,
+    agentMode: config.agentMode ?? false,
+    continuous: config.continuous ?? false,
     onSwitch: config.onSwitch,
     showStatus: config.showStatus,
   };
@@ -115,10 +117,13 @@ export function syncConfigReviewIdentity(config: AnySyncConfig) {
     config.include,
     config.automatic,
     config.automaticTransfer ?? false,
+    config.agentMode ?? false,
     config.localFields,
     config.mergeSettings ?? false,
     config.mergeContent ?? false,
     config.partialSync ?? false,
+    // Preserve existing Off identities and cached candidates across the upgrade.
+    ...(config.continuous ? ["continuous"] : []),
   ]);
 }
 
@@ -166,6 +171,8 @@ function resolveSyncConfig(
     include,
     automatic: setup.sync.automatic,
     automaticTransfer: setup.sync.automaticTransfer ?? false,
+    agentMode: setup.sync.agentMode ?? false,
+    continuous: setup.sync.continuous ?? false,
     localFields: setup.sync.localFields === undefined ? undefined : normalizeLocalFields(setup.sync.localFields),
     mergeSettings: setup.sync.mergeSettings ?? false,
     mergeContent: setup.sync.mergeContent ?? false,

package/src/settings/settings-store.ts

@@ -1,6 +1,3 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { localConfigPath, readMigratingLocalConfigDocument, updateLocalConfigDocument } from "./config-file.js";
 import type { OnSwitchAction, PiSyncSettingsV3 } from "./settings-types.js";
 import { DEFAULT_ON_SWITCH, validateSettingsDocument } from "./settings-validation.js";
@@ -63,34 +60,3 @@ export function updateLocalConfig(update: (current: PiSyncSettingsV3) => PiSyncS
 async function performLocalConfigUpdate(update: (current: PiSyncSettingsV3) => PiSyncSettingsV3, signal?: AbortSignal) {
   return updateLocalConfigDocument(localConfigTemplate(), update, validateSettingsDocument, signal);
 }
-
-export async function writeLocalConfigObject(value: PiSyncSettingsV3 | Record<string, unknown>) {
-  validateSettingsDocument(value as Record<string, unknown>);
-  const configPath = localConfigPath();
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  try {
-    const stat = await fs.lstat(configPath);
-    if (stat.isSymbolicLink()) throw new Error(`Refusing to overwrite symlinked pi-sync settings: ${configPath}`);
-    if (!stat.isFile()) throw new Error(`pi-sync settings are not a regular file: ${configPath}`);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-  const temporaryPath = path.join(
-    path.dirname(configPath),
-    `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`,
-  );
-  let handle: fs.FileHandle | undefined;
-  try {
-    handle = await fs.open(temporaryPath, "wx", 0o600);
-    await handle.writeFile(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
-    if (process.platform !== "win32") await handle.chmod(0o600);
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-    await fs.rename(temporaryPath, configPath);
-  } catch (error) {
-    await handle?.close().catch(() => undefined);
-    await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
-    throw error;
-  }
-}

package/src/settings/settings-types.ts

@@ -81,6 +81,10 @@ export interface SyncPolicySettings {
   automatic: boolean;
   /** Explicit opt-in, separate from the legacy observe/shutdown policy. */
   automaticTransfer?: boolean;
+  /** Experimental autonomous merged-sync authorization. */
+  agentMode?: boolean;
+  /** Separate explicit authorization for recurring background work. */
+  continuous?: boolean;
   /** Version 4: settings.json root fields never uploaded. */
   localFields?: string[];
   mergeSettings?: boolean;
@@ -116,6 +120,8 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
   include: string[];
   automatic: boolean;
   automaticTransfer?: boolean;
+  agentMode?: boolean;
+  continuous?: boolean;
   localFields?: string[];
   mergeSettings?: boolean;
   mergeContent?: boolean;
@@ -139,6 +145,8 @@ export interface PartialConfig {
   include: string[];
   automatic: boolean;
   automaticTransfer?: boolean;
+  agentMode?: boolean;
+  continuous?: boolean;
   onSwitch: OnSwitchAction;
   showStatus: boolean;
   bucket?: string;