@awebai/oats 0.58.0 → 0.59.0

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 (53) hide show
  1. package/bin/oats.mjs +1 -1
  2. package/docs/desktop-cli-api.md +68 -3
  3. package/docs/desktop.md +30 -3
  4. package/docs/execution-targets.md +11 -0
  5. package/docs/implementation.md +2 -0
  6. package/docs/integrations.md +2 -2
  7. package/docs/knowledge.md +4 -4
  8. package/docs/official-catalog.md +4 -4
  9. package/docs/packages.md +14 -14
  10. package/docs/release-notes/v0.59.0.md +288 -0
  11. package/docs/servers.md +4 -1
  12. package/docs/souls-and-instances.md +21 -0
  13. package/docs/tui.md +644 -118
  14. package/docs/workspaces.md +2 -2
  15. package/lib/core.mjs +216 -42
  16. package/lib/read-ahead-worker.mjs +119 -0
  17. package/lib/read-ahead.mjs +115 -0
  18. package/lib/retire-state.mjs +33 -0
  19. package/lib/servers.mjs +9 -1
  20. package/lib/session-input.mjs +14 -4
  21. package/package-catalog.json +3 -3
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-data.mjs +4 -0
  25. package/packages/client/deployment-panel.mjs +3 -0
  26. package/packages/client/instance-acts.mjs +23 -8
  27. package/packages/client/instance-presentation.mjs +3 -2
  28. package/packages/client/instance-tree.mjs +84 -39
  29. package/packages/client/lifecycle-confirmation.mjs +9 -3
  30. package/packages/client/remote-roster.mjs +4 -1
  31. package/packages/client/retire-in-flight.mjs +65 -0
  32. package/packages/client/retire-state.mjs +30 -0
  33. package/packages/client/spawn-apply.mjs +13 -4
  34. package/packages/tui/README.md +23 -10
  35. package/packages/tui/lib/actions.mjs +63 -5
  36. package/packages/tui/lib/client.mjs +12 -1
  37. package/packages/tui/lib/config.mjs +7 -2
  38. package/packages/tui/lib/main.mjs +315 -82
  39. package/packages/tui/lib/model.mjs +523 -56
  40. package/packages/tui/lib/panel.mjs +436 -125
  41. package/packages/tui/lib/read.mjs +52 -26
  42. package/packages/tui/lib/store.mjs +908 -65
  43. package/packages/tui/lib/term/keys.mjs +9 -2
  44. package/packages/tui/lib/term/text.mjs +4 -0
  45. package/packages/tui/lib/term/through.mjs +12 -1
  46. package/packages/tui/lib/views/frame.mjs +394 -95
  47. package/packages/tui/lib/views/help.mjs +54 -13
  48. package/packages/tui/lib/views/instances.mjs +43 -25
  49. package/packages/tui/lib/views/palette.mjs +61 -0
  50. package/packages/tui/lib/views/souls.mjs +268 -0
  51. package/packages/tui/lib/views/spawn.mjs +299 -0
  52. package/packages/tui/lib/views/split.mjs +29 -0
  53. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.12.0 # bare version → resolves through the official catalog
58
- oats.okf: v5.2.0
57
+ oats.framework: v1.12.2 # bare version → resolves through the official catalog
58
+ oats.okf: v5.2.1
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
package/lib/core.mjs CHANGED
@@ -38,7 +38,7 @@ import {
38
38
  } from "node:fs";
39
39
  import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
40
40
  import { homedir } from "node:os";
41
- import { accessSync, constants as fsConstants } from "node:fs";
41
+ import { accessSync, constants as fsConstants, fstatSync } from "node:fs";
42
42
  import { recordLocalInput } from "./local-inputs.mjs";
43
43
  import { createHash, randomUUID } from "node:crypto";
44
44
  import { fileURLToPath } from "node:url";
@@ -51,6 +51,7 @@ import { appendEvent, incarnationOf, liveWaiting, recordStartBoundary, retireRef
51
51
  import { killGroup } from "./process-group.mjs";
52
52
  import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
53
53
  import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
54
+ import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
54
55
  import { captureLoginEnvironment } from "./login-environment.mjs";
55
56
  import { kernelNode } from "./stable-node.mjs";
56
57
 
@@ -76,12 +77,14 @@ import { validateBindingInterface } from "./provider-binding.mjs";
76
77
  /** Retirement/rollback tree fingerprint (exported for scope tests: kernel-field neutrality is opt-in per instance home),
77
78
  * the exact digest a copied path is compared with (exported so a test holds it to the copier),
78
79
  * a worktree's byte digest and the Git directories it leaves out (exported so a test holds them to exact paths),
79
- * and the receipts the stored digest passes over in a home (exported so a test holds the manifest grammar to refusing each of them). */
80
- export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS, storedTreeDigest, worktreeBytes, worktreeGitPaths };
80
+ * the receipts the stored digest passes over in a home (exported so a test holds the manifest grammar to refusing each of them),
81
+ * and a worktree's untracked and ignored digest, alone and with its bytes from one read (exported so a test holds the one read to the two apart). */
82
+ export { exactTreeDigest, fingerprintTree, generatedWorkDigest, KERNEL_HOME_RECEIPTS, storedTreeDigest, worktreeBytes, worktreeDigests, worktreeGitPaths };
81
83
 
82
84
  import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
83
85
  import { readPortableBytes } from "./bounded-read.mjs";
84
86
  import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes } from "./tree-copy.mjs";
87
+ import { readAheadConsumed, readingAhead } from "./read-ahead.mjs";
85
88
  import { assertSameWorktreeHead, gitRead, gitRefPresence, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
86
89
  import { systemTool } from "./system-tools.mjs";
87
90
  import { creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
@@ -5236,11 +5239,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5236
5239
  // owed a retirement, not live work. Read-only here — completion is the
5237
5240
  // detached child's or an operator's `oats retire`, never status.
5238
5241
  const pending = retirePendingMarkerPath(home);
5239
- let retirePending;
5242
+ let retirePending, marker;
5240
5243
  if (existsSync(pending)) {
5241
- try { retirePending = JSON.parse(readFileSync(pending, "utf8")); }
5242
- catch { retirePending = { reason: "retire pending" }; }
5244
+ try { retirePending = JSON.parse(readFileSync(pending, "utf8")); marker = { read: retirePending }; }
5245
+ catch { retirePending = { reason: "retire pending" }; marker = { read: undefined }; }
5243
5246
  }
5247
+ const retire = retireStateOf(home, marker);
5244
5248
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
5245
5249
  // A home whose record cannot be read is listed, never observed: where its session is, is in the record.
5246
5250
  const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
@@ -5277,7 +5281,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io) {
5277
5281
  try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
5278
5282
  catch { waitingOnYou = null; }
5279
5283
  }
5280
- return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}) };
5284
+ // `retire` is only ever the value read above: a record that carries one (hand-edited, or
5285
+ // copied from a row) never stands in for it.
5286
+ const { retire: _recordedRetire, ...recorded } = meta;
5287
+ return { ...recorded, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
5281
5288
 
5282
5289
  });
5283
5290
  };
@@ -5908,14 +5915,34 @@ const GIT_NAME = Buffer.from(".git");
5908
5915
  * `children` is for a root the copier creates itself (a home, a worktree):
5909
5916
  * its copy is made inside a directory the copier creates, so the root's bits
5910
5917
  * are no part of what it carries, and the root is compared through its
5911
- * children alone. The stored digest never holds the root's bits. */
5912
- function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], instanceHome = false, stored = true, digestVersion = 1, exact = false, children = false } = {}) {
5918
+ * children alone. The stored digest never holds the root's bits.
5919
+ *
5920
+ * `taps` (paths under the root, as bytes; not with the legacy digest) are
5921
+ * entries read into a digest of their own from the same read: each one's
5922
+ * stored digest of version 2, as storedTreeDigest takes it of that path
5923
+ * alone, in `taps` of the answer (a Map by the hex of the path). A tap the
5924
+ * walk does not read whole has none there: one it passes over or does not
5925
+ * reach, one inside another tap, and one that holds a path it passes over
5926
+ * (the caller does not ask for those; worktreeDigests).
5927
+ *
5928
+ * The walk reads every byte it hashes itself, in this order. While it does,
5929
+ * worker threads read the files it reads next into the page cache
5930
+ * (read-ahead.mjs), which changes nothing it computes or throws. */
5931
+ function fingerprintTrees(root, options = {}) {
5932
+ const { excludeRoot = new Set(), excludePaths = [], stored = true, digestVersion = 1 } = options;
5933
+ // The files are read ahead in this walk's order (read-ahead.mjs); the digest is the read below, alone.
5934
+ return readingAhead([root], { order: stored && digestVersion === 1 ? "locale" : "bytes", excludeRoot, excludePaths }, () => treeDigests(root, options));
5935
+ }
5936
+ function treeDigests(root, { excludeRoot = new Set(), excludePaths = [], instanceHome = false, stored = true, digestVersion = 1, exact = false, children = false, taps = [] } = {}) {
5913
5937
  if (stored && digestVersion !== 1 && digestVersion !== BASELINE_DIGEST_VERSION) throw new Error(`no stored digest of version ${digestVersion}`);
5914
5938
  const legacy = stored && digestVersion === 1;
5939
+ if (taps.length && legacy) throw new Error("taps are read in the order of the names' bytes, which the legacy digest does not take");
5940
+ // Each tap's digest, by the hex of its path; undefined until the walk has read it.
5941
+ const tapDigests = new Map(taps.map((tap) => [tap.toString("hex"), undefined]));
5915
5942
  const excluded = new Set(excludePaths.map((path) => path.toString("hex")));
5916
5943
  // The stored digest: `s` when it is the legacy one, `v` when it is version 2.
5917
5944
  const s = legacy ? createHash("sha256") : null, v = stored && !legacy ? createHash("sha256") : null, x = exact ? createHash("sha256") : null;
5918
- const digests = () => ({ stored: s || v ? `sha256:${(s || v).digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined });
5945
+ const digests = () => ({ stored: s || v ? `sha256:${(s || v).digest("hex")}` : undefined, exact: x ? `sha256:${x.digest("hex")}` : undefined, ...(taps.length ? { taps: tapDigests } : {}) });
5919
5946
  /** A field whose length is not fixed, in the exact digest or in version 2: its length, NUL, its bytes. */
5920
5947
  const sizedIn = (hash, bytes) => { hash.update(String(bytes.length)); hash.update("\0"); hash.update(bytes); };
5921
5948
  const sized = (bytes) => sizedIn(x, bytes);
@@ -5926,7 +5953,7 @@ function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], in
5926
5953
  v?.update("entry\0"); v?.update(mode); v?.update("\0");
5927
5954
  x?.update("entry\0"); x?.update(mode); x?.update("\0");
5928
5955
  if (rootStat.isSymbolicLink()) { const target = readlinkSync(root, "buffer"); s?.update("link\0"); s?.update(target); if (v) { v.update("link\0"); sizedIn(v, target); } if (x) { x.update("link\0"); sized(target); } }
5929
- else if (rootStat.isFile()) { const bytes = readFileSync(root); s?.update("file\0"); s?.update(bytes); if (v) { v.update("file\0"); sizedIn(v, bytes); } if (x) { x.update("file\0"); sized(bytes); } }
5956
+ else if (rootStat.isFile()) { const bytes = readFileSync(root); readAheadConsumed(bytes.length); s?.update("file\0"); s?.update(bytes); if (v) { v.update("file\0"); sizedIn(v, bytes); } if (x) { x.update("file\0"); sized(bytes); } }
5930
5957
  else throw unsupportedEntry(String(root));
5931
5958
  return digests();
5932
5959
  }
@@ -5935,7 +5962,8 @@ function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], in
5935
5962
  // `dir` and `rel` are bytes: the directory, and its path under the root
5936
5963
  // (empty at the root). `relText` is `rel` as text, for the name tests.
5937
5964
  // `storedOn` is false inside an entry the stored digest passes over.
5938
- const walk = (dir, rel, relText, storedOn) => {
5965
+ // `tap`: inside a tap, its hash and where its paths start in `rel`.
5966
+ const walk = (dir, rel, relText, storedOn, tap) => {
5939
5967
  // The legacy order is the one it has always been: the names as text,
5940
5968
  // compared by localeCompare, on the listing as readdirSync returns it.
5941
5969
  // The sort is stable and the listing is the same whether its names come
@@ -5964,25 +5992,39 @@ function fingerprintTrees(root, { excludeRoot = new Set(), excludePaths = [], in
5964
5992
  s?.update(childRel); s?.update("\0"); s?.update(mode); s?.update("\0");
5965
5993
  if (v) { sizedIn(v, childRel); v.update(mode); v.update("\0"); }
5966
5994
  if (x) { sized(childRel); x.update(mode); x.update("\0"); }
5995
+ // A tap is framed as the stored digest of version 2 frames a root of its own: a directory
5996
+ // as "tree", anything else as one entry without a path. Not one inside another: the inner
5997
+ // one is read apart.
5998
+ if (tap) { sizedIn(tap.hash, childRel.subarray(tap.at)); tap.hash.update(mode); tap.hash.update("\0"); }
5999
+ const opens = !tap && tapDigests.size && tapDigests.has(childRel.toString("hex")) ? createHash("sha256") : null;
6000
+ if (opens) opens.update(st.isDirectory() ? "tree\0" : `entry\0${mode}\0`);
6001
+ const t = tap?.hash ?? opens;
5967
6002
  if (st.isSymbolicLink()) {
5968
6003
  const target = readlinkSync(path, "buffer");
5969
6004
  s?.update("link\0"); s?.update(target); s?.update("\0");
5970
6005
  if (v) { v.update("link\0"); sizedIn(v, target); }
5971
6006
  if (x) { x.update("link\0"); sized(target); }
6007
+ if (t) { t.update("link\0"); sizedIn(t, target); }
5972
6008
  } else if (st.isFile()) {
5973
6009
  const bytes = readFileSync(path);
6010
+ readAheadConsumed(bytes.length);
5974
6011
  // Kernel-field neutrality applies ONLY when the tree IS an instance home, and only to the
5975
6012
  // stored digest; a work tree's instance.json is the agent's bytes.
5976
6013
  const storedBytes = s || v ? (instanceHome && !relText && name === "instance.json" ? kernelNeutralInstanceJson(bytes) : bytes) : undefined;
5977
6014
  s?.update("file\0"); s?.update(storedBytes); s?.update("\0");
5978
6015
  if (v) { v.update("file\0"); sizedIn(v, storedBytes); }
5979
6016
  if (x) { x.update("file\0"); sized(bytes); }
5980
- } else if (st.isDirectory()) { s?.update("dir\0"); v?.update("dir\0"); x?.update("dir\0"); walk(path, childRel, childRelText, on); }
6017
+ if (t) { t.update("file\0"); sizedIn(t, bytes); }
6018
+ } else if (st.isDirectory()) {
6019
+ s?.update("dir\0"); v?.update("dir\0"); x?.update("dir\0"); tap?.hash.update("dir\0");
6020
+ walk(path, childRel, childRelText, on, tap ?? (opens ? { hash: opens, at: childRel.length + PATH_SEPARATOR_BYTES.length } : null));
6021
+ }
5981
6022
  else throw unsupportedEntry(join(String(root), childRelText));
6023
+ if (opens) tapDigests.set(childRel.toString("hex"), `sha256:${opens.digest("hex")}`);
5982
6024
  }
5983
6025
  };
5984
6026
  const outerS = s, outerV = v;
5985
- walk(Buffer.from(root), Buffer.alloc(0), "", true);
6027
+ walk(Buffer.from(root), Buffer.alloc(0), "", true, null);
5986
6028
  return digests();
5987
6029
  }
5988
6030
  /** The legacy stored digest of a tree (fingerprintTrees, version 1): what a spawn baseline without
@@ -6090,13 +6132,28 @@ function generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposable
6090
6132
  * (an entry under it without permission, for example) is no path the digest can prove anything
6091
6133
  * of: it throws E_WORK_INSPECTION_FAILED, `could not inspect <path>: <reason>`, the path as text. */
6092
6134
  function generatedWorkDigest(work, statusBytes, disposableRoots = []) {
6135
+ const paths = generatedWorkPaths(statusBytes, disposableRoots);
6136
+ return readingAhead(paths.map((rel) => generatedWorkPath(work, rel)), {}, () => generatedWorkDigestOf(work, paths));
6137
+ }
6138
+ /** The paths generatedWorkDigest reads, under the worktree, in its order: the
6139
+ * untracked and ignored ones, outside the disposable roots, as bytes. */
6140
+ function generatedWorkPaths(statusBytes, disposableRoots) {
6093
6141
  const roots = disposableRoots.map((root) => [Buffer.from(root), Buffer.from(`${root}${sep}`)]);
6094
6142
  const owned = (path) => roots.some(([root, under]) => path.equals(root) || (path.length >= under.length && path.subarray(0, under.length).equals(under)));
6095
- const paths = untrackedOrIgnoredPaths(statusBytes).filter((path) => !owned(path)).sort(Buffer.compare);
6143
+ return untrackedOrIgnoredPaths(statusBytes).filter((path) => !owned(path)).sort(Buffer.compare);
6144
+ }
6145
+ /** Where generatedWorkDigest reads the status's path `rel`: without the `/` an ignored directory's row ends in. */
6146
+ const generatedWorkPath = (work, rel) => joinBytes(work, rel.length > 1 && rel[rel.length - 1] === 0x2f ? rel.subarray(0, -1) : rel);
6147
+ /** generatedWorkDigest of `paths` (generatedWorkPaths), each read as it is in
6148
+ * there, or as `read` has it already: a Map of a path's stored digest by the
6149
+ * hex of where it is read (worktreeDigests). */
6150
+ function generatedWorkDigestOf(work, paths, read = new Map()) {
6096
6151
  const hash = createHash("sha256");
6097
6152
  for (const rel of paths) {
6098
6153
  hash.update(String(rel.length)); hash.update("\0"); hash.update(rel);
6099
- const path = joinBytes(work, rel.length > 1 && rel[rel.length - 1] === 0x2f ? rel.subarray(0, -1) : rel);
6154
+ const path = generatedWorkPath(work, rel);
6155
+ const known = read.get(path.subarray(pathBytes(work).length + PATH_SEPARATOR_BYTES.length).toString("hex"));
6156
+ if (known !== undefined) { hash.update(known); hash.update("\0"); continue; }
6100
6157
  const uninspectable = (e) => (e?.code === "E_WORK_INSPECTION_FAILED" ? e : oatsError("E_WORK_INSPECTION_FAILED", `could not inspect ${path.toString()}: ${e.message}`));
6101
6158
  try { lstatSync(path); }
6102
6159
  catch (e) {
@@ -6110,6 +6167,29 @@ function generatedWorkDigest(work, statusBytes, disposableRoots = []) {
6110
6167
  }
6111
6168
  return `sha256:${hash.digest("hex")}`;
6112
6169
  }
6170
+ /** A worktree's generatedWorkDigest and its bytes (worktreeBytes) from one
6171
+ * read of each file (#1247): one walk of the worktree for its bytes, in
6172
+ * which each path of the digest that the walk reads whole is a tap
6173
+ * (fingerprintTrees), read into its stored digest from the same bytes. A
6174
+ * path it cannot read whole (one under a link or a Git directory the bytes
6175
+ * leave out, one that holds such a directory, one inside another path, one
6176
+ * that is not there) is read apart, as generatedWorkDigest reads it.
6177
+ * → { generated, bytes, gitPaths }, the values the two give apart; or
6178
+ * undefined when anything fails: the caller then takes them apart, as
6179
+ * before, so that whatever fails fails in their order, with their words. */
6180
+ function worktreeDigests(work, statusBytes, disposableRoots = []) {
6181
+ try {
6182
+ const gitPaths = worktreeGitPaths(work);
6183
+ const paths = generatedWorkPaths(statusBytes, disposableRoots);
6184
+ const under = pathBytes(work).length + PATH_SEPARATOR_BYTES.length;
6185
+ const holdsLeftOut = (rel) => gitPaths.some((git) => git.length > rel.length && git[rel.length] === PATH_SEPARATOR_BYTES[0] && git.subarray(0, rel.length).equals(rel));
6186
+ const taps = paths.map((rel) => generatedWorkPath(work, rel).subarray(under)).filter((rel) => rel.length && !holdsLeftOut(rel));
6187
+ const { exact, taps: read } = fingerprintTrees(work, { stored: false, exact: true, excludePaths: gitPaths, children: true, taps });
6188
+ return { generated: generatedWorkDigestOf(work, paths, read ?? new Map()), bytes: exact, gitPaths };
6189
+ } catch {
6190
+ return undefined;
6191
+ }
6192
+ }
6113
6193
  /** The legacy generatedWorkFingerprint (digest version 1), for a baseline without `digestVersion`.
6114
6194
  * It never changes: the decoded status's paths, tested with existsSync, which follows a link. */
6115
6195
  function generatedWorkFingerprint(work, status, disposableRoots = []) {
@@ -6117,14 +6197,16 @@ function generatedWorkFingerprint(work, status, disposableRoots = []) {
6117
6197
  const paths = status.split("\0").filter(Boolean)
6118
6198
  .filter((row) => row.startsWith("?? ") || row.startsWith("!! "))
6119
6199
  .map((row) => row.slice(3)).filter((path) => !owned(path)).sort();
6120
- const hash = createHash("sha256");
6121
- for (const rel of paths) {
6122
- const path = join(work, rel);
6123
- hash.update(rel); hash.update("\0");
6124
- if (!existsSync(path)) { hash.update("missing\0"); continue; }
6125
- hash.update(fingerprintTree(path)); hash.update("\0");
6126
- }
6127
- return `sha256:${hash.digest("hex")}`;
6200
+ return readingAhead(paths.map((rel) => join(work, rel)), { order: "locale" }, () => {
6201
+ const hash = createHash("sha256");
6202
+ for (const rel of paths) {
6203
+ const path = join(work, rel);
6204
+ hash.update(rel); hash.update("\0");
6205
+ if (!existsSync(path)) { hash.update("missing\0"); continue; }
6206
+ hash.update(fingerprintTree(path)); hash.update("\0");
6207
+ }
6208
+ return `sha256:${hash.digest("hex")}`;
6209
+ });
6128
6210
  }
6129
6211
 
6130
6212
  function retirementDisposableRoots(work, capabilities) {
@@ -6558,7 +6640,7 @@ export function inspectInstanceSession(home) {
6558
6640
  const s = instanceSessionTarget(home);
6559
6641
  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", waitingOnYou: null };
6560
6642
  let observed;
6561
- try { observed = inspectSessionTarget(s.target); }
6643
+ try { observed = inspectSessionTarget(s.target, undefined, { includeSize: true }); }
6562
6644
  // The tmux failure stays the cause: sessionServerGone judges it.
6563
6645
  catch (e) { throw Object.assign(oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`), { cause: e }); }
6564
6646
  // Feature waiting-on-you: beside `state`, whose enum is unchanged.
@@ -7987,7 +8069,8 @@ const worktreeBytes = (work, gitPaths = worktreeGitPaths(work)) => exactTreeDige
7987
8069
  /** The byte part of an observed worktree's work state, read at most once per
7988
8070
  * observation and kept on it with the Git directories it leaves out
7989
8071
  * (`workGitPaths`, for the copy's verification); undefined where the
7990
- * observation saw no worktree. An inspection never reads it. The retire reads it before it
8072
+ * observation saw no worktree. An inspection reads it only with its own walk,
8073
+ * for inspectedWorkBytes, and never sets it. The retire reads it before it
7991
8074
  * writes the pre-hook recovery, the copy's verification uses it (so a pass
7992
8075
  * that copies the work costs no extra read), and so does the proof that the
7993
8076
  * retire hooks left the work as it was (movedByHooks). */
@@ -8007,6 +8090,18 @@ function observedWorkBytes(observation) {
8007
8090
  }
8008
8091
  return observation.workBytes;
8009
8092
  }
8093
+ /** observedWorkBytes, taken from the inspection's own read where it took one
8094
+ * (`inspectedWorkBytes`, worktreeDigests): it read the worktree whole for its
8095
+ * untracked and ignored digest, and nothing has written the worktree since.
8096
+ * Asked only where the retire reads the bytes right after that inspection
8097
+ * (#1247): before the pre-hook recovery, and in movedByHooks. */
8098
+ function inspectedWorkBytes(observation) {
8099
+ if (observation.workBytes === undefined && observation.inspectedWorkBytes) {
8100
+ observation.workBytes = observation.inspectedWorkBytes.bytes;
8101
+ observation.workGitPaths = observation.inspectedWorkBytes.gitPaths;
8102
+ }
8103
+ return observedWorkBytes(observation);
8104
+ }
8010
8105
  /** What the retire hooks moved, between the observation before them and the
8011
8106
  * one after → { home, work }. Nothing when the later observation has nothing
8012
8107
  * to preserve. The home moved when its exact digest did: that is its bytes,
@@ -8025,7 +8120,7 @@ function movedByHooks(before, after) {
8025
8120
  if (!after.classes.length) return { home: false, work: false };
8026
8121
  const home = after.homeBytes !== before.homeBytes;
8027
8122
  let work = after.workFingerprint !== before.workFingerprint;
8028
- if (!work && after.worktree) work = !before.workProvable || !after.workProvable || before.workBytes === undefined || observedWorkBytes(after) !== before.workBytes;
8123
+ if (!work && after.worktree) work = !before.workProvable || !after.workProvable || before.workBytes === undefined || inspectedWorkBytes(after) !== before.workBytes;
8029
8124
  return { home, work };
8030
8125
  }
8031
8126
 
@@ -8048,7 +8143,7 @@ function assertWorktreeTopLevel(work, disclosure) {
8048
8143
  }
8049
8144
  }
8050
8145
 
8051
- function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, directoryMode = directory, link = false, instance, orphanedWork = false, disclosure } = {}) {
8146
+ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktreeRemoval, directory = false, directoryMode = directory, link = false, instance, orphanedWork = false, disclosure, readWorkBytes = false } = {}) {
8052
8147
  // `directory`: work/ is read, copied and checked as a directory's bytes. `directoryMode`: the
8053
8148
  // record says `directory`. They differ for a directory of the home (instanceWork, #962), which
8054
8149
  // is copied the same way and is no directory instance: it has no receipt of its roots.
@@ -8110,7 +8205,7 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
8110
8205
  const unreached = worktreeRemoval?.removes && worktreeRemoval.repo && !directory && isWorktree && existsSync(work) ? worktreeCommitUnreached(worktreeRemoval.repo, work) : undefined;
8111
8206
  if (unreached?.unreached) classes.push("worktree commits no ref reaches");
8112
8207
  const worktree = isWorktree && existsSync(work);
8113
- let gitState = "", workProvable = true;
8208
+ let gitState = "", workProvable = true, inspectedBytes;
8114
8209
  if (worktree) {
8115
8210
  // Read once, as bytes. The bytes go into the Git state and into the
8116
8211
  // comparison with the spawn baseline (its legacy digest reads them as
@@ -8122,8 +8217,14 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
8122
8217
  const disposableRoots = baseline?.disposableReceipts?.map((r) => r.root) || [];
8123
8218
  // A path the digest cannot inspect refuses, with what this retire has
8124
8219
  // and has not done by now, as the other refusals of an inspection do.
8125
- let generated;
8126
- try { generated = baseline && digestVersion !== undefined ? generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots) : undefined; }
8220
+ // `readWorkBytes`: the retire will read the worktree's bytes right after
8221
+ // this inspection, so both digests come from one read (worktreeDigests),
8222
+ // or, where that cannot be done, apart as before.
8223
+ let generated, both;
8224
+ try {
8225
+ if (readWorkBytes && baseline && digestVersion === BASELINE_DIGEST_VERSION) both = worktreeDigests(work, statusBytes, disposableRoots);
8226
+ generated = both ? both.generated : baseline && digestVersion !== undefined ? generatedWorkFingerprintIn(digestVersion, work, statusBytes, disposableRoots) : undefined;
8227
+ }
8127
8228
  catch (e) {
8128
8229
  if (e?.code !== "E_WORK_INSPECTION_FAILED") throw e;
8129
8230
  throw oatsError(e.code, `${e.message}.${disclosure ? ` ${disclosure}.` : ""}`);
@@ -8159,12 +8260,16 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
8159
8260
  // branch, and a worktree commit no ref reaches is preserved (the class
8160
8261
  // above, `unreached`).
8161
8262
  if (found.length) workProvable = false;
8263
+ if (both && workProvable) inspectedBytes = { bytes: both.bytes, gitPaths: both.gitPaths };
8162
8264
  }
8163
8265
  // Two values, so the post-hook pass can tell which part a hook moved: the
8164
8266
  // home's bytes (its exact digest), and the work state's fingerprint. A
8165
8267
  // directory's work state is its bytes (`directoryFingerprint`, an exact
8166
- // digest too). A worktree's is its Git state here, and its bytes, which an
8167
- // inspection does not read (observedWorkBytes). `workProvable`: whether
8268
+ // digest too). A worktree's is its Git state here, and its bytes, which the
8269
+ // observation holds apart (observedWorkBytes): an inspection asked to
8270
+ // (`readWorkBytes`) reads them with its untracked and ignored digest, and
8271
+ // keeps them as `inspectedWorkBytes` for inspectedWorkBytes to adopt; it
8272
+ // never sets them. `workProvable`: whether
8168
8273
  // that state could be read and covers everything a copy of the work would
8169
8274
  // carry. None of these is kept in a baseline, a receipt or recovery.json.
8170
8275
  // When the worktree will be removed, its HEAD (the commit and the ref's
@@ -8176,7 +8281,7 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
8176
8281
  .update("\0").update(unreached ? `${unreached.head.commit}\0${unreached.unreached ? "unreached" : "reached"}\0` : "")
8177
8282
  .update(unreached?.head.ref ?? "")
8178
8283
  .digest("hex");
8179
- return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
8284
+ return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, inspectedWorkBytes: inspectedBytes, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
8180
8285
  }
8181
8286
 
8182
8287
  /** Copy the entries of `src` into `dest` (created), names as bytes, except
@@ -8941,7 +9046,7 @@ function copyRecoveryHome(observation, dest) {
8941
9046
  * cannot be read is an inspection failure, not a failed copy: its error is
8942
9047
  * put in `unreadableHeads`, and the callers throw it as it is. */
8943
9048
  const unreadableHeads = new WeakSet();
8944
- function copyRecoveryWork(observation, meta, parent) {
9049
+ function copyRecoveryWork(observation, meta, parent, { rereadSource = true } = {}) {
8945
9050
  let branchDrift, excludes, statusConfig, copied = false;
8946
9051
  // A worktree that is there is copied from itself: only one that is gone needs the recorded
8947
9052
  // branch, to be copied from the repository. (An own tree whose record holds no branch, #962.)
@@ -9003,7 +9108,15 @@ function copyRecoveryWork(observation, meta, parent) {
9003
9108
  if (observation.directory && observation.directoryFingerprint) {
9004
9109
  const recoveredWork = join(parent, "work");
9005
9110
  copyTreeSafe(observation.work, recoveredWork);
9006
- if (directoryBytes(observation.work) !== observation.directoryFingerprint || directoryBytes(recoveredWork) !== observation.directoryFingerprint) {
9111
+ // The copy is read back and held against the inspected bytes. A change to
9112
+ // the source before the copy read it is in the copy, and refuses here. One
9113
+ // made during the copy, to a file already copied, is not: the source is
9114
+ // read again for that unless `rereadSource` is false, which only the
9115
+ // retire's pre-hook copy passes. There the inspection after the hooks
9116
+ // reads the source again in any case, sees the change and copies the work
9117
+ // again, verified, under after-hooks/ (#1247). Every other copy is the
9118
+ // last read of its source before the home is removed.
9119
+ if ((rereadSource && directoryBytes(observation.work) !== observation.directoryFingerprint) || directoryBytes(recoveredWork) !== observation.directoryFingerprint) {
9007
9120
  throw new Error("directory recovery verification disagreed with the inspected source");
9008
9121
  }
9009
9122
  copied = true;
@@ -9081,7 +9194,7 @@ function writeRetirementRecovery(observation, meta, instance, phase) {
9081
9194
  const homeOnly = homeOnlyRecovery(observation, meta);
9082
9195
  const recoveredHome = join(staging, "home");
9083
9196
  copyRecoveryHome(observation, recoveredHome);
9084
- const { branchDrift, excludes, statusConfig } = homeOnly ? {} : copyRecoveryWork(observation, meta, staging);
9197
+ const { branchDrift, excludes, statusConfig } = homeOnly ? {} : copyRecoveryWork(observation, meta, staging, { rereadSource: phase !== "before-hooks" });
9085
9198
  const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
9086
9199
  // What the copy cost: the home entries it carries and the untracked/ignored (or directory) outputs, named.
9087
9200
  const home = preservedHome(recoveredHome);
@@ -9227,6 +9340,62 @@ export function retirePendingMarkerPath(home) {
9227
9340
  return join(dirname(home), `.oats-retire-pending-${basename(home)}.json`);
9228
9341
  }
9229
9342
 
9343
+ /** A status row's `retire` (feature status-retire-state, lib/retire-state.mjs): whether a retire of
9344
+ * `home` runs, could not be told, failed or was interrupted, read from what is beside the home
9345
+ * (`marker`: `{ read }` when its retire marker is there, `read` what its file parsed as, undefined
9346
+ * when it did not parse; the row's own read, so `retirePending` and this agree). Only read: no
9347
+ * claim is taken, no file removed, no process signalled. → the value, or undefined when no retire
9348
+ * runs, is scheduled or is owed.
9349
+ * - The marker of a self-retire comes first, whatever the claim says (its completion holds the
9350
+ * claim for its own retire), and gives `self: true`. A completion's result that says `ok:
9351
+ * false` is `failed`, with its time, code and message. Otherwise, a result that says anything
9352
+ * else included, the marker's completion decides: `running` while it lives (pid and recorded
9353
+ * start), `interrupted` once it is gone, and `unknown` when that cannot be read or the marker
9354
+ * names no completion. A marker that does not parse is `unknown`.
9355
+ * - Without a marker, the home's claim held for a retire is `running` while its holder lives and
9356
+ * `unknown` when that cannot be read, with `self: false`. A holder that is gone, a stop's claim
9357
+ * or no claim gives no value.
9358
+ * `since` is required (a reader drops a value without one): the recorded time when it is an
9359
+ * instant as `toISOString()` gives it (the result's `completedAt`, then the marker's
9360
+ * `requestedAt`; the claim's `at`), else the marker's or the claim file's mtime. When none can be
9361
+ * read there is no value at all. */
9362
+ function retireStateOf(home, marker) {
9363
+ const mtimeOf = (path) => { try { return statSync(path).mtime.toISOString(); } catch { return undefined; } };
9364
+ // A file beside the home as JSON, only when it is a regular file: opened without blocking and
9365
+ // checked on the open descriptor, so a pipe (whose open or read would not return) or a device put
9366
+ // there is no value, never a status that hangs. Anything that does not read is undefined.
9367
+ const regularJson = (path) => {
9368
+ let fd;
9369
+ try {
9370
+ fd = openSync(path, fsConstants.O_RDONLY | (fsConstants.O_NONBLOCK ?? 0));
9371
+ return fstatSync(fd).isFile() ? JSON.parse(readFileSync(fd, "utf8")) : undefined;
9372
+ } catch { return undefined; } finally { if (fd !== undefined) closeSync(fd); }
9373
+ };
9374
+ const instantOr = (...times) => times.find((t) => isInstantString(t));
9375
+ if (marker) {
9376
+ const pending = marker.read, markerTime = () => mtimeOf(retirePendingMarkerPath(home));
9377
+ if (!isPlainObject(pending)) return readRetireState({ state: "unknown", self: true, since: markerTime() });
9378
+ const result = regularJson(deferredRetireResultPath(home));
9379
+ if (isPlainObject(result) && result.ok === false) {
9380
+ return readRetireState({ state: "failed", self: true, since: instantOr(result.completedAt, pending.requestedAt) ?? markerTime(), code: result.error?.code, message: result.error?.message });
9381
+ }
9382
+ const pid = pending.completionPid;
9383
+ const state = !Number.isSafeInteger(pid) || pid <= 0 ? "unknown"
9384
+ : { alive: "running", gone: "interrupted" }[processLiveness({ pid, processStart: pending.completionStart }).state] ?? "unknown";
9385
+ return readRetireState({ state, self: true, since: instantOr(pending.requestedAt) ?? markerTime() });
9386
+ }
9387
+ // Most rows have no claim: asked without the throw of a read that finds none, which is most of
9388
+ // what reading it costs. A path that is not there (a dangling link too) reads as no claim either way.
9389
+ // The claim is read as homeClaimHolder reads it (claimAction, processLiveness), through regularJson.
9390
+ const lock = retireClaimPath(home);
9391
+ if (!existsSync(lock)) return undefined;
9392
+ const holder = regularJson(lock);
9393
+ if (!isPlainObject(holder) || claimAction(holder) !== "retire") return undefined;
9394
+ const { state } = processLiveness(holder);
9395
+ if (state !== "alive" && state !== "unknown") return undefined;
9396
+ return readRetireState({ state: state === "alive" ? "running" : "unknown", self: false, since: shownHolder(holder).since ?? mtimeOf(lock) });
9397
+ }
9398
+
9230
9399
  /** Where a deferred self-retirement writes its explicit outcome: a FILE beside
9231
9400
  * the (former) home, so it survives the home's removal and never reads as an
9232
9401
  * instance directory. */
@@ -10083,8 +10252,10 @@ function retireSteps(root, name, o, found, at) {
10083
10252
  // cannot read or that is gone included, is an inspection that failed (E_WORK_INSPECTION_FAILED),
10084
10253
  // and says what the retire has and has not done by then (`disclosure`), once. Classified here,
10085
10254
  // at the retire's own calls: the digests' other callers do not answer that code for it.
10086
- const inspect = (disclosure) => {
10087
- try { return inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, directoryMode, link, instance: name, orphanedWork, disclosure }); }
10255
+ // `readWorkBytes`: whether the worktree's bytes are likely to be read right after this inspection,
10256
+ // so that it takes them in its own read (worktreeDigests). A guess either way costs time, never a proof.
10257
+ const inspect = (disclosure, readWorkBytes = false) => {
10258
+ try { return inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, directoryMode, link, instance: name, orphanedWork, disclosure, readWorkBytes }); }
10088
10259
  catch (e) { throw statedFailure(e, "E_WORK_INSPECTION_FAILED", `${disclosure}.`, `could not inspect the home of ${name} or its work`); }
10089
10260
  };
10090
10261
  const initialObservation = inspect(nothingYet());
@@ -10190,7 +10361,9 @@ function retireSteps(root, name, o, found, at) {
10190
10361
  }
10191
10362
  ownSession = "stopped";
10192
10363
  }
10193
- const stableObservation = inspect(beforeHooks());
10364
+ // Its bytes are read before the pre-hook recovery when it has something to preserve, which the
10365
+ // first inspection, of the same work before the stop, foretells.
10366
+ const stableObservation = inspect(beforeHooks(), initialObservation.classes.length > 0 && initialObservation.workProvable);
10194
10367
  // The bytes of the worktree as they are before the hooks: after the hooks,
10195
10368
  // "the work did not move" is then proven, never taken from a status text.
10196
10369
  // Read before the recovery is written, so that a worktree that cannot be
@@ -10203,7 +10376,7 @@ function retireSteps(root, name, o, found, at) {
10203
10376
  // before the hooks there is nothing to prove: any class after them is
10204
10377
  // preserved.
10205
10378
  if (stableObservation.classes.length && stableObservation.workProvable) {
10206
- try { observedWorkBytes(stableObservation); }
10379
+ try { inspectedWorkBytes(stableObservation); }
10207
10380
  catch (e) {
10208
10381
  throw statedFailure(e, "E_WORK_INSPECTION_FAILED", `No recovery was written and nothing was deleted: ${soFar("its home is kept")}`);
10209
10382
  }
@@ -10313,7 +10486,8 @@ function retireSteps(root, name, o, found, at) {
10313
10486
  // step and before the home is removed.
10314
10487
  // A refusal here says what has and has not happened, as one before the hooks
10315
10488
  // does: the hooks have run, and what is kept (#659).
10316
- const finalObservation = inspect(afterHooks());
10489
+ // Its bytes are read when movedByHooks compares them with the bytes read before the hooks.
10490
+ const finalObservation = inspect(afterHooks(), !!preHookRecovery && stableObservation.workBytes !== undefined);
10317
10491
  try {
10318
10492
  if (preHookRecovery) workRecovery = completeRetirementRecovery(preHookRecovery, stableObservation, finalObservation, workMeta);
10319
10493
  else if (finalObservation.classes.length) {
@@ -0,0 +1,119 @@
1
+ /** The threads of read-ahead.mjs: one planner and its readers. They only read,
2
+ * and only to bring files into the page cache: every result and every error
3
+ * is dropped. Nothing they do is part of a digest.
4
+ *
5
+ * The planner walks each root of a job in the order the digest will read it
6
+ * and hands each regular file to a free reader. It never gets more than the
7
+ * window (`windowKiB`, `windowFiles`) ahead of what the digest has read
8
+ * (CONSUMED_KIB, CONSUMED_FILES, which read-ahead.mjs counts), so the cache
9
+ * it fills is read before it can be evicted. A file larger than the window
10
+ * is passed over: the digest reads it itself, as one sequential read. A job
11
+ * ends when the digest finishes and moves JOB on; whatever is still queued
12
+ * is then dropped. */
13
+ import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync } from "node:fs";
14
+ import { sep } from "node:path";
15
+ import { parentPort, workerData, Worker } from "node:worker_threads";
16
+ import { CTL } from "./read-ahead.mjs";
17
+
18
+ const ctl = workerData.ctl;
19
+ const current = (job) => Atomics.load(ctl, CTL.JOB) === job;
20
+
21
+ if (workerData.role === "reader") {
22
+ // One read at a time, through one reused buffer: a reader holds CHUNK bytes, whatever the file's size.
23
+ const CHUNK = 1 << 20;
24
+ const buffer = Buffer.allocUnsafe(CHUNK);
25
+ // O_NONBLOCK: a FIFO put in a file's place since the planner's lstat never blocks the open.
26
+ const flags = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
27
+ parentPort.on("message", ({ job, path }) => {
28
+ if (current(job)) {
29
+ const inFlight = Atomics.add(ctl, CTL.IN_FLIGHT, 1) + 1;
30
+ if (inFlight > Atomics.load(ctl, CTL.MAX_IN_FLIGHT)) Atomics.store(ctl, CTL.MAX_IN_FLIGHT, inFlight);
31
+ try {
32
+ const fd = openSync(path, flags);
33
+ try { if (fstatSync(fd).isFile()) while (current(job) && readSync(fd, buffer, 0, CHUNK, null) > 0); }
34
+ finally { closeSync(fd); }
35
+ } catch { /* the digest reads this file itself, and reports what it finds */ }
36
+ Atomics.sub(ctl, CTL.IN_FLIGHT, 1);
37
+ }
38
+ parentPort.postMessage(0);
39
+ });
40
+ } else {
41
+ const { readers: count, windowKiB, windowFiles } = workerData;
42
+ const readers = [];
43
+ const free = [];
44
+ let wake = null;
45
+ const woken = () => { const w = wake; wake = null; w?.(); };
46
+ for (let i = 0; i < count; i++) {
47
+ const reader = new Worker(new URL(import.meta.url), { workerData: { role: "reader", ctl } });
48
+ reader.on("error", () => {}); // a reader that fails is one reader fewer
49
+ reader.on("message", () => { free.push(reader); woken(); });
50
+ readers.push(reader);
51
+ free.push(reader);
52
+ }
53
+ const SEP = Buffer.from(sep);
54
+ const join = (dir, name) => Buffer.concat([dir, SEP, name]);
55
+ // The digest's order of a directory's names (fingerprintTrees): their bytes,
56
+ // or, for the legacy stored digest, their text by localeCompare.
57
+ const names = (dir, order) => {
58
+ const list = readdirSync(dir, { encoding: "buffer" });
59
+ return order === "locale"
60
+ ? list.map((bytes) => ({ bytes, name: bytes.toString("utf8") })).sort((a, b) => a.name.localeCompare(b.name)).map((e) => e.bytes)
61
+ : list.sort(Buffer.compare);
62
+ };
63
+ // The regular files under `root` in walk order, with their sizes, passing
64
+ // over what the digest passes over. An entry that cannot be read is skipped.
65
+ function* files(root, { order, excludeRoot, excludePaths }) {
66
+ let st;
67
+ try { st = lstatSync(root); } catch { return; }
68
+ if (st.isFile()) { yield [root, st.size]; return; }
69
+ if (!st.isDirectory()) return;
70
+ const walk = function* (dir, rel) {
71
+ let list;
72
+ try { list = names(dir, order); } catch { return; }
73
+ for (const name of list) {
74
+ const childRel = rel ? Buffer.concat([rel, SEP, name]) : name;
75
+ if ((!rel && excludeRoot.has(name.toString("utf8"))) || (excludePaths.size && excludePaths.has(childRel.toString("hex")))) continue;
76
+ const path = join(dir, name);
77
+ let entry;
78
+ try { entry = lstatSync(path); } catch { continue; }
79
+ if (entry.isDirectory()) yield* walk(path, childRel);
80
+ else if (entry.isFile()) yield [path, entry.size];
81
+ }
82
+ };
83
+ yield* walk(root, null);
84
+ }
85
+ const kib = (bytes) => Math.ceil(bytes / 1024);
86
+ // Resolves when a reader is free or the digest has read more, or after a
87
+ // short while in any case, so that a job that ended is seen.
88
+ const progress = () => new Promise((resolve) => {
89
+ wake = resolve;
90
+ const waited = Atomics.waitAsync(ctl, CTL.CONSUMED_KIB, Atomics.load(ctl, CTL.CONSUMED_KIB), 20);
91
+ (waited.async ? waited.value : Promise.resolve()).then(() => { if (wake === resolve) woken(); });
92
+ });
93
+ let running = Promise.resolve();
94
+ parentPort.on("message", (job) => {
95
+ running = running.then(() => plan(job)).catch(() => {});
96
+ });
97
+ async function plan({ job, roots, order, excludeRoot, excludePaths }) {
98
+ const options = { order, excludeRoot: new Set(excludeRoot), excludePaths: new Set(excludePaths) };
99
+ let plannedKiB = 0, plannedFiles = 0;
100
+ for (const root of roots) {
101
+ for (const [path, size] of files(Buffer.from(root), options)) {
102
+ if (!current(job)) return;
103
+ plannedKiB += kib(size); plannedFiles++;
104
+ if (kib(size) > windowKiB) continue;
105
+ for (;;) {
106
+ if (!current(job)) return;
107
+ const aheadKiB = plannedKiB - Atomics.load(ctl, CTL.CONSUMED_KIB), aheadFiles = plannedFiles - Atomics.load(ctl, CTL.CONSUMED_FILES);
108
+ if (free.length && aheadKiB <= windowKiB && aheadFiles <= windowFiles) {
109
+ if (aheadKiB > Atomics.load(ctl, CTL.MAX_AHEAD_KIB)) Atomics.store(ctl, CTL.MAX_AHEAD_KIB, aheadKiB);
110
+ if (aheadFiles > Atomics.load(ctl, CTL.MAX_AHEAD_FILES)) Atomics.store(ctl, CTL.MAX_AHEAD_FILES, aheadFiles);
111
+ break;
112
+ }
113
+ await progress();
114
+ }
115
+ free.pop().postMessage({ job, path });
116
+ }
117
+ }
118
+ }
119
+ }