@awebai/oats 0.69.18 → 0.69.20
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/bin/oats.mjs +2 -2
- package/docs/capabilities.md +27 -14
- package/docs/container.md +416 -43
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +52 -31
- package/docs/desktop.md +29 -6
- package/docs/execution-targets.md +32 -17
- package/docs/implementation.md +4 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +6 -4
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/release-notes/v0.69.20.md +325 -0
- package/docs/servers.md +6 -4
- package/docs/souls-and-instances.md +37 -13
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +13 -7
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/core.mjs +33 -197
- package/lib/hook-outcome.mjs +6 -0
- package/lib/host-run.mjs +24 -19
- package/lib/instance-lifecycle.mjs +3 -1
- package/lib/instance-listing.mjs +3 -2
- package/lib/launch-prompt-fixtures/README.md +6 -0
- package/lib/retire-admission.mjs +215 -0
- package/lib/servers.mjs +3 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +130 -47
- package/lib/session-seen.mjs +3 -3
- package/package-catalog.json +3 -3
- package/package.json +3 -1
- package/packages/client/attributed-human.mjs +13 -0
- package/packages/client/deployment-data.mjs +4 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/instance-lifecycle.mjs +6 -4
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/lifecycle-confirmation.mjs +4 -2
- package/packages/client/lifecycle-contract.mjs +11 -6
- package/packages/client/remote-roster.mjs +4 -0
- package/packages/record/README.md +15 -2
- package/packages/record/docs/capture-service.md +14 -0
- package/packages/record/lib/canonical.mjs +2 -70
- package/packages/record/lib/capture-aw-unit.mjs +14 -3
- package/packages/record/lib/capture-aw.mjs +11 -5
- package/packages/record/lib/capture-health.mjs +16 -5
- package/skills/oats-getting-started/SKILL.md +3 -3
package/docs/desktop-cli-api.md
CHANGED
|
@@ -463,8 +463,10 @@ with the soul's merged payload. `oats <namespace> --help --json` answers
|
|
|
463
463
|
captured home (`details: {home, captured: true}`), the selectors
|
|
464
464
|
`--deployment`, `--resolution` and `--artifact-set` (`details.selector`), and
|
|
465
465
|
an inherited `OATS_DEPLOYMENT` or `OATS_RESOLUTION` (`details.inherited`).
|
|
466
|
-
`oats version`
|
|
467
|
-
|
|
466
|
+
`oats version` still answers. For captured homes, inspect and clean up external
|
|
467
|
+
state first; without positive proof that no spawn hook ran, retirement needs
|
|
468
|
+
`oats retire <instance> --force`. `oats status --json` names such homes in
|
|
469
|
+
`problems[]`: `legacy-captured-home {code, instances, homes,
|
|
468
470
|
message}` and `legacy-local-agents {code, dirs, instances, message}`.
|
|
469
471
|
|
|
470
472
|
<a id="observation-reuse-feature-observe-max-age-oats-0311"></a>
|
|
@@ -2166,7 +2168,7 @@ The messaging provider's `teams` operation (`messaging:teams`) is produced by
|
|
|
2166
2168
|
the provider (oats.aweb 1.17 or later), not the kernel:
|
|
2167
2169
|
|
|
2168
2170
|
```json
|
|
2169
|
-
{"defaultTeam":{"label":"
|
|
2171
|
+
{"defaultTeam":{"label":"builder","team":"builder:ana.aweb.ai","from":"deployment"},
|
|
2170
2172
|
"eligible":[{"label":"oats","team":"oats:oats.aweb.ai","joined":true}],
|
|
2171
2173
|
"joined":[{"label":"oats","team":"oats:oats.aweb.ai","identityHome":"/w/agents/oe/instances/oe-1/.aw-teams/oats","receive":"live","since":"2026-09-28T09:00:00.000Z"}],
|
|
2172
2174
|
"left":[{"label":"reviewers","team":"reviewers:acme.aweb.ai","at":"2026-09-28T09:30:00.000Z","reason":"no-longer-eligible"}],
|
|
@@ -4177,9 +4179,9 @@ whose key is not known; an unparsable ref is `E_REPO_REF`.
|
|
|
4177
4179
|
|
|
4178
4180
|
```json
|
|
4179
4181
|
{"file":"/Users/me/.oats/servers.json",
|
|
4180
|
-
"servers":[{"id":"
|
|
4181
|
-
"workspaceKey":"github.com/
|
|
4182
|
-
"target":{"sshHost":"
|
|
4182
|
+
"servers":[{"id":"devbox-aweb","sshHost":"devbox","operatorSshHost":"devbox-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"devbox",
|
|
4183
|
+
"workspaceKey":"github.com/example/app",
|
|
4184
|
+
"target":{"sshHost":"devbox","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
|
|
4183
4185
|
"unknownWorkspace":["build"]}
|
|
4184
4186
|
```
|
|
4185
4187
|
|
|
@@ -4205,18 +4207,18 @@ An envelope, `ok: true` whenever no step failed, human steps included
|
|
|
4205
4207
|
([servers.md](servers.md#connect-a-machine) has what each step does):
|
|
4206
4208
|
|
|
4207
4209
|
```json
|
|
4208
|
-
{"id":"
|
|
4210
|
+
{"id":"devbox-aweb","ready":false,
|
|
4209
4211
|
"registration":null,
|
|
4210
4212
|
"steps":[{"step":"ssh","status":"ok"},
|
|
4211
4213
|
{"step":"oats","status":"done","detail":"installed @awebai/oats 0.39.0 (was missing)"},
|
|
4212
4214
|
{"step":"git","status":"needs-human","code":"E_REMOTE_UNREADABLE",
|
|
4213
|
-
"detail":"cannot read remote https://github.com/
|
|
4214
|
-
"remedy":"on
|
|
4215
|
+
"detail":"cannot read remote https://github.com/example/app (auth): on macOS a session without a terminal …",
|
|
4216
|
+
"remedy":"on devbox: on macOS a session without a terminal … (`gh auth login --insecure-storage`, then `gh auth setup-git`), or use an SSH key the session can reach: …",
|
|
4215
4217
|
"hint":"keychain-non-interactive"},
|
|
4216
4218
|
{"step":"deployment","status":"skipped","detail":"waits for git"},
|
|
4217
4219
|
{"step":"register","status":"skipped","detail":"waits for git"},
|
|
4218
4220
|
{"step":"readiness","status":"skipped","detail":"waits for git"}],
|
|
4219
|
-
"human":["on
|
|
4221
|
+
"human":["on devbox: on macOS a session without a terminal … or the desktop login's ssh-agent (point SSH_AUTH_SOCK at it in the shell's startup file)"]}
|
|
4220
4222
|
```
|
|
4221
4223
|
|
|
4222
4224
|
- `steps` is always the six steps `ssh`, `oats`, `git`, `deployment`,
|
|
@@ -5675,6 +5677,9 @@ had begun.
|
|
|
5675
5677
|
| `E_AMBIGUOUS` | yes | yes |
|
|
5676
5678
|
| `E_SNAPSHOT_UNKNOWN` | yes | yes |
|
|
5677
5679
|
|
|
5680
|
+
`E_UNIDENTIFIED_INSTANCE_HOME` includes cleanup-hook admission in both retire
|
|
5681
|
+
plan and apply; the refusal returns no work facts when the home cannot be identified.
|
|
5682
|
+
|
|
5678
5683
|
`E_HOME_NOT_OWNED` is the answer of every command that takes a home's
|
|
5679
5684
|
lifecycle claim (a start, a resume, a stop, a retire, an upgrade) when the
|
|
5680
5685
|
user it runs as does not own the home. It is answered before the claim is
|
|
@@ -6578,13 +6583,10 @@ message names the entry or the state that could not be read, or the directory
|
|
|
6578
6583
|
Git reads as the top level of a `work/` whose `core.worktree` names another
|
|
6579
6584
|
one),
|
|
6580
6585
|
`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
|
|
6581
|
-
`E_UNIDENTIFIED_INSTANCE_HOME` (a
|
|
6582
|
-
|
|
6583
|
-
`instance.json`
|
|
6584
|
-
|
|
6585
|
-
([capabilities.md](capabilities.md#manifest)), until `--force`;
|
|
6586
|
-
a home whose `instance.json` [cannot be read](#unreadable-record), `--plan`
|
|
6587
|
-
and `--force` included),
|
|
6586
|
+
`E_UNIDENTIFIED_INSTANCE_HOME` (a missing or unusable cleanup record, or
|
|
6587
|
+
recorded hooks that cannot run without proof that no cleanup is owed, until
|
|
6588
|
+
`--force`; a home whose `instance.json` [cannot be read](#unreadable-record)
|
|
6589
|
+
refuses even with `--plan` or `--force`),
|
|
6588
6590
|
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
|
|
6589
6591
|
home is running or scheduled, or a stop of it is running, `--force`
|
|
6590
6592
|
included: one retire or stop of a home at a time, above; or, feature
|
|
@@ -6592,8 +6594,20 @@ included: one retire or stop of a home at a time, above; or, feature
|
|
|
6592
6594
|
hooks, a row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
6593
6595
|
cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
|
|
6594
6596
|
group whose leader's start cannot be read, until `--force`; every one is
|
|
6595
|
-
answered before any effect and carries [`details.holder`](#busy-holder)).
|
|
6596
|
-
|
|
6597
|
+
answered before any effect and carries [`details.holder`](#busy-holder)).
|
|
6598
|
+
|
|
6599
|
+
Hook admission refuses both `--plan` (including Desktop Remove) and apply
|
|
6600
|
+
before anything is stopped, run or removed, children included. Causes include
|
|
6601
|
+
homes spawned before `capabilityRuntime`, recorded retire hooks without a
|
|
6602
|
+
context repository (recorded or identified by Git for its own worktree),
|
|
6603
|
+
and captured homes from before 0.26 without positive proof that no spawn hook ran. An ordinary home's explicit capability set with
|
|
6604
|
+
no retire hooks proves no hook is owed. Captured proof also excludes any
|
|
6605
|
+
recorded hook intents, failures or lifecycle cleanup debt. The refusal names
|
|
6606
|
+
known capabilities, external identities/memberships at risk, and the remedy:
|
|
6607
|
+
clean up with the provider's tooling, then `oats retire <instance> --force`.
|
|
6608
|
+
See [the cleanup rule](capabilities.md#manifest).
|
|
6609
|
+
|
|
6610
|
+
The codes a retire answers only before any effect are
|
|
6597
6611
|
[one list](#before-effect-codes). A recovery whose Git status disagrees with
|
|
6598
6612
|
the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
|
|
6599
6613
|
source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
|
|
@@ -7175,7 +7189,7 @@ whatever the rows say:
|
|
|
7175
7189
|
| `already-running` | none |
|
|
7176
7190
|
| `skipped` | `not-seen-recently` (the sweep cannot vouch for this loss: OATS never saw the home running for its current start, an earlier sweep already answered the loss, the loss was first seen 24 hours ago or more, or, within one boot, it was first seen 24 hours or more after the last running look; with a `message` that says which, nothing started: [Which losses come back](execution-targets.md#which-losses-come-back)), `unknown` (running reads `null`, or the start could not establish it: `code` `E_SESSION_UNKNOWN`), `start-busy` (`E_SESSION_START_BUSY`: a concurrent start), `not-lost` (`E_RESUME_NOT_LOST` or `E_SESSION_RUNNING`, or any refusal of a home that is gone: it stopped, started or was removed between the read and the start), `lifecycle-busy` (OATS 0.69.2: OATS is stopping, upgrading or retiring the home, or its retire is owed; read from its row, with a `message`, or answered by its start, with the start's `code`, `E_INSTANCE_RETIRING` or `E_LIFECYCLE_BUSY`, and `message`; nothing started) |
|
|
7177
7191
|
| `blocked` | `resume-confirmation` (Claude's resume-cost dialog: the session runs and waits for its human), `launch-prompt` (`code` `E_SPAWN_INCOMPLETE`, with `launchPrompts`: the session is kept) |
|
|
7178
|
-
| `refused` | `start-refused` (`code` and `message`: the start's own refusal), `refused-
|
|
7192
|
+
| `refused` | `start-refused` (`code` and `message`: the start's own refusal, and `nextAttemptAt`: a refused start launched nothing, so it does not answer the loss, and a sweep tries it again no sooner than that time), `start-refused-retrying` (an earlier sweep in this boot was refused for this home and start and its delay has not run: reported again with that `code`, `message` and `nextAttemptAt`, nothing started; the delay is 1 minute after the first refusal and doubles at each further one, up to 15 minutes, and the retries end when the loss is `not-seen-recently`), `keeps-getting-lost` (sweeps started this home 3 times in the last hour and it was lost again each time: nothing started, no `code`, a `message` that says so and `nextAttemptAt`, when the oldest of those starts is an hour old and a sweep starts the home again; a home that used up its starts 3 hours in a row is given up: the row has no `nextAttemptAt`, its `message` says a person starts it, and the loss is answered) |
|
|
7179
7193
|
|
|
7180
7194
|
The kernel defines every `sessionEnd`, `resume` and row name in one
|
|
7181
7195
|
module, `lib/session-resume-contract.mjs`; a change to one is a contract
|
|
@@ -7188,11 +7202,15 @@ whatever the rows say:
|
|
|
7188
7202
|
runs in the OATS tmux server's cgroup, not a scope of its own, and why).
|
|
7189
7203
|
Each start still records it in its own home's events. `--plan` has none.
|
|
7190
7204
|
- A lost home is answered with the first that applies: `lifecycle-busy`,
|
|
7191
|
-
`not-seen-recently`, `refused-
|
|
7192
|
-
start. A sweep that is not a plan answers each lost home
|
|
7193
|
-
sweep answers that loss `not-seen-recently`.
|
|
7194
|
-
not answer
|
|
7195
|
-
|
|
7205
|
+
`not-seen-recently`, `start-refused-retrying`, `keeps-getting-lost`, then
|
|
7206
|
+
its start. A sweep that is not a plan answers each lost home it started
|
|
7207
|
+
once: a later sweep answers that loss `not-seen-recently`. Four rows do
|
|
7208
|
+
not answer the loss, and a later sweep reads the home again:
|
|
7209
|
+
`lifecycle-busy` (whatever OATS was doing to the home decides what it is
|
|
7210
|
+
next), `start-refused` and `start-refused-retrying` (nothing was
|
|
7211
|
+
launched), and `keeps-getting-lost` (until its hour has passed; one
|
|
7212
|
+
without `nextAttemptAt` does answer it). The counts and the delays are
|
|
7213
|
+
one boot's: a reboot starts them again.
|
|
7196
7214
|
- A home whose self-retire is scheduled or owed reads no `sessionEnd`; a
|
|
7197
7215
|
launched one that does not run is listed `skipped`, `lifecycle-busy`, as
|
|
7198
7216
|
a lost one is.
|
|
@@ -7275,12 +7293,15 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
|
|
|
7275
7293
|
nothing of how far it got. A child that ended without an answer is
|
|
7276
7294
|
reported under that code too, in `sweep.error` or on stderr, and does not
|
|
7277
7295
|
end the run.
|
|
7278
|
-
- **What it runs, in order.** The resume sweep
|
|
7296
|
+
- **What it runs, in order.** The resume sweep (`oats session resume`).
|
|
7279
7297
|
Then at second 0 of every minute: `oats schedule tick --host` when the
|
|
7280
|
-
host schedule registry lists a scope, and
|
|
7281
|
-
|
|
7282
|
-
|
|
7283
|
-
|
|
7298
|
+
host schedule registry lists a scope, and the resume sweep again, which
|
|
7299
|
+
starts a home lost while the host runs, within the sweep's own bounds, and
|
|
7300
|
+
records what runs for a later sweep. Each is a child process. A minute
|
|
7301
|
+
whose tick still runs is skipped, and a sweep that still runs is not run
|
|
7302
|
+
beside itself; a minute missed is never replayed. With no scope registered
|
|
7303
|
+
it ticks nothing and says so. A sweep is said on stderr when its outcomes
|
|
7304
|
+
differ from those of the sweep before.
|
|
7284
7305
|
- **On SIGTERM or SIGINT.** No further minute starts; a tick or a sweep that
|
|
7285
7306
|
runs gets 10 seconds to finish naturally, then a private admission fence
|
|
7286
7307
|
stops further launches and owned child groups get a further 5-second
|
|
@@ -7296,7 +7317,7 @@ this machine's: it takes no `--server`. It runs until SIGTERM or SIGINT.
|
|
|
7296
7317
|
modes. **The answer** is written once, when the run ends:
|
|
7297
7318
|
`result` `{schemaVersion: 1, plan: false, signal, warnings, sweep, ticks, stopped}`.
|
|
7298
7319
|
`signal` is `"SIGTERM"` or `"SIGINT"`; `warnings` an array of strings;
|
|
7299
|
-
`sweep` the sweep's own `result`
|
|
7320
|
+
`sweep` the first sweep's own `result`
|
|
7300
7321
|
([The machine sweep](#the-machine-sweep-oats-session-resume)), or
|
|
7301
7322
|
`{error: {code, message}}` when it failed (the run goes on); `ticks`
|
|
7302
7323
|
`{run, skipped, failed, noScope}`, minutes counted; `stopped` one row per
|
package/docs/desktop.md
CHANGED
|
@@ -686,10 +686,10 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
|
|
|
686
686
|
One sentence above them says what a machine is: "Each machine runs this
|
|
687
687
|
workspace in a folder of its own. The instances under a machine run on
|
|
688
688
|
that machine." **All** stacks one section per deployment, each headed by
|
|
689
|
-
its machine and folder ("This Mac · ~/acme", "
|
|
690
|
-
with "Instances on this machine" or "Instances on
|
|
691
|
-
each deployment has a tab of its own, named by its machine ("
|
|
692
|
-
"This Mac ·
|
|
689
|
+
its machine and folder ("This Mac · ~/acme", "devbox · ~/northwind"),
|
|
690
|
+
with "Instances on this machine" or "Instances on devbox" under it. Then
|
|
691
|
+
each deployment has a tab of its own, named by its machine ("devbox";
|
|
692
|
+
"This Mac · acme-2" when this Mac holds two). A workspace with one
|
|
693
693
|
deployment shows just that deployment's tab, its tree under the same
|
|
694
694
|
heading. The tab you chose is
|
|
695
695
|
remembered per workspace. With two or more deployments, the sidebar's
|
|
@@ -712,7 +712,7 @@ heading. The tab you chose is
|
|
|
712
712
|
can't read other machines. A server that can't be reached stays under the
|
|
713
713
|
workspace it last reported, marked "remembered".
|
|
714
714
|
- **The list of workspaces.** Each workspace names its machines on one line ("This Mac ·
|
|
715
|
-
|
|
715
|
+
devbox"), with a mark when one of them isn't live.
|
|
716
716
|
- **Not matched to a workspace.** A deployment that can't be matched is
|
|
717
717
|
listed on its own under that heading in the list, with its machine and
|
|
718
718
|
a short reason; choosing it opens its tab on the Machines tab. When this
|
|
@@ -973,13 +973,20 @@ right of its parent, and related instances are grouped together. Siblings are
|
|
|
973
973
|
joined by a dotted line through their dots. A parent's line to its children
|
|
974
974
|
runs just to the right of the dotted line, so the two never merge.
|
|
975
975
|
|
|
976
|
+
The newest instance is on top: the tree is in spawn order, newest first, at
|
|
977
|
+
every level. A group of related instances sits where its first instance's
|
|
978
|
+
spawn time puts it, so spawning a child doesn't move the group, and starting
|
|
979
|
+
or stopping an instance moves nothing. Instances spawned at the same moment
|
|
980
|
+
are in name order, and an instance whose spawn time can't be read comes after
|
|
981
|
+
every one whose time can.
|
|
982
|
+
|
|
976
983
|
A parent's line joins only the children that do its work. When the instances'
|
|
977
984
|
OATS has the `instance-same-work` feature, a child the kernel reports as doing
|
|
978
985
|
its parent's work (`sameWork: true` in its row, set with `oats spawn …
|
|
979
986
|
--same-work` or `oats instance same-work <instance> on`) is joined to its
|
|
980
987
|
parent, and any other child keeps its place and its indent with no line to its
|
|
981
988
|
parent. Under one parent the joined children are listed first, then the others,
|
|
982
|
-
each part
|
|
989
|
+
each part newest first, so the parent's line ends at its last joined child and
|
|
983
990
|
never passes one it doesn't join. Nothing else marks the flag: no label, no
|
|
984
991
|
tag, and nothing for a screen reader, which still hears each child "under" its
|
|
985
992
|
parent in the command palette. The command palette draws the same lines, in
|
|
@@ -1094,6 +1101,22 @@ computer, and for an instance on a server, on that server too; until then the
|
|
|
1094
1101
|
buttons are disabled and the dialog says which is missing. An instance whose
|
|
1095
1102
|
home is being spawned or retired can't be given a colour meanwhile.
|
|
1096
1103
|
|
|
1104
|
+
## An instance's owning human
|
|
1105
|
+
|
|
1106
|
+
Where the messaging capability attributes an instance's messaging identity to
|
|
1107
|
+
a human, the instance panel's Lineage section shows that human first, as
|
|
1108
|
+
**Owning human**, above the instance's parent and sibling. It is the
|
|
1109
|
+
`attributedHuman` of the instance's row in `oats status --json`, and of a
|
|
1110
|
+
server's row for an instance on a server
|
|
1111
|
+
([Attributed human](desktop-cli-api.md#attributed-human)), shown as OATS
|
|
1112
|
+
reports it. The instance is still named by its own name everywhere: the
|
|
1113
|
+
sidebar, its terminal tab, the command palette and the panel's header.
|
|
1114
|
+
|
|
1115
|
+
An instance with no human attributed shows no such field, and nothing says
|
|
1116
|
+
one is missing: that is the usual case, on a deployment whose messaging
|
|
1117
|
+
capability supplies no human identities and for an older OATS that doesn't
|
|
1118
|
+
report it. A label OATS would not show as one line of text reads the same way.
|
|
1119
|
+
|
|
1097
1120
|
## Identity marks and harness badges
|
|
1098
1121
|
|
|
1099
1122
|
Souls, capabilities and workspaces carry a coloured two-letter mark beside
|
|
@@ -1350,7 +1350,9 @@ The sweep resumes a lost home only when OATS can vouch for the loss, from
|
|
|
1350
1350
|
what its own reads of that home saw (`oats status`, OATS Desktop and `oats
|
|
1351
1351
|
tui` reading it, and the sweep's own read). All four must hold:
|
|
1352
1352
|
|
|
1353
|
-
1. OATS saw the home running for its current start.
|
|
1353
|
+
1. OATS saw the home running for its current start. A start the sweep itself
|
|
1354
|
+
made counts as seen, so a home that is lost again before any read saw it
|
|
1355
|
+
running is still started again, within the hour's count below.
|
|
1354
1356
|
2. No earlier sweep answered this loss. A sweep answers each lost home once,
|
|
1355
1357
|
whatever it did with it (resumed, started fresh, blocked, refused or
|
|
1356
1358
|
skipped), except a home it skipped because OATS was stopping, upgrading
|
|
@@ -1454,21 +1456,34 @@ refused. A home removed between the read and its start is reported
|
|
|
1454
1456
|
`resume-lock-stuck` problem, with the path and what to do. It reads the
|
|
1455
1457
|
lock and takes nothing. A free lock, a sweep that runs and a lock a gone
|
|
1456
1458
|
sweep left are not reported.
|
|
1457
|
-
- A loss is answered once:
|
|
1458
|
-
|
|
1459
|
-
a reboot; a later sweep reports it `not-seen-recently`. A
|
|
1460
|
-
skip
|
|
1461
|
-
|
|
1462
|
-
|
|
1463
|
-
|
|
1464
|
-
|
|
1465
|
-
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
1459
|
+
- A loss a sweep started is answered once: whether that start resumed, came
|
|
1460
|
+
up fresh or is blocked, no later sweep starts it again, in this boot or
|
|
1461
|
+
after a reboot; a later sweep reports it `not-seen-recently`. A
|
|
1462
|
+
`lifecycle-busy` skip answers nothing: the next sweep reads the home again.
|
|
1463
|
+
- A refused start answers nothing either. It launched nothing, and what
|
|
1464
|
+
refused it (a launch variable not set, no wake broker yet) is how the host
|
|
1465
|
+
was at that moment. The sweep notes it and tries that home again no sooner
|
|
1466
|
+
than 1 minute later, then 2, 4 and 8, and every 15 minutes after that; a
|
|
1467
|
+
sweep that runs before then reports it `start-refused-retrying`, with the
|
|
1468
|
+
refusal's code and the time of the next attempt, and starts nothing. The
|
|
1469
|
+
retries end when the loss is 24 hours old (`not-seen-recently`).
|
|
1470
|
+
- A home lost unexpectedly is started by sweeps at most 3 times in an hour. A
|
|
1471
|
+
home lost again after each resume (a harness that crashes the host or its
|
|
1472
|
+
terminal server, say) is then reported `keeps-getting-lost`, with the time
|
|
1473
|
+
the oldest of those starts is an hour old: a sweep starts the home again
|
|
1474
|
+
then. Every sweep start that launched something counts (resumed, fresh or
|
|
1475
|
+
blocked), by home, as soon as that start has answered, so a sweep killed
|
|
1476
|
+
while other starts run has counted it; a refused, skipped or busy one does
|
|
1477
|
+
not. The count and the retry delays are kept for one boot: a reboot starts
|
|
1478
|
+
both again. `oats session start --resume` run by hand is neither bounded
|
|
1479
|
+
nor counted.
|
|
1480
|
+
- That does not go on for ever. A home that uses up its 3 starts in 3 hours
|
|
1481
|
+
in a row is given up: its row has no time of a next attempt, the loss is
|
|
1482
|
+
answered, and no sweep starts it again until a person does. Hours are in a
|
|
1483
|
+
row when each begins less than an hour after the one before it cleared.
|
|
1484
|
+
Only an hour without one begins the count again: no start does. A person
|
|
1485
|
+
may start a home that was given up, and if it is lost again in a used-up
|
|
1486
|
+
hour it is given up again at once.
|
|
1472
1487
|
A stop of the current start with the host is different: a successful
|
|
1473
1488
|
restore after that administrative stop neither spends nor resets the
|
|
1474
1489
|
crash budget, and the crash ceiling cannot prevent it. A failed or
|
|
@@ -1505,7 +1520,7 @@ refused. A home removed between the read and its start is reported
|
|
|
1505
1520
|
restarts on the same kernel, including when read from older qualified
|
|
1506
1521
|
records. A kernel reboot gives a fresh budget. Loss judgements remain
|
|
1507
1522
|
per start, and a running look of a newly resumed start resets its prior
|
|
1508
|
-
seen/lost judgement. Every
|
|
1523
|
+
seen/lost judgement. Every `oats host run` invokes the sweep at its start and each minute;
|
|
1509
1524
|
successful restores after a host stop remain eligible as described above.
|
|
1510
1525
|
- The lock, the per-boot note and the record of what status saw live in
|
|
1511
1526
|
`session-resume/` under `~/.oats` (`$OATS_HOME_DIR` when set). All three
|
package/docs/implementation.md
CHANGED
|
@@ -84,7 +84,7 @@ and the rules its tests pin.
|
|
|
84
84
|
| `lib/` | the kernel (below) |
|
|
85
85
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
86
86
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
87
|
-
| `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build
|
|
87
|
+
| `capabilities/` | this repository's own member capabilities, discovered at the member's latest state: `oats-desktop-ui`, `oats-workspace-experts`, and the copy of the engineering template (`oats-dispatcher`, `oats-engineering-expert`, `oats-developer`, `oats-build`, `oats-code-review`, `oats-maintainer`, `oats-landing-rules`; the release it came from in `TEMPLATE-RELEASE`, its MIT notice in `TEMPLATE-LICENSE`, the notices of the sources its build skill and its quality floor adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
|
|
88
88
|
| `mirrors/` | copies of the official packages' capabilities at their pinned tags: release-lane and test material, kept out of `capabilities/` so member discovery does not list them a second time; not shipped in the npm package. The three OKF mirrors (`oats-okf*`) are generated by `scripts/check-okf-mirror.mjs` and checked byte for byte against `scripts/okf-source-inventory.json`; the other seven (`oats-aweb`, `oats-aweb-tasks`, `oats-folio`, `oats-library`, `oats-jira`, `oats-linear`, `oats-authoring`) are copied from their tags by hand and checked for their version only, until every mirror has that check (oats-project/oats#1848) |
|
|
89
89
|
| `oats-package/` | the `oats.framework` package |
|
|
90
90
|
| `souls/` | this repository's own souls (a workspace member) |
|
|
@@ -128,11 +128,11 @@ and the rules its tests pin.
|
|
|
128
128
|
| `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 |
|
|
129
129
|
| `soul-launch-verbs.mjs` | `oats soul launch set\|remove`, the writer of `souls.launch` |
|
|
130
130
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer; a job's slot (`acquireJobLock`, `releaseJobLock`) is taken by renaming a directory that already holds its record into place, and released by renaming it out before it is removed, so it is never there without its record; a slot whose record cannot be read (`unreadableSlot`, over `jobLockInfo`) marks only its job invalid in the tick, is released by `reconcile --clear`, and is doctor's `schedule-slot-unreadable` problem; a slot whose schedule is gone (`scheduleAbsence`: a local one not in `oats-schedules.json`; a workspace one not in the saved snapshot, its member read at a commit and no problem of it that could hide one; never refreshed there) is counted until reconcile --clear releases it with the job's attempt and state (`orphanSlot`, `reconcileOrphanSlot`), and is doctor's `schedule-slot-orphaned` problem, as is a workspace one absent that cannot be shown gone |
|
|
131
|
-
| `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`:
|
|
131
|
+
| `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`: local listings and the sweep recording homes it started; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
|
|
132
132
|
| `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 |
|
|
133
133
|
| `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 |
|
|
134
134
|
| `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 |
|
|
135
|
-
| `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep
|
|
135
|
+
| `host-run.mjs`, `host-run-work.mjs`, `host-run-child.mjs`, `host-run-admission.mjs`, `host-stop-child.mjs` | `oats host run` (#1789), the foreground entry for a host with no timer (a container): its refusals before any effect (inside an instance session, an active host timer, another host run), its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot, as the resume sweep's), the sweep at the start, then the tick and the sweep each minute, every one an owned child group (`host-run-work.mjs`) so that the loop stays free for the signal. On SIGTERM no minute is armed; active work gets 10 s, then the private scratch-file fence is closed and owned groups get 5 s of cancellation. The private bootstrap carries the fence only through kernel child argv, never public flags or environment. A detached kernel group atomically registers its pid/start and waits for the owner to verify it and acknowledge responsibility before importing launch-capable code; cancellation therefore does not depend on an intermediate supervisor remaining responsive. Schedule/trigger loops, resume batches and core launch boundaries read it synchronously, because a synchronous tick cannot service IPC while a command runs. Interrupted attempts remain unknown. The host-run claim stays held until owned work ends. After a final bounded listing, each running home is stopped by a private child of its own (`host-stop-child.mjs`: `core.mjs` `stopInstanceSession` with `withHost`, whose stop record asks for a resume and is written before the signal, read by `session-end.mjs` as `lost`). The clock, the timer, the children and the signal are options, for its tests |
|
|
136
136
|
| `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 |
|
|
137
137
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
138
138
|
| `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 |
|
|
@@ -153,6 +153,7 @@ and the rules its tests pin.
|
|
|
153
153
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
154
154
|
| `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
|
|
155
155
|
| `retire-git-forms.mjs` | which of a retire's Git commands read no work-tree file, by their exact form: the ones `core.mjs` runs without the overrides of the repository's filter drivers |
|
|
156
|
+
| `retire-admission.mjs` | the shared internal preflight for Remove plans and retire apply: the record reader, cleanup descriptor validator, positive hook-cleanup proof and spawn liveness read. Both callers import it directly. `core.mjs` re-exports only its existing record readers and constants from this leaf, by reference; admission itself is not public API |
|
|
156
157
|
| `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
|
|
157
158
|
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
158
159
|
| `retire-incomplete.mjs` | retirements left open (a quarantine, a failed or interrupted self-retire) as `oats doctor`'s `retire-incomplete` problems (oats-project/oats#1747), read with `instance-listing.mjs`'s `openRetirements`, the readers of the status rows: read-only, no claim, no tmux |
|
package/docs/integrations.md
CHANGED
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 6.0
|
|
9
|
+
This is the operator guide for **oats.okf 6.2.0** (OATS **>=0.69.2**). Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
In 6.0 there is no knowledge harvester: a working instance proposes its own
|
|
12
12
|
knowledge as a pull request at its checkpoints (`oats okf propose`), and the
|
|
@@ -28,7 +28,7 @@ knowledge maintainer gates every merge.
|
|
|
28
28
|
```yaml
|
|
29
29
|
# oats-workspace.yaml (excerpt)
|
|
30
30
|
packages:
|
|
31
|
-
oats.okf: v6.0
|
|
31
|
+
oats.okf: v6.2.0
|
|
32
32
|
defaults:
|
|
33
33
|
knowledge: { oats.okf: { from: package } }
|
|
34
34
|
stores:
|
|
@@ -56,9 +56,9 @@ Upgrading from 4.x requires the ordered
|
|
|
56
56
|
just editing a version line. The package requires OATS >=0.69.2: its
|
|
57
57
|
`knowledge-maintainer` soul says `background: true`, which an older kernel
|
|
58
58
|
refuses. Upgrade OATS first, then the package. Each 5.x step is in
|
|
59
|
-
[oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.0
|
|
59
|
+
[oats.okf's CHANGELOG](https://github.com/oats-project/oats-okf/blob/v6.2.0/CHANGELOG.md).
|
|
60
60
|
|
|
61
|
-
**Upgrade to 6.0:** pin `oats.okf: v6.0
|
|
61
|
+
**Upgrade to 6.0:** pin `oats.okf: v6.2.0` and run `oats sync`. Only new
|
|
62
62
|
spawns get `oats okf propose`, the 6.0 `okf-propose` skill and the
|
|
63
63
|
spawn-recorded duty. Existing homes keep their copied provider even after a
|
|
64
64
|
session restart; a stopped 5.x home can move with `oats instance upgrade`
|
|
@@ -67,7 +67,7 @@ remedy to retire and respawn it. Harvester spawns stop: the stub soul
|
|
|
67
67
|
`oats.okf/knowledge-harvester`, kept until 7.0, refuses every spawn with
|
|
68
68
|
`E_REMOVED` and the fix. Harvesters already running keep their 5.x modules
|
|
69
69
|
and finish, or a person retires them. Then, by hand, from the deployment
|
|
70
|
-
(oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0
|
|
70
|
+
(oats.okf's [Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.2.0/README.md#upgrading-to-60)
|
|
71
71
|
has each step's commands):
|
|
72
72
|
|
|
73
73
|
1. Delete the harvester's launch preference, if any:
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ 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.
|
|
13
|
-
| `oats.okf` | `v6.0
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.26.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory`, `oats.coordination-setup` | `knowledge-theory-expert`, `oats-setup-expert` |
|
|
13
|
+
| `oats.okf` | `v6.2.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.42.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
15
|
| `oats.engineering` | `v1.18.0` (frozen: see Coordination templates) | `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.1.0` | `oats.cloning` | `cloner` |
|
|
@@ -49,7 +49,7 @@ release it came from in its description, and the copy records it as a whole in
|
|
|
49
49
|
|
|
50
50
|
| Template | Latest release | Way of working |
|
|
51
51
|
| --- | --- | --- |
|
|
52
|
-
| `oats-project/oats-engineering-coordination` | `template-
|
|
52
|
+
| `oats-project/oats-engineering-coordination` | `template-v4.0.2` | Work that lands as pull requests: a dispatcher, a lead for each effort with a tree sized to the work (alone, with short-lived probes and helpers, or with one specialist per area), whoever builds a change iterating with a fresh reviewer each round, a maintainer's green light where a lane asks for one, and every finished instance retiring itself. |
|
|
53
53
|
| `oats-project/oats-research-coordination` | `template-v2.1.2` | Work that ends in a finding or a report: a dispatcher, a research lead for each question that researches a single small angle itself or sends a researcher for each, and a verifier briefed to disprove, which checks the lead's own claims too. A report lands when the person who asked accepts it. |
|
|
54
54
|
| `oats-project/oats-scientific-research-coordination` | `template-v2.1.2` | Studies that end in claims a person is accountable for: a dispatcher, a study lead for each study, an analyst for each arm of a locked protocol, fresh study reviewers for the methods, an independent check, leakage and citations, and a record steward that locks protocols and keeps the study records. A claim lands when the scientist accepts it; one that leaves the group needs a check that isn't LLM judgement. |
|
|
55
55
|
|
|
@@ -64,7 +64,7 @@ aliases, a later decision once no workspace we know of pins it.
|
|
|
64
64
|
## Find and use packages
|
|
65
65
|
|
|
66
66
|
- A workspace pins an official package by **bare version** in its
|
|
67
|
-
`packages:` map (`oats.okf: v6.0
|
|
67
|
+
`packages:` map (`oats.okf: v6.2.0`); `oats sync` resolves it through the
|
|
68
68
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
69
69
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
70
70
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -48,14 +48,14 @@ whole organisation:
|
|
|
48
48
|
|
|
49
49
|
```yaml
|
|
50
50
|
packages:
|
|
51
|
-
oats.okf: v6.0
|
|
51
|
+
oats.okf: v6.2.0 # bare version → the official catalog
|
|
52
52
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
53
53
|
```
|
|
54
54
|
|
|
55
55
|
- **Bare version** (`v5.8.0`, `5.8.0`, `1.0.0-rc.1`): the id is looked up in
|
|
56
56
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
57
57
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
58
|
-
convention (`v5.8.0` or `oats-framework/v1.
|
|
58
|
+
convention (`v5.8.0` or `oats-framework/v1.26.0`) and the payload path. An id
|
|
59
59
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
60
60
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
61
61
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -78,9 +78,9 @@ members:
|
|
|
78
78
|
- git:github.com/acme/agents
|
|
79
79
|
- git:github.com/acme/platform
|
|
80
80
|
packages:
|
|
81
|
-
oats.framework: v1.
|
|
82
|
-
oats.okf: v6.0
|
|
83
|
-
oats.aweb: v1.
|
|
81
|
+
oats.framework: v1.26.0
|
|
82
|
+
oats.okf: v6.2.0
|
|
83
|
+
oats.aweb: v1.42.1
|
|
84
84
|
teams:
|
|
85
85
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
86
86
|
defaults:
|
|
@@ -109,7 +109,7 @@ decision recorded in the lock.
|
|
|
109
109
|
$ oats sync
|
|
110
110
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
111
111
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
112
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.0
|
|
112
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 6.2.0 ✓ (@ 92c63060)
|
|
113
113
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
114
114
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
115
115
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -155,7 +155,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
155
155
|
## `oats package add | remove`
|
|
156
156
|
|
|
157
157
|
```bash
|
|
158
|
-
oats package add oats.aweb v1.
|
|
158
|
+
oats package add oats.aweb v1.42.1 # a catalog version
|
|
159
159
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
160
160
|
oats package remove acme.tools
|
|
161
161
|
```
|
|
@@ -181,8 +181,8 @@ same workspace commit hold identical locks.
|
|
|
181
181
|
"source": "catalog:oats.okf",
|
|
182
182
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
183
183
|
"path": "oats-package",
|
|
184
|
-
"version": "6.0
|
|
185
|
-
"commit": "
|
|
184
|
+
"version": "6.2.0",
|
|
185
|
+
"commit": "92c630606db81f55c3e31002cb51d0e603dc7902",
|
|
186
186
|
"integrity": "sha256-…",
|
|
187
187
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
188
188
|
},
|
|
@@ -431,12 +431,12 @@ A soul that names one of the package's capabilities with
|
|
|
431
431
|
{
|
|
432
432
|
"policy": "docs/official-catalog.md",
|
|
433
433
|
"packages": {
|
|
434
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.0
|
|
435
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
434
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v6.2.0", "path": "oats-package" },
|
|
435
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.26.0", "path": "oats-package" }
|
|
436
436
|
}
|
|
437
437
|
}
|
|
438
438
|
```
|
|
439
439
|
|
|
440
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
441
|
-
resolves to tag `oats-framework/v1.
|
|
440
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.26.0`
|
|
441
|
+
resolves to tag `oats-framework/v1.26.0`. Resolving through the catalog never
|
|
442
442
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -180,21 +180,23 @@ runs the same installer steps, so it names the same commits. So does
|
|
|
180
180
|
lane's call of 2026-10-27: it runs a branch's code on the release's own
|
|
181
181
|
actions, and its run is that pull request's macOS evidence, so it names them
|
|
182
182
|
at the commits that were read
|
|
183
|
-
([Implementation](implementation.md#the-tuis-tests-on-macos)).
|
|
183
|
+
([Implementation](implementation.md#the-tuis-tests-on-macos)).
|
|
184
|
+
`team-image.yml` also names these commits for
|
|
185
|
+
[image acceptance](container.md#image-ci-and-publication). Every other
|
|
184
186
|
workflow keeps tags (`actions/checkout@v4`): nothing is published from them.
|
|
185
187
|
|
|
186
188
|
`test/workflow-no-cache.test.mjs` holds this. Its table of the actions that
|
|
187
|
-
were read has a row for each action: `action`, `id`, `version`. In
|
|
189
|
+
were read has a row for each action: `action`, `id`, `version`. In these four
|
|
188
190
|
files every `uses:` is a row's id, the same action is the same id in all of
|
|
189
191
|
them, and the comment beside an id is the row's version. In every other
|
|
190
192
|
workflow a `uses:` is the major of a row's version.
|
|
191
193
|
|
|
192
194
|
**An id is moved by a pull request, reviewed like any change to that
|
|
193
|
-
workflow.** It changes these together, and nothing else in
|
|
195
|
+
workflow.** It changes these together, and nothing else in these four workflow
|
|
194
196
|
files:
|
|
195
197
|
|
|
196
198
|
- the id and the version comment, on every `uses:` line of that action in
|
|
197
|
-
`release.yml`, `build-installers.yml` and `
|
|
199
|
+
`release.yml`, `build-installers.yml`, `tui-macos.yml` and `team-image.yml`;
|
|
198
200
|
- the action's row in the table.
|
|
199
201
|
|
|
200
202
|
**The id is read from an exact version tag of the action's own repository**
|