Remember why a container stopped across an apiserver restart

The exit code lived only in the in-memory ContainerState, so it survived
exactly as long as the apiserver process did. Restart the engine and a
container that had died with 127 was indistinguishable from one stopped
on purpose - which is the moment you most want the answer, since you are
usually restarting *because* something went wrong.

- ExitRecord is written to exit.json in the container bundle when
  handleContainerExit sees a code, and read back by loadAtBoot into the
  snapshot it builds. Bundle already owned this directory's layout, so
  the read/write pair sits there next to the other bundle files.
- A failed write is logged, not thrown: the container really has exited,
  and refusing to record that would leave the state machine wedged.
- ContainerStatus carries exitCode/exitedAt too, so `container inspect`
  shows them. ManagedContainer is what the CLI serializes, and it was
  dropping both on the floor.

Author: devops-thiago

Sources/ContainerResource/Container/Bundle.swift

@@ -26,6 +26,10 @@ public struct Bundle: Sendable {
     private static let containerRootFsFilename = "rootfs.json"
 
     static let containerConfigFilename = "config.json"
+    /// Why the container last stopped. Persisted beside the configuration so the
+    /// answer survives an apiserver restart — in memory only, every stopped
+    /// container looks alike after a restart.
+    public static let exitStatusFilename = "exit.json"
 
     /// The path to the bundle.
     public let path: URL
@@ -154,6 +158,16 @@ extension Bundle {
         try FileManager.default.removeItem(at: self.path)
     }
 
+    /// The recorded exit of the container's initial process, if it has stopped at least
+    /// once. Absent for one that has never run.
+    public var exitStatus: ExitRecord? {
+        try? load(filename: Self.exitStatusFilename)
+    }
+
+    public func setExitStatus(_ record: ExitRecord) throws {
+        try write(filename: Self.exitStatusFilename, value: record)
+    }
+
     public func write(filename: String, value: Encodable) throws {
         try Self.write(self.path.appendingPathComponent(filename), value: value)
     }

Sources/ContainerResource/Container/ContainerStatus.swift

@@ -25,10 +25,24 @@ public struct ContainerStatus: Codable, Sendable {
     public let networks: [Attachment]
     /// When the container was started, if it has been.
     public let startedDate: Date?
+    /// The exit code of the container's initial process, once it has exited.
+    /// `nil` while running, and for containers stopped by an engine that
+    /// predates the recorded exit status.
+    public let exitCode: Int32?
+    /// When the container's initial process exited.
+    public let exitedAt: Date?
 
-    public init(state: RuntimeStatus, networks: [Attachment], startedDate: Date? = nil) {
+    public init(
+        state: RuntimeStatus,
+        networks: [Attachment],
+        startedDate: Date? = nil,
+        exitCode: Int32? = nil,
+        exitedAt: Date? = nil
+    ) {
         self.state = state
         self.networks = networks
         self.startedDate = startedDate
+        self.exitCode = exitCode
+        self.exitedAt = exitedAt
     }
 }

Sources/ContainerResource/Container/ExitRecord.swift

@@ -0,0 +1,32 @@
+//===----------------------------------------------------------------------===//
+// 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
+
+/// How a container's initial process last exited.
+///
+/// Written to the container's bundle when it stops, so the reason outlives the apiserver.
+/// Kept in memory alone, a restart erased it and every stopped container looked identical
+/// — including the one that had crashed.
+public struct ExitRecord: Codable, Sendable, Equatable {
+    public let exitCode: Int32
+    public let exitedAt: Date
+
+    public init(exitCode: Int32, exitedAt: Date) {
+        self.exitCode = exitCode
+        self.exitedAt = exitedAt
+    }
+}

Sources/ContainerResource/Container/ManagedContainer.swift

@@ -62,7 +62,9 @@ public struct ManagedContainer: ManagedResource {
         self.status = ContainerStatus(
             state: snapshot.status,
             networks: snapshot.networks,
-            startedDate: snapshot.startedDate
+            startedDate: snapshot.startedDate,
+            exitCode: snapshot.exitCode,
+            exitedAt: snapshot.exitedAt
         )
     }
 }

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

@@ -132,12 +132,15 @@ public actor ContainersService {
                     continue
                 }
 
+                let exit = ContainerResource.Bundle(path: dir).exitStatus
                 let state = ContainerState(
                     snapshot: .init(
                         configuration: config,
                         status: .stopped,
                         networks: [],
-                        startedDate: nil
+                        startedDate: nil,
+                        exitCode: exit?.exitCode,
+                        exitedAt: exit?.exitedAt
                     ),
                 )
                 results[config.id] = state
@@ -992,10 +995,19 @@ public actor ContainersService {
 
         state.snapshot.status = .stopped
         state.snapshot.networks = []
-        // Keep why it stopped, not just that it did.
+        // Keep why it stopped, not just that it did — in memory for this apiserver, and
+        // on disk so the answer survives a restart.
         if let code {
             state.snapshot.exitCode = code.exitCode
             state.snapshot.exitedAt = code.exitedAt
+            do {
+                try bundle.setExitStatus(
+                    ExitRecord(exitCode: code.exitCode, exitedAt: code.exitedAt))
+            } catch {
+                self.log.warning(
+                    "failed to record exit status",
+                    metadata: ["id": "\(id)", "error": "\(error)"])
+            }
         }
         state.client = nil
         await self.setContainerState(id, state, context: context)