@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 +26 -3
- package/docs/capabilities.md +1 -1
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +106 -65
- package/docs/implementation.md +1 -1
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +2 -2
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/upgrading.md +11 -5
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +1 -0
- package/lib/core.mjs +5 -3
- package/lib/instance-inspect.mjs +3 -0
- package/lib/instance-lifecycle.mjs +16 -0
- package/lib/instance-listing.mjs +8 -4
- package/lib/instance-pin.mjs +59 -0
- package/lib/kernel-features.mjs +1 -1
- package/lib/servers.mjs +8 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/skills/oats-getting-started/SKILL.md +210 -27
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
|
package/docs/capabilities.md
CHANGED
|
@@ -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
|
}
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -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 **
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
**
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
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,
|
|
290
|
-
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
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
|
|
973
|
-
|
|
974
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
987
|
-
parent
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
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
|
|
1002
|
-
palette (which still finds the instance by its name), its terminal tab,
|
|
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
|
|
1015
|
-
Workspace page's tabs),
|
|
1016
|
-
scheduler that is off.
|
|
1017
|
-
The row keeps its soul and
|
|
1018
|
-
hears "Needs input" after the name,
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
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.
|
|
1034
|
-
|
|
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
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
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
|
package/docs/implementation.md
CHANGED
|
@@ -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. |
|
package/docs/integrations.md
CHANGED
package/docs/official-catalog.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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
|
```
|