@awebai/oats 0.69.20 → 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.
package/bin/oats.mjs CHANGED
@@ -83,7 +83,7 @@ const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = aw
83
83
  const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
84
84
  const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
85
85
  const { observeInstanceGit, diffInstanceFile, NO_FILE_MONITOR } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
86
- const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
86
+ const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstancePin, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
87
87
  const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
88
88
  const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
89
89
  const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
@@ -1453,8 +1453,8 @@ async function instanceCmd() {
1453
1453
  if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
1454
1454
  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
1455
1455
  if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
1456
- const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1457
- if (!["git", "diff", "stop", "events", "color", "background", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1456
+ const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message=<text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message=<text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json] | oats instance background <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json] | oats instance same-work <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1457
+ if (!["git", "diff", "stop", "events", "color", "background", "pin", "same-work"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
1458
1458
  dropAmbientRoot();
1459
1459
  if (sub === "events") {
1460
1460
  // K7: typed producer events, bounded window; nothing inferred.
@@ -1528,6 +1528,25 @@ async function instanceCmd() {
1528
1528
  return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1529
1529
  }
1530
1530
  }
1531
+ if (sub === "pin") {
1532
+ // Feature instance-pin: presentation only, so no plan; addressed as `instance background` addresses an instance.
1533
+ const homeOpt = flag("home");
1534
+ if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
1535
+ const pinUsage = "usage: oats instance pin <instance> on|off [--home <abs>] [--dir <d>] [--json]";
1536
+ // The words after the instance that are not a flag or the value of --home or --dir: exactly one, on or off.
1537
+ const words = [];
1538
+ for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
1539
+ if (words.length !== 1 || !["on", "off"].includes(words[0])) return bail("E_BAD_ARGS", `give on or off; ${pinUsage}`);
1540
+ let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
1541
+ try {
1542
+ const r = setInstancePin(dirFlag(), root, name, { home: homeOpt, pinned: words[0] === "on" });
1543
+ if (JSON_MODE) { jsonOk(r); return; }
1544
+ console.log(`${r.instance}: ${r.pinned ? "pinned" : "not pinned"}${r.changed ? "" : " (unchanged)"}`);
1545
+ return;
1546
+ } catch (e) {
1547
+ return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
1548
+ }
1549
+ }
1531
1550
  if (sub === "same-work") {
1532
1551
  // Feature instance-same-work: presentation only, so no plan; addressed as color addresses an instance.
1533
1552
  const homeOpt = flag("home");
@@ -5245,6 +5264,10 @@ Usage:
5245
5264
  oats instance background <instance> on|off [--home <abs>] [--json]
5246
5265
  whether clients list the instance under
5247
5266
  Background, presentation only
5267
+ oats instance pin <instance> on|off [--home <abs>] [--json]
5268
+ pin the instance at the top of its machine's
5269
+ list; shared, as every viewer of the machine
5270
+ reads it from the home
5248
5271
  oats instance same-work <instance> on|off [--home <abs>] [--json]
5249
5272
  record that this instance does the same work as
5250
5273
  its parent (on needs a recorded parent); clients
@@ -333,7 +333,7 @@ A self-contained package has an `oats.json`:
333
333
  - an exact name that is `.oats`, `.agents` or `.claude`, or that starts
334
334
  with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
335
335
  `.oats-agents-md`, `.oats-start`, `.oats-attachments`, `.oats-color`,
336
- `.oats-background` or `.oats-same-work`: the top-level entries the kernel
336
+ `.oats-background`, `.oats-pinned` or `.oats-same-work`: the top-level entries the kernel
337
337
  itself writes in an instance home;
338
338
  - a prefix that starts with `.oats-`.
339
339
 
@@ -374,7 +374,7 @@
374
374
  "description": "Home entries the kernel owns cannot be declared.",
375
375
  "anyOf": [
376
376
  {"pattern": "^\\.(?:oats|agents|claude)$"},
377
- {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|same-work)"},
377
+ {"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color|background|pinned|same-work)"},
378
378
  {"pattern": "^\\.oats-.*\\*$"}
379
379
  ]
380
380
  }
@@ -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 |
@@ -3762,6 +3764,10 @@ its absence.
3762
3764
  holds a valid background record ([Background instances](#background-instances-oats-instance-background)),
3763
3765
  absent otherwise; never `false`. A `background` in `instance.json` never
3764
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.
3765
3771
  - <a id="row-same-work"></a>**`sameWork`** (feature `instance-same-work`):
3766
3772
  `true` when the home's same-work flag
3767
3773
  ([Same work as the parent](#same-work-as-the-parent-oats-instance-same-work))
@@ -4040,6 +4046,10 @@ route target:
4040
4046
  host's row has exactly `background: true`; any other value, a host whose
4041
4047
  kernel predates the feature and a saved route the host did not list carry
4042
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)).
4043
4053
  - **`sameWork`** (feature `instance-same-work`) is on a row only when the
4044
4054
  host's row has `sameWork: true`, and is then `true`. Any other value, a host
4045
4055
  whose kernel predates the feature, and a saved route the host did not list
@@ -4288,6 +4298,7 @@ instance's own machine: the local command, with `--server <id>` added.
4288
4298
  | `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
4289
4299
  | `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
4290
4300
  | `oats instance background <name> on\|off --server <id>` | none | `instance-background` |
4301
+ | `oats instance pin <name> on\|off --server <id>` | none | `instance-pin` |
4291
4302
  | `oats instance same-work <name> on\|off --server <id>` | none | `instance-same-work` |
4292
4303
 
4293
4304
  - The flags are the local command's. The instance is addressed like every
@@ -6840,6 +6851,75 @@ on [remote roster rows](#the-remote-roster-oats-server-roster---json), on
6840
6851
  [`oats souls`](#oats-capabilities-and-oats-souls) for a soul that declares
6841
6852
  it. Each is absent when not background.
6842
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
+
6843
6923
  ## Same work as the parent (`oats instance same-work`)
6844
6924
 
6845
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
 
@@ -1128,9 +1169,9 @@ letters. So `oats-desktop-expert` is DE, `oats-okf--knowledge-maintainer` KM and
1128
1169
  `oats.aweb` OA. Two names can share a mark (`oats-expert` and
1129
1170
  `oats-operator-expert` are both OE); the name and the colour tell them apart.
1130
1171
 
1131
- Roster rows, soul cards, the soul page, the context panel and the spawn
1132
- dialog show each instance's or soul's harness as a small badge, next to its
1133
- 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
1134
1175
  whether that harness is installed or signed in. Pi's badge is the official
1135
1176
  pi.dev press-kit mark (MIT), and Claude Code's is Anthropic's Claude spark
1136
1177
  in the theme's colours. The Codex badge is OATS's own drawing, not OpenAI's
@@ -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. |
@@ -41,7 +41,7 @@ arrives from.
41
41
  # oats-workspace.yaml: one default per slot, for every soul
42
42
  packages:
43
43
  oats.okf: v6.2.0
44
- oats.aweb: v1.42.1
44
+ oats.aweb: v1.43.0
45
45
  oats.linear: v1.0.1
46
46
  oats.jira: v1.0.1
47
47
  defaults:
@@ -11,7 +11,7 @@ or workspace membership alone does not make a package official.
11
11
  |---|---|---|---|
12
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
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) | |
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` |
package/docs/packages.md CHANGED
@@ -80,7 +80,7 @@ members:
80
80
  packages:
81
81
  oats.framework: v1.26.0
82
82
  oats.okf: v6.2.0
83
- oats.aweb: v1.42.1
83
+ oats.aweb: v1.43.0
84
84
  teams:
85
85
  platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
86
86
  defaults:
@@ -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.42.1 # a catalog version
158
+ oats package add oats.aweb v1.43.0 # 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
  ```