@awebai/oats 0.69.12 → 0.69.14

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 (70) hide show
  1. package/README.md +216 -178
  2. package/bin/oats.mjs +176 -184
  3. package/docs/capabilities.md +4 -1
  4. package/docs/configuration.md +63 -5
  5. package/docs/container.md +246 -0
  6. package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
  7. package/docs/desktop-cli-api.md +376 -37
  8. package/docs/desktop-instance-start.md +4 -1
  9. package/docs/desktop.md +58 -12
  10. package/docs/execution-targets.md +69 -6
  11. package/docs/implementation.md +86 -29
  12. package/docs/integrations.md +3 -2
  13. package/docs/knowledge-and-learning.md +72 -0
  14. package/docs/oats-local.schema.json +11 -2
  15. package/docs/official-catalog.md +39 -5
  16. package/docs/packages.md +93 -14
  17. package/docs/release-lane.md +2 -1
  18. package/docs/release-notes/v0.69.13.md +767 -0
  19. package/docs/release-notes/v0.69.14.md +83 -0
  20. package/docs/schedules.md +26 -3
  21. package/docs/servers.md +181 -5
  22. package/docs/souls-and-instances.md +140 -11
  23. package/docs/tui.md +1 -1
  24. package/docs/upgrading.md +24 -5
  25. package/docs/workspaces.md +31 -5
  26. package/lib/claim.mjs +21 -5
  27. package/lib/command-flags.mjs +238 -0
  28. package/lib/core.mjs +791 -563
  29. package/lib/deployments.mjs +4 -3
  30. package/lib/dir-lock.mjs +126 -31
  31. package/lib/errors.mjs +1 -1
  32. package/lib/harness-token.mjs +110 -0
  33. package/lib/hot-reads.mjs +4 -3
  34. package/lib/instance-events.mjs +28 -6
  35. package/lib/instance-git.mjs +138 -13
  36. package/lib/instance-inspect.mjs +6 -1
  37. package/lib/instance-listing.mjs +80 -38
  38. package/lib/instance-resolution.mjs +56 -3
  39. package/lib/instance-upgrade.mjs +16 -20
  40. package/lib/launch-env-exec.sh +7 -0
  41. package/lib/launch-env.mjs +74 -0
  42. package/lib/launch-preference.mjs +19 -12
  43. package/lib/member-clone.mjs +7 -1
  44. package/lib/packages.mjs +74 -2
  45. package/lib/read-call.mjs +3 -0
  46. package/lib/reader.mjs +3 -2
  47. package/lib/refused-text.mjs +3 -2
  48. package/lib/remote.mjs +119 -27
  49. package/lib/retained-after-retire.mjs +2 -7
  50. package/lib/retire-git-forms.mjs +41 -0
  51. package/lib/retire-incomplete.mjs +96 -0
  52. package/lib/schedule.mjs +2 -1
  53. package/lib/servers.mjs +78 -23
  54. package/lib/session-resume.mjs +68 -53
  55. package/lib/session-seen.mjs +54 -5
  56. package/lib/start-env.mjs +13 -7
  57. package/lib/system-tools.mjs +1 -1
  58. package/lib/teams.mjs +11 -4
  59. package/lib/upgrade-state.mjs +13 -2
  60. package/lib/worktree.mjs +56 -7
  61. package/package-catalog.json +1 -1
  62. package/package.json +2 -1
  63. package/packages/client/instance-lifecycle.mjs +1 -1
  64. package/packages/client/lifecycle-contract.mjs +3 -1
  65. package/packages/client/session-resume-cli.mjs +2 -1
  66. package/packages/client/session-start.mjs +10 -7
  67. package/packages/client/workspace-cli.mjs +5 -1
  68. package/share/oats-login-receive +204 -0
  69. package/skills/oats-getting-started/SKILL.md +92 -25
  70. package/lib/tmux-config.mjs +0 -35
package/lib/servers.mjs CHANGED
@@ -21,6 +21,7 @@ import { createHash, randomBytes } from "node:crypto";
21
21
  import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
22
22
  import { homedir } from "node:os";
23
23
  import { basename, join, resolve } from "node:path";
24
+ import { isDeepStrictEqual } from "node:util";
24
25
  import { parseStrictJson } from "./canonical-json.mjs";
25
26
  import { noteRuntimeName } from "./deprecation.mjs";
26
27
  import { readWaitingClaim, validWaitingMessage } from "./instance-events.mjs";
@@ -39,6 +40,7 @@ export { compareSemver } from "./semver.mjs";
39
40
 
40
41
  const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
41
42
  export const SERVERS_FILE = () => join(OATS_HOME_DIR(), "servers.json");
43
+ export const SERVER_OPERATOR_ROUTES_FILE = () => join(OATS_HOME_DIR(), "server-operator-routes.json");
42
44
  export const REMOTE_SNAPSHOT_DIR = () => join(OATS_HOME_DIR(), "remote");
43
45
 
44
46
  /** Every ssh invocation is non-interactive: a host that needs a password or a
@@ -131,6 +133,28 @@ export function readServers() {
131
133
  return out;
132
134
  }
133
135
 
136
+ /** Operator routes stay out of servers.json so an older kernel can still read every agent route. */
137
+ export function readServerOperatorRoutes() {
138
+ const file = SERVER_OPERATOR_ROUTES_FILE();
139
+ if (!existsSync(file)) return {};
140
+ let routes;
141
+ try { routes = JSON.parse(readFileSync(file, "utf8")); }
142
+ catch { throw serverError("E_SERVERS_UNREADABLE", `${file} is not valid JSON`); }
143
+ validateOperatorRoutes(routes);
144
+ return routes;
145
+ }
146
+
147
+ export function validateOperatorSshHost(alias) {
148
+ if (typeof alias !== "string" || !SSH_HOST_RE.test(alias)) throw serverError("E_SERVER_INVALID", "operatorSshHost must be an OpenSSH host alias or host name (no user@, no options)");
149
+ }
150
+ function validateOperatorRoutes(routes) {
151
+ if (!routes || typeof routes !== "object" || Array.isArray(routes)) throw serverError("E_SERVERS_UNREADABLE", `${SERVER_OPERATOR_ROUTES_FILE()} must map server ids to { operatorSshHost: <alias> }`);
152
+ for (const [id, entry] of Object.entries(routes)) {
153
+ if (!ID_RE.test(id) || !entry || typeof entry !== "object" || Array.isArray(entry) || Object.keys(entry).length !== 1 || !Object.hasOwn(entry, "operatorSshHost")) throw serverError("E_SERVER_INVALID", `${SERVER_OPERATOR_ROUTES_FILE()}: expected a server id and { operatorSshHost: <alias> }`);
154
+ validateOperatorSshHost(entry.operatorSshHost);
155
+ }
156
+ }
157
+
134
158
  export function writeServers(servers) {
135
159
  const file = SERVERS_FILE();
136
160
  // A registration whose target changes (server add --replace) is probed afresh.
@@ -144,15 +168,24 @@ export function writeServers(servers) {
144
168
  }
145
169
 
146
170
  /** Every read-modify-write of the registry: under one short lock, over the file as it is NOW (never a
147
- * copy read before a network call), written only when `change` altered it. `change(servers)`
148
- * mutates its argument and returns what the caller needs. */
149
- export function updateServers(change) {
171
+ * copy read before a network call), written only when `change` altered it. `change(servers, routes)`
172
+ * mutates its arguments and returns what the caller needs. With `operatorRoutes`, the sidecar is
173
+ * read and written under this same lock; agent-only updates never need to read it. */
174
+ export function updateServers(change, { operatorRoutes = false } = {}) {
150
175
  const lock = join(OATS_HOME_DIR(), "servers.lock");
151
176
  return withDirLock(lock, "the server registry", () => {
152
177
  const servers = readServers();
153
- const before = JSON.stringify(servers);
154
- const out = change(servers);
155
- if (JSON.stringify(servers) !== before) writeServers(servers);
178
+ const routes = operatorRoutes ? readServerOperatorRoutes() : undefined;
179
+ const before = structuredClone(servers);
180
+ const routesBefore = JSON.stringify(routes);
181
+ const out = change(servers, routes);
182
+ if (routes) validateOperatorRoutes(routes);
183
+ // Key ordering alone must not rewrite the legacy registry when only an operator route changes.
184
+ if (!isDeepStrictEqual(servers, before)) writeServers(servers);
185
+ if (JSON.stringify(routes) !== routesBefore) {
186
+ mkdirSync(OATS_HOME_DIR(), { recursive: true });
187
+ writeFileSync(SERVER_OPERATOR_ROUTES_FILE(), JSON.stringify(routes, null, 2) + "\n", { mode: 0o600 });
188
+ }
156
189
  return out;
157
190
  }, { retryMs: 5000, busy: (why) => serverError("E_SERVERS_BUSY", `the server registry is locked (${why}); if no oats process is changing it, remove ${lock} and retry; nothing was changed`) });
158
191
  }
@@ -160,13 +193,15 @@ export function updateServers(change) {
160
193
  /** Record the workspace key a host reported for registration `id`, only if the registration is still
161
194
  * the one that was asked (same host, workspace, oats path and PATH), so a registration changed or
162
195
  * removed meanwhile is never overwritten or brought back. → "recorded" | "same" | "changed" |
163
- * { mismatch: <the recorded key> } (a recorded key is never rewritten). */
164
- export function learnWorkspaceKey(id, asked, reported) {
196
+ * { mismatch: <the recorded key> }. `replace` is the explicit server add --replace remedy: a
197
+ * preserved key may be replaced only while it is still the key this request observed. */
198
+ export function learnWorkspaceKey(id, asked, reported, { replace = false } = {}) {
165
199
  return updateServers((servers) => {
166
200
  const current = servers[id];
167
201
  if (!current || JSON.stringify(targetOf(current)) !== JSON.stringify(targetOf(asked))) return "changed";
168
202
  if (sameRepo(current.workspaceKey, reported)) return "same";
169
- if (current.workspaceKey) return { mismatch: current.workspaceKey };
203
+ if (replace && current.workspaceKey !== asked.workspaceKey) return "changed";
204
+ if (current.workspaceKey && !replace) return { mismatch: current.workspaceKey };
170
205
  current.workspaceKey = reported;
171
206
  return "recorded";
172
207
  });
@@ -193,7 +228,7 @@ export function validateServer(id, s) {
193
228
  // The canonical key of the workspace the host deployment realizes, as its own `status --json` reported it.
194
229
  if (s.workspaceKey !== undefined && (typeof s.workspaceKey !== "string" || !WORKSPACE_KEY_RE.test(s.workspaceKey))) throw serverError("E_SERVER_INVALID", `server ${id}: workspaceKey must be a canonical workspace key (as the host's oats status --json reports it)`);
195
230
  for (const k of Object.keys(s)) {
196
- if (!["label", "sshHost", "workspace", "oatsPath", "path", "workspaceKey"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path, workspaceKey and nothing else — never keys or passwords)`);
231
+ if (!["label", "sshHost", "workspace", "oatsPath", "path", "workspaceKey"].includes(k)) throw serverError("E_SERVER_INVALID", `server ${id}: unknown field ${JSON.stringify(k)} (a registration holds label, sshHost, workspace, oatsPath, path, workspaceKey and nothing else — never keys or passwords; operator routes belong in server-operator-routes.json)`);
197
232
  }
198
233
  return true;
199
234
  }
@@ -220,9 +255,8 @@ export function workspaceMismatch(id, server, reported) {
220
255
 
221
256
  export function getServer(id) {
222
257
  const servers = readServers();
223
- const s = servers[id];
224
- if (!s) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(id)} (oats server list)`);
225
- return { id, ...s };
258
+ if (!Object.hasOwn(servers, id)) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(id)} (oats server list)`);
259
+ return { id, ...servers[id] };
226
260
  }
227
261
 
228
262
  // ------------------------------------------------------------------ quoting
@@ -284,6 +318,13 @@ function sshLineArgv(target, cmd, { control = false } = {}) {
284
318
  return ["ssh", ...SSH_OPTS, ...(control && !controlPathProblem() ? controlOpts() : NO_CONTROL_OPTS), "--", target.sshHost, cmd];
285
319
  }
286
320
 
321
+ /** The forced-command operator key must never reuse the agent route's authenticated master.
322
+ * Only receiver command words belong here; credential bytes go exclusively on stdin. */
323
+ export function operatorSshArgv(alias, words) {
324
+ validateOperatorSshHost(alias);
325
+ return ["ssh", ...SSH_OPTS, ...NO_CONTROL_OPTS, "--", alias, ...words.map(remoteQuote)];
326
+ }
327
+
287
328
  // ------------------------------------------------------------------ running
288
329
 
289
330
  /** Parse the remote kernel's JSON envelope; anything else on stdout is a
@@ -1442,15 +1483,17 @@ function relayedFailure(envelope, what) {
1442
1483
 
1443
1484
  /**
1444
1485
  * options: { id, sshHost, workspaceRef, dir (absolute, or ~/… resolved by the host), oatsPath?, path?,
1445
- * label?, installOats?, replace?, localVersion (this kernel's: the version installed) }
1486
+ * label?, operatorSshHost?, noOperatorSsh?, installOats?, replace?, localVersion (this kernel's: the version installed) }
1446
1487
  * io: { execFileSync, now, readinessBudgetMs } (the transport and clock; tests inject them).
1447
1488
  * → { id, ready, registration, steps, human }; a failed step throws its code with
1448
1489
  * details { ...the step's details, steps }.
1449
1490
  */
1450
1491
  export function connectServer(options, io = {}) {
1451
- const { id, sshHost, workspaceRef, dir, oatsPath, path, label, installOats = false, replace = false, localVersion } = options;
1492
+ const { id, sshHost, workspaceRef, dir, oatsPath, path, label, operatorSshHost, noOperatorSsh = false, installOats = false, replace = false, localVersion } = options;
1452
1493
  const now = io.now || Date.now;
1453
1494
  validateServer(id, { sshHost, workspace: "/", ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}) });
1495
+ if (operatorSshHost !== undefined) validateOperatorSshHost(operatorSshHost);
1496
+ if (operatorSshHost !== undefined && noOperatorSsh) throw serverError("E_BAD_ARGS", "choose --operator-ssh or --no-operator-ssh, not both");
1454
1497
  if (typeof dir !== "string" || !(dir === "~" || dir.startsWith("~/") || dir.startsWith("/"))) throw serverError("E_BAD_ARGS", `--dir must be an absolute path or ~/… on the host (got ${JSON.stringify(dir)})`);
1455
1498
  io = { ...io, serverId: id, input: undefined };
1456
1499
  const target = { sshHost, workspace: dir, oatsPath: oatsPath || "oats", ...(path ? { path } : {}) };
@@ -1551,10 +1594,18 @@ export function connectServer(options, io = {}) {
1551
1594
 
1552
1595
  // One guarded update of the registry as it is now. The requested id comes first: an id registered for
1553
1596
  // another target is refused (or replaced), never quietly answered by a twin that serves this target.
1554
- run("register", () => updateServers((servers) => {
1597
+ run("register", () => updateServers((servers, routes) => {
1555
1598
  const abs = check.dir;
1556
1599
  const given = { ...(oatsPath ? { oatsPath } : {}), ...(path ? { path } : {}), ...(label ? { label } : {}) };
1557
1600
  const entry = { sshHost, workspace: abs, ...found, ...given, workspaceKey: reportedKey };
1601
+ const operatorAt = (regId) => Object.hasOwn(routes, regId) ? routes[regId] : undefined;
1602
+ const operatorChange = (regId) => {
1603
+ const before = operatorAt(regId)?.operatorSshHost;
1604
+ if (operatorSshHost !== undefined) routes[regId] = { operatorSshHost };
1605
+ else if (noOperatorSsh) delete routes[regId];
1606
+ return before !== operatorAt(regId)?.operatorSshHost;
1607
+ };
1608
+ const joined = (regId) => ({ ...servers[regId], ...operatorAt(regId) });
1558
1609
  const sameTarget = (s) => s.sshHost === sshHost && s.workspace === abs;
1559
1610
  /** A registration of this very target: its key confirmed, or recorded; never contradicted. What
1560
1611
  * this run found on the host fills only what it lacks. */
@@ -1562,30 +1613,34 @@ export function connectServer(options, io = {}) {
1562
1613
  const existing = servers[regId];
1563
1614
  if (existing.workspaceKey && !sameRepo(existing.workspaceKey, reportedKey)) throw workspaceMismatch(regId, existing, reportedKey);
1564
1615
  registeredAs = regId;
1565
- registration = existing;
1566
1616
  const filled = Object.keys(found).filter((k) => existing[k] === undefined || existing[k] === null).sort();
1567
1617
  for (const k of filled) existing[k] = found[k];
1568
1618
  const keyed = !existing.workspaceKey;
1569
1619
  if (keyed) existing.workspaceKey = reportedKey;
1570
- if (!filled.length && !keyed) return { status: "ok", ...(detail ? { detail } : {}) };
1571
- return { status: "done", detail: [detail, filled.length ? `recorded ${filled.join(", ")}` : null, keyed ? `recorded workspace ${reportedKey}` : null].filter(Boolean).join("; ") };
1620
+ const operatorDiffers = operatorSshHost !== undefined ? operatorSshHost !== operatorAt(regId)?.operatorSshHost : noOperatorSsh && operatorAt(regId) !== undefined;
1621
+ if (!replace && operatorDiffers) detail = [detail, "operator route differs from the registration and was not changed (--replace rewrites it)"].filter(Boolean).join("; ");
1622
+ const operatorChanged = replace && operatorChange(regId);
1623
+ registration = joined(regId);
1624
+ if (!filled.length && !keyed && !operatorChanged) return { status: "ok", ...(detail ? { detail } : {}) };
1625
+ return { status: "done", detail: [detail, filled.length ? `recorded ${filled.join(", ")}` : null, keyed ? `recorded workspace ${reportedKey}` : null, operatorChanged ? "updated operator route" : null].filter(Boolean).join("; ") };
1572
1626
  };
1573
- const mine = servers[id];
1627
+ const mine = Object.hasOwn(servers, id) ? servers[id] : undefined;
1574
1628
  if (mine && sameTarget(mine)) {
1575
1629
  // A value given differs; one only found here differs only under --replace.
1576
1630
  const differ = ["oatsPath", "path", "label"].filter((k) => entry[k] !== undefined && entry[k] !== mine[k] && (Object.hasOwn(given, k) || replace));
1577
1631
  if (!differ.length || !replace) return keep(id, differ.length ? `${differ.join(", ")} differ from the registration and were not changed (--replace rewrites it)` : undefined);
1578
1632
  if (mine.workspaceKey && !sameRepo(mine.workspaceKey, reportedKey)) throw workspaceMismatch(id, mine, reportedKey);
1579
- servers[id] = entry; registration = entry;
1633
+ servers[id] = entry; operatorChange(id); registration = joined(id);
1580
1634
  return { status: "done", detail: `updated ${differ.join(", ")}` };
1581
1635
  }
1582
1636
  if (mine && !replace) throw Object.assign(serverError("E_SERVER_EXISTS", `server ${id} is already registered for ${mine.sshHost}:${mine.workspace} (pass --replace to point it at ${sshHost}:${abs}; instances spawned through it keep their saved routes)`), { details: { registered: { sshHost: mine.sshHost, workspace: mine.workspace } } });
1583
1637
  const twin = Object.keys(servers).find((other) => other !== id && sameTarget(servers[other]));
1584
1638
  if (twin && !mine) return keep(twin, `${sshHost}:${abs} is already registered as ${twin}; not registered again`);
1585
1639
  validateServer(id, entry);
1586
- servers[id] = entry; registration = entry;
1640
+ if (!mine) delete routes[id];
1641
+ servers[id] = entry; operatorChange(id); registration = joined(id);
1587
1642
  return { status: "done", detail: [mine ? `replaced ${mine.sshHost}:${mine.workspace}` : `registered ${id}`, twin ? `${sshHost}:${abs} is also registered as ${twin}` : null].filter(Boolean).join("; ") };
1588
- }));
1643
+ }, { operatorRoutes: true }));
1589
1644
 
1590
1645
  // Every soul the host deployment lists (disabled ones skipped), one routed readiness each, within one
1591
1646
  // budget; each failing or unknown required item is a human line, said once for the souls sharing it.
@@ -15,9 +15,11 @@
15
15
  * - Each home starts as a child process of this kernel (`session start --resume --home <home>
16
16
  * --json`, its cwd the home's deployment), so each start resolves its own deployment's scope; at
17
17
  * most RESUME_CONCURRENCY at once. A per-home failure is a row, never the sweep's failure.
18
- * - One sweep per machine: a mkdir lock under OATS_HOME_DIR (default ~/.oats) `session-resume/`,
19
- * holding its pid and boot id; a lock whose pid is gone, or taken in another boot, is stale and
20
- * taken over. A second sweep answers E_RESUME_BUSY.
18
+ * - One sweep per machine: the lock `session-resume/lock` under OATS_HOME_DIR (default ~/.oats),
19
+ * a claim (lib/claim.mjs, through lib/dir-lock.mjs) that names its holder by pid, process start
20
+ * and boot id; a lock whose holder is gone, or that was taken in another boot, is taken over at
21
+ * once. A second sweep answers E_RESUME_BUSY; a lock that needs a person, E_RESUME_LOCK_STUCK,
22
+ * which `oats doctor` reports too (acquireResumeLock, resumeLockProblem).
21
23
  * - No retry storm. A loss the sweep answered is judged (above) and not started again, whatever the
22
24
  * boot; one note per boot (`note.json`) backs that: a refused resume is noted, and a later sweep
23
25
  * in the same boot reports it again (`refused-this-boot`) without starting it, also when its
@@ -31,14 +33,15 @@
31
33
  * The lock and the note are kernel-private, not a contract. `plan` predicts from the note, starting
32
34
  * nothing, taking no lock and writing no note. */
33
35
  import { execFile } from "node:child_process";
34
- import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
36
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
35
37
  import { join, resolve } from "node:path";
36
38
  import { oatsError } from "./errors.mjs";
37
39
  import { deploymentState, readDeploymentsDocument } from "./deployments.mjs";
38
- import { homeClaimHolder, listInstances, missingLaunchEnvRefs, owedRetireSaid, resumeConversation } from "./core.mjs";
39
- import { checkStartEnv, fromEnvNames, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning } from "./start-env.mjs";
40
+ import { acquireDirLock, dirLockHeld } from "./dir-lock.mjs";
41
+ import { homeClaimHolder, listInstances, launchEnvRefs, missingLaunchEnvRefs, owedRetireSaid, resumeConversation } from "./core.mjs";
42
+ import { checkStartEnv, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning } from "./start-env.mjs";
40
43
  import { FRESH_REASON, NOT_SWEPT, OUTCOME, RESUME_WAITING, ROW_REASON, SESSION_END } from "./session-resume-contract.mjs";
41
- import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir } from "./session-seen.mjs";
44
+ import { bootId, homeKey, judgeLosses, readSeen, resumeEligible, resumeStateDir, takenInAnotherBoot } from "./session-seen.mjs";
42
45
  import { isAgentScopeWarning } from "./tmux-server-scope.mjs";
43
46
 
44
47
  export { bootId, resumeStateDir };
@@ -48,56 +51,67 @@ export const RESUME_SCHEMA = 1;
48
51
  export const RESUME_CONCURRENCY = 4;
49
52
  /** At most this many sweep starts of one home in one boot. */
50
53
  export const RESUME_LIMIT = 3;
51
- /** An acquirer's lock without an owner record yet is its own for this long (the gap between mkdir and
52
- * the owner's write); older, it is a crashed acquirer's. */
53
- const OWNERLESS_GRACE_MS = 60_000;
54
-
55
- const lockDir = () => join(resumeStateDir(), "lock");
54
+ const lockPath = () => join(resumeStateDir(), "lock");
56
55
  const notePath = () => join(resumeStateDir(), "note.json");
57
56
 
58
- function pidAlive(pid) {
59
- if (!Number.isSafeInteger(pid) || pid < 1) return false;
60
- try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
61
- }
62
57
  const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } };
63
58
 
64
- /** Take the machine's resume lock → its release function. Busy: E_RESUME_BUSY. A lock whose owner's
65
- * pid is gone, whose owner was recorded in another boot, or that has had no owner for
66
- * OWNERLESS_GRACE_MS is stale: it is taken over under a second mkdir (`lock.takeover`), so two
67
- * sweeps that both find it stale cannot both take it. */
68
- export function acquireResumeLock({ boot = bootId(), now = () => Date.now() } = {}) {
69
- const dir = lockDir(), takeover = `${dir}.takeover`;
59
+ /** What to do about a sweep's lock `path` that needs a person, by what was found (lib/dir-lock.mjs
60
+ * `found`). A directory is the lock of a kernel that locked with one: nothing here tells whether
61
+ * that kernel's sweep runs, so it is the operator who removes it. A record that cannot be read,
62
+ * or whose holder cannot be told to run, is removed once a person has seen that no sweep runs. A
63
+ * gone holder's record is removed without that. Where nothing is in the way (the lock was taken
64
+ * again each time, or this process cannot read its own start) there is nothing to remove. */
65
+ const STUCK_REMEDY = {
66
+ directory: (path) => `once no earlier oats is running on this machine, remove the directory ${path} and run it again`,
67
+ "cannot-take-over": (path) => `remove ${path} and run it again`,
68
+ "held-again": () => "run it again",
69
+ "own-start-unreadable": (path) => `run it again; nothing at ${path} is to be removed`,
70
+ };
71
+ const removeOnceNoSweepRuns = (path) => `if no oats session resume is running on this machine, remove ${path} and run it again`;
72
+ /** A sweep's lock `path` that needs a person, found as lib/dir-lock.mjs says it (`why`, `found`) →
73
+ * what is said of it and what to do. Exported for its test. */
74
+ export function resumeLockStuck(path, why, found) {
75
+ return {
76
+ lock: path, found,
77
+ said: `the session resume lock ${path} cannot be taken (${why})`,
78
+ remedy: (STUCK_REMEDY[found] ?? removeOnceNoSweepRuns)(path),
79
+ };
80
+ }
81
+
82
+ /** Take the machine's resume lock → its release function. The lock is a claim (lib/dir-lock.mjs
83
+ * acquireDirLock) whose record also names the boot it was taken in.
84
+ * - A sweep that runs holds it: E_RESUME_BUSY, at once.
85
+ * - A holder that is gone (exited, killed, its pid another process's) is taken over at once. So
86
+ * is one that took the lock in another boot (takenInAnotherBoot).
87
+ * - A lock that needs a person is E_RESUME_LOCK_STUCK, with what was found and what to do, its
88
+ * `details` `{ lock, found }` (`found`: lib/dir-lock.mjs), and is left as it is: a holder
89
+ * whose liveness cannot be read, a record that does not parse, a gone holder's record that
90
+ * cannot be taken over, a lock taken again each time it was found free, this process's own
91
+ * start unreadable, and a directory at the lock's path, the lock of an earlier kernel, which
92
+ * is never judged and never removed. */
93
+ export function acquireResumeLock({ boot = bootId() } = {}) {
94
+ const path = lockPath();
70
95
  mkdirSync(resumeStateDir(), { recursive: true, mode: 0o700 });
71
- const busy = (why) => oatsError("E_RESUME_BUSY", `another session resume on this machine holds ${dir} (${why}); nothing was started`);
72
- const stale = () => {
73
- const owner = readJson(join(dir, "owner.json"));
74
- if (!owner) { try { return now() - statSync(dir).mtimeMs > OWNERLESS_GRACE_MS ? "no owner" : null; } catch { return "gone"; } }
75
- if (boot && owner.bootId && owner.bootId !== boot) return `taken in another boot by pid ${owner.pid}`;
76
- return pidAlive(owner.pid) ? null : `its owner pid ${owner.pid} is gone`;
96
+ const busy = (why, { found }) => {
97
+ if (found === "running") return oatsError("E_RESUME_BUSY", `another session resume on this machine holds ${path} (${why}); nothing was started`);
98
+ const stuck = resumeLockStuck(path, why, found);
99
+ return Object.assign(oatsError("E_RESUME_LOCK_STUCK", `${stuck.said}; ${stuck.remedy}; nothing was started`), { details: { lock: path, found } });
77
100
  };
78
- const take = () => { mkdirSync(dir); writeFileSync(join(dir, "owner.json"), JSON.stringify({ pid: process.pid, bootId: boot, at: new Date(now()).toISOString() }) + "\n", { mode: 0o600 }); };
79
- try { take(); }
80
- catch (e) {
81
- if (e.code !== "EEXIST") throw e;
82
- if (!stale()) { const owner = readJson(join(dir, "owner.json")); throw busy(owner ? `pid ${owner.pid} holds it` : "its owner is not recorded yet"); }
83
- try { mkdirSync(takeover); }
84
- catch (t) {
85
- if (t.code !== "EEXIST") throw t;
86
- // A takeover that crashed leaves its directory: after the grace it is gone for good.
87
- let old = false; try { old = now() - statSync(takeover).mtimeMs > OWNERLESS_GRACE_MS; } catch { /* removed meanwhile */ }
88
- if (!old) throw busy("another sweep is taking over a stale lock");
89
- rmSync(takeover, { recursive: true, force: true });
90
- try { mkdirSync(takeover); } catch { throw busy("another sweep is taking over a stale lock"); }
91
- }
92
- try {
93
- // Read again under the takeover: another sweep may have taken it meanwhile.
94
- if (existsSync(dir) && !stale()) throw busy("another sweep took it over");
95
- const aside = `${dir}.stale-${process.pid}-${now()}`;
96
- try { renameSync(dir, aside); rmSync(aside, { recursive: true, force: true }); } catch (r) { if (r.code !== "ENOENT") throw r; }
97
- take();
98
- } finally { rmSync(takeover, { recursive: true, force: true }); }
99
- }
100
- return () => { try { if (readJson(join(dir, "owner.json"))?.pid === process.pid) rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } };
101
+ return acquireDirLock(path, { bootId: boot }, { busy, holderGone: takenInAnotherBoot(boot) });
102
+ }
103
+
104
+ export const RESUME_LOCK_STUCK = "resume-lock-stuck";
105
+ /** `oats doctor`'s `resume-lock-stuck` problem: the machine's resume lock when it needs a person
106
+ * → `{ code, message, remedy }`, or null. The lock is read where a sweep would take it
107
+ * (lib/dir-lock.mjs dirLockHeld, with the same boot rule), and nothing is taken or changed. Every
108
+ * state acquireResumeLock answers E_RESUME_LOCK_STUCK for a lock it finds is one; a free lock, a
109
+ * sweep that runs and a lock a gone sweep left, which the next sweep takes over, are not. */
110
+ export function resumeLockProblem({ boot = bootId() } = {}) {
111
+ const path = lockPath(), held = dirLockHeld(path, { holderGone: takenInAnotherBoot(boot) });
112
+ if (!held || held.found === "running") return null;
113
+ const stuck = resumeLockStuck(path, held.why, held.found);
114
+ return { code: RESUME_LOCK_STUCK, message: `${stuck.said}: oats session resume starts nothing on this machine while it is there`, remedy: stuck.remedy };
101
115
  }
102
116
 
103
117
  /** This boot's note: `{ bootId, refused: [{ home, startId, code, message, at }], resumes: { <home>: n } }`,
@@ -329,8 +343,9 @@ function predicted(row, env) {
329
343
  const refused = (code, message) => ({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED, code, message });
330
344
  if (!(row.launch && typeof row.launch === "object")) return refused("E_LAUNCH_LEGACY", `${row.instance} records no launch recipe (an earlier kernel spawned it): re-spawn it from the deployment`);
331
345
  const missing = missingLaunchEnvRefs(row.launch.env, env);
332
- if (missing.length) return refused("E_LAUNCH_ENV_MISSING", launchEnvMissingMessage(missing));
333
- const fit = checkStartEnv(row.home, row.startId ?? null, fromEnvNames(row.launch.env), env);
346
+ if (missing.length) return refused("E_LAUNCH_ENV_MISSING", launchEnvMissingMessage(missing, row.launch.harness));
347
+ const refs = launchEnvRefs(row.launch, env);
348
+ const fit = checkStartEnv(row.home, row.startId ?? null, refs.map((r) => r.source), Object.fromEntries(refs.map((r) => [r.source, r.value])));
334
349
  if (fit.changed) return refused("E_LAUNCH_ENV_CHANGED", launchEnvChangedMessage(fit.changed));
335
350
  const extra = fit.unverified ? { warnings: [launchEnvUnverifiedWarning(row.instance)] } : {};
336
351
  const found = resumeConversation(row.home, row);
@@ -19,9 +19,10 @@
19
19
  * Dependency-free. */
20
20
  import { execFileSync } from "node:child_process";
21
21
  import { createHash, randomBytes } from "node:crypto";
22
- import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
22
+ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from "node:fs";
23
23
  import { homedir } from "node:os";
24
24
  import { dirname, join, resolve } from "node:path";
25
+ import { systemTool } from "./system-tools.mjs";
25
26
 
26
27
  /** A loss first seen this long ago or more is not resumed. */
27
28
  export const FIRST_SEEN_MAX_MS = 24 * 60 * 60_000;
@@ -34,11 +35,53 @@ const oatsHomeDir = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
34
35
  /** The kernel-private directory of the sweep's lock, its per-boot note and this record. */
35
36
  export const resumeStateDir = () => join(oatsHomeDir(), "session-resume");
36
37
 
37
- /** This boot's identity, or null where the kernel cannot read one: Linux's boot id, macOS's boot
38
- * time (`sysctl -n kern.boottime`, its `sec`/`usec`). */
39
- export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), sysctl = () => execFileSync("sysctl", ["-n", "kern.boottime"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] }) } = {}) {
38
+ /** What says this process runs in a container: a file each runtime puts in its containers, or the
39
+ * variable Kubernetes sets in every pod. Docker writes `/.dockerenv`, Podman `/run/.containerenv`. */
40
+ const CONTAINER_FILES = ["/.dockerenv", "/run/.containerenv"];
41
+ const inContainer = (exists, env) => CONTAINER_FILES.some((file) => exists(file)) || Boolean(env.KUBERNETES_SERVICE_HOST);
42
+
43
+ /** When PID 1 started, as this process sees PID 1: field 22 of `/proc/1/stat`, in clock ticks after
44
+ * the kernel's boot, as the digits the kernel printed; null when the file cannot be read or does
45
+ * not hold it. The fields are counted after the last ")": the name (field 2) may hold spaces and
46
+ * parentheses. */
47
+ function initStart(read) {
48
+ try {
49
+ const stat = read("/proc/1/stat"), named = stat.lastIndexOf(")");
50
+ const start = named < 0 ? undefined : stat.slice(named + 1).trim().split(/\s+/)[19];
51
+ return typeof start === "string" && /^\d+$/.test(start) ? start : null;
52
+ } catch { return null; }
53
+ }
54
+
55
+ /** macOS's boot time, from the system's sysctl (systemTool), never one the caller's PATH names: a
56
+ * PATH without /usr/sbin, or with another sysctl first, must not change or lose the boot id. */
57
+ function systemSysctl() {
58
+ const tool = systemTool("sysctl");
59
+ if (!tool.file) throw new Error(tool.reason);
60
+ return execFileSync(tool.file, ["-n", "kern.boottime"], { encoding: "utf8", timeout: 5000, stdio: ["ignore", "pipe", "ignore"] });
61
+ }
62
+ /** This boot's identity, or null where the kernel cannot read one. A boot is what ends every
63
+ * process the kernel may have recorded: the sessions, their terminal server, a sweep.
64
+ * - macOS: the boot time (`sysctl -n kern.boottime`, its `sec`/`usec`).
65
+ * - Linux: the kernel's boot id (`/proc/sys/kernel/random/boot_id`).
66
+ * - Linux in a container (inContainer): `<boot id>:<PID 1's start>`. A container shares its
67
+ * host's kernel and so its boot id, which outlives a stop and start of the container; its PID 1
68
+ * does not. PID 1 starts once per run of the container and ends every process of the run when
69
+ * it ends, so its start is the same for every process of one run and another in the next; the
70
+ * boot id keeps a start apart from the same number of ticks after another kernel boot. When
71
+ * PID 1's start cannot be read there, the boot id alone: the sweep then counts a home's starts
72
+ * across the runs and applies the in-boot clause across them, so it starts less, never more.
73
+ * PID 1's start is read only in a container. A process in a PID namespace of its own on a host (a
74
+ * command a harness runs in a sandbox) reads that namespace's PID 1, which is not the machine's,
75
+ * and it is on the host's boot all the same.
76
+ * Each is read from the kernel without privileges and written nowhere. */
77
+ export function bootId({ platform = process.platform, read = (p) => readFileSync(p, "utf8"), exists = existsSync, env = process.env, sysctl = systemSysctl } = {}) {
40
78
  try {
41
- if (platform === "linux") return read("/proc/sys/kernel/random/boot_id").trim() || null;
79
+ if (platform === "linux") {
80
+ const id = read("/proc/sys/kernel/random/boot_id").trim();
81
+ if (!id) return null;
82
+ const start = inContainer(exists, env) ? initStart(read) : null;
83
+ return start === null ? id : `${id}:${start}`;
84
+ }
42
85
  if (platform === "darwin") { const m = /sec = (\d+), usec = (\d+)/.exec(sysctl()); return m ? `${m[1]}.${m[2]}` : null; }
43
86
  } catch { /* unknown */ }
44
87
  return null;
@@ -46,6 +89,12 @@ export function bootId({ platform = process.platform, read = (p) => readFileSync
46
89
  let processBoot;
47
90
  /** bootId, read once per process: a process never outlives its boot. */
48
91
  export const thisBoot = () => (processBoot === undefined ? (processBoot = bootId()) : processBoot);
92
+ /** Whether the lock record `holder` (the sweep's lock, a cache write lock: lib/remote.mjs) was taken
93
+ * in another boot than `boot`: its holder is gone then, whatever its pid reads as. A boot ends
94
+ * every process, and a pid and a start counted from the boot can both come again in the next (in a
95
+ * container, a boot is one run: bootId). Without a boot id on either side the process alone is
96
+ * judged. */
97
+ export const takenInAnotherBoot = (boot) => (holder) => Boolean(boot) && typeof holder.bootId === "string" && holder.bootId !== "" && holder.bootId !== boot;
49
98
 
50
99
  const realOrResolved = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
51
100
  /** The key of `home` in a record: its real path, so a deployment reached through a symlink (an
package/lib/start-env.mjs CHANGED
@@ -1,16 +1,17 @@
1
1
  /** What a start's launch environment was (feature session-resume, #1559): the record that lets a
2
- * resume refuse to start under a `fromEnv` value that changed since the start it brings back.
2
+ * resume refuse to start under a reference value that changed since the start it brings back.
3
3
  * Kernel-private files in the home, not a contract:
4
4
  * - `.oats-start-env.key`: 32 random bytes, mode 0600, made once, at the first start that records.
5
5
  * It never leaves the home: never logged, answered or put in an event.
6
- * - `.oats-start-env.json`: `{ startId, digests: { <fromEnv source name>: <hex HMAC-SHA256(key,
6
+ * - `.oats-start-env.json`: `{ startId, digests: { <reference source (env name or file:path)>: <hex HMAC-SHA256(key,
7
7
  * value)> } }`, written whole (tmp + rename) at every start that renders a recipe, for that
8
8
  * start's id; `digests` is `{}` for a launch with no reference. A value is never written: a
9
- * `fromEnv` value may be a credential, and only its keyed one-way digest is kept.
9
+ * reference value may be a credential, and only its keyed one-way digest is kept.
10
10
  * The record is best effort: a write that fails leaves the previous record (for another start) or
11
11
  * none, which a resume reads as unverified. A retire's recovery copy of the home leaves both out
12
- * (lib/core.mjs copyRecoveryHome). Dependency-free: the start, the spawn and the sweep's
12
+ * (lib/core.mjs copyRecoveryHome). Uses only Node built-ins and kernel helpers: the start, the spawn and the sweep's
13
13
  * `--plan` read and write it through here. */
14
+ import { fileReferenceProblems, fileReferenceRemedy } from "./launch-env.mjs";
14
15
  import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
15
16
  import { readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
16
17
  import { join } from "node:path";
@@ -29,8 +30,13 @@ export function fromEnvNames(recipeEnv) {
29
30
  }
30
31
 
31
32
  /** The message of a resume refused for references that are not set (E_LAUNCH_ENV_MISSING). */
32
- export function launchEnvMissingMessage(names) {
33
- return `this home's launch references ${names.join(", ")}, not set on this host; nothing was started`;
33
+ export function launchEnvMissingMessage(names, harness) {
34
+ const files = fileReferenceProblems(names);
35
+ if (files.length) {
36
+ const variables = names.filter((name) => !name.startsWith("file:"));
37
+ return [...(variables.length ? [`launch references ${variables.join(", ")}, not set on this host`] : []), ...files, "nothing was created or started"].join("; ") + fileReferenceRemedy(names, harness);
38
+ }
39
+ return `this home's launch references ${names.join(", ")}, not set on this host; nothing was started${fileReferenceRemedy(names, harness)}`;
34
40
  }
35
41
  /** The message of a resume refused for a changed value (E_LAUNCH_ENV_CHANGED): names only, sorted. */
36
42
  export function launchEnvChangedMessage(names) {
@@ -64,7 +70,7 @@ function writeWhole(path, bytes) {
64
70
  }
65
71
 
66
72
  /** Record the launch environment of start `startId` of `home`: the digest of each of `names` (source
67
- * names, fromEnvNames) as `env` holds it. A home without a usable key gets a new one first, and its
73
+ * names, fromEnvNames or launchEnvRefs source fields) as `env` holds it. A home without a usable key gets a new one first, and its
68
74
  * old record goes before the key is replaced, so no record is ever read with a key it was not made
69
75
  * with. Never throws: → true when the record was written. */
70
76
  export function recordStartEnv(home, startId, names, env) {
@@ -5,7 +5,7 @@ import { accessSync, constants, statSync } from "node:fs";
5
5
  import { isAbsolute, join } from "node:path";
6
6
 
7
7
  /** Where a system tool is looked for, in order. */
8
- export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin"]);
8
+ export const SYSTEM_TOOL_DIRS = Object.freeze(["/usr/bin", "/bin", "/usr/sbin", "/sbin"]);
9
9
 
10
10
  /** The directories a system tool is looked for in → { dirs } | { reason }. SYSTEM_TOOL_DIRS, or for a
11
11
  * test only, OATS_TEST_SYSTEM_TOOL_DIRS: absolute directories separated by `:`. A seam with any other
package/lib/teams.mjs CHANGED
@@ -128,6 +128,9 @@ export function discoveredTeamKeys(discovery) {
128
128
 
129
129
  /** The `souls:` patterns that apply to `key`, most specific first. */
130
130
  const patternsOf = (key) => (key === "*" ? ["*"] : [key, `${key.slice(0, key.lastIndexOf("/"))}/*`, "*"]);
131
+ /** Whether the pattern `<prefix>/*` applies to at least one of `soulKeys` (each `<member|package>/<soul>`).
132
+ * The slash is compared too, so `oats.eng/*` does not match `oats.engineering/x`. */
133
+ const patternMatchesAny = (pattern, soulKeys) => { const prefix = `${pattern.slice(0, -2)}/`; return [...soulKeys].some((k) => k.startsWith(prefix)); };
131
134
 
132
135
  const unknown = (label, at) => fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared (${at}): declare it with \`oats teams add\`, or in oats-workspace.yaml teams: for a shared team`, { label, at });
133
136
  const closedMessage = (keys) => `${LOCAL_FILE} declares ${keys.join(", ")}, but oats-workspace.yaml does not allow local teams (localTeams: true): ${CLOSED_FIX}`;
@@ -204,8 +207,9 @@ const unconfiguredProblem = (model) => ({ code: "E_TEAM_UNCONFIGURED", severity:
204
207
  : `run \`oats aweb setup\` to create a team, then commit it in oats-workspace.yaml as defaultTeam (or as a soul's default in souls:)${model.localTeams ? ", or record it here with `oats teams add <label> --team <id>`" : ""}` });
205
208
  const refusalProblem = (e) => ({ code: e.code, ...e.details, severity: "failure", message: e.message,
206
209
  fix: "declare the team (`oats teams add`), or choose another default (`oats teams default`)" });
207
- const soulUnknownProblem = (key, at) => ({ code: "team-soul-unknown", severity: "warning", key, at,
208
- message: `souls: ${key} names no soul of this workspace (a pattern is "*" or <member|package>/*)`, fix: "correct the key to a soul's qualified name (oats souls lists them), or remove it" });
210
+ const soulUnknownProblem = (key, at, pattern = false) => ({ code: "team-soul-unknown", severity: "warning", key, at,
211
+ ...(pattern ? { message: `souls: ${key} is a pattern that matches no soul of this workspace`, fix: "correct the prefix to a member's or package's name (oats souls lists them), or remove the key" }
212
+ : { message: `souls: ${key} names no soul of this workspace (a pattern is "*" or <member|package>/*)`, fix: "correct the key to a soul's qualified name (oats souls lists them), or remove it" }) });
209
213
  /** local-teams-closed as a problem (oats teams, readiness, doctor): the refusal's facts, never thrown. */
210
214
  export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA", severity: "failure", condition: "local-teams-closed", path: LOCAL_FILE, keys: [...keys],
211
215
  message: closedMessage(keys), fix: CLOSED_FIX });
@@ -216,7 +220,8 @@ export const localTeamsClosedProblem = (keys) => ({ code: "E_WORKSPACE_SCHEMA",
216
220
  * With `key`: only what concerns that soul (`default` marks ITS default). Local teams the workspace does
217
221
  * not allow are the one problem either way. `messaging`: a messaging layer is active, so no default is
218
222
  * E_TEAM_UNCONFIGURED. `soulKeys` (discoveredTeamKeys; null when the souls are not known): a `souls:` key
219
- * that is neither a pattern nor one of them is `team-soul-unknown` (a typo guard, either way).
223
+ * that is not one of them, or a `<prefix>/*` pattern that matches none of them, is `team-soul-unknown` (a typo
224
+ * guard, either way); `"*"` never is.
220
225
  */
221
226
  export function teamProblems(model, { key = null, messaging = false, soulKeys = null } = {}) {
222
227
  if (model.closedKeys.length) return [localTeamsClosedProblem(model.closedKeys)];
@@ -229,7 +234,9 @@ export function teamProblems(model, { key = null, messaging = false, soulKeys =
229
234
  for (const label of labels) { const d = model.labels.get(label); if (d.team === null) problems.push(unmappedProblem(d, t)); }
230
235
  if (messaging && t.defaultTeam === null && model.localDefault === null) problems.push(unconfiguredProblem(model));
231
236
  if (soulKeys !== null) for (const k of Object.keys(model.souls).sort(byCodepoint)) {
232
- if (k !== "*" && !k.endsWith("/*") && !soulKeys.has(k)) problems.push(soulUnknownProblem(k, `${model.soulsAt}/${pointerKey(k)}`));
237
+ if (k === "*") continue;
238
+ const pattern = k.endsWith("/*");
239
+ if (pattern ? !patternMatchesAny(k, soulKeys) : !soulKeys.has(k)) problems.push(soulUnknownProblem(k, `${model.soulsAt}/${pointerKey(k)}`, pattern));
233
240
  }
234
241
  return problems;
235
242
  }
@@ -49,8 +49,9 @@ function retryFor(home, receipt) {
49
49
  return { instance, command: `oats instance upgrade ${shellWord(instance)}${receipt.undo === true ? " --undo" : ""} --plan-revision ${shellWord(receipt.planRevision)} --idempotency-key ${shellWord(receipt.idempotencyKey)}` };
50
50
  }
51
51
 
52
- /** The shared start mutex is a directory for starts and a regular file for upgrades.
53
- * A start never reclaims an upgrade file, even if its owner died during the initial write. */
52
+ /** The command that finishes the upgrade whose regular file is at the home's `.oats-start.lock`,
53
+ * or null when no regular file is there (a start makes nothing at that path). A start never
54
+ * reclaims an upgrade's file, even if its owner died during the initial write. */
54
55
  export function upgradeMutexRetry(home) {
55
56
  const path = join(home, ".oats-start.lock");
56
57
  try { if (!lstatSync(path).isFile()) return null; }
@@ -99,3 +100,13 @@ export function packageUpgradeDrift(meta, { lock } = {}) {
99
100
  locked: { version: row.current.version ?? null, commit: row.current.commit ?? null },
100
101
  }));
101
102
  }
103
+
104
+ /** The start's line for package modules an upgrade cannot move: their package is no longer locked, or no
105
+ * longer provides the capability. An upgrade keeps them; a respawn moves the home onto the lock.
106
+ * → a warning string, or null when there are none. */
107
+ export function packageRespawnWarning(meta, { lock } = {}) {
108
+ const rows = driftOf(meta, null, { lock }).filter((row) => row.from.kind === "package" && row.status === "missing");
109
+ if (!rows.length) return null;
110
+ const why = (row) => row.reason === "capability-absent" ? `package ${row.recorded.package} no longer provides it` : `package ${row.recorded.package} is no longer locked`;
111
+ return `${rows.length} package module(s) cannot move in place (${rows.map((row) => `${row.module}: ${why(row)}`).join("; ")}); an upgrade keeps them as they are, so respawn this instance to move it onto the lock`;
112
+ }