@alfe.ai/openclaw-sync 0.3.6 → 0.3.7

package/dist/sync-engine.js

@@ -1,11 +1,58 @@
-import { appendFile, copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { appendFile, copyFile, lstat, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createReadStream, existsSync, readFileSync } from "node:fs";
 import { createHash } from "node:crypto";
-import { basename, dirname, extname, join } from "node:path";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import micromatch from "micromatch";
 import { createLogger } from "@auriclabs/logger";
+//#region src/path-contract.ts
+/**
+* Canonical path contract for the private workspace sync data plane.
+*
+* Paths received from manifests, relays, CLI arguments, and watcher events
+* are identifiers relative to the configured workspace. Keep validation in
+* one place so a malformed remote path can never become an arbitrary local
+* read, write, or delete.
+*/
+const MAX_SYNC_PATH_LENGTH = 1024;
+function validatePrivateRelativePath(relativePath) {
+	if (relativePath.length === 0 || relativePath.length > MAX_SYNC_PATH_LENGTH || relativePath.includes("\0") || relativePath.includes("\\") || isAbsolute(relativePath)) throw new Error("Invalid private sync path");
+	const segments = relativePath.split("/");
+	if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) throw new Error("Invalid private sync path");
+	if (segments[0] === "shared") throw new Error("The shared workspace tree is not part of private sync");
+	return segments.join("/");
+}
+function resolvePrivateWorkspacePath(workspacePath, relativePath) {
+	const canonical = validatePrivateRelativePath(relativePath);
+	const workspace = resolve(workspacePath);
+	const absolutePath = resolve(workspace, canonical);
+	const fromWorkspace = relative(workspace, absolutePath);
+	if (fromWorkspace === "" || fromWorkspace === ".." || fromWorkspace.startsWith(`..${sep}`) || isAbsolute(fromWorkspace)) throw new Error("Private sync path escapes the workspace");
+	return absolutePath;
+}
+/**
+* Reject an existing symlink in any path component. Lexical containment alone
+* is insufficient: `workspace/link/file` can escape when `link` points out of
+* the workspace. This check covers reads, writes, and parent-directory walks.
+*/
+async function assertNoSymlinkTraversal(workspacePath, relativePath) {
+	const canonical = validatePrivateRelativePath(relativePath);
+	const absolutePath = resolvePrivateWorkspacePath(workspacePath, canonical);
+	const segments = canonical.split("/");
+	let current = resolve(workspacePath);
+	for (const segment of segments) {
+		current = resolve(current, segment);
+		try {
+			if ((await lstat(current)).isSymbolicLink()) throw new Error("Private sync path crosses a symbolic link");
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") break;
+			throw error;
+		}
+	}
+	return absolutePath;
+}
+//#endregion
 //#region src/manifest.ts
 /**
 * AlfeSync manifest — local file manifest at `~/.alfe/sync/manifest.json`.
@@ -25,6 +72,9 @@ import { createLogger } from "@auriclabs/logger";
 */
 const SYNC_STATE_DIR = join(homedir(), ".alfe", "sync");
 const MANIFEST_FILE = "manifest.json";
+const MANIFEST_LOCK_FILE = "manifest.lock";
+const MANIFEST_LOCK_TIMEOUT_MS = 1e4;
+const MANIFEST_LOCK_STALE_MS = 6e4;
 /**
 * Resolve the manifest file path. Lives under `~/.alfe/sync/`, independent
 * of the workspace path — one agent has one manifest.
@@ -32,6 +82,82 @@ const MANIFEST_FILE = "manifest.json";
 function manifestPath() {
 	return join(SYNC_STATE_DIR, MANIFEST_FILE);
 }
+function manifestLockPath() {
+	return join(SYNC_STATE_DIR, MANIFEST_LOCK_FILE);
+}
+async function readManifestUnlocked() {
+	try {
+		const raw = await readFile(manifestPath(), "utf-8");
+		const parsed = JSON.parse(raw);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { files: {} };
+		const candidate = parsed;
+		const files = candidate.files;
+		if (typeof files !== "object" || files === null || Array.isArray(files)) return { files: {} };
+		const validFiles = {};
+		for (const [relativePath, value] of Object.entries(files)) {
+			try {
+				validatePrivateRelativePath(relativePath);
+			} catch {
+				continue;
+			}
+			if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+			const entry = value;
+			if (typeof entry.hash !== "string" || typeof entry.size !== "number" || !Number.isFinite(entry.size) || entry.size < 0 || typeof entry.lastSynced !== "string" || entry.storageClass !== "STANDARD" && entry.storageClass !== "GLACIER_IR") continue;
+			validFiles[relativePath] = {
+				hash: entry.hash,
+				size: entry.size,
+				lastSynced: entry.lastSynced,
+				storageClass: entry.storageClass
+			};
+		}
+		return {
+			files: validFiles,
+			...typeof candidate.agentId === "string" ? { agentId: candidate.agentId } : {}
+		};
+	} catch {
+		return { files: {} };
+	}
+}
+async function writeManifestUnlocked(manifest) {
+	await mkdir(SYNC_STATE_DIR, { recursive: true });
+	const target = manifestPath();
+	const temporary = `${target}.${String(process.pid)}.${String(Date.now())}.tmp`;
+	try {
+		await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+		await rename(temporary, target);
+	} catch (error) {
+		await unlink(temporary).catch(() => void 0);
+		throw error;
+	}
+}
+async function withManifestLock(operation) {
+	await mkdir(SYNC_STATE_DIR, { recursive: true });
+	const lockPath = manifestLockPath();
+	const deadline = Date.now() + MANIFEST_LOCK_TIMEOUT_MS;
+	for (;;) {
+		let handle;
+		try {
+			handle = await open(lockPath, "wx");
+		} catch (error) {
+			if ((error instanceof Error && "code" in error ? error.code : void 0) !== "EEXIST") throw error;
+			const lockStat = await stat(lockPath).catch(() => null);
+			if (lockStat && Date.now() - lockStat.mtimeMs > MANIFEST_LOCK_STALE_MS) {
+				await unlink(lockPath).catch(() => void 0);
+				continue;
+			}
+			if (Date.now() >= deadline) throw new Error("Timed out waiting for the local sync manifest lock");
+			await new Promise((resolve) => setTimeout(resolve, 25));
+			continue;
+		}
+		try {
+			await handle.writeFile(`${String(process.pid)}\n`, "utf-8");
+			return await operation();
+		} finally {
+			await handle.close().catch(() => void 0);
+			await unlink(lockPath).catch(() => void 0);
+		}
+	}
+}
 /**
 * Read the local manifest. Returns empty manifest if not found.
 *
@@ -40,31 +166,25 @@ function manifestPath() {
 * `~/.alfe/sync/` regardless of which workspace the call comes from.
 */
 async function readManifest(workspacePath) {
-	const path = manifestPath();
-	if (!existsSync(path)) return { files: {} };
-	try {
-		const raw = await readFile(path, "utf-8");
-		return JSON.parse(raw);
-	} catch {
-		return { files: {} };
-	}
+	if (!existsSync(manifestPath())) return { files: {} };
+	return readManifestUnlocked();
 }
 /**
 * Write the local manifest. `workspacePath` is accepted for call-site
 * symmetry but unused (see `readManifest`).
 */
 async function writeManifest(workspacePath, manifest) {
-	const path = manifestPath();
-	await mkdir(SYNC_STATE_DIR, { recursive: true });
-	await writeFile(path, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+	await withManifestLock(() => writeManifestUnlocked(manifest));
 }
 /**
 * Update a single file entry in the local manifest.
 */
 async function updateManifestEntry(workspacePath, relativePath, entry) {
-	const manifest = await readManifest(workspacePath);
-	manifest.files[relativePath] = entry;
-	await writeManifest(workspacePath, manifest);
+	await withManifestLock(async () => {
+		const manifest = await readManifestUnlocked();
+		manifest.files[relativePath] = entry;
+		await writeManifestUnlocked(manifest);
+	});
 }
 /**
 * Update many file entries in one read-modify-write pass.
@@ -75,18 +195,22 @@ async function updateManifestEntry(workspacePath, relativePath, entry) {
 * "identical → heal" pass). Optionally stamps the owning agentId.
 */
 async function updateManifestEntries(workspacePath, entries, options = {}) {
-	const manifest = await readManifest(workspacePath);
-	Object.assign(manifest.files, entries);
-	if (options.agentId) manifest.agentId = options.agentId;
-	await writeManifest(workspacePath, manifest);
+	await withManifestLock(async () => {
+		const manifest = await readManifestUnlocked();
+		Object.assign(manifest.files, entries);
+		if (options.agentId) manifest.agentId = options.agentId;
+		await writeManifestUnlocked(manifest);
+	});
 }
 /**
 * Remove a file entry from the local manifest.
 */
 async function removeManifestEntry(workspacePath, relativePath) {
-	const manifest = await readManifest(workspacePath);
-	manifest.files = Object.fromEntries(Object.entries(manifest.files).filter(([key]) => key !== relativePath));
-	await writeManifest(workspacePath, manifest);
+	await withManifestLock(async () => {
+		const manifest = await readManifestUnlocked();
+		manifest.files = Object.fromEntries(Object.entries(manifest.files).filter(([key]) => key !== relativePath));
+		await writeManifestUnlocked(manifest);
+	});
 }
 /**
 * Compute SHA-256 hash of a file using streaming (memory-efficient).
@@ -267,6 +391,8 @@ async function withRetry(fn, options = {}) {
 * Each step retries with exponential backoff via `withRetry`.
 */
 const log$2 = createLogger("SyncUploader");
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+const MAX_TRANSFER_CONCURRENCY$1 = 100;
 /**
 * Prefixes stored as GLACIER_IR on the sync bucket. Shared with the recovery
 * classifier in sync-engine.ts, which must never cut conflict sidecars for
@@ -286,20 +412,26 @@ function getContentType(relativePath) {
 	return "application/octet-stream";
 }
 async function uploadOne(workspacePath, relativePath, client) {
-	const absolutePath = join(workspacePath, relativePath);
+	let canonicalPath;
 	try {
+		canonicalPath = validatePrivateRelativePath(relativePath);
+		const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
+		const fileStat = await stat(absolutePath);
+		if (!fileStat.isFile()) throw new Error("Sync upload path is not a file");
+		const size = fileStat.size;
+		if (size > MAX_UPLOAD_BYTES) throw new Error("File exceeds the sync upload limit");
+		const fileContent = await readFile(absolutePath);
+		if (fileContent.length > MAX_UPLOAD_BYTES) throw new Error("File exceeds the sync upload limit");
+		const hash = `sha256:${createHash("sha256").update(fileContent).digest("hex")}`;
+		const storageClass = getStorageClass(canonicalPath);
+		const contentType = getContentType(canonicalPath);
 		return await withRetry(async () => {
-			const [hash, fileStat] = await Promise.all([computeFileHash(absolutePath), stat(absolutePath)]);
-			const size = fileStat.size;
-			const storageClass = getStorageClass(relativePath);
-			const contentType = getContentType(relativePath);
 			const url = (await client.syncPresign({ files: [{
-				path: relativePath,
+				path: canonicalPath,
 				operation: "put",
 				contentType
 			}] })).urls[0]?.url;
 			if (!url) throw new Error("No presigned URL returned");
-			const fileContent = await readFile(absolutePath);
 			const putResponse = await fetch(url, {
 				method: "PUT",
 				headers: { "Content-Type": contentType },
@@ -307,22 +439,23 @@ async function uploadOne(workspacePath, relativePath, client) {
 			});
 			if (!putResponse.ok) throw new Error(`S3 PUT failed (${String(putResponse.status)}): ${await putResponse.text()}`);
 			await client.syncConfirmUpload({
-				filePath: relativePath,
+				filePath: canonicalPath,
 				hash,
 				size,
 				storageClass
 			});
+			const entry = {
+				hash,
+				size,
+				lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
+				storageClass
+			};
 			return {
-				path: relativePath,
+				path: canonicalPath,
 				success: true,
 				hash,
 				size,
-				entry: {
-					hash,
-					size,
-					lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
-					storageClass
-				}
+				entry
 			};
 		});
 	} catch (err) {
@@ -338,6 +471,7 @@ async function uploadOne(workspacePath, relativePath, client) {
 */
 async function uploadFiles(workspacePath, relativePaths, client, options = {}) {
 	const { concurrency = 5, quiet = false } = options;
+	if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > MAX_TRANSFER_CONCURRENCY$1) throw new Error("Upload concurrency must be an integer between 1 and 100");
 	const results = [];
 	for (let i = 0; i < relativePaths.length; i += concurrency) {
 		const batch = relativePaths.slice(i, i + concurrency);
@@ -376,28 +510,35 @@ function formatBytes$1(bytes) {
 *   4. Update the local manifest
 */
 const log$1 = createLogger("SyncDownloader");
+const MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024;
+const MAX_TRANSFER_CONCURRENCY = 100;
 async function downloadOne(workspacePath, relativePath, client, remoteEntry) {
+	let canonicalPath;
 	try {
+		canonicalPath = validatePrivateRelativePath(relativePath);
 		return await withRetry(async () => {
 			const url = (await client.syncPresign({ files: [{
-				path: relativePath,
+				path: canonicalPath,
 				operation: "get"
 			}] })).urls[0]?.url;
 			if (!url) throw new Error("No presigned URL returned");
 			const response = await fetch(url);
 			if (!response.ok) throw new Error(`S3 GET failed (${String(response.status)}): ${await response.text()}`);
+			const contentLength = Number(response.headers.get("content-length") ?? "0");
+			if (Number.isFinite(contentLength) && contentLength > MAX_DOWNLOAD_BYTES) throw new Error("S3 object exceeds the local sync download limit");
 			const buffer = Buffer.from(await response.arrayBuffer());
-			const absolutePath = join(workspacePath, relativePath);
+			if (buffer.length > MAX_DOWNLOAD_BYTES) throw new Error("S3 object exceeds the local sync download limit");
+			const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
 			await mkdir(dirname(absolutePath), { recursive: true });
 			await writeFile(absolutePath, buffer);
 			const entry = {
 				hash: remoteEntry?.hash ?? "",
 				size: buffer.length,
 				lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
-				storageClass: remoteEntry?.storageClass ?? "STANDARD"
+				storageClass: remoteEntry?.storageClass === "GLACIER_IR" ? "GLACIER_IR" : "STANDARD"
 			};
 			return {
-				path: relativePath,
+				path: canonicalPath,
 				success: true,
 				size: buffer.length,
 				entry
@@ -413,6 +554,7 @@ async function downloadOne(workspacePath, relativePath, client, remoteEntry) {
 }
 async function downloadFiles(workspacePath, relativePaths, client, remoteManifest, options = {}) {
 	const { concurrency = 5, quiet = false } = options;
+	if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > MAX_TRANSFER_CONCURRENCY) throw new Error("Download concurrency must be an integer between 1 and 100");
 	const results = [];
 	for (let i = 0; i < relativePaths.length; i += concurrency) {
 		const batch = relativePaths.slice(i, i + concurrency);
@@ -462,6 +604,15 @@ const log = createLogger("SyncEngine");
 const MAX_PRESERVE_BYTES = 100 * 1024 * 1024;
 /** Marker that keeps the heartbeat recovery nudge idempotent across runs. */
 const RECOVERY_NUDGE_MARKER = "<!-- alfe-sync:recovery-nudge -->";
+function filterSafePrivatePaths(paths) {
+	const safe = [];
+	for (const candidate of paths) try {
+		safe.push(validatePrivateRelativePath(candidate));
+	} catch {
+		log.warn("Ignored an invalid path from sync state");
+	}
+	return [...new Set(safe)];
+}
 /**
 * Recovery artifacts: `.conflict-<ts>` sidecars and `RECOVERY-<ts>.md`
 * reports. Anchored to the timestamp shape so legitimate user files like
@@ -499,7 +650,8 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 		async push(paths, options = {}) {
 			const { quiet = false, filter } = options;
 			const ignorePatterns = await loadIgnorePatterns(workspacePath, runtime);
-			let filesToPush = paths && paths.length > 0 ? filterIgnored(paths, ignorePatterns) : await detectLocalChanges(workspacePath, ignorePatterns);
+			let filesToPush = paths && paths.length > 0 ? filterIgnored(filterSafePrivatePaths(paths), ignorePatterns) : await detectLocalChanges(workspacePath, ignorePatterns);
+			if (paths && paths.length > 0) filesToPush = await filterChangedExplicitPaths(workspacePath, filesToPush);
 			if (filter) filesToPush = filesToPush.filter((p) => p.startsWith(filter));
 			if (filesToPush.length === 0) {
 				if (!quiet) log.info("Nothing to push");
@@ -533,7 +685,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 			if (!quiet) log.info(`Deleting ${String(paths.length)} file(s) from cloud`);
 			let deleted = 0;
 			let errors = 0;
-			for (const path of paths) try {
+			for (const path of filterSafePrivatePaths(paths)) try {
 				await client.syncDeleteFile(path);
 				await removeManifestEntry(workspacePath, path);
 				deleted++;
@@ -564,7 +716,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 				};
 			}
 			if (!quiet) log.info(`Pulling ${String(diff.toPull.length)} file(s)`);
-			const results = await downloadFiles(workspacePath, [...diff.toPull], client, remoteManifest, { quiet });
+			const results = await downloadFiles(workspacePath, filterSafePrivatePaths([...diff.toPull]), client, remoteManifest, { quiet });
 			const pulled = results.filter((r) => r.success).length;
 			const errors = results.filter((r) => !r.success).length;
 			if (!quiet) log.info(`Pull complete: ${String(pulled)} downloaded, ${String(errors)} failed`);
@@ -581,8 +733,8 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 			const ignorePatterns = await loadIgnorePatterns(workspacePath, runtime);
 			const localChanges = await detectLocalChanges(workspacePath, ignorePatterns);
 			const diff = diffManifests(localManifest, remoteManifest);
-			const trueConflicts = diff.conflicts.filter((p) => localChanges.includes(p));
-			const remoteOnlyChanges = diff.conflicts.filter((p) => !localChanges.includes(p));
+			const trueConflicts = filterSafePrivatePaths(diff.conflicts.filter((p) => localChanges.includes(p)));
+			const remoteOnlyChanges = filterSafePrivatePaths(diff.conflicts.filter((p) => !localChanges.includes(p)));
 			let conflictCount = 0;
 			const conflictTimestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 			for (const conflictPath of trueConflicts) {
@@ -591,12 +743,12 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 				if (outcome.status !== "too-large" && !quiet) log.warn(`Conflict: ${conflictPath} — saved as ${outcome.conflictPath}`);
 				conflictCount++;
 			}
-			const filesToPush = filterIgnored([...diff.toPush, ...localChanges.filter((p) => !diff.conflicts.includes(p))], ignorePatterns);
-			const filesToPull = [
+			const filesToPush = filterIgnored(filterSafePrivatePaths([...diff.toPush, ...localChanges.filter((p) => !diff.conflicts.includes(p))]), ignorePatterns);
+			const filesToPull = filterSafePrivatePaths([
 				...diff.toPull,
 				...remoteOnlyChanges,
 				...trueConflicts
-			];
+			]);
 			const pushResult = {
 				pushed: 0,
 				errors: 0
@@ -629,7 +781,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 		async firstRunReconcile(options = {}) {
 			const { quiet = false } = options;
 			const remoteManifest = await client.syncGetManifest();
-			const remotePaths = Object.keys(remoteManifest.files);
+			const remotePaths = filterSafePrivatePaths(Object.keys(remoteManifest.files));
 			if (remotePaths.length === 0) {
 				if (!quiet) log.info("First-run sync: no cloud state — seeding workspace to cloud");
 				const seedResult = await this.push(void 0, options);
@@ -680,7 +832,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 			let recoveryReportPath = null;
 			if (preserved.length > 0 && (newlyPreserved > 0 || !await recoveryReportExists(workspacePath))) {
 				recoveryReportPath = `${agentDirPrefix(workspacePath)}RECOVERY-${timestamp}.md`;
-				const reportAbsolute = join(workspacePath, recoveryReportPath);
+				const reportAbsolute = await assertNoSymlinkTraversal(workspacePath, recoveryReportPath);
 				await mkdir(dirname(reportAbsolute), { recursive: true });
 				await writeFile(reportAbsolute, buildRecoveryReport(preserved, workspacePath), "utf-8");
 				log.warn(`Recovery: ${String(preserved.length)} diverged local file(s) — see ${recoveryReportPath}`);
@@ -742,7 +894,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 			};
 			const remoteManifest = await client.syncGetManifest();
 			const localManifest = await readManifest(workspacePath);
-			const filesToPull = paths.filter((p) => {
+			const filesToPull = filterSafePrivatePaths(paths).filter((p) => {
 				if (!(p in remoteManifest.files)) return false;
 				if (!(p in localManifest.files)) return true;
 				return localManifest.files[p].hash !== remoteManifest.files[p].hash;
@@ -772,7 +924,7 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 			const { quiet = false, limit = 1e3 } = options;
 			const ignorePatterns = await loadIgnorePatterns(workspacePath, runtime);
 			const remoteManifest = await client.syncGetManifest();
-			const ignoredPaths = Object.keys(remoteManifest.files).filter((p) => shouldIgnore(p, ignorePatterns));
+			const ignoredPaths = filterSafePrivatePaths(Object.keys(remoteManifest.files)).filter((p) => shouldIgnore(p, ignorePatterns));
 			if (ignoredPaths.length === 0) return {
 				pushed: 0,
 				pulled: 0,
@@ -788,20 +940,38 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 		},
 		async removeLocalFile(filePath, options = {}) {
 			const { quiet = false } = options;
-			const absolutePath = join(workspacePath, filePath);
+			const canonicalPath = validatePrivateRelativePath(filePath);
+			const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
 			try {
 				const { unlink } = await import("node:fs/promises");
 				if (existsSync(absolutePath)) {
 					await unlink(absolutePath);
-					if (!quiet) log.info(`Deleted: ${filePath}`);
+					if (!quiet) log.info(`Deleted: ${canonicalPath}`);
 				}
 			} catch (err) {
-				if (!quiet) log.error({ err }, `Failed to delete ${filePath}`);
+				if (!quiet) log.error({ err }, `Failed to delete ${canonicalPath}`);
 			}
-			await removeManifestEntry(workspacePath, filePath);
+			await removeManifestEntry(workspacePath, canonicalPath);
 		}
 	};
 }
+async function filterChangedExplicitPaths(workspacePath, paths) {
+	const manifest = await readManifest(workspacePath);
+	const changed = [];
+	for (const relativePath of paths) {
+		if (!(relativePath in manifest.files)) {
+			changed.push(relativePath);
+			continue;
+		}
+		const entry = manifest.files[relativePath];
+		try {
+			if (await computeFileHash(await assertNoSymlinkTraversal(workspacePath, relativePath)) !== entry.hash) changed.push(relativePath);
+		} catch {
+			changed.push(relativePath);
+		}
+	}
+	return changed;
+}
 /**
 * Walk the workspace and return paths whose hash differs from the manifest
 * (or that are missing from it entirely).
@@ -857,10 +1027,11 @@ async function recoveryReportExists(workspacePath) {
 * `sourceHash` when the caller already hashed the file.
 */
 async function preserveConflictCopy(workspacePath, relativePath, timestamp, options = {}) {
-	const absolutePath = join(workspacePath, relativePath);
-	const ext = extname(relativePath);
-	const base = basename(relativePath, ext);
-	const dir = dirname(relativePath);
+	const canonicalPath = validatePrivateRelativePath(relativePath);
+	const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
+	const ext = extname(canonicalPath);
+	const base = basename(canonicalPath, ext);
+	const dir = dirname(canonicalPath);
 	try {
 		const fileStat = await stat(absolutePath);
 		if (options.maxBytes !== void 0 && fileStat.size > options.maxBytes) return {
@@ -872,16 +1043,17 @@ async function preserveConflictCopy(workspacePath, relativePath, timestamp, opti
 		for (const name of siblings) {
 			if (!name.startsWith(`${base}.conflict-`)) continue;
 			if (ext !== "" && !name.endsWith(ext)) continue;
-			if (await computeFileHash(join(workspacePath, dir, name)).catch(() => null) === sourceHash) return {
+			if (await assertNoSymlinkTraversal(workspacePath, dir === "." ? name : `${dir}/${name}`).then((path) => computeFileHash(path)).catch(() => null) === sourceHash) return {
 				status: "already-preserved",
 				conflictPath: join(dir, name).replace(/\\/g, "/")
 			};
 		}
 		const conflictName = `${base}.conflict-${timestamp}${ext}`;
-		await copyFile(absolutePath, join(workspacePath, dir, conflictName));
+		const conflictPath = dir === "." ? conflictName : `${dir}/${conflictName}`;
+		await copyFile(absolutePath, await assertNoSymlinkTraversal(workspacePath, conflictPath));
 		return {
 			status: "preserved",
-			conflictPath: join(dir, conflictName).replace(/\\/g, "/")
+			conflictPath
 		};
 	} catch {
 		return { status: "vanished" };
@@ -908,7 +1080,13 @@ async function classifyRestorePaths(workspacePath, restorePaths, remoteFiles, lo
 	async function classifyOne(path) {
 		const remote = remoteFiles[path];
 		const entry = manifestTrusted ? localManifest.files[path] : void 0;
-		const absolutePath = join(workspacePath, path);
+		let absolutePath;
+		try {
+			absolutePath = await assertNoSymlinkTraversal(workspacePath, path);
+		} catch {
+			log.warn("Skipped a cloud sync path that crosses a local symbolic link");
+			return;
+		}
 		let fileStat = null;
 		try {
 			fileStat = await stat(absolutePath);
@@ -937,7 +1115,7 @@ async function classifyRestorePaths(workspacePath, restorePaths, remoteFiles, lo
 				hash: remote.hash,
 				size: fileStat.size,
 				lastSynced: (/* @__PURE__ */ new Date()).toISOString(),
-				storageClass: remote.storageClass ?? "STANDARD"
+				storageClass: remote.storageClass === "GLACIER_IR" ? "GLACIER_IR" : "STANDARD"
 			};
 			return;
 		}
@@ -997,7 +1175,7 @@ function buildRecoveryReport(records, workspacePath) {
 async function appendRecoveryNudge(workspacePath, recoveryReportPath, preservedCount) {
 	const prefix = agentDirPrefix(workspacePath);
 	const heartbeatPath = `${prefix}HEARTBEAT.md`;
-	const absolutePath = join(workspacePath, heartbeatPath);
+	const absolutePath = await assertNoSymlinkTraversal(workspacePath, heartbeatPath);
 	if ((existsSync(absolutePath) ? await readFile(absolutePath, "utf-8") : "").includes(RECOVERY_NUDGE_MARKER)) return null;
 	const reportForAgent = recoveryReportPath.startsWith(prefix) ? recoveryReportPath.slice(prefix.length) : recoveryReportPath;
 	const block = [
@@ -1017,6 +1195,6 @@ async function appendRecoveryNudge(workspacePath, recoveryReportPath, preservedC
 	return heartbeatPath;
 }
 //#endregion
-export { withRetry as a, loadIgnorePatterns as c, computeFileHash as d, diffManifests as f, writeManifest as g, updateManifestEntry as h, uploadFiles as i, shouldIgnore as l, removeManifestEntry as m, isRecoveryArtifact as n, DEFAULT_IGNORES as o, readManifest as p, downloadFiles as r, filterIgnored as s, createSyncEngine as t, shouldIgnoreDir as u };
+export { assertNoSymlinkTraversal as _, withRetry as a, loadIgnorePatterns as c, computeFileHash as d, diffManifests as f, writeManifest as g, updateManifestEntry as h, uploadFiles as i, shouldIgnore as l, removeManifestEntry as m, isRecoveryArtifact as n, DEFAULT_IGNORES as o, readManifest as p, downloadFiles as r, filterIgnored as s, createSyncEngine as t, shouldIgnoreDir as u, resolvePrivateWorkspacePath as v, validatePrivateRelativePath as y };
 
 //# sourceMappingURL=sync-engine.js.map