@awebai/oats 0.69.4 → 0.69.6

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 (74) hide show
  1. package/bin/oats.mjs +141 -364
  2. package/docs/configuration.md +12 -0
  3. package/docs/design/2026-09-26-okf-knowledge-operations.md +2 -0
  4. package/docs/design/2026-10-29-warm-reader.md +261 -0
  5. package/docs/design/README.md +4 -0
  6. package/docs/desktop-cli-api.md +258 -13
  7. package/docs/execution-targets.md +36 -5
  8. package/docs/implementation.md +34 -9
  9. package/docs/integrations.md +2 -2
  10. package/docs/knowledge.md +18 -8
  11. package/docs/named-test-runs.md +4 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-notes/v0.69.5.md +146 -0
  15. package/docs/release-notes/v0.69.6.md +165 -0
  16. package/docs/schedules.md +8 -1
  17. package/docs/tui.md +23 -5
  18. package/docs/upgrading.md +20 -5
  19. package/docs/workspaces.md +2 -2
  20. package/lib/agents-root.mjs +51 -0
  21. package/lib/argv.mjs +41 -0
  22. package/lib/automation-api.mjs +7 -0
  23. package/lib/automation-scope.mjs +37 -0
  24. package/lib/automations.mjs +63 -12
  25. package/lib/captured-context.mjs +12 -0
  26. package/lib/compile-cache.mjs +36 -0
  27. package/lib/core.mjs +39 -1348
  28. package/lib/deployment-path.mjs +127 -0
  29. package/lib/deployments.mjs +2 -2
  30. package/lib/drift.mjs +95 -0
  31. package/lib/hot-reads.mjs +137 -0
  32. package/lib/install-stamp.mjs +61 -0
  33. package/lib/instance-address.mjs +21 -0
  34. package/lib/instance-events.mjs +8 -6
  35. package/lib/instance-lifecycle.mjs +4 -16
  36. package/lib/instance-listing.mjs +738 -0
  37. package/lib/instance-resolution.mjs +5 -166
  38. package/lib/kernel-features.mjs +10 -0
  39. package/lib/local-edit.mjs +1 -1
  40. package/lib/local-inputs.mjs +3 -0
  41. package/lib/materialize.mjs +2 -87
  42. package/lib/member-clone.mjs +192 -0
  43. package/lib/package-catalog.mjs +93 -0
  44. package/lib/packages.mjs +4 -24
  45. package/lib/read-call.mjs +143 -0
  46. package/lib/reader.mjs +203 -0
  47. package/lib/remote.mjs +47 -6
  48. package/lib/reserved-launch-env.mjs +20 -0
  49. package/lib/resolved-deployment.mjs +13 -5
  50. package/lib/roster-read.mjs +199 -0
  51. package/lib/schedule.mjs +5 -29
  52. package/lib/semver.mjs +12 -0
  53. package/lib/servers.mjs +10 -12
  54. package/lib/session-end.mjs +3 -2
  55. package/lib/session-input.mjs +35 -11
  56. package/lib/session-inspect.mjs +219 -0
  57. package/lib/soul-listing.mjs +216 -0
  58. package/lib/status-words.mjs +30 -0
  59. package/lib/version.mjs +9 -0
  60. package/lib/workspace-read.mjs +160 -0
  61. package/lib/write-file-atomic.mjs +28 -0
  62. package/package-catalog.json +4 -4
  63. package/package.json +1 -1
  64. package/packages/client/cli-locator.mjs +1 -0
  65. package/packages/client/cli-probe-contract.mjs +4 -2
  66. package/packages/client/deployment-observer.mjs +8 -3
  67. package/packages/client/deployment-panel.mjs +17 -1
  68. package/packages/client/deployment-read-cli.mjs +48 -27
  69. package/packages/client/own-codes.mjs +3 -0
  70. package/packages/client/warm-reader.mjs +241 -0
  71. package/packages/tui/lib/client.mjs +2 -1
  72. package/packages/tui/lib/read.mjs +59 -11
  73. package/packages/tui/lib/store.mjs +7 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -2,9 +2,10 @@
2
2
  * list (awebai/oats#1390; lib/deployments.mjs listResolved).
3
3
  *
4
4
  * The resolvers report the deployment directory they found: `loadLocal` (lib/workspace.mjs) the
5
- * directory of the oats-local.yaml its walk up found, as spelled; `ensureRoot` (lib/core.mjs) the
5
+ * directory of the oats-local.yaml its walk up found, as spelled; `ensureRoot` (lib/agents-root.mjs) the
6
6
  * directory of the canonical agents root, `canonical`. The observer is called once, when the
7
- * process exits, with the root the command settled on: the first canonical one reported, else the
7
+ * process exits (or, in a process answering many reads, when each read ends: lib/read-call.mjs), with
8
+ * the root the command settled on: the first canonical one reported, else the
8
9
  * first one, and whether it is canonical. So a command that resolves its canonical root is compared
9
10
  * with that root, never with an earlier spelling of the same deployment. Nothing happens until the
10
11
  * CLI sets an observer for this process (the commands in its one table): library callers and tests
@@ -14,11 +15,18 @@
14
15
  let observer = null;
15
16
  const reported = { canonical: null, spelled: null };
16
17
 
17
- /** Observe the deployment this process resolves; called once, at exit. */
18
- export function observeResolvedDeployment(fn) {
19
- if (!observer) process.once("exit", settleResolvedDeployment);
18
+ /** Observe the deployment this process resolves; called once, at exit. `atExit: false`: the caller
19
+ * settles it itself (settleResolvedDeployment), as a process answering many reads does at the end of
20
+ * each one (lib/read-call.mjs). */
21
+ export function observeResolvedDeployment(fn, { atExit = true } = {}) {
22
+ if (!observer && atExit) process.once("exit", settleResolvedDeployment);
20
23
  observer = fn;
21
24
  }
25
+ /** Forget what the resolvers reported, keeping the observer: the start of one read in a process that
26
+ * answers many (lib/read-call.mjs). */
27
+ export function resetResolvedDeployment() {
28
+ reported.canonical = reported.spelled = null;
29
+ }
22
30
 
23
31
  /** A resolver found the deployment directory `dir` (`canonical`: its canonical spelling). */
24
32
  export function resolvedDeployment(dir, { canonical = false } = {}) {
@@ -0,0 +1,199 @@
1
+ /** lib/roster-read.mjs — `oats status`, the roster read (awebai/oats#1630): the deployment's agents and
2
+ * instances, each instance's workspace drift, and its workspace identity. One implementation behind the
3
+ * CLI (bin/oats.mjs status) and a process that answers it many times (lib/read-call.mjs, whose header
4
+ * describes the context and the answer). `statusAnswer(ctx)` is the `--json` answer, a bare document
5
+ * (never an envelope) or a failure envelope; `statusView(ctx)` the data bin's text renderer reads. A
6
+ * leaf a hot read loads (lib/hot-reads.mjs): never core.mjs. Kernel-private, not exported from `./core`. */
7
+ import { readFileSync } from "node:fs";
8
+ import { dirname, join } from "node:path";
9
+ import { ensureRoot } from "./agents-root.mjs";
10
+ import { legacyCapturedHomes, legacyLocalAgents, listInstances } from "./instance-listing.mjs";
11
+ import { KERNEL_FEATURES } from "./kernel-features.mjs";
12
+ import { readLockIfPresent } from "./packages.mjs";
13
+ import { answerWarnings, refuse, runRead } from "./read-call.mjs";
14
+ import { lastObservedCommit, parseRepoRef, peekAtCommit } from "./remote.mjs";
15
+ import { readSessionViewer } from "./session-viewer.mjs";
16
+ import { teamModel } from "./teams.mjs";
17
+ import { loadLocal, memberRowByKey } from "./workspace.mjs";
18
+
19
+ /** `oats status --json`: → `{ exit, answer, stderr }` (lib/read-call.mjs). `ctx.team`: `--team` was given. */
20
+ export function statusAnswer(ctx) {
21
+ return runRead(ctx, async (call) => ({ answer: statusDocument(call, await statusFacts(call, ctx)) }));
22
+ }
23
+
24
+ /** `oats status` in text mode: → `{ exit, answer, view, stderr }`, `view` `{ root, agents, ws, problems }`
25
+ * (`ws`: statusDrift's answer) when it did not refuse, `answer` the failure envelope when it did. */
26
+ export function statusView(ctx) {
27
+ return runRead(ctx, async (call) => ({ view: await statusFacts(call, ctx) }));
28
+ }
29
+
30
+ /** The problems doctor and status share for a v2 deployment: what OATS 0.25 left
31
+ * under local-agents/ (named, never read), and the captured homes under the agents root
32
+ * (`records`: legacyCapturedHomes'). */
33
+ export function legacyLayoutProblems(root, { records } = {}) {
34
+ return [legacyLocalAgents(root), legacyCapturedHomes(root, { records })].filter(Boolean);
35
+ }
36
+
37
+ async function statusFacts(call, { dir, team = false }) {
38
+ if (team) refuse("E_BAD_ARGS", "status --team was removed with the classic team scope: `oats status` in the deployment lists every instance, and `oats workspace status` shows the members");
39
+ let root;
40
+ try { root = ensureRoot(dir); }
41
+ catch (e) { if (e?.code === "E_NO_DEPLOYMENT") refuse("E_NO_DEPLOYMENT", e.message, e.details ?? e.provenance); throw e; }
42
+ // Each home's instance.json, as the listing read it: parsed once for the whole read.
43
+ const records = new Map();
44
+ const data = listInstances(root, undefined, undefined, { records });
45
+ const ws = await statusDrift(data, call, dir);
46
+ const problems = legacyLayoutProblems(root, { records });
47
+ return { root, agents: data, ws, problems };
48
+ }
49
+
50
+ function statusDocument(call, { root, agents: data, ws, problems }) {
51
+ // The soul key (feature launch-preference): what souls.launch and `oats soul teams <key>` use —
52
+ // from the instances' records, so it needs no remote.
53
+ for (const a of data) a.key = agentSoulKey(a);
54
+ if (ws) for (const a of data) {
55
+ const stamp = ws.souls.get(a.name);
56
+ if (stamp) a.soulSource = { repoKey: stamp.repoKey, commit: stamp.commit, path: stamp.path, ...(stamp.current ? { current: stamp.current, status: stamp.current === stamp.commit ? "current" : "moved" } : {}) };
57
+ for (const i of a.instances || []) {
58
+ const key = i.home ?? `${a.name}/${i.instance}`;
59
+ const rows = ws.drift.get(key);
60
+ if (rows) i.modules = rows.map((r) => ({ name: r.module, from: r.from, commit: r.recorded?.commit ?? null, current: r.current, status: r.status, ...(r.reason ? { reason: r.reason } : {}) }));
61
+ const s = ws.soul.get(key);
62
+ if (s) i.soul = { repoKey: s.repoKey, commit: s.commit, current: s.current?.commit ?? null, status: s.status, ...(s.reason ? { reason: s.reason } : {}), ...(s.package ? { package: s.package, version: s.version, currentVersion: s.current?.version ?? null } : {}) };
63
+ }
64
+ }
65
+ const observation = call.maxAge === null ? {} : { observation: call.observation() };
66
+ // `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
67
+ // it, so a remote roster relays the host's without probing it. Never part of a reused observation.
68
+ return { root, agents: data, ...observation, features: KERNEL_FEATURES, sessionViewer: readSessionViewer(), ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery, call.remoteOptions) } } : {}), ...(problems.length ? { problems } : {}), ...answerWarnings() };
69
+ }
70
+
71
+ /** Workspace drift for `oats status` (decision 17: shown, not prevented). ONE discovery over
72
+ * the remotes serves every instance; `driftOf` compares each instance's recorded modules to
73
+ * the members' current state (and package modules to the lock), `soulDriftOf` the instance's
74
+ * recorded SOUL SOURCE (instance.json.workspace.soul) to its member's current commit. Offline →
75
+ * { unreachable }. Returns null when the deployment is not a workspace deployment (no
76
+ * oats-local.yaml). `souls` maps each workspace soul NAME (agents/<name>/.oats-soul-source.json
77
+ * present) to its stamp — the roster's `repo:` column for a workspace soul. */
78
+ async function statusDrift(data, call, dir) {
79
+ let ctx;
80
+ try { ctx = loadLocal(dir); }
81
+ catch (e) {
82
+ if (e?.code === "E_LOCAL_MISSING") return null;
83
+ // A 0.25 oats-config.yaml inside the deployment: the typed migration error, never a stack.
84
+ if (e?.code === "E_CONFIG_BROKEN") refuse(e.code, e.message, e.details);
85
+ throw e;
86
+ }
87
+ const hasModules = (i) => i.modules && typeof i.modules === "object" && Object.keys(i.modules).length > 0;
88
+ const hasSoul = (i) => i.workspace && typeof i.workspace === "object" && i.workspace.soul && typeof i.workspace.soul === "object" && typeof i.workspace.soul.repoKey === "string";
89
+ // Workspace souls of this roster: the stamp ensureWorkspaceSoul leaves beside the soul pointer.
90
+ const souls = new Map();
91
+ for (const a of data) {
92
+ if (!a.dir) continue;
93
+ try { const stamp = JSON.parse(readFileSync(join(a.dir, ".oats-soul-source.json"), "utf8")); if (stamp && typeof stamp.repoKey === "string") souls.set(a.name, { repoKey: stamp.repoKey, commit: typeof stamp.commit === "string" ? stamp.commit : null, path: stamp.path ?? null, ...(typeof stamp.package === "string" ? { package: stamp.package, version: stamp.version ?? null } : {}) }); }
94
+ catch { /* not a workspace soul (classic, or an unreadable stamp) */ }
95
+ }
96
+ const anything = data.some((a) => (a.instances || []).some((i) => hasModules(i) || hasSoul(i)));
97
+ if (!anything) return { drift: new Map(), soul: new Map(), souls, unreachable: null, local: ctx.local, discovery: null };
98
+ const deploymentDir = dirname(ctx.path);
99
+ let lock = null;
100
+ try { lock = readLockIfPresent(deploymentDir); } catch { lock = null; }
101
+ let discovery;
102
+ // The standalone view (decisions 10/25) is a discovery too: drift of a standalone
103
+ // instance is computed against its member's current state, not reported "unreachable".
104
+ try { const { discoverOrStandalone } = await import("./member-clone.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: call.remoteOptions() }); }
105
+ catch (e) {
106
+ const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
107
+ return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
108
+ }
109
+ const { driftOf, soulDriftOf } = await import("./drift.mjs");
110
+ const drift = new Map();
111
+ const soul = new Map();
112
+ for (const a of data) for (const i of a.instances || []) {
113
+ const key = i.home ?? `${a.name}/${i.instance}`;
114
+ if (hasModules(i)) { try { drift.set(key, driftOf(i, discovery, { lock })); } catch { /* an unreadable module record shows as no drift rows */ } }
115
+ if (hasSoul(i)) { try { const row = soulDriftOf(i, discovery); if (row) soul.set(key, row); } catch { /* an unreadable soul record shows as no soul row */ } }
116
+ }
117
+ // The roster's soul row reflects the CURRENT member commit too (the pointer may lag a moved member).
118
+ // First match per key, as `find` gave, from indexes built once (not a scan per agent).
119
+ const packageSoulAt = new Map();
120
+ for (const p of discovery.packageSouls || []) { const k = `${p.package}\0${p.path}`; if (!packageSoulAt.has(k)) packageSoulAt.set(k, p); }
121
+ for (const [, stamp] of souls) {
122
+ if (typeof stamp.package === "string") { const now = packageSoulAt.get(`${stamp.package}\0${stamp.path}`); if (now) stamp.current = now.commit; continue; }
123
+ const member = memberRowByKey(discovery.members, stamp.repoKey);
124
+ if (member && typeof member.commit === "string" && (member.confirmed || (discovery.standalone === true && member.key === discovery.key))) stamp.current = member.commit;
125
+ }
126
+ return { drift, soul, souls, unreachable: null, local: ctx.local, discovery };
127
+ }
128
+ /** The deployment's workspace identity in `oats status --json` (feature workspace-identity), read
129
+ * OFFLINE. `key` is the workspace HOST's canonical repo key (parseRepoRef(...).key) and `ref` the
130
+ * reference as oats-local.yaml writes it. The host is the one this run observed, else the one this
131
+ * machine's parsed cache knows: `ref` itself when the cache holds its workspace file, or the host its
132
+ * cached oats-membership.yaml names when `ref` is a member ("workspace"). A member whose host is not
133
+ * known keys as itself ("member"); a ref nothing is known of is taken as the host, as the schema
134
+ * defines `workspace:` ("workspace"). The team model resolves as teamModel resolves it (the default is
135
+ * the local one the workspace allows, else the workspace's; a committed team wins a collision) over the shared teams of, in order, the workspace
136
+ * file this run observed (`teamsFrom: "observed"`), the cached file ("cache": no git process), or none
137
+ * ("local"). `standalone` is the CONFIGURED standalone view only (oats-local.yaml `standalone:`): it
138
+ * reads no workspace file, so its local teams are the whole team model. A run that fell back to the
139
+ * standalone view (the host unreadable) is not: its team model is the workspace's, and its
140
+ * discovery is the member's, never the host's key. */
141
+ function workspaceIdentity(local, discovery, remoteOptions) {
142
+ const ref = local.workspace;
143
+ const standalone = typeof local.standalone === "string" && local.standalone !== "";
144
+ const observed = discovery && discovery.standalone !== true && discovery.workspace ? discovery : null;
145
+ const cached = observed ? null : cachedWorkspace(ref, remoteOptions);
146
+ const keyOf = (r) => { try { return parseRepoRef(r).key; } catch { return null; } };
147
+ let key, keyFrom;
148
+ if (observed) [key, keyFrom] = [observed.key, "workspace"];
149
+ else if (cached && cached.host === null) [key, keyFrom] = [keyOf(ref), "member"];
150
+ else [key, keyFrom] = [keyOf(cached?.host ?? ref), "workspace"];
151
+ if (key === null) keyFrom = null; // a reference parseRepoRef refuses: unusable, never matched
152
+ let shared = null, teamsFrom = "local";
153
+ if (!standalone) {
154
+ if (observed) [shared, teamsFrom] = [observed.workspace, "observed"];
155
+ else if (cached?.file) [shared, teamsFrom] = [cached.file, "cache"];
156
+ }
157
+ const model = teamModel(shared, local);
158
+ // A soul with no souls: default of its own lives here (team model 3: the local default the workspace allows, else the workspace's).
159
+ const deploymentDefault = model.localDefault ?? model.workspaceDefault;
160
+ const labels = [...model.labels.keys()].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
161
+ return {
162
+ key, ref, keyFrom, standalone,
163
+ defaultTeam: deploymentDefault === null ? null : { label: deploymentDefault, team: model.labels.get(deploymentDefault)?.team ?? null },
164
+ teams: Object.fromEntries(labels.map((l) => [l, model.labels.get(l).team])),
165
+ teamsFrom,
166
+ };
167
+ }
168
+ /** What this machine's parsed cache knows of the workspace `ref` names (the values observeWorkspace and
169
+ * confirmMembership stored, each at its repo's last observed commit): { host, file } — `host` the ref
170
+ * of the workspace host, `file` its workspace file or null — when `ref` is the host (its workspace file
171
+ * is cached) or a member whose cached oats-membership.yaml names it (discoverOrStandalone follows the
172
+ * same backlink). A member's backlink is cached whether its own workspace slot was observed (missing)
173
+ * or never was (the host's discovery confirmed it). { host: null, file: null } for a ref cached as
174
+ * having no workspace file and no backlink; null when nothing is known. */
175
+ export function cachedWorkspace(ref, remoteOptions) {
176
+ const options = remoteOptions();
177
+ const cached = (r, item) => {
178
+ const commit = lastObservedCommit(r, options);
179
+ const value = commit ? peekAtCommit(r, commit, item, options) : undefined;
180
+ return value && typeof value === "object" ? value : null;
181
+ };
182
+ const fileOf = (read) => (read && !read.missing && !read.problems && read.value && typeof read.value === "object" ? read.value : null);
183
+ const read = cached(ref, "workspace");
184
+ if (read && !read.missing) return { host: ref, file: fileOf(read) };
185
+ const membership = cached(ref, "membership");
186
+ const host = membership?.kind === "ok" && typeof membership.value?.workspace === "string" ? membership.value.workspace : null;
187
+ if (host !== null) return { host, file: fileOf(cached(host, "workspace")) };
188
+ return read ? { host: null, file: null } : null;
189
+ }
190
+ /** A roster agent's soul key: the qualified name of a package soul, else the recorded agent (soul) name;
191
+ * null when no instance records a workspace soul. Exactly soulKeyOf for the soul it was spawned from. */
192
+ function agentSoulKey(a) {
193
+ for (const i of a.instances || []) {
194
+ const soul = i?.workspace?.soul;
195
+ if (!soul || typeof soul !== "object") continue;
196
+ return soul.package && typeof soul.qualifiedName === "string" ? soul.qualifiedName : (typeof i.agent === "string" ? i.agent : a.name);
197
+ }
198
+ return null;
199
+ }
package/lib/schedule.mjs CHANGED
@@ -33,14 +33,15 @@ import { noteRuntimeName } from "./deprecation.mjs";
33
33
  import { herdrSettingRemoved } from "./errors.mjs";
34
34
  import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
35
35
  import { pollSourced, tickTriggers } from "./triggers.mjs";
36
- import { resolveMemberClone } from "./instance-resolution.mjs";
37
- import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
38
- import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
36
+ import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
37
+ import { MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
39
38
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
40
39
  import { readStartExited } from "./session-end.mjs";
40
+ import { childEnv, scopeAutomations } from "./automation-scope.mjs";
41
+ export { SCHEDULE_API } from "./automation-api.mjs";
42
+ export { childEnv, scopeAutomations } from "./automation-scope.mjs";
41
43
 
42
44
  export const SCHEDULE_FILE = "oats-schedules.json";
43
- export const SCHEDULE_API = 2;
44
45
  const ID_RE = SCHEDULE_NAME_RE;
45
46
  const HARNESSES = new Set(["pi", "claude", "codex"]);
46
47
  const MESSAGE_MAX = 256 * 1024;
@@ -545,22 +546,6 @@ export function findHomesInScope(ws, instance) {
545
546
  function scheduleBlock(def, minute) {
546
547
  return `\n\n## Scheduled run\n\nThis instance was launched by OATS schedule "${def.workspace?.qid ?? def.id}" for ${minute.toISOString()} (cron "${def.cron}" in ${def.tz}). It is disposable: finish the task above, bring your memory files up to date, and end with \`oats retire --self\`.\n`;
547
548
  }
548
- /** The environment a scheduler-launched oats child runs with: the caller's
549
- * frozen instance identity and capability snapshot removed (a tick or run-now
550
- * may be invoked from inside an unrelated instance; dispatch belongs to the
551
- * job's cwd and explicit selectors, never to that caller), host configuration
552
- * such as OATS_HOME_DIR and credentials kept. Shared by command and spawn jobs. */
553
- export function childEnv() {
554
- const env = { ...process.env };
555
- for (const key of [...RESERVED_LAUNCH_ENV,
556
- "OATS_DEPLOYMENT", "OATS_RESOLUTION", "OATS_CAPABILITY", "OATS_LAYER", "OATS_LEVEL", "OATS_META", "OATS_OPERATION",
557
- "OATS_REPO", "OATS_BRANCH", "OATS_WORK", "OATS_KIND", "OATS_TASK",
558
- "OATS_HARNESS", "OATS_PREVIOUS_HARNESS", "OATS_RUNTIME", "OATS_PREVIOUS_RUNTIME", "OATS_LAUNCH_PREVIEW", "OATS_RETIRE_INTENT",
559
- "OATS_TEAM_NAME", "OATS_TEAM_SCOPE", "OATS_TEAM_ID", "OATS_TEAM_LABEL", "OATS_TEAM_LABELS", "OATS_DEFAULT_TEAM", "OATS_DEFAULT_TEAM_ID", "OATS_DEFAULT_TEAM_FROM", "OATS_TEAMS", "OATS_TEAMS_SOURCE", "OATS_TRIGGER_EVENT_FILE",
560
- "OATS_TREE", "OATS_TREE_CLONE", "OATS_TREE_REMOTE", "OATS_TREE_MEMBER", "OATS_TREE_BASE", "OATS_TREE_BASE_OID", "OATS_PURPOSE", "OATS_TREE_ORIGIN",
561
- ]) delete env[key];
562
- return env;
563
- }
564
549
  /** The deployment a spawn job runs in (module contract §5, decision 7): the
565
550
  * scope's oats-local.yaml. An unreadable one is reported (E_WORKSPACE_SCHEMA)
566
551
  * by the spawn, never answered some other way. */
@@ -937,15 +922,6 @@ export function tickWorkspace(ws, { now = new Date(), firedAt = now, io, reg, ws
937
922
  return considered;
938
923
  }
939
924
 
940
- /** One scope's automations context (lib/automations.mjs automationContext) with its oats-local.yaml;
941
- * an unreadable oats-local.yaml means no workspace automations (the local jobs still run). */
942
- export function scopeAutomations(ws, { io, now = new Date(), refresh = false, cache = new Map() } = {}) {
943
- let local = null;
944
- try { local = loadLocal(ws).local; } catch { local = null; }
945
- const clonePathOf = (repoKey) => resolveMemberClone({ deployment: ws, soulEntry: { repoKey }, local });
946
- const ctx = automationContext(ws, { local, io: { ...(io || {}), childEnv }, now, refresh, cache, clonePathOf });
947
- return Object.assign(ctx, { ws, local });
948
- }
949
925
  /** A stored minute key as a time, or null when it is not one. */
950
926
  function minuteTime(key) {
951
927
  const t = typeof key === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(key) ? Date.parse(`${key}:00Z`) : NaN;
package/lib/semver.mjs ADDED
@@ -0,0 +1,12 @@
1
+ /** The order of two kernel or package versions. A leaf (awebai/oats#1630): `oats workspace status`
2
+ * compares versions without loading servers.mjs, which imports it and re-exports it. */
3
+
4
+ export function compareSemver(a, b) {
5
+ const pa = String(a).split(/[.-]/).map((x) => Number.parseInt(x, 10));
6
+ const pb = String(b).split(/[.-]/).map((x) => Number.parseInt(x, 10));
7
+ for (let i = 0; i < 3; i++) {
8
+ const d = (pa[i] || 0) - (pb[i] || 0);
9
+ if (d) return d;
10
+ }
11
+ return 0;
12
+ }
package/lib/servers.mjs CHANGED
@@ -25,11 +25,14 @@ import { parseStrictJson } from "./canonical-json.mjs";
25
25
  import { noteRuntimeName } from "./deprecation.mjs";
26
26
  import { readWaitingClaim } from "./instance-events.mjs";
27
27
  import { readRetireState } from "./retire-state.mjs";
28
+ import { SESSION_END } from "./session-resume-contract.mjs";
28
29
  import { paletteColor } from "./instance-color.mjs";
29
30
  import { withDirLock } from "./dir-lock.mjs";
30
- import { shellWord } from "./core.mjs";
31
+ import { shellWord } from "./shell-word.mjs";
31
32
  import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
32
33
  import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
34
+ import { compareSemver } from "./semver.mjs";
35
+ export { compareSemver } from "./semver.mjs";
33
36
 
34
37
  const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
35
38
  export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
@@ -529,16 +532,6 @@ export const SESSION_REMOTE_VERSION = "0.22.2";
529
532
  * moves to 0.22.2 with that release. */
530
533
  export const MIN_REMOTE_VERSION = "0.22.1";
531
534
 
532
- export function compareSemver(a, b) {
533
- const pa = String(a).split(/[.-]/).map((x) => Number.parseInt(x, 10));
534
- const pb = String(b).split(/[.-]/).map((x) => Number.parseInt(x, 10));
535
- for (let i = 0; i < 3; i++) {
536
- const d = (pa[i] || 0) - (pb[i] || 0);
537
- if (d) return d;
538
- }
539
- return 0;
540
- }
541
-
542
535
  // ---------------------------------------------------------------- snapshots
543
536
 
544
537
  export function snapshotPath(serverId, instance) {
@@ -913,6 +906,11 @@ const rowRetire = (i) => {
913
906
  /** `sameWork` (feature instance-same-work) as `background`: relayed ONLY when the host's row says
914
907
  * `sameWork: true`, the one value a row carries; anything else, and a host that omits it, is absent. */
915
908
  const rowSameWork = (i) => (i.sameWork === true ? { sameWork: true } : {});
909
+ /** `sessionEnd` (feature session-resume, #1628) as `retire` is: relayed ONLY when the host's row has the
910
+ * key, which a host whose kernel predates the feature never sends, so its rows say nothing. A value that
911
+ * is not one of the contract's (lib/session-resume-contract.mjs SESSION_END) drops the key. */
912
+ const SESSION_ENDS = new Set(Object.values(SESSION_END));
913
+ const rowSessionEnd = (i) => (SESSION_ENDS.has(i.sessionEnd) ? { sessionEnd: i.sessionEnd } : {});
916
914
 
917
915
  /** The bounds a host's `features` list must meet to be relayed (feature server-probe-features). */
918
916
  export const HOST_FEATURES_MAX = 256;
@@ -1015,7 +1013,7 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
1015
1013
  harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null,
1016
1014
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
1017
1015
  running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
1018
- ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i),
1016
+ ...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowSameWork(i), ...rowSessionEnd(i),
1019
1017
  // Every row the host reports is addressed by its home, saved
1020
1018
  // route or not; savedRoute says only that it was spawned from here.
1021
1019
  retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
@@ -4,8 +4,9 @@
4
4
  * - `.oats-start-exited`: the window a spawn or a start made writes it when the harness exits,
5
5
  * `{"startId":"<id>","status":<n>}` (the harness's exit status). A kernel before 0.69 wrote the
6
6
  * start id alone on one line, and only from a start's window.
7
- * - `.oats-stop.json`: `oats instance stop` / `oats session stop`, `{ instance, at, stop, retained,
8
- * startId }`; `startId` (0.69) is the start the stop ended, null when the home had none.
7
+ * - `.oats-stop.json`: `oats instance stop` / `oats session stop`, a retire and a restart (before
8
+ * they end the session), `{ instance, at, stop, retained, startId }`; `startId` (0.69) is the
9
+ * start the stop ended, null when the home had none.
9
10
  * A reboot or a killed tmux server leaves neither file for the start that was running: that is a
10
11
  * lost session, the one a resume brings back. Dependency-free: status, start --resume and the
11
12
  * schedule runner read the files through here. */
@@ -56,6 +56,9 @@ export function inspectSessionTarget(target, io, { includeSize = false, includeP
56
56
  const state = createSessionPaneInspector(io)(rows, { includeSize, name: target.window });
57
57
  return includePanes ? { ...state, panes: rows.length } : state;
58
58
  }
59
+ /** The shell/descendant rule's answer when the process table cannot establish it (#1641): unknown,
60
+ * never a fallback shell, with the reason status carries as `runtimeError`. */
61
+ const unestablished = (why) => new Error(`${why}, so whether the harness runs cannot be told`);
59
62
  /** Interpret one window's panes: resolve the agent's pane (resolveAgentPane, `name` the window's
60
63
  * instance name), then judge that pane alone with the lifecycle's shell/descendant rule; the other
61
64
  * panes never make it unknown. Each row is `id, dead, command, pid[, cols, rows], mark` (the mark may
@@ -63,17 +66,27 @@ export function inspectSessionTarget(target, io, { includeSize = false, includeP
63
66
  * process scans cost one child. */
64
67
  export function createSessionPaneInspector(io) {
65
68
  let processRead;
69
+ // Rows are `{ pid, ppid, name }`, `name` "" when ps printed none. A line that is not a process row
70
+ // is never dropped silently: `malformed` keeps the snapshot from proving a fallback shell.
66
71
  const readProcesses = () => {
67
72
  if (!processRead) {
68
73
  try {
69
74
  const output = (io?.exec || execFileSync)("ps", ["-axo", "pid=,ppid=,comm="], {
70
75
  encoding: "utf8", timeout: 10000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"],
71
76
  });
72
- processRead = { rows: output.split("\n").map(line => line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/)).filter(Boolean) };
77
+ const rows = [];
78
+ let malformed = false;
79
+ for (const line of output.split("\n")) {
80
+ if (!line.trim()) continue;
81
+ const row = line.trim().match(/^(\d+)\s+(\d+)(?:\s+(.*))?$/);
82
+ if (row) rows.push({ pid: row[1], ppid: row[2], name: row[3] ?? "" });
83
+ else malformed = true;
84
+ }
85
+ processRead = { rows, malformed };
73
86
  } catch (error) { processRead = { error }; }
74
87
  }
75
88
  if (processRead.error) throw processRead.error;
76
- return processRead.rows;
89
+ return processRead;
77
90
  };
78
91
  return (rows, { includeSize = false, name } = {}) => {
79
92
  if (!rows.length) return { backend: "tmux", present: false, state: "stopped" };
@@ -95,26 +108,37 @@ export function createSessionPaneInspector(io) {
95
108
  // A missing tmux label can still be a fallback shell. Only the pane's
96
109
  // own comm can establish that; an optional failed read stays unknown.
97
110
  try {
98
- const own = readProcesses().find(([, pid]) => pid === panePid);
99
- shell = own ? isShellProcess(own[3]) : false;
111
+ const own = readProcesses().rows.find((p) => p.pid === panePid);
112
+ shell = own ? isShellProcess(own.name) : false;
100
113
  } catch { /* missing process information is not proof of a fallback shell */ }
101
114
  }
102
115
  if (dead === "0" && shell) {
103
- // macOS tmux can report the wrapper shell while the harness is its child.
104
- // Only a shell with no non-shell descendants is a fallback prompt.
116
+ // tmux names the pane's foreground process group's leader: the launch's own shell
117
+ // (default-shell -c) while the harness runs as its child, on macOS and Linux alike.
118
+ // Only the pane's own process, in the snapshot as a shell, with no non-shell
119
+ // descendant, is a fallback prompt. A live non-shell process is the harness running;
120
+ // anything else is unknown, never the prompt (#1641).
105
121
  if (!/^\d+$/.test(panePid)) throw new Error("tmux returned no pane process id");
106
- const processes = readProcesses();
122
+ const { rows: processes, malformed } = readProcesses();
123
+ const own = processes.find((p) => p.pid === panePid);
124
+ // A ps that cannot see the pane (another PID namespace, a sandbox) or a pane respawned since
125
+ // tmux answered.
126
+ if (!own) throw unestablished(`the process table has no process ${panePid}, the agent's pane's own`);
107
127
  const descendants = new Set([panePid]);
108
- let active = false;
128
+ let active = !isShellProcess(own.name) && own.name !== "", unnamed = own.name === "" ? own.pid : null;
109
129
  for (let changed = true; changed;) {
110
130
  changed = false;
111
- for (const [, pid, parent, name] of processes) {
112
- if (descendants.has(parent) && !descendants.has(pid)) {
131
+ for (const { pid, ppid, name } of processes) {
132
+ if (descendants.has(ppid) && !descendants.has(pid)) {
113
133
  descendants.add(pid); changed = true;
114
- if (!isShellProcess(name)) active = true;
134
+ if (name === "") unnamed ??= pid;
135
+ else if (!isShellProcess(name)) active = true;
115
136
  }
116
137
  }
117
138
  }
139
+ if (!active && unnamed !== null) throw unestablished(`process ${unnamed} in the agent's pane has no command name in the process table`);
140
+ // A line that is not a process row may be one of the pane's processes.
141
+ if (!active && malformed) throw unestablished("the process table has a line that is not a process");
118
142
  state = active ? "unknown" : "shell";
119
143
  }
120
144
  return { backend: "tmux", present: dead === "0", state, paneId,