@awebai/oats 0.69.16 → 0.69.18

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 (53) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +7 -0
  4. package/docs/container.md +172 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/desktop-cli-api.md +73 -33
  7. package/docs/desktop.md +40 -18
  8. package/docs/execution-targets.md +36 -33
  9. package/docs/implementation.md +7 -6
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +7 -7
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +24 -19
  15. package/docs/release-notes/v0.69.17.md +49 -0
  16. package/docs/release-notes/v0.69.18.md +358 -0
  17. package/docs/servers.md +3 -1
  18. package/docs/souls-and-instances.md +18 -16
  19. package/docs/trust-model.md +119 -0
  20. package/docs/upgrading.md +46 -21
  21. package/docs/workspaces.md +3 -3
  22. package/lib/command-flags.mjs +1 -1
  23. package/lib/core.mjs +24 -9
  24. package/lib/errors.mjs +1 -1
  25. package/lib/home-owner.mjs +25 -0
  26. package/lib/host-run-admission.mjs +21 -0
  27. package/lib/host-run-child.mjs +31 -0
  28. package/lib/host-run-work.mjs +150 -0
  29. package/lib/host-run.mjs +20 -11
  30. package/lib/instance-naming.mjs +26 -44
  31. package/lib/packages.mjs +0 -43
  32. package/lib/pi-bridge.mjs +18 -6
  33. package/lib/schedule.mjs +5 -3
  34. package/lib/servers.mjs +4 -3
  35. package/lib/session-end.mjs +9 -0
  36. package/lib/session-resume.mjs +19 -9
  37. package/lib/session-seen.mjs +13 -8
  38. package/lib/triggers.mjs +3 -1
  39. package/lib/worktree.mjs +5 -2
  40. package/package-catalog.json +3 -3
  41. package/package.json +2 -2
  42. package/packages/client/above-tested-notice.mjs +30 -0
  43. package/packages/client/above-tested.mjs +225 -0
  44. package/packages/client/cli-locator.mjs +67 -52
  45. package/packages/client/deployment-label.mjs +4 -4
  46. package/packages/client/instance-name.mjs +5 -29
  47. package/packages/client/session-start.mjs +31 -3
  48. package/packages/client/workspace-choices.mjs +1 -1
  49. package/packages/client/workspace-views.mjs +1 -1
  50. package/packages/record/README.md +10 -8
  51. package/packages/record/lib/process-identity.mjs +14 -36
  52. package/packages/tui/lib/read.mjs +19 -3
  53. package/skills/oats-getting-started/SKILL.md +33 -4
package/docs/desktop.md CHANGED
@@ -86,9 +86,13 @@ the one with **this Desktop's own version** — the app's degradation card
86
86
  shows that exact `npm install -g @awebai/oats@<version>` command, and
87
87
  copying it from the card is the reliable route.
88
88
 
89
- Each Desktop accepts a band of released CLI versions around its own
90
- (prereleases never), and a feature may need a higher floor; the app states
91
- both, so this guide does not repeat the numbers. The contract is
89
+ Each Desktop accepts released CLI versions from a floor up (prereleases
90
+ never), and a feature may need a higher floor; the app states both, so this
91
+ guide does not repeat the numbers. A CLI newer than the Desktop's own minor
92
+ version is accepted with only reads, terminals, Spawn, Start, Restart, the
93
+ colour and the background on: one line in the card's place says that every
94
+ other change is off until you install the OATS Desktop of that CLI's version,
95
+ and links its release. A Desktop of 0.69.17 or older refuses such a CLI. The contract is
92
96
  [desktop-cli-api.md](desktop-cli-api.md). The app discovers the CLI automatically
93
97
  (your PATH, the npm global prefix, a login shell) and re-probes on launch,
94
98
  app focus, and Retry. Until a compatible CLI is verified, the Soul roster's
@@ -166,8 +170,9 @@ recently added workspaces there, once.
166
170
  opened, or your home directory when there is none (never ~/Downloads);
167
171
  **Choose oats…** opens in the directory of the chosen or discovered CLI.
168
172
 
169
- Launch flags for scripted use: `--dir <workspace>`, `--instance <name>` and
170
- `OATS_DESKTOP_PORT`.
173
+ Launch flags for scripted use: `--dir <workspace>` and `--instance <name>`.
174
+ The app always starts its own backend server, on a private socket (below); it
175
+ never uses a server it did not start.
171
176
 
172
177
  ### Opening on an instance
173
178
 
@@ -554,12 +559,11 @@ scroll down with the fields to read it.
554
559
 
555
560
  The dialog's last field before **Developer settings** is **Name · optional**.
556
561
  Left empty, the kernel numbers the new instance (`<soul>-<n>`). A name you type
557
- is used in lowercase and gets the soul's role, the last word of the soul's
558
- name, as its suffix:
559
- `desktop-improvements` for `oats-desktop-expert` becomes
560
- `desktop-improvements-expert`. A name that already ends in the role, or is
561
- the role, stays as typed. The line under the field shows the final name, and a
562
- name that is too long, invalid or already taken is explained there. A spawn
562
+ is used in lowercase, as typed: nothing is appended to it, and the soul is
563
+ shown beside the instance. What to name it is
564
+ [oats.core's naming rule](../oats-package/capabilities/oats-core/skills/oats-souls/SKILL.md#name-the-instance)
565
+ (oats-souls, "Name the instance"). The line under the field shows the name,
566
+ and a name that is too long, invalid or already taken is explained there. A spawn
563
567
  on a server takes the exact name the same way when that machine's OATS can
564
568
  take one (feature `spawn-name`, read from its last roster answer), and its
565
569
  name is explained there too when that machine refuses it. With an OATS older
@@ -571,8 +575,9 @@ instance is named `<soul>-<purpose>`, and the field shows that prefix.
571
575
  `spawn-suggest-name`), the help under an empty Name reads "Left empty, the
572
576
  instance is named from its task." Once the Opening instruction holds at
573
577
  least seven words, the Desktop asks OATS for a name as you type. The soul's
574
- own harness reads the instruction and replies with a short name for the work,
575
- and the role is added as its suffix. The name shows as the field's
578
+ own harness reads the instruction and replies with a short name: a few words
579
+ for the work, then the instance's role as the instruction gives it. The name
580
+ shows as the field's
576
581
  placeholder ("release-notes-manager"), on the line under the field ("(from
577
582
  the task)") and in **What will be created**. It belongs to the instruction it
578
583
  was made for: when you change the instruction it goes, and the Desktop asks
@@ -1112,9 +1117,24 @@ unknown or unreported harness shows "?". Sources and licences are in
1112
1117
 
1113
1118
  ## Security posture
1114
1119
 
1115
- - The bundled backend binds **127.0.0.1 only** and guards against DNS
1116
- rebinding (loopback Host on every request, loopback Origin on POSTs).
1117
- Do not expose it: it can type into your agent terminals.
1120
+ - The bundled backend listens on a **private socket only the app's main
1121
+ process can reach**: a Unix domain socket in a directory of its own, owned
1122
+ by you and closed to group and others (under `$XDG_RUNTIME_DIR` on Linux
1123
+ when it is private, else the system temporary directory). It opens no TCP
1124
+ port. The renderer reaches it only through main.
1125
+ - **Every request carries the per-launch credential** main hands its server
1126
+ over a private pipe when it starts it: 32 random bytes, fresh for each
1127
+ server, never on a command line, in an environment, a URL, a log or the
1128
+ renderer. A request without it is refused (401) before anything else
1129
+ happens, and no reply carries it: a reply that would (a file, a skill or
1130
+ a Git diff holding it) is refused (403) with no content. The Host guard (a loopback Host on every request) and the Origin
1131
+ guard (a loopback Origin on POSTs) stay. Main only ever talks to the
1132
+ server it started, and discards a reply from a server it has since
1133
+ replaced. Do not expose the socket: the server can type into your agent
1134
+ terminals.
1135
+ - **The CLI binary is chosen only through the app's own file dialog**
1136
+ (**Choose oats…**): main saves the pick, and the server reads it at each
1137
+ probe. No request to the server names a binary.
1118
1138
  - The app never imports framework code from a checkout and accepts no
1119
1139
  framework-root environment override; deployments are read with an
1120
1140
  app-owned read-only reader. Lifecycle actions run the installed `oats` CLI
@@ -1135,12 +1155,14 @@ unknown or unreported harness shows "?". Sources and licences are in
1135
1155
  | Symptom | Cause / fix |
1136
1156
  | --- | --- |
1137
1157
  | "Compatible oats CLI required" card | No CLI, or a version outside the range the card itself states. Copy the card's install command, or **Choose oats…** to point at the right binary; **Retry** re-probes. Spawn is disabled until a compatible CLI is verified. |
1138
- | "This Desktop is older than the installed oats CLI" card | The CLI found is a released version above the range this Desktop works with, usually because the CLI was updated first. Install OATS Desktop of the version the card names; the card offers no npm command, since installing the CLI this Desktop pins would downgrade it. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
1158
+ | "This Desktop was tested with oats CLIs up to …" line, and most changes off | The CLI is of a later minor or major version than this Desktop, usually because the CLI was updated first. Reads, terminals, Spawn, Start, Restart, the colour and the background keep working; every other change is off until you install OATS Desktop of the version the line names, from the release it links. There is no npm command, since installing the CLI this Desktop pins would downgrade it; **Choose oats…** points at another CLI and **Retry** re-probes. |
1159
+ | "This Desktop is older than the installed oats CLI" card | The CLI found speaks a newer desktop API than this Desktop. Install OATS Desktop of the version the card names; the card offers no npm command. Reads and terminals keep working meanwhile; **Choose oats…** points at another, compatible CLI and **Retry** re-probes. |
1139
1160
  | Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
1140
1161
  | 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). |
1141
1162
  | 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: scroll back first (wheel up, Shift+PgUp or Ctrl+B then `[`) for older output. In `oats session attach` in your own terminal, hold **Option** (iTerm2, Ghostty, Terminal.app) or **Shift** while dragging. |
1142
1163
  | 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. |
1143
- | 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. |
1164
+ | Log says `the backend server's socket path is N bytes, over the limit of 103` | The directory for the server's private socket is too deep for a Unix socket path. On Linux it is `$XDG_RUNTIME_DIR` when that is a private directory of yours, else `$TMPDIR` (on macOS always `$TMPDIR`). Start the app with that variable set to a shorter directory of your own, or on Linux with `XDG_RUNTIME_DIR` unset and a short `TMPDIR`. The app never falls back to a TCP port. |
1165
+ | A backend server of an earlier Desktop is still running | From 0.49.0 a server the app starts exits when the app ends, however it ends (quit, crash or kill), and the app never uses a server it did not start. A server left by a Desktop older than 0.49.0 (seen on Linux, where it outlived the app in its own `app-…scope`) is harmless to a newer app but may 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>`). |
1144
1166
  | Roster empty | The opened directory isn't an OATS deployment (it needs `oats-local.yaml` and `agents/`). Use **Add local workspace…** (the **+** at the top of the sidebar) to select the right folder. |
1145
1167
 
1146
1168
  For bugs, attach the terminal output of the app (`OATS Desktop` prints
@@ -1460,7 +1460,7 @@ refused. A home removed between the read and its start is reported
1460
1460
  skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1461
1461
  never retried automatically: it is also noted for the boot, and reported
1462
1462
  `refused-this-boot` should that answer be lost.
1463
- - A home is started by sweeps at most 3 times in a boot. A home lost again
1463
+ - A home lost unexpectedly is started by sweeps at most 3 times in a boot. A home lost again
1464
1464
  after each resume (a harness that crashes the host or its terminal server,
1465
1465
  say) is then reported `keeps-getting-lost`, and that loss is answered: no
1466
1466
  sweep starts it again, after a reboot either. Start it by hand: its next
@@ -1469,41 +1469,44 @@ refused. A home removed between the read and its start is reported
1469
1469
  has answered, so a sweep killed while other starts run has counted it; a
1470
1470
  refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1471
1471
  bounded nor counted.
1472
+ A stop of the current start with the host is different: a successful
1473
+ restore after that administrative stop neither spends nor resets the
1474
+ crash budget, and the crash ceiling cannot prevent it. A failed or
1475
+ blocked restore keeps its failure accounting; prior refusals and loss
1476
+ eligibility checks still apply. A stop receipt from an earlier start
1477
+ cannot grant this exception.
1478
+ For a validated current-start host stop, the in-boot gap is measured
1479
+ from the last running observation to the stop receipt's time, excluding
1480
+ container downtime. A running observation during the stop's grace period
1481
+ may be later than the receipt; that gap is zero and the receipt remains
1482
+ valid. Thus a clean stop lasting more than 24 hours can
1483
+ still resume. The first-observed-loss age limit and prior judgement
1484
+ still apply; unknown, pre-start, future and other-start receipts relax
1485
+ none of these guards.
1472
1486
  - The boot is the boot time on macOS and the kernel's boot id
1473
1487
  (`/proc/sys/kernel/random/boot_id`) on Linux. Elsewhere there
1474
1488
  is no boot: nothing is noted or counted, and every sweep tries again.
1475
- - **Inside a container a boot is one run of the container.** A container
1476
- shares its host's kernel, so the kernel's boot id stays the same when the
1477
- container is stopped and started, restarted or made again, while every
1478
- process in it, its terminal server and its sessions included, is gone. The
1479
- boot there is the kernel's boot id together with the start time of the
1480
- container's PID 1 (field 22 of `/proc/1/stat`, clock ticks after the
1481
- kernel's boot): PID 1 starts once per run and its end ends the run, so the
1482
- identity is the same for every `oats` process of one run and another one
1483
- in the next, and the boot id keeps it apart from a run after the host's
1484
- restart. Each run has its own count of 3 starts per home, takes over a lock
1485
- the run before left, and clause 4 does not reach from one run into the
1486
- next. Both values are read without privileges and nothing is written for
1487
- them.
1488
- - OATS takes itself to be in a container when one of these is there: the
1489
- file `/.dockerenv` (Docker), the file `/run/.containerenv` (Podman), or
1490
- the environment variable `KUBERNETES_SERVICE_HOST` (every Kubernetes
1491
- pod). A container runtime that sets none of them is read as a host: give
1492
- its containers `KUBERNETES_SERVICE_HOST` or one of the files.
1493
- - Without one of them PID 1's start is not read. A command that a harness
1494
- runs in a sandbox with a PID namespace of its own (bubblewrap's
1495
- `--unshare-pid`) has that sandbox's PID 1, and is on the host's boot all
1496
- the same.
1497
- - When PID 1's start cannot be read in a container (a `/proc` mounted with
1498
- `hidepid`, say) the boot is the boot id alone. Every run on one host boot
1499
- is then the same boot: the count runs across them and clause 4 applies
1500
- across them, so a sweep starts fewer homes, never more.
1501
- - A container that shares its host's PID namespace (`--pid=host`), and a
1502
- Kubernetes pod with `shareProcessNamespace: true`, read a PID 1 that
1503
- outlives the container, so their boot is the same in every run.
1504
- - Inside a container, a command run in a sandbox with a PID namespace of
1505
- its own reads the sandbox's PID 1 and records a boot of its own. Run the
1506
- sweep outside such a sandbox there.
1489
+ - **Containers and PID sandboxes share their host kernel's boot.** No
1490
+ environment variable, marker file or PID 1 lookup changes that identity.
1491
+ An SSH command and the entrypoint in the same PID namespace therefore
1492
+ agree on the boot and holder identity. An unmarked bubblewrap PID
1493
+ namespace keeps the host's boot string. Holder liveness still requires
1494
+ that the reader can see the holder's pid; equal boot strings do not
1495
+ provide cross-PID-namespace process visibility or pid translation.
1496
+ - A lock left by an earlier container run is reclaimed when its recorded
1497
+ pid is gone or has another process start time. A live holder is never
1498
+ reclaimed; an unreadable or missing start stays unknown and held.
1499
+ - Old Linux boot IDs of the form `<kernel UUID>:<PID 1 start>` compare as
1500
+ that kernel UUID. Across an upgrade, a qualifier alone cannot make a
1501
+ live holder another boot. This comparison is read-only; it never edits
1502
+ the holder's record. Run one OATS version per machine: an already
1503
+ running older binary still applies its older comparison.
1504
+ - Failure counts, prior refusals and clause 4 carry across container
1505
+ restarts on the same kernel, including when read from older qualified
1506
+ records. A kernel reboot gives a fresh budget. Loss judgements remain
1507
+ per start, and a running look of a newly resumed start resets its prior
1508
+ seen/lost judgement. Every new `oats host run` invokes the sweep;
1509
+ successful restores after a host stop remain eligible as described above.
1507
1510
  - The lock, the per-boot note and the record of what status saw live in
1508
1511
  `session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
1509
1512
  are kernel-private, not a contract.
@@ -17,9 +17,10 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
17
17
  [tui.md](tui.md)), and the directory of readers the terminal client shares
18
18
  with the Desktop (`packages/client/`, below), which has no dependency
19
19
  either. None of their tests is packed. The package's
20
- manifest declares three runtime dependencies: `yaml` (the kernel reads and
21
- writes the configuration files with it), `croner` (schedule expressions) and
22
- `@awebai/pi` (pi's aweb messaging extension). The terminal client adds none
20
+ manifest declares two runtime dependencies: `yaml` (the kernel reads and
21
+ writes the configuration files with it) and `croner` (schedule expressions).
22
+ The pi SDK is a development dependency for adapter tests; pi's aweb
23
+ messaging extension is installed by its capability. The terminal client adds none
23
24
  and may never add one: with a dependency it could no longer ship in this
24
25
  tarball.
25
26
  - **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
@@ -119,7 +120,7 @@ and the rules its tests pin.
119
120
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
120
121
  | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
121
122
  | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul`, `inspect --soul --instructions` and `--composed-skills` (its `inScratch` reads the scratch home before it is removed, so the two flags share one materialization) |
122
- | `instance-naming.mjs` | the suggested instance name of `spawn --suggest-name` (a preview's or an apply's) and of `oats instance suggest-name`: the prompt, the soul's role (`soulRole`, the clients' rule), the name built from a reply, each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself. Two drivers in `core.mjs`, both reusing it unchanged: `spawnBody`, after the spawn's harness checks, where a suggested name is then placed as `--name` would place it (a preview's call within its preflight budget, an apply's within its own 20 s); and `suggestSpawnName`, for a spawn elsewhere, which resolves the launch configuration and executable the way a spawn here would but places nothing and passes a `taken` that is always false. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
123
+ | `instance-naming.mjs` | the suggested instance name of `spawn --suggest-name` (a preview's or an apply's) and of `oats instance suggest-name`: the prompt, the name in a reply (`nameFromReply`: the model's whole `<work>-<role>`, the last word the role, always kept; nothing reads the soul's name), each harness's proven naming call (`NAMING_CALLS`) and the isolated call itself. Two drivers in `core.mjs`, both reusing it unchanged: `spawnBody`, after the spawn's harness checks, where a suggested name is then placed as `--name` would place it (a preview's call within its preflight budget, an apply's within its own 20 s); and `suggestSpawnName`, for a spawn elsewhere, which resolves the launch configuration and executable the way a spawn here would but places nothing and passes a `taken` that is always false. The test seam `OATS_TEST_NAMING_TIMEOUT_MS` shortens the call's 20 s limit |
123
124
  | `doctor-capture.mjs` | one fixed bounded package health child for deployment doctor, excluded from `--soul`; package-owned envelope validation and existing warning-row mapping. No kernel status/DB/freshness parser. Command failures become `capture-health-unavailable`; see [the package boundary](../packages/record/docs/capture-service.md#kernel-doctor-delegation) |
124
125
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
125
126
  | `local-edit.mjs` | the one way a verb rewrites `oats-local.yaml` in place (`editLocal`): the file as it is now, the deployment's local lock, compare-and-swap, the local schema and the caller's check before the rename, and the permission bits of the file it replaces on the new one (a link at that path is replaced by a regular file with its target's bits, and the target is not written). Every kernel command that rewrites that file writes through it (`grep editLocal` lists them; this row does not), and a new writer does too, so that no two drop each other's change. An edit changes the parsed document, which is then rendered, or returns the text to write when the command has a writer of its own for its block (`oats launch-config set\|remove`, whose write leaves every byte outside `launch-configs` as it was) |
@@ -131,7 +132,7 @@ and the rules its tests pin.
131
132
  | `stable-node.mjs` | the one rule for a node path written into anything that outlives the process: the host timer's unit and `OATS_NODE_BIN` ([capabilities](capabilities.md#the-node-a-hook-writes-down)). It imports nothing of the kernel |
132
133
  | `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
133
134
  | `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
134
- | `host-run.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep once and the tick and the listing each minute, every one an `oats` child (`session-resume.mjs` `kernelAnswer`) so that the loop stays free for the signal, and the stop on SIGTERM: ticking ends, then each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
135
+ | `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep once and the tick and the listing each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
135
136
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
136
137
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
137
138
  | `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 |
@@ -169,7 +170,7 @@ and the rules its tests pin.
169
170
  | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches; the table of the variable that moves each harness's folder (`HARNESS_FOLDER_VAR`) and the one reader of a launch configuration's (`launchConfigFolder`), used by the trust code, `pi-bridge.mjs` and `core.mjs`: it reads only files and imports none of them. What a launch's pane will have for those variables, `PATH` and `HOME` is `launchEnvironment` in `core.mjs`, the one answer every check of a launch reads ([execution-targets.md](execution-targets.md#the-checks-read-the-pane)); it carries the names the launch removes (`removedLaunchEnv`: declared by its capabilities, not in their payload), which `launchEffectiveEnv` leaves out and the window command (`paneCommand`) unsets ([capabilities.md](capabilities.md#a-declared-name-is-the-providers)) |
170
171
  | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
171
172
  | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
172
- | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line that the Desktop goes first ([upgrading](upgrading.md)). Reads only: `bin/oats.mjs` runs the steps |
173
+ | `pi-bridge.mjs` | the pi bridge (`@awebai/oats-pi`) in every pi folder a launch of a deployment uses: the folder list (the default, the process's own `PI_CODING_AGENT_DIR`, each pi launch configuration's, by real path), the bridge read in each, `oats doctor`'s skew warnings, and the plan `oats update` runs with its line on what an older Desktop holds back, whose core is the Desktop's own notice (`test/above-tested-wording.test.mjs`; [upgrading](upgrading.md#either-order-works)). Reads only: `bin/oats.mjs` runs the steps |
173
174
 
174
175
  An upgrade records a hook's in-flight marker before spawning it. A resumed
175
176
  unknown outcome is durably recorded as uncertain before any retry work,
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v6.0.1
44
- oats.aweb: v1.39.0
43
+ oats.okf: v6.0.3
44
+ oats.aweb: v1.41.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 6.0.1** (OATS **>=0.69.2**). Provider implementation and
9
+ This is the operator guide for **oats.okf 6.0.3** (OATS **>=0.69.2**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
  In 6.0 there is no knowledge harvester: a working instance proposes its own
12
12
  knowledge as a pull request at its checkpoints (`oats okf propose`), and the
@@ -28,7 +28,7 @@ knowledge maintainer gates every merge.
28
28
  ```yaml
29
29
  # oats-workspace.yaml (excerpt)
30
30
  packages:
31
- oats.okf: v6.0.1
31
+ oats.okf: v6.0.3
32
32
  defaults:
33
33
  knowledge: { oats.okf: { from: package } }
34
34
  stores:
@@ -56,9 +56,9 @@ Upgrading from 4.x requires the ordered
56
56
  just editing a version line. The package requires OATS >=0.69.2: its
57
57
  `knowledge-maintainer` soul says `background: true`, which an older kernel
58
58
  refuses. Upgrade OATS first, then the package. Each 5.x step is in
59
- [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.1/CHANGELOG.md).
59
+ [oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.3/CHANGELOG.md).
60
60
 
61
- **Upgrade to 6.0:** pin `oats.okf: v6.0.1` and run `oats sync`. Only new
61
+ **Upgrade to 6.0:** pin `oats.okf: v6.0.3` and run `oats sync`. Only new
62
62
  spawns get `oats okf propose`, the 6.0 `okf-propose` skill and the
63
63
  spawn-recorded duty. Existing homes keep their copied provider even after a
64
64
  session restart; a stopped 5.x home can move with `oats instance upgrade`
@@ -67,7 +67,7 @@ remedy to retire and respawn it. Harvester spawns stop: the stub soul
67
67
  `oats.okf/knowledge-harvester`, kept until 7.0, refuses every spawn with
68
68
  `E_REMOVED` and the fix. Harvesters already running keep their 5.x modules
69
69
  and finish, or a person retires them. Then, by hand, from the deployment
70
- (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.1/README.md#upgrading-to-60)
70
+ (oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.3/README.md#upgrading-to-60)
71
71
  has each step's commands):
72
72
 
73
73
  1. Delete the harvester's launch preference, if any:
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.24.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
- | `oats.okf` | `v6.0.1` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.39.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
12
+ | `oats.framework` | `oats-framework/v1.25.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
13
+ | `oats.okf` | `v6.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
+ | `oats.aweb` | `v1.41.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
15
  | `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
@@ -49,9 +49,9 @@ release it came from in its description, and the copy records it as a whole in
49
49
 
50
50
  | Template | Latest release | Way of working |
51
51
  | --- | --- | --- |
52
- | `oats-project/oats-engineering-coordination` | `template-v3.0.1` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
53
- | `oats-project/oats-research-coordination` | `template-v2.0.0` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
54
- | `oats-project/oats-scientific-research-coordination` | `template-v2.0.0` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
52
+ | `oats-project/oats-engineering-coordination` | `template-v3.1.3` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
53
+ | `oats-project/oats-research-coordination` | `template-v2.1.2` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
54
+ | `oats-project/oats-scientific-research-coordination` | `template-v2.1.2` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
55
55
 
56
56
  The package `oats.engineering` is frozen at `v1.18.0`. Its entry and its four
57
57
  aliases stay, so existing pins keep resolving, and its repository,
@@ -64,7 +64,7 @@ aliases, a later decision once no workspace we know of pins it.
64
64
  ## Find and use packages
65
65
 
66
66
  - A workspace pins an official package by **bare version** in its
67
- `packages:` map (`oats.okf: v6.0.1`); `oats sync` resolves it through the
67
+ `packages:` map (`oats.okf: v6.0.3`); `oats sync` resolves it through the
68
68
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
69
69
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
70
70
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -48,14 +48,14 @@ whole organisation:
48
48
 
49
49
  ```yaml
50
50
  packages:
51
- oats.okf: v6.0.1 # bare version → the official catalog
51
+ oats.okf: v6.0.3 # bare version → the official catalog
52
52
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
53
53
  ```
54
54
 
55
55
  - **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
56
56
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
57
57
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
58
- convention (`v5.8.0` or `oats-framework/v1.24.0`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.25.0`) and the payload path. An id
59
59
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
60
60
  a package outside the catalog"). The catalog is the reviewed official list
61
61
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -78,9 +78,9 @@ members:
78
78
  - git:github.com/acme/agents
79
79
  - git:github.com/acme/platform
80
80
  packages:
81
- oats.framework: v1.24.0
82
- oats.okf: v6.0.1
83
- oats.aweb: v1.39.0
81
+ oats.framework: v1.25.0
82
+ oats.okf: v6.0.3
83
+ oats.aweb: v1.41.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -109,7 +109,7 @@ decision recorded in the lock.
109
109
  $ oats sync
110
110
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
111
111
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
112
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.0.1 ✓ (@ 95449a66)
112
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.0.3 ✓ (@ fa13ca0b)
113
113
  changed acme.tools — → 0.4.0 (@ 47f4b816)
114
114
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
115
115
  teams platform (shared) · this deployment's: oats teams
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
155
155
  ## `oats package add | remove`
156
156
 
157
157
  ```bash
158
- oats package add oats.aweb v1.39.0 # a catalog version
158
+ oats package add oats.aweb v1.41.0 # a catalog version
159
159
  oats package add acme.tools git:github.com/acme/tools@v0.4.0
160
160
  oats package remove acme.tools
161
161
  ```
@@ -181,8 +181,8 @@ same workspace commit hold identical locks.
181
181
  "source": "catalog:oats.okf",
182
182
  "url": "https://github.com/awebai/oats-okf.git",
183
183
  "path": "oats-package",
184
- "version": "6.0.1",
185
- "commit": "95449a665146f36fbaecddeea413c9421d109912",
184
+ "version": "6.0.3",
185
+ "commit": "fa13ca0b026995fe5a278f7fb922ecd4eb09d6a9",
186
186
  "integrity": "sha256-…",
187
187
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
188
188
  },
@@ -431,12 +431,12 @@ A soul that names one of the package's capabilities with
431
431
  {
432
432
  "policy": "docs/official-catalog.md",
433
433
  "packages": {
434
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0.1", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.24.0", "path": "oats-package" }
434
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0.3", "path": "oats-package" },
435
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.25.0", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.24.0`
441
- resolves to tag `oats-framework/v1.24.0`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.25.0`
441
+ resolves to tag `oats-framework/v1.25.0`. Resolving through the catalog never
442
442
  advances a lock by itself: `oats sync` does, and says so.
@@ -132,13 +132,18 @@ Everything after `build` reads `MANIFEST.json` and the files already staged:
132
132
  so no checks run on it by themselves; close and reopen it to run them, and
133
133
  do not read missing checks as green. Open the PR by hand if the workflow
134
134
  does not run.
135
- - **The accepted range also decides which kernel `oats tui` accepts.**
136
- `ACCEPT_RANGE` (`packages/client/cli-locator.mjs`) is read by the Desktop
137
- and by the terminal client, which runs the kernel it ships with: a bump
138
- that leaves the new version outside the range ships an `oats tui` that
139
- stops at its start with `E_TUI_KERNEL`. The test "the accepted band admits
140
- the kernel version this Desktop ships with"
141
- (`packages/desktop/test/cli-locator.test.mjs`) fails for such a bump.
135
+ - **No bump moves an accepted range.** The Desktop's tested bound is the
136
+ minor of its own version (`packages/desktop/package.json`), read at run
137
+ time (`testedBound`, `packages/client/cli-locator.mjs`); `ACCEPT_RANGE`
138
+ holds only the floor. A newer CLI is accepted with only the operations
139
+ `packages/client/above-tested.mjs` allows on. `oats tui` judges the kernel
140
+ it ships with against that kernel's own `package.json`, so it never finds
141
+ it above. The version-bump PR moves the two manifests together; should they
142
+ differ, the Desktop's own wins (it is the installed app's version), and
143
+ `checkReleaseVersions` refuses the checkout. The test "the tested bound is
144
+ the minor of the version the release manifests carry, from one source, and
145
+ no file spells an upper bound" (`test/release-packaging.test.mjs`) holds
146
+ this.
142
147
  - **Legs for hosts you do not have.** The Linux AppImage/DEB need a Linux
143
148
  host; the lane says so and `stage` lists what is missing.
144
149
  - **The packaged window launch.** `release.yml` launches the packaged window
@@ -355,29 +360,29 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
355
360
  entries merged since, which go after the earlier ones.
356
361
  - **The Upgrade section opens with the order of the Desktop and the CLI.**
357
362
  The tag owner writes it in the release-prep pull request, for every
358
- release, from `ACCEPT_RANGE` in `packages/client/cli-locator.mjs`:
359
- - when the release moves the range's upper bound (a new minor), the first
360
- Upgrade line says to install the Desktop first and the CLI second,
361
- because the previous Desktop refuses this CLI ([Upgrading](upgrading.md));
362
- - when the range already admits the new version (a patch), it says that
363
- either order works.
363
+ release: either order works ([Upgrading](upgrading.md#either-order-works)).
364
+ For a new minor or major it adds what the previous Desktop holds back with
365
+ this CLI until it is updated, and that a Desktop of 0.69.17 or older
366
+ (`LAST_HARD_CEILING_DESKTOP`, `lib/pi-bridge.mjs`) refuses it: install the
367
+ Desktop first there.
364
368
 
365
369
  No entry file writes this line: only the tag owner knows the release's
366
370
  version when the notes are assembled.
367
371
  - **The same pull request updates "Upgrading to the latest version"**, the
368
372
  section [Upgrading](upgrading.md) opens with: the version being tagged in
369
373
  each place the section names it (the latest version, its notes, the
370
- Desktop and the CLI install), and the CLIs that version's Desktop accepts,
371
- up to its next minor (`ACCEPT_RANGE` in `packages/client/cli-locator.mjs`
372
- once the release plan has moved it). The page
373
- states only this band; the earlier ones stay in their notes. When the
374
+ Desktop and the CLI install), and the CLIs that version's Desktop accepts:
375
+ up to 0.69.17, its band (`>=0.26.0 <0.70.0`); after it, `The <version>
376
+ Desktop accepts OATS CLIs \`>=<floor>\`, tested through <X.Y>`, with the
377
+ Desktop and the CLI `in either order`. The page
378
+ states only this version's; the earlier ones stay in their notes. When the
374
379
  release's Upgrade section asks for more than the page's steps, the order
375
380
  of the Desktop and the CLI and an optional package pin, the pull request
376
381
  also adds the release's entry at the top of "Coming from an older
377
382
  version", one line that links its notes.
378
383
  `test/release-packaging.test.mjs` checks that the section names the
379
- version the manifests carry and no other, and that the page's only band
380
- is that version's Desktop's. The oats.setup skill `oats-upgrade` reads
384
+ version the manifests carry and no other, and states that version's
385
+ Desktop's accepted CLIs in the form above. The oats.setup skill `oats-upgrade` reads
381
386
  this page at the release's tag, so what the tag carries is what an upgrade
382
387
  follows.
383
388
  - **A tag is refused while anything is under `docs/release-notes/next/`:** by
@@ -0,0 +1,49 @@
1
+ # OATS 0.69.17
2
+
3
+ 0.69.17 moves OATS's two coordination souls, `oats-engineering-expert` and
4
+ `oats-product-expert`, onto knowledge subjects (`okf.json` version 2). The
5
+ official catalog pins oats.okf 6.0.2 and oats.framework 1.24.1; oats.aweb
6
+ stays at 1.39.0.
7
+
8
+ ## Upgrade
9
+
10
+ - **Either order of the Desktop and the CLI works.**
11
+ [Upgrading](../upgrading.md) installs the Desktop first, and a host that
12
+ installed the CLI first is fine too: the 0.69.17 Desktop accepts OATS CLIs
13
+ `>=0.26.0 <0.70.0`, as the 0.69.16 Desktop does.
14
+ - **Package pins:** oats.okf 6.0.2 (from 6.0.1) and oats.framework 1.24.1
15
+ (from 1.24.0). Neither asks for a hand step: `oats sync` takes them. A
16
+ deployment that keeps its own pins changes nothing until it moves them.
17
+ - **Respawn an instance of `oats-engineering-expert` or `oats-product-expert`
18
+ once** after `oats sync`. An instance keeps the `okf.json` its spawn
19
+ recorded, so one started before this release still reads and proposes to
20
+ its old node; a new spawn reads the soul's subjects. The soul needs a
21
+ knowledge base bound with the subject layout: on a base that is not
22
+ bridged, its spawn refuses with `E_CONFIG` naming the base
23
+ ([okf.json version 2](../knowledge.md#the-souls-okfjson)).
24
+
25
+ ## Changed
26
+
27
+ - **`oats.framework` 1.24.1: `oats.setup` 2.15.1's `/oats-onboarding` names
28
+ `oats.okf` 6.0.2**, the release the catalog pins, in its knowledge card and
29
+ its workspace example. Nothing else changes, and no capability needs a
30
+ newer OATS.
31
+
32
+ - **The official catalog pins oats.okf 6.0.2** (from 6.0.1), and OATS's own
33
+ workspace takes it. A claim merged into a bridged base without the
34
+ maintainer's id stamp no longer stops version-2 spawns: readers warn
35
+ `W_ID_MISSING`, `oats okf bases` shows it, and writers and strict checks
36
+ still refuse. The generated mirror under `mirrors/oats-okf*` is finalized
37
+ from the v6.0.2 tag
38
+ ([oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0.2/CHANGELOG.md)).
39
+
40
+ - **`oats-engineering-expert` and `oats-product-expert` read by subject**
41
+ (`okf.json` version 2). The engineering expert's subjects are
42
+ `system/oats-kernel`, `system/oats-desktop`,
43
+ `workstream/provider-integration`, `workstream/operations` and
44
+ `workstream/coordination`; the product expert's are
45
+ `workstream/oats-direction` and `workstream/positioning`. Their spawn brief
46
+ lists those subjects, and their texts say each proposed claim names the
47
+ subjects it is about. Every other soul keeps its version-1 `okf.json`.
48
+ - **`oats.workspace-experts` 1.3.1:** its table of surfaces names, beside each
49
+ knowledge node, the subject that absorbs it ("Knowledge it reads").