@awebai/oats 0.69.12 → 0.69.15

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 (92) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +254 -201
  3. package/docs/capabilities.md +58 -13
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +291 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +590 -55
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +84 -9
  11. package/docs/first-team.md +4 -3
  12. package/docs/implementation.md +99 -32
  13. package/docs/integrations.md +3 -2
  14. package/docs/knowledge-and-learning.md +72 -0
  15. package/docs/oats-local.schema.json +11 -2
  16. package/docs/official-catalog.md +39 -5
  17. package/docs/packages.md +93 -14
  18. package/docs/release-lane.md +2 -1
  19. package/docs/release-notes/v0.69.13.md +767 -0
  20. package/docs/release-notes/v0.69.14.md +83 -0
  21. package/docs/release-notes/v0.69.15.md +444 -0
  22. package/docs/schedules.md +159 -5
  23. package/docs/servers.md +241 -7
  24. package/docs/souls-and-instances.md +223 -14
  25. package/docs/tui.md +1 -1
  26. package/docs/upgrading.md +36 -5
  27. package/docs/workspaces.md +31 -5
  28. package/lib/claim.mjs +20 -5
  29. package/lib/command-flags.mjs +240 -0
  30. package/lib/core.mjs +1004 -633
  31. package/lib/deployments.mjs +4 -3
  32. package/lib/dir-lock.mjs +145 -33
  33. package/lib/errors.mjs +3 -2
  34. package/lib/harness-token.mjs +110 -0
  35. package/lib/host-run.mjs +218 -0
  36. package/lib/host-stop-child.mjs +21 -0
  37. package/lib/hot-reads.mjs +4 -3
  38. package/lib/instance-events.mjs +28 -6
  39. package/lib/instance-git.mjs +165 -14
  40. package/lib/instance-inspect.mjs +6 -1
  41. package/lib/instance-lifecycle.mjs +4 -3
  42. package/lib/instance-listing.mjs +114 -43
  43. package/lib/instance-resolution.mjs +56 -3
  44. package/lib/instance-upgrade.mjs +16 -20
  45. package/lib/kernel-features.mjs +4 -1
  46. package/lib/launch-env-exec.sh +7 -0
  47. package/lib/launch-env.mjs +74 -0
  48. package/lib/launch-preference.mjs +19 -12
  49. package/lib/member-clone.mjs +7 -1
  50. package/lib/packages.mjs +74 -2
  51. package/lib/read-call.mjs +4 -1
  52. package/lib/reader.mjs +3 -2
  53. package/lib/refused-text.mjs +3 -2
  54. package/lib/remote.mjs +126 -31
  55. package/lib/retained-after-retire.mjs +2 -7
  56. package/lib/retire-git-forms.mjs +41 -0
  57. package/lib/retire-incomplete.mjs +96 -0
  58. package/lib/schedule.mjs +239 -21
  59. package/lib/servers.mjs +161 -28
  60. package/lib/session-end.mjs +28 -8
  61. package/lib/session-resume.mjs +63 -56
  62. package/lib/session-seen.mjs +3 -14
  63. package/lib/start-env.mjs +13 -7
  64. package/lib/status-words.mjs +11 -4
  65. package/lib/system-tools.mjs +1 -36
  66. package/lib/teams.mjs +11 -4
  67. package/lib/upgrade-state.mjs +13 -2
  68. package/lib/worktree-hooks.mjs +6 -175
  69. package/lib/worktree.mjs +68 -10
  70. package/package-catalog.json +1 -1
  71. package/package.json +5 -1
  72. package/packages/client/instance-lifecycle.mjs +1 -1
  73. package/packages/client/lifecycle-contract.mjs +3 -1
  74. package/packages/client/session-resume-cli.mjs +2 -1
  75. package/packages/client/session-start.mjs +10 -7
  76. package/packages/client/workspace-cli.mjs +5 -1
  77. package/packages/record/README.md +56 -21
  78. package/packages/record/docs/capture-service.md +8 -5
  79. package/packages/record/docs/turn-record-sot.md +9 -0
  80. package/packages/record/lib/capture-health.mjs +6 -4
  81. package/packages/record/lib/capture-lock.mjs +31 -27
  82. package/packages/record/lib/capture-retained-scratch.mjs +4 -3
  83. package/packages/record/lib/capture-scratch.mjs +2 -1
  84. package/packages/record/lib/derived-state.mjs +4 -2
  85. package/packages/record/lib/index-db.mjs +4 -2
  86. package/packages/record/lib/lock-holder.mjs +21 -0
  87. package/packages/record/lib/private-files.mjs +18 -0
  88. package/packages/record/lib/process-identity.mjs +310 -0
  89. package/packages/record/lib/store.mjs +31 -25
  90. package/share/oats-login-receive +204 -0
  91. package/skills/oats-getting-started/SKILL.md +93 -26
  92. package/lib/tmux-config.mjs +0 -35
@@ -107,7 +107,9 @@ souls, and keeping its messages to other instances few and short:
107
107
  `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
108
108
  knowledge an onboarding expert needs, **`oats.onboarding`** (same package)
109
109
  is how the package soul `oats-setup-expert` tailors a new workspace to its use
110
- case, and **`oats.support`** (same package)
110
+ case, **`oats.coordination-setup`** (same package) is how it shapes OATS's
111
+ coordination practices to that organisation, and **`oats.support`** (same
112
+ package)
111
113
  is the support desk role: a publicly reachable soul that tickets requests and
112
114
  hands them to a support maintainer. None of them is kernel magic; the kernel still
113
115
  composes its own instance-boundary and work-mode briefings, and the "You run
@@ -531,6 +533,30 @@ takes a final capture of notes and the session record into durable custody; an
531
533
  incomplete capture keeps the home for a retry. Retirement never waits for a
532
534
  model or GitHub: processing continues after the home is gone.
533
535
 
536
+ A spawn that is killed after its spawn hooks started and before it wrote the
537
+ home's record (SIGKILL, a container stop, a dropped connection) leaves a home
538
+ `oats retire` still cleans up: the spawn records, before its first spawn hook,
539
+ which retire hooks a retire must run, and the retire runs them before it
540
+ removes the home. A home whose record does not say which retire hooks to run,
541
+ and that has no such marker, is refused with `E_UNIDENTIFIED_INSTANCE_HOME`
542
+ and kept; `--force` removes it without running a hook, once what its
543
+ capabilities registered is cleaned up by hand
544
+ ([A spawn in progress](capabilities.md#manifest)).
545
+
546
+ A retire hook's warning, such as an action someone must still take, is in the
547
+ retire's `warnings` and stays readable after the home is gone: each one is a
548
+ `retire-warning` event in the instance's workspace log, read with
549
+ `oats instance events <instance>` ([Events](desktop-cli-api.md#events)).
550
+
551
+ `oats retire <instance>` reads these flags: `--plan`, `--plan-revision <rev>`
552
+ with `--idempotency-key <key>`, `--home <path>`, `--dir <d>`, `--server <id>`,
553
+ `--self`, `--discard-worktree`, `--keep-dir`, `--force` and `--json`. Any
554
+ other flag, and any argument after the instance, is refused with `E_BAD_ARGS`
555
+ before anything happens: before a plan is read, a child is stopped, a hook
556
+ runs, or a routed retire is sent to its server. The refusal names the flag
557
+ (`oats retire: unknown flag --keep-dirs`) and prints the usage, so a mistyped
558
+ `--keep-dir` never removes the home.
559
+
534
560
  One retire of an instance runs at a time. A retire holds the instance's claim
535
561
  from the moment it has resolved the home until it ends: the file
536
562
  `.oats-retirement/claims/<instance>.lock` in the agent's instances directory,
@@ -700,9 +726,64 @@ them, and without them a status can read differently (a global
700
726
  `core.excludesFile`, `core.autocrlf`, a filter), which would add a copy
701
727
  attempt to every existing instance's retire. They are the operator's own;
702
728
  what the retire guards against is configuration the retired agent could
703
- write. One limit remains: a filter driver that the repository's own
704
- configuration names and its `.gitattributes` select can still run during
705
- `git status`. Turning it off would change what status reports.
729
+ write.
730
+
731
+ <a id="retire-filter-drivers"></a>
732
+ **Filter drivers of the repository are not run.** Git runs a
733
+ `filter.<name>.clean` or `.process` command when a status compares a
734
+ work-tree file that carries the `filter` attribute (`.gitattributes`, or
735
+ `info/attributes` in the Git directory), and it has no switch that turns
736
+ filters off. Before each `git status` of the worktree, of a repository under
737
+ it and of a recovery, and before a recovery's `git checkout`, the retire
738
+ reads the repository's own configuration (`git config --list`, which runs
739
+ nothing and follows `include.path` and `includeIf`) and overrides every
740
+ filter driver it defines to no command (`clean`, `smudge`, `process`) and
741
+ not required. The status the spawn baseline is taken from is read the same
742
+ way.
743
+
744
+ - A file such a filter applies to is compared as its bytes are in the work
745
+ tree, not as the filter would store them. An untouched file still reads as
746
+ unchanged, by the size and times the index recorded for it. One that was
747
+ rewritten, or whose times Git cannot tell from the index's, reads as
748
+ changed even when its filtered form is what is stored: it is work to
749
+ preserve, the retire copies it, and a worktree holding it is not removed
750
+ as a clean one.
751
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
752
+ or is not UTF-8) cannot be overridden. Git is not run, and the status has
753
+ failed: the retire refuses with `E_WORK_INSPECTION_FAILED` at its first
754
+ inspection, as for any [status that fails](#retire-status-fails), with
755
+ `--discard-worktree` and `--force` too. A spawn into a worktree of such a
756
+ repository is refused with the same code before its checkout and rolled
757
+ back ([a checkout runs no filter driver](#checkout-filter-drivers)). Remove
758
+ or rename the driver in the repository's configuration, then retry.
759
+ - A driver that the operator's global or system configuration defines is
760
+ the operator's own and runs with the operator's command, in the worktree
761
+ and in the recovery alike. That holds when the repository's configuration
762
+ defines a driver of the same name too (`git lfs install --local` beside
763
+ `git lfs install`): the repository's values for it are replaced by the
764
+ operator's, so a command the repository gives that name never runs. The
765
+ operator's configuration is the human's; the repository's is the agent's
766
+ to write. One case runs neither: the repository defines `process` for that
767
+ name and the operator's configuration does not. Git has no way to unset a
768
+ variable on its command line, and a `process` set to nothing turns the
769
+ driver's `clean` and `smudge` off with it, so the file is read unfiltered.
770
+ - The recovery has no local configuration, so it has none of the
771
+ repository's drivers. Its status must still be the worktree's, and for a
772
+ file such a filter applies to it can differ: the worktree reads an
773
+ untouched file as unchanged by the size and times its index recorded,
774
+ while the copy, whose files are written anew, compares its bytes with the
775
+ stored form. The copy then cannot be verified: the retire refuses with
776
+ `E_WORK_PRESERVATION_FAILED` and removes nothing. This is so only for a
777
+ driver the repository alone defines.
778
+ - Not covered: a driver written into the configuration between that read
779
+ and the Git command that follows it, and a filter a **submodule's own**
780
+ configuration defines. Git runs inside each populated submodule to learn
781
+ whether it is dirty, and the overrides name the repository's drivers, not
782
+ the submodule's. Where the agent and whoever retires it are one system
783
+ user, which is the usual arrangement, such a filter runs nothing the agent
784
+ could not run itself. Where they are separate users, it runs the agent's
785
+ command as the retiring user: do not retire a worktree with populated
786
+ submodules across users.
706
787
 
707
788
  **A worktree whose top level is another directory.** A worktree's
708
789
  per-worktree configuration can set `core.worktree` to a directory other
@@ -961,6 +1042,7 @@ That changes no digest and no error, and it is bounded: at most four files
961
1042
  are read at once, each through a 1 MiB buffer, and never more than 64 MiB or
962
1043
  4096 files ahead of the digest.
963
1044
 
1045
+ <a id="retire-status-fails"></a>
964
1046
  A worktree whose `git status` fails refuses the retire with
965
1047
  `E_WORK_INSPECTION_FAILED` at the first inspection: no recovery was written,
966
1048
  nothing was deleted, and the retire has not stopped the instance's session.
@@ -1235,9 +1317,12 @@ leaves what happened on disk (OATS 0.53.0):
1235
1317
  - **Its pending marker, only when the home is owed a retire:** when a retire
1236
1318
  hook was started or the removal of the home began. The usual quarantine
1237
1319
  marker is there too when hooks reported incomplete cleanup. The instance
1238
- then reads as retiring: `oats instance stop --apply` and `oats session
1239
- start` answer `E_INSTANCE_RETIRING`, and `oats retire <instance>`
1240
- continues. In every other case the completion removes its marker.
1320
+ is then owed a retire: `oats session start` answers
1321
+ `E_INSTANCE_RETIRING`, and `oats retire <instance>` continues. `oats
1322
+ instance stop --apply` is not refused: the completion has ended, so
1323
+ nothing holds the home against a stop
1324
+ ([a completion that was killed](#self-retire-interrupted)). In every
1325
+ other case the completion removes its marker.
1241
1326
  Nothing of the home was changed, so the instance is a stopped or a
1242
1327
  running instance like any other: a start works, and a wake schedule may
1243
1328
  start it. A session or a child that the completion stopped on its way
@@ -1245,9 +1330,71 @@ leaves what happened on disk (OATS 0.53.0):
1245
1330
  - **One event,** `retire-refused`, which says which of the two it was
1246
1331
  ([Events](desktop-cli-api.md#retire-refused-event)).
1247
1332
 
1248
- Nothing retries by itself: `oats retire <instance>` does. A completion
1249
- removes only the marker of its own scheduling, so the marker of a later
1250
- `--self` is left for that one's completion.
1333
+ <a id="self-retire-interrupted"></a>**A completion that was killed** (a
1334
+ `SIGKILL`, a container that stopped, a reboot) leaves no outcome, and its
1335
+ pending marker stays. The marker names the completion by its pid, its start
1336
+ and its boot, and the rule is: a pending marker holds its home only while
1337
+ the completion it names can still act; once that completion is gone,
1338
+ `oats retire <instance>` takes the retire over and completes it,
1339
+ `oats session start` is refused with that command in its message, and a
1340
+ stop is not refused: `oats instance stop --apply`, the stop a retire makes
1341
+ of a recorded child, and the stop `oats host run` makes of every running
1342
+ home when the host stops all stop a session that still runs there, and the
1343
+ marker stays. A
1344
+ completion is gone when its process has ended, when its pid runs with
1345
+ another start, and when the marker was written in another boot, whatever
1346
+ its pid reads as there. `oats status` shows the row's `retire` as
1347
+ `interrupted`, and `oats doctor` lists the home. A start answers
1348
+ `E_INSTANCE_RETIRING`, `<instance> is owed a retire (its retire was
1349
+ interrupted): finish it with` and the retire to run, because the home is
1350
+ never started again: the completion may have run retire hooks before it
1351
+ was killed, and a start would bring back an instance whose identity is
1352
+ gone. A marker that names no completion (one an OATS before 0.51.0 wrote)
1353
+ refuses a start and a stop as before, since whether its retire runs cannot
1354
+ be told, and `oats retire <instance>` completes it.
1355
+
1356
+ <a id="self-retire-hook-retry"></a>**A completion retries a cleanup that only
1357
+ retire hooks left incomplete** (oats-project/oats#1747), because a provider's
1358
+ failure is often transient. When the retire ends with the home quarantined,
1359
+ and what it owes is retire hooks and nothing else, the completion runs the
1360
+ same retire again: up to three times, about 1, 5 and 15 minutes after each
1361
+ failed attempt. Every attempt is an ordinary retire of the home, under its
1362
+ claim. Its quarantine retry clears only once the owed hooks are shown to have
1363
+ run.
1364
+
1365
+ - **A retry whose hooks pass ends as a first success does.** The home is
1366
+ removed and nothing is left beside it.
1367
+ - **After the last failed attempt** the completion leaves what it leaves
1368
+ today: the outcome, the pending marker, the quarantine and one
1369
+ `retire-refused` event. The outcome adds `attempts`, the number of attempts
1370
+ that ran.
1371
+ - **Every attempt has its own `retired` event** with its `hooks` list, so
1372
+ `oats instance events <instance>` shows each one and how its hooks ended.
1373
+ - **What is never retried.** A quarantine that also owes a Git step,
1374
+ directory preservation or an orphaned work directory, or whose descriptor
1375
+ could not be stored in the home. A capability that declares no retire
1376
+ hook, or hooks that cannot be rerun. The retries also stop at an attempt
1377
+ that answers an error, and at one whose debt is no longer hooks alone. No
1378
+ retry starts once the home is gone or the pending marker is no longer this
1379
+ completion's: the retry checks that after its wait and again under the
1380
+ home's claim, and leaves a later scheduling's marker as it is.
1381
+ - **While the completion waits**, `oats status` reads the retire as
1382
+ `running`. Any other retire of the home is refused with `E_LIFECYCLE_BUSY`,
1383
+ for up to about 21 minutes after a hook failure. The refusal names the next
1384
+ attempt and the earliest time the last one starts. The time is only a lower
1385
+ bound: how long each attempt runs cannot be known in advance. The completion
1386
+ keeps this in a file of its own beside the home,
1387
+ `.oats-retire-retry-<instance>.json`, kernel-internal. It is removed on
1388
+ every way out, and by any retire that removes the home.
1389
+ - **A completion killed while it waits** leaves the instance `interrupted`,
1390
+ as before.
1391
+
1392
+ After that, nothing retries by itself: `oats retire <instance>` does, and
1393
+ `oats doctor` lists every retirement left open as a `retire-incomplete`
1394
+ problem, with that command and the capability whose hook failed last
1395
+ ([doctor](desktop-cli-api.md)). A completion removes only the marker of its
1396
+ own scheduling, so the marker of a later `--self` is left for that one's
1397
+ completion. Plain retires are not retried: their caller gets the answer.
1251
1398
 
1252
1399
  A completion does not start its retire while its scheduling still holds
1253
1400
  the home's claim (OATS 0.53.0). A scheduling that the host holds up
@@ -1729,6 +1876,41 @@ a `--repo` that is not a clone of the soul's repository starts at its `HEAD`.
1729
1876
  The spawn result and `instance.json` record the start point as
1730
1877
  `base: {ref, oid}`.
1731
1878
 
1879
+ <a id="checkout-filter-drivers"></a>
1880
+ **A checkout runs no filter driver of the repository.** Every Git command
1881
+ OATS runs that writes a tree's files (the spawn's `git worktree add` here,
1882
+ and the `git worktree add` and `git switch` of
1883
+ [`oats worktree add`](#extra-trees)) runs with every filter driver the
1884
+ repository's own configuration defines overridden to no command, so a
1885
+ `filter.<name>.smudge` or `.process` command that configuration names is
1886
+ never run and a file carrying the `filter` attribute is written as its
1887
+ committed bytes. The read of the configuration, the override and their
1888
+ limits are [a retire's](#retire-filter-drivers).
1889
+
1890
+ - A driver that the operator's global or system configuration defines is
1891
+ the operator's own and runs. Git LFS set up with `git lfs install` is one:
1892
+ its files are checked out as before. A driver of that name in the
1893
+ repository's configuration is replaced by the operator's values.
1894
+ - A driver only the repository's configuration defines does not run. With
1895
+ Git LFS set up by `git lfs install --local` alone, a tree OATS checks out
1896
+ holds the pointer files, not their content: run `git lfs install` for the
1897
+ operator, or `git lfs pull` in the tree.
1898
+ - A driver whose name cannot be passed on Git's command line (it holds `=`
1899
+ or is not UTF-8) cannot be overridden, so Git is not run: the spawn is
1900
+ refused with `E_WORK_INSPECTION_FAILED` and rolled back, and
1901
+ `oats worktree add` with `E_GIT_FAILED`, its tree removed.
1902
+
1903
+ <a id="no-file-monitor"></a>
1904
+ **No file monitor.** Every Git command OATS runs that reads or writes a work
1905
+ tree's files or its index runs with `core.fsmonitor=false`, so a file
1906
+ monitor command the repository's configuration names is never run: these
1907
+ checkouts and the fetch of `oats worktree add` between its two,
1908
+ `oats worktree remove`, a retire and its recovery copy, the status a spawn's
1909
+ baseline is taken from, the reads of `oats instance git` and
1910
+ `oats instance diff`, and the check `oats package add|remove` makes that
1911
+ `oats-workspace.yaml` is tracked in the checkout that holds it. The clone's Git hooks (`post-checkout` among them) are not part of
1912
+ this: they run in a checkout as they do for the operator's own Git.
1913
+
1732
1914
  After the spawn hooks succeed, the spawn fires the
1733
1915
  [`worktree` event](capabilities.md#the-worktree-event) for `work/`: the
1734
1916
  `worktree` hook of each capability the soul composes runs once, with `work/`
@@ -1904,10 +2086,17 @@ option.
1904
2086
  rework an existing one).
1905
2087
  - `--repo`: the instance's repository by default. A member key is looked up
1906
2088
  as a spawn looks up a clone (`oats-local.yaml` `clones:`, then
1907
- `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A path
1908
- (absolute, or starting with `.` or `~`) is used as given. It must be a
1909
- clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an `origin`
1910
- remote (`E_CLONE_MISMATCH`). Not a Git repository: `E_CLONE_MISSING`.
2089
+ `<deployment>/<member name>`; `E_CLONE_MISSING` when there is none). A name
2090
+ that isn't a repository key (`oats`, `awebai/oats`, `oats.git`) names no
2091
+ member and is refused as before: `E_CLONE_MISMATCH` when a clone is at its
2092
+ convention path or `clones:` names one for it, `E_CLONE_MISSING` when there
2093
+ is none. When that clone has a remote of that name (its key is the name or ends
2094
+ in `/<name>`), the refusal names the key to pass, `--repo <key>`, and the
2095
+ clone's path as the other spelling that works. It never suggests repointing
2096
+ the clone. A path (absolute, or starting with `.` or `~`) is used as given.
2097
+ It must be a clone, not a linked worktree (`E_CLONE_MISMATCH`), and have an
2098
+ `origin` remote (`E_CLONE_MISMATCH`). Not a Git repository:
2099
+ `E_CLONE_MISSING`.
1911
2100
 
1912
2101
  **What `add` does.** It writes a record, `<home>/.oats/trees/<p>.json`, in
1913
2102
  state `creating`, with its own pid and start time. Then it runs, as argument
@@ -1919,6 +2108,10 @@ git -C <home>/.work-<p> fetch --refmap= origin <base>
1919
2108
  git -C <home>/.work-<p> switch -c <branch> <the fetched commit>
1920
2109
  ```
1921
2110
 
2111
+ - Neither checkout (`worktree add`, `switch`) runs a filter driver the
2112
+ repository's configuration defines: the files are written as their
2113
+ committed bytes ([a checkout runs no filter
2114
+ driver](#checkout-filter-drivers)).
1922
2115
  - The tree starts from the remote's current state, never from a local branch
1923
2116
  of the clone, which may be stale. A fetch that fails is
1924
2117
  `E_REMOTE_UNREADABLE`; a HEAD that is not the fetched commit is
@@ -2005,6 +2198,22 @@ output. This never changes the clone's index. Cleanup grants directories
2005
2198
  owner read, write and search access, and keeps `.git` until all other entries
2006
2199
  are deleted, so a failed deletion can be retried.
2007
2200
  An unreadable branch or a failed inspection keeps the tree and record.
2201
+
2202
+ `remove` runs no file monitor the repository's configuration names
2203
+ ([no file monitor](#no-file-monitor)), and no filter driver it defines
2204
+ (`filter.<name>.clean`, `.process`): its own status of the tree, the clean
2205
+ check inside `git worktree remove` and the comparison of an unregistered
2206
+ tree's surviving files are each preceded by one read of that configuration,
2207
+ and every driver it defines is overridden to no command, [as a retire does
2208
+ it](#retire-filter-drivers). A file such a filter applies to is compared as
2209
+ its bytes are in the tree, so one that was rewritten is uncommitted work
2210
+ (`E_WORKTREE_DIRTY`)
2211
+ even when its filtered form is what the branch stores. A driver whose name
2212
+ cannot be passed on Git's command line (it holds `=` or is not UTF-8)
2213
+ refuses the removal with `E_WORK_PRESERVATION_FAILED` before Git is run on
2214
+ the tree: no files were removed, and the record is kept. The same limits
2215
+ hold: a driver written between that read and the Git command, and a
2216
+ submodule's own configuration.
2008
2217
  Failures after Git started removing files say that removal may be partial
2009
2218
  and name the retry. If Git already removed `.git` too, automatic comparison
2010
2219
  is refused: save any work and remove the directory by hand, then run
package/docs/tui.md CHANGED
@@ -1296,7 +1296,7 @@ The exit status never depends on it.
1296
1296
  - An `oats tui` started again knows nothing of the acts an earlier one
1297
1297
  sent: `Check again` there answers that the plan expired, the list shows
1298
1298
  what the kernel reports, and against an earlier one's start still running
1299
- the kernel's start lock is the only guard.
1299
+ the home's lifecycle claim is the only guard.
1300
1300
  - An agent on a machine whose OATS is older than 0.52.0: a stop interrupted
1301
1301
  there can leave `.oats-stop-pending.json` in the agent's home, and then
1302
1302
  the agent can be started but not stopped while that file exists.
package/docs/upgrading.md CHANGED
@@ -6,11 +6,11 @@ host that comes from it.
6
6
 
7
7
  ## Upgrading to the latest version
8
8
 
9
- The latest version is **OATS 0.69.12** ([release notes](release-notes/v0.69.12.md)).
10
- The 0.69.12 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
9
+ The latest version is **OATS 0.69.15** ([release notes](release-notes/v0.69.15.md)).
10
+ The 0.69.15 Desktop accepts OATS CLIs `>=0.26.0 <0.70.0`.
11
11
 
12
12
  **First, read the `## Upgrade` section of every release after yours, up to
13
- 0.69.12,** in the [release notes](release-notes/): it says what to do before
13
+ 0.69.15,** in the [release notes](release-notes/): it says what to do before
14
14
  the CLI changes, and what else must change with it (the Desktop, another
15
15
  tool, a package pin). [Coming from an older version](#coming-from-an-older-version)
16
16
  names the releases that ask for more than the steps below. `oats version`
@@ -19,8 +19,8 @@ prints the version you have.
19
19
  Then, on each host:
20
20
 
21
21
  ```sh
22
- # 0. where the Desktop is installed: Desktop 0.69.12 first
23
- npm install -g @awebai/oats@0.69.12 # 1. the CLI
22
+ # 0. where the Desktop is installed: Desktop 0.69.15 first
23
+ npm install -g @awebai/oats@0.69.15 # 1. the CLI
24
24
  oats update # 2. in each deployment: the plan, then it asks before it runs
25
25
  oats doctor # 3. in the same deployment
26
26
  ```
@@ -122,6 +122,8 @@ oats session start --home <absolute-home>
122
122
  Read the plan before applying it. It lists every moving package module,
123
123
  skill/inject/hook changes and provider adoption decisions, modules kept
124
124
  because their package is no longer locked, and member drift for information.
125
+ A kept package module moves only by a respawn; `oats session start` and
126
+ `restart` say so in one warning that names each one.
125
127
  One provider refusal refuses the whole move. A running or unreadable session
126
128
  refuses with `E_SESSION_RUNNING`; stop it first. A stale plan returns
127
129
  `E_PLAN_STALE` and a fresh plan to review.
@@ -202,6 +204,19 @@ of the Desktop and the CLI, and an optional package pin. A change a script
202
204
  must follow is in its release's Upgrade section whether or not it is listed
203
205
  here.
204
206
 
207
+ - **[0.69.15](release-notes/v0.69.15.md#upgrade):** Node 22.5.0 or later
208
+ before the CLI; on a shared host, `chmod -R go-rwx` each turn-record root;
209
+ a record root is written from one machine at a time; release a schedule
210
+ slot an earlier OATS left without its record (`oats doctor` lists it).
211
+ - **[0.69.14](release-notes/v0.69.14.md#upgrade):** 0.69.13 was tagged but
212
+ never published, so its steps (below) are this release's; the remaining
213
+ state-changing commands refuse a flag they do not define.
214
+ - **[0.69.13](release-notes/v0.69.13.md#upgrade):** the catalog pins
215
+ oats.framework 1.23.0. Remove a sweep lock (`~/.oats/session-resume/lock`)
216
+ or a home's start lock (`<home>/.oats-start.lock`) an earlier OATS left;
217
+ check each `git:` package pin names its own id; a deployment of OATS's
218
+ own workspace takes the four hand steps for the reviewer soul's new name,
219
+ then respawns its homes onto the new souls and starts a dispatcher.
205
220
  - **[0.69.12](release-notes/v0.69.12.md#upgrade):** the catalog pins
206
221
  oats.okf 5.8.0, oats.aweb 1.37.0 and oats.framework 1.22.1. Where
207
222
  `oats.aweb-tasks` is composed, readiness warns until the host wake daemon
@@ -552,6 +567,22 @@ resolve, or a bridge that cannot be read). A folder that does not exist or
552
567
  holds no bridge is not a skew, and it says nothing about it. The warnings are
553
568
  in the text output only; `oats doctor --json` does not carry them.
554
569
 
570
+ `oats doctor` also reports this machine's session resume lock when it needs a
571
+ person, as a `resume-lock-stuck` problem with the path and what to do: after
572
+ an upgrade that is a lock directory left by the earlier OATS
573
+ (`~/.oats/session-resume/lock/`), which `oats session resume` refuses with
574
+ `E_RESUME_LOCK_STUCK` and never removes. Remove the directory once no earlier
575
+ `oats` is running on the machine
576
+ ([The sweep](execution-targets.md#the-sweep)).
577
+
578
+ `oats doctor` reports a schedule slot whose record cannot be read as a
579
+ `schedule-slot-unreadable` problem, naming the deployment, the job and the
580
+ remedy. After an upgrade that is a slot directory an earlier OATS left
581
+ without its `owner.json`. The tick reports that job invalid and runs the
582
+ deployment's other jobs. Check `oats schedule show <id>`; once its last run
583
+ is not running, `oats schedule reconcile <id> --clear` releases the slot
584
+ ([Schedules](schedules.md#files)).
585
+
555
586
  ## After a change of Node version
556
587
 
557
588
  Two paths are written into things that outlive a command: the kernel's, and
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.22.1 # bare version → resolves through the official catalog
57
+ oats.framework: v1.23.0 # bare version → resolves through the official catalog
58
58
  oats.okf: v5.8.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
@@ -336,6 +336,10 @@ output, `timeout` for a timeout). The partial cache, its fetch mode and its
336
336
  commit pins are preserved, and a later read can retry the version probe.
337
337
  This also applies to library reads without a session. A cache already using
338
338
  whole trees stays in that mode when a later probe finds a newer Git.
339
+ With an older Git, a command says so once, however many repositories it
340
+ fetches: one `oats: warning` line naming the Git version and the 2.45 floor,
341
+ and saying that OATS fetches whole trees instead. A Git of 2.45 or later
342
+ removes the line.
339
343
 
340
344
  **Repo-owned capabilities.** `private: true` in a capability's `oats.json`
341
345
  makes it **repo-owned**: it is listed like any other capability (with
@@ -418,6 +422,23 @@ So the framework's own souls say `oats.okf: { from: package }` even though
418
422
  member soul that is the expert in that capability (`oats-okf-expert`,
419
423
  `oats-aweb-expert`, …), discoverable at latest state like any member soul.
420
424
 
425
+ **OATS's coordination is a member copy of the engineering template.** The
426
+ `oats` repository keeps its own copy of
427
+ [oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
428
+ at template-v3.0.1, adapted to OATS: `oats.engineering-expert`,
429
+ `oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
430
+ `oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
431
+ `capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
432
+ `capabilities/THIRD-PARTY-NOTICES.md` the sources four of the build skills and the
433
+ developer's quality floor adapt. `oats.build` holds the build skills, and every soul that
434
+ builds composes it: the developers, and the engineering experts that build their own
435
+ specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies; the
436
+ landing rules point at the lane map, which stays the one home of OATS's lanes.
437
+ The reviewer is the template's `code-reviewer` soul, in `souls/`. The workspace
438
+ doesn't pin the `oats.engineering` package, frozen at v1.18.0
439
+ ([official catalog](official-catalog.md#coordination-templates)), so each of
440
+ those ids has one source here: the member copy.
441
+
421
442
  ## Packages, lock, catalog
422
443
 
423
444
  `packages:` values have two forms, a **bare version** resolved through the
@@ -438,6 +459,7 @@ the workspace's slot default):
438
459
  ```
439
460
  from: package → some locked package provides `name` else E_PACKAGE_MISSING (run `oats sync`)
440
461
  → read its manifests at the locked commit; the lock's capability list must match else E_PACKAGE_INTEGRITY
462
+ → at spawn, the package tree at the locked commit must digest to the lock's integrity else E_PACKAGE_INTEGRITY
441
463
  → copy; record package/version/commit/digest
442
464
  from: <repo> → <repo> is a CONFIRMED member else E_NOT_A_MEMBER / E_MEMBERSHIP_UNCONFIRMED
443
465
  (or `here`) → it has capabilities/<name>/oats.json else E_CAPABILITY_MISSING
@@ -527,7 +549,9 @@ souls: # per soul pattern: its default team an
527
549
  `<member>/*` or `<package>/*`, and `"*"`, with the member and package names
528
550
  `souls.disabled` uses (a member's name is its repository's). A bare soul name
529
551
  is refused. A key that is neither a pattern nor a soul the workspace offers
530
- is the warning `team-soul-unknown` (a typo guard).
552
+ is the warning `team-soul-unknown` (a typo guard). So is a `<prefix>/*`
553
+ pattern whose prefix matches no soul the workspace offers: a typo, or a
554
+ member or package that was renamed or dropped. `"*"` never warns.
531
555
  - **The most specific key wins outright** for a soul's teams, and lists never
532
556
  merge: the soul's own key, then `<member|package>/*`, then `"*"`. The
533
557
  default comes from the most specific key that sets one. So
@@ -820,8 +844,10 @@ PATH STATE VIA
820
844
  ```
821
845
 
822
846
  **Concurrency.** Every change runs under `~/.oats/config/deployments.lock`
823
- (waiting up to 3 s for it) and re-reads the file inside it, and each write
824
- replaces the file atomically. Readers take no lock: they read a regular file
847
+ (waiting up to 3 s for a holder that is running) and re-reads the file inside
848
+ it, and each write replaces the file atomically. The lock is a file that names
849
+ the process holding it: one left by a command that was killed is taken over by
850
+ the next command. Readers take no lock: they read a regular file
825
851
  only, without following a link, up to 1 MiB. A missing file is an empty list.
826
852
 
827
853
  **Errors:**
@@ -830,7 +856,7 @@ only, without following a link, up to 1 MiB. A missing file is an empty list.
830
856
  |---|---|
831
857
  | `E_DEPLOYMENTS_INVALID` | the file is not JSON, not an object, a link, over 1 MiB, or a row breaks the schema: "`<file>` cannot be read as this computer's deployments list (`<reason>`). Fix it, or move it aside and run `oats deployments add <dir>` for each deployment; nothing was changed" |
832
858
  | `E_DEPLOYMENTS_VERSION` | `schemaVersion` is newer than this oats reads: "`<file>` was written by a newer oats (schema `<n>`); upgrade oats". The file is never rewritten down |
833
- | `E_DEPLOYMENTS_BUSY` | the lock is still held after 3 s: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed" |
859
+ | `E_DEPLOYMENTS_BUSY` | the lock is still held by a running process after 3 s, or cannot be judged: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed". `<why>` says what was found: `pid <n> holds it`; `the record at <lock> is unreadable` (remove that file); that it cannot be established whether pid `<n>` still runs (check that pid by hand, then remove the file); or `<lock> is a lock directory written by an earlier kernel` (remove the directory once no older oats is running) |
834
860
  | `E_DEPLOYMENTS_WRITE` | the write failed, or would make the file larger than 1 MiB: "cannot write `<file>` (`<system error>`); nothing was changed" |
835
861
  | `E_DEPLOYMENTS_IMPORT` | `~/Agents` cannot be read for the first-use import: "cannot read `<dir>` to import its deployments (`<system error>`); make it readable, or move it aside, and retry; nothing was changed" |
836
862
 
package/lib/claim.mjs CHANGED
@@ -1,10 +1,11 @@
1
1
  /** The claim: one file that says which process is doing a thing that must happen once at a time.
2
2
  * One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
3
3
  * `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
4
- * `claimHomeFor`).
4
+ * `claimHomeFor`), and by the lock of the kernel's shared files and of the machine's resume sweep
5
+ * (lib/dir-lock.mjs `withDirLock`, `acquireDirLock`).
5
6
  *
6
- * Unlike lib/dir-lock.mjs, a claim left by a process that died is taken over, so a killed command
7
- * can always be run again: the owner is named by pid AND start time (processLiveness), never by a
7
+ * A claim left by a process that died is taken over, so a killed command can always be run
8
+ * again: the owner is named by pid AND start time (processLiveness), never by a
8
9
  * pid alone, and a holder whose start cannot be read is never taken for gone.
9
10
  *
10
11
  * - Taking it: the owner's facts `{ pid, processStart, nonce, at }`, with what the caller adds to
@@ -87,6 +88,13 @@
87
88
  * caller's answer for a step that could not be ended
88
89
  * (`at` is kept); `ended` is a clause naming what it
89
90
  * ended, when it ended something
91
+ * holderGone(holder) optional: whether a fact of the caller's own in the record
92
+ * says that `holder` is gone, whatever its pid reads as (the
93
+ * resume sweep's lock: taken in another boot, which no process
94
+ * outlives, while a pid and a start counted from the boot can
95
+ * both come again in the next). Asked in place of reading the
96
+ * process, by acquireClaim and by claimUnheld; such a holder
97
+ * is taken over as any gone one
90
98
  * waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
91
99
  * warnings optional array a takeover's warnings are pushed to
92
100
  * facts optional object, what the caller's claim says besides its
@@ -223,7 +231,7 @@ export function claimUnheld(path, opts, otherwise) {
223
231
  try { holder = JSON.parse(text); } catch { holder = null; }
224
232
  // readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
225
233
  if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
226
- const live = processLiveness(holder);
234
+ const live = holderLiveness(holder, opts);
227
235
  if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
228
236
  const stuck = cannotBeTakenOver(holder, 0);
229
237
  if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
@@ -231,6 +239,13 @@ export function claimUnheld(path, opts, otherwise) {
231
239
  }
232
240
  }
233
241
 
242
+ /** Whether the holder a claim record names can still act, as processLiveness answers it, for the
243
+ * caller whose refusals are `opts`: gone when its `holderGone` says so, whatever the process reads
244
+ * as. The one reading of a holder for taking a claim (takeClaim) and for reading one (claimUnheld). */
245
+ function holderLiveness(holder, opts) {
246
+ return opts.holderGone?.(holder) ? { state: "gone" } : processLiveness(holder);
247
+ }
248
+
234
249
  /** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
235
250
  * pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
236
251
  * any error that is not the kernel's. The directory exists. */
@@ -258,7 +273,7 @@ function takeClaim(path, opts, depth, endedSteps) {
258
273
  catch (e) { if (e?.code !== "EEXIST") throw e; }
259
274
  const holder = readClaim(path);
260
275
  if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
261
- const live = holder ? processLiveness(holder) : null;
276
+ const live = holder ? holderLiveness(holder, opts) : null;
262
277
  // Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
263
278
  if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
264
279
  const gone = live?.state === "gone";