@awebai/oats 0.48.0 → 0.49.0

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 (41) hide show
  1. package/bin/oats.mjs +226 -14
  2. package/docs/capabilities.md +256 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +6 -0
  5. package/docs/desktop-cli-api.md +368 -31
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +17 -2
  8. package/docs/implementation.md +62 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +2 -2
  12. package/docs/packages.md +8 -8
  13. package/docs/release-notes/v0.49.0.md +770 -0
  14. package/docs/schedules.md +62 -39
  15. package/docs/servers.md +7 -0
  16. package/docs/souls-and-instances.md +381 -53
  17. package/docs/workspaces.md +2 -2
  18. package/injects/work-checkout.md +17 -11
  19. package/injects/work-worktree.md +19 -13
  20. package/lib/capability-contract.mjs +100 -11
  21. package/lib/capability-show.mjs +5 -2
  22. package/lib/core.mjs +1109 -321
  23. package/lib/instance-events.mjs +6 -3
  24. package/lib/instance-git.mjs +11 -5
  25. package/lib/instance-inspect.mjs +14 -3
  26. package/lib/instance-lifecycle.mjs +106 -16
  27. package/lib/instance-resolution.mjs +15 -3
  28. package/lib/launch-prompt-policy.mjs +17 -3
  29. package/lib/packages.mjs +1 -0
  30. package/lib/real-path.mjs +27 -0
  31. package/lib/resolve.mjs +4 -4
  32. package/lib/retire-output.mjs +6 -1
  33. package/lib/schedule.mjs +1 -0
  34. package/lib/servers.mjs +32 -6
  35. package/lib/tree-copy.mjs +18 -7
  36. package/lib/triggers.mjs +201 -65
  37. package/lib/workspace.mjs +20 -5
  38. package/lib/worktree-hooks.mjs +392 -0
  39. package/lib/worktree.mjs +655 -0
  40. package/package-catalog.json +1 -1
  41. package/package.json +1 -1
package/docs/desktop.md CHANGED
@@ -45,6 +45,15 @@ it, but opening a terminal will fail until tmux is installed. The DEB
45
45
  declares the dependency; for the AppImage install it yourself
46
46
  (`apt install tmux`, `dnf install tmux`, …) and verify with `tmux -V`.
47
47
 
48
+ The AppImage mounts itself with FUSE, which some current distributions
49
+ don't install. Without it, start the AppImage with
50
+ `--appimage-extract-and-run`. Don't extract the image and run its `AppRun`
51
+ yourself: started that way, Desktop can't tell which entries in `PATH`,
52
+ `XDG_DATA_DIRS`, `LD_LIBRARY_PATH` and `GSETTINGS_SCHEMA_DIR` the image
53
+ added, so the programs it starts keep them, among them the tmux server it
54
+ starts and every agent pane on it (see
55
+ [the environment of the programs Desktop starts](../packages/desktop/README.md#the-environment-of-the-programs-desktop-starts)).
56
+
48
57
  ### The `oats` CLI
49
58
 
50
59
  Reads (roster, hierarchy, files, terminals) work with no CLI at all.
@@ -167,11 +176,47 @@ pills (**All**, then one per repository, each with its count) show one
167
176
  repository at a time; "N of M shown" appears while a pill or the search
168
177
  narrows the list.
169
178
 
179
+ A soul's page (open a soul from **Workspace › Souls**) ends with
180
+ **Instructions**, what its instances are told: the soul's own `AGENTS.md`,
181
+ read like a capability's injected instructions (a navigation tree on the left,
182
+ the file on the right), at its path in the soul's repository. It comes from the
183
+ same inspection as the rest of the page, so **Refresh** re-reads it and keeps
184
+ what you had open, and your place in it. A file over 200,000 characters is
185
+ shown cut, and says so.
186
+
187
+ With an OATS that composes a soul's instructions (0.46.0 and later), the tree
188
+ also has **Instance**: its **AGENTS.md**, *after spawn, with injects*, is the
189
+ file a spawn of this soul on this computer would write, with one entry per part
190
+ (the soul's own text, then each block OATS and the soul's capabilities add, in
191
+ order). Open it to read the whole document; choose a part to go to it. Each
192
+ part's header says where it comes from (**From this soul** or **Injected by …**)
193
+ and names its file; a capability's part has **Open capability**, and **Copy
194
+ composed AGENTS.md** copies the exact file. When the soul can't be composed
195
+ here, the group says so and the problem shows at the top of the page. For a
196
+ soul on another machine (a server workspace), the page shows the composed file
197
+ when that machine supports it: this computer's OATS must be 0.49.0 or later, to
198
+ pass on what each server reports about itself, and the server's OATS must say
199
+ it composes a soul's instructions (0.49.0 and later report this). Until a
200
+ server reports it (an older server, or one whose last read failed), its soul
201
+ pages show only the soul's own `AGENTS.md`, with no **Instance** group.
202
+
170
203
  The **Spawn** dialog's left column, **What will be created**, starts with the
171
204
  new instance's name and its home. Then come where it works, its harness and
172
205
  model (with where that choice came from), its default team and the teams it may
173
206
  also join, and its relationship when it has one. Under them are its core
174
- capabilities and its other capabilities. Every dropdown in the app has the
207
+ capabilities and its other capabilities.
208
+
209
+ When capabilities set up the new worktree (OATS 0.49.0 and later), **Setup**
210
+ names them, in the order they run, and says this can take several minutes. Such
211
+ a spawn may run for a long time: its roster row reads **Setting up worktree…**
212
+ until the worktree is ready, and offers no actions meanwhile. If the spawn was
213
+ interrupted or a capability couldn't set up the worktree, the spawn was rolled
214
+ back, and the notification says that nothing was created. A home whose spawn
215
+ didn't finish its cleanup reads **Spawn didn't finish**, and one whose retire
216
+ didn't finish reads **Retire didn't finish**; both offer only **Retire
217
+ instance…**, which completes them. A server spawn whose worktree hooks take
218
+ more than about a minute is not yet supported from the Desktop; use the CLI on
219
+ the server. Every dropdown in the app has the
175
220
  same themed look, and its open list follows the light or dark theme.
176
221
 
177
222
  ## One workspace, several machines
@@ -301,6 +346,10 @@ from" line and "older build" chip show the facts the server relays. Only its pul
301
346
  computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
302
347
  <path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
303
348
  against it.
349
+ When this computer's OATS advertises `server-probe-features` (0.49.0), each server's roster group
350
+ also carries the features of the server's own OATS, as its `oats status` reports them
351
+ ([`probe.features`](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)); a server
352
+ before 0.49.0 reports none, so they read as unknown.
304
353
 
305
354
  A read waits for the server: the view says "Reading from <server>…", and gives up after about
306
355
  45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
@@ -377,7 +426,16 @@ has reached the execution host. Both CLI installations must advertise
377
426
  `session-upload`. A failed transfer leaves the draft unchanged and shows an
378
427
  error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
379
428
 
380
- ## Harness badges
429
+ ## Identity marks and harness badges
430
+
431
+ Souls, capabilities and workspaces carry a coloured two-letter mark beside
432
+ their name. It is decorative: the name beside it is authoritative. The letters
433
+ come from the name without its package qualifier (what follows the last `/`
434
+ or `--`), and from three words or more without its first (a namespace word like
435
+ `oats`): the initials of the first two words, or a one-word name's first two
436
+ letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-harvester` KH and
437
+ `oats.aweb` OA. Two names can share a mark (`oats-expert` and
438
+ `oats-operator-expert` are both OE); the name and the colour tell them apart.
381
439
 
382
440
  Roster rows, soul cards, the soul page, the context panel and the spawn
383
441
  dialog show each instance's or soul's harness as a small badge, next to its
@@ -399,7 +457,11 @@ unknown or unreported harness shows "?". Sources and licences are in
399
457
  app-owned read-only reader. All lifecycle mutations go through the
400
458
  installed CLI via `execFile` with an absolute binary — never a shell.
401
459
  - Task text for spawns travels via an owner-only (0600) tempfile, never
402
- argv. Harvest always runs in the server-verified instance home.
460
+ argv. A local start or restart launches only in the server-verified
461
+ instance home. A provider operation on an instance (its harvest included)
462
+ is addressed with `--home` to a home the server's roster reports, and one
463
+ on a soul to a soul and agents root the server lists, never a path the
464
+ caller names.
403
465
  - Workspace content is treated as untrusted: symlinked directories never
404
466
  widen the file API, and capability packages cannot read outside their
405
467
  own tree.
@@ -413,6 +475,7 @@ unknown or unreported harness shows "?". Sources and licences are in
413
475
  | Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux -L oats ls` (the OATS tmux server, where instances run) and `tmux ls` (your default server, where an instance started by an earlier kernel may still be). |
414
476
  | Can't select/copy text in a terminal tab | A plain drag selects, and copying is a separate step: ⌘C / Edit › Copy (macOS), Ctrl+Shift+C (Linux/Windows) or right-click › Copy ([Copy from a terminal](#copy-from-a-terminal)). A drag selects only what is on screen: wheel up first for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
415
477
  | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
478
+ | Log says `server on 4820 — this app's server at version X (this app is Y), not started by this app — left running — starting a dedicated one on 4821` | Another OATS Desktop server holds the default port: another installed version or a dev checkout that is running, or one an earlier Desktop left running. The app serves from the port it names and never stops a server it did not start. From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill). A server left by an earlier Desktop (seen on Linux, where it outlived the app in its own `app-…scope`) must be stopped once by hand: find it with `ss -ltnp 'sport = :4820'` (or `lsof -iTCP:4820 -sTCP:LISTEN` on macOS) and stop that pid, or its scope (`systemctl --user stop <scope>`), then restart the app. |
416
479
  | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use the workspace switcher → Add workspace to select the right folder. |
417
480
 
418
481
  For bugs, attach the terminal output of the app (`OATS Desktop` prints
@@ -426,5 +489,9 @@ Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README
426
489
  certificate auto-discovery disabled) and
427
490
  `npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
428
491
  marked build-verify mode (inventory + strict codesign verification +
429
- node-pty ABI, no GUI launch); a local
430
- interactive run may also exercise the launch phase.
492
+ node-pty ABI + a headless run of the bundled backend and its liveness
493
+ collector from `app.asar`, no GUI launch); a local
494
+ interactive run may also exercise the launch phase. The headless run starts
495
+ the backend as the app does, checks that it answers and that it exits when its
496
+ stdin closes, and runs the collector once; it does not exercise the GUI or,
497
+ on Linux, the AppImage's launcher and runtime.
@@ -326,7 +326,11 @@ operation, a retire or a trigger is given (`OATS_CAPABILITY`, `OATS_LAYER`,
326
326
  `OATS_PREVIOUS_RUNTIME`, `OATS_LAUNCH_PREVIEW`, `OATS_RETIRE_INTENT`,
327
327
  `OATS_TRIGGER_EVENT_FILE`, `OATS_TEST_LOGIN_SHELL` (a test seam that replaces
328
328
  the login shell, honoured only for a process whose `HOME` is not your home
329
- directory; a launch configuration cannot set it), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
329
+ directory; a launch configuration cannot set it),
330
+ `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS`, `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS`
331
+ and `OATS_TEST_PROCESS_START_PS` (below), a `worktree` hook's tree
332
+ (`OATS_TREE`, `OATS_TREE_CLONE`, `OATS_TREE_REMOTE`, `OATS_TREE_MEMBER`,
333
+ `OATS_TREE_BASE`, `OATS_TREE_BASE_OID`, `OATS_PURPOSE`, `OATS_TREE_ORIGIN`), `OATS_TEAM_NAME`, `OATS_TEAM_SCOPE`,
330
334
  `OATS_TEAM_ID`, `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS`, `OATS_TEAMS`,
331
335
  `OATS_TEAMS_SOURCE`, `OATS_DEFAULT_TEAM`, `OATS_DEFAULT_TEAM_ID`,
332
336
  `OATS_DEFAULT_TEAM_FROM`, `OATS_WORKSPACE_NAME`, `OATS_WORKSPACE_KEY`); and
@@ -336,6 +340,15 @@ for. Other `OATS_` variables you export (`OATS_HOME_DIR`,
336
340
  with your login environment (above). An agent's plain `oats` finds its
337
341
  deployment from its home.
338
342
 
343
+ `OATS_TEST_WORKTREE_HOOK_TIMEOUT_MS` is another test seam, not a setting: a
344
+ positive whole number of milliseconds replaces the fixed 30-minute timeout of
345
+ [`worktree` hooks](capabilities.md#the-worktree-event), so the kernel's own
346
+ tests can reach it. `OATS_TEST_WORKTREE_FETCH_TIMEOUT_MS` does the same for the
347
+ 10-minute fetch of `oats worktree add`. `OATS_TEST_PROCESS_START_PS=1` makes
348
+ the kernel read a process's start time with `ps`, as on a host without
349
+ `/proc` (macOS), on a host that has it. A launch configuration cannot set
350
+ any of them. Do not set them in a deployment.
351
+
339
352
  **An instance creates an agents' session or window without its own
340
353
  environment.** Nothing of an instance's environment reaches a server or a
341
354
  pane through the calls that create an agents' session or window. A harness
@@ -745,7 +758,9 @@ oats session attach --home /abs/home
745
758
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
746
759
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
747
760
  A home without its session receipt is refused with
748
- `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for; what
761
+ `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for (and, for a
762
+ spelling that differs from the on-disk one, the path a kernel before 0.49.0
763
+ used for that spelling); what
749
764
  to do is in [souls and instances](souls-and-instances.md#retire).
750
765
  Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
751
766
  live claim that the instance needs input from a human, `{since, producer,
@@ -62,9 +62,11 @@ published to npm. Its developer docs are in
62
62
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
63
63
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
64
64
  | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance |
65
+ | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, and the rollback of an interrupted add |
66
+ | `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL |
65
67
  | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
66
68
  | `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
67
- | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
69
+ | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
68
70
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
69
71
  | `servers.mjs` | routing commands to a registered server |
70
72
  | `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
@@ -321,6 +323,16 @@ install, and the gate requires it. `test/continuous-integration.test.mjs` pins
321
323
  that job against `desktop-build`: change how one installs or tests Desktop and
322
324
  the other changes with it.
323
325
 
326
+ The Desktop suite runs in the root shards and in `desktop-standalone`, and
327
+ `desktop-standalone` is its release gate. `test/release-workflow.test.mjs` no
328
+ longer runs it nested inside a root shard: it checks that the Desktop scripts
329
+ the release invokes exist. `test/helpers/nested-test-failure.mjs` remains the
330
+ way to build a readable failure message from a nested `node --test` run's
331
+ output. The message names the failing tests (TAP or spec reporter) with their
332
+ location and error, then gives bounded stdout and stderr tails, and its size
333
+ is capped. It is built only when the run failed, and it never throws: if
334
+ reading the failures fails, the message says so and still carries the tails.
335
+
324
336
  Cross-package tests that import both the kernel and Desktop belong under root
325
337
  `test/`; install dependencies at the root and in `packages/desktop` before
326
338
  running those tests. The schedule
@@ -361,6 +373,10 @@ and acts on every existing session through its recorded socket
361
373
  fixture, with no user configuration unless the test asks for it;
362
374
  `oatsSocket()` is the socket `-L oats` resolves to there. Its restore
363
375
  function kills that server, by socket.
376
+ - A test may instead start its own server on a private socket it creates
377
+ under the temporary directory (`tmux -S <socket>`) and kill that server by
378
+ its socket, as the older live tests in `test/desktop-tmux-target.test.mjs`
379
+ (base-index, wheel, drag, Slice G) do.
364
380
  - The shared fixture (`test/helpers/v2-deployment.mjs`) gives every command
365
381
  it runs a private `TMUX_TMPDIR` too, so a test with a fake `tmux` on `PATH`
366
382
  cannot reach a real server either. A fake answers what the kernel asks:
@@ -387,3 +403,48 @@ Nor does a test depend on where or how the suite runs:
387
403
  - A fixture the filesystem may not represent (a file name that is not valid
388
404
  UTF-8, which APFS refuses) is probed in the fixture directory and skipped
389
405
  with its reason only when refused; Linux CI runs it.
406
+
407
+ A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
408
+ unit, a live operator tmux server and Apple git, run from inside an instance
409
+ home. A pull request that could not be run there says so in its hand-over. The
410
+ suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
411
+ with `require`), git ≥ 2.45, lsof and tmux (awebai/oats#783). The
412
+ helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
413
+ shared fixture (`v2Deployment`) applies all of it, so a suite built on it
414
+ inherits it (awebai/oats#816):
415
+
416
+ - **A short base.** `fixtureBase(prefix)` makes the fixture directory under
417
+ the platform's temporary directory, or under `/tmp` when that is longer than
418
+ 20 characters (macOS's `/private/var/folders/…/T/` is about 49), as its
419
+ realpath, taken once.
420
+ - **Names and paths sized from the base.** `nameOfLength(base, n)` (a file
421
+ name or branch segment) and `pathOfLength(base, n)` (an absolute path under
422
+ the base, `n` characters in all) are capped below NAME_MAX and PATH_MAX of
423
+ the platform (255/1024 on macOS, 255/4096 on Linux), measured from the
424
+ actual base. A "too long" test then exercises the kernel's bound, never the
425
+ filesystem's.
426
+ - **An explicit environment for every child.** `fixtureEnv(base)` is what
427
+ every child the fixture starts gets, and `fx.inEnv` applies the same rules
428
+ to the test process for an in-process kernel call. It sets `HOME` and the XDG
429
+ base directories under the base, and `GIT_CONFIG_NOSYSTEM=1`,
430
+ `GIT_CONFIG_GLOBAL=/dev/null` and `GIT_TERMINAL_PROMPT=0`, so no host git
431
+ configuration or credential helper is read. It removes every `*_PROXY`,
432
+ `CLAUDECODE` and git configuration passed through the environment. PATH
433
+ starts with `launchctl` and `systemctl` stubs that answer as a service
434
+ manager with nothing loaded. A test that needs another answer puts its own
435
+ stub ahead of them.
436
+ - **The same rules under real tmux.** `isolateSessionEnvironment` applies the
437
+ same git, XDG and proxy rules. Its PATH stays its own small set of tools, so
438
+ no host service manager is reachable at all.
439
+ - **No leftover processes.** The fixture's cleanup fails when a process still
440
+ works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
441
+ `processesInHome` (lsof). It catches a hook's or a CLI's grandchild that
442
+ outlived the test, once its parent has exited. The scan leaves out its caller
443
+ and the caller's direct children, so a test's own forgotten child is not
444
+ found here: that is the test's bug to fix. A process still exiting gets 2 s.
445
+ Nothing is killed, the base is removed, and the failure names each pid and
446
+ command. A test that leaves a process running on purpose (a group the kernel
447
+ must not signal) ends it itself before that check, on failure too: node:test
448
+ runs `t.after` hooks in the order they were added, so its own hook added
449
+ after `t.after(fx.cleanup)` runs too late (`test/worktree-event.test.mjs`
450
+ ends them inside its cleanup hook, ahead of `fx.cleanup`).
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v4.1.1
43
+ oats.okf: v5.0.0
44
44
  oats.aweb: v1.21.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
@@ -78,15 +78,17 @@ operations in full.
78
78
 
79
79
  | Slot | Provider | Needs on the host | Documentation |
80
80
  | --- | --- | --- | --- |
81
- | `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` and `gh` for Git-backed bases; the harvest harness (`harvest-runtime`: `pi`, `claude` or `codex`) when harvest is on | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
81
+ | `knowledge` | `oats.okf` | `settings.oats.okf.bindings-file` and `state-dir` (absolute paths) in `oats-local.yaml`; `git` for Git-backed consultation, `git` and `gh` for proposal/review PRs; ordinary kernel/harness selection, no provider harvest-runtime setting | [awebai/oats-okf](https://github.com/awebai/oats-okf), [knowledge.md](knowledge.md) |
82
82
  | `messaging` | `oats.aweb` | the `aw` CLI at 1.36.13 or later; for channel delivery, `@awebai/pi` in pi or the `aweb-channel` plugin in Claude Code; host-only `root`, `roots` and `residents` in `oats-local.yaml` | [awebai/oats-aweb](https://github.com/awebai/oats-aweb) |
83
83
  | `tasks` | `oats.jira` | `acli`, authenticated to the Jira site; `site` and `project` in the soul's `tasks:` payload or `settings.oats.jira` | [awebai/oats-jira](https://github.com/awebai/oats-jira) |
84
84
  | `tasks` | `oats.linear` | `LINEAR_API_KEY` in the environment (never in OATS config); `team` (and optionally `project`) in the soul's `tasks:` payload or `settings.oats.linear` | [awebai/oats-linear](https://github.com/awebai/oats-linear) |
85
85
 
86
86
  - **`oats.okf`** consults the soul's external OKF bases, keeps instance
87
- knowledge, and, where the host switches harvest on, hands each instance's
88
- notes and session to the `knowledge-harvester` package soul; the
89
- `knowledge-maintainer` package soul reviews the resulting PRs.
87
+ knowledge, and briefs eligible working instances to propose durable claims
88
+ at checkpoints by directly spawning `oats.okf/knowledge-harvester`. The
89
+ soul-only `knowledge: { harvest: off }` forbids harvest while retaining
90
+ consultation. No host switch or automatic transcript/retire capture remains;
91
+ `knowledge-maintainer` reviews the resulting Git PRs.
90
92
  - **`oats.aweb`** mints a messaging identity for each instance at spawn and
91
93
  removes it at retire, contributes the aweb messaging skills, and wires the
92
94
  channel so sessions are woken by mail. Under `delivery: channel`, Claude Code