@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
@@ -4,8 +4,9 @@
4
4
  * invisible hiders U+200B, U+2060 and U+FEFF, and the tag characters (U+E0000-E007F).
5
5
  * Everything else is allowed, ZWJ and ZWNJ (U+200C/D, emoji sequences, Persian and Indic text)
6
6
  * and the marks LRM, RLM and ALM (U+200E/F, U+061C) included. One set for the kernel: a waiting
7
- * claim's message (lib/instance-events.mjs) refuses it, a trigger source's text
8
- * (lib/triggers.mjs) has it replaced. The Desktop keeps its own identical copy. */
7
+ * claim's message (lib/instance-events.mjs) refuses it, a warning row's message (the same
8
+ * module) and a trigger source's text (lib/triggers.mjs) have it replaced. The Desktop keeps its
9
+ * own identical copy. */
9
10
  export const REFUSED_TEXT = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
10
11
  const REFUSED_TEXT_ALL = new RegExp(REFUSED_TEXT.source, "gu");
11
12
 
package/lib/remote.mjs CHANGED
@@ -36,10 +36,12 @@
36
36
  * every budget is applied to real sizes. A server that cannot serve partial fetches
37
37
  * (no filter support; or blob wants refused, so the commit is fetched again with
38
38
  * `--refetch`) gets whole trees from then on: the cache records `oats.fetch = full`,
39
- * and the session's `notices` say so once. So does a git older than PARTIAL_FETCH_GIT
40
- * (2.45, which brought GIT_NO_LAZY_FETCH): an older git would fetch a missing blob on
41
- * its own or die, so every cache it touches fetches whole trees, and a partial cache it
42
- * finds is deleted and fetched again whole (rebuildWhole). A lost `.lock` race on the
39
+ * and the session's `notices` say so once for that repository. So does a git older than
40
+ * PARTIAL_FETCH_GIT (2.45, which brought GIT_NO_LAZY_FETCH): an older git would fetch a
41
+ * missing blob on its own or die, so every cache it touches fetches whole trees, and a
42
+ * partial cache it finds is deleted and fetched again whole (rebuildWhole). Each such
43
+ * cache records `oats.fetch = full`, but the notice names no repository and is said once
44
+ * per session (once per command, or per reader call), however many caches it starts. A lost `.lock` race on the
43
45
  * cache repo's config or objects (another process starting the same cache) is retried.
44
46
  *
45
47
  * The cache is invisible plumbing: it may be wiped at any time (a wiped cache
@@ -88,9 +90,10 @@
88
90
  * CONCURRENCY (awebai/oats#386): per-key operations on one cache repo are serialized
89
91
  * in-process (withCacheLock), and every WRITE to a cache repo (init, config, fetch, pin)
90
92
  * holds its cross-process write lock `<cacheRoot>/.locks/<repo>.lock` (withCacheWriteLock):
91
- * a live holder is waited for (bounded by a whole fetch) and never stolen from, a dead
92
- * one is reclaimed; reads take no lock. A cache repo is created whole (init into a private
93
- * directory, then rename). A git `.lock` met under the write lock belongs to an older
93
+ * a live holder is waited for (bounded by a whole fetch) and never stolen from, a gone
94
+ * one (dead, its pid another process's, or of another boot) is reclaimed; reads take no
95
+ * lock. A cache repo is created whole (init into a private directory, then rename).
96
+ * A git `.lock` met under the write lock belongs to an older
94
97
  * kernel's live write (retried briefly) or to a git that was killed: one older than the
95
98
  * longest fetch, inside the cache and a regular file, is removed (a session notice says
96
99
  * so) and the write made once more; any other is E_REMOTE_UNREADABLE { reason: "cache" }
@@ -160,6 +163,16 @@
160
163
  * keep a record each. A record is reused only
161
164
  * under `maxAge`, only when key, ref args and urlDigest all match, and never in place of
162
165
  * a live observation that failed.
166
+ *
167
+ * VERIFIED STORE (`treeVerification`; kernel-private, not a contract):
168
+ * `<cacheRoot>/.verified/<sha256([key, commit, dir, digest])>.json` records that the tree `dir` of
169
+ * (repo key, commit), read from this cache, had the content digest `digest`:
170
+ * { v, key, commit, dir, digest, entry }. `entry` is the state of the cache repo the tree was read from
171
+ * (cacheEntryState: every file under it by path, size, mode, inode, and modification and status-change times),
172
+ * so a record is believed only while every recorded field is the asked one AND the cache repo is file for
173
+ * file what it was: git reads an object without checking it against its id, so an object changed in the
174
+ * cache is answered as it is. A cache repo that reads objects from outside itself (a symlink, an alternates
175
+ * file) has no state and no record. Written atomically, last writer wins; a corrupt record is a miss.
163
176
  */
164
177
  import { execFileSync, spawn } from "node:child_process";
165
178
  import { createHash, randomBytes } from "node:crypto";
@@ -170,10 +183,13 @@ import {
170
183
  import { homedir } from "node:os";
171
184
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
172
185
  import { fileURLToPath } from "node:url";
186
+ import { holderLiveness } from "./claim.mjs";
173
187
  import { oatsError } from "./errors.mjs";
174
188
  import { REFUSED_TEXT } from "./refused-text.mjs";
175
189
  import { killGroup, signalGroup, terminateGroup, watchGroup } from "./process-group.mjs";
190
+ import { takenInAnotherBoot, thisBoot } from "./session-seen.mjs";
176
191
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
192
+ import { processStartToken } from "./worktree-hooks.mjs";
177
193
 
178
194
  export const FILE_BUDGET = 4 * 1024 * 1024; // readRemoteFile: 4 MiB per file
179
195
  export const TREE_BUDGET = 64 * 1024 * 1024; // fetchRemoteTree: 64 MiB per subtree
@@ -662,17 +678,19 @@ function readCacheWriteLock(path) {
662
678
  * Run `fn` holding the cache repo's cross-process write lock (docs: oats-kernel-expert decision
663
679
  * record-lock-liveness-tradeoff): every oats write to a cache repo — init, config, fetch, pin — happens under
664
680
  * it, so two processes never write one cache at once; reads take no lock. The lock is an exclusive-create file
665
- * holding { pid, token, startedAt }, linked into place whole. A live holder is waited for, never stolen from,
666
- * whatever its age; a dead holder's lock (or an unreadable one past UNREADABLE_LOCK_STALE_MS) is removed after
667
- * checking it is still the same file. Every pass that does not acquire falls through one deadline check and
668
- * one sleep. At the deadline: E_REMOTE_UNREADABLE { reason: "cache", stage, cacheDir, lock, holderPid }; at once
681
+ * holding { pid, token, startedAt, bootId, processStart }, linked into place whole: its holder named by pid,
682
+ * boot and start, as a claim's is (lib/claim.mjs). A live holder is waited for, never stolen from, whatever
683
+ * its age; a gone holder's lock (isStaleLock: one taken in another boot, or whose pid is gone or runs with
684
+ * another start; or an unreadable one past UNREADABLE_LOCK_STALE_MS) is removed after checking it is still the
685
+ * same file. A record that names no boot or start is its holder's by pid alone. Every pass that does not
686
+ * acquire falls through one deadline check and one sleep. At the deadline: E_REMOTE_UNREADABLE { reason: "cache", stage, cacheDir, lock, holderPid }; at once
669
687
  * when a reclaimer died holding the reclaim guard (reclaimCacheWriteLock), with details.guard.
670
688
  * `fn({ waited })`: whether another process held the lock first (what it wrote is worth checking again).
671
689
  */
672
690
  async function withCacheWriteLock(ref, dir, stage, session, fn) {
673
691
  const signal = session?.signal;
674
692
  const lock = cacheWriteLockOf(dir);
675
- const owner = { pid: process.pid, token: randomBytes(12).toString("hex"), startedAt: new Date().toISOString() };
693
+ const owner = { pid: process.pid, token: randomBytes(12).toString("hex"), startedAt: new Date().toISOString(), bootId: thisBoot(), processStart: processStartToken(process.pid) };
676
694
  const url = displayRepoRef(ref.url);
677
695
  const refuse = (message, extra = {}) => fail("E_REMOTE_UNREADABLE", `cannot write the cache of ${url} at ${dir} (cache, ${stage}): ${message}`,
678
696
  { url: ref.url, key: ref.key, reason: "cache", stage, cacheDir: dir, lock, ...extra });
@@ -706,7 +724,7 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
706
724
  }
707
725
  }
708
726
  if (Date.now() >= deadline) {
709
- throw refuse(held?.owner ? `oats process ${held.owner.pid} has been writing it since ${held.owner.startedAt} (lock ${lock}); try again once it finishes`
727
+ throw refuse(held?.owner ? `process ${held.owner.pid} has been writing it since ${held.owner.startedAt} (lock ${lock}); try again once it finishes; check whether pid ${held.owner.pid} is an oats process: once no oats process holds it, the lock ${lock} is safe to remove`
710
728
  : `its write lock ${lock} is held; it is safe to remove once no oats process is running`, held?.owner ? { holderPid: held.owner.pid } : {});
711
729
  }
712
730
  if (session?.expired()) throw budgetEnded();
@@ -721,9 +739,16 @@ async function withCacheWriteLock(ref, dir, stage, session, fn) {
721
739
  }
722
740
  }
723
741
 
724
- /** Whether a lock record (readCacheWriteLock) is provably abandoned: its owner's pid is gone, or it has no
725
- * readable owner and is older than UNREADABLE_LOCK_STALE_MS. A live owner is never stale, whatever its age. */
726
- const isStaleLock = (held) => (held.owner ? !pidAlive(held.owner.pid) : Date.now() - held.mtimeMs > UNREADABLE_LOCK_STALE_MS);
742
+ /** Whether a lock record (readCacheWriteLock) is provably abandoned: its owner is gone (ownerGone), or it has
743
+ * no readable owner and is older than UNREADABLE_LOCK_STALE_MS. A live owner is never stale, whatever its age. */
744
+ const isStaleLock = (held) => (held.owner ? ownerGone(held.owner) : Date.now() - held.mtimeMs > UNREADABLE_LOCK_STALE_MS);
745
+ /** Whether the owner a lock record names is gone. One that names its boot or start (`bootId`, `processStart`)
746
+ * is judged as a claim's holder is (lib/claim.mjs holderLiveness): gone when taken in another boot, or when
747
+ * its pid is gone, runs with another start or is a zombie; one whose start cannot be read is never gone. One
748
+ * that names neither is gone when its pid is. */
749
+ const ownerGone = (owner) => ("bootId" in owner || "processStart" in owner
750
+ ? holderLiveness(owner, { holderGone: takenInAnotherBoot(thisBoot()) }).state === "gone"
751
+ : !pidAlive(owner.pid));
727
752
  /** The same record still at `path`: the same owner token, or (no readable owner) the same file. */
728
753
  const sameLock = (now, held) => (held.owner ? now?.owner?.token === held.owner.token : now && !now.owner && now.ino === held.ino && now.mtimeMs === held.mtimeMs);
729
754
 
@@ -1373,8 +1398,8 @@ function touchParsed(file, dir, session) {
1373
1398
  /**
1374
1399
  * Bound the stores under `root` (one scan): the current fingerprint's entries, least recently used first,
1375
1400
  * down to keepEntries AND keepBytes once over maxEntries OR maxBytes; other fingerprint directories unused
1376
- * for staleFingerprintMs; observation records older than staleObservationMs; temp files a crashed writer
1377
- * left. Never throws. → { removed, entries, bytes } for the current fingerprint.
1401
+ * for staleFingerprintMs; observation records and verified-tree records older than staleObservationMs; temp
1402
+ * files a crashed writer left. Never throws. → { removed, entries, bytes } for the current fingerprint.
1378
1403
  */
1379
1404
  export function pruneStores(root, { fingerprint = kernelFingerprint(), limits = PARSED_LIMITS, now = Date.now() } = {}) {
1380
1405
  const L = { ...PARSED_LIMITS, ...limits };
@@ -1406,13 +1431,69 @@ export function pruneStores(root, { fingerprint = kernelFingerprint(), limits =
1406
1431
  if (st && now - st.mtimeMs > L.staleFingerprintMs && remove(dir, { recursive: true })) removed++;
1407
1432
  }
1408
1433
  }
1409
- for (const observed of [join(root, ".observed"), join(root, ".observed-facts")]) for (const f of list(observed)) {
1434
+ for (const observed of [join(root, ".observed"), join(root, ".observed-facts"), join(root, ".verified")]) for (const f of list(observed)) {
1410
1435
  const p = join(observed, f), st = stat(p);
1411
1436
  if (st && now - st.mtimeMs > (f.endsWith(".tmp") ? L.staleTempMs : L.staleObservationMs) && remove(p)) removed++;
1412
1437
  }
1413
1438
  return { removed, entries, bytes };
1414
1439
  }
1415
1440
 
1441
+ // ---------------------------------------------------------------------------
1442
+ // the verified store: trees whose content digest was checked, bound to the cache repo they were read from
1443
+ // ---------------------------------------------------------------------------
1444
+
1445
+ /** What the cache repo at `dir` is, without reading its content: sha256 over every file under it, in path
1446
+ * order, as (path, size, mode, inode, mtime ns, ctime ns). Adding, removing, replacing or rewriting a file
1447
+ * changes it; so does a rewrite that restores the size and the modification time (the status-change time
1448
+ * moves). → "sha256-<hex>", or null when the repo has no such state: it cannot be listed (absent, or a file
1449
+ * went while it was read: a write in progress), or what git reads there is not all under it (an entry that is
1450
+ * neither a directory nor a regular file, such as a symlink; an alternates file). */
1451
+ function cacheEntryState(dir) {
1452
+ const hash = createHash("sha256");
1453
+ const walk = (abs, rel) => {
1454
+ for (const e of readdirSync(abs, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
1455
+ const p = join(abs, e.name), r = rel ? `${rel}/${e.name}` : e.name;
1456
+ if (e.isDirectory()) { if (!walk(p, r)) return false; continue; }
1457
+ if (!e.isFile() || r === "objects/info/alternates" || r === "objects/info/http-alternates") return false;
1458
+ const st = lstatSync(p, { bigint: true });
1459
+ hash.update(`${r}\0${st.size}\0${st.mode}\0${st.ino}\0${st.mtimeNs}\0${st.ctimeNs}\0`);
1460
+ }
1461
+ return true;
1462
+ };
1463
+ try { return lstatSync(dir).isDirectory() && walk(dir, "") ? `sha256-${hash.digest("hex")}` : null; }
1464
+ catch { return null; }
1465
+ }
1466
+
1467
+ /**
1468
+ * The verified store (see the module header) for the tree `dir` of (refText's key, commit) and the content
1469
+ * digest `digest` it is expected to have. The cache repo's state is taken when this is called, before the
1470
+ * caller reads the tree. → {
1471
+ * holds() → true when a record says this tree had this digest in the cache repo as it is: every
1472
+ * recorded field is the asked one and the recorded state is the state taken;
1473
+ * record() → write the record, after the caller read the tree from the cache and found its digest to be
1474
+ * `digest`. Only when the cache repo is still in the state taken (what was read is then what
1475
+ * that state holds). → whether it was written.
1476
+ * } Starts no git process.
1477
+ */
1478
+ export function treeVerification(refText, commit, dir, digest, options = {}) {
1479
+ const ref = parseRepoRef(refText, options);
1480
+ const rel = normalizeTreePath(dir, { allowRoot: true });
1481
+ const root = cacheRootOf(options);
1482
+ const file = join(root, ".verified", `${sha256(JSON.stringify([ref.key, commit, rel, digest]))}.json`);
1483
+ const state = () => cacheEntryState(cacheDirOf(root, ref));
1484
+ const entry = state();
1485
+ return {
1486
+ holds() {
1487
+ if (entry === null) return false;
1488
+ const rec = readStoreFile(file);
1489
+ return Boolean(rec) && typeof rec === "object" && rec.v === 1 && rec.key === ref.key && rec.commit === commit && rec.dir === rel && rec.digest === digest && rec.entry === entry;
1490
+ },
1491
+ record() {
1492
+ return entry !== null && state() === entry && writeAtomicQuiet(file, JSON.stringify({ v: 1, key: ref.key, commit, dir: rel, digest, entry }));
1493
+ },
1494
+ };
1495
+ }
1496
+
1416
1497
  // ---------------------------------------------------------------------------
1417
1498
  // the observation store: successful live head observations, for --max-age
1418
1499
  // ---------------------------------------------------------------------------
@@ -1526,7 +1607,7 @@ async function ensureCommit(ref, oid, options) {
1526
1607
  const cached = peeled && !waited ? null : await asReadTimeout(repo, peelCommit(repo, oid));
1527
1608
  if (cached) return { repo, commit: remember(cached) }; // pinned AND present AND (peels to) a commit
1528
1609
  const mode = await fetchMode(repo)
1529
- ?? (keepsPartialCache(version) ? await startPartialFetches(repo, ref) : await recordFullFetches(repo, ref, olderGitNotice(version, ref)));
1610
+ ?? (keepsPartialCache(version) ? await startPartialFetches(repo, ref) : await recordOlderGitFetches(repo, ref, version));
1530
1611
  const filter = mode === "partial" ? [`--filter=${PARTIAL_FILTER}`] : ["--no-filter"];
1531
1612
  const { stderr } = await fetchCommit(repo, ref, ["fetch", "-q", "--depth", "1", "--no-tags", "--no-recurse-submodules", ...filter, "origin", oid], oid);
1532
1613
  // A server without filters says so and sends the whole tree: nothing is lost, the cache remembers.
@@ -1606,16 +1687,27 @@ async function writeConfig(repo, ref, key, value) {
1606
1687
  catch (error) { throw unreadable(ref, error, { cacheDir: repo.dir, stage: "config" }); }
1607
1688
  }
1608
1689
 
1609
- /** This cache fetches whole trees from now on (its server cannot serve partial fetches, or this git cannot keep
1610
- * a partial cache): recorded, and said once (the session's notices; the CLI prints them when the command ends). */
1611
- async function recordFullFetches(repo, ref, notice = `${displayRepoRef(ref.url)} does not serve partial fetches; OATS fetches whole trees from it`) {
1690
+ /** This cache fetches whole trees from now on, because its server cannot serve partial fetches: recorded, and
1691
+ * said once for this repository (the session's notices; the CLI prints them when the command ends). */
1692
+ async function recordFullFetches(repo, ref) {
1693
+ await writeConfig(repo, ref, "oats.fetch", "full");
1694
+ repo.session?.notices.push(displayDiagnosticText(`${displayRepoRef(ref.url)} does not serve partial fetches; OATS fetches whole trees from it`, ref.url));
1695
+ return "full";
1696
+ }
1697
+
1698
+ /** This cache fetches whole trees from now on, because this git cannot keep a partial cache: recorded per cache,
1699
+ * every time, but said once per session (once per command, or per reader call), however many caches it starts
1700
+ * or rebuilds. The notice names the git, not a repository. */
1701
+ async function recordOlderGitFetches(repo, ref, version) {
1612
1702
  await writeConfig(repo, ref, "oats.fetch", "full");
1613
- repo.session?.notices.push(displayDiagnosticText(notice, ref.url));
1703
+ const notices = repo.session?.notices;
1704
+ const notice = displayDiagnosticText(olderGitNotice(version), null);
1705
+ if (notices && !notices.includes(notice)) notices.push(notice);
1614
1706
  return "full";
1615
1707
  }
1616
1708
 
1617
- const olderGitNotice = (version, ref) =>
1618
- `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}); OATS fetches whole trees from ${displayRepoRef(ref.url)}`;
1709
+ const olderGitNotice = (version) =>
1710
+ `git ${version?.text ?? "(unknown version)"} cannot keep a partial cache (it needs ${PARTIAL_FETCH_GIT.join(".")}), so OATS fetches whole trees instead; a git of ${PARTIAL_FETCH_GIT.join(".")} or later removes this notice`;
1619
1711
 
1620
1712
  /** One strict probe per exec: share in-flight work and retain only parsed success. A failed or abandoned
1621
1713
  * probe cannot authorize rebuilding a cache, nor erase a newer probe installed by a retry. */
@@ -1680,7 +1772,7 @@ export function keepsPartialCache(version) {
1680
1772
  * it again recording whole-tree fetches. The cache is disposable: everything in it is fetched again. */
1681
1773
  async function rebuildWhole(repo, ref, options, version) {
1682
1774
  const fresh = await freshCache(repo, ref, options);
1683
- await recordFullFetches(fresh, ref, olderGitNotice(version, ref));
1775
+ await recordOlderGitFetches(fresh, ref, version);
1684
1776
  return fresh;
1685
1777
  }
1686
1778
 
@@ -17,7 +17,7 @@
17
17
  import { closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readdirSync, readFileSync, realpathSync } from "node:fs";
18
18
  import { isAbsolute, join } from "node:path";
19
19
  import { gitOperationInProgress, instancesDirs, retainedWorktreesRoot, retirementRecoveryRoot } from "./core.mjs";
20
- import { gitRead, gitRepoRead } from "./instance-git.mjs";
20
+ import { filterDriverKeys, gitRead, gitRepoRead } from "./instance-git.mjs";
21
21
  import { formatBytes } from "./retire-output.mjs";
22
22
  import { joinBytes } from "./tree-copy.mjs";
23
23
 
@@ -167,12 +167,7 @@ function headOf(read) {
167
167
  function contentFilters(path) {
168
168
  const config = gitRead(path, ["config", "--list", "-z"]);
169
169
  if (!config.ok) return { error: config.err };
170
- const names = new Set();
171
- for (const entry of config.out.split("\0")) {
172
- const nl = entry.indexOf("\n");
173
- const m = /^filter\.(.*)\.(clean|process)$/s.exec(nl < 0 ? entry : entry.slice(0, nl));
174
- if (m) names.add(m[1]);
175
- }
170
+ const names = new Set(filterDriverKeys(config.out).filter((key) => key.variable === "clean" || key.variable === "process").map((key) => key.name));
176
171
  return { names: [...names].sort(byCodeUnit) };
177
172
  }
178
173
  /** Whether the index of the tree at `path` holds a submodule (a gitlink,
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Which of a retire's Git commands read no file of a work tree. lib/core.mjs
3
+ * (retireGitArgv) runs those without the overrides of the repository's filter
4
+ * drivers, and every other one with them. Kernel-private, dependency-free.
5
+ */
6
+
7
+ /** A form whose first argument is one of `verbs`. */
8
+ const firstIs = (...verbs) => (rest) => verbs.includes(rest[0]);
9
+ /** The forms of Git command a retire runs that read refs, objects, the index or
10
+ * the configuration, and no file of a work tree: no filter driver can run in
11
+ * them, so they are not preceded by the read of the repository's drivers.
12
+ * A subcommand is here with the forms of it that are so, never as a whole:
13
+ * `true` for one that has no form that touches a work tree, else what its
14
+ * arguments must be (`stash store` is here, `stash push` is not). A form that
15
+ * is not here gets the overrides, so one added to the retire is covered until
16
+ * it is listed. */
17
+ const RETIRE_READS_NO_WORK_TREE_FILE = new Map([
18
+ ["rev-parse", true], ["symbolic-ref", true], ["show-ref", true], ["for-each-ref", true], ["update-ref", true],
19
+ ["cat-file", true], ["ls-tree", true], ["fetch", true], ["config", true],
20
+ // The index's entries, as recorded. Other forms compare the work tree's files with it (--modified, --deleted) or list them (--others).
21
+ ["ls-files", (rest) => rest.length > 0 && rest.every((arg) => ["--stage", "-s", "-v", "-z", "--resolve-undo"].includes(arg)) && rest.some((arg) => arg !== "-z" && arg !== "-v")],
22
+ // Content from standard input, hashed as it is. With a file, or with `--path` (which gives the
23
+ // content read from standard input the filters of that path), the content goes through filters.
24
+ ["hash-object", (rest) => rest.includes("--stdin") && !rest.some((arg) => arg === "--path" || arg.startsWith("--path="))],
25
+ ["reflog", firstIs("show")],
26
+ ["remote", firstIs("remove")],
27
+ ["stash", firstIs("store")],
28
+ ["worktree", firstIs("list")],
29
+ ]);
30
+ /** Where the subcommand is in `args`, a retire Git command: after any `-c <setting>` of its own. */
31
+ export function retireSubcommandAt(args) {
32
+ let at = 0;
33
+ while (args[at] === "-c") at += 2;
34
+ return at;
35
+ }
36
+ /** Whether `args` (a retire Git command) is a form in RETIRE_READS_NO_WORK_TREE_FILE. */
37
+ export function retireGitReadsNoWorkTreeFile(args) {
38
+ const at = retireSubcommandAt(args);
39
+ const form = RETIRE_READS_NO_WORK_TREE_FILE.get(args[at]);
40
+ return form === true || (typeof form === "function" && form(args.slice(at + 1)));
41
+ }
@@ -0,0 +1,96 @@
1
+ /** `oats doctor`'s `retire-incomplete` problems (oats-project/oats#1747): one per instance home whose
2
+ * retirement was left open, with the command that finishes it and the capability whose retire hook
3
+ * failed last, so the operator knows whose service to check.
4
+ *
5
+ * A retirement is open when the home's status row reads a quarantine (`rollbackIncomplete`, never
6
+ * a spawn still in progress), when its `retire.state` is `failed` or `interrupted`, or when a
7
+ * failed self-retire left its outcome beside it. A home whose retire is `running` or `unknown` is
8
+ * not listed: a retire may be under way, or cannot be read. An outcome whose home is gone is not
9
+ * an open retirement either: a home is removed only once its hooks proved clean or `--force` took
10
+ * over the debt, and `oats status` still lists the outcome.
11
+ *
12
+ * Read with the readers `oats status` uses (openRetirements, lib/instance-listing.mjs): read-only
13
+ * and offline, no claim taken, no file removed, nothing signalled. */
14
+ import { openRetirements } from "./instance-listing.mjs";
15
+ import { shellWord } from "./shell-word.mjs";
16
+
17
+ export const RETIRE_INCOMPLETE = "retire-incomplete";
18
+
19
+ /** The capabilities a failed outcome's items name as `retire hook <capability>: …`, in order. */
20
+ function hooksNamedIn(items) {
21
+ const caps = [];
22
+ for (const item of Array.isArray(items) ? items : []) {
23
+ const m = typeof item === "string" && /^retire hook ([^\s:]+): /.exec(item);
24
+ if (m && !caps.includes(m[1])) caps.push(m[1]);
25
+ }
26
+ return caps;
27
+ }
28
+ const list = (items) => items.join(", ");
29
+
30
+ /** What a quarantine marker owes, as the clauses of a message; the hooks it owes; and the hooks its
31
+ * latest attempt left incomplete (`latest`). */
32
+ function quarantineOwes(marker) {
33
+ const owed = marker?.cleanup?.outstanding;
34
+ if (!owed || typeof owed !== "object") return { said: ["it is quarantined, and its quarantine marker cannot be read"], hooks: [], latest: hooksNamedIn(marker?.incomplete) };
35
+ const hooks = Array.isArray(owed.hooks) ? owed.hooks.filter((h) => typeof h === "string" && h) : [];
36
+ const git = Array.isArray(owed.git) ? owed.git.filter((g) => typeof g === "string" && g) : [];
37
+ const debts = [
38
+ ...(hooks.length ? [`retire hooks of ${list(hooks)}`] : []),
39
+ ...(git.length ? [`Git steps (${list(git)})`] : []),
40
+ ...(owed.directory === true ? ["the preservation of its directory"] : []),
41
+ ...(owed.orphanedWork === true ? ["its orphaned work directory"] : []),
42
+ ];
43
+ const at = [marker.lastRetryAt, marker.createdAt].find((t) => typeof t === "string" && t);
44
+ // `outstanding` is what the quarantine first owed, and a retry does not rewrite it; `incomplete`
45
+ // is what its latest attempt left, which names the hook that failed last.
46
+ return { said: [`it is quarantined${debts.length ? `, owing ${debts.join(" and ")}` : ""}${at ? ` (since ${at})` : ""}`], hooks, latest: hooksNamedIn(marker.incomplete) };
47
+ }
48
+
49
+ /** The `retire-incomplete` problem of one home, or null when its retirement is not open. */
50
+ function problemOf(row, failures) {
51
+ const state = row.retire?.state;
52
+ if (state === "running" || state === "unknown") return null;
53
+ if (!row.rollbackIncomplete && state !== "failed" && state !== "interrupted" && !failures.length) return null;
54
+ const said = [];
55
+ let owed = [], latest = [];
56
+ if (row.rollbackIncomplete) {
57
+ const owes = quarantineOwes(row.rollbackIncomplete);
58
+ said.push(...owes.said);
59
+ owed = owes.hooks;
60
+ latest = owes.latest;
61
+ }
62
+ if (state === "failed") {
63
+ const why = row.retire.message ?? (failures.some((f) => f.incomplete) ? "its cleanup did not finish" : undefined);
64
+ said.push(`its self-retire failed at ${row.retire.since}${row.retire.code ? ` (${row.retire.code})` : ""}${why ? `: ${why}` : ""}`);
65
+ }
66
+ else if (state === "interrupted") said.push(`its self-retire, requested at ${row.retire.since}, was interrupted: its completion ended without an outcome`);
67
+ for (const f of failures) {
68
+ if (f.error === "unreadable result file") said.push(`its result file ${f.resultPath} cannot be read`);
69
+ // A failure the row's `failed` state already said is said once.
70
+ else if (state !== "failed") said.push(`its self-retire failed at ${f.completedAt ?? "an unknown time"}${f.error ? `: ${f.error}` : f.incomplete ? ": its cleanup did not finish" : ""}`);
71
+ }
72
+ if (row.record === "unreadable") said.push(`its record ${row.recordSaid}`);
73
+ // The hook that failed last: as the quarantine's latest attempt names it, else as the outcome's
74
+ // items do, else the hooks the quarantine owes.
75
+ const named = failures.flatMap((f) => hooksNamedIn(f.incomplete)).filter((cap, i, all) => all.indexOf(cap) === i);
76
+ const hooks = latest.length ? latest : named.length ? named : owed;
77
+ const command = `oats retire ${shellWord(row.instance)} --home ${shellWord(row.home)}`;
78
+ const remedy = hooks.length
79
+ ? `check the service of ${list(hooks)}, whose retire hook failed last, then run: ${command}`
80
+ : `no failed retire hook is recorded; run: ${command}`;
81
+ return { code: RETIRE_INCOMPLETE, message: `the retirement of ${row.instance} (${row.home}) is not finished: ${said.join("; ")}`, remedy };
82
+ }
83
+
84
+ /** Every `retire-incomplete` problem of the deployment whose agents root is `root`, ordered by soul
85
+ * and home. [] when no retirement is open. */
86
+ export function retireIncompleteProblems(root) {
87
+ const problems = [];
88
+ for (const agent of openRetirements(root)) {
89
+ const homes = [...agent.homes].sort((a, b) => (a.home < b.home ? -1 : a.home > b.home ? 1 : 0));
90
+ for (const row of homes) {
91
+ const problem = problemOf(row, agent.retireFailures.filter((f) => f.instance === row.instance));
92
+ if (problem) problems.push(problem);
93
+ }
94
+ }
95
+ return problems;
96
+ }
package/lib/schedule.mjs CHANGED
@@ -284,7 +284,8 @@ export function writeHostState(st) { writeJson(join(hostScheduleDir(), "state.js
284
284
 
285
285
  // ---------------------------------------------------------------- locks
286
286
 
287
- /** Schedule locks (lib/dir-lock.mjs): a holder still there after the retry is E_SCHEDULER_BUSY. */
287
+ /** Schedule locks (lib/dir-lock.mjs): a holder still running after the retry is E_SCHEDULER_BUSY, and so is
288
+ * a lock that cannot be judged; one left by a process that is gone is taken over. `dir` is the lock's file. */
288
289
  function withDirLock(dir, what, fn, { retryMs = 0 } = {}) {
289
290
  return withSharedDirLock(dir, what, fn, { retryMs, busy: (why) => scheduleError("E_SCHEDULER_BUSY", `${what} is locked (${why}). If no oats schedule process is running, remove ${dir} and retry; nothing was changed.`) });
290
291
  }