@awebai/oats 0.69.1 → 0.69.3

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 (71) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +273 -66
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +4 -4
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/release-notes/v0.69.3.md +43 -0
  17. package/docs/servers.md +7 -2
  18. package/docs/soul.schema.json +1 -0
  19. package/docs/souls-and-instances.md +35 -2
  20. package/docs/tui.md +112 -15
  21. package/docs/upgrading.md +9 -5
  22. package/docs/workspaces.md +2 -2
  23. package/injects/instance-boundary.md +19 -33
  24. package/injects/work-attached.md +8 -13
  25. package/injects/work-checkout.md +16 -30
  26. package/injects/work-directory.md +9 -15
  27. package/injects/work-workspace.md +8 -19
  28. package/injects/work-worktree.md +18 -33
  29. package/lib/capability-contract.mjs +2 -2
  30. package/lib/core.mjs +162 -49
  31. package/lib/instance-background.mjs +54 -0
  32. package/lib/instance-inspect.mjs +3 -0
  33. package/lib/instance-lifecycle.mjs +35 -0
  34. package/lib/instance-resolution.mjs +3 -2
  35. package/lib/instance-same-work.mjs +67 -0
  36. package/lib/instance-upgrade.mjs +18 -0
  37. package/lib/materialize.mjs +23 -2
  38. package/lib/resolve.mjs +32 -5
  39. package/lib/servers.mjs +19 -4
  40. package/lib/session-resume-contract.mjs +1 -0
  41. package/lib/session-resume.mjs +36 -9
  42. package/lib/soul-composition.mjs +13 -10
  43. package/lib/workspace.mjs +3 -2
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +30 -8
  47. package/packages/client/deployment-data.mjs +9 -0
  48. package/packages/client/deployment-panel.mjs +4 -0
  49. package/packages/client/instance-tree.mjs +64 -14
  50. package/packages/client/launch-prompt-outcome.mjs +1 -1
  51. package/packages/client/panel-views.mjs +11 -3
  52. package/packages/client/remote-roster.mjs +5 -1
  53. package/packages/client/roster-sections.mjs +50 -6
  54. package/packages/client/same-work.mjs +49 -0
  55. package/packages/client/session-resume-trigger.mjs +15 -37
  56. package/packages/client/session-resume.mjs +22 -259
  57. package/packages/client/soul-rows.mjs +2 -0
  58. package/packages/client/spawn-apply-contract.mjs +2 -1
  59. package/packages/client/spawn-decision.mjs +4 -1
  60. package/packages/client/spawn-preview-contract.mjs +12 -1
  61. package/packages/client/spawn-preview.mjs +2 -0
  62. package/packages/tui/README.md +2 -2
  63. package/packages/tui/lib/client.mjs +6 -2
  64. package/packages/tui/lib/main.mjs +44 -11
  65. package/packages/tui/lib/model.mjs +101 -43
  66. package/packages/tui/lib/panel.mjs +23 -13
  67. package/packages/tui/lib/store.mjs +76 -20
  68. package/packages/tui/lib/views/frame.mjs +2 -0
  69. package/packages/tui/lib/views/help.mjs +2 -0
  70. package/packages/tui/lib/views/instances.mjs +38 -1
  71. package/skills/oats-getting-started/SKILL.md +2 -2
package/docs/desktop.md CHANGED
@@ -270,10 +270,15 @@ shortcut unless you give it one in the shortcuts editor), with two choices:
270
270
 
271
271
  Desktop knows a computer runs Omarchy when Omarchy's theme directory
272
272
  (`~/.local/state/omarchy/current`) is there, the same one the **This computer**
273
- theme reads. A font you chose always wins over the default. On Omarchy the
274
- terminal's default size is also smaller, 13px (JetBrains Mono, Omarchy's
275
- default face, at 13px), where it is 15px elsewhere. A size you set wins, and
276
- resetting the size or the zoom goes back to the computer's default.
273
+ theme reads. A font you chose always wins over the default.
274
+
275
+ The terminal's size belongs to the face its terminals are in, since the same
276
+ size looks larger in a wider face. Omarchy's font in the terminals defaults to
277
+ 13px (JetBrains Mono, Omarchy's default face, at 13px), and Inconsolata, with
278
+ System font, on macOS or when Omarchy's font shows System font's faces, to
279
+ 15px, on every computer. A size you set is kept for that face only, and a
280
+ font change never carries it to the other. Resetting the size or the zoom
281
+ goes back to the default of the face in use.
277
282
 
278
283
  The computer's monospace font is used only once it draws at a fixed width.
279
284
  Desktop checks it at start and on each choice in the picker. Where the
@@ -284,10 +289,11 @@ font**. The choice stays Omarchy's font, so the computer's font is used once
284
289
  it draws.
285
290
 
286
291
  The choice is kept on this computer, like the theme, and applies at once:
287
- open terminals switch font in place and keep what they show. The terminal's
288
- font size, Settings → Terminal and the zoom keys are not changed by it, and a
289
- terminal font family set with the palette's **Terminal: set font family…**
290
- still wins until **Terminal: reset typography**.
292
+ open terminals switch font and take that face's size in place, and keep what
293
+ they show. Settings → Terminal shows the size and the default of the face in
294
+ use. A terminal font family set with the palette's **Terminal: set font
295
+ family…** still wins until **Terminal: reset typography**, and the size stays
296
+ the one of the font chosen underneath it.
291
297
 
292
298
  The list of workspaces is always shown. Its heading holds **Add local
293
299
  workspace…** (the **+**). The list has one row per workspace this window can show, whatever
@@ -915,6 +921,22 @@ right of its parent, and related instances are grouped together. Siblings are
915
921
  joined by a dotted line through their dots. A parent's line to its children
916
922
  runs just to the right of the dotted line, so the two never merge.
917
923
 
924
+ A parent's line joins only the children that do its work. When the instances'
925
+ OATS has the `instance-same-work` feature, a child the kernel reports as doing
926
+ its parent's work (`sameWork: true` in its row, set with `oats spawn …
927
+ --same-work` or `oats instance same-work <instance> on`) is joined to its
928
+ parent, and any other child keeps its place and its indent with no line to its
929
+ parent. Under one parent the joined children are listed first, then the others,
930
+ each part in name order, so the parent's line ends at its last joined child and
931
+ never passes one it doesn't join. Nothing else marks the flag: no label, no
932
+ tag, and nothing for a screen reader, which still hears each child "under" its
933
+ parent in the command palette. The command palette draws the same lines, in
934
+ its own recency order inside each part. For another machine's instances, its
935
+ host must report the feature too, through an installed OATS with
936
+ `server-probe-features`. A host without the feature, or one whose features are
937
+ not known (its last read failed), keeps a line to every child. A spawn from the
938
+ Desktop never sets the flag.
939
+
918
940
  A row shows the instance's name as words: each `-` is a space, and the first
919
941
  letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
920
942
  maintainer lanes". Only the row's label changes. The hover card, the command
@@ -940,7 +962,8 @@ line for the rows it hides that need input, beside its own mark when it waits
940
962
  too. Rows never move or grow, and nothing animates.
941
963
 
942
964
  A row has no ⋯ button. Its actions (Open in split, Open pull request…,
943
- Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…, and
965
+ Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…,
966
+ Move to background or out of it ([Background instances](#background-instances)), and
944
967
  Forget… for an instance its server no longer lists) are in the row's context
945
968
  menu (right-click, Shift+F10 or the ContextMenu key), as a workspace row's are.
946
969
  It opens where you right-click, or on the row from the keyboard; the arrow keys,
@@ -951,6 +974,50 @@ can't be used from this computer), it opens nothing, and one line at the
951
974
  bottom of the main area says why, as a leader key that can't act does. The row's own tools stay: its pull request link and, on a
952
975
  stopped row, **Start…**.
953
976
 
977
+ ## Background instances
978
+
979
+ An instance can run in the background: it is listed apart, so the main tree
980
+ keeps the agents you work with. Background changes only where an instance is
981
+ listed. It starts, opens, takes input, messages and retires as any other.
982
+
983
+ - **Where it is listed.** Background instances leave the main tree for one
984
+ **Background** heading at the very end of the list, in the machine
985
+ headings' style, with a chevron and the number of instances under it. A
986
+ child of a background instance is listed under it there, whatever its own
987
+ setting, and so is the whole chain below it. A background instance whose
988
+ parent is in the main tree is a top row of the section. Inside, the rows
989
+ form their own tree, with the machine headings when the workspace has two
990
+ or more machines; no line joins a row of the section to a row of the main
991
+ tree. With no background instance there is no heading.
992
+ - **Closed by default.** The section starts closed in every new window. A
993
+ click, Enter or Space on the heading opens or closes it, and the right and
994
+ left arrows open and close it as they do a parent row. It stays as you left
995
+ it while the window shows the workspace, as a parent row's fold does.
996
+ Selecting an instance's tab, or opening one from the command palette, never
997
+ opens it; **Show in roster** and a spawn's **Show its row** do, since they
998
+ ask to see the row. A spawn you run in the background is listed there from
999
+ the start. The command palette lists every instance, background ones
1000
+ included, and the previous and next instance keys pass over the rows of a
1001
+ closed section. When the row you are on moves to a closed section, the
1002
+ focus goes to the heading.
1003
+ - **Needs input.** While an instance of the section waits on you, the
1004
+ heading carries the **Needs input** mark, open or closed. Open, the
1005
+ waiting row shows its own mark, and a folded parent says how many below it
1006
+ wait, as in the main tree. The workspace's Needs input mark counts
1007
+ background instances too.
1008
+ - **Choosing it.** The **Spawn** dialog has a **Run in background** switch,
1009
+ set to the soul's default (`background:` in its `soul.yaml`). A row's
1010
+ context menu offers **Move to background**, or **Move out of background**
1011
+ on a background instance, which runs `oats instance background`. A row
1012
+ that is in the section only because its parent is offers neither: move
1013
+ the parent. The setting is the instance's own, kept in its home by OATS:
1014
+ it lasts through restarts and is not inherited.
1015
+
1016
+ This needs OATS with the `instance-background` feature on this computer,
1017
+ and for an instance on a server, on that server too. With an older OATS the
1018
+ sidebar lists every instance in the main tree, and the switch and the menu
1019
+ items are not shown.
1020
+
954
1021
  ## An instance's colour
955
1022
 
956
1023
  An instance can have a colour, one of the soul palette's six (Sand, Sage,
@@ -1173,6 +1173,18 @@ stopped with OATS, or whose harness ended by itself, stay stopped. Stopping an
1173
1173
  instance with OATS is the only way to keep it down: nothing opts a deployment
1174
1174
  or an instance out of the sweep.
1175
1175
 
1176
+ **A home OATS is stopping, upgrading or retiring, or whose retire did not
1177
+ finish, is never resumed** (OATS 0.69.2). A resume holds the home's lifecycle
1178
+ claim for its whole start, the claim a retire, a stop and an upgrade hold, so
1179
+ it never runs beside one of them, and it reads under that claim whether the
1180
+ home owes a retire and whether its session is still lost. The sweep reports
1181
+ such a home `skipped`, `lifecycle-busy`, and starts nothing; what OATS was
1182
+ doing decides what the home is next. A retire records the stop of the session
1183
+ it ends, before it ends it, so a home it was retiring reads `stopped`, never
1184
+ `lost`, even when the retire fails afterwards. The one exception is when the
1185
+ stop record itself cannot be written (a full disk) and the retire then fails
1186
+ as well: that home reads `lost`, as it did before 0.69.2.
1187
+
1176
1188
  #### How a session's end is read
1177
1189
 
1178
1190
  A launched home that does not run reads one of three ends, `sessionEnd` on
@@ -1188,7 +1200,8 @@ for its current start (`startId` in `instance.json`):
1188
1200
 
1189
1201
  The window a spawn or a start makes writes the exit marker,
1190
1202
  `.oats-start-exited`, when the harness exits; `oats instance stop` writes its
1191
- record, `.oats-stop.json`. Both are kernel-private files of the home, not a
1203
+ record, `.oats-stop.json`, and so does a retire, before it ends the window
1204
+ (0.69.2). Both are kernel-private files of the home, not a
1192
1205
  contract: read `sessionEnd`. A shutdown kills the window's shell with the
1193
1206
  harness, so a lost session leaves no marker. A home spawned before 0.69 and
1194
1207
  never restarted since names no start: it reads `stopped` only after a stop,
@@ -1289,7 +1302,9 @@ tui` reading it, and the sweep's own read). All four must hold:
1289
1302
  1. OATS saw the home running for its current start.
1290
1303
  2. No earlier sweep answered this loss. A sweep answers each lost home once,
1291
1304
  whatever it did with it (resumed, started fresh, blocked, refused or
1292
- skipped). A status read never uses a loss up, and `--plan` answers none.
1305
+ skipped), except a home it skipped because OATS was stopping, upgrading
1306
+ or retiring it. A status read never uses a loss up, and `--plan` answers
1307
+ none.
1293
1308
  3. OATS first saw it not running less than 24 hours ago.
1294
1309
  4. Within one boot, OATS first saw it not running less than 24 hours after it
1295
1310
  last saw it running. Across a reboot this one does not apply.
@@ -1343,8 +1358,14 @@ kernel (`lib/session-seen.mjs`).
1343
1358
  writes it, and skips a deployment `oats deployments remove` took out of it;
1344
1359
  `--deployment <dir>` sweeps one directory, listed or not. It starts each lost
1345
1360
  home it can vouch for with `--resume` in that home's own deployment scope, at
1346
- most 4 at once. What it answers a lost home, the first that applies: not
1347
- seen recently; refused this boot; keeps getting lost; started.
1361
+ most 4 at once. What it answers a lost home, the first that applies: OATS
1362
+ is stopping, upgrading or retiring it, or its retire is owed
1363
+ (`lifecycle-busy`); not seen recently; refused this boot; keeps getting lost;
1364
+ started. The first is read from the home's status row, and the start's own
1365
+ claim decides when the row read missed it: a start that meets a retire, a
1366
+ stop, an upgrade or another resume is reported `lifecycle-busy` too, never
1367
+ refused. A home removed between the read and its start is reported
1368
+ `not-lost`.
1348
1369
  `--plan` says what it would do and starts nothing. Its answer is in
1349
1370
  [desktop-cli-api.md](desktop-cli-api.md#the-machine-sweep-oats-session-resume).
1350
1371
 
@@ -1352,7 +1373,8 @@ seen recently; refused this boot; keeps getting lost; started.
1352
1373
  left by a process that is gone, or by another boot, is taken over.
1353
1374
  - A loss is answered once: whatever a sweep did with it (resumed, refused,
1354
1375
  skipped or blocked), no later sweep starts it again, in this boot or after
1355
- a reboot; a later sweep reports it `not-seen-recently`. A refused resume is
1376
+ a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
1377
+ skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1356
1378
  never retried automatically: it is also noted for the boot, and reported
1357
1379
  `refused-this-boot` should that answer be lost.
1358
1380
  - A home is started by sweeps at most 3 times in a boot. A home lost again
@@ -53,10 +53,11 @@ effect of reading: for each deployment opened in a run it runs the kernel
53
53
  of the same install and the shared liveness collector as children, through
54
54
  the shared observer and refresh loop; it runs that kernel's read of the
55
55
  other machines (`oats server roster --json`), one at a time and awaited by
56
- no cycle; it ends every child; and it makes the one look at the file
56
+ no cycle; it ends every read child and lets changes finish; and it makes the one look at the file
57
57
  system the workspace switcher needs (whether a picked row is a deployment).
58
58
  This computer's list of deployments is the kernel's: `lib/main.mjs` reads
59
- and changes it through the shared `cliDeploymentList`. `lib/store.mjs` is the state and a pure
59
+ and changes it through the shared `cliDeploymentList`, and runs the kernel's
60
+ machine sweep of lost sessions when the shared resume trigger says, as a change. `lib/store.mjs` is the state and a pure
60
61
  `reduce(state, event)`; `lib/model.mjs` turns the state into the rows to
61
62
  draw by calling the shared readers through `lib/client.mjs`, the one module
62
63
  that imports `packages/client/`; `lib/views/` are pure functions from that
@@ -107,17 +108,17 @@ and the rules its tests pin.
107
108
  | `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 |
108
109
  | `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
109
110
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
110
- | `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); 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` |
111
+ | `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), 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` |
111
112
  | `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 |
112
113
  | `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 |
113
114
  | `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 |
114
115
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
115
116
  | `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
116
117
  | `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
117
- | `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 |
118
+ | `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 |
118
119
  | `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 |
119
120
  | `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 |
120
- | `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` and `oats instance stop --apply` (`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 |
121
+ | `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` and `oats session start --resume` (`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 |
121
122
  | `write-through-private-file.mjs` | the one writer of a file written through a private file beside it and renamed over it (`writeThroughPrivateFile`): 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, an exact mode, a failed removal reported, a sync) keeps its own code |
122
123
  | `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 |
123
124
  | `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 |
@@ -40,7 +40,7 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v5.3.0
43
+ oats.okf: v5.5.0
44
44
  oats.aweb: v1.32.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
package/docs/knowledge.md CHANGED
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
6
6
  owns its knowledge format, instructions and promotion procedure. The model is
7
7
  in [Knowledge, instances and evolving expertise](knowledge-theory.md).
8
8
 
9
- This is the operator guide for **oats.okf 5.3.0** (OATS **>=0.49.0**). Provider implementation and
9
+ This is the operator guide for **oats.okf 5.5.0** (OATS **>=0.49.0**). Provider implementation and
10
10
  recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
11
11
 
12
12
  | Surface | What it holds |
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
25
25
  ```yaml
26
26
  # oats-workspace.yaml (excerpt)
27
27
  packages:
28
- oats.okf: v5.3.0
28
+ oats.okf: v5.5.0
29
29
  defaults:
30
30
  knowledge: { oats.okf: { from: package } }
31
31
  stores:
@@ -50,18 +50,22 @@ settings:
50
50
 
51
51
  Upgrading from 4.x requires the ordered
52
52
  [5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
53
- just editing a version line. For 5.3.0, OATS >=0.49.0 remains required:
53
+ just editing a version line. For 5.5.0, OATS >=0.49.0 remains required:
54
54
  that kernel first supports the public source-event lookup after retirement.
55
55
 
56
- **Upgrade:** pin `oats.okf: v5.3.0` and run `oats sync`. Only new spawns get
56
+ **Upgrade:** pin `oats.okf: v5.5.0` and run `oats sync`. Only new spawns get
57
57
  the capability-owned harvest duty, skill and spawn-recorded policy. Existing
58
- homes keep their copied provider even after a session restart. Deployments
59
- whose briefings never mentioned harvesting now get knowledge proposals at
60
- the harvest checkpoints; souls not ready for this must declare
61
- `knowledge: { harvest: off }`. Consultation and instance-memory upkeep remain.
62
- From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the checkpoint
63
- line in `log.md`, drops the available-memory gate, and has the proposer name
64
- each harvester (`--name`, below).
58
+ homes keep their copied provider even after a session restart; from 5.4.0, a
59
+ stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
60
+ later), and a home spawned under 4.x is refused with the remedy to retire and
61
+ respawn it. Deployments whose briefings never mentioned harvesting now get
62
+ knowledge proposals at the harvest checkpoints; souls not ready for this must
63
+ declare `knowledge: { harvest: off }`. Consultation and instance-memory upkeep
64
+ remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
65
+ checkpoint line in `log.md`, drops the available-memory gate, and has the
66
+ proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
67
+ the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
68
+ that line, so run `oats sync` to 5.5.0 before instances on 5.5.0 propose.
65
69
 
66
70
  ### Bindings document
67
71
 
@@ -191,8 +195,9 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
191
195
  home: What (one claim per concept), Why, Evidence (observations, dates,
192
196
  limits and accepted concepts cited), and optional `## Backing notes` with
193
197
  one `- notes/<file>.md` entry per note. It has exactly one line
194
- `Source: instance <name>, home <path>, soul <name>` naming the actual
195
- source, a pointer to verify rather than authority. Claim only for owned
198
+ `Source: instance <name>, home <path>, soul <name>, incarnation <createdAt>`
199
+ naming the actual source, with `createdAt` copied from its `instance.json`:
200
+ a pointer to verify rather than authority. Claim only for owned
196
201
  nodes; a lesson for a node the soul only reads is named in one line in its
197
202
  hand-back for that node's owner.
198
203
 
@@ -239,9 +244,13 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
239
244
  <harvester>`).
240
245
  3. **Capture, judge and submit.** Before the model starts, the required spawn
241
246
  hook checks the source's live record or the completed recovery named by
242
- its public retirement event. Source identity, single-incarnation history,
243
- recovery manifest and soul opt-out must agree; guessed copies and reused
244
- or ambiguous identities refuse. It atomically captures the proposal,
247
+ its public retirement event. Source identity, the named incarnation,
248
+ recovery manifest and soul opt-out must agree; guessed copies and
249
+ ambiguous identities refuse. A live source whose name was used before is
250
+ matched by its incarnation; a `Source:` line without one still works for an
251
+ unambiguous source, and on a reused name it refuses with the remedy to
252
+ propose again with the incarnation. A retired source is captured only when
253
+ it had a single known incarnation. It atomically captures the proposal,
245
254
  verified source declarations/bindings and only named notes into the
246
255
  harvester's own `harvest-source/`. The model uses that snapshot, not a later
247
256
  live-source read: retirement or recovery disposal after capture cannot
@@ -9,10 +9,10 @@ or workspace membership alone does not make a package official.
9
9
 
10
10
  | package | release | capabilities | package souls |
11
11
  |---|---|---|---|
12
- | `oats.framework` | `oats-framework/v1.15.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
- | `oats.okf` | `v5.3.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
12
+ | `oats.framework` | `oats-framework/v1.16.1` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
13
+ | `oats.okf` | `v5.5.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
14
  | `oats.aweb` | `v1.32.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
15
- | `oats.engineering` | `v1.15.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
15
+ | `oats.engineering` | `v1.16.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
16
16
  | `oats.authoring` | `v1.0.3` | `oats.authoring` | |
17
17
  | `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
18
18
  | `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
30
30
  ## Find and use packages
31
31
 
32
32
  - A workspace pins an official package by **bare version** in its
33
- `packages:` map (`oats.okf: v5.3.0`); `oats sync` resolves it through the
33
+ `packages:` map (`oats.okf: v5.5.0`); `oats sync` resolves it through the
34
34
  catalog to an exact commit, fetches it, verifies its integrity and locks it.
35
35
  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
36
36
  not join a team or adopt the publisher's workspace. See
package/docs/packages.md CHANGED
@@ -44,14 +44,14 @@ whole organisation:
44
44
 
45
45
  ```yaml
46
46
  packages:
47
- oats.okf: v5.3.0 # bare version → the official catalog
47
+ oats.okf: v5.5.0 # bare version → the official catalog
48
48
  acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
49
49
  ```
50
50
 
51
- - **Bare version** (`v5.3.0`, `5.3.0`, `1.0.0-rc.1`): the id is looked up in
51
+ - **Bare version** (`v5.5.0`, `5.5.0`, `1.0.0-rc.1`): the id is looked up in
52
52
  the official catalog — `package-catalog.json` in the `oats` repo, or the file
53
53
  named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
54
- convention (`v5.3.0` or `oats-framework/v1.15.1`) and the payload path. An id
54
+ convention (`v5.5.0` or `oats-framework/v1.16.1`) and the payload path. An id
55
55
  the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
56
56
  a package outside the catalog"). The catalog is the reviewed official list
57
57
  ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,8 +74,8 @@ members:
74
74
  - git:github.com/acme/agents
75
75
  - git:github.com/acme/platform
76
76
  packages:
77
- oats.framework: v1.15.1
78
- oats.okf: v5.3.0
77
+ oats.framework: v1.16.1
78
+ oats.okf: v5.5.0
79
79
  oats.aweb: v1.32.0
80
80
  teams:
81
81
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
@@ -105,7 +105,7 @@ decision recorded in the lock.
105
105
  $ oats sync
106
106
  workspace acme (github.com/acme/agents @ 3f2a9c1e)
107
107
  members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
108
- packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.3.0 ✓ (@ 79befeaf)
108
+ packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.5.0 ✓ (@ 4817c74e)
109
109
  changed acme.tools — → 0.4.0 (@ 47f4b816)
110
110
  souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
111
111
  teams platform (shared) · this deployment's: oats teams
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
160
160
  "source": "catalog:oats.okf",
161
161
  "url": "https://github.com/awebai/oats-okf.git",
162
162
  "path": "oats-package",
163
- "version": "5.3.0",
164
- "commit": "79befeaf98e04a5a46896ddad8ac3333ee90bce3",
163
+ "version": "5.5.0",
164
+ "commit": "4817c74ede1e1b578e5a78759862964ea077ded1",
165
165
  "integrity": "sha256-…",
166
166
  "capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
167
167
  },
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
352
352
  {
353
353
  "policy": "docs/official-catalog.md",
354
354
  "packages": {
355
- "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.3.0", "path": "oats-package" },
356
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.15.1", "path": "oats-package" }
355
+ "oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.5.0", "path": "oats-package" },
356
+ "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.1", "path": "oats-package" }
357
357
  }
358
358
  }
359
359
  ```
360
360
 
361
- `ref` carries the tag convention: a workspace's `oats.framework: v1.15.1`
362
- resolves to tag `oats-framework/v1.15.1`. Resolving through the catalog never
361
+ `ref` carries the tag convention: a workspace's `oats.framework: v1.16.1`
362
+ resolves to tag `oats-framework/v1.16.1`. Resolving through the catalog never
363
363
  advances a lock by itself: `oats sync` does, and says so.