@awebai/oats 0.69.16 → 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 (53) 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.17.md +49 -0
  16. package/docs/release-notes/v0.69.18.md +358 -0
  17. package/docs/servers.md +3 -1
  18. package/docs/souls-and-instances.md +18 -16
  19. package/docs/trust-model.md +119 -0
  20. package/docs/upgrading.md +46 -21
  21. package/docs/workspaces.md +3 -3
  22. package/lib/command-flags.mjs +1 -1
  23. package/lib/core.mjs +24 -9
  24. package/lib/errors.mjs +1 -1
  25. package/lib/home-owner.mjs +25 -0
  26. package/lib/host-run-admission.mjs +21 -0
  27. package/lib/host-run-child.mjs +31 -0
  28. package/lib/host-run-work.mjs +150 -0
  29. package/lib/host-run.mjs +20 -11
  30. package/lib/instance-naming.mjs +26 -44
  31. package/lib/packages.mjs +0 -43
  32. package/lib/pi-bridge.mjs +18 -6
  33. package/lib/schedule.mjs +5 -3
  34. package/lib/servers.mjs +4 -3
  35. package/lib/session-end.mjs +9 -0
  36. package/lib/session-resume.mjs +19 -9
  37. package/lib/session-seen.mjs +13 -8
  38. package/lib/triggers.mjs +3 -1
  39. package/lib/worktree.mjs +5 -2
  40. package/package-catalog.json +3 -3
  41. package/package.json +2 -2
  42. package/packages/client/above-tested-notice.mjs +30 -0
  43. package/packages/client/above-tested.mjs +225 -0
  44. package/packages/client/cli-locator.mjs +67 -52
  45. package/packages/client/deployment-label.mjs +4 -4
  46. package/packages/client/instance-name.mjs +5 -29
  47. package/packages/client/session-start.mjs +31 -3
  48. package/packages/client/workspace-choices.mjs +1 -1
  49. package/packages/client/workspace-views.mjs +1 -1
  50. package/packages/record/README.md +10 -8
  51. package/packages/record/lib/process-identity.mjs +14 -36
  52. package/packages/tui/lib/read.mjs +19 -3
  53. package/skills/oats-getting-started/SKILL.md +33 -4
@@ -218,23 +218,6 @@ export function processLiveness(record) {
218
218
 
219
219
  // ---------- the boot a record was taken in ----------
220
220
 
221
- /** What says this process runs in a container: a file each runtime puts in its containers, or the
222
- * variable Kubernetes sets in every pod. Docker writes `/.dockerenv`, Podman `/run/.containerenv`. */
223
- const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
224
- const inContainer = (exists, env) => CONTAINER_FILES.some((file) => exists(file)) || Boolean(env.KUBERNETES_SERVICE_HOST);
225
-
226
- /** When PID 1 started, as this process sees PID 1: field 22 of `/proc/1/stat`, in clock ticks after
227
- * the kernel's boot, as the digits the kernel printed; null when the file cannot be read or does
228
- * not hold it. The fields are counted after the last ")": the name (field 2) may hold spaces and
229
- * parentheses. */
230
- function initStart(read) {
231
- try {
232
- const stat = read("/proc/1/stat"), named = stat.lastIndexOf(")");
233
- const start = named < 0 ? undefined : stat.slice(named + 1).trim().split(/\s+/)[19];
234
- return typeof start === "string" && /^\d+$/.test(start) ? start : null;
235
- } catch { return null; }
236
- }
237
-
238
221
  /** macOS's boot time, from the system's sysctl (systemTool), never one the caller's PATH names: a
239
222
  * PATH without /usr/sbin, or with another sysctl first, must not change or lose the boot id. */
240
223
  function systemSysctl() {
@@ -246,24 +229,16 @@ function systemSysctl() {
246
229
  * process the kernel may have recorded: the sessions, their terminal server, a sweep.
247
230
  * - macOS: the boot time (`sysctl -n kern.boottime`, its `sec`/`usec`).
248
231
  * - Linux: the kernel's boot id (`/proc/sys/kernel/random/boot_id`).
249
- * - Linux in a container (inContainer): `<boot id>:<PID 1's start>`. A container shares its
250
- * host's kernel and so its boot id, which outlives a stop and start of the container; its PID 1
251
- * does not. PID 1 starts once per run of the container and ends every process of the run when
252
- * it ends, so its start is the same for every process of one run and another in the next; the
253
- * boot id keeps a start apart from the same number of ticks after another kernel boot. When
254
- * PID 1's start cannot be read there, the boot id alone: the sweep then counts a home's starts
255
- * across the runs and applies the in-boot clause across them, so it starts less, never more.
256
- * PID 1's start is read only in a container. A process in a PID namespace of its own on a host (a
257
- * command a harness runs in a sandbox) reads that namespace's PID 1, which is not the machine's,
258
- * and it is on the host's boot all the same.
232
+ * A container and a sandbox share the kernel's boot. Their environment, marker files and PID 1
233
+ * cannot change this identity: a holder's pid and processStart distinguish a dead or reused pid
234
+ * on that kernel. Old records that qualified the UUID are read by sameBoot below.
259
235
  * Each is read from the kernel without privileges and written nowhere. */
260
- export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), exists = existsSync, env = process.env, sysctl = systemSysctl } = {}) {
236
+ export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), sysctl = systemSysctl } = {}) {
261
237
  try {
262
238
  if (platform === "linux") {
263
239
  const id = read("/proc/sys/kernel/random/boot_id").trim();
264
240
  if (!id) return null;
265
- const start = inContainer(exists, env) ? initStart(read) : null;
266
- return start === null ? id : `${id}:${start}`;
241
+ return id;
267
242
  }
268
243
  if (platform === "darwin") { const m = /sec = (\d+), usec = (\d+)/.exec(sysctl()); return m ? `${m[1]}.${m[2]}` : null; }
269
244
  } catch { /* unknown */ }
@@ -272,12 +247,15 @@ export function bootId({ platform = process.platform, read = (p) => readFileSync
272
247
  let processBoot;
273
248
  /** bootId, read once per process: a process never outlives its boot. */
274
249
  export const thisBoot = () => (processBoot === undefined ? (processBoot = bootId()) : processBoot);
275
- /** Whether the lock record `holder` (the sweep's lock, a cache write lock: lib/remote.mjs) was taken
276
- * in another boot than `boot`: its holder is gone then, whatever its pid reads as. A boot ends
277
- * every process, and a pid and a start counted from the boot can both come again in the next (in a
278
- * container, a boot is one run: bootId). Without a boot id on either side the process alone is
279
- * judged. */
280
- export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && holder.bootId !== boot;
250
+ // Only the historical Linux UUID:PID1-start format is normalized. Opaque boot identities (macOS
251
+ // included) keep their exact comparison. This does not rewrite records held by another process.
252
+ const linuxKernelBoot = (id) => typeof id === "string" ? id.replace(/^([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}):\d+$/i, "$1") : id;
253
+ /** True only for two known identities of the same kernel boot, including old qualified Linux IDs.
254
+ * Qualification never proves a live holder gone during an upgrade; pid/start still decide. */
255
+ export const sameBoot = (a, b) => typeof a === "string" && a !== "" && typeof b === "string" && b !== "" && linuxKernelBoot(a) === linuxKernelBoot(b);
256
+ /** Whether the two known identities establish another kernel boot. Without either boot the
257
+ * reader must judge the process itself; a missing/unreadable start remains unknown, never gone. */
258
+ export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && !sameBoot(holder.bootId, boot);
281
259
 
282
260
  /** Whether a lock record names the boot it was taken in or its holder's start (`bootId`,
283
261
  * `processStart`), whatever their values. */
@@ -106,7 +106,8 @@ export function admitDeployment(path, io = {}) {
106
106
 
107
107
  /** Run the kernel once with `version --json` and make its record:
108
108
  * -> Promise<{ ok: true, cli } | { ok: false, reason }>, never rejected.
109
- * The answer is read with the shared parseProbeStdout and judged by the shared acceptProbe; an
109
+ * The answer is read with the shared parseProbeStdout and judged by the shared acceptProbe, against
110
+ * `testedVersion` (KERNEL_VERSION: the kernel it ships with); an
110
111
  * accepted one becomes `cliRecord(payload, { bin, source: "tui" })`, the record every shared gate
111
112
  * reads. `reason` is acceptProbe's own when it refused, and one of the TUI's four when there was
112
113
  * no answer to judge. A nonzero exit or a timeout is a refusal even when stdout looks valid: a
@@ -115,7 +116,7 @@ export function admitDeployment(path, io = {}) {
115
116
  * the caller shows it as it shows any kernel text.
116
117
  * NOT detached, unlike every later child: it runs before the terminal is taken, and a Ctrl+C then
117
118
  * must end it with the TUI. `timeoutMs` is for tests. */
118
- export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = nodeExecFile, timeoutMs = PROBE_TIMEOUT_MS } = {}) {
119
+ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = nodeExecFile, timeoutMs = PROBE_TIMEOUT_MS, testedVersion = KERNEL_VERSION } = {}) {
119
120
  return new Promise((done) => {
120
121
  const refuse = (reason) => done({ ok: false, reason });
121
122
  try {
@@ -123,7 +124,10 @@ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = no
123
124
  if (error) return refuse(typeof error.syscall === "string" && error.syscall.startsWith("spawn") ? "it did not start" : error.killed === true ? `it did not answer within ${timeoutMs / 1000} seconds` : "it failed");
124
125
  const payload = parseProbeStdout(stdout);
125
126
  if (!payload) return refuse("it answered something that is not a version record");
126
- const verdict = acceptProbe(payload);
127
+ const verdict = acceptProbe(payload, testedVersion);
128
+ // A kernel newer than the TUI's own is not the kernel it shipped with: the TUI holds nothing back
129
+ // (it has no allowlist), so it refuses it, as before the Desktop's soft ceiling (#1879).
130
+ if (verdict.ok && verdict.aboveTested) return refuse(`version ${payload.version} is newer than this TUI's kernel ${testedVersion}`);
127
131
  return verdict.ok ? done({ ok: true, cli: cliRecord(payload, { bin, source: "tui" }) }) : refuse(verdict.reason);
128
132
  });
129
133
  } catch { refuse("it did not start"); }
@@ -161,6 +165,18 @@ export const CHANGE_FILES = Object.freeze({
161
165
  },
162
166
  });
163
167
 
168
+ /** The version of the kernel's own package (its package.json, beside bin/, as KERNEL_BIN): the TUI's tested
169
+ * version, which the shared acceptProbe requires (cli-locator.mjs). The kernel the TUI runs is this one, so it is
170
+ * never above it. Read once, by the bounded read a change's output is read with (no other read of node:fs); null
171
+ * when the manifest cannot be read or is over 1 MiB: the probe then refuses, as acceptProbe does without one. */
172
+ export const KERNEL_VERSION = (() => {
173
+ try {
174
+ const { text, over } = CHANGE_FILES.read(fileURLToPath(new URL("../../../package.json", import.meta.url)), 1024 * 1024);
175
+ const version = over ? null : JSON.parse(text).version;
176
+ return typeof version === "string" ? version : null;
177
+ } catch { return null; }
178
+ })();
179
+
164
180
  /** A child that did not end well, as execFile reports one: the facts on an Error, and no text of the child's. */
165
181
  const failure = (facts) => Object.assign(new Error("the child did not end with an answer"), facts);
166
182
  /** A child the reader ended itself: its time limit, or the reader giving it up. As execFile's timeout. */
@@ -533,7 +533,7 @@ installed CLI's catalog:
533
533
  node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
534
534
  ```
535
535
 
536
- It prints the two refs, for example `oats-framework/v1.24.0 v1.39.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.25.0 v1.41.0`. If the
537
537
  framework's version (after the `/`) is below `1.19.0`, or with aweb
538
538
  `oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
539
539
  skill: stop, and tell the person to wait for the next OATS
@@ -548,7 +548,9 @@ its skills, so it puts none on the computer; each agent gets its own;
548
548
  from 0.5.0 it bundles none, and the setting is harmless, so set it
549
549
  whatever the version). Never install `@awebai/claude-skills` in that pi
550
550
  folder: its skills would load in every agent there, and each agent gets
551
- its own skills from OATS. Codex nothing (the setup expert sets up its wake). Claude's aweb channel
551
+ its own skills from OATS. Codex has no channel of its own: it is woken by
552
+ the host wake broker, which the person starts in step 9, item 6, before the
553
+ setup expert is spawned. Claude's aweb channel
552
554
  plugin still carries one skill of its own, until aweb ships it without
553
555
  (a known gap). The pi entry, which matches `npm:@awebai/pi` alone or with
554
556
  `@` and a version, never another `@awebai/pi-…` package, and prints it so
@@ -768,8 +770,8 @@ name: acme
768
770
  members:
769
771
  - git:github.com/acme/acme-oats # the host; the setup expert adds the others
770
772
  packages:
771
- oats.framework: v1.24.0 # the installed CLI's catalog versions (below)
772
- oats.aweb: v1.39.0 # messaging: agent identities, mail and chat
773
+ oats.framework: v1.25.0 # the installed CLI's catalog versions (below)
774
+ oats.aweb: v1.41.0 # messaging: agent identities, mail and chat
773
775
  oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
774
776
  defaults:
775
777
  capabilities:
@@ -1046,6 +1048,33 @@ readiness still reports a problem.
1046
1048
  their own agent whether that name is in the group (its agent reads
1047
1049
  `oats aweb roster --label L`); the fix (a new invite and a name for this
1048
1050
  machine) is the workspace owner's. Never take the other machine's name.
1051
+ 6. **Codex, or `delivery: session`: the wake broker runs before the spawn.**
1052
+ Skip this item when the setup expert's harness is Claude or pi and the
1053
+ effective `oats.aweb` settings (the soul's or this host's) don't set
1054
+ `delivery: session`: its own channel wakes it (step 4). Any other setup
1055
+ expert is woken only by the host wake broker, and oats.aweb refuses to
1056
+ spawn or start it while no broker runs (`wake-daemon-not-running`). The
1057
+ broker is the person's own user service, so it is theirs to start. Open
1058
+ their own terminal ("How to work") running this, with `D` filled in:
1059
+
1060
+ ```text
1061
+ cd "D" && oats aweb wake install
1062
+ ```
1063
+
1064
+ In a container, or on a machine with neither launchd nor systemd (the
1065
+ command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
1066
+ the line is `aw wake run`, kept running as a supervised process.
1067
+
1068
+ Then check it yourself:
1069
+
1070
+ ```bash
1071
+ cd "D" && oats aweb wake status --json
1072
+ ```
1073
+
1074
+ Go on to step 10 only when it reports `"daemon": { "running": true }`.
1075
+ Otherwise stop, spawn nothing, and tell the person what the status
1076
+ shows.
1077
+
1049
1078
  The setup expert does the rest of this machine's messaging
1050
1079
  (`/oats-host-delivery`).
1051
1080