@alfe.ai/openclaw-sync 0.3.6 → 0.3.8

package/dist/sync-engine.cjs

@@ -29,6 +29,53 @@ let node_url = require("node:url");
 let micromatch = require("micromatch");
 micromatch = __toESM(micromatch);
 let _auriclabs_logger = require("@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("\\") || (0, node_path.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 = (0, node_path.resolve)(workspacePath);
+	const absolutePath = (0, node_path.resolve)(workspace, canonical);
+	const fromWorkspace = (0, node_path.relative)(workspace, absolutePath);
+	if (fromWorkspace === "" || fromWorkspace === ".." || fromWorkspace.startsWith(`..${node_path.sep}`) || (0, node_path.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 = (0, node_path.resolve)(workspacePath);
+	for (const segment of segments) {
+		current = (0, node_path.resolve)(current, segment);
+		try {
+			if ((await (0, node_fs_promises.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`.
@@ -48,6 +95,9 @@ let _auriclabs_logger = require("@auriclabs/logger");
 */
 const SYNC_STATE_DIR = (0, node_path.join)((0, node_os.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.
@@ -55,6 +105,82 @@ const MANIFEST_FILE = "manifest.json";
 function manifestPath() {
 	return (0, node_path.join)(SYNC_STATE_DIR, MANIFEST_FILE);
 }
+function manifestLockPath() {
+	return (0, node_path.join)(SYNC_STATE_DIR, MANIFEST_LOCK_FILE);
+}
+async function readManifestUnlocked() {
+	try {
+		const raw = await (0, node_fs_promises.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 (0, node_fs_promises.mkdir)(SYNC_STATE_DIR, { recursive: true });
+	const target = manifestPath();
+	const temporary = `${target}.${String(process.pid)}.${String(Date.now())}.tmp`;
+	try {
+		await (0, node_fs_promises.writeFile)(temporary, `${JSON.stringify(manifest, null, 2)}\n`, "utf-8");
+		await (0, node_fs_promises.rename)(temporary, target);
+	} catch (error) {
+		await (0, node_fs_promises.unlink)(temporary).catch(() => void 0);
+		throw error;
+	}
+}
+async function withManifestLock(operation) {
+	await (0, node_fs_promises.mkdir)(SYNC_STATE_DIR, { recursive: true });
+	const lockPath = manifestLockPath();
+	const deadline = Date.now() + MANIFEST_LOCK_TIMEOUT_MS;
+	for (;;) {
+		let handle;
+		try {
+			handle = await (0, node_fs_promises.open)(lockPath, "wx");
+		} catch (error) {
+			if ((error instanceof Error && "code" in error ? error.code : void 0) !== "EEXIST") throw error;
+			const lockStat = await (0, node_fs_promises.stat)(lockPath).catch(() => null);
+			if (lockStat && Date.now() - lockStat.mtimeMs > MANIFEST_LOCK_STALE_MS) {
+				await (0, node_fs_promises.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 (0, node_fs_promises.unlink)(lockPath).catch(() => void 0);
+		}
+	}
+}
 /**
 * Read the local manifest. Returns empty manifest if not found.
 *
@@ -63,31 +189,25 @@ function manifestPath() {
 * `~/.alfe/sync/` regardless of which workspace the call comes from.
 */
 async function readManifest(workspacePath) {
-	const path = manifestPath();
-	if (!(0, node_fs.existsSync)(path)) return { files: {} };
-	try {
-		const raw = await (0, node_fs_promises.readFile)(path, "utf-8");
-		return JSON.parse(raw);
-	} catch {
-		return { files: {} };
-	}
+	if (!(0, node_fs.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 (0, node_fs_promises.mkdir)(SYNC_STATE_DIR, { recursive: true });
-	await (0, node_fs_promises.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.
@@ -98,18 +218,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).
@@ -290,6 +414,8 @@ async function withRetry(fn, options = {}) {
 * Each step retries with exponential backoff via `withRetry`.
 */
 const log$2 = (0, _auriclabs_logger.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
@@ -309,20 +435,26 @@ function getContentType(relativePath) {
 	return "application/octet-stream";
 }
 async function uploadOne(workspacePath, relativePath, client) {
-	const absolutePath = (0, node_path.join)(workspacePath, relativePath);
+	let canonicalPath;
 	try {
+		canonicalPath = validatePrivateRelativePath(relativePath);
+		const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
+		const fileStat = await (0, node_fs_promises.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 (0, node_fs_promises.readFile)(absolutePath);
+		if (fileContent.length > MAX_UPLOAD_BYTES) throw new Error("File exceeds the sync upload limit");
+		const hash = `sha256:${(0, node_crypto.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), (0, node_fs_promises.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 (0, node_fs_promises.readFile)(absolutePath);
 			const putResponse = await fetch(url, {
 				method: "PUT",
 				headers: { "Content-Type": contentType },
@@ -330,22 +462,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) {
@@ -361,6 +494,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);
@@ -399,28 +533,35 @@ function formatBytes$1(bytes) {
 *   4. Update the local manifest
 */
 const log$1 = (0, _auriclabs_logger.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 = (0, node_path.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 (0, node_fs_promises.mkdir)((0, node_path.dirname)(absolutePath), { recursive: true });
 			await (0, node_fs_promises.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
@@ -436,6 +577,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);
@@ -485,6 +627,15 @@ const log = (0, _auriclabs_logger.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
@@ -522,7 +673,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");
@@ -556,7 +708,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++;
@@ -587,7 +739,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`);
@@ -604,8 +756,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) {
@@ -614,12 +766,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
@@ -652,7 +804,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);
@@ -703,7 +855,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 = (0, node_path.join)(workspacePath, recoveryReportPath);
+				const reportAbsolute = await assertNoSymlinkTraversal(workspacePath, recoveryReportPath);
 				await (0, node_fs_promises.mkdir)((0, node_path.dirname)(reportAbsolute), { recursive: true });
 				await (0, node_fs_promises.writeFile)(reportAbsolute, buildRecoveryReport(preserved, workspacePath), "utf-8");
 				log.warn(`Recovery: ${String(preserved.length)} diverged local file(s) — see ${recoveryReportPath}`);
@@ -765,7 +917,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;
@@ -795,7 +947,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,
@@ -811,20 +963,38 @@ function createSyncEngine({ workspacePath, client, runtime = "openclaw", maxPres
 		},
 		async removeLocalFile(filePath, options = {}) {
 			const { quiet = false } = options;
-			const absolutePath = (0, node_path.join)(workspacePath, filePath);
+			const canonicalPath = validatePrivateRelativePath(filePath);
+			const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
 			try {
 				const { unlink } = await import("node:fs/promises");
 				if ((0, node_fs.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).
@@ -880,10 +1050,11 @@ async function recoveryReportExists(workspacePath) {
 * `sourceHash` when the caller already hashed the file.
 */
 async function preserveConflictCopy(workspacePath, relativePath, timestamp, options = {}) {
-	const absolutePath = (0, node_path.join)(workspacePath, relativePath);
-	const ext = (0, node_path.extname)(relativePath);
-	const base = (0, node_path.basename)(relativePath, ext);
-	const dir = (0, node_path.dirname)(relativePath);
+	const canonicalPath = validatePrivateRelativePath(relativePath);
+	const absolutePath = await assertNoSymlinkTraversal(workspacePath, canonicalPath);
+	const ext = (0, node_path.extname)(canonicalPath);
+	const base = (0, node_path.basename)(canonicalPath, ext);
+	const dir = (0, node_path.dirname)(canonicalPath);
 	try {
 		const fileStat = await (0, node_fs_promises.stat)(absolutePath);
 		if (options.maxBytes !== void 0 && fileStat.size > options.maxBytes) return {
@@ -895,16 +1066,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((0, node_path.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: (0, node_path.join)(dir, name).replace(/\\/g, "/")
 			};
 		}
 		const conflictName = `${base}.conflict-${timestamp}${ext}`;
-		await (0, node_fs_promises.copyFile)(absolutePath, (0, node_path.join)(workspacePath, dir, conflictName));
+		const conflictPath = dir === "." ? conflictName : `${dir}/${conflictName}`;
+		await (0, node_fs_promises.copyFile)(absolutePath, await assertNoSymlinkTraversal(workspacePath, conflictPath));
 		return {
 			status: "preserved",
-			conflictPath: (0, node_path.join)(dir, conflictName).replace(/\\/g, "/")
+			conflictPath
 		};
 	} catch {
 		return { status: "vanished" };
@@ -931,7 +1103,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 = (0, node_path.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 (0, node_fs_promises.stat)(absolutePath);
@@ -960,7 +1138,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;
 		}
@@ -1020,7 +1198,7 @@ function buildRecoveryReport(records, workspacePath) {
 async function appendRecoveryNudge(workspacePath, recoveryReportPath, preservedCount) {
 	const prefix = agentDirPrefix(workspacePath);
 	const heartbeatPath = `${prefix}HEARTBEAT.md`;
-	const absolutePath = (0, node_path.join)(workspacePath, heartbeatPath);
+	const absolutePath = await assertNoSymlinkTraversal(workspacePath, heartbeatPath);
 	if (((0, node_fs.existsSync)(absolutePath) ? await (0, node_fs_promises.readFile)(absolutePath, "utf-8") : "").includes(RECOVERY_NUDGE_MARKER)) return null;
 	const reportForAgent = recoveryReportPath.startsWith(prefix) ? recoveryReportPath.slice(prefix.length) : recoveryReportPath;
 	const block = [
@@ -1052,6 +1230,12 @@ Object.defineProperty(exports, "__toESM", {
 		return __toESM;
 	}
 });
+Object.defineProperty(exports, "assertNoSymlinkTraversal", {
+	enumerable: true,
+	get: function() {
+		return assertNoSymlinkTraversal;
+	}
+});
 Object.defineProperty(exports, "computeFileHash", {
 	enumerable: true,
 	get: function() {
@@ -1106,6 +1290,12 @@ Object.defineProperty(exports, "removeManifestEntry", {
 		return removeManifestEntry;
 	}
 });
+Object.defineProperty(exports, "resolvePrivateWorkspacePath", {
+	enumerable: true,
+	get: function() {
+		return resolvePrivateWorkspacePath;
+	}
+});
 Object.defineProperty(exports, "shouldIgnore", {
 	enumerable: true,
 	get: function() {
@@ -1130,6 +1320,12 @@ Object.defineProperty(exports, "uploadFiles", {
 		return uploadFiles;
 	}
 });
+Object.defineProperty(exports, "validatePrivateRelativePath", {
+	enumerable: true,
+	get: function() {
+		return validatePrivateRelativePath;
+	}
+});
 Object.defineProperty(exports, "withRetry", {
 	enumerable: true,
 	get: function() {