@awebai/oats 0.69.14 → 0.69.16

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 (60) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +79 -18
  3. package/docs/capabilities.md +57 -14
  4. package/docs/container.md +111 -17
  5. package/docs/desktop-cli-api.md +215 -19
  6. package/docs/desktop.md +3 -3
  7. package/docs/execution-targets.md +15 -3
  8. package/docs/first-team.md +4 -3
  9. package/docs/implementation.md +19 -9
  10. package/docs/integrations.md +9 -8
  11. package/docs/knowledge-and-learning.md +2 -2
  12. package/docs/knowledge-theory.md +17 -15
  13. package/docs/knowledge.md +202 -179
  14. package/docs/official-catalog.md +4 -4
  15. package/docs/packages.md +13 -13
  16. package/docs/release-notes/v0.69.15.md +444 -0
  17. package/docs/release-notes/v0.69.16.md +169 -0
  18. package/docs/schedules.md +168 -34
  19. package/docs/servers.md +64 -3
  20. package/docs/souls-and-instances.md +100 -19
  21. package/docs/upgrading.md +26 -6
  22. package/docs/workspaces.md +2 -2
  23. package/lib/claim.mjs +2 -3
  24. package/lib/command-flags.mjs +4 -2
  25. package/lib/core.mjs +215 -72
  26. package/lib/dir-lock.mjs +17 -0
  27. package/lib/errors.mjs +2 -1
  28. package/lib/host-run.mjs +218 -0
  29. package/lib/host-stop-child.mjs +21 -0
  30. package/lib/instance-git.mjs +32 -6
  31. package/lib/instance-lifecycle.mjs +4 -3
  32. package/lib/instance-listing.mjs +35 -6
  33. package/lib/kernel-features.mjs +4 -1
  34. package/lib/read-call.mjs +1 -1
  35. package/lib/remote.mjs +17 -14
  36. package/lib/schedule.mjs +237 -20
  37. package/lib/servers.mjs +83 -5
  38. package/lib/session-end.mjs +28 -8
  39. package/lib/session-resume.mjs +10 -18
  40. package/lib/session-seen.mjs +4 -64
  41. package/lib/status-words.mjs +11 -4
  42. package/lib/system-tools.mjs +1 -36
  43. package/lib/worktree-hooks.mjs +6 -175
  44. package/lib/worktree.mjs +19 -10
  45. package/package-catalog.json +3 -3
  46. package/package.json +4 -1
  47. package/packages/record/README.md +56 -21
  48. package/packages/record/docs/capture-service.md +8 -5
  49. package/packages/record/docs/turn-record-sot.md +9 -0
  50. package/packages/record/lib/capture-health.mjs +6 -4
  51. package/packages/record/lib/capture-lock.mjs +31 -27
  52. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  53. package/packages/record/lib/capture-scratch.mjs +2 -1
  54. package/packages/record/lib/derived-state.mjs +4 -2
  55. package/packages/record/lib/index-db.mjs +4 -2
  56. package/packages/record/lib/lock-holder.mjs +21 -0
  57. package/packages/record/lib/private-files.mjs +18 -0
  58. package/packages/record/lib/process-identity.mjs +310 -0
  59. package/packages/record/lib/store.mjs +31 -25
  60. package/skills/oats-getting-started/SKILL.md +9 -6
@@ -0,0 +1,169 @@
1
+ # OATS 0.69.16
2
+
3
+ 0.69.16 moves OATS onto oats.okf 6: there is no knowledge harvester any more,
4
+ and an instance proposes what it learned itself, as a pull request the
5
+ knowledge maintainer reviews (`oats okf propose`). The official catalog pins
6
+ oats.okf 6.0.1, oats.aweb 1.39.0 and oats.framework 1.24.0, and OATS's own
7
+ texts, souls and template copy follow. The team agent image now runs
8
+ `oats host run`.
9
+
10
+ ## Upgrade
11
+
12
+ - **Either order of the Desktop and the CLI works.**
13
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
14
+ installed the CLI first is fine too: the 0.69.16 Desktop accepts OATS CLIs
15
+ `>=0.26.0 <0.70.0`, as the 0.69.15 Desktop does.
16
+ - **Package pins:** oats.okf 6.0.1 (from 5.8.0), oats.aweb 1.39.0 (from
17
+ 1.37.0) and oats.framework 1.24.0 (from 1.23.0). A deployment that pins
18
+ them takes the steps below; one that keeps its own pins changes nothing
19
+ until it moves them.
20
+
21
+ - **A deployment that takes oats.okf 6.0.1 does these by hand**, from its
22
+ deployment directory (oats.okf's
23
+ [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.1/README.md#upgrading-to-60)
24
+ has each step's commands; [knowledge.md](../knowledge.md#pin-and-select-the-package)
25
+ the summary):
26
+ 1. Delete the harvester's launch preference, if any:
27
+ `oats soul launch remove oats.okf/knowledge-harvester --plan`, then
28
+ without `--plan`.
29
+ 2. Delete every `--provider oats.okf harvest=…` spawn flag from the
30
+ scripts and briefs that spawn instances. Remove a leftover host
31
+ `harvest` key with `oats okf setup --remove-legacy-settings --soul
32
+ <soul>` (`--plan` first).
33
+ 3. Add the `proposal-review` trigger beside `harvest-review`: an existing
34
+ `harvest-review` watches only the 5.x label `okf-harvest`, so it never
35
+ reviews a 6.0 proposal. For a workspace file, copy it under the template
36
+ `oats.okf:proposal-review` and the id `okf-proposal-review`, keeping its
37
+ `set:`, `runsOn` and `owner`. On its review host, if `oats-local.yaml`
38
+ lists named `automations: trust:` entries, add
39
+ `- <member>/okf-proposal-review` beside the old one, then check that
40
+ `oats trigger show <member>/okf-proposal-review --json` answers
41
+ `runsHere: true`. For a local trigger, read its values with `oats
42
+ trigger show <id> --json` and repeat them as `--set` values on `oats
43
+ trigger add --from oats.okf:proposal-review`. Remove `harvest-review`
44
+ (and its trust line) once no 5.x harvester can open an `okf-harvest`
45
+ PR.
46
+ 4. Protect every Git base's accepted branch (pull requests only, merged by
47
+ the knowledge maintainer's account), and give each proposing host's
48
+ account branch-create access on the knowledge repository, never
49
+ accepted-branch push; optionally set `screen-terms-file`
50
+ ([Settings](../knowledge.md#settings)).
51
+ 5. Retire the harvesters `oats status` still lists, once they have handed
52
+ over. A retired source's claims are proposed with the operator form,
53
+ `oats okf propose --home <retirement recovery directory> --soul <soul>`
54
+ (`--plan`, `--check`, `--apply`).
55
+ - **OATS's own workspace** adds `oats-triggers/okf-proposal-review.yaml`
56
+ beside `okf-harvest-review.yaml`. On the host it names, add its trust line
57
+ as in step 3 unless that host trusts `"*"`.
58
+
59
+ - **oats.aweb 1.39.0 tests aw 1.36.56** (from 1.36.53). The floor stays
60
+ aw 1.36.33. `aw-newer-than-tested` now warns only above 1.36.56, and the
61
+ pin it names is `npm i -g @awebai/aw@1.36.56`. Install that version on
62
+ each host where readiness asks for it.
63
+ - **pi homes: remove or filter `@awebai/claude-skills` in the launch's pi
64
+ folder.** From oats.aweb 1.38.0, home readiness warns
65
+ `pi-skills-package-loaded` when that pi folder lists
66
+ `npm:@awebai/claude-skills` without `"skills": []`. Remove the entry, or
67
+ filter it. With @awebai/pi 0.5.0 or later installed there,
68
+ `pi-extension-skills-loaded` no longer asks for the skills filter.
69
+ - **Bringing your own team** (`oats aweb setup --create <label> --namespace
70
+ <domain>`) needs aw 1.36.53 or later, and refuses an older aw before it
71
+ creates anything.
72
+
73
+ - **Rebuild the [team agent image](../container.md) and recreate its
74
+ container.** The image pins OATS 0.69.15 and its entrypoint runs
75
+ `oats host run`; an existing container keeps the old entrypoint, the
76
+ 10-second stop timeout and no healthcheck until it is made again from the
77
+ new image and `container/agent/compose.agent.yaml` (`docker compose ... up
78
+ -d`). `container/agent/accept.sh` refuses a container whose stop timeout
79
+ is not 45 seconds or whose healthcheck is not the service file's.
80
+ - **A platform that does not read the Compose file** gives the container a
81
+ stop timeout of 45 seconds itself: `oats host run` gives each harness 20
82
+ seconds to end, and Docker's default of 10 kills the agents before they
83
+ are stopped in order.
84
+ - **Register the deployment for schedules once**, after `server connect`:
85
+ `oats schedule host install --register-only --server team-agent`. The
86
+ operator's OATS must be 0.69.15 or later for the option.
87
+
88
+ ## Changed
89
+
90
+ - **The official catalog pins oats.okf 6.0.1** (from 5.8.0, crossing 6.0.0),
91
+ and OATS's own workspace takes it. 6.0 removes the knowledge harvester: an
92
+ instance proposes its knowledge by pull request at its checkpoints (`oats
93
+ okf propose`), and the knowledge maintainer reviews it. `oats.okf-harvest`
94
+ and `oats.okf/knowledge-harvester` stay as refusing stubs until 7.0. It
95
+ also reads a bridged knowledge base by subject (`okf.json` version 2, and
96
+ the `subjects`, `subject`, `claims` and `verdicts` verbs); a base that is
97
+ not bridged, and a version-1 soul, are served as before. The generated
98
+ mirror under `mirrors/oats-okf*` is finalized from the v6.0.1 tag
99
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-
100
+ okf/blob/v6.0.1/CHANGELOG.md)).
101
+
102
+ - **OATS's texts follow oats.okf 6: an instance proposes its own knowledge.**
103
+ The docs, the souls and the `oats.framework` skills no longer name a
104
+ harvester to launch, wait for or retire: at each knowledge checkpoint an
105
+ instance with a duty to propose runs `oats okf propose` itself, and the
106
+ knowledge maintainer's review gates the pull request
107
+ ([knowledge.md](../knowledge.md#the-flow),
108
+ [schedules.md](../schedules.md#knowledge-proposal-review)). A finished
109
+ instance's done line is one of "done, proposed: <PR URLs>", "done, nothing
110
+ to propose: <reason>" or "done, no duty to propose"; "done, proposal
111
+ pending: <slug and why>" means it is not finished yet.
112
+
113
+ - **`oats.framework` 1.24.0 carries OATS's texts for oats.okf 6 and the pi
114
+ folder steps for @awebai/pi 0.5.0.**
115
+ - `oats.setup` 2.15.0:
116
+ - `/oats-onboarding`, `/oats-automations` and `/oats-agent-permissions`
117
+ describe oats.okf 6.0.1: an instance proposes its own knowledge with
118
+ `oats okf propose`, the `oats.okf:proposal-review` trigger reviews it,
119
+ and there is no harvester to set up.
120
+ - `/oats-host-delivery`'s pi step asks for the skills filter only below
121
+ @awebai/pi 0.5.0, and keeps @awebai/claude-skills out of OATS pi
122
+ folders.
123
+ - `oats.coordination-setup` 1.0.1's `/coordination-best-practices` says
124
+ knowledge is proposed at checkpoints, not harvested.
125
+
126
+ The commands these name come from oats.okf 6, which the catalog pins. None
127
+ needs a newer OATS than each capability already admits.
128
+
129
+ - **OATS's copy of the engineering template moves to template-v3.0.2**, which
130
+ makes the same change in the coordination skills and injects.
131
+
132
+ - **The official catalog pins oats.aweb 1.39.0** (from 1.37.0, crossing
133
+ 1.38.0), and OATS's own workspace takes it. It brings:
134
+ - from 1.38.0, the pi skills-filter change above;
135
+ - from 1.39.0, a bring-your-own-team create that runs to the end
136
+ (registers the team, publishes and verifies its team-server record, and
137
+ resumes when re-run); a public `aw-compat.json` stating the aw floor and
138
+ the tested aw; and owner-only draft files for mail and chat bodies
139
+ instead of fixed `/tmp` paths.
140
+
141
+ `mirrors/oats-aweb` and `mirrors/oats-aweb-tasks` are copied from the
142
+ v1.39.0 tag
143
+ ([oats.aweb's CHANGELOG](https://github.com/awebai/oats-aweb/blob/v1.39.0/CHANGELOG.md)).
144
+
145
+ - **The team agent image runs the kernel's periodic work.** Its entrypoint
146
+ starts sshd in the background and ends in `exec oats host run`, so that
147
+ command is tini's direct child, the process the runtime's SIGTERM reaches
148
+ and the container waits for. At start it resumes the sessions lost when
149
+ the container last stopped, then runs the schedule tick each minute for
150
+ the registered deployments; on `docker stop` it stops the agents in order
151
+ and the next start resumes them
152
+ ([container.md](../container.md#the-kernels-periodic-work)).
153
+ - The image pins OATS 0.69.15, the first release with `oats host run`.
154
+ - The Compose service sets `stop_grace_period: 45s`.
155
+ - The Compose service has a healthcheck that opens sshd's port,
156
+ `127.0.0.1:2222`, every 30 seconds. `oats host run` does not supervise
157
+ sshd, and Docker does not restart an unhealthy container: when
158
+ `docker inspect --format '{{.State.Health.Status}}'` reads `unhealthy`,
159
+ `docker restart` the container.
160
+ - The acceptance script requires the 45-second stop timeout and that
161
+ healthcheck in the container's inspect evidence.
162
+
163
+ ## Documentation
164
+
165
+ - **The pi skills filter is for @awebai/pi below 0.5.0, and @awebai/claude-skills stays out of OATS pi folders.**
166
+ - **Why:** @awebai/pi 0.5.0 bundles no skills. They now ship on their own in @awebai/claude-skills, which pi would load in every session that uses the folder.
167
+ - **`/oats-host-delivery`** (`oats.framework`): the pi step of channel delivery makes the extension's entry `{"source": "npm:@awebai/pi", "skills": []}` only below 0.5.0.
168
+ - **The getting-started onboarding:** it still sets the filter whatever the version, because it's harmless on 0.5.0.
169
+ - Both now say never to install @awebai/claude-skills in a pi folder that OATS homes use, because a home gets its skills from its capabilities. This matches oats.aweb 1.38.0, whose readiness warns `pi-extension-skills-loaded` only below 0.5.0 and adds `pi-skills-package-loaded`.
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
@@ -152,9 +221,9 @@ refuses the key on a trigger.
152
221
  again only at due minutes, so a harness that keeps exiting is not restarted
153
222
  in a loop. Unobservable or still starting: skipped, delivery kept pending.
154
223
  Word wake messages so that receiving one again is harmless.
155
- - **operation** `{…, operation, home}` — runs a provider operation such as
156
- `knowledge:harvest` in the instance at `home` through `oats operation run
157
- <layer>:<name> --home <home>`. The provider is whatever fills that layer
224
+ - **operation** `{…, operation, home}` — runs a provider operation
225
+ (`<layer>:<name>`, one the capability filling that layer declares) in the
226
+ instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
158
227
  when the job runs. Tracking is that of a command job.
159
228
 
160
229
  `--wake-every N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07,
@@ -175,11 +244,11 @@ reports `gh.credentialSource` (`keyring`, `config`, `env:<VAR>`) and warns
175
244
  when the timer cannot reach it.
176
245
 
177
246
  ```json
178
- { "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
179
- "description": "Review every harvest PR on the knowledge base",
247
+ { "id": "okf-proposal-review", "enabled": true, "kind": "trigger",
248
+ "description": "Review every knowledge proposal PR on the knowledge base",
180
249
  "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
181
250
  "events": ["opened", "reopened", "ready_for_review"],
182
- "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
251
+ "labels": ["okf-proposal"], "base": "main", "poll": "2m" },
183
252
  "spawn": { "soul": "oats.okf/knowledge-maintainer", "purpose": "review-pr-{number}",
184
253
  "task": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
185
254
  "harness": "claude", "model": "opus" },
@@ -259,7 +328,7 @@ when the timer cannot reach it.
259
328
 
260
329
  ```sh
261
330
  oats trigger add --file trigger.json [--description=<text>] # or:
262
- oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
331
+ oats trigger add --from oats.okf:proposal-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
263
332
  oats trigger update <id> --description=<text> # the description only; --description= clears it
264
333
  oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
265
334
  oats trigger test <id> # dry run: gh credentials, repo permissions, the soul, what WOULD fire
@@ -507,11 +576,11 @@ with the kind's suffix anywhere in the member (`.yml` works too), for example
507
576
  `oats-package/`, `.git/` and `node_modules/` are never scanned.
508
577
 
509
578
  ```yaml
510
- # <member>/oats-triggers/okf-harvest-review.yaml
579
+ # <member>/oats-triggers/okf-proposal-review.yaml
511
580
  kind: oats-trigger
512
581
  schemaVersion: 1
513
- description: Review every harvest PR on the knowledge base
514
- from: oats.okf:harvest-review # a package template at the locked commit, then its parameters
582
+ description: Review every knowledge proposal PR on the knowledge base
583
+ from: oats.okf:proposal-review # a package template at the locked commit, then its parameters
515
584
  set: { repo: github.com/acme/knowledge }
516
585
  runsOn: kb-bot-server # the host.name that runs it
517
586
  owner: github.com/acme-kb-bot # the GitHub account it acts as
@@ -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.
@@ -991,35 +1122,38 @@ more than that:
991
1122
  fails, the spawn result still carries the instance receipt, plus
992
1123
  `wakeScheduleError` and a warning.
993
1124
 
994
- ## Knowledge harvest and review
1125
+ ## Knowledge proposal review
995
1126
 
996
- **oats.okf 5.x does not schedule harvest jobs.** In 5.2 the capability's
997
- IMPORTANT inject and compulsory `okf-propose` skill give the duty, not TASK.md.
998
- A working instance keeps its notes current, checks `oats okf status`, and at
999
- a finished task or PR hand-over proposes only durable, non-duplicate claims.
1000
- At most one proposal per completed unit of work, one harvester at a time,
1001
- and no spawn under memory pressure or below 8 GB available; otherwise defer
1002
- and hand back the pending claims. Most checkpoints propose nothing. When the
1003
- skill's gates pass, the instance directly spawns the package harvester:
1127
+ **oats.okf 6 schedules no knowledge job.** Its IMPORTANT inject and
1128
+ compulsory `okf-propose` skill give the duty to propose, not TASK.md. At each
1129
+ knowledge checkpoint an instance with that duty proposes its durable,
1130
+ non-duplicate claims itself, from its home, as one pull request on the
1131
+ knowledge base:
1004
1132
 
1005
1133
  ```sh
1006
- oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
1134
+ oats okf propose --plan --slug <slug> # stages the proposal in the home
1135
+ oats okf propose --check --slug <slug> # the diff and its digest
1136
+ oats okf propose --apply --slug <slug> --digest <digest>
1007
1137
  ```
1008
1138
 
1009
- The unrelated harvester can outlive the proposing instance. It checks the
1010
- recorded source and its soul opt-out, accepted knowledge and open/recent
1011
- harvest PRs, then proposes an owned-node change through a normal reviewed
1012
- Git PR. Retirement does not automatically capture or harvest anything.
1013
- There is no host harvest switch, per-source command job, run-source command
1014
- or capture/drain/worker engine. The soul-only `knowledge: { harvest: off }`
1015
- keeps consultation while forbidding harvest of that soul's material.
1139
+ `--apply` pushes a create-only `okf-proposal/<date>-<id>` branch and opens
1140
+ one PR labelled `okf-proposal`; most checkpoints propose nothing. No worker
1141
+ is spawned, nobody waits for the PR, and retirement captures nothing. There
1142
+ is no host switch, per-source job or capture engine. The soul-only
1143
+ `knowledge: { harvest: off }` keeps consultation while giving that soul no
1144
+ duty to propose ([The soul's opt-out](knowledge.md#the-souls-opt-out)).
1016
1145
 
1017
- **Review still uses a trigger.** Each harvest PR can be reviewed by
1146
+ **Review still uses a trigger.** Each proposal PR can be reviewed by
1018
1147
  `oats.okf/knowledge-maintainer`, spawned from the package template
1019
- `oats.okf:harvest-review`: a workspace trigger file or a local
1020
- `oats trigger add --from oats.okf:harvest-review`. This is a PR-review
1021
- trigger, not a harvest scheduler or a kernel PR-opened capture hook.
1022
-
1148
+ `oats.okf:proposal-review`: a workspace trigger file or a local
1149
+ `oats trigger add --from oats.okf:proposal-review`. Through 6.x the template
1150
+ `oats.okf:harvest-review` watches only the 5.x label `okf-harvest`: keep it
1151
+ beside `proposal-review` only while a 5.x harvester may still open such a
1152
+ PR. These are PR-review triggers, not a knowledge scheduler or a kernel
1153
+ PR-opened capture hook.
1154
+
1155
+ A deployment moving from 5.x takes the hand steps in
1156
+ [Pin and select the package](knowledge.md#pin-and-select-the-package).
1023
1157
  Deployments upgrading from 4.x must settle registered sources before
1024
1158
  changing the pin, then use the 5.0 guard-exempt host-key cleanup before new
1025
1159
  spawns. See the [5.0 cutover sequence](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters). Provider
package/docs/servers.md CHANGED
@@ -425,7 +425,9 @@ Every routed ssh call carries these options, before `--` and the host:
425
425
  failed: …`). When ssh never started on this machine, the `--json` envelope
426
426
  says so with `error.details: {"sshStarted": false}`; without details, ssh
427
427
  ran and the link failed
428
- ([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)).
428
+ ([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)). A link that
429
+ fails under a routed spawn carries the decision and the key to run it
430
+ again with ([Run there](#run-there)).
429
431
 
430
432
  ## Run there
431
433
 
@@ -440,9 +442,27 @@ Arguments are quoted for the remote shell. Local files (`--task-file`,
440
442
  `--wake-file`, a schedule or launch-configuration `--file`) are read here and
441
443
  sent as text or on stdin, never as paths.
442
444
 
445
+ <a id="a-routed-spawns-task"></a>
446
+ **A routed spawn's task is on no command line, for a server that advertises
447
+ `spawn-task-stdin`.** The text of `--task` or of `--task-file` goes to such a
448
+ server on the standard input of the ssh session, to the server's preview and
449
+ to its spawn alike, and the remote command carries `--task-file -` in its
450
+ place: the text is in the arguments of neither the local `ssh` process nor
451
+ the server's `oats`, where every user of either machine could read it in the
452
+ process list. A server that does not advertise `spawn-task-stdin` cannot read
453
+ it there, and gets it as an argument of the remote command: the spawn
454
+ succeeds, the task is readable in both process lists while it runs (this
455
+ machine's, in the `ssh` command, and the server's), and the answer carries
456
+ one warning that says so: `remote oats <version> at <host> does not
457
+ advertise spawn-task-stdin, so the task was passed as an argument, visible
458
+ in this machine's process list (the ssh command) and the host's while the
459
+ spawn runs; upgrade the host`. Upgrade OATS on the server to keep tasks off
460
+ both command lines. A `--wake-message` and a
461
+ schedule's spec still travel as arguments.
462
+
443
463
  | Command | Where it runs | The server must advertise |
444
464
  |---|---|---|
445
- | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
465
+ | `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
446
466
  | `status` | registered workspace | |
447
467
  | `retire` | the instance's home | `retire-home` to retire by exact home |
448
468
  | `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
@@ -472,6 +492,44 @@ checked against the harness it would use (the flag, or the soul's default as
472
492
  the remote roster reports it). A host that advertises no harness list is
473
493
  assumed to run only pi and claude, on tmux, with no launch options.
474
494
 
495
+ **A routed spawn.** `oats spawn <soul> --server <id>` runs the spawn's checks
496
+ here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and options), then
497
+ asks the server's kernel in two calls:
498
+
499
+ 1. its preview (`spawn … --preview`), which decides the name and everything
500
+ else and creates nothing;
501
+ 2. the spawn itself, bound to that decision and to a key made for this
502
+ request (`--expect-decision <revision> --idempotency-key <key>`).
503
+
504
+ The answer is the server's keyed answer (`decision`, `replayed`, `wake`
505
+ beside the rest) plus `server`, `target` and `snapshot`, and the route is
506
+ saved. With `--suggest-name` the preview chooses the name and the spawn
507
+ carries it as `--name`; the answer keeps the preview's `naming`. This needs
508
+ the server's `spawn-suggest-name` and `spawn-name` too.
509
+
510
+ - **A link that fails under the second call** (a lost connection, a
511
+ timeout) is `E_SSH`, and the server may have started the spawn. The
512
+ message ends with the fix, and `--json` carries it:
513
+ `error.details: {decision, idempotencyKey, fix}`. Run the same spawn again
514
+ with `--expect-decision <decision.revision> --idempotency-key
515
+ <idempotencyKey>` (and `--name <decision.instance>` in place of
516
+ `--suggest-name`): the server answers the instance the first attempt
517
+ created (`replayed: true`), or creates it, and the route is saved. An
518
+ attempt still running there answers `E_SPAWN_INCOMPLETE`, naming the
519
+ instance. Run again without the two flags, the spawn is a separate request
520
+ and may create a second instance.
521
+ - **A name taken between the two calls** (another spawn on the server took
522
+ it) is `E_DECISION_STALE`; nothing was created. Run the spawn again.
523
+ - **A spawn that brings `--expect-decision` or `--idempotency-key`** travels
524
+ as given, in one call: the caller previewed (`--server <id> --preview`) and
525
+ holds the key.
526
+ - **A server that does not advertise `spawn-preview-2`, `spawn-apply-2` and
527
+ `spawn-idempotency-2`** gets the spawn in one call, as given, and the
528
+ answer carries a warning: if the link drops while it spawns, the spawn
529
+ cannot be retried safely, since the instance may exist there and a second
530
+ run would create another. Check `oats status --server <id>` before running
531
+ it again, or upgrade OATS there.
532
+
475
533
  **A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
476
534
  spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
477
535
  options), then asks the server's kernel for its preview. It prints the local
@@ -611,7 +669,10 @@ It relays the host's viewer fact the same way, `probe.sessionViewer`
611
669
  host's viewer takes `C-b [`, or `null` when unknown.
612
670
 
613
671
  **Harvest** runs the knowledge capability's `okf harvest --json` in the
614
- instance's saved home on the server and relays its envelope.
672
+ instance's saved home on the server and relays its envelope. oats.okf 5.0
673
+ and later refuse that command with `E_REMOVED`: an instance proposes its
674
+ knowledge from its own home with `oats okf propose`
675
+ ([the flow](knowledge.md#the-flow)).
615
676
 
616
677
  ## What this machine keeps
617
678