@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
@@ -780,9 +780,14 @@ function packageSoulItem(t, d) {
780
780
  const shipped = (d.packageSouls || []).filter((s) => s.package === p.id);
781
781
  const live = shipped.find((s) => s.name === p.soul);
782
782
  if (!live) {
783
+ // A home whose package is no longer locked: readiness cannot tell a deliberate drop (only a respawn moves
784
+ // the home) from an accidental unpin or a pending sync (declaring it again fixes it in place), so the
785
+ // remedy names both, the respawn first. A soul (no home) can still be pinned.
786
+ const absent = t.home ? `if the workspace dropped ${p.id} on purpose, spawn a new instance from a soul this workspace offers (oats souls lists them), then retire this one; otherwise declare ${p.id} in the workspace's packages:, then oats sync`
787
+ : `declare ${p.id} in the workspace's packages:, then oats sync`;
783
788
  return item(subject, "fail", { producer: "workspace lock", evidence,
784
789
  reason: shipped.length ? `the version of ${p.id} locked in this workspace does not ship the soul ${p.soul}` : `${p.id} is not locked in this workspace's packages:`,
785
- remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : `declare ${p.id} in the workspace's packages:, then oats sync` });
790
+ remedy: shipped.length ? `pin a release of ${p.id} that ships ${p.soul} in the workspace's packages:, then oats sync` : absent });
786
791
  }
787
792
  const integrity = (reason, remedy) => item(subject, "fail", { producer: "workspace lock", code: "E_PACKAGE_INTEGRITY", reason, evidence, remedy });
788
793
  const lockRemedy = "oats sync (a lock that was edited: remove the entry and sync again)";
@@ -180,7 +180,7 @@ export function redactLaunchCommand(command) {
180
180
  /** The recipe as answers carry it: every environment value withheld, and without `kernelBin`
181
181
  * (the home's record keeps it; human `oats status` reads it from there). */
182
182
  export function redactLaunchRecipe(recipe) {
183
- const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { fromEnv: recipe.env[n].fromEnv }]));
183
+ const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { ...recipe.env[n] }]));
184
184
  const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
185
185
  const { kernelBin: _recorded, ...answered } = recipe;
186
186
  return { ...answered, env, ...(hooks ? { hooks } : {}) };
@@ -312,27 +312,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
312
312
  const record = readHomeRecord(home);
313
313
  if (record.state === "record") records?.set(home, record.meta);
314
314
  const meta = record.state === "record" ? upgradeHomeMeta(record.meta, home) : { instance: e.name, home };
315
- // A home retained by an incomplete rollback is NOT a live instance: it
316
- // is preserved state awaiting cleanup, and must read that way.
317
- const fallback = directoryRollbackPath(home);
318
- const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
319
- let rollbackIncomplete, spawnInProgress;
320
- if (existsSync(quarantine)) {
321
- try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
322
- catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
323
- // #796: a spawn still running its worktree hooks keeps a marker that names it
324
- // (`inProgress`). While that process is verifiably alive the home is a spawn in
325
- // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
326
- // start cannot be read is not shown in progress either: on a host that never reads it, the
327
- // row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
328
- // the pid), and retire, which never takes it for gone, refuses it with the way out.
329
- if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
330
- }
331
- // A self-retire that has been requested but not completed: the home is
332
- // owed a retirement, not live work. Read-only here — completion is the
333
- // detached child's or an operator's `oats retire`, never status.
334
- const { retirePending, marker } = readRetirePending(home);
335
- const retire = retireStateOf(home, marker);
315
+ const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
336
316
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
337
317
  // A home whose record cannot be read is listed, never observed: where its session is, is in the record.
338
318
  const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
@@ -387,22 +367,6 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
387
367
 
388
368
  });
389
369
  };
390
- // Failed deferred self-retirements leave their outcome beside the home; a
391
- // successful one is evidence only and is not a problem to surface.
392
- const readRetireFailuresOf = (agentDir) => {
393
- const instancesDir = join(agentDir, "instances");
394
- if (!existsSync(instancesDir)) return [];
395
- const out = [];
396
- for (const e of readdirSync(instancesDir, { withFileTypes: true })) {
397
- const m = e.isFile() && /^\.oats-retired-(.+)\.json$/.exec(e.name);
398
- if (!m) continue;
399
- try {
400
- const r = JSON.parse(readFileSync(join(instancesDir, e.name), "utf8"));
401
- if (r.ok === false) out.push({ instance: m[1], completedAt: r.completedAt, error: r.error?.message, incomplete: r.result?.rollbackIncomplete, retry: r.retry, resultPath: join(instancesDir, e.name) });
402
- } catch { out.push({ instance: m[1], error: "unreadable result file", resultPath: join(instancesDir, e.name) }); }
403
- }
404
- return out;
405
- };
406
370
  const withFailures = (entry, agentDir) => {
407
371
  const retireFailures = readRetireFailuresOf(agentDir);
408
372
  return retireFailures.length ? { ...entry, retireFailures } : entry;
@@ -430,6 +394,84 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
430
394
  return out;
431
395
  }
432
396
 
397
+ /** What is beside and in `home` about a retire of it, as its status row reads it (listInstances,
398
+ * openRetirements): `rollbackIncomplete` (the quarantine marker), `spawnInProgress`,
399
+ * `retirePending` (the pending marker) and `retire` (retireStateOf). Each is undefined when it
400
+ * does not apply. Only read: no claim is taken, no file removed, no process signalled. */
401
+ function readRetireFacts(home) {
402
+ // A home retained by an incomplete rollback is NOT a live instance: it
403
+ // is preserved state awaiting cleanup, and must read that way.
404
+ const fallback = directoryRollbackPath(home);
405
+ const quarantine = existsSync(fallback) ? fallback : join(home, ".oats-rollback-incomplete.json");
406
+ let rollbackIncomplete, spawnInProgress;
407
+ if (existsSync(quarantine)) {
408
+ try { rollbackIncomplete = JSON.parse(readFileSync(quarantine, "utf8")); }
409
+ catch { rollbackIncomplete = { reason: "rollback incomplete" }; }
410
+ // #796: a spawn still running its worktree hooks keeps a marker that names it
411
+ // (`inProgress`). While that process is verifiably alive the home is a spawn in
412
+ // progress, not a failed one; otherwise the marker reads as the quarantine. A process whose
413
+ // start cannot be read is not shown in progress either: on a host that never reads it, the
414
+ // row would say "setting up" forever. It reads as the quarantine (its `inProgress` names
415
+ // the pid), and retire, which never takes it for gone, refuses it with the way out.
416
+ if (rollbackIncomplete?.inProgress && processLiveness(rollbackIncomplete.inProgress).state === "alive") { rollbackIncomplete = undefined; spawnInProgress = true; }
417
+ }
418
+ // A self-retire that has been requested but not completed: the home is
419
+ // owed a retirement, not live work. Read-only here — completion is the
420
+ // detached child's or an operator's `oats retire`, never status.
421
+ const { retirePending, marker } = readRetirePending(home);
422
+ const retire = retireStateOf(home, marker);
423
+ return { rollbackIncomplete, spawnInProgress, retirePending, retire };
424
+ }
425
+
426
+ /** The failed deferred self-retirements of the soul at `agentDir`: the outcome each left beside its
427
+ * home, whether the home is still there or not (a status listing's `retireFailures`). A successful
428
+ * one is evidence only and is not a problem to surface. */
429
+ function readRetireFailuresOf(agentDir) {
430
+ const instancesDir = join(agentDir, "instances");
431
+ if (!existsSync(instancesDir)) return [];
432
+ const out = [];
433
+ for (const e of readdirSync(instancesDir, { withFileTypes: true })) {
434
+ const m = e.isFile() && /^\.oats-retired-(.+)\.json$/.exec(e.name);
435
+ if (!m) continue;
436
+ try {
437
+ const r = JSON.parse(readFileSync(join(instancesDir, e.name), "utf8"));
438
+ if (r.ok === false) out.push({ instance: m[1], completedAt: r.completedAt, error: r.error?.message, incomplete: r.result?.rollbackIncomplete, retry: r.retry, resultPath: join(instancesDir, e.name) });
439
+ } catch { out.push({ instance: m[1], error: "unreadable result file", resultPath: join(instancesDir, e.name) }); }
440
+ }
441
+ return out;
442
+ }
443
+
444
+ /** The homes under `root` and what is beside each about a retire of it, read as `oats status` reads
445
+ * it and from the same souls' directories (listInstances), without its sessions, tmux or process
446
+ * scans and without recording what it saw: for `oats doctor` (lib/retire-incomplete.mjs). Only
447
+ * read. → [{ agent, dir, homes: [{ instance, home, record, rollbackIncomplete?, spawnInProgress?,
448
+ * retirePending?, retire? }], retireFailures }]: `record` is "record", "absent" or "unreadable"
449
+ * (readHomeRecord), with `recordSaid` for an unreadable one. */
450
+ export function openRetirements(root) {
451
+ const homesOf = (agentDir) => {
452
+ const instancesDir = join(agentDir, "instances");
453
+ return (existsSync(instancesDir) ? readdirSync(instancesDir, { withFileTypes: true }) : [])
454
+ .filter((e) => e.isDirectory() && !e.name.startsWith("."))
455
+ .map((e) => {
456
+ const home = join(instancesDir, e.name);
457
+ const record = readHomeRecord(home);
458
+ return { instance: e.name, home, record: record.state, ...(record.state === "unreadable" ? { recordSaid: unreadableRecordSaid(record) } : {}), kind: record.state === "record" ? record.meta.kind : undefined, ...readRetireFacts(home) };
459
+ });
460
+ };
461
+ const out = listAgents(root).map((a) => ({ agent: a.name, dir: a._dir, homes: homesOf(a._dir), retireFailures: readRetireFailuresOf(a._dir) }));
462
+ // The capability-defined agents listInstances lists, by its rule.
463
+ const seen = new Set(out.map((a) => a.agent));
464
+ for (const { name, dir } of capabilityAgentDirs(root)) {
465
+ if (seen.has(name)) continue;
466
+ const homes = homesOf(dir), retireFailures = readRetireFailuresOf(dir);
467
+ if (!homes.some((h) => h.kind === "capability") && !retireFailures.length) continue;
468
+ out.push({ agent: name, dir, homes, retireFailures });
469
+ seen.add(name);
470
+ }
471
+ for (const a of out) for (const h of a.homes) delete h.kind;
472
+ return out;
473
+ }
474
+
433
475
  // A substituted/missing home cannot hold its own receipt. This sibling fallback
434
476
  // is independent of both home bytes and the recovery storage that may have failed.
435
477
  function directoryRollbackPath(home) {
@@ -19,16 +19,16 @@
19
19
  import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
20
20
  import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
21
21
  import { loadLocal, observeWorkspace } from "./workspace.mjs";
22
- import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
22
+ import { resolveSoul, kernelCompatibility, packageRef } from "./resolve.mjs";
23
23
  import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
24
- import { launchLayers } from "./launch-preference.mjs";
24
+ import { LOCAL_FILE, launchLayers, nearestSoulKeys } from "./launch-preference.mjs";
25
25
  import { APPROVED_HOOKS, declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
26
26
  import { materialize, moduleSkills, MODULES_DIR, plannedModuleSkills, SKILLS_DIR } from "./materialize.mjs";
27
27
  import { contentDigest, fetchRemoteTree } from "./remote.mjs";
28
28
  import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
29
29
  import { tmpdir } from "node:os";
30
30
  import { randomBytes } from "node:crypto";
31
- import { readLockIfPresent, SOUL_ALIAS_SYMLINK } from "./packages.mjs";
31
+ import { readLockIfPresent, SOUL_ALIAS_SYMLINK, verifyLockedPackage } from "./packages.mjs";
32
32
  import { parseRepoRef } from "./remote.mjs";
33
33
  import { cloneRemotes, conventionCloneDir, discoverOrStandalone, err, resolveMemberClone, sameRepoKey } from "./member-clone.mjs";
34
34
  import { sameRepo } from "./repo-moves.mjs";
@@ -217,6 +217,44 @@ export function disabledEntry(local, soulEntry) {
217
217
  return list.find((d) => d === soulEntry.name || d === qualified) ?? null;
218
218
  }
219
219
 
220
+ /**
221
+ * THE function that decides which entries of oats-local.yaml souls.disabled name no soul
222
+ * (oats-project/oats#1772): every reader asks it and none computes the answer itself. Such an entry
223
+ * keeps nothing off this machine, so the soul it was meant for spawns again: it fails open.
224
+ * `local` is the oats-local.yaml value; `discovery` one read of the workspace.
225
+ * MATCHED: disabledEntry holds for at least one offered soul (soulCandidates; a soul in
226
+ * souls.disabled is still offered). Spawn's own rule, not findSoulEntry's looser one (key
227
+ * suffixes, external sources): an entry a spawn would not match is not matched.
228
+ * UNCHECKED: it matches nothing, and the source that could hold its soul was not read (soulsOffered's
229
+ * `unread`, the reasons of the souls.launch check): every entry under `all`; an entry under a
230
+ * package of `unread.packages` for that package's reason; an entry under the package of an
231
+ * offered package soul is checked whatever a member left unread; any other (a bare name,
232
+ * `<member>/<soul>`, or a prefix that is neither, which may be a member's name) under `bare`.
233
+ * UNMATCHED: every other entry, with at most three qualified names of offered souls, ranked as the
234
+ * launch check ranks (nearestSoulKeys): each is a valid entry that names one soul.
235
+ * A souls.disabled that is not a list is no entry, as disabledEntry reads it; the schema admits only
236
+ * names, so an entry that is not a string is no name and is passed over.
237
+ * → { unmatched: [{ entry, at, suggestions }], unchecked: [{ entry, at, reason }] }, in file order.
238
+ */
239
+ export function disabledEntriesUnmatched({ local, discovery }) {
240
+ const list = Array.isArray(local?.souls?.disabled) ? local.souls.disabled : [];
241
+ const unmatched = [], unchecked = [];
242
+ if (!list.length) return { unmatched, unchecked };
243
+ const offered = soulCandidates(discovery).map((c) => c.entry);
244
+ const { unread } = soulsOffered(discovery);
245
+ const names = [...new Set(offered.map(qualifiedSoulName))];
246
+ const packages = new Set(offered.filter((e) => typeof e.package === "string").map((e) => e.package));
247
+ list.forEach((entry, index) => {
248
+ if (typeof entry !== "string" || offered.some((soul) => disabledEntry({ souls: { disabled: [entry] } }, soul) !== null)) return;
249
+ const at = `${LOCAL_FILE}#/souls/disabled/${index}`;
250
+ const prefix = entry.includes("/") ? entry.slice(0, entry.lastIndexOf("/")) : null;
251
+ const reason = unread.all ?? (prefix !== null && Object.hasOwn(unread.packages, prefix) ? unread.packages[prefix] : prefix !== null && packages.has(prefix) ? null : unread.bare);
252
+ if (reason !== null) unchecked.push({ entry, at, reason });
253
+ else unmatched.push({ entry, at, suggestions: nearestSoulKeys(entry, names) });
254
+ });
255
+ return { unmatched, unchecked };
256
+ }
257
+
220
258
  /**
221
259
  * A home's LIVE teams (team model v2): the committed shared teams (the workspace host read now) and the
222
260
  * deployment's oats-local.yaml as it is now, resolved for the home's soul key (its name, or
@@ -492,6 +530,21 @@ export async function prepareInstance(contextDir, soulName, { spawn = {}, remote
492
530
  return { local, deployment, lock, discovery, soulEntry, resolution, remoteOptions, spawn, launch };
493
531
  }
494
532
 
533
+ /** Every package a prepared resolution takes a module from is the content the lock records (lib/packages.mjs
534
+ * verifyLockedPackage: the digest of the package tree at the locked commit is the lock's `integrity`), else
535
+ * E_PACKAGE_INTEGRITY. A spawn runs it on what prepareInstance returned, before its first write: the modules
536
+ * a spawn copies are parts of that tree, fetched one by one. Each package is read from the repo its manifests
537
+ * were resolved from (resolveSoul). */
538
+ export async function verifyPreparedPackages(prepared) {
539
+ const verified = new Set();
540
+ for (const { from } of prepared.resolution.modules) {
541
+ if (from.kind !== "package" || verified.has(from.package)) continue;
542
+ const entry = prepared.lock.packages[from.package];
543
+ await verifyLockedPackage(from.package, entry, packageRef(from.package, entry, null, { parseRepoRef }), prepared.remoteOptions);
544
+ verified.add(from.package);
545
+ }
546
+ }
547
+
495
548
  /** The first soul of the deployment, by name (then qualified name), not disabled here, whose
496
549
  * resolution `provides(resolution)`: each soul is prepared in turn over one discovery, and the search
497
550
  * stops at the first that does. A soul whose resolution is refused cannot provide anything and is
@@ -58,7 +58,7 @@ import {
58
58
  revisionOf,
59
59
  kernelCompatibility,
60
60
  } from "./resolve.mjs";
61
- import { readLock, writeFileAtomic } from "./packages.mjs";
61
+ import { fetchLockedPackage, readLock, writeFileAtomic } from "./packages.mjs";
62
62
  import { loadLocal, memberSoulPath } from "./workspace.mjs";
63
63
  import { copyTreeSafe, treeDisagreement } from "./tree-copy.mjs";
64
64
  import { appendEvent, readEvents } from "./instance-events.mjs";
@@ -525,22 +525,13 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
525
525
  remoteOptions: opts.remoteOptions,
526
526
  });
527
527
  const tree = join(scratch, `package-${packages.size}`);
528
- await remote.fetchRemoteTree(
528
+ await fetchLockedPackage(
529
+ pkgid,
530
+ entry,
529
531
  found.ref,
530
- entry.commit,
531
- entry.path,
532
532
  tree,
533
- { ...opts.remoteOptions, allowSymlinks: remote.OATS_ALIAS_SYMLINK },
533
+ opts.remoteOptions,
534
534
  );
535
- const digest = remote.contentDigest(tree, {
536
- allowSymlinks: remote.OATS_ALIAS_SYMLINK,
537
- });
538
- if (digest !== entry.integrity)
539
- throw fail(
540
- "E_PACKAGE_INTEGRITY",
541
- `package ${pkgid} does not match locked integrity`,
542
- { package: pkgid, expected: entry.integrity, actual: digest },
543
- );
544
535
  packages.set(pkgid, { ...found, tree });
545
536
  }
546
537
  const pkg = packages.get(pkgid),
@@ -1020,10 +1011,15 @@ function reclaimUpgradeMutex(home, name) {
1020
1011
  if (error.code === "ENOENT") return;
1021
1012
  throw error;
1022
1013
  }
1014
+ if (stat.isDirectory())
1015
+ throw fail(
1016
+ "E_SESSION_RUNNING",
1017
+ `${name}: ${path} is a start lock left by an earlier OATS; upgrade never removes it. Once no earlier oats is running, remove that directory and retry`,
1018
+ );
1023
1019
  if (!stat.isFile())
1024
1020
  throw fail(
1025
1021
  "E_SESSION_RUNNING",
1026
- `${name} has a start in progress; its directory mutex is never reclaimed by upgrade`,
1022
+ `${name}: ${path} is neither an upgrade's file nor a start lock left by an earlier OATS; upgrade never removes it. Remove it and retry`,
1027
1023
  );
1028
1024
  rmSync(path);
1029
1025
  }
@@ -1113,10 +1109,10 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1113
1109
  writeJson(path, receipt);
1114
1110
  }
1115
1111
  stopped(home, name, opts, stored?.priorMeta);
1116
- // One path, two atomic shapes: start owns a mkdir directory; upgrade owns
1117
- // an exclusive regular file. Under our lifecycle claim a prior upgrade
1118
- // cannot still run, so even an empty interrupted wx file is reclaimable.
1119
- // A directory or symlink is never reclaimed by this act.
1112
+ // The upgrade owns an exclusive regular file at this path; a start makes
1113
+ // nothing here. Under our lifecycle claim a prior upgrade cannot still run,
1114
+ // so even an empty interrupted wx file is reclaimable. A directory (an
1115
+ // earlier OATS's start lock) or a symlink is never reclaimed by this act.
1120
1116
  reclaimUpgradeMutex(home, name);
1121
1117
  const startMutex = join(home, ".oats-start.lock");
1122
1118
  let fd;
@@ -1138,7 +1134,7 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1138
1134
  if (error.code === "EEXIST")
1139
1135
  throw fail(
1140
1136
  "E_SESSION_RUNNING",
1141
- `${name} has a start in progress; wait for it to finish before upgrading`,
1137
+ `${name}: ${startMutex} appeared after the upgrade checked it: a start lock left by an earlier OATS, or a file made there between the check and the create. Once no earlier oats is running, remove it and retry`,
1142
1138
  );
1143
1139
  throw error;
1144
1140
  } finally {
@@ -0,0 +1,7 @@
1
+ #!/bin/sh
2
+ # The kernel writes only quoted exports to this private, per-start file.
3
+ # Do not enable tracing: the environment can contain credentials.
4
+ . "$1" || exit 1
5
+ /bin/rm -f -- "$1" || exit 1
6
+ shift
7
+ exec "$@"
@@ -0,0 +1,74 @@
1
+ /** Launch references stay references in recipes. Values live only on the execution host. */
2
+ import { closeSync, constants, fstatSync, openSync, readSync, readdirSync, writeFileSync, rmSync } from "node:fs";
3
+ import { TextDecoder } from "node:util";
4
+ import { fileURLToPath } from "node:url";
5
+ import { isAbsolute, join } from "node:path";
6
+ import { shellWord } from "./shell-word.mjs";
7
+
8
+ /** The same reference grammar validates declarations and recorded launch recipes. */
9
+ export function isLaunchEnvReference(value) {
10
+ return !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 1
11
+ && ((typeof value.fromEnv === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(value.fromEnv))
12
+ || (typeof value.fromFile === "string" && isAbsolute(value.fromFile) && !value.fromFile.includes("\0")));
13
+ }
14
+
15
+ export const referenceSource = (ref) => ref.fromFile !== undefined ? `file:${ref.fromFile}` : ref.fromEnv;
16
+ const FILE_MAX_BYTES = 64 * 1024;
17
+ /** Resolve a reference without ever putting its bytes in a diagnostic. */
18
+ export function readLaunchReference(ref, env) {
19
+ if (ref.fromFile === undefined) return { value: env[ref.fromEnv] };
20
+ let fd;
21
+ const tooLarge = { problem: "is larger than 64 KiB; fromFile holds a credential value, not a file's contents" };
22
+ try {
23
+ fd = openSync(ref.fromFile, constants.O_RDONLY | constants.O_NONBLOCK);
24
+ const before = fstatSync(fd);
25
+ if (!before.isFile()) return { problem: "is not a regular file" };
26
+ if (before.size > FILE_MAX_BYTES) return tooLarge;
27
+ // One extra byte detects growth during this bounded read, without ever reading a log whole.
28
+ const bytes = Buffer.alloc(FILE_MAX_BYTES + 1);
29
+ let length = 0;
30
+ while (length < bytes.length) {
31
+ const count = readSync(fd, bytes, length, bytes.length - length, null);
32
+ if (!count) break;
33
+ length += count;
34
+ }
35
+ if (length > FILE_MAX_BYTES || fstatSync(fd).size > FILE_MAX_BYTES) return tooLarge;
36
+ let text;
37
+ try { text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes.subarray(0, length)); }
38
+ catch { return { problem: "is not UTF-8" }; }
39
+ return text.includes("\0") ? { problem: "contains NUL" } : { value: text.replace(/\r?\n$/, "") };
40
+ } catch (error) { return { problem: error.code === "ENOENT" ? "is missing" : "cannot be read" }; }
41
+ finally { if (fd !== undefined) closeSync(fd); }
42
+ }
43
+ export const referenceValue = (ref, env) => readLaunchReference(ref, env).value;
44
+ export function fileReferenceProblems(names) {
45
+ return names.filter((name) => name.startsWith("file:")).map((name) => {
46
+ const path = name.slice(5), { problem } = readLaunchReference({ fromFile: path }, {});
47
+ return `file reference ${path} ${problem || "is unavailable"}`;
48
+ });
49
+ }
50
+ export function fileReferenceRemedy(names, harness = "<harness>") {
51
+ return names.some((name) => name.startsWith("file:")) ? `; restore the readable credential file with oats harness token set ${harness} --server <id>, or ask the operator to provision it on this host` : "";
52
+ }
53
+
54
+ /** Private, one-use reference handoff. Never put values in tmux argv or its command string. */
55
+ export const LAUNCH_ENV_HANDOFF = /^\.oats-launch-env-[A-Za-z0-9-]+\.sh$/;
56
+ export function launchEnvHandoff(home, startId, refs) {
57
+ if (!/^[A-Za-z0-9-]+$/.test(startId)) throw new Error("invalid launch environment start id");
58
+ const current = `.oats-launch-env-${startId}.sh`;
59
+ // Starts are serialized by the home's lifecycle claim. A previous pane may have died
60
+ // before consuming its handoff; remove that plaintext before this start dispatches.
61
+ for (const name of readdirSync(home)) if (LAUNCH_ENV_HANDOFF.test(name) && name !== current) rmSync(join(home, name), { force: true });
62
+ if (!refs.length) return { wrap: (command) => command, remove: () => {} };
63
+ const file = join(home, current);
64
+ const content = refs.map((ref) => {
65
+ if (!/^OATS_LAUNCH_REF_[A-Za-z_][A-Za-z0-9_]*$/.test(ref.name) || ref.value.includes("\0")) throw new Error("invalid launch environment reference");
66
+ return `export ${ref.name}=${shellWord(ref.value)}\n`;
67
+ }).join("");
68
+ writeFileSync(file, content, { mode: 0o600, flag: "wx" });
69
+ const launcher = fileURLToPath(new URL("./launch-env-exec.sh", import.meta.url));
70
+ return {
71
+ wrap: (command) => `/bin/sh ${shellWord(launcher)} ${shellWord(file)} /bin/sh -c ${shellWord(command)}`,
72
+ remove: () => rmSync(file, { force: true }),
73
+ };
74
+ }
@@ -87,8 +87,10 @@ function editDistance(a, b, max, over = max + 1) {
87
87
  }
88
88
  const SUGGESTIONS = 3, NEAR = 2;
89
89
  /** The offered soul keys nearest to `key`, at most three: first those with its bare name (the part after
90
- * the last `/`), then those whose bare name is within two edits, by distance then by code point. */
91
- function nearestSoulKeys(key, offered) {
90
+ * the last `/`), then those whose bare name is within two edits, by distance then by code point. Any
91
+ * names of offered souls rank the same way: souls.disabled's check ranks their qualified names
92
+ * (lib/instance-resolution.mjs disabledEntriesUnmatched). */
93
+ export function nearestSoulKeys(key, offered) {
92
94
  const bare = bareName(key);
93
95
  const ranked = [];
94
96
  for (const k of offered) { const d = editDistance(bareName(k), bare, NEAR); if (d <= NEAR) ranked.push([d, k]); }
@@ -128,16 +130,21 @@ export function launchKeysUnmatched({ local, offered }) {
128
130
  return { unmatched, unchecked };
129
131
  }
130
132
 
131
- /** Why a key of souls.launch was not checked, one sentence per reason launchKeysUnmatched can give
132
- * (soulsOffered's): what `oats doctor` says after the key. */
133
- export const LAUNCH_KEY_UNCHECKED = Object.freeze({
134
- standalone: "this deployment sees a standalone view (the workspace's host could not be read), so the workspace's souls are not known",
135
- unrecorded: "the read of the workspace kept no record of the souls it could not read, so it established nothing about this key",
136
- "member-unconfirmed": "a member of the workspace is not confirmed, and the key may be a soul of it",
137
- "soul-unread": "a member's or an external soul could not be read, and the key may be that soul's",
138
- "package-unlocked": "its package is declared and not locked (oats sync)",
139
- "package-soul-unread": "a soul of its package could not be read, and the key may be that soul's",
140
- });
133
+ /** Why a name in oats-local.yaml was not checked against the souls a read offers, one sentence per
134
+ * reason soulsOffered gives, said of `noun`: what `oats doctor` says after the name. One set of reasons
135
+ * for every check that reads soulsOffered: "key" for souls.launch, "entry" for souls.disabled. */
136
+ export function uncheckedSentences(noun) {
137
+ return Object.freeze({
138
+ standalone: "this deployment sees a standalone view (the workspace's host could not be read), so the workspace's souls are not known",
139
+ unrecorded: `the read of the workspace kept no record of the souls it could not read, so it established nothing about this ${noun}`,
140
+ "member-unconfirmed": `a member of the workspace is not confirmed, and the ${noun} may be a soul of it`,
141
+ "soul-unread": `a member's or an external soul could not be read, and the ${noun} may be that soul's`,
142
+ "package-unlocked": "its package is declared and not locked (oats sync)",
143
+ "package-soul-unread": `a soul of its package could not be read, and the ${noun} may be that soul's`,
144
+ });
145
+ }
146
+ /** Why a key of souls.launch was not checked, by each reason launchKeysUnmatched can give (soulsOffered's). */
147
+ export const LAUNCH_KEY_UNCHECKED = uncheckedSentences("key");
141
148
 
142
149
  /** A key or a name from outside the kernel, as a sentence of a launch answer carries it: every character
143
150
  * the kernel never prints (lib/refused-text.mjs REFUSED_TEXT) replaced. `safeText` and not `terminalText`:
@@ -29,12 +29,18 @@ export function conventionCloneDir(deployment, key) {
29
29
  * `https://…`, `git@host:…`, `/abs/bare.git`) — to the canonical key. A key that
30
30
  * parses no way is returned as written (it can then only match literally). */
31
31
  export function canonicalCloneKey(written) {
32
+ return parsedCloneKey(written) ?? String(written).trim();
33
+ }
34
+
35
+ /** canonicalCloneKey's answer when `written` is a repository reference, or null when it parses no
36
+ * way (a member's name, `org/name`): such a string can match no remote. */
37
+ export function parsedCloneKey(written) {
32
38
  const s = String(written).trim();
33
39
  if (s.startsWith("local/")) return s; // a local key is already canonical
34
40
  for (const candidate of [s, `git:${s}`]) {
35
41
  try { return parseRepoRef(candidate).key; } catch { /* next form */ }
36
42
  }
37
- return s;
43
+ return null;
38
44
  }
39
45
 
40
46
  /** The remotes a clone carries (any remote, not only origin), each with its url parsed
package/lib/packages.mjs CHANGED
@@ -50,6 +50,7 @@ import * as defaultRemote from "./remote.mjs";
50
50
  import { manifestContractProblems } from "./capability-contract.mjs";
51
51
  import { writeFileAtomic } from "./write-file-atomic.mjs";
52
52
  import { sameRepo } from "./repo-moves.mjs";
53
+ import { PACKAGE_ID_RE } from "./package-catalog.mjs";
53
54
  export { writeFileAtomic } from "./write-file-atomic.mjs";
54
55
 
55
56
  export const LOCK_FILE = "oats-lock.json";
@@ -429,6 +430,36 @@ async function packageIntegrity(remote, remoteRef, commit, path) {
429
430
  } finally { rmSync(scratch, { recursive: true, force: true }); }
430
431
  }
431
432
 
433
+ /** The package tree of a lock entry copied to `dest` (which must not exist), only when its content is what
434
+ * the lock records: the content digest of the copy must be the entry's `integrity`, else E_PACKAGE_INTEGRITY
435
+ * { package, version, commit, expected, actual } (the copy is left for the caller to remove). `ref` is the
436
+ * repo the package is read from (lib/resolve.mjs packageRef). The one comparison of a package tree with the
437
+ * lock behind a spawn (verifyLockedPackage) and an in-place module move (lib/instance-upgrade.mjs). */
438
+ export async function fetchLockedPackage(id, entry, ref, dest, remoteOptions) {
439
+ const allowSymlinks = defaultRemote.OATS_ALIAS_SYMLINK;
440
+ await defaultRemote.fetchRemoteTree(ref, entry.commit, entry.path, dest, { ...remoteOptions, allowSymlinks });
441
+ const observed = defaultRemote.contentDigest(dest, { allowSymlinks });
442
+ if (observed !== entry.integrity) {
443
+ throw oatsError("E_PACKAGE_INTEGRITY",
444
+ `package ${id} v${entry.version}: ${entry.path} at commit ${entry.commit} digests ${observed}, and oats-lock.json records ${entry.integrity} for it — either the lock was edited (restore it: only \`oats sync\` writes it), or this computer's cached copy of the package changed (remove the remote cache: the next read fetches it again)`,
445
+ { package: id, version: entry.version, commit: entry.commit, expected: entry.integrity, actual: observed });
446
+ }
447
+ }
448
+
449
+ /** A spawn's check that a locked package is the content the lock records, before the spawn has any effect:
450
+ * fetchLockedPackage into a scratch directory, once per (repo, commit, path, integrity) and state of the
451
+ * package's cache repo on this computer (lib/remote.mjs treeVerification): a recorded verification the cache
452
+ * repo has not changed under is believed, and nothing is fetched. A cache repo that changed while its tree
453
+ * was read (the first fetch of the package's blobs) records nothing: the next spawn reads the tree again. */
454
+ export async function verifyLockedPackage(id, entry, ref, remoteOptions) {
455
+ const verification = defaultRemote.treeVerification(ref, entry.commit, entry.path, entry.integrity, remoteOptions);
456
+ if (verification.holds()) return;
457
+ const scratch = mkdtempSync(join(tmpdir(), "oats-pkg-"));
458
+ try { await fetchLockedPackage(id, entry, ref, join(scratch, "tree"), remoteOptions); }
459
+ finally { rmSync(scratch, { recursive: true, force: true }); }
460
+ verification.record();
461
+ }
462
+
432
463
  // ---------- resolvePackages ----------
433
464
 
434
465
  function assertDigest(what, value, details) {
@@ -436,6 +467,42 @@ function assertDigest(what, value, details) {
436
467
  return value;
437
468
  }
438
469
 
470
+ /** A package is locked under its own id (#1759): the manifest's `package` must equal the `packages:` key it
471
+ * is pinned under, or its souls would be named after the wrong package. A mismatch is
472
+ * E_PACKAGE_INTEGRITY { why: "package-id", manifestPackage, commit } whose message names the line to write.
473
+ * The fix line is built from displayed parts: a catalog url may carry user information (displayRepoRef
474
+ * drops it), except the `git@host:` ssh form, whose `git` user is part of the address and which a `git:`
475
+ * value accepts as written; a `git:` value carries no other user information (classifyPackageValue
476
+ * refuses it), so it is repeated as written. */
477
+ function assertManifestNamesId(id, manifest, { req, value, catalog, commit, details }) {
478
+ const named = manifest.package;
479
+ if (named === id) return;
480
+ const text = value.trim();
481
+ const ssh = req.kind === "catalog" && /^git@[^@/:]+:/.test(req.remoteRef);
482
+ const repo = req.kind !== "catalog" ? null : ssh ? req.remoteRef : defaultRemote.displayRepoRef(req.remoteRef);
483
+ const pinned = req.kind === "catalog" ? `${text} resolves to ${repo}@${req.at} (${commit.slice(0, 12)})` : `${text} resolves to ${commit.slice(0, 12)}`;
484
+ let fix = null, note = "";
485
+ if (!PACKAGE_ID_RE.test(named)) note = ", which is not a package id";
486
+ else if (req.kind === "git" || plainObject(catalogPackages(catalog)[named])) fix = text; // the catalog decides where a catalog package lives
487
+ else if (req.path !== DEFAULT_PACKAGE_PATH) note = ` (a git: pin reads ${DEFAULT_PACKAGE_PATH}/ and this package is at ${req.path}/, so no git: line can name it)`;
488
+ else fix = gitValueFor(repo, req.at);
489
+ const shown = JSON.stringify(!fix && named.length > 64 ? `${named.slice(0, 64)}…` : named);
490
+ const way = fix ? `declare ${named}: ${fix} in packages: in place of ${id}, or pin` : "pin";
491
+ const message = `packages.${id}: ${pinned}, whose ${PACKAGE_MANIFEST} names package ${shown}, not ${JSON.stringify(id)}${note}`
492
+ + ` — a package is locked under its own id: ${way} a version of ${id} whose manifest names ${id}; then run \`oats sync\``;
493
+ throw oatsError("E_PACKAGE_INTEGRITY", defaultRemote.displayDiagnosticText(message, req.kind === "catalog" && !ssh ? req.remoteRef : null, { refusal: true }),
494
+ { ...details, why: "package-id", manifestPackage: named, commit });
495
+ }
496
+
497
+ /** The `git:<repo>@<ref>` value for a displayed repo, or the placeholder when that value would not resolve
498
+ * (a withheld display, or a form a git: value cannot carry). */
499
+ function gitValueFor(repo, at) {
500
+ const composed = `git:${repo.startsWith("git:") ? repo.slice(4) : repo}@${at}`;
501
+ const c = classifyPackageValue(composed);
502
+ try { if (!c.problem) { defaultRemote.parseRepoRef(c.repo); return composed; } } catch { /* placeholder below */ }
503
+ return `git:<repo>@${at}`;
504
+ }
505
+
439
506
  /** A remote whose reads at a commit are shared for one command (feature desktop-facts): the souls and
440
507
  * capabilities listings resolve many souls over the same package manifests and skill listings, and a read at
441
508
  * an immutable commit gives the same answer every time. A failed read is not kept (it is retried). */
@@ -488,6 +555,8 @@ export function bindRemote(remote, remoteOptions) {
488
555
  * - A locked entry whose version string is unchanged but whose commit or
489
556
  * integrity moved → E_PACKAGE_INTEGRITY { id, version, locked, observed }.
490
557
  * - A value resolving to a BRANCH → E_PACKAGE_INTEGRITY { why: "branch" }: versions are immutable.
558
+ * - A manifest whose `package` is not the entry's key, fresh or already locked →
559
+ * E_PACKAGE_INTEGRITY { why: "package-id", manifestPackage, commit } (assertManifestNamesId).
491
560
  */
492
561
  export async function resolvePackages(workspace, { catalog = {}, lock = emptyLock(), remote = defaultRemote, remoteOptions } = {}) {
493
562
  if (!remote || typeof remote.observeRemote !== "function" || typeof remote.readRemoteFile !== "function") {
@@ -532,7 +601,9 @@ export async function resolvePackages(workspace, { catalog = {}, lock = emptyLoc
532
601
  // The lock's capability list must still be what the package declares at that commit —
533
602
  // spawn refuses a mismatch (E_PACKAGE_INTEGRITY why:capabilities), so sync must too, or
534
603
  // a bad list would pass every sync and fail every spawn.
535
- const { capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, old.path, details);
604
+ const { manifest, capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, old.path, details);
605
+ // A lock an older kernel wrote under another package's id is refused here too (#1759).
606
+ assertManifestNamesId(id, manifest, { req, value: requests[id], catalog, commit: obs.commit, details });
536
607
  const listed = capabilities.map((c) => c.name).sort(), locked = [...old.capabilities].sort();
537
608
  if (listed.length !== locked.length || listed.some((c, i) => c !== locked[i])) {
538
609
  throw oatsError("E_PACKAGE_INTEGRITY",
@@ -555,7 +626,8 @@ export async function resolvePackages(workspace, { catalog = {}, lock = emptyLoc
555
626
  continue;
556
627
  }
557
628
 
558
- const { capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, req.path, details);
629
+ const { manifest, capabilities, souls: soulDirs } = await readPackageManifests(remote, req.remoteRef, obs.commit, req.path, details);
630
+ assertManifestNamesId(id, manifest, { req, value: requests[id], catalog, commit: obs.commit, details });
559
631
  const integrity = assertDigest(`packages.${id} integrity`, await packageIntegrity(remote, req.remoteRef, obs.commit, req.path), details);
560
632
  const souls = await packageSoulDigests(remote, req.remoteRef, obs.commit, soulDirs, details);
561
633
  nextPackages[id] = {
package/lib/read-call.mjs CHANGED
@@ -42,6 +42,9 @@ export const READ_STATE = [
42
42
  { module: "lib/remote.mjs", binding: "liveChildren", how: "safe", why: "a registry of live git process groups, each leaving on 'close': empty once a call's session is closed, never cleared (that would lose exit reaping)" },
43
43
  { module: "lib/remote.mjs", binding: "cacheLocks", how: "safe", why: "an in-process mutex per cache repo; an entry is removed when its holder releases it" },
44
44
  { module: "lib/remote.mjs", binding: "fingerprintMemo", how: "safe", why: "the kernel code's fingerprint, install data: a process that runs a changed install exits first (the warm reader's install stamp)" },
45
+ { module: "lib/dir-lock.mjs", binding: "sections", how: "safe", why: "how many locked sections run now: a section is synchronous, so it is 0 between calls" },
46
+ { module: "lib/dir-lock.mjs", binding: "listening", how: "safe", why: "whether the lock's signal listeners are on: they hold a signal back around a section and decide no answer" },
47
+ { module: "lib/dir-lock.mjs", binding: "idle", how: "safe", why: "the pending removal of those listeners, run once the event loop turns" },
45
48
  { module: "lib/session-seen.mjs", binding: "processBoot", how: "safe", why: "the boot id: a process never outlives its boot" },
46
49
  { module: "lib/session-viewer.mjs", binding: "probed", how: "safe", why: "only an attach's preparation reads it; readSessionViewer asks tmux -V at every call" },
47
50
  { module: "lib/session-viewer.mjs", binding: "onQuit", how: "safe", why: "only an attach (attachSessionTarget) sets it" },
package/lib/reader.mjs CHANGED
@@ -17,7 +17,8 @@
17
17
  * reader exits 0.
18
18
  * - Its lifetime is the client's: stdin EOF or error, EPIPE on stdout, SIGTERM/SIGINT/SIGHUP end it. A request in
19
19
  * flight is not answered, and its read session is closed from the `exit` handler, which kills its git
20
- * children (a deployments-list lock, lib/dir-lock.mjs, exits from its own signal handler).
20
+ * children (a deployments-list lock, lib/dir-lock.mjs, raises a signal that arrived inside its
21
+ * section again once the lock is released, and this handler then ends the reader).
21
22
  * - Its stdout carries protocol lines only: anything else written there (console.log) goes to stderr, and every
22
23
  * child on the read path pipes or ignores its stdout.
23
24
  * Kernel-private, not exported from `./core`. Dependency-free. */
@@ -69,7 +70,7 @@ export async function runReader({ stamp }) {
69
70
  let inFlight = null;
70
71
  process.on("exit", () => inFlight?.closeNow());
71
72
  for (const [signal, code] of [["SIGINT", 130], ["SIGTERM", 143], ["SIGHUP", 129]]) process.on(signal, () => {
72
- // A deployments-list lock (lib/dir-lock.mjs) holds its own handler, which releases the lock and exits.
73
+ // Any other handler still listening ends the reader itself after this one.
73
74
  if (process.listenerCount(signal) === 1) end(code);
74
75
  });
75
76
  process.stdout.on("error", () => end(0)); // EPIPE: the client is gone