@awebai/oats 0.69.12 → 0.69.14
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 +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +24 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +1 -1
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +92 -25
- package/lib/tmux-config.mjs +0 -35
|
@@ -201,7 +201,10 @@ home its deployment's kernel reported for it, canonicalizing to
|
|
|
201
201
|
home check (`E_HOME_UNVERIFIED`), then the CLI call (`cliStart`, with its wait),
|
|
202
202
|
and says whether the CLI ran. A failed start is `refused`, nothing was
|
|
203
203
|
started: every refusal of the gate and the home check, the kernel's
|
|
204
|
-
`E_SESSION_START_BUSY
|
|
204
|
+
`E_SESSION_START_BUSY`, `E_SESSION_START_LOCK_STUCK` (an earlier OATS's start
|
|
205
|
+
lock in the home, which a person removes: its sentence says so, and the
|
|
206
|
+
kernel's message under it names the path) and `E_SESSION_RUNNING`
|
|
207
|
+
(`STARTED_NOTHING_CODES`), and
|
|
205
208
|
its `E_LIFECYCLE_BUSY` and `E_INSTANCE_RETIRING` when the answering kernel
|
|
206
209
|
lists `lifecycle-claim-start` (`CLAIM_STARTED_NOTHING_CODES`: a stop, an upgrade
|
|
207
210
|
or a retire holds the home, or a retirement or a failed spawn left cleanup to
|
package/docs/desktop.md
CHANGED
|
@@ -9,7 +9,7 @@ retires and schedules agents.
|
|
|
9
9
|
## Install
|
|
10
10
|
|
|
11
11
|
Download the installer for your platform from the
|
|
12
|
-
[GitHub Release](https://github.com/
|
|
12
|
+
[GitHub Release](https://github.com/oats-project/oats/releases) assets:
|
|
13
13
|
|
|
14
14
|
| Platform | Artifacts | Notes |
|
|
15
15
|
| --- | --- | --- |
|
|
@@ -25,8 +25,21 @@ the app was tested on.
|
|
|
25
25
|
Windows and Linux arm64 are not supported.
|
|
26
26
|
|
|
27
27
|
Verify downloads against the release's `SHA256SUMS.txt`. GitHub
|
|
28
|
-
build-provenance attestations are published for every asset
|
|
29
|
-
|
|
28
|
+
build-provenance attestations are published for every asset. Where they live
|
|
29
|
+
depends on where the release was built:
|
|
30
|
+
|
|
31
|
+
- **Releases after 0.69.12**, built in `oats-project/oats`:
|
|
32
|
+
`gh attestation verify <file> --repo oats-project/oats --signer-workflow oats-project/oats/.github/workflows/release.yml --source-ref refs/tags/v<version>`.
|
|
33
|
+
- **Releases up to 0.69.12**, built in `awebai/oats` before the repository
|
|
34
|
+
moved. Their attestations stayed with the `awebai` organisation, so
|
|
35
|
+
`--repo` finds none (`HTTP 404`):
|
|
36
|
+
`gh attestation verify <file> --owner awebai --signer-workflow awebai/oats/.github/workflows/release.yml --source-ref refs/tags/v<version>`.
|
|
37
|
+
Use it only for these versions. For a later release it would trust the old
|
|
38
|
+
organisation in place of the new one.
|
|
39
|
+
|
|
40
|
+
Both forms accept only that repository's release workflow, run for the
|
|
41
|
+
release's tag. They accept no other workflow of the owner and no run from a
|
|
42
|
+
branch.
|
|
30
43
|
|
|
31
44
|
### macOS: ad-hoc signed build
|
|
32
45
|
|
|
@@ -161,11 +174,16 @@ Launch flags for scripted use: `--dir <workspace>`, `--instance <name>` and
|
|
|
161
174
|
`--instance <name>` beside `--dir <deployment>` opens the deployment's window
|
|
162
175
|
with that instance selected in the roster, as **Show in roster** selects it:
|
|
163
176
|
its row is revealed (a collapsed parent or the Background section opens) and
|
|
164
|
-
takes the keyboard focus.
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
177
|
+
takes the keyboard focus. If the row is running, its terminal tab opens in
|
|
178
|
+
the main area through the same path as a click. Keyboard focus stays on the
|
|
179
|
+
roster row: no key reaches the terminal until you click into it or use
|
|
180
|
+
**Terminal: focus the active terminal input**. First and repeated launches
|
|
181
|
+
behave the same way.
|
|
182
|
+
|
|
183
|
+
- **Only a running local row opens.** Stopped, never-launched, unknown, held,
|
|
184
|
+
unavailable or stale rows stay selected only, with no Start dialog. Nothing
|
|
185
|
+
starts, stops, is written or receives input. The only kernel calls are the
|
|
186
|
+
roster reads and the viewer attach a click makes.
|
|
169
187
|
- **The name must be an instance name**, the one `oats spawn --name` takes. Any
|
|
170
188
|
other value is ignored, and the window says the instance named at launch
|
|
171
189
|
isn't a valid instance name, without repeating the value.
|
|
@@ -173,7 +191,9 @@ and on a launch while Desktop runs, it behaves the same way.
|
|
|
173
191
|
other workspaces never match. A name that isn't there yet (a spawn still
|
|
174
192
|
finishing) is waited for, over the roster's next reads, for about 30
|
|
175
193
|
seconds; then the window says "No instance <name> in this workspace". A name
|
|
176
|
-
two of its instances share selects nothing, and the window says so.
|
|
194
|
+
two of its instances share selects nothing, and the window says so. A row
|
|
195
|
+
first observed running opens; one first observed stopped stays selected
|
|
196
|
+
only even if it later starts.
|
|
177
197
|
- **Your choice wins.** Selecting anything, typing or clicking while it waits
|
|
178
198
|
drops it. A later launch's `--instance` replaces it.
|
|
179
199
|
- Without `--dir`, with a `--dir` that isn't a deployment, or from a folder
|
|
@@ -1125,6 +1145,14 @@ unknown or unreported harness shows "?". Sources and licences are in
|
|
|
1125
1145
|
|
|
1126
1146
|
For bugs, attach the terminal output of the app (`OATS Desktop` prints
|
|
1127
1147
|
server and CLI-discovery logs to stdout) and your platform/arch.
|
|
1148
|
+
On Linux, a launch from a terminal writes to that terminal; redirect stdout
|
|
1149
|
+
and stderr to a file to capture it. A launch through a systemd user unit
|
|
1150
|
+
(including `systemd-run --user`) normally goes to that unit's journal:
|
|
1151
|
+
`journalctl --user -u <unit>`. Desktop does not maintain a separate log file.
|
|
1152
|
+
A launch carrying `--instance` prints one disposition line: `selecting it in
|
|
1153
|
+
<dir>` when main sends the selection request, or `not selected (<reason>)`
|
|
1154
|
+
when it cannot. This records the request, not whether the renderer has found
|
|
1155
|
+
the instance yet.
|
|
1128
1156
|
|
|
1129
1157
|
## Building from source
|
|
1130
1158
|
|
|
@@ -1141,8 +1169,26 @@ the bundled backend, of its liveness collector and of every module main
|
|
|
1141
1169
|
imports, from `app.asar` and the `client/` directory beside it, no GUI
|
|
1142
1170
|
launch). The Linux leg then runs the
|
|
1143
1171
|
smoke once more with its launch phase, under a virtual display; no macOS leg
|
|
1144
|
-
launches the window.
|
|
1145
|
-
|
|
1146
|
-
|
|
1172
|
+
launches the window. The GUI phase retains the empty-directory picker launch
|
|
1173
|
+
and adds fresh AppImage probes with `--dir <fixture> --instance smoke-probe`,
|
|
1174
|
+
asserting main's selection-request diagnostic. Repeated launches of the same
|
|
1175
|
+
arguments reach the running app. Both launches of the running fixture must
|
|
1176
|
+
open its terminal tab in the main area while keeping keyboard focus on its
|
|
1177
|
+
roster row. Before the repeated running launch, the smoke switches to Workspace
|
|
1178
|
+
overview, then requires that launch to reactivate the retained tab with exactly
|
|
1179
|
+
one viewer and no terminal focus event. CDP sends a key to the window;
|
|
1180
|
+
independent tmux pane/output reads prove no input reached the inert harness. The stopped fixture stays selected
|
|
1181
|
+
only, with no tab or Start dialog, on Workspace overview. The smoke also
|
|
1182
|
+
asserts that viewer cleanup restores its private tmux baseline. The fixture's
|
|
1183
|
+
workspace/member source, soul definition and inert harness executable are authored by the test-only
|
|
1184
|
+
[`launch-fixture.mjs`](../packages/desktop/test/helpers/launch-fixture.mjs).
|
|
1185
|
+
The checkout's CLI creates the deployment and lock through `onboard`, creates
|
|
1186
|
+
the stopped fixture through `spawn --no-launch` and the running fixture
|
|
1187
|
+
through an ordinary spawn using the inert harness, and checks their status.
|
|
1188
|
+
Each fresh app uses private home,
|
|
1189
|
+
OATS, tmux and profile directories. The AppImage runtime extracts and runs
|
|
1190
|
+
without requiring FUSE, retaining its private extraction until both launches
|
|
1191
|
+
are reaped. The headless run starts the backend as the app does,
|
|
1192
|
+
checks that it answers and that it exits when its stdin closes, and runs the collector once;
|
|
1147
1193
|
it does not exercise the GUI or, on Linux, the AppImage's launcher and
|
|
1148
1194
|
runtime (the glibc floor runs the runtime only to unpack the AppImage).
|
|
@@ -7,6 +7,8 @@ Closing a viewer, or the Desktop, stops neither the agent nor its session.
|
|
|
7
7
|
|
|
8
8
|
All session commands run on the execution host, the machine that holds the
|
|
9
9
|
home. To run them on another machine, see [servers.md](servers.md).
|
|
10
|
+
For a team container reached over the same SSH route, see
|
|
11
|
+
[the agent container contract](container.md).
|
|
10
12
|
|
|
11
13
|
## Harnesses
|
|
12
14
|
|
|
@@ -1279,9 +1281,9 @@ a signed-in host.
|
|
|
1279
1281
|
|
|
1280
1282
|
#### The launch environment a resume runs under
|
|
1281
1283
|
|
|
1282
|
-
A resume starts only under the `
|
|
1283
|
-
back ran with. Every start that renders a recipe, the
|
|
1284
|
-
included, records them. A resume compares them, after the check that every
|
|
1284
|
+
A resume starts only under the reference values (`fromEnv` or `fromFile`)
|
|
1285
|
+
the start it brings back ran with. Every start that renders a recipe, the
|
|
1286
|
+
spawn's own launch included, records them. A resume compares them, after the check that every
|
|
1285
1287
|
reference is set (`E_LAUNCH_ENV_MISSING`, which comes first):
|
|
1286
1288
|
|
|
1287
1289
|
- **A changed value** refuses the resume before anything is launched:
|
|
@@ -1413,8 +1415,36 @@ refused. A home removed between the read and its start is reported
|
|
|
1413
1415
|
`--plan` says what it would do and starts nothing. Its answer is in
|
|
1414
1416
|
[desktop-cli-api.md](desktop-cli-api.md#the-machine-sweep-oats-session-resume).
|
|
1415
1417
|
|
|
1416
|
-
- One sweep runs per machine: a second one answers `E_RESUME_BUSY
|
|
1417
|
-
|
|
1418
|
+
- One sweep runs per machine: a second one answers `E_RESUME_BUSY`, at once,
|
|
1419
|
+
and starts nothing. The lock is one file, `session-resume/lock`, that names
|
|
1420
|
+
the sweep holding it by pid, by the time that process started and by the
|
|
1421
|
+
boot it was taken in.
|
|
1422
|
+
- A lock left by a sweep that is gone (it exited, was killed, or its pid
|
|
1423
|
+
belongs to another process) is taken over at once by the next sweep. A
|
|
1424
|
+
sweep ended by a signal, a container's stop included, releases nothing:
|
|
1425
|
+
its lock is one of these.
|
|
1426
|
+
- A lock taken in another boot is taken over whatever its pid reads as: a
|
|
1427
|
+
boot ends every process, and a pid and a start time counted from the boot
|
|
1428
|
+
can both come again in the next.
|
|
1429
|
+
- A lock that needs a person is refused with `E_RESUME_LOCK_STUCK`, never
|
|
1430
|
+
with `E_RESUME_BUSY`, and left as it is. The message says which was
|
|
1431
|
+
found and what to remove: a record that cannot be read, a holder that
|
|
1432
|
+
cannot be told to be running or gone, a gone holder's record that cannot
|
|
1433
|
+
be taken over, a lock that was taken again each time the sweep found it
|
|
1434
|
+
free, or a sweep that cannot read its own start time. Remove the file
|
|
1435
|
+
the message names once no `oats session resume` is running, and run the
|
|
1436
|
+
sweep again. No sweep starts anything on this machine until then.
|
|
1437
|
+
- A directory at the lock's path is the lock of an OATS that locked with
|
|
1438
|
+
one. It is refused with `E_RESUME_LOCK_STUCK` too, whoever its owner is,
|
|
1439
|
+
and is never removed for you: remove the directory once no earlier
|
|
1440
|
+
`oats` is running on this machine. That OATS, meeting the file, answers
|
|
1441
|
+
`E_RESUME_BUSY` for the file's first minute and takes the lock over
|
|
1442
|
+
after it, also from a sweep that still runs: run one OATS version per
|
|
1443
|
+
machine.
|
|
1444
|
+
- `oats doctor` reports a lock in any of those states as one
|
|
1445
|
+
`resume-lock-stuck` problem, with the path and what to do. It reads the
|
|
1446
|
+
lock and takes nothing. A free lock, a sweep that runs and a lock a gone
|
|
1447
|
+
sweep left are not reported.
|
|
1418
1448
|
- A loss is answered once: whatever a sweep did with it (resumed, refused,
|
|
1419
1449
|
skipped or blocked), no later sweep starts it again, in this boot or after
|
|
1420
1450
|
a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
|
|
@@ -1430,8 +1460,41 @@ refused. A home removed between the read and its start is reported
|
|
|
1430
1460
|
has answered, so a sweep killed while other starts run has counted it; a
|
|
1431
1461
|
refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
|
|
1432
1462
|
bounded nor counted.
|
|
1433
|
-
- The boot is the boot
|
|
1463
|
+
- The boot is the boot time on macOS and the kernel's boot id
|
|
1464
|
+
(`/proc/sys/kernel/random/boot_id`) on Linux. Elsewhere there
|
|
1434
1465
|
is no boot: nothing is noted or counted, and every sweep tries again.
|
|
1466
|
+
- **Inside a container a boot is one run of the container.** A container
|
|
1467
|
+
shares its host's kernel, so the kernel's boot id stays the same when the
|
|
1468
|
+
container is stopped and started, restarted or made again, while every
|
|
1469
|
+
process in it, its terminal server and its sessions included, is gone. The
|
|
1470
|
+
boot there is the kernel's boot id together with the start time of the
|
|
1471
|
+
container's PID 1 (field 22 of `/proc/1/stat`, clock ticks after the
|
|
1472
|
+
kernel's boot): PID 1 starts once per run and its end ends the run, so the
|
|
1473
|
+
identity is the same for every `oats` process of one run and another one
|
|
1474
|
+
in the next, and the boot id keeps it apart from a run after the host's
|
|
1475
|
+
restart. Each run has its own count of 3 starts per home, takes over a lock
|
|
1476
|
+
the run before left, and clause 4 does not reach from one run into the
|
|
1477
|
+
next. Both values are read without privileges and nothing is written for
|
|
1478
|
+
them.
|
|
1479
|
+
- OATS takes itself to be in a container when one of these is there: the
|
|
1480
|
+
file `/.dockerenv` (Docker), the file `/run/.containerenv` (Podman), or
|
|
1481
|
+
the environment variable `KUBERNETES_SERVICE_HOST` (every Kubernetes
|
|
1482
|
+
pod). A container runtime that sets none of them is read as a host: give
|
|
1483
|
+
its containers `KUBERNETES_SERVICE_HOST` or one of the files.
|
|
1484
|
+
- Without one of them PID 1's start is not read. A command that a harness
|
|
1485
|
+
runs in a sandbox with a PID namespace of its own (bubblewrap's
|
|
1486
|
+
`--unshare-pid`) has that sandbox's PID 1, and is on the host's boot all
|
|
1487
|
+
the same.
|
|
1488
|
+
- When PID 1's start cannot be read in a container (a `/proc` mounted with
|
|
1489
|
+
`hidepid`, say) the boot is the boot id alone. Every run on one host boot
|
|
1490
|
+
is then the same boot: the count runs across them and clause 4 applies
|
|
1491
|
+
across them, so a sweep starts fewer homes, never more.
|
|
1492
|
+
- A container that shares its host's PID namespace (`--pid=host`), and a
|
|
1493
|
+
Kubernetes pod with `shareProcessNamespace: true`, read a PID 1 that
|
|
1494
|
+
outlives the container, so their boot is the same in every run.
|
|
1495
|
+
- Inside a container, a command run in a sandbox with a PID namespace of
|
|
1496
|
+
its own reads the sandbox's PID 1 and records a boot of its own. Run the
|
|
1497
|
+
sweep outside such a sandbox there.
|
|
1435
1498
|
- The lock, the per-boot note and the record of what status saw live in
|
|
1436
1499
|
`session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
|
|
1437
1500
|
are kernel-private, not a contract.
|
package/docs/implementation.md
CHANGED
|
@@ -28,9 +28,9 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
28
28
|
through the home's `oats` link, before any PATH or global lookup (the
|
|
29
29
|
order is in [its README](../packages/pi/README.md)).
|
|
30
30
|
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
31
|
-
`oats.onboarding`, `oats.
|
|
32
|
-
capabilities and the `knowledge-theory-expert`
|
|
33
|
-
souls,
|
|
31
|
+
`oats.onboarding`, `oats.coordination-setup`, `oats.support` and
|
|
32
|
+
`oats.knowledge-theory` capabilities and the `knowledge-theory-expert`
|
|
33
|
+
and `oats-setup-expert` souls,
|
|
34
34
|
released as a package under its own `oats-framework/v<version>` tags.
|
|
35
35
|
`oats.core` is the one with executables: its spawn and launch hook and the
|
|
36
36
|
Claude Code waiting emitter (`capabilities/oats-core/bin/`).
|
|
@@ -83,7 +83,7 @@ and the rules its tests pin.
|
|
|
83
83
|
| `lib/` | the kernel (below) |
|
|
84
84
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
85
85
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
86
|
-
| `capabilities/` | this repository's own member capabilities
|
|
86
|
+
| `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skills adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
|
|
87
87
|
| `mirrors/` | generated byte mirrors of the official packages' capabilities (for example `oats-okf*`, checked by `scripts/check-okf-mirror.mjs`): release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package |
|
|
88
88
|
| `oats-package/` | the `oats.framework` package |
|
|
89
89
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
@@ -110,6 +110,7 @@ and the rules its tests pin.
|
|
|
110
110
|
| `reader.mjs` | `oats reader --stdio`, the warm reader (awebai/oats#1630; [the contract](desktop-cli-api.md#the-warm-reader), [the decisions](design/2026-10-29-warm-reader.md)): a client's child that answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, through `read-call.mjs` and the two answer functions, never a copy of them. It loads every module the reads import lazily (`PRELOAD`) before its hello; classifies a request with `hot-reads.mjs` `hotRead` and expands its flags with `argv.mjs`, then runs the dispatch's read part in the CLI's order (the flag syntax, `--max-age`, the inherited context), so a refusal there is the CLI's own answer; answers one request at a time, in arrival order, each with its own read session, closed at its end, and its deployments observer; changes its working directory to the request's `--dir` for the read and back to the install root after, because the programs the reads run by name resolve a relative `PATH` entry against it (a second lane must first give each child its own cwd). It compares `install-stamp.mjs`'s stamp, taken by `bin` before the kernel loaded, when a request starts and before its answer is written: a change refuses `E_READER_STALE` and exits. Its stdout carries protocol lines only (other writes go to stderr); a request in flight at exit has its session closed from the `exit` handler. `test/reader-protocol.test.mjs` pins the protocol and `PRELOAD` against the reads' closure. `oats reader --stdio` is a hot-read form, so `bin` loads only its dispatch's leaves for it, never `core.mjs` (`test/cli-hot-reads.test.mjs`). Kernel-private, not in `./core`. Dependency-free |
|
|
111
111
|
| `install-stamp.mjs` | the warm reader's install stamp: `stat` of the install's code and data (package.json, bin/oats.mjs, the catalog, every file under lib/, the docs schemas, each runtime dependency's package.json where it resolves now, the Node binary) as one string. Node built-ins only: `bin` imports it statically and takes the reader's baseline before any kernel module loads; `reader.mjs` compares each request against it |
|
|
112
112
|
| `argv.mjs` | how the kernel reads `--flag=value` ([Flag syntax](desktop-cli-api.md#flags)): `expandInlineValues`, which the CLI's dispatch runs once on its argv and the reader on each request's, so both give a malformed flag the same `E_BAD_ARGS`, and `flagValue`, a flag's value in an expanded argv. Kernel-private, not in `./core`. Dependency-free |
|
|
113
|
+
| `command-flags.mjs` | the flags each state-changing command defines ([The flags a command defines](desktop-cli-api.md#command-flags)): `COMMAND_FLAGS`, each command's operands (and how many it requires), value flags (and their words), switches, the flags it refuses in its own words, the answers it gives in its own words and its usage line, and `commandArgvProblem`, the one check of the CLI's argv against it, which the dispatch runs before the command runs and before a `--server` command is sent. Kernel-private, not in `./core`. Dependency-free |
|
|
113
114
|
| `kernel-features.mjs` | `KERNEL_FEATURES`, the features this kernel implements: `features` in `version --json` and in `status --json`; `READER_API`, the warm reader's protocol number (`readerApi` in `version --json` and in the reader's hello). Kernel-private, not in `./core` |
|
|
114
115
|
| `captured-context.mjs` | the refusal (`E_UNSUPPORTED_MODE`) of an environment that carries `OATS_RESOLUTION` or `OATS_DEPLOYMENT`, which the dispatch asks for every command but `version` and `reader`; the reader asks it for each request instead, so it starts and answers each read as the CLI would. Dependency-free |
|
|
115
116
|
| `repo-moves.mjs` | the moved repositories: `currentRepoKey` and `sameRepo`, what a compare of two repository keys goes through. It compares and never rewrites ([Moved repositories](workspaces.md#moved-repositories)). No I/O, no imports. `packages/client/repo-moves.mjs` is the same file, byte for byte, because the kernel and the clients import nothing of each other; `test/repo-moves.test.mjs` pins it |
|
|
@@ -122,11 +123,11 @@ and the rules its tests pin.
|
|
|
122
123
|
| `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) |
|
|
123
124
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
124
125
|
| `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) |
|
|
125
|
-
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|
|
126
|
+
| `launch-preference.mjs` | a soul's launch preference, pure: the layers a new launch reads, the `Launch` report, and `launchKeysUnmatched`, the one function that decides which keys of `souls.launch` name no soul. It decides from a description of one read of the workspace (`soulsOffered` in `instance-resolution.mjs`, built from the discovery and its `soulsUnread`); a reader never computes the answer itself. The same discipline decides `souls.disabled`: `disabledEntriesUnmatched` in `instance-resolution.mjs` is the one function that decides which entries name no soul, by spawn's own rule (`disabledEntry`) over the offered souls, with `soulsOffered`'s reasons as the proof boundary; both checks share the reason sentences (`uncheckedSentences`, said of a key or an entry) and the ranking of the nearest souls (`nearestSoulKeys`), and `oats doctor` reads this machine's cache once for both (`doctorDiscovery`). What a read did not record, it did not establish: a discovery with no `soulsUnread` leaves every key unchecked (`unrecorded`), and a member's enumeration with no `soulsSkipped` counts as one with a soul skipped (`skippedSome` in `workspace.mjs`). `launchLayers` takes that description and carries the unmatched keys, so every caller that has layers has the fact, and `launchPreferenceUnmatched` is the one constructor of `E_LAUNCH_PREFERENCE_UNMATCHED` (its code and the bound of its texts are the exported `LAUNCH_PREFERENCE_UNMATCHED` and `LAUNCH_PROBLEM_TEXT_MAX`): `selectNewLaunch` throws it and `launchReportFor` reports it, both in `core.mjs`, before the refusals that describe the fall-through launch. `soulLaunchCommand` is the one place the command an answer suggests (`oats soul launch set\|remove …`) is rendered: the `fix` of a launch refusal (`harnessFix`, `launchConfigUnknownFix`, `launchConfigAmbiguous`), the texts about an unmatched key and `oats doctor`'s `remedy` all call it, and none tells a person to edit `souls.launch` in the file. The one exception is made there too: a key that holds a character the kernel never prints (`REFUSED_TEXT`) cannot be written into a command line, so the function gives no command and says the key is deleted from the file by hand; `launchKeyQuoted` is the one quoting of a key in a sentence, with such a character replaced (`safeText`). No sentence checks its key itself |
|
|
126
127
|
| `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 |
|
|
127
128
|
| `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
|
|
128
129
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
129
|
-
| `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 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` values (`start-env.mjs`: a keyed digest per
|
|
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` |
|
|
130
131
|
| `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 |
|
|
131
132
|
| `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 |
|
|
132
133
|
| `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 |
|
|
@@ -136,18 +137,21 @@ and the rules its tests pin.
|
|
|
136
137
|
| `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
|
|
137
138
|
| `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
|
|
138
139
|
| `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
|
|
139
|
-
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`,
|
|
140
|
+
| `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too |
|
|
140
141
|
| `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`; `exact` gives the mode whatever the umask, as `core.mjs` `writeHomeRecord`, the kernel's write of a home's record, needs): a failed write or rename removes the private file and throws that failure's error (#1076). The caller gives the private name, the bytes and the mode. A writer that needs more (an exclusive link, a failed removal reported, a sync) keeps its own code |
|
|
141
142
|
| `worktree-hooks.mjs` | the `worktree` event's runner (cwd the tree, detached process group, log under `.oats/logs/`, fixed timeout, interrupt handling), process identity by pid and start time, and the credential-free `origin` URL. Two questions, two functions: `processStart` says whose a pid is (a zombie still holds its pid and start, which is what proves a recorded process group), `processLiveness` says whether the `oats` command a record names can still act (a zombie cannot: it is gone). Ask `processLiveness` only about an `oats` command's own process, never about a hook's or a harness's pid. `runPs` is the one way the kernel calls `ps` where an identity is read: the program, the fixed environment and how the answer is classified. `isStartToken` says the shape of a start token, once, beside its writer: it decides what of a record may be shown (`claim.mjs` `shownHolder`, `unknownGroupNote`), never whether a process lives |
|
|
142
|
-
| `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS
|
|
143
|
+
| `system-tools.mjs` | `systemTool`: a program the kernel runs from the system directories (`SYSTEM_TOOL_DIRS`: `/usr/bin`, `/bin`, `/usr/sbin`, `/sbin`, in that order), never from the caller's `PATH`. `ps` runs on the same directories: `worktree-hooks.mjs`'s `PS_ENV` takes its `PATH` from them. macOS's boot id (`session-seen.mjs` `bootId`) reads `sysctl` from them |
|
|
143
144
|
| `tmux-server-scope.mjs` | where sessions run on a systemd host: whether the OATS tmux server starts in a scope of its own (the creator's cgroup judged: Linux, unified hierarchy, inside a `.service` or a scope of the user manager), and whether each agent's harness is launched in one (`agentScope`: the probe, run with the pane's bus variables and cached per process, and the wrapper `nativeRecordCommand` renders); the scopes' names and the warnings when they cannot |
|
|
144
|
-
| `
|
|
145
|
+
| `session-*.mjs` | the tmux session backend and terminal input |
|
|
146
|
+
| `launch-env.mjs`, `launch-env-exec.sh` | host-side launch reference resolution and a private per-start 0600 handoff: aliases reach the pane without values in tmux argv; the shell launcher reads and deletes the file before executing the pane command. A later start removes abandoned handoffs before dispatch; retirement recovery excludes them. |
|
|
145
147
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
146
148
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
147
149
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
148
150
|
| `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
|
|
151
|
+
| `retire-git-forms.mjs` | which of a retire's Git commands read no work-tree file, by their exact form: the ones `core.mjs` runs without the overrides of the repository's filter drivers |
|
|
149
152
|
| `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
|
|
150
153
|
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
154
|
+
| `retire-incomplete.mjs` | retirements left open (a quarantine, a failed or interrupted self-retire) as `oats doctor`'s `retire-incomplete` problems (oats-project/oats#1747), read with `instance-listing.mjs`'s `openRetirements`, the readers of the status rows: read-only, no claim, no tmux |
|
|
151
155
|
| `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
|
|
152
156
|
| `file-pieces.mjs` | a regular file's bytes read in pieces of 1 MiB (`readFilePieces`, `hashFile`, and `readFileUpTo` for a home's `instance.json`, read whole up to 16 MiB for its neutral form), for every digest of the retire path: what a digest holds of a file is bounded whatever its size (Node reads no file over 2 GiB whole), and a file is read for the size it had when it was opened. One that ends before that size refuses with `E_WORK_INSPECTION_FAILED` |
|
|
153
157
|
| `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; a shell-labelled pane is a fallback shell only when that scan shows the pane's own process as a shell with no non-shell descendant, and a scan that cannot show it throws its reason (unknown, never idle: #1641); `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
|
|
@@ -173,15 +177,22 @@ success or uncertainty, permits rollback of composed bytes. An uncertain hook
|
|
|
173
177
|
is retried idempotently; a later refusal cannot turn that recovery into a
|
|
174
178
|
rollback.
|
|
175
179
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
180
|
+
Upgrade creates a regular file at the home's `.oats-start.lock` with `wx`
|
|
181
|
+
and keeps it until it has persisted its final invocation receipt. Upgrade
|
|
182
|
+
takes the lifecycle claim before reclaiming an interrupted upgrade's
|
|
183
|
+
regular-file mutex, including an empty file left by a killed opener, and
|
|
184
|
+
never reclaims a directory. A start makes nothing at this path: it holds the
|
|
185
|
+
lifecycle claim (#1602), which excludes another start and an upgrade that
|
|
186
|
+
runs, and then only reads the path (`core.mjs` `refuseStartMutex`). A
|
|
187
|
+
regular file there is an upgrade that died before it finished, refused with
|
|
188
|
+
`E_SESSION_START_BUSY` naming the same-key retry; a directory is the start
|
|
189
|
+
lock an earlier OATS made for each start, refused with
|
|
190
|
+
`E_SESSION_START_LOCK_STUCK` naming it, and so is anything else there: only a
|
|
191
|
+
person ends either, and the code keeps an unattended start from reading it
|
|
192
|
+
as a start that runs. A start never removes what it finds there. The upgrade
|
|
193
|
+
names a directory there as a start lock left by an earlier OATS, and an entry
|
|
194
|
+
that appears between its check and its create as that or a file made there
|
|
195
|
+
in between (`E_SESSION_RUNNING`).
|
|
185
196
|
|
|
186
197
|
Upgrade compares the home with its independent spawn baseline before it
|
|
187
198
|
changes anything there. A dirty home retains the entire baseline byte for
|
|
@@ -218,10 +229,32 @@ read-modify-write callers must supply the lock and reread. Later explicit one
|
|
|
218
229
|
stays explicit, including one reintroduced by an older writer: the stored
|
|
219
230
|
marker cannot distinguish its provenance. The trigger cap stays independent.
|
|
220
231
|
|
|
221
|
-
The
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
232
|
+
The lock of these shared files (`dir-lock.mjs` `withDirLock`: the schedule
|
|
233
|
+
locks, `servers.lock`, `deployments.lock`, a deployment's `local.lock`) is a
|
|
234
|
+
claim (`claim.mjs`): a file hard-linked into place that names its holder by pid
|
|
235
|
+
and start time. A holder that runs is waited for within the caller's retry
|
|
236
|
+
deadline and then refused with the caller's busy error. A holder that is
|
|
237
|
+
verifiably gone is taken over. A holder that cannot be judged, a record that
|
|
238
|
+
does not parse and a directory at the lock's path (the lock of an earlier
|
|
239
|
+
kernel) are refused with the same busy error and left as they are. A SIGINT or
|
|
240
|
+
SIGTERM that arrives while a section runs waits for it: the section completes,
|
|
241
|
+
the lock is released, and the module raises the signal again, so the process
|
|
242
|
+
ends by it as it would have. A SIGKILL leaves the lock, and the next acquirer
|
|
243
|
+
takes it over.
|
|
244
|
+
|
|
245
|
+
The resume sweep holds the same lock across its starts, which are
|
|
246
|
+
asynchronous (`acquireDirLock`, released by the sweep itself;
|
|
247
|
+
`session-resume.mjs` `acquireResumeLock`). No signal is held back for it: a
|
|
248
|
+
sweep a signal ends leaves its lock, and the next sweep takes it over. Its
|
|
249
|
+
record carries the boot it was taken in, and a lock of another boot is gone
|
|
250
|
+
whatever its pid reads as (`claim.mjs` `holderGone`). A sweep that runs is
|
|
251
|
+
`E_RESUME_BUSY`; every refusal that needs a person, a directory at the lock's
|
|
252
|
+
path included, is `E_RESUME_LOCK_STUCK`, told apart by the one word the lock
|
|
253
|
+
gives its caller for what it found (`dir-lock.mjs` `refusals`, `found`).
|
|
254
|
+
`oats doctor` reads the same lock without taking it (`dirLockHeld`, over
|
|
255
|
+
`claim.mjs` `claimUnheld`, with the same `holderGone`) and reports those
|
|
256
|
+
states as its `resume-lock-stuck` problem (`session-resume.mjs`
|
|
257
|
+
`resumeLockProblem`): one classification for the sweep and for doctor.
|
|
225
258
|
|
|
226
259
|
Spawn compensation returns its diagnostic and a structural uncertainty flag;
|
|
227
260
|
only an incomplete result marks the original error's `details.unconfirmed`.
|
|
@@ -401,8 +434,11 @@ caches need git 2.45 or later (`PARTIAL_FETCH_GIT`, the first git with
|
|
|
401
434
|
`GIT_NO_LAZY_FETCH`): only a successfully parsed version below that floor
|
|
402
435
|
authorizes a version-driven rebuild. With that older git every cache fetches
|
|
403
436
|
whole trees, a partial cache it meets is deleted and fetched again whole,
|
|
404
|
-
and
|
|
405
|
-
|
|
437
|
+
and one notice says why: it names the git version, not a repository, and the
|
|
438
|
+
session says it once (once per command, or per reader call), however many
|
|
439
|
+
caches it starts or rebuilds. Each of those caches still records
|
|
440
|
+
`oats.fetch = full`. An existing full cache stays full even when a later
|
|
441
|
+
probe reports a modern git.
|
|
406
442
|
|
|
407
443
|
One private strict version probe owns the memo per `exec`: concurrent callers
|
|
408
444
|
share the in-flight probe, and a parsed success is retained. A rejection,
|
|
@@ -465,10 +501,17 @@ reason text do not depend on whether Git's words can be shown.
|
|
|
465
501
|
|
|
466
502
|
Every write to a cache repo (its `git init`, config, fetches and pins) holds
|
|
467
503
|
the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
|
|
468
|
-
(`withCacheWriteLock`): an exclusive file holding
|
|
469
|
-
waited for while its holder
|
|
470
|
-
`reason: "cache"` naming the pid
|
|
471
|
-
|
|
504
|
+
(`withCacheWriteLock`): an exclusive file holding
|
|
505
|
+
`{pid, token, startedAt, bootId, processStart}`, waited for while its holder
|
|
506
|
+
lives (bounded by a whole fetch, then `reason: "cache"` naming the pid and
|
|
507
|
+
saying to check whether it is an oats process: once no oats process holds
|
|
508
|
+
it, the lock is safe to remove), reclaimed when the holder is gone, and
|
|
509
|
+
released only by its owner. A holder is judged by its pid, boot and start,
|
|
510
|
+
as a claim's holder is (`lib/claim.mjs`): a lock taken in another boot, or
|
|
511
|
+
whose pid is gone or runs with another start (a reused pid), is reclaimed
|
|
512
|
+
at once, and one whose start cannot be read is waited for. A record that
|
|
513
|
+
names no boot or start, as an earlier kernel writes it, is judged by its
|
|
514
|
+
pid alone, and so is every record by that kernel. Reclaimers take a short guard,
|
|
472
515
|
`<lock>.reclaim`, and check under it that the lock is still the dead
|
|
473
516
|
record before removing it, so a reclaimer that paused cannot delete a
|
|
474
517
|
live process's new lock. A guard whose holder died is never removed
|
|
@@ -513,7 +556,21 @@ A record is named by the digest of its fact's context (`ghLoginParts` in
|
|
|
513
556
|
`automations.mjs`: never a token value) and holds only the answer and when it
|
|
514
557
|
was observed; only `workspace-read.mjs` passes the reuse to `ghLogin` (its
|
|
515
558
|
`lookup`, with the display's 5 s wait), so a tick, a poll or a run always asks
|
|
516
|
-
`gh` live. `pruneStores` bounds both stores alike.
|
|
559
|
+
`gh` live. `pruneStores` bounds both stores alike. A third store,
|
|
560
|
+
`<cache>/.verified/`, holds the package trees a spawn found to digest to the
|
|
561
|
+
lock's `integrity` (`treeVerification` in `remote.mjs`, used by
|
|
562
|
+
`verifyLockedPackage` in `packages.mjs`;
|
|
563
|
+
[The integrity check at spawn](packages.md#the-integrity-check-at-spawn)).
|
|
564
|
+
A record is named by the digest of (repo key, commit, path, digest) and holds
|
|
565
|
+
those fields and the state of the cache repo the tree was read from
|
|
566
|
+
(`cacheEntryState`: a digest over every file's path, size, mode, inode,
|
|
567
|
+
mtime and ctime). It is believed only while the cache repo is in that state,
|
|
568
|
+
because git answers an object from the cache without checking it against its
|
|
569
|
+
id. `spawn` calls `verifyPreparedPackages` (`instance-resolution.mjs`)
|
|
570
|
+
between `prepareInstance` and `ensureWorkspaceSoul`, the first write under
|
|
571
|
+
the agents root; `instance-upgrade.mjs` compares through the same
|
|
572
|
+
`fetchLockedPackage`. `pruneStores` removes a record older than an
|
|
573
|
+
observation may be. Adding a cached item
|
|
517
574
|
means choosing an item name unique to its producer (the item string its
|
|
518
575
|
call site passes to `memoAtCommit`, or to `atCommit` in `workspace.mjs`) and
|
|
519
576
|
adding it to `test/parsed-cache.test.mjs`; `test/read-path-scale.test.mjs` pins the member
|
package/docs/integrations.md
CHANGED
|
@@ -139,8 +139,9 @@ The pinned versions and each package's capabilities and souls are in the
|
|
|
139
139
|
|
|
140
140
|
## Building an integration
|
|
141
141
|
|
|
142
|
-
Building an integration is implementing a contract.
|
|
143
|
-
`
|
|
142
|
+
Building an integration is implementing a contract. In the framework's own
|
|
143
|
+
workspace, `oats-engineering-expert` leads contract design, reading the
|
|
144
|
+
integrations knowledge node (`oats/integrations-expert`).
|
|
144
145
|
|
|
145
146
|
**Any slot.**
|
|
146
147
|
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
# Knowledge and learning
|
|
2
|
+
|
|
3
|
+
How OATS agents keep what they learn, so that every new instance of a soul starts wiser than the last. This page describes our default approach, implemented by the official `oats.okf` knowledge capability. Other knowledge capabilities can adopt it, adapt it or work differently.
|
|
4
|
+
|
|
5
|
+
## Four kinds of value, four places
|
|
6
|
+
|
|
7
|
+
An experienced agent carries four kinds of value, and each belongs in a different place:
|
|
8
|
+
|
|
9
|
+
- **Reusable procedures and know-how** belong in skills and capabilities. How to run a release is a skill.
|
|
10
|
+
- **Lasting judgment and the larger picture** belong in the knowledge base. Why a release must verify the installed artifact is a lesson.
|
|
11
|
+
- **A detailed understanding of the current problem** belongs in the instance's working context.
|
|
12
|
+
- **Unfinished work and next steps** belong in the instance's own state. Which release check is still running is state.
|
|
13
|
+
|
|
14
|
+
Only the second goes into the knowledge base.
|
|
15
|
+
|
|
16
|
+
## Keep expertise, not a second description of the code
|
|
17
|
+
|
|
18
|
+
> **Knowledge is what makes an expert an expert in a subject or project. It is not a description of what lives in the code.**
|
|
19
|
+
|
|
20
|
+
A lesson is kept when both answers are yes:
|
|
21
|
+
|
|
22
|
+
1. Would a future instance of this soul act differently for knowing it?
|
|
23
|
+
2. Is it something the instance could not learn by simply reading the repository?
|
|
24
|
+
|
|
25
|
+
- **Kept:** decisions and their reasons, rejected alternatives, discoveries, research conclusions, design inspiration, and awareness of the larger situation.
|
|
26
|
+
- **Not kept:** code structure, file maps, ordinary task progress, or anything the repository already makes clear. A second copy of what the code says only grows stale.
|
|
27
|
+
|
|
28
|
+
## Souls divide the knowledge base
|
|
29
|
+
|
|
30
|
+
- The knowledge base is divided into areas, such as the release process, the kernel or the design system.
|
|
31
|
+
- Each area has exactly one owning soul. Its instances' lessons are proposed to that area, and other souls hand lessons for it to its owner. Keeping the base consistent is maintenance, done by a knowledge maintainer or a person.
|
|
32
|
+
- Other souls read an area when their work touches it, and link to it rather than copying it.
|
|
33
|
+
- So every agent starts with a well-defined context: the area its soul owns, and the few it reads. Every area lives in one place, owned by one kind of agent.
|
|
34
|
+
- Each instance of a soul keeps its own working context and state for its own piece of work.
|
|
35
|
+
- Adopting someone else's published soul does not send your learning back to its publisher.
|
|
36
|
+
|
|
37
|
+
## How learning flows
|
|
38
|
+
|
|
39
|
+
1. **Instances work and capture evidence.** Each one keeps notes on what it decided and discovered.
|
|
40
|
+
2. **An independent harvester judges what is worth keeping,** at set moments such as a pull request handed over or a task finished.
|
|
41
|
+
3. **The proposal is validated and delivered** through the knowledge base's acceptance process. For a Git-backed knowledge base that is a pull request, reviewed by a knowledge maintainer agent or a person.
|
|
42
|
+
4. **Future instances consult the accepted result.**
|
|
43
|
+
|
|
44
|
+
Working instances never rewrite the accepted knowledge base directly. An open pull request is not yet accepted knowledge, and a delivery receipt does not prove that a person approved it or that another instance has read it.
|
|
45
|
+
|
|
46
|
+
## Our default: oats.okf
|
|
47
|
+
|
|
48
|
+
- It uses **Open Knowledge Format**: readable Markdown concepts with metadata, links and history.
|
|
49
|
+
- A team shares its knowledge bases, one or more, divided among its souls as above.
|
|
50
|
+
- It needs explicit bindings and setup; not every step is automatic.
|
|
51
|
+
|
|
52
|
+
## Your own way
|
|
53
|
+
|
|
54
|
+
OATS provides the contracts, and the knowledge capability decides how knowledge works. With the right capability you can, for example:
|
|
55
|
+
|
|
56
|
+
- let new instances inherit a soul's accumulated expertise;
|
|
57
|
+
- let instances of one soul develop their own specialisations from a shared foundation;
|
|
58
|
+
- let a long-running instance keep its working understanding across many tasks;
|
|
59
|
+
- turn selected learning into shared knowledge after review.
|
|
60
|
+
|
|
61
|
+
A knowledge capability can organise knowledge per soul, per topic or per project, centrally or next to the soul definitions, as long as it actually supports the arrangement you choose. Messaging and tasks work the same way: OATS provides the contracts, and you choose how your team works through them.
|
|
62
|
+
|
|
63
|
+
## Expertise can evolve
|
|
64
|
+
|
|
65
|
+
- Souls can widen their scope, hand an area to a better-placed soul, merge, or split into more specialised souls.
|
|
66
|
+
- A deliberate split into new reusable specialisations is called **speciation**. A generalist that keeps handling UX work, for example, can give rise to a dedicated UX expert. The new expert owns the UX area, and the generalist consults it rather than duplicating it.
|
|
67
|
+
- These changes are proposed and reviewed. A busy period or a large pile of notes is not enough on its own, and no agent reshapes its own soul.
|
|
68
|
+
|
|
69
|
+
## Learn more
|
|
70
|
+
|
|
71
|
+
- [Knowledge, instances and evolving expertise](knowledge-theory.md): the full model, including long-running instances, harvesting, maintenance, hand-offs and cloning.
|
|
72
|
+
- [Knowledge operations](knowledge.md): how the knowledge capability is set up and run.
|
|
@@ -73,10 +73,19 @@
|
|
|
73
73
|
"additionalProperties": {
|
|
74
74
|
"oneOf": [
|
|
75
75
|
{ "type": "string" },
|
|
76
|
-
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
|
|
76
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } },
|
|
77
|
+
{ "type": "object", "additionalProperties": false, "required": ["fromFile"], "properties": { "fromFile": { "type": "string", "pattern": "^/[^\\u0000]*$" } } }
|
|
77
78
|
]
|
|
78
79
|
},
|
|
79
|
-
"
|
|
80
|
+
"allOf": [{ "properties": {
|
|
81
|
+
"HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
82
|
+
"PATH": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
83
|
+
"CLAUDE_CONFIG_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
84
|
+
"CODEX_HOME": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
85
|
+
"PI_CODING_AGENT_DIR": { "not": { "type": "object", "required": ["fromFile"] } },
|
|
86
|
+
"PI_CODING_AGENT_SESSION_DIR": { "not": { "type": "object", "required": ["fromFile"] } }
|
|
87
|
+
} }],
|
|
88
|
+
"description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops. {fromFile: /absolute/path} reads a regular UTF-8 file of at most 64 KiB (source bytes including a final newline) on the execution host at every start, stripping one trailing LF or CRLF. NUL, missing, unreadable or nonregular files refuse with E_LAUNCH_ENV_MISSING. Both reference kinds are redacted and recorded only as keyed digests. fromFile is for credential values; directory selectors require a literal or fromEnv."
|
|
80
89
|
},
|
|
81
90
|
"model": { "type": "string", "minLength": 1, "description": "Model for this configuration's harness; overrides the soul default when this configuration is selected." },
|
|
82
91
|
"yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." },
|