@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.
Files changed (52) hide show
  1. package/bin/oats.mjs +2 -2
  2. package/docs/capabilities.md +27 -14
  3. package/docs/container.md +416 -43
  4. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  5. package/docs/design/2026-09-28-automations-trust.md +1 -1
  6. package/docs/desktop-cli-api.md +52 -31
  7. package/docs/desktop.md +29 -6
  8. package/docs/execution-targets.md +32 -17
  9. package/docs/implementation.md +4 -3
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +6 -4
  15. package/docs/release-notes/v0.69.19.md +172 -0
  16. package/docs/release-notes/v0.69.20.md +325 -0
  17. package/docs/servers.md +6 -4
  18. package/docs/souls-and-instances.md +37 -13
  19. package/docs/tui.md +8 -8
  20. package/docs/upgrading.md +17 -5
  21. package/docs/workspaces.md +13 -7
  22. package/injects/work-directory.md +27 -2
  23. package/injects/work-workspace.md +32 -6
  24. package/lib/core.mjs +33 -197
  25. package/lib/hook-outcome.mjs +6 -0
  26. package/lib/host-run.mjs +24 -19
  27. package/lib/instance-lifecycle.mjs +3 -1
  28. package/lib/instance-listing.mjs +3 -2
  29. package/lib/launch-prompt-fixtures/README.md +6 -0
  30. package/lib/retire-admission.mjs +215 -0
  31. package/lib/servers.mjs +3 -0
  32. package/lib/session-resume-contract.mjs +1 -1
  33. package/lib/session-resume.mjs +130 -47
  34. package/lib/session-seen.mjs +3 -3
  35. package/package-catalog.json +3 -3
  36. package/package.json +3 -1
  37. package/packages/client/attributed-human.mjs +13 -0
  38. package/packages/client/deployment-data.mjs +4 -0
  39. package/packages/client/deployment-panel.mjs +2 -0
  40. package/packages/client/instance-lifecycle.mjs +6 -4
  41. package/packages/client/instance-presentation.mjs +2 -2
  42. package/packages/client/instance-tree.mjs +18 -7
  43. package/packages/client/lifecycle-confirmation.mjs +4 -2
  44. package/packages/client/lifecycle-contract.mjs +11 -6
  45. package/packages/client/remote-roster.mjs +4 -0
  46. package/packages/record/README.md +15 -2
  47. package/packages/record/docs/capture-service.md +14 -0
  48. package/packages/record/lib/canonical.mjs +2 -70
  49. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  50. package/packages/record/lib/capture-aw.mjs +11 -5
  51. package/packages/record/lib/capture-health.mjs +16 -5
  52. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -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` and `oats retire` still work. `oats status --json` names such
467
- homes in `problems[]`: `legacy-captured-home {code, instances, homes,
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":"antares","team":"antares:ana.aweb.ai","from":"deployment"},
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":"altair-aweb","sshHost":"altair","operatorSshHost":"altair-operator","workspace":"/Users/me/acme","path":"/opt/homebrew/bin","label":"altair",
4181
- "workspaceKey":"github.com/awebai/ac",
4182
- "target":{"sshHost":"altair","workspace":"/Users/me/acme","oatsPath":"oats","path":"/opt/homebrew/bin"},"snapshots":0}],
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":"altair-aweb","ready":false,
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/awebai/ac (auth): on macOS a session without a terminal …",
4214
- "remedy":"on altair: 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
+ "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 altair: 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)"]}
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 home with no `instance.json` and no cleanup
6582
- descriptor, or a rollback marker that cannot drive a retry, or an
6583
- `instance.json` that names no repository and does not show that no capability
6584
- has a retire hook, what a spawn killed before its record leaves
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)). The
6596
- codes a retire answers only before any effect are
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-this-boot` (an earlier sweep in this boot was refused for this home and start, and its answer to the loss was lost: reported again with that `code` and `message`, nothing started; a refused loss is never retried automatically, after a reboot either), `keeps-getting-lost` (sweeps started this home 3 times in this boot and it was lost again each time: nothing started, no `code`, a `message` that says so; no sweep starts this loss again, after a reboot either: a person starts it by hand) |
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-this-boot`, `keeps-getting-lost`, then its
7192
- start. A sweep that is not a plan answers each lost home once: a later
7193
- sweep answers that loss `not-seen-recently`. A `lifecycle-busy` row does
7194
- not answer it: whatever OATS was doing to the home decides what it is
7195
- next, and a later sweep reads it again.
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 once (`oats session resume`).
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 a listing of every deployment's
7281
- instances, which records what runs for the next start's sweep. Each is a
7282
- child process. A minute whose tick still runs is skipped; a minute missed
7283
- is never replayed. With no scope registered it ticks nothing and says so.
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", "altair · ~/northwind"),
690
- with "Instances on this machine" or "Instances on altair" under it. Then
691
- each deployment has a tab of its own, named by its machine ("altair";
692
- "This Mac · oats-v2" when this Mac holds two). A workspace with one
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
- altair"), with a mark when one of them isn't live.
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 in name order, so the parent's line ends at its last joined child and
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: whatever a sweep did with it (resumed, refused,
1458
- skipped or blocked), no later sweep starts it again, in this boot or after
1459
- a reboot; a later sweep reports it `not-seen-recently`. A `lifecycle-busy`
1460
- skip is the one that answers nothing: the next sweep reads the home again. A refused resume is
1461
- never retried automatically: it is also noted for the boot, and reported
1462
- `refused-this-boot` should that answer be lost.
1463
- - A home lost unexpectedly is started by sweeps at most 3 times in a boot. A home lost again
1464
- after each resume (a harness that crashes the host or its terminal server,
1465
- say) is then reported `keeps-getting-lost`, and that loss is answered: no
1466
- sweep starts it again, after a reboot either. Start it by hand: its next
1467
- loss is a new one, with a new count in each boot. Every sweep start that launched
1468
- something counts (resumed, fresh or blocked), by home, as soon as that start
1469
- has answered, so a sweep killed while other starts run has counted it; a
1470
- refused, skipped or busy one does not. `oats session start --resume` run by hand is neither
1471
- bounded nor counted.
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 new `oats host run` invokes the sweep;
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
@@ -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 skills adapt in `THIRD-PARTY-NOTICES.md`) that the framework's own souls compose |
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`: one producer, `listInstances`; never in the way of the listing); the contract's names (`sessionEnd`, the start's `resume` object, the sweep's outcomes and reasons, the feature) in one dependency-free module that every producer, test and doc reads (awebai/oats#1567 settles them); how a launched home's last session ended (`sessionEnd`, from the kernel-private exit marker and stop record, both forms of the marker), and the machine sweep `oats session resume` with its lock (a claim taken through `dir-lock.mjs` `acquireDirLock`, its record naming the boot too; `E_RESUME_LOCK_STUCK` for a lock that needs a person, which `oats doctor` reports as `resume-lock-stuck`) and its per-boot note (refusals, and the count behind the bound of 3 sweep starts per home per boot); a resume holds the home's lifecycle claim (`claim.mjs` below), as every start does, the sweep's status-row read of a retire or a claim holder is only its filter, and every stop OATS does writes the stop record through `core.mjs` `recordStop`, a retire's before its window kill; the record of each start's `fromEnv` and `fromFile` values (`start-env.mjs`: a keyed digest per source, never a value) and the one check a resume and `--plan` share, so a resume never starts under a changed value; the conversation a resume continues is `packages/record/lib/last-conversation.mjs` |
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 once and the tick and the listing 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 |
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 |
@@ -40,8 +40,8 @@ arrives from.
40
40
  ```yaml
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
- oats.okf: v6.0.3
44
- oats.aweb: v1.41.0
43
+ oats.okf: v6.2.0
44
+ oats.aweb: v1.42.1
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
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.3** (OATS **>=0.69.2**). Provider implementation and
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.3
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.3/CHANGELOG.md).
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.3` and run `oats sync`. Only new
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.3/README.md#upgrading-to-60)
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:
@@ -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.25.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.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
14
- | `oats.aweb` | `v1.41.0` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
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-v3.1.3` | Work that lands as pull requests: a dispatcher, a lead for each effort that builds a change itself or sends developers, whoever builds it iterating with a fresh reviewer each round, and a maintainer where a lane needs one. |
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.3`); `oats sync` resolves it through the
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.3 # bare version → the official catalog
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.25.0`) and the payload path. An id
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.25.0
82
- oats.okf: v6.0.3
83
- oats.aweb: v1.41.0
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.3 ✓ (@ fa13ca0b)
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.41.0 # a catalog version
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.3",
185
- "commit": "fa13ca0b026995fe5a278f7fb922ecd4eb09d6a9",
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.3", "path": "oats-package" },
435
- "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.25.0", "path": "oats-package" }
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.25.0`
441
- resolves to tag `oats-framework/v1.25.0`. Resolving through the catalog never
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.
@@ -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)). Every other
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 the three
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 the three workflow
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 `tui-macos.yml`;
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**