@awebai/oats 0.69.17 → 0.69.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +7 -0
  4. package/docs/container.md +172 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/desktop-cli-api.md +73 -33
  7. package/docs/desktop.md +40 -18
  8. package/docs/execution-targets.md +36 -33
  9. package/docs/implementation.md +7 -6
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge.md +5 -5
  12. package/docs/official-catalog.md +7 -7
  13. package/docs/packages.md +13 -13
  14. package/docs/release-lane.md +24 -19
  15. package/docs/release-notes/v0.69.18.md +358 -0
  16. package/docs/servers.md +3 -1
  17. package/docs/souls-and-instances.md +18 -16
  18. package/docs/trust-model.md +119 -0
  19. package/docs/upgrading.md +39 -19
  20. package/docs/workspaces.md +3 -3
  21. package/lib/command-flags.mjs +1 -1
  22. package/lib/core.mjs +24 -9
  23. package/lib/errors.mjs +1 -1
  24. package/lib/home-owner.mjs +25 -0
  25. package/lib/host-run-admission.mjs +21 -0
  26. package/lib/host-run-child.mjs +31 -0
  27. package/lib/host-run-work.mjs +150 -0
  28. package/lib/host-run.mjs +20 -11
  29. package/lib/instance-naming.mjs +26 -44
  30. package/lib/packages.mjs +0 -43
  31. package/lib/pi-bridge.mjs +18 -6
  32. package/lib/schedule.mjs +5 -3
  33. package/lib/servers.mjs +4 -3
  34. package/lib/session-end.mjs +9 -0
  35. package/lib/session-resume.mjs +19 -9
  36. package/lib/session-seen.mjs +13 -8
  37. package/lib/triggers.mjs +3 -1
  38. package/lib/worktree.mjs +5 -2
  39. package/package-catalog.json +3 -3
  40. package/package.json +2 -2
  41. package/packages/client/above-tested-notice.mjs +30 -0
  42. package/packages/client/above-tested.mjs +225 -0
  43. package/packages/client/cli-locator.mjs +67 -52
  44. package/packages/client/deployment-label.mjs +4 -4
  45. package/packages/client/instance-name.mjs +5 -29
  46. package/packages/client/session-start.mjs +31 -3
  47. package/packages/client/workspace-choices.mjs +1 -1
  48. package/packages/client/workspace-views.mjs +1 -1
  49. package/packages/record/README.md +10 -8
  50. package/packages/record/lib/process-identity.mjs +14 -36
  51. package/packages/tui/lib/read.mjs +19 -3
  52. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -0,0 +1,225 @@
1
+ /* What a client still does with an oats CLI above its tested bound (oats-project/oats#1879, option 3).
2
+
3
+ The locator accepts a released CLI of a later minor or major than the client's own release and flags it
4
+ `aboveTested` (cli-locator.mjs acceptProbe). This module names every operation that stays on then, each
5
+ with its reason, and DENIES EVERYTHING ELSE: an operation not named here, an operation added later
6
+ included, is held back until the Desktop is updated. A new operation is opened above the bound only by
7
+ adding it here, with a reason (the decision's condition 1).
8
+
9
+ Why these and not others: the four traced cases on #1879 (schedule edit at 0.40, Remove at 0.49 and
10
+ 0.53, the Stop outcome at 0.52) all sit where the Desktop words a consequence itself or writes a whole
11
+ definition. What stays on is a read, a terminal, or a change fenced by the kernel's own answer: Spawn
12
+ applies only the decision its preview showed (`--expect-decision`), and Start, Restart, colour and
13
+ background report only an answer the Desktop reads in full (each fails closed on a shape it does not
14
+ know).
15
+
16
+ Enforcement is not the renderer's. Every place an operation enters the backend asks
17
+ `aboveTestedRefusal(cli, operation)` before any CLI process starts: each POST handler of
18
+ packages/desktop/server/oats-web.mjs by (route, action), and each caller in main that runs the CLI for
19
+ an effect (packages/desktop/main.mjs, session-resume-launch.mjs). The renderer reads the same table to
20
+ disable what would be refused, and never decides by itself.
21
+
22
+ An operation is a string: `POST <route> <action>` for an HTTP entry whose body names an action (the
23
+ action is the body's `action`, or `<kind>:<action>` for /api/automations), `POST <route>` for one that has
24
+ none, and `main <what>` for an entry outside HTTP. packages/desktop/test/above-tested-inventory.test.mjs
25
+ holds every POST route the server accepts, and every module that executes a command, to a class here.
26
+
27
+ Pure data; no node: imports, so the renderer shares it with the server. */
28
+ import { aboveTestedNotice, desktopReleaseUrl } from './above-tested-notice.mjs';
29
+
30
+ /** The refusal's code: the Desktop's own, never the kernel's. */
31
+ export const ABOVE_TESTED_CODE = 'cli-above-tested';
32
+
33
+ /** The reads that stay on, as a named set: every operation of class `read` is one of them. */
34
+ export const READS = Object.freeze({
35
+ status: 'the deployment observation (`oats status`, `oats workspace status`, the souls and capabilities catalogs)',
36
+ roster: 'the remote roster and the machines list',
37
+ inspect: 'what a soul, an instance or a capability is (`oats inspect`, `oats capabilities show`, the launch configurations)',
38
+ readiness: '`oats readiness`',
39
+ events: "an instance's events",
40
+ git: "an instance's Git state and diffs, and the forge reads beside them (they run gh, never oats)",
41
+ preview: 'the spawn and launch previews',
42
+ version: 'the `version --json` probe itself',
43
+ 'warm reader': 'the warm `oats reader --stdio` the background reads go through',
44
+ });
45
+
46
+ const read = (name) => Object.freeze({ class: 'read', reason: READS[name], read: name });
47
+ const allowed = (reason) => Object.freeze({ class: 'allowed', reason });
48
+ const held = (reason) => Object.freeze({ class: 'held', reason });
49
+
50
+ const HELD_WRITE = 'it writes something an older Desktop may word or shape wrongly for a newer kernel';
51
+
52
+ /** Every operation, by its name (see the header for the form). Anything not here is held back. */
53
+ export const OPERATIONS = Object.freeze({
54
+ // ── Spawn: the preview the apply is bound to, and the apply that the kernel fences.
55
+ 'POST /api/spawn prepare': allowed('Spawn: prepares the apply from the preview it is bound to'),
56
+ 'POST /api/spawn apply': allowed('Spawn: applies only the decision its preview showed (--expect-decision); a drift is E_DECISION_STALE'),
57
+ 'POST /api/spawn result': read('preview'),
58
+ 'POST /api/spawn execution-server': held('an execution-server spawn is not fenced by --expect-decision'),
59
+ 'POST /api/workspace-spawn-preview preview': allowed('Spawn: the preview, a read'),
60
+ 'POST /api/workspace-spawn-preview suggest': allowed('Spawn: a suggested task, a read'),
61
+ 'POST /api/workspace-spawn-preview suggest-name': allowed('Spawn: a suggested name, a read'),
62
+ // ── Start and Restart: an answer the Desktop reads in full, nothing worded by the Desktop.
63
+ 'POST /api/start': allowed('Start: the kernel starts the session and answers what it started'),
64
+ 'POST /api/restart': allowed('Restart: the kernel restarts the session and answers what it started'),
65
+ // ── An instance's own record.
66
+ 'POST /api/instance-color': allowed("colour: one field of the instance's own record, the answer read in full"),
67
+ 'POST /api/instance-background': allowed("background: one field of the instance's own record, the answer read in full"),
68
+ // ── Reads.
69
+ 'POST /api/instance-git git': read('git'),
70
+ 'POST /api/instance-git diff': read('git'),
71
+ 'POST /api/instance-events read': read('events'),
72
+ 'POST /api/workspace-readiness read': read('readiness'),
73
+ 'POST /api/capabilities inspect': read('inspect'),
74
+ 'POST /api/capabilities show': read('inspect'),
75
+ 'POST /api/capabilities file': read('inspect'),
76
+ 'POST /api/workspace-sync read': read('status'),
77
+ 'POST /api/launch-configs list': read('inspect'),
78
+ 'POST /api/launch-configs preview': read('preview'),
79
+ 'POST /api/workspace-teams list': read('inspect'),
80
+ 'POST /api/workspace-soul-teams show': read('inspect'),
81
+ 'POST /api/automations trigger:list': read('status'),
82
+ 'POST /api/automations trigger:status': read('status'),
83
+ 'POST /api/automations schedule:list': read('status'),
84
+ 'POST /api/forge-connections': read('git'),
85
+ 'POST /api/instance-forge': read('git'),
86
+ 'POST /api/forge-roster': read('git'),
87
+ 'POST /api/instance-review-threads preview': read('git'),
88
+ 'POST /api/models': read('preview'),
89
+ 'POST /api/cli/reprobe': read('version'),
90
+ 'POST /api/remote-roster/refresh': read('roster'),
91
+ 'POST /api/window-state': read('status'),
92
+ 'POST /api/windows': read('roster'),
93
+ 'main deployments list': read('status'),
94
+ // ── Terminals.
95
+ 'POST /api/instance-review-threads send': allowed("terminals: pastes the review threads into the agent's own terminal, as typing there does"),
96
+ 'main terminal attach': allowed('terminals: attaches to a session the kernel names'),
97
+ 'main terminal viewer': allowed('terminals: a linked, locked viewer of a session'),
98
+ 'main terminal upload': allowed("terminals: files attached to the agent's own terminal, as a paste there does"),
99
+ // ── Held back: named so their reason is on record; anything unnamed is held back too.
100
+ 'POST /api/instance-lifecycle plan': held('Stop and Remove: the dialog words what the kernel will do (the 0.49, 0.52 and 0.53 cases on #1879)'),
101
+ 'POST /api/instance-lifecycle apply': held('Stop and Remove: the dialog words what the kernel will do (the 0.49, 0.52 and 0.53 cases on #1879)'),
102
+ 'POST /api/retire': held('Remove'),
103
+ 'POST /api/schedules': held('a schedule write replaces a whole definition (the 0.40 case on #1879)'),
104
+ 'POST /api/automations schedule:enable': held(HELD_WRITE),
105
+ 'POST /api/automations schedule:disable': held(HELD_WRITE),
106
+ 'POST /api/automations schedule:test': held('runs the schedule'),
107
+ 'POST /api/automations schedule:run': held('runs the schedule'),
108
+ 'POST /api/automations schedule:reconcile': held(HELD_WRITE),
109
+ 'POST /api/automations schedule:describe': held("writes the schedule's description"),
110
+ 'POST /api/automations trigger:enable': held(HELD_WRITE),
111
+ 'POST /api/automations trigger:disable': held(HELD_WRITE),
112
+ 'POST /api/automations trigger:test': held('runs the trigger'),
113
+ 'POST /api/automations trigger:describe': held("writes the trigger's description"),
114
+ 'POST /api/workspace-sync sync': held('writes the lock'),
115
+ 'POST /api/capabilities run': held('runs a provider operation'),
116
+ 'POST /api/workspace-teams add': held(HELD_WRITE),
117
+ 'POST /api/workspace-teams remove': held(HELD_WRITE),
118
+ 'POST /api/workspace-teams default': held(HELD_WRITE),
119
+ 'POST /api/workspace-soul-teams add': held(HELD_WRITE),
120
+ 'POST /api/workspace-soul-teams remove': held(HELD_WRITE),
121
+ 'POST /api/workspace-soul-teams default': held(HELD_WRITE),
122
+ 'POST /api/workspace-soul-teams clear-default': held(HELD_WRITE),
123
+ 'POST /api/launch-configs set': held(HELD_WRITE),
124
+ 'POST /api/launch-configs remove': held(HELD_WRITE),
125
+ 'POST /api/server-connect': held('connects a machine (and messaging) for the workspace'),
126
+ 'POST /api/server-check': held('server check'),
127
+ 'POST /api/server-remove': held('removes a machine'),
128
+ 'POST /api/server-forget': held("forgets a remote row's saved route"),
129
+ 'main session-resume': held('the launch sweep starts sessions the Desktop did not ask for'),
130
+ 'main deployments add': held("writes this computer's deployments list"),
131
+ 'main deployments import': held("writes this computer's deployments list"),
132
+ 'main deployments remove': held("writes this computer's deployments list"),
133
+ 'main workspace onboard': held('creates a deployment'),
134
+ });
135
+
136
+ /** Every module under packages/client/, packages/desktop/ and packages/desktop/server/ that starts a process,
137
+ * by the class of the most that it runs: a module that can run a held-back operation is `held`, and its
138
+ * reason says where that operation is refused. The inventory test finds such modules by what their code
139
+ * names (child_process, execFile, an injected exec, spawn or probe); an unclassified one fails it. */
140
+ export const CLI_MODULES = Object.freeze({
141
+ 'packages/client/cli-adapter.mjs': held('every verb the backend runs; each is refused where it enters, the POST handlers of oats-web.mjs'),
142
+ 'packages/client/cli-locator.mjs': read('version'),
143
+ 'packages/client/deployment-list-cli.mjs': held("its add, import and remove write this computer's deployments list; refused in main (main deployments …)"),
144
+ 'packages/client/deployment-read-cli.mjs': read('status'),
145
+ 'packages/client/file-output-exec.mjs': held('the runner of the session resume sweep, refused in session-resume-launch.mjs (main session-resume)'),
146
+ 'packages/client/lifecycle-cli.mjs': held('Stop and Remove; refused at POST /api/instance-lifecycle'),
147
+ 'packages/client/session-attach.mjs': allowed('terminals: attach'),
148
+ 'packages/client/session-resume-cli.mjs': held('the session resume sweep; refused in session-resume-launch.mjs (main session-resume)'),
149
+ 'packages/client/spawn-apply-cli.mjs': allowed('Spawn apply, fenced by --expect-decision'),
150
+ 'packages/client/spawn-preview-cli.mjs': allowed('Spawn preview, a read'),
151
+ 'packages/client/terminal-exec.mjs': allowed('terminals: the run of an attach'),
152
+ 'packages/client/tmux-status.mjs': read('status'),
153
+ 'packages/client/warm-reader.mjs': read('warm reader'),
154
+ 'packages/client/workspace-cli.mjs': held('its sync and onboard write; refused at POST /api/workspace-sync sync and in main (main workspace onboard)'),
155
+ 'packages/desktop/forge-cli.mjs': read('git'),
156
+ 'packages/desktop/instance-events-cli.mjs': read('events'),
157
+ 'packages/desktop/local-tmux-io.mjs': allowed('terminals: the local tmux the viewers run on'),
158
+ 'packages/desktop/login-path.mjs': read('version'),
159
+ 'packages/desktop/main.mjs': held('runs the deployments list, onboard and the resume sweep; each refused where main calls it'),
160
+ 'packages/desktop/readiness-cli.mjs': read('readiness'),
161
+ 'packages/desktop/server-host.mjs': allowed("starts the Desktop's own backend server (a node process), not the CLI; the server's CLI runs are classified under packages/desktop/server/oats-web.mjs"),
162
+ 'packages/desktop/terminal-attachments.mjs': allowed("terminals: files attached to an agent's terminal (main terminal upload)"),
163
+ 'packages/desktop/terminal-io.mjs': allowed('terminals: the terminal broker'),
164
+ 'packages/desktop/server/oats-web.mjs': held('the POST handlers, each refused by (route, action) before it runs anything'),
165
+ 'packages/desktop/server/review-paste.mjs': allowed("terminals: the paste into the agent's own terminal"),
166
+ });
167
+
168
+ /** The operation's name, as OPERATIONS keys it: `POST <route> <action>`, `POST <route>` when the entry has
169
+ * no action. An action that is not a short printable word names no operation (held back). */
170
+ export function postOperation(route, action) {
171
+ if (action === undefined) return `POST ${route}`;
172
+ return `POST ${route} ${typeof action === 'string' && /^[a-z][a-z:-]{0,63}$/.test(action) ? action : '?'}`;
173
+ }
174
+
175
+ /** The routes OPERATIONS names for a POST. */
176
+ const POST_ROUTES = Object.freeze([...new Set(Object.keys(OPERATIONS).filter((k) => k.startsWith('POST ')).map((k) => k.split(' ')[1]))]);
177
+ const INSTANCE_SEGMENT = /^[A-Za-z0-9._-]+$/;
178
+
179
+ /** Whether a POST to `path` is to a route OPERATIONS names: the route itself, or one instance under it
180
+ * (`<route>/<name>`, as `/api/start/<instance>`). The server asks it of every POST before it dispatches, so a
181
+ * route added without a classification is held back above the bound before its handler runs. */
182
+ export function postRouteClassified(path) {
183
+ return typeof path === 'string' && POST_ROUTES.some((route) => path === route
184
+ || (path.startsWith(`${route}/`) && INSTANCE_SEGMENT.test(path.slice(route.length + 1))));
185
+ }
186
+
187
+ /** Whether `operation` stays on above the tested bound: a read, or allowed. False for anything else. */
188
+ export function permittedAboveTested(operation) {
189
+ const entry = Object.hasOwn(OPERATIONS, operation) ? OPERATIONS[operation] : null;
190
+ return entry?.class === 'read' || entry?.class === 'allowed';
191
+ }
192
+
193
+ /** The notice for an accepted CLI above the tested bound, or null when `cli` is not one: what the card's
194
+ * place shows, and what every refusal carries. */
195
+ export function aboveTestedState(cli) {
196
+ if (cli?.ok !== true || cli.aboveTested !== true || typeof cli.version !== 'string' || typeof cli.testedThrough !== 'string') return null;
197
+ return { message: aboveTestedNotice({ cliVersion: cli.version, testedThrough: cli.testedThrough }), release: desktopReleaseUrl(cli.version), version: cli.version };
198
+ }
199
+
200
+ /** The one gate: null, or the refusal of `operation` while `cli` is above its tested bound, carrying the
201
+ * notice sentence, the release to install and this module's own code. Called before any CLI process
202
+ * starts. A CLI whose flag is set but whose record is incomplete is refused too: no notice is invented,
203
+ * nothing runs. */
204
+ export function aboveTestedRefusal(cli, operation) {
205
+ if (cli?.aboveTested !== true || permittedAboveTested(operation)) return null;
206
+ const state = aboveTestedState(cli);
207
+ return { code: ABOVE_TESTED_CODE, message: state?.message ?? 'This Desktop is older than the installed oats CLI: install the OATS Desktop of its version.',
208
+ ...(state ? { release: state.release } : {}), operation };
209
+ }
210
+
211
+ /** The operation each roster act runs (instance-acts.mjs verbs): Stop and Remove open the lifecycle plan,
212
+ * Start and Restart their own route. `inspect` and `open` are reads and terminals, and run none of these. */
213
+ export const ACT_OPERATIONS = Object.freeze({ start: 'POST /api/start', restart: 'POST /api/restart',
214
+ stop: 'POST /api/instance-lifecycle plan', retire: 'POST /api/instance-lifecycle plan' });
215
+
216
+ /** A roster row's acts (instance-acts.mjs `instanceActs`) with each act held back above the tested bound made
217
+ * not enabled, its reason the notice sentence (`{ code, sentence }`, as an act's reason is read). The same
218
+ * answer otherwise. */
219
+ export function heldBackActs(offer, cli) {
220
+ if (cli?.aboveTested !== true || !Array.isArray(offer?.acts)) return offer;
221
+ return { ...offer, acts: offer.acts.map((act) => {
222
+ const refused = Object.hasOwn(ACT_OPERATIONS, act.verb) ? aboveTestedRefusal(cli, ACT_OPERATIONS[act.verb]) : null;
223
+ return refused && act.enabled ? { ...act, enabled: false, reason: { code: refused.code, sentence: refused.message } } : act;
224
+ }) };
225
+ }
@@ -13,8 +13,11 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.70.0 (the band is
17
- // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
16
+ // Desktop accepts desktopApi === 1 and a released semver at or above the floor
17
+ // (ACCEPT_RANGE.min). There is no ceiling: a CLI of a later minor than the
18
+ // client's own release (its TESTED BOUND, testedBound below) is accepted and
19
+ // flagged `aboveTested`, and the client then holds back every operation its
20
+ // allowlist does not name (above-tested.mjs, oats-project/oats#1879).
18
21
  // API version — not source adjacency — is authoritative.
19
22
  //
20
23
  // Pure/injected: all process, fs and exec effects come through `io` so the
@@ -24,39 +27,34 @@ import { delimiter, isAbsolute, join } from "node:path";
24
27
  import { harnessList } from "./harness-names.mjs";
25
28
 
26
29
  export const DESKTOP_API = 1;
27
- // The accepted band is per-minor and widened DELIBERATELY, once per kernel
28
- // minor, after confirming the Desktop v1 surface (`version --json` probe,
29
- // `spawn --json`, `okf harvest --json` — test/cli-json-contract.test.mjs) is
30
- // unchanged. It must always admit the kernel version shipped by the SAME
31
- // release: Desktop and the kernel are built from one tag, so a band that
32
- // excluded its own kernel would ship an app that degrades to observation-only
33
- // against the CLI it was released with (the 0.19.0 readiness blocker).
34
- // Rebased to >=0.22.0 <0.23.0 for the OATS rename (v0.22.0, first release
35
- // under the new name): the CLI binary and probe name changed to `oats` /
36
- // `@awebai/oats`, so the pre-rename band pointed at versions that will never
37
- // exist under the new name. The Desktop v1 surface is UNCHANGED across that
38
- // kernel bump (`version --json`, `spawn --json`, `okf harvest --json` —
39
- // test/cli-json-contract.test.mjs), so DESKTOP_API stays 1.
40
- // Widened through 0.24.x for the retained-execution first cut. Desktop CLI API
41
- // v1 and the 0.22.x floor remain unchanged; individual capability/refusal gates
42
- // still apply. Version acceptance does not assert captured UI/backend parity.
43
- // Widened through 0.25.x for the workspace model (v0.25.0): the Desktop v1
44
- // surface (`version --json` probe, `spawn --json`, the retained lifecycle
45
- // verbs — test/cli-json-contract.test.mjs) is unchanged; the removed verbs
46
- // (`catalog`, install/use/…) surface as typed E_USAGE through the adapter.
47
- // Widened through 0.26.x for package-approval removal (F2b). The floor is
48
- // the first kernel the Desktop's feature gates let through (workspace-cli
49
- // WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES); those gates
50
- // stay the REAL gate.
51
- // Widened through 0.43.x for the 0.43.0 release: schedule and trigger rows
52
- // carry a `description` for every kind and `<kind> update <id> --description`
53
- // sets one (feature `automation-descriptions`, which gates the Desktop's
54
- // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 70, 0] };
56
- /** The band as humans read it — derived, never hand-spelled, so the probe
57
- * rejection reason, the backend's /api status and the degradation card can
58
- * never disagree with the numbers actually enforced above. */
59
- export const ACCEPT_RANGE_TEXT = `>=${ACCEPT_RANGE.min.join(".")} <${ACCEPT_RANGE.maxExclusive.join(".")}`;
30
+ // The floor is hand-set: the first kernel the Desktop's feature gates let through (workspace-cli
31
+ // WORKSPACE_FEATURES, deployment-contract DEPLOYMENT_FEATURES); those gates stay the REAL gate.
32
+ //
33
+ // The upper bound is not spelled here, nor anywhere (oats-project/oats#1879, option 3). It is the
34
+ // TESTED BOUND: the minor of the client's own release version, which the caller passes in (the
35
+ // Desktop server its own manifest, packages/desktop/package.json; `oats tui` its kernel's
36
+ // package.json, which is the kernel it runs). Until 0.69.x it was an exclusive ceiling widened by
37
+ // hand at every minor, and every installed Desktop lost every action at each kernel minor until it
38
+ // was reinstalled. Now a CLI of a later minor or major is accepted with `aboveTested: true`, and
39
+ // only the operations above-tested.mjs allows stay on. The version-bump PR moves the bound with the
40
+ // manifests; nothing in release prep moves it by hand.
41
+ export const ACCEPT_RANGE = Object.freeze({ min: Object.freeze([0, 26, 0]) });
42
+ /** [major, minor] of a client's release version: the newest CLI minor it was tested with. A
43
+ * prerelease or build of a release counts as that release (0.70.0-rc.1 tests 0.70). null for a value
44
+ * that is not a version. */
45
+ export function testedBound(releaseVersion) {
46
+ const v = parseSemver(releaseVersion);
47
+ return v ? [v.nums[0], v.nums[1]] : null;
48
+ }
49
+ /** The bound as people read it: "X.Y". */
50
+ export const testedThroughText = (bound) => `${bound[0]}.${bound[1]}`;
51
+ /** The accepted range as humans read it, derived and never hand-spelled, so the probe rejection
52
+ * reason, the backend's /api/cli and the degradation card can never disagree with what is enforced:
53
+ * the floor, then the tested bound of `releaseVersion` (">=0.26.0, tested through 0.69"). */
54
+ export function acceptRangeText(releaseVersion) {
55
+ const bound = testedBound(releaseVersion);
56
+ return `>=${ACCEPT_RANGE.min.join(".")}${bound ? `, tested through ${testedThroughText(bound)}` : ""}`;
57
+ }
60
58
  // The npm names of the oats CLI. `version --json` answers the first under either, until a later minor flips it.
61
59
  export const PROBE_NAME = Object.freeze(["@awebai/oats", "@oats-project/oats"]);
62
60
  // Spawn-time agent relations (--relation/--relative-to) AND the anchor
@@ -108,24 +106,38 @@ export function parseSemver(v) {
108
106
  }
109
107
  const cmp = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
110
108
 
111
- /** Accept/reject one probe payload. Returns { ok } or { ok:false, reason }, and { ok:false, reason, above:true }
112
- * when the payload's sole failure is a released version at or above the band's ceiling: every other check
113
- * passed first, so a prerelease, an unparsable version or another API is never `above`. A Desktop older than
114
- * its CLI says so from this flag (views/cli-status.mjs), never from the reason's words. */
115
- export function acceptProbe(payload) {
109
+ /** Accept/reject one probe payload against the client's own release version (`testedVersion`,
110
+ * required: see ACCEPT_RANGE). Returns:
111
+ * { ok: true } a CLI of the tested minor or older, down to the floor;
112
+ * { ok: true, aboveTested: true, testedThrough: "X.Y" } a released CLI of a later minor or major;
113
+ * { ok: false, reason } refused, and { ok: false, reason, newerApi: true }
114
+ * when the payload's sole failure is a desktopApi
115
+ * above this client's: the Desktop is the older of the
116
+ * two (views/cli-status.mjs reads the flag, never the
117
+ * reason's words).
118
+ * Without a tested version it refuses: a caller that forgot it never falls back to "no bound". */
119
+ export function acceptProbe(payload, testedVersion) {
120
+ const bound = testedBound(testedVersion);
121
+ if (!bound) return { ok: false, reason: "no tested client version given: the probe is not judged without one" };
116
122
  if (!payload || typeof payload !== "object") return { ok: false, reason: "no probe payload" };
117
123
  if (payload.schemaVersion !== 1) return { ok: false, reason: `unexpected schemaVersion ${payload.schemaVersion}` };
118
124
  if (!PROBE_NAME.includes(payload.name)) return { ok: false, reason: `not the oats CLI (name: ${payload.name || "missing"}, not ${PROBE_NAME.join(" or ")})` };
119
- if (payload.desktopApi !== DESKTOP_API) return { ok: false, reason: `desktopApi ${payload.desktopApi ?? "missing"} (need ${DESKTOP_API})` };
125
+ if (payload.desktopApi !== DESKTOP_API) {
126
+ // Another API, newer than this client's: the client is the older (the card's older-Desktop branch). Only an
127
+ // integer counts; every other check already passed.
128
+ const newer = Number.isSafeInteger(payload.desktopApi) && payload.desktopApi > DESKTOP_API;
129
+ return { ok: false, reason: `desktopApi ${payload.desktopApi ?? "missing"} (need ${DESKTOP_API})`, ...(newer ? { newerApi: true } : {}) };
130
+ }
120
131
  const v = parseSemver(payload.version);
121
132
  if (!v) return { ok: false, reason: `unparsable version "${payload.version}"` };
133
+ const range = acceptRangeText(testedVersion);
122
134
  // Prerelease policy: prereleases are NOT accepted. Precedence-wise
123
135
  // 0.18.0-rc.1 < 0.18.0 (below the minimum), and a prerelease of any
124
- // in-range version is not a released CLI — Desktop pairs with released
125
- // kernels only.
126
- if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${ACCEPT_RANGE_TEXT})` };
127
- if (cmp(v.nums, ACCEPT_RANGE.maxExclusive) >= 0) return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}`, above: true };
128
- if (cmp(v.nums, ACCEPT_RANGE.min) < 0) return { ok: false, reason: `version ${payload.version} outside ${ACCEPT_RANGE_TEXT}` };
136
+ // version is not a released CLI — Desktop pairs with released kernels only,
137
+ // above its tested bound as below it.
138
+ if (v.prerelease) return { ok: false, reason: `prerelease version ${payload.version} not accepted (need a released ${range})` };
139
+ if (cmp(v.nums, ACCEPT_RANGE.min) < 0) return { ok: false, reason: `version ${payload.version} outside ${range}` };
140
+ if (v.nums[0] > bound[0] || (v.nums[0] === bound[0] && v.nums[1] > bound[1])) return { ok: true, aboveTested: true, testedThrough: testedThroughText(bound) };
129
141
  return { ok: true };
130
142
  }
131
143
 
@@ -212,11 +224,14 @@ export function cliRecord(payload, { bin, source }) {
212
224
  * looks valid (review 53a20c7: a binary that prints a plausible probe and
213
225
  * then fails/hangs must never become the mutation binary). Sources are
214
226
  * evaluated lazily: expensive helpers never run once a candidate wins.
227
+ * `io.testedVersion` is the client's own release version (acceptProbe): required, and without it
228
+ * every candidate is refused.
215
229
  * Returns:
216
- * { ok:true, bin, source, version }
230
+ * { ok:true, bin, source, version, aboveTested?, testedThrough? } — the cliRecord, flagged when the
231
+ * CLI is of a later minor than the tested bound
217
232
  * { ok:false, tried: [{path, source, reason}] } — stable diagnostics; an entry whose probe was
218
- * refused only for being above the band also has
219
- * `version` and `above: true` (acceptProbe)
233
+ * refused only for a newer desktopApi also has
234
+ * `version` and `newerApi: true` (acceptProbe)
220
235
  */
221
236
  export async function discover(io, probe) {
222
237
  const tried = [];
@@ -241,9 +256,9 @@ export async function discover(io, probe) {
241
256
  tried.push({ path, source: src.source, reason: `probe failed: ${String(e.message || e).slice(0, 120)}` });
242
257
  continue;
243
258
  }
244
- const a = acceptProbe(payload);
245
- if (a.ok) return cliRecord(payload, { bin: path, source: src.source });
246
- tried.push({ path, source: src.source, reason: a.reason, version: payload?.version, ...(a.above === true ? { above: true } : {}) });
259
+ const a = acceptProbe(payload, io.testedVersion);
260
+ if (a.ok) return { ...cliRecord(payload, { bin: path, source: src.source }), ...(a.aboveTested === true ? { aboveTested: true, testedThrough: a.testedThrough } : {}) };
261
+ tried.push({ path, source: src.source, reason: a.reason, version: payload?.version, ...(a.newerApi === true ? { newerApi: true } : {}) });
247
262
  }
248
263
  }
249
264
  return { ok: false, tried };
@@ -32,21 +32,21 @@ export function deploymentLabelParts(deployment, terms) {
32
32
  return { machine, path };
33
33
  }
34
34
 
35
- /** `This Mac · ~/acme`, `altair · ~/northwind`. */
35
+ /** `This Mac · ~/acme`, `builder · ~/northwind`. */
36
36
  export function deploymentLabel(deployment, terms) {
37
37
  requireTerms(terms, 'deploymentLabel');
38
38
  const { machine, path } = deploymentLabelParts(deployment, terms);
39
39
  return path ? `${machine} · ${path}` : machine;
40
40
  }
41
41
 
42
- /** The last segment of a path ("/Users/juan/awebai/oats-v2" → "oats-v2"), or the last `n`. */
42
+ /** The last segment of a path ("/Users/alex/work/acme" → "acme"), or the last `n`. */
43
43
  export function pathTail(path, n = 1) {
44
44
  if (typeof path !== 'string' || !path) return '';
45
45
  return path.split('/').filter(Boolean).slice(-n).join('/');
46
46
  }
47
47
 
48
- /** Each deployment's short name on screen (UI spec, #482): its machine ("This Mac", "altair"); when one
49
- * machine holds two or more of the deployments, the machine and its path tail ("This Mac · oats-v2"),
48
+ /** Each deployment's short name on screen (UI spec, #482): its machine ("This Mac", "builder"); when one
49
+ * machine holds two or more of the deployments, the machine and its path tail ("This Mac · acme"),
50
50
  * the last two segments when the tails collide. Never an id. Returns Map<deployment id, label>. */
51
51
  export function machineLabels(deployments, terms) {
52
52
  requireTerms(terms, 'machineLabels');
@@ -1,18 +1,11 @@
1
- /** The instance-name rules of the clients. A typed name follows one before it reaches `oats spawn --name`: the
2
- * soul's role is its suffix. One copy for the clients (the Desktop's spawn dialog today); the kernel keeps its own
3
- * for the suggestion it will make, and test/client-instance-name.test.mjs pins the cases both must agree on.
4
- *
5
- * A soul's role is the last word of its name: `oats-desktop-expert` → `expert`, `code-reviewer` → `reviewer`,
6
- * `cloner` → `cloner`. A package qualifier is dropped first (what follows the last `/` or `--`, as the
7
- * identity marks read a name: renderer/identity-marks.mjs markText), so `acme-pkg--keeper` → `keeper`.
8
- * A typed name gets the role once: `desktop-improvements` → `desktop-improvements-expert`, while
9
- * `desktop-improvements-expert` and `expert` stay as typed; the kernel refuses a typed name that breaks its
10
- * grammar (E_INSTANCE_NAME_INVALID).
1
+ /** The instance-name rules of the clients. A typed name goes to `oats spawn --name` as typed, lowercased: nothing
2
+ * is appended to it (the soul is shown beside the name). What to name an instance, `<descriptive>-<role>`, is
3
+ * oats.core's rule (oats-souls "Name the instance"), never this module's.
11
4
  *
12
5
  * The grammar itself, the kernel's `--name` check (explicitInstanceName: a slug of at most MAX_INSTANCE_NAME
13
6
  * characters), is mirrored here for a client that must judge a name with no kernel call (the
14
- * Desktop's `--instance` launch argument, a spawn's suggested name); the agreement test drives the kernel's own
15
- * check over the same cases.
7
+ * Desktop's `--instance` launch argument, a spawn's suggested name); test/client-instance-name.test.mjs drives
8
+ * the kernel's own check over the same cases.
16
9
  * DOM-free and import-free, with no module state. */
17
10
 
18
11
  /** The kernel's longest instance name (its MAX_INSTANCE_NAME). */
@@ -24,20 +17,3 @@ const INSTANCE_NAME = new RegExp(`^(?=.{1,${INSTANCE_NAME_MAX}}$)[a-z0-9]+(?:-[a
24
17
  export function validInstanceName(name) {
25
18
  return typeof name === 'string' && INSTANCE_NAME.test(name);
26
19
  }
27
-
28
- /** The role of a soul name: its last `-`-separated word after any package qualifier; '' when there is none. */
29
- export function soulRole(soulName) {
30
- if (typeof soulName !== 'string') return '';
31
- const slash = soulName.lastIndexOf('/'), dashes = soulName.lastIndexOf('--');
32
- const bare = soulName.slice(Math.max(slash < 0 ? 0 : slash + 1, dashes < 0 ? 0 : dashes + 2));
33
- return bare.slice(bare.lastIndexOf('-') + 1);
34
- }
35
-
36
- /** `name` with the role of `soulName` as its suffix, unless it already ends in `-<role>` or is the role itself;
37
- * the name as given when the soul has no role, and '' for no name (the kernel numbers it). */
38
- export function nameWithRole(name, soulName) {
39
- if (typeof name !== 'string' || !name) return '';
40
- const role = soulRole(soulName);
41
- if (!role || name === role || name.endsWith(`-${role}`)) return name;
42
- return `${name}-${role}`;
43
- }
@@ -86,6 +86,27 @@ export function verifiedLocalHome(row, deployments, realpath) {
86
86
  return null;
87
87
  }
88
88
 
89
+ /** How a start came by its session, as the kernel's receipt says (`reused`): a new window, a retained pane, or the
90
+ * adopted launch of an earlier start whose record was not written. */
91
+ const START_REUSED = Object.freeze(['new', 'pane', 'adopted']);
92
+
93
+ /** Whether `v` is the receipt of a completed start or restart of `row`, as the kernel answers one
94
+ * (docs/desktop-cli-api.md, `oats session start`: `{instance, agent, home, harness, backend, model, launchConfig,
95
+ * yolo, target, startedAt, restartCount, reused, warnings}`): the row's instance, in the row's home (the kernel
96
+ * answers with its real path: `canonical`, the verified local home), on the one backend there is, tmux, with its
97
+ * target (`{backend, session, window, socket}`, more keys allowed) and the other fields a start always carries.
98
+ * Read where the CLI is newer than this client was tested with, so a format it does not know is not taken for one. */
99
+ function startReceipt(v, row, canonical) {
100
+ const record = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
101
+ const text = (x) => typeof x === 'string' && x.length > 0;
102
+ return record(v) && v.instance === row.instance && text(v.home) && (v.home === row.home || (canonical !== null && v.home === canonical))
103
+ && text(v.agent) && text(v.harness) && v.backend === 'tmux' && text(v.startedAt)
104
+ && record(v.target) && v.target.backend === 'tmux' && text(v.target.session) && text(v.target.window)
105
+ && text(v.target.socket) && v.target.socket.startsWith('/')
106
+ && Number.isSafeInteger(v.restartCount) && v.restartCount >= 0 && START_REUSED.includes(v.reused)
107
+ && Array.isArray(v.warnings) && v.warnings.every((w) => typeof w === 'string');
108
+ }
109
+
89
110
  /** Start or restart one row.
90
111
  * choices { model, launchConfig, harness, yolo }: the launch choices, each one argv value
91
112
  * restart a restart (the kernel's one call, never a stop then a start)
@@ -109,8 +130,8 @@ export async function startInstance(cli, row, choices = {}, { restart = false, d
109
130
  const gate = startGate(cli, row, { restart, choices }, terms);
110
131
  if (gate) return refused(gate.code, gate.sentence, gate.detail ? { detail: gate.detail } : {});
111
132
  const local = !row.server;
112
- if (local && !(verifyHome ? verifyHome(row) : verifiedLocalHome(row, deployments, realpath)))
113
- return refused('E_HOME_UNVERIFIED', 'Instance home is outside the workspace instances layout');
133
+ const canonical = local ? (verifyHome ? verifyHome(row) : verifiedLocalHome(row, deployments, realpath)) : null;
134
+ if (local && !canonical) return refused('E_HOME_UNVERIFIED', 'Instance home is outside the workspace instances layout');
114
135
  let envelope;
115
136
  // A call that could not be made, or failed on its way (an exec that throws, a rejected call), is uncertain like
116
137
  // any answer this cannot read: the CLI may have begun the start. Its words are the rule's; the exception's text
@@ -119,7 +140,14 @@ export async function startInstance(cli, row, choices = {}, { restart = false, d
119
140
  harnessFlag: harnessFlag(cli), yolo: choices.yolo, restart, workspaceDir: local ? dirname(row.agentsRoot) : localCwd, server: row.server },
120
141
  { ...(exec ? { exec } : {}), ...(after ? { after } : {}), ...(wait !== undefined ? { wait } : {}) }); }
121
142
  catch { return { ok: false, outcome: 'uncertain', code: 'E_CLI_FAILED', sentence: CLI_FAILED, detail: null, ran: true }; }
122
- if (envelope?.ok === true) return { ok: true, result: envelope.result };
143
+ if (envelope?.ok === true) {
144
+ // Above the client's tested bound (#1879, cli-locator.mjs aboveTested) a start is reported started only on the
145
+ // receipt it knows (startReceipt): any other answer is an outcome not known, never a start, and nothing more
146
+ // is run. Within the bound the answer is taken as before.
147
+ if (cli?.aboveTested === true && !startReceipt(envelope.result, row, canonical))
148
+ return { ok: false, outcome: 'uncertain', code: 'E_CLI_PROTOCOL', sentence: null, detail: null, ran: true };
149
+ return { ok: true, result: envelope.result };
150
+ }
123
151
  const code = typeof envelope?.error?.code === 'string' ? envelope.error.code : 'E_CLI_PROTOCOL';
124
152
  const detail = displayLine(envelope?.error?.message);
125
153
  if (CLAIM_STARTED_NOTHING_CODES.includes(code)) {
@@ -15,7 +15,7 @@ const short = (value, max = 256) => typeof value === "string" && value.length >
15
15
 
16
16
  const machinesOf = (choice) => Array.isArray(choice?.machines) ? choice.machines.filter((m) => short(m)) : [];
17
17
 
18
- /** The machines a choice's deployments are on, as one line (UI spec, #482): "This Mac · altair", from
18
+ /** The machines a choice's deployments are on, as one line (UI spec, #482): "This Mac · builder", from
19
19
  * the server's `machines`. Never a path or an id: without `machines` (an older server), nothing. */
20
20
  export function workspaceChoicePlace(choice) {
21
21
  return machinesOf(choice).join(" · ");
@@ -145,7 +145,7 @@ export function deploymentReason(d, terms) {
145
145
  return deploymentReasonParts(d, terms)?.detail ?? null;
146
146
  }
147
147
 
148
- /** The last segment of a canonical key: github.com/GreaterSkies/tsm → tsm. */
148
+ /** The last segment of a canonical key: github.com/example/app → app. */
149
149
  const keyTail = key => String(key).split('/').filter(Boolean).pop() || String(key);
150
150
 
151
151
  /** Build the views from the served deployments, in their served order (locals first, as given).
@@ -203,7 +203,7 @@ enter the record.
203
203
  7fe2a1b4-9c3d-4e21-b0aa-1f2e3d4c5b6a
204
204
 
205
205
  # never capture anything from this project's transcripts
206
- **/-Users-juanre-private-project/**
206
+ **/-Users-alex-private-project/**
207
207
 
208
208
  # never capture one aw account's comm log
209
209
  acme-secret
@@ -283,9 +283,12 @@ guarantees rest on that token:
283
283
  provably stale and is reclaimed at once, without waiting out any threshold.
284
284
  A holder is gone when its pid is gone, when its pid runs with another start
285
285
  than the recorded one (the pid went to another process), or when the lock
286
- was taken in another boot. A run of a container counts as a boot, so a lock
287
- left on a volume by a container that was stopped is reclaimed by the next
288
- one, whatever its hostname and whichever process holds the pid there. The
286
+ was taken in another kernel boot. Containers and PID sandboxes use the same
287
+ Linux kernel UUID; a container restart reclaims a lock when its recorded
288
+ pid is gone or has another start time. Old qualified Linux UUIDs compare as
289
+ their base UUID, so an upgrade does not reclaim a visible live holder.
290
+ Holder liveness assumes the reader can see the recorded pid in its PID
291
+ namespace; a shared boot string does not translate pids across namespaces. The
289
292
  kernel judges its own claims by the same rule, with the same code
290
293
  (`lib/process-identity.mjs`).
291
294
 
@@ -353,10 +356,9 @@ its registered worker too:
353
356
 
354
357
  - An owner, a worker or a reclaimer is dead when its pid is gone, when its
355
358
  pid runs with another start than the recorded one (the pid went to
356
- another process), or when its record was taken in another boot. A run of
357
- a container counts as a boot: a lock left on a volume by a container that
358
- was stopped is reclaimed by the first pass of the next one, whatever its
359
- hostname and whichever process holds the pid there. The host a record
359
+ another process), or when its record was taken in another kernel boot.
360
+ Container restarts use pid and process start on that same kernel; old
361
+ qualified UUIDs are compared as their base UUID. The host a record
360
362
  names does not enter this judgement. One whose start cannot be read is
361
363
  unknowable, and never dead.
362
364
  - A record that names neither boot nor start, as an earlier version writes