@awebai/oats 0.69.17 → 0.69.19

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 (61) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +14 -13
  3. package/docs/capabilities.md +8 -1
  4. package/docs/container.md +345 -18
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
  6. package/docs/design/2026-09-27-team-model-v2.md +2 -2
  7. package/docs/design/2026-09-28-automations-trust.md +1 -1
  8. package/docs/desktop-cli-api.md +100 -53
  9. package/docs/desktop.md +53 -24
  10. package/docs/execution-targets.md +66 -48
  11. package/docs/implementation.md +8 -7
  12. package/docs/integrations.md +2 -2
  13. package/docs/knowledge.md +5 -5
  14. package/docs/official-catalog.md +7 -7
  15. package/docs/packages.md +13 -13
  16. package/docs/release-lane.md +30 -23
  17. package/docs/release-notes/v0.69.18.md +358 -0
  18. package/docs/release-notes/v0.69.19.md +172 -0
  19. package/docs/servers.md +5 -3
  20. package/docs/souls-and-instances.md +51 -27
  21. package/docs/trust-model.md +119 -0
  22. package/docs/tui.md +8 -8
  23. package/docs/upgrading.md +45 -19
  24. package/docs/workspaces.md +3 -3
  25. package/injects/work-directory.md +27 -2
  26. package/injects/work-workspace.md +32 -6
  27. package/lib/command-flags.mjs +1 -1
  28. package/lib/core.mjs +26 -11
  29. package/lib/errors.mjs +1 -1
  30. package/lib/home-owner.mjs +25 -0
  31. package/lib/host-run-admission.mjs +21 -0
  32. package/lib/host-run-child.mjs +31 -0
  33. package/lib/host-run-work.mjs +150 -0
  34. package/lib/host-run.mjs +43 -29
  35. package/lib/instance-naming.mjs +26 -44
  36. package/lib/packages.mjs +0 -43
  37. package/lib/pi-bridge.mjs +18 -6
  38. package/lib/schedule.mjs +5 -3
  39. package/lib/servers.mjs +4 -3
  40. package/lib/session-end.mjs +9 -0
  41. package/lib/session-resume-contract.mjs +1 -1
  42. package/lib/session-resume.mjs +144 -51
  43. package/lib/session-seen.mjs +16 -11
  44. package/lib/triggers.mjs +3 -1
  45. package/lib/worktree.mjs +5 -2
  46. package/package-catalog.json +3 -3
  47. package/package.json +4 -2
  48. package/packages/client/above-tested-notice.mjs +30 -0
  49. package/packages/client/above-tested.mjs +225 -0
  50. package/packages/client/cli-locator.mjs +67 -52
  51. package/packages/client/deployment-label.mjs +4 -4
  52. package/packages/client/instance-name.mjs +5 -29
  53. package/packages/client/instance-presentation.mjs +2 -2
  54. package/packages/client/instance-tree.mjs +18 -7
  55. package/packages/client/session-start.mjs +31 -3
  56. package/packages/client/workspace-choices.mjs +1 -1
  57. package/packages/client/workspace-views.mjs +1 -1
  58. package/packages/record/README.md +10 -8
  59. package/packages/record/lib/process-identity.mjs +14 -36
  60. package/packages/tui/lib/read.mjs +19 -3
  61. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -6,9 +6,9 @@
6
6
  * firstNotRunningAt, firstNotRunningBoot, judgedBy } } }
7
7
  * (times ISO; boots bootId's, null without one; `judgedBy` `{ at, boot, outcome }` or null).
8
8
  *
9
- * - Observations have one producer, a local `listInstances` (`oats status`, the sweep's own read
10
- * and every other local listing): recordSeen. A status routed to another machine reads nothing
11
- * here; a start writes nothing.
9
+ * - Observations come from local `listInstances` calls (`oats status`, the sweep's own read
10
+ * and every other local listing) and from the sweep recording the homes it started: recordSeen.
11
+ * A status routed to another machine reads nothing here; `session start` writes nothing.
12
12
  * - `judgedBy` has one writer, a sweep that is not a plan (judgeLosses), once its rows are known:
13
13
  * a status read never uses up a loss.
14
14
  * - Never in the way of what reads it: an unreadable file is an empty record (which resumes
@@ -21,9 +21,9 @@ import { createHash, randomBytes } from "node:crypto";
21
21
  import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
22
22
  import { homedir } from "node:os";
23
23
  import { dirname, join, resolve } from "node:path";
24
- import { thisBoot } from "../packages/record/lib/process-identity.mjs";
24
+ import { sameBoot, thisBoot } from "../packages/record/lib/process-identity.mjs";
25
25
 
26
- export { bootId, identityHolderState, namesIdentity, takenInAnotherBoot, thisBoot, validPid } from "../packages/record/lib/process-identity.mjs";
26
+ export { bootId, identityHolderState, namesIdentity, sameBoot, takenInAnotherBoot, thisBoot, validPid } from "../packages/record/lib/process-identity.mjs";
27
27
 
28
28
  /** A loss first seen this long ago or more is not resumed. */
29
29
  export const FIRST_SEEN_MAX_MS = 24 * 60 * 60_000;
@@ -88,7 +88,7 @@ export function nextSeen(homes, rows, { now, boot }) {
88
88
  let next = prior;
89
89
  if (row.running === true) {
90
90
  if (!prior || prior.startId !== startId) next = { startId, lastSeenRunningAt: at, lastSeenRunningBoot: boot, firstNotRunningAt: null, firstNotRunningBoot: null, judgedBy: null };
91
- else if (!(now - Date.parse(prior.lastSeenRunningAt) < RUNNING_REFRESH_MS) || prior.lastSeenRunningBoot !== boot) next = { ...prior, lastSeenRunningAt: at, lastSeenRunningBoot: boot };
91
+ else if (!(now - Date.parse(prior.lastSeenRunningAt) < RUNNING_REFRESH_MS) || (prior.lastSeenRunningBoot !== boot && !sameBoot(prior.lastSeenRunningBoot, boot))) next = { ...prior, lastSeenRunningAt: at, lastSeenRunningBoot: boot };
92
92
  } else if (row.running === false && row.launched === true && prior && prior.startId === startId && !prior.firstNotRunningAt) {
93
93
  next = { ...prior, firstNotRunningAt: at, firstNotRunningBoot: boot };
94
94
  }
@@ -135,10 +135,11 @@ export function judgeLosses(root, judged, { now = Date.now(), boot = thisBoot()
135
135
  * 2. no earlier sweep judged this loss (`judgedBy`);
136
136
  * 3. the loss was first seen less than FIRST_SEEN_MAX_MS ago;
137
137
  * 4. within one boot (both looks in the same boot, or either without a boot id), the last running
138
- * look is less than WITHIN_BOOT_GAP_MS before the first not-running look. Across a reboot it
139
- * does not apply.
138
+ * look is less than WITHIN_BOOT_GAP_MS before the loss. A validated current-start host stop
139
+ * (`hostStoppedAt`) establishes that moment before downtime; otherwise the first not-running
140
+ * look does. Across a kernel reboot this gap clause does not apply.
140
141
  * The rule reads the boots the record holds, not this one's. Pure. */
141
- export function resumeEligible(record, row, { now }) {
142
+ export function resumeEligible(record, row, { now, hostStoppedAt = null }) {
142
143
  const no = (why) => ({ eligible: false, why });
143
144
  const lastRunning = Date.parse(record?.lastSeenRunningAt);
144
145
  if (!record || record.startId !== startIdOf(row) || !Number.isFinite(lastRunning)) return no("OATS never saw it running for its current start");
@@ -146,7 +147,11 @@ export function resumeEligible(record, row, { now }) {
146
147
  const firstLost = Date.parse(record.firstNotRunningAt);
147
148
  if (!Number.isFinite(firstLost)) return no("OATS has not seen it stop since it last saw it running");
148
149
  if (now - firstLost >= FIRST_SEEN_MAX_MS) return no(`its loss was first seen ${record.firstNotRunningAt}, 24 hours ago or more`);
149
- const oneBoot = !record.lastSeenRunningBoot || !record.firstNotRunningBoot || record.lastSeenRunningBoot === record.firstNotRunningBoot;
150
- if (oneBoot && firstLost - lastRunning >= WITHIN_BOOT_GAP_MS) return no(`in the boot it was lost in, it was last seen running ${record.lastSeenRunningAt}, 24 hours or more before its loss was seen`);
150
+ const oneBoot = !record.lastSeenRunningBoot || !record.firstNotRunningBoot || sameBoot(record.lastSeenRunningBoot, record.firstNotRunningBoot);
151
+ // A validated host stop establishes the loss before downtime. Keep the separate age of the
152
+ // first observation above, and every other guard. A listing during stop grace can still see
153
+ // the harness running after its receipt; that establishes no gap, not an invalid receipt.
154
+ const gapEnd = Number.isFinite(hostStoppedAt) && hostStoppedAt <= firstLost && hostStoppedAt <= now ? Math.max(lastRunning, hostStoppedAt) : firstLost;
155
+ if (oneBoot && gapEnd - lastRunning >= WITHIN_BOOT_GAP_MS) return no(`in the boot it was lost in, it was last seen running ${record.lastSeenRunningAt}, 24 hours or more before its loss was seen`);
151
156
  return { eligible: true };
152
157
  }
package/lib/triggers.mjs CHANGED
@@ -34,6 +34,7 @@
34
34
  * test/trigger-pipeline-fixture.test.mjs pins the built-in's state and outputs byte for byte.
35
35
  *
36
36
  * State: <scope>/.agents/schedules/triggers.json (gitignored with the schedule state). */
37
+ import { hostRunAdmissionOpen, hostRunChildArgs } from "./host-run-admission.mjs";
37
38
  import { spawnSync } from "node:child_process";
38
39
  import { createHash } from "node:crypto";
39
40
  import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
@@ -792,7 +793,7 @@ function retainFired(ts) {
792
793
  /** Run a child `oats` in the deployment: COMMAND_TIMEOUT_MS and SIGTERM unless `timeoutMs` and
793
794
  * `killSignal` say otherwise; `env` adds to the child's environment. */
794
795
  function runOats(ws, argv, io, { timeoutMs = io?.commandTimeoutMs || COMMAND_TIMEOUT_MS, killSignal = "SIGTERM", env = {} } = {}) {
795
- const r = spawnSync(process.execPath, [io?.oatsBin || OATS_BIN, ...argv], { cwd: ws, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs, killSignal, maxBuffer: 16 * 1024 * 1024, env: { ...childEnv(), ...env } });
796
+ const r = spawnSync(process.execPath, hostRunChildArgs(io?.oatsBin || OATS_BIN, argv), { cwd: ws, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs, killSignal, maxBuffer: 16 * 1024 * 1024, env: { ...childEnv(), ...env } });
796
797
  const timedOut = r.error?.code === "ETIMEDOUT" || (r.status === null && r.signal === killSignal);
797
798
  return { envelope: parseEnvelopeText(r.stdout), timedOut, status: r.status, stderr: String(r.stderr || "") };
798
799
  }
@@ -901,6 +902,7 @@ function firePending(ws, def, work, queue, { now, io, dryRun, host, rec }) {
901
902
  const live = liveTriggerInstances(ws, def.qid ?? def.id);
902
903
  let pv = null;
903
904
  for (const ev of queue) {
905
+ if (!dryRun && !hostRunAdmissionOpen()) break;
904
906
  const held = heldBy(def, ev, live) ?? (host.cap && host.live >= host.cap ? `host triggersMaxConcurrent ${host.cap} reached (${host.live} live)` : null);
905
907
  if (held) { rec("held", { key: ev.key, reason: held }); continue; }
906
908
  pv ??= previewSoul(ws, def, io);
package/lib/worktree.mjs CHANGED
@@ -506,6 +506,9 @@ export async function worktreeAdd(homeArg, o = {}) {
506
506
  const hooks = worktreeHooksOf(meta.capabilityRuntime);
507
507
  const want = { clone, branch, base };
508
508
  const unknownAdder = (found, reason) => unknownAdderRefusal({ purpose, tree, recPath, rec: found, reason });
509
+ // E_BRANCH_EXISTS's remedy and details, one construction for the precheck and the race path (#1865).
510
+ const remedy = `${meta.instance ?? basename(home)}/${branch}`;
511
+ const branchExists = (why) => ({ message: `${why}; a tree never reuses or resets a branch — name another, e.g. ${remedy}`, details: { branch, clone, remedy } });
509
512
  // What the record says, read under the claim when this add acts on it (the preview only reads).
510
513
  const decide = () => {
511
514
  const found = readRecord(recPath);
@@ -532,7 +535,7 @@ export async function worktreeAdd(homeArg, o = {}) {
532
535
  ? `${tree} exists and is ${st.isSymbolicLink() ? "a symbolic link" : "not a directory"}; it is never followed or replaced — use another --purpose`
533
536
  : `${tree} exists and no oats worktree add made it (no record); use another --purpose, or remove that tree yourself (git worktree remove ${tree})`), { details: { purpose, path: tree } });
534
537
  const exists = git(["-C", clone, "rev-parse", "--verify", "--quiet", "--end-of-options", `refs/heads/${branch}`]);
535
- if (exists.ok) throw Object.assign(oatsError("E_BRANCH_EXISTS", `branch ${branch} already exists in ${clone}; a tree never reuses or resets a branch — name another, e.g. ${meta.instance ?? basename(home)}/${branch}`), { details: { branch, clone, remedy: `${meta.instance ?? basename(home)}/${branch}` } });
538
+ if (exists.ok) { const r = branchExists(`branch ${branch} already exists in ${clone}`); throw Object.assign(oatsError("E_BRANCH_EXISTS", r.message), { details: r.details }); }
536
539
  };
537
540
 
538
541
  if (o.preview) {
@@ -594,7 +597,7 @@ export async function worktreeAdd(homeArg, o = {}) {
594
597
  if (!sw.ok) {
595
598
  // Another add created the branch first (the precheck passed for both): that is E_BRANCH_EXISTS; any other failure is git's.
596
599
  const taken = git(["-C", clone, "rev-parse", "--verify", "--quiet", "--end-of-options", `refs/heads/${branch}`]).ok;
597
- if (taken) throw await fail("E_BRANCH_EXISTS", `git switch -c ${branch} failed: ${firstLine(sw.err)}`, { branch });
600
+ if (taken) { const r = branchExists(`git switch -c ${branch} failed: ${firstLine(sw.err)}`); throw await fail("E_BRANCH_EXISTS", r.message, r.details); }
598
601
  throw await fail("E_GIT_FAILED", `git switch failed in ${tree}: ${firstLine(sw.err) || "unknown error"}`, { branch });
599
602
  }
600
603
  rec = { ...rec, branchCreated: true };
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v6.0.2",
6
+ "ref": "v6.0.3",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.39.0",
11
+ "ref": "v1.42.1",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.24.1",
51
+ "ref": "oats-framework/v1.25.2",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.17",
3
+ "version": "0.69.19",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -37,6 +37,8 @@
37
37
  "skills/",
38
38
  "injects/",
39
39
  "docs/",
40
+ "package.json",
41
+ "LICENSE",
40
42
  "README.md",
41
43
  "package-catalog.json",
42
44
  "packages/record/bin/",
@@ -52,7 +54,6 @@
52
54
  "packages/tui/package.json"
53
55
  ],
54
56
  "dependencies": {
55
- "@awebai/pi": "^0.2.1",
56
57
  "croner": "10.0.1",
57
58
  "yaml": "2.9.1"
58
59
  },
@@ -60,6 +61,7 @@
60
61
  "oats": "./bin/oats.mjs"
61
62
  },
62
63
  "devDependencies": {
64
+ "@earendil-works/pi-coding-agent": "0.80.3",
63
65
  "ajv": "8.17.1"
64
66
  }
65
67
  }
@@ -0,0 +1,30 @@
1
+ /* The one sentence a client says when its oats CLI is above its tested bound (oats-project/oats#1879,
2
+ option 3): why, what is held back, and which Desktop to install. Every place that shows the notice or
3
+ refuses a held-back operation builds its words here, so they cannot drift apart.
4
+
5
+ The kernel cannot import this module (lib/ never imports packages/): `oats update` writes the same core
6
+ sentence itself (lib/pi-bridge.mjs `desktopFirstLine`), and test/above-tested-wording.test.mjs holds
7
+ the two equal for the same version.
8
+
9
+ Pure data and strings; no node: imports, so the renderer shares it with the server. */
10
+
11
+ /** The held-back core, verbatim as decided on #1879: the Desktop to install is the installed CLI's own
12
+ * version, since Desktop and kernel are released together from one tag. */
13
+ export function heldBackSentence(cliVersion) {
14
+ return `Stop, Remove, schedules, triggers and every other change except Spawn, Start, Restart, colour and background are off until you install OATS Desktop ${cliVersion}.`;
15
+ }
16
+
17
+ /** The why, before the core: the tested bound ("X.Y") and the installed CLI's version. */
18
+ export function testedWhySentence(testedThrough, cliVersion) {
19
+ return `This Desktop was tested with oats CLIs up to ${testedThrough}; the installed CLI is ${cliVersion}.`;
20
+ }
21
+
22
+ /** The notice: one line, the why then the core. */
23
+ export function aboveTestedNotice({ cliVersion, testedThrough }) {
24
+ return `${testedWhySentence(testedThrough, cliVersion)} ${heldBackSentence(cliVersion)}`;
25
+ }
26
+
27
+ /** The GitHub Release whose assets are the Desktop of that version (docs/desktop.md, "Install"). */
28
+ export function desktopReleaseUrl(version) {
29
+ return `https://github.com/oats-project/oats/releases/tag/v${version}`;
30
+ }
@@ -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 };