@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.
Files changed (70) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. 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` and `E_SESSION_RUNNING` (`STARTED_NOTHING_CODES`), and
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/awebai/oats/releases) assets:
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
- (`gh attestation verify <file> --repo awebai/oats`).
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. Press Enter to open its terminal. On a first launch
165
- and on a launch while Desktop runs, it behaves the same way.
166
-
167
- - **It only selects.** Nothing starts, attaches or is written, and Desktop
168
- reads nothing for it beyond the roster reads it makes anyway.
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. A local interactive run may also exercise the launch
1145
- phase. The headless run starts the backend as the app does, checks that it
1146
- answers and that it exits when its stdin closes, and runs the collector once;
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 `{fromEnv: SRC}` values the start it brings
1283
- back ran with. Every start that renders a recipe, the spawn's own launch
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`. A lock
1417
- left by a process that is gone, or by another boot, is taken over.
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 id on Linux and the boot time on macOS. Elsewhere there
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.
@@ -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.support` and `oats.knowledge-theory`
32
- capabilities and the `knowledge-theory-expert` and `oats-setup-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 (`oats-desktop-ui`, `oats-workspace-experts`), discovered at the member's latest state |
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 variable, 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
+ | `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`, before the start lock: 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
+ | `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`), never from the caller's `PATH`. `ps` runs on the same directories: `worktree-hooks.mjs`'s `PS_ENV` takes its `PATH` from them |
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
- | `tmux-config.mjs`, `session-*.mjs` | the tmux session backend and terminal input |
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
- Start and upgrade share the `.oats-start.lock` path through exclusive
177
- acquisition: start uses `mkdir`, while upgrade creates a regular file with
178
- `wx`. Both treat `EEXIST` as held. Upgrade takes the lifecycle claim before
179
- reclaiming an interrupted upgrade's regular-file mutex, including an empty
180
- file left by a killed opener, and never reclaims a directory. Start never
181
- reclaims this path. Upgrade releases it only after persisting its final
182
- invocation receipt. A start takes the lifecycle claim before this mutex too
183
- (#1602), so beside an upgrade that runs it is refused at the claim; it meets
184
- the mutex only when an upgrade that died left it.
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 shared mkdir lock retries every occupied-directory window within the
222
- caller's retry deadline, including owner-file publication and removal. It never
223
- removes a contender's lock or steals from a live, dead or unreadable owner;
224
- persistent contention ends in the caller's existing busy error.
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 the same notice says why. An existing full cache stays full even when a
405
- later probe reports a modern git.
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 `{pid, token, startedAt}`,
469
- waited for while its holder lives (bounded by a whole fetch, then
470
- `reason: "cache"` naming the pid), reclaimed when the holder is dead, and
471
- released only by its owner. Reclaimers take a short guard,
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. Adding a cached item
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
@@ -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. The framework's
143
- `integrations-expert` soul is the specialist for contract design.
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
- "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."
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." },