@awebai/oats 0.69.20 → 0.69.22
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/container.md +311 -4
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/desktop-cli-api.md +80 -0
- package/docs/desktop.md +404 -177
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/official-catalog.md +44 -1
- package/docs/packages.md +2 -2
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.21.md +155 -0
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/servers.md +5 -1
- package/docs/souls-and-instances.md +11 -0
- package/docs/tui.md +44 -4
- package/docs/upgrading.md +16 -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/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +3 -0
- package/packages/client/deployment-panel.mjs +2 -0
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +62 -20
- package/packages/client/keymap.mjs +11 -3
- package/packages/client/remote-roster.mjs +8 -1
- package/packages/client/roster-row-facts.mjs +50 -0
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +283 -30
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# K2 retirement audit against oats.aweb v1.44.0
|
|
2
|
+
|
|
3
|
+
Release: `v1.44.0`, peeled commit `5d1c6720bdf60a16379f8486c7d3f6f972294279`.
|
|
4
|
+
Transfer merge: `dc90c9556e58d03a80da9c5b3e6ed6139f22471e`; `git merge-base --is-ancestor dc90c955 v1.44.0` exits 0 in the owned `.work-aweb-audit` tree.
|
|
5
|
+
Original assertion inventory: kernel `3a5503c2993a307a0bb48d0b41dcab7d175adc27`.
|
|
6
|
+
Released transfer manifest: [docs/kernel-test-transfer.md](https://github.com/awebai/oats-aweb/blob/v1.44.0/docs/kernel-test-transfer.md) (17 + 11 + 9 + 19 = 56 rows).
|
|
7
|
+
This is a static assertion match, not a run of provider tests or a claim about a CI result. Of the 47 original rows in hook-1-10, hook-1-12 and hook-1-13, three native opt-ins were already removed by PR #1992; this change retires the other 44. Hook-1-12-1's nine rows remain under the hold below.
|
|
8
|
+
|
|
9
|
+
Package test files below are at that exact released commit. Titles/behaviour identify cases independently of line shifts. `hook13` means `test/oats-aweb-hook-1-13.test.mjs`; other short names are files under `test/` with `.test.mjs` suffix. The old kernel files run provider binaries directly and never the kernel hook runner.
|
|
10
|
+
|
|
11
|
+
## hook-1-10 — 17 rows
|
|
12
|
+
|
|
13
|
+
| Original line | Released covering assertion or explicit retirement reason |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| 145 | hook13 normal global grants: scopes, custody-before-mint order, socket/team/cwd/env and written grant home. Old brief spelling is superseded by current messaging text. |
|
|
16
|
+
| 165 | hook13 attachment verification failure vectors: mismatch/missing socket fails, revokes actual fake-service grant and removes home. |
|
|
17
|
+
| 177 | hook13 fresh launch renewal: new home/locator, written grant, old grant revoke and service state. |
|
|
18
|
+
| 192 | hook13 recorded-final-locator readiness: wrong/newer unattached home cannot override selected locator. Old unconditional ready expectation is superseded because broker evidence is now required. |
|
|
19
|
+
| 209 | resident-journey printedStepsJourney: minted disposable grant copied without socket_path, real custody status exits nonzero with missing locator. Replaces external optional fixture. |
|
|
20
|
+
| 222 | 1-18 session runtime matrix, fatal register/refused transition and retire deregister; new “an unrecognized delivery setting uses the channel route for Claude” covers fallback explicitly. |
|
|
21
|
+
| 255 | 1-18 codex/claude/pi transitions, registration-state assertions, refusal to leave two paths and side-effect-free preview cases. |
|
|
22
|
+
| 292 | 1-17-4 killed/deadline mint returns confirmed identity for compensation; killed-mint-240 retains intent cleanup/redaction. Old test never invoked kernel compensation. |
|
|
23
|
+
| 304 | 1-17-4 “retire recovers an alias missing from meta from the workspace binding”: exact delete argv uses recovered alias. |
|
|
24
|
+
| 317 | 1-17-4 alias-held first/retry receipts and successful self-delete retry: aliasReusable, persisted completion, exactly one delete. Old arbitrary native reason spelling is superseded by current native reason handling. |
|
|
25
|
+
| 341 | 1-17-4 alias-held refusal, no meta, redaction and --name remedy; killed-mint-240 covers refusal intent removal. |
|
|
26
|
+
| 356 | oats-aweb 64/65-character alias test plus 1-17-4 exactly one init --join-from from home: exact argv and absence of separate token/invite route. |
|
|
27
|
+
| 389 | retained-seat-killed-spawn-228 “retained authority closure, copy exclusions, command sequence and lock do not depend on a spawner PID”; copied bytes, exclusions, lock.home/no pid, no API-key leak/no mint. retained-seat-modes checks private directories and files at all nested depths plus source unchanged; lock-227/-236/restart-226 own takeover/source retention. Old check --online tuple intentionally superseded by native status/whoami (#276). |
|
|
28
|
+
| 439 | retained-seat-killed-spawn-228 rollback vector “a status pointing elsewhere”: second connect in original cwd, copied state and lock absent, source key preserved. |
|
|
29
|
+
| 457 | Same test vector “a whoami with another DID”: same restoration/cleanup assertions. |
|
|
30
|
+
| 469 | retained-seat-restart-226 local identity and no grant/custody calls; 1-14 retained retirement drops lock while preserving retained primary. |
|
|
31
|
+
| 484 | retained-seat-killed-spawn-228 vector “wake registration refused after connect”: restore original binding, remove copied authority/lock, preserve source. |
|
|
32
|
+
|
|
33
|
+
## hook-1-12 — 11 rows
|
|
34
|
+
|
|
35
|
+
| Original line | Released covering assertion or explicit retirement reason |
|
|
36
|
+
| --- | --- |
|
|
37
|
+
| 126 | 1-17-4 byte-for-byte local spawn output across runtime/delivery and 1-18 channel matrix cover metadata/env/launch. |
|
|
38
|
+
| 141 | hook13 parameterized “global spawn refuses missing resident name” and “unresolved resident”: fatal remedy before mint. |
|
|
39
|
+
| 156 | hook13 “global spawn refuses retained source in global mode before mint”: both configuration keys in warning, no mint. |
|
|
40
|
+
| 167 | hook13 legacy grant receipt: full explicit scopes/90m TTL, seat/global metadata, env, exact mint and wake tuples, custody cwd/no inherited identity home. |
|
|
41
|
+
| 193 | hook13 wrong minted team, both successful/failed compensation: service team/status, retained seat receipt, truthful live-grant metadata/remedy, team-qualified revoke cwd/no caller identity. |
|
|
42
|
+
| 209 | hook13 global post-mint wake-register failure: actual revoked service state, absent grant metadata/home, retained seat receipt, correct custody cwd/env. |
|
|
43
|
+
| 223 | hook13 no-JSON mint, revoke failure=false: id recovered from grant.yaml, exact team-qualified revoke/custody cwd/env, actual revoked state, home removed, truthful warning. |
|
|
44
|
+
| 237 | Same no-JSON case failure=true: actual active state, compensation grant metadata and remedy, home removed, no false revoked claim. The transfer preserves the current removal policy; it does not endorse a new policy. |
|
|
45
|
+
| 250 | hook13 global retire uses custody, caller identity cleared, exact revoke, wake deregister and identityRevoked. |
|
|
46
|
+
| 267 | hook13 uncertain-revoke show-status revoked/active vectors: show invoked for current team/id; retired/identityRevoked only on revoked, active fails and warns. |
|
|
47
|
+
| 281 | hook13 missing-id retire now uses documented nothing-to-delete; never-grant failed revoke covers finite expiry and never-grant remedy plus successful retry. Old nothing-to-revoke assertion is deliberately rejected by K1's kernel contract. The base also asserted hookCleanupComplete against the real mirror answer; that kernel integration survives in test/aweb-mirror-retire-contract.test.mjs, while K1's lifecycle runner test remains unchanged. |
|
|
48
|
+
|
|
49
|
+
## hook-1-12-1 — 9 rows retained
|
|
50
|
+
|
|
51
|
+
**Hold:** this entire file remains unchanged at the pin merge. Its current
|
|
52
|
+
base test at lines 217–222 was adapted for oats-aweb#286: the onboarding menu
|
|
53
|
+
must show `--invite-stdin` and must never show `--invite <token>`. Released
|
|
54
|
+
v1.44.0 emits that menu but has no test of these two menu assertions. The
|
|
55
|
+
original audit keyed to 3a5503c2 incorrectly classified this adapted current
|
|
56
|
+
behaviour as obsolete prose. Retire this file only after the package carries
|
|
57
|
+
those assertions in a released version and the kernel pins it. The parent
|
|
58
|
+
owns that provider follow-up (decision `6403afb0-8600-4c17-972f-595818e6b90c`).
|
|
59
|
+
The other eight rows are retained with it until that gate is satisfied.
|
|
60
|
+
|
|
61
|
+
| Original line | Released covering assertion or explicit retirement reason |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| 115 | oats-aweb roots[team] before root/workspace primary spawn: selected authority, one mint from new home, .aw env, no separate invite/join. |
|
|
64
|
+
| 144 | oats-aweb explicitly selected empty root: refuses rather than falling back to working workspace root, names selected root/current setup remedy, no init. Old classic/bounded prose is obsolete. |
|
|
65
|
+
| 167 | oats-aweb authority discovery does not walk above workspace: ancestor authority cannot mint. |
|
|
66
|
+
| 191 | 1-14 classic OATS environment refuses spawn/setup/binding before any aw call. |
|
|
67
|
+
| 205 | RETAIN: current base #286 menu assertions require --invite-stdin and forbid --invite <token>; no released v1.44.0 menu test pins them. Other setup acts cover missing team/root but do not cover this token-hygiene menu contract. |
|
|
68
|
+
| 224 | workspace-readiness-wire binding-less check pins ready result and read-only wake read; no-team readiness/spawn test pins actionable failure. Retire old combined error ordering: current no-team result and broker prerequisites supersede it. |
|
|
69
|
+
| 254 | 1-15 unmapped default refuses both spawn and binding; no init or team calls/active-team fallback. |
|
|
70
|
+
| 277 | 1-15 removed settings.team refuses spawn and binding with zero native effects. |
|
|
71
|
+
| 298 | setup-team-roots / setup-invite-56 / 1-21 current invite combinations cover explicit deployment/join and token redaction. Retire old argument/help prose where current native invite inspection now supports token-only joining; no old refusal is claimed as still required. |
|
|
72
|
+
|
|
73
|
+
## hook-1-13 — 19 rows
|
|
74
|
+
|
|
75
|
+
| Original line | Released covering assertion or explicit retirement reason |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| 164 | hook13 normal grants scopes, custody ordering, socket/team/cwd/env and materialized home. |
|
|
78
|
+
| 185 | hook13 reviewer/default/explicit scopes and unknown profile refusal. |
|
|
79
|
+
| 207 | hook13 typed custody failure/status/errors and serve remedy before mint. |
|
|
80
|
+
| 219 | hook13 grant-status endpoint readiness, missing readiness compatibility, required certificate. |
|
|
81
|
+
| 242 | hook13 real floor custody preflight case: explicit Claude runtime, native needs-configuration/custody_unavailable and no grant minted. v1.44.0 CI unit job provisions AW_REAL_CLI_BIN and zero-skips gate; this audit does not claim a CI run succeeded. |
|
|
82
|
+
| 260 | resident-journey real minted missing-socket case, as hook10:209; removes duplicate external fixture. |
|
|
83
|
+
| 271 | hook13 missing E2EE ops refuses; explicit e2ee:false permits signing-only with warning. |
|
|
84
|
+
| 287 | hook13 single aw floor refuses old binary before mint, always passes team. |
|
|
85
|
+
| 305 | hook13 all attachment verification failures revoke service grant and remove home. |
|
|
86
|
+
| 326 | hook13 missing preflight socket refuses before mint/home creation. |
|
|
87
|
+
| 337 | hook13 grant.yaml alias overrides mint alias, resident fallback only when both absent. |
|
|
88
|
+
| 352 | hook13 recorded-final-locator readiness supersedes old ready-without-broker assertion, as hook10:192. |
|
|
89
|
+
| 372 | hook13 renewal off retains locator/metadata, session env and registration on existing grant. |
|
|
90
|
+
| 386 | hook13 local renew=launch retains local identity env and delivery without grant renewal. |
|
|
91
|
+
| 398 | hook13 fresh renewal writes new home, emits exact locator and revokes old grant. |
|
|
92
|
+
| 416 | hook13 mint failure keeps old home/locator/grant and warns without old revoke. |
|
|
93
|
+
| 432 | hook13 failed attachment/missing preflight keeps old grant; any failed newly minted grant is revoked/removed. |
|
|
94
|
+
| 461 | hook13 old revoke failure warns truthfully and keeps newly active grant/home. |
|
|
95
|
+
| 474 | hook13 retire current grant id and every .aweb-identity directory; additional custody cwd/env/wake tuple in transferred retire test. |
|
|
96
|
+
|
|
97
|
+
## Satisfied retirement gates
|
|
98
|
+
|
|
99
|
+
K1 #1950 merged as 6b69263e66bdb29f802c7f4b8aef75edfe057bc4. Keep `test/retire-hook-contract.test.mjs` unchanged; it exercises kernel consumption in ordinary retire, rollback, quarantine retry and outstanding hook debt.
|
|
100
|
+
OATS #1989 merged as `6d3d282ede454567232c7ec0fca978773c03b84a`, this
|
|
101
|
+
branch's ancestor. The branch is rebased onto PR #1992 merge
|
|
102
|
+
`e98b719563c24733322b77926b57e676f223970a`. The catalog pins `v1.44.0`. A read-only Git-object comparison
|
|
103
|
+
matched all 70 mirrored blobs, their executable modes/symlink targets and the
|
|
104
|
+
complete file/directory set to that release. No mirror bytes were edited.
|
|
105
|
+
|
|
106
|
+
This change removes exactly three direct-provider suites:
|
|
107
|
+
`test/oats-aweb-hook-1-10.test.mjs`, `test/oats-aweb-hook-1-12.test.mjs`,
|
|
108
|
+
`test/oats-aweb-hook-1-13.test.mjs`.
|
|
109
|
+
`test/oats-aweb-hook-1-12-1.test.mjs` remains unchanged under the hold above.
|
|
110
|
+
The table above records every source test, its released covering case or
|
|
111
|
+
specific superseded/prose reason, and the hold for the uncovered menu case. The released package retains the regression
|
|
112
|
+
coverage; no direct-provider suite is renamed as kernel integration evidence.
|
|
113
|
+
Release-lane adaptations outside the retired files remain, as does K1's kernel
|
|
114
|
+
contract test. The new mirror/classifier test retains the base-state bridge
|
|
115
|
+
and rejects any native aw call at its boundary. No production code or deployment contract changes.
|
|
116
|
+
|
|
117
|
+
The maintainer authorized retirement after both merges and this released-row
|
|
118
|
+
match (parent decisions `cef42455-e66b-405e-87bc-a2edd82f2695` and
|
|
119
|
+
`e55641a6-1e17-4b71-98a4-6436c1293b0d`). The pre-deletion plan and complete
|
|
120
|
+
row table were sent as `4b923d01-236a-4c44-8a03-2c268f42a684`.
|
|
121
|
+
Full CI was not run locally; it runs after parent acceptance and PR creation.
|
|
122
|
+
|
|
123
|
+
The r1 findings were accepted in parent decision `6403afb0-8600-4c17-972f-595818e6b90c`: split the retirement, keep the current token-hygiene test until released coverage, and preserve the real mirror/classifier bridge in a small kernel test.
|
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).
|