feat(api): add ContainerLogOptions {since, timestamps} to ContainerClient.logs

Adds an additive overload to ContainerClient.logs that accepts a
ContainerLogOptions { since: Date?, timestamps: Bool } and plumbs the
two parameters through XPC into the daemon's existing log-handle path.

Motivation
----------

External orchestrators that drive the API server (the canonical use
case is a Compose-spec orchestrator implementing 'compose logs --since
<timestamp>' and '--timestamps') need to retrieve only recent log
output and optionally annotate lines with timestamps. Today
ContainerClient.logs(id:) returns raw containerLog + bootlog file
handles unconditionally; consumers either replay the entire log buffer
or implement their own line-by-line filter on the client. Surfacing
the parameters at the API boundary keeps the line scanning where the
file lives — server-side — and matches the docker-compose UX users
expect.

What this PR changes
--------------------

- Sources/ContainerResource/Container/ContainerLogOptions.swift (new):
  the ContainerLogOptions struct, Sendable + Codable, with a static
  '.default' equivalent to the original logs(id:) zero-config call.
- Sources/Services/ContainerAPIService/Client/XPC+.swift: two new
  XPCKeys cases ('logSince', 'logTimestamps') for the optional
  parameters.
- Sources/Services/ContainerAPIService/Client/ContainerClient.swift:
  new logs(id:options:) overload. The existing logs(id:) is retained
  as a thin wrapper over .default for source compatibility.
- Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift:
  matching logs(id:options:) overload; when options.since is provided,
  applies a private 'filterFileHandleSince' that parses ISO-8601
  timestamps from line starts and drops older lines (lines without a
  parseable timestamp pass through unchanged).
- Sources/Services/ContainerAPIService/Server/Containers/ContainersHarness.swift:
  parses the two optional XPC keys, builds ContainerLogOptions, and
  forwards to the new service overload.

Wire compatibility
------------------

XPC calls without the new keys decode as 'sinceRaw.timeIntervalSince1970
== 0' (the harness treats this as 'no since filter') and 'timestamps =
false', so older clients hitting a newer server see unchanged behavior.
Newer clients hitting an older server send the keys; an old harness
will silently drop them and run the original codepath.

Known limitations (intentional, follow-up work)
-----------------------------------------------

- The 'options.timestamps' parameter is plumbed end-to-end but the
  daemon does not currently decorate raw log lines that lack a
  timestamp prefix. Line decoration is a deliberate follow-up; keeping
  the parameter on the API surface today avoids a second wire-format
  break later.
- 'filterFileHandleSince' currently slurps the file into memory then
  returns a Pipe-backed FileHandle. For the typical container log
  size this is fine; for very large logs a streaming line iterator
  would be a worthwhile optimization. Filed as a known-issue for the
  follow-up timestamp-decoration PR.

Verification
------------

Full 'swift build' clean on macOS 26 / Apple silicon (release config,
all targets including downstream consumers of ContainerClient.logs).

Author: chrisgeo

Sources/ContainerResource/Container/ContainerLogOptions.swift

@@ -0,0 +1,42 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2026 Apple Inc. and the container project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import Foundation
+
+/// Options that refine how `ContainerClient.logs(id:options:)` returns
+/// container log file handles.
+///
+/// Both fields are optional / additive; ``default`` is the zero-value
+/// equivalent to the original `logs(id:)` behavior.
+public struct ContainerLogOptions: Sendable, Codable {
+    /// If non-nil, log lines whose ISO-8601 timestamp prefix is older than
+    /// this date are filtered out before the file handle is returned to the
+    /// client. Lines without a parseable timestamp are passed through
+    /// unchanged.
+    public let since: Date?
+
+    /// If true, the client wants timestamps preserved on the returned lines.
+    /// At present this is a hint only — the daemon does not decorate raw log
+    /// lines that lack a timestamp prefix; line decoration is a follow-up.
+    public let timestamps: Bool
+
+    public static let `default` = ContainerLogOptions(since: nil, timestamps: false)
+
+    public init(since: Date? = nil, timestamps: Bool = false) {
+        self.since = since
+        self.timestamps = timestamps
+    }
+}

Sources/Services/ContainerAPIService/Client/ContainerClient.swift

@@ -264,9 +264,23 @@ public struct ContainerClient: Sendable {
 
     /// Get the log file handles for a container.
     public func logs(id: String) async throws -> [FileHandle] {
+        try await logs(id: id, options: .default)
+    }
+
+    /// Get the log file handles for a container, refined by ``ContainerLogOptions``.
+    ///
+    /// `options.since` filters out log lines whose ISO-8601 timestamp prefix
+    /// predates the given date; lines without a parseable timestamp are
+    /// passed through. `options.timestamps` is forwarded to the daemon as a
+    /// hint; line-level timestamp decoration is a deferred follow-up.
+    public func logs(id: String, options: ContainerLogOptions) async throws -> [FileHandle] {
         do {
             let request = XPCMessage(route: .containerLogs)
             request.set(key: .id, value: id)
+            if let since = options.since {
+                request.set(key: .logSince, value: since)
+            }
+            request.set(key: .logTimestamps, value: options.timestamps)
 
             let response = try await xpcClient.send(request)
             let fds = response.fileHandles(key: .logs)

Sources/Services/ContainerAPIService/Client/XPC+.swift

@@ -147,6 +147,11 @@ public enum XPCKeys: String {
     case destinationPath
     case fileMode
     case createParents
+
+    /// Optional `since: Date` filter on `logs`.
+    case logSince
+    /// Optional `timestamps: Bool` flag on `logs`.
+    case logTimestamps
 }
 
 public enum XPCRoute: String {

Sources/Services/ContainerAPIService/Server/Containers/ContainersHarness.swift

@@ -289,7 +289,16 @@ public struct ContainersHarness: Sendable {
                 message: "id cannot be empty"
             )
         }
-        let fds = try await service.logs(id: id)
+
+        var since: Date? = nil
+        let sinceRaw = message.date(key: .logSince)
+        if sinceRaw.timeIntervalSince1970 > 0 {
+            since = sinceRaw
+        }
+        let timestamps = message.bool(key: .logTimestamps)
+        let options = ContainerLogOptions(since: since, timestamps: timestamps)
+
+        let fds = try await service.logs(id: id, options: options)
         let reply = message.reply()
         try reply.set(key: .logs, value: fds)
         return reply

Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift

@@ -729,8 +729,11 @@ public actor ContainersService {
         try await client.resize(processID, size: size)
     }
 
-    // Get the logs for the container.
     public func logs(id: String) async throws -> [FileHandle] {
+        try await logs(id: id, options: .default)
+    }
+
+    public func logs(id: String, options: ContainerLogOptions) async throws -> [FileHandle] {
         log.debug(
             "ContainersService: enter",
             metadata: [
@@ -748,18 +751,22 @@ public actor ContainersService {
             )
         }
 
-        // Logs doesn't care if the container is running or not, just that
-        // the bundle is there, and that the files actually exist. We do
-        // first try and get the container state so we get a nicer error message
-        // (container foo not found) however.
         do {
             _ = try _getContainerState(id: id)
             let path = self.containerRoot.appendingPathComponent(id)
             let bundle = ContainerResource.Bundle(path: path)
-            return [
+            var handles = [
                 try FileHandle(forReadingFrom: bundle.containerLog),
                 try FileHandle(forReadingFrom: bundle.bootlog),
             ]
+
+            if let since = options.since {
+                handles = handles.map { fh in
+                    Self.filterFileHandleSince(fh, since: since)
+                }
+            }
+
+            return handles
         } catch {
             throw ContainerizationError(
                 .internalError,
@@ -792,6 +799,44 @@ public actor ContainersService {
         try await client.copyOut(source: source, destination: destination, createParents: createParents)
     }
 
+    private static func filterFileHandleSince(_ fh: FileHandle, since: Date) -> FileHandle {
+        guard let data = try? fh.readToEnd(),
+              let content = String(data: data, encoding: .utf8) else {
+            return fh
+        }
+
+        let iso8601 = ISO8601DateFormatter()
+        iso8601.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        let fallbackFormatter = ISO8601DateFormatter()
+        fallbackFormatter.formatOptions = [.withInternetDateTime]
+
+        let lines = content.components(separatedBy: .newlines)
+        var filtered: [String] = []
+        for line in lines {
+            guard !line.isEmpty else { continue }
+            let parts = line.split(separator: " ", maxSplits: 1)
+            guard let timestampStr = parts.first else {
+                filtered.append(line)
+                continue
+            }
+            if let date = iso8601.date(from: String(timestampStr)) ?? fallbackFormatter.date(from: String(timestampStr)) {
+                if date >= since {
+                    filtered.append(line)
+                }
+            } else {
+                filtered.append(line)
+            }
+        }
+
+        let pipe = Pipe()
+        let result = filtered.joined(separator: "\n")
+        if let resultData = result.data(using: .utf8) {
+            pipe.fileHandleForWriting.write(resultData)
+        }
+        try? pipe.fileHandleForWriting.close()
+        return pipe.fileHandleForReading
+    }
+
     /// Get statistics for the container.
     public func stats(id: String) async throws -> ContainerStats {
         log.debug(