dst-server 0.4.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. {dst_server-0.4.0 → dst_server-0.5.0}/Cargo.lock +2 -2
  2. {dst_server-0.4.0 → dst_server-0.5.0}/Cargo.toml +1 -1
  3. {dst_server-0.4.0 → dst_server-0.5.0}/PKG-INFO +33 -16
  4. {dst_server-0.4.0 → dst_server-0.5.0}/README.md +32 -15
  5. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/agent.rs +177 -229
  6. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/archive.rs +6 -19
  7. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/cli.rs +18 -28
  8. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/configuration.rs +7 -11
  9. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/deployment.rs +20 -1
  10. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/external.rs +2 -3
  11. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/files.rs +11 -13
  12. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/host.rs +342 -38
  13. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/host_operations.rs +2 -19
  14. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/model.rs +2 -21
  15. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/mods.rs +2 -12
  16. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/policy.rs +54 -4
  17. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/preloader.rs +0 -20
  18. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/probe.rs +27 -59
  19. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/recovery.rs +7 -9
  20. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/room.rs +3 -11
  21. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/rooms.rs +2 -2
  22. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/rpc.rs +148 -53
  23. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/settings.rs +5 -8
  24. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/agent.rs +230 -91
  25. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/fixtures/game.py +8 -0
  26. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/policy.rs +1 -1
  27. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/rpc.rs +52 -0
  28. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/archive.rs +8 -11
  29. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/host.rs +2 -20
  30. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/lib.rs +16 -1
  31. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/logs.rs +2 -9
  32. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/settings.rs +12 -19
  33. {dst_server-0.4.0 → dst_server-0.5.0}/pyproject.toml +1 -1
  34. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/archive.py +2 -5
  35. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/logs.py +2 -5
  36. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/commands.lua +3 -2
  37. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/message_events.lua +14 -26
  38. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/values.lua +2 -1
  39. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server.lua +10 -10
  40. {dst_server-0.4.0 → dst_server-0.5.0}/LICENSE +0 -0
  41. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/Cargo.toml +0 -0
  42. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/build.rs +0 -0
  43. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/examples/rpc_fixture.rs +0 -0
  44. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/resources/events.json +0 -0
  45. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/resources/settings/defaults.json +0 -0
  46. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/resources/settings/ini.json +0 -0
  47. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/resources/settings/presets.json +0 -0
  48. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/resources/settings/schemas.json +0 -0
  49. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/schema/room.capnp +0 -0
  50. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/annotations.rs +0 -0
  51. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/archive_cli.rs +0 -0
  52. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/driver.rs +0 -0
  53. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/events.rs +0 -0
  54. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/host_cli.rs +0 -0
  55. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/lib.rs +0 -0
  56. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/logs.rs +0 -0
  57. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/logs_cli.rs +0 -0
  58. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/lua.rs +0 -0
  59. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/main.rs +0 -0
  60. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/observability.rs +0 -0
  61. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/process.rs +0 -0
  62. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/scripts.rs +0 -0
  63. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/src/telemetry.rs +0 -0
  64. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/driver.rs +0 -0
  65. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/events.rs +0 -0
  66. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/external.rs +0 -0
  67. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/filesystem_failures.rs +0 -0
  68. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/fixtures/fleet_systemctl.py +0 -0
  69. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/fleet.rs +0 -0
  70. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/logs.rs +0 -0
  71. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/model.rs +0 -0
  72. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/mods.rs +0 -0
  73. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/observability.rs +0 -0
  74. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/otlp.rs +0 -0
  75. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/otlp_tls.rs +0 -0
  76. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/process.rs +0 -0
  77. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/room.rs +0 -0
  78. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server/tests/telemetry_config.rs +0 -0
  79. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/Cargo.toml +0 -0
  80. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/events.rs +0 -0
  81. {dst_server-0.4.0 → dst_server-0.5.0}/crates/dst-server-python/src/external.rs +0 -0
  82. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/__init__.py +0 -0
  83. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/__main__.py +0 -0
  84. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/_native.pyi +0 -0
  85. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/events.py +0 -0
  86. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/external.py +0 -0
  87. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/host.py +0 -0
  88. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/py.typed +0 -0
  89. {dst_server-0.4.0 → dst_server-0.5.0}/python/dst_server/settings.py +0 -0
  90. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/components/dst_server_runtime.lua +0 -0
  91. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/actions.lua +0 -0
  92. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/bootstrap.lua +0 -0
  93. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/connections.lua +0 -0
  94. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/console.lua +0 -0
  95. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/gameplay_events.lua +0 -0
  96. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/input_events.lua +0 -0
  97. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/load_observer.lua +0 -0
  98. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/mode_votes.lua +0 -0
  99. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/player_events.lua +0 -0
  100. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/player_queries.lua +0 -0
  101. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/player_values.lua +0 -0
  102. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/recovery.lua +0 -0
  103. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/rpc.lua +0 -0
  104. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/save_observer.lua +0 -0
  105. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/state.lua +0 -0
  106. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/telemetry.lua +0 -0
  107. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/vote_events.lua +0 -0
  108. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/wire.lua +0 -0
  109. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/world_events.lua +0 -0
  110. {dst_server-0.4.0 → dst_server-0.5.0}/resources/lua/dst_server/world_queries.lua +0 -0
  111. {dst_server-0.4.0 → dst_server-0.5.0}/rust-toolchain.toml +0 -0
@@ -654,7 +654,7 @@ dependencies = [
654
654
 
655
655
  [[package]]
656
656
  name = "dst-server"
657
- version = "0.4.0"
657
+ version = "0.5.0"
658
658
  dependencies = [
659
659
  "anyhow",
660
660
  "capnp",
@@ -695,7 +695,7 @@ dependencies = [
695
695
 
696
696
  [[package]]
697
697
  name = "dst-server-python"
698
- version = "0.4.0"
698
+ version = "0.5.0"
699
699
  dependencies = [
700
700
  "anyhow",
701
701
  "dst-server",
@@ -3,7 +3,7 @@ members = ["crates/dst-server", "crates/dst-server-python"]
3
3
  resolver = "3"
4
4
 
5
5
  [workspace.package]
6
- version = "0.4.0"
6
+ version = "0.5.0"
7
7
  edition = "2024"
8
8
  rust-version = "1.99"
9
9
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: dst-server
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  License-File: LICENSE
5
5
  Summary: Native SDK and room agent for Don't Starve Together.
6
6
  License-Expression: MIT
@@ -15,16 +15,18 @@ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
15
15
  English | [简体中文](README.zh-Hans.md)
16
16
 
17
17
  A Rust SDK, Agent and CLI for Don't Starve Together, with Python bindings.
18
- Each room runs in one container: one Agent supervises every configured shard and remains available while the games are closed.
18
+ Each room runs in one container: one Agent supervises every configured shard and exits with the games when the room closes.
19
+ An external scheduler starts the container at each opening.
19
20
  Published binaries and Python wheels support Linux x86_64 and CPython 3.14.
20
21
  The control socket is for trusted callers on the same host.
21
22
 
22
- Version `0.4.0` replaces the earlier Python implementation.
23
+ Version `0.4.0` replaced the earlier Python implementation.
24
+ Version `0.5.0` exits each container when its room closes and uses external scheduling for the next opening.
23
25
  See the [migration guide](docs/migration.md) for API changes, verification and known limitations.
24
26
  Internal readiness does not establish public network reachability.
25
27
 
26
- Install the Python SDK with `pip install dst-server==0.4.0` in a CPython 3.14 environment.
27
- The [GitHub release](https://github.com/LetsStarveTogether/dst-server/releases/tag/v0.4.0) also includes a standalone Linux x86_64 CLI.
28
+ Install the Python SDK with `pip install dst-server==0.5.0` in a CPython 3.14 environment.
29
+ The [GitHub release](https://github.com/LetsStarveTogether/dst-server/releases/tag/v0.5.0) also includes a standalone Linux x86_64 CLI.
28
30
 
29
31
  ## Build and Create a Room
30
32
 
@@ -142,9 +144,14 @@ dst-server call get_player '{"userid":"KU_example"}' --socket /srv/dst/299/.dst-
142
144
  dst-server subscribe lifecycle --socket /srv/dst/299/.dst-agent.sock
143
145
  ```
144
146
 
145
- `call stop` stops games while leaving the Agent available; the opening schedule can start them again.
147
+ `call stop` gracefully closes every shard, then exits the Agent and container with code `0`.
146
148
  `host stop --room 299` stops the container service, including its Agent.
147
- Use the latter before offline configuration changes:
149
+ Either stop permits the independent external scheduler to start the service at its next trigger.
150
+ `call restart` confirms the stop and requests container replacement; its reply does not confirm the next startup.
151
+ Use `host start` or `host restart` to wait for all shards to become ready.
152
+ Outside opening hours, startup exits successfully with the room closed.
153
+ Recovery that remains exhausted is reported as an error.
154
+ Stop the service before offline configuration changes:
148
155
 
149
156
  ```sh
150
157
  dst-server host stop --room 299
@@ -152,8 +159,7 @@ dst-server host edit --room 299 --set '/cluster/settings/max_players=9'
152
159
  dst-server host start --room 299
153
160
  ```
154
161
 
155
- A closed game can still have a live Agent holding the room lock.
156
- Use Agent operations for maintenance while it is running.
162
+ After container exit, `host status` reads the saved policy, current schedule, maintenance and recovery state.
157
163
  Changing world-generation settings preserves existing saves; `regenerate` creates new worlds.
158
164
 
159
165
  ## Rust and Python SDKs
@@ -199,8 +205,10 @@ Entity references contain world session and runtime generation; old references b
199
205
  Each room permits one mutation at a time and returns `busy` for a conflicting operation.
200
206
  Accepted mutations belong to the Agent.
201
207
  Cancellation, disconnection and caller timeouts stop waiting without undoing the operation.
202
- Check `status` after an unknown result before deciding whether to retry.
208
+ Check `status`, or `host status` after container exit, before deciding whether to retry an unknown result.
203
209
  Save success requires native completion on every shard.
210
+ Graceful shutdown sends one native `c_shutdown()` to each shard and lets the game perform its final save.
211
+ The game may save more than once within its native shutdown path.
204
212
  Normal shutdown requires exit code zero, process reaping and output drainage, with no force or protocol fault.
205
213
  Failed shutdown retains each shard's exit status and confirmed saved snapshot.
206
214
  Signal termination uses the negative signal number.
@@ -293,16 +301,25 @@ dst-server call set_policy - --socket /srv/dst/299/.dst-agent.sock <<'JSON'
293
301
  JSON
294
302
  ```
295
303
 
296
- The Agent checks schedules every 30 seconds, including windows across midnight.
297
- At closing time it stops all games and stays available for the next opening.
298
- Pending Mod maintenance runs before reopening.
304
+ The Agent checks opening hours at startup and every 30 seconds while running, including windows across midnight.
305
+ At closing time it stops all games and exits the container with code `0`.
306
+ Startup outside opening hours also exits with code `0` before starting games.
307
+ Configure an independent host scheduler to activate the service at each opening; see the [systemd timer example](docs/migration.md#external-opening-timer).
308
+ Update that scheduler separately when changing policy times or timezone.
309
+ Stopping a room leaves the external scheduler active; manage the scheduler separately when its next trigger should be suppressed.
310
+ Pending Mod maintenance runs in the next container's startup before opening games.
311
+ `call update_mods` queues maintenance and returns before the next container performs it.
312
+ With `restart: false`, that container closes after the update.
313
+ Explicit Mod maintenance may run outside opening hours, but games still follow the schedule.
299
314
  The default maintenance countdown is 60 seconds with announcements every 30 seconds.
300
315
  Failed downloads or validation receive two additional attempts, five minutes apart, then leave games closed.
301
316
  An explicit maintenance request or a later opening can retry.
302
317
 
303
318
  A required shard crash or sustained control failure stops the whole room.
304
- Abnormal process exits, forced termination and IPC faults require container replacement.
305
- Recovery state persists across that replacement.
319
+ Abnormal process exits, forced termination and IPC faults persist recovery state and exit with code `75` for container replacement.
320
+ Intentional restart and Mod maintenance use code `76`.
321
+ The generated Quadlet treats it as successful and forces a restart through the same startup path.
322
+ Update existing Quadlets with the [required restart directives](docs/migration.md#container-exit-contract) before using this lifecycle.
306
323
  Retryable failures allow two restarts of the current save, 30 seconds apart.
307
324
  Only confirmed save-loading failure can then try one previous complete room snapshot.
308
325
  The loss must be proven to be at most one game day per world.
@@ -350,7 +367,7 @@ Compression uses 7z with Zstd level 3 by default and one concurrent compressor.
350
367
  Uploads use the native object-store implementation and explicitly abort incomplete multipart uploads on failure or cancellation.
351
368
  Cleanup failures remain visible in the result and logs.
352
369
  Python exposes `dst_server.archive.export_cluster` and `ClusterArchive.save/upload`.
353
- Export requires stopped games and uses the live Agent or an exclusive offline lock.
370
+ Export requires stopped games and an exclusive room lock.
354
371
  For an offline local export:
355
372
 
356
373
  ```sh
@@ -6,16 +6,18 @@
6
6
  English | [简体中文](README.zh-Hans.md)
7
7
 
8
8
  A Rust SDK, Agent and CLI for Don't Starve Together, with Python bindings.
9
- Each room runs in one container: one Agent supervises every configured shard and remains available while the games are closed.
9
+ Each room runs in one container: one Agent supervises every configured shard and exits with the games when the room closes.
10
+ An external scheduler starts the container at each opening.
10
11
  Published binaries and Python wheels support Linux x86_64 and CPython 3.14.
11
12
  The control socket is for trusted callers on the same host.
12
13
 
13
- Version `0.4.0` replaces the earlier Python implementation.
14
+ Version `0.4.0` replaced the earlier Python implementation.
15
+ Version `0.5.0` exits each container when its room closes and uses external scheduling for the next opening.
14
16
  See the [migration guide](docs/migration.md) for API changes, verification and known limitations.
15
17
  Internal readiness does not establish public network reachability.
16
18
 
17
- Install the Python SDK with `pip install dst-server==0.4.0` in a CPython 3.14 environment.
18
- The [GitHub release](https://github.com/LetsStarveTogether/dst-server/releases/tag/v0.4.0) also includes a standalone Linux x86_64 CLI.
19
+ Install the Python SDK with `pip install dst-server==0.5.0` in a CPython 3.14 environment.
20
+ The [GitHub release](https://github.com/LetsStarveTogether/dst-server/releases/tag/v0.5.0) also includes a standalone Linux x86_64 CLI.
19
21
 
20
22
  ## Build and Create a Room
21
23
 
@@ -133,9 +135,14 @@ dst-server call get_player '{"userid":"KU_example"}' --socket /srv/dst/299/.dst-
133
135
  dst-server subscribe lifecycle --socket /srv/dst/299/.dst-agent.sock
134
136
  ```
135
137
 
136
- `call stop` stops games while leaving the Agent available; the opening schedule can start them again.
138
+ `call stop` gracefully closes every shard, then exits the Agent and container with code `0`.
137
139
  `host stop --room 299` stops the container service, including its Agent.
138
- Use the latter before offline configuration changes:
140
+ Either stop permits the independent external scheduler to start the service at its next trigger.
141
+ `call restart` confirms the stop and requests container replacement; its reply does not confirm the next startup.
142
+ Use `host start` or `host restart` to wait for all shards to become ready.
143
+ Outside opening hours, startup exits successfully with the room closed.
144
+ Recovery that remains exhausted is reported as an error.
145
+ Stop the service before offline configuration changes:
139
146
 
140
147
  ```sh
141
148
  dst-server host stop --room 299
@@ -143,8 +150,7 @@ dst-server host edit --room 299 --set '/cluster/settings/max_players=9'
143
150
  dst-server host start --room 299
144
151
  ```
145
152
 
146
- A closed game can still have a live Agent holding the room lock.
147
- Use Agent operations for maintenance while it is running.
153
+ After container exit, `host status` reads the saved policy, current schedule, maintenance and recovery state.
148
154
  Changing world-generation settings preserves existing saves; `regenerate` creates new worlds.
149
155
 
150
156
  ## Rust and Python SDKs
@@ -190,8 +196,10 @@ Entity references contain world session and runtime generation; old references b
190
196
  Each room permits one mutation at a time and returns `busy` for a conflicting operation.
191
197
  Accepted mutations belong to the Agent.
192
198
  Cancellation, disconnection and caller timeouts stop waiting without undoing the operation.
193
- Check `status` after an unknown result before deciding whether to retry.
199
+ Check `status`, or `host status` after container exit, before deciding whether to retry an unknown result.
194
200
  Save success requires native completion on every shard.
201
+ Graceful shutdown sends one native `c_shutdown()` to each shard and lets the game perform its final save.
202
+ The game may save more than once within its native shutdown path.
195
203
  Normal shutdown requires exit code zero, process reaping and output drainage, with no force or protocol fault.
196
204
  Failed shutdown retains each shard's exit status and confirmed saved snapshot.
197
205
  Signal termination uses the negative signal number.
@@ -284,16 +292,25 @@ dst-server call set_policy - --socket /srv/dst/299/.dst-agent.sock <<'JSON'
284
292
  JSON
285
293
  ```
286
294
 
287
- The Agent checks schedules every 30 seconds, including windows across midnight.
288
- At closing time it stops all games and stays available for the next opening.
289
- Pending Mod maintenance runs before reopening.
295
+ The Agent checks opening hours at startup and every 30 seconds while running, including windows across midnight.
296
+ At closing time it stops all games and exits the container with code `0`.
297
+ Startup outside opening hours also exits with code `0` before starting games.
298
+ Configure an independent host scheduler to activate the service at each opening; see the [systemd timer example](docs/migration.md#external-opening-timer).
299
+ Update that scheduler separately when changing policy times or timezone.
300
+ Stopping a room leaves the external scheduler active; manage the scheduler separately when its next trigger should be suppressed.
301
+ Pending Mod maintenance runs in the next container's startup before opening games.
302
+ `call update_mods` queues maintenance and returns before the next container performs it.
303
+ With `restart: false`, that container closes after the update.
304
+ Explicit Mod maintenance may run outside opening hours, but games still follow the schedule.
290
305
  The default maintenance countdown is 60 seconds with announcements every 30 seconds.
291
306
  Failed downloads or validation receive two additional attempts, five minutes apart, then leave games closed.
292
307
  An explicit maintenance request or a later opening can retry.
293
308
 
294
309
  A required shard crash or sustained control failure stops the whole room.
295
- Abnormal process exits, forced termination and IPC faults require container replacement.
296
- Recovery state persists across that replacement.
310
+ Abnormal process exits, forced termination and IPC faults persist recovery state and exit with code `75` for container replacement.
311
+ Intentional restart and Mod maintenance use code `76`.
312
+ The generated Quadlet treats it as successful and forces a restart through the same startup path.
313
+ Update existing Quadlets with the [required restart directives](docs/migration.md#container-exit-contract) before using this lifecycle.
297
314
  Retryable failures allow two restarts of the current save, 30 seconds apart.
298
315
  Only confirmed save-loading failure can then try one previous complete room snapshot.
299
316
  The loss must be proven to be at most one game day per world.
@@ -341,7 +358,7 @@ Compression uses 7z with Zstd level 3 by default and one concurrent compressor.
341
358
  Uploads use the native object-store implementation and explicitly abort incomplete multipart uploads on failure or cancellation.
342
359
  Cleanup failures remain visible in the result and logs.
343
360
  Python exposes `dst_server.archive.export_cluster` and `ClusterArchive.save/upload`.
344
- Export requires stopped games and uses the live Agent or an exclusive offline lock.
361
+ Export requires stopped games and an exclusive room lock.
345
362
  For an offline local export:
346
363
 
347
364
  ```sh