@awebai/oats 0.69.19 → 0.69.21

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 (46) hide show
  1. package/bin/oats.mjs +28 -5
  2. package/docs/capabilities.md +27 -14
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +218 -18
  5. package/docs/desktop-cli-api.md +105 -11
  6. package/docs/desktop.md +122 -65
  7. package/docs/implementation.md +3 -2
  8. package/docs/integrations.md +2 -2
  9. package/docs/knowledge.md +5 -5
  10. package/docs/official-catalog.md +5 -5
  11. package/docs/packages.md +13 -13
  12. package/docs/release-notes/v0.69.20.md +325 -0
  13. package/docs/release-notes/v0.69.21.md +155 -0
  14. package/docs/servers.md +9 -3
  15. package/docs/souls-and-instances.md +15 -2
  16. package/docs/upgrading.md +17 -5
  17. package/docs/workspaces.md +13 -7
  18. package/lib/capability-contract.mjs +2 -2
  19. package/lib/command-flags.mjs +1 -0
  20. package/lib/core.mjs +36 -198
  21. package/lib/hook-outcome.mjs +6 -0
  22. package/lib/instance-inspect.mjs +3 -0
  23. package/lib/instance-lifecycle.mjs +19 -1
  24. package/lib/instance-listing.mjs +11 -6
  25. package/lib/instance-pin.mjs +59 -0
  26. package/lib/kernel-features.mjs +1 -1
  27. package/lib/launch-prompt-fixtures/README.md +6 -0
  28. package/lib/retire-admission.mjs +215 -0
  29. package/lib/servers.mjs +11 -3
  30. package/package-catalog.json +3 -3
  31. package/package.json +1 -1
  32. package/packages/client/attributed-human.mjs +13 -0
  33. package/packages/client/deployment-data.mjs +4 -0
  34. package/packages/client/deployment-panel.mjs +2 -0
  35. package/packages/client/instance-lifecycle.mjs +6 -4
  36. package/packages/client/lifecycle-confirmation.mjs +4 -2
  37. package/packages/client/lifecycle-contract.mjs +11 -6
  38. package/packages/client/remote-roster.mjs +4 -0
  39. package/packages/client/roster-row-facts.mjs +50 -0
  40. package/packages/record/README.md +15 -2
  41. package/packages/record/docs/capture-service.md +14 -0
  42. package/packages/record/lib/canonical.mjs +2 -70
  43. package/packages/record/lib/capture-aw-unit.mjs +14 -3
  44. package/packages/record/lib/capture-aw.mjs +11 -5
  45. package/packages/record/lib/capture-health.mjs +16 -5
  46. package/skills/oats-getting-started/SKILL.md +211 -28
@@ -173,6 +173,7 @@ see the [official catalog](official-catalog.md) for current pins.
173
173
  | `instance-suggest-name` | `oats instance suggest-name [--soul <soul>] (--task <t> \| --task-file <f>) [--harness claude\|pi] [--model <m>] [--launch-config <n>] --json`: the name a `--suggest-name` spawn would get, chosen on this machine for a spawn that may land on another, not made unique ([A name for a spawn elsewhere](#a-name-for-a-spawn-elsewhere-oats-instance-suggest-name)). Local only: `--server` is `E_BAD_ARGS`. Gate on the local probe; without it, the spawn goes unnamed (numbered, or named where it lands) | |
174
174
  | `spawn-apply-suggest-name` | `--suggest-name` on a spawn apply, without `--preview`: the apply names the instance as a preview's `--suggest-name` would, on the machine that spawns, and its result carries `naming` ([On an apply](#on-an-apply-feature-spawn-apply-suggest-name)). Routed, the host needs the feature (`E_REMOTE_INCOMPATIBLE`, nothing sent): gate on the host's `probe.features` and don't send the flag to a host without it | |
175
175
  | `instance-background` | background instances (awebai/oats#1579): `soul.yaml` `background:`; `oats spawn … --background\|--no-background`, whose preview and result carry `background` and `backgroundFrom`; `oats instance background <instance> on\|off`, local and `--server`; `background: true` on `oats status --json` instance rows, `oats server roster --json` rows, `oats inspect --home` `instance` and `oats souls --json` soul rows, absent otherwise ([Background instances](#background-instances-oats-instance-background)). Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the flags and the verb, and its rows have no `background`. A routed spawn with either flag needs the host's feature (`E_REMOTE_INCOMPATIBLE`, nothing sent) | `instanceBackgroundApi: 1` (payload only) |
176
+ | `instance-pin` | pinned instances: `oats instance pin <instance> on\|off`, local and `--server`; `pinned: true` on `oats status --json` instance rows, `oats server roster --json` rows and `oats inspect --home` `instance`, absent otherwise ([Pinned instances](#pinned-instances-oats-instance-pin)). The pin is the home's, so it is shared by every client of that machine. Gate on the probe, locally or in the host's `probe.features`: an older kernel refuses the verb, and its rows have no `pinned` | `instancePinApi: 1` (payload only) |
176
177
  | `session-resume` | sessions come back after a shutdown, OATS 0.69 (#1559): `sessionEnd` on `oats status --json` instance rows ([`sessionEnd`](#row-session-end)); `oats session start --resume --home <abs>` and its `resume` answer ([Resume a lost session](#resume-a-lost-session---resume)); the machine sweep `oats session resume [--deployment <dir>] [--plan] --json` ([`oats session resume`](#the-machine-sweep-oats-session-resume)); `E_RESUME_BUSY`, `E_RESUME_NOT_LOST`. Local only: `--server` is `E_BAD_ARGS`. Gate a client's resume-on-open on the probe: a kernel without it has no `session resume` | |
177
178
  | `warm-reader` | `oats reader --stdio`, the warm reader: a child process a client starts, which answers `oats status --json` and `oats workspace status --json` on its stdin and stdout, many times, with the CLI's own answers ([The warm reader](#the-warm-reader)). Gate on the probe, never by trying: a kernel without it has no `oats reader` | `readerApi: 1` |
178
179
  | `status-liveness` | the local liveness on `oats status --json` instance rows is complete: `running` and `runtimeState` are read live at every call, from the row's recorded tmux server under the pane and shell-descendant rule, with `false` for a shell only on positive evidence and `null` when the reading is inconclusive ([The roster](#the-roster-oats-status---json)). A client needs no liveness probe of its own beside the roster where the probe lists it, whether the read goes through the warm reader or the CLI. Independent of `warm-reader` | |
@@ -327,6 +328,7 @@ for `--no-recursive`) is never ignored.
327
328
  | `oats instance upgrade` | `<instance>` | `--plan-revision`, `--idempotency-key`, `--home`, `--dir` | `--undo`, `--plan`, `--json` | `--server` | none |
328
329
  | `oats instance color` | `<instance>` `[<color>]` | `--home`, `--dir`, `--server` | `--clear`, `--json` | none | none |
329
330
  | `oats instance background` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
331
+ | `oats instance pin` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
330
332
  | `oats instance same-work` | `<instance>` `<state>` | `--home`, `--dir`, `--server` | `--json` | none | none |
331
333
  | `oats instance waiting set` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
332
334
  | `oats instance waiting clear` | none | `--producer`, `--reason`, `--message`, `--home`, `--dir` | `--json` | none | none |
@@ -463,8 +465,10 @@ with the soul's merged payload. `oats <namespace> --help --json` answers
463
465
  captured home (`details: {home, captured: true}`), the selectors
464
466
  `--deployment`, `--resolution` and `--artifact-set` (`details.selector`), and
465
467
  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,
468
+ `oats version` still answers. For captured homes, inspect and clean up external
469
+ state first; without positive proof that no spawn hook ran, retirement needs
470
+ `oats retire <instance> --force`. `oats status --json` names such homes in
471
+ `problems[]`: `legacy-captured-home {code, instances, homes,
468
472
  message}` and `legacy-local-agents {code, dirs, instances, message}`.
469
473
 
470
474
  <a id="observation-reuse-feature-observe-max-age-oats-0311"></a>
@@ -3760,6 +3764,10 @@ its absence.
3760
3764
  holds a valid background record ([Background instances](#background-instances-oats-instance-background)),
3761
3765
  absent otherwise; never `false`. A `background` in `instance.json` never
3762
3766
  stands in for it. The text rows mark it: `• <instance> [background]`.
3767
+ - <a id="row-pinned"></a>**`pinned`** (feature `instance-pin`): `true` while
3768
+ the home holds a valid pin ([Pinned instances](#pinned-instances-oats-instance-pin)),
3769
+ absent otherwise; never `false`. A `pinned` in `instance.json` never
3770
+ stands in for it. Clients list a pinned row first in its machine's list.
3763
3771
  - <a id="row-same-work"></a>**`sameWork`** (feature `instance-same-work`):
3764
3772
  `true` when the home's same-work flag
3765
3773
  ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work))
@@ -4038,6 +4046,10 @@ route target:
4038
4046
  host's row has exactly `background: true`; any other value, a host whose
4039
4047
  kernel predates the feature and a saved route the host did not list carry
4040
4048
  none.
4049
+ - **`pinned`** (feature `instance-pin`) is on a row only when the host's row
4050
+ has exactly `pinned: true`; any other value (`"true"`, `1`), a host whose
4051
+ kernel predates the feature and a saved route the host did not list carry
4052
+ none ([`pinned`](#row-pinned)).
4041
4053
  - **`sameWork`** (feature `instance-same-work`) is on a row only when the
4042
4054
  host's row has `sameWork: true`, and is then `true`. Any other value, a host
4043
4055
  whose kernel predates the feature, and a saved route the host did not list
@@ -4286,6 +4298,7 @@ instance's own machine: the local command, with `--server <id>` added.
4286
4298
  | `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
4287
4299
  | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
4288
4300
  | `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
4301
+ | `oats instance pin <name> on\|off --server <id>` | none | `instance-pin` |
4289
4302
  | `oats instance same-work <name> on\|off --server <id>` | none | `instance-same-work` |
4290
4303
 
4291
4304
  - The flags are the local command's. The instance is addressed like every
@@ -5675,6 +5688,9 @@ had begun.
5675
5688
  | `E_AMBIGUOUS` | yes | yes |
5676
5689
  | `E_SNAPSHOT_UNKNOWN` | yes | yes |
5677
5690
 
5691
+ `E_UNIDENTIFIED_INSTANCE_HOME` includes cleanup-hook admission in both retire
5692
+ plan and apply; the refusal returns no work facts when the home cannot be identified.
5693
+
5678
5694
  `E_HOME_NOT_OWNED` is the answer of every command that takes a home's
5679
5695
  lifecycle claim (a start, a resume, a stop, a retire, an upgrade) when the
5680
5696
  user it runs as does not own the home. It is answered before the claim is
@@ -6578,13 +6594,10 @@ message names the entry or the state that could not be read, or the directory
6578
6594
  Git reads as the top level of a `work/` whose `core.worktree` names another
6579
6595
  one),
6580
6596
  `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),
6597
+ `E_UNIDENTIFIED_INSTANCE_HOME` (a missing or unusable cleanup record, or
6598
+ recorded hooks that cannot run without proof that no cleanup is owed, until
6599
+ `--force`; a home whose `instance.json` [cannot be read](#unreadable-record)
6600
+ refuses even with `--plan` or `--force`),
6588
6601
  `E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
6589
6602
  home is running or scheduled, or a stop of it is running, `--force`
6590
6603
  included: one retire or stop of a home at a time, above; or, feature
@@ -6592,8 +6605,20 @@ included: one retire or stop of a home at a time, above; or, feature
6592
6605
  hooks, a row with `spawnInProgress: true`, `--force` included; or one whose start time
6593
6606
  cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
6594
6607
  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
6608
+ answered before any effect and carries [`details.holder`](#busy-holder)).
6609
+
6610
+ Hook admission refuses both `--plan` (including Desktop Remove) and apply
6611
+ before anything is stopped, run or removed, children included. Causes include
6612
+ homes spawned before `capabilityRuntime`, recorded retire hooks without a
6613
+ context repository (recorded or identified by Git for its own worktree),
6614
+ and captured homes from before 0.26 without positive proof that no spawn hook ran. An ordinary home's explicit capability set with
6615
+ no retire hooks proves no hook is owed. Captured proof also excludes any
6616
+ recorded hook intents, failures or lifecycle cleanup debt. The refusal names
6617
+ known capabilities, external identities/memberships at risk, and the remedy:
6618
+ clean up with the provider's tooling, then `oats retire <instance> --force`.
6619
+ See [the cleanup rule](capabilities.md#manifest).
6620
+
6621
+ The codes a retire answers only before any effect are
6597
6622
  [one list](#before-effect-codes). A recovery whose Git status disagrees with
6598
6623
  the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
6599
6624
  source, recovery}], total}}` (the first 10 paths). A worktree recovery whose
@@ -6826,6 +6851,75 @@ on [remote roster rows](#the-remote-roster-oats-server-roster---json), on
6826
6851
  [`oats souls`](#oats-capabilities-and-oats-souls) for a soul that declares
6827
6852
  it. Each is absent when not background.
6828
6853
 
6854
+ ## Pinned instances (`oats instance pin`)
6855
+
6856
+ Feature `instance-pin`.
6857
+
6858
+ ```text
6859
+ oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json]
6860
+ ```
6861
+
6862
+ A pinned instance is listed first in its machine's list, by every client of
6863
+ that machine: the Desktop, the TUI, and another machine's routed view. That
6864
+ is all it changes. Like the colour and background, it is presentation, never
6865
+ identity or policy, and anyone may change it at any time, a stopped
6866
+ instance's included. Several pinned instances keep the list's own order among
6867
+ themselves; there is no manual ranking.
6868
+
6869
+ - **Shared.** The pin is recorded in the instance's home, so everyone who
6870
+ views that machine sees the same pins. There is no per-viewer pin.
6871
+ - **No default.** An instance is not pinned when it is spawned: there is no
6872
+ spawn flag and no `soul.yaml` key. This command is the only way to pin.
6873
+ - **The record** is `<home>/.oats-pinned.json`, `{"pinnedApi": 1,
6874
+ "at": "<ISO time>"}`, mode 0600, written atomically. Present means
6875
+ pinned; `off` removes it. It lasts as long as the home, through start,
6876
+ restart, stop, resume and `oats instance upgrade`, and a retire removes
6877
+ it with the home. It is a kernel-owned home file: a capability cannot
6878
+ declare it as its own, and it is no change to the home at retire.
6879
+ - **A reader** takes a regular file only, without following a link, of at
6880
+ most 4 KiB, holding a JSON object with `pinnedApi: 1`. Anything else (a
6881
+ link, a directory, an oversize or invalid file, another `pinnedApi`) reads
6882
+ as not pinned, never as an error; `off` removes it, and `on` replaces it
6883
+ with a valid record.
6884
+ - **The instance** is addressed and refused exactly as `oats instance
6885
+ background` addresses and refuses it ([Background instances](#background-instances-oats-instance-background)),
6886
+ with "the pin was not changed" where its refusals say the background.
6887
+
6888
+ The answer names the home it resolved, as `oats instance background`'s does,
6889
+ so a routed or `--home` pin says which home it pinned:
6890
+
6891
+ ```json
6892
+ {"instancePinApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","pinned":true,"changed":true}
6893
+ ```
6894
+
6895
+ `on` for a pinned instance and `off` for one that is not answer
6896
+ `changed: false` and write nothing (`off` still removes an invalid file).
6897
+ The text answer is `<instance>: pinned` or `<instance>: not pinned`, with
6898
+ ` (unchanged)` when nothing changed.
6899
+
6900
+ | Code | When |
6901
+ |---|---|
6902
+ | `E_BAD_ARGS` | Not exactly one of `on` or `off`, or an argument after it: the usage line |
6903
+ | `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH` | Instance resolution, as `oats instance background` answers it |
6904
+ | `E_INSTANCE_RETIRING` | A retire of the home is running (its live lifecycle claim, or its pending marker), or the home is quarantined |
6905
+ | `E_LIFECYCLE_BUSY` | The home's lifecycle claim cannot be read, or its holder is a retire whose liveness cannot be read |
6906
+
6907
+ Beside a running stop, start or upgrade, the pin goes through, as `oats
6908
+ instance background` does: the pin is a file of its own that none of them
6909
+ writes, and refusing would fail every pin for the whole length of a start.
6910
+ In each refusal, the pin was not changed.
6911
+
6912
+ Routed with `--server <id>`, the command runs on the host
6913
+ ([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
6914
+ not advertise `instance-pin` is refused with `E_REMOTE_INCOMPATIBLE`, and
6915
+ nothing is sent.
6916
+
6917
+ Where it is read: `pinned: true` on [status rows](#row-pinned), on
6918
+ [remote roster rows](#the-remote-roster-oats-server-roster---json) (only
6919
+ when the host's row says exactly `true`), and on `oats inspect --home` as
6920
+ `instance.pinned`. Each is absent when not pinned. A client reads `pinned`
6921
+ only where the probe lists `instance-pin`.
6922
+
6829
6923
  ## Same work as the parent (`oats instance same-work`)
6830
6924
 
6831
6925
  Feature `instance-same-work` (awebai/oats#1577).
package/docs/desktop.md CHANGED
@@ -268,31 +268,37 @@ workspace on a server: `name — server`).
268
268
 
269
269
  ## Workspaces
270
270
 
271
- The sidebar, top to bottom: the **Workspace** heading, with **Show only the
272
- current workspace** and **Add local workspace…** at its end, over the list of
273
- workspaces; a thin line; the two main views, **Workspace overview** and
274
- **Automations**, one under the other; another line; **Instances**, a heading
275
- with the running count over the list of instances; and, over a line, the
276
- foot, one bar: the OATS mark and the sidebar toggle (**Hide the sidebar**)
277
- after it, and at the bar's right **Spawn instance**, its words alone (a ground
278
- only on hover), which
279
- opens Quick Open (⌘P / Alt+P, named in its tooltip) to pick a soul and then
280
- the spawn dialog, and the settings cog, whose menu holds **Theme…**, **Font…** and
281
- **Keyboard shortcuts…**, each with its shortcut when it has one. A window opens on the **Workspace
282
- overview** page, on its **Souls** tab: at launch, and after you choose a
283
- workspace for it. Connections is in the command palette
284
- (**Settings: Connections…**), and the palette opens with its shortcut or
285
- Ctrl+X then `k`.
271
+ The sidebar, top to bottom: the **Workspace** heading, with **Add local
272
+ workspace…** (the **+**) at its end, over the list of workspaces; a thin line;
273
+ two pinned rows, **Workspace overview** and **Automations**, drawn like the
274
+ instance rows (Automations shows a red dot, and says "a run failed", while a
275
+ schedule's last run failed: see [Scheduling agents](#scheduling-agents-and-wake-messages));
276
+ another line; **Instances**, a heading with the running count over the list of
277
+ instances; and, over a line, the foot, one bar: at its left **N need you**, the
278
+ number of this workspace's agents that need input (hidden when none does;
279
+ it takes you to the first of them, in the roster's order, expanding a collapsed
280
+ parent or opening the Background section to show it), and at its right
281
+ **New agent**, which opens Quick Open (⌘P / Alt+P, named in its tooltip) to
282
+ pick a soul and then the spawn dialog, and **?**, which opens the keyboard
283
+ shortcuts. The foot has no mark, no Hide sidebar button and no settings menu:
284
+ ⌘B / Ctrl+Shift+B and the palette's **Sidebar: toggle (hide/show)** hide the
285
+ sidebar, and the palette's **Theme: choose…**, **Font: choose…** and
286
+ **Shortcuts: edit keyboard shortcuts…** open the theme, the font and the
287
+ shortcuts. A window opens on the **Workspace overview** page, on its **Souls**
288
+ tab: at launch, and after you choose a workspace for it. Connections is in the
289
+ command palette (**Settings: Connections…**), and the palette opens with its
290
+ shortcut or Ctrl+X then `k`.
286
291
  The instances have no search field: to find one by name, type it in the
287
292
  command palette, which opens its terminal. ⌘F / Alt+F (**Focus the
288
293
  instance roster**) and `/` in the sidebar go to the roster's current row;
289
- on an empty roster, to its one action, the foot's **Spawn instance**, where
290
- F6 lands too (a failed read's **Retry** comes first).
294
+ on an empty roster, which says "No agents yet · ⌘P starts one" (New
295
+ agent's key, Alt+P off macOS, as you bound it), to its one action, the foot's **New
296
+ agent**, where F6 lands too (a failed read's **Retry** comes first).
291
297
 
292
298
  The sidebar is 288px wide, and you can make it wider or narrower: drag its
293
299
  right edge, between 240px and 480px (or 45% of the window, when that is
294
300
  less, so the terminals keep the rest). With the keyboard, Tab to that edge
295
- (after the settings cog) and use ← and → (8px a step, 32px with Shift), Home
301
+ (after the foot's **?**) and use ← and → (8px a step, 32px with Shift), Home
296
302
  and End for the narrowest and the widest. A double-click on the edge, Enter
297
303
  on it, or the command palette's **Sidebar: reset width** put it back to 288px.
298
304
  The width is remembered on this computer, and kept while the sidebar is
@@ -300,10 +306,10 @@ hidden; a window too narrow for it shows it narrower, and gives it back when
300
306
  the window grows again. The terminals refit as it moves, and their programs
301
307
  hear the new size once, when you let go.
302
308
 
303
- **Theme and font.** The settings cog's **Theme…**, the palette's **Theme: choose…** and
309
+ **Theme and font.** The palette's **Theme: choose…** and
304
310
  ⇧⌘Space / Ctrl+Shift+Space open the theme picker (White, Solarized, Dark, or
305
311
  This computer, which follows the computer's own theme). The font has a picker
306
- of its own, the settings cog's **Font…** or **Font: choose…** in the palette (no
312
+ of its own, **Font: choose…** in the palette (no
307
313
  shortcut unless you give it one in the shortcuts editor), with two choices:
308
314
 
309
315
  - **Omarchy's font**, the default on a computer that runs Omarchy. On Linux the whole window and its
@@ -359,16 +365,10 @@ below, a line under the list says how many ("2 more below"), with the
359
365
  needs-input mark at its right when one of them has an instance that needs
360
366
  input.
361
367
 
362
- **Show only the current workspace** is the toggle before the **+** in the
363
- heading, for working in one workspace at a time. Pressed (its icon in the
364
- accent colour), the list shows the current workspace's row alone. Nothing
365
- stands for the others: no "N more" line, and no needs-input mark for one of
366
- them that waits. Press it again, or use ⌥⇧⌘O on macOS / Ctrl+Alt+Shift+O on
367
- Linux and Windows (the same in every chord family, and from a terminal) or the
368
- palette's **Show only the current workspace**, to see every workspace again.
369
- Ctrl+X then ↑ / ↓ still move to the previous / next workspace, which then
370
- shows alone. A window choosing a workspace shows them all. The choice is remembered on this
371
- computer.
368
+ The list always shows every workspace: one is shown at a time by construction,
369
+ and everything under the list belongs to it. (**Show only the current
370
+ workspace** is gone, with its ⌥⇧⌘O / Ctrl+Alt+Shift+O and its palette command;
371
+ a choice saved for it is ignored.)
372
372
 
373
373
  - **A row is one line: a circle and the workspace's name.** No icon, no
374
374
  machine, no state: a workspace's own pages show its machines and
@@ -746,7 +746,12 @@ pattern and time zone; new agent jobs also offer harness, model, permissions
746
746
  and session backend. The list shows the next run, last observed outcome and
747
747
  whether the host scheduler is enabled. Pause, edit, run now and delete operate
748
748
  on that workspace's saved jobs. Launching an agent is reported separately from
749
- the end of its run; neither means its task succeeded.
749
+ the end of its run; neither means its task succeeded. While a schedule's last
750
+ run is **launch failed** or **invalid**, the sidebar's **Automations** shows a
751
+ red dot, and a screen reader hears "Automations, a run failed"; it clears once
752
+ no last run has failed. The sidebar reads both lists when the workspace opens
753
+ and then at most once a minute. A trigger's last run carries no outcome, so a
754
+ trigger never marks it.
750
755
 
751
756
  Each schedule and trigger can carry a one-line **summary** (up to 200
752
757
  characters), shown under its name in the list. Without one, the list shows the
@@ -969,39 +974,67 @@ error in the terminal. Each drop/paste accepts up to 16 files totaling 25 MB.
969
974
  ## The sidebar's instance tree
970
975
 
971
976
  The sidebar lists a workspace's instances as a tree: a child sits one step
972
- right of its parent, and related instances are grouped together. Siblings are
973
- joined by a dotted line through their dots. A parent's line to its children
974
- runs just to the right of the dotted line, so the two never merge.
977
+ right of its parent, and related instances are grouped together, with a little
978
+ space before the next group. The sidebar draws no lines between them: the
979
+ indent and that space show the tree. A screen reader hears each row's state ("running", "stopped" or "status
980
+ unknown") after its two lines, then each child "under"
981
+ its parent, with "same work" when its host reports it doing its parent's work,
982
+ and each instance linked as a sibling "sibling of" the other, after the row's
983
+ two lines.
984
+
985
+ The sidebar shows the top-level instances only until you open one. An
986
+ instance with children has a chevron before its name, with the number of
987
+ instances under it at every depth. Click the chevron to show its group as
988
+ it was drawn before, and click it again to hide the group. A click anywhere
989
+ else on the row still opens its terminal. From the keyboard, Right opens the
990
+ focused row and Left closes it. Every instance at the top of the tree, the
991
+ [Background section](#background-instances)'s included, starts collapsed in
992
+ each new window, except one still being set up or retired, or whose retire
993
+ failed: while its row shows that state, it has no chevron and its group
994
+ stays open, so an instance under it that needs input is never hidden. An instance inside a group starts open, and each one with
995
+ children has its own chevron. What you open or close stays as you left it
996
+ until the window closes. **Show in roster**, `--instance` and a spawn from
997
+ the Desktop open the rows above the instance they show. The TUI's list still
998
+ shows every instance open.
975
999
 
976
1000
  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
1001
+ every level. A little space separates each top-level group (an instance with
1002
+ its children and the siblings joined to it) from the next; the order never
1003
+ changes for it. A group of related instances sits where its first instance's
978
1004
  spawn time puts it, so spawning a child doesn't move the group, and starting
979
1005
  or stopping an instance moves nothing. Instances spawned at the same moment
980
1006
  are in name order, and an instance whose spawn time can't be read comes after
981
1007
  every one whose time can.
982
1008
 
983
- A parent's line joins only the children that do its work. When the instances'
1009
+ Children that do their parent's work come first under it. When the instances'
984
1010
  OATS has the `instance-same-work` feature, a child the kernel reports as doing
985
1011
  its parent's work (`sameWork: true` in its row, set with `oats spawn …
986
- --same-work` or `oats instance same-work <instance> on`) is joined to its
987
- parent, and any other child keeps its place and its indent with no line to its
988
- parent. Under one parent the joined children are listed first, then the others,
989
- each part newest first, so the parent's line ends at its last joined child and
990
- never passes one it doesn't join. Nothing else marks the flag: no label, no
991
- tag, and nothing for a screen reader, which still hears each child "under" its
992
- parent in the command palette. The command palette draws the same lines, in
993
- its own recency order inside each part. For another machine's instances, its
994
- host must report the feature too, through an installed OATS with
995
- `server-probe-features`. A host without the feature, or one whose features are
996
- not known (its last read failed), keeps a line to every child. A spawn from the
997
- Desktop never sets the flag.
1012
+ --same-work` or `oats instance same-work <instance> on`) is listed before its
1013
+ parent's other children, each part newest first. The command palette still
1014
+ draws lines: there a parent's line joins only those children (siblings by a
1015
+ dotted line through their dots), in its own recency order inside each part.
1016
+ For another machine's instances, its host must report the feature too, through
1017
+ an installed OATS with `server-probe-features`. A host without the feature, or
1018
+ one whose features are not known (its last read failed), lists every child as
1019
+ doing its parent's work. A spawn from the Desktop never sets the flag.
998
1020
 
999
1021
  A row shows the instance's name as words: each `-` is a space, and the first
1000
1022
  letter is a capital, so `oats-expert-maintainer-lanes` reads "Oats expert
1001
- maintainer lanes". Only the row's label changes. The hover card, the command
1002
- palette (which still finds the instance by its name), its terminal tab, a
1003
- screen reader and the `oats` CLI all use the instance's real name. The TUI's
1004
- sidebar shows the same words.
1023
+ maintainer lanes". Only the row's label changes. The instance panel, the
1024
+ command palette (which still finds the instance by its name), its terminal tab,
1025
+ a screen reader and the `oats` CLI all use the instance's real name. The TUI's
1026
+ sidebar shows the same words. A long name is cut at its end with "…".
1027
+
1028
+ A row's second line says its soul and the machine it runs on, "oats-expert ·
1029
+ falcon", or the machine alone when its soul isn't known. This computer's rows
1030
+ name it by the host name OATS records for it (`host.name` in its
1031
+ `oats-local.yaml`); with none recorded, they say "This Mac". A limit for now:
1032
+ the Desktop learns that name from its Automations read, so these rows say
1033
+ "This Mac" until that read answers, and keep saying it where the installed
1034
+ OATS serves no automations ([#1972](https://github.com/oats-project/oats/issues/1972)
1035
+ tracks reading it from the status answer instead). That's all a row
1036
+ says: its repository, branch, pull request and harness are in the instance
1037
+ panel. Rows are 44px tall, the dot centred on the row.
1005
1038
 
1006
1039
  A row's dot says the instance's state: filled while it runs, a ring when it is
1007
1040
  stopped, a grey ring with a small grey centre when its state is unknown (the
@@ -1011,14 +1044,21 @@ instance that needs input (a running session's claim, from OATS with the
1011
1044
  slightly larger amber disc with a "!" cut out of it, the mark its terminal tab
1012
1045
  and the workspace list show. Amber means needs input and nothing else.
1013
1046
  Elsewhere, a dot that flags a problem is red: a keyboard shortcut that clashes
1014
- with another (on the settings cog), Setup or Teams needing attention (on the
1015
- Workspace page's tabs), and an automation that doesn't run here or a
1016
- scheduler that is off.
1017
- The row keeps its soul and repository on its second line. A screen reader
1018
- hears "Needs input" after the name, and the hover card gives the reason and
1019
- how long it has waited. A collapsed parent shows "! N below" on its second
1020
- line for the rows it hides that need input, beside its own mark when it waits
1021
- too. Rows never move or grow, and nothing animates.
1047
+ with another (on the foot's **?**), Setup or Teams needing attention (on the
1048
+ Workspace page's tabs), the sidebar's **Automations** while a last run failed,
1049
+ and an automation that doesn't run here or a scheduler that is off.
1050
+ The row keeps its soul and machine on its second line. A screen reader
1051
+ hears "Needs input" after the name, then the reason and when it started
1052
+ waiting; the instance panel's **Needs input** section gives the reason, how
1053
+ long it has waited and the agent's message. A collapsed parent shows "! N
1054
+ below" on its second line for the rows it hides that need input, beside its
1055
+ own mark when it waits too. Rows never move or grow, and nothing animates. The
1056
+ row has no hover card: its facts are the instance panel's, and a row's error
1057
+ ("OATS says: the last start failed") is its tooltip and its description. Until
1058
+ the panel serves a row with no terminal open, the row's tooltip also says its
1059
+ repository, branch, harness and model; a screen reader doesn't hear these on
1060
+ the row, so with the keyboard alone they show once the row's terminal is
1061
+ open.
1022
1062
 
1023
1063
  A row has no ⋯ button. Its actions (Open in split, Open pull request…,
1024
1064
  Knowledge & capabilities…, Start…, Restart with…, Stop…, Retire instance…,
@@ -1030,8 +1070,9 @@ Home and End move in it, and Esc or Tab close it with the focus back on the
1030
1070
  row. A right-click never opens the row's terminal. While the menu can't be used
1031
1071
  (the roster is out of date, one of its actions is still running, or the row
1032
1072
  can't be used from this computer), it opens nothing, and one line at the
1033
- bottom of the main area says why, as a leader key that can't act does. The row's own tools stay: its pull request link and, on a
1034
- stopped row, **Start…**.
1073
+ bottom of the main area says why, as a leader key that can't act does. A row
1074
+ draws no tools of its own: its pull request opens with **Open pull request…**,
1075
+ and a stopped row starts with **Start…**, both in its menu.
1035
1076
 
1036
1077
  ## Background instances
1037
1078
 
@@ -1101,6 +1142,22 @@ computer, and for an instance on a server, on that server too; until then the
1101
1142
  buttons are disabled and the dialog says which is missing. An instance whose
1102
1143
  home is being spawned or retired can't be given a colour meanwhile.
1103
1144
 
1145
+ ## An instance's owning human
1146
+
1147
+ Where the messaging capability attributes an instance's messaging identity to
1148
+ a human, the instance panel's Lineage section shows that human first, as
1149
+ **Owning human**, above the instance's parent and sibling. It is the
1150
+ `attributedHuman` of the instance's row in `oats status --json`, and of a
1151
+ server's row for an instance on a server
1152
+ ([Attributed human](desktop-cli-api.md#attributed-human)), shown as OATS
1153
+ reports it. The instance is still named by its own name everywhere: the
1154
+ sidebar, its terminal tab, the command palette and the panel's header.
1155
+
1156
+ An instance with no human attributed shows no such field, and nothing says
1157
+ one is missing: that is the usual case, on a deployment whose messaging
1158
+ capability supplies no human identities and for an older OATS that doesn't
1159
+ report it. A label OATS would not show as one line of text reads the same way.
1160
+
1104
1161
  ## Identity marks and harness badges
1105
1162
 
1106
1163
  Souls, capabilities and workspaces carry a coloured two-letter mark beside
@@ -1112,9 +1169,9 @@ letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-maintainer` KM and
1112
1169
  `oats.aweb` OA. Two names can share a mark (`oats-expert` and
1113
1170
  `oats-operator-expert` are both OE); the name and the colour tell them apart.
1114
1171
 
1115
- Roster rows, soul cards, the soul page, the context panel and the spawn
1116
- dialog show each instance's or soul's harness as a small badge, next to its
1117
- name. The badge names the harness the CLI reports; it says nothing about
1172
+ Soul cards, the soul page, the context panel and the spawn dialog show each
1173
+ instance's or soul's harness as a small badge, next to its name (a roster row
1174
+ doesn't: its second line is its soul and machine). The badge names the harness the CLI reports; it says nothing about
1118
1175
  whether that harness is installed or signed in. Pi's badge is the official
1119
1176
  pi.dev press-kit mark (MIT), and Claude Code's is Anthropic's Claude spark
1120
1177
  in the theme's colours. The Codex badge is OATS's own drawing, not OpenAI's
@@ -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) |
@@ -136,7 +136,7 @@ and the rules its tests pin.
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 |
139
- | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
139
+ | `instance-*.mjs` | inspection, lifecycle, events and Git views of an instance; `instance-color.mjs` is an instance's colour, its palette (pinned equal to `packages/client/soul-colors.mjs`) and its home record, which every reader goes through; `instance-background.mjs` is the same for whether an instance is background: its home record, read by the rows, inspect and the command, and written by spawn and the command; `instance-pin.mjs` is the same for whether an instance is pinned at the top of its machine's list: its home record, read by the rows and inspect, and written only by `oats instance pin`; `instance-same-work.mjs` is an instance's same-work flag, its home record bound to a parent, and `sameWorkOf`, the one rule of whether it is on, which status rows, spawn and `oats instance same-work` go through |
140
140
  | `worktree.mjs` | `oats worktree add\|remove`: an instance's extra trees (`.work-<purpose>`), their records (`.oats/trees/`), argument checks before any write, the rollback of an interrupted add, and completion of Git's partial removal. An unregistered residue with a dangling `.git` file is compared with the recorded branch through a private temporary index (`read-tree`, refresh, `diff-files` allowing deletions, and `ls-files --others --exclude-standard`) before permissions or files change; the clone's index is never used. Only clean residue is made writable, without following symlinks, and deleted |
141
141
  | `errors.mjs` | `oatsError`, and the door of the lifecycle verbs: `isKernelCode` (the shape of a kernel code, `^E_[A-Z0-9_]+$`, never a list of codes), `kernelCode`, `asKernelError` and `errorCause`. An answer of `oats retire`, `oats instance stop`, `oats session` and `oats worktree` carries a kernel code, or one of the two names every command answers as they are (`OWN_NAME_FAILURES`: `unsafe-config-key`, `unsafe-config-value`), and no other: `isAnswerCode` is what the door and its wrappers keep, `isKernelCode` stays the test of the shape. An error of the system's or of Node's, a refusal written as a plain `Error` without a code, and a defect (`isDefect`: a `TypeError` and its like without a code, or a thrown value that is no `Error`), is wrapped at the boundary (`bin/oats.mjs` `lifecycleFail`; in a retire, `core.mjs` `retireClaimed`, which also says what the retire had done by then) and its own code goes to `details.cause` (a defect's name does; a plain `Error` without a code has no cause, and is answered with the general code and its message alone, which is what an ordinary refusal of `tmux`, `git` or the kernel itself must read as). New code that answers an error tests the shape with these, never `e.code \|\| "E_…"`: a system error has a `code` too. Whoever ends an error's way up prints the stack of a defect with `reportDefect`: the door, and any code that turns a caught error into a row of results (a stop's `results[]`, a retire's `childrenStopped[]`), after which nobody else can. Two more rules of the lifecycle verbs live here. **`lifecycleBusy(holder, said, remedy, details)` is the only way `E_LIFECYCLE_BUSY` is made** (`test/lifecycle-busy-holder.test.mjs` scans `lib/` and `bin/` for any other): it sets `details.holder` (`BUSY_HOLDERS`: `"running"` only where the kernel established that the other command is alive, `"unknown"`, `"none"`) and refuses to build an `"unknown"` or `"none"` answer without the step that ends it. **`BEFORE_EFFECT_CODES` lists, per verb, the codes that verb answers only before any effect**; `afterFirstEffect` turns a listed code raised after a verb's first effect into a defect (`E_LIFECYCLE_FAILED`, `cause.name: "LateRefusal"`), and is called at the one place of each verb that knows how far it got (`core.mjs` `retireFailure`, from `at.phase`; `instance-lifecycle.mjs` `applyStop`, from whether a target's stop began). A code may join the list only when every place that raises it in that verb is before the first effect; a place found after it gets a code of its own, never the net |
142
142
  | `claim.mjs` | the claim: one file naming, by pid and start time, the process doing something that happens once at a time; taken over when its holder is verifiably gone, never when that cannot be read. Synchronous. Held by `oats worktree add\|remove` per purpose (`worktree.mjs`), and per home by `oats retire`, `oats instance stop --apply`, `oats instance upgrade`, `oats session start --resume` (verb `resume`) and every other session start and restart, a scheduled start included (verb `start`, #1602; `core.mjs` `startClaimed`, the only exclusion of one start by another: two starts are answered `E_SESSION_START_BUSY` from the claim, `startPair`; a path with no record it can read takes no claim (`readHomeRecord`, as every lifecycle verb reads its record first); the start runs on the home's path on disk, and a home given through a link first answers what a start of the path as given answered before any guard (`startRefusals`, in their order; a partial upgrade is left to the claim while an upgrade holds it, `upgradeHoldsClaim`, as the CLI's pre-check does), then is held to its own authority on the path as given, `sessionDirectoryGuard`, then again with every check of the start's roots; an owned directory home must resolve to the home its own receipt records, bound by the receipt's paths, not by a second read of the disk: `requestedHomeGuard`) (`core.mjs` `claimHomeFor`: the one way a verb takes a home's lifecycle claim; the record names the holder's verb, `action`, from the instant the file exists, through the `facts` option of `acquireClaim`). A verb that only reads the home's claim (`oats worktree add`; a stop plan's `retiring` and `stopPending`) uses `homeClaimHolder` or `refuseBesideRetire`. The refusals of every pair (arriving verb, holder's verb) are built in one place, `core.mjs` `lifecycleClaimRefusals`; the pair table of `docs/desktop-cli-api.md` is walked by `test/lifecycle-pair-table.test.mjs`. A new verb that must not run beside a retire takes the claim through `claimHomeFor`, joins `CLAIM_VERBS` and adds its row and column there. Its loop has one rule: every pass that does not take the claim falls through one check of its time and one pause, so no state of the path makes it spin. Each caller words the refusals (`busy`, `unreadableClaim`, `cannotTakeOver`, `heldAgain`, `ownStartUnreadable`), and is handed with each what the acquisition's takeovers ended before it (`ended`): it writes "nothing else was done" then, and the answer is `E_LIFECYCLE_FAILED`, what was ended first (`errors.mjs` `nothingAfter`, `afterEndedSteps`; `lifecycleBusy` takes `ended`). No message is rewritten after it was made. A claim is read back as whatever is in its file, which others than its writer can write, so no text of it enters an answer: a refusal names the holder through `shownHolder` (its pid, time and start, each only in the shape the kernel writes) and `core.mjs` `claimAction` (one of `CLAIM_VERBS`, the list `claimHomeFor` accepts). A claim that could not be WRITTEN is marked at the write that failed (`claimWrite`: the claim's directory, its private file, its link, and the same of a takeover's own claim) for the system's code as it was thrown there, one of `CLAIM_UNWRITABLE_CODES`; the mark travels on the refusal (`unwritableCode`), and an answer made after a takeover ended something carries none. One caller reads it, `claimHomeFor` with the option `READ_CLAIM_WHEN_UNWRITABLE`, which a stop apply passes and nobody else: it then reads the claim where it would have taken it (`claimUnheld`: nobody, or the refusal the taking would have given, from the same builder) and answers a holding without a claim, whose `look()` makes that read again. No caller tells that failure from another by an answer's code, words or `details.cause`: a defect and a claim that could not be removed are `E_LIFECYCLE_FAILED` too A holder may add to its record as it goes (`recordInClaim`), and the next holder reads what a gone one left: a worktree add its running Git step; a retire the retire hooks that ended, `retireHooks: [{capability, meta?}]` with `retireHooksFor` (the home's `createdAt`: the list is bound to the incarnation it ran for, so a claim left by a retire that is gone never skips hooks for another home of the same name), which the retire that takes the claim over does not run again (`core.mjs` `finishedRetireHooks`; `claimHomeFor` hands the gone holder's record over as `tookOver`). A record without them skips nothing. |
@@ -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.42.1
43
+ oats.okf: v6.2.0
44
+ oats.aweb: v1.43.0
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.2` (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.42.1` | `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.43.0` | `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