@awebai/oats 0.69.12 → 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 (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -0,0 +1,83 @@
1
+ # OATS 0.69.14
2
+
3
+ 0.69.14 publishes what 0.69.13 carried: the tag v0.69.13 was cut, but its
4
+ release workflow stopped before publication (the Desktop's Linux launch
5
+ check lacked the root dependencies), so no 0.69.13 reached npm or GitHub
6
+ Releases. Everything in the [0.69.13 notes](v0.69.13.md) ships here, with
7
+ the workflow fixed and the rest of the state-changing commands refusing a
8
+ flag they do not define.
9
+
10
+ ## Upgrade
11
+
12
+ - **Read the [0.69.13 Upgrade section](v0.69.13.md#upgrade) first:** its
13
+ steps are this release's too, since 0.69.13 was never published.
14
+ - **Either order of the Desktop and the CLI works.**
15
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
16
+ installed the CLI first is fine too: the 0.69.14 Desktop accepts OATS CLIs
17
+ `>=0.26.0 <0.70.0`, as the 0.69.12 and 0.69.11 Desktops do.
18
+ - **Package pins** are 0.69.13's: oats.framework 1.23.0, oats.okf 5.8.0 and
19
+ oats.aweb 1.37.0.
20
+
21
+ - **A flag these commands never defined is now refused, where it was
22
+ ignored** (oats-project/oats#1824). A typo of a real flag is now refused
23
+ before anything happens: `oats schedule host install --prnt` installed the
24
+ host timer and `oats schedule tick --dry-rn` ran the tick; both are now
25
+ refused with `E_BAD_ARGS`. Check scripts and schedules that call `oats
26
+ instance`, `oats schedule`, `oats trigger`, `oats session`, `oats server
27
+ check` or `oats update`: what is now refused is listed under Fixed below,
28
+ and the flags each command defines in
29
+ [The flags a command defines](../desktop-cli-api.md#command-flags).
30
+
31
+ ## Fixed
32
+
33
+ - **The rest of the commands that change state refuse a flag they do not
34
+ define** (oats-project/oats#1791, after #1813). These read the flags they
35
+ knew and ignored every other one: `oats instance color`, `background`,
36
+ `same-work`, `waiting set|clear` and `attention`; `oats schedule add`,
37
+ `update`, `tick` and `host install`; `oats trigger add`, `poll` and
38
+ `test`; `oats session input`, `receive`, `upload` and `attach`; `oats
39
+ server check`; and `oats update`. A typo of one of their flags did the
40
+ thing without it: `oats schedule host install --prnt` installed the host
41
+ timer where `--print` only prints its files, and `oats schedule tick
42
+ --dry-rn` ran the tick.
43
+ - Each of them now refuses, with `E_BAD_ARGS` and before anything
44
+ happens, a flag it does not define, a value given with `=` to one of its
45
+ switches, and an argument after the last one it takes, with the same
46
+ words as the commands of #1813 (`oats schedule tick: unknown flag
47
+ --dry-rn` and the usage line; `error.details.flag` or
48
+ `error.details.argument`). A routed one (`--server`) missing an argument
49
+ it requires is `E_USAGE` here, and nothing is sent.
50
+ - A script that passes one of these commands a flag it never defined gets
51
+ the refusal where the flag was ignored: remove the flag. Among them:
52
+ `--dir` on `oats session input`, `receive`, `upload` and `attach` (they
53
+ take `--home`), `--server` on `oats trigger add`, `poll` and `test`
54
+ (which have no route), `--clear` on `oats instance waiting` (it is
55
+ `oats instance attention`'s), and anything after `oats update`'s own
56
+ flags. `--server` on `oats instance waiting`, `oats instance attention`,
57
+ `oats session input` and `oats session receive`, which have no route, is
58
+ `E_BAD_ARGS`, unknown flag, where it was `E_USAGE` from the router. The flags each command defines
59
+ are listed in
60
+ [The flags a command defines](../desktop-cli-api.md#command-flags).
61
+ - **The commands that already refused a flag they do not read check it in
62
+ the same place**: `oats spawn`, `oats sync`, `oats session resume`, `oats
63
+ instance suggest-name`, `oats teams` and `oats soul launch set|remove`.
64
+ Their answers keep their words: `oats teams` and `oats soul launch` still
65
+ answer `E_USAGE {flag}`, `oats spawn` its own `unknown flag` and
66
+ capability-setting words. What changed:
67
+ - `oats spawn --instructions-file`, `--def-file` and `--ephemeral` are
68
+ refused in their own words on a `--server` spawn too, where they were an
69
+ unknown flag, and carry `error.details.flag`. `oats spawn <soul> -x` is
70
+ `oats spawn: unknown flag -x`, where it was an unexpected argument.
71
+ - `oats instance suggest-name` says `unknown flag <flag>` with the usage
72
+ line and `error.details.flag`, where it said `unexpected flag "<flag>"`;
73
+ `oats session resume`'s refusal carries `error.details.flag` or
74
+ `error.details.argument`, and an argument is `unexpected argument
75
+ "<word>": session resume takes no argument`. `oats sync <word>` is
76
+ `sync takes no argument`, where it said `sync takes no positional`.
77
+ - `oats teams add|remove|default <label> <word>` refuses the second word,
78
+ which it ignored; `oats teams --dir <d> add <label>` (a flag before the
79
+ form) is refused with the forms' usage, where it listed the teams.
80
+ - `oats instance background|same-work <instance> on off` is `unexpected
81
+ argument "off" after the state "on"`, where it said `give on or off`.
82
+
83
+ - **The release workflow installs the root dependencies before the Desktop's Linux launch check.** The packaged-window launch phase (#1757) onboards a fixture deployment with this repository's kernel. `release.yml`'s Desktop job installed only `packages/desktop`'s dependencies, so on the v0.69.13 tag the Linux leg failed (`Cannot find package 'yaml'`) and nothing was published. The pull-request workflow, `build-installers.yml`, already installed both. The release now installs them on the Linux leg after packaging, just before the launch, so the Desktop suite and packaging still run with the Desktop's dependencies alone. `test/release-workflow.test.mjs` requires each workflow to install the root dependencies before the launch, and `test/continuous-integration.test.mjs` allows that one root install and no other.
@@ -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.