File dialogs & artefact helpers — dedicated pickers + host helpers (#6)

- One dedicated method per purpose: selectTargetFile (save .ti1),
  selectExistingTarget (ti1/ti2), selectProfileFile (icc/icm/mpp —
  never ti*, #172), selectSpectrumFile (.sp), selectDatasetFile
  (open-only ti3/txt/cgats/csv, #211), selectCsvSavePath, selectCalFile,
  selectDirectory. No shared generic picker API (#103/#210/#211).
- Ti2Header: TARGET_INSTRUMENT / NUMBER_OF_SETS / NUMBER_OF_PAGES +
  sibling .ti1 detection; NUMBER_OF_FIELDS explicitly not patch count
- TiffPreview: host-side TIFF→PNG thumbnail, 1200px max edge (#58)
- ArtefactFiles: defaultWorkingDirectory, readBase64, appInfo
- 7 new tests; 47/47 green

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Packages/ICCeryCore/Sources/ICCeryCore/Files/ArtefactFiles.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+/// Small host-side file helpers (issue #6).
+public enum ArtefactFiles {
+
+    /// `get_default_working_dir` — `resolveSafeCwd(nil)`.
+    public static func defaultWorkingDirectory() -> URL {
+        PathSecurity.resolveSafeCwd(nil)
+    }
+
+    /// `read_file_base64` — for **text artefacts** the UI needs verbatim
+    /// (ti1/ti2 previews, CGATS datasets, logs). Binary payloads (TIFF)
+    /// go through `TiffPreview` instead.
+    public static func readBase64(_ url: URL) throws -> String {
+        try Data(contentsOf: url).base64EncodedString()
+    }
+
+    /// `get_app_info` — version + build for the About dialog.
+    public static func appInfo(
+        bundle: Bundle = .main
+    ) -> (version: String, build: String) {
+        let info = bundle.infoDictionary ?? [:]
+        return (
+            info["CFBundleShortVersionString"] as? String ?? "0.0.0",
+            info["CFBundleVersion"] as? String ?? "0"
+        )
+    }
+}

Packages/ICCeryCore/Sources/ICCeryCore/Files/ArtefactProbe.swift

@@ -0,0 +1,98 @@
+import Foundation
+
+/// Result of `verify_stage_artefacts(cwd, basename)` (docs/06).
+public struct StageArtefacts: Sendable, Equatable {
+    /// `<basename>.ti1` exists (Stage 1 done → unlocks Stage 2).
+    public var stage1Complete = false
+    /// `<basename>.ti2` exists (Stage 2 done → with ti1, unlocks Stage 3).
+    public var stage2Complete = false
+    /// `<basename>.ti3` exists (Stage 3 done → unlocks Stage 4).
+    public var stage3Complete = false
+    /// `.icc`/`.icm` exists (Stage 4 done → with ti3, unlocks Stage 5).
+    public var stage4Complete = false
+    /// Absolute path of the profile file when present.
+    public var profilePath: URL?
+}
+
+/// Filesystem probing for wizard artefacts (docs/02 §Working directory,
+/// docs/06 §Stages). All artefacts live next to each other in `cwd`.
+public enum ArtefactProbe {
+
+    /// `verify_stage_artefacts` — the gating truth source.
+    public static func verify(
+        basename: String,
+        cwd: URL,
+        fileManager: FileManager = .default
+    ) -> StageArtefacts {
+        var out = StageArtefacts()
+        out.stage1Complete = exists(artefact(basename, "ti1", cwd), fm: fileManager)
+        out.stage2Complete = exists(artefact(basename, "ti2", cwd), fm: fileManager)
+        out.stage3Complete = exists(artefact(basename, "ti3", cwd), fm: fileManager)
+        if let profile = resolveProfile(basename: basename, cwd: cwd, fileManager: fileManager) {
+            out.stage4Complete = true
+            out.profilePath = profile
+        }
+        return out
+    }
+
+    /// `<cwd>/<basename>.<ext>` — the canonical artefact URL.
+    public static func artefact(_ basename: String, _ ext: String, _ cwd: URL) -> URL {
+        cwd.appendingPathComponent("\(basename).\(ext)", isDirectory: false)
+    }
+
+    /// Profile extension resolution (#69): existing `.icm` wins over
+    /// `.icc`; when neither exists the macOS default is `.icc`.
+    /// (`profcheck`/`iccgamut` swap extension when the requested path is
+    /// missing.)
+    public static func resolveProfile(
+        basename: String,
+        cwd: URL,
+        fileManager: FileManager = .default
+    ) -> URL? {
+        let icm = artefact(basename, "icm", cwd)
+        if exists(icm, fm: fileManager) { return icm }
+        let icc = artefact(basename, "icc", cwd)
+        if exists(icc, fm: fileManager) { return icc }
+        return nil
+    }
+
+    /// Default extension for a *new* profile on macOS (#69).
+    public static let defaultProfileExtension = "icc"
+
+    /// Every artefact path for a basename: `.ti1 .ti2 .tif .N.tif
+    /// .ti3 _passN.ti3 .icc .icm .gam` plus the `CAL_<basename>` namespace.
+    /// Multi-page TIFFs match `<basename>.tif`, `<basename>.1.tif` … and
+    /// `<basename>_NN.tif` (manifest naming).
+    public static func existingArtefacts(
+        basename: String,
+        cwd: URL,
+        fileManager: FileManager = .default
+    ) -> [URL] {
+        guard let entries = try? fileManager.contentsOfDirectory(
+            at: cwd,
+            includingPropertiesForKeys: nil,
+            options: [.skipsHiddenFiles]
+        ) else { return [] }
+
+        let prefixes = [basename + ".", "CAL_" + basename + "."]
+        let suffixes: Set<String> = ["ti1", "ti2", "tif", "ti3", "icc", "icm", "gam", "cal"]
+        let passPrefix = basename + "_pass"
+        let tifStemPrefix = basename + "_"
+        let calPrefix = "CAL_" + basename
+
+        return entries.filter { url in
+            let name = url.lastPathComponent
+            let ext = url.pathExtension.lowercased()
+            guard suffixes.contains(ext) else { return false }
+            if prefixes.contains(where: { name.hasPrefix($0) }) { return true }
+            if name.hasPrefix(passPrefix), ext == "ti3" { return true }
+            if name.hasPrefix(tifStemPrefix), ext == "tif" { return true }
+            if name.hasPrefix(calPrefix) { return true }
+            return false
+        }.sorted { $0.lastPathComponent < $1.lastPathComponent }
+    }
+
+    private static func exists(_ url: URL, fm: FileManager) -> Bool {
+        fm.fileExists(atPath: url.path)
+    }
+}

Packages/ICCeryCore/Sources/ICCeryCore/Files/AtomicFileWriter.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+/// Atomic `.tmp`-then-rename file writes — the convention used by
+/// settings.json, verification_history.json and wizard_state.json
+/// (docs/02 §Persistence, #213).
+public enum AtomicFileWriter {
+
+    /// Writes `data` to `url` atomically: sibling `<name>.tmp`, then a
+    /// rename (which is atomic on APFS/HFS+). Parent dirs are created.
+    public static func write(_ data: Data, to url: URL) throws {
+        let fm = FileManager.default
+        let dir = url.deletingLastPathComponent()
+        try fm.createDirectory(at: dir, withIntermediateDirectories: true)
+
+        let tmp = url.appendingPathExtension("tmp")
+        do {
+            try data.write(to: tmp, options: [])
+            // replaceItemAt handles same-volume atomic swap and removes
+            // the destination cleanly; fall back to remove+move.
+            if fm.fileExists(atPath: url.path) {
+                _ = try fm.replaceItemAt(url, withItemAt: tmp)
+            } else {
+                try fm.moveItem(at: tmp, to: url)
+            }
+        } catch {
+            try? fm.removeItem(at: tmp)
+            throw error
+        }
+    }
+
+    public static func write(_ text: String, to url: URL) throws {
+        try write(Data(text.utf8), to: url)
+    }
+}

Packages/ICCeryCore/Sources/ICCeryCore/Files/PathSecurity.swift

@@ -0,0 +1,54 @@
+import Foundation
+
+/// Basename sanitisation and safe working-directory resolution
+/// (docs/02 §Working directory, docs/06 §Empty cwd).
+public enum PathSecurity {
+
+    public enum Error: Swift.Error, Equatable, Sendable {
+        case invalidBasename(String)
+    }
+
+    /// Basenames must not contain `/`, `\`, or `..` and must be
+    /// non-empty. Never invent a default basename (#60).
+    public static func isValidBasename(_ name: String) -> Bool {
+        guard !name.isEmpty else { return false }
+        return !name.contains("/") && !name.contains("\\") && !name.contains("..")
+    }
+
+    @discardableResult
+    public static func sanitizeBasename(_ name: String) throws -> String {
+        guard isValidBasename(name) else {
+            throw Error.invalidBasename(name)
+        }
+        return name
+    }
+
+    /// `resolve_safe_cwd` (docs/04 §0.2): explicit real directory →
+    /// Documents → Home → app-data. Never returns an empty/nil cwd.
+    public static func resolveSafeCwd(
+        _ explicit: URL?,
+        fileManager: FileManager = .default
+    ) -> URL {
+        if let explicit,
+           fileManager.fileExists(atPath: explicit.path, isDirectory: nil) {
+            return explicit
+        }
+        let candidates: [URL?] = [
+            fileManager.urls(for: .documentDirectory, in: .userDomainMask).first,
+            fileManager.homeDirectoryForCurrentUser,
+            AppPaths.appDataDir,
+        ]
+        for candidate in candidates {
+            guard let url = candidate else { continue }
+            if !fileManager.fileExists(atPath: url.path) {
+                try? fileManager.createDirectory(at: url, withIntermediateDirectories: true)
+            }
+            if fileManager.fileExists(atPath: url.path, isDirectory: nil) {
+                return url
+            }
+        }
+        // Last resort: app-data, created unconditionally.
+        try? fileManager.createDirectory(at: AppPaths.appDataDir, withIntermediateDirectories: true)
+        return AppPaths.appDataDir
+    }
+}

Packages/ICCeryCore/Sources/ICCeryCore/Files/Ti2Header.swift

@@ -0,0 +1,53 @@
+import Foundation
+
+/// Parsed header of a `.ti2` chart-layout file (docs/06 §Resume).
+/// `parse_ti2_header` reads only CGATS keyword lines — the data grid
+/// itself belongs to issue #30.
+public struct Ti2Header: Sendable, Equatable {
+    /// `TARGET_INSTRUMENT` (e.g. `i1`, `i1iO`, `CM`).
+    public var instrument: String?
+    /// `NUMBER_OF_SETS` — the patch count. Note: `NUMBER_OF_FIELDS` is
+    /// the CGATS column count, *not* the patch count.
+    public var patchCount: Int?
+    /// `NUMBER_OF_PAGES`.
+    public var pageCount: Int?
+    /// A sibling `<stem>.ti1` exists next to the parsed file.
+    public var hasSiblingTi1 = false
+
+    public static func parse(
+        _ url: URL,
+        fileManager: FileManager = .default
+    ) -> Ti2Header {
+        var header = Ti2Header()
+        guard let text = try? String(contentsOf: url, encoding: .utf8) else {
+            return header
+        }
+        for rawLine in text.split(whereSeparator: \.isNewline) {
+            let line = rawLine.trimmingCharacters(in: .whitespaces)
+            if line.hasPrefix("BEGIN_DATA_FORMAT") || line.hasPrefix("BEGIN_DATA") {
+                break
+            }
+            // CGATS keyword lines: `KEYWORD "value"` or `KEYWORD value`.
+            guard let space = line.firstIndex(of: " ") else { continue }
+            let key = String(line[..<space])
+            let value = String(line[line.index(after: space)...])
+                .trimmingCharacters(in: .whitespaces)
+                .trimmingCharacters(in: CharacterSet(charactersIn: "\""))
+            switch key {
+            case "TARGET_INSTRUMENT":
+                header.instrument = value
+            case "NUMBER_OF_SETS":
+                header.patchCount = Int(value)
+            case "NUMBER_OF_PAGES":
+                header.pageCount = Int(value)
+            default:
+                continue
+            }
+        }
+        let stem = url.deletingPathExtension()
+        header.hasSiblingTi1 = fileManager.fileExists(
+            atPath: stem.appendingPathExtension("ti1").path
+        )
+        return header
+    }
+}

Packages/ICCeryCore/Sources/ICCeryCore/Files/TiffPreview.swift

@@ -0,0 +1,38 @@
+import Foundation
+import ImageIO
+import UniformTypeIdentifiers
+
+/// TIFF → PNG preview for the Stage 2 gallery (#58): decode on the host
+/// side, cap the long edge at 1200 px, emit PNG. Never hand raw TIFF
+/// bytes to the UI.
+public enum TiffPreview {
+
+    public static let maxEdge: Int = 1200
+
+    /// Returns PNG data for the first page of a TIFF, or `nil` when the
+    /// file cannot be decoded.
+    public static func previewPNG(
+        tiff url: URL,
+        maxEdge: Int = Self.maxEdge
+    ) -> Data? {
+        guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
+            return nil
+        }
+        let options: [CFString: Any] = [
+            kCGImageSourceCreateThumbnailFromImageAlways: true,
+            kCGImageSourceThumbnailMaxPixelSize: maxEdge,
+            kCGImageSourceCreateThumbnailWithTransform: true,
+        ]
+        guard let image = CGImageSourceCreateThumbnailAtIndex(
+            source, 0, options as CFDictionary
+        ) else { return nil }
+
+        let out = NSMutableData()
+        guard let dest = CGImageDestinationCreateWithData(
+            out, UTType.png.identifier as CFString, 1, nil
+        ) else { return nil }
+        CGImageDestinationAddImage(dest, image, nil)
+        guard CGImageDestinationFinalize(dest) else { return nil }
+        return out as Data
+    }
+}

Sources/ICCery/FileDialogService.swift

@@ -0,0 +1,112 @@
+import AppKit
+import UniformTypeIdentifiers
+
+/// Dedicated NSOpenPanel / NSSavePanel wrappers (issue #6) — one method
+/// per purpose, matching the v1 `select_*` commands (docs/21 §Dialogs).
+/// No call site shares a generic picker (#103/#210/#211).
+@MainActor
+final class FileDialogService {
+
+    static let shared = FileDialogService()
+    private init() {}
+
+    // MARK: - selectDirectory
+
+    /// `#btnBrowse` — working directory for Argyll artefacts.
+    /// Defaults to Documents (docs/06 §Empty cwd).
+    func selectDirectory(startingAt start: URL? = nil) -> URL? {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = true
+        panel.canChooseFiles = false
+        panel.allowsMultipleSelection = false
+        panel.directoryURL = start
+            ?? FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first
+        panel.prompt = "Choose"
+        return run(panel)
+    }
+
+    // MARK: - Dedicated open pickers
+
+    /// `selectTargetFile` — **save** panel for the new `.ti1` target.
+    func selectTargetFile(startingAt start: URL? = nil) -> URL? {
+        let panel = NSSavePanel()
+        panel.nameFieldStringValue = "target.ti1"
+        panel.allowedContentTypes = utTypes(["ti1"])
+        panel.allowsOtherFileTypes = false
+        panel.directoryURL = start
+        panel.message = "Choose the .ti1 target file to create"
+        return run(panel)
+    }
+
+    /// `selectExistingTarget` — open `.ti1`/`.ti2` (docs/06 §Resume, #140).
+    func selectExistingTarget(startingAt start: URL? = nil) -> URL? {
+        open(extensions: ["ti1", "ti2"], startingAt: start,
+             message: "Open an existing target (.ti1 or .ti2)")
+    }
+
+    /// `selectProfileFile` — `.icc`/`.icm`/`.mpp` only — **never** `.ti*`
+    /// (#172: the profile filter must not accept datasets).
+    func selectProfileFile(startingAt start: URL? = nil) -> URL? {
+        open(extensions: ["icc", "icm", "mpp"], startingAt: start,
+             message: "Choose an ICC/ICM profile or measurement preconditioning file")
+    }
+
+    /// `selectSpectrumFile` — `.sp` illuminant spectrum (colprof -i).
+    func selectSpectrumFile(startingAt start: URL? = nil) -> URL? {
+        open(extensions: ["sp"], startingAt: start,
+             message: "Choose a custom illuminant spectrum (.sp)")
+    }
+
+    /// `selectDatasetFile` — open a measured dataset (`.ti3`, `.txt`,
+    /// `.cgats`, `.csv`). Always an *open* dialog, never save (#211).
+    func selectDatasetFile(startingAt start: URL? = nil) -> URL? {
+        open(extensions: ["ti3", "txt", "cgats", "csv"], startingAt: start,
+             message: "Import a measured dataset")
+    }
+
+    /// `selectCsvSavePath` — verification-history CSV export.
+    func selectCsvSavePath(startingAt start: URL? = nil) -> URL? {
+        let panel = NSSavePanel()
+        panel.nameFieldStringValue = "verification-history.csv"
+        panel.allowedContentTypes = utTypes(["csv"])
+        panel.allowsOtherFileTypes = false
+        panel.directoryURL = start
+        return run(panel)
+    }
+
+    /// `selectCalFile` — `.cal` calibration curves.
+    func selectCalFile(startingAt start: URL? = nil) -> URL? {
+        open(extensions: ["cal"], startingAt: start,
+             message: "Choose a calibration file (.cal)")
+    }
+
+    // MARK: - Internals (private — not a shared public picker API)
+
+    private func open(
+        extensions: [String],
+        startingAt start: URL?,
+        message: String?
+    ) -> URL? {
+        let panel = NSOpenPanel()
+        panel.canChooseDirectories = false
+        panel.canChooseFiles = true
+        panel.allowsMultipleSelection = false
+        panel.allowedContentTypes = utTypes(extensions)
+        panel.allowsOtherFileTypes = true
+        panel.directoryURL = start
+        if let message { panel.message = message }
+        return run(panel)
+    }
+
+    private func utTypes(_ extensions: [String]) -> [UTType] {
+        extensions.compactMap { UTType(filenameExtension: $0) }
+    }
+
+    private func run(_ panel: NSOpenPanel) -> URL? {
+        panel.runModal() == .OK ? panel.url : nil
+    }
+
+    private func run(_ panel: NSSavePanel) -> URL? {
+        panel.runModal() == .OK ? panel.url : nil
+    }
+}

Tests/ICCeryCoreTests/ArtefactFilesTests.swift

@@ -0,0 +1,124 @@
+import Testing
+import Foundation
+import ImageIO
+import UniformTypeIdentifiers
+@testable import ICCeryCore
+
+private func tempURL(_ name: String) -> URL {
+    FileManager.default.temporaryDirectory
+        .appendingPathComponent("iccery-af-\(UUID().uuidString)")
+        .appendingPathComponent(name)
+}
+
+@Suite("Ti2Header")
+struct Ti2HeaderTests {
+    @Test func parsesKeywordsAndSibling() throws {
+        let dir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("iccery-ti2-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        try """
+        CTI2
+        TARGET_INSTRUMENT "i1iO"
+        NUMBER_OF_FIELDS 9
+        NUMBER_OF_SETS 800
+        NUMBER_OF_PAGES 3
+        BEGIN_DATA_FORMAT
+        SAMPLE_ID RGB_R
+        END_DATA_FORMAT
+        """.write(to: dir.appendingPathComponent("job.ti2"), atomically: true, encoding: .utf8)
+        try "CGATS".write(
+            to: dir.appendingPathComponent("job.ti1"), atomically: true, encoding: .utf8
+        )
+
+        let h = Ti2Header.parse(dir.appendingPathComponent("job.ti2"))
+        #expect(h.instrument == "i1iO")
+        #expect(h.patchCount == 800)
+        #expect(h.pageCount == 3)
+        #expect(h.hasSiblingTi1)
+    }
+
+    @Test func missingFileYieldsEmptyHeader() {
+        let h = Ti2Header.parse(URL(fileURLWithPath: "/nonexistent/x.ti2"))
+        #expect(h.instrument == nil && h.patchCount == nil && !h.hasSiblingTi1)
+    }
+
+    @Test func numberOfFieldsIsNotPatchCount() throws {
+        let url = tempURL("t.ti2")
+        try FileManager.default.createDirectory(
+            at: url.deletingLastPathComponent(), withIntermediateDirectories: true
+        )
+        try "NUMBER_OF_FIELDS 9\nNUMBER_OF_SETS 52\nBEGIN_DATA\n".write(
+            to: url, atomically: true, encoding: .utf8
+        )
+        #expect(Ti2Header.parse(url).patchCount == 52)
+    }
+}
+
+@Suite("TiffPreview")
+struct TiffPreviewTests {
+    /// Builds a real 2000×1000 TIFF in a temp dir via ImageIO.
+    private func makeTiff(width: Int = 2000, height: Int = 1000) throws -> URL {
+        let url = tempURL("big.tif")
+        try FileManager.default.createDirectory(
+            at: url.deletingLastPathComponent(), withIntermediateDirectories: true
+        )
+        let colorSpace = CGColorSpace(name: CGColorSpace.sRGB)!
+        let ctx = CGContext(
+            data: nil, width: width, height: height,
+            bitsPerComponent: 8, bytesPerRow: width * 4,
+            space: colorSpace,
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        )!
+        ctx.setFillColor(CGColor(red: 0.5, green: 0.5, blue: 0.5, alpha: 1))
+        ctx.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        let image = ctx.makeImage()!
+
+        guard let dest = CGImageDestinationCreateWithURL(
+            url as CFURL, UTType.tiff.identifier as CFString, 1, nil
+        ) else { throw CocoaError(.fileWriteUnknown) }
+        CGImageDestinationAddImage(dest, image, nil)
+        guard CGImageDestinationFinalize(dest) else { throw CocoaError(.fileWriteUnknown) }
+        return url
+    }
+
+    @Test func producesCappedPNG() throws {
+        let tiff = try makeTiff()
+        let png = TiffPreview.previewPNG(tiff: tiff)
+        #expect(png != nil)
+        // PNG magic
+        #expect(png!.prefix(8) == Data([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]))
+        // Verify the cap by decoding the thumbnail header.
+        let src = CGImageSourceCreateWithData(png! as CFData, nil)!
+        let img = CGImageSourceCreateImageAtIndex(src, 0, nil)!
+        #expect(max(img.width, img.height) <= TiffPreview.maxEdge)
+        #expect(img.width == 1200)
+    }
+
+    @Test func nonTiffReturnsNil() throws {
+        let url = tempURL("not-tiff.txt")
+        try FileManager.default.createDirectory(
+            at: url.deletingLastPathComponent(), withIntermediateDirectories: true
+        )
+        try "hello".write(to: url, atomically: true, encoding: .utf8)
+        #expect(TiffPreview.previewPNG(tiff: url) == nil)
+    }
+}
+
+@Suite("ArtefactFiles")
+struct ArtefactFilesTests {
+    @Test func base64RoundTrip() throws {
+        let url = tempURL("a.txt")
+        try FileManager.default.createDirectory(
+            at: url.deletingLastPathComponent(), withIntermediateDirectories: true
+        )
+        try "hello".write(to: url, atomically: true, encoding: .utf8)
+        let b64 = try ArtefactFiles.readBase64(url)
+        #expect(Data(base64Encoded: b64) == Data("hello".utf8))
+    }
+
+    @Test func defaultWorkingDirExists() {
+        #expect(FileManager.default.fileExists(
+            atPath: ArtefactFiles.defaultWorkingDirectory().path
+        ))
+    }
+}

Tests/ICCeryCoreTests/FileHelpersTests.swift

@@ -0,0 +1,129 @@
+import Testing
+import Foundation
+@testable import ICCeryCore
+
+private func tempDir(_ name: String = UUID().uuidString) throws -> URL {
+    let url = FileManager.default.temporaryDirectory
+        .appendingPathComponent("iccery-files-\(name)")
+    try FileManager.default.createDirectory(at: url, withIntermediateDirectories: true)
+    return url
+}
+
+private func touch(_ url: URL, _ contents: String = "x") throws {
+    try contents.write(to: url, atomically: true, encoding: .utf8)
+}
+
+@Suite("PathSecurity")
+struct PathSecurityTests {
+    @Test func rejectsTraversalAndSeparators() {
+        for bad in ["a/b", "a\\b", "..", "a/../b", "", "..x"] {
+            #expect(!PathSecurity.isValidBasename(bad))
+            #expect(throws: PathSecurity.Error.self) {
+                try PathSecurity.sanitizeBasename(bad)
+            }
+        }
+    }
+
+    @Test func acceptsNormalNames() {
+        for good in ["target", "My Target 01", "écheneau-ümläut", "a.b"] {
+            #expect(PathSecurity.isValidBasename(good))
+        }
+    }
+
+    @Test func resolveSafeCwdPrefersExplicit() throws {
+        let dir = try tempDir()
+        #expect(PathSecurity.resolveSafeCwd(dir) == dir)
+    }
+
+    @Test func resolveSafeCwdNeverReturnsNil() {
+        let missing = URL(fileURLWithPath: "/nonexistent-\(UUID().uuidString)")
+        let resolved = PathSecurity.resolveSafeCwd(missing)
+        #expect(FileManager.default.fileExists(atPath: resolved.path))
+    }
+}
+
+@Suite("AtomicFileWriter")
+struct AtomicFileWriterTests {
+    @Test func writesAndLeavesNoTmp() throws {
+        let dir = try tempDir()
+        let url = dir.appendingPathComponent("state.json")
+        try AtomicFileWriter.write(Data("{\"a\":1}".utf8), to: url)
+        #expect(try String(contentsOf: url, encoding: .utf8) == "{\"a\":1}")
+        #expect(!FileManager.default.fileExists(atPath: url.appendingPathExtension("tmp").path))
+    }
+
+    @Test func overwritesExistingAtomically() throws {
+        let dir = try tempDir()
+        let url = dir.appendingPathComponent("f.txt")
+        try AtomicFileWriter.write("one", to: url)
+        try AtomicFileWriter.write("two-longer", to: url)
+        #expect(try String(contentsOf: url, encoding: .utf8) == "two-longer")
+    }
+
+    @Test func createsParentDirs() throws {
+        let dir = try tempDir()
+        let url = dir.appendingPathComponent("a/b/c/deep.json")
+        try AtomicFileWriter.write("{}", to: url)
+        #expect(FileManager.default.fileExists(atPath: url.path))
+    }
+}
+
+@Suite("ArtefactProbe")
+struct ArtefactProbeTests {
+    @Test func verifyProgression() throws {
+        let dir = try tempDir()
+        var v = ArtefactProbe.verify(basename: "t", cwd: dir)
+        #expect(v == StageArtefacts())
+
+        try touch(dir.appendingPathComponent("t.ti1"))
+        v = ArtefactProbe.verify(basename: "t", cwd: dir)
+        #expect(v.stage1Complete && !v.stage2Complete && !v.stage3Complete)
+
+        try touch(dir.appendingPathComponent("t.ti2"))
+        try touch(dir.appendingPathComponent("t.ti3"))
+        v = ArtefactProbe.verify(basename: "t", cwd: dir)
+        #expect(v.stage2Complete && v.stage3Complete && !v.stage4Complete)
+
+        try touch(dir.appendingPathComponent("t.icc"))
+        v = ArtefactProbe.verify(basename: "t", cwd: dir)
+        #expect(v.stage4Complete && v.profilePath?.pathExtension == "icc")
+    }
+
+    @Test func icmWinsOverIcc() throws {
+        let dir = try tempDir()
+        try touch(dir.appendingPathComponent("p.icc"))
+        try touch(dir.appendingPathComponent("p.icm"))
+        let profile = ArtefactProbe.resolveProfile(basename: "p", cwd: dir)
+        #expect(profile?.pathExtension == "icm")
+    }
+
+    @Test func enumeratesPassesPagesAndCAL() throws {
+        let dir = try tempDir()
+        for name in [
+            "t.ti1", "t.ti2", "t.tif", "t.2.tif", "t_03.tif",
+            "t.ti3", "t_pass1.ti3", "t_pass2.ti3",
+            "t.icc", "t.gam",
+            "CAL_t.ti1", "CAL_t.cal",
+            // must NOT match:
+            "other.ti1", "t.txt", "CAL_other.ti1",
+        ] { try touch(dir.appendingPathComponent(name)) }
+
+        let names = ArtefactProbe.existingArtefacts(basename: "t", cwd: dir)
+            .map(\.lastPathComponent)
+        for expected in [
+            "t.ti1", "t.ti2", "t.tif", "t.2.tif", "t_03.tif",
+            "t.ti3", "t_pass1.ti3", "t_pass2.ti3",
+            "t.icc", "t.gam", "CAL_t.ti1", "CAL_t.cal",
+        ] {
+            #expect(names.contains(expected), "missing \(expected)")
+        }
+        #expect(!names.contains("other.ti1"))
+        #expect(!names.contains("t.txt"))
+        #expect(!names.contains("CAL_other.ti1"))
+    }
+
+    @Test func emptyDirReturnsEmpty() throws {
+        let dir = try tempDir()
+        #expect(ArtefactProbe.existingArtefacts(basename: "x", cwd: dir).isEmpty)
+    }
+}

scripts/fetch-argyll.sh

@@ -110,6 +110,28 @@ find "$DEST" -type f -exec chmod 0755 {} +
 # Downloads carry com.apple.quarantine; the app cannot spawn quarantined tools.
 xattr -dr com.apple.quarantine "$DEST" 2>/dev/null || true
 
+# Ad-hoc sign every Mach-O (#165: unsigned arm64 → "Killed: 9"), then
+# verify — an unsigned sidecar fails the script.
+for f in "$DEST"/*; do
+    [ -f "$f" ] || continue
+    if file -b "$f" | grep -q 'Mach-O'; then
+        codesign -f -s - "$f" 2>/dev/null || true
+    fi
+done
+UNSIGNED=""
+for f in "$DEST"/*; do
+    [ -f "$f" ] || continue
+    if file -b "$f" | grep -q 'Mach-O'; then
+        if ! codesign -dvv "$f" >/dev/null 2>&1; then
+            UNSIGNED="$UNSIGNED $f"
+        fi
+    fi
+done
+if [ -n "$UNSIGNED" ]; then
+    echo "error: unsigned binaries remain:$UNSIGNED" >&2
+    exit 1
+fi
+
 if [ ! -x "$DEST/$MARKER" ]; then
     echo "error: marker binary $MARKER missing after extraction" >&2
     exit 1