@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.
- package/README.md +1 -1
- package/bin/oats.mjs +14 -13
- package/docs/capabilities.md +8 -1
- package/docs/container.md +345 -18
- package/docs/design/2026-09-23-workspace-module-contracts.md +8 -2
- package/docs/design/2026-09-27-team-model-v2.md +2 -2
- package/docs/design/2026-09-28-automations-trust.md +1 -1
- package/docs/desktop-cli-api.md +100 -53
- package/docs/desktop.md +53 -24
- package/docs/execution-targets.md +66 -48
- package/docs/implementation.md +8 -7
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +7 -7
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +30 -23
- package/docs/release-notes/v0.69.18.md +358 -0
- package/docs/release-notes/v0.69.19.md +172 -0
- package/docs/servers.md +5 -3
- package/docs/souls-and-instances.md +51 -27
- package/docs/trust-model.md +119 -0
- package/docs/tui.md +8 -8
- package/docs/upgrading.md +45 -19
- package/docs/workspaces.md +3 -3
- package/injects/work-directory.md +27 -2
- package/injects/work-workspace.md +32 -6
- package/lib/command-flags.mjs +1 -1
- package/lib/core.mjs +26 -11
- package/lib/errors.mjs +1 -1
- package/lib/home-owner.mjs +25 -0
- package/lib/host-run-admission.mjs +21 -0
- package/lib/host-run-child.mjs +31 -0
- package/lib/host-run-work.mjs +150 -0
- package/lib/host-run.mjs +43 -29
- package/lib/instance-naming.mjs +26 -44
- package/lib/packages.mjs +0 -43
- package/lib/pi-bridge.mjs +18 -6
- package/lib/schedule.mjs +5 -3
- package/lib/servers.mjs +4 -3
- package/lib/session-end.mjs +9 -0
- package/lib/session-resume-contract.mjs +1 -1
- package/lib/session-resume.mjs +144 -51
- package/lib/session-seen.mjs +16 -11
- package/lib/triggers.mjs +3 -1
- package/lib/worktree.mjs +5 -2
- package/package-catalog.json +3 -3
- package/package.json +4 -2
- package/packages/client/above-tested-notice.mjs +30 -0
- package/packages/client/above-tested.mjs +225 -0
- package/packages/client/cli-locator.mjs +67 -52
- package/packages/client/deployment-label.mjs +4 -4
- package/packages/client/instance-name.mjs +5 -29
- package/packages/client/instance-presentation.mjs +2 -2
- package/packages/client/instance-tree.mjs +18 -7
- package/packages/client/session-start.mjs +31 -3
- package/packages/client/workspace-choices.mjs +1 -1
- package/packages/client/workspace-views.mjs +1 -1
- package/packages/record/README.md +10 -8
- package/packages/record/lib/process-identity.mjs +14 -36
- package/packages/tui/lib/read.mjs +19 -3
- 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`, `
|
|
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/
|
|
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", "
|
|
49
|
-
* machine holds two or more of the deployments, the machine and its path tail ("This Mac ·
|
|
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
|
|
2
|
-
*
|
|
3
|
-
*
|
|
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);
|
|
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
|
|
14
|
-
* `rosterOrder
|
|
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
|
-
/**
|
|
70
|
-
*
|
|
71
|
-
|
|
72
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
113
|
-
|
|
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)
|
|
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 ·
|
|
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/
|
|
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-
|
|
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.
|
|
287
|
-
|
|
288
|
-
|
|
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.
|
|
357
|
-
|
|
358
|
-
|
|
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
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
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"),
|
|
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
|
-
|
|
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
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
*
|
|
280
|
-
export const
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
772
|
-
oats.aweb: v1.
|
|
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
|
|