feat: add Tier 2 fork APIs (CHAOS-1319/1321/1322/1323/1324)

- Flags.ProcessBase: minimal subset without -e/-u/-w/-i/-t short flags
- ContainerLogOptions: since/timestamps parameters for logs API
- HealthStatus enum + health field on ContainerSnapshot
- ContainerEvent type + event recording in lifecycle methods + events() API
- RestartPolicy type + restartPolicy on ContainerCreateOptions + --restart flag

Author: chrisgeo

Sources/APIServer/APIServer+Start.swift

@@ -285,6 +285,7 @@ extension APIServer {
             routes[XPCRoute.containerStats] = harness.stats
             routes[XPCRoute.containerDiskUsage] = harness.diskUsage
             routes[XPCRoute.containerExport] = harness.export
+            routes[XPCRoute.containerEvent] = harness.events
 
             return service
         }

Sources/ContainerCommands/Container/ContainerRun.swift

@@ -104,7 +104,11 @@ extension Application {
 
             progress.set(description: "Starting container")
 
-            let options = ContainerCreateOptions(autoRemove: managementFlags.remove)
+            let restartPolicy = Self.parseRestartPolicy(managementFlags.restart)
+            let options = ContainerCreateOptions(
+                autoRemove: managementFlags.remove,
+                restartPolicy: restartPolicy
+            )
             try await client.create(
                 configuration: ck.0,
                 options: options,
@@ -172,5 +176,18 @@ extension Application {
             }
             throw ArgumentParser.ExitCode(exitCode)
         }
+
+        static func parseRestartPolicy(_ raw: String?) -> RestartPolicy? {
+            guard let raw, !raw.isEmpty else { return nil }
+            if raw == "no" { return .none }
+            if raw == "always" { return RestartPolicy(mode: .always) }
+            if raw == "unless-stopped" { return RestartPolicy(mode: .unlessStopped) }
+            if raw.hasPrefix("on-failure") {
+                let parts = raw.split(separator: ":", maxSplits: 1)
+                let retries = parts.count > 1 ? Int(parts[1]) ?? 0 : 0
+                return RestartPolicy(mode: .onFailure, maxRetries: retries)
+            }
+            return nil
+        }
     }
 }

Sources/ContainerResource/Container/ContainerCreateOptions.swift

@@ -15,14 +15,14 @@
 //===----------------------------------------------------------------------===//
 
 public struct ContainerCreateOptions: Codable, Sendable {
-    /// Remove the container and wipe out its data on container stop
     public let autoRemove: Bool
-    /// Override the rootFs with this one other than the image-cloned version
     public let rootFsOverride: Filesystem?
+    public let restartPolicy: RestartPolicy?
 
-    public init(autoRemove: Bool, rootFsOverride: Filesystem? = nil) {
+    public init(autoRemove: Bool, rootFsOverride: Filesystem? = nil, restartPolicy: RestartPolicy? = nil) {
         self.autoRemove = autoRemove
         self.rootFsOverride = rootFsOverride
+        self.restartPolicy = restartPolicy
     }
 
     public static let `default` = ContainerCreateOptions(autoRemove: false)

Sources/ContainerResource/Container/ContainerEvent.swift

@@ -0,0 +1,37 @@
+//===----------------------------------------------------------------------===//
+// 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
+
+public struct ContainerEvent: Codable, Sendable, Equatable {
+    public enum Action: String, Codable, Sendable, Equatable {
+        case create
+        case start
+        case stop
+        case die
+        case destroy
+    }
+
+    public let containerId: String
+    public let action: Action
+    public let timestamp: Date
+
+    public init(containerId: String, action: Action, timestamp: Date = Date()) {
+        self.containerId = containerId
+        self.action = action
+        self.timestamp = timestamp
+    }
+}

Sources/ContainerResource/Container/ContainerLogOptions.swift

@@ -0,0 +1,29 @@
+//===----------------------------------------------------------------------===//
+// 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
+
+public struct ContainerLogOptions: Sendable, Codable {
+    public let since: Date?
+    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/ContainerResource/Container/ContainerSnapshot.swift

@@ -43,18 +43,21 @@ public struct ContainerSnapshot: Codable, Sendable {
     /// Populated when the container transitions to ``RuntimeStatus/stopped``.
     /// `nil` if the container has never exited or its exit was not captured.
     public var lastExitCode: Int32?
+    public var health: HealthStatus?
 
     public init(
         configuration: ContainerConfiguration,
         status: RuntimeStatus,
         networks: [Attachment],
         startedDate: Date? = nil,
-        lastExitCode: Int32? = nil
+        lastExitCode: Int32? = nil,
+        health: HealthStatus? = nil
     ) {
         self.configuration = configuration
         self.status = status
         self.networks = networks
         self.startedDate = startedDate
         self.lastExitCode = lastExitCode
+        self.health = health
     }
 }

Sources/ContainerResource/Container/HealthStatus.swift

@@ -0,0 +1,24 @@
+//===----------------------------------------------------------------------===//
+// 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
+
+public enum HealthStatus: String, CaseIterable, Sendable, Codable {
+    case none
+    case starting
+    case healthy
+    case unhealthy
+}

Sources/ContainerResource/Container/RestartPolicy.swift

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+// 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
+
+public struct RestartPolicy: Codable, Sendable, Equatable {
+    public enum Mode: String, Codable, Sendable, Equatable {
+        case no
+        case always
+        case onFailure = "on-failure"
+        case unlessStopped = "unless-stopped"
+    }
+
+    public let mode: Mode
+    public let maxRetries: Int
+
+    public static let none = RestartPolicy(mode: .no, maxRetries: 0)
+
+    public init(mode: Mode, maxRetries: Int = 0) {
+        self.mode = mode
+        self.maxRetries = maxRetries
+    }
+}

Sources/Services/ContainerAPIService/Client/ContainerClient.swift

@@ -262,11 +262,18 @@ 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)
+    }
+
+    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)
@@ -349,4 +356,21 @@ public struct ContainerClient: Sendable {
             )
         }
     }
+
+    public func events() async throws -> [ContainerEvent] {
+        do {
+            let request = XPCMessage(route: .containerEvent)
+            let response = try await xpcClient.send(request)
+            guard let data = response.dataNoCopy(key: .containerEvent) else {
+                return []
+            }
+            return try JSONDecoder().decode([ContainerEvent].self, from: data)
+        } catch {
+            throw ContainerizationError(
+                .internalError,
+                message: "failed to get container events",
+                cause: error
+            )
+        }
+    }
 }

Sources/Services/ContainerAPIService/Client/Flags.swift

@@ -30,6 +30,34 @@ public struct Flags {
         public var debug = false
     }
 
+    /// Minimal subset of process-related flags that don't claim the common
+    /// short flags (`-e`, `-u`, `-w`, `-i`, `-t`). Downstream tools like
+    /// Container-Compose can `@OptionGroup` this instead of `Flags.Process`
+    /// to reclaim those short names for their own compose-specific options.
+    public struct ProcessBase: ParsableArguments {
+        public init() {}
+
+        public init(cwd: String?, envFile: [String]) {
+            self.cwd = cwd
+            self.envFile = envFile
+        }
+
+        @Option(
+            name: .long,
+            help: .init(
+                "Set the initial working directory inside the container",
+                valueName: "dir"
+            )
+        )
+        public var cwd: String?
+
+        @Option(
+            name: .long,
+            help: "Read in a file of environment variables (key=value format, ignores # comments and blank lines)"
+        )
+        public var envFile: [String] = []
+    }
+
     public struct Process: ParsableArguments {
         public init() {}
 
@@ -341,6 +369,9 @@ public struct Flags {
 
         @Option(name: [.customLong("volume"), .short], help: "Bind mount a volume into the container")
         public var volumes: [String] = []
+
+        @Option(name: .long, help: "Restart policy (no, always, on-failure[:max-retries], unless-stopped)")
+        public var restart: String?
     }
 
     public struct Progress: ParsableArguments {