From 8440a5c16971ffc553a481984428c2342a80e0ec Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 09:34:48 -0700
Subject: [PATCH 01/49] feat(query): serve Prometheus exposition at
 /metrics?format=prometheus (B7)

Render the latest snapshot as Prometheus text exposition so a dev with
Grafana can scrape their own Mac in minutes. New pure
MetricsPrometheus.exposition: gauges for CPU/memory/health/uptime/battery,
per-disk and per-interface labeled series, GPU omitted when unavailable
(-1 on Apple Silicon), and Prometheus label-value escaping.

QueryServer.route now returns (body, contentType): every route stays JSON
except the new endpoint, which serves text/plain; version=0.0.4 (the
de-facto scrape content type). A missing or undecodable snapshot yields a
comment line rather than error JSON, so scrapers tolerate an empty target.

Tests: 4 formatter cases + 2 route cases; existing route tests migrated to
the (body, contentType) tuple.
---
 Sources/MetricsPrometheus.swift    | 73 ++++++++++++++++++++++++++++++
 Sources/QueryServer.swift          | 51 +++++++++++++++------
 Tests/MetricsPrometheusTests.swift | 66 +++++++++++++++++++++++++++
 Tests/QueryServerTests.swift       | 61 ++++++++++++++++++-------
 4 files changed, 221 insertions(+), 30 deletions(-)
 create mode 100644 Sources/MetricsPrometheus.swift
 create mode 100644 Tests/MetricsPrometheusTests.swift

diff --git a/Sources/MetricsPrometheus.swift b/Sources/MetricsPrometheus.swift
new file mode 100644
index 00000000..b7301706
--- /dev/null
+++ b/Sources/MetricsPrometheus.swift
@@ -0,0 +1,73 @@
+//
+//  MetricsPrometheus.swift
+//  Burrow
+//
+//  Render the latest snapshot as Prometheus text exposition (roadmap B7),
+//  served from `GET /metrics?format=prometheus`. Pure: MoleStatus in,
+//  exposition text out — so a dev with Grafana can scrape their own Mac in
+//  minutes. Gauges only (these are instantaneous readings); per-disk and
+//  per-interface values are labeled series.
+//
+
+import Foundation
+
+enum MetricsPrometheus {
+    static func exposition(from s: MoleStatus) -> String {
+        var out = ""
+        gauge(&out, "burrow_cpu_usage_percent", "Current CPU usage (percent).", s.cpu.usage)
+        gauge(&out, "burrow_load1", "1-minute load average.", s.cpu.load1)
+        gauge(&out, "burrow_cpu_cores", "Physical core count.", Double(s.cpu.coreCount))
+        gauge(&out, "burrow_memory_used_bytes", "Memory used (bytes).", Double(s.memory.used))
+        gauge(&out, "burrow_memory_total_bytes", "Memory total (bytes).", Double(s.memory.total))
+        gauge(&out, "burrow_memory_used_percent", "Memory used (percent).", s.memory.usedPercent)
+        gauge(&out, "burrow_health_score", "Burrow health score (0-100).", Double(s.healthScore))
+        gauge(&out, "burrow_uptime_seconds", "System uptime (seconds).", Double(s.uptimeSeconds))
+
+        // Per-disk + per-interface are labeled series on one metric name.
+        labeled(&out, "burrow_disk_used_bytes", "Disk space used (bytes), by mount.",
+                s.disks.map { ("mount=\"\(esc($0.mount))\"", Double($0.used)) })
+        labeled(&out, "burrow_disk_total_bytes", "Disk total (bytes), by mount.",
+                s.disks.map { ("mount=\"\(esc($0.mount))\"", Double($0.total)) })
+        labeled(&out, "burrow_disk_free_bytes", "Disk free (bytes), by mount.",
+                s.disks.map { ("mount=\"\(esc($0.mount))\"", Double($0.total > $0.used ? $0.total - $0.used : 0)) })
+        labeled(&out, "burrow_disk_used_percent", "Disk used (percent), by mount.",
+                s.disks.map { ("mount=\"\(esc($0.mount))\"", $0.usedPercent) })
+        labeled(&out, "burrow_network_rx_mbps", "Receive rate (MB/s), by interface.",
+                s.network.map { ("interface=\"\(esc($0.name))\"", $0.rxRateMbs) })
+        labeled(&out, "burrow_network_tx_mbps", "Transmit rate (MB/s), by interface.",
+                s.network.map { ("interface=\"\(esc($0.name))\"", $0.txRateMbs) })
+
+        if let b = s.batteries?.first {
+            gauge(&out, "burrow_battery_percent", "Battery charge (percent).", b.percent)
+            gauge(&out, "burrow_battery_cycle_count", "Battery cycle count.", Double(b.cycleCount))
+        }
+        if let g = s.gpu?.first, g.usage >= 0 {   // -1 = unavailable on Apple Silicon
+            gauge(&out, "burrow_gpu_usage_percent", "GPU usage (percent).", g.usage)
+        }
+        return out
+    }
+
+    private static func gauge(_ out: inout String, _ name: String, _ help: String, _ v: Double) {
+        out += "# HELP \(name) \(help)\n# TYPE \(name) gauge\n\(name) \(num(v))\n"
+    }
+
+    /// A labeled gauge: one `# HELP`/`# TYPE` then one line per series.
+    /// Empty series (no disks/interfaces) emits nothing.
+    private static func labeled(_ out: inout String, _ name: String, _ help: String,
+                                _ series: [(labels: String, value: Double)]) {
+        guard !series.isEmpty else { return }
+        out += "# HELP \(name) \(help)\n# TYPE \(name) gauge\n"
+        for s in series { out += "\(name){\(s.labels)} \(num(s.value))\n" }
+    }
+
+    /// Escape a Prometheus label value (backslash and double-quote).
+    private static func esc(_ s: String) -> String {
+        s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
+    }
+
+    /// Whole numbers print without a decimal point (`42`, not `42.0`); the
+    /// rest keep their value. Prometheus accepts both.
+    private static func num(_ v: Double) -> String {
+        v == v.rounded() && abs(v) < 1e15 ? String(Int64(v)) : String(v)
+    }
+}
diff --git a/Sources/QueryServer.swift b/Sources/QueryServer.swift
index 4975e8f9..5d124942 100644
--- a/Sources/QueryServer.swift
+++ b/Sources/QueryServer.swift
@@ -150,31 +150,40 @@ final class QueryServer {
     /// client, and an allow-all grant would let any web page read /snapshot
     /// (hostname, process command lines) cross-origin. The real clients —
     /// curl and the stdio MCP bridge — don't need CORS at all.
-    static func httpHead(contentLength: Int) -> String {
+    static let jsonContentType = "application/json; charset=utf-8"
+    /// Prometheus text exposition format, version 0.0.4 — the de-facto scrape
+    /// content type. Served only by `/metrics?format=prometheus`.
+    static let prometheusContentType = "text/plain; version=0.0.4; charset=utf-8"
+
+    static func httpHead(contentLength: Int, contentType: String = jsonContentType) -> String {
         return "HTTP/1.1 200 OK\r\n"
-            + "Content-Type: application/json; charset=utf-8\r\n"
+            + "Content-Type: \(contentType)\r\n"
             + "Content-Length: \(contentLength)\r\n"
             + "Cache-Control: no-store\r\n"
             + "Connection: close\r\n"
             + "\r\n"
     }
 
-    private func send(_ json: String, on conn: NWConnection) {
-        let body = Data(json.utf8)
-        var payload = Data(Self.httpHead(contentLength: body.count).utf8)
+    private func send(_ response: (body: String, contentType: String), on conn: NWConnection) {
+        let body = Data(response.body.utf8)
+        var payload = Data(Self.httpHead(contentLength: body.count, contentType: response.contentType).utf8)
         payload.append(body)
         conn.send(content: payload, completion: .contentProcessed { _ in conn.cancel() })
     }
 
     // MARK: - Routing
 
-    func route(_ raw: String) -> String {
+    /// Returns the response body and its content type. Everything is JSON
+    /// except `/metrics?format=prometheus`, which is text exposition.
+    func route(_ raw: String) -> (body: String, contentType: String) {
+        func json(_ s: String) -> (body: String, contentType: String) { (s, Self.jsonContentType) }
+
         guard let first = raw.split(separator: "\r\n", maxSplits: 1).first else {
-            return Self.errorJSON("malformed request")
+            return json(Self.errorJSON("malformed request"))
         }
         let parts = first.split(separator: " ")
         guard parts.count >= 2, parts[0] == "GET" else {
-            return Self.errorJSON("only GET supported")
+            return json(Self.errorJSON("only GET supported"))
         }
         let target = String(parts[1])
         let split = target.split(separator: "?", maxSplits: 1)
@@ -183,19 +192,22 @@ final class QueryServer {
 
         switch path {
         case "/health":
-            return "{\"ok\":true,\"app\":\"Burrow\",\"port\":\(self.port)}"
+            return json("{\"ok\":true,\"app\":\"Burrow\",\"port\":\(self.port)}")
 
         case "/info":
-            return self.routeInfo()
+            return json(self.routeInfo())
 
         case "/snapshot":
-            return self.routeSnapshot()
+            return json(self.routeSnapshot())
 
         case "/metrics":
-            return self.routeMetrics(query: query)
+            if query["format"] == "prometheus" {
+                return (self.routeMetricsPrometheus(), Self.prometheusContentType)
+            }
+            return json(self.routeMetrics(query: query))
 
         default:
-            return Self.errorJSON("unknown route")
+            return json(Self.errorJSON("unknown route"))
         }
     }
 
@@ -239,6 +251,19 @@ final class QueryServer {
         return "{\"ts\":\(row.ts),\"snapshot\":\(row.json)}"
     }
 
+    /// `GET /metrics?format=prometheus` → the latest snapshot rendered as
+    /// Prometheus text exposition (roadmap B7), so a dev can point Grafana at
+    /// their own Mac. A missing or undecodable snapshot yields a comment line
+    /// rather than an error JSON — scrapers tolerate an empty target.
+    private func routeMetricsPrometheus() -> String {
+        guard let row = self.metrics.latestRaw(),
+              let status = try? JSONDecoder().decode(MoleStatus.self, from: Data(row.json.utf8))
+        else {
+            return "# burrow: no snapshot available\n"
+        }
+        return MetricsPrometheus.exposition(from: status)
+    }
+
     private func routeMetrics(query: [String: String]) -> String {
         guard let prefix = query["prefix"], !prefix.isEmpty else {
             return Self.errorJSON("missing 'prefix' query param")
diff --git a/Tests/MetricsPrometheusTests.swift b/Tests/MetricsPrometheusTests.swift
new file mode 100644
index 00000000..e289375d
--- /dev/null
+++ b/Tests/MetricsPrometheusTests.swift
@@ -0,0 +1,66 @@
+//
+//  MetricsPrometheusTests.swift
+//  BurrowTests
+//
+//  The Prometheus text-exposition formatter (roadmap B7): a pure
+//  MoleStatus → exposition-text function, so a dev with Grafana can scrape
+//  their Mac. Tested through the public `exposition(from:)` only.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MetricsPrometheusTests: XCTestCase {
+    private func decode(_ json: String) throws -> MoleStatus {
+        try JSONDecoder().decode(MoleStatus.self, from: Data(json.utf8))
+    }
+
+    /// Minimal valid snapshot; disks/network/gpu/battery are optional and
+    /// added per-test where the behavior needs them.
+    private func base(cpu: Double = 42,
+                      extra: String = "") -> String {
+        """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":\(cpu),"load1":1.5,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},
+         "top_processes":[]\(extra)}
+        """
+    }
+
+    func testExposition_cpuUsageGauge() throws {
+        let out = MetricsPrometheus.exposition(from: try decode(base(cpu: 42)))
+        XCTAssertTrue(out.contains("# TYPE burrow_cpu_usage_percent gauge"), out)
+        XCTAssertTrue(out.contains("\nburrow_cpu_usage_percent 42\n"), out)
+    }
+
+    func testExposition_memoryAndHealthGauges() throws {
+        let out = MetricsPrometheus.exposition(from: try decode(base()))
+        XCTAssertTrue(out.contains("\nburrow_memory_used_bytes 100\n"), out)
+        XCTAssertTrue(out.contains("\nburrow_memory_used_percent 50\n"), out)
+        XCTAssertTrue(out.contains("\nburrow_health_score 90\n"), out)
+    }
+
+    func testExposition_disksAndNetworkAreLabeledSeries() throws {
+        let extra = """
+        ,"disks":[{"mount":"/","used":40,"total":100,"used_percent":40,"external":false}],
+         "network":[{"name":"en0","rx_rate_mbs":1.5,"tx_rate_mbs":0.25,"ip":"10.0.0.2"}],
+         "batteries":[{"percent":80,"status":"","time_left":"","health":"Good","cycle_count":120,"capacity":95}],
+         "gpu":[{"name":"M","usage":12,"memory_used":0,"memory_total":0,"core_count":10}]
+        """
+        let out = MetricsPrometheus.exposition(from: try decode(base(extra: extra)))
+        XCTAssertTrue(out.contains("burrow_disk_used_bytes{mount=\"/\"} 40"), out)
+        XCTAssertTrue(out.contains("burrow_disk_free_bytes{mount=\"/\"} 60"), out)
+        XCTAssertTrue(out.contains("burrow_network_rx_mbps{interface=\"en0\"} 1.5"), out)
+        XCTAssertTrue(out.contains("burrow_battery_percent 80"), out)
+        XCTAssertTrue(out.contains("burrow_gpu_usage_percent 12"), out)
+    }
+
+    func testExposition_omitsGpuWhenUnavailable() throws {
+        let extra = #","gpu":[{"name":"M","usage":-1,"memory_used":0,"memory_total":0,"core_count":10}]"#
+        let out = MetricsPrometheus.exposition(from: try decode(base(extra: extra)))
+        XCTAssertFalse(out.contains("burrow_gpu_usage_percent"), out)
+    }
+}
diff --git a/Tests/QueryServerTests.swift b/Tests/QueryServerTests.swift
index 56ec4205..712e553b 100644
--- a/Tests/QueryServerTests.swift
+++ b/Tests/QueryServerTests.swift
@@ -82,24 +82,25 @@ final class QueryServerTests: XCTestCase {
 
     func testRoute_health() {
         let res = server.route("GET /health HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("\"ok\":true"))
-        XCTAssertTrue(res.contains("9277"))
+        XCTAssertTrue(res.body.contains("\"ok\":true"))
+        XCTAssertTrue(res.body.contains("9277"))
+        XCTAssertEqual(res.contentType, QueryServer.jsonContentType)
     }
 
     func testRoute_rejectsNonGET() {
         let res = server.route("POST /health HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("error"))
-        XCTAssertTrue(res.contains("only GET"))
+        XCTAssertTrue(res.body.contains("error"))
+        XCTAssertTrue(res.body.contains("only GET"))
     }
 
     func testRoute_unknownPathIsError() {
         let res = server.route("GET /admin HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("unknown route"))
+        XCTAssertTrue(res.body.contains("unknown route"))
     }
 
     func testRoute_malformedRequestIsError() {
-        XCTAssertTrue(server.route("").contains("error"))
-        XCTAssertTrue(server.route("\r\n\r\n").contains("error"))
+        XCTAssertTrue(server.route("").body.contains("error"))
+        XCTAssertTrue(server.route("\r\n\r\n").body.contains("error"))
     }
 
     func testRoute_snapshotReturnsLatestSeededRow() throws {
@@ -107,19 +108,19 @@ final class QueryServerTests: XCTestCase {
         try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 60, json: "{\"old\":true}")
         try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now, json: "{\"new\":true}")
         let res = server.route("GET /snapshot HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("\"new\":true"), "should embed the most recent row verbatim")
-        XCTAssertFalse(res.contains("\"old\":true"))
-        XCTAssertTrue(res.contains("\"ts\":\(now)"))
+        XCTAssertTrue(res.body.contains("\"new\":true"), "should embed the most recent row verbatim")
+        XCTAssertFalse(res.body.contains("\"old\":true"))
+        XCTAssertTrue(res.body.contains("\"ts\":\(now)"))
     }
 
     func testRoute_snapshotWithEmptyDBIsError() {
         let res = server.route("GET /snapshot HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("no snapshot yet"))
+        XCTAssertTrue(res.body.contains("no snapshot yet"))
     }
 
     func testRoute_metricsRequiresPrefix() {
         let res = server.route("GET /metrics HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("missing 'prefix'"))
+        XCTAssertTrue(res.body.contains("missing 'prefix'"))
     }
 
     func testRoute_metricsReturnsSeededRange() throws {
@@ -128,9 +129,35 @@ final class QueryServerTests: XCTestCase {
         try db.insert(prefix: "cpu", ts: now - 5, json: "{\"v\":2}")
         try db.insert(prefix: "other", ts: now - 5, json: "{\"v\":9}")
         let res = server.route("GET /metrics?prefix=cpu&since=0&until=\(now + 1) HTTP/1.1\r\n\r\n")
-        XCTAssertTrue(res.contains("{\"v\":1}"))
-        XCTAssertTrue(res.contains("{\"v\":2}"))
-        XCTAssertFalse(res.contains("{\"v\":9}"), "other prefixes must not bleed into the slice")
+        XCTAssertTrue(res.body.contains("{\"v\":1}"))
+        XCTAssertTrue(res.body.contains("{\"v\":2}"))
+        XCTAssertFalse(res.body.contains("{\"v\":9}"), "other prefixes must not bleed into the slice")
+    }
+
+    // Roadmap B7: `/metrics?format=prometheus` renders the latest snapshot as
+    // Prometheus text exposition, served with the text/plain scrape
+    // content-type (not JSON) so a real scraper accepts it.
+    func testRoute_metricsPrometheusRendersLatestSnapshot() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let snap = """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":42,"load1":1.5,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},"top_processes":[]}
+        """
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now, json: snap)
+        let res = server.route("GET /metrics?format=prometheus HTTP/1.1\r\n\r\n")
+        XCTAssertEqual(res.contentType, QueryServer.prometheusContentType)
+        XCTAssertTrue(res.body.contains("\nburrow_cpu_usage_percent 42\n"), res.body)
+        XCTAssertTrue(res.body.contains("# TYPE burrow_health_score gauge"), res.body)
+    }
+
+    func testRoute_metricsPrometheusWithEmptyDBYieldsComment() {
+        let res = server.route("GET /metrics?format=prometheus HTTP/1.1\r\n\r\n")
+        XCTAssertEqual(res.contentType, QueryServer.prometheusContentType)
+        XCTAssertTrue(res.body.hasPrefix("#"), "scrapers tolerate an empty target; emit a comment, not error JSON")
     }
 
     // Drift counters ride along on /info so a blank chart always has a
@@ -138,7 +165,7 @@ final class QueryServerTests: XCTestCase {
     func testRoute_infoSurfacesDriftCounters() throws {
         MetricsStore.resetDriftCounters()
         let clean = server.route("GET /info HTTP/1.1\r\n\r\n")
-        let cleanObj = try XCTUnwrap(try JSONSerialization.jsonObject(with: Data(clean.utf8)) as? [String: Any])
+        let cleanObj = try XCTUnwrap(try JSONSerialization.jsonObject(with: Data(clean.body.utf8)) as? [String: Any])
         XCTAssertEqual(cleanObj["decode_skipped_total"] as? Int, 0)
         XCTAssertTrue(cleanObj["last_drift"] is NSNull, "no drift yet → explicit null")
 
@@ -147,7 +174,7 @@ final class QueryServerTests: XCTestCase {
         _ = MetricsStore(db: db).snapshots(.init(since: 0, until: now + 1))
 
         let drifted = server.route("GET /info HTTP/1.1\r\n\r\n")
-        let obj = try XCTUnwrap(try JSONSerialization.jsonObject(with: Data(drifted.utf8)) as? [String: Any])
+        let obj = try XCTUnwrap(try JSONSerialization.jsonObject(with: Data(drifted.body.utf8)) as? [String: Any])
         XCTAssertEqual(obj["decode_skipped_total"] as? Int, 1)
         let last = try XCTUnwrap(obj["last_drift"] as? [String: Any])
         XCTAssertEqual(last["ts"] as? Int, now)

From 4419e3955013b5005a40bc9cd0e98b8405c402ef Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 09:54:01 -0700
Subject: [PATCH 02/49] feat(forecast): disk-full forecaster from free-space
 history (A.3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pure (ts, free-bytes) series → projection. Honest by construction: no date
under a week of history, none when free space is flat or growing, and none
past a 5-year horizon. Robust to single-sample cliffs (a temp file briefly
eating space) via a Theil–Sen median slope rather than least-squares, which
one outlier can drag arbitrarily far.

Tracer-bullet core for roadmap A.3; the MCP tool + Home/History tile wiring
follow as their own slices.
---
 Sources/DiskForecast.swift    | 84 +++++++++++++++++++++++++++++++++++
 Tests/DiskForecastTests.swift | 83 ++++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 Sources/DiskForecast.swift
 create mode 100644 Tests/DiskForecastTests.swift

diff --git a/Sources/DiskForecast.swift b/Sources/DiskForecast.swift
new file mode 100644
index 00000000..f6aea964
--- /dev/null
+++ b/Sources/DiskForecast.swift
@@ -0,0 +1,84 @@
+//
+//  DiskForecast.swift
+//  Burrow
+//
+//  Disk-full forecasting from free-space history (roadmap A.3). Pure: a
+//  series of (timestamp, free-bytes) in, a projection out — so the Home disk
+//  tile and the History disk chart can both say "full in ~3 weeks" from the
+//  same honest estimate.
+//
+//  Honest by construction. It refuses to name a date when the trend is flat,
+//  when free space is *growing*, or when there's less than a week of history,
+//  and it resists single-sample cliffs (a temp file briefly eating space) by
+//  fitting a robust median (Theil–Sen) slope rather than least-squares, which
+//  one outlier can drag arbitrarily far.
+//
+
+import Foundation
+
+enum DiskForecast {
+    struct Projection: Equatable {
+        /// Estimated days until free space reaches zero, or nil when not
+        /// forecastable — the UI shows the basis instead of a bare date.
+        let daysUntilFull: Double?
+        /// Trend in bytes/day (negative = filling up). Always present.
+        let slopeBytesPerDay: Double
+        /// Span of history the fit used, in days — surfaced so the UI can say
+        /// "based on N days" and never present precision it doesn't have.
+        let basisDays: Double
+    }
+
+    /// Below this much history, a date is noise dressed as precision.
+    static let minBasisDays = 7.0
+    /// Forecasts past this horizon mean the slope is effectively flat; we
+    /// suppress the date rather than tell someone their disk fills in 80 years.
+    static let maxHorizonDays = 365.0 * 5
+    /// Pairwise Theil–Sen is O(n²); bound the input so a pathological caller
+    /// can't stall. Snapshots already arrive ≤720, so this rarely bites.
+    static let maxSamples = 1500
+
+    static func forecast(_ samples: [(ts: Int, freeBytes: Double)], now: Int) -> Projection {
+        let sorted = samples.sorted { $0.ts < $1.ts }
+        let pts = sorted.count > maxSamples ? stride(from: 0, to: sorted.count,
+                        by: sorted.count / maxSamples + 1).map { sorted[$0] } : sorted
+        guard pts.count >= 2, let first = pts.first, let last = pts.last,
+              last.ts > first.ts else {
+            return Projection(daysUntilFull: nil, slopeBytesPerDay: 0, basisDays: 0)
+        }
+        let basisDays = Double(last.ts - first.ts) / 86_400.0
+
+        // Theil–Sen slope: median of all pairwise slopes (bytes/day).
+        var slopes: [Double] = []
+        slopes.reserveCapacity(pts.count * (pts.count - 1) / 2)
+        for i in 0..<pts.count {
+            for j in (i + 1)..<pts.count {
+                let dtDays = Double(pts[j].ts - pts[i].ts) / 86_400.0
+                if dtDays > 0 {
+                    slopes.append((pts[j].freeBytes - pts[i].freeBytes) / dtDays)
+                }
+            }
+        }
+        let slope = median(slopes)
+        // Robust "free right now": the Theil–Sen line (median intercept +
+        // slope) evaluated at `now`, so one cliff sample can't move the start.
+        let intercepts = pts.map { $0.freeBytes - slope * (Double($0.ts) / 86_400.0) }
+        let currentFree = slope * (Double(now) / 86_400.0) + median(intercepts)
+
+        guard basisDays >= minBasisDays else {
+            return Projection(daysUntilFull: nil, slopeBytesPerDay: slope, basisDays: basisDays)
+        }
+        guard slope < 0 else {  // flat or growing → it never fills
+            return Projection(daysUntilFull: nil, slopeBytesPerDay: slope, basisDays: basisDays)
+        }
+        let days = max(0, currentFree) / (-slope)
+        return Projection(daysUntilFull: days <= maxHorizonDays ? days : nil,
+                          slopeBytesPerDay: slope, basisDays: basisDays)
+    }
+
+    private static func median(_ xs: [Double]) -> Double {
+        guard !xs.isEmpty else { return 0 }
+        let s = xs.sorted()
+        let n = s.count
+        return n % 2 == 1 ? s[n / 2] : (s[n / 2 - 1] + s[n / 2]) / 2
+    }
+}
diff --git a/Tests/DiskForecastTests.swift b/Tests/DiskForecastTests.swift
new file mode 100644
index 00000000..e3d299fd
--- /dev/null
+++ b/Tests/DiskForecastTests.swift
@@ -0,0 +1,83 @@
+//
+//  DiskForecastTests.swift
+//  BurrowTests
+//
+//  The disk-full forecaster (roadmap A.3): a pure (ts, free-bytes) series →
+//  projection. Tested through `forecast(_:now:)` only, so the regression
+//  method can change without rewriting these.
+//
+
+import XCTest
+@testable import Burrow
+
+final class DiskForecastTests: XCTestCase {
+    private let gb = 1_000_000_000.0
+    private let day = 86_400
+
+    /// `count` daily samples ending at day `count-1`, free starting at
+    /// `startGB` and changing by `perDayGB` each day.
+    private func series(count: Int, startGB: Double, perDayGB: Double)
+        -> [(ts: Int, freeBytes: Double)] {
+        (0..<count).map { d in
+            (ts: d * day, freeBytes: (startGB + perDayGB * Double(d)) * gb)
+        }
+    }
+
+    func testForecast_steadyDecline_projectsDaysToZero() {
+        // 31 daily points, 130 GB losing 1 GB/day → 100 GB left at day 30.
+        let s = series(count: 31, startGB: 130, perDayGB: -1)
+        let p = DiskForecast.forecast(s, now: 30 * day)
+        XCTAssertEqual(p.slopeBytesPerDay, -gb, accuracy: gb * 0.02)
+        XCTAssertEqual(p.basisDays, 30, accuracy: 0.001)
+        XCTAssertNotNil(p.daysUntilFull)
+        XCTAssertEqual(p.daysUntilFull ?? -1, 100, accuracy: 1.0)
+    }
+
+    func testForecast_shortHistory_givesNoDate() {
+        // Declining, but only 2 days of history (< minBasisDays).
+        let s = series(count: 3, startGB: 100, perDayGB: -5)
+        let p = DiskForecast.forecast(s, now: 2 * day)
+        XCTAssertNil(p.daysUntilFull, "under a week of history must not name a date")
+        XCTAssertLessThan(p.slopeBytesPerDay, 0, "but the slope is still reported")
+    }
+
+    func testForecast_flatTrend_givesNoDate() {
+        let s = series(count: 30, startGB: 100, perDayGB: 0)
+        let p = DiskForecast.forecast(s, now: 29 * day)
+        XCTAssertNil(p.daysUntilFull, "a flat disk never fills")
+    }
+
+    func testForecast_growingFree_givesNoDate() {
+        let s = series(count: 30, startGB: 50, perDayGB: +1)
+        let p = DiskForecast.forecast(s, now: 29 * day)
+        XCTAssertNil(p.daysUntilFull, "free space growing → no fill date")
+        XCTAssertGreaterThan(p.slopeBytesPerDay, 0)
+    }
+
+    func testForecast_barelyDeclining_beyondHorizon_givesNoDate() {
+        // 100 GB losing 1 MB/day → ~100,000 days; past the 5-year horizon.
+        var s = series(count: 30, startGB: 100, perDayGB: 0)
+        s = s.enumerated().map { i, p in (ts: p.ts, freeBytes: p.freeBytes - Double(i) * 1_000_000) }
+        let p = DiskForecast.forecast(s, now: 29 * day)
+        XCTAssertNil(p.daysUntilFull, "a forecast past the horizon is suppressed")
+        XCTAssertLessThan(p.slopeBytesPerDay, 0)
+    }
+
+    func testForecast_resistsSingleCliff() {
+        // Steady -1 GB/day for 31 days, but one sample cliffs to ~1 GB free
+        // (a temp file). The robust slope must barely move.
+        var s = series(count: 31, startGB: 130, perDayGB: -1)
+        s[15] = (ts: 15 * day, freeBytes: 1 * gb)
+        let p = DiskForecast.forecast(s, now: 30 * day)
+        XCTAssertNotNil(p.daysUntilFull)
+        XCTAssertEqual(p.daysUntilFull ?? -1, 100, accuracy: 15,
+                       "one cliff sample must not derail the forecast")
+    }
+
+    func testForecast_emptyOrSingleSample_returnsNil() {
+        XCTAssertNil(DiskForecast.forecast([], now: 0).daysUntilFull)
+        XCTAssertEqual(DiskForecast.forecast([], now: 0).basisDays, 0)
+        let one: [(ts: Int, freeBytes: Double)] = [(ts: 0, freeBytes: 50 * gb)]
+        XCTAssertNil(DiskForecast.forecast(one, now: 0).daysUntilFull)
+    }
+}

From 75a3b55ff497709511495b0d400fcf55d9d7b92e Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:00:14 -0700
Subject: [PATCH 03/49] feat(anomaly): baseline-vs-recent regression rules
 (A.2)

Pure stats: percentile/median primitives, a sustained-CPU-exceedance rule
(recent median clears baseline p95 + a minimum effect size so near-idle
noise can't trip it), and battery-drain regression (OLS %/hr per session,
flagged when a recent discharge runs >=factor x the baseline median). The
Maintenance pass writing burrow.findings + the Home card are integration.
---
 Sources/Anomaly.swift    | 77 ++++++++++++++++++++++++++++++++++++++++
 Tests/AnomalyTests.swift | 70 ++++++++++++++++++++++++++++++++++++
 2 files changed, 147 insertions(+)
 create mode 100644 Sources/Anomaly.swift
 create mode 100644 Tests/AnomalyTests.swift

diff --git a/Sources/Anomaly.swift b/Sources/Anomaly.swift
new file mode 100644
index 00000000..c1259556
--- /dev/null
+++ b/Sources/Anomaly.swift
@@ -0,0 +1,77 @@
+//
+//  Anomaly.swift
+//  Burrow
+//
+//  Baseline-vs-recent regression detection (roadmap A.2). Pure statistics:
+//  arrays in, a verdict out — so the "WindowServer baseline doubled" and
+//  "battery drains faster than two weeks ago" findings are computed the same
+//  way wherever they're surfaced (Home card, notifications, the Explain lens,
+//  a future MCP tool), and the credibility tuning lives in one place.
+//
+//  The rules are deliberately conservative: a finding needs a clear effect
+//  size on top of statistical exceedance, because a false "your Mac is
+//  degrading" alert costs more trust than a missed one.
+//
+
+import Foundation
+
+enum Anomaly {
+    // MARK: Statistical primitives
+
+    /// Linear-interpolated percentile (the numpy/"type 7" convention), so
+    /// p95 of a short baseline is stable and well-defined. `p` is 0...100.
+    static func percentile(_ xs: [Double], _ p: Double) -> Double {
+        guard !xs.isEmpty else { return 0 }
+        let s = xs.sorted()
+        if s.count == 1 { return s[0] }
+        let rank = (p / 100.0) * Double(s.count - 1)
+        let lo = Int(rank.rounded(.down))
+        let hi = Int(rank.rounded(.up))
+        let frac = rank - Double(lo)
+        return s[lo] + (s[hi] - s[lo]) * frac
+    }
+
+    static func median(_ xs: [Double]) -> Double { percentile(xs, 50) }
+
+    // MARK: Process CPU regression
+
+    /// True when a process's recent CPU is *sustainedly* above its own
+    /// baseline: the typical recent value clears the baseline's 95th
+    /// percentile AND beats the baseline median by at least `minDelta` points.
+    /// The effect-size floor stops near-idle processes (0.5% → 2%) from
+    /// tripping a "doubled!" alert that's technically true but meaningless.
+    static func processCPUExceedsBaseline(baseline: [Double], recent: [Double],
+                                          minSamples: Int = 5, minDelta: Double = 10) -> Bool {
+        guard baseline.count >= minSamples, recent.count >= minSamples else { return false }
+        let recentMid = median(recent)
+        return recentMid > percentile(baseline, 95)
+            && (recentMid - median(baseline)) >= minDelta
+    }
+
+    // MARK: Battery drain regression
+
+    /// Discharge rate of one session in percent-per-hour (positive = losing
+    /// charge), via least-squares slope over elapsed hours. Robust to a
+    /// noisy reading or two. nil when the session is too short to have a rate.
+    static func batteryDrainRate(_ session: [(ts: Int, percent: Double)]) -> Double? {
+        guard session.count >= 2 else { return nil }
+        let pts = session.map { (h: Double($0.ts) / 3600.0, p: $0.percent) }
+        let n = Double(pts.count)
+        let meanH = pts.reduce(0) { $0 + $1.h } / n
+        let meanP = pts.reduce(0) { $0 + $1.p } / n
+        var num = 0.0, den = 0.0
+        for pt in pts { num += (pt.h - meanH) * (pt.p - meanP); den += (pt.h - meanH) * (pt.h - meanH) }
+        guard den > 0 else { return nil }
+        return -(num / den)  // negate: a falling % is a positive drain rate
+    }
+
+    /// True when the recent discharge drains meaningfully faster than the
+    /// baseline sessions: at least `factor`× the median baseline rate and at
+    /// least `minDelta` %/hr faster in absolute terms.
+    static func batteryDrainRegressed(baselineRates: [Double], recentRate: Double,
+                                      factor: Double = 1.25, minDelta: Double = 1) -> Bool {
+        guard !baselineRates.isEmpty else { return false }
+        let base = median(baselineRates)
+        return base > 0 && recentRate >= base * factor && (recentRate - base) >= minDelta
+    }
+}
diff --git a/Tests/AnomalyTests.swift b/Tests/AnomalyTests.swift
new file mode 100644
index 00000000..81b88299
--- /dev/null
+++ b/Tests/AnomalyTests.swift
@@ -0,0 +1,70 @@
+//
+//  AnomalyTests.swift
+//  BurrowTests
+//
+//  The baseline-vs-recent regression rules (roadmap A.2), tested through
+//  their public verdicts so the thresholds can be tuned without rewriting
+//  the specification of *what* counts as a regression.
+//
+
+import XCTest
+@testable import Burrow
+
+final class AnomalyTests: XCTestCase {
+    // MARK: percentile convention
+
+    func testPercentile_interpolatesBetweenSamples() {
+        let xs = [0.0, 10, 20, 30, 40]
+        XCTAssertEqual(Anomaly.median(xs), 20, accuracy: 0.001)
+        XCTAssertEqual(Anomaly.percentile(xs, 100), 40, accuracy: 0.001)
+        XCTAssertEqual(Anomaly.percentile(xs, 0), 0, accuracy: 0.001)
+    }
+
+    // MARK: process CPU
+
+    func testProcessCPU_stableProcess_notFlagged() {
+        let baseline = Array(repeating: 20.0, count: 20) + [22, 18, 21, 19]
+        let recent = [20.0, 21, 19, 20, 22, 18]
+        XCTAssertFalse(Anomaly.processCPUExceedsBaseline(baseline: baseline, recent: recent))
+    }
+
+    func testProcessCPU_sustainedDoubling_flagged() {
+        let baseline = Array(repeating: 20.0, count: 20)
+        let recent = Array(repeating: 45.0, count: 8)   // clears p95(=20) by 25 pts
+        XCTAssertTrue(Anomaly.processCPUExceedsBaseline(baseline: baseline, recent: recent))
+    }
+
+    func testProcessCPU_tinyAbsoluteChange_notFlagged() {
+        // 0.5% → 3%: exceeds the baseline p95 but the effect size is trivial.
+        let baseline = Array(repeating: 0.5, count: 20)
+        let recent = Array(repeating: 3.0, count: 8)
+        XCTAssertFalse(Anomaly.processCPUExceedsBaseline(baseline: baseline, recent: recent),
+                       "near-idle noise must not trip a regression alert")
+    }
+
+    func testProcessCPU_tooFewSamples_notFlagged() {
+        XCTAssertFalse(Anomaly.processCPUExceedsBaseline(baseline: [20, 20, 20],
+                                                         recent: [90, 90, 90]))
+    }
+
+    // MARK: battery drain
+
+    func testBatteryDrainRate_lostTenPercentOverTwoHours() {
+        let session = [(ts: 0, percent: 100.0), (ts: 3600, percent: 95.0), (ts: 7200, percent: 90.0)]
+        let rate = Anomaly.batteryDrainRate(session)
+        XCTAssertNotNil(rate)
+        XCTAssertEqual(rate ?? 0, 5, accuracy: 0.001)  // 10% over 2h → 5%/hr
+    }
+
+    func testBatteryDrainRate_singlePoint_isNil() {
+        XCTAssertNil(Anomaly.batteryDrainRate([(ts: 0, percent: 100)]))
+    }
+
+    func testBatteryDrainRegressed_fasterThanBaseline_flagged() {
+        XCTAssertTrue(Anomaly.batteryDrainRegressed(baselineRates: [3, 3.5, 4, 3.2], recentRate: 6))
+    }
+
+    func testBatteryDrainRegressed_withinNormalVariation_notFlagged() {
+        XCTAssertFalse(Anomaly.batteryDrainRegressed(baselineRates: [4, 4.2, 3.8, 4.1], recentRate: 4.3))
+    }
+}

From d8fc3e618f3664236a0619a5882f9cd47a1fabc4 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:00:14 -0700
Subject: [PATCH 04/49] feat(diff): set-membership inventory diff (B.8 + D.12)

Shared kernel for burrow_diff(since:) and the new-LaunchAgent watcher:
sorted, de-duplicated added/removed over two identifier lists (apps, login
items, LaunchAgents, ports, top-process membership).
---
 Sources/InventoryDiff.swift    | 32 ++++++++++++++++++++++++++
 Tests/InventoryDiffTests.swift | 41 ++++++++++++++++++++++++++++++++++
 2 files changed, 73 insertions(+)
 create mode 100644 Sources/InventoryDiff.swift
 create mode 100644 Tests/InventoryDiffTests.swift

diff --git a/Sources/InventoryDiff.swift b/Sources/InventoryDiff.swift
new file mode 100644
index 00000000..06749161
--- /dev/null
+++ b/Sources/InventoryDiff.swift
@@ -0,0 +1,32 @@
+//
+//  InventoryDiff.swift
+//  Burrow
+//
+//  Set-membership diffing for periodic inventories (roadmap B.8 + D.12).
+//  Pure: two lists of identifiers in, what was added/removed out. Apps,
+//  login items, LaunchAgents, listening ports, and top-process membership
+//  all diff the same way, so `burrow_diff` ("what changed since <time>") and
+//  the new-LaunchAgent watcher ("a persistence item appeared") share one
+//  audited implementation instead of each hand-rolling set math.
+//
+
+import Foundation
+
+enum InventoryDiff {
+    struct Change: Equatable {
+        let added: [String]
+        let removed: [String]
+        /// Nothing moved — lets callers skip "what changed" sections and
+        /// suppress no-op alerts.
+        var isEmpty: Bool { added.isEmpty && removed.isEmpty }
+    }
+
+    /// Added = present now but not before; removed = the reverse. Both are
+    /// de-duplicated and sorted, so the output is stable regardless of how
+    /// the inventories were ordered (DB row order, enumeration order).
+    static func diff(old: [String], new: [String]) -> Change {
+        let o = Set(old), n = Set(new)
+        return Change(added: n.subtracting(o).sorted(),
+                      removed: o.subtracting(n).sorted())
+    }
+}
diff --git a/Tests/InventoryDiffTests.swift b/Tests/InventoryDiffTests.swift
new file mode 100644
index 00000000..ad43da91
--- /dev/null
+++ b/Tests/InventoryDiffTests.swift
@@ -0,0 +1,41 @@
+//
+//  InventoryDiffTests.swift
+//  BurrowTests
+//
+//  Set-membership diffing (roadmap B.8 / D.12), tested through `diff`.
+//
+
+import XCTest
+@testable import Burrow
+
+final class InventoryDiffTests: XCTestCase {
+    func testDiff_addedAndRemoved() {
+        let c = InventoryDiff.diff(old: ["a", "b", "c"], new: ["b", "c", "d"])
+        XCTAssertEqual(c.added, ["d"])
+        XCTAssertEqual(c.removed, ["a"])
+        XCTAssertFalse(c.isEmpty)
+    }
+
+    func testDiff_outputIsSortedRegardlessOfInputOrder() {
+        let c = InventoryDiff.diff(old: ["x"], new: ["zeta", "alpha", "x", "mu"])
+        XCTAssertEqual(c.added, ["alpha", "mu", "zeta"], "added is sorted, stable")
+        XCTAssertTrue(c.removed.isEmpty)
+    }
+
+    func testDiff_identicalInventories_isEmpty() {
+        let c = InventoryDiff.diff(old: ["a", "b"], new: ["b", "a"])
+        XCTAssertTrue(c.isEmpty, "same membership, different order → no change")
+    }
+
+    func testDiff_deduplicates() {
+        let c = InventoryDiff.diff(old: ["a", "a"], new: ["a", "b", "b"])
+        XCTAssertEqual(c.added, ["b"])
+        XCTAssertTrue(c.removed.isEmpty)
+    }
+
+    func testDiff_emptyOldMeansAllNew() {
+        let c = InventoryDiff.diff(old: [], new: ["a", "b"])
+        XCTAssertEqual(c.added, ["a", "b"])
+        XCTAssertTrue(c.removed.isEmpty)
+    }
+}

From 2d68dfa0161b9f8b0ae29ac94d58dd4161fc7953 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:00:14 -0700
Subject: [PATCH 05/49] feat(purge): git status --porcelain -b parser for purge
 safety (C.11)

Parses dirty/ahead/upstream/detached into a needs-attention verdict so the
purge checklist can badge repos with uncommitted or unpushed work.
Conservative: untracked files count, and a never-pushed branch is unpushed.
Running git (timeout + concurrency cap) and badging the UI are integration.
---
 Sources/GitRepoStatus.swift    | 51 +++++++++++++++++++++++++++++++
 Tests/GitRepoStatusTests.swift | 55 ++++++++++++++++++++++++++++++++++
 2 files changed, 106 insertions(+)
 create mode 100644 Sources/GitRepoStatus.swift
 create mode 100644 Tests/GitRepoStatusTests.swift

diff --git a/Sources/GitRepoStatus.swift b/Sources/GitRepoStatus.swift
new file mode 100644
index 00000000..d1767e2f
--- /dev/null
+++ b/Sources/GitRepoStatus.swift
@@ -0,0 +1,51 @@
+//
+//  GitRepoStatus.swift
+//  Burrow
+//
+//  Purge-safety check for project folders (roadmap C.11): before Burrow
+//  offers to delete a directory, it walks up to the containing repo and asks
+//  "would this lose work?" This is the pure half — parsing
+//  `git status --porcelain=v1 -b` into a verdict. Running `git` (with a short
+//  timeout + concurrency cap) and badging the purge checklist is the
+//  integration half. Conservative on purpose: untracked files count as work,
+//  and a branch that was never pushed is treated as unpushed — the whole
+//  point is to be safer than deleting by hand.
+//
+
+import Foundation
+
+enum GitRepoStatus {
+    struct Status: Equatable {
+        /// Any working-tree change, including untracked files.
+        let dirty: Bool
+        /// Commits ahead of the upstream (0 when synced or no upstream).
+        let ahead: Int
+        let hasUpstream: Bool
+        let detached: Bool
+
+        /// Work that exists only locally: commits ahead of upstream, or a
+        /// real branch with no upstream at all (never pushed anywhere).
+        var unpushed: Bool { ahead > 0 || (!hasUpstream && !detached) }
+        /// The badge condition — purging this would risk losing something.
+        var needsAttention: Bool { dirty || unpushed }
+    }
+
+    static func parse(_ porcelain: String) -> Status {
+        var dirty = false, ahead = 0, hasUpstream = false, detached = false
+        for raw in porcelain.split(separator: "\n", omittingEmptySubsequences: false) {
+            let line = String(raw)
+            if line.hasPrefix("## ") {
+                let branch = String(line.dropFirst(3))
+                detached = branch.hasPrefix("HEAD (no branch)")
+                hasUpstream = branch.contains("...")
+                if let r = branch.range(of: "[ahead "),
+                   let end = branch[r.upperBound...].firstIndex(where: { $0 == "," || $0 == "]" }) {
+                    ahead = Int(branch[r.upperBound..<end]) ?? 0
+                }
+            } else if !line.trimmingCharacters(in: .whitespaces).isEmpty {
+                dirty = true  // any porcelain entry (modified, staged, untracked)
+            }
+        }
+        return Status(dirty: dirty, ahead: ahead, hasUpstream: hasUpstream, detached: detached)
+    }
+}
diff --git a/Tests/GitRepoStatusTests.swift b/Tests/GitRepoStatusTests.swift
new file mode 100644
index 00000000..d8bc98b0
--- /dev/null
+++ b/Tests/GitRepoStatusTests.swift
@@ -0,0 +1,55 @@
+//
+//  GitRepoStatusTests.swift
+//  BurrowTests
+//
+//  The `git status --porcelain -b` parser (roadmap C.11), tested through
+//  `parse` with real porcelain fixtures.
+//
+
+import XCTest
+@testable import Burrow
+
+final class GitRepoStatusTests: XCTestCase {
+    func testParse_cleanSynced_needsNoAttention() {
+        let s = GitRepoStatus.parse("## main...origin/main")
+        XCTAssertFalse(s.dirty)
+        XCTAssertEqual(s.ahead, 0)
+        XCTAssertFalse(s.needsAttention, "clean + synced is safe to purge")
+    }
+
+    func testParse_modifiedFile_isDirty() {
+        let s = GitRepoStatus.parse("## main...origin/main\n M Sources/App.swift")
+        XCTAssertTrue(s.dirty)
+        XCTAssertTrue(s.needsAttention)
+    }
+
+    func testParse_untrackedFile_isDirty() {
+        let s = GitRepoStatus.parse("## main...origin/main\n?? notes.txt")
+        XCTAssertTrue(s.dirty, "untracked files are unsaved work too")
+    }
+
+    func testParse_aheadOfUpstream_isUnpushed() {
+        let s = GitRepoStatus.parse("## main...origin/main [ahead 3]")
+        XCTAssertEqual(s.ahead, 3)
+        XCTAssertTrue(s.unpushed)
+        XCTAssertTrue(s.needsAttention)
+    }
+
+    func testParse_aheadAndBehind_countsAheadOnly() {
+        let s = GitRepoStatus.parse("## main...origin/main [ahead 2, behind 5]")
+        XCTAssertEqual(s.ahead, 2)
+        XCTAssertTrue(s.unpushed)
+    }
+
+    func testParse_branchWithNoUpstream_isUnpushed() {
+        let s = GitRepoStatus.parse("## experiment")
+        XCTAssertFalse(s.hasUpstream)
+        XCTAssertTrue(s.unpushed, "a branch that was never pushed is unpushed work")
+    }
+
+    func testParse_detachedHeadClean_needsNoAttention() {
+        let s = GitRepoStatus.parse("## HEAD (no branch)")
+        XCTAssertTrue(s.detached)
+        XCTAssertFalse(s.needsAttention, "a clean detached checkout isn't a stranded branch")
+    }
+}

From 5088ef6f338f4ea0a40697a7c77879e1f75f42e5 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:00:14 -0700
Subject: [PATCH 06/49] feat(doctor): diagnostics verdict composer (roadmap I)

System facts -> ranked ok/warn/fail checks (engine, Full Disk Access, memory
pressure, disk headroom, recent errors). Level.rawValue orders worst-first.
Gathering the facts + the Help-menu sheet are integration.
---
 Sources/Doctor.swift    | 78 +++++++++++++++++++++++++++++++++++++++++
 Tests/DoctorTests.swift | 67 +++++++++++++++++++++++++++++++++++
 2 files changed, 145 insertions(+)
 create mode 100644 Sources/Doctor.swift
 create mode 100644 Tests/DoctorTests.swift

diff --git a/Sources/Doctor.swift b/Sources/Doctor.swift
new file mode 100644
index 00000000..0cdbe4fa
--- /dev/null
+++ b/Sources/Doctor.swift
@@ -0,0 +1,78 @@
+//
+//  Doctor.swift
+//  Burrow
+//
+//  Diagnostics report (roadmap I / appendix parity gap): a one-glance health
+//  check from the Help menu — permissions, memory pressure, disk headroom,
+//  the engine, recent errors. This is the pure half: system facts in, ranked
+//  verdicts out, so the same logic backs the Help-menu sheet and (later) a
+//  `burrow_doctor` MCP tool. Gathering the facts (TCC state, pressure, log
+//  scan) is the integration half.
+//
+
+import Foundation
+
+enum Doctor {
+    enum Level: Int { case ok, warn, fail }  // Int so callers can sort worst-first
+    enum MemoryPressure { case normal, warning, critical }
+
+    struct Check: Equatable {
+        let name: String
+        let level: Level
+        let detail: String
+    }
+
+    struct Input {
+        var fullDiskAccess: Bool
+        var moInstalled: Bool
+        var pressure: MemoryPressure
+        var diskFreeBytes: Int64
+        var diskTotalBytes: Int64
+        var recentErrorCount: Int
+    }
+
+    /// One `Check` per facet, in a stable order. Each verdict is independent;
+    /// callers can sort by `level` to surface failures first.
+    static func report(_ i: Input) -> [Check] {
+        [engine(i), permissions(i), memory(i), disk(i), errors(i)]
+    }
+
+    private static func engine(_ i: Input) -> Check {
+        i.moInstalled
+            ? Check(name: "Engine", level: .ok, detail: "mo is installed")
+            : Check(name: "Engine", level: .fail, detail: "mo is not installed — core features are unavailable")
+    }
+
+    private static func permissions(_ i: Input) -> Check {
+        i.fullDiskAccess
+            ? Check(name: "Full Disk Access", level: .ok, detail: "granted")
+            : Check(name: "Full Disk Access", level: .warn, detail: "off — some scans and cleanups are limited")
+    }
+
+    private static func memory(_ i: Input) -> Check {
+        switch i.pressure {
+        case .normal:   return Check(name: "Memory pressure", level: .ok, detail: "normal")
+        case .warning:  return Check(name: "Memory pressure", level: .warn, detail: "elevated")
+        case .critical: return Check(name: "Memory pressure", level: .fail, detail: "critical — the system is low on memory")
+        }
+    }
+
+    private static func disk(_ i: Input) -> Check {
+        guard i.diskTotalBytes > 0 else {
+            return Check(name: "Disk space", level: .warn, detail: "unknown")
+        }
+        let freePct = Double(i.diskFreeBytes) / Double(i.diskTotalBytes) * 100
+        if freePct < 5 {
+            return Check(name: "Disk space", level: .fail, detail: "under 5% free")
+        } else if freePct < 10 {
+            return Check(name: "Disk space", level: .warn, detail: "under 10% free")
+        }
+        return Check(name: "Disk space", level: .ok, detail: "\(Int(freePct.rounded()))% free")
+    }
+
+    private static func errors(_ i: Input) -> Check {
+        i.recentErrorCount == 0
+            ? Check(name: "Recent errors", level: .ok, detail: "none logged")
+            : Check(name: "Recent errors", level: .warn, detail: "\(i.recentErrorCount) in recent logs")
+    }
+}
diff --git a/Tests/DoctorTests.swift b/Tests/DoctorTests.swift
new file mode 100644
index 00000000..da02fe41
--- /dev/null
+++ b/Tests/DoctorTests.swift
@@ -0,0 +1,67 @@
+//
+//  DoctorTests.swift
+//  BurrowTests
+//
+//  The diagnostics verdict composer (roadmap I), tested through `report`.
+//
+
+import XCTest
+@testable import Burrow
+
+final class DoctorTests: XCTestCase {
+    private func healthy() -> Doctor.Input {
+        .init(fullDiskAccess: true, moInstalled: true, pressure: .normal,
+              diskFreeBytes: 200_000_000_000, diskTotalBytes: 500_000_000_000,
+              recentErrorCount: 0)
+    }
+
+    private func check(_ report: [Doctor.Check], _ name: String) -> Doctor.Check? {
+        report.first { $0.name == name }
+    }
+
+    func testReport_healthyMachine_allOK() {
+        let r = Doctor.report(healthy())
+        XCTAssertEqual(r.count, 5)
+        XCTAssertTrue(r.allSatisfy { $0.level == .ok })
+    }
+
+    func testReport_noEngine_fails() {
+        var i = healthy(); i.moInstalled = false
+        XCTAssertEqual(check(Doctor.report(i), "Engine")?.level, .fail)
+    }
+
+    func testReport_noFullDiskAccess_warns() {
+        var i = healthy(); i.fullDiskAccess = false
+        XCTAssertEqual(check(Doctor.report(i), "Full Disk Access")?.level, .warn)
+    }
+
+    func testReport_criticalPressure_fails() {
+        var i = healthy(); i.pressure = .critical
+        XCTAssertEqual(check(Doctor.report(i), "Memory pressure")?.level, .fail)
+    }
+
+    func testReport_diskNearlyFull_fails() {
+        var i = healthy()
+        i.diskFreeBytes = 10_000_000_000  // 2% of 500 GB
+        XCTAssertEqual(check(Doctor.report(i), "Disk space")?.level, .fail)
+    }
+
+    func testReport_diskTight_warns() {
+        var i = healthy()
+        i.diskFreeBytes = 40_000_000_000  // 8% of 500 GB
+        XCTAssertEqual(check(Doctor.report(i), "Disk space")?.level, .warn)
+    }
+
+    func testReport_recentErrors_warn() {
+        var i = healthy(); i.recentErrorCount = 3
+        let c = check(Doctor.report(i), "Recent errors")
+        XCTAssertEqual(c?.level, .warn)
+        XCTAssertTrue(c?.detail.contains("3") ?? false)
+    }
+
+    func testReport_sortableWorstFirst() {
+        var i = healthy(); i.moInstalled = false; i.pressure = .critical
+        let worst = Doctor.report(i).max { $0.level.rawValue < $1.level.rawValue }
+        XCTAssertEqual(worst?.level, .fail, "Level.rawValue orders ok<warn<fail for sorting")
+    }
+}

From 61c5c7d104ac0b6d70396d8e186b9a10dcadcf98 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:04:51 -0700
Subject: [PATCH 07/49] feat(alerts): threshold engine with hysteresis +
 cooldown (D.12)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pure value-folding step(): fire on crossing high, re-arm only after recovery
below low, and a cooldown caps fires across episodes — one alert per episode,
not per sample. Shared by notifications (D.12), SSE (B.6), the report (A.4).
Rule thresholds, Sampler wiring, and UNUserNotification delivery are integration.
---
 Sources/AlertEngine.swift    | 53 +++++++++++++++++++++++++++++
 Tests/AlertEngineTests.swift | 64 ++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+)
 create mode 100644 Sources/AlertEngine.swift
 create mode 100644 Tests/AlertEngineTests.swift

diff --git a/Sources/AlertEngine.swift b/Sources/AlertEngine.swift
new file mode 100644
index 00000000..dc253548
--- /dev/null
+++ b/Sources/AlertEngine.swift
@@ -0,0 +1,53 @@
+//
+//  AlertEngine.swift
+//  Burrow
+//
+//  Threshold-alert evaluation (roadmap D.12). Pure and stateful-by-value: a
+//  rule + the latest reading + the prior state → the next state and whether
+//  to fire. Hysteresis (fire on crossing `high`, don't re-arm until the value
+//  recovers below `low`) plus a cooldown mean an alert fires once per
+//  *episode*, not once per sample — the difference between a useful nudge and
+//  alert fatigue. The same evaluator backs notifications (D.12), the SSE
+//  stream (B.6), and the report (A.4); the rules' thresholds, the Sampler
+//  wiring, and UserNotifications delivery are integration.
+//
+
+import Foundation
+
+struct ThresholdRule: Equatable {
+    let id: String
+    /// Fire when the reading reaches `high`…
+    let high: Double
+    /// …and don't re-arm until it falls back below `low` (hysteresis).
+    let low: Double
+    /// Minimum seconds between fires, across episodes.
+    let cooldownSeconds: Int
+}
+
+struct AlertState: Equatable {
+    /// In an active episode: above `high` and not yet recovered below `low`.
+    var firing = false
+    var lastFiredTS: Int?
+}
+
+enum AlertEngine {
+    /// Fold one reading into the alert state. Returns the next state and
+    /// whether this tick should emit an alert.
+    static func step(rule: ThresholdRule, value: Double, ts: Int,
+                     state: AlertState) -> (state: AlertState, fired: Bool) {
+        var s = state
+        if s.firing {
+            // Episode continues until the value recovers below `low`; dips
+            // that stay above `low` do not re-fire.
+            if value < rule.low { s.firing = false }
+            return (s, false)
+        }
+        guard value >= rule.high else { return (s, false) }
+        s.firing = true
+        if let last = s.lastFiredTS, ts - last < rule.cooldownSeconds {
+            return (s, false)  // armed, but still cooling down from the last fire
+        }
+        s.lastFiredTS = ts
+        return (s, true)
+    }
+}
diff --git a/Tests/AlertEngineTests.swift b/Tests/AlertEngineTests.swift
new file mode 100644
index 00000000..d9817c41
--- /dev/null
+++ b/Tests/AlertEngineTests.swift
@@ -0,0 +1,64 @@
+//
+//  AlertEngineTests.swift
+//  BurrowTests
+//
+//  Threshold-alert hysteresis + cooldown (roadmap D.12), tested by folding a
+//  reading sequence through `step` and asserting when it fires.
+//
+
+import XCTest
+@testable import Burrow
+
+final class AlertEngineTests: XCTestCase {
+    private let rule = ThresholdRule(id: "cpu", high: 90, low: 70, cooldownSeconds: 300)
+
+    func testBelowThreshold_neverFires() {
+        let r = AlertEngine.step(rule: rule, value: 50, ts: 0, state: AlertState())
+        XCTAssertFalse(r.fired)
+        XCTAssertFalse(r.state.firing)
+    }
+
+    func testCrossingHigh_firesOnce() {
+        let r = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState())
+        XCTAssertTrue(r.fired)
+        XCTAssertTrue(r.state.firing)
+        XCTAssertEqual(r.state.lastFiredTS, 0)
+    }
+
+    func testStayingHigh_doesNotRefire() {
+        let first = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState())
+        let second = AlertEngine.step(rule: rule, value: 97, ts: 60, state: first.state)
+        XCTAssertFalse(second.fired, "one fire per episode, not per sample")
+        XCTAssertTrue(second.state.firing)
+    }
+
+    func testDipAboveLow_staysInEpisode() {
+        let fire = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState())
+        let dip = AlertEngine.step(rule: rule, value: 80, ts: 60, state: fire.state)  // 70<80<90
+        XCTAssertTrue(dip.state.firing, "still firing until it recovers below low")
+        XCTAssertFalse(dip.fired)
+    }
+
+    func testRecoveryBelowLow_endsEpisode() {
+        let fire = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState())
+        let recover = AlertEngine.step(rule: rule, value: 65, ts: 60, state: fire.state)
+        XCTAssertFalse(recover.state.firing)
+        XCTAssertFalse(recover.fired)
+    }
+
+    func testReCrossWithinCooldown_doesNotFire() {
+        var s = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState()).state
+        s = AlertEngine.step(rule: rule, value: 65, ts: 100, state: s).state   // recovered
+        let again = AlertEngine.step(rule: rule, value: 95, ts: 200, state: s)  // 200-0 < 300
+        XCTAssertFalse(again.fired, "still cooling down from the last fire")
+        XCTAssertTrue(again.state.firing, "but the episode is armed")
+    }
+
+    func testReCrossAfterCooldown_firesAgain() {
+        var s = AlertEngine.step(rule: rule, value: 95, ts: 0, state: AlertState()).state
+        s = AlertEngine.step(rule: rule, value: 65, ts: 100, state: s).state
+        let again = AlertEngine.step(rule: rule, value: 95, ts: 400, state: s)  // 400-0 >= 300
+        XCTAssertTrue(again.fired, "new episode past the cooldown fires")
+        XCTAssertEqual(again.state.lastFiredTS, 400)
+    }
+}

From 2ca9f539fe8622b849536c6657664e913712281d Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:04:51 -0700
Subject: [PATCH 08/49] feat(report): weekly digest markdown composer (A.4)

Pure facts -> markdown (cleanup freed, disk forecast phrased in weeks, top
energy, battery delta, new-startup-items security note). Same artifact for
the Home card and a burrow_report tool. Reuses Fmt.bytes; only names a fill
date when DiskForecast was willing to. DB gathering is integration.
---
 Sources/WeeklyReport.swift    | 67 ++++++++++++++++++++++++++++++++
 Tests/WeeklyReportTests.swift | 73 +++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+)
 create mode 100644 Sources/WeeklyReport.swift
 create mode 100644 Tests/WeeklyReportTests.swift

diff --git a/Sources/WeeklyReport.swift b/Sources/WeeklyReport.swift
new file mode 100644
index 00000000..5a8d565b
--- /dev/null
+++ b/Sources/WeeklyReport.swift
@@ -0,0 +1,67 @@
+//
+//  WeeklyReport.swift
+//  Burrow
+//
+//  The weekly system digest (roadmap A.4): a pure composer over facts already
+//  on disk (history deltas, space reclaimed, top energy, new login items,
+//  battery delta, the disk forecast). Markdown out — the same artifact the
+//  Home "Report" card renders and the future burrow_report MCP tool returns,
+//  so the two can't drift. Gathering the Input from the DB is integration.
+//
+
+import Foundation
+
+enum WeeklyReport {
+    struct Input {
+        var periodDays: Int
+        var spaceReclaimedBytes: Int64
+        var topEnergy: [(name: String, cpuSeconds: Double)]
+        var newLoginItems: [String]
+        /// Negative = health declined since the period start; nil = unknown.
+        var batteryHealthDeltaPct: Double?
+        var forecast: DiskForecast.Projection?
+    }
+
+    static func markdown(_ i: Input) -> String {
+        var out = "# Burrow weekly report\n\n_Last \(i.periodDays) days._\n\n"
+
+        out += "## Cleanup\n"
+        out += i.spaceReclaimedBytes > 0
+            ? "- Freed **\(Fmt.bytes(i.spaceReclaimedBytes))** this period.\n\n"
+            : "- No space reclaimed this period.\n\n"
+
+        // Only name a fill date when the forecaster was willing to — never a
+        // bare date (see DiskForecast).
+        if let f = i.forecast, let days = f.daysUntilFull {
+            out += "## Disk\n- At the current rate, the disk fills in **~\(phrase(days))** "
+                + "(based on \(Int(f.basisDays.rounded())) days).\n\n"
+        }
+
+        if !i.topEnergy.isEmpty {
+            out += "## Top energy users\n"
+            for e in i.topEnergy.prefix(5) {
+                out += "- \(e.name) — \(Int(e.cpuSeconds.rounded())) CPU-seconds\n"
+            }
+            out += "\n"
+        }
+
+        if let d = i.batteryHealthDeltaPct, d < 0 {
+            out += "## Battery\n- Health down **\(String(format: "%.1f", -d))%** since the period start.\n\n"
+        }
+
+        // Persistence items that appeared this period — a light security note.
+        if !i.newLoginItems.isEmpty {
+            out += "## New startup items\nThese now launch automatically and appeared this period:\n"
+            for item in i.newLoginItems { out += "- `\(item)`\n" }
+            out += "\n"
+        }
+        return out
+    }
+
+    /// Days → the roundest honest phrase ("3 weeks", not "21 days").
+    private static func phrase(_ days: Double) -> String {
+        if days < 14 { return "\(Int(days.rounded())) days" }
+        if days < 60 { return "\(Int((days / 7).rounded())) weeks" }
+        return "\(Int((days / 30).rounded())) months"
+    }
+}
diff --git a/Tests/WeeklyReportTests.swift b/Tests/WeeklyReportTests.swift
new file mode 100644
index 00000000..3f758cad
--- /dev/null
+++ b/Tests/WeeklyReportTests.swift
@@ -0,0 +1,73 @@
+//
+//  WeeklyReportTests.swift
+//  BurrowTests
+//
+//  The weekly digest composer (roadmap A.4), tested through the markdown it
+//  produces: which sections appear, and the load-bearing numbers.
+//
+
+import XCTest
+@testable import Burrow
+
+final class WeeklyReportTests: XCTestCase {
+    private func base() -> WeeklyReport.Input {
+        .init(periodDays: 7, spaceReclaimedBytes: 0, topEnergy: [],
+              newLoginItems: [], batteryHealthDeltaPct: nil, forecast: nil)
+    }
+
+    func testMarkdown_alwaysHasTitleAndPeriod() {
+        let md = WeeklyReport.markdown(base())
+        XCTAssertTrue(md.contains("# Burrow weekly report"))
+        XCTAssertTrue(md.contains("Last 7 days"))
+    }
+
+    func testMarkdown_spaceReclaimed_rendersHumanSize() {
+        var i = base(); i.spaceReclaimedBytes = 3_221_225_472  // 3 GB
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("Freed"))
+        XCTAssertTrue(md.contains(Fmt.bytes(3_221_225_472)), "uses the house byte formatter")
+    }
+
+    func testMarkdown_noReclaim_saysSo() {
+        XCTAssertTrue(WeeklyReport.markdown(base()).contains("No space reclaimed"))
+    }
+
+    func testMarkdown_forecastPresent_namesAWeeksPhrase() {
+        var i = base()
+        i.forecast = .init(daysUntilFull: 21, slopeBytesPerDay: -1, basisDays: 30)
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("fills in"))
+        XCTAssertTrue(md.contains("3 weeks"), "21 days renders as ~3 weeks")
+        XCTAssertTrue(md.contains("based on 30 days"))
+    }
+
+    func testMarkdown_noForecast_omitsDiskSection() {
+        XCTAssertFalse(WeeklyReport.markdown(base()).contains("## Disk"),
+                       "no bare date when the forecaster declined")
+    }
+
+    func testMarkdown_topEnergy_listsNames() {
+        var i = base(); i.topEnergy = [("Xcode", 5000), ("Chrome", 3000)]
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("Xcode"))
+        XCTAssertTrue(md.contains("Chrome"))
+    }
+
+    func testMarkdown_newLoginItems_securitySection() {
+        var i = base(); i.newLoginItems = ["com.sketchy.helper"]
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("New startup items"))
+        XCTAssertTrue(md.contains("com.sketchy.helper"))
+    }
+
+    func testMarkdown_noLoginItems_omitsSection() {
+        XCTAssertFalse(WeeklyReport.markdown(base()).contains("New startup items"))
+    }
+
+    func testMarkdown_batteryDecline_shown_butImprovementHidden() {
+        var i = base(); i.batteryHealthDeltaPct = -2.5
+        XCTAssertTrue(WeeklyReport.markdown(i).contains("Health down"))
+        i.batteryHealthDeltaPct = +1.0
+        XCTAssertFalse(WeeklyReport.markdown(i).contains("Health down"))
+    }
+}

From be62c419ebb3906b7926960aa099dbb420777089 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:04:51 -0700
Subject: [PATCH 09/49] feat(backup): tmutil output parsing for backup
 awareness (D.14)

Pure: latest-backup + local-snapshot date tokens from tmutil, token->UTC
Date. Backs 'Last backup: N days ago' in Clean/Purge sheets + the purgeable
note. SMART/IOKit disk-health half of D.14 lands separately; tmutil
invocation is integration.
---
 Sources/TimeMachine.swift    | 44 ++++++++++++++++++++++++++++++++++
 Tests/TimeMachineTests.swift | 46 ++++++++++++++++++++++++++++++++++++
 2 files changed, 90 insertions(+)
 create mode 100644 Sources/TimeMachine.swift
 create mode 100644 Tests/TimeMachineTests.swift

diff --git a/Sources/TimeMachine.swift b/Sources/TimeMachine.swift
new file mode 100644
index 00000000..67f69167
--- /dev/null
+++ b/Sources/TimeMachine.swift
@@ -0,0 +1,44 @@
+//
+//  TimeMachine.swift
+//  Burrow
+//
+//  Backup awareness (roadmap D.14). Pure parsing of `tmutil` output so the
+//  Clean/Purge confirm sheets can show "Last backup: 26 days ago" and the
+//  Analyze sidebar can note purgeable local snapshots. Running tmutil and
+//  rendering the pre-flight line are integration; the SMART/disk-health half
+//  of D.14 is native IOKit and lands separately.
+//
+
+import Foundation
+
+enum TimeMachine {
+    // Time Machine stamps every backup/snapshot with a yyyy-MM-dd-HHmmss token.
+    private static let tokenRE = try! NSRegularExpression(pattern: "\\d{4}-\\d{2}-\\d{2}-\\d{6}")
+
+    private static func tokens(in s: String) -> [String] {
+        let ns = s as NSString
+        return tokenRE.matches(in: s, range: NSRange(location: 0, length: ns.length))
+            .map { ns.substring(with: $0.range) }
+    }
+
+    /// The newest date token in `tmutil latestbackup` output, or nil when
+    /// there's no backup (empty output / no match).
+    static func latestBackupToken(_ output: String) -> String? { tokens(in: output).last }
+
+    /// Date tokens from `tmutil listlocalsnapshots /` — one per local APFS
+    /// snapshot (the "where did my space go" purgeable answer).
+    static func localSnapshotTokens(_ output: String) -> [String] {
+        output.split(separator: "\n")
+            .filter { $0.contains("com.apple.TimeMachine") }
+            .flatMap { tokens(in: String($0)) }
+    }
+
+    /// Parse a backup token to a UTC Date, or nil if malformed.
+    static func date(fromToken token: String) -> Date? {
+        let f = DateFormatter()
+        f.dateFormat = "yyyy-MM-dd-HHmmss"
+        f.timeZone = TimeZone(identifier: "UTC")
+        f.locale = Locale(identifier: "en_US_POSIX")
+        return f.date(from: token)
+    }
+}
diff --git a/Tests/TimeMachineTests.swift b/Tests/TimeMachineTests.swift
new file mode 100644
index 00000000..b107313d
--- /dev/null
+++ b/Tests/TimeMachineTests.swift
@@ -0,0 +1,46 @@
+//
+//  TimeMachineTests.swift
+//  BurrowTests
+//
+//  tmutil output parsing (roadmap D.14), tested with real tmutil fixtures.
+//
+
+import XCTest
+@testable import Burrow
+
+final class TimeMachineTests: XCTestCase {
+    func testLatestBackup_extractsToken() {
+        let out = "/Volumes/.timemachine/Mac/2026-06-15-143000.backup\n"
+        XCTAssertEqual(TimeMachine.latestBackupToken(out), "2026-06-15-143000")
+    }
+
+    func testLatestBackup_noBackup_isNil() {
+        XCTAssertNil(TimeMachine.latestBackupToken(""))
+        XCTAssertNil(TimeMachine.latestBackupToken("No backups found.\n"))
+    }
+
+    func testLocalSnapshots_listsAllTokens() {
+        let out = """
+        Snapshots for volume group containing disk /:
+        com.apple.TimeMachine.2026-06-14-010000.local
+        com.apple.TimeMachine.2026-06-15-020000.local
+        """
+        XCTAssertEqual(TimeMachine.localSnapshotTokens(out),
+                       ["2026-06-14-010000", "2026-06-15-020000"])
+    }
+
+    func testDateFromToken_parsesUTC() throws {
+        let d = try XCTUnwrap(TimeMachine.date(fromToken: "2026-06-15-143000"))
+        var cal = Calendar(identifier: .gregorian)
+        cal.timeZone = TimeZone(identifier: "UTC")!
+        let c = cal.dateComponents([.year, .month, .day, .hour], from: d)
+        XCTAssertEqual(c.year, 2026)
+        XCTAssertEqual(c.month, 6)
+        XCTAssertEqual(c.day, 15)
+        XCTAssertEqual(c.hour, 14)
+    }
+
+    func testDateFromToken_malformed_isNil() {
+        XCTAssertNil(TimeMachine.date(fromToken: "not-a-date"))
+    }
+}

From 37deee03f120e191257f37521b588bf73213ffed Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:04:51 -0700
Subject: [PATCH 10/49] feat(restore): restore-last-cleanup planning (D.13)

Pure: recorded removals + a filesystem probe -> per-item restorable verdict.
Only Trash-based removals are recoverable; a re-created origin is a collision,
not an overwrite. Finder put-back + UI are integration.
---
 Sources/RestorePlan.swift    | 47 ++++++++++++++++++++++++++++++++++++
 Tests/RestorePlanTests.swift | 42 ++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 Sources/RestorePlan.swift
 create mode 100644 Tests/RestorePlanTests.swift

diff --git a/Sources/RestorePlan.swift b/Sources/RestorePlan.swift
new file mode 100644
index 00000000..13ceeda1
--- /dev/null
+++ b/Sources/RestorePlan.swift
@@ -0,0 +1,47 @@
+//
+//  RestorePlan.swift
+//  Burrow
+//
+//  "Restore last cleanup" planning (roadmap D.13). Pure: the items a cleanup
+//  session moved + a probe for what's currently at each origin → a per-item
+//  verdict on what can actually be put back. Honest by construction: only
+//  Trash-based removals are recoverable (Clean's cache deletions are
+//  permanent by design), and an origin that's been re-created is a collision,
+//  not a silent overwrite. Doing the Finder "put back" / move is integration.
+//
+
+import Foundation
+
+enum RestorePlan {
+    /// One recorded removal from `mo history --json`.
+    struct Item: Equatable {
+        let originalPath: String
+        /// Mole's action: "trash" (recoverable) or "remove" (permanent).
+        let action: String
+    }
+
+    struct Entry: Equatable {
+        let path: String
+        let restorable: Bool
+        let reason: String
+    }
+
+    /// Build the plan. `existsAtOriginal` probes the live filesystem (injected
+    /// so the decision logic stays pure and testable).
+    static func build(_ items: [Item], existsAtOriginal: (String) -> Bool) -> [Entry] {
+        items.map { item in
+            guard item.action == "trash" else {
+                return Entry(path: item.originalPath, restorable: false,
+                             reason: "permanently removed — not recoverable")
+            }
+            if existsAtOriginal(item.originalPath) {
+                return Entry(path: item.originalPath, restorable: false,
+                             reason: "a file already exists at the original path")
+            }
+            return Entry(path: item.originalPath, restorable: true, reason: "recoverable from Trash")
+        }
+    }
+
+    /// Convenience: how many of a plan can actually be restored.
+    static func restorableCount(_ plan: [Entry]) -> Int { plan.filter(\.restorable).count }
+}
diff --git a/Tests/RestorePlanTests.swift b/Tests/RestorePlanTests.swift
new file mode 100644
index 00000000..7b26cd67
--- /dev/null
+++ b/Tests/RestorePlanTests.swift
@@ -0,0 +1,42 @@
+//
+//  RestorePlanTests.swift
+//  BurrowTests
+//
+//  Restore planning (roadmap D.13), tested through `build` with an injected
+//  filesystem probe.
+//
+
+import XCTest
+@testable import Burrow
+
+final class RestorePlanTests: XCTestCase {
+    func testTrashedItem_noCollision_isRestorable() {
+        let plan = RestorePlan.build([.init(originalPath: "/Users/x/App.app", action: "trash")],
+                                     existsAtOriginal: { _ in false })
+        XCTAssertEqual(plan.first?.restorable, true)
+        XCTAssertEqual(RestorePlan.restorableCount(plan), 1)
+    }
+
+    func testPermanentlyRemovedItem_notRestorable() {
+        let plan = RestorePlan.build([.init(originalPath: "/Users/x/cache", action: "remove")],
+                                     existsAtOriginal: { _ in false })
+        XCTAssertEqual(plan.first?.restorable, false)
+        XCTAssertTrue(plan.first?.reason.contains("permanently") ?? false)
+    }
+
+    func testTrashedItem_originalPathTaken_isCollision() {
+        let plan = RestorePlan.build([.init(originalPath: "/Users/x/App.app", action: "trash")],
+                                     existsAtOriginal: { $0 == "/Users/x/App.app" })
+        XCTAssertEqual(plan.first?.restorable, false)
+        XCTAssertTrue(plan.first?.reason.contains("already exists") ?? false)
+    }
+
+    func testMixedSession_countsOnlyRestorable() {
+        let plan = RestorePlan.build([
+            .init(originalPath: "/a", action: "trash"),   // restorable
+            .init(originalPath: "/b", action: "remove"),  // permanent
+            .init(originalPath: "/c", action: "trash"),   // collision
+        ], existsAtOriginal: { $0 == "/c" })
+        XCTAssertEqual(RestorePlan.restorableCount(plan), 1)
+    }
+}

From c8a5765a0de96087562e31cd1b8da22806e7e1b8 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:08:41 -0700
Subject: [PATCH 11/49] feat(audit): agent-action audit record + encoding (B.5)

---
 Sources/AgentAudit.swift    | 43 +++++++++++++++++++++++++++++++++++++
 Tests/AgentAuditTests.swift | 36 +++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)
 create mode 100644 Sources/AgentAudit.swift
 create mode 100644 Tests/AgentAuditTests.swift

diff --git a/Sources/AgentAudit.swift b/Sources/AgentAudit.swift
new file mode 100644
index 00000000..0a46ece0
--- /dev/null
+++ b/Sources/AgentAudit.swift
@@ -0,0 +1,43 @@
+//
+//  AgentAudit.swift
+//  Burrow
+//
+//  Agent-action audit records (roadmap B.5): the trust feature that makes
+//  "let agents act" adoptable — every MCP tool dispatch leaves a row humans
+//  can read. This is the record shape + its stable JSON encoding (one DB row
+//  under `prefix`). Writing rows from the MCP process through a serialized
+//  writer, and the Activity-view pane, are integration.
+//
+//  Args are NOT redacted — they're local, and the whole point is to show
+//  exactly what an agent asked for.
+//
+
+import Foundation
+
+enum AgentAudit {
+    static let prefix = "burrow.agent_audit"
+
+    struct Entry: Codable, Equatable {
+        var tool: String
+        var client: String
+        var dryRun: Bool
+        var durationMs: Int
+        var ok: Bool
+        var summary: String
+        /// The tool's arguments, pre-serialized to a JSON string by the caller.
+        var argsJSON: String
+    }
+
+    /// Canonical, key-sorted JSON for one row — deterministic so tests and
+    /// the GUI read the same bytes the MCP process wrote.
+    static func encode(_ e: Entry) -> String {
+        let enc = JSONEncoder()
+        enc.outputFormatting = [.sortedKeys]
+        guard let d = try? enc.encode(e), let s = String(data: d, encoding: .utf8) else { return "{}" }
+        return s
+    }
+
+    static func decode(_ json: String) -> Entry? {
+        try? JSONDecoder().decode(Entry.self, from: Data(json.utf8))
+    }
+}
diff --git a/Tests/AgentAuditTests.swift b/Tests/AgentAuditTests.swift
new file mode 100644
index 00000000..e818c2e2
--- /dev/null
+++ b/Tests/AgentAuditTests.swift
@@ -0,0 +1,36 @@
+//
+//  AgentAuditTests.swift
+//  BurrowTests
+//
+//  Agent-audit record encoding (roadmap B.5), tested through encode/decode.
+//
+
+import XCTest
+@testable import Burrow
+
+final class AgentAuditTests: XCTestCase {
+    private let entry = AgentAudit.Entry(
+        tool: "burrow_clean", client: "claude-code", dryRun: true,
+        durationMs: 42, ok: true, summary: "would free 1.2 GB",
+        argsJSON: "{\"confirm\":false}")
+
+    func testEncodeDecode_roundTrips() {
+        let json = AgentAudit.encode(entry)
+        XCTAssertEqual(AgentAudit.decode(json), entry)
+    }
+
+    func testEncode_isKeySortedAndCarriesFields() {
+        let json = AgentAudit.encode(entry)
+        XCTAssertTrue(json.contains("\"tool\":\"burrow_clean\""))
+        XCTAssertTrue(json.contains("\"client\":\"claude-code\""))
+        XCTAssertTrue(json.contains("\"dryRun\":true"))
+        // sortedKeys → "client" precedes "tool"
+        let ci = json.range(of: "\"client\"")!.lowerBound
+        let ti = json.range(of: "\"tool\"")!.lowerBound
+        XCTAssertLessThan(ci, ti, "keys are sorted for deterministic rows")
+    }
+
+    func testDecode_garbage_isNil() {
+        XCTAssertNil(AgentAudit.decode("not json"))
+    }
+}

From a62356de5696553a01b148f75a7f876120b025bc Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:08:41 -0700
Subject: [PATCH 12/49] feat(ports): listening-port model + kill-safety rule
 (C.10)

---
 Sources/PortInspector.swift    | 35 ++++++++++++++++++++++++++++++++++
 Tests/PortInspectorTests.swift | 30 +++++++++++++++++++++++++++++
 2 files changed, 65 insertions(+)
 create mode 100644 Sources/PortInspector.swift
 create mode 100644 Tests/PortInspectorTests.swift

diff --git a/Sources/PortInspector.swift b/Sources/PortInspector.swift
new file mode 100644
index 00000000..90174a00
--- /dev/null
+++ b/Sources/PortInspector.swift
@@ -0,0 +1,35 @@
+//
+//  PortInspector.swift
+//  Burrow
+//
+//  Listening-port inspector (roadmap C.10): the GUI of `lsof -i` + `kill`.
+//  Native enumeration (proc_listpids + proc_pidfdinfo socket info) and the
+//  confirm-gated SIGTERM/SIGKILL are integration; this is the model plus the
+//  safety rule that keeps Burrow from offering to kill system daemons.
+//
+
+import Foundation
+
+struct ListeningPort: Equatable {
+    let pid: Int
+    let process: String
+    let port: Int
+    let proto: String   // "tcp" | "udp"
+    let address: String
+    let uid: Int
+}
+
+enum PortInspector {
+    /// We only offer to kill a process the user actually owns. Root-owned
+    /// (uid 0) and other users' processes are shown read-only — killing a
+    /// system daemon by accident is exactly the footgun to avoid.
+    static func isKillable(_ p: ListeningPort, currentUID: Int) -> Bool {
+        p.uid != 0 && p.uid == currentUID
+    }
+
+    /// Stable display order: by port, then process name — so the table
+    /// doesn't reshuffle every 5-second refresh.
+    static func sorted(_ ports: [ListeningPort]) -> [ListeningPort] {
+        ports.sorted { ($0.port, $0.process) < ($1.port, $1.process) }
+    }
+}
diff --git a/Tests/PortInspectorTests.swift b/Tests/PortInspectorTests.swift
new file mode 100644
index 00000000..d433337c
--- /dev/null
+++ b/Tests/PortInspectorTests.swift
@@ -0,0 +1,30 @@
+//
+//  PortInspectorTests.swift
+//  BurrowTests
+//
+//  Port-inspector safety + ordering (roadmap C.10).
+//
+
+import XCTest
+@testable import Burrow
+
+final class PortInspectorTests: XCTestCase {
+    private func port(_ p: Int, _ name: String, uid: Int) -> ListeningPort {
+        ListeningPort(pid: 1, process: name, port: p, proto: "tcp", address: "127.0.0.1", uid: uid)
+    }
+
+    func testKillable_onlyOwnNonRootProcesses() {
+        XCTAssertTrue(PortInspector.isKillable(port(3000, "node", uid: 501), currentUID: 501))
+        XCTAssertFalse(PortInspector.isKillable(port(22, "sshd", uid: 0), currentUID: 501),
+                       "never offer to kill a root-owned daemon")
+        XCTAssertFalse(PortInspector.isKillable(port(8080, "other", uid: 502), currentUID: 501),
+                       "not another user's process")
+    }
+
+    func testSorted_byPortThenName_isStable() {
+        let unsorted = [port(8080, "b", uid: 1), port(3000, "z", uid: 1), port(3000, "a", uid: 1)]
+        let s = PortInspector.sorted(unsorted)
+        XCTAssertEqual(s.map(\.port), [3000, 3000, 8080])
+        XCTAssertEqual(s.map(\.process), ["a", "z", "b"])
+    }
+}

From 592b457147186cce0053d50740ca2521811eac9a Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:08:41 -0700
Subject: [PATCH 13/49] feat(tuneup): safe-set selection for one-click Tune-Up
 (#77)

---
 Sources/TuneUp.swift    | 41 +++++++++++++++++++++++++++++++++++++++++
 Tests/TuneUpTests.swift | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 Sources/TuneUp.swift
 create mode 100644 Tests/TuneUpTests.swift

diff --git a/Sources/TuneUp.swift b/Sources/TuneUp.swift
new file mode 100644
index 00000000..dcc1008a
--- /dev/null
+++ b/Sources/TuneUp.swift
@@ -0,0 +1,41 @@
+//
+//  TuneUp.swift
+//  Burrow
+//
+//  Tune-Up redesign (roadmap F / #77): a persistent pane that auto-flags work
+//  (apps to update/uninstall, brew cleanup, startup items, big disks), runs
+//  the *safe* set, and leaves the rest for review. This is the selection
+//  logic — which recommendations are auto-runnable vs review-only, and the
+//  reclaimable total. Generating recommendations (querying updates/unused
+//  apps/startup/disk) and the persistent pane are integration.
+//
+
+import Foundation
+
+enum TuneUp {
+    enum Kind: String, Equatable {
+        case brewCleanup, freeCache, updateApp        // safe to auto-run
+        case uninstallUnused, disableStartupItem       // destructive — review only
+    }
+
+    struct Recommendation: Equatable {
+        let kind: Kind
+        let title: String
+        let bytes: Int64
+        /// Auto-runnable without per-item confirmation. Reversible /
+        /// non-destructive actions only; anything that removes an app or
+        /// changes what launches at login is review-only by design.
+        var safe: Bool {
+            switch kind {
+            case .brewCleanup, .freeCache, .updateApp: return true
+            case .uninstallUnused, .disableStartupItem: return false
+            }
+        }
+    }
+
+    /// The set Tune-Up may run in one click.
+    static func safeSet(_ recs: [Recommendation]) -> [Recommendation] { recs.filter(\.safe) }
+    /// What needs the user's eyes first.
+    static func reviewSet(_ recs: [Recommendation]) -> [Recommendation] { recs.filter { !$0.safe } }
+    static func reclaimable(_ recs: [Recommendation]) -> Int64 { recs.reduce(0) { $0 + $1.bytes } }
+}
diff --git a/Tests/TuneUpTests.swift b/Tests/TuneUpTests.swift
new file mode 100644
index 00000000..3cbaa1f5
--- /dev/null
+++ b/Tests/TuneUpTests.swift
@@ -0,0 +1,33 @@
+//
+//  TuneUpTests.swift
+//  BurrowTests
+//
+//  Tune-Up safe-set selection (roadmap F / #77).
+//
+
+import XCTest
+@testable import Burrow
+
+final class TuneUpTests: XCTestCase {
+    private let recs: [TuneUp.Recommendation] = [
+        .init(kind: .brewCleanup, title: "brew cleanup", bytes: 500_000_000),
+        .init(kind: .freeCache, title: "clear caches", bytes: 1_000_000_000),
+        .init(kind: .uninstallUnused, title: "remove OldApp", bytes: 2_000_000_000),
+        .init(kind: .disableStartupItem, title: "disable Updater", bytes: 0),
+    ]
+
+    func testSafeSet_excludesDestructiveActions() {
+        let safe = TuneUp.safeSet(recs).map(\.kind)
+        XCTAssertEqual(Set(safe), [.brewCleanup, .freeCache])
+        XCTAssertFalse(safe.contains(.uninstallUnused), "uninstall is review-only")
+        XCTAssertFalse(safe.contains(.disableStartupItem), "startup changes are review-only")
+    }
+
+    func testReviewSet_isTheDestructiveRemainder() {
+        XCTAssertEqual(Set(TuneUp.reviewSet(recs).map(\.kind)), [.uninstallUnused, .disableStartupItem])
+    }
+
+    func testReclaimable_sumsAllBytes() {
+        XCTAssertEqual(TuneUp.reclaimable(recs), 3_500_000_000)
+    }
+}

From 87c7306dbdabb06f92dc4e58736f501e49f3b073 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:08:41 -0700
Subject: [PATCH 14/49] feat(updates): brew-upgrade progress line parser (H)

---
 Sources/BrewProgress.swift    | 23 +++++++++++++++++++++++
 Tests/BrewProgressTests.swift | 28 ++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 Sources/BrewProgress.swift
 create mode 100644 Tests/BrewProgressTests.swift

diff --git a/Sources/BrewProgress.swift b/Sources/BrewProgress.swift
new file mode 100644
index 00000000..fd162c3e
--- /dev/null
+++ b/Sources/BrewProgress.swift
@@ -0,0 +1,23 @@
+//
+//  BrewProgress.swift
+//  Burrow
+//
+//  Brew-upgrade progress parsing (roadmap H deferral). Pure: a line of
+//  `brew upgrade` output → a human progress phrase, or nil for noise — so the
+//  Updates flow can show live progress ("Pouring foo…") instead of a blocking
+//  spinner. Wiring this into the streaming upgrade run is integration.
+//
+
+import Foundation
+
+enum BrewProgress {
+    /// Brew prints its step headers as `==> <phrase>`. Those are exactly the
+    /// progress beats worth surfacing; everything else (download bars, blank
+    /// lines, bottle hashes) is noise.
+    static func phrase(_ line: String) -> String? {
+        let t = line.trimmingCharacters(in: .whitespaces)
+        guard t.hasPrefix("==> ") else { return nil }
+        let phrase = String(t.dropFirst(4)).trimmingCharacters(in: .whitespaces)
+        return phrase.isEmpty ? nil : phrase
+    }
+}
diff --git a/Tests/BrewProgressTests.swift b/Tests/BrewProgressTests.swift
new file mode 100644
index 00000000..4d6c3f60
--- /dev/null
+++ b/Tests/BrewProgressTests.swift
@@ -0,0 +1,28 @@
+//
+//  BrewProgressTests.swift
+//  BurrowTests
+//
+//  Brew-upgrade progress parsing (roadmap H).
+//
+
+import XCTest
+@testable import Burrow
+
+final class BrewProgressTests: XCTestCase {
+    func testHeaderLines_becomePhrases() {
+        XCTAssertEqual(BrewProgress.phrase("==> Pouring foo--1.1.bottle.tar.gz"),
+                       "Pouring foo--1.1.bottle.tar.gz")
+        XCTAssertEqual(BrewProgress.phrase("==> Downloading https://example.com/foo"),
+                       "Downloading https://example.com/foo")
+    }
+
+    func testNonHeaderLines_areNoise() {
+        XCTAssertNil(BrewProgress.phrase("Already up-to-date."))
+        XCTAssertNil(BrewProgress.phrase(""))
+        XCTAssertNil(BrewProgress.phrase("  some progress bar  "))
+    }
+
+    func testEmptyHeader_isNil() {
+        XCTAssertNil(BrewProgress.phrase("==>   "))
+    }
+}

From 94885366a26be3d10f2cbaad000e680274d15c1b Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:08:41 -0700
Subject: [PATCH 15/49] feat(hygiene): dev-ecosystem cache catalog (C.9)

---
 Sources/DevHygiene.swift    | 45 +++++++++++++++++++++++++++++++++++++
 Tests/DevHygieneTests.swift | 29 ++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 Sources/DevHygiene.swift
 create mode 100644 Tests/DevHygieneTests.swift

diff --git a/Sources/DevHygiene.swift b/Sources/DevHygiene.swift
new file mode 100644
index 00000000..35d80539
--- /dev/null
+++ b/Sources/DevHygiene.swift
@@ -0,0 +1,45 @@
+//
+//  DevHygiene.swift
+//  Burrow
+//
+//  Dev hygiene page (roadmap C.9): break out what generic cleaners lump
+//  together — Xcode, containers, package-manager caches, toolchains — each
+//  with size and a per-item action. This is the catalog (which ecosystem owns
+//  which paths) plus aggregation. The on-disk size scan, the "hide what isn't
+//  installed" existence check, and the confirm-gated actions are integration.
+//
+
+import Foundation
+
+enum DevHygiene {
+    struct Ecosystem: Equatable {
+        let name: String
+        /// Absolute paths this ecosystem's reclaimable data lives in.
+        let paths: [String]
+    }
+
+    /// The known ecosystems and their cache/artifact roots, resolved under
+    /// `home`. Stage 1 surfaces these read-only; integration hides any whose
+    /// paths don't exist and attaches sizes.
+    static func catalog(home: String) -> [Ecosystem] {
+        func p(_ suffix: String) -> String { home + "/" + suffix }
+        return [
+            Ecosystem(name: "Xcode", paths: [
+                p("Library/Developer/Xcode/DerivedData"),
+                p("Library/Developer/Xcode/iOS DeviceSupport"),
+                p("Library/Developer/CoreSimulator/Caches"),
+            ]),
+            Ecosystem(name: "Homebrew", paths: [p("Library/Caches/Homebrew")]),
+            Ecosystem(name: "npm", paths: [p(".npm")]),
+            Ecosystem(name: "pnpm", paths: [p("Library/pnpm/store"), p(".local/share/pnpm")]),
+            Ecosystem(name: "Yarn", paths: [p("Library/Caches/Yarn")]),
+            Ecosystem(name: "Cargo", paths: [p(".cargo/registry")]),
+            Ecosystem(name: "Go", paths: [p("go/pkg/mod"), p("Library/Caches/go-build")]),
+            Ecosystem(name: "pip", paths: [p("Library/Caches/pip")]),
+            Ecosystem(name: "Gradle", paths: [p(".gradle/caches")]),
+            Ecosystem(name: "Docker", paths: [p("Library/Containers/com.docker.docker/Data/vms")]),
+        ]
+    }
+
+    static func total(_ sizes: [Int64]) -> Int64 { sizes.reduce(0, +) }
+}
diff --git a/Tests/DevHygieneTests.swift b/Tests/DevHygieneTests.swift
new file mode 100644
index 00000000..5d18e749
--- /dev/null
+++ b/Tests/DevHygieneTests.swift
@@ -0,0 +1,29 @@
+//
+//  DevHygieneTests.swift
+//  BurrowTests
+//
+//  Dev-hygiene ecosystem catalog (roadmap C.9).
+//
+
+import XCTest
+@testable import Burrow
+
+final class DevHygieneTests: XCTestCase {
+    func testCatalog_coversTheMajorEcosystems() {
+        let names = Set(DevHygiene.catalog(home: "/Users/x").map(\.name))
+        for expected in ["Xcode", "Homebrew", "npm", "Cargo", "Docker"] {
+            XCTAssertTrue(names.contains(expected), "catalog is missing \(expected)")
+        }
+    }
+
+    func testCatalog_pathsResolveUnderHome() {
+        let cat = DevHygiene.catalog(home: "/Users/x")
+        let xcode = cat.first { $0.name == "Xcode" }
+        XCTAssertTrue(xcode?.paths.contains("/Users/x/Library/Developer/Xcode/DerivedData") ?? false)
+        XCTAssertTrue(cat.allSatisfy { $0.paths.allSatisfy { $0.hasPrefix("/Users/x/") } })
+    }
+
+    func testTotal_sumsSizes() {
+        XCTAssertEqual(DevHygiene.total([100, 200, 300]), 600)
+    }
+}

From 90678aacfe3c976c40572805ae459284b4c391da Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:13:46 -0700
Subject: [PATCH 16/49] feat(forecast): burrow_disk_forecast MCP tool over
 disk-free history (A.3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds MetricsStore.diskFreeSeries (total-used per snapshot for a mount, or the
largest volume) and a burrow_disk_forecast tool that runs DiskForecast over
it — agents get an honest 'fills in ~N days' (or null) without the GUI. Integration test seeds declining/flat disks through the real dispatch path.
---
 Sources/MCP.swift            | 31 ++++++++++++++
 Sources/MetricsStore.swift   | 21 +++++++++
 Tests/MCPForecastTests.swift | 82 ++++++++++++++++++++++++++++++++++++
 Tests/MCPTests.swift         |  2 +-
 4 files changed, 135 insertions(+), 1 deletion(-)
 create mode 100644 Tests/MCPForecastTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 64932cb9..d43315cd 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -274,6 +274,18 @@ struct ToolCatalog {
                     "additionalProperties": false,
                 ] as [String: Any],
             ],
+            [
+                "name": "burrow_disk_forecast",
+                "description": "Forecast when a volume runs out of space, from free-space history. `days` (default 30, 7-365) is the history window to fit; `mount` selects a volume (default: the largest). Returns days_until_full (null when the trend is flat, free space is growing, or there's under a week of history — never a bare date), the bytes/day trend, and the basis it used. Robust to single-sample cliffs. Read-only.",
+                "inputSchema": [
+                    "type": "object",
+                    "properties": [
+                        "days": ["type": "integer", "minimum": 7, "maximum": 365],
+                        "mount": ["type": "string", "description": "Volume mount point, e.g. \"/\". Defaults to the largest volume."],
+                    ],
+                    "additionalProperties": false,
+                ] as [String: Any],
+            ],
             [
                 "name": "burrow_info",
                 "description": "Burrow's own state: list of prefixes with row counts + staleness, current retention setting. Use when diagnosing whether data is flowing.",
@@ -396,6 +408,8 @@ struct ToolCatalog {
             return try self.callTopProcesses(arguments)
         case "burrow_process_usage":
             return try self.callProcessUsage(arguments)
+        case "burrow_disk_forecast":
+            return try self.callDiskForecast(arguments)
         case "burrow_info":
             return self.callInfo()
         case "burrow_cleanup_history":
@@ -514,6 +528,23 @@ struct ToolCatalog {
         return "{\"metric\":\"\(metric)\",\"window_minutes\":\(minutes),\"start_ts\":\(pw.startTS),\"end_ts\":\(pw.endTS),\"sample_count\":\(pw.sampleCount),\"interval_seconds\":\(Int(pw.intervalSeconds.rounded())),\"processes\":[\(pieces.joined(separator: ","))]}"
     }
 
+    /// `burrow_disk_forecast` — when does this volume fill? Reads the
+    /// free-space history and runs the (honest, cliff-resistant) forecaster.
+    private func callDiskForecast(_ args: [String: Any]) throws -> String {
+        let days = max(7, min((args["days"] as? Int) ?? 30, 365))
+        let mount = args["mount"] as? String
+        let now = Int(Date().timeIntervalSince1970)
+        let w = MetricsStore.Window(since: now - days * 86_400, until: now)
+        let series = self.metrics.diskFreeSeries(mount: mount, w)
+        let p = DiskForecast.forecast(series, now: now)
+        let mountStr = (mount ?? "primary")
+            .replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
+        let daysStr = p.daysUntilFull.map { String(format: "%.1f", $0) } ?? "null"
+        return "{\"mount\":\"\(mountStr)\",\"basis_days\":\(String(format: "%.1f", p.basisDays)),"
+            + "\"slope_bytes_per_day\":\(Int64(p.slopeBytesPerDay.rounded())),"
+            + "\"days_until_full\":\(daysStr),\"samples\":\(series.count)}"
+    }
+
     private func callInfo() -> String {
         let now = Int(Date().timeIntervalSince1970)
         var pieces: [String] = []
diff --git a/Sources/MetricsStore.swift b/Sources/MetricsStore.swift
index b40e69a5..1b193a22 100644
--- a/Sources/MetricsStore.swift
+++ b/Sources/MetricsStore.swift
@@ -345,6 +345,27 @@ struct MetricsStore {
                              stats: stats)
     }
 
+    // MARK: Disk free history
+
+    /// Free-bytes series for a volume over the window — `total − used` per
+    /// snapshot, the input to `DiskForecast`. `mount == nil` picks the largest
+    /// volume by total size (the main drive); a value matches that mount
+    /// exactly. Snapshots with no matching disk are skipped, not zero-filled.
+    func diskFreeSeries(mount: String?, _ w: Window, maxPoints: Int = 720)
+        -> [(ts: Int, freeBytes: Double)] {
+        snapshots(w, maxPoints: maxPoints).snapshots.compactMap { s in
+            let disk: DiskStatus?
+            if let m = mount {
+                disk = s.status.disks.first { $0.mount == m }
+            } else {
+                disk = s.status.disks.max { $0.total < $1.total }
+            }
+            guard let d = disk else { return nil }
+            let free = d.total > d.used ? d.total - d.used : 0
+            return (s.ts, Double(free))
+        }
+    }
+
     // MARK: Reader staleness
 
     struct ReaderStatus {
diff --git a/Tests/MCPForecastTests.swift b/Tests/MCPForecastTests.swift
new file mode 100644
index 00000000..e15d2b3d
--- /dev/null
+++ b/Tests/MCPForecastTests.swift
@@ -0,0 +1,82 @@
+//
+//  MCPForecastTests.swift
+//  BurrowTests
+//
+//  End-to-end for the burrow_disk_forecast tool (roadmap A.3 agent surface):
+//  seed real snapshot rows with a declining/flat disk and assert the tool's
+//  JSON reply, exercising MetricsStore.diskFreeSeries → DiskForecast through
+//  the actual dispatch path.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MCPForecastTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+    private var catalog: ToolCatalog!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-fc-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+        catalog = ToolCatalog(db: db)
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+    }
+
+    /// A snapshot with one "/" volume at `freeBytes` free of 500 GB.
+    private func snapshot(freeBytes: Int64) -> String {
+        let total: Int64 = 500_000_000_000
+        let used = max(0, total - freeBytes)
+        return """
+        {"collected_at":"2026-06-08T03:16:25-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":10,"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},
+         "disks":[{"mount":"/","used":\(used),"total":\(total),"used_percent":50,"external":false}],
+         "top_processes":[]}
+        """
+    }
+
+    private func obj(_ json: String) throws -> [String: Any] {
+        try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any])
+    }
+
+    func testDiskForecast_steadyDecline_namesADate() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let day = 86_400
+        for d in 0...30 {  // 31 daily points, -1 GB/day, ending ~100 GB free
+            let free = Int64(130_000_000_000) - Int64(d) * 1_000_000_000
+            try db.insert(prefix: MetricsStore.snapshotPrefix,
+                          ts: now - (30 - d) * day, json: snapshot(freeBytes: free))
+        }
+        let o = try obj(catalog.call(name: "burrow_disk_forecast", arguments: ["days": 60]))
+        let daysUntil = try XCTUnwrap((o["days_until_full"] as? NSNumber)?.doubleValue)
+        XCTAssertEqual(daysUntil, 100, accuracy: 15)
+        let slope = try XCTUnwrap((o["slope_bytes_per_day"] as? NSNumber)?.doubleValue)
+        XCTAssertLessThan(slope, 0)
+    }
+
+    func testDiskForecast_flatDisk_returnsNull() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let day = 86_400
+        for d in 0...30 {
+            try db.insert(prefix: MetricsStore.snapshotPrefix,
+                          ts: now - (30 - d) * day, json: snapshot(freeBytes: 100_000_000_000))
+        }
+        let o = try obj(catalog.call(name: "burrow_disk_forecast", arguments: [:]))
+        XCTAssertTrue(o["days_until_full"] is NSNull, "a flat disk never fills → null, not a bare date")
+    }
+
+    func testDiskForecast_isListedInCatalog() {
+        let names = catalog.descriptors().compactMap { $0["name"] as? String }
+        XCTAssertTrue(names.contains("burrow_disk_forecast"))
+    }
+}
diff --git a/Tests/MCPTests.swift b/Tests/MCPTests.swift
index 8620f343..d670833b 100644
--- a/Tests/MCPTests.swift
+++ b/Tests/MCPTests.swift
@@ -98,7 +98,7 @@ final class MCPTests: XCTestCase {
         let names = d.compactMap { $0["name"] as? String }
         XCTAssertEqual(Set(names),
                        ["burrow_snapshot", "burrow_history", "burrow_top_processes",
-                        "burrow_process_usage", "burrow_info",
+                        "burrow_process_usage", "burrow_disk_forecast", "burrow_info",
                         "burrow_cleanup_history", "burrow_deleted_files",
                         "burrow_analyze", "burrow_list_apps", "burrow_clean",
                         "burrow_optimize", "burrow_uninstall", "burrow_purge",

From 241f0d4c41580b0ccb4f5cfc76e4eaaed80f610a Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:20:01 -0700
Subject: [PATCH 17/49] test(forecast): fix snapshot fixture date format so
 rows decode

collected_at needs fractional seconds to match mo's ISO8601 decoder; without
them the seeded rows dropped and the forecast saw an empty series. Also
surface the tool JSON in the unwrap message for faster diagnosis.
---
 Tests/MCPForecastTests.swift | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/Tests/MCPForecastTests.swift b/Tests/MCPForecastTests.swift
index e15d2b3d..67531f57 100644
--- a/Tests/MCPForecastTests.swift
+++ b/Tests/MCPForecastTests.swift
@@ -34,7 +34,7 @@ final class MCPForecastTests: XCTestCase {
         let total: Int64 = 500_000_000_000
         let used = max(0, total - freeBytes)
         return """
-        {"collected_at":"2026-06-08T03:16:25-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
          "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
          "health_score":90,"health_score_msg":"Good",
          "cpu":{"usage":10,"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
@@ -57,8 +57,9 @@ final class MCPForecastTests: XCTestCase {
             try db.insert(prefix: MetricsStore.snapshotPrefix,
                           ts: now - (30 - d) * day, json: snapshot(freeBytes: free))
         }
-        let o = try obj(catalog.call(name: "burrow_disk_forecast", arguments: ["days": 60]))
-        let daysUntil = try XCTUnwrap((o["days_until_full"] as? NSNumber)?.doubleValue)
+        let json = try catalog.call(name: "burrow_disk_forecast", arguments: ["days": 60])
+        let o = try obj(json)
+        let daysUntil = try XCTUnwrap((o["days_until_full"] as? NSNumber)?.doubleValue, json)
         XCTAssertEqual(daysUntil, 100, accuracy: 15)
         let slope = try XCTUnwrap((o["slope_bytes_per_day"] as? NSNumber)?.doubleValue)
         XCTAssertLessThan(slope, 0)

From 47b2d51e6c997431715e20f42693684aefadc216 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:24:37 -0700
Subject: [PATCH 18/49] =?UTF-8?q?feat(diff):=20burrow=5Fdiff=20MCP=20tool?=
 =?UTF-8?q?=20=E2=80=94=20v1=20over=20snapshots=20(B.8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Diffs top-process membership (via InventoryDiff) and free-space delta between
the snapshot nearest `since` and the latest. v1 scope: app/login-item/port
inventories aren't persisted across time yet, so they're out — noted in the
reply. Integration-tested through the dispatch path.
---
 Sources/MCP.swift        | 46 ++++++++++++++++++++++++
 Tests/MCPDiffTests.swift | 76 ++++++++++++++++++++++++++++++++++++++++
 Tests/MCPTests.swift     |  2 +-
 3 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 Tests/MCPDiffTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index d43315cd..809174ca 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -286,6 +286,18 @@ struct ToolCatalog {
                     "additionalProperties": false,
                 ] as [String: Any],
             ],
+            [
+                "name": "burrow_diff",
+                "description": "What changed between the snapshot nearest `since` (unix seconds; or use `minutes` back from now, default 1440) and the latest: which processes entered/left the top list, and the free-space delta on the largest volume. v1 scope — app, login-item, and port inventories aren't tracked across time yet, so they're not diffed. Read-only.",
+                "inputSchema": [
+                    "type": "object",
+                    "properties": [
+                        "since": ["type": "integer", "description": "Unix-seconds lower bound. Overrides `minutes`."],
+                        "minutes": ["type": "integer", "minimum": 1],
+                    ],
+                    "additionalProperties": false,
+                ] as [String: Any],
+            ],
             [
                 "name": "burrow_info",
                 "description": "Burrow's own state: list of prefixes with row counts + staleness, current retention setting. Use when diagnosing whether data is flowing.",
@@ -410,6 +422,8 @@ struct ToolCatalog {
             return try self.callProcessUsage(arguments)
         case "burrow_disk_forecast":
             return try self.callDiskForecast(arguments)
+        case "burrow_diff":
+            return self.callDiff(arguments)
         case "burrow_info":
             return self.callInfo()
         case "burrow_cleanup_history":
@@ -545,6 +559,38 @@ struct ToolCatalog {
             + "\"days_until_full\":\(daysStr),\"samples\":\(series.count)}"
     }
 
+    /// `burrow_diff` — what changed since a point in time. v1 diffs top-process
+    /// membership and free-space delta from the snapshots already on disk;
+    /// app/login-item/port inventories aren't yet persisted over time.
+    private func callDiff(_ args: [String: Any]) -> String {
+        let now = Int(Date().timeIntervalSince1970)
+        let since: Int
+        if let s = args["since"] as? Int {
+            since = s
+        } else {
+            let m = max(1, min((args["minutes"] as? Int) ?? 1440, 1_000_000))
+            since = now - m * 60
+        }
+        let snaps = self.metrics.snapshots(MetricsStore.Window(since: since, until: now)).snapshots
+        guard let first = snaps.first, let last = snaps.last, snaps.count >= 2 else {
+            return "{\"error\":\"need at least two snapshots in the window\",\"since_ts\":\(since),\"until_ts\":\(now)}"
+        }
+        let change = InventoryDiff.diff(old: (first.status.topProcesses ?? []).map(\.name),
+                                        new: (last.status.topProcesses ?? []).map(\.name))
+        func freeOf(_ s: MoleStatus) -> Int64 {
+            guard let d = s.disks.max(by: { $0.total < $1.total }) else { return 0 }
+            return Int64(d.total > d.used ? d.total - d.used : 0)
+        }
+        func arr(_ xs: [String]) -> String {
+            "[" + xs.map { "\"\($0.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\"" }
+                .joined(separator: ",") + "]"
+        }
+        return "{\"since_ts\":\(first.ts),\"until_ts\":\(last.ts),"
+            + "\"processes_entered\":\(arr(change.added)),\"processes_left\":\(arr(change.removed)),"
+            + "\"disk_free_delta_bytes\":\(freeOf(last.status) - freeOf(first.status)),"
+            + "\"note\":\"app, login-item, and port inventories are not yet tracked across time\"}"
+    }
+
     private func callInfo() -> String {
         let now = Int(Date().timeIntervalSince1970)
         var pieces: [String] = []
diff --git a/Tests/MCPDiffTests.swift b/Tests/MCPDiffTests.swift
new file mode 100644
index 00000000..a8f048a9
--- /dev/null
+++ b/Tests/MCPDiffTests.swift
@@ -0,0 +1,76 @@
+//
+//  MCPDiffTests.swift
+//  BurrowTests
+//
+//  End-to-end for burrow_diff v1 (roadmap B.8 agent surface): seed two
+//  snapshots and assert the process-membership + disk-delta diff through the
+//  real dispatch path.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MCPDiffTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+    private var catalog: ToolCatalog!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-diff-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+        catalog = ToolCatalog(db: db)
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+    }
+
+    /// Snapshot with a "/" volume at `freeGB` free of 500 GB and the given
+    /// process names in top_processes.
+    private func snapshot(freeGB: Int64, procs: [String]) -> String {
+        let total: Int64 = 500_000_000_000
+        let used = total - freeGB * 1_000_000_000
+        let procJSON = procs.map {
+            "{\"pid\":1,\"name\":\"\($0)\",\"command\":\"/bin/\($0)\",\"cpu\":10,\"memory\":5}"
+        }.joined(separator: ",")
+        return """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":10,"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},
+         "disks":[{"mount":"/","used":\(used),"total":\(total),"used_percent":50,"external":false}],
+         "top_processes":[\(procJSON)]}
+        """
+    }
+
+    func testDiff_reportsProcessChurnAndDiskDelta() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let then = now - 3600
+        // Older: chrome+xcode, 200 GB free. Newer: chrome+docker, 150 GB free.
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: then,
+                      json: snapshot(freeGB: 200, procs: ["chrome", "xcode"]))
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now,
+                      json: snapshot(freeGB: 150, procs: ["chrome", "docker"]))
+
+        let json = try catalog.call(name: "burrow_diff", arguments: ["since": then - 10])
+        let o = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any], json)
+        XCTAssertEqual(o["processes_entered"] as? [String], ["docker"], json)
+        XCTAssertEqual(o["processes_left"] as? [String], ["xcode"], json)
+        // 150 GB − 200 GB = −50 GB.
+        let delta = try XCTUnwrap((o["disk_free_delta_bytes"] as? NSNumber)?.int64Value, json)
+        XCTAssertEqual(delta, -50_000_000_000)
+    }
+
+    func testDiff_tooFewSnapshots_reportsError() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now,
+                      json: snapshot(freeGB: 100, procs: ["chrome"]))
+        let json = try catalog.call(name: "burrow_diff", arguments: [:])
+        XCTAssertTrue(json.contains("need at least two snapshots"), json)
+    }
+}
diff --git a/Tests/MCPTests.swift b/Tests/MCPTests.swift
index d670833b..a12df13b 100644
--- a/Tests/MCPTests.swift
+++ b/Tests/MCPTests.swift
@@ -98,7 +98,7 @@ final class MCPTests: XCTestCase {
         let names = d.compactMap { $0["name"] as? String }
         XCTAssertEqual(Set(names),
                        ["burrow_snapshot", "burrow_history", "burrow_top_processes",
-                        "burrow_process_usage", "burrow_disk_forecast", "burrow_info",
+                        "burrow_process_usage", "burrow_disk_forecast", "burrow_diff", "burrow_info",
                         "burrow_cleanup_history", "burrow_deleted_files",
                         "burrow_analyze", "burrow_list_apps", "burrow_clean",
                         "burrow_optimize", "burrow_uninstall", "burrow_purge",

From 9ac1babf35b4dc7d0cac8e53b7c657305ecf4223 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:49:43 -0700
Subject: [PATCH 19/49] =?UTF-8?q?feat(report):=20burrow=5Freport=20MCP=20t?=
 =?UTF-8?q?ool=20=E2=80=94=20markdown=20digest=20(A.4)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Composes WeeklyReport from real snapshot data (disk forecast + top energy by
CPU-seconds); cleanup/battery/login sections are nil='unavailable' until
their sources land, never faked. spaceReclaimedBytes is now optional so
'unknown' is distinct from a genuine zero. Returns markdown as the tool text.
---
 Sources/MCP.swift             | 31 +++++++++++++++++++++++++++++++
 Sources/WeeklyReport.swift    | 13 +++++++++----
 Tests/MCPForecastTests.swift  | 13 +++++++++++++
 Tests/MCPTests.swift          |  3 ++-
 Tests/WeeklyReportTests.swift |  7 +++++++
 5 files changed, 62 insertions(+), 5 deletions(-)

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 809174ca..873385d9 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -298,6 +298,17 @@ struct ToolCatalog {
                     "additionalProperties": false,
                 ] as [String: Any],
             ],
+            [
+                "name": "burrow_report",
+                "description": "A weekly system digest as Markdown over the last `days` (default 7, 1-90): disk-full forecast, top energy users (by estimated CPU-seconds), and cleanup summary. The same artifact the Home Report card shows. Read-only.",
+                "inputSchema": [
+                    "type": "object",
+                    "properties": [
+                        "days": ["type": "integer", "minimum": 1, "maximum": 90],
+                    ],
+                    "additionalProperties": false,
+                ] as [String: Any],
+            ],
             [
                 "name": "burrow_info",
                 "description": "Burrow's own state: list of prefixes with row counts + staleness, current retention setting. Use when diagnosing whether data is flowing.",
@@ -424,6 +435,8 @@ struct ToolCatalog {
             return try self.callDiskForecast(arguments)
         case "burrow_diff":
             return self.callDiff(arguments)
+        case "burrow_report":
+            return self.callReport(arguments)
         case "burrow_info":
             return self.callInfo()
         case "burrow_cleanup_history":
@@ -591,6 +604,24 @@ struct ToolCatalog {
             + "\"note\":\"app, login-item, and port inventories are not yet tracked across time\"}"
     }
 
+    /// `burrow_report` — the weekly digest as Markdown (the tool's text
+    /// payload IS the markdown). v1 composes the disk forecast + top energy
+    /// from snapshots; cleanup/battery/login-item sections fill in as their
+    /// data sources land (so they're omitted/"unavailable" rather than faked).
+    private func callReport(_ args: [String: Any]) -> String {
+        let days = max(1, min((args["days"] as? Int) ?? 7, 90))
+        let now = Int(Date().timeIntervalSince1970)
+        let w = MetricsStore.Window(since: now - days * 86_400, until: now)
+        let series = self.metrics.diskFreeSeries(mount: nil, w)
+        let forecast = series.count >= 2 ? DiskForecast.forecast(series, now: now) : nil
+        let top = self.metrics.processWindow(w).ranked(by: .cpuTime, limit: 5)
+            .map { (name: $0.name, cpuSeconds: $0.estCPUSeconds) }
+        let input = WeeklyReport.Input(periodDays: days, spaceReclaimedBytes: nil,
+                                       topEnergy: top, newLoginItems: [],
+                                       batteryHealthDeltaPct: nil, forecast: forecast)
+        return WeeklyReport.markdown(input)
+    }
+
     private func callInfo() -> String {
         let now = Int(Date().timeIntervalSince1970)
         var pieces: [String] = []
diff --git a/Sources/WeeklyReport.swift b/Sources/WeeklyReport.swift
index 5a8d565b..af8f7505 100644
--- a/Sources/WeeklyReport.swift
+++ b/Sources/WeeklyReport.swift
@@ -14,7 +14,8 @@ import Foundation
 enum WeeklyReport {
     struct Input {
         var periodDays: Int
-        var spaceReclaimedBytes: Int64
+        /// nil = cleanup history unavailable (distinct from a genuine zero).
+        var spaceReclaimedBytes: Int64?
         var topEnergy: [(name: String, cpuSeconds: Double)]
         var newLoginItems: [String]
         /// Negative = health declined since the period start; nil = unknown.
@@ -26,9 +27,13 @@ enum WeeklyReport {
         var out = "# Burrow weekly report\n\n_Last \(i.periodDays) days._\n\n"
 
         out += "## Cleanup\n"
-        out += i.spaceReclaimedBytes > 0
-            ? "- Freed **\(Fmt.bytes(i.spaceReclaimedBytes))** this period.\n\n"
-            : "- No space reclaimed this period.\n\n"
+        if let reclaimed = i.spaceReclaimedBytes {
+            out += reclaimed > 0
+                ? "- Freed **\(Fmt.bytes(reclaimed))** this period.\n\n"
+                : "- No space reclaimed this period.\n\n"
+        } else {
+            out += "- Cleanup history unavailable.\n\n"
+        }
 
         // Only name a fill date when the forecaster was willing to — never a
         // bare date (see DiskForecast).
diff --git a/Tests/MCPForecastTests.swift b/Tests/MCPForecastTests.swift
index 67531f57..18802532 100644
--- a/Tests/MCPForecastTests.swift
+++ b/Tests/MCPForecastTests.swift
@@ -76,6 +76,19 @@ final class MCPForecastTests: XCTestCase {
         XCTAssertTrue(o["days_until_full"] is NSNull, "a flat disk never fills → null, not a bare date")
     }
 
+    func testReport_includesTitleAndForecast() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let day = 86_400
+        for d in 0...30 {  // steady decline so the report has a forecast line
+            let free = Int64(130_000_000_000) - Int64(d) * 1_000_000_000
+            try db.insert(prefix: MetricsStore.snapshotPrefix,
+                          ts: now - (30 - d) * day, json: snapshot(freeBytes: free))
+        }
+        let md = try catalog.call(name: "burrow_report", arguments: ["days": 60])
+        XCTAssertTrue(md.contains("# Burrow weekly report"), md)
+        XCTAssertTrue(md.contains("fills in"), "a steady decline should yield a forecast line")
+    }
+
     func testDiskForecast_isListedInCatalog() {
         let names = catalog.descriptors().compactMap { $0["name"] as? String }
         XCTAssertTrue(names.contains("burrow_disk_forecast"))
diff --git a/Tests/MCPTests.swift b/Tests/MCPTests.swift
index a12df13b..51ba362d 100644
--- a/Tests/MCPTests.swift
+++ b/Tests/MCPTests.swift
@@ -98,7 +98,8 @@ final class MCPTests: XCTestCase {
         let names = d.compactMap { $0["name"] as? String }
         XCTAssertEqual(Set(names),
                        ["burrow_snapshot", "burrow_history", "burrow_top_processes",
-                        "burrow_process_usage", "burrow_disk_forecast", "burrow_diff", "burrow_info",
+                        "burrow_process_usage", "burrow_disk_forecast", "burrow_diff",
+                        "burrow_report", "burrow_info",
                         "burrow_cleanup_history", "burrow_deleted_files",
                         "burrow_analyze", "burrow_list_apps", "burrow_clean",
                         "burrow_optimize", "burrow_uninstall", "burrow_purge",
diff --git a/Tests/WeeklyReportTests.swift b/Tests/WeeklyReportTests.swift
index 3f758cad..3eb3d083 100644
--- a/Tests/WeeklyReportTests.swift
+++ b/Tests/WeeklyReportTests.swift
@@ -32,6 +32,13 @@ final class WeeklyReportTests: XCTestCase {
         XCTAssertTrue(WeeklyReport.markdown(base()).contains("No space reclaimed"))
     }
 
+    func testMarkdown_reclaimUnknown_saysUnavailable() {
+        var i = base(); i.spaceReclaimedBytes = nil
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("unavailable"), "nil reclaimed is 'unavailable', not a false zero")
+        XCTAssertFalse(md.contains("No space reclaimed"))
+    }
+
     func testMarkdown_forecastPresent_namesAWeeksPhrase() {
         var i = base()
         i.forecast = .init(daysUntilFull: 21, slopeBytesPerDay: -1, basisDays: 30)

From 2c477364524bb80e0df54a7fbb669e877b6eff4b Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 10:53:08 -0700
Subject: [PATCH 20/49] feat(doctor): burrow_doctor MCP tool (roadmap I agent
 surface)

Composes Doctor.report from on-hand signals: mo presence (MoEngine.availability),
Full Disk Access (Privacy), and memory-pressure + disk headroom from the latest
snapshot, plus decode-drift count. Returns ok/warn/fail checks as JSON.
Integration-tested on the snapshot-derived (deterministic) verdicts.
---
 Sources/MCP.swift          | 47 ++++++++++++++++++++++++
 Tests/MCPDoctorTests.swift | 75 ++++++++++++++++++++++++++++++++++++++
 Tests/MCPTests.swift       |  2 +-
 3 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 Tests/MCPDoctorTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 873385d9..e26aaa00 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -309,6 +309,15 @@ struct ToolCatalog {
                     "additionalProperties": false,
                 ] as [String: Any],
             ],
+            [
+                "name": "burrow_doctor",
+                "description": "Quick diagnostics: engine (mo) presence, Full Disk Access, memory pressure, disk headroom, and recent decode errors — each an ok/warn/fail check with a short detail. Read-only.",
+                "inputSchema": [
+                    "type": "object",
+                    "properties": [String: Any](),
+                    "additionalProperties": false,
+                ] as [String: Any],
+            ],
             [
                 "name": "burrow_info",
                 "description": "Burrow's own state: list of prefixes with row counts + staleness, current retention setting. Use when diagnosing whether data is flowing.",
@@ -437,6 +446,8 @@ struct ToolCatalog {
             return self.callDiff(arguments)
         case "burrow_report":
             return self.callReport(arguments)
+        case "burrow_doctor":
+            return self.callDoctor(arguments)
         case "burrow_info":
             return self.callInfo()
         case "burrow_cleanup_history":
@@ -622,6 +633,42 @@ struct ToolCatalog {
         return WeeklyReport.markdown(input)
     }
 
+    /// `burrow_doctor` — diagnostics from signals already on hand: engine
+    /// presence, Full Disk Access, and (from the latest snapshot) memory
+    /// pressure + disk headroom, plus the decode-drift count.
+    private func callDoctor(_ args: [String: Any]) -> String {
+        let moInstalled: Bool
+        if case .installed = MoEngine.shared.availability() { moInstalled = true } else { moInstalled = false }
+        let latest = self.metrics.latest()?.status
+        var free: Int64 = 0, total: Int64 = 0
+        if let d = latest?.disks.max(by: { $0.total < $1.total }) {
+            total = Int64(d.total)
+            free = Int64(d.total > d.used ? d.total - d.used : 0)
+        }
+        let input = Doctor.Input(
+            fullDiskAccess: Privacy.hasFullDiskAccess(),
+            moInstalled: moInstalled,
+            pressure: Self.mapPressure(latest?.memory.pressure),
+            diskFreeBytes: free, diskTotalBytes: total,
+            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal)
+        func esc(_ s: String) -> String {
+            "\"\(s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\""
+        }
+        let levels = ["ok", "warn", "fail"]
+        let items = Doctor.report(input).map { c in
+            "{\"name\":\(esc(c.name)),\"level\":\"\(levels[c.level.rawValue])\",\"detail\":\(esc(c.detail))}"
+        }
+        return "{\"checks\":[\(items.joined(separator: ","))]}"
+    }
+
+    /// Map mo's free-text memory-pressure string to the Doctor enum.
+    private static func mapPressure(_ s: String?) -> Doctor.MemoryPressure {
+        guard let s = s?.lowercased() else { return .normal }
+        if s.contains("critical") { return .critical }
+        if s.contains("warn") { return .warning }
+        return .normal
+    }
+
     private func callInfo() -> String {
         let now = Int(Date().timeIntervalSince1970)
         var pieces: [String] = []
diff --git a/Tests/MCPDoctorTests.swift b/Tests/MCPDoctorTests.swift
new file mode 100644
index 00000000..c472e80b
--- /dev/null
+++ b/Tests/MCPDoctorTests.swift
@@ -0,0 +1,75 @@
+//
+//  MCPDoctorTests.swift
+//  BurrowTests
+//
+//  End-to-end for burrow_doctor (roadmap I agent surface): the snapshot-derived
+//  verdicts (memory pressure, disk headroom) are deterministic from a seeded
+//  row; engine/FDA checks depend on the runner environment, so they aren't
+//  asserted here.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MCPDoctorTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+    private var catalog: ToolCatalog!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-doc-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+        catalog = ToolCatalog(db: db)
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+    }
+
+    private func snapshot(pressure: String, freeGB: Int64) -> String {
+        let total: Int64 = 500_000_000_000
+        let used = total - freeGB * 1_000_000_000
+        return """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":10,"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":"\(pressure)"},
+         "disk_io":{"read_rate":0,"write_rate":0},
+         "disks":[{"mount":"/","used":\(used),"total":\(total),"used_percent":98,"external":false}],
+         "top_processes":[]}
+        """
+    }
+
+    private func levels(_ json: String) throws -> [String: String] {
+        let o = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any], json)
+        let checks = try XCTUnwrap(o["checks"] as? [[String: Any]], json)
+        var out: [String: String] = [:]
+        for c in checks { if let n = c["name"] as? String, let l = c["level"] as? String { out[n] = l } }
+        return out
+    }
+
+    func testDoctor_seededCriticalSnapshot_failsPressureAndDisk() throws {
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: Int(Date().timeIntervalSince1970),
+                      json: snapshot(pressure: "critical", freeGB: 10))  // 10/500 = 2% free
+        let l = try levels(catalog.call(name: "burrow_doctor", arguments: [:]))
+        XCTAssertEqual(l["Memory pressure"], "fail")
+        XCTAssertEqual(l["Disk space"], "fail")        // 2% < 5%
+        XCTAssertEqual(l.count, 5, "all five checks present")
+    }
+
+    func testDoctor_healthySnapshot_pressureAndDiskOK() throws {
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: Int(Date().timeIntervalSince1970),
+                      json: snapshot(pressure: "", freeGB: 250))  // 50% free
+        let l = try levels(catalog.call(name: "burrow_doctor", arguments: [:]))
+        XCTAssertEqual(l["Memory pressure"], "ok")
+        XCTAssertEqual(l["Disk space"], "ok")
+    }
+
+    func testDoctor_isListedInCatalog() {
+        XCTAssertTrue(catalog.descriptors().compactMap { $0["name"] as? String }.contains("burrow_doctor"))
+    }
+}
diff --git a/Tests/MCPTests.swift b/Tests/MCPTests.swift
index 51ba362d..64739be6 100644
--- a/Tests/MCPTests.swift
+++ b/Tests/MCPTests.swift
@@ -99,7 +99,7 @@ final class MCPTests: XCTestCase {
         XCTAssertEqual(Set(names),
                        ["burrow_snapshot", "burrow_history", "burrow_top_processes",
                         "burrow_process_usage", "burrow_disk_forecast", "burrow_diff",
-                        "burrow_report", "burrow_info",
+                        "burrow_report", "burrow_doctor", "burrow_info",
                         "burrow_cleanup_history", "burrow_deleted_files",
                         "burrow_analyze", "burrow_list_apps", "burrow_clean",
                         "burrow_optimize", "burrow_uninstall", "burrow_purge",

From bafeafebb3ec002ab34da0b2feb4972f2484c108 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:05:45 -0700
Subject: [PATCH 21/49] feat(watcher): new-persistence-item detection (D.12)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

StartupWatcher.newlyAppeared diffs a previous inventory against the current
StartupInventory scan (via InventoryDiff) → the 'new LaunchAgent/login item
appeared' items. Baseline persistence + notification firing are integration.
---
 Sources/StartupWatcher.swift    | 24 ++++++++++++++++++++++++
 Tests/StartupWatcherTests.swift | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 Sources/StartupWatcher.swift
 create mode 100644 Tests/StartupWatcherTests.swift

diff --git a/Sources/StartupWatcher.swift b/Sources/StartupWatcher.swift
new file mode 100644
index 00000000..e9cc0817
--- /dev/null
+++ b/Sources/StartupWatcher.swift
@@ -0,0 +1,24 @@
+//
+//  StartupWatcher.swift
+//  Burrow
+//
+//  New-persistence-item detection (roadmap D.12, the differentiating alert).
+//  Pure: a previous inventory (identifiers) + the current StartupInventory
+//  scan → the items that just appeared. Reuses InventoryDiff so "what changed"
+//  is computed one way everywhere. Persisting the baseline (Maintenance tick),
+//  firing the notification, and the reveal-in-Finder action are integration.
+//
+//  First run has no baseline; callers must NOT alert on the first scan (an
+//  empty `previousIDs` makes everything "new"), only on subsequent deltas.
+//
+
+import Foundation
+
+enum StartupWatcher {
+    /// Items whose identifier wasn't in the previous inventory — the
+    /// "a new LaunchAgent/login item appeared" signal.
+    static func newlyAppeared(previousIDs: [String], current: [StartupItem]) -> [StartupItem] {
+        let added = Set(InventoryDiff.diff(old: previousIDs, new: current.map(\.id)).added)
+        return current.filter { added.contains($0.id) }
+    }
+}
diff --git a/Tests/StartupWatcherTests.swift b/Tests/StartupWatcherTests.swift
new file mode 100644
index 00000000..5c743943
--- /dev/null
+++ b/Tests/StartupWatcherTests.swift
@@ -0,0 +1,33 @@
+//
+//  StartupWatcherTests.swift
+//  BurrowTests
+//
+//  New-persistence-item detection (roadmap D.12), tested through newlyAppeared.
+//
+
+import XCTest
+@testable import Burrow
+
+final class StartupWatcherTests: XCTestCase {
+    private func item(_ path: String) -> StartupItem {
+        StartupItem(label: path, kind: .launchAgent, scope: .user,
+                    plistPath: path, executable: "/bin/x", problem: nil)
+    }
+
+    func testNewlyAppeared_returnsOnlyAddedItems() {
+        let appeared = StartupWatcher.newlyAppeared(
+            previousIDs: ["/a", "/b"], current: [item("/a"), item("/b"), item("/c")])
+        XCTAssertEqual(appeared.map(\.id), ["/c"])
+    }
+
+    func testNewlyAppeared_noBaseline_treatsAllAsNew() {
+        // First run: caller must suppress alerts when there's no baseline.
+        let appeared = StartupWatcher.newlyAppeared(previousIDs: [], current: [item("/a"), item("/b")])
+        XCTAssertEqual(Set(appeared.map(\.id)), ["/a", "/b"])
+    }
+
+    func testNewlyAppeared_nothingNew_isEmpty() {
+        XCTAssertTrue(StartupWatcher.newlyAppeared(
+            previousIDs: ["/a", "/old"], current: [item("/a")]).isEmpty)
+    }
+}

From 00d4c0d32df0e8a60757d12057bf8813624b6499 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:05:45 -0700
Subject: [PATCH 22/49] refactor(report): shared ReportComposer.gather for GUI
 + MCP (A.4)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One history→Input gather behind both burrow_report and the Home card, so the
two can't drift. burrow_report now calls it. Tested by seeding snapshots.
---
 Sources/MCP.swift               | 13 ++------
 Sources/ReportComposer.swift    | 25 +++++++++++++++
 Tests/ReportComposerTests.swift | 57 +++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+), 10 deletions(-)
 create mode 100644 Sources/ReportComposer.swift
 create mode 100644 Tests/ReportComposerTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index e26aaa00..a60a88e1 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -621,16 +621,9 @@ struct ToolCatalog {
     /// data sources land (so they're omitted/"unavailable" rather than faked).
     private func callReport(_ args: [String: Any]) -> String {
         let days = max(1, min((args["days"] as? Int) ?? 7, 90))
-        let now = Int(Date().timeIntervalSince1970)
-        let w = MetricsStore.Window(since: now - days * 86_400, until: now)
-        let series = self.metrics.diskFreeSeries(mount: nil, w)
-        let forecast = series.count >= 2 ? DiskForecast.forecast(series, now: now) : nil
-        let top = self.metrics.processWindow(w).ranked(by: .cpuTime, limit: 5)
-            .map { (name: $0.name, cpuSeconds: $0.estCPUSeconds) }
-        let input = WeeklyReport.Input(periodDays: days, spaceReclaimedBytes: nil,
-                                       topEnergy: top, newLoginItems: [],
-                                       batteryHealthDeltaPct: nil, forecast: forecast)
-        return WeeklyReport.markdown(input)
+        return WeeklyReport.markdown(
+            ReportComposer.gather(metrics: self.metrics, days: days,
+                                  now: Int(Date().timeIntervalSince1970)))
     }
 
     /// `burrow_doctor` — diagnostics from signals already on hand: engine
diff --git a/Sources/ReportComposer.swift b/Sources/ReportComposer.swift
new file mode 100644
index 00000000..4bc06aef
--- /dev/null
+++ b/Sources/ReportComposer.swift
@@ -0,0 +1,25 @@
+//
+//  ReportComposer.swift
+//  Burrow
+//
+//  Gathers a WeeklyReport.Input from the metrics store (roadmap A.4). The one
+//  place that turns history into report inputs, so the Home Report card and
+//  the burrow_report MCP tool render the same digest and can't drift. v1
+//  fills disk-forecast + top-energy from snapshots; cleanup/battery/login
+//  stay nil ("unavailable") until those sources land — never faked.
+//
+
+import Foundation
+
+enum ReportComposer {
+    static func gather(metrics: MetricsStore, days: Int, now: Int) -> WeeklyReport.Input {
+        let w = MetricsStore.Window(since: now - days * 86_400, until: now)
+        let series = metrics.diskFreeSeries(mount: nil, w)
+        let forecast = series.count >= 2 ? DiskForecast.forecast(series, now: now) : nil
+        let top = metrics.processWindow(w).ranked(by: .cpuTime, limit: 5)
+            .map { (name: $0.name, cpuSeconds: $0.estCPUSeconds) }
+        return WeeklyReport.Input(periodDays: days, spaceReclaimedBytes: nil,
+                                  topEnergy: top, newLoginItems: [],
+                                  batteryHealthDeltaPct: nil, forecast: forecast)
+    }
+}
diff --git a/Tests/ReportComposerTests.swift b/Tests/ReportComposerTests.swift
new file mode 100644
index 00000000..2766a58b
--- /dev/null
+++ b/Tests/ReportComposerTests.swift
@@ -0,0 +1,57 @@
+//
+//  ReportComposerTests.swift
+//  BurrowTests
+//
+//  The history→report-input gather (roadmap A.4), shared by the Home card and
+//  burrow_report. Seeds snapshots and asserts the composed Input.
+//
+
+import XCTest
+@testable import Burrow
+
+final class ReportComposerTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-rc-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+    }
+
+    private func snapshot(freeGB: Int64, proc: String) -> String {
+        let total: Int64 = 500_000_000_000
+        let used = total - freeGB * 1_000_000_000
+        return """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":10,"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},
+         "disks":[{"mount":"/","used":\(used),"total":\(total),"used_percent":50,"external":false}],
+         "top_processes":[{"pid":1,"name":"\(proc)","command":"/bin/\(proc)","cpu":80,"memory":5}]}
+        """
+    }
+
+    func testGather_fillsForecastAndTopEnergy() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let day = 86_400
+        for d in 0...30 {
+            let free = Int64(130_000_000_000) - Int64(d) * 1_000_000_000
+            try db.insert(prefix: MetricsStore.snapshotPrefix,
+                          ts: now - (30 - d) * day, json: snapshot(freeGB: free / 1_000_000_000, proc: "xcode"))
+        }
+        let input = ReportComposer.gather(metrics: MetricsStore(db: db), days: 60, now: now)
+        XCTAssertEqual(input.periodDays, 60)
+        XCTAssertNil(input.spaceReclaimedBytes, "cleanup history isn't a v1 source")
+        XCTAssertNotNil(input.forecast?.daysUntilFull, "steady decline yields a forecast")
+        XCTAssertEqual(input.topEnergy.first?.name, "xcode")
+    }
+}

From 7b49813e48eae02857d903281f34f5b349c35648 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:05:45 -0700
Subject: [PATCH 23/49] feat(report): Report section on Home (A.4 GUI)

New Home segment rendering the weekly digest from ReportComposer. zh-Hans/Hant
'Report' added. Compile-verified; needs hand-test against a real history DB.
---
 Resources/zh-Hans.lproj/Localizable.strings |  3 +-
 Resources/zh-Hant.lproj/Localizable.strings |  3 +-
 Sources/HomeView.swift                      |  2 +
 Sources/ReportView.swift                    | 55 +++++++++++++++++++++
 4 files changed, 61 insertions(+), 2 deletions(-)
 create mode 100644 Sources/ReportView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index da56bde3..77e87163 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -288,8 +288,9 @@
 "Close" = "关闭";
 "Mole CLI not found" = "未找到 Mole CLI";
 
-/* Home (Overview / History / Activity) + Explain */
+/* Home (Overview / History / Activity / Report) + Explain */
 "Overview" = "概览";
+"Report" = "报告";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index f702209d..7d489ce3 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -288,8 +288,9 @@
 "Close" = "關閉";
 "Mole CLI not found" = "找不到 Mole CLI";
 
-/* Home (Overview / History / Activity) + Explain */
+/* Home (Overview / History / Activity / Report) + Explain */
 "Overview" = "總覽";
+"Report" = "報告";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/HomeView.swift b/Sources/HomeView.swift
index bb95f477..65f24bbe 100644
--- a/Sources/HomeView.swift
+++ b/Sources/HomeView.swift
@@ -25,6 +25,7 @@ struct HomeView: View {
         case overview = "Overview"
         case history = "History"
         case activity = "Activity"
+        case report = "Report"
         var id: String { rawValue }
     }
 
@@ -91,6 +92,7 @@ struct HomeView: View {
         case .overview: StatusView(db: db, live: live, feeds: feeds)
         case .history:  HistoryView(db: db, live: live, feeds: feeds)
         case .activity: ActivityView(feeds: feeds)
+        case .report:   ReportView(db: db)
         }
     }
 }
diff --git a/Sources/ReportView.swift b/Sources/ReportView.swift
new file mode 100644
index 00000000..56d4d294
--- /dev/null
+++ b/Sources/ReportView.swift
@@ -0,0 +1,55 @@
+//
+//  ReportView.swift
+//  Burrow
+//
+//  The weekly-report Home section (roadmap A.4). Renders the markdown from
+//  ReportComposer/WeeklyReport — the same digest burrow_report returns. Styled
+//  lightly with system type for now; Brand styling is a follow-up.
+//
+//  NOTE (hand-test): compile-verified only. Verify the section renders and the
+//  forecast/top-energy lines populate against a real history DB.
+//
+
+import SwiftUI
+
+struct ReportView: View {
+    let db: DB
+    @State private var lines: [String] = []
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 8) {
+                ForEach(Array(lines.enumerated()), id: \.offset) { _, line in
+                    row(line)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { reload() }
+    }
+
+    @ViewBuilder private func row(_ line: String) -> some View {
+        if line.hasPrefix("# ") {
+            Text(String(line.dropFirst(2))).font(.title2.bold()).padding(.bottom, 2)
+        } else if line.hasPrefix("## ") {
+            Text(String(line.dropFirst(3))).font(.headline).padding(.top, 8)
+        } else if line.hasPrefix("- ") {
+            Text("•  " + strip(String(line.dropFirst(2)))).font(.body)
+        } else if line.hasPrefix("_"), line.hasSuffix("_") {
+            Text(String(line.dropFirst().dropLast())).font(.caption).foregroundStyle(.secondary)
+        } else if !line.trimmingCharacters(in: .whitespaces).isEmpty {
+            Text(strip(line)).font(.body)
+        }
+    }
+
+    /// Drop the markdown bold markers we emit; the GUI shows weight via font.
+    private func strip(_ s: String) -> String { s.replacingOccurrences(of: "**", with: "") }
+
+    private func reload() {
+        let md = WeeklyReport.markdown(
+            ReportComposer.gather(metrics: MetricsStore(db: db), days: 7,
+                                  now: Int(Date().timeIntervalSince1970)))
+        lines = md.components(separatedBy: "\n")
+    }
+}

From 4014ff6ea7ef81af01b9e4d7f6cd9554524a7a4e Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:18:02 -0700
Subject: [PATCH 24/49] feat(doctor): Diagnostics section on Home (roadmap I
 GUI)

Renders Doctor.report (same verdicts as burrow_doctor) from the latest
snapshot + live FDA/engine checks, ok/warn/fail with colour. zh added.
Compile-verified; needs hand-test.
---
 Resources/zh-Hans.lproj/Localizable.strings |  2 +
 Resources/zh-Hant.lproj/Localizable.strings |  2 +
 Sources/DoctorView.swift                    | 76 +++++++++++++++++++++
 Sources/HomeView.swift                      |  2 +
 4 files changed, 82 insertions(+)
 create mode 100644 Sources/DoctorView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 77e87163..a28a9d5a 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -291,6 +291,8 @@
 /* Home (Overview / History / Activity / Report) + Explain */
 "Overview" = "概览";
 "Report" = "报告";
+"Doctor" = "诊断";
+"Diagnostics" = "系统诊断";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 7d489ce3..3f5d8e1d 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -291,6 +291,8 @@
 /* Home (Overview / History / Activity / Report) + Explain */
 "Overview" = "總覽";
 "Report" = "報告";
+"Doctor" = "診斷";
+"Diagnostics" = "系統診斷";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/DoctorView.swift b/Sources/DoctorView.swift
new file mode 100644
index 00000000..a2c0426a
--- /dev/null
+++ b/Sources/DoctorView.swift
@@ -0,0 +1,76 @@
+//
+//  DoctorView.swift
+//  Burrow
+//
+//  Diagnostics Home section (roadmap I). Renders Doctor.report — engine,
+//  Full Disk Access, memory pressure, disk headroom, recent errors — from the
+//  latest snapshot + live permission/engine checks. Same verdict logic as the
+//  burrow_doctor MCP tool.
+//
+//  NOTE (hand-test): compile-verified only. Verify the checks populate and the
+//  ok/warn/fail colours read correctly against a real machine.
+//
+
+import SwiftUI
+
+struct DoctorView: View {
+    let db: DB
+    @State private var checks: [Doctor.Check] = []
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 12) {
+                Text(NSLocalizedString("Diagnostics", comment: "")).font(.title2.bold())
+                ForEach(Array(checks.enumerated()), id: \.offset) { _, c in
+                    HStack(alignment: .top, spacing: 10) {
+                        Image(systemName: glyph(c.level)).foregroundStyle(tint(c.level))
+                            .frame(width: 20)
+                        VStack(alignment: .leading, spacing: 2) {
+                            Text(c.name).font(.headline)
+                            Text(c.detail).font(.caption).foregroundStyle(.secondary)
+                        }
+                        Spacer()
+                    }
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { reload() }
+    }
+
+    private func glyph(_ l: Doctor.Level) -> String {
+        switch l {
+        case .ok:   return "checkmark.circle.fill"
+        case .warn: return "exclamationmark.triangle.fill"
+        case .fail: return "xmark.octagon.fill"
+        }
+    }
+
+    private func tint(_ l: Doctor.Level) -> Color {
+        switch l {
+        case .ok:   return .green
+        case .warn: return .yellow
+        case .fail: return .red
+        }
+    }
+
+    private func reload() {
+        let latest = MetricsStore(db: db).latest()?.status
+        var free: Int64 = 0, total: Int64 = 0
+        if let d = latest?.disks.max(by: { $0.total < $1.total }) {
+            total = Int64(d.total)
+            free = Int64(d.total > d.used ? d.total - d.used : 0)
+        }
+        let moInstalled: Bool
+        if case .installed = MoEngine.shared.availability() { moInstalled = true } else { moInstalled = false }
+        let p = (latest?.memory.pressure ?? "").lowercased()
+        let pressure: Doctor.MemoryPressure = p.contains("critical") ? .critical
+            : (p.contains("warn") ? .warning : .normal)
+        checks = Doctor.report(.init(
+            fullDiskAccess: Privacy.hasFullDiskAccess(),
+            moInstalled: moInstalled, pressure: pressure,
+            diskFreeBytes: free, diskTotalBytes: total,
+            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal))
+    }
+}
diff --git a/Sources/HomeView.swift b/Sources/HomeView.swift
index 65f24bbe..e55c2499 100644
--- a/Sources/HomeView.swift
+++ b/Sources/HomeView.swift
@@ -26,6 +26,7 @@ struct HomeView: View {
         case history = "History"
         case activity = "Activity"
         case report = "Report"
+        case doctor = "Doctor"
         var id: String { rawValue }
     }
 
@@ -93,6 +94,7 @@ struct HomeView: View {
         case .history:  HistoryView(db: db, live: live, feeds: feeds)
         case .activity: ActivityView(feeds: feeds)
         case .report:   ReportView(db: db)
+        case .doctor:   DoctorView(db: db)
         }
     }
 }

From 362d71e4911846f20da80e22db45cc7760697a7c Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:24:18 -0700
Subject: [PATCH 25/49] =?UTF-8?q?feat(hygiene):=20Dev=20hygiene=20section?=
 =?UTF-8?q?=20on=20Home=20=E2=80=94=20stage=201=20read-only=20(C.9)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lists each ecosystem's (DevHygiene.catalog) existing cache roots with size
(off-main recursive scan), biggest first, + reveal-in-Finder. Stage-2
per-item delete is a follow-up. zh added. Compile-verified; needs hand-test.
NOTE: Home now has 6 segments — nav may want restructuring (your call).
---
 Resources/zh-Hans.lproj/Localizable.strings |  2 +
 Resources/zh-Hant.lproj/Localizable.strings |  2 +
 Sources/DevHygieneView.swift                | 91 +++++++++++++++++++++
 Sources/HomeView.swift                      |  2 +
 4 files changed, 97 insertions(+)
 create mode 100644 Sources/DevHygieneView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index a28a9d5a..f8289cf5 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -293,6 +293,8 @@
 "Report" = "报告";
 "Doctor" = "诊断";
 "Diagnostics" = "系统诊断";
+"Dev hygiene" = "开发清理";
+"No developer caches found." = "未发现开发者缓存。";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 3f5d8e1d..8bd69c9c 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -293,6 +293,8 @@
 "Report" = "報告";
 "Doctor" = "診斷";
 "Diagnostics" = "系統診斷";
+"Dev hygiene" = "開發清理";
+"No developer caches found." = "未發現開發者快取。";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/DevHygieneView.swift b/Sources/DevHygieneView.swift
new file mode 100644
index 00000000..ea0f3ed7
--- /dev/null
+++ b/Sources/DevHygieneView.swift
@@ -0,0 +1,91 @@
+//
+//  DevHygieneView.swift
+//  Burrow
+//
+//  Dev hygiene Home section (roadmap C.9, stage 1 = read-only). Lists each
+//  developer ecosystem's cache/artifact roots (from DevHygiene.catalog) that
+//  exist on disk, with their size, biggest first, and a reveal-in-Finder
+//  affordance. Stage 2 (per-item delete via the ecosystem's own tool) is a
+//  follow-up.
+//
+//  NOTE (hand-test): compile-verified only. Verify sizes look right and the
+//  scan stays off the main thread on a machine with large caches.
+//
+
+import SwiftUI
+import AppKit
+
+struct DevHygieneView: View {
+    private struct Row: Identifiable {
+        let id = UUID()
+        let ecosystem: String
+        let path: String
+        let bytes: Int64
+    }
+
+    @State private var rows: [Row] = []
+    @State private var scanning = true
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 12) {
+                HStack {
+                    Text(NSLocalizedString("Dev hygiene", comment: "")).font(.title2.bold())
+                    if scanning { ProgressView().controlSize(.small).padding(.leading, 6) }
+                }
+                if !scanning, rows.isEmpty {
+                    Text(NSLocalizedString("No developer caches found.", comment: ""))
+                        .foregroundStyle(.secondary)
+                }
+                ForEach(rows) { r in
+                    HStack(spacing: 12) {
+                        VStack(alignment: .leading, spacing: 2) {
+                            Text(r.ecosystem).font(.headline)
+                            Text(r.path).font(.caption).foregroundStyle(.secondary)
+                                .lineLimit(1).truncationMode(.middle)
+                        }
+                        Spacer()
+                        Text(Fmt.bytes(r.bytes)).font(.body.monospacedDigit())
+                        Button {
+                            NSWorkspace.shared.activateFileViewerSelecting([URL(fileURLWithPath: r.path)])
+                        } label: { Image(systemName: "magnifyingglass") }
+                            .buttonStyle(.plain)
+                            .help(NSLocalizedString("Reveal in Finder", comment: ""))
+                    }
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { await scan() }
+    }
+
+    private func scan() async {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        let found = await Task.detached(priority: .utility) { () -> [Row] in
+            var out: [Row] = []
+            for eco in DevHygiene.catalog(home: home) {
+                for path in eco.paths where FileManager.default.fileExists(atPath: path) {
+                    let bytes = Self.directorySize(path)
+                    if bytes > 0 { out.append(Row(ecosystem: eco.name, path: path, bytes: bytes)) }
+                }
+            }
+            return out.sorted { $0.bytes > $1.bytes }
+        }.value
+        rows = found
+        scanning = false
+    }
+
+    /// Recursive allocated size of a directory. Off-main only.
+    private static func directorySize(_ path: String) -> Int64 {
+        let url = URL(fileURLWithPath: path)
+        let keys: Set<URLResourceKey> = [.totalFileAllocatedSizeKey, .fileAllocatedSizeKey]
+        guard let en = FileManager.default.enumerator(at: url, includingPropertiesForKeys: Array(keys)) else { return 0 }
+        var total: Int64 = 0
+        for case let file as URL in en {
+            let v = try? file.resourceValues(forKeys: keys)
+            total += Int64(v?.totalFileAllocatedSize ?? v?.fileAllocatedSize ?? 0)
+        }
+        return total
+    }
+}
diff --git a/Sources/HomeView.swift b/Sources/HomeView.swift
index e55c2499..d2027508 100644
--- a/Sources/HomeView.swift
+++ b/Sources/HomeView.swift
@@ -27,6 +27,7 @@ struct HomeView: View {
         case activity = "Activity"
         case report = "Report"
         case doctor = "Doctor"
+        case hygiene = "Dev hygiene"
         var id: String { rawValue }
     }
 
@@ -95,6 +96,7 @@ struct HomeView: View {
         case .activity: ActivityView(feeds: feeds)
         case .report:   ReportView(db: db)
         case .doctor:   DoctorView(db: db)
+        case .hygiene:  DevHygieneView()
         }
     }
 }

From aa004a19f2f1ffe82d1bdde40b21f2f029543e33 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:27:12 -0700
Subject: [PATCH 26/49] feat(ports): native proc_listpids listening-port
 enumeration (C.10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-pid fd scan → socket fdinfo → TCP-listen + bound-UDP ports, feeding
PortInspector (sort + kill-safety). No lsof, no elevation for own processes.
NOTE: native C-interop, runtime-unverifiable in CI; hand-test vs lsof -i -P.
---
 Sources/PortEnumerator.swift | 86 ++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 Sources/PortEnumerator.swift

diff --git a/Sources/PortEnumerator.swift b/Sources/PortEnumerator.swift
new file mode 100644
index 00000000..78454f58
--- /dev/null
+++ b/Sources/PortEnumerator.swift
@@ -0,0 +1,86 @@
+//
+//  PortEnumerator.swift
+//  Burrow
+//
+//  Native listening-port enumeration (roadmap C.10): proc_listpids → per-pid
+//  fd scan → socket fdinfo, no shelling out to lsof, no elevation for the
+//  user's own processes. Feeds PortInspector (sort + kill-safety) and the
+//  ports pane / burrow_ports tool.
+//
+//  NOTE (hand-test): native C-interop, runtime-unverifiable in CI (no
+//  guaranteed listening sockets). Verify the port list matches `lsof -i -P`
+//  on a real machine.
+//
+
+import Foundation
+import Darwin
+
+enum PortEnumerator {
+    static func listening(currentUID: uid_t = getuid()) -> [ListeningPort] {
+        var out: [ListeningPort] = []
+        var pids = [pid_t](repeating: 0, count: 8192)
+        let bytes = proc_listpids(UInt32(PROC_ALL_PIDS), 0, &pids,
+                                  Int32(pids.count * MemoryLayout<pid_t>.stride))
+        guard bytes > 0 else { return [] }
+        let pidCount = Int(bytes) / MemoryLayout<pid_t>.stride
+
+        for i in 0..<pidCount {
+            let pid = pids[i]
+            guard pid > 0 else { continue }
+
+            let fdBytes = proc_pidinfo(pid, PROC_PIDLISTFDS, 0, nil, 0)
+            guard fdBytes > 0 else { continue }
+            let fdCount = Int(fdBytes) / MemoryLayout<proc_fdinfo>.stride
+            var fds = [proc_fdinfo](repeating: proc_fdinfo(), count: fdCount)
+            let gotFds = proc_pidinfo(pid, PROC_PIDLISTFDS, 0, &fds, fdBytes)
+            guard gotFds > 0 else { continue }
+
+            var name: String?
+            var uid: uid_t?
+            for f in 0..<(Int(gotFds) / MemoryLayout<proc_fdinfo>.stride) {
+                guard fds[f].proc_fdtype == UInt32(PROX_FDTYPE_SOCKET) else { continue }
+                var si = socket_fdinfo()
+                let r = proc_pidfdinfo(pid, fds[f].proc_fd, PROC_PIDFDSOCKETINFO,
+                                       &si, Int32(MemoryLayout<socket_fdinfo>.stride))
+                guard r >= Int32(MemoryLayout<socket_fdinfo>.stride) else { continue }
+
+                let psi = si.psi
+                let proto: String
+                let lportRaw: Int32
+                if psi.soi_kind == Int32(SOCKINFO_TCP) {
+                    guard si.psi.soi_proto.pri_tcp.tcpsi_state == Int32(TSI_S_LISTEN) else { continue }
+                    proto = "tcp"
+                    lportRaw = si.psi.soi_proto.pri_tcp.tcpsi_ini.insi_lport
+                } else if psi.soi_kind == Int32(SOCKINFO_IN) {
+                    lportRaw = si.psi.soi_proto.pri_in.insi_lport
+                    guard lportRaw != 0 else { continue }   // only bound UDP sockets
+                    proto = "udp"
+                } else {
+                    continue
+                }
+                // insi_lport holds the port in network byte order in its low 16 bits.
+                let port = Int(UInt16(bigEndian: UInt16(truncatingIfNeeded: lportRaw)))
+                guard port > 0 else { continue }
+
+                if name == nil { name = Self.processName(pid) }
+                if uid == nil { uid = Self.processUID(pid) }
+                out.append(ListeningPort(pid: Int(pid), process: name ?? "pid \(pid)",
+                                         port: port, proto: proto,
+                                         address: "*", uid: Int(uid ?? 0)))
+            }
+        }
+        return PortInspector.sorted(out)
+    }
+
+    private static func processName(_ pid: pid_t) -> String {
+        var buf = [CChar](repeating: 0, count: 256)
+        let n = proc_name(pid, &buf, UInt32(buf.count))
+        return n > 0 ? String(cString: buf) : "pid \(pid)"
+    }
+
+    private static func processUID(_ pid: pid_t) -> uid_t {
+        var info = proc_bsdinfo()
+        let r = proc_pidinfo(pid, PROC_PIDTBSDINFO, 0, &info, Int32(MemoryLayout<proc_bsdinfo>.stride))
+        return r > 0 ? info.pbi_uid : 0
+    }
+}

From 6b07fc33dc01d1abb69b10ff43302366d09a9f41 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:32:08 -0700
Subject: [PATCH 27/49] feat(ports): burrow_ports MCP tool over native
 enumeration (C.10)

Lists listening sockets + owning process via PortEnumerator/PortInspector.
Read-only. Shape-tested through dispatch (specific ports are machine-dependent).
---
 Sources/MCP.swift         | 24 ++++++++++++++++++++
 Tests/MCPPortsTests.swift | 48 +++++++++++++++++++++++++++++++++++++++
 Tests/MCPTests.swift      |  2 +-
 3 files changed, 73 insertions(+), 1 deletion(-)
 create mode 100644 Tests/MCPPortsTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index a60a88e1..fc9260fa 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -318,6 +318,15 @@ struct ToolCatalog {
                     "additionalProperties": false,
                 ] as [String: Any],
             ],
+            [
+                "name": "burrow_ports",
+                "description": "Listening TCP/UDP ports with the owning process (pid, name, uid). Native enumeration (no lsof). Read-only — to free a port, kill the process yourself.",
+                "inputSchema": [
+                    "type": "object",
+                    "properties": [String: Any](),
+                    "additionalProperties": false,
+                ] as [String: Any],
+            ],
             [
                 "name": "burrow_info",
                 "description": "Burrow's own state: list of prefixes with row counts + staleness, current retention setting. Use when diagnosing whether data is flowing.",
@@ -448,6 +457,8 @@ struct ToolCatalog {
             return self.callReport(arguments)
         case "burrow_doctor":
             return self.callDoctor(arguments)
+        case "burrow_ports":
+            return self.callPorts(arguments)
         case "burrow_info":
             return self.callInfo()
         case "burrow_cleanup_history":
@@ -662,6 +673,19 @@ struct ToolCatalog {
         return .normal
     }
 
+    /// `burrow_ports` — listening sockets + owning process, via native
+    /// enumeration. Read-only; killing is a GUI-only, confirm-gated action.
+    private func callPorts(_ args: [String: Any]) -> String {
+        func esc(_ s: String) -> String {
+            "\"\(s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\""
+        }
+        let ports = PortEnumerator.listening()
+        let items = ports.map { p in
+            "{\"pid\":\(p.pid),\"process\":\(esc(p.process)),\"port\":\(p.port),\"proto\":\"\(p.proto)\",\"uid\":\(p.uid)}"
+        }
+        return "{\"count\":\(ports.count),\"ports\":[\(items.joined(separator: ","))]}"
+    }
+
     private func callInfo() -> String {
         let now = Int(Date().timeIntervalSince1970)
         var pieces: [String] = []
diff --git a/Tests/MCPPortsTests.swift b/Tests/MCPPortsTests.swift
new file mode 100644
index 00000000..2b85c1eb
--- /dev/null
+++ b/Tests/MCPPortsTests.swift
@@ -0,0 +1,48 @@
+//
+//  MCPPortsTests.swift
+//  BurrowTests
+//
+//  burrow_ports shape (roadmap C.10). The enumeration is native + machine-
+//  dependent (can't assert specific ports on a CI runner), so this asserts the
+//  reply is well-formed JSON with the documented fields, exercising the real
+//  dispatch + PortEnumerator → PortInspector path.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MCPPortsTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+    private var catalog: ToolCatalog!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-ports-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+        catalog = ToolCatalog(db: db)
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+    }
+
+    func testPorts_returnsWellFormedJSON() throws {
+        let json = try catalog.call(name: "burrow_ports", arguments: [:])
+        let o = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any], json)
+        XCTAssertNotNil(o["count"] as? Int, json)
+        let ports = try XCTUnwrap(o["ports"] as? [[String: Any]], json)
+        // Each entry, if any, carries the documented fields.
+        for p in ports {
+            XCTAssertNotNil(p["pid"] as? Int)
+            XCTAssertNotNil(p["port"] as? Int)
+            XCTAssertNotNil(p["proto"] as? String)
+        }
+    }
+
+    func testPorts_isListedInCatalog() {
+        XCTAssertTrue(catalog.descriptors().compactMap { $0["name"] as? String }.contains("burrow_ports"))
+    }
+}
diff --git a/Tests/MCPTests.swift b/Tests/MCPTests.swift
index 64739be6..a34adc67 100644
--- a/Tests/MCPTests.swift
+++ b/Tests/MCPTests.swift
@@ -99,7 +99,7 @@ final class MCPTests: XCTestCase {
         XCTAssertEqual(Set(names),
                        ["burrow_snapshot", "burrow_history", "burrow_top_processes",
                         "burrow_process_usage", "burrow_disk_forecast", "burrow_diff",
-                        "burrow_report", "burrow_doctor", "burrow_info",
+                        "burrow_report", "burrow_doctor", "burrow_ports", "burrow_info",
                         "burrow_cleanup_history", "burrow_deleted_files",
                         "burrow_analyze", "burrow_list_apps", "burrow_clean",
                         "burrow_optimize", "burrow_uninstall", "burrow_purge",

From e7a74f129c888412771482994225f879cefb4a25 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:35:12 -0700
Subject: [PATCH 28/49] feat(ports): Ports inspector pane as a Tool (C.10 GUI)

New .ports Tool (top-nav pill) rendering PortEnumerator.listening() with a
confirm-gated Quit (SIGTERM) on the user's own processes only. zh added.
Compile-verified; needs hand-test (native enum + real kill).
---
 Resources/zh-Hans.lproj/Localizable.strings |  5 ++
 Resources/zh-Hant.lproj/Localizable.strings |  5 ++
 Sources/PortsView.swift                     | 70 +++++++++++++++++++++
 Sources/RootView.swift                      |  1 +
 Sources/Tool.swift                          |  9 ++-
 5 files changed, 88 insertions(+), 2 deletions(-)
 create mode 100644 Sources/PortsView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index f8289cf5..a7c00366 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -295,6 +295,11 @@
 "Diagnostics" = "系统诊断";
 "Dev hygiene" = "开发清理";
 "No developer caches found." = "未发现开发者缓存。";
+"ports" = "端口";
+"Ports" = "端口";
+"Listening ports" = "监听端口";
+"See who's listening." = "看看谁在监听。";
+"Quit this process?" = "退出此进程？";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 8bd69c9c..75e1dcdc 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -295,6 +295,11 @@
 "Diagnostics" = "系統診斷";
 "Dev hygiene" = "開發清理";
 "No developer caches found." = "未發現開發者快取。";
+"ports" = "連接埠";
+"Ports" = "連接埠";
+"Listening ports" = "監聽連接埠";
+"See who's listening." = "看看誰在監聽。";
+"Quit this process?" = "退出此程序？";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/PortsView.swift b/Sources/PortsView.swift
new file mode 100644
index 00000000..38685e8d
--- /dev/null
+++ b/Sources/PortsView.swift
@@ -0,0 +1,70 @@
+//
+//  PortsView.swift
+//  Burrow
+//
+//  Listening-port inspector pane (roadmap C.10): the GUI of `lsof -i` + kill.
+//  Lists PortEnumerator.listening() with a confirm-gated Quit (SIGTERM) on the
+//  user's own processes only (PortInspector.isKillable); root/other-user
+//  sockets are shown read-only.
+//
+//  NOTE (hand-test): native enumeration + a real kill — verify the list vs
+//  `lsof -i -P` and that Quit only targets your own processes.
+//
+
+import SwiftUI
+import Darwin
+
+struct PortsView: View {
+    @State private var ports: [ListeningPort] = []
+    @State private var killTarget: ListeningPort?
+    private let uid = Int(getuid())
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 8) {
+                Text(NSLocalizedString("Listening ports", comment: "")).font(.title2.bold())
+                ForEach(Array(ports.enumerated()), id: \.offset) { _, p in
+                    HStack(spacing: 12) {
+                        Text("\(p.port)").font(.body.monospacedDigit().weight(.bold))
+                            .frame(width: 64, alignment: .leading)
+                        Text(p.proto).font(.caption).foregroundStyle(.secondary)
+                            .frame(width: 36, alignment: .leading)
+                        VStack(alignment: .leading, spacing: 2) {
+                            Text(p.process).font(.headline)
+                            Text("pid \(p.pid)").font(.caption).foregroundStyle(.secondary)
+                        }
+                        Spacer()
+                        if PortInspector.isKillable(p, currentUID: uid) {
+                            Button(NSLocalizedString("Quit", comment: "")) { killTarget = p }
+                                .buttonStyle(.bordered)
+                        }
+                    }
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { reload() }
+        .confirmationDialog(
+            NSLocalizedString("Quit this process?", comment: ""),
+            isPresented: Binding(get: { killTarget != nil },
+                                 set: { if !$0 { killTarget = nil } }),
+            presenting: killTarget
+        ) { p in
+            Button(NSLocalizedString("Quit", comment: ""), role: .destructive) {
+                _ = kill(pid_t(p.pid), SIGTERM)
+                reload()
+            }
+            Button(NSLocalizedString("Cancel", comment: ""), role: .cancel) {}
+        } message: { p in
+            Text("\(p.process) (pid \(p.pid)) — port \(p.port)")
+        }
+    }
+
+    private func reload() {
+        Task.detached(priority: .userInitiated) {
+            let found = PortEnumerator.listening()
+            await MainActor.run { ports = found }
+        }
+    }
+}
diff --git a/Sources/RootView.swift b/Sources/RootView.swift
index a5ddbe62..c2dc6049 100644
--- a/Sources/RootView.swift
+++ b/Sources/RootView.swift
@@ -137,6 +137,7 @@ struct RootView: View {
             SoftwareView(isActive: pane == .tool(.apps)).tabVisible(pane == .tool(.apps))
             CleanHub().tabVisible(pane == .tool(.clean))
             OptimizeView().tabVisible(pane == .tool(.optimize))
+            PortsView().tabVisible(pane == .tool(.ports))
 
             // Gated on window visibility too: these two carry live timers
             // (2 s polls, 15 s DB reads) that must stop when the window
diff --git a/Sources/Tool.swift b/Sources/Tool.swift
index aec6ef24..52d9fa06 100644
--- a/Sources/Tool.swift
+++ b/Sources/Tool.swift
@@ -12,7 +12,7 @@
 import SwiftUI
 
 enum Tool: String, CaseIterable, Identifiable {
-    case clean, purge, installer, apps, optimize, analyze, status
+    case clean, purge, installer, apps, optimize, analyze, status, ports
 
     var id: String { rawValue }
 
@@ -21,7 +21,7 @@ enum Tool: String, CaseIterable, Identifiable {
     /// optimize, then apps / analyze. The .purge/.installer cases live on for
     /// the hub cards, MCP actions, and Explain deep-links. The live dashboard
     /// isn't a tool anymore — it's Home, reached by the Burrow mark.
-    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze]
+    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze, .ports]
 
     /// Lowercase tab label (matches the instrument-panel voice).
     var label: String { NSLocalizedString(rawValue, comment: "") }
@@ -36,6 +36,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .optimize:  return NSLocalizedString("Optimize", comment: "")
         case .analyze:   return NSLocalizedString("Analyze", comment: "")
         case .status:    return NSLocalizedString("Status", comment: "")
+        case .ports:     return NSLocalizedString("Ports", comment: "")
         }
     }
 
@@ -48,6 +49,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .optimize:  return "wand.and.stars"
         case .analyze:   return "square.grid.2x2"
         case .status:    return "waveform.path.ecg"
+        case .ports:     return "network"
         }
     }
 
@@ -61,6 +63,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .optimize:  return Color(hex: 0x8E84F0) // violet
         case .analyze:   return Color(hex: 0x4FA3E3) // azure
         case .status:    return Color(hex: 0xE6A93C) // gold
+        case .ports:     return Color(hex: 0xB58BD6) // lilac
         }
     }
 
@@ -75,6 +78,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .optimize:  return Color(hex: 0x1A1730)
         case .analyze:   return Color(hex: 0x0E1F2E)
         case .status:    return Color(hex: 0x241D11)
+        case .ports:     return Color(hex: 0x1B1426)
         }
     }
 
@@ -94,6 +98,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .optimize:  return NSLocalizedString("Small turns, a smoother run.", comment: "")
         case .analyze:   return NSLocalizedString("Map every chamber below.", comment: "")
         case .status:    return NSLocalizedString("Every pulse of the den.", comment: "")
+        case .ports:     return NSLocalizedString("See who's listening.", comment: "")
         }
     }
 }

From f9e95514c228c2768dd2486b22c3f89c88683b05 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:49:41 -0700
Subject: [PATCH 29/49] feat(watcher): fire on new LaunchAgent/login items
 (D.12)

StartupWatcher.check folds a scanLive() against a persisted baseline
(Store.startupBaselineJSON), first-run-suppressing. BurrowNotifier.checkStartupWatcher
runs it on the existing reminder timer (default-on Store.watchStartupItems,
independent of smart reminders) and posts once per appearance. The fold is
unit-tested; firing is compile-verified (hand-test the notification).
---
 Resources/zh-Hans.lproj/Localizable.strings |  2 ++
 Resources/zh-Hant.lproj/Localizable.strings |  2 ++
 Sources/Notifications.swift                 | 31 ++++++++++++++++++++-
 Sources/StartupWatcher.swift                | 19 +++++++++++++
 Sources/Store.swift                         | 15 ++++++++++
 Tests/StartupWatcherTests.swift             | 20 +++++++++++++
 6 files changed, 88 insertions(+), 1 deletion(-)

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index a7c00366..134f30fe 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -300,6 +300,8 @@
 "Listening ports" = "监听端口";
 "See who's listening." = "看看谁在监听。";
 "Quit this process?" = "退出此进程？";
+"A new startup item appeared" = "出现了新的启动项";
+"“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 75e1dcdc..c60a1721 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -300,6 +300,8 @@
 "Listening ports" = "監聽連接埠";
 "See who's listening." = "看看誰在監聽。";
 "Quit this process?" = "退出此程序？";
+"A new startup item appeared" = "出現了新的啟動項";
+"“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/Notifications.swift b/Sources/Notifications.swift
index 708aeaa3..29f84235 100644
--- a/Sources/Notifications.swift
+++ b/Sources/Notifications.swift
@@ -149,12 +149,41 @@ final class BurrowNotifier: NSObject {
     func startReminders() {
         guard !inert, reminderTimer == nil else { return }
         let timer = Timer(timeInterval: 3_600, repeats: true) { _ in
-            Task { @MainActor in BurrowNotifier.shared.checkReminders() }
+            Task { @MainActor in
+                BurrowNotifier.shared.checkReminders()
+                BurrowNotifier.shared.checkStartupWatcher()
+            }
         }
         RunLoop.main.add(timer, forMode: .common)
         reminderTimer = timer
         DispatchQueue.main.asyncAfter(deadline: .now() + 120) { [weak self] in
             self?.checkReminders()
+            self?.checkStartupWatcher()
+        }
+    }
+
+    /// New-persistence-item watcher (D.12). Scans login items / LaunchAgents
+    /// off the main thread, diffs against the stored baseline, and posts once
+    /// per newly-appeared item. First run only establishes the baseline (no
+    /// alarm); gated by its own default-on toggle, independent of the
+    /// taste-based smart reminders.
+    func checkStartupWatcher() {
+        guard !inert, Store.watchStartupItems else { return }
+        DispatchQueue.global(qos: .utility).async { [weak self] in
+            let items = StartupInventory.scanLive()
+            Task { @MainActor in
+                guard let self else { return }
+                let prev = Store.startupBaselineJSON
+                let result = StartupWatcher.check(previousBaselineJSON: prev.isEmpty ? nil : prev,
+                                                  current: items)
+                Store.startupBaselineJSON = result.baselineJSON
+                for item in result.newItems.prefix(5) {
+                    self.postReminder(
+                        title: NSLocalizedString("A new startup item appeared", comment: ""),
+                        body: String(format: NSLocalizedString("“%@” now launches automatically. If you didn't add it, review it.", comment: ""), item.label),
+                        pane: "apps", id: "burrow-startup-\(item.id)")
+                }
+            }
         }
     }
 
diff --git a/Sources/StartupWatcher.swift b/Sources/StartupWatcher.swift
index e9cc0817..f06abd4f 100644
--- a/Sources/StartupWatcher.swift
+++ b/Sources/StartupWatcher.swift
@@ -21,4 +21,23 @@ enum StartupWatcher {
         let added = Set(InventoryDiff.diff(old: previousIDs, new: current.map(\.id)).added)
         return current.filter { added.contains($0.id) }
     }
+
+    /// Fold a fresh scan against the persisted baseline JSON (a `[String]` of
+    /// ids). First run — no baseline, or an empty one — alerts on nothing and
+    /// just establishes the baseline; only later scans report appearances.
+    /// Returns what to alert on plus the baseline JSON to persist.
+    static func check(previousBaselineJSON: String?,
+                      current: [StartupItem]) -> (newItems: [StartupItem], baselineJSON: String) {
+        let baseline = encode(current.map(\.id))
+        guard let prev = previousBaselineJSON,
+              let prevIDs = try? JSONDecoder().decode([String].self, from: Data(prev.utf8)),
+              !prevIDs.isEmpty else {
+            return ([], baseline)
+        }
+        return (newlyAppeared(previousIDs: prevIDs, current: current), baseline)
+    }
+
+    private static func encode(_ ids: [String]) -> String {
+        (try? JSONEncoder().encode(ids)).flatMap { String(data: $0, encoding: .utf8) } ?? "[]"
+    }
 }
diff --git a/Sources/Store.swift b/Sources/Store.swift
index d975467e..18b16d15 100644
--- a/Sources/Store.swift
+++ b/Sources/Store.swift
@@ -372,6 +372,21 @@ enum Store {
         set { write(newValue, "smart_reminders_enabled") }
     }
 
+    /// New-LaunchAgent / login-item watcher (D.12). On by default — a
+    /// persistence item appearing is a lightweight security signal most
+    /// utilities miss, so this is one of the few default-on notices.
+    static var watchStartupItems: Bool {
+        get { d.object(forKey: "watch_startup_items") as? Bool ?? true }
+        set { write(newValue, "watch_startup_items") }
+    }
+
+    /// Persisted baseline for the startup watcher — a JSON `[String]` of item
+    /// ids. Not user-facing; it's the watcher's diff anchor.
+    static var startupBaselineJSON: String {
+        get { d.string(forKey: "startup_baseline_json") ?? "" }
+        set { write(newValue, "startup_baseline_json") }
+    }
+
     // Reminder throttle state (not user-facing): hysteresis flags so a
     // metric hovering at its threshold can't flap, timestamps for the
     // weekly cooldowns. See ReminderRules (Notifications.swift).
diff --git a/Tests/StartupWatcherTests.swift b/Tests/StartupWatcherTests.swift
index 5c743943..e1bee2b3 100644
--- a/Tests/StartupWatcherTests.swift
+++ b/Tests/StartupWatcherTests.swift
@@ -30,4 +30,24 @@ final class StartupWatcherTests: XCTestCase {
         XCTAssertTrue(StartupWatcher.newlyAppeared(
             previousIDs: ["/a", "/old"], current: [item("/a")]).isEmpty)
     }
+
+    // MARK: check (baseline fold)
+
+    func testCheck_firstRun_alertsNothingButSetsBaseline() {
+        let r = StartupWatcher.check(previousBaselineJSON: nil, current: [item("/a"), item("/b")])
+        XCTAssertTrue(r.newItems.isEmpty, "no baseline → don't alarm on everything")
+        XCTAssertTrue(r.baselineJSON.contains("/a") && r.baselineJSON.contains("/b"))
+    }
+
+    func testCheck_subsequentRun_reportsAppearance() {
+        let first = StartupWatcher.check(previousBaselineJSON: nil, current: [item("/a")])
+        let second = StartupWatcher.check(previousBaselineJSON: first.baselineJSON,
+                                          current: [item("/a"), item("/evil")])
+        XCTAssertEqual(second.newItems.map(\.id), ["/evil"])
+    }
+
+    func testCheck_emptyBaseline_treatedAsFirstRun() {
+        let r = StartupWatcher.check(previousBaselineJSON: "[]", current: [item("/a")])
+        XCTAssertTrue(r.newItems.isEmpty)
+    }
 }

From 2d3789068680b7c00867d2b35fd01f6f71fa30fd Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:51:05 -0700
Subject: [PATCH 30/49] feat(anomaly): findings scan over per-process CPU
 history (A.2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MetricsStore.processCPUSamples (name → CPU%/snapshot) feeds AnomalyScan.cpuFindings,
which applies the Anomaly rule per process (recent vs baseline window) and
ranks regressions. Pure + tested; the Maintenance pass writing burrow.findings
+ the Home Changes card are integration.
---
 Sources/AnomalyScan.swift    | 36 +++++++++++++++++++++++++++++++++++
 Sources/MetricsStore.swift   | 15 +++++++++++++++
 Tests/AnomalyScanTests.swift | 37 ++++++++++++++++++++++++++++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 Sources/AnomalyScan.swift
 create mode 100644 Tests/AnomalyScanTests.swift

diff --git a/Sources/AnomalyScan.swift b/Sources/AnomalyScan.swift
new file mode 100644
index 00000000..a0b1e240
--- /dev/null
+++ b/Sources/AnomalyScan.swift
@@ -0,0 +1,36 @@
+//
+//  AnomalyScan.swift
+//  Burrow
+//
+//  Connects the Anomaly rules (A.2) to real history: per-process CPU samples
+//  for a recent window vs a baseline window → the processes whose usage has
+//  regressed. Pure over the two sample maps (which MetricsStore.processCPUSamples
+//  produces), so it's testable without a DB. Persisting findings under
+//  `burrow.findings` (Maintenance pass) and the Home "Changes" card are
+//  integration.
+//
+
+import Foundation
+
+enum AnomalyScan {
+    struct Finding: Equatable {
+        let process: String
+        let recentMedian: Double
+        let baselineMedian: Double
+    }
+
+    /// Flag every process whose recent CPU clears its own baseline per the
+    /// Anomaly rule, worst (highest recent median) first.
+    static func cpuFindings(baseline: [String: [Double]],
+                            recent: [String: [Double]]) -> [Finding] {
+        var out: [Finding] = []
+        for (name, recentSamples) in recent {
+            guard let baseSamples = baseline[name] else { continue }
+            guard Anomaly.processCPUExceedsBaseline(baseline: baseSamples, recent: recentSamples) else { continue }
+            out.append(Finding(process: name,
+                               recentMedian: Anomaly.median(recentSamples),
+                               baselineMedian: Anomaly.median(baseSamples)))
+        }
+        return out.sorted { $0.recentMedian > $1.recentMedian }
+    }
+}
diff --git a/Sources/MetricsStore.swift b/Sources/MetricsStore.swift
index 1b193a22..1dd34bff 100644
--- a/Sources/MetricsStore.swift
+++ b/Sources/MetricsStore.swift
@@ -366,6 +366,21 @@ struct MetricsStore {
         }
     }
 
+    // MARK: Per-process CPU history
+
+    /// Per-process CPU samples over the window: process name → one CPU% value
+    /// per snapshot it appeared in. The input to anomaly baselining (A.2) —
+    /// recent vs prior-period medians per process.
+    func processCPUSamples(_ w: Window, maxPoints: Int = 720) -> [String: [Double]] {
+        var out: [String: [Double]] = [:]
+        for s in snapshots(w, maxPoints: maxPoints).snapshots {
+            for p in (s.status.topProcesses ?? []) {
+                out[p.name, default: []].append(p.cpu)
+            }
+        }
+        return out
+    }
+
     // MARK: Reader staleness
 
     struct ReaderStatus {
diff --git a/Tests/AnomalyScanTests.swift b/Tests/AnomalyScanTests.swift
new file mode 100644
index 00000000..69cea22e
--- /dev/null
+++ b/Tests/AnomalyScanTests.swift
@@ -0,0 +1,37 @@
+//
+//  AnomalyScanTests.swift
+//  BurrowTests
+//
+//  Anomaly findings over baseline/recent per-process CPU maps (roadmap A.2).
+//
+
+import XCTest
+@testable import Burrow
+
+final class AnomalyScanTests: XCTestCase {
+    func testCPUFindings_flagsRegressedProcessOnly() {
+        let baseline: [String: [Double]] = [
+            "WindowServer": Array(repeating: 20.0, count: 20),
+            "Finder": Array(repeating: 2.0, count: 20),
+        ]
+        let recent: [String: [Double]] = [
+            "WindowServer": Array(repeating: 50.0, count: 8),   // doubled+ → flagged
+            "Finder": Array(repeating: 2.5, count: 8),           // steady → not flagged
+        ]
+        let findings = AnomalyScan.cpuFindings(baseline: baseline, recent: recent)
+        XCTAssertEqual(findings.map(\.process), ["WindowServer"])
+        XCTAssertEqual(findings.first?.baselineMedian ?? 0, 20, accuracy: 0.001)
+    }
+
+    func testCPUFindings_ignoresProcessWithoutBaseline() {
+        let findings = AnomalyScan.cpuFindings(
+            baseline: [:], recent: ["new": Array(repeating: 90.0, count: 8)])
+        XCTAssertTrue(findings.isEmpty, "no baseline to compare against → not a regression")
+    }
+
+    func testCPUFindings_sortedByRecentMedianDescending() {
+        let baseline = ["a": Array(repeating: 5.0, count: 20), "b": Array(repeating: 5.0, count: 20)]
+        let recent = ["a": Array(repeating: 40.0, count: 8), "b": Array(repeating: 70.0, count: 8)]
+        XCTAssertEqual(AnomalyScan.cpuFindings(baseline: baseline, recent: recent).map(\.process), ["b", "a"])
+    }
+}

From 0185f0b5ab428bec31eea038e9326f587b629a45 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 11:56:39 -0700
Subject: [PATCH 31/49] feat(alerts): threshold-rule orchestrator over
 snapshots (D.12)

ThresholdAlerts folds CPU/memory through AlertEngine (hysteresis + cooldown,
one fire per episode) given prior per-rule states. Pure + tested. Per-sample
evaluation (Sampler), state persistence, and posting are integration;
disk-low stays in ReminderRules.
---
 Sources/ThresholdAlerts.swift    | 48 +++++++++++++++++++++++++++++++
 Tests/ThresholdAlertsTests.swift | 49 ++++++++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 Sources/ThresholdAlerts.swift
 create mode 100644 Tests/ThresholdAlertsTests.swift

diff --git a/Sources/ThresholdAlerts.swift b/Sources/ThresholdAlerts.swift
new file mode 100644
index 00000000..fdd6a256
--- /dev/null
+++ b/Sources/ThresholdAlerts.swift
@@ -0,0 +1,48 @@
+//
+//  ThresholdAlerts.swift
+//  Burrow
+//
+//  The concrete threshold rules (roadmap D.12) folded over a snapshot through
+//  the tested AlertEngine: CPU pegged / memory pressure high, with hysteresis
+//  + cooldown so each fires once per episode. Pure — snapshot + prior states
+//  in, next states + fires out. Disk-low already lives in ReminderRules; this
+//  is the "high metric = bad" family. Evaluating per sample (Sampler), the
+//  per-rule state persistence, and posting the notification are integration.
+//
+
+import Foundation
+
+enum ThresholdAlerts {
+    static let rules: [ThresholdRule] = [
+        ThresholdRule(id: "cpu", high: 90, low: 70, cooldownSeconds: 1800),
+        ThresholdRule(id: "memory", high: 90, low: 75, cooldownSeconds: 1800),
+    ]
+
+    /// The metric a rule watches, read out of a snapshot.
+    static func reading(_ ruleID: String, in s: MoleStatus) -> Double? {
+        switch ruleID {
+        case "cpu":    return s.cpu.usage
+        case "memory": return s.memory.usedPercent
+        default:       return nil
+        }
+    }
+
+    struct Fire: Equatable {
+        let ruleID: String
+        let value: Double
+    }
+
+    /// Fold a snapshot through every rule given the prior per-rule states.
+    static func evaluate(_ s: MoleStatus, ts: Int,
+                         states: [String: AlertState]) -> (states: [String: AlertState], fires: [Fire]) {
+        var next = states
+        var fires: [Fire] = []
+        for rule in rules {
+            guard let v = reading(rule.id, in: s) else { continue }
+            let r = AlertEngine.step(rule: rule, value: v, ts: ts, state: states[rule.id] ?? AlertState())
+            next[rule.id] = r.state
+            if r.fired { fires.append(Fire(ruleID: rule.id, value: v)) }
+        }
+        return (next, fires)
+    }
+}
diff --git a/Tests/ThresholdAlertsTests.swift b/Tests/ThresholdAlertsTests.swift
new file mode 100644
index 00000000..d1fd657b
--- /dev/null
+++ b/Tests/ThresholdAlertsTests.swift
@@ -0,0 +1,49 @@
+//
+//  ThresholdAlertsTests.swift
+//  BurrowTests
+//
+//  Threshold-rule orchestration over snapshots (roadmap D.12).
+//
+
+import XCTest
+@testable import Burrow
+
+final class ThresholdAlertsTests: XCTestCase {
+    private func status(cpu: Double, mem: Double) throws -> MoleStatus {
+        let json = """
+        {"collected_at":"2026-06-08T03:16:25.068057-07:00","host":"h","platform":"darwin","uptime_seconds":100,"procs":1,
+         "hardware":{"model":"Mac","cpu_model":"M","total_ram":"24 GB","disk_size":"460 GB","os_version":"26"},
+         "health_score":90,"health_score_msg":"Good",
+         "cpu":{"usage":\(cpu),"load1":1,"load5":1,"load15":1,"core_count":10,"logical_cpu":10},
+         "memory":{"used":100,"total":200,"used_percent":\(mem),"swap_used":0,"swap_total":0,"pressure":""},
+         "disk_io":{"read_rate":0,"write_rate":0},"top_processes":[]}
+        """
+        return try JSONDecoder().decode(MoleStatus.self, from: Data(json.utf8))
+    }
+
+    func testReading_mapsRulesToMetrics() throws {
+        let s = try status(cpu: 42, mem: 55)
+        XCTAssertEqual(ThresholdAlerts.reading("cpu", in: s), 42)
+        XCTAssertEqual(ThresholdAlerts.reading("memory", in: s), 55)
+        XCTAssertNil(ThresholdAlerts.reading("bogus", in: s))
+    }
+
+    func testEvaluate_firesCPUWhenPegged_thenNotWhileStillPegged() throws {
+        let hot = try status(cpu: 95, mem: 50)
+        let r1 = ThresholdAlerts.evaluate(hot, ts: 0, states: [:])
+        XCTAssertEqual(r1.fires.map(\.ruleID), ["cpu"])
+        let r2 = ThresholdAlerts.evaluate(hot, ts: 60, states: r1.states)
+        XCTAssertTrue(r2.fires.isEmpty, "one alert per episode, not per sample")
+    }
+
+    func testEvaluate_quietSnapshot_noFires() throws {
+        let calm = try status(cpu: 20, mem: 40)
+        XCTAssertTrue(ThresholdAlerts.evaluate(calm, ts: 0, states: [:]).fires.isEmpty)
+    }
+
+    func testEvaluate_bothHigh_firesBoth() throws {
+        let bad = try status(cpu: 96, mem: 94)
+        XCTAssertEqual(Set(ThresholdAlerts.evaluate(bad, ts: 0, states: [:]).fires.map(\.ruleID)),
+                       ["cpu", "memory"])
+    }
+}

From 1a054cd0968209a7a4431a0e2b96d785bd46d0c5 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:09:26 -0700
Subject: [PATCH 32/49] feat(alerts): wire threshold alerts into the live
 snapshot stream (D.12)

ThresholdMonitor evaluates ThresholdAlerts on each LiveFeed.applySnapshot,
holding per-rule AlertState and posting via BurrowNotifier.thresholdAlert.
Off-by-default (Store.thresholdAlertsEnabled), inert under XCTest. Completes
D.12's threshold half (watcher half already fires).
---
 Resources/zh-Hans.lproj/Localizable.strings |  4 +++
 Resources/zh-Hant.lproj/Localizable.strings |  4 +++
 Sources/Notifications.swift                 | 18 ++++++++++++
 Sources/SnapshotProducer.swift              |  3 ++
 Sources/Store.swift                         |  7 +++++
 Sources/ThresholdMonitor.swift              | 31 +++++++++++++++++++++
 6 files changed, 67 insertions(+)
 create mode 100644 Sources/ThresholdMonitor.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 134f30fe..8f52e36a 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -302,6 +302,10 @@
 "Quit this process?" = "退出此进程？";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
+"CPU usage is high" = "CPU 使用率过高";
+"CPU has been pegged at %.0f%%." = "CPU 已持续满载于 %.0f%%。";
+"Memory pressure is high" = "内存压力过高";
+"Memory is at %.0f%%." = "内存使用率为 %.0f%%。";
 "Explain" = "解读";
 
 /* Language switch */
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index c60a1721..5f8ea87a 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -302,6 +302,10 @@
 "Quit this process?" = "退出此程序？";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
+"CPU usage is high" = "CPU 使用率過高";
+"CPU has been pegged at %.0f%%." = "CPU 已持續滿載於 %.0f%%。";
+"Memory pressure is high" = "記憶體壓力過高";
+"Memory is at %.0f%%." = "記憶體使用率為 %.0f%%。";
 "Explain" = "解讀";
 
 /* Language switch */
diff --git a/Sources/Notifications.swift b/Sources/Notifications.swift
index 29f84235..3787b5e0 100644
--- a/Sources/Notifications.swift
+++ b/Sources/Notifications.swift
@@ -140,6 +140,24 @@ final class BurrowNotifier: NSObject {
         post(content, id: "burrow-op-\(UUID().uuidString)")
     }
 
+    /// Post a threshold-alert notification (D.12). Called by ThresholdMonitor
+    /// when a CPU/memory rule fires (once per episode).
+    func thresholdAlert(ruleID: String, value: Double) {
+        guard !inert else { return }
+        let title: String, body: String
+        switch ruleID {
+        case "cpu":
+            title = NSLocalizedString("CPU usage is high", comment: "")
+            body = String(format: NSLocalizedString("CPU has been pegged at %.0f%%.", comment: ""), value)
+        case "memory":
+            title = NSLocalizedString("Memory pressure is high", comment: "")
+            body = String(format: NSLocalizedString("Memory is at %.0f%%.", comment: ""), value)
+        default:
+            return
+        }
+        postReminder(title: title, body: body, pane: nil, id: "burrow-threshold-\(ruleID)")
+    }
+
     // MARK: Smart reminders
 
     /// Started once from AppDelegate.startServices. Hourly sweep — each
diff --git a/Sources/SnapshotProducer.swift b/Sources/SnapshotProducer.swift
index 54f3c801..633cfb04 100644
--- a/Sources/SnapshotProducer.swift
+++ b/Sources/SnapshotProducer.swift
@@ -119,6 +119,9 @@ final class LiveFeed: ObservableObject {
         assert(Thread.isMainThread, "LiveFeed must publish on the main thread")
         lastSnapshot = s
         sampledAt = at
+        // Threshold alerts ride the same snapshot stream (D.12) — off by
+        // default, inert under XCTest, so this is a no-op unless opted in.
+        ThresholdMonitor.shared.evaluate(s, at: at)
     }
 
     /// nil rate = no usable delta this tick (first tick, counter reset) —
diff --git a/Sources/Store.swift b/Sources/Store.swift
index 18b16d15..d54c4318 100644
--- a/Sources/Store.swift
+++ b/Sources/Store.swift
@@ -387,6 +387,13 @@ enum Store {
         set { write(newValue, "startup_baseline_json") }
     }
 
+    /// Threshold alerts (CPU pegged / memory pressure high). Off by default —
+    /// a taste thing, like the smart reminders.
+    static var thresholdAlertsEnabled: Bool {
+        get { d.object(forKey: "threshold_alerts_enabled") as? Bool ?? false }
+        set { write(newValue, "threshold_alerts_enabled") }
+    }
+
     // Reminder throttle state (not user-facing): hysteresis flags so a
     // metric hovering at its threshold can't flap, timestamps for the
     // weekly cooldowns. See ReminderRules (Notifications.swift).
diff --git a/Sources/ThresholdMonitor.swift b/Sources/ThresholdMonitor.swift
new file mode 100644
index 00000000..e1df0b7e
--- /dev/null
+++ b/Sources/ThresholdMonitor.swift
@@ -0,0 +1,31 @@
+//
+//  ThresholdMonitor.swift
+//  Burrow
+//
+//  Drives ThresholdAlerts off the live snapshot stream (roadmap D.12): holds
+//  per-rule AlertState across ticks and posts a notification on each fire.
+//  Called from LiveFeed.applySnapshot on the main thread; inert under XCTest
+//  and gated by an off-by-default toggle (threshold alerts are a taste thing,
+//  unlike the default-on disk-low and new-login-item notices).
+//
+
+import Foundation
+
+final class ThresholdMonitor {
+    static let shared = ThresholdMonitor()
+
+    private let inert = Foundation.ProcessInfo.processInfo
+        .environment["XCTestConfigurationFilePath"] != nil
+    private var states: [String: AlertState] = [:]
+
+    private init() {}
+
+    func evaluate(_ s: MoleStatus, at: Date) {
+        guard !inert, Store.thresholdAlertsEnabled else { return }
+        let r = ThresholdAlerts.evaluate(s, ts: Int(at.timeIntervalSince1970), states: states)
+        states = r.states
+        for fire in r.fires {
+            BurrowNotifier.shared.thresholdAlert(ruleID: fire.ruleID, value: fire.value)
+        }
+    }
+}

From 1033c0dcc1e3f761681057bb335ef2ee40b4fd7b Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:12:12 -0700
Subject: [PATCH 33/49] feat(audit): write agent-action audit rows on mutating
 tools (B.5)

call() now dispatches then records a burrow.agent_audit row for the mutating
tools (clean/optimize/uninstall/purge/installer): tool, dry-run flag, duration,
ok, summary, args. Read tools aren't audited. db.insert is serialized + busy-
timed, safe alongside the GUI writer. Tested through dispatch.
---
 Sources/MCP.swift         | 38 +++++++++++++++++++++++++++++++++
 Tests/MCPAuditTests.swift | 45 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 Tests/MCPAuditTests.swift

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index fc9260fa..95c6e2af 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -439,7 +439,45 @@ struct ToolCatalog {
         ]
     }
 
+    /// Public entry: dispatch the tool, then (for mutating tools) leave an
+    /// audit row so a human can see what an agent did (B.5).
     func call(name: String, arguments: [String: Any]) throws -> String {
+        let start = Date()
+        do {
+            let result = try dispatch(name: name, arguments: arguments)
+            if Self.auditedTools.contains(name) {
+                recordAudit(tool: name, arguments: arguments, ok: true, summary: result, since: start)
+            }
+            return result
+        } catch {
+            if Self.auditedTools.contains(name) {
+                recordAudit(tool: name, arguments: arguments, ok: false, summary: "\(error)", since: start)
+            }
+            throw error
+        }
+    }
+
+    /// The mutating tools whose use we record. Read-only tools aren't audited
+    /// — no action taken, and it would bloat the log (and the reader list).
+    static let auditedTools: Set<String> = [
+        "burrow_clean", "burrow_optimize", "burrow_uninstall", "burrow_purge", "burrow_installer",
+    ]
+
+    private func recordAudit(tool: String, arguments: [String: Any], ok: Bool, summary: String, since: Date) {
+        let argsJSON = (try? JSONSerialization.data(withJSONObject: arguments, options: [.sortedKeys]))
+            .flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
+        let entry = AgentAudit.Entry(
+            tool: tool, client: "mcp",
+            dryRun: (arguments["confirm"] as? Bool) != true,
+            durationMs: Int(Date().timeIntervalSince(since) * 1000),
+            ok: ok, summary: String(summary.prefix(200)), argsJSON: argsJSON)
+        // db.insert is serialized (writeQueue) with a busy timeout, so this is
+        // safe alongside the GUI sampler's writes.
+        try? db.insert(prefix: AgentAudit.prefix, ts: Int(Date().timeIntervalSince1970),
+                       json: AgentAudit.encode(entry))
+    }
+
+    private func dispatch(name: String, arguments: [String: Any]) throws -> String {
         switch name {
         case "burrow_snapshot":
             return self.callSnapshot()
diff --git a/Tests/MCPAuditTests.swift b/Tests/MCPAuditTests.swift
new file mode 100644
index 00000000..aa245ab7
--- /dev/null
+++ b/Tests/MCPAuditTests.swift
@@ -0,0 +1,45 @@
+//
+//  MCPAuditTests.swift
+//  BurrowTests
+//
+//  Agent-action audit rows (roadmap B.5): a mutating tool leaves a
+//  burrow.agent_audit row through the real dispatch path; a read tool doesn't.
+//
+
+import XCTest
+@testable import Burrow
+
+final class MCPAuditTests: XCTestCase {
+    private var tempDir: URL!
+    private var db: DB!
+    private var catalog: ToolCatalog!
+
+    override func setUpWithError() throws {
+        tempDir = FileManager.default.temporaryDirectory
+            .appendingPathComponent("burrow-audit-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true)
+        db = try DB(at: tempDir.appendingPathComponent("burrow.db"))
+        catalog = ToolCatalog(db: db)
+    }
+
+    override func tearDown() {
+        db = nil
+        try? FileManager.default.removeItem(at: tempDir)
+        Store.d.removePersistentDomain(forName: StoreTests.scratchSuite)
+        Store.d = .standard
+    }
+
+    func testMutatingTool_leavesAuditRow() throws {
+        _ = try? catalog.call(name: "burrow_clean", arguments: ["confirm": false])
+        let row = try XCTUnwrap(db.findLatest(prefix: AgentAudit.prefix), "a mutating tool must audit")
+        let entry = try XCTUnwrap(AgentAudit.decode(row.json))
+        XCTAssertEqual(entry.tool, "burrow_clean")
+        XCTAssertTrue(entry.dryRun, "confirm:false is a dry run")
+        XCTAssertEqual(entry.client, "mcp")
+    }
+
+    func testReadTool_doesNotAudit() throws {
+        _ = try catalog.call(name: "burrow_snapshot", arguments: [:])
+        XCTAssertNil(db.findLatest(prefix: AgentAudit.prefix), "read tools take no action → no audit row")
+    }
+}

From 3f53c4ffee5d06ee33881134d02ba996be25298b Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:16:20 -0700
Subject: [PATCH 34/49] fix(alerts): hop threshold post to main actor; surface
 anomalies in report (A.2)

ThresholdMonitor posts via Task { @MainActor } (thresholdAlert is main-actor
isolated). AnomalyScan.scan pulls recent-24h vs prior-14d per-process CPU;
ReportComposer folds findings into the report's new Changes section. Tested.
---
 Sources/AnomalyScan.swift       | 10 ++++++++++
 Sources/ReportComposer.swift    |  3 ++-
 Sources/ThresholdMonitor.swift  |  6 +++++-
 Sources/WeeklyReport.swift      | 10 ++++++++++
 Tests/ReportComposerTests.swift | 21 +++++++++++++++++++--
 Tests/WeeklyReportTests.swift   | 12 ++++++++++++
 6 files changed, 58 insertions(+), 4 deletions(-)

diff --git a/Sources/AnomalyScan.swift b/Sources/AnomalyScan.swift
index a0b1e240..8cfae7d8 100644
--- a/Sources/AnomalyScan.swift
+++ b/Sources/AnomalyScan.swift
@@ -19,6 +19,16 @@ enum AnomalyScan {
         let baselineMedian: Double
     }
 
+    /// Convenience: pull recent (last 24h) vs baseline (prior 14d) per-process
+    /// CPU from the store and flag regressions. The window split the roadmap
+    /// specifies for A.2.
+    static func scan(metrics: MetricsStore, now: Int) -> [Finding] {
+        let day = 86_400
+        let recent = metrics.processCPUSamples(.init(since: now - day, until: now))
+        let baseline = metrics.processCPUSamples(.init(since: now - 15 * day, until: now - day))
+        return cpuFindings(baseline: baseline, recent: recent)
+    }
+
     /// Flag every process whose recent CPU clears its own baseline per the
     /// Anomaly rule, worst (highest recent median) first.
     static func cpuFindings(baseline: [String: [Double]],
diff --git a/Sources/ReportComposer.swift b/Sources/ReportComposer.swift
index 4bc06aef..e4f1166e 100644
--- a/Sources/ReportComposer.swift
+++ b/Sources/ReportComposer.swift
@@ -20,6 +20,7 @@ enum ReportComposer {
             .map { (name: $0.name, cpuSeconds: $0.estCPUSeconds) }
         return WeeklyReport.Input(periodDays: days, spaceReclaimedBytes: nil,
                                   topEnergy: top, newLoginItems: [],
-                                  batteryHealthDeltaPct: nil, forecast: forecast)
+                                  batteryHealthDeltaPct: nil, forecast: forecast,
+                                  anomalies: AnomalyScan.scan(metrics: metrics, now: now))
     }
 }
diff --git a/Sources/ThresholdMonitor.swift b/Sources/ThresholdMonitor.swift
index e1df0b7e..0463693b 100644
--- a/Sources/ThresholdMonitor.swift
+++ b/Sources/ThresholdMonitor.swift
@@ -25,7 +25,11 @@ final class ThresholdMonitor {
         let r = ThresholdAlerts.evaluate(s, ts: Int(at.timeIntervalSince1970), states: states)
         states = r.states
         for fire in r.fires {
-            BurrowNotifier.shared.thresholdAlert(ruleID: fire.ruleID, value: fire.value)
+            // thresholdAlert is main-actor-isolated; hop to it (we're already
+            // on main, but evaluate is statically nonisolated).
+            Task { @MainActor in
+                BurrowNotifier.shared.thresholdAlert(ruleID: fire.ruleID, value: fire.value)
+            }
         }
     }
 }
diff --git a/Sources/WeeklyReport.swift b/Sources/WeeklyReport.swift
index af8f7505..5b45e01b 100644
--- a/Sources/WeeklyReport.swift
+++ b/Sources/WeeklyReport.swift
@@ -21,6 +21,8 @@ enum WeeklyReport {
         /// Negative = health declined since the period start; nil = unknown.
         var batteryHealthDeltaPct: Double?
         var forecast: DiskForecast.Projection?
+        /// Regressed processes from AnomalyScan (A.2); empty = nothing flagged.
+        var anomalies: [AnomalyScan.Finding] = []
     }
 
     static func markdown(_ i: Input) -> String {
@@ -54,6 +56,14 @@ enum WeeklyReport {
             out += "## Battery\n- Health down **\(String(format: "%.1f", -d))%** since the period start.\n\n"
         }
 
+        if !i.anomalies.isEmpty {
+            out += "## Changes\nProcesses using notably more CPU than their recent baseline:\n"
+            for a in i.anomalies.prefix(5) {
+                out += "- \(a.process) — now ~\(Int(a.recentMedian.rounded()))% CPU (was ~\(Int(a.baselineMedian.rounded()))%)\n"
+            }
+            out += "\n"
+        }
+
         // Persistence items that appeared this period — a light security note.
         if !i.newLoginItems.isEmpty {
             out += "## New startup items\nThese now launch automatically and appeared this period:\n"
diff --git a/Tests/ReportComposerTests.swift b/Tests/ReportComposerTests.swift
index 2766a58b..e4049889 100644
--- a/Tests/ReportComposerTests.swift
+++ b/Tests/ReportComposerTests.swift
@@ -25,7 +25,7 @@ final class ReportComposerTests: XCTestCase {
         try? FileManager.default.removeItem(at: tempDir)
     }
 
-    private func snapshot(freeGB: Int64, proc: String) -> String {
+    private func snapshot(freeGB: Int64, proc: String, cpu: Double = 80) -> String {
         let total: Int64 = 500_000_000_000
         let used = total - freeGB * 1_000_000_000
         return """
@@ -36,7 +36,7 @@ final class ReportComposerTests: XCTestCase {
          "memory":{"used":100,"total":200,"used_percent":50,"swap_used":0,"swap_total":0,"pressure":""},
          "disk_io":{"read_rate":0,"write_rate":0},
          "disks":[{"mount":"/","used":\(used),"total":\(total),"used_percent":50,"external":false}],
-         "top_processes":[{"pid":1,"name":"\(proc)","command":"/bin/\(proc)","cpu":80,"memory":5}]}
+         "top_processes":[{"pid":1,"name":"\(proc)","command":"/bin/\(proc)","cpu":\(cpu),"memory":5}]}
         """
     }
 
@@ -54,4 +54,21 @@ final class ReportComposerTests: XCTestCase {
         XCTAssertNotNil(input.forecast?.daysUntilFull, "steady decline yields a forecast")
         XCTAssertEqual(input.topEnergy.first?.name, "xcode")
     }
+
+    func testGather_includesAnomalies() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let day = 86_400
+        // Baseline window (prior 14d): "hog" idles low.
+        for k in 0..<8 {
+            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 10 * day - k * 60,
+                          json: snapshot(freeGB: 100, proc: "hog", cpu: 5))
+        }
+        // Recent window (last 24h): "hog" is pegged.
+        for k in 0..<8 {
+            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 3600 - k * 60,
+                          json: snapshot(freeGB: 100, proc: "hog", cpu: 60))
+        }
+        let input = ReportComposer.gather(metrics: MetricsStore(db: db), days: 7, now: now)
+        XCTAssertTrue(input.anomalies.contains { $0.process == "hog" }, "a regressed process is flagged")
+    }
 }
diff --git a/Tests/WeeklyReportTests.swift b/Tests/WeeklyReportTests.swift
index 3eb3d083..43728765 100644
--- a/Tests/WeeklyReportTests.swift
+++ b/Tests/WeeklyReportTests.swift
@@ -71,6 +71,18 @@ final class WeeklyReportTests: XCTestCase {
         XCTAssertFalse(WeeklyReport.markdown(base()).contains("New startup items"))
     }
 
+    func testMarkdown_anomalies_rendersChangesSection() {
+        var i = base()
+        i.anomalies = [.init(process: "WindowServer", recentMedian: 45, baselineMedian: 20)]
+        let md = WeeklyReport.markdown(i)
+        XCTAssertTrue(md.contains("## Changes"))
+        XCTAssertTrue(md.contains("WindowServer"))
+    }
+
+    func testMarkdown_noAnomalies_omitsChangesSection() {
+        XCTAssertFalse(WeeklyReport.markdown(base()).contains("## Changes"))
+    }
+
     func testMarkdown_batteryDecline_shown_butImprovementHidden() {
         var i = base(); i.batteryHealthDeltaPct = -2.5
         XCTAssertTrue(WeeklyReport.markdown(i).contains("Health down"))

From 7e2a2e2a50092f1af08e734f2b6b72963ce546a8 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:18:06 -0700
Subject: [PATCH 35/49] feat(hygiene): stage-2 per-item Clear-to-Trash (C.9)

Confirm-gated Move-to-Trash on each Dev Hygiene cache row, then re-scan.
Compile-verified; needs hand-test (real Trash move).
---
 Resources/zh-Hans.lproj/Localizable.strings |  2 ++
 Resources/zh-Hant.lproj/Localizable.strings |  2 ++
 Sources/DevHygieneView.swift                | 17 +++++++++++++++++
 3 files changed, 21 insertions(+)

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 8f52e36a..8da380f3 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -295,6 +295,8 @@
 "Diagnostics" = "系统诊断";
 "Dev hygiene" = "开发清理";
 "No developer caches found." = "未发现开发者缓存。";
+"Clear" = "清理";
+"Move this cache to the Trash?" = "将此缓存移到废纸篓？";
 "ports" = "端口";
 "Ports" = "端口";
 "Listening ports" = "监听端口";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 5f8ea87a..bb8eb818 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -295,6 +295,8 @@
 "Diagnostics" = "系統診斷";
 "Dev hygiene" = "開發清理";
 "No developer caches found." = "未發現開發者快取。";
+"Clear" = "清理";
+"Move this cache to the Trash?" = "將此快取移到垃圾桶？";
 "ports" = "連接埠";
 "Ports" = "連接埠";
 "Listening ports" = "監聽連接埠";
diff --git a/Sources/DevHygieneView.swift b/Sources/DevHygieneView.swift
index ea0f3ed7..90e85ea4 100644
--- a/Sources/DevHygieneView.swift
+++ b/Sources/DevHygieneView.swift
@@ -25,6 +25,7 @@ struct DevHygieneView: View {
 
     @State private var rows: [Row] = []
     @State private var scanning = true
+    @State private var clearTarget: Row?
 
     var body: some View {
         ScrollView {
@@ -51,6 +52,8 @@ struct DevHygieneView: View {
                         } label: { Image(systemName: "magnifyingglass") }
                             .buttonStyle(.plain)
                             .help(NSLocalizedString("Reveal in Finder", comment: ""))
+                        Button(NSLocalizedString("Clear", comment: "")) { clearTarget = r }
+                            .buttonStyle(.bordered)
                     }
                 }
             }
@@ -58,6 +61,20 @@ struct DevHygieneView: View {
             .padding(20)
         }
         .task { await scan() }
+        .confirmationDialog(
+            NSLocalizedString("Move this cache to the Trash?", comment: ""),
+            isPresented: Binding(get: { clearTarget != nil },
+                                 set: { if !$0 { clearTarget = nil } }),
+            presenting: clearTarget
+        ) { r in
+            Button(NSLocalizedString("Move to Trash", comment: ""), role: .destructive) {
+                try? FileManager.default.trashItem(at: URL(fileURLWithPath: r.path), resultingItemURL: nil)
+                Task { await scan() }
+            }
+            Button(NSLocalizedString("Cancel", comment: ""), role: .cancel) {}
+        } message: { r in
+            Text("\(r.ecosystem) — \(Fmt.bytes(r.bytes))\n\(r.path)")
+        }
     }
 
     private func scan() async {

From 8e6ec65719879b9f9cf2997ae7a4d0accfc23b93 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:21:33 -0700
Subject: [PATCH 36/49] feat(tuneup): Tune-Up Tool pane (#77)

New .tuneup Tool gathering safe (cache-clear) + review (startup) recommendations
via TuneUp's tested selection logic, with a one-click Run-safe-set (trashes
caches). Shared DevHygiene.directorySize. zh added. Compile-verified; hand-test.
---
 Resources/zh-Hans.lproj/Localizable.strings |   9 ++
 Resources/zh-Hant.lproj/Localizable.strings |   9 ++
 Sources/DevHygiene.swift                    |  14 +++
 Sources/DevHygieneView.swift                |  15 +--
 Sources/RootView.swift                      |   1 +
 Sources/Tool.swift                          |   9 +-
 Sources/TuneUpView.swift                    | 109 ++++++++++++++++++++
 7 files changed, 150 insertions(+), 16 deletions(-)
 create mode 100644 Sources/TuneUpView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 8da380f3..9889e08d 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -302,6 +302,15 @@
 "Listening ports" = "监听端口";
 "See who's listening." = "看看谁在监听。";
 "Quit this process?" = "退出此进程？";
+"tuneup" = "调优";
+"Tune-Up" = "调优";
+"One pass, a tidier den." = "一次整理，洞穴更整洁。";
+"Safe to run" = "可安全执行";
+"Needs review" = "需要审查";
+"Run safe set" = "执行安全项";
+"Clear %@ cache" = "清理 %@ 缓存";
+"Review startup item: %@" = "审查启动项：%@";
+"Nothing to tune up — you're clean." = "没有需要调优的内容——很干净。";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "CPU usage is high" = "CPU 使用率过高";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index bb8eb818..64230d3d 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -302,6 +302,15 @@
 "Listening ports" = "監聽連接埠";
 "See who's listening." = "看看誰在監聽。";
 "Quit this process?" = "退出此程序？";
+"tuneup" = "調校";
+"Tune-Up" = "調校";
+"One pass, a tidier den." = "一次整理，洞穴更整潔。";
+"Safe to run" = "可安全執行";
+"Needs review" = "需要審查";
+"Run safe set" = "執行安全項";
+"Clear %@ cache" = "清理 %@ 快取";
+"Review startup item: %@" = "審查啟動項：%@";
+"Nothing to tune up — you're clean." = "沒有需要調校的內容——很乾淨。";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "CPU usage is high" = "CPU 使用率過高";
diff --git a/Sources/DevHygiene.swift b/Sources/DevHygiene.swift
index 35d80539..3a0f7533 100644
--- a/Sources/DevHygiene.swift
+++ b/Sources/DevHygiene.swift
@@ -42,4 +42,18 @@ enum DevHygiene {
     }
 
     static func total(_ sizes: [Int64]) -> Int64 { sizes.reduce(0, +) }
+
+    /// Recursive allocated size of a directory (0 if absent/unreadable). FS
+    /// work — call off the main thread. Shared by the hygiene + Tune-Up panes.
+    static func directorySize(_ path: String) -> Int64 {
+        let url = URL(fileURLWithPath: path)
+        let keys: Set<URLResourceKey> = [.totalFileAllocatedSizeKey, .fileAllocatedSizeKey]
+        guard let en = FileManager.default.enumerator(at: url, includingPropertiesForKeys: Array(keys)) else { return 0 }
+        var total: Int64 = 0
+        for case let file as URL in en {
+            let v = try? file.resourceValues(forKeys: keys)
+            total += Int64(v?.totalFileAllocatedSize ?? v?.fileAllocatedSize ?? 0)
+        }
+        return total
+    }
 }
diff --git a/Sources/DevHygieneView.swift b/Sources/DevHygieneView.swift
index 90e85ea4..43893077 100644
--- a/Sources/DevHygieneView.swift
+++ b/Sources/DevHygieneView.swift
@@ -83,7 +83,7 @@ struct DevHygieneView: View {
             var out: [Row] = []
             for eco in DevHygiene.catalog(home: home) {
                 for path in eco.paths where FileManager.default.fileExists(atPath: path) {
-                    let bytes = Self.directorySize(path)
+                    let bytes = DevHygiene.directorySize(path)
                     if bytes > 0 { out.append(Row(ecosystem: eco.name, path: path, bytes: bytes)) }
                 }
             }
@@ -92,17 +92,4 @@ struct DevHygieneView: View {
         rows = found
         scanning = false
     }
-
-    /// Recursive allocated size of a directory. Off-main only.
-    private static func directorySize(_ path: String) -> Int64 {
-        let url = URL(fileURLWithPath: path)
-        let keys: Set<URLResourceKey> = [.totalFileAllocatedSizeKey, .fileAllocatedSizeKey]
-        guard let en = FileManager.default.enumerator(at: url, includingPropertiesForKeys: Array(keys)) else { return 0 }
-        var total: Int64 = 0
-        for case let file as URL in en {
-            let v = try? file.resourceValues(forKeys: keys)
-            total += Int64(v?.totalFileAllocatedSize ?? v?.fileAllocatedSize ?? 0)
-        }
-        return total
-    }
 }
diff --git a/Sources/RootView.swift b/Sources/RootView.swift
index c2dc6049..a9a1f6d1 100644
--- a/Sources/RootView.swift
+++ b/Sources/RootView.swift
@@ -138,6 +138,7 @@ struct RootView: View {
             CleanHub().tabVisible(pane == .tool(.clean))
             OptimizeView().tabVisible(pane == .tool(.optimize))
             PortsView().tabVisible(pane == .tool(.ports))
+            TuneUpView().tabVisible(pane == .tool(.tuneup))
 
             // Gated on window visibility too: these two carry live timers
             // (2 s polls, 15 s DB reads) that must stop when the window
diff --git a/Sources/Tool.swift b/Sources/Tool.swift
index 52d9fa06..a4a80f21 100644
--- a/Sources/Tool.swift
+++ b/Sources/Tool.swift
@@ -12,7 +12,7 @@
 import SwiftUI
 
 enum Tool: String, CaseIterable, Identifiable {
-    case clean, purge, installer, apps, optimize, analyze, status, ports
+    case clean, purge, installer, apps, optimize, analyze, status, ports, tuneup
 
     var id: String { rawValue }
 
@@ -21,7 +21,7 @@ enum Tool: String, CaseIterable, Identifiable {
     /// optimize, then apps / analyze. The .purge/.installer cases live on for
     /// the hub cards, MCP actions, and Explain deep-links. The live dashboard
     /// isn't a tool anymore — it's Home, reached by the Burrow mark.
-    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze, .ports]
+    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze, .ports, .tuneup]
 
     /// Lowercase tab label (matches the instrument-panel voice).
     var label: String { NSLocalizedString(rawValue, comment: "") }
@@ -37,6 +37,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .analyze:   return NSLocalizedString("Analyze", comment: "")
         case .status:    return NSLocalizedString("Status", comment: "")
         case .ports:     return NSLocalizedString("Ports", comment: "")
+        case .tuneup:    return NSLocalizedString("Tune-Up", comment: "")
         }
     }
 
@@ -50,6 +51,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .analyze:   return "square.grid.2x2"
         case .status:    return "waveform.path.ecg"
         case .ports:     return "network"
+        case .tuneup:    return "slider.horizontal.3"
         }
     }
 
@@ -64,6 +66,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .analyze:   return Color(hex: 0x4FA3E3) // azure
         case .status:    return Color(hex: 0xE6A93C) // gold
         case .ports:     return Color(hex: 0xB58BD6) // lilac
+        case .tuneup:    return Color(hex: 0x5AA98B) // sage
         }
     }
 
@@ -79,6 +82,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .analyze:   return Color(hex: 0x0E1F2E)
         case .status:    return Color(hex: 0x241D11)
         case .ports:     return Color(hex: 0x1B1426)
+        case .tuneup:    return Color(hex: 0x12231D)
         }
     }
 
@@ -99,6 +103,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .analyze:   return NSLocalizedString("Map every chamber below.", comment: "")
         case .status:    return NSLocalizedString("Every pulse of the den.", comment: "")
         case .ports:     return NSLocalizedString("See who's listening.", comment: "")
+        case .tuneup:    return NSLocalizedString("One pass, a tidier den.", comment: "")
         }
     }
 }
diff --git a/Sources/TuneUpView.swift b/Sources/TuneUpView.swift
new file mode 100644
index 00000000..e19766da
--- /dev/null
+++ b/Sources/TuneUpView.swift
@@ -0,0 +1,109 @@
+//
+//  TuneUpView.swift
+//  Burrow
+//
+//  Tune-Up pane (roadmap F / #77): gathers recommendations, splits them into a
+//  one-click *safe set* (reversible cache clears) and a *review set*
+//  (destructive / behaviour-changing, e.g. startup items), via the tested
+//  TuneUp selection logic. v1 sources: dev-ecosystem caches + controllable
+//  startup items.
+//
+//  NOTE (hand-test): compile-verified only. Verify the scan, the reclaimable
+//  total, and that "Run safe set" only trashes caches (reversible).
+//
+
+import SwiftUI
+import AppKit
+
+struct TuneUpView: View {
+    private struct Row: Identifiable {
+        let id = UUID()
+        let rec: TuneUp.Recommendation
+        let path: String?   // freeCache rows carry the dir to trash
+    }
+
+    @State private var rows: [Row] = []
+    @State private var scanning = true
+
+    var body: some View {
+        let safeRows = rows.filter { $0.rec.safe }
+        let reviewRows = rows.filter { !$0.rec.safe }
+        ScrollView {
+            VStack(alignment: .leading, spacing: 12) {
+                Text(NSLocalizedString("Tune-Up", comment: "")).font(.title2.bold())
+                if scanning { ProgressView().controlSize(.small) }
+
+                if !safeRows.isEmpty {
+                    HStack {
+                        Text(NSLocalizedString("Safe to run", comment: "")).font(.headline)
+                        Spacer()
+                        Text(Fmt.bytes(TuneUp.reclaimable(safeRows.map(\.rec))))
+                            .font(.body.monospacedDigit()).foregroundStyle(.secondary)
+                    }
+                    ForEach(safeRows) { row($0) }
+                    Button(NSLocalizedString("Run safe set", comment: "")) { runSafe(safeRows) }
+                        .buttonStyle(.borderedProminent).padding(.top, 4)
+                }
+
+                if !reviewRows.isEmpty {
+                    Text(NSLocalizedString("Needs review", comment: "")).font(.headline).padding(.top, 10)
+                    ForEach(reviewRows) { row($0) }
+                }
+
+                if !scanning, rows.isEmpty {
+                    Text(NSLocalizedString("Nothing to tune up — you're clean.", comment: ""))
+                        .foregroundStyle(.secondary)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { await gather() }
+    }
+
+    @ViewBuilder private func row(_ r: Row) -> some View {
+        HStack {
+            Text(r.rec.title)
+            Spacer()
+            if r.rec.bytes > 0 {
+                Text(Fmt.bytes(r.rec.bytes)).font(.body.monospacedDigit()).foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private func gather() async {
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        let found = await Task.detached(priority: .utility) { () -> [Row] in
+            var out: [Row] = []
+            for eco in DevHygiene.catalog(home: home) {
+                for path in eco.paths where FileManager.default.fileExists(atPath: path) {
+                    let bytes = DevHygiene.directorySize(path)
+                    if bytes > 200_000_000 {  // only surface caches worth clearing
+                        out.append(Row(rec: .init(
+                            kind: .freeCache,
+                            title: String(format: NSLocalizedString("Clear %@ cache", comment: ""), eco.name),
+                            bytes: bytes), path: path))
+                    }
+                }
+            }
+            for item in StartupInventory.scanLive() where item.controllable {
+                out.append(Row(rec: .init(
+                    kind: .disableStartupItem,
+                    title: String(format: NSLocalizedString("Review startup item: %@", comment: ""), item.label),
+                    bytes: 0), path: nil))
+            }
+            return out.sorted { $0.rec.bytes > $1.rec.bytes }
+        }.value
+        rows = found
+        scanning = false
+    }
+
+    private func runSafe(_ safeRows: [Row]) {
+        for r in safeRows {
+            if let p = r.path {
+                try? FileManager.default.trashItem(at: URL(fileURLWithPath: p), resultingItemURL: nil)
+            }
+        }
+        Task { await gather() }
+    }
+}

From 4d89e941fec89fbc5c63c795419b74cc16475c88 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 12:25:12 -0700
Subject: [PATCH 37/49] test(anomaly): space seeded rows past the query
 down-sample stride

findRangeSampled buckets by (ts-since)/stride; 60s-apart rows collapsed to one
sample, below the 5-sample minimum. Spread baseline 2h / recent 10min apart so
8 survive each window. Feature was correct; the fixture clustered.
---
 Tests/ReportComposerTests.swift | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/Tests/ReportComposerTests.swift b/Tests/ReportComposerTests.swift
index e4049889..e79522c6 100644
--- a/Tests/ReportComposerTests.swift
+++ b/Tests/ReportComposerTests.swift
@@ -58,17 +58,22 @@ final class ReportComposerTests: XCTestCase {
     func testGather_includesAnomalies() throws {
         let now = Int(Date().timeIntervalSince1970)
         let day = 86_400
-        // Baseline window (prior 14d): "hog" idles low.
+        // Rows must be spaced wider than the query's down-sample stride
+        // (~28 min over a 14-day baseline, ~2 min over 24h) or they collapse
+        // into one bucket. Baseline (prior 14d): "hog" idles low, 2h apart.
         for k in 0..<8 {
-            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 10 * day - k * 60,
+            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 5 * day + k * 7200,
                           json: snapshot(freeGB: 100, proc: "hog", cpu: 5))
         }
-        // Recent window (last 24h): "hog" is pegged.
+        // Recent (last 24h): "hog" is pegged, 10 min apart.
         for k in 0..<8 {
-            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 3600 - k * 60,
+            try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now - 600 - k * 600,
                           json: snapshot(freeGB: 100, proc: "hog", cpu: 60))
         }
-        let input = ReportComposer.gather(metrics: MetricsStore(db: db), days: 7, now: now)
-        XCTAssertTrue(input.anomalies.contains { $0.process == "hog" }, "a regressed process is flagged")
+        let found = AnomalyScan.scan(metrics: MetricsStore(db: db), now: now)
+        XCTAssertTrue(found.contains { $0.process == "hog" },
+                      "scan returned: \(found.map { "\($0.process) \($0.recentMedian)/\($0.baselineMedian)" })")
+        XCTAssertTrue(ReportComposer.gather(metrics: MetricsStore(db: db), days: 7, now: now)
+            .anomalies.contains { $0.process == "hog" })
     }
 }

From ce50af3a1a9fb006452b701e0d039e5d6512a9d0 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 20:46:15 -0700
Subject: [PATCH 38/49] feat(restore): Restore-last-cleanup Tool pane (D.13)

RestorePlan.parseLog turns Mole's deletion log into restore candidates;
RestoreView builds the plan and offers a ~/.Trash put-back per Trash-based
item (caches shown locked, permanent). New .restore Tool. parseLog tested;
the Trash move is compile-verified, needs hand-test.
---
 Resources/zh-Hans.lproj/Localizable.strings |  6 ++
 Resources/zh-Hant.lproj/Localizable.strings |  6 ++
 Sources/RestorePlan.swift                   | 13 ++++
 Sources/RestoreView.swift                   | 81 +++++++++++++++++++++
 Sources/RootView.swift                      |  1 +
 Sources/Tool.swift                          |  9 ++-
 Tests/RestorePlanTests.swift                | 15 ++++
 7 files changed, 129 insertions(+), 2 deletions(-)
 create mode 100644 Sources/RestoreView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 9889e08d..e5660fb9 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -311,6 +311,12 @@
 "Clear %@ cache" = "清理 %@ 缓存";
 "Review startup item: %@" = "审查启动项：%@";
 "Nothing to tune up — you're clean." = "没有需要调优的内容——很干净。";
+"restore" = "恢复";
+"Restore" = "恢复";
+"Put back what the last clean moved." = "把上次清理移走的放回原处。";
+"Restore last cleanup" = "恢复上次清理";
+"Only Trash-based removals can be restored — cache deletions are permanent." = "仅可恢复移到废纸篓的项目——缓存删除是永久性的。";
+"No restorable items found." = "未找到可恢复的项目。";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "CPU usage is high" = "CPU 使用率过高";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 64230d3d..e96357b0 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -311,6 +311,12 @@
 "Clear %@ cache" = "清理 %@ 快取";
 "Review startup item: %@" = "審查啟動項：%@";
 "Nothing to tune up — you're clean." = "沒有需要調校的內容——很乾淨。";
+"restore" = "復原";
+"Restore" = "復原";
+"Put back what the last clean moved." = "把上次清理移走的放回原處。";
+"Restore last cleanup" = "復原上次清理";
+"Only Trash-based removals can be restored — cache deletions are permanent." = "僅可復原移到垃圾桶的項目——快取刪除是永久性的。";
+"No restorable items found." = "未找到可復原的項目。";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "CPU usage is high" = "CPU 使用率過高";
diff --git a/Sources/RestorePlan.swift b/Sources/RestorePlan.swift
index 13ceeda1..7189cde1 100644
--- a/Sources/RestorePlan.swift
+++ b/Sources/RestorePlan.swift
@@ -44,4 +44,17 @@ enum RestorePlan {
 
     /// Convenience: how many of a plan can actually be restored.
     static func restorableCount(_ plan: [Entry]) -> Int { plan.filter(\.restorable).count }
+
+    /// Parse Mole's tab-separated deletion log (`ts\taction\tcategory\tstatus\tpath`)
+    /// into restore candidates: entries that succeeded (`status == "ok"`),
+    /// newest first. The path is the remainder so an embedded tab survives.
+    static func parseLog(_ text: String) -> [Item] {
+        var out: [Item] = []
+        for line in text.split(separator: "\n", omittingEmptySubsequences: true) {
+            let p = line.split(separator: "\t", maxSplits: 4, omittingEmptySubsequences: false).map(String.init)
+            guard p.count >= 5, p[3] == "ok" else { continue }
+            out.append(Item(originalPath: p[4], action: p[1]))
+        }
+        return out.reversed()
+    }
 }
diff --git a/Sources/RestoreView.swift b/Sources/RestoreView.swift
new file mode 100644
index 00000000..8e2d3fb8
--- /dev/null
+++ b/Sources/RestoreView.swift
@@ -0,0 +1,81 @@
+//
+//  RestoreView.swift
+//  Burrow
+//
+//  "Restore last cleanup" pane (roadmap D.13). Reads Mole's deletion log,
+//  builds a RestorePlan, and offers to put each Trash-based removal back.
+//  Honest by construction: cache deletions (action "remove") are permanent and
+//  shown locked; only trashed items with a free original path are restorable.
+//
+//  NOTE (hand-test): compile-verified only. Verify against a real cleanup —
+//  the ~/.Trash fallback move and collision handling need a live Trash.
+//
+
+import SwiftUI
+
+struct RestoreView: View {
+    private struct Row: Identifiable { let id = UUID(); let entry: RestorePlan.Entry }
+
+    @State private var rows: [Row] = []
+    @State private var loading = true
+
+    private var logPath: String {
+        (NSHomeDirectory() as NSString).appendingPathComponent("Library/Logs/mole/deletions.log")
+    }
+
+    var body: some View {
+        ScrollView {
+            VStack(alignment: .leading, spacing: 10) {
+                Text(NSLocalizedString("Restore last cleanup", comment: "")).font(.title2.bold())
+                Text(NSLocalizedString("Only Trash-based removals can be restored — cache deletions are permanent.", comment: ""))
+                    .font(.caption).foregroundStyle(.secondary)
+                if loading { ProgressView().controlSize(.small) }
+                ForEach(rows) { r in
+                    HStack(spacing: 10) {
+                        Image(systemName: r.entry.restorable ? "arrow.uturn.backward.circle" : "lock.circle")
+                            .foregroundStyle(r.entry.restorable ? Color.green : Color.secondary)
+                        VStack(alignment: .leading, spacing: 2) {
+                            Text((r.entry.path as NSString).lastPathComponent).font(.headline)
+                            Text(r.entry.reason).font(.caption).foregroundStyle(.secondary)
+                        }
+                        Spacer()
+                        if r.entry.restorable {
+                            Button(NSLocalizedString("Restore", comment: "")) { restore(r.entry) }
+                                .buttonStyle(.bordered)
+                        }
+                    }
+                }
+                if !loading, rows.isEmpty {
+                    Text(NSLocalizedString("No restorable items found.", comment: "")).foregroundStyle(.secondary)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(20)
+        }
+        .task { await reload() }
+    }
+
+    private func reload() async {
+        let path = logPath
+        let entries = await Task.detached(priority: .utility) { () -> [RestorePlan.Entry] in
+            let text = (try? String(contentsOfFile: path, encoding: .utf8)) ?? ""
+            let items = RestorePlan.parseLog(text)
+            return RestorePlan.build(items, existsAtOriginal: { FileManager.default.fileExists(atPath: $0) })
+        }.value
+        rows = entries.map { Row(entry: $0) }
+        loading = false
+    }
+
+    /// Fallback restore: find the item by name in ~/.Trash and move it back to
+    /// its recorded origin, skipping on collision. (Finder "put back" needs
+    /// Finder's own metadata; this works without it.)
+    private func restore(_ entry: RestorePlan.Entry) {
+        let name = (entry.path as NSString).lastPathComponent
+        let trashed = (NSHomeDirectory() as NSString).appendingPathComponent(".Trash/\(name)")
+        let fm = FileManager.default
+        if fm.fileExists(atPath: trashed), !fm.fileExists(atPath: entry.path) {
+            try? fm.moveItem(atPath: trashed, toPath: entry.path)
+        }
+        Task { await reload() }
+    }
+}
diff --git a/Sources/RootView.swift b/Sources/RootView.swift
index a9a1f6d1..93f21e1b 100644
--- a/Sources/RootView.swift
+++ b/Sources/RootView.swift
@@ -139,6 +139,7 @@ struct RootView: View {
             OptimizeView().tabVisible(pane == .tool(.optimize))
             PortsView().tabVisible(pane == .tool(.ports))
             TuneUpView().tabVisible(pane == .tool(.tuneup))
+            RestoreView().tabVisible(pane == .tool(.restore))
 
             // Gated on window visibility too: these two carry live timers
             // (2 s polls, 15 s DB reads) that must stop when the window
diff --git a/Sources/Tool.swift b/Sources/Tool.swift
index a4a80f21..501449d0 100644
--- a/Sources/Tool.swift
+++ b/Sources/Tool.swift
@@ -12,7 +12,7 @@
 import SwiftUI
 
 enum Tool: String, CaseIterable, Identifiable {
-    case clean, purge, installer, apps, optimize, analyze, status, ports, tuneup
+    case clean, purge, installer, apps, optimize, analyze, status, ports, tuneup, restore
 
     var id: String { rawValue }
 
@@ -21,7 +21,7 @@ enum Tool: String, CaseIterable, Identifiable {
     /// optimize, then apps / analyze. The .purge/.installer cases live on for
     /// the hub cards, MCP actions, and Explain deep-links. The live dashboard
     /// isn't a tool anymore — it's Home, reached by the Burrow mark.
-    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze, .ports, .tuneup]
+    static let navOrder: [Tool] = [.clean, .optimize, .apps, .analyze, .ports, .tuneup, .restore]
 
     /// Lowercase tab label (matches the instrument-panel voice).
     var label: String { NSLocalizedString(rawValue, comment: "") }
@@ -38,6 +38,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .status:    return NSLocalizedString("Status", comment: "")
         case .ports:     return NSLocalizedString("Ports", comment: "")
         case .tuneup:    return NSLocalizedString("Tune-Up", comment: "")
+        case .restore:   return NSLocalizedString("Restore", comment: "")
         }
     }
 
@@ -52,6 +53,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .status:    return "waveform.path.ecg"
         case .ports:     return "network"
         case .tuneup:    return "slider.horizontal.3"
+        case .restore:   return "arrow.uturn.backward"
         }
     }
 
@@ -67,6 +69,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .status:    return Color(hex: 0xE6A93C) // gold
         case .ports:     return Color(hex: 0xB58BD6) // lilac
         case .tuneup:    return Color(hex: 0x5AA98B) // sage
+        case .restore:   return Color(hex: 0xC98A4B) // amber
         }
     }
 
@@ -83,6 +86,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .status:    return Color(hex: 0x241D11)
         case .ports:     return Color(hex: 0x1B1426)
         case .tuneup:    return Color(hex: 0x12231D)
+        case .restore:   return Color(hex: 0x241A0E)
         }
     }
 
@@ -104,6 +108,7 @@ enum Tool: String, CaseIterable, Identifiable {
         case .status:    return NSLocalizedString("Every pulse of the den.", comment: "")
         case .ports:     return NSLocalizedString("See who's listening.", comment: "")
         case .tuneup:    return NSLocalizedString("One pass, a tidier den.", comment: "")
+        case .restore:   return NSLocalizedString("Put back what the last clean moved.", comment: "")
         }
     }
 }
diff --git a/Tests/RestorePlanTests.swift b/Tests/RestorePlanTests.swift
index 7b26cd67..e074a911 100644
--- a/Tests/RestorePlanTests.swift
+++ b/Tests/RestorePlanTests.swift
@@ -31,6 +31,21 @@ final class RestorePlanTests: XCTestCase {
         XCTAssertTrue(plan.first?.reason.contains("already exists") ?? false)
     }
 
+    func testParseLog_extractsOkEntriesNewestFirst() {
+        let log = """
+        1700000000\ttrash\tcache\tok\t/Users/x/A.app
+        1700000001\tremove\tlog\tok\t/Users/x/old.log
+        1700000002\ttrash\tcache\tfailed\t/Users/x/B.app
+        """
+        let items = RestorePlan.parseLog(log)
+        XCTAssertEqual(items.map(\.originalPath), ["/Users/x/old.log", "/Users/x/A.app"], "ok-only, newest first")
+        XCTAssertEqual(items.first?.action, "remove")
+    }
+
+    func testParseLog_skipsMalformedLines() {
+        XCTAssertTrue(RestorePlan.parseLog("garbage\nalso bad").isEmpty)
+    }
+
     func testMixedSession_countsOnlyRestorable() {
         let plan = RestorePlan.build([
             .init(originalPath: "/a", action: "trash"),   // restorable

From b730baf7aaa0ea921ae6c555e7ce3a281b3426a8 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 20:48:23 -0700
Subject: [PATCH 39/49] feat(attrib+git): folder-growth diff (A.3) + git
 purge-safety runner (C.11)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FolderGrowth.diff ranks per-folder size growth between two scans. GitSweep
walks up to the containing repo and runs git status (bounded) → GitRepoStatus
verdict. Diff + walk-up tested; the mo-analyze scan, git subprocess, and purge-
checklist badges are integration.
---
 Sources/FolderGrowth.swift    | 31 ++++++++++++++++++++++
 Sources/GitSweep.swift        | 49 +++++++++++++++++++++++++++++++++++
 Tests/FolderGrowthTests.swift | 31 ++++++++++++++++++++++
 Tests/GitSweepTests.swift     | 28 ++++++++++++++++++++
 4 files changed, 139 insertions(+)
 create mode 100644 Sources/FolderGrowth.swift
 create mode 100644 Sources/GitSweep.swift
 create mode 100644 Tests/FolderGrowthTests.swift
 create mode 100644 Tests/GitSweepTests.swift

diff --git a/Sources/FolderGrowth.swift b/Sources/FolderGrowth.swift
new file mode 100644
index 00000000..5c59d78a
--- /dev/null
+++ b/Sources/FolderGrowth.swift
@@ -0,0 +1,31 @@
+//
+//  FolderGrowth.swift
+//  Burrow
+//
+//  Growth attribution (roadmap A.3): diff two per-folder size scans to answer
+//  "Downloads grew 11 GB this month." Pure — two {path: bytes} maps in, the
+//  movers out, biggest growth first. The weekly `mo analyze` scan that
+//  produces the maps, persisting them, and surfacing in the report are
+//  integration.
+//
+
+import Foundation
+
+enum FolderGrowth {
+    struct Change: Equatable {
+        let path: String
+        let deltaBytes: Int64
+    }
+
+    /// Per-folder size delta (new − old). Folders only in `new` count their
+    /// full size as growth; unchanged folders are dropped. Sorted by delta
+    /// descending so the biggest growers lead (shrinkers sort last).
+    static func diff(old: [String: Int64], new: [String: Int64]) -> [Change] {
+        var out: [Change] = []
+        for (path, size) in new {
+            let delta = size - (old[path] ?? 0)
+            if delta != 0 { out.append(Change(path: path, deltaBytes: delta)) }
+        }
+        return out.sorted { $0.deltaBytes > $1.deltaBytes }
+    }
+}
diff --git a/Sources/GitSweep.swift b/Sources/GitSweep.swift
new file mode 100644
index 00000000..154e7a2c
--- /dev/null
+++ b/Sources/GitSweep.swift
@@ -0,0 +1,49 @@
+//
+//  GitSweep.swift
+//  Burrow
+//
+//  Purge-safety git runner (roadmap C.11): find the repo containing a purge
+//  candidate and ask `git status` whether deleting it would lose work. The
+//  parse + verdict live in GitRepoStatus (tested); this is the filesystem
+//  walk-up (testable) and the bounded subprocess. Badging the purge checklist
+//  is the GUI integration.
+//
+
+import Foundation
+
+enum GitSweep {
+    /// Walk up from `path` to the nearest directory containing a `.git`.
+    static func repoRoot(for path: String) -> String? {
+        var url = URL(fileURLWithPath: path)
+        let fm = FileManager.default
+        for _ in 0..<64 {
+            if fm.fileExists(atPath: url.appendingPathComponent(".git").path) { return url.path }
+            let parent = url.deletingLastPathComponent()
+            if parent.path == url.path { break }
+            url = parent
+        }
+        return nil
+    }
+
+    /// `git -C <repo> status --porcelain=v1 -b`, bounded by `timeout`, parsed
+    /// into a verdict. nil when git is unavailable, times out, or errors.
+    static func status(repo: String, timeout: TimeInterval = 3) -> GitRepoStatus.Status? {
+        let p = Process()
+        p.executableURL = URL(fileURLWithPath: "/usr/bin/git")
+        p.arguments = ["-C", repo, "status", "--porcelain=v1", "-b"]
+        let out = Pipe()
+        p.standardOutput = out
+        p.standardError = Pipe()
+        do { try p.run() } catch { return nil }
+
+        let sem = DispatchSemaphore(value: 0)
+        DispatchQueue.global(qos: .utility).async { p.waitUntilExit(); sem.signal() }
+        if sem.wait(timeout: .now() + timeout) == .timedOut {
+            p.terminate()
+            return nil
+        }
+        guard p.terminationStatus == 0 else { return nil }
+        let data = out.fileHandleForReading.readDataToEndOfFile()
+        return GitRepoStatus.parse(String(decoding: data, as: UTF8.self))
+    }
+}
diff --git a/Tests/FolderGrowthTests.swift b/Tests/FolderGrowthTests.swift
new file mode 100644
index 00000000..053406ce
--- /dev/null
+++ b/Tests/FolderGrowthTests.swift
@@ -0,0 +1,31 @@
+//
+//  FolderGrowthTests.swift
+//  BurrowTests
+//
+//  Growth attribution diff (roadmap A.3).
+//
+
+import XCTest
+@testable import Burrow
+
+final class FolderGrowthTests: XCTestCase {
+    func testDiff_reportsGrowersBiggestFirst() {
+        let changes = FolderGrowth.diff(
+            old: ["~/Downloads": 100, "~/Documents": 50],
+            new: ["~/Downloads": 300, "~/Documents": 50, "~/Movies": 80])
+        XCTAssertEqual(changes.map(\.path), ["~/Downloads", "~/Movies"], "growers, biggest first")
+        XCTAssertEqual(changes.first?.deltaBytes, 200)
+        XCTAssertFalse(changes.contains { $0.path == "~/Documents" }, "unchanged folders dropped")
+    }
+
+    func testDiff_newFolderCountsFullSize() {
+        let changes = FolderGrowth.diff(old: [:], new: ["~/New": 42])
+        XCTAssertEqual(changes, [.init(path: "~/New", deltaBytes: 42)])
+    }
+
+    func testDiff_shrinkersSortLast() {
+        let changes = FolderGrowth.diff(old: ["a": 100], new: ["a": 10, "b": 5])
+        XCTAssertEqual(changes.map(\.path), ["b", "a"])
+        XCTAssertEqual(changes.last?.deltaBytes, -90)
+    }
+}
diff --git a/Tests/GitSweepTests.swift b/Tests/GitSweepTests.swift
new file mode 100644
index 00000000..45517fce
--- /dev/null
+++ b/Tests/GitSweepTests.swift
@@ -0,0 +1,28 @@
+//
+//  GitSweepTests.swift
+//  BurrowTests
+//
+//  Repo-root walk-up (roadmap C.11). The git subprocess needs a real repo, so
+//  it's compile-verified, not unit-tested here.
+//
+
+import XCTest
+@testable import Burrow
+
+final class GitSweepTests: XCTestCase {
+    func testRepoRoot_findsContainingDotGit() throws {
+        let root = FileManager.default.temporaryDirectory.appendingPathComponent("gs-\(UUID().uuidString)")
+        let deep = root.appendingPathComponent("a/b/c")
+        try FileManager.default.createDirectory(at: deep, withIntermediateDirectories: true)
+        try FileManager.default.createDirectory(at: root.appendingPathComponent(".git"), withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: root) }
+        XCTAssertEqual(GitSweep.repoRoot(for: deep.path), root.path)
+    }
+
+    func testRepoRoot_noRepoBelowTemp_isNil() throws {
+        let dir = FileManager.default.temporaryDirectory.appendingPathComponent("nogit-\(UUID().uuidString)")
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        defer { try? FileManager.default.removeItem(at: dir) }
+        XCTAssertNil(GitSweep.repoRoot(for: dir.path))
+    }
+}

From d0f5032f7ff36f5d74c146858b6fa56d9b926e7c Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 20:51:46 -0700
Subject: [PATCH 40/49] feat(backup): backup-awareness Doctor check (D.14
 backup half)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

BackupStatus runs tmutil latestbackup → days-ago via the tested TimeMachine
parser; Doctor gains a Backups check (ok / stale-warn / no-backup-warn),
surfaced in the Doctor pane + burrow_doctor. SMART/IOKit half is separate.
---
 Sources/BackupStatus.swift | 31 +++++++++++++++++++++++++++++++
 Sources/Doctor.swift       | 14 +++++++++++++-
 Sources/DoctorView.swift   |  3 ++-
 Sources/MCP.swift          |  3 ++-
 Tests/DoctorTests.swift    | 14 ++++++++++++--
 Tests/MCPDoctorTests.swift |  2 +-
 6 files changed, 61 insertions(+), 6 deletions(-)
 create mode 100644 Sources/BackupStatus.swift

diff --git a/Sources/BackupStatus.swift b/Sources/BackupStatus.swift
new file mode 100644
index 00000000..4e2f683c
--- /dev/null
+++ b/Sources/BackupStatus.swift
@@ -0,0 +1,31 @@
+//
+//  BackupStatus.swift
+//  Burrow
+//
+//  Backup awareness (roadmap D.14, backup half): how stale is Time Machine?
+//  Runs `tmutil latestbackup` (fast, unprivileged) and reduces it to a
+//  days-ago count via the tested TimeMachine parser. Used by the Doctor check
+//  (GUI + burrow_doctor). The SMART/IOKit half of D.14 is separate native work.
+//
+
+import Foundation
+
+enum BackupStatus {
+    /// Whole days since the most recent Time Machine backup, or nil when there
+    /// are no backups / Time Machine is unavailable.
+    static func lastBackupDaysAgo(now: Date = Date()) -> Int? {
+        let p = Process()
+        p.executableURL = URL(fileURLWithPath: "/usr/bin/tmutil")
+        p.arguments = ["latestbackup"]
+        let out = Pipe()
+        p.standardOutput = out
+        p.standardError = Pipe()
+        do { try p.run() } catch { return nil }
+        p.waitUntilExit()
+        guard p.terminationStatus == 0 else { return nil }
+        let text = String(decoding: out.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+        guard let token = TimeMachine.latestBackupToken(text),
+              let date = TimeMachine.date(fromToken: token) else { return nil }
+        return max(0, Int(now.timeIntervalSince(date) / 86_400))
+    }
+}
diff --git a/Sources/Doctor.swift b/Sources/Doctor.swift
index 0cdbe4fa..bd41049a 100644
--- a/Sources/Doctor.swift
+++ b/Sources/Doctor.swift
@@ -29,12 +29,14 @@ enum Doctor {
         var diskFreeBytes: Int64
         var diskTotalBytes: Int64
         var recentErrorCount: Int
+        /// Days since the last Time Machine backup; nil = none found / unknown.
+        var lastBackupDaysAgo: Int? = nil
     }
 
     /// One `Check` per facet, in a stable order. Each verdict is independent;
     /// callers can sort by `level` to surface failures first.
     static func report(_ i: Input) -> [Check] {
-        [engine(i), permissions(i), memory(i), disk(i), errors(i)]
+        [engine(i), permissions(i), memory(i), disk(i), backup(i), errors(i)]
     }
 
     private static func engine(_ i: Input) -> Check {
@@ -70,6 +72,16 @@ enum Doctor {
         return Check(name: "Disk space", level: .ok, detail: "\(Int(freePct.rounded()))% free")
     }
 
+    private static func backup(_ i: Input) -> Check {
+        guard let days = i.lastBackupDaysAgo else {
+            return Check(name: "Backups", level: .warn, detail: "no recent Time Machine backup found")
+        }
+        if days > 14 {
+            return Check(name: "Backups", level: .warn, detail: "last backup \(days) days ago")
+        }
+        return Check(name: "Backups", level: .ok, detail: "last backup \(days) day\(days == 1 ? "" : "s") ago")
+    }
+
     private static func errors(_ i: Input) -> Check {
         i.recentErrorCount == 0
             ? Check(name: "Recent errors", level: .ok, detail: "none logged")
diff --git a/Sources/DoctorView.swift b/Sources/DoctorView.swift
index a2c0426a..541f3dfa 100644
--- a/Sources/DoctorView.swift
+++ b/Sources/DoctorView.swift
@@ -71,6 +71,7 @@ struct DoctorView: View {
             fullDiskAccess: Privacy.hasFullDiskAccess(),
             moInstalled: moInstalled, pressure: pressure,
             diskFreeBytes: free, diskTotalBytes: total,
-            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal))
+            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal,
+            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo()))
     }
 }
diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 95c6e2af..0c51b37e 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -692,7 +692,8 @@ struct ToolCatalog {
             moInstalled: moInstalled,
             pressure: Self.mapPressure(latest?.memory.pressure),
             diskFreeBytes: free, diskTotalBytes: total,
-            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal)
+            recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal,
+            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo())
         func esc(_ s: String) -> String {
             "\"\(s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\""
         }
diff --git a/Tests/DoctorTests.swift b/Tests/DoctorTests.swift
index da02fe41..b1195d4f 100644
--- a/Tests/DoctorTests.swift
+++ b/Tests/DoctorTests.swift
@@ -12,7 +12,7 @@ final class DoctorTests: XCTestCase {
     private func healthy() -> Doctor.Input {
         .init(fullDiskAccess: true, moInstalled: true, pressure: .normal,
               diskFreeBytes: 200_000_000_000, diskTotalBytes: 500_000_000_000,
-              recentErrorCount: 0)
+              recentErrorCount: 0, lastBackupDaysAgo: 1)
     }
 
     private func check(_ report: [Doctor.Check], _ name: String) -> Doctor.Check? {
@@ -21,10 +21,20 @@ final class DoctorTests: XCTestCase {
 
     func testReport_healthyMachine_allOK() {
         let r = Doctor.report(healthy())
-        XCTAssertEqual(r.count, 5)
+        XCTAssertEqual(r.count, 6)
         XCTAssertTrue(r.allSatisfy { $0.level == .ok })
     }
 
+    func testReport_staleBackup_warns() {
+        var i = healthy(); i.lastBackupDaysAgo = 26
+        XCTAssertEqual(check(Doctor.report(i), "Backups")?.level, .warn)
+    }
+
+    func testReport_noBackup_warns() {
+        var i = healthy(); i.lastBackupDaysAgo = nil
+        XCTAssertEqual(check(Doctor.report(i), "Backups")?.level, .warn)
+    }
+
     func testReport_noEngine_fails() {
         var i = healthy(); i.moInstalled = false
         XCTAssertEqual(check(Doctor.report(i), "Engine")?.level, .fail)
diff --git a/Tests/MCPDoctorTests.swift b/Tests/MCPDoctorTests.swift
index c472e80b..1fe82cfb 100644
--- a/Tests/MCPDoctorTests.swift
+++ b/Tests/MCPDoctorTests.swift
@@ -58,7 +58,7 @@ final class MCPDoctorTests: XCTestCase {
         let l = try levels(catalog.call(name: "burrow_doctor", arguments: [:]))
         XCTAssertEqual(l["Memory pressure"], "fail")
         XCTAssertEqual(l["Disk space"], "fail")        // 2% < 5%
-        XCTAssertEqual(l.count, 5, "all five checks present")
+        XCTAssertEqual(l.count, 6, "all six checks present")
     }
 
     func testDoctor_healthySnapshot_pressureAndDiskOK() throws {

From 7f9c10e701c6607fa7463f057f15cfd0c296a62f Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 21:05:43 -0700
Subject: [PATCH 41/49] =?UTF-8?q?feat(spike):=20drag-select=20on=20the=20H?=
 =?UTF-8?q?istory=20chart=20=E2=86=92=20top=20processes=20(A.1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Additive chartOverlay on the line chart maps a drag to a [t0,t1] window and
opens SpikeSheet, which ranks processes via the tested MetricsStore.processWindow.
Overlay-only — doesn't touch the chart's marks/axes. zh added. Compile-verified.
---
 Resources/zh-Hans.lproj/Localizable.strings |  2 +
 Resources/zh-Hant.lproj/Localizable.strings |  2 +
 Sources/HistoryView.swift                   | 36 ++++++++++
 Sources/SpikeView.swift                     | 75 +++++++++++++++++++++
 4 files changed, 115 insertions(+)
 create mode 100644 Sources/SpikeView.swift

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index e5660fb9..d48af596 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -317,6 +317,8 @@
 "Restore last cleanup" = "恢复上次清理";
 "Only Trash-based removals can be restored — cache deletions are permanent." = "仅可恢复移到废纸篓的项目——缓存删除是永久性的。";
 "No restorable items found." = "未找到可恢复的项目。";
+"Top processes in selection" = "所选区间内的主要进程";
+"No process samples in that window." = "该区间内没有进程采样。";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "CPU usage is high" = "CPU 使用率过高";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index e96357b0..3333a5a7 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -317,6 +317,8 @@
 "Restore last cleanup" = "復原上次清理";
 "Only Trash-based removals can be restored — cache deletions are permanent." = "僅可復原移到垃圾桶的項目——快取刪除是永久性的。";
 "No restorable items found." = "未找到可復原的項目。";
+"Top processes in selection" = "所選區間內的主要程序";
+"No process samples in that window." = "該區間內沒有程序取樣。";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "CPU usage is high" = "CPU 使用率過高";
diff --git a/Sources/HistoryView.swift b/Sources/HistoryView.swift
index 019f7835..a771c8b8 100644
--- a/Sources/HistoryView.swift
+++ b/Sources/HistoryView.swift
@@ -216,6 +216,10 @@ struct HistoryView: View {
     @State private var snapshot: HistorySnapshot = HistorySnapshot()
     @State private var loading: Bool = false
     @State private var procMetric: ProcMetric = .cpu
+    // Spike forensics (A.1): drag-select on the line chart → top processes.
+    @State private var spikeDragStart: CGFloat?
+    @State private var spikeDragCurrent: CGFloat?
+    @State private var spikeWindow: SpikeWindow?
     /// The currently-subscribed board feed — held so the toolbar's manual
     /// refresh can poke it; lifecycle belongs to `.task(id: range)` below.
     @State private var board: Feed<HistorySnapshot>?
@@ -430,6 +434,38 @@ struct HistoryView: View {
                         }
                     }
                     .chartXScale(domain: snapshot.windowSince...snapshot.windowUntil)
+                    .chartOverlay { proxy in
+                        GeometryReader { geo in
+                            if let anchor = proxy.plotFrame {
+                                let plot = geo[anchor]
+                                Rectangle().fill(Color.clear).contentShape(Rectangle())
+                                    .gesture(DragGesture(minimumDistance: 4)
+                                        .onChanged { v in
+                                            if spikeDragStart == nil { spikeDragStart = v.startLocation.x - plot.minX }
+                                            spikeDragCurrent = v.location.x - plot.minX
+                                        }
+                                        .onEnded { v in
+                                            let x0 = spikeDragStart ?? 0
+                                            let x1 = v.location.x - plot.minX
+                                            spikeDragStart = nil; spikeDragCurrent = nil
+                                            let lo = min(x0, x1), hi = max(x0, x1)
+                                            guard hi - lo > 4,
+                                                  let d0 = proxy.value(atX: lo, as: Date.self),
+                                                  let d1 = proxy.value(atX: hi, as: Date.self) else { return }
+                                            spikeWindow = SpikeWindow(since: Int(d0.timeIntervalSince1970),
+                                                                      until: Int(d1.timeIntervalSince1970))
+                                        })
+                                if let s = spikeDragStart, let c = spikeDragCurrent {
+                                    Rectangle().fill(Brand.textSecondary.opacity(0.18))
+                                        .frame(width: abs(c - s), height: plot.height)
+                                        .position(x: plot.minX + min(s, c) + abs(c - s) / 2, y: plot.midY)
+                                }
+                            }
+                        }
+                    }
+                    .sheet(item: $spikeWindow) { w in
+                        SpikeSheet(db: db, window: w, onClose: { spikeWindow = nil })
+                    }
                     .chartXAxis {
                         AxisMarks(values: .automatic(desiredCount: style.desiredCount)) { _ in
                             AxisGridLine().foregroundStyle(Brand.hairline)
diff --git a/Sources/SpikeView.swift b/Sources/SpikeView.swift
new file mode 100644
index 00000000..00152bb2
--- /dev/null
+++ b/Sources/SpikeView.swift
@@ -0,0 +1,75 @@
+//
+//  SpikeView.swift
+//  Burrow
+//
+//  Spike forensics (roadmap A.1): drag-select a window on a History chart and
+//  see the top processes for that exact range. The selection is captured by a
+//  chartOverlay drag in HistoryView; this sheet renders the result via the
+//  already-tested MetricsStore.processWindow — GUI and MCP share one impl.
+//
+//  NOTE (hand-test): compile-verified only. Verify the drag maps to the right
+//  timestamps and the ranked list matches.
+//
+
+import SwiftUI
+
+/// A drag-selected window on the History chart, in unix seconds.
+struct SpikeWindow: Identifiable {
+    let id = UUID()
+    let since: Int
+    let until: Int
+}
+
+struct SpikeSheet: View {
+    let db: DB
+    let window: SpikeWindow
+    let onClose: () -> Void
+
+    @State private var rows: [(name: String, peakCPU: Double, peakMem: Double)] = []
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            HStack {
+                Text(NSLocalizedString("Top processes in selection", comment: "")).font(.headline)
+                Spacer()
+                Button(NSLocalizedString("Done", comment: "")) { onClose() }
+            }
+            Text(rangeLabel).font(.caption).foregroundStyle(.secondary)
+            if rows.isEmpty {
+                Text(NSLocalizedString("No process samples in that window.", comment: ""))
+                    .foregroundStyle(.secondary).padding(.top, 8)
+            } else {
+                ScrollView {
+                    VStack(spacing: 6) {
+                        ForEach(Array(rows.enumerated()), id: \.offset) { _, r in
+                            HStack {
+                                Text(r.name)
+                                Spacer()
+                                Text(String(format: "%.0f%% CPU", r.peakCPU))
+                                    .font(.body.monospacedDigit()).foregroundStyle(.secondary)
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        .padding(20)
+        .frame(width: 400, height: 380)
+        .task { load() }
+    }
+
+    private var rangeLabel: String {
+        let f = DateFormatter()
+        f.dateFormat = "MMM d, HH:mm"
+        let a = f.string(from: Date(timeIntervalSince1970: TimeInterval(window.since)))
+        let b = f.string(from: Date(timeIntervalSince1970: TimeInterval(window.until)))
+        return "\(a) – \(b)"
+    }
+
+    private func load() {
+        let pw = MetricsStore(db: db).processWindow(.init(since: window.since, until: window.until))
+        rows = pw.ranked(by: .peakCPU, limit: 12).map {
+            (name: $0.name, peakCPU: $0.peakCPU, peakMem: $0.peakMem)
+        }
+    }
+}

From cbc8301da3e6c3cbd89eae9942f1127328e4cd78 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 21:10:14 -0700
Subject: [PATCH 42/49] feat(forecast): disk-tile 'Full in ~N' annotation (A.3)

DiskCard takes an optional db and annotates the Status disk tile with the
DiskForecast over 30d of free-space history (silent unless a date is honest).
Exposed StatusModel.db. Additive line; zh added.
---
 Resources/zh-Hans.lproj/Localizable.strings |  4 +++
 Resources/zh-Hant.lproj/Localizable.strings |  4 +++
 Sources/StatusView.swift                    | 30 +++++++++++++++++++--
 3 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index d48af596..503edfa0 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -319,6 +319,10 @@
 "No restorable items found." = "未找到可恢复的项目。";
 "Top processes in selection" = "所选区间内的主要进程";
 "No process samples in that window." = "该区间内没有进程采样。";
+"Full in ~%@" = "约 %@ 后写满";
+"%d days" = "%d 天";
+"%d weeks" = "%d 周";
+"%d months" = "%d 个月";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "CPU usage is high" = "CPU 使用率过高";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 3333a5a7..7d4c2958 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -319,6 +319,10 @@
 "No restorable items found." = "未找到可復原的項目。";
 "Top processes in selection" = "所選區間內的主要程序";
 "No process samples in that window." = "該區間內沒有程序取樣。";
+"Full in ~%@" = "約 %@ 後寫滿";
+"%d days" = "%d 天";
+"%d weeks" = "%d 週";
+"%d months" = "%d 個月";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "CPU usage is high" = "CPU 使用率過高";
diff --git a/Sources/StatusView.swift b/Sources/StatusView.swift
index e7d938ec..32cc68ae 100644
--- a/Sources/StatusView.swift
+++ b/Sources/StatusView.swift
@@ -39,7 +39,7 @@ struct StatusView: View {
                         gpuTile(s).frame(minHeight: row1H)
                     }
                     HStack(spacing: 13) {
-                        DiskCard(s: s, liveRead: io.readMBs, liveWrite: io.writeMBs, minHeight: row2H)
+                        DiskCard(s: s, db: model.db, liveRead: io.readMBs, liveWrite: io.writeMBs, minHeight: row2H)
                         netTile(s).frame(minHeight: row2H)
                         fanTile(s).frame(minHeight: row2H)
                     }
@@ -270,6 +270,9 @@ struct DiskCard: View {
     var liveRead: Double? = nil
     var liveWrite: Double? = nil
     var minHeight: CGFloat? = nil
+    /// When set, annotate the tile with a disk-full forecast (A.3).
+    var db: DB? = nil
+    @State private var forecastText: String? = nil
 
     var body: some View {
         let disk = s.disks.first
@@ -293,8 +296,31 @@ struct DiskCard: View {
                 Text(String(format: NSLocalizedString("%.0f%% used · R %.0f · W %.0f MB/s", comment: ""),
                             pct, liveRead ?? s.diskIO.readRate, liveWrite ?? s.diskIO.writeRate))
                     .font(Brand.mono(10)).foregroundStyle(Brand.textTertiary).lineLimit(1)
+                if let f = forecastText {
+                    Text(f).font(Brand.mono(10)).foregroundStyle(Brand.textSecondary).lineLimit(1)
+                }
             }
         }
+        .task { computeForecast() }
+    }
+
+    /// Annotate with a disk-full forecast over the last 30 days of free-space
+    /// history (A.3). Silent unless the forecaster is willing to name a date.
+    private func computeForecast() {
+        guard let db else { return }
+        let now = Int(Date().timeIntervalSince1970)
+        let series = MetricsStore(db: db).diskFreeSeries(mount: nil, .init(since: now - 30 * 86_400, until: now))
+        guard series.count >= 2, let days = DiskForecast.forecast(series, now: now).daysUntilFull else {
+            forecastText = nil
+            return
+        }
+        forecastText = String(format: NSLocalizedString("Full in ~%@", comment: ""), phrase(days))
+    }
+
+    private func phrase(_ days: Double) -> String {
+        if days < 14 { return String(format: NSLocalizedString("%d days", comment: ""), Int(days.rounded())) }
+        if days < 60 { return String(format: NSLocalizedString("%d weeks", comment: ""), Int((days / 7).rounded())) }
+        return String(format: NSLocalizedString("%d months", comment: ""), Int((days / 30).rounded()))
     }
 }
 
@@ -755,7 +781,7 @@ final class StatusModel: ObservableObject {
     /// — the table then falls back to the snapshot's engine top five.
     @Published var processes: [ProcessInfo] = []
 
-    private let db: DB
+    let db: DB
     private let live: LiveFeed
     private let feeds: FeedHub
 

From f205704a32dd2edafde45db5f742e87b83e030f4 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 21:12:38 -0700
Subject: [PATCH 43/49] feat(diff): login-item churn in burrow_diff (B.8)

Maintenance persists a time-indexed login-item/LaunchAgent inventory
(burrow.startup_inv); burrow_diff now reports login_items_added/removed since
<time> via InventoryDiff. Tested through dispatch. Apps/ports still untracked.
---
 Sources/MCP.swift         | 11 ++++++++++-
 Sources/Maintenance.swift | 14 ++++++++++++++
 Tests/MCPDiffTests.swift  | 16 ++++++++++++++++
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 0c51b37e..0c1c35d5 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -658,10 +658,19 @@ struct ToolCatalog {
             "[" + xs.map { "\"\($0.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\"" }
                 .joined(separator: ",") + "]"
         }
+        func ids(_ json: String) -> [String] {
+            (try? JSONDecoder().decode([String].self, from: Data(json.utf8))) ?? []
+        }
+        let invRows = self.metrics.rawRows(prefix: Maintenance.startupInvPrefix,
+                                           MetricsStore.Window(since: since, until: now), maxPoints: nil)
+        let login = invRows.count >= 2
+            ? InventoryDiff.diff(old: ids(invRows.first!.json), new: ids(invRows.last!.json))
+            : InventoryDiff.Change(added: [], removed: [])
         return "{\"since_ts\":\(first.ts),\"until_ts\":\(last.ts),"
             + "\"processes_entered\":\(arr(change.added)),\"processes_left\":\(arr(change.removed)),"
+            + "\"login_items_added\":\(arr(login.added)),\"login_items_removed\":\(arr(login.removed)),"
             + "\"disk_free_delta_bytes\":\(freeOf(last.status) - freeOf(first.status)),"
-            + "\"note\":\"app, login-item, and port inventories are not yet tracked across time\"}"
+            + "\"note\":\"app and port inventories are not yet tracked across time\"}"
     }
 
     /// `burrow_report` — the weekly digest as Markdown (the tool's text
diff --git a/Sources/Maintenance.swift b/Sources/Maintenance.swift
index 098e8851..3e43e024 100644
--- a/Sources/Maintenance.swift
+++ b/Sources/Maintenance.swift
@@ -119,8 +119,22 @@ final class Maintenance {
             }
         }
 
+        self.persistStartupInventory()
+
         let finished = Date()
         stats.withLock { $0.lastPruneDeleted = deleted; $0.lastRunAt = finished }
         return MaintenanceReport(deleted: deleted, vacuumed: vacuumed, finishedAt: finished)
     }
+
+    /// Time-indexed login-item / LaunchAgent inventory (B.8): a JSON list of
+    /// ids per tick, so burrow_diff can answer "what login items changed since
+    /// <time>". Cheap (no `mo`); pruned with everything else.
+    static let startupInvPrefix = "burrow.startup_inv"
+    private func persistStartupInventory() {
+        let ids = StartupInventory.scanLive().map(\.id)
+        guard let data = try? JSONEncoder().encode(ids),
+              let json = String(data: data, encoding: .utf8) else { return }
+        try? self.db.insert(prefix: Self.startupInvPrefix,
+                            ts: Int(Date().timeIntervalSince1970), json: json)
+    }
 }
diff --git a/Tests/MCPDiffTests.swift b/Tests/MCPDiffTests.swift
index a8f048a9..1e18db92 100644
--- a/Tests/MCPDiffTests.swift
+++ b/Tests/MCPDiffTests.swift
@@ -66,6 +66,22 @@ final class MCPDiffTests: XCTestCase {
         XCTAssertEqual(delta, -50_000_000_000)
     }
 
+    func testDiff_reportsLoginItemChurn() throws {
+        let now = Int(Date().timeIntervalSince1970)
+        let then = now - 3600
+        // Two snapshots (the process/disk diff needs them).
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: then, json: snapshot(freeGB: 100, procs: ["a"]))
+        try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now, json: snapshot(freeGB: 100, procs: ["a"]))
+        // Two login-item inventories — a new persistence item appeared.
+        try db.insert(prefix: Maintenance.startupInvPrefix, ts: then, json: "[\"/A.plist\"]")
+        try db.insert(prefix: Maintenance.startupInvPrefix, ts: now, json: "[\"/A.plist\",\"/evil.plist\"]")
+
+        let json = try catalog.call(name: "burrow_diff", arguments: ["since": then - 10])
+        let o = try XCTUnwrap(JSONSerialization.jsonObject(with: Data(json.utf8)) as? [String: Any], json)
+        XCTAssertEqual(o["login_items_added"] as? [String], ["/evil.plist"], json)
+        XCTAssertEqual(o["login_items_removed"] as? [String], [], json)
+    }
+
     func testDiff_tooFewSnapshots_reportsError() throws {
         let now = Int(Date().timeIntervalSince1970)
         try db.insert(prefix: MetricsStore.snapshotPrefix, ts: now,

From d48518fba50683df862a5cfe5a2ddac87a7e7b73 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 21:16:36 -0700
Subject: [PATCH 44/49] fix(forecast): DiskCard arg order (db follows minHeight
 in memberwise init)

---
 Sources/StatusView.swift | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Sources/StatusView.swift b/Sources/StatusView.swift
index 32cc68ae..5abbdd9a 100644
--- a/Sources/StatusView.swift
+++ b/Sources/StatusView.swift
@@ -39,7 +39,7 @@ struct StatusView: View {
                         gpuTile(s).frame(minHeight: row1H)
                     }
                     HStack(spacing: 13) {
-                        DiskCard(s: s, db: model.db, liveRead: io.readMBs, liveWrite: io.writeMBs, minHeight: row2H)
+                        DiskCard(s: s, liveRead: io.readMBs, liveWrite: io.writeMBs, minHeight: row2H, db: model.db)
                         netTile(s).frame(minHeight: row2H)
                         fanTile(s).frame(minHeight: row2H)
                     }

From d956a2cd1be5611c263f6994e61f0951b755c0a8 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 21:38:53 -0700
Subject: [PATCH 45/49] feat(smart): SMART status Doctor check (D.14 health
 half)

DiskHealth reads the NVMe SMART verdict from system_profiler (no private API);
Doctor gains a Disk-health check (verified=ok / failing=fail / unreadable=ok).
Surfaced in the Doctor pane + burrow_doctor. wear%/temp still need IOKit.
---
 Sources/DiskHealth.swift   | 34 ++++++++++++++++++++++++++++++++++
 Sources/Doctor.swift       | 12 +++++++++++-
 Sources/DoctorView.swift   |  3 ++-
 Sources/MCP.swift          |  3 ++-
 Tests/DoctorTests.swift    |  9 +++++++--
 Tests/MCPDoctorTests.swift |  2 +-
 6 files changed, 57 insertions(+), 6 deletions(-)
 create mode 100644 Sources/DiskHealth.swift

diff --git a/Sources/DiskHealth.swift b/Sources/DiskHealth.swift
new file mode 100644
index 00000000..5c4dd17f
--- /dev/null
+++ b/Sources/DiskHealth.swift
@@ -0,0 +1,34 @@
+//
+//  DiskHealth.swift
+//  Burrow
+//
+//  SMART status (roadmap D.14, health half). The full wear%/temperature/hours
+//  need the private IONVMeSMARTUserClient log; the pass/fail SMART verdict,
+//  though, is readable from `system_profiler SPNVMeDataType` without elevation
+//  or private API — so that's what we surface (as a Doctor check).
+//
+
+import Foundation
+
+enum DiskHealth {
+    /// true = SMART "Verified", false = any other status, nil = unreadable
+    /// (no internal NVMe, or system_profiler failed).
+    static func smartVerified() -> Bool? {
+        let p = Process()
+        p.executableURL = URL(fileURLWithPath: "/usr/sbin/system_profiler")
+        p.arguments = ["SPNVMeDataType"]
+        let out = Pipe()
+        p.standardOutput = out
+        p.standardError = Pipe()
+        do { try p.run() } catch { return nil }
+        p.waitUntilExit()
+        guard p.terminationStatus == 0 else { return nil }
+        let text = String(decoding: out.fileHandleForReading.readDataToEndOfFile(), as: UTF8.self)
+        guard let line = text.split(separator: "\n").first(where: { $0.contains("SMART Status:") }) else {
+            return nil
+        }
+        let status = line.split(separator: ":", maxSplits: 1).last
+            .map { $0.trimmingCharacters(in: .whitespaces) } ?? ""
+        return status.lowercased().contains("verified")
+    }
+}
diff --git a/Sources/Doctor.swift b/Sources/Doctor.swift
index bd41049a..2f60c562 100644
--- a/Sources/Doctor.swift
+++ b/Sources/Doctor.swift
@@ -31,12 +31,14 @@ enum Doctor {
         var recentErrorCount: Int
         /// Days since the last Time Machine backup; nil = none found / unknown.
         var lastBackupDaysAgo: Int? = nil
+        /// SMART verdict: true = verified, false = failing, nil = unreadable.
+        var smartVerified: Bool? = nil
     }
 
     /// One `Check` per facet, in a stable order. Each verdict is independent;
     /// callers can sort by `level` to surface failures first.
     static func report(_ i: Input) -> [Check] {
-        [engine(i), permissions(i), memory(i), disk(i), backup(i), errors(i)]
+        [engine(i), permissions(i), memory(i), disk(i), diskHealth(i), backup(i), errors(i)]
     }
 
     private static func engine(_ i: Input) -> Check {
@@ -72,6 +74,14 @@ enum Doctor {
         return Check(name: "Disk space", level: .ok, detail: "\(Int(freePct.rounded()))% free")
     }
 
+    private static func diskHealth(_ i: Input) -> Check {
+        switch i.smartVerified {
+        case .some(true):  return Check(name: "Disk health", level: .ok, detail: "SMART status: verified")
+        case .some(false): return Check(name: "Disk health", level: .fail, detail: "SMART status: failing — back up now")
+        case .none:        return Check(name: "Disk health", level: .ok, detail: "SMART not reported")
+        }
+    }
+
     private static func backup(_ i: Input) -> Check {
         guard let days = i.lastBackupDaysAgo else {
             return Check(name: "Backups", level: .warn, detail: "no recent Time Machine backup found")
diff --git a/Sources/DoctorView.swift b/Sources/DoctorView.swift
index 541f3dfa..9e724c4a 100644
--- a/Sources/DoctorView.swift
+++ b/Sources/DoctorView.swift
@@ -72,6 +72,7 @@ struct DoctorView: View {
             moInstalled: moInstalled, pressure: pressure,
             diskFreeBytes: free, diskTotalBytes: total,
             recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal,
-            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo()))
+            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo(),
+            smartVerified: DiskHealth.smartVerified()))
     }
 }
diff --git a/Sources/MCP.swift b/Sources/MCP.swift
index 0c1c35d5..a6c0a218 100644
--- a/Sources/MCP.swift
+++ b/Sources/MCP.swift
@@ -702,7 +702,8 @@ struct ToolCatalog {
             pressure: Self.mapPressure(latest?.memory.pressure),
             diskFreeBytes: free, diskTotalBytes: total,
             recentErrorCount: MetricsStore.driftCounters.decodeSkippedTotal,
-            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo())
+            lastBackupDaysAgo: BackupStatus.lastBackupDaysAgo(),
+            smartVerified: DiskHealth.smartVerified())
         func esc(_ s: String) -> String {
             "\"\(s.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\""))\""
         }
diff --git a/Tests/DoctorTests.swift b/Tests/DoctorTests.swift
index b1195d4f..c603ccc4 100644
--- a/Tests/DoctorTests.swift
+++ b/Tests/DoctorTests.swift
@@ -12,7 +12,7 @@ final class DoctorTests: XCTestCase {
     private func healthy() -> Doctor.Input {
         .init(fullDiskAccess: true, moInstalled: true, pressure: .normal,
               diskFreeBytes: 200_000_000_000, diskTotalBytes: 500_000_000_000,
-              recentErrorCount: 0, lastBackupDaysAgo: 1)
+              recentErrorCount: 0, lastBackupDaysAgo: 1, smartVerified: true)
     }
 
     private func check(_ report: [Doctor.Check], _ name: String) -> Doctor.Check? {
@@ -21,7 +21,7 @@ final class DoctorTests: XCTestCase {
 
     func testReport_healthyMachine_allOK() {
         let r = Doctor.report(healthy())
-        XCTAssertEqual(r.count, 6)
+        XCTAssertEqual(r.count, 7)
         XCTAssertTrue(r.allSatisfy { $0.level == .ok })
     }
 
@@ -35,6 +35,11 @@ final class DoctorTests: XCTestCase {
         XCTAssertEqual(check(Doctor.report(i), "Backups")?.level, .warn)
     }
 
+    func testReport_smartFailing_fails() {
+        var i = healthy(); i.smartVerified = false
+        XCTAssertEqual(check(Doctor.report(i), "Disk health")?.level, .fail)
+    }
+
     func testReport_noEngine_fails() {
         var i = healthy(); i.moInstalled = false
         XCTAssertEqual(check(Doctor.report(i), "Engine")?.level, .fail)
diff --git a/Tests/MCPDoctorTests.swift b/Tests/MCPDoctorTests.swift
index 1fe82cfb..dbe15a5b 100644
--- a/Tests/MCPDoctorTests.swift
+++ b/Tests/MCPDoctorTests.swift
@@ -58,7 +58,7 @@ final class MCPDoctorTests: XCTestCase {
         let l = try levels(catalog.call(name: "burrow_doctor", arguments: [:]))
         XCTAssertEqual(l["Memory pressure"], "fail")
         XCTAssertEqual(l["Disk space"], "fail")        // 2% < 5%
-        XCTAssertEqual(l.count, 6, "all six checks present")
+        XCTAssertEqual(l.count, 7, "all seven checks present")
     }
 
     func testDoctor_healthySnapshot_pressureAndDiskOK() throws {

From 6263d695484f68a200bb601281d31be1e618706b Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 22:31:31 -0700
Subject: [PATCH 46/49] feat(updates): live brew-upgrade progress (H)

runBrewStreaming pipes brew output line-by-line; upgrade()/upgradeAll() feed
each line through BrewProgress.phrase and publish brewPhrase, shown live in the
row instead of a bare spinner. NOTE (hand-test): exercises a real brew upgrade.
---
 Sources/UpdatesView.swift | 57 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 53 insertions(+), 4 deletions(-)

diff --git a/Sources/UpdatesView.swift b/Sources/UpdatesView.swift
index 398a4bc9..160d0c9d 100644
--- a/Sources/UpdatesView.swift
+++ b/Sources/UpdatesView.swift
@@ -173,8 +173,13 @@ struct UpdatesView: View {
                     Text(item.name).font(Brand.sans(13, .medium)).foregroundStyle(Brand.textPrimary).lineLimit(1)
                     Chip(text: UpdateSources.Source.homebrew.badge, color: Brand.textSecondary)
                 }
-                Text(verbatim: "\(item.installed) → \(item.latest)")
-                    .font(Brand.mono(10)).foregroundStyle(Brand.textTertiary)
+                if model.upgrading.contains(item.id), !model.brewPhrase.isEmpty {
+                    Text(model.brewPhrase)
+                        .font(Brand.mono(10)).foregroundStyle(Tool.apps.accent).lineLimit(1)
+                } else {
+                    Text(verbatim: "\(item.installed) → \(item.latest)")
+                        .font(Brand.mono(10)).foregroundStyle(Brand.textTertiary)
+                }
             }
             Spacer(minLength: 8)
             if model.upgrading.contains(item.id) {
@@ -247,6 +252,8 @@ final class UpdatesModel: ObservableObject {
     @Published var checked = false
     @Published var error: String?
     @Published var upgrading: Set<String> = []
+    /// Live brew step during an upgrade (H: brew-upgrade streaming).
+    @Published var brewPhrase: String = ""
     private var preparedCount = -1
     private var brewSurfaced = false
 
@@ -388,8 +395,11 @@ final class UpdatesModel: ObservableObject {
         guard !upgrading.contains(item.id) else { return }
         upgrading.insert(item.id)
         DispatchQueue.global(qos: .userInitiated).async {
-            _ = Self.runBrew(brew, ["upgrade", item.name], timeout: 1800)
+            Self.runBrewStreaming(brew, ["upgrade", item.name], timeout: 1800) { line in
+                if let phrase = BrewProgress.phrase(line) { Task { @MainActor in self.brewPhrase = phrase } }
+            }
             Task { @MainActor in
+                self.brewPhrase = ""
                 self.upgrading.remove(item.id)
                 self.brewItems = await Self.brewOutdated()
             }
@@ -402,8 +412,11 @@ final class UpdatesModel: ObservableObject {
         let ids = Set(brewItems.map(\.id))
         upgrading.formUnion(ids)
         DispatchQueue.global(qos: .userInitiated).async {
-            _ = Self.runBrew(brew, ["upgrade"], timeout: 3600)
+            Self.runBrewStreaming(brew, ["upgrade"], timeout: 3600) { line in
+                if let phrase = BrewProgress.phrase(line) { Task { @MainActor in self.brewPhrase = phrase } }
+            }
             Task { @MainActor in
+                self.brewPhrase = ""
                 self.upgrading.subtract(ids)
                 self.brewItems = await Self.brewOutdated()
             }
@@ -440,6 +453,42 @@ final class UpdatesModel: ObservableObject {
         }
     }
 
+    /// Stream a brew run, calling `onLine` per stdout line (H: live progress).
+    /// The readability handler drains the pipe so waitUntilExit can't deadlock;
+    /// a work item terminates on timeout.
+    private nonisolated static func runBrewStreaming(_ brew: String, _ args: [String],
+                                                     timeout: TimeInterval,
+                                                     onLine: @escaping (String) -> Void) {
+        var env = Foundation.ProcessInfo.processInfo.environment
+        let dir = (brew as NSString).deletingLastPathComponent
+        env["PATH"] = "\(dir):/usr/bin:/bin:/usr/sbin:/sbin:" + (env["PATH"] ?? "")
+        let p = Process()
+        p.executableURL = URL(fileURLWithPath: brew)
+        p.arguments = args
+        p.environment = env
+        let pipe = Pipe()
+        p.standardOutput = pipe
+        p.standardError = pipe
+        let handle = pipe.fileHandleForReading
+        var buffer = Data()
+        handle.readabilityHandler = { fh in
+            let chunk = fh.availableData
+            guard !chunk.isEmpty else { return }
+            buffer.append(chunk)
+            while let nl = buffer.firstIndex(of: 0x0A) {
+                let line = String(decoding: buffer[buffer.startIndex..<nl], as: UTF8.self)
+                buffer.removeSubrange(buffer.startIndex...nl)
+                onLine(line)
+            }
+        }
+        let killer = DispatchWorkItem { if p.isRunning { p.terminate() } }
+        DispatchQueue.global().asyncAfter(deadline: .now() + timeout, execute: killer)
+        do { try p.run() } catch { handle.readabilityHandler = nil; return }
+        p.waitUntilExit()
+        killer.cancel()
+        handle.readabilityHandler = nil
+    }
+
     /// Pure parser for `brew outdated --json=v2` — unit-tested against captured
     /// brew output, like the other `mo`/CLI parsers.
     nonisolated static func parseOutdated(_ json: String) -> [OutdatedItem] {

From 03783ae17d71b264fc2c0281d5aa6b16944d1be9 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 22:34:02 -0700
Subject: [PATCH 47/49] feat(purge): git purge-safety badge on selection rows
 (C.11)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MoItemRow runs GitSweep (repo-walk + git status, off-main) per row and shows a
warning badge when the candidate's folder has uncommitted/unpushed work.
Read-only — never changes the selection. zh added.
---
 Resources/zh-Hans.lproj/Localizable.strings |  1 +
 Resources/zh-Hant.lproj/Localizable.strings |  1 +
 Sources/InstallerView.swift                 | 19 +++++++++++++++++++
 3 files changed, 21 insertions(+)

diff --git a/Resources/zh-Hans.lproj/Localizable.strings b/Resources/zh-Hans.lproj/Localizable.strings
index 503edfa0..778ae3d8 100644
--- a/Resources/zh-Hans.lproj/Localizable.strings
+++ b/Resources/zh-Hans.lproj/Localizable.strings
@@ -323,6 +323,7 @@
 "%d days" = "%d 天";
 "%d weeks" = "%d 周";
 "%d months" = "%d 个月";
+"Uncommitted or unpushed git changes in this repo" = "此仓库有未提交或未推送的 git 更改";
 "A new startup item appeared" = "出现了新的启动项";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 现在会自动启动。如果不是你添加的，请检查它。";
 "CPU usage is high" = "CPU 使用率过高";
diff --git a/Resources/zh-Hant.lproj/Localizable.strings b/Resources/zh-Hant.lproj/Localizable.strings
index 7d4c2958..181dcf0e 100644
--- a/Resources/zh-Hant.lproj/Localizable.strings
+++ b/Resources/zh-Hant.lproj/Localizable.strings
@@ -323,6 +323,7 @@
 "%d days" = "%d 天";
 "%d weeks" = "%d 週";
 "%d months" = "%d 個月";
+"Uncommitted or unpushed git changes in this repo" = "此儲存庫有未提交或未推送的 git 變更";
 "A new startup item appeared" = "出現了新的啟動項";
 "“%@” now launches automatically. If you didn't add it, review it." = "“%@” 現在會自動啟動。如果不是你新增的，請檢查它。";
 "CPU usage is high" = "CPU 使用率過高";
diff --git a/Sources/InstallerView.swift b/Sources/InstallerView.swift
index 7f12398a..38b5b531 100644
--- a/Sources/InstallerView.swift
+++ b/Sources/InstallerView.swift
@@ -410,6 +410,7 @@ struct MoItemRow: View {
     let selected: Bool
     let onToggle: () -> Void
     @State private var hover = false
+    @State private var gitWarn = false
 
     var body: some View {
         HStack(spacing: 12) {
@@ -420,6 +421,11 @@ struct MoItemRow: View {
                     .font(Brand.mono(10)).foregroundStyle(Brand.textTertiary).lineLimit(1)
             }
             Spacer(minLength: 8)
+            if gitWarn {
+                Image(systemName: "exclamationmark.triangle.fill")
+                    .font(.system(size: 11)).foregroundStyle(.yellow)
+                    .help(NSLocalizedString("Uncommitted or unpushed git changes in this repo", comment: ""))
+            }
             Image(systemName: selected ? "checkmark.circle.fill" : "circle")
                 .font(.system(size: 17)).foregroundStyle(selected ? accent : Brand.textTertiary)
         }
@@ -428,5 +434,18 @@ struct MoItemRow: View {
         .contentShape(Rectangle())
         .onHover { hover = $0 }
         .onTapGesture { onToggle() }
+        .task { await checkGit() }
+    }
+
+    /// Purge-safety badge (C.11): flag rows whose folder sits in a repo with
+    /// uncommitted/unpushed work. Read-only — never changes what's selected.
+    private func checkGit() async {
+        let loc = item.location
+        guard loc.hasPrefix("/") || loc.hasPrefix("~") else { return }
+        let path = (loc as NSString).expandingTildeInPath
+        gitWarn = await Task.detached(priority: .utility) { () -> Bool in
+            guard let repo = GitSweep.repoRoot(for: path) else { return false }
+            return GitSweep.status(repo: repo)?.needsAttention ?? false
+        }.value
     }
 }

From e42a897ec545ae74bc992fa797d50fff23f13611 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 22:41:08 -0700
Subject: [PATCH 48/49] feat(sse): token-gated /events SSE stream (B.6)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EventHub holds open event-stream connections and fans out SSE frames (dead ones
self-evict). QueryServer serves GET /events?token=… (Store.queryAuthToken;
loopback-only server), exempting the stream from the idle-cancel timeout.
Threshold + new-startup-item alerts broadcast onto it. Token parse unit-tested.
---
 Sources/EventHub.swift       | 65 ++++++++++++++++++++++++++++++++++++
 Sources/Notifications.swift  |  3 ++
 Sources/QueryServer.swift    | 46 +++++++++++++++++++++++--
 Sources/Store.swift          | 10 ++++++
 Tests/QueryEventsTests.swift | 22 ++++++++++++
 5 files changed, 144 insertions(+), 2 deletions(-)
 create mode 100644 Sources/EventHub.swift
 create mode 100644 Tests/QueryEventsTests.swift

diff --git a/Sources/EventHub.swift b/Sources/EventHub.swift
new file mode 100644
index 00000000..92cff6e0
--- /dev/null
+++ b/Sources/EventHub.swift
@@ -0,0 +1,65 @@
+//
+//  EventHub.swift
+//  Burrow
+//
+//  The fan-out behind the SSE /events stream (roadmap B.6). Holds the open
+//  event-stream connections and broadcasts already-encoded SSE frames to them;
+//  dead connections self-evict on the next failed write or keep-alive tick, so
+//  there's no per-connection teardown plumbing to leak. Thread-safe.
+//
+
+import Foundation
+import Network
+
+final class EventHub {
+    static let shared = EventHub()
+
+    private let lock = NSLock()
+    private var conns: [ObjectIdentifier: NWConnection] = [:]
+    private var keepAlive: Timer?
+
+    private init() {}
+
+    func register(_ conn: NWConnection) {
+        lock.lock(); conns[ObjectIdentifier(conn)] = conn; lock.unlock()
+        startKeepAlive()
+    }
+
+    func deregister(_ conn: NWConnection) {
+        lock.lock(); conns[ObjectIdentifier(conn)] = nil; lock.unlock()
+    }
+
+    /// Is this connection an active event stream? The query server uses this
+    /// to exempt /events connections from its short idle-cancel timeout.
+    func isStreaming(_ conn: NWConnection) -> Bool {
+        lock.lock(); defer { lock.unlock() }
+        return conns[ObjectIdentifier(conn)] != nil
+    }
+
+    /// Fan an SSE-encoded frame out to every open connection, evicting any that
+    /// error on write.
+    func broadcast(_ frame: String) {
+        let data = Data(frame.utf8)
+        lock.lock(); let all = conns; lock.unlock()
+        for (id, c) in all {
+            c.send(content: data, completion: .contentProcessed { [weak self] err in
+                if err != nil { self?.deregisterID(id) }
+            })
+        }
+    }
+
+    private func deregisterID(_ id: ObjectIdentifier) {
+        lock.lock(); conns[id] = nil; lock.unlock()
+    }
+
+    private func startKeepAlive() {
+        DispatchQueue.main.async { [weak self] in
+            guard let self, self.keepAlive == nil else { return }
+            let t = Timer(timeInterval: 15, repeats: true) { _ in
+                EventHub.shared.broadcast(SSE.comment("keep-alive"))
+            }
+            RunLoop.main.add(t, forMode: .common)
+            self.keepAlive = t
+        }
+    }
+}
diff --git a/Sources/Notifications.swift b/Sources/Notifications.swift
index 3787b5e0..23e905f6 100644
--- a/Sources/Notifications.swift
+++ b/Sources/Notifications.swift
@@ -156,6 +156,7 @@ final class BurrowNotifier: NSObject {
             return
         }
         postReminder(title: title, body: body, pane: nil, id: "burrow-threshold-\(ruleID)")
+        EventHub.shared.broadcast(SSE.event("threshold", data: "{\"rule\":\"\(ruleID)\",\"value\":\(value)}"))
     }
 
     // MARK: Smart reminders
@@ -200,6 +201,8 @@ final class BurrowNotifier: NSObject {
                         title: NSLocalizedString("A new startup item appeared", comment: ""),
                         body: String(format: NSLocalizedString("“%@” now launches automatically. If you didn't add it, review it.", comment: ""), item.label),
                         pane: "apps", id: "burrow-startup-\(item.id)")
+                    let safeID = item.id.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
+                    EventHub.shared.broadcast(SSE.event("startup_item", data: "{\"id\":\"\(safeID)\"}"))
                 }
             }
         }
diff --git a/Sources/QueryServer.swift b/Sources/QueryServer.swift
index 5d124942..366decf8 100644
--- a/Sources/QueryServer.swift
+++ b/Sources/QueryServer.swift
@@ -100,7 +100,9 @@ final class QueryServer {
         // inside this window; cancelling an already-closed connection is a
         // no-op.
         self.queue.asyncAfter(deadline: .now() + 10) { [weak conn] in
-            conn?.cancel()
+            guard let conn else { return }
+            // SSE /events connections are long-lived; don't idle-cancel them.
+            if !EventHub.shared.isStreaming(conn) { conn.cancel() }
         }
         self.receive(conn, accumulated: Data())
     }
@@ -136,7 +138,9 @@ final class QueryServer {
             if let data { buf.append(data) }
             switch Self.nextAction(buffer: buf, isComplete: isComplete) {
             case .respond(let header):
-                self.send(self.route(header), on: conn)
+                if !self.tryServeEvents(header, on: conn) {
+                    self.send(self.route(header), on: conn)
+                }
             case .drop:
                 conn.cancel()
             case .keepReading:
@@ -171,6 +175,44 @@ final class QueryServer {
         conn.send(content: payload, completion: .contentProcessed { _ in conn.cancel() })
     }
 
+    // MARK: - SSE /events (B.6)
+
+    /// Parse the `token` query param from a request target. Static + pure so
+    /// the auth gate is unit-tested without a socket.
+    static func eventsToken(from target: String) -> String {
+        let parts = target.split(separator: "?", maxSplits: 1)
+        guard parts.count > 1 else { return "" }
+        for kv in parts[1].split(separator: "&") {
+            let p = kv.split(separator: "=", maxSplits: 1)
+            if p.count == 2, p[0] == "token" { return String(p[1]) }
+        }
+        return ""
+    }
+
+    /// Handle `GET /events`: a token-gated SSE stream. Returns true if it took
+    /// ownership of the connection (streaming, or 401'd it), false to fall
+    /// through to the normal one-shot router. The server binds loopback only,
+    /// so the token just keeps other local processes/pages from subscribing.
+    private func tryServeEvents(_ header: String, on conn: NWConnection) -> Bool {
+        let line = header.split(separator: "\r\n", maxSplits: 1).first.map(String.init) ?? ""
+        let parts = line.split(separator: " ")
+        guard parts.count >= 2, parts[0] == "GET" else { return false }
+        let target = String(parts[1])
+        guard target.split(separator: "?", maxSplits: 1).first.map(String.init) == "/events" else { return false }
+
+        guard !Store.queryAuthToken.isEmpty, Self.eventsToken(from: target) == Store.queryAuthToken else {
+            let resp = "HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\nConnection: close\r\n\r\n"
+            conn.send(content: Data(resp.utf8), completion: .contentProcessed { _ in conn.cancel() })
+            return true
+        }
+        let head = "HTTP/1.1 200 OK\r\n"
+            + "Content-Type: text/event-stream; charset=utf-8\r\n"
+            + "Cache-Control: no-store\r\nConnection: keep-alive\r\n\r\n"
+        conn.send(content: Data((head + SSE.comment("connected")).utf8), completion: .contentProcessed { _ in })
+        EventHub.shared.register(conn)
+        return true
+    }
+
     // MARK: - Routing
 
     /// Returns the response body and its content type. Everything is JSON
diff --git a/Sources/Store.swift b/Sources/Store.swift
index d54c4318..522dafe5 100644
--- a/Sources/Store.swift
+++ b/Sources/Store.swift
@@ -394,6 +394,16 @@ enum Store {
         set { write(newValue, "threshold_alerts_enabled") }
     }
 
+    /// Bearer token for the query server's SSE /events stream (B.6). Generated
+    /// once and persisted; agents pass it as `?token=…`. The server is loopback-
+    /// only, so this just stops other local processes/pages from subscribing.
+    static var queryAuthToken: String {
+        if let t = d.string(forKey: "query_auth_token"), !t.isEmpty { return t }
+        let t = UUID().uuidString
+        write(t, "query_auth_token")
+        return t
+    }
+
     // Reminder throttle state (not user-facing): hysteresis flags so a
     // metric hovering at its threshold can't flap, timestamps for the
     // weekly cooldowns. See ReminderRules (Notifications.swift).
diff --git a/Tests/QueryEventsTests.swift b/Tests/QueryEventsTests.swift
new file mode 100644
index 00000000..a33c7cae
--- /dev/null
+++ b/Tests/QueryEventsTests.swift
@@ -0,0 +1,22 @@
+//
+//  QueryEventsTests.swift
+//  BurrowTests
+//
+//  The SSE /events auth gate (roadmap B.6): the token parse is pure, so it's
+//  unit-tested without a socket. (The streaming itself is exercised by hand.)
+//
+
+import XCTest
+@testable import Burrow
+
+final class QueryEventsTests: XCTestCase {
+    func testEventsToken_parsesTokenParam() {
+        XCTAssertEqual(QueryServer.eventsToken(from: "/events?token=abc123"), "abc123")
+        XCTAssertEqual(QueryServer.eventsToken(from: "/events?foo=1&token=xy&bar=2"), "xy")
+    }
+
+    func testEventsToken_absent_isEmpty() {
+        XCTAssertEqual(QueryServer.eventsToken(from: "/events"), "")
+        XCTAssertEqual(QueryServer.eventsToken(from: "/events?foo=1"), "")
+    }
+}

From 20637b280aaf9fd1744098ac4cb65545d3864bf5 Mon Sep 17 00:00:00 2001
From: caezium <113233555+caezium@users.noreply.github.com>
Date: Mon, 15 Jun 2026 22:46:23 -0700
Subject: [PATCH 49/49] =?UTF-8?q?fix(sse):=20rename=20SSE=20=E2=86=92=20SS?=
 =?UTF-8?q?EFrame=20(avoid=20AppKit-scope=20symbol=20clash)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

'SSE' resolved as an out-of-scope symbol in Notifications.swift (imports AppKit);
EventHub/QueryServer (no AppKit) were fine. Renamed the type to disambiguate.
---
 Sources/EventHub.swift      |  2 +-
 Sources/Notifications.swift |  4 ++--
 Sources/QueryServer.swift   |  2 +-
 Sources/SSE.swift           | 34 ++++++++++++++++++++++++++++++++++
 Tests/SSETests.swift        | 32 ++++++++++++++++++++++++++++++++
 5 files changed, 70 insertions(+), 4 deletions(-)
 create mode 100644 Sources/SSE.swift
 create mode 100644 Tests/SSETests.swift

diff --git a/Sources/EventHub.swift b/Sources/EventHub.swift
index 92cff6e0..eab1e5f8 100644
--- a/Sources/EventHub.swift
+++ b/Sources/EventHub.swift
@@ -56,7 +56,7 @@ final class EventHub {
         DispatchQueue.main.async { [weak self] in
             guard let self, self.keepAlive == nil else { return }
             let t = Timer(timeInterval: 15, repeats: true) { _ in
-                EventHub.shared.broadcast(SSE.comment("keep-alive"))
+                EventHub.shared.broadcast(SSEFrame.comment("keep-alive"))
             }
             RunLoop.main.add(t, forMode: .common)
             self.keepAlive = t
diff --git a/Sources/Notifications.swift b/Sources/Notifications.swift
index 23e905f6..23ae3634 100644
--- a/Sources/Notifications.swift
+++ b/Sources/Notifications.swift
@@ -156,7 +156,7 @@ final class BurrowNotifier: NSObject {
             return
         }
         postReminder(title: title, body: body, pane: nil, id: "burrow-threshold-\(ruleID)")
-        EventHub.shared.broadcast(SSE.event("threshold", data: "{\"rule\":\"\(ruleID)\",\"value\":\(value)}"))
+        EventHub.shared.broadcast(SSEFrame.event("threshold", data: "{\"rule\":\"\(ruleID)\",\"value\":\(value)}"))
     }
 
     // MARK: Smart reminders
@@ -202,7 +202,7 @@ final class BurrowNotifier: NSObject {
                         body: String(format: NSLocalizedString("“%@” now launches automatically. If you didn't add it, review it.", comment: ""), item.label),
                         pane: "apps", id: "burrow-startup-\(item.id)")
                     let safeID = item.id.replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
-                    EventHub.shared.broadcast(SSE.event("startup_item", data: "{\"id\":\"\(safeID)\"}"))
+                    EventHub.shared.broadcast(SSEFrame.event("startup_item", data: "{\"id\":\"\(safeID)\"}"))
                 }
             }
         }
diff --git a/Sources/QueryServer.swift b/Sources/QueryServer.swift
index 366decf8..ec3a6a15 100644
--- a/Sources/QueryServer.swift
+++ b/Sources/QueryServer.swift
@@ -208,7 +208,7 @@ final class QueryServer {
         let head = "HTTP/1.1 200 OK\r\n"
             + "Content-Type: text/event-stream; charset=utf-8\r\n"
             + "Cache-Control: no-store\r\nConnection: keep-alive\r\n\r\n"
-        conn.send(content: Data((head + SSE.comment("connected")).utf8), completion: .contentProcessed { _ in })
+        conn.send(content: Data((head + SSEFrame.comment("connected")).utf8), completion: .contentProcessed { _ in })
         EventHub.shared.register(conn)
         return true
     }
diff --git a/Sources/SSE.swift b/Sources/SSE.swift
new file mode 100644
index 00000000..9b97399f
--- /dev/null
+++ b/Sources/SSE.swift
@@ -0,0 +1,34 @@
+//
+//  SSE.swift
+//  Burrow
+//
+//  Server-Sent Events encoding (roadmap B.6). Pure text framing for the
+//  `GET /events` stream so agents can react to threshold alerts, new
+//  LaunchAgents, and operation lifecycle instead of polling. The long-lived
+//  Network.framework response, the AlertEngine source, and the off-by-default
+//  + token + Origin/Host gating are integration; this is just the wire format,
+//  which is fiddly enough (multi-line data, keep-alive comments) to deserve
+//  its own tested unit.
+//
+
+import Foundation
+
+enum SSEFrame {
+    /// Encode one event. Multi-line `data` is split so each physical line
+    /// gets its own `data:` field, per the SSE spec; the trailing blank line
+    /// dispatches the event on the client.
+    static func event(_ type: String, data: String, id: Int? = nil) -> String {
+        var out = ""
+        if let id { out += "id: \(id)\n" }
+        out += "event: \(type)\n"
+        for line in data.split(separator: "\n", omittingEmptySubsequences: false) {
+            out += "data: \(line)\n"
+        }
+        out += "\n"
+        return out
+    }
+
+    /// A comment line — used as a keep-alive so proxies don't drop an idle
+    /// stream. Clients ignore comments.
+    static func comment(_ text: String) -> String { ": \(text)\n\n" }
+}
diff --git a/Tests/SSETests.swift b/Tests/SSETests.swift
new file mode 100644
index 00000000..807b8a65
--- /dev/null
+++ b/Tests/SSETests.swift
@@ -0,0 +1,32 @@
+//
+//  SSETests.swift
+//  BurrowTests
+//
+//  SSE wire framing (roadmap B.6), tested through `event`/`comment`.
+//
+
+import XCTest
+@testable import Burrow
+
+final class SSETests: XCTestCase {
+    func testEvent_singleLine() {
+        let s = SSEFrame.event("alert", data: "{\"k\":1}")
+        XCTAssertEqual(s, "event: alert\ndata: {\"k\":1}\n\n")
+    }
+
+    func testEvent_withId() {
+        let s = SSEFrame.event("alert", data: "x", id: 7)
+        XCTAssertTrue(s.hasPrefix("id: 7\nevent: alert\n"))
+    }
+
+    func testEvent_multiLineDataGetsPerLinePrefix() {
+        let s = SSEFrame.event("log", data: "line1\nline2")
+        XCTAssertTrue(s.contains("data: line1\n"))
+        XCTAssertTrue(s.contains("data: line2\n"))
+        XCTAssertTrue(s.hasSuffix("\n\n"), "event terminates with a blank line")
+    }
+
+    func testComment_isIgnorableKeepAlive() {
+        XCTAssertEqual(SSEFrame.comment("keep-alive"), ": keep-alive\n\n")
+    }
+}