@awebai/oats 0.69.14 → 0.69.15

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 (49) hide show
  1. package/bin/oats.mjs +79 -18
  2. package/docs/capabilities.md +54 -12
  3. package/docs/container.md +57 -12
  4. package/docs/desktop-cli-api.md +215 -19
  5. package/docs/execution-targets.md +15 -3
  6. package/docs/first-team.md +4 -3
  7. package/docs/implementation.md +18 -8
  8. package/docs/release-notes/v0.69.15.md +444 -0
  9. package/docs/schedules.md +133 -2
  10. package/docs/servers.md +60 -2
  11. package/docs/souls-and-instances.md +87 -7
  12. package/docs/upgrading.md +17 -5
  13. package/lib/claim.mjs +2 -3
  14. package/lib/command-flags.mjs +4 -2
  15. package/lib/core.mjs +215 -72
  16. package/lib/dir-lock.mjs +17 -0
  17. package/lib/errors.mjs +2 -1
  18. package/lib/host-run.mjs +218 -0
  19. package/lib/host-stop-child.mjs +21 -0
  20. package/lib/instance-git.mjs +32 -6
  21. package/lib/instance-lifecycle.mjs +4 -3
  22. package/lib/instance-listing.mjs +35 -6
  23. package/lib/kernel-features.mjs +4 -1
  24. package/lib/read-call.mjs +1 -1
  25. package/lib/remote.mjs +17 -14
  26. package/lib/schedule.mjs +237 -20
  27. package/lib/servers.mjs +83 -5
  28. package/lib/session-end.mjs +28 -8
  29. package/lib/session-resume.mjs +10 -18
  30. package/lib/session-seen.mjs +4 -64
  31. package/lib/status-words.mjs +11 -4
  32. package/lib/system-tools.mjs +1 -36
  33. package/lib/worktree-hooks.mjs +6 -175
  34. package/lib/worktree.mjs +19 -10
  35. package/package.json +4 -1
  36. package/packages/record/README.md +56 -21
  37. package/packages/record/docs/capture-service.md +8 -5
  38. package/packages/record/docs/turn-record-sot.md +9 -0
  39. package/packages/record/lib/capture-health.mjs +6 -4
  40. package/packages/record/lib/capture-lock.mjs +31 -27
  41. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  42. package/packages/record/lib/capture-scratch.mjs +2 -1
  43. package/packages/record/lib/derived-state.mjs +4 -2
  44. package/packages/record/lib/index-db.mjs +4 -2
  45. package/packages/record/lib/lock-holder.mjs +21 -0
  46. package/packages/record/lib/private-files.mjs +18 -0
  47. package/packages/record/lib/process-identity.mjs +310 -0
  48. package/packages/record/lib/store.mjs +31 -25
  49. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -0,0 +1,444 @@
1
+ # OATS 0.69.15
2
+
3
+ 0.69.15 gives a host without a timer, a container among them, the kernel's
4
+ periodic work: `oats host run` is one foreground process that resumes
5
+ sessions at start, runs the schedules every minute, and stops the agents in
6
+ order on SIGTERM, so the next start resumes them. A spawn routed through a
7
+ server keeps its task off both machines' command lines. And a spawn, a
8
+ retire or a stop that was killed half-way (a container that stopped, a
9
+ dropped ssh link) now ends in a state the next command finishes, instead of
10
+ a home with no record, a retire hook run twice, or a refused stop.
11
+
12
+ ## Upgrade
13
+
14
+ - **`@awebai/oats` declares the Node it needs: 22.5.0 or later.** Check
15
+ `node --version` on each host before upgrading. On an older Node, `npm
16
+ install -g @awebai/oats` now warns `EBADENGINE` (and refuses where npm's
17
+ `engine-strict` is set): install Node 22, whose current releases are all
18
+ past 22.5, then install OATS. Hosts on Node 22.5 or later change nothing.
19
+
20
+ - **Either order of the Desktop and the CLI works.**
21
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
22
+ installed the CLI first is fine too: the 0.69.15 Desktop accepts OATS CLIs
23
+ `>=0.26.0 <0.70.0`, as the 0.69.14 Desktop does.
24
+ - **Package pins** are 0.69.14's: oats.framework 1.23.0, oats.okf 5.8.0 and
25
+ oats.aweb 1.37.0.
26
+
27
+ - **Upgrade hosts to keep tasks off their command line.** A spawn routed
28
+ with `--server` keeps its task off every command line only on a host that
29
+ runs this release. An older host still gets the task as an argument, and
30
+ the spawn's answer warns that it was readable in both machines' process
31
+ lists.
32
+
33
+ - **Tighten a record root that an earlier version wrote.** The turn-record
34
+ store now creates its files and directories for their owner alone (see
35
+ Fixed below), and it never changes the permissions of what already exists:
36
+ journals, objects and index databases written before this release keep the
37
+ mode they were created with, `0644` and `0755` under the usual umask. On a
38
+ host with more than one user, run once, for each record root (the `--root`
39
+ given to capture, else `$TURN_RECORD_ROOT`, else `~/.turn-record`):
40
+
41
+ ```sh
42
+ chmod -R go-rwx ~/.turn-record
43
+ ```
44
+
45
+ A process that reads a record root as another user, or through a group,
46
+ can no longer read what the store creates from this release on; run it as
47
+ the root's owner.
48
+
49
+ - **A capture lock or a stream lock written by an earlier version is still
50
+ judged as that version judges it.** Its record names neither a boot nor a
51
+ process start: the capture lock (`<record root>/.capture.lock`) is
52
+ reclaimed only when it names this host and its pid is gone, and a stream
53
+ lock (`streams/<id>/.lock`) by its pid on this host, or by its age when it
54
+ names another. One left on a volume by a container that ran an earlier
55
+ version can therefore still stop capture for that root after the upgrade:
56
+ the pass names the lock and the command that removes it. Locks this
57
+ version writes do not need that.
58
+
59
+ - **A record root is written from one machine at a time.** A record root
60
+ must not be shared by two machines. A lock taken on
61
+ another machine was taken in another boot, so it is reclaimed at once
62
+ though its holder may be running there. Earlier versions never reclaimed
63
+ another host's capture lock, and reclaimed another host's stream lock only
64
+ after 30 s. A record root that two machines write at once (a home on NFS)
65
+ is no longer serialized between them
66
+ ([turn record: Durability and concurrency](../../packages/record/README.md#durability-and-concurrency)).
67
+
68
+ - **After upgrading, release any schedule slot left without its record.**
69
+ An earlier OATS killed while it took a job's slot could leave the
70
+ directory `<deployment>/.agents/schedules/locks/<id>/` with no
71
+ `owner.json` in it. This OATS never writes into it or removes it for
72
+ you: `oats doctor` lists it as a `schedule-slot-unreadable` problem, the
73
+ tick reports that job invalid, and the slot counts against
74
+ `maxConcurrent`. Check `oats schedule show <id>`; once its last run is
75
+ not running, run `oats schedule reconcile <id> --clear` to release it
76
+ ([Schedules](../schedules.md#files)).
77
+
78
+ ## Added
79
+
80
+ - **`oats host run`: the kernel's periodic work in one foreground process,
81
+ for a host without a timer** (oats-project/oats#1789). Every `oats` command is
82
+ short-lived, and the resume sweep and the schedule tick were started by a
83
+ client or by a host timer. A container has neither, so nothing there
84
+ resumes sessions after a restart, runs schedules, or stops the agents in
85
+ order when the container stops. The command is what an operator, or the
86
+ entrypoint of an image, runs for that; the agent image in
87
+ `container/agent/` does not run it yet
88
+ ([container.md](../container.md#the-kernels-periodic-work)).
89
+ - `oats host run [--stop-grace <seconds>] [--plan] [--json]` runs the
90
+ resume sweep once, then `oats schedule tick --host` at second 0 of every
91
+ minute for the registered scopes, and lists the instances each minute so
92
+ that the next start's sweep knows what ran. A minute whose tick still
93
+ runs is skipped, and a missed minute is never replayed. With no scope
94
+ registered it ticks nothing and says so.
95
+ - On SIGTERM or SIGINT it stops ticking, waits for a tick that runs, then
96
+ stops every running instance side by side: SIGTERM to the harness, a
97
+ wait of `--stop-grace` seconds (default 20), never escalated. It exits
98
+ 0. The next start's sweep resumes those instances.
99
+ - It refuses to start, before any effect, inside an instance session
100
+ (`E_USAGE`), while the host timer is active (`E_HOST_RUN_TIMER_ACTIVE`),
101
+ and while another `oats host run` holds this machine's lock
102
+ (`E_HOST_RUN_BUSY`). Unit files that are installed and not active are a
103
+ warning. The lock names its boot, so a lock left by a killed container
104
+ is taken over by the next run.
105
+ - `--plan` says what a run would refuse, the scopes it would tick and what
106
+ its sweep would do, and changes nothing.
107
+ - New contracts
108
+ ([desktop-cli-api.md](../desktop-cli-api.md#the-host-run-oats-host-run)):
109
+ the command and its flags; its answer, `{schemaVersion, plan, signal,
110
+ warnings, sweep, ticks, stopped}`, and its plan, `{schemaVersion, plan,
111
+ refusals, warnings, scopes, sweep}`; `E_HOST_RUN_BUSY` with
112
+ `details.lock` and `details.found`; `E_HOST_RUN_TIMER_ACTIVE` with
113
+ `details.unit`; `E_HOST_RUN_FAILED` for any other failure of the run.
114
+ - **`oats schedule host install --register-only`** records the deployment in
115
+ the host schedule registry, with any caps given, and installs no timer
116
+ (oats-project/oats#1789). It asks neither launchd nor systemd for
117
+ anything, so it works in a container, where plain `host install` fails
118
+ after registering. It does not go with `--print`. With `--server` it is
119
+ sent only to a host that advertises the new feature
120
+ `schedule-host-register-only` (and `schedule`); any other is refused here
121
+ with `E_REMOTE_INCOMPATIBLE` before anything is sent, since a host that
122
+ does not know the option ignores it and installs a timer. New contracts:
123
+ the flag; its answer, which is `host install`'s; and the feature
124
+ `schedule-host-register-only` in the probe
125
+ ([schedules.md](../schedules.md#without-a-host-timer)).
126
+ - **A session that OATS stopped with the host is resumed**
127
+ (oats-project/oats#1789). A stop by `oats host run` writes the home's stop
128
+ record with `"resume": true` and `"reason": "host-stop"`, before the
129
+ harness is signalled. Such a home reads `sessionEnd: "lost"`, whatever
130
+ status its harness ended with; `sessionEnd` has no new value, and every
131
+ other stop still reads `stopped`. `oats status` says `lost (stopped with
132
+ the host)` under a local row. A new contract: `resume` and `reason` in
133
+ `.oats-stop.json`
134
+ ([execution-targets.md](../execution-targets.md#how-a-sessions-end-is-read)).
135
+
136
+ - **`oats spawn <soul> --task-file -` reads the task from standard input**
137
+ (feature `spawn-task-stdin`). A terminal on standard input is refused
138
+ (`E_BAD_ARGS`).
139
+
140
+ - **`oats doctor` lists a schedule slot whose record cannot be read** as a
141
+ `schedule-slot-unreadable` problem, `{code, severity, scope, id, message,
142
+ remedy}`, naming the deployment, the job and the remedy
143
+ ([Schedules](../schedules.md#what-a-run-reports)).
144
+ - **`oats doctor` lists a schedule slot whose schedule is gone** as a
145
+ `schedule-slot-orphaned` problem of the same shape, naming the run and the
146
+ instance its record names, and, for a workspace schedule, the time of the
147
+ saved snapshot that says it is gone. A workspace schedule absent from the
148
+ snapshot that cannot be shown gone is listed with the step that applies.
149
+
150
+ ## Changed
151
+
152
+ - **A spawn through a server is bound to the server's preview and a key.**
153
+ `oats spawn <soul> --server <id>` asks the server for its preview, then
154
+ spawns with that decision and a key made for the request
155
+ (`--expect-decision`, `--idempotency-key`): one more call to the server
156
+ per spawn. Its `--json` answer is the server's keyed answer, with
157
+ `decision`, `replayed` and `wake` beside the fields it had. A name another
158
+ spawn takes between the two calls is `E_DECISION_STALE` and nothing is
159
+ created: run the spawn again. `--suggest-name` is given to the preview,
160
+ and the spawn carries the name it chose. A spawn that brings
161
+ `--expect-decision` or `--idempotency-key` travels as given
162
+ ([Run there](../servers.md#run-there)).
163
+ - **A server that does not advertise `spawn-preview-2`, `spawn-apply-2` and
164
+ `spawn-idempotency-2` gets the spawn in one call, as given,** and the
165
+ answer carries a warning that a dropped link cannot be retried safely
166
+ there.
167
+
168
+ - **The kernel's package declares `engines.node: >=22.5.0`.** It declared no
169
+ floor, while CI runs Node 22 and the turn record the kernel ships reads its
170
+ index through `node:sqlite`, which Node has from 22.5. The floor is the one
171
+ `@awebai/turn-record` already declared. `npm run validate` holds the root
172
+ package to a declared floor, the lock to the same one, and every package
173
+ under `packages/` to no lower one.
174
+ [First team](../first-team.md#0-prerequisites) states the floor.
175
+
176
+ - **An owner whose liveness can't be judged is never reclaimed.** The
177
+ remote cache write lock (`<cache>/.locks/<repo>.lock`) and the turn
178
+ record's capture and stream locks read a lock's owner through one
179
+ function, which answers "unknown" for a pid whose existence cannot be
180
+ checked (`kill` answers neither `ESRCH` nor `EPERM`) and for a record
181
+ whose pid is no process ID (zero, a negative number, one above the
182
+ range). The cache write lock reclaimed a lock without a boot or a start
183
+ on such a failed check, and one of another boot whatever its pid; it
184
+ waits for both and refuses with `E_REMOTE_UNREADABLE` (`reason:
185
+ "cache"`), as for a live holder. For a pid that is no process ID the
186
+ refusal says that the lock names none and is safe to remove once no oats
187
+ process is running, and its details carry no `holderPid`
188
+ ([Implementation](../implementation.md)).
189
+
190
+ - **A home whose record does not say which retire hooks to run is refused by
191
+ `oats retire`, where it was removed with a warning.** A record that names
192
+ no repository and does not show that no capability has a retire hook (the
193
+ stub a spawn leaves when it is killed before its record) is refused with
194
+ `E_UNIDENTIFIED_INSTANCE_HOME` before anything is stopped, run or removed,
195
+ unless a usable cleanup marker is beside it. Clean up by hand what the
196
+ home's capabilities registered, then `oats retire <instance> --force`
197
+ removes it, running no hook
198
+ ([capabilities.md](../capabilities.md#manifest)).
199
+ - **`spawnInProgress: true` on a status row, and `E_LIFECYCLE_BUSY` from a
200
+ retire, also cover a spawn that is running its spawn hooks**, when a
201
+ capability with a spawn hook has a retire hook. Before, only a spawn
202
+ running its `worktree` hooks read that way.
203
+
204
+ - **A retire's lifecycle claim records the retire hooks that ended.** The
205
+ claim file of a home (`<instances>/.oats-retirement/claims/<name>.lock`)
206
+ gains two fields while a retire holds it: `retireHooks`, a list of
207
+ `{capability, meta?}` for each retire hook that ended, with the `meta` it
208
+ answered, and `retireHooksFor`, the `createdAt` of the home they ran for.
209
+ This is an addition to the claim's format. An earlier OATS that takes
210
+ such a claim over ignores the fields and runs every retire hook, as it
211
+ always did. This OATS, taking over a claim without them, runs every
212
+ retire hook too. Nothing is written into the home
213
+ ([One retire at a time](../desktop-cli-api.md#retire-hooks-in-claim)).
214
+
215
+ - The [team agent image](../container.md) pins OATS 0.69.14, adding file-backed launch environment and the operator's harness token route; amd64 and live-lab acceptance remain separate evidence.
216
+
217
+ ## Fixed
218
+
219
+ - **A schedule's job slot is never left without its record.** The slot was
220
+ made as an empty directory and its record written into it after, and
221
+ released by removing the record before the directory, so a tick killed
222
+ between the two steps left a slot without its record. The record is now
223
+ written first, in a directory beside the slots, and that directory is
224
+ renamed to the slot; a release renames the slot out before removing it
225
+ ([Schedules](../schedules.md#files)).
226
+ - **A slot whose record cannot be read stops only its job.** Such a slot
227
+ (an earlier OATS's, a hand edit, a disk fault) made every tick of its
228
+ deployment fail with `job lock custody is unreadable`, so none of the
229
+ deployment's jobs ran, and `oats schedule reconcile` answered `nothing to
230
+ reconcile`. The tick now reports only that job `invalid` and runs the
231
+ others; `oats schedule reconcile <id>` answers the remedy, and
232
+ `reconcile <id> --clear` releases the slot once you have checked
233
+ ([Schedules](../schedules.md#files)).
234
+ - **A slot left by a schedule that is gone can be released.** A local
235
+ schedule removed by hand, or a workspace schedule removed upstream, could
236
+ leave its slot, which every tick counted against `maxConcurrent` and no
237
+ command could release: `oats schedule reconcile` and `remove --force`
238
+ answered `E_SCHEDULE_UNKNOWN`. The slot still counts until it is released,
239
+ since its run may still be going; `oats schedule reconcile <id>` now
240
+ answers what it found, and `reconcile <id> --clear` releases it once you
241
+ have checked, with the job's retained attempt and state; a gone
242
+ schedule's retained state with no slot is cleared the same way. A workspace
243
+ schedule is gone only when the saved snapshot shows it: run `oats
244
+ automations refresh` first if the snapshot is stale. One that is disabled,
245
+ untrusted or placed elsewhere is refused as before, and `oats doctor`
246
+ names the step that acts for its unreadable slot: remove it by hand once
247
+ `oats status` shows no run of it here, never a `reconcile --clear` that
248
+ refuses it ([Schedules](../schedules.md#files)).
249
+
250
+ - **A spawn whose link dropped while the server spawned can be run again
251
+ onto the one instance.** The failure is `E_SSH`, its message ends with the fix, and
252
+ `--json` carries `error.details: {decision, idempotencyKey, fix}`. The same
253
+ spawn with `--expect-decision <decision.revision> --idempotency-key
254
+ <idempotencyKey>` answers the instance the first attempt created
255
+ (`replayed: true`) and saves its route
256
+ ([ssh failures](../desktop-cli-api.md#ssh-failures-e_ssh)).
257
+ - **A replayed keyed spawn answers `attach`,** as the first apply did.
258
+
259
+ - **The turn-record store creates transcripts private to their owner.** The
260
+ store created journals, objects, quarantined copies and its index
261
+ databases with the process's default permissions, so on a shared host
262
+ other users could read agents' conversations. It now creates files with
263
+ mode `0600` and directories with mode `0700`:
264
+ [Store layout](../../packages/record/docs/turn-record-sot.md#store-layout)
265
+ has the rule.
266
+
267
+ - **A capture lock or a stream lock whose holder is gone no longer stops
268
+ capture when the container is created again.** Both locks of the turn
269
+ record named their holder by pid and hostname. On a volume that outlives
270
+ its container, a lock left by a stopped container named a hostname the
271
+ next container does not have, so the capture lock was never reclaimed and
272
+ every pass skipped, and a pid that the next run had given to another
273
+ process, so the lock read as held. Both records also name the boot the
274
+ lock was taken in and the holder's process start (`bootId`,
275
+ `processStart`), as the kernel's claims do, and are judged by the same
276
+ code: a lock taken in another boot (a container run counts as one), or
277
+ whose pid is gone or runs with another start, is reclaimed at once,
278
+ whatever host it names. The capture lock's registered worker and its
279
+ reclaim guard are judged the same way. A holder that is still running is
280
+ never taken over, and a pass that finds one says that it skipped, naming
281
+ it ([turn record: Durability and concurrency](../../packages/record/README.md#durability-and-concurrency),
282
+ #1812).
283
+ - **The standalone `turn-record` package judges its locks as an OATS
284
+ install does.** The process start token, the boot id and the rule for a
285
+ record of another boot are one dependency-free module of the package,
286
+ `packages/record/lib/process-identity.mjs`, which the kernel imports
287
+ ([Implementation](../implementation.md)).
288
+
289
+ - **A spawn killed inside its spawn hooks no longer leaves a registration
290
+ that nothing can release.** `oats spawn` ran its spawn hooks (a
291
+ capability's may register an identity with an external service and take a
292
+ seat) and wrote the home's record only later. A spawn killed in between
293
+ (SIGKILL, a container stop, a dropped connection) left a home whose record
294
+ named neither a repository nor its capabilities; `oats retire` then ran no
295
+ retire hook, removed the home and the keys in it, and exited 0 with a
296
+ warning.
297
+ - The spawn now writes its in-progress marker
298
+ (`.oats-rollback-incomplete.json`) before its first spawn hook, in every
299
+ work mode, when a capability with a spawn hook has a retire hook: the
300
+ repository, the capabilities with their hooks, the soul, and the record's
301
+ `workspace`, `teams` and `defaultTeam`. It writes it again with the spawn
302
+ hooks' receipt once they have answered, and removes it when the final
303
+ record is written.
304
+ - `oats retire` of the home such a spawn leaves runs the retire hooks,
305
+ with the environment a retire of a whole home gives them, and then
306
+ removes the home. A retire hook that runs after a spawn hook that never
307
+ answered gets an empty `OATS_META`.
308
+
309
+ - **A self-retire whose completion was killed says what to run, and a
310
+ reboot no longer hides that it was killed.** `oats retire <instance>
311
+ --self` schedules the retire in a detached completion and leaves a pending
312
+ marker beside the home. When that completion was killed before it
313
+ finished (a `SIGKILL`, a container that stopped), `oats session start`
314
+ answered `<instance> is being retired`, which was not true and named no
315
+ way out. It now answers `E_INSTANCE_RETIRING` with `<instance> is owed a
316
+ retire (its retire was interrupted): finish it with` and the `oats retire`
317
+ command, which takes the retire over and completes it. The marker also
318
+ records the boot its completion runs in (`completionBoot`): after a
319
+ reboot or a container restart, a marker whose pid and start had both come
320
+ again read as a retire still running, and `oats retire` was refused
321
+ `E_LIFECYCLE_BUSY` for a completion that no longer existed. Such a marker
322
+ now names a completion that is gone. A marker written by an earlier OATS
323
+ names no boot and is judged by its process alone, as before
324
+ ([a completion that was killed](../souls-and-instances.md#self-retire-interrupted)).
325
+
326
+ - **A spawn whose caller went away no longer ends as a failure, or with a
327
+ home that has no record.** When the reader of `oats spawn` closed stdout
328
+ or stderr while it ran (an ssh session that ended), the spawn completed
329
+ and then ended with an unhandled `EPIPE` and exit status 1, as if it had
330
+ failed. It now ends with the spawn's own status, `0`, as `oats worktree
331
+ add` does; the answer nobody read is the home's record, and a spawn
332
+ repeated with the same `--expect-decision` and `--idempotency-key`
333
+ answers it again. A SIGINT, SIGTERM or SIGHUP that arrived while the
334
+ capabilities were copied into the new home ended the process there and
335
+ left a home with no `instance.json`, which only `oats retire --force`
336
+ removed. The signal is now held until the copy ends: the home is removed
337
+ and the spawn answers `E_INTERRUPTED` (`details: {signal, hooks: []}`),
338
+ exit 128 + the signal number, as it does while its `worktree` hooks run
339
+ ([a caller that goes away](../desktop-cli-api.md#spawn-caller-gone)).
340
+
341
+ - **A stop is not refused by a self-retire whose completion is gone.** A
342
+ scheduled self-retire whose detached completion was killed, or that
343
+ failed after its hooks started, leaves its pending marker, and every stop
344
+ of that home answered `E_INSTANCE_RETIRING`: `oats instance stop
345
+ --apply`, a retire's stop of a recorded child, and the stop `oats host
346
+ run` makes of every running home on SIGTERM, which reported a failed stop
347
+ on each container stop. The marker now holds the home against a stop only
348
+ while the completion it names is not gone. Once it has ended, runs with
349
+ another start, or belongs to another boot, the stop plan shows `retiring:
350
+ false` for that target and the session is stopped; the marker stays, and
351
+ the home is still owed its retire (`oats retire <instance>`). A
352
+ completion that lives, and a marker that names none, refuse a stop as
353
+ before
354
+ ([a completion that was killed](../souls-and-instances.md#self-retire-interrupted)).
355
+
356
+ - **A retire, a session start, a session restart and a stop apply whose
357
+ caller went away no longer end as failures.** When the reader of `oats
358
+ retire`, `oats session start`, `oats session restart` or `oats instance
359
+ stop --apply` closed stdout or stderr before the answer was written (an
360
+ ssh session that ended, a Desktop that quit), the act completed under
361
+ the home's lifecycle claim and the process could then end with an
362
+ unhandled `EPIPE` and exit status 1: a retire did, and so did a start
363
+ that started the OATS tmux server, which writes a line on stderr while it
364
+ acts. They now end with the act's own status, as `oats spawn` and `oats
365
+ worktree add` do, and what could not be printed is dropped
366
+ ([a caller that goes away](../desktop-cli-api.md#spawn-caller-gone)).
367
+
368
+ - **A retire that takes over from a killed one no longer runs again the
369
+ retire hooks that one had finished.** A retire, or the detached
370
+ completion of a self-retire, that was killed after some of its retire
371
+ hooks had returned (a `SIGKILL`, a container that stopped) left nothing
372
+ that said so, and the next `oats retire` of the home ran every hook a
373
+ second time. The next retire now reads
374
+ the finished hooks from the claim the killed one left, skips them, and
375
+ judges the cleanup and writes its `retired` row with what they answered.
376
+ A hook that had not ended when the retire was killed is run again. The
377
+ retry of a quarantined home, and the retries a self-retire's completion
378
+ makes of a cleanup its hooks left incomplete, run every hook again, as
379
+ before
380
+ ([One retire at a time](../desktop-cli-api.md#retire-hooks-in-claim)).
381
+
382
+ - **A checkout OATS makes runs no filter driver the repository's
383
+ configuration defines.** The `git worktree add` of a spawn into a worktree,
384
+ and the `git worktree add` and `git switch` of `oats worktree add`, ran the
385
+ `filter.<name>.smudge` or `.process` command the clone's configuration
386
+ names for a file carrying the `filter` attribute, as whoever spawned. Each
387
+ is preceded by one read of that configuration, and every driver it defines
388
+ is overridden to no command, as for a retire's status: such a file is
389
+ written as its committed bytes
390
+ ([a checkout runs no filter driver](../souls-and-instances.md#checkout-filter-drivers)).
391
+ - A driver the operator's global or system configuration defines runs as
392
+ before: Git LFS set up with `git lfs install` checks its files out. With
393
+ `git lfs install --local` alone, a tree OATS checks out holds the
394
+ pointer files: run `git lfs install`, or `git lfs pull` in the tree.
395
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
396
+ or is not UTF-8) refuses the checkout. The spawn's refusal is
397
+ `E_WORK_INSPECTION_FAILED`, as before, raised before
398
+ `git worktree add` and no longer at the baseline's status, with the
399
+ message `could not make the instance worktree: git worktree add was not
400
+ run in <clone>: …`; `oats worktree add` answers `E_GIT_FAILED`.
401
+ - **No Git command OATS runs on a work tree's files or index runs the file
402
+ monitor the repository's configuration names.** The same three commands,
403
+ the fetch of `oats worktree add`, the reads of `oats worktree remove` (its
404
+ status, the clean check inside `git worktree remove`, the comparison of an
405
+ unregistered tree's surviving files) and the check `oats package
406
+ add|remove` makes that `oats-workspace.yaml` is tracked ran the
407
+ `core.fsmonitor` command of the repository's configuration when they read
408
+ the index of the tree. They run with `core.fsmonitor=false`, as a retire
409
+ and `oats instance git` do
410
+ ([no file monitor](../souls-and-instances.md#no-file-monitor)). The clone's Git
411
+ hooks (`post-checkout` among them) still run at these checkouts.
412
+ - **A driver of the operator's that has no `process` command runs where the
413
+ repository's configuration names the same driver.** This reaches every
414
+ command that takes these overrides: a retire and `oats worktree remove` as
415
+ well as a checkout. Each overrides that driver with the operator's values.
416
+ They also set its `process` to nothing, which made Git skip the operator's
417
+ `clean` and `smudge` commands. `process` is left alone when neither
418
+ configuration defines it. When the repository defines it and the operator
419
+ does not, neither side's command runs.
420
+
421
+ - **A spawn through a server that runs this release keeps the task off every
422
+ command line.**
423
+ `oats spawn <soul> --server <id>` with `--task` or `--task-file` put the
424
+ whole task text in the remote command, so it was in the arguments of the
425
+ local `ssh` process and of the server's `oats` for as long as each ran,
426
+ readable by every user of either machine in the process list. The text
427
+ goes on the ssh session's standard input, to the server's preview and to
428
+ its spawn, and the remote command carries `--task-file -`
429
+ ([a routed spawn's task](../servers.md#a-routed-spawns-task)). A task
430
+ file over Linux's limit for one argument (128 KiB) is sent like any
431
+ other.
432
+ - **A spawn with a task through a server that does not advertise
433
+ `spawn-task-stdin` says where the task was readable.** Such a server gets
434
+ the task as an argument, as before, and the answer's warnings gain one
435
+ line: `remote oats <version> at <host> does not advertise
436
+ spawn-task-stdin, so the task was passed as an argument, visible in this
437
+ machine's process list (the ssh command) and the host's while the spawn
438
+ runs; upgrade the host`.
439
+
440
+ ## Documentation
441
+
442
+ - [capabilities.md](../capabilities.md#manifest) states the rule for retire
443
+ hooks: one must be safe to run when its spawn hook did not finish and when
444
+ it has run before.
package/docs/schedules.md CHANGED
@@ -31,6 +31,10 @@ while the machine slept are skipped, never replayed; there are no retries and
31
31
  no queue. A schedule on a registered server keeps running while your laptop
32
32
  sleeps.
33
33
 
34
+ A host with neither launchd nor a systemd user manager (a container) has no
35
+ timer: there `oats host run`, a foreground process, runs the same tick at
36
+ second 0 of every minute ([Without a host timer](#without-a-host-timer)).
37
+
34
38
  The design is in the
35
39
  [knowledge-operations design record](design/2026-09-26-okf-knowledge-operations.md#23-triggers)
36
40
  (§2.3 and §2.3a).
@@ -41,7 +45,7 @@ The design is in the
41
45
  | --- | --- |
42
46
  | `<deployment>/oats-schedules.json` | This machine's local definitions, `{version: 1, jobs: {<id>: …}}`, local triggers included (`kind: "trigger"`). |
43
47
  | `<deployment>/.agents/automations/snapshot.json` | The workspace definitions discovered from the members. |
44
- | `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one lock directory per running job. |
48
+ | `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one slot directory per running job, `locks/<id>/` with its record `owner.json`. |
45
49
  | `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
46
50
 
47
51
  One host lock, `~/.oats/schedules/host.lock`, serializes ticks, run-now,
@@ -71,6 +75,71 @@ A lock whose holder is gone and whose record cannot be taken over (a record
71
75
  without the identifier a takeover needs) is reported the same way, with the
72
76
  file that must be removed.
73
77
 
78
+ **A job's slot is never there without its record.** The slot a running job
79
+ holds against `maxConcurrent`, `.agents/schedules/locks/<id>/`, is no lock
80
+ between processes: the host lock serializes everything that takes or
81
+ releases it, and it stands for the job's run until that run's instance ends.
82
+ Its record is written in `.agents/schedules/.slot-<id>/`, which is then
83
+ renamed to the slot, and a release renames the slot back there before
84
+ removing it. A command killed while it takes or releases a slot leaves the
85
+ slot with its record or no slot, and at most that directory, which the next
86
+ take or release of the slot removes.
87
+
88
+ **A slot whose record cannot be read stops only its job.** A slot directory
89
+ without its record (which an earlier oats could leave), a record that does
90
+ not parse, or something else at the slot's path says nothing about whether
91
+ the run it stands for still runs. OATS never writes into it or removes it
92
+ for you. The tick reports that job `invalid`, with the error `the slot <path>
93
+ has no readable record; check oats schedule show <id>; once its last run is
94
+ not running, run oats schedule reconcile <id> --clear to release the slot`
95
+ (`E_SCHEDULE_INVALID`), and ticks the deployment's other jobs as usual; the
96
+ slot counts against `maxConcurrent` until it is released. `oats schedule
97
+ run <id>` refuses with the same words. `oats schedule reconcile <id>`
98
+ answers `reconciled: "unknown"` with that sentence as its `remedy` and
99
+ leaves the slot; once you have checked, `reconcile <id> --clear` releases
100
+ it (`reconciled: "cleared"`), and reconciles an attempt beside it as
101
+ `--clear` does any attempt. `oats doctor` lists the slot as a
102
+ `schedule-slot-unreadable` problem ([Unresolved attempts](#what-a-run-reports)).
103
+
104
+ **A slot whose schedule is not defined is held until a person releases it.**
105
+ A schedule that is gone can leave its slot behind, readable or not, and it may
106
+ stand for a run that is still going. A local schedule is gone when it is no
107
+ longer in `oats-schedules.json`. A workspace schedule is gone when the saved
108
+ automation snapshot says so: its member was read at a commit, the snapshot
109
+ has no problem of that member that could hide a schedule (a schedule file
110
+ that could not be read or parsed, which may carry any id, or a member that
111
+ could not be listed), and no schedule has its id. That is decided from the
112
+ snapshot as it was last saved: reconcile and doctor refresh nothing, and
113
+ both name the snapshot's time. A workspace schedule that is disabled,
114
+ untrusted or placed on another host still has its entry there: it is not
115
+ gone, and reconcile refuses it as before (`E_AUTOMATION_NOT_HERE`). Without a
116
+ snapshot nothing is gone.
117
+
118
+ No tick reads the slot of a schedule that is gone, and every tick counts it
119
+ against `maxConcurrent` until it is released. `oats schedule reconcile <id>`
120
+ answers `{schedule: null, reconciled: "unknown", remedy}` with what it found
121
+ (the slot, how the schedule is known to be gone, and the run its record
122
+ names: its due minute and, for a wake, the home of its instance; a spawn's or
123
+ a command's record names no instance) and changes nothing. Once you have
124
+ checked `oats status`, `reconcile <id> --clear` releases the slot, resolves a
125
+ retained launch attempt as cleared (as for a defined job) and removes the
126
+ job's state: `{schedule: null, reconciled: "cleared", cleared: [...]}`, which
127
+ lists `"slot"`, `"attempt"` and `"state"` as each was there. A schedule that is
128
+ gone with retained state and no slot is reconciled the same way: reconcile
129
+ answers that it has retained state (and a launch attempt with no recorded
130
+ result, when there is one) and points to `--clear`, which answers `cleared:
131
+ ["attempt", "state"]`. `oats doctor` lists the slot as a
132
+ `schedule-slot-orphaned` problem, and the `schedule-unresolved` row of a
133
+ retained attempt names the same `reconcile <id> --clear`.
134
+
135
+ A workspace schedule that is absent from the snapshot but cannot be shown gone
136
+ stays refused (`E_SCHEDULE_UNKNOWN`), and doctor lists its slot as
137
+ `schedule-slot-orphaned` with the step that applies: when its member is not
138
+ in the snapshot (removed from the workspace, or not read), check `oats
139
+ status` and remove the slot by hand, at the path doctor names; when its
140
+ member has a schedule file that could not be read, fix that file and run
141
+ `oats automations refresh`.
142
+
74
143
  ## Kinds
75
144
 
76
145
  Every definition carries `id`, `enabled`, `cron`, `tz` and `kind`. `cron` has
@@ -633,6 +702,7 @@ oats schedule host install # register this deployment and install the one
633
702
  oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
634
703
  oats schedule host install --max-concurrent default --triggers-max-concurrent none
635
704
  oats schedule host install --print [--os darwin|linux] # what install would write; changes nothing
705
+ oats schedule host install --register-only # register this deployment and install no timer (oats host run ticks)
636
706
  oats schedule host status | uninstall
637
707
  oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?" # or --wake-file spec.json
638
708
  ```
@@ -686,6 +756,25 @@ five. Correct it with `oats schedule host install --max-concurrent N` (or
686
756
  An absent value still means five. Set caps through the CLI; do not edit the
687
757
  registry by hand.
688
758
 
759
+ ### Without a host timer
760
+
761
+ `oats schedule host install --register-only` records the deployment in the
762
+ host registry, with any caps given, and installs no unit. It asks neither
763
+ launchd nor systemd for anything, so it works where neither exists. It does
764
+ not go with `--print` (`E_BAD_ARGS`). Its answer is install's: `scheduler`
765
+ with `registered: true` and `installed: false`, and no warnings.
766
+
767
+ On such a host `oats host run` is the ticker
768
+ ([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)): each minute it
769
+ runs `oats schedule tick --host` for the scopes the registry lists, and with
770
+ none it ticks nothing and says so. It refuses to start while a host timer is
771
+ active (`E_HOST_RUN_TIMER_ACTIVE`), so a host has one ticker, never two.
772
+ With `--server`, `--register-only` is sent only to a destination that
773
+ advertises `schedule` and `schedule-host-register-only`. Any other is
774
+ refused with `E_REMOTE_INCOMPATIBLE` before anything is sent, because a
775
+ destination that does not know the option ignores it and installs a timer.
776
+ Upgrade OATS on the destination.
777
+
689
778
  ### The host timer's unit
690
779
 
691
780
  The unit is a launchd user agent (`~/Library/LaunchAgents/ai.oats.schedule-tick.plist`,
@@ -842,9 +931,51 @@ schedule whose saved state supports reconciliation, `remedy` names
842
931
  `oats schedule reconcile <id>`, with `--clear` for unproven command/operation
843
932
  effects (check the roster and host by hand first), and `--dir <scope>` for
844
933
  another deployment. Invalid or unsupported saved inputs instead receive a
845
- warning to preserve state and inspect effects with the deployment owner.
934
+ warning to preserve state and inspect effects with the deployment owner. A
935
+ job whose slot has no readable record gets the slot's remedy below.
846
936
  A warning never changes doctor's exit status.
847
937
 
938
+ `oats doctor` also lists each slot whose record cannot be read, in the same
939
+ deployments, as its own problem. The text form is `! schedule-slot-unreadable:
940
+ <message>` with the remedy on the next line; in `--json` it is a `problems[]`
941
+ item:
942
+
943
+ ```text
944
+ { code: "schedule-slot-unreadable", severity: "warning", scope, id, message, remedy }
945
+ ```
946
+
947
+ `message` names the job and the slot's path; `remedy` is `check oats schedule
948
+ show <id>; once its last run is not running, run oats schedule reconcile <id>
949
+ --clear to release the slot`, with `--dir <scope>` on both commands for
950
+ another deployment. A workspace schedule that this host does not run
951
+ (disabled, untrusted, placed on another host, as the saved snapshot and
952
+ `oats-local.yaml` say offline), or that it cannot tell it runs, is refused by
953
+ reconcile here: its message says why, and its remedy is `once oats status
954
+ shows no run of schedule <id> here, remove the slot by hand: rm -r --
955
+ '<path>'`. No doctor row names a `--clear` that reconcile would refuse.
956
+ Doctor reads the slot as the tick does and changes nothing. A readable slot of a defined job, and no slot, are not listed.
957
+
958
+ A slot whose schedule is gone, readable or not, is listed as a
959
+ `schedule-slot-orphaned` problem instead, of the same shape (`! schedule-slot-orphaned:
960
+ <message>`, the remedy on the next line). Its message says how the schedule
961
+ is known gone (`which is not defined`, or `which as of <takenAt> is not in
962
+ the workspace (run oats automations refresh if that is stale)`) and what the
963
+ slot's record names (`has no readable record`, or `holds the run due
964
+ <minute> of the instance at <home>`, or `… of an instance its record does
965
+ not name`). Its remedy is `once oats status shows the instance at <home> is
966
+ not running, run oats schedule reconcile <id> --clear to release the slot`,
967
+ or, when the record names no instance, `once no run of schedule <id> is
968
+ running (oats status lists the instances it started), run oats schedule
969
+ reconcile <id> --clear to release the slot`. The `schedule-unresolved` row of
970
+ a gone workspace schedule's retained attempt names the same remedy. A
971
+ workspace schedule absent from the snapshot that cannot be shown gone is
972
+ listed as `schedule-slot-orphaned` too, with `which is not in the
973
+ workspace's snapshot of <takenAt>`, why, and its step: `check oats status for
974
+ a run of schedule <id>; once none is running, remove the slot by hand: rm -r
975
+ -- '<path>'` for a member not in the snapshot, `fix <file> in member
976
+ <member> and run oats automations refresh; doctor then says whether
977
+ schedule <id> is gone` for a file that could not be read.
978
+
848
979
  Workspace guidance uses only validated local settings and the saved automation
849
980
  snapshot. A known opt-out, missing saved definition, different assigned host or
850
981
  absent trust explains why retained-state reconciliation is currently unavailable.