@awebai/oats 0.69.17 → 0.69.19

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 (61) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +8 -1
  4. package/docs/container.md +345 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  7. package/docs/design/2026-09-28-automations-trust.md +1 -1
  8. package/docs/desktop-cli-api.md +100 -53
  9. package/docs/desktop.md +53 -24
  10. package/docs/execution-targets.md +66 -48
  11. package/docs/implementation.md +8 -7
  12. package/docs/integrations.md +2 -2
  13. package/docs/knowledge.md +5 -5
  14. package/docs/official-catalog.md +7 -7
  15. package/docs/packages.md +13 -13
  16. package/docs/release-lane.md +30 -23
  17. package/docs/release-notes/v0.69.18.md +358 -0
  18. package/docs/release-notes/v0.69.19.md +172 -0
  19. package/docs/servers.md +5 -3
  20. package/docs/souls-and-instances.md +51 -27
  21. package/docs/trust-model.md +119 -0
  22. package/docs/tui.md +8 -8
  23. package/docs/upgrading.md +45 -19
  24. package/docs/workspaces.md +3 -3
  25. package/injects/work-directory.md +27 -2
  26. package/injects/work-workspace.md +32 -6
  27. package/lib/command-flags.mjs +1 -1
  28. package/lib/core.mjs +26 -11
  29. package/lib/errors.mjs +1 -1
  30. package/lib/home-owner.mjs +25 -0
  31. package/lib/host-run-admission.mjs +21 -0
  32. package/lib/host-run-child.mjs +31 -0
  33. package/lib/host-run-work.mjs +150 -0
  34. package/lib/host-run.mjs +43 -29
  35. package/lib/instance-naming.mjs +26 -44
  36. package/lib/packages.mjs +0 -43
  37. package/lib/pi-bridge.mjs +18 -6
  38. package/lib/schedule.mjs +5 -3
  39. package/lib/servers.mjs +4 -3
  40. package/lib/session-end.mjs +9 -0
  41. package/lib/session-resume-contract.mjs +1 -1
  42. package/lib/session-resume.mjs +144 -51
  43. package/lib/session-seen.mjs +16 -11
  44. package/lib/triggers.mjs +3 -1
  45. package/lib/worktree.mjs +5 -2
  46. package/package-catalog.json +3 -3
  47. package/package.json +4 -2
  48. package/packages/client/above-tested-notice.mjs +30 -0
  49. package/packages/client/above-tested.mjs +225 -0
  50. package/packages/client/cli-locator.mjs +67 -52
  51. package/packages/client/deployment-label.mjs +4 -4
  52. package/packages/client/instance-name.mjs +5 -29
  53. package/packages/client/instance-presentation.mjs +2 -2
  54. package/packages/client/instance-tree.mjs +18 -7
  55. package/packages/client/session-start.mjs +31 -3
  56. package/packages/client/workspace-choices.mjs +1 -1
  57. package/packages/client/workspace-views.mjs +1 -1
  58. package/packages/record/README.md +10 -8
  59. package/packages/record/lib/process-identity.mjs +14 -36
  60. package/packages/tui/lib/read.mjs +19 -3
  61. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -1350,7 +1350,9 @@ The sweep resumes a lost home only when OATS can vouch for the loss, from
1350
1350
  what its own reads of that home saw (`oats status`, OATS Desktop and `oats
1351
1351
  tui` reading it, and the sweep's own read). All four must hold:
1352
1352
 
1353
- 1. OATS saw the home running for its current start.
1353
+ 1. OATS saw the home running for its current start. A start the sweep itself
1354
+ made counts as seen, so a home that is lost again before any read saw it
1355
+ running is still started again, within the hour's count below.
1354
1356
  2. No earlier sweep answered this loss. A sweep answers each lost home once,
1355
1357
  whatever it did with it (resumed, started fresh, blocked, refused or
1356
1358
  skipped), except a home it skipped because OATS was stopping, upgrading
@@ -1454,56 +1456,72 @@ refused. A home removed between the read and its start is reported
1454
1456
  `resume-lock-stuck` problem, with the path and what to do. It reads the
1455
1457
  lock and takes nothing. A free lock, a sweep that runs and a lock a gone
1456
1458
  sweep left are not reported.
1457
- - A loss is answered once: whatever a sweep did with it (resumed, refused,
1458
- skipped or blocked), no later sweep starts it again, in this boot or after
1459
- a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
1460
- skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1461
- never retried automatically: it is also noted for the boot, and reported
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
1464
- after each resume (a harness that crashes the host or its terminal server,
1465
- say) is then reported `keeps-getting-lost`, and that loss is answered: no
1466
- sweep starts it again, after a reboot either. Start it by hand: its next
1467
- loss is a new one, with a new count in each boot. Every sweep start that launched
1468
- something counts (resumed, fresh or blocked), by home, as soon as that start
1469
- has answered, so a sweep killed while other starts run has counted it; a
1470
- refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1471
- bounded nor counted.
1459
+ - A loss a sweep started is answered once: whether that start resumed, came
1460
+ up fresh or is blocked, no later sweep starts it again, in this boot or
1461
+ after a reboot; a later sweep reports it `not-seen-recently`. A
1462
+ `lifecycle-busy` skip answers nothing: the next sweep reads the home again.
1463
+ - A refused start answers nothing either. It launched nothing, and what
1464
+ refused it (a launch variable not set, no wake broker yet) is how the host
1465
+ was at that moment. The sweep notes it and tries that home again no sooner
1466
+ than 1 minute later, then 2, 4 and 8, and every 15 minutes after that; a
1467
+ sweep that runs before then reports it `start-refused-retrying`, with the
1468
+ refusal's code and the time of the next attempt, and starts nothing. The
1469
+ retries end when the loss is 24 hours old (`not-seen-recently`).
1470
+ - A home lost unexpectedly is started by sweeps at most 3 times in an hour. A
1471
+ home lost again after each resume (a harness that crashes the host or its
1472
+ terminal server, say) is then reported `keeps-getting-lost`, with the time
1473
+ the oldest of those starts is an hour old: a sweep starts the home again
1474
+ then. Every sweep start that launched something counts (resumed, fresh or
1475
+ blocked), by home, as soon as that start has answered, so a sweep killed
1476
+ while other starts run has counted it; a refused, skipped or busy one does
1477
+ not. The count and the retry delays are kept for one boot: a reboot starts
1478
+ both again. `oats session start --resume` run by hand is neither bounded
1479
+ nor counted.
1480
+ - That does not go on for ever. A home that uses up its 3 starts in 3 hours
1481
+ in a row is given up: its row has no time of a next attempt, the loss is
1482
+ answered, and no sweep starts it again until a person does. Hours are in a
1483
+ row when each begins less than an hour after the one before it cleared.
1484
+ Only an hour without one begins the count again: no start does. A person
1485
+ may start a home that was given up, and if it is lost again in a used-up
1486
+ hour it is given up again at once.
1487
+ A stop of the current start with the host is different: a successful
1488
+ restore after that administrative stop neither spends nor resets the
1489
+ crash budget, and the crash ceiling cannot prevent it. A failed or
1490
+ blocked restore keeps its failure accounting; prior refusals and loss
1491
+ eligibility checks still apply. A stop receipt from an earlier start
1492
+ cannot grant this exception.
1493
+ For a validated current-start host stop, the in-boot gap is measured
1494
+ from the last running observation to the stop receipt's time, excluding
1495
+ container downtime. A running observation during the stop's grace period
1496
+ may be later than the receipt; that gap is zero and the receipt remains
1497
+ valid. Thus a clean stop lasting more than 24 hours can
1498
+ still resume. The first-observed-loss age limit and prior judgement
1499
+ still apply; unknown, pre-start, future and other-start receipts relax
1500
+ none of these guards.
1472
1501
  - The boot is the boot time on macOS and the kernel's boot id
1473
1502
  (`/proc/sys/kernel/random/boot_id`) on Linux. Elsewhere there
1474
1503
  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.
1504
+ - **Containers and PID sandboxes share their host kernel's boot.** No
1505
+ environment variable, marker file or PID 1 lookup changes that identity.
1506
+ An SSH command and the entrypoint in the same PID namespace therefore
1507
+ agree on the boot and holder identity. An unmarked bubblewrap PID
1508
+ namespace keeps the host's boot string. Holder liveness still requires
1509
+ that the reader can see the holder's pid; equal boot strings do not
1510
+ provide cross-PID-namespace process visibility or pid translation.
1511
+ - A lock left by an earlier container run is reclaimed when its recorded
1512
+ pid is gone or has another process start time. A live holder is never
1513
+ reclaimed; an unreadable or missing start stays unknown and held.
1514
+ - Old Linux boot IDs of the form `<kernel UUID>:<PID 1 start>` compare as
1515
+ that kernel UUID. Across an upgrade, a qualifier alone cannot make a
1516
+ live holder another boot. This comparison is read-only; it never edits
1517
+ the holder's record. Run one OATS version per machine: an already
1518
+ running older binary still applies its older comparison.
1519
+ - Failure counts, prior refusals and clause 4 carry across container
1520
+ restarts on the same kernel, including when read from older qualified
1521
+ records. A kernel reboot gives a fresh budget. Loss judgements remain
1522
+ per start, and a running look of a newly resumed start resets its prior
1523
+ seen/lost judgement. Every `oats host run` invokes the sweep at its start and each minute;
1524
+ successful restores after a host stop remain eligible as described above.
1507
1525
  - The lock, the per-boot note and the record of what status saw live in
1508
1526
  `session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
1509
1527
  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) |
@@ -127,11 +128,11 @@ and the rules its tests pin.
127
128
  | `shell-word.mjs` | `shellWord` and `shq`: one word of a command the kernel prints for a person to paste into a shell. It imports nothing, so `launch-preference.mjs` quotes by the rule `core.mjs` re-exports |
128
129
  | `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
129
130
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer; a job's slot (`acquireJobLock`, `releaseJobLock`) is taken by renaming a directory that already holds its record into place, and released by renaming it out before it is removed, so it is never there without its record; a slot whose record cannot be read (`unreadableSlot`, over `jobLockInfo`) marks only its job invalid in the tick, is released by `reconcile --clear`, and is doctor's `schedule-slot-unreadable` problem; a slot whose schedule is gone (`scheduleAbsence`: a local one not in `oats-schedules.json`; a workspace one not in the saved snapshot, its member read at a commit and no problem of it that could hide one; never refreshed there) is counted until reconcile --clear releases it with the job's attempt and state (`orphanSlot`, `reconcileOrphanSlot`), and is doctor's `schedule-slot-orphaned` problem, as is a workspace one absent that cannot be shown gone |
130
- | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: one producer, `listInstances`; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
131
+ | `session-end.mjs`, `session-resume.mjs`, `session-resume-contract.mjs`, `session-seen.mjs`, `start-env.mjs` | session resume (#1559): what every local listing saw of each home and the pure rule that decides which losses the sweep resumes (`session-seen.mjs`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
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 at the start, then the tick and the sweep 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.2
44
- oats.aweb: v1.39.0
43
+ oats.okf: v6.0.3
44
+ oats.aweb: v1.42.1
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.2** (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.2
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.2/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.2` 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.2/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.1` (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.2` | `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.2` (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.42.1` | `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.2`); `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.2 # 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.1`) and the payload path. An id
58
+ convention (`v5.8.0` or `oats-framework/v1.25.2`) 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.1
82
- oats.okf: v6.0.2
83
- oats.aweb: v1.39.0
81
+ oats.framework: v1.25.2
82
+ oats.okf: v6.0.3
83
+ oats.aweb: v1.42.1
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.2 ✓ (@ 5c3f684c)
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.42.1 # 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.2",
185
- "commit": "5c3f684c35b2ea9eeec5cdca915b6d845273fb4d",
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.2", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.24.1", "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.2", "path": "oats-package" }
436
436
  }
437
437
  }
438
438
  ```
439
439
 
440
- `ref` carries the tag convention: a workspace's `oats.framework: v1.24.1`
441
- resolves to tag `oats-framework/v1.24.1`. Resolving through the catalog never
440
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.25.2`
441
+ resolves to tag `oats-framework/v1.25.2`. 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
@@ -175,21 +180,23 @@ runs the same installer steps, so it names the same commits. So does
175
180
  lane's call of 2026-10-27: it runs a branch's code on the release's own
176
181
  actions, and its run is that pull request's macOS evidence, so it names them
177
182
  at the commits that were read
178
- ([Implementation](implementation.md#the-tuis-tests-on-macos)). Every other
183
+ ([Implementation](implementation.md#the-tuis-tests-on-macos)).
184
+ `team-image.yml` also names these commits for
185
+ [image acceptance](container.md#image-ci-and-publication). Every other
179
186
  workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
180
187
 
181
188
  `test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
182
- were read has a row for each action: `action`, `id`, `version`. In the three
189
+ were read has a row for each action: `action`, `id`, `version`. In these four
183
190
  files every `uses:` is a row's id, the same action is the same id in all of
184
191
  them, and the comment beside an id is the row's version. In every other
185
192
  workflow a `uses:` is the major of a row's version.
186
193
 
187
194
  **An id is moved by a pull request, reviewed like any change to that
188
- workflow.** It changes these together, and nothing else in the three workflow
195
+ workflow.** It changes these together, and nothing else in these four workflow
189
196
  files:
190
197
 
191
198
  - the id and the version comment, on every `uses:` line of that action in
192
- `release.yml`, `build-installers.yml` and `tui-macos.yml`;
199
+ `release.yml`, `build-installers.yml`, `tui-macos.yml` and `team-image.yml`;
193
200
  - the action's row in the table.
194
201
 
195
202
  **The id is read from an exact version tag of the action's own repository**
@@ -355,29 +362,29 @@ node scripts/assemble-release-notes.mjs --tag v0.54.0
355
362
  entries merged since, which go after the earlier ones.
356
363
  - **The Upgrade section opens with the order of the Desktop and the CLI.**
357
364
  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.
365
+ release: either order works ([Upgrading](upgrading.md#either-order-works)).
366
+ For a new minor or major it adds what the previous Desktop holds back with
367
+ this CLI until it is updated, and that a Desktop of 0.69.17 or older
368
+ (`LAST_HARD_CEILING_DESKTOP`, `lib/pi-bridge.mjs`) refuses it: install the
369
+ Desktop first there.
364
370
 
365
371
  No entry file writes this line: only the tag owner knows the release's
366
372
  version when the notes are assembled.
367
373
  - **The same pull request updates "Upgrading to the latest version"**, the
368
374
  section [Upgrading](upgrading.md) opens with: the version being tagged in
369
375
  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
376
+ Desktop and the CLI install), and the CLIs that version's Desktop accepts:
377
+ up to 0.69.17, its band (`>=0.26.0 <0.70.0`); after it, `The <version>
378
+ Desktop accepts OATS CLIs \`>=<floor>\`, tested through <X.Y>`, with the
379
+ Desktop and the CLI `in either order`. The page
380
+ states only this version's; the earlier ones stay in their notes. When the
374
381
  release's Upgrade section asks for more than the page's steps, the order
375
382
  of the Desktop and the CLI and an optional package pin, the pull request
376
383
  also adds the release's entry at the top of "Coming from an older
377
384
  version", one line that links its notes.
378
385
  `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
386
+ version the manifests carry and no other, and states that version's
387
+ Desktop's accepted CLIs in the form above. The oats.setup skill `oats-upgrade` reads
381
388
  this page at the release's tag, so what the tag carries is what an upgrade
382
389
  follows.
383
390
  - **A tag is refused while anything is under `docs/release-notes/next/`:** by