@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.
- package/README.md +216 -178
- package/bin/oats.mjs +254 -201
- package/docs/capabilities.md +58 -13
- package/docs/configuration.md +63 -5
- package/docs/container.md +291 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +590 -55
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +84 -9
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +99 -32
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/schedules.md +159 -5
- package/docs/servers.md +241 -7
- package/docs/souls-and-instances.md +223 -14
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +36 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +20 -5
- package/lib/command-flags.mjs +240 -0
- package/lib/core.mjs +1004 -633
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +145 -33
- package/lib/errors.mjs +3 -2
- package/lib/harness-token.mjs +110 -0
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +165 -14
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +114 -43
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/kernel-features.mjs +4 -1
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +4 -1
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +126 -31
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +239 -21
- package/lib/servers.mjs +161 -28
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +63 -56
- package/lib/session-seen.mjs +3 -14
- package/lib/start-env.mjs +13 -7
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +68 -10
- package/package-catalog.json +1 -1
- package/package.json +5 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +93 -26
- 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,
|
|
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.
|
|
704
|
-
|
|
705
|
-
|
|
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
|
|
1239
|
-
|
|
1240
|
-
|
|
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
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
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
|
|
1908
|
-
|
|
1909
|
-
|
|
1910
|
-
|
|
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
|
|
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.
|
|
10
|
-
The 0.69.
|
|
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.
|
|
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.
|
|
23
|
-
npm install -g @awebai/oats@0.69.
|
|
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
|
package/docs/workspaces.md
CHANGED
|
@@ -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.
|
|
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
|
|
824
|
-
replaces the file atomically.
|
|
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
|
-
*
|
|
7
|
-
*
|
|
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 =
|
|
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 ?
|
|
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";
|