feature: sent-PDF history (10) + image retention (30) with pruning per Ben's 2026-09-02 ruling

# Conflicts:
#	Sources/Shotdeck/PickerSelfTest.swift

Info.plist

@@ -2,26 +2,24 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-	<!-- Identity invariants: CFBundleIdentifier stays ai.flowmaster.shotdeck and
-	     CFBundleExecutable stays Shotdeck. Changing either one invalidates the
-	     user's existing Screen Recording grant. CFBundleName is the user-facing
-	     product name only. -->
+	<key>CFBundleExecutable</key>
+	<string>Shotdeck</string>
+	<key>CFBundleIconFile</key>
+	<string>AppIcon</string>
 	<key>CFBundleIdentifier</key>
 	<string>ai.flowmaster.shotdeck</string>
 	<key>CFBundleName</key>
 	<string>Redline</string>
-	<key>CFBundleExecutable</key>
-	<string>Shotdeck</string>
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>0.1.0</string>
+	<string>0.2.0</string>
 	<key>CFBundleVersion</key>
-	<string>1</string>
-	<key>LSUIElement</key>
-	<true/>
+	<string>2</string>
 	<key>LSMinimumSystemVersion</key>
 	<string>14.0</string>
+	<key>LSUIElement</key>
+	<true/>
 	<key>NSHumanReadableCopyright</key>
 	<string>Copyright © 2026 Flowmaster FZC LLC. All rights reserved.</string>
 </dict>

Sources/Shotdeck/AppModel.swift

@@ -36,9 +36,13 @@ public final class AppModel {
     public private(set) var outboxURL: URL
     /// Live watch folder; WP-4c updates this alongside `ReturnWatcher.updateWatchFolder`.
     public private(set) var watchFolderURL: URL
+    /// Absolute URL of the PDF composed this run, if any. Used by "Reveal last PDF".
+    public private(set) var lastComposedPDFURL: URL?
     /// Currently bound capture combo (the last one Carbon accepted, or the preferred load).
     private(set) var captureHotkey: HotkeyPreference
     var hotkeyDisplayString: String { captureHotkey.displayString }
+    /// Staged update offered in the menu. Set only after checksum + payload validation.
+    public private(set) var updateAvailable: (version: String, notes: String)?
 
     let paths: AppSupportPaths
     let spool: SpoolStore
@@ -48,6 +52,8 @@ public final class AppModel {
     let picker: RegionPickerController
     let ledger: ReturnLedger
     let watcher: ReturnWatcher
+    let historyStore: HistoryStore
+    let updateChecker: UpdateChecker
 
     public init(
         paths: AppSupportPaths,
@@ -58,7 +64,7 @@ public final class AppModel {
         picker: RegionPickerController,
         ledger: ReturnLedger,
         watcher: ReturnWatcher
-    ) {
+    ) throws {
         self.paths = paths
         self.spool = spool
         self.composer = composer
@@ -67,6 +73,7 @@ public final class AppModel {
         self.picker = picker
         self.ledger = ledger
         self.watcher = watcher
+        self.historyStore = try HistoryStore(paths: paths)
         self.session = CaptureSession(
             id: UUID(),
             createdAt: Date(),
@@ -83,6 +90,14 @@ public final class AppModel {
         self.outboxDisplayName = folders.outbox.lastPathComponent
         self.watchFolderDisplayName = folders.watch.lastPathComponent
         self.captureHotkey = HotkeyPreference.load()
+        self.updateChecker = UpdateChecker()
+        self.updateChecker.onChecked = { [weak self] in
+            guard let self else { return }
+            self.updateAvailable = self.updateChecker.availableUpdate
+            if let message = self.updateChecker.statusMessage {
+                self.setStatus(message)
+            }
+        }
     }
 
     // MARK: Seam mutators — the only way a WP-4b/4c extension changes state.
@@ -105,6 +120,42 @@ public final class AppModel {
         watchFolderURL = watch
         setFolderDisplayNames(outbox: outbox.lastPathComponent, watch: watch.lastPathComponent)
     }
+    func rememberLastComposedPDF(_ url: URL) { lastComposedPDFURL = url }
+
+    /// True when a last-composed PDF path is known this run, or the newest
+    /// `Redline-*.pdf` in the outbox exists on disk.
+    var canRevealLastPDF: Bool { revealablePDFURL() != nil }
+
+    public func revealLastPDF() {
+        guard let url = revealablePDFURL() else { return }
+        NSWorkspace.shared.activateFileViewerSelecting([url])
+    }
+
+    func revealablePDFURL() -> URL? {
+        if let last = lastComposedPDFURL, FileManager.default.fileExists(atPath: last.path) {
+            return last
+        }
+        return newestOutboxRedlinePDF()
+    }
+
+    func newestOutboxRedlinePDF() -> URL? {
+        let fm = FileManager.default
+        let items = (try? fm.contentsOfDirectory(
+            at: outboxURL,
+            includingPropertiesForKeys: [.contentModificationDateKey],
+            options: [.skipsHiddenFiles]
+        )) ?? []
+        let matches = items.filter {
+            $0.lastPathComponent.hasPrefix("Redline-") && $0.pathExtension.lowercased() == "pdf"
+        }
+        return matches.max { a, b in
+            let da = (try? a.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate) ?? .distantPast
+            let db = (try? b.resourceValues(forKeys: [.contentModificationDateKey])
+                .contentModificationDate) ?? .distantPast
+            return da < db
+        }
+    }
 
     public var iconState: MenuIconState {
         if !screenRecordingGranted { return .recordingMissing }
@@ -154,6 +205,21 @@ public final class AppModel {
         if !bindCaptureHotkey(pref) {
             setStatus("\(pref.displayString) is already used by another app — capture only works from the menu.")
         }
+
+        let skipSchedule =
+            ProcessInfo.processInfo.environment["SHOTDECK_PICKER_SELFTEST"] != nil
+            || ProcessInfo.processInfo.environment["SHOTDECK_SNAPSHOT_DIR"] != nil
+            || ProcessInfo.processInfo.environment["SHOTDECK_UPDATE_SELFTEST"] != nil
+            || ProcessInfo.processInfo.environment["SHOTDECK_HISTORY_SELFTEST"] != nil
+        if !skipSchedule {
+            updateChecker.startSchedule()
+        }
+    }
+
+    /// Installs the staged update over `/Applications/Redline.app` and relaunches.
+    /// Does nothing unless the user clicked the menu row.
+    public func installUpdate() {
+        updateChecker.installStaged()
     }
 
     /// Unregisters `capture` and binds `HotkeyPreference.load()`. If Carbon rejects the new

Sources/Shotdeck/MenuBarView.swift

@@ -74,6 +74,15 @@ struct MenuBarView: View {
 
     private var actionsList: some View {
         VStack(alignment: .leading, spacing: 2) {
+            if let update = model.updateAvailable {
+                Button {
+                    model.installUpdate()
+                } label: {
+                    actionLabel("Update to \(update.version)")
+                        .foregroundStyle(Color.accentColor)
+                }
+            }
+
             Button {
                 let anchor = NSApp.keyWindow?.contentView
                 if let sender = model as? SendCapable {
@@ -86,6 +95,13 @@ struct MenuBarView: View {
             }
             .disabled(model.session.isEmpty || model.isSending)
 
+            Button {
+                model.revealLastPDF()
+            } label: {
+                actionLabel("Reveal last PDF")
+            }
+            .disabled(!model.canRevealLastPDF)
+
             Button {
                 Task { await model.captureNow() }
             } label: {

Sources/Shotdeck/PanelSnapshot.swift

@@ -163,7 +163,7 @@ enum PanelSnapshot {
             watchFolder: root.appendingPathComponent("watch", isDirectory: true)
         )
         let ledger = try ReturnLedger(paths: paths)
-        let model = AppModel(
+        let model = try AppModel(
             paths: paths,
             spool: try SpoolStore(paths: paths),
             composer: PDFComposer(),

Sources/Shotdeck/PickerSelfTest.swift

@@ -1,6 +1,8 @@
 import AppKit
+import CoreGraphics
 import Darwin
 import Foundation
+import ImageIO
 import ShotdeckCore
 
 /// In-process self-test for the region picker, driven by `SHOTDECK_PICKER_SELFTEST`.
@@ -28,6 +30,20 @@ enum PickerSelfTest {
         }
     }
 
+    /// Standalone HISTORY phase when `SHOTDECK_HISTORY_SELFTEST` is set without
+    /// the picker chain. Waits for NSApp like the other phases, then exits.
+    static func runHistoryIfRequested() {
+        guard let raw = ProcessInfo.processInfo.environment["SHOTDECK_HISTORY_SELFTEST"],
+              !raw.isEmpty
+        else { return }
+        _ = raw
+        DispatchQueue.main.async {
+            MainActor.assumeIsolated {
+                runHistoryPhase()
+            }
+        }
+    }
+
     private static func execute(outputDirectory: URL) {
         do {
             try FileManager.default.createDirectory(
@@ -113,7 +129,11 @@ enum PickerSelfTest {
         fflush(stdout)
 
         runRegionPersistPhase()
-        exit(0)
+        // Hop off this MainActor job so the SEND-TRUTH Task can run; do not
+        // exit(0) here — runSendTruthPhase prints its own PASS/FAIL, then
+        // chains to HISTORY, then UPDATE-SELFTEST (or exits if that phase is
+        // not requested).
+        runSendTruthPhase()
     }
 
     /// Phase 2: writes a known region under `CaptureRegion.defaultsKey`, reloads it through
@@ -157,6 +177,462 @@ enum PickerSelfTest {
         fflush(stdout)
     }
 
+    /// Phase 3: drive SendController's share-outcome seams with no AirDrop sheet.
+    /// Fail path must leave the session open in the temp spool; success path archives
+    /// and mints a fresh empty session. Scheduled as a new MainActor job because this
+    /// function is called from inside `execute()` — a nested run-loop wait would never
+    /// let the Task start. On success, chains to HISTORY instead of exiting.
+    private static func runSendTruthPhase() {
+        Task { @MainActor in
+            do {
+                try await executeSendTruth()
+                print("SEND-TRUTH PASS")
+                fflush(stdout)
+            } catch {
+                print("SEND-TRUTH FAIL \(error)")
+                fflush(stdout)
+                exit(1)
+            }
+            runHistoryPhase()
+        }
+    }
+
+    /// Phase 4: drive HistoryStore record/prune in a temp root. Env-gated by
+    /// `SHOTDECK_HISTORY_SELFTEST` the same way UPDATE is gated, and also runs
+    /// whenever the picker self-test chain is already in flight so a full
+    /// self-test prints HISTORY PASS|FAIL. Chains to UPDATE-SELFTEST (or exits).
+    private static func runHistoryPhase() {
+        let historyRequested = ProcessInfo.processInfo.environment["SHOTDECK_HISTORY_SELFTEST"]
+        let pickerRequested = ProcessInfo.processInfo.environment["SHOTDECK_PICKER_SELFTEST"]
+        let shouldRun = (historyRequested.map { !$0.isEmpty } ?? false)
+            || (pickerRequested.map { !$0.isEmpty } ?? false)
+        guard shouldRun else {
+            if !startUpdateSelfTestIfRequested() {
+                exit(0)
+            }
+            return
+        }
+
+        Task { @MainActor in
+            do {
+                try await executeHistorySelfTest()
+                print("HISTORY PASS")
+                fflush(stdout)
+                if !startUpdateSelfTestIfRequested() {
+                    exit(0)
+                }
+            } catch {
+                print("HISTORY FAIL \(error)")
+                fflush(stdout)
+                exit(1)
+            }
+        }
+    }
+
+    private static func executeHistorySelfTest() async throws {
+        let fm = FileManager.default
+        let root = fm.temporaryDirectory
+            .appendingPathComponent("shotdeck-history-selftest-\(UUID().uuidString)", isDirectory: true)
+        defer { try? fm.removeItem(at: root) }
+
+        let paths = try AppSupportPaths(
+            root: root.appendingPathComponent("root", isDirectory: true),
+            outbox: root.appendingPathComponent("outbox", isDirectory: true),
+            watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+        )
+        let store = try HistoryStore(paths: paths)
+        let sources = root.appendingPathComponent("user-sources", isDirectory: true)
+        try fm.createDirectory(at: sources, withIntermediateDirectories: true)
+
+        var recorded: [HistoryEntry] = []
+        for i in 0..<12 {
+            let source = sources.appendingPathComponent("source-\(i).pdf")
+            try Data("%PDF-1.4\n%hist-\(i)\n%%EOF\n".utf8).write(to: source)
+            let entry = try await store.recordSentPDF(
+                sourceURL: source,
+                sessionID: UUID(),
+                pageCount: 1,
+                sentAt: Date(timeIntervalSince1970: 1_800_000_000 + TimeInterval(i))
+            )
+            recorded.append(entry)
+            let onDisk = try Data(contentsOf: source)
+            guard onDisk == Data("%PDF-1.4\n%hist-\(i)\n%%EOF\n".utf8) else {
+                throw HistorySelfTestError.detail("user source PDF was modified: \(source.path)")
+            }
+        }
+
+        let listed = await store.listPDFs()
+        guard listed.count == 10 else {
+            throw HistorySelfTestError.detail("listPDFs count \(listed.count) want 10")
+        }
+        let wantNewest = Array(recorded.suffix(10).reversed())
+        guard listed.map(\.id) == wantNewest.map(\.id) else {
+            throw HistorySelfTestError.detail("listPDFs did not return the 10 newest")
+        }
+        let pdfsDir = paths.root.appendingPathComponent("history/pdfs", isDirectory: true)
+        for entry in recorded.prefix(2) {
+            let gone = pdfsDir.appendingPathComponent(entry.fileName)
+            guard !fm.fileExists(atPath: gone.path) else {
+                throw HistorySelfTestError.detail("oldest PDF still on disk: \(gone.path)")
+            }
+        }
+
+        let same = sources.appendingPathComponent("same.pdf")
+        try Data("%PDF-1.4\n%same\n%%EOF\n".utf8).write(to: same)
+        let first = try await store.recordSentPDF(
+            sourceURL: same, sessionID: nil, pageCount: 1,
+            sentAt: Date(timeIntervalSince1970: 1_800_000_100)
+        )
+        let second = try await store.recordSentPDF(
+            sourceURL: same, sessionID: nil, pageCount: 1,
+            sentAt: Date(timeIntervalSince1970: 1_800_000_101)
+        )
+        guard first.id != second.id, first.fileURL.path != second.fileURL.path,
+              fm.fileExists(atPath: first.fileURL.path),
+              fm.fileExists(atPath: second.fileURL.path),
+              fm.fileExists(atPath: same.path)
+        else {
+            throw HistorySelfTestError.detail("re-record same source did not produce two distinct copies")
+        }
+
+        let spool = try SpoolStore(paths: paths)
+        let png = try makeTinyPNGData()
+        let base = Date(timeIntervalSince1970: 1_800_100_000)
+        var n = 0
+        var oldestSessionID: UUID?
+        for count in [5, 15, 15] {
+            if n == 0 {
+                oldestSessionID = try await spool.currentSession().id
+            }
+            for _ in 0..<count {
+                _ = try await spool.append(
+                    pngData: png, pixelWidth: 64, pixelHeight: 48, scale: 1,
+                    capturedAt: base.addingTimeInterval(TimeInterval(n))
+                )
+                n += 1
+            }
+            _ = try await spool.archiveCurrent(pdfFileName: "Redline-hist-\(n).pdf")
+        }
+        let openCapture = try await spool.append(
+            pngData: png, pixelWidth: 64, pixelHeight: 48, scale: 1,
+            capturedAt: Date(timeIntervalSince1970: 1_900_000_000)
+        )
+        let openSession = try await spool.currentSession()
+        let openPNG = paths.sessionDirectory(openSession.id).appendingPathComponent(openCapture.fileName)
+        let openBytes = try Data(contentsOf: openPNG)
+
+        try await store.pruneImages()
+
+        let images = try await store.listImages(limit: 50)
+        guard images.count == 30 else {
+            throw HistorySelfTestError.detail("listImages count \(images.count) want 30")
+        }
+        if let oldestSessionID {
+            let oldDir = paths.archiveDirectory(oldestSessionID)
+            guard !fm.fileExists(atPath: oldDir.path) else {
+                throw HistorySelfTestError.detail("emptied archive session still on disk")
+            }
+        }
+        guard fm.fileExists(atPath: openPNG.path), try Data(contentsOf: openPNG) == openBytes else {
+            throw HistorySelfTestError.detail("open session PNG was touched")
+        }
+        let remainingOpen = try await spool.currentSession()
+        guard remainingOpen.id == openSession.id,
+              remainingOpen.captures.map(\.id) == [openCapture.id]
+        else {
+            throw HistorySelfTestError.detail("open session manifest was touched")
+        }
+    }
+
+    private static func executeSendTruth() async throws {
+        let fm = FileManager.default
+        let root = fm.temporaryDirectory
+            .appendingPathComponent("shotdeck-send-truth-\(UUID().uuidString)", isDirectory: true)
+        defer { try? fm.removeItem(at: root) }
+
+        let paths = try AppSupportPaths(
+            root: root,
+            outbox: root.appendingPathComponent("outbox", isDirectory: true),
+            watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+        )
+        let ledger = try ReturnLedger(paths: paths)
+        let model = try AppModel(
+            paths: paths,
+            spool: try SpoolStore(paths: paths),
+            composer: PDFComposer(),
+            capturer: ScreenCapturer(),
+            hotkeys: HotkeyCenter(),
+            picker: RegionPickerController(),
+            ledger: ledger,
+            watcher: ReturnWatcher(paths: paths, ledger: ledger)
+        )
+        model.setFolderURLs(outbox: paths.outbox, watch: paths.watchFolder)
+
+        let png = try makeTinyPNGData()
+        _ = try await model.spool.append(
+            pngData: png,
+            pixelWidth: 64,
+            pixelHeight: 48,
+            scale: 1,
+            capturedAt: Date()
+        )
+        model.replaceSession(try await model.spool.currentSession())
+        let openID = model.session.id
+        guard !model.session.isEmpty else {
+            sendTruthFail("seeded session was empty")
+        }
+
+        let pending = try await model.composePDFForSend()
+        guard fm.fileExists(atPath: pending.fileURL.path) else {
+            sendTruthFail("PDF was not written")
+        }
+
+        model.handleDidFailToShareItems(fileName: pending.fileName)
+        let still = try await model.spool.currentSession()
+        guard still.id == openID, !still.isEmpty, still.state == .open else {
+            sendTruthFail("fail path archived or replaced the session")
+        }
+        let spoolDir = paths.sessionDirectory(openID)
+        guard fm.fileExists(atPath: spoolDir.path) else {
+            sendTruthFail("fail path: session missing from temp spool")
+        }
+        guard let status = model.statusLine, status.contains("nothing was sent") else {
+            sendTruthFail("fail path status missing 'nothing was sent': \(model.statusLine ?? "nil")")
+        }
+
+        await model.handleDidShareItems(fileName: pending.fileName, pageCount: pending.pageCount)
+        let fresh = try await model.spool.currentSession()
+        guard fresh.isEmpty, fresh.id != openID, fresh.state == .open else {
+            sendTruthFail("success path did not mint a fresh empty session")
+        }
+        let archived = try await model.spool.archivedSessions()
+        guard archived.contains(where: { $0.id == openID && $0.state == .archived }) else {
+            sendTruthFail("success path did not archive the session")
+        }
+        let archiveDir = paths.archiveDirectory(openID)
+        guard fm.fileExists(atPath: archiveDir.path) else {
+            sendTruthFail("success path: archive dir missing")
+        }
+        guard !fm.fileExists(atPath: spoolDir.path) else {
+            sendTruthFail("success path: session still in spool")
+        }
+    }
+
+    private static func makeTinyPNGData() throws -> Data {
+        let width = 64
+        let height = 48
+        let colorSpace = CGColorSpaceCreateDeviceRGB()
+        guard let context = CGContext(
+            data: nil,
+            width: width,
+            height: height,
+            bitsPerComponent: 8,
+            bytesPerRow: width * 4,
+            space: colorSpace,
+            bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+        ) else {
+            sendTruthFail("could not create PNG context")
+        }
+        context.setFillColor(red: 0.2, green: 0.4, blue: 0.8, alpha: 1)
+        context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        guard let image = context.makeImage() else {
+            sendTruthFail("could not make CGImage")
+        }
+        let buffer = NSMutableData()
+        guard let destination = CGImageDestinationCreateWithData(
+            buffer,
+            "public.png" as CFString,
+            1,
+            nil
+        ) else {
+            sendTruthFail("could not create PNG destination")
+        }
+        CGImageDestinationAddImage(destination, image, nil)
+        guard CGImageDestinationFinalize(destination) else {
+            sendTruthFail("could not finalize PNG")
+        }
+        return buffer as Data
+    }
+
+    private static func sendTruthFail(_ reason: String) -> Never {
+        print("SEND-TRUTH FAIL \(reason)")
+        fflush(stdout)
+        exit(1)
+    }
+
+    /// Phase 5: builds a fake 99.0.0 bundle, serves a local appcast, stages via
+    /// `checkNow`, then `installStaged` into the env dir — never `/Applications`.
+    /// Returns true when the async phase was scheduled (it calls `exit` itself).
+    @discardableResult
+    private static func startUpdateSelfTestIfRequested() -> Bool {
+        guard let raw = ProcessInfo.processInfo.environment["SHOTDECK_UPDATE_SELFTEST"],
+              !raw.isEmpty
+        else { return false }
+
+        let output = URL(fileURLWithPath: raw, isDirectory: true)
+        Task { @MainActor in
+            do {
+                try await runUpdateSelfTest(outputDirectory: output)
+                print("UPDATE-SELFTEST PASS version=99.0.0")
+                fflush(stdout)
+                exit(0)
+            } catch let error as UpdateSelfTestError {
+                updateFail(error.description)
+            } catch {
+                updateFail(String(describing: error))
+            }
+        }
+        return true
+    }
+
+    private static func runUpdateSelfTest(outputDirectory: URL) async throws {
+        let fm = FileManager.default
+        try fm.createDirectory(at: outputDirectory, withIntermediateDirectories: true)
+
+        guard let sourceApp = ownAppBundleURL() else {
+            throw UpdateSelfTestError.detail("own bundle is not a .app (\(Bundle.main.bundleURL.path))")
+        }
+
+        let payload = outputDirectory.appendingPathComponent("payload", isDirectory: true)
+        if fm.fileExists(atPath: payload.path) {
+            try fm.removeItem(at: payload)
+        }
+        try fm.createDirectory(at: payload, withIntermediateDirectories: true)
+        let fakeApp = payload.appendingPathComponent("Redline.app")
+        try fm.copyItem(at: sourceApp, to: fakeApp)
+
+        let plistURL = fakeApp.appendingPathComponent("Contents/Info.plist")
+        let plistData = try Data(contentsOf: plistURL)
+        guard var plist = try PropertyListSerialization.propertyList(from: plistData, format: nil) as? [String: Any] else {
+            throw UpdateSelfTestError.detail("could not parse copied Info.plist")
+        }
+        plist["CFBundleShortVersionString"] = "99.0.0"
+        let rewritten = try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
+        try rewritten.write(to: plistURL)
+
+        let zipURL = outputDirectory.appendingPathComponent("Redline-99.0.0.zip")
+        if fm.fileExists(atPath: zipURL.path) {
+            try fm.removeItem(at: zipURL)
+        }
+        try runDitto(arguments: ["-c", "-k", payload.path, zipURL.path])
+
+        let zipData = try Data(contentsOf: zipURL)
+        let hex = UpdateChecker.sha256Hex(zipData)
+
+        let appcastURL = outputDirectory.appendingPathComponent("appcast.json")
+        let appcast: [String: String] = [
+            "version": "99.0.0",
+            "zipURL": zipURL.absoluteString,
+            "sha256": hex,
+            "notes": "UPDATE-SELFTEST",
+        ]
+        let appcastData = try JSONSerialization.data(withJSONObject: appcast, options: [.sortedKeys])
+        try appcastData.write(to: appcastURL)
+
+        let defaults = UserDefaults.standard
+        let previous = defaults.string(forKey: UpdateChecker.appcastURLDefaultsKey)
+        defaults.set(appcastURL.absoluteString, forKey: UpdateChecker.appcastURLDefaultsKey)
+        defer {
+            if let previous {
+                defaults.set(previous, forKey: UpdateChecker.appcastURLDefaultsKey)
+            } else {
+                defaults.removeObject(forKey: UpdateChecker.appcastURLDefaultsKey)
+            }
+        }
+
+        let (model, isolatedRoot) = try makeIsolatedUpdateModel()
+        defer { try? fm.removeItem(at: isolatedRoot) }
+
+        await model.updateChecker.checkNow()
+
+        guard model.updateAvailable?.version == "99.0.0" else {
+            throw UpdateSelfTestError.detail(
+                "updateAvailable=\(model.updateAvailable?.version ?? "nil")"
+            )
+        }
+        guard let staged = model.updateChecker.stagedAppURL else {
+            throw UpdateSelfTestError.detail("staged payload missing")
+        }
+        guard staged.lastPathComponent == "Redline.app" else {
+            throw UpdateSelfTestError.detail("staged name \(staged.lastPathComponent)")
+        }
+        let stagedExe = staged.appendingPathComponent("Contents/MacOS/Shotdeck")
+        guard fm.fileExists(atPath: stagedExe.path) else {
+            throw UpdateSelfTestError.detail("staged Contents/MacOS/Shotdeck missing")
+        }
+
+        let targetRoot = outputDirectory.appendingPathComponent("target", isDirectory: true)
+        if fm.fileExists(atPath: targetRoot.path) {
+            try fm.removeItem(at: targetRoot)
+        }
+        let target = targetRoot.appendingPathComponent("Redline.app")
+        model.updateChecker.installStaged(to: target)
+
+        let installedPlist = target.appendingPathComponent("Contents/Info.plist")
+        guard let installed = NSDictionary(contentsOf: installedPlist) as? [String: Any],
+              let installedVersion = installed["CFBundleShortVersionString"] as? String
+        else {
+            throw UpdateSelfTestError.detail("installed Info.plist unreadable")
+        }
+        guard installedVersion == "99.0.0" else {
+            throw UpdateSelfTestError.detail("installed version \(installedVersion)")
+        }
+    }
+
+    private static func ownAppBundleURL() -> URL? {
+        let bundle = Bundle.main.bundleURL
+        if bundle.pathExtension == "app" { return bundle }
+        let up3 = bundle
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+            .deletingLastPathComponent()
+        if up3.pathExtension == "app" { return up3 }
+        return nil
+    }
+
+    private static func makeIsolatedUpdateModel() throws -> (AppModel, URL) {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("shotdeck-update-selftest-\(UUID().uuidString)", isDirectory: true)
+        let paths = try AppSupportPaths(
+            root: root,
+            outbox: root.appendingPathComponent("outbox", isDirectory: true),
+            watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+        )
+        let ledger = try ReturnLedger(paths: paths)
+        let model = try AppModel(
+            paths: paths,
+            spool: try SpoolStore(paths: paths),
+            composer: PDFComposer(),
+            capturer: ScreenCapturer(),
+            hotkeys: HotkeyCenter(),
+            picker: RegionPickerController(),
+            ledger: ledger,
+            watcher: ReturnWatcher(paths: paths, ledger: ledger)
+        )
+        return (model, root)
+    }
+
+    private static func runDitto(arguments: [String]) throws {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: "/usr/bin/ditto")
+        process.arguments = arguments
+        let err = Pipe()
+        process.standardError = err
+        process.standardOutput = Pipe()
+        try process.run()
+        process.waitUntilExit()
+        guard process.terminationStatus == 0 else {
+            let message = String(data: err.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+            throw UpdateSelfTestError.detail("ditto failed: \(message)")
+        }
+    }
+
+    private static func updateFail(_ detail: String) -> Never {
+        print("UPDATE-SELFTEST FAIL \(detail)")
+        fflush(stdout)
+        exit(1)
+    }
+
     private static func interpolate(_ step: Int) -> NSPoint {
         let t = CGFloat(step) / CGFloat(dragSteps)
         return NSPoint(
@@ -213,3 +689,21 @@ enum PickerSelfTest {
         exit(1)
     }
 }
+
+private enum UpdateSelfTestError: Error, CustomStringConvertible {
+    case detail(String)
+    var description: String {
+        switch self {
+        case .detail(let s): return s
+        }
+    }
+}
+
+private enum HistorySelfTestError: Error, CustomStringConvertible {
+    case detail(String)
+    var description: String {
+        switch self {
+        case .detail(let s): return s
+        }
+    }
+}

Sources/Shotdeck/SendController.swift

@@ -3,12 +3,59 @@ import Darwin
 import Foundation
 import ShotdeckCore
 
+/// Result of composing a send PDF. Kept so the self-test can drive the share
+/// outcome without presenting a real AirDrop sheet.
+struct ComposedSend: Sendable {
+    let fileName: String
+    let fileURL: URL
+    let pageCount: Int
+}
+
 extension AppModel: SendCapable {
     public func send(anchor: NSView?) async {
         guard !session.isEmpty, !isSending else { return }
         setSending(true)
-        defer { setSending(false) }
 
+        let pending: ComposedSend
+        do {
+            pending = try await composePDFForSend()
+        } catch {
+            // Never unlink the published PDF, and never unlink the temp file either:
+            // a rename failure would leave the complete document at the temp name.
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "The PDF could not be built.")
+            setSending(false)
+            return
+        }
+
+        guard let anchor else {
+            handleDidFailToShareItems(fileName: pending.fileName)
+            setSending(false)
+            return
+        }
+
+        do {
+            try Sharing.airDrop(fileURL: pending.fileURL, from: anchor) { [weak self] success in
+                guard let self else { return }
+                if success {
+                    await self.handleDidShareItems(
+                        fileName: pending.fileName,
+                        pageCount: pending.pageCount
+                    )
+                } else {
+                    self.handleDidFailToShareItems(fileName: pending.fileName)
+                }
+                self.setSending(false)
+            }
+        } catch {
+            // canPerform false, no service, or no visible window: same as cancel.
+            handleDidFailToShareItems(fileName: pending.fileName)
+            setSending(false)
+        }
+    }
+
+    /// Writes the PDF to the outbox and records its path. Does not archive the session
+    /// and does not present AirDrop — that happens only after the share completes.
+    func composePDFForSend() async throws -> ComposedSend {
         let workingSession = session
         let composer = self.composer
         // Live outbox (FolderSettings), not `paths.outbox` — Settings changes take effect.
@@ -20,52 +67,70 @@ extension AppModel: SendCapable {
         let tempURL = outboxDir.appendingPathComponent(".shotdeck-\(UUID().uuidString).pdf")
         let title = "Redline – \(DubaiTime.stamp(workingSession.createdAt))"
 
-        do {
-            // D-13: build off the main actor. Only Sendable values cross into the
-            // detached task — never `anchor` (NSView is not Sendable).
-            try await Task.detached(priority: .userInitiated) {
-                _ = try composer.compose(
-                    session: workingSession,
-                    imageURL: { capture in sourceDir.appendingPathComponent(capture.fileName) },
-                    title: title,
-                    to: tempURL
+        // D-13: build off the main actor. Only Sendable values cross into the
+        // detached task — never `anchor` (NSView is not Sendable).
+        try await Task.detached(priority: .userInitiated) {
+            _ = try composer.compose(
+                session: workingSession,
+                imageURL: { capture in sourceDir.appendingPathComponent(capture.fileName) },
+                title: title,
+                to: tempURL
+            )
+            // POSIX rename onto `finalURL` replaces any same-name file in one
+            // directory operation; there is never a window where the PDF is gone.
+            if Darwin.rename(tempURL.path, finalURL.path) != 0 {
+                throw ShotdeckError.pdfCompositionFailed(
+                    reason: "could not publish the PDF: \(String(cString: strerror(errno)))"
                 )
-                // POSIX rename onto `finalURL` replaces any same-name file in one
-                // directory operation; there is never a window where the PDF is gone.
-                if Darwin.rename(tempURL.path, finalURL.path) != 0 {
-                    throw ShotdeckError.pdfCompositionFailed(
-                        reason: "could not publish the PDF: \(String(cString: strerror(errno)))"
-                    )
-                }
-                try AtomicFile.fsyncDirectory(at: outboxDir)
-            }.value
-
-            // File exists on disk now — archive only after that (D-13). A later AirDrop
-            // failure never deletes this file.
-            guard FileManager.default.fileExists(atPath: finalURL.path) else {
-                throw ShotdeckError.pdfCompositionFailed(reason: "the PDF was not written to disk")
             }
+            try AtomicFile.fsyncDirectory(at: outboxDir)
+        }.value
+
+        guard FileManager.default.fileExists(atPath: finalURL.path) else {
+            throw ShotdeckError.pdfCompositionFailed(reason: "the PDF was not written to disk")
+        }
+        rememberLastComposedPDF(finalURL)
+        return ComposedSend(
+            fileName: fileName,
+            fileURL: finalURL,
+            pageCount: workingSession.captures.count
+        )
+    }
+
+    /// `NSSharingServiceDelegate.sharingService(_:didShareItems:)` seam.
+    func handleDidShareItems(fileName: String, pageCount: Int) async {
+        guard !session.isEmpty else { return }
+        let sentSessionID = session.id
+        let sourceURL = lastComposedPDFURL ?? outboxURL.appendingPathComponent(fileName)
+        do {
             _ = try await spool.archiveCurrent(pdfFileName: fileName)
             replaceSession(try await spool.currentSession())
-
-            let pageWord = workingSession.captures.count == 1 ? "page" : "pages"
-            setStatus("Sent — \(workingSession.captures.count) \(pageWord).")
-
-            guard let anchor else {
-                setStatus("PDF saved to \(outboxDisplayName). Open the panel to AirDrop it.")
-                return
-            }
-            do {
-                try Sharing.airDrop(fileURL: finalURL, from: anchor)
-            } catch {
-                setStatus(
-                    "AirDrop is not available right now — the PDF is on your \(outboxDisplayName)."
-                )
-            }
+            let pageWord = pageCount == 1 ? "page" : "pages"
+            setStatus("Sent — \(pageCount) \(pageWord).")
         } catch {
-            // Never unlink the published PDF, and never unlink `tempURL` either:
-            // a rename failure would leave the complete document at the temp name.
-            setStatus((error as? ShotdeckError)?.errorDescription ?? "The PDF could not be built.")
+            setStatus((error as? ShotdeckError)?.errorDescription ?? "Could not archive the session.")
+            return
+        }
+        do {
+            _ = try await historyStore.recordSentPDF(
+                sourceURL: sourceURL,
+                sessionID: sentSessionID,
+                pageCount: pageCount,
+                sentAt: Date()
+            )
+            try await historyStore.pruneImages()
+        } catch {
+            Log.spool.error(
+                "Could not record sent PDF into history at \(sourceURL.path, privacy: .public): \(error.localizedDescription, privacy: .public)"
+            )
         }
     }
+
+    /// `NSSharingServiceDelegate.sharingService(_:didFailToShareItems:error:)` seam,
+    /// also used when `canPerform` is false or the user cancels. Does not archive.
+    func handleDidFailToShareItems(fileName: String) {
+        setStatus(
+            "AirDrop didn't complete — nothing was sent. Your captures are still here; the PDF is on your \(outboxDisplayName) as \(fileName)."
+        )
+    }
 }

Sources/Shotdeck/Sharing.swift

@@ -7,7 +7,14 @@ enum Sharing {
     /// Throws `ShotdeckError.airDropUnavailable` when the service cannot be created,
     /// `canPerform` is false, or `view` is not in a visible window (a detached view
     /// never produces an on-screen sheet).
-    static func airDrop(fileURL: URL, from view: NSView) throws {
+    ///
+    /// `onFinished` is invoked on the main actor when the sheet completes: `true` for
+    /// `didShareItems`, `false` for `didFailToShareItems` (including user cancel).
+    static func airDrop(
+        fileURL: URL,
+        from view: NSView,
+        onFinished: @escaping @MainActor @Sendable (Bool) async -> Void
+    ) throws {
         guard let service = NSSharingService(named: .sendViaAirDrop),
               service.canPerform(withItems: [fileURL]) else {
             throw ShotdeckError.airDropUnavailable
@@ -21,7 +28,12 @@ enum Sharing {
         window.makeKeyAndOrderFront(nil)
 
         service.subject = fileURL.lastPathComponent
-        let session = AirDropSession(service: service, window: window, view: view)
+        let session = AirDropSession(
+            service: service,
+            window: window,
+            view: view,
+            onFinished: onFinished
+        )
         AirDropSession.keepAlive(session)
         service.delegate = session
         service.perform(withItems: [fileURL])
@@ -29,7 +41,9 @@ enum Sharing {
 }
 
 /// Retains the sharing service for the life of the picker and supplies the real
-/// on-screen window as the sheet parent. `NSSharingService.delegate` is weak.
+/// on-screen window as the sheet parent. `NSSharingService.delegate` is weak, so
+/// `live` is the strong reference that keeps this object alive until the sheet
+/// reports success or failure (including cancel).
 @MainActor
 private final class AirDropSession: NSObject, NSSharingServiceDelegate {
     static var live: [AirDropSession] = []
@@ -37,11 +51,19 @@ private final class AirDropSession: NSObject, NSSharingServiceDelegate {
     let service: NSSharingService
     let window: NSWindow
     let view: NSView
+    let onFinished: @MainActor @Sendable (Bool) async -> Void
+    private var reported = false
 
-    init(service: NSSharingService, window: NSWindow, view: NSView) {
+    init(
+        service: NSSharingService,
+        window: NSWindow,
+        view: NSView,
+        onFinished: @escaping @MainActor @Sendable (Bool) async -> Void
+    ) {
         self.service = service
         self.window = window
         self.view = view
+        self.onFinished = onFinished
     }
 
     static func keepAlive(_ session: AirDropSession) {
@@ -52,6 +74,15 @@ private final class AirDropSession: NSObject, NSSharingServiceDelegate {
         Self.live.removeAll { $0 === self }
     }
 
+    private func report(_ success: Bool) {
+        guard !reported else { return }
+        reported = true
+        Task { @MainActor in
+            await self.onFinished(success)
+            self.drop()
+        }
+    }
+
     func sharingService(
         _ sharingService: NSSharingService,
         sourceWindowForShareItems items: [Any],
@@ -70,7 +101,7 @@ private final class AirDropSession: NSObject, NSSharingServiceDelegate {
     }
 
     func sharingService(_ sharingService: NSSharingService, didShareItems items: [Any]) {
-        drop()
+        report(true)
     }
 
     func sharingService(
@@ -78,6 +109,6 @@ private final class AirDropSession: NSObject, NSSharingServiceDelegate {
         didFailToShareItems items: [Any],
         error: any Error
     ) {
-        drop()
+        report(false)
     }
 }

Sources/Shotdeck/UpdateChecker.swift

@@ -0,0 +1,281 @@
+import AppKit
+import CryptoKit
+import Foundation
+
+/// Built-in updater. Checks an appcast, stages a verified payload, and installs
+/// only when the user clicks the menu row — never automatically.
+@MainActor
+final class UpdateChecker {
+    static let appcastURLDefaultsKey = "ai.flowmaster.shotdeck.appcastURL"
+    static let defaultAppcastURL = URL(string: "https://get.baobab-ts.com/cowork/redline/appcast.json")!
+    static let defaultInstallTarget = URL(fileURLWithPath: "/Applications/Redline.app")
+
+    private(set) var availableUpdate: (version: String, notes: String)?
+    private(set) var stagedAppURL: URL?
+    private(set) var statusMessage: String?
+
+    var onChecked: (() -> Void)?
+
+    private let urlSession: URLSession
+    private var repeatingTimer: Timer?
+    private var firstCheckTask: Task<Void, Never>?
+    private var isChecking = false
+    private var stagingDirectory: URL?
+
+    init() {
+        let config = URLSessionConfiguration.ephemeral
+        config.timeoutIntervalForRequest = 15
+        config.timeoutIntervalForResource = 15
+        config.httpCookieAcceptPolicy = .never
+        config.httpShouldSetCookies = false
+        config.httpCookieStorage = nil
+        config.urlCache = nil
+        urlSession = URLSession(configuration: config)
+    }
+
+    /// First check 10 seconds after start, then every 6 hours. Stages only — never installs.
+    func startSchedule() {
+        firstCheckTask?.cancel()
+        firstCheckTask = Task { [weak self] in
+            try? await Task.sleep(for: .seconds(10))
+            guard !Task.isCancelled else { return }
+            await self?.checkNow()
+        }
+        repeatingTimer?.invalidate()
+        let timer = Timer(timeInterval: 6 * 60 * 60, repeats: true) { [weak self] _ in
+            Task { @MainActor in
+                await self?.checkNow()
+            }
+        }
+        RunLoop.main.add(timer, forMode: .common)
+        repeatingTimer = timer
+    }
+
+    func checkNow() async {
+        guard !isChecking else { return }
+        isChecking = true
+        defer { isChecking = false }
+
+        let appcast: Appcast
+        do {
+            appcast = try await fetchAppcast()
+        } catch {
+            statusMessage = "Could not check for updates."
+            onChecked?()
+            return
+        }
+
+        guard Self.isNewer(appcast.version, than: Self.currentVersion()) else {
+            clearOffer()
+            statusMessage = nil
+            onChecked?()
+            return
+        }
+
+        do {
+            try await downloadAndStage(appcast)
+            availableUpdate = (version: appcast.version, notes: appcast.notes ?? "")
+            statusMessage = nil
+        } catch UpdateCheckError.checksumMismatch {
+            discardStaging()
+            availableUpdate = nil
+            statusMessage = "Update file failed the checksum — not installed."
+        } catch {
+            discardStaging()
+            availableUpdate = nil
+            statusMessage = "The update could not be prepared."
+        }
+        onChecked?()
+    }
+
+    /// Copies the staged app onto `target` with ditto (in place; never deletes the old app).
+    /// Relaunches unless `SHOTDECK_UPDATE_SELFTEST` is set, so the in-process self-test
+    /// can assert the installed Info.plist without killing the process.
+    func installStaged(to target: URL = UpdateChecker.defaultInstallTarget) {
+        guard let staged = stagedAppURL else {
+            statusMessage = "No update is staged."
+            onChecked?()
+            return
+        }
+
+        do {
+            try FileManager.default.createDirectory(
+                at: target.deletingLastPathComponent(),
+                withIntermediateDirectories: true
+            )
+            try Self.runProcess(executable: "/usr/bin/ditto", arguments: [staged.path, target.path])
+        } catch {
+            statusMessage = "The update could not be installed."
+            onChecked?()
+            return
+        }
+
+        let isSelfTest = ProcessInfo.processInfo.environment["SHOTDECK_UPDATE_SELFTEST"] != nil
+        if isSelfTest { return }
+
+        do {
+            try Self.runProcess(executable: "/usr/bin/open", arguments: ["-n", target.path])
+        } catch {
+            statusMessage = "The update was installed but Redline could not relaunch. Open it from Applications."
+            onChecked?()
+            return
+        }
+        NSApp.terminate(nil)
+    }
+
+    static func resolvedAppcastURL() -> URL {
+        if let env = ProcessInfo.processInfo.environment["REDLINE_APPCAST_URL"],
+           !env.isEmpty,
+           let url = URL(string: env)
+        {
+            return url
+        }
+        if let stored = UserDefaults.standard.string(forKey: appcastURLDefaultsKey),
+           !stored.isEmpty,
+           let url = URL(string: stored)
+        {
+            return url
+        }
+        return defaultAppcastURL
+    }
+
+    static func currentVersion() -> String {
+        Bundle.main.object(forInfoDictionaryKey: "CFBundleShortVersionString") as? String ?? "0.0.0"
+    }
+
+    static func isNewer(_ candidate: String, than current: String) -> Bool {
+        let a = semverParts(candidate)
+        let b = semverParts(current)
+        for i in 0..<3 {
+            if a[i] != b[i] { return a[i] > b[i] }
+        }
+        return false
+    }
+
+    static func sha256Hex(_ data: Data) -> String {
+        SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+    }
+
+    // MARK: - Private
+
+    private struct Appcast: Decodable {
+        var version: String
+        var zipURL: URL
+        var sha256: String
+        var notes: String?
+    }
+
+    private enum UpdateCheckError: Error {
+        case checksumMismatch
+        case invalidPayload
+        case httpStatus(Int)
+        case processFailed(String)
+    }
+
+    private func fetchAppcast() async throws -> Appcast {
+        let data = try await fetchData(from: Self.resolvedAppcastURL())
+        return try JSONDecoder().decode(Appcast.self, from: data)
+    }
+
+    private func fetchData(from url: URL) async throws -> Data {
+        if url.isFileURL {
+            return try Data(contentsOf: url)
+        }
+        let (data, response) = try await urlSession.data(from: url)
+        if let http = response as? HTTPURLResponse, !(200...299).contains(http.statusCode) {
+            throw UpdateCheckError.httpStatus(http.statusCode)
+        }
+        return data
+    }
+
+    private func downloadAndStage(_ appcast: Appcast) async throws {
+        let zipData = try await fetchData(from: appcast.zipURL)
+        let expected = appcast.sha256.trimmingCharacters(in: .whitespacesAndNewlines)
+        let actual = Self.sha256Hex(zipData)
+        guard actual.caseInsensitiveCompare(expected) == .orderedSame else {
+            throw UpdateCheckError.checksumMismatch
+        }
+
+        discardStaging()
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("shotdeck-update-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        stagingDirectory = root
+
+        let zipURL = root.appendingPathComponent("update.zip")
+        try zipData.write(to: zipURL)
+
+        let extracted = root.appendingPathComponent("extracted", isDirectory: true)
+        try FileManager.default.createDirectory(at: extracted, withIntermediateDirectories: true)
+        try Self.runProcess(
+            executable: "/usr/bin/ditto",
+            arguments: ["-x", "-k", zipURL.path, extracted.path]
+        )
+
+        guard let appURL = Self.findRedlineApp(in: extracted) else {
+            throw UpdateCheckError.invalidPayload
+        }
+        let executable = appURL.appendingPathComponent("Contents/MacOS/Shotdeck")
+        guard FileManager.default.fileExists(atPath: executable.path) else {
+            throw UpdateCheckError.invalidPayload
+        }
+        stagedAppURL = appURL
+    }
+
+    private func clearOffer() {
+        availableUpdate = nil
+        discardStaging()
+    }
+
+    private func discardStaging() {
+        if let stagingDirectory {
+            try? FileManager.default.removeItem(at: stagingDirectory)
+        }
+        stagingDirectory = nil
+        stagedAppURL = nil
+    }
+
+    private static func findRedlineApp(in directory: URL) -> URL? {
+        let fm = FileManager.default
+        let direct = directory.appendingPathComponent("Redline.app")
+        if fm.fileExists(atPath: direct.path) { return direct }
+
+        guard let enumerator = fm.enumerator(
+            at: directory,
+            includingPropertiesForKeys: [.isDirectoryKey],
+            options: [.skipsHiddenFiles]
+        ) else { return nil }
+
+        while let item = enumerator.nextObject() as? URL {
+            if item.lastPathComponent == "Redline.app" {
+                return item
+            }
+            if item.pathExtension == "app" {
+                enumerator.skipDescendants()
+            }
+        }
+        return nil
+    }
+
+    private static func semverParts(_ string: String) -> [Int] {
+        let core = string.split(separator: "-").first.map(String.init) ?? string
+        var parts = core.split(separator: ".").prefix(3).map { Int($0) ?? 0 }
+        while parts.count < 3 { parts.append(0) }
+        return parts
+    }
+
+    private static func runProcess(executable: String, arguments: [String]) throws {
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: executable)
+        process.arguments = arguments
+        let err = Pipe()
+        process.standardError = err
+        process.standardOutput = Pipe()
+        try process.run()
+        process.waitUntilExit()
+        guard process.terminationStatus == 0 else {
+            let message = String(data: err.fileHandleForReading.readDataToEndOfFile(), encoding: .utf8) ?? ""
+            throw UpdateCheckError.processFailed("\(executable) failed: \(message)")
+        }
+    }
+}

Sources/Shotdeck/main.swift

@@ -9,6 +9,8 @@ if ProcessInfo.processInfo.environment["SHOTDECK_SNAPSHOT_DIR"] != nil {
 }
 if ProcessInfo.processInfo.environment["SHOTDECK_PICKER_SELFTEST"] != nil {
     MainActor.assumeIsolated { PickerSelfTest.runIfRequested() }
+} else if ProcessInfo.processInfo.environment["SHOTDECK_HISTORY_SELFTEST"] != nil {
+    MainActor.assumeIsolated { PickerSelfTest.runHistoryIfRequested() }
 }
 ShotdeckApp.main()
 
@@ -67,7 +69,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
 
     private static func makeModel(paths: AppSupportPaths) throws -> AppModel {
         let ledger = try ReturnLedger(paths: paths)
-        return AppModel(
+        return try AppModel(
             paths: paths,
             spool: try SpoolStore(paths: paths),
             composer: PDFComposer(),

Sources/ShotdeckCore/History/HistoryStore.swift

@@ -0,0 +1,446 @@
+import Foundation
+
+/// Retention ruling (2026-09-02). Ben's instruction is the authority that
+/// supersedes the earlier D-11 never-delete rule FOR THIS STORE only:
+///
+///     "the last 10 files are saved, and the past 30 images, and cleared up
+///     afterwards. user should be able to select from those and send again."
+///
+/// App-managed copies live under `AppSupportPaths.root/history/`. Pruning
+/// unlinks files under `history/pdfs/` and archived capture PNGs beyond the
+/// newest 30. It never deletes a user file, never touches the outbox PDF, and
+/// never touches the open spool session (D-11 still applies there).
+
+/// One sent-PDF copy retained for re-send. The file at `fileURL` is the
+/// app-managed copy under `history/pdfs/`, not the user's original.
+public struct HistoryEntry: Codable, Sendable, Equatable, Identifiable {
+    public let id: UUID
+    public let fileName: String
+    public let fileURL: URL
+    public let originalFileName: String
+    public let sessionID: UUID?
+    public let pageCount: Int
+    public let sentAt: Date
+
+    public init(
+        id: UUID,
+        fileName: String,
+        fileURL: URL,
+        originalFileName: String,
+        sessionID: UUID?,
+        pageCount: Int,
+        sentAt: Date
+    ) {
+        self.id = id
+        self.fileName = fileName
+        self.fileURL = fileURL
+        self.originalFileName = originalFileName
+        self.sessionID = sessionID
+        self.pageCount = pageCount
+        self.sentAt = sentAt
+    }
+}
+
+/// A capture PNG on disk under an archived session, listed for re-send.
+/// `path` is the real file; HistoryStore never copies images.
+public struct ImageRef: Sendable, Equatable {
+    public let path: URL
+    public let capturedAt: Date
+    public let sessionID: UUID
+
+    public init(path: URL, capturedAt: Date, sessionID: UUID) {
+        self.path = path
+        self.capturedAt = capturedAt
+        self.sessionID = sessionID
+    }
+}
+
+public actor HistoryStore {
+    public static let pdfRetentionCount = 10
+    public static let imageRetentionCount = 30
+
+    private let paths: AppSupportPaths
+    private let historyRoot: URL
+    private let pdfsDirectory: URL
+    private let manifestURL: URL
+    private var entries: [HistoryEntry]
+
+    public init(paths: AppSupportPaths) throws {
+        self.paths = paths
+        self.historyRoot = paths.root.appendingPathComponent("history", isDirectory: true)
+        self.pdfsDirectory = historyRoot.appendingPathComponent("pdfs", isDirectory: true)
+        self.manifestURL = historyRoot.appendingPathComponent("history.json")
+        do {
+            try FileManager.default.createDirectory(at: historyRoot, withIntermediateDirectories: true)
+            try FileManager.default.createDirectory(at: pdfsDirectory, withIntermediateDirectories: true)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: historyRoot.path,
+                underlying: error.localizedDescription
+            )
+        }
+        self.entries = try Self.loadEntries(from: manifestURL, pdfsDirectory: pdfsDirectory)
+    }
+
+    /// Copies `sourceURL` into `history/pdfs/` (never moves or writes the
+    /// user's file), appends an entry, then keeps the 10 newest PDF copies.
+    public func recordSentPDF(
+        sourceURL: URL,
+        sessionID: UUID?,
+        pageCount: Int,
+        sentAt: Date
+    ) throws -> HistoryEntry {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: sourceURL.path) else {
+            throw ShotdeckError.spoolWriteFailed(
+                path: sourceURL.path,
+                underlying: "source PDF does not exist"
+            )
+        }
+        let data: Data
+        do {
+            data = try Data(contentsOf: sourceURL)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: sourceURL.path,
+                underlying: error.localizedDescription
+            )
+        }
+
+        let id = UUID()
+        let fileName = "\(DubaiTime.fileStamp(sentAt))-\(id.uuidString.lowercased()).pdf"
+        let destURL = pdfsDirectory.appendingPathComponent(fileName)
+        try AtomicFile.write(data, to: destURL)
+
+        let entry = HistoryEntry(
+            id: id,
+            fileName: fileName,
+            fileURL: destURL,
+            originalFileName: sourceURL.lastPathComponent,
+            sessionID: sessionID,
+            pageCount: pageCount,
+            sentAt: sentAt
+        )
+        entries.append(entry)
+        try prunePDFEntries()
+        return entry
+    }
+
+    /// Newest first, at most `pdfRetentionCount`.
+    public func listPDFs() -> [HistoryEntry] {
+        Array(sortedPDFs().prefix(Self.pdfRetentionCount))
+    }
+
+    /// The newest capture PNGs across `archive/` sessions (including
+    /// `removed/`). Does not copy files and does not look at the open spool.
+    public func listImages(limit: Int = 30) throws -> [ImageRef] {
+        let images = try collectArchivedImages()
+        return images.prefix(max(limit, 0)).map(\.ref)
+    }
+
+    /// Across archived sessions only: keep the 30 newest PNGs total (including
+    /// `removed/`); delete older PNGs, drop them from `session.json`, and
+    /// remove a session directory left with zero PNGs. Never touches spool/.
+    public func pruneImages() throws {
+        let fm = FileManager.default
+        let images = try collectArchivedImages()
+        let keepCount = Self.imageRetentionCount
+        let doomed = Array(images.dropFirst(keepCount))
+        guard !doomed.isEmpty else { return }
+
+        var remainingBySession: [UUID: CaptureSession] = [:]
+        var dirBySession: [UUID: URL] = [:]
+        for item in images {
+            remainingBySession[item.session.id] = item.session
+            dirBySession[item.session.id] = item.sessionDir
+        }
+
+        var droppedIDs: [UUID: Set<UUID>] = [:]
+        for item in doomed {
+            try deleteIfPrunableImage(item.ref.path)
+            if let captureID = item.captureID {
+                droppedIDs[item.session.id, default: []].insert(captureID)
+            }
+        }
+
+        for (sessionID, ids) in droppedIDs {
+            guard var session = remainingBySession[sessionID] else { continue }
+            for id in ids {
+                session = session.removing(captureID: id)
+            }
+            remainingBySession[sessionID] = session
+        }
+
+        let touchedIDs = Set(doomed.map(\.session.id))
+        for sessionID in touchedIDs {
+            guard let sessionDir = dirBySession[sessionID] else { continue }
+            guard isUnderArchive(sessionDir), !isUnderSpool(sessionDir) else { continue }
+
+            if pngsRemaining(in: sessionDir).isEmpty {
+                if fm.fileExists(atPath: sessionDir.path) {
+                    try fm.removeItem(at: sessionDir)
+                    Log.spool.warning("Pruned \(sessionDir.path, privacy: .public)")
+                }
+                try AtomicFile.fsyncDirectory(at: paths.archive)
+                continue
+            }
+
+            if let session = remainingBySession[sessionID], droppedIDs[sessionID] != nil {
+                try AtomicFile.writeJSON(
+                    session,
+                    to: sessionDir.appendingPathComponent("session.json")
+                )
+            }
+        }
+    }
+
+    // MARK: - PDF retention
+
+    private func prunePDFEntries() throws {
+        let sorted = sortedPDFs()
+        let kept = Array(sorted.prefix(Self.pdfRetentionCount))
+        let discarded = sorted.dropFirst(Self.pdfRetentionCount)
+        for entry in discarded {
+            let url = pdfsDirectory.appendingPathComponent(entry.fileName)
+            try deleteIfAppManagedPDF(url)
+        }
+        entries = kept
+        try persistEntries()
+    }
+
+    private func sortedPDFs() -> [HistoryEntry] {
+        entries.sorted { lhs, rhs in
+            if lhs.sentAt != rhs.sentAt { return lhs.sentAt > rhs.sentAt }
+            return lhs.id.uuidString > rhs.id.uuidString
+        }
+    }
+
+    private func persistEntries() throws {
+        try AtomicFile.writeJSON(entries, to: manifestURL)
+    }
+
+    private func deleteIfAppManagedPDF(_ url: URL) throws {
+        guard isUnderPDFs(url) else { return }
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: url.path) else { return }
+        do {
+            try fm.removeItem(at: url)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path,
+                underlying: error.localizedDescription
+            )
+        }
+        Log.spool.warning("Pruned \(url.path, privacy: .public)")
+        try AtomicFile.fsyncDirectory(at: pdfsDirectory)
+    }
+
+    // MARK: - Archived images
+
+    private struct ArchivedImage {
+        let ref: ImageRef
+        let session: CaptureSession
+        let sessionDir: URL
+        let captureID: UUID?
+    }
+
+    private func collectArchivedImages() throws -> [ArchivedImage] {
+        let dirs = try archivedSessionDirectories()
+        var collected: [ArchivedImage] = []
+        for dir in dirs {
+            let sessionID = UUID(uuidString: dir.lastPathComponent) ?? UUID()
+            let session = (try? loadSession(at: dir, id: sessionID))
+                ?? CaptureSession(
+                    id: sessionID,
+                    createdAt: fileDate(dir) ?? Date(),
+                    state: .archived,
+                    captures: [],
+                    pdfFileName: nil
+                )
+            var referenced = Set<String>()
+            for capture in session.captures {
+                let url = dir.appendingPathComponent(capture.fileName)
+                guard FileManager.default.fileExists(atPath: url.path) else { continue }
+                referenced.insert(capture.fileName)
+                collected.append(
+                    ArchivedImage(
+                        ref: ImageRef(path: url, capturedAt: capture.capturedAt, sessionID: session.id),
+                        session: session,
+                        sessionDir: dir,
+                        captureID: capture.id
+                    )
+                )
+            }
+            let removedDir = dir.appendingPathComponent("removed", isDirectory: true)
+            for url in pngFiles(in: dir) where !referenced.contains(url.lastPathComponent) {
+                collected.append(
+                    ArchivedImage(
+                        ref: ImageRef(
+                            path: url,
+                            capturedAt: fileDate(url) ?? .distantPast,
+                            sessionID: session.id
+                        ),
+                        session: session,
+                        sessionDir: dir,
+                        captureID: nil
+                    )
+                )
+            }
+            for url in pngFiles(in: removedDir) {
+                collected.append(
+                    ArchivedImage(
+                        ref: ImageRef(
+                            path: url,
+                            capturedAt: fileDate(url) ?? .distantPast,
+                            sessionID: session.id
+                        ),
+                        session: session,
+                        sessionDir: dir,
+                        captureID: nil
+                    )
+                )
+            }
+        }
+        return collected.sorted { lhs, rhs in
+            if lhs.ref.capturedAt != rhs.ref.capturedAt {
+                return lhs.ref.capturedAt > rhs.ref.capturedAt
+            }
+            return lhs.ref.path.path > rhs.ref.path.path
+        }
+    }
+
+    private func archivedSessionDirectories() throws -> [URL] {
+        let fm = FileManager.default
+        let entries: [URL]
+        do {
+            entries = try fm.contentsOfDirectory(
+                at: paths.archive,
+                includingPropertiesForKeys: [.isDirectoryKey],
+                options: []
+            )
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: paths.archive.path,
+                underlying: error.localizedDescription
+            )
+        }
+        return entries.filter { url in
+            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
+            return isDirectory && UUID(uuidString: url.lastPathComponent) != nil
+        }
+    }
+
+    private func loadSession(at dir: URL, id: UUID) throws -> CaptureSession {
+        let url = dir.appendingPathComponent("session.json")
+        let data = try Data(contentsOf: url)
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        let session = try decoder.decode(CaptureSession.self, from: data)
+        guard session.id == id else {
+            throw ShotdeckError.manifestCorrupt(path: url.path)
+        }
+        return session
+    }
+
+    private func pngFiles(in dir: URL) -> [URL] {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: dir.path) else { return [] }
+        let entries = (try? fm.contentsOfDirectory(
+            at: dir,
+            includingPropertiesForKeys: [.isDirectoryKey],
+            options: []
+        )) ?? []
+        return entries.filter { url in
+            let isDirectory = (try? url.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false
+            return !isDirectory && url.pathExtension.lowercased() == "png"
+        }
+    }
+
+    private func pngsRemaining(in sessionDir: URL) -> [URL] {
+        pngFiles(in: sessionDir)
+            + pngFiles(in: sessionDir.appendingPathComponent("removed", isDirectory: true))
+    }
+
+    private func deleteIfPrunableImage(_ url: URL) throws {
+        guard isUnderArchive(url), !isUnderSpool(url) else { return }
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: url.path) else { return }
+        do {
+            try fm.removeItem(at: url)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path,
+                underlying: error.localizedDescription
+            )
+        }
+        Log.spool.warning("Pruned \(url.path, privacy: .public)")
+        try AtomicFile.fsyncDirectory(at: url.deletingLastPathComponent())
+    }
+
+    private func fileDate(_ url: URL) -> Date? {
+        let values = try? url.resourceValues(forKeys: [.creationDateKey, .contentModificationDateKey])
+        return values?.creationDate ?? values?.contentModificationDate
+    }
+
+    // MARK: - Path guards
+
+    private func isUnderPDFs(_ url: URL) -> Bool {
+        isUnderDirectory(url, parent: pdfsDirectory)
+    }
+
+    private func isUnderArchive(_ url: URL) -> Bool {
+        isUnderDirectory(url, parent: paths.archive)
+    }
+
+    private func isUnderSpool(_ url: URL) -> Bool {
+        isUnderDirectory(url, parent: paths.spool)
+    }
+
+    private func isUnderDirectory(_ url: URL, parent: URL) -> Bool {
+        let parentPath = parent.standardizedFileURL.path
+        let path = url.standardizedFileURL.path
+        if path == parentPath { return true }
+        let prefix = parentPath.hasSuffix("/") ? parentPath : parentPath + "/"
+        return path.hasPrefix(prefix)
+    }
+
+    // MARK: - Manifest load
+
+    private static func loadEntries(from url: URL, pdfsDirectory: URL) throws -> [HistoryEntry] {
+        let fm = FileManager.default
+        guard fm.fileExists(atPath: url.path) else { return [] }
+        let data: Data
+        do {
+            data = try Data(contentsOf: url)
+        } catch {
+            throw ShotdeckError.spoolWriteFailed(
+                path: url.path,
+                underlying: error.localizedDescription
+            )
+        }
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601
+        do {
+            let decoded = try decoder.decode([HistoryEntry].self, from: data)
+            return decoded.map { entry in
+                HistoryEntry(
+                    id: entry.id,
+                    fileName: entry.fileName,
+                    fileURL: pdfsDirectory.appendingPathComponent(entry.fileName),
+                    originalFileName: entry.originalFileName,
+                    sessionID: entry.sessionID,
+                    pageCount: entry.pageCount,
+                    sentAt: entry.sentAt
+                )
+            }
+        } catch {
+            let corruptURL = url.deletingLastPathComponent()
+                .appendingPathComponent("history.json.corrupt-\(DubaiTime.fileStamp(Date()))")
+            try? fm.moveItem(at: url, to: corruptURL)
+            Log.spool.error(
+                "history.json could not be decoded; moved to \(corruptURL.path, privacy: .public): \(error.localizedDescription, privacy: .public)"
+            )
+            return []
+        }
+    }
+}

Sources/ShotdeckCore/PDF/PDFComposer.swift

@@ -70,8 +70,8 @@ public struct PDFComposer: Sendable {
         }
     }
 
-    public static func fileName(for session: CaptureSession) -> String {
-        "Redline-\(DubaiTime.fileStamp(session.createdAt)).pdf"
+    public static func fileName(for _: CaptureSession) -> String {
+        "Redline-\(DubaiTime.fileStamp(Date())).pdf"
     }
 
     private static func writePDF(

Tests/ShotdeckCoreTests/HistoryStoreTests.swift

@@ -0,0 +1,319 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+import Testing
+import ShotdeckCore
+
+@Test
+func recordTwelvePDFsKeepsTenNewestAndDeletesOldestCopies() async throws {
+    let (root, paths) = try makeHistoryPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let store = try HistoryStore(paths: paths)
+    let sources = root.appendingPathComponent("user-sources", isDirectory: true)
+    try FileManager.default.createDirectory(at: sources, withIntermediateDirectories: true)
+
+    var recorded: [HistoryEntry] = []
+    for i in 0..<12 {
+        let source = sources.appendingPathComponent("source-\(i).pdf")
+        try writeDummyPDF(to: source, marker: "pdf-\(i)")
+        let sentAt = Date(timeIntervalSince1970: 1_800_000_000 + TimeInterval(i))
+        let entry = try await store.recordSentPDF(
+            sourceURL: source,
+            sessionID: UUID(),
+            pageCount: i + 1,
+            sentAt: sentAt
+        )
+        recorded.append(entry)
+    }
+
+    let listed = await store.listPDFs()
+    #expect(listed.count == 10)
+    #expect(listed.map(\.id) == recorded.suffix(10).reversed().map(\.id))
+    #expect(listed.map(\.sentAt) == recorded.suffix(10).reversed().map(\.sentAt))
+
+    let pdfsDir = paths.root.appendingPathComponent("history/pdfs", isDirectory: true)
+    for entry in recorded.prefix(2) {
+        #expect(!FileManager.default.fileExists(atPath: pdfsDir.appendingPathComponent(entry.fileName).path))
+    }
+    for entry in recorded.suffix(10) {
+        #expect(FileManager.default.fileExists(atPath: pdfsDir.appendingPathComponent(entry.fileName).path))
+    }
+}
+
+@Test
+func pruneImagesKeepsThirtyNewestAcrossThreeArchivedSessionsAndLeavesOpenSessionAlone() async throws {
+    let (root, paths) = try makeHistoryPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let spool = try SpoolStore(paths: paths)
+    let base = Date(timeIntervalSince1970: 1_800_100_000)
+    var captures: [(id: UUID, capturedAt: Date, sessionID: UUID)] = []
+
+    // 5 oldest + 15 + 15 = 35 archived PNGs. The oldest session is emptied by prune.
+    let perSession = [5, 15, 15]
+    var index = 0
+    for count in perSession {
+        let sessionID = try await spool.currentSession().id
+        for _ in 0..<count {
+            let capturedAt = base.addingTimeInterval(TimeInterval(index))
+            let capture = try await spool.append(
+                pngData: try makeHistoryPNGData(width: 6, height: 4, red: 0.2, green: 0.3, blue: 0.4),
+                pixelWidth: 6,
+                pixelHeight: 4,
+                scale: 1.0,
+                capturedAt: capturedAt
+            )
+            captures.append((capture.id, capturedAt, sessionID))
+            index += 1
+        }
+        _ = try await spool.archiveCurrent(pdfFileName: "Redline-hist-\(sessionID.uuidString).pdf")
+    }
+
+    let openBefore = try await spool.currentSession()
+    let openCapture = try await spool.append(
+        pngData: try makeHistoryPNGData(width: 8, height: 6, red: 0.9, green: 0.1, blue: 0.1),
+        pixelWidth: 8,
+        pixelHeight: 6,
+        scale: 1.0,
+        capturedAt: Date(timeIntervalSince1970: 1_900_000_000)
+    )
+    let openSession = try await spool.currentSession()
+    #expect(openSession.id == openBefore.id)
+    let openDir = paths.sessionDirectory(openSession.id)
+    let openPNG = openDir.appendingPathComponent(openCapture.fileName)
+    let openPNGBytes = try Data(contentsOf: openPNG)
+    let openManifest = try Data(contentsOf: openDir.appendingPathComponent("session.json"))
+
+    let store = try HistoryStore(paths: paths)
+    try await store.pruneImages()
+
+    let remaining = try await store.listImages(limit: 50)
+    #expect(remaining.count == 30)
+
+    let newestThirty = Array(captures.suffix(30))
+    let remainingDates = Set(remaining.map(\.capturedAt))
+    #expect(remainingDates == Set(newestThirty.map(\.capturedAt)))
+    #expect(remaining.map(\.sessionID).allSatisfy { $0 != openSession.id })
+
+    let oldestFive = Array(captures.prefix(5))
+    for old in oldestFive {
+        let archiveDir = paths.archiveDirectory(old.sessionID)
+        #expect(!FileManager.default.fileExists(atPath: archiveDir.path))
+    }
+
+    #expect(pngFiles(under: paths.archive).count == 30)
+    try assertManifestsMatchDisk(archiveRoot: paths.archive)
+
+    #expect(FileManager.default.fileExists(atPath: openPNG.path))
+    #expect(try Data(contentsOf: openPNG) == openPNGBytes)
+    #expect(try Data(contentsOf: openDir.appendingPathComponent("session.json")) == openManifest)
+    #expect(try await spool.currentSession().captures.map(\.id) == [openCapture.id])
+}
+
+@Test
+func recordSentPDFLeavesTheUserSourceUntouched() async throws {
+    let (root, paths) = try makeHistoryPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let source = root.appendingPathComponent("outside-appsupport.pdf")
+    let payload = Data("%PDF-1.4\n%user-original\n%%EOF\n".utf8)
+    try payload.write(to: source)
+
+    let store = try HistoryStore(paths: paths)
+    let entry = try await store.recordSentPDF(
+        sourceURL: source,
+        sessionID: UUID(),
+        pageCount: 2,
+        sentAt: Date(timeIntervalSince1970: 1_800_200_000)
+    )
+
+    #expect(FileManager.default.fileExists(atPath: source.path))
+    #expect(try Data(contentsOf: source) == payload)
+    #expect(entry.fileURL.path != source.path)
+    #expect(try Data(contentsOf: entry.fileURL) == payload)
+    #expect(entry.fileURL.path.hasPrefix(
+        paths.root.appendingPathComponent("history/pdfs", isDirectory: true).path
+    ))
+}
+
+@Test
+func recordingTheSameSourceTwiceMakesTwoDistinctCopies() async throws {
+    let (root, paths) = try makeHistoryPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let source = root.appendingPathComponent("resend.pdf")
+    try writeDummyPDF(to: source, marker: "same-source")
+
+    let store = try HistoryStore(paths: paths)
+    let first = try await store.recordSentPDF(
+        sourceURL: source,
+        sessionID: nil,
+        pageCount: 1,
+        sentAt: Date(timeIntervalSince1970: 1_800_300_000)
+    )
+    let second = try await store.recordSentPDF(
+        sourceURL: source,
+        sessionID: nil,
+        pageCount: 1,
+        sentAt: Date(timeIntervalSince1970: 1_800_300_001)
+    )
+
+    #expect(first.id != second.id)
+    #expect(first.fileName != second.fileName)
+    #expect(first.fileURL.path != second.fileURL.path)
+    #expect(FileManager.default.fileExists(atPath: first.fileURL.path))
+    #expect(FileManager.default.fileExists(atPath: second.fileURL.path))
+    let firstBytes = try Data(contentsOf: first.fileURL)
+    let secondBytes = try Data(contentsOf: second.fileURL)
+    #expect(firstBytes == secondBytes)
+    #expect(FileManager.default.fileExists(atPath: source.path))
+
+    let listed = await store.listPDFs()
+    #expect(listed.count == 2)
+    #expect(Set(listed.map(\.id)) == [first.id, second.id])
+}
+
+@Test
+func pruneImagesDeletesOlderPNGsInRemovedFolders() async throws {
+    let (root, paths) = try makeHistoryPaths()
+    defer { try? FileManager.default.removeItem(at: root) }
+
+    let spool = try SpoolStore(paths: paths)
+    let base = Date(timeIntervalSince1970: 1_800_400_000)
+    for i in 0..<30 {
+        _ = try await spool.append(
+            pngData: try makeHistoryPNGData(width: 4, height: 4, red: 0.1, green: 0.2, blue: 0.3),
+            pixelWidth: 4,
+            pixelHeight: 4,
+            scale: 1.0,
+            capturedAt: base.addingTimeInterval(TimeInterval(10 + i))
+        )
+    }
+    _ = try await spool.archiveCurrent(pdfFileName: "Redline-keep.pdf")
+
+    let oldSessionID = UUID()
+    let oldDir = paths.archiveDirectory(oldSessionID)
+    let removedDir = oldDir.appendingPathComponent("removed", isDirectory: true)
+    try FileManager.default.createDirectory(at: removedDir, withIntermediateDirectories: true)
+    let oldPNG = removedDir.appendingPathComponent("001-DEADBEEF.png")
+    try makeHistoryPNGData(width: 4, height: 4, red: 0.5, green: 0.5, blue: 0.5).write(to: oldPNG)
+    try FileManager.default.setAttributes(
+        [.creationDate: base],
+        ofItemAtPath: oldPNG.path
+    )
+    let oldSession = CaptureSession(
+        id: oldSessionID,
+        createdAt: base,
+        state: .archived,
+        captures: [],
+        pdfFileName: "Redline-old.pdf"
+    )
+    try AtomicFile.writeJSON(oldSession, to: oldDir.appendingPathComponent("session.json"))
+
+    let store = try HistoryStore(paths: paths)
+    try await store.pruneImages()
+
+    #expect(!FileManager.default.fileExists(atPath: oldPNG.path))
+    #expect(pngFiles(under: paths.archive).count == 30)
+}
+
+// MARK: - Fixtures
+
+private func makeHistoryPaths() throws -> (root: URL, paths: AppSupportPaths) {
+    let root = FileManager.default.temporaryDirectory
+        .appendingPathComponent("shotdeck-history-\(UUID().uuidString)", isDirectory: true)
+    let paths = try AppSupportPaths(
+        root: root.appendingPathComponent("root", isDirectory: true),
+        outbox: root.appendingPathComponent("outbox", isDirectory: true),
+        watchFolder: root.appendingPathComponent("watch", isDirectory: true)
+    )
+    return (root, paths)
+}
+
+private func writeDummyPDF(to url: URL, marker: String) throws {
+    try Data("%PDF-1.4\n%\(marker)\n%%EOF\n".utf8).write(to: url)
+}
+
+private func makeHistoryPNGData(
+    width: Int,
+    height: Int,
+    red: CGFloat,
+    green: CGFloat,
+    blue: CGFloat
+) throws -> Data {
+    let colorSpace = CGColorSpaceCreateDeviceRGB()
+    guard let context = CGContext(
+        data: nil,
+        width: width,
+        height: height,
+        bitsPerComponent: 8,
+        bytesPerRow: width * 4,
+        space: colorSpace,
+        bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
+    ) else {
+        throw HistoryFixtureError.pngGenerationFailed
+    }
+    context.setFillColor(red: red, green: green, blue: blue, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    guard let image = context.makeImage() else {
+        throw HistoryFixtureError.pngGenerationFailed
+    }
+    let buffer = NSMutableData()
+    guard let destination = CGImageDestinationCreateWithData(buffer, "public.png" as CFString, 1, nil) else {
+        throw HistoryFixtureError.pngGenerationFailed
+    }
+    CGImageDestinationAddImage(destination, image, nil)
+    guard CGImageDestinationFinalize(destination) else {
+        throw HistoryFixtureError.pngGenerationFailed
+    }
+    return buffer as Data
+}
+
+private func pngFiles(under root: URL) -> [URL] {
+    let fm = FileManager.default
+    guard let enumerator = fm.enumerator(
+        at: root,
+        includingPropertiesForKeys: [.isRegularFileKey],
+        options: []
+    ) else { return [] }
+    var urls: [URL] = []
+    for case let url as URL in enumerator {
+        let isFile = (try? url.resourceValues(forKeys: [.isRegularFileKey]).isRegularFile) ?? false
+        if isFile, url.pathExtension.lowercased() == "png" {
+            urls.append(url)
+        }
+    }
+    return urls
+}
+
+private func assertManifestsMatchDisk(archiveRoot: URL) throws {
+    let fm = FileManager.default
+    let sessions = (try fm.contentsOfDirectory(
+        at: archiveRoot,
+        includingPropertiesForKeys: [.isDirectoryKey],
+        options: []
+    )).filter {
+        ((try? $0.resourceValues(forKeys: [.isDirectoryKey]).isDirectory) ?? false)
+            && UUID(uuidString: $0.lastPathComponent) != nil
+    }
+    let decoder = JSONDecoder()
+    decoder.dateDecodingStrategy = .iso8601
+    for dir in sessions {
+        let manifestURL = dir.appendingPathComponent("session.json")
+        #expect(fm.fileExists(atPath: manifestURL.path))
+        let session = try decoder.decode(CaptureSession.self, from: Data(contentsOf: manifestURL))
+        for capture in session.captures {
+            let url = dir.appendingPathComponent(capture.fileName)
+            #expect(fm.fileExists(atPath: url.path))
+        }
+        let topLevelPNGs = (try fm.contentsOfDirectory(at: dir, includingPropertiesForKeys: nil, options: []))
+            .filter { $0.pathExtension.lowercased() == "png" }
+        let manifestNames = Set(session.captures.map(\.fileName))
+        #expect(Set(topLevelPNGs.map(\.lastPathComponent)) == manifestNames)
+    }
+}
+
+private enum HistoryFixtureError: Error {
+    case pngGenerationFailed
+}

Tests/ShotdeckCoreTests/PDFComposerTests.swift

@@ -203,6 +203,17 @@ private func pixelWindow(
     return (pixelX0, pixelY0, pixelX1, pixelY1)
 }
 
+@Test("fileName uses compose time, not session.createdAt, and matches Redline-yyyyMMdd-HHmmss.pdf")
+func fileNameUsesComposeTimeNotSessionCreatedAt() {
+    let old = Date(timeIntervalSince1970: 1_600_000_000) // 2020-09-13
+    let session = makeSession(captures: [], createdAt: old)
+    let name = PDFComposer.fileName(for: session)
+    #expect(name.wholeMatch(of: /^Redline-\d{8}-\d{6}\.pdf$/) != nil)
+    #expect(!name.contains(DubaiTime.fileStamp(old)))
+    let today = String(DubaiTime.fileStamp(Date()).prefix(8))
+    #expect(name.contains(today))
+}
+
 @Test("Three-page basic compose")
 func threePageBasicCompose() throws {
     let directory = try makeScratchDirectory()

scripts/build-app.sh

@@ -43,6 +43,7 @@ mkdir -p "${APP_BUNDLE}/Contents/Resources"
 cp "${BIN_PATH}" "${APP_BUNDLE}/Contents/MacOS/Shotdeck"
 chmod +x "${APP_BUNDLE}/Contents/MacOS/Shotdeck"
 cp "${ROOT}/Info.plist" "${APP_BUNDLE}/Contents/Info.plist"
+cp "${ROOT}/Resources/AppIcon.icns" "${APP_BUNDLE}/Contents/Resources/AppIcon.icns"
 
 if [[ "${SKIP_SIGN}" -eq 1 ]]; then
     echo

scripts/make-icon.swift

@@ -0,0 +1,324 @@
+#!/usr/bin/env swift
+import Foundation
+import CoreGraphics
+import ImageIO
+
+// Programmatic Redline app icon.
+// Draws a 1024×1024 master, writes AppIcon.iconset (16…1024 incl. @2x),
+// and compiles Resources/AppIcon.icns via iconutil.
+//
+// Usage:
+//   swift scripts/make-icon.swift
+//   swift scripts/make-icon.swift --preview /path/to/icon-512.png
+
+private let masterSize = 1024
+
+private enum Palette {
+    static let charcoalTop = CGColor(srgbRed: 44.0 / 255.0, green: 44.0 / 255.0, blue: 46.0 / 255.0, alpha: 1)
+    static let charcoalBottom = CGColor(srgbRed: 28.0 / 255.0, green: 28.0 / 255.0, blue: 30.0 / 255.0, alpha: 1) // #1C1C1E
+    static let white = CGColor(srgbRed: 1, green: 1, blue: 1, alpha: 1)
+    static let redline = CGColor(srgbRed: 229.0 / 255.0, green: 72.0 / 255.0, blue: 63.0 / 255.0, alpha: 1) // #E5483F
+}
+
+private struct IconsetEntry {
+    let filename: String
+    let pixels: Int
+}
+
+private let iconsetEntries: [IconsetEntry] = [
+    IconsetEntry(filename: "icon_16x16.png", pixels: 16),
+    IconsetEntry(filename: "icon_16x16@2x.png", pixels: 32),
+    IconsetEntry(filename: "icon_32x32.png", pixels: 32),
+    IconsetEntry(filename: "icon_32x32@2x.png", pixels: 64),
+    IconsetEntry(filename: "icon_128x128.png", pixels: 128),
+    IconsetEntry(filename: "icon_128x128@2x.png", pixels: 256),
+    IconsetEntry(filename: "icon_256x256.png", pixels: 256),
+    IconsetEntry(filename: "icon_256x256@2x.png", pixels: 512),
+    IconsetEntry(filename: "icon_512x512.png", pixels: 512),
+    IconsetEntry(filename: "icon_512x512@2x.png", pixels: 1024),
+]
+
+// MARK: - Geometry
+
+/// Apple-style continuous-corner rounded square (squircle-like).
+/// Superellipse |x/a|^n + |y/b|^n = 1 with n≈5, inset 1px so antialiased
+/// edge pixels are not clipped by the bitmap.
+private func continuousRoundedSquare(size: CGFloat, exponent n: CGFloat = 5.0, segments: Int = 256) -> CGPath {
+    let inset: CGFloat = 1
+    let a = (size - inset * 2) / 2
+    let cx = size / 2
+    let cy = size / 2
+    let twoOverN = 2 / n
+    let path = CGMutablePath()
+    for i in 0...segments {
+        let theta = CGFloat(i) / CGFloat(segments) * 2 * .pi
+        let ct = cos(theta)
+        let st = sin(theta)
+        let x = cx + (ct < 0 ? -1 : 1) * pow(abs(ct), twoOverN) * a
+        let y = cy + (st < 0 ? -1 : 1) * pow(abs(st), twoOverN) * a
+        if i == 0 {
+            path.move(to: CGPoint(x: x, y: y))
+        } else {
+            path.addLine(to: CGPoint(x: x, y: y))
+        }
+    }
+    path.closeSubpath()
+    return path
+}
+
+// MARK: - Drawing
+
+private func drawMasterIcon(size: Int) -> CGImage {
+    let s = CGFloat(size)
+    let colorSpace = CGColorSpace(name: CGColorSpace.sRGB)!
+    let bitmapInfo = CGBitmapInfo.byteOrder32Big.rawValue | CGImageAlphaInfo.premultipliedLast.rawValue
+    guard let ctx = CGContext(
+        data: nil,
+        width: size,
+        height: size,
+        bitsPerComponent: 8,
+        bytesPerRow: 0,
+        space: colorSpace,
+        bitmapInfo: bitmapInfo
+    ) else {
+        fputs("error: failed to create \(size)×\(size) bitmap context\n", stderr)
+        exit(1)
+    }
+
+    ctx.setShouldAntialias(true)
+    ctx.setAllowsAntialiasing(true)
+    ctx.interpolationQuality = .high
+
+    // Flip to top-left origin so "top-to-bottom gradient" is literal.
+    ctx.translateBy(x: 0, y: s)
+    ctx.scaleBy(x: 1, y: -1)
+
+    ctx.clear(CGRect(x: 0, y: 0, width: s, height: s))
+
+    let squircle = continuousRoundedSquare(size: s)
+
+    ctx.saveGState()
+    ctx.addPath(squircle)
+    ctx.clip()
+
+    let gradient = CGGradient(
+        colorsSpace: colorSpace,
+        colors: [Palette.charcoalTop, Palette.charcoalBottom] as CFArray,
+        locations: [0, 1]
+    )!
+    ctx.drawLinearGradient(
+        gradient,
+        start: CGPoint(x: s / 2, y: 0),
+        end: CGPoint(x: s / 2, y: s),
+        options: [.drawsBeforeStartLocation, .drawsAfterEndLocation]
+    )
+    ctx.restoreGState()
+
+    // Viewfinder corner brackets: thick L-strokes, rounded caps/joins, inset ~18%.
+    let inset = s * 0.18
+    let bracketWidth = s * 0.095
+    let arm = s * 0.155
+    let centerline = inset + bracketWidth / 2
+
+    ctx.saveGState()
+    ctx.addPath(squircle)
+    ctx.clip()
+    ctx.setStrokeColor(Palette.white)
+    ctx.setLineWidth(bracketWidth)
+    ctx.setLineCap(.round)
+    ctx.setLineJoin(.round)
+
+    func strokeBracket(cornerX: CGFloat, cornerY: CGFloat, dirX: CGFloat, dirY: CGFloat) {
+        let path = CGMutablePath()
+        path.move(to: CGPoint(x: cornerX + dirX * arm, y: cornerY))
+        path.addLine(to: CGPoint(x: cornerX, y: cornerY))
+        path.addLine(to: CGPoint(x: cornerX, y: cornerY + dirY * arm))
+        ctx.addPath(path)
+        ctx.strokePath()
+    }
+
+    // Top-left, top-right, bottom-left, bottom-right.
+    strokeBracket(cornerX: centerline, cornerY: centerline, dirX: 1, dirY: 1)
+    strokeBracket(cornerX: s - centerline, cornerY: centerline, dirX: -1, dirY: 1)
+    strokeBracket(cornerX: centerline, cornerY: s - centerline, dirX: 1, dirY: -1)
+    strokeBracket(cornerX: s - centerline, cornerY: s - centerline, dirX: -1, dirY: -1)
+
+    // Bold redline slash over the frame, lower-left bracket area → upper-right.
+    let slashWidth = s * 0.078
+    ctx.setStrokeColor(Palette.redline)
+    ctx.setLineWidth(slashWidth)
+    ctx.setLineCap(.round)
+    ctx.setLineJoin(.round)
+    let slashInset = centerline + arm * 0.12
+    let slash = CGMutablePath()
+    slash.move(to: CGPoint(x: slashInset, y: s - slashInset))
+    slash.addLine(to: CGPoint(x: s - slashInset, y: slashInset))
+    ctx.addPath(slash)
+    ctx.strokePath()
+    ctx.restoreGState()
+
+    guard let image = ctx.makeImage() else {
+        fputs("error: failed to materialize master CGImage\n", stderr)
+        exit(1)
+    }
+    return image
+}
+
+private func scaledImage(_ image: CGImage, pixels: Int) -> CGImage {
+    if image.width == pixels && image.height == pixels {
+        return image
+    }
+    let colorSpace = CGColorSpace(name: CGColorSpace.sRGB)!
+    let bitmapInfo = CGBitmapInfo.byteOrder32Big.rawValue | CGImageAlphaInfo.premultipliedLast.rawValue
+    guard let ctx = CGContext(
+        data: nil,
+        width: pixels,
+        height: pixels,
+        bitsPerComponent: 8,
+        bytesPerRow: 0,
+        space: colorSpace,
+        bitmapInfo: bitmapInfo
+    ) else {
+        fputs("error: failed to create \(pixels)×\(pixels) scale context\n", stderr)
+        exit(1)
+    }
+    ctx.interpolationQuality = .high
+    ctx.setShouldAntialias(true)
+    ctx.draw(image, in: CGRect(x: 0, y: 0, width: pixels, height: pixels))
+    guard let out = ctx.makeImage() else {
+        fputs("error: failed to scale image to \(pixels)px\n", stderr)
+        exit(1)
+    }
+    return out
+}
+
+private func writePNG(_ image: CGImage, to url: URL) {
+    let dir = url.deletingLastPathComponent()
+    try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    if FileManager.default.fileExists(atPath: url.path) {
+        try? FileManager.default.removeItem(at: url)
+    }
+    guard let dest = CGImageDestinationCreateWithURL(url as CFURL, "public.png" as CFString, 1, nil) else {
+        fputs("error: cannot create PNG destination at \(url.path)\n", stderr)
+        exit(1)
+    }
+    CGImageDestinationAddImage(dest, image, nil)
+    if !CGImageDestinationFinalize(dest) {
+        fputs("error: failed to write PNG \(url.path)\n", stderr)
+        exit(1)
+    }
+}
+
+// MARK: - Paths / CLI
+
+private func repoRoot() -> URL {
+    let cwd = URL(fileURLWithPath: FileManager.default.currentDirectoryPath, isDirectory: true)
+    let arg0 = URL(fileURLWithPath: CommandLine.arguments[0])
+    let scriptURL: URL
+    if arg0.path.hasPrefix("/") {
+        scriptURL = arg0.standardizedFileURL
+    } else {
+        scriptURL = cwd.appendingPathComponent(arg0.path).standardizedFileURL
+    }
+    let fromScript = scriptURL.deletingLastPathComponent().deletingLastPathComponent()
+    if FileManager.default.fileExists(atPath: fromScript.appendingPathComponent("Package.swift").path) {
+        return fromScript
+    }
+    if FileManager.default.fileExists(atPath: cwd.appendingPathComponent("Package.swift").path) {
+        return cwd
+    }
+    fputs("error: could not find repo root (Package.swift)\n", stderr)
+    exit(1)
+}
+
+private func parsePreviewPath() -> String? {
+    let args = CommandLine.arguments
+    var i = 1
+    var preview: String?
+    while i < args.count {
+        let arg = args[i]
+        if arg == "--preview" {
+            i += 1
+            guard i < args.count else {
+                fputs("error: --preview requires a path\n", stderr)
+                exit(1)
+            }
+            preview = args[i]
+        } else if arg.hasPrefix("--preview=") {
+            preview = String(arg.dropFirst("--preview=".count))
+        } else if arg == "--help" || arg == "-h" {
+            fputs("Usage: swift scripts/make-icon.swift [--preview PATH]\n", stderr)
+            exit(0)
+        } else {
+            fputs("error: unknown argument \(arg)\n", stderr)
+            fputs("Usage: swift scripts/make-icon.swift [--preview PATH]\n", stderr)
+            exit(1)
+        }
+        i += 1
+    }
+    return preview
+}
+
+private func runIconutil(iconset: URL, icns: URL) {
+    let proc = Process()
+    proc.executableURL = URL(fileURLWithPath: "/usr/bin/iconutil")
+    proc.arguments = ["-c", "icns", iconset.path, "-o", icns.path]
+    proc.standardOutput = FileHandle.standardOutput
+    proc.standardError = FileHandle.standardError
+    do {
+        try proc.run()
+        proc.waitUntilExit()
+    } catch {
+        fputs("error: failed to launch iconutil: \(error)\n", stderr)
+        exit(1)
+    }
+    if proc.terminationStatus != 0 {
+        fputs("error: iconutil exited \(proc.terminationStatus)\n", stderr)
+        exit(1)
+    }
+}
+
+// MARK: - Main
+
+let root = repoRoot()
+let resources = root.appendingPathComponent("Resources", isDirectory: true)
+let icnsURL = resources.appendingPathComponent("AppIcon.icns")
+let previewPath = parsePreviewPath()
+let fm = FileManager.default
+
+print("==> Drawing \(masterSize)×\(masterSize) master")
+let master = drawMasterIcon(size: masterSize)
+
+let iconset = fm.temporaryDirectory.appendingPathComponent("Redline-AppIcon-\(UUID().uuidString).iconset", isDirectory: true)
+
+do {
+    try fm.createDirectory(at: iconset, withIntermediateDirectories: true)
+    try fm.createDirectory(at: resources, withIntermediateDirectories: true)
+
+    print("==> Writing AppIcon.iconset")
+    for entry in iconsetEntries {
+        let img = scaledImage(master, pixels: entry.pixels)
+        writePNG(img, to: iconset.appendingPathComponent(entry.filename))
+    }
+
+    if fm.fileExists(atPath: icnsURL.path) {
+        try fm.removeItem(at: icnsURL)
+    }
+
+    print("==> Compiling \(icnsURL.path)")
+    runIconutil(iconset: iconset, icns: icnsURL)
+
+    try? fm.removeItem(at: iconset)
+} catch {
+    try? fm.removeItem(at: iconset)
+    fputs("error: \(error)\n", stderr)
+    exit(1)
+}
+
+if let previewPath {
+    let previewURL = URL(fileURLWithPath: previewPath)
+    print("==> Writing 512px preview \(previewURL.path)")
+    writePNG(scaledImage(master, pixels: 512), to: previewURL)
+}
+
+print("App icon: \(icnsURL.path)")

scripts/publish-update.sh

@@ -0,0 +1,287 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# One-command Redline release: bump Info.plist, commit, signed build, zip,
+# DMG, appcast, upload to mmd01, verify the public URLs.
+# Hidden flag: --test  — upload under .../redline/test/ and skip the git commit.
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "${ROOT}"
+
+PLIST="${ROOT}/Info.plist"
+PLISTBUDDY="/usr/libexec/PlistBuddy"
+REMOTE_HOST="mmd01"
+REMOTE_BASE="/opt/mmd-installer-content/cowork/redline"
+PUBLIC_BASE="https://get.baobab-ts.com/cowork/redline"
+SIGN_IDENTITY="Apple Development: ben@flow-master.ai (QH2H9G2LK5)"
+
+usage() {
+    echo "Usage: $0 <version> [\"notes\"]" >&2
+    exit 1
+}
+
+TEST_MODE=0
+VERSION=""
+NOTES=""
+NOTES_SET=0
+for arg in "$@"; do
+    case "${arg}" in
+        --test)
+            TEST_MODE=1
+            ;;
+        --help|-h)
+            usage
+            ;;
+        --*)
+            echo "Unknown argument: ${arg}" >&2
+            usage
+            ;;
+        *)
+            if [[ -z "${VERSION}" ]]; then
+                VERSION="${arg}"
+            elif [[ "${NOTES_SET}" -eq 0 ]]; then
+                NOTES="${arg}"
+                NOTES_SET=1
+            else
+                echo "Unexpected extra argument: ${arg}" >&2
+                usage
+            fi
+            ;;
+    esac
+done
+
+if [[ -z "${VERSION}" ]]; then
+    usage
+fi
+
+if [[ ! "${VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][A-Za-z0-9.-]+)*$ ]]; then
+    echo "Version '${VERSION}' is not a semver (e.g. 1.2.3 or 0.0.0-test)." >&2
+    exit 1
+fi
+
+if [[ "${VERSION}" == *'/'* || "${VERSION}" == *'..'* ]]; then
+    echo "Version contains illegal path characters: ${VERSION}" >&2
+    exit 1
+fi
+
+if [[ "${TEST_MODE}" -eq 1 ]]; then
+    REMOTE_DIR="${REMOTE_BASE}/test"
+    PUBLIC_DIR="${PUBLIC_BASE}/test"
+else
+    REMOTE_DIR="${REMOTE_BASE}"
+    PUBLIC_DIR="${PUBLIC_BASE}"
+fi
+
+ZIP_NAME="Redline-${VERSION}.zip"
+DMG_NAME="Redline-${VERSION}.dmg"
+ZIP_PATH="${ROOT}/.build/${ZIP_NAME}"
+DMG_PATH="${ROOT}/.build/Redline.dmg"
+APPCAST_PATH="${ROOT}/.build/appcast.json"
+ZIP_URL="${PUBLIC_DIR}/${ZIP_NAME}"
+APPCAST_URL="${PUBLIC_DIR}/appcast.json"
+
+if [[ "${TEST_MODE}" -eq 1 ]]; then
+    echo "==> Publish Redline ${VERSION} (test)"
+else
+    echo "==> Publish Redline ${VERSION}"
+fi
+echo "    remote: ${REMOTE_HOST}:${REMOTE_DIR}/"
+echo "    public: ${PUBLIC_DIR}/"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    echo "Not inside a git work tree." >&2
+    exit 1
+fi
+
+# Tracked files must match HEAD. Untracked files are ignored so this script
+# can be dry-run (--test) before it is itself committed.
+if [[ -n "$(git status --porcelain -uno)" ]]; then
+    echo "git tree is not clean; commit or stash before publishing." >&2
+    git status --porcelain -uno >&2
+    exit 1
+fi
+
+if [[ ! -x "${PLISTBUDDY}" ]]; then
+    echo "PlistBuddy not found at ${PLISTBUDDY}" >&2
+    exit 1
+fi
+if [[ ! -f "${PLIST}" ]]; then
+    echo "Info.plist not found at ${PLIST}" >&2
+    exit 1
+fi
+
+restore_plist() {
+    git checkout -- "${PLIST}" >/dev/null 2>&1 || true
+}
+
+if [[ "${TEST_MODE}" -eq 1 ]]; then
+    trap restore_plist EXIT
+fi
+
+CURRENT_BUILD="$("${PLISTBUDDY}" -c 'Print :CFBundleVersion' "${PLIST}")"
+if [[ ! "${CURRENT_BUILD}" =~ ^[0-9]+$ ]]; then
+    echo "CFBundleVersion is not an integer: ${CURRENT_BUILD}" >&2
+    exit 1
+fi
+NEW_BUILD=$((CURRENT_BUILD + 1))
+
+echo "==> Bumping Info.plist"
+echo "    CFBundleShortVersionString -> ${VERSION}"
+echo "    CFBundleVersion ${CURRENT_BUILD} -> ${NEW_BUILD}"
+"${PLISTBUDDY}" -c "Set :CFBundleShortVersionString ${VERSION}" "${PLIST}"
+"${PLISTBUDDY}" -c "Set :CFBundleVersion ${NEW_BUILD}" "${PLIST}"
+
+if [[ "${TEST_MODE}" -eq 0 ]]; then
+    echo "==> Committing version bump on $(git rev-parse --abbrev-ref HEAD)"
+    git add "${PLIST}"
+    git commit -m "release: v${VERSION}"
+else
+    echo "==> --test: skipping git commit of version bump"
+fi
+
+# Restricted HOMEs (agent sandboxes) hide the login keychain from codesign.
+# Re-run signed steps with the account's real home when the identity is missing.
+signing_home() {
+    if security find-identity -v -p codesigning 2>/dev/null | grep -Fq "${SIGN_IDENTITY}"; then
+        echo "${HOME}"
+        return
+    fi
+    local rh
+    rh="$(dscl . -read "/Users/$(id -un)" NFSHomeDirectory 2>/dev/null | awk '{print $2}')"
+    if [[ -n "${rh}" && -d "${rh}" ]]; then
+        echo "${rh}"
+    else
+        echo "${HOME}"
+    fi
+}
+
+run_signed() {
+    local sign_home
+    sign_home="$(signing_home)"
+    if [[ "${sign_home}" != "${HOME}" ]]; then
+        echo "==> Using HOME=${sign_home} so codesign can see the login keychain"
+    fi
+    HOME="${sign_home}" "$@"
+}
+
+echo "==> Building signed Redline.app"
+run_signed ./scripts/build-app.sh
+
+if [[ ! -d "${ROOT}/.build/Redline.app" ]]; then
+    echo "Signed app missing at ${ROOT}/.build/Redline.app" >&2
+    exit 1
+fi
+
+echo "==> Zipping Redline.app -> ${ZIP_PATH}"
+mkdir -p "${ROOT}/.build"
+(
+    cd "${ROOT}/.build"
+    rm -f "${ZIP_NAME}"
+    ditto -c -k --keepParent Redline.app "${ZIP_NAME}"
+)
+
+if [[ ! -s "${ZIP_PATH}" ]]; then
+    echo "Zip was not created at ${ZIP_PATH}" >&2
+    exit 1
+fi
+
+echo "==> Building manual installer DMG"
+run_signed ./scripts/make-dmg.sh
+
+if [[ ! -s "${DMG_PATH}" ]]; then
+    echo "DMG was not created at ${DMG_PATH}" >&2
+    exit 1
+fi
+
+SHA256="$(shasum -a 256 "${ZIP_PATH}" | awk '{print $1}')"
+ZIP_BYTES="$(stat -f%z "${ZIP_PATH}")"
+PUBDATE="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+
+echo "==> Zip SHA256: ${SHA256}"
+echo "    Zip bytes:  ${ZIP_BYTES}"
+
+echo "==> Writing ${APPCAST_PATH}"
+python3 - "${VERSION}" "${ZIP_URL}" "${SHA256}" "${NOTES}" "${PUBDATE}" "${APPCAST_PATH}" <<'PY'
+import json
+import sys
+
+version, zip_url, sha256, notes, pub_date, out_path = sys.argv[1:]
+payload = {
+    "version": version,
+    "zipURL": zip_url,
+    "sha256": sha256,
+    "notes": notes,
+    "pubDate": pub_date,
+}
+with open(out_path, "w", encoding="utf-8") as fh:
+    json.dump(payload, fh, indent=2)
+    fh.write("\n")
+PY
+
+echo "==> Uploading to ${REMOTE_HOST}:${REMOTE_DIR}/"
+ssh -o BatchMode=yes "${REMOTE_HOST}" "mkdir -p '${REMOTE_DIR}'"
+rsync -e "ssh -o BatchMode=yes" -av "${ZIP_PATH}" "${REMOTE_HOST}:${REMOTE_DIR}/${ZIP_NAME}"
+rsync -e "ssh -o BatchMode=yes" -av "${DMG_PATH}" "${REMOTE_HOST}:${REMOTE_DIR}/Redline.dmg"
+rsync -e "ssh -o BatchMode=yes" -av "${DMG_PATH}" "${REMOTE_HOST}:${REMOTE_DIR}/${DMG_NAME}"
+rsync -e "ssh -o BatchMode=yes" -av "${APPCAST_PATH}" "${REMOTE_HOST}:${REMOTE_DIR}/appcast.json"
+ssh -o BatchMode=yes "${REMOTE_HOST}" \
+    "chmod 644 \
+        '${REMOTE_DIR}/${ZIP_NAME}' \
+        '${REMOTE_DIR}/Redline.dmg' \
+        '${REMOTE_DIR}/${DMG_NAME}' \
+        '${REMOTE_DIR}/appcast.json'"
+
+echo "==> Verifying public appcast ${APPCAST_URL}"
+APPCAST_BODY=""
+ok=0
+attempt=1
+while [[ "${attempt}" -le 15 ]]; do
+    if APPCAST_BODY="$(curl -fsS "${APPCAST_URL}")"; then
+        echo "${APPCAST_BODY}"
+        if grep -F -q "${VERSION}" <<<"${APPCAST_BODY}"; then
+            echo "OK: appcast contains ${VERSION}"
+            ok=1
+            break
+        fi
+        echo "appcast fetched but does not contain '${VERSION}' (attempt ${attempt})" >&2
+    else
+        echo "appcast fetch failed (attempt ${attempt})" >&2
+    fi
+    attempt=$((attempt + 1))
+    sleep 2
+done
+if [[ "${ok}" -ne 1 ]]; then
+    echo "Public appcast verification failed for ${APPCAST_URL}" >&2
+    exit 1
+fi
+
+echo "==> Verifying public zip HEAD ${ZIP_URL}"
+ok=0
+attempt=1
+HEAD_OUT=""
+while [[ "${attempt}" -le 15 ]]; do
+    HEAD_OUT="$(curl -sS -D - -o /dev/null -I "${ZIP_URL}" || true)"
+    echo "${HEAD_OUT}"
+    HTTP_CODE="$(awk 'BEGIN{c=""} toupper($1) ~ /^HTTP\//{c=$2} END{print c}' <<<"${HEAD_OUT}" | tr -d '\r')"
+    CONTENT_LENGTH="$(awk 'tolower($1)=="content-length:" {gsub("\r","",$2); print $2}' <<<"${HEAD_OUT}" | tail -n 1)"
+    if [[ "${HTTP_CODE}" == "200" && "${CONTENT_LENGTH}" == "${ZIP_BYTES}" ]]; then
+        echo "OK: zip HTTP ${HTTP_CODE}, Content-Length ${CONTENT_LENGTH} matches local ${ZIP_BYTES}"
+        ok=1
+        break
+    fi
+    echo "zip HEAD mismatch (attempt ${attempt}): HTTP '${HTTP_CODE}', Content-Length '${CONTENT_LENGTH}', local '${ZIP_BYTES}'" >&2
+    attempt=$((attempt + 1))
+    sleep 2
+done
+if [[ "${ok}" -ne 1 ]]; then
+    echo "Public zip verification failed for ${ZIP_URL}" >&2
+    exit 1
+fi
+
+echo
+echo "Published v${VERSION}"
+echo "  appcast: ${APPCAST_URL}"
+echo "  zip:     ${ZIP_URL}"
+echo "  sha256:  ${SHA256}"
+echo "  dmg:     ${PUBLIC_DIR}/${DMG_NAME}"
+echo "  dmg:     ${PUBLIC_DIR}/Redline.dmg"