@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
@@ -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
- }
@@ -10,8 +10,8 @@ const RUNTIME_ORDER = Object.freeze({ running: 0, unknown: 1, stopped: 2 });
10
10
  /** The panel's runtime order, a comparator for `sort`: running, then unknown (`running` null or anything not
11
11
  * a boolean: it may be running, so it stands above the rows nobody needs to watch), then stopped; by name
12
12
  * within each. Each row's place depends on that row alone, so it is a total order whatever `running` holds.
13
- * Read by `panelInstances` (deployment-panel.mjs). The sidebar's roster orders by name (instance-tree.mjs
14
- * `rosterOrder`, #1262). */
13
+ * Read by `panelInstances` (deployment-panel.mjs). The sidebar's roster orders by spawn time, newest first
14
+ * (instance-tree.mjs `rosterOrder`). */
15
15
  export function byRuntimeState(a, b) {
16
16
  return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
17
17
  }
@@ -66,11 +66,23 @@ export function resolveLinkId(fromInstance, name, byName) {
66
66
  return sameRoot.length === 1 ? instanceId(sameRoot[0]) : null;
67
67
  }
68
68
 
69
- /** The roster's order, a comparator for `sort`: by instance name, ties broken by `instanceId`, so it is total and
70
- * deterministic. It ranks roots, siblings under one parent, and so clusters (by their first root). A start or a
71
- * stop moves no row; only adding or removing one does (Pepe's decision on #1262, comment 6196531154, which
72
- * replaces #1083's running-first order for the roster). The one place the roster's order is decided. */
69
+ /** When a row was spawned, in ms: its `createdAt` (the kernel's ISO time from instance.json), or null when it has
70
+ * none or the reader can't parse it. */
71
+ function spawnTime(instance) {
72
+ const time = typeof instance.createdAt === "string" ? Date.parse(instance.createdAt) : NaN;
73
+ return Number.isFinite(time) ? time : null;
74
+ }
75
+
76
+ /** The roster's order, a comparator for `sort`: by spawn time, newest first (Pepe, 2026-11-13: "by spawn time not
77
+ * alphabetically, i.e. new to old"); a row with no readable spawn time after every row with one; then by instance
78
+ * name, ties broken by `instanceId`, so it is total and deterministic. It ranks roots, siblings under one parent,
79
+ * and so clusters (by their first root: a bundle sits where its newest root sits, so a new child never moves it).
80
+ * A spawn time never changes, so a start or a stop moves no row; only adding or removing one does (#1262's
81
+ * recognition rule, whose name order this replaces; #1083's running-first order stays out of the roster). The one
82
+ * place the roster's order is decided. */
73
83
  function rosterOrder(a, b) {
84
+ const ta = spawnTime(a), tb = spawnTime(b);
85
+ if (ta !== tb) return ta === null ? 1 : tb === null ? -1 : tb - ta;
74
86
  const ia = instanceId(a), ib = instanceId(b);
75
87
  return String(a.instance).localeCompare(String(b.instance)) || (ia < ib ? -1 : ia > ib ? 1 : 0);
76
88
  }
@@ -117,8 +129,7 @@ export function instanceSiblings(instances) {
117
129
  * duplicate names across repos render as distinct nodes.
118
130
  * Under one parent, the children that draw their parent line come first (same-work.mjs `drawingFirst`: on a
119
131
  * host that declares instance-same-work, the flagged ones), each part in the roster's order (#1577). The product
120
- * owner's contract (awebai/oats#1577, comment 6441606665) refines the name order (the Desktop expert's decision
121
- * roster-name-order-preserves-recognition) inside one parent's children only: roots, clusters and groups keep it.
132
+ * owner's contract (awebai/oats#1577, comment 6441606665) refines the roster's order inside one parent's children only: roots, clusters and groups keep it.
122
133
  * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
123
134
  * their first ROOT in the roster's order (`rosterOrder`), never by another member (#1262): a bundle sits where
124
135
  * its root sits, and gaining or losing a child, or a start or a stop, moves nothing. A cluster without a root
@@ -185,7 +196,7 @@ export function clusterInstances(instances, { links = instanceLinks, roster = in
185
196
  // Deterministic cluster label: the lexically-smallest ROOT name —
186
197
  // independent of liveness, so the visible cluster name does not flip
187
198
  // when a different member starts/stops running (review f921f7d nit).
188
- // `rank` (rosterOrder: by name) governs display ORDER within the cluster.
199
+ // `rank` (rosterOrder: by spawn time, newest first) governs display ORDER within the cluster.
189
200
  const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
190
201
  clusters.push({ key: rootNames[0], instances: ordered, head: roots[0] ?? [...members].sort(rank)[0] });
191
202
  }
@@ -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
@@ -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.1 v1.39.0`. If the
536
+ It prints the two refs, for example `oats-framework/v1.25.2 v1.42.1`. 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.1 # the installed CLI's catalog versions (below)
772
- oats.aweb: v1.39.0 # messaging: agent identities, mail and chat
773
+ oats.framework: v1.25.2 # the installed CLI's catalog versions (below)
774
+ oats.aweb: v1.42.1 # 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