diff --git a/src/services/file-safety/__tests__/safeWriteText.spec.ts b/src/services/file-safety/__tests__/safeWriteText.spec.ts
new file mode 100644
index 0000000000..6312961863
--- /dev/null
+++ b/src/services/file-safety/__tests__/safeWriteText.spec.ts
@@ -0,0 +1,672 @@
+import * as fs from "fs/promises"
+import * as fsSync from "fs"
+import { execFile } from "child_process"
+import type { ChildProcess } from "child_process"
+import * as path from "path"
+
+import { safeWriteText, type SafeWriteTextOptions } from "../safeWriteText"
+
+// Full mock for fs/promises — all methods are vi.fn() stubs
+vi.mock("fs/promises", () => ({
+	mkdir: vi.fn(),
+	access: vi.fn(),
+	rename: vi.fn(),
+	unlink: vi.fn(),
+	realpath: vi.fn(),
+}))
+
+// Full mock for fs — all sync methods are vi.fn() stubs. Stats is a bare
+// class stub so tests can build minimal Stats stand-ins via its prototype.
+vi.mock("fs", () => ({
+	openSync: vi.fn(),
+	writeSync: vi.fn(),
+	closeSync: vi.fn(),
+	mkdirSync: vi.fn(),
+	fsyncSync: vi.fn(),
+	chmodSync: vi.fn(),
+	fchmodSync: vi.fn(),
+	statSync: vi.fn(),
+	Stats: class Stats {},
+}))
+
+// Mock child_process.execFile (callback-based — must invoke callback to resolve)
+vi.mock("child_process", () => ({
+	execFile: vi.fn((cmd, args, opts, cb) => {
+		if (typeof cb === "function") cb(null)
+	}),
+}))
+
+// Minimal stand-in for the ChildProcess that callback-form execFile returns.
+const fakeChild = { kill: () => true } as unknown as ChildProcess
+
+// Helper that mirrors safeWriteText's path resolution exactly
+function _resolvedTarget(filePath: string): string {
+	return path.resolve(filePath)
+}
+function _dirPath(filePath: string): string {
+	return path.dirname(_resolvedTarget(filePath))
+}
+function _stagingDir(dir: string): string {
+	return path.join(dir, ".file-safety-staging")
+}
+
+// Minimal Stats stand-in: the SUT only reads `.mode` from it.
+function _stats(mode: number): fsSync.Stats {
+	const s = Object.create(fsSync.Stats.prototype) as fsSync.Stats
+	Object.assign(s, { mode })
+	return s
+}
+
+// ── Test 1: staging file created then cleaned after success ────────────────
+
+describe("safeWriteText", () => {
+	beforeEach(() => {
+		vi.resetAllMocks()
+		// After resetAllMocks, vi.fn() returns undefined — restore promise defaults.
+		vi.mocked(fs.mkdir).mockResolvedValue(undefined)
+		vi.mocked(fs.access).mockResolvedValue(undefined)
+		vi.mocked(fs.rename).mockResolvedValue(undefined)
+		vi.mocked(fs.unlink).mockResolvedValue(undefined)
+		vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o644))
+		// Default sync-write behaviour: report that all requested bytes were written
+		// (the Buffer overload passes (fd, buffer, offset, length) — arg 3 is the length)
+		vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) =>
+			typeof args[3] === "number" ? args[3] : 0,
+		)
+	})
+
+	describe("staging and cleanup", () => {
+		it("creates a temp file in the staging dir, fsyncs it, renames to target, and cleans up on success", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1) // fd=1
+			vi.mocked(fsSync.closeSync).mockReturnValue(undefined)
+
+			await safeWriteText(targetPath, "hello world", { platform: "linux" })
+
+			// stringContaining: the resolved staging dir renders differently per platform
+			expect(fsSync.mkdirSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), {
+				recursive: true,
+				mode: 0o700,
+			})
+			// a pre-existing staging dir is repaired to private permissions too
+			expect(fsSync.chmodSync).toHaveBeenCalledWith(expect.stringContaining(".file-safety-staging"), 0o700)
+
+			// temp file was opened for writing with the existing target's mode (default 0o644);
+			// the full temp-name shape (dot prefix, timestamp, random suffix, .tmp) must hold
+			expect(fsSync.openSync).toHaveBeenCalledWith(
+				expect.stringMatching(/\.safeWriteText_\d+_[0-9a-z]+\.tmp$/),
+				"w",
+				0o644,
+			)
+
+			expect(fsSync.writeSync).toHaveBeenCalledWith(1, Buffer.from("hello world", "utf8"), 0, 11)
+			expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+			expect(fsSync.closeSync).toHaveBeenCalledWith(1)
+
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+			// no unlink of temp (it's now the committed file; DACL skipped via platform:linux)
+			expect(fs.unlink).not.toHaveBeenCalled()
+
+			// parent dir was ensured with the recursive flag
+			expect(fs.mkdir).toHaveBeenCalledWith(path.dirname(targetPath), { recursive: true })
+		})
+	})
+
+	// ── Test 2: fsync ordering ───────────────────────────────────────────────
+
+	describe("fsync ordering", () => {
+		it("calls fsync on the fd before close, and rename after close", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(targetPath, "data", { platform: "linux" })
+
+			// openSync(temp) → writeSync → fsyncSync(temp) → closeSync → rename; on POSIX
+			// the parent dir is then fsynced, so each gets a second (directory) call
+			expect(vi.mocked(fsSync.openSync).mock.calls.length).toBe(2)
+			expect(vi.mocked(fsSync.writeSync).mock.calls.length).toBe(1)
+			expect(vi.mocked(fsSync.fsyncSync).mock.calls.length).toBe(2)
+			expect(vi.mocked(fsSync.closeSync).mock.calls.length).toBe(2)
+
+			// the temp file was fully closed before the commit rename
+			expect(vi.mocked(fsSync.closeSync).mock.calls[0][0]).toBe(1)
+			expect(fs.rename).toHaveBeenCalled()
+		})
+	})
+
+	// ── Test 3: simulated failure between write and rename leaves target intact ──
+
+	describe("crash/torn-write safety", () => {
+		it("simulated failure between fsync and rename leaves the target byte-identical and no temp left behind", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			vi.mocked(fs.rename).mockRejectedValue(new Error("ENOSPC"))
+
+			await expect(safeWriteText(targetPath, "new data", { platform: "linux" })).rejects.toThrow("ENOSPC")
+
+			// rename was attempted (the failure point)
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+			// temp file was cleaned up on failure
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+
+			// backup was NOT created (backup:false by default), so target is untouched
+			// The only rename call was temp→target, not a rollback rename
+			expect(fs.rename).toHaveBeenCalledTimes(1)
+		})
+
+		it("a post-commit backup cleanup failure is non-fatal: the target stays committed and no temp is left behind", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			// The post-commit backup unlink (SUT step 6) fails — the write must
+			// still succeed; an orphaned backup is the documented acceptable
+			// outcome, so the failure is swallowed instead of rolling back.
+			vi.mocked(fs.unlink).mockRejectedValueOnce(new Error("EPERM"))
+
+			await safeWriteText(targetPath, "data", { backup: true, platform: "linux" })
+
+			// the commit rename (temp -> target) still happened
+			expect(fs.rename).toHaveBeenNthCalledWith(2, expect.stringContaining("safeWriteText_"), targetPath)
+
+			// the failing cleanup was the post-commit backup unlink
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+
+			// no rollback rename: the committed target is not restored from the backup
+			expect(fs.rename).toHaveBeenCalledTimes(2)
+
+			// the staging temp was already committed by the rename; nothing
+			// temp-shaped is unlinked afterwards
+			expect(fs.unlink).not.toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+		})
+	})
+
+	// ── Test 4: backup:true keeps old safeWriteJson semantics incl. rollback ──
+
+	describe("backup:true", () => {
+		it("renames target -> backup before commit, deletes backup on success", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(targetPath, "new data", { backup: true })
+
+			expect(fs.access).toHaveBeenCalledWith(targetPath)
+			expect(fs.rename).toHaveBeenNthCalledWith(1, targetPath, expect.stringContaining("safeWriteText.bak_"))
+			expect(fs.rename).toHaveBeenNthCalledWith(2, expect.stringContaining("safeWriteText_"), targetPath)
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText.bak_"))
+		})
+
+		it("rollback: on failure after rename target->backup, restores backup to target", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			let callCount = 0
+			vi.mocked(fs.rename).mockImplementation(async () => {
+				callCount++
+				if (callCount === 1) return // target -> backup
+				throw new Error("ENOSPC") // temp -> target fails
+			})
+
+			await expect(safeWriteText(targetPath, "new data", { backup: true })).rejects.toThrow("ENOSPC")
+
+			expect(fs.rename).toHaveBeenNthCalledWith(3, expect.stringContaining("safeWriteText.bak_"), targetPath)
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"))
+		})
+
+		it("backup:true when target does not exist: no backup created, just commit", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			// fs.access resolves for dirPath check, but rejects for target check (backup path)
+			vi.mocked(fs.access).mockImplementation(async (p) => {
+				if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" }
+			})
+
+			await safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })
+
+			expect(fs.access).toHaveBeenCalledWith(targetPath)
+
+			expect(fs.rename).toHaveBeenCalledTimes(1)
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+
+			// no unlink (no backup to delete; DACL skipped via platform:linux)
+			expect(fs.unlink).not.toHaveBeenCalled()
+		})
+
+		it("backup:true: ENOENT from the backup rename is swallowed; commit succeeds, no backup unlink", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			// the backup rename (1st fs.rename call) hits a vanished target; the commit (2nd) succeeds
+			vi.mocked(fs.rename).mockImplementationOnce(async () => {
+				throw { code: "ENOENT" }
+			})
+
+			await safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })
+
+			// swallowed backup rename + commit rename, and no backup unlink follows
+			expect(fs.rename).toHaveBeenCalledTimes(2)
+			expect(fs.unlink).not.toHaveBeenCalled()
+		})
+
+		it("backup:true: swallowed ENOENT then a failed commit → no rollback rename (no backup exists)", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			// 1st rename: backup (ENOENT, swallowed); 2nd: commit (fails)
+			vi.mocked(fs.rename).mockImplementationOnce(async () => {
+				throw { code: "ENOENT" }
+			})
+			vi.mocked(fs.rename).mockImplementationOnce(async () => {
+				throw new Error("ENOSPC")
+			})
+
+			await expect(safeWriteText(targetPath, "new data", { backup: true, platform: "linux" })).rejects.toThrow(
+				"ENOSPC",
+			)
+
+			// no backup was created, so the rollback guard must not add a 3rd rename
+			expect(fs.rename).toHaveBeenCalledTimes(2)
+		})
+
+		it("backup:true: function and null rejections from the backup rename propagate untouched", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			// a function is not an object: its code:ENOENT cannot be read, so it must be rethrown
+			const fnErr: unknown = Object.assign(() => undefined, { code: "ENOENT" })
+			vi.mocked(fs.rename).mockRejectedValueOnce(fnErr)
+			await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toBe(fnErr)
+
+			// a null rejection must propagate as-is (no TypeError from the guard)
+			vi.mocked(fs.rename).mockRejectedValueOnce(null)
+			await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toBeNull()
+
+			// each failed backup rename left exactly one rename (no rollback ran)
+			expect(fs.rename).toHaveBeenCalledTimes(2)
+		})
+	})
+
+	// ── Test 5: win32 DACL path ──────────────────────────────────────────────
+
+	describe("win32 DACL", () => {
+		it.skipIf(process.platform !== "win32")(
+			"copies target DACL onto staging file via icacls before rename on Windows",
+			async () => {
+				const targetPath = "/tmp/test-dir/target.txt"
+				vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+				await safeWriteText(targetPath, "data", { platform: "win32" })
+
+				expect(execFile).toHaveBeenCalledTimes(2)
+			},
+		)
+
+		it("non-win32: DACL path is unreachable when platform is not win32", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(targetPath, "data", { platform: "linux" })
+
+			expect(execFile).not.toHaveBeenCalled()
+		})
+
+		it("no options: default platform (pinned win32) runs the DACL path; failures unlink the dump", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			const platformSpy = vi.spyOn(process, "platform", "get").mockReturnValue("win32")
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			try {
+				// no options at all: the generated temp + the pinned win32 platform
+				// take the full DACL path
+				await safeWriteText(targetPath, "data")
+				expect(fsSync.openSync).toHaveBeenCalledWith(
+					expect.stringMatching(/\.safeWriteText_\d+_[0-9a-z]+\.tmp$/),
+					"w",
+					0o644,
+				)
+				expect(execFile).toHaveBeenCalledTimes(2)
+
+				// commit fails, target present: dump (inner finally) + temp + dump (catch)
+				vi.mocked(fs.unlink).mockClear()
+				vi.mocked(fs.rename).mockImplementation(async () => {
+					throw new Error("ENOSPC")
+				})
+				await expect(safeWriteText(targetPath, "data")).rejects.toThrow("ENOSPC")
+				expect(fs.unlink).toHaveBeenCalledTimes(3)
+
+				// target absent: no save ran → only the temp is unlinked
+				vi.mocked(fs.unlink).mockClear()
+				vi.mocked(fs.access).mockImplementation(async (p) => {
+					if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" }
+				})
+				await expect(safeWriteText(targetPath, "data")).rejects.toThrow("ENOSPC")
+				expect(fs.unlink).toHaveBeenCalledTimes(1)
+			} finally {
+				platformSpy.mockRestore()
+			}
+		})
+
+		it("win32 DACL failure falls back to plain rename (never fails the write)", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			// icacls dump fails — the callback-based mock must invoke cb with an error.
+			vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+				if (typeof cb === "function") cb(new Error("icacls error"), "", "")
+				return fakeChild
+			})
+
+			await safeWriteText(targetPath, "data", { platform: "win32" })
+
+			expect(fs.rename).toHaveBeenCalled()
+
+			// only the failed save ran: daclDumpPath is nulled, so no restore follows
+			expect(execFile).toHaveBeenCalledTimes(1)
+		})
+
+		it("win32 DACL save args are [targetPath, /save, dumpPath, /T] before backup rename", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(targetPath, "data", { backup: true, platform: "win32" })
+
+			expect(execFile).toHaveBeenCalledTimes(2)
+
+			const firstCall = vi.mocked(execFile).mock.calls[0]
+			expect(firstCall[0]).toBe("icacls")
+			expect(firstCall[1]).toEqual([targetPath, "/save", expect.stringContaining(".acl.tmp"), "/T"])
+			expect(firstCall[2]).toEqual({ windowsHide: true })
+
+			const secondCall = vi.mocked(execFile).mock.calls[1]
+			expect(secondCall[0]).toBe("icacls")
+			expect(secondCall[1]).toEqual([
+				expect.stringContaining("/tmp/test-dir"),
+				"/restore",
+				expect.stringContaining(".acl.tmp"),
+			])
+			expect(secondCall[2]).toEqual({ windowsHide: true })
+
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining(".acl.tmp"))
+		})
+
+		it("win32 DACL: dump is unlinked even when restore fails", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			let callCount = 0
+			vi.mocked(execFile).mockImplementation((_cmd, _args, _opts, cb) => {
+				callCount++
+				if (typeof cb === "function") {
+					cb(callCount === 1 ? null : new Error("icacls restore error"), "", "")
+				}
+				return fakeChild
+			})
+
+			await safeWriteText(targetPath, "data", { platform: "win32" })
+
+			expect(fs.rename).toHaveBeenCalled()
+			expect(fs.unlink).toHaveBeenCalledWith(expect.stringContaining(".acl.tmp"))
+		})
+
+		it("win32 DACL: when target does not exist, no save/restore/dump", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			// fs.access rejects for targetPath (ENOENT), but resolves for dirPath
+			vi.mocked(fs.access).mockImplementation(async (p) => {
+				if (typeof p === "string" && p.endsWith("target.txt")) throw { code: "ENOENT" }
+				return undefined
+			})
+
+			await safeWriteText(targetPath, "data", { platform: "win32" })
+
+			expect(execFile).not.toHaveBeenCalled()
+			expect(fs.unlink).not.toHaveBeenCalled()
+		})
+	})
+
+	// ── Test 6: pre-written temp path (tempPath option) ──────────────────────
+
+	describe("pre-written temp path", () => {
+		it("uses the provided tempPath, fsyncs it, and renames to target", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			const customTempPath = "/tmp/custom-temp.tmp"
+
+			await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+			expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+			expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+			expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+			expect(fs.unlink).not.toHaveBeenCalled()
+			expect(fsSync.mkdirSync).not.toHaveBeenCalled()
+		})
+
+		it("applies the existing target's mode to a caller-supplied tempPath before publishing", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600))
+			vi.mocked(fsSync.openSync).mockReturnValue(2)
+
+			const customTempPath = "/tmp/custom-temp.tmp"
+
+			await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+			// the temp is fchmod'd to the 0o600 target mode before the atomic rename (CWE-732)
+			expect(fsSync.fchmodSync).toHaveBeenCalledWith(2, 0o600)
+			expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+			expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+		})
+
+		it("keeps the temp's default mode when the target does not exist yet (ENOENT)", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			const enoent = Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })
+			vi.mocked(fsSync.statSync).mockImplementation(() => {
+				throw enoent
+			})
+			vi.mocked(fsSync.openSync).mockReturnValue(2)
+
+			const customTempPath = "/tmp/custom-temp.tmp"
+
+			await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+			expect(fsSync.fchmodSync).not.toHaveBeenCalled()
+			expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+		})
+
+		it("opens the temp before applying a read-only target's mode (0o444 does not block the open)", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o444))
+			vi.mocked(fsSync.openSync).mockReturnValue(3)
+
+			const customTempPath = "/tmp/custom-temp.tmp"
+
+			await safeWriteText(targetPath, "", { tempPath: customTempPath, platform: "linux" })
+
+			// a 0o444 target must not block the open; the mode is fchmod'd after it
+			expect(fsSync.openSync).toHaveBeenCalledWith(customTempPath, "r+")
+			expect(fsSync.fchmodSync).toHaveBeenCalledWith(3, 0o444)
+			const openIdx = vi.mocked(fsSync.openSync).mock.invocationCallOrder[0]
+			const fchmodIdx = vi.mocked(fsSync.fchmodSync).mock.invocationCallOrder[0]
+			expect(openIdx).toBeLessThan(fchmodIdx)
+			expect(fs.rename).toHaveBeenCalledWith(customTempPath, targetPath)
+		})
+
+		it("win32 + tempPath: the temp fd is the only fsync/closed fd (no POSIX directory fsync)", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+
+			await safeWriteText(targetPath, "", { tempPath: "/tmp/custom-temp.tmp", platform: "win32" })
+
+			// exactly one fsync+close pair (the temp fd); a directory fsync would add a second
+			expect(fsSync.fsyncSync).toHaveBeenCalledTimes(1)
+			expect(fsSync.closeSync).toHaveBeenCalledTimes(1)
+		})
+	})
+
+	// ── Test 7: symlink handling (Finding 4 regression test) ─────────────────
+
+	describe("symlink handling", () => {
+		it("a write through a symlink commits onto the resolved referent, never the link path", async () => {
+			const linkPath = "/tmp/links/link.txt"
+			const referentPath = "/tmp/targets/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(referentPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(linkPath, "new-content", { platform: "linux" })
+
+			// the commit rename targets the resolved referent, never the link itself
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), referentPath)
+			expect(fs.rename).not.toHaveBeenCalledWith(expect.anything(), linkPath)
+		})
+
+		it("when realpath reports ENOENT (target absent), uses the given path as-is", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockRejectedValue(Object.assign(new Error("ENOENT"), { code: "ENOENT" }))
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+
+			await safeWriteText(targetPath, "data", { platform: "linux" })
+
+			// rename still happened with the fallback path (path.resolve on /tmp → C:\tmp)
+			const resolvedFallback = _resolvedTarget(targetPath)
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), resolvedFallback)
+		})
+	})
+
+	// ── Test 8: review fixes (permissions, partial writes, resolution, durability) ──
+
+	describe("review fixes", () => {
+		it("preserves the target's restrictive mode and tolerates a failed staging-dir permission repair", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			vi.mocked(fsSync.statSync).mockReturnValue(_stats(0o600))
+			// a pre-existing staging dir may fail its best-effort permission repair
+			vi.mocked(fsSync.chmodSync).mockImplementationOnce(() => {
+				throw new Error("EACCES")
+			})
+
+			await safeWriteText(targetPath, "secret", { platform: "linux" })
+
+			expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o600)
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+		})
+
+		it("falls back to the 0o644 default when the target does not exist yet", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			vi.mocked(fsSync.statSync).mockImplementation(() => {
+				throw Object.assign(new Error("ENOENT"), { code: "ENOENT" })
+			})
+
+			await safeWriteText(targetPath, "fresh", { platform: "linux" })
+
+			expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), "w", 0o644)
+		})
+
+		it("loops on short writes until the full content is durable before fsync", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			const content = "0123456789" // 10 bytes
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			const buffer = Buffer.from(content, "utf8")
+			// first write (offset 0) reports 4 bytes (short write); the loop continues
+			vi.mocked(fsSync.writeSync).mockImplementation((...args: unknown[]) =>
+				args[2] === 0 ? 4 : typeof args[3] === "number" ? args[3] : 0,
+			)
+
+			await safeWriteText(targetPath, content, { platform: "linux" })
+
+			expect(fsSync.writeSync).toHaveBeenCalledTimes(2)
+			expect(fsSync.writeSync).toHaveBeenNthCalledWith(1, 1, buffer, 0, 10)
+			expect(fsSync.writeSync).toHaveBeenNthCalledWith(2, 1, buffer, 4, 6)
+			expect(fsSync.fsyncSync).toHaveBeenCalledWith(1)
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+		})
+
+		it("fsyncs the parent directory after the commit rename on POSIX", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValueOnce(1).mockReturnValue(2)
+
+			await safeWriteText(targetPath, "data", { platform: "linux" })
+
+			// the dir fsync (fd 2) is after the file fsync (fd 1); path-agnostic match
+			expect(fsSync.openSync).toHaveBeenCalledWith(expect.stringContaining("test-dir"), "r")
+			expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(1, 1)
+			expect(fsSync.fsyncSync).toHaveBeenNthCalledWith(2, 2)
+			expect(fsSync.closeSync).toHaveBeenCalledWith(2)
+		})
+
+		it("treats a failed parent-directory fsync as best-effort", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync)
+				.mockReturnValueOnce(1)
+				.mockImplementationOnce(() => {
+					throw new Error("EBADF")
+				})
+
+			// the content rename already committed; a missing directory fsync is not fatal
+			await safeWriteText(targetPath, "data", { platform: "linux" })
+
+			expect(fs.rename).toHaveBeenCalledWith(expect.stringContaining("safeWriteText_"), targetPath)
+		})
+
+		it("propagates realpath errors (EACCES, code-less, null, and function) instead of the fallback path", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			const eacces = Object.assign(new Error("EACCES: permission denied"), { code: "EACCES" })
+			vi.mocked(fs.realpath).mockRejectedValueOnce(eacces)
+			await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(eacces)
+			expect(fs.rename).not.toHaveBeenCalled()
+
+			const plain = new Error("resolution failed")
+			vi.mocked(fs.realpath).mockRejectedValueOnce(plain)
+			await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(plain)
+			expect(fs.rename).not.toHaveBeenCalled()
+
+			// non-object rejections must propagate untouched: null (no TypeError from
+			// the guard) and a function carrying code:ENOENT (not an object → rethrow)
+			vi.mocked(fs.realpath).mockRejectedValueOnce(null)
+			await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBeNull()
+			const fnErr: unknown = Object.assign(() => undefined, { code: "ENOENT" })
+			vi.mocked(fs.realpath).mockRejectedValueOnce(fnErr)
+			await expect(safeWriteText(targetPath, "data", { platform: "linux" })).rejects.toBe(fnErr)
+		})
+
+		it("backup:true propagates access errors (EACCES and code-less) instead of skipping the backup", async () => {
+			const targetPath = "/tmp/test-dir/target.txt"
+			const eacces = Object.assign(new Error("EACCES"), { code: "EACCES" })
+			const plain = new Error("access failed")
+			vi.mocked(fs.realpath).mockResolvedValue(targetPath)
+			vi.mocked(fsSync.openSync).mockReturnValue(1)
+			// each write accesses dirPath then target; only the target access rejects
+			const rejectTarget = (error: Error) => async (p: unknown) => {
+				if (typeof p === "string" && p.endsWith("target.txt")) throw error
+			}
+			vi.mocked(fs.access)
+				.mockImplementationOnce(rejectTarget(eacces))
+				.mockImplementationOnce(rejectTarget(eacces))
+				.mockImplementationOnce(rejectTarget(plain))
+				.mockImplementationOnce(rejectTarget(plain))
+
+			await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toEqual(
+				expect.objectContaining({ code: "EACCES" }),
+			)
+			await expect(safeWriteText(targetPath, "data", { backup: true, platform: "linux" })).rejects.toThrow(
+				"access failed",
+			)
+			expect(fs.rename).not.toHaveBeenCalled()
+		})
+	})
+})
diff --git a/src/services/file-safety/safeWriteText.ts b/src/services/file-safety/safeWriteText.ts
new file mode 100644
index 0000000000..29025b3a28
--- /dev/null
+++ b/src/services/file-safety/safeWriteText.ts
@@ -0,0 +1,304 @@
+import * as fs from "fs/promises"
+import * as fsSync from "fs"
+import * as path from "path"
+import { execFile } from "child_process"
+
+/**
+ * Options for safeWriteText atomic text publish primitive.
+ */
+export interface SafeWriteTextOptions {
+	/**
+	 * When true, preserve the old-file semantics: rename target -> backup first,
+	 * after commit rename delete the backup; on failure roll the backup back to
+	 * the target path.  When false (default) the atomic rename simply replaces
+	 * the target -- crash-safe window is zero.
+	 */
+	backup?: boolean
+
+	/**
+	 * Platform override for testing.  When omitted the real process.platform
+	 * value is used.  Set to "win32" or "linux" / "darwin" from tests so that
+	 * both branches are reachable without needing a real Windows runner.
+	 */
+	platform?: string
+
+	/**
+	 * Custom execFile runner for testing (e.g. vi.fn).  When omitted the real
+	 * child_process.execFile is used.
+	 */
+	execFileRunner?: typeof execFile
+
+	/**
+	 * Pre-written temp path to use for the commit phase.  When provided,
+	 * safeWriteText skips creating its own staging file and uses this path
+	 * instead (it still fsyncs before rename).  Useful when a caller has
+	 * already written data to a temp file via a custom stream.
+	 */
+	tempPath?: string
+}
+
+// -- helpers ---------------------------------------------------------------
+
+/** Generate a unique temp file name in the given directory. */
+function _tempName(dir: string, prefix: string): string {
+	return path.join(dir, "." + prefix + "_" + Date.now() + "_" + Math.random().toString(36).substring(2) + ".tmp")
+}
+
+/** Create a private staging sub-directory inside *dir* so that multiple
+ * concurrent writes never collide on their temp names. */
+function _stagingDir(dir: string): string {
+	const sd = path.join(dir, ".file-safety-staging")
+	// mode:0o700 protects a freshly created staging dir; the best-effort chmod
+	// repairs a pre-existing one (mkdirSync with recursive:true never chmods an
+	// existing directory), so staged temp files are never group/world readable.
+	fsSync.mkdirSync(sd, { recursive: true, mode: 0o700 })
+	try {
+		fsSync.chmodSync(sd, 0o700)
+	} catch {
+		// best-effort: chmod denied or unavailable; a fresh dir was still
+		// created with the requested mode
+	}
+	return sd
+}
+
+/**
+ * fsync a file descriptor so its data is durable before the atomic rename.
+ * Uses the sync form because this repo's @types/node does not declare
+ * fs.promises.fsync; the staging file is small, so the blocking window is bounded.
+ */
+function _fsyncFile(fd: number): void {
+	fsSync.fsyncSync(fd)
+}
+
+/** Save the DACL of *srcPath* to a dump file on Windows.
+ * Returns true when the dump was written successfully; false otherwise.
+ * Never throws — callers treat failure as "skip DACL handling". */
+async function _saveDaclWindows(srcPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise<boolean> {
+	const runner = execFileRunner ?? execFile
+	try {
+		await new Promise<void>((resolve, reject) => {
+			runner("icacls", [srcPath, "/save", dumpPath, "/T"], { windowsHide: true }, (err) =>
+				err ? reject(err) : resolve(),
+			)
+		})
+		return true
+	} catch {
+		return false
+	}
+}
+
+/** Restore a DACL dump onto *dirPath* on Windows.
+ * Best-effort: content is already committed, so failure is non-fatal. */
+async function _restoreDaclWindows(dirPath: string, dumpPath: string, execFileRunner?: typeof execFile): Promise<void> {
+	const runner = execFileRunner ?? execFile
+	try {
+		await new Promise<void>((resolve, reject) => {
+			runner("icacls", [dirPath, "/restore", dumpPath], { windowsHide: true }, (err) =>
+				err ? reject(err) : resolve(),
+			)
+		})
+	} catch {
+		// best-effort; content already committed
+	}
+}
+
+// -- public API ------------------------------------------------------------
+
+/**
+ * Atomic text publish primitive.
+ *
+ * 1. Write content to a temp file in a private per-write staging subdir
+ *    (same volume -> atomic rename guaranteed).
+ * 2. fsync the temp file, then close it.
+ * 3. win32 only: if target exists save its DACL dump BEFORE backup rename.
+ * 4. Optionally rename target -> backup (when backup:true).
+ * 5. Atomic rename temp -> target.
+ * 6. win32 only: restore DACL onto the directory AFTER commit rename.
+ * 7. On success: delete backup (if any) and unlink DACL dump.
+ * 8. On failure: rollback backup to target path; clean up temp + dump.
+ */
+
+/**
+ * Resolve the publish target: the symlink referent when the given path is an
+ * existing symlink, the path itself otherwise. Only ENOENT (target absent yet)
+ * may fall back to the given path; any other resolution error (EACCES, EIO, ...)
+ * propagates so a broken or unreadable symlink is never written through its
+ * link path. Callers that stage a temp file themselves must stage it beside
+ * the resolved path: the commit is a rename onto the referent, and a rename
+ * across filesystems fails with EXDEV.
+ */
+export async function resolvePublishTarget(absoluteFilePath: string): Promise<string> {
+	return fs.realpath(absoluteFilePath).catch((error: unknown) => {
+		const code = typeof error === "object" && error !== null ? (error as { code?: string }).code : undefined
+		if (code !== "ENOENT") throw error
+		return absoluteFilePath
+	})
+}
+
+export async function safeWriteText(filePath: string, content: string, options?: SafeWriteTextOptions): Promise<void> {
+	const absoluteFilePath = path.resolve(filePath)
+
+	// Resolve the symlink referent (see resolvePublishTarget).
+	const targetPath = await resolvePublishTarget(absoluteFilePath)
+	const dirPath = path.dirname(targetPath)
+	const opts: SafeWriteTextOptions = options ?? {}
+
+	// Ensure parent directory exists (mirrors safeWriteJson behaviour).
+	await fs.mkdir(dirPath, { recursive: true })
+	await fs.access(dirPath)
+
+	// Create the staging directory only when we generate the temp file there;
+	// callers supplying their own tempPath (e.g. safeWriteJson) must not be left
+	// with an empty .file-safety-staging directory behind.
+	const tempPath = opts.tempPath ?? _tempName(_stagingDir(dirPath), "safeWriteText")
+
+	let backupPath: string | null = null
+	let releaseBackupOnSuccess = false
+	let daclDumpPath: string | null = null // tracked for cleanup in finally
+
+	try {
+		// -- Step 1: write content to staging temp file -------------------
+		if (!opts.tempPath) {
+			// Preserve the existing target's permissions: the staging file must
+			// not be published wider than the file it replaces (a 0o600 target
+			// must not become 0o644 through the atomic rename).
+			let targetMode = 0o644 // default for a fresh target
+			try {
+				targetMode = fsSync.statSync(targetPath).mode & 0o777
+			} catch {
+				// target does not exist yet - keep the default
+			}
+			const fd = fsSync.openSync(tempPath, "w", targetMode)
+			try {
+				// Loop until every byte is written: writeSync can report a short
+				// (partial) write, and publishing a truncated staging file would
+				// commit corrupt content.
+				const buffer = Buffer.from(content)
+				let offset = 0
+				while (offset < buffer.length) {
+					offset += fsSync.writeSync(fd, buffer, offset, buffer.length - offset)
+				}
+				_fsyncFile(fd)
+			} finally {
+				fsSync.closeSync(fd)
+			}
+		} else {
+			// Preserve the existing target's mode (CWE-732): the caller-staged
+			// temp carries its own creation mode, and publishing it as-is would
+			// widen a restrictive target (e.g. 0o600 -> 0o644) through rename.
+			// The mode is applied with fchmodSync on the open fd (AFTER openSync):
+			// chmodSync on the path before the open would make a read-only target
+			// (0o400/0o444) fail openSync(tempPath, "r+") with EACCES.
+			let targetMode: number | null = null
+			try {
+				targetMode = fsSync.statSync(targetPath).mode & 0o777
+			} catch {
+				// target does not exist yet - keep the temp's default mode
+			}
+			const fd = fsSync.openSync(tempPath, "r+")
+			try {
+				if (targetMode !== null) {
+					fsSync.fchmodSync(fd, targetMode)
+				}
+				_fsyncFile(fd)
+			} finally {
+				fsSync.closeSync(fd)
+			}
+		}
+
+		// -- Step 2 (win32): save DACL BEFORE backup rename ---------------
+		const platform = options?.platform ?? process.platform
+		if (platform === "win32") {
+			try {
+				await fs.access(targetPath) // target exists?
+				daclDumpPath = targetPath + ".acl.tmp"
+				const saved = await _saveDaclWindows(targetPath, daclDumpPath, opts.execFileRunner)
+				if (!saved) {
+					daclDumpPath = null // skip DACL handling entirely
+				}
+			} catch {
+				// target does not exist or access failed — no DACL handling
+				daclDumpPath = null
+			}
+		}
+
+		try {
+			// -- Step 3 (backup:true): rename target -> backup --------------
+			if (opts.backup) {
+				try {
+					await fs.access(targetPath)
+					backupPath = _tempName(dirPath, "safeWriteText.bak")
+					await fs.rename(targetPath, backupPath)
+					releaseBackupOnSuccess = true
+				} catch (err: unknown) {
+					const code = typeof err === "object" && err !== null ? (err as { code?: string }).code : undefined
+					if (code !== "ENOENT") throw err
+				}
+			}
+
+			// -- Step 4: atomic rename temp -> target ---------------------
+			await fs.rename(tempPath, targetPath)
+
+			// -- Step 4b (POSIX): fsync the parent directory so the directory entry
+			// changed by the commit rename is durable, not just the file content.
+			if (platform !== "win32") {
+				try {
+					const dirFd = fsSync.openSync(dirPath, "r")
+					try {
+						_fsyncFile(dirFd)
+					} finally {
+						fsSync.closeSync(dirFd)
+					}
+				} catch {
+					// best-effort: the content rename already committed
+				}
+			}
+
+			// -- Step 5 (win32): restore DACL AFTER commit rename ---------
+			// daclDumpPath is non-null only on the win32 save path above, so the
+			// platform check is redundant here.
+			if (daclDumpPath !== null) {
+				const restoredDir = path.dirname(targetPath)
+				await _restoreDaclWindows(restoredDir, daclDumpPath, opts.execFileRunner)
+			}
+
+			// -- Step 6 (backup:true): delete backup on success -----------
+			if (releaseBackupOnSuccess && backupPath) {
+				try {
+					await fs.unlink(backupPath)
+				} catch {
+					// non-fatal — orphaned backup is acceptable
+				}
+			}
+		} finally {
+			// Unlink DACL dump regardless of success/failure in this span.
+			if (daclDumpPath !== null) {
+				await fs.unlink(daclDumpPath).catch(() => {})
+			}
+		}
+
+		// tempPath is now the committed file; no cleanup needed.
+	} catch (originalError: unknown) {
+		// -- Rollback / cleanup on failure ----------------------------------
+		if (backupPath && releaseBackupOnSuccess) {
+			try {
+				await fs.rename(backupPath, targetPath)
+			} catch {
+				// rollback failed — do not mask original error
+			}
+		}
+
+		// Always clean up the staging temp file on failure.
+		try {
+			await fs.unlink(tempPath).catch(() => {})
+		} catch {
+			// cleanup failure is non-fatal
+		}
+
+		if (daclDumpPath !== null) {
+			await fs.unlink(daclDumpPath).catch(() => {})
+		}
+
+		throw originalError
+	}
+}