@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.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +8 -1
- package/docs/container.md +345 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +100 -53
- package/docs/desktop.md +53 -24
- package/docs/execution-targets.md +66 -48
- package/docs/implementation.md +8 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +30 -23
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +5 -3
- package/docs/souls-and-instances.md +51 -27
- package/docs/trust-model.md +119 -0
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +45 -19
- package/docs/workspaces.md +3 -3
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +26 -11
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +43 -29
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +144 -51
- package/lib/session-seen.mjs +16 -11
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +4 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- 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:
|
|
1458
|
-
|
|
1459
|
-
a reboot; a later sweep reports it `not-seen-recently`. A
|
|
1460
|
-
skip
|
|
1461
|
-
|
|
1462
|
-
|
|
1463
|
-
|
|
1464
|
-
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
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
|
-
- **
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1485
|
-
|
|
1486
|
-
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
|
|
1490
|
-
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
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.
|
package/docs/implementation.md
CHANGED
|
@@ -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
|
|
21
|
-
writes the configuration files with it)
|
|
22
|
-
|
|
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
|
|
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`:
|
|
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
|
|
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
|
|
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,
|
package/docs/integrations.md
CHANGED
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
|
package/docs/official-catalog.md
CHANGED
|
@@ -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.
|
|
13
|
-
| `oats.okf` | `v6.0.
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
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.
|
|
53
|
-
| `oats-project/oats-research-coordination` | `template-v2.
|
|
54
|
-
| `oats-project/oats-scientific-research-coordination` | `template-v2.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
82
|
-
oats.okf: v6.0.
|
|
83
|
-
oats.aweb: v1.
|
|
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.
|
|
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.
|
|
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.
|
|
185
|
-
"commit": "
|
|
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.
|
|
435
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
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.
|
|
441
|
-
resolves to tag `oats-framework/v1.
|
|
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.
|
package/docs/release-lane.md
CHANGED
|
@@ -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
|
-
- **
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
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)).
|
|
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
|
|
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
|
|
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 `
|
|
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
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
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
|
|
372
|
-
|
|
373
|
-
|
|
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
|
|
380
|
-
|
|
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
|