@awebai/oats 0.62.0 → 0.64.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 (40) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +58 -23
  3. package/docs/desktop-cli-api.md +73 -3
  4. package/docs/execution-targets.md +45 -2
  5. package/docs/first-team.md +6 -0
  6. package/docs/official-catalog.md +1 -1
  7. package/docs/packages.md +5 -5
  8. package/docs/release-lane.md +13 -0
  9. package/docs/release-notes/v0.63.0.md +135 -0
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/souls-and-instances.md +32 -7
  12. package/docs/upgrading.md +6 -3
  13. package/docs/workspaces.md +1 -1
  14. package/lib/core.mjs +100 -28
  15. package/lib/session-input.mjs +12 -2
  16. package/lib/tree-copy.mjs +188 -7
  17. package/package-catalog.json +1 -1
  18. package/package.json +1 -1
  19. package/packages/client/cli-locator.mjs +2 -2
  20. package/packages/client/instance-tree.mjs +53 -3
  21. package/packages/client/roster-sections.mjs +22 -6
  22. package/packages/record/bin/capture.mjs +59 -17
  23. package/packages/record/bin/setup.mjs +2 -1
  24. package/packages/record/docs/capture-service.md +89 -5
  25. package/packages/record/lib/capture-command-operation.mjs +2 -2
  26. package/packages/record/lib/capture-command-output.mjs +3 -2
  27. package/packages/record/lib/capture-command.mjs +20 -3
  28. package/packages/record/lib/capture-hook-runner.mjs +1 -1
  29. package/packages/record/lib/capture-index-reset.mjs +1 -0
  30. package/packages/record/lib/capture-lock.mjs +67 -33
  31. package/packages/record/lib/capture-pass.mjs +22 -8
  32. package/packages/record/lib/capture-run.mjs +1 -1
  33. package/packages/record/lib/capture-service-runner.mjs +1 -1
  34. package/packages/record/lib/capture-supervisor.mjs +24 -5
  35. package/packages/record/lib/capture-work-session.mjs +7 -4
  36. package/packages/record/lib/capture-worker.mjs +20 -4
  37. package/packages/record/lib/derived-state.mjs +30 -2
  38. package/packages/record/lib/index-db.mjs +118 -49
  39. package/packages/record/lib/store.mjs +13 -6
  40. package/skills/oats-getting-started/SKILL.md +438 -170
package/lib/tree-copy.mjs CHANGED
@@ -1,9 +1,11 @@
1
1
  /** Tree mechanics only: the kernel's catchable recursive copy (spawn, retire and
2
- * work recovery). No acquisition, selection, trust, lock or lifecycle policy. */
3
- import {
4
- chmodSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readlinkSync, symlinkSync,
2
+ * work recovery), and a bounded comparison of a copy with its source. No
3
+ * acquisition, selection, trust, lock or lifecycle policy. */
4
+ import fs, {
5
+ chmodSync, closeSync, constants, copyFileSync, fstatSync, lstatSync, mkdirSync, opendirSync, openSync, readSync, readdirSync, readlinkSync, symlinkSync,
5
6
  } from "node:fs";
6
7
  import { sep } from "node:path";
8
+ import { performance } from "node:perf_hooks";
7
9
  import { oatsError } from "./errors.mjs";
8
10
 
9
11
  const SEPARATOR = Buffer.from(sep);
@@ -36,22 +38,201 @@ export const entriesAsBytes = (dir) => readdirSync(pathBytes(dir), { encoding: "
36
38
  * - symlinks are recreated VERBATIM — never followed, never rewritten — because
37
39
  * the bytes about to be hashed must be the bytes the author wrote. The target
38
40
  * is read and written as bytes: read as text, a target that is not valid
39
- * UTF-8 would be recreated as another one;
41
+ * UTF-8 would be recreated as another one. A link keeps its own mode, which
42
+ * the exact digest holds: where the new link's mode is not the source's
43
+ * (macOS gives a link the umask's mode; Linux every link 0777), it is set
44
+ * with lchmod, on the link and never on its target. A platform with no
45
+ * lchmod cannot, and the copy is refused (linkModeUnsupported) rather than
46
+ * left with another mode;
40
47
  * - FIFOs, sockets and device nodes are rejected fail-closed: they are not
41
48
  * distributable content, and copying them has no defined meaning here;
42
49
  * - directory modes are applied AFTER their children, so a read-only source
43
50
  * directory cannot block writing its own contents. */
44
- export function copyTreeSafe(src, dest) {
51
+ export function copyTreeSafe(src, dest, { lchmod = fs.lchmodSync } = {}) {
45
52
  const st = lstatSync(src);
46
- if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); return; }
53
+ if (st.isSymbolicLink()) { symlinkSync(readlinkSync(src, "buffer"), dest); copyLinkMode(dest, st.mode & 0o7777, lchmod); return; }
47
54
  if (st.isFile()) { copyFileSync(src, dest); chmodSync(dest, st.mode & 0o7777); return; }
48
55
  if (!st.isDirectory()) {
49
56
  throw oatsError("invalid-source", `${src.toString()} is not a regular file, directory or symlink (${st.isFIFO() ? "FIFO" : st.isSocket() ? "socket" : st.isBlockDevice() || st.isCharacterDevice() ? "device node" : "unsupported file type"}) — package and capability trees carry distributable content only`);
50
57
  }
51
58
  mkdirSync(dest, { recursive: true });
52
- for (const e of entriesAsBytes(src)) copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name));
59
+ for (const e of entriesAsBytes(src)) copyTreeSafe(joinBytes(src, e.name), joinBytes(dest, e.name), { lchmod });
53
60
  chmodSync(dest, st.mode & 0o7777);
54
61
  }
62
+ /** Give the link `dest`, just made, the permission bits `mode` of its source: nothing to do when it
63
+ * has them already, else lchmod (`lchmod`: fs.lchmodSync, which only a platform that can set a
64
+ * link's mode has), read back. A mode that cannot be set is refused, never dropped. */
65
+ function copyLinkMode(dest, mode, lchmod) {
66
+ if ((lstatSync(dest).mode & 0o7777) === mode) return;
67
+ if (typeof lchmod !== "function") throw linkModeUnsupported(dest, mode, "this platform cannot set a link's mode (no lchmod)");
68
+ lchmod(dest, mode);
69
+ const now = lstatSync(dest).mode & 0o7777;
70
+ if (now !== mode) throw linkModeUnsupported(dest, mode, `lchmod left it ${now.toString(8).padStart(4, "0")}`);
71
+ }
72
+ const linkModeUnsupported = (dest, mode, why) =>
73
+ new Error(`cannot copy the link ${pathBytes(dest).toString()} with its mode ${mode.toString(8).padStart(4, "0")}: ${why}; the copy would differ from its source`);
74
+
75
+ /** How far treeDisagreement goes before it stops: differences listed, directory
76
+ * entries read (on both sides, together), file bytes read (on both sides,
77
+ * together) and milliseconds. */
78
+ export const TREE_DISAGREEMENT_LIMITS = Object.freeze({ discrepancies: 20, entries: 200_000, bytes: 64 * 1024 * 1024, ms: 5000 });
79
+ const COMPARE_CHUNK = 64 * 1024;
80
+ // A file is opened as the regular file lstat saw: a name that became a link is not followed
81
+ // (O_NOFOLLOW), and one that became a FIFO does not block the open (O_NONBLOCK).
82
+ const COMPARE_OPEN = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
55
83
 
84
+ /** A relative path, as bytes, in text that reads back one way only: each
85
+ * printable ASCII byte as itself (space included), `\` as `\\`, and every
86
+ * other byte (a control character, a byte of a UTF-8 sequence or of no valid
87
+ * one) as `\xHH`. */
88
+ export function escapedPath(bytes) {
89
+ let out = "";
90
+ for (const b of pathBytes(bytes)) out += b === 0x5c ? "\\\\" : b >= 0x20 && b <= 0x7e ? String.fromCharCode(b) : `\\x${b.toString(16).padStart(2, "0")}`;
91
+ return out;
92
+ }
56
93
 
94
+ /** Where a copy differs from its source, for a diagnosis only: never a verdict.
95
+ * It is read when an exact comparison of the two has already refused, and
96
+ * what it reads is the two trees as they are NOW, so a source that changed
97
+ * since its bytes were recorded can show differences that are not the ones
98
+ * the recorded comparison saw, or none.
99
+ *
100
+ * Both trees are walked together, names as bytes in the order of those bytes,
101
+ * with lstat: an entry that is a link is compared as a link, never followed.
102
+ * `excludePaths` (relative paths, as bytes)
103
+ * are passed over on both sides, exactly. The roots' own modes are not
104
+ * compared. Each difference is `{ path, kind }`: `path` relative to the roots,
105
+ * escaped (escapedPath), and `kind` one of `missing` (in the source, not the
106
+ * copy), `extra` (in the copy, not the source), `type`, `mode` (permission
107
+ * bits), `link-target` and `file-content`. Below a `missing`, `extra` or
108
+ * `type` entry nothing is listed. One entry can have several kinds, in that
109
+ * order. Nothing else is said: no content, no link target, no absolute path.
110
+ *
111
+ * The trees may change while they are read, and every read is by path (Node has
112
+ * no call relative to an open directory). So what is read is checked against
113
+ * what lstat saw: a file is opened without following a link or waiting on a
114
+ * FIFO and must be the regular file lstat saw (device, inode, size); a
115
+ * directory must be the directory lstat saw (device, inode) before its
116
+ * listing, after it, and when the search leaves it, also by a stop below it.
117
+ * A directory that fails its check stops the search as `unreadable`, and
118
+ * nothing noted below it is reported. A replacement that is undone before the
119
+ * replaced directory is checked again is not detected: what was read through
120
+ * it can then be compared and named. Every path named is relative to the
121
+ * roots.
122
+ *
123
+ * The work is bounded (`limits`, TREE_DISAGREEMENT_LIMITS): a directory's
124
+ * entries count as they are read, so no listing is read beyond the budget
125
+ * before the search stops; only what was read is sorted. Files are compared
126
+ * in chunks, sizes first, and never read whole. The time budget is checked
127
+ * between filesystem calls; it does not interrupt one. → `{ entries, complete }`,
128
+ * with `stoppedBy` when it stopped early: `discrepancies` (more than it
129
+ * lists), `entries`, `bytes`, `time`, or `unreadable` when a tree could not
130
+ * be read (it may have changed while it was read). It never throws. An
131
+ * answer with `complete: true` and no entries found nothing that differs now. */
132
+ export function treeDisagreement(source, copy, { excludePaths = [], limits = TREE_DISAGREEMENT_LIMITS, clock = () => performance.now(), io = { lstat: lstatSync, opendir: opendirSync } } = {}) {
133
+ const excluded = new Set(excludePaths.map((path) => pathBytes(path).toString("hex")));
134
+ const entries = [];
135
+ const started = clock();
136
+ let looked = 0, read = 0;
137
+ const STOP = Symbol("stop");
138
+ const stop = (reason) => { throw { [STOP]: reason }; };
139
+ const inTime = () => { if (clock() - started > limits.ms) stop("time"); };
140
+ const note = (rel, kind) => {
141
+ if (entries.length === limits.discrepancies) stop("discrepancies");
142
+ entries.push({ path: escapedPath(rel), kind });
143
+ };
144
+ const kindOf = (st) => (st.isSymbolicLink() ? "link" : st.isFile() ? "file" : st.isDirectory() ? "dir" : "other");
145
+ /** `path` opened as the regular file `st` (its lstat) describes, else the search stops: the tree
146
+ * changed while it was read. */
147
+ const openAsSeen = (path, st) => {
148
+ const fd = openSync(path, COMPARE_OPEN);
149
+ const now = fstatSync(fd);
150
+ if (!now.isFile() || now.ino !== st.ino || now.dev !== st.dev || now.size !== st.size) { closeSync(fd); stop("unreadable"); }
151
+ return fd;
152
+ };
153
+ const sameBytes = (a, sa, b, sb) => {
154
+ const size = sa.size;
155
+ const fa = openAsSeen(a, sa);
156
+ try {
157
+ const fb = openAsSeen(b, sb);
158
+ try {
159
+ const ba = Buffer.allocUnsafe(COMPARE_CHUNK), bb = Buffer.allocUnsafe(COMPARE_CHUNK);
160
+ for (let at = 0; at < size;) {
161
+ const want = Math.min(COMPARE_CHUNK, size - at);
162
+ if (read + 2 * want > limits.bytes) stop("bytes");
163
+ inTime();
164
+ const na = readSync(fa, ba, 0, want, at), nb = readSync(fb, bb, 0, want, at);
165
+ read += na + nb;
166
+ if (na !== nb || na === 0 || !ba.subarray(0, na).equals(bb.subarray(0, nb))) return false;
167
+ at += na;
168
+ }
169
+ return true;
170
+ } finally { closeSync(fb); }
171
+ } finally { closeSync(fa); }
172
+ };
173
+ /** Whether `path` is still the directory `st` (its lstat) describes. */
174
+ const sameDirectory = (path, st) => {
175
+ let now;
176
+ try { now = io.lstat(path); } catch { return false; }
177
+ return now.isDirectory() && now.dev === st.dev && now.ino === st.ino;
178
+ };
179
+ /** The names of the directory `dir` (lstat `st`), as bytes in their order, each counted as it is
180
+ * read: the listing stops with the search once the budget is spent. */
181
+ const listing = (dir, st) => {
182
+ const names = [];
183
+ const d = io.opendir(dir, { encoding: "buffer" });
184
+ try {
185
+ for (let e = d.readSync(); e !== null; e = d.readSync()) {
186
+ if (++looked > limits.entries) stop("entries");
187
+ inTime();
188
+ names.push(e.name);
189
+ }
190
+ } finally { d.closeSync(); }
191
+ if (!sameDirectory(dir, st)) stop("unreadable");
192
+ return names.sort(Buffer.compare);
193
+ };
194
+ /** One directory of each tree, compared. Leaving it, by its end or by a stop below it, it is
195
+ * checked again: if either is no longer the directory lstat saw, everything noted below it was
196
+ * read through a replacement and is dropped, and the search stops as `unreadable`. */
197
+ const walk = (a, sa0, b, sb0, rel) => {
198
+ const mark = entries.length;
199
+ const unchanged = () => sameDirectory(a, sa0) && sameDirectory(b, sb0);
200
+ try { compareDirectories(a, sa0, b, sb0, rel); } catch (e) {
201
+ if (!unchanged()) { entries.length = mark; stop("unreadable"); }
202
+ throw e;
203
+ }
204
+ if (!unchanged()) { entries.length = mark; stop("unreadable"); }
205
+ };
206
+ const compareDirectories = (a, sa0, b, sb0, rel) => {
207
+ const na = listing(a, sa0), nb = listing(b, sb0);
208
+ for (let i = 0, j = 0; i < na.length || j < nb.length;) {
209
+ const order = i === na.length ? 1 : j === nb.length ? -1 : Buffer.compare(na[i], nb[j]);
210
+ const inA = order <= 0, inB = order >= 0;
211
+ const name = inA ? na[i] : nb[j];
212
+ if (inA) i++;
213
+ if (inB) j++;
214
+ const childRel = rel.length ? Buffer.concat([rel, SEPARATOR, name]) : name;
215
+ if (excluded.has(childRel.toString("hex"))) continue;
216
+ inTime();
217
+ if (!inB) { note(childRel, "missing"); continue; }
218
+ if (!inA) { note(childRel, "extra"); continue; }
219
+ const pa = joinBytes(a, name), pb = joinBytes(b, name);
220
+ const sa = io.lstat(pa), sb = io.lstat(pb);
221
+ const kind = kindOf(sa);
222
+ if (kind !== kindOf(sb)) { note(childRel, "type"); continue; }
223
+ if ((sa.mode & 0o7777) !== (sb.mode & 0o7777)) note(childRel, "mode");
224
+ if (kind === "link" && !readlinkSync(pa, "buffer").equals(readlinkSync(pb, "buffer"))) note(childRel, "link-target");
225
+ else if (kind === "file" && (sa.size !== sb.size || !sameBytes(pa, sa, pb, sb))) note(childRel, "file-content");
226
+ else if (kind === "dir") walk(pa, sa, pb, sb, childRel);
227
+ }
228
+ };
229
+ try {
230
+ const ra = io.lstat(pathBytes(source)), rb = io.lstat(pathBytes(copy));
231
+ if (!ra.isDirectory() || !rb.isDirectory()) stop("unreadable");
232
+ walk(pathBytes(source), ra, pathBytes(copy), rb, Buffer.alloc(0));
233
+ return { entries, complete: true };
234
+ } catch (e) {
235
+ return { entries, complete: false, stoppedBy: e && typeof e === "object" && STOP in e ? e[STOP] : "unreadable" };
236
+ }
237
+ }
57
238
 
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.13.1",
46
+ "ref": "oats-framework/v1.13.3",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.62.0",
3
+ "version": "0.64.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.63.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.65.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
52
52
  // carry a `description` for every kind and `<kind> update <id> --description`
53
53
  // sets one (feature `automation-descriptions`, which gates the Desktop's
54
54
  // summary writes). The Desktop v1 surface is otherwise unchanged.
55
- export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 63, 0] };
55
+ export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 65, 0] };
56
56
  /** The band as humans read it — derived, never hand-spelled, so the probe
57
57
  * rejection reason, the backend's /api status and the degradation card can
58
58
  * never disagree with the numbers actually enforced above. */
@@ -185,6 +185,51 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
185
185
  return clusters.sort((a, b) => rank(a.head, b.head)).map(({ head: _head, ...c }) => c);
186
186
  }
187
187
 
188
+ /** `clusterInstances` output ordered by last focus (#1383; the command palette's order, never the sidebar's).
189
+ * `lastFocus` is Map<instanceId, time>. A node's key is the latest focus time over the node and all of its
190
+ * descendants; a node with no focus anywhere in its subtree has none. Clusters are ordered by their key, most
191
+ * recent first, and so is each set of nodes at one level of a cluster: its depth-0 roots, and the children of
192
+ * each parent. Nodes without a key follow every node with one, in their input order (a stable sort), so an
193
+ * empty record returns the input order. A child stays under its parent: each cluster is walked again in
194
+ * pre-order, every depth unchanged. Parentage is read from the pre-order and the depths alone (a node's
195
+ * children are the following rows one level deeper, until a row at its depth or above), never from names: the
196
+ * tree was built by identity, and a malformed cycle's depth-0 leftovers are roots like any other. Returns new
197
+ * cluster objects over the same rows; the input is not mutated. */
198
+ export function recencyOrder(clusters, lastFocus) {
199
+ const timeOf = (inst) => {
200
+ const time = lastFocus?.get(instanceId(inst));
201
+ return Number.isFinite(time) ? time : null;
202
+ };
203
+ const recentFirst = (a, b) => (a.key === null ? (b.key === null ? 0 : 1) : b.key === null ? -1 : b.key - a.key);
204
+ const ranked = clusters.map((cluster) => {
205
+ const roots = [];
206
+ const open = []; // the path from a root to the last row read
207
+ for (const inst of cluster.instances) {
208
+ const node = { inst, depth: inst.depth || 0, key: timeOf(inst), kids: [] };
209
+ while (open.length && open.at(-1).depth >= node.depth) open.pop();
210
+ (open.length ? open.at(-1).kids : roots).push(node);
211
+ open.push(node);
212
+ }
213
+ // Keys bottom-up, then each level sorted (stable) and walked again in pre-order.
214
+ const keyOf = (node) => {
215
+ for (const kid of node.kids) {
216
+ const key = keyOf(kid);
217
+ if (key !== null && (node.key === null || key > node.key)) node.key = key;
218
+ }
219
+ return node.key;
220
+ };
221
+ const instances = [];
222
+ const walk = (nodes) => {
223
+ for (const node of [...nodes].sort(recentFirst)) { instances.push(node.inst); walk(node.kids); }
224
+ };
225
+ const top = { key: null, kids: roots };
226
+ keyOf(top);
227
+ walk(roots);
228
+ return { key: top.key, cluster: { ...cluster, instances } };
229
+ });
230
+ return ranked.sort(recentFirst).map(({ cluster }) => cluster);
231
+ }
232
+
188
233
  /** Find the roster instance a UI reference means. References carry the
189
234
  * display name plus whatever identity the caller knows (home/agentsRoot —
190
235
  * sidebar rows know both; older callers pass a bare name). Identity match
@@ -449,12 +494,17 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
449
494
  * [{ key, label, clusters: [{ key, instances }] }], each cluster projected to its visible members, which carry
450
495
  * their tree depth. A group's key is unique even when two roots share a name (other agents roots or hosts), and
451
496
  * does not depend on what is visible: a cluster's is `cluster:<its place among the full roster's multi-member
452
- * clusters>:<name>`, a run's `independent:<instanceId of its first member in the full roster>`. */
453
- export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks } = {}) {
497
+ * clusters>:<name>`, a run's `independent:<instanceId of its first member in the full roster>`.
498
+ * `lastFocus` (Map<instanceId, time>, optional; the command palette's, #1383): the full roster's clusters are
499
+ * ordered by last focus (`recencyOrder`) before the groups form by the same rule, so a run is the consecutive
500
+ * single clusters of that order, keyed by its first member there. What is visible still decides only which rows
501
+ * are listed, never the order. Without it, the roster's own order (the sidebar's and the TUI's). */
502
+ export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus } = {}) {
454
503
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
455
504
  const groups = [];
456
505
  let place = 0, run = null;
457
- for (const c of clusterInstances(allInstances, { links })) {
506
+ const clusters = clusterInstances(allInstances, { links });
507
+ for (const c of lastFocus instanceof Map ? recencyOrder(clusters, lastFocus) : clusters) {
458
508
  const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
459
509
  if (c.instances.length > 1) {
460
510
  run = null;
@@ -5,7 +5,7 @@
5
5
  * A deployment is `{ id, machine, path, label, local, reachable, identityFrom, primary, stale?, reason? }`
6
6
  * and a row carries `deployment: { id }`. Nothing is derived from a host name or a path beyond the
7
7
  * display label. A view with one deployment has one section and no heading. */
8
- import { rosterGroups } from './instance-tree.mjs';
8
+ import { rosterGroups, instanceId } from './instance-tree.mjs';
9
9
  import { machineLabelParts } from './deployment-label.mjs';
10
10
  import { requireTerms } from './client-terms.mjs';
11
11
 
@@ -51,16 +51,32 @@ export const rowStale = (row, deployments) => {
51
51
  * Sections with no visible row are left out. Each is labelled by its machine, with the path tail
52
52
  * only when one machine holds two (deployment-label.mjs machineLabels), in the client's terms
53
53
  * (client-terms.mjs: the label of a deployment that names no machine). Returns
54
- * `[{ deployment|null, label|null, groups }]`, a group being `{ key, label, clusters }` as before. */
55
- export function rosterSections(instances, visible, deployments, terms) {
54
+ * `[{ deployment|null, label|null, groups }]`, a group being `{ key, label, clusters }` as before.
55
+ * `lastFocus` (Map<instanceId, time>, optional; the command palette's, #1383): each section's groups follow
56
+ * last focus (rosterGroups), and the sections are ordered by the latest focus over each one's full roster,
57
+ * most recent first, then the panel's order. Without it, the panel's order (the sidebar's and the TUI's). */
58
+ export function rosterSections(instances, visible, deployments, terms, { lastFocus } = {}) {
56
59
  requireTerms(terms, 'rosterSections');
57
- const groupsOf = (all, shown) => rosterGroups(all, shown); // the relation groups the palette lists too
60
+ const recency = lastFocus instanceof Map ? { lastFocus } : {};
61
+ const groupsOf = (all, shown) => rosterGroups(all, shown, recency); // the relation groups the palette lists too
58
62
  if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible) }];
59
63
  const sectionOf = splitByDeployment(deployments);
60
64
  const all = sectionOf(instances), shown = sectionOf(visible), labels = machineLabelParts(deployments, terms);
61
65
  const label = ({ machine, tail }) => (tail ? `${machine} · ${tail}` : machine);
62
- return deployments.map(d => ({ deployment: d, parts: labels.get(d.id), all: all.get(d.id), shown: shown.get(d.id) }))
63
- .filter(s => s.shown.length)
66
+ const sections = deployments.map(d => ({ deployment: d, parts: labels.get(d.id), all: all.get(d.id), shown: shown.get(d.id) }));
67
+ if (recency.lastFocus) {
68
+ const latest = rows => rows.reduce((max, row) => {
69
+ const time = lastFocus.get(instanceId(row));
70
+ return Number.isFinite(time) && (max === null || time > max) ? time : max;
71
+ }, null);
72
+ const keyed = new Map(sections.map(s => [s, latest(s.all)]));
73
+ // Stable: sections without a focus keep the panel's order, after those with one.
74
+ sections.sort((a, b) => {
75
+ const ka = keyed.get(a), kb = keyed.get(b);
76
+ return ka === null ? (kb === null ? 0 : 1) : kb === null ? -1 : kb - ka;
77
+ });
78
+ }
79
+ return sections.filter(s => s.shown.length)
64
80
  .map(s => ({ deployment: s.deployment, label: label(s.parts), machine: s.parts.machine, tail: s.parts.tail, groups: groupsOf(s.all, s.shown) }));
65
81
  }
66
82
 
@@ -33,6 +33,8 @@ import { acquireCaptureLock } from "../lib/capture-lock.mjs";
33
33
  import { captureHealthForDoctor } from "../lib/capture-health.mjs";
34
34
  import { captureDefaultRootPlan, resolveCaptureDefaultRoots } from "../lib/capture-default-roots.mjs";
35
35
  import { captureCommandPass, reportLockInitializationFailure, reportReclaimedLock, releaseDetail } from "../lib/capture-command-output.mjs";
36
+ import { captureCommandEntry } from "../lib/capture-command.mjs";
37
+ import { captureSignalPoll } from "../lib/capture-supervisor.mjs";
36
38
  import { captureWatchQueue } from "../lib/capture-watch.mjs";
37
39
  import { launchCaptureHook } from "../lib/capture-hook.mjs";
38
40
 
@@ -48,6 +50,31 @@ function loadIgnoreForCommand(recordRoot) {
48
50
  }
49
51
  }
50
52
 
53
+ // The exact commands (--home, --file, --reset-cursors) run in this process.
54
+ // TERM/INT while one runs is observed only at its safe points: before the
55
+ // lock, after taking it, before each format's batch of exact files and before
56
+ // the index update. Discovery, one format's batch, the index update and the
57
+ // receipt summaries are synchronous and cannot be preempted, so a signal
58
+ // waits for the segment it arrived in; no response time is promised. An
59
+ // interruption at a safe point unwinds through the lock's release.
60
+ class CaptureInterrupted extends Error {}
61
+ let signalled = null;
62
+ const onSignal = signal => { signalled ??= signal; };
63
+ /** Run `fn` with TERM/INT observed, from before its lock until it returns. */
64
+ async function observingSignals(fn) {
65
+ process.on("SIGTERM", onSignal); process.on("SIGINT", onSignal);
66
+ try { return await fn(); }
67
+ finally { process.off("SIGTERM", onSignal); process.off("SIGINT", onSignal); }
68
+ }
69
+ /** A safe point: a signal pending from synchronous work dispatches during
70
+ * the poll this yields to, and an observed one ends the command here.
71
+ * `after` says what had already been done, so the answer never implies it
72
+ * was not. */
73
+ async function safePoint(after) {
74
+ await captureSignalPoll();
75
+ if (signalled) throw new CaptureInterrupted(`capture interrupted by ${signalled}${after ? ` after ${after}` : ""}`);
76
+ }
77
+
51
78
  // Every flag this program understands. An unknown flag is rejected rather
52
79
  // than ignored, because the fall-through from argument parsing is pass() —
53
80
  // a WRITE. `capture --help` was once a full reconciliation pass under a
@@ -242,7 +269,7 @@ if (args.health) {
242
269
  if (args["reset-cursors"] || args["retry-set-aside"]) {
243
270
  try {
244
271
  const result = args["reset-cursors"]
245
- ? withCaptureLock(() => { resetSourceCursors(root, owner, args.source); return { reset: true, sources: args.source ? [args.source] : CAPTURE_SOURCES }; })
272
+ ? await observingSignals(() => withCaptureLock(() => { resetSourceCursors(root, owner, args.source); return { reset: true, sources: args.source ? [args.source] : CAPTURE_SOURCES }; }, "reset-cursors", "the cursor reset was committed"))
246
273
  : await pass({ retry: true });
247
274
  if (result.skipped) throw new Error("capture lock held; recovery was not performed");
248
275
  if (process.exitCode) throw new Error("recovery failed to release its capture lock");
@@ -309,11 +336,13 @@ function log(...parts) {
309
336
  * in the finally, and a release that did not happen is said so on stderr
310
337
  * with the operator recovery and a nonzero exit status. Likewise an owner
311
338
  * record that could not be written: the lock never silently outlives the
312
- * pass that created it. */
313
- function withCaptureLock(fn) {
339
+ * pass that created it. `command` labels the owner record; `done` names
340
+ * what `fn` committed, for an interruption observed after it returned. */
341
+ async function withCaptureLock(fn, command, done) {
314
342
  let lock;
343
+ await safePoint();
315
344
  try {
316
- lock = acquireCaptureLock(root);
345
+ lock = acquireCaptureLock(root, { command, caller: { entry: captureCommandEntry(), trigger: "manual" } });
317
346
  // Said by the pass that removed it, never quiet, whether or not it then took the lock: a pass that
318
347
  // died holding the lock is worth knowing about.
319
348
  if (lock.reclaimed) reportReclaimedLock({ path: lock.path, ...lock.reclaimed });
@@ -331,7 +360,9 @@ function withCaptureLock(fn) {
331
360
  }
332
361
  try {
333
362
  let result, failure;
334
- try { cleanupCaptureScratch(root, lock); result = fn(); return result; }
363
+ // The callback's last segment is synchronous too: poll once more before
364
+ // its result can become a success answer.
365
+ try { cleanupCaptureScratch(root, lock); await safePoint(); result = await fn(); await safePoint(done); return result; }
335
366
  catch (err) { failure = err; throw err; }
336
367
  finally {
337
368
  try { writeCaptureStatus(root, { pending: Boolean(failure || result?.pending || result?.held || result?.incomplete || result?.failed) }); }
@@ -365,14 +396,15 @@ async function pass({ retry = false, trigger = "manual" } = {}) {
365
396
  loadIgnoreForCommand(root);
366
397
  // Recovery JSON keeps its existing small shape. Never read a later status
367
398
  // file after releasing the lock to reconstruct this pass's counters.
368
- return captureCommandPass(root, { owner, plan: commandPlan(), indexEnabled: !args["no-index"], trigger, retrySetAside: retry }, { log });
399
+ return captureCommandPass(root, { owner, plan: commandPlan(), indexEnabled: !args["no-index"], trigger, retrySetAside: retry }, { log, entry: captureCommandEntry() });
369
400
  }
370
401
 
371
402
  /** A final capture of exact files, one batch per format, under the lock: counts into `outcome`, issues into
372
403
  * `issues`, then the index unless --no-index. → withCaptureLock's answer (`outcome`, or a skip). */
373
- function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, issues) {
374
- return withCaptureLock(() => {
404
+ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, issues, command) {
405
+ return withCaptureLock(async () => {
375
406
  for (const [format, files] of batches) {
407
+ await safePoint();
376
408
  const r = captureSessions(recordStore, { owner: recordOwner, files, format, ignore, final: true });
377
409
  outcome.appended += r.appended;
378
410
  outcome.held += r.held;
@@ -381,6 +413,7 @@ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, is
381
413
  issues.push(...r.issues);
382
414
  }
383
415
  if (!args["no-index"]) { // an earlier append-only pass may have left unindexed turns
416
+ await safePoint();
384
417
  const index = new RecordIndex(recordStore);
385
418
  try {
386
419
  index.update();
@@ -389,7 +422,7 @@ function captureUnderLock(recordStore, recordOwner, batches, ignore, outcome, is
389
422
  }
390
423
  }
391
424
  return outcome;
392
- });
425
+ }, command, "every batch completed");
393
426
  }
394
427
 
395
428
  /** The outcome vocabulary: complete only with no failure, skip, hold or incomplete tail (and, for --home, no
@@ -437,7 +470,7 @@ function fileKind(stat) {
437
470
  }
438
471
 
439
472
  /** → the exit status. */
440
- function fileCapture() {
473
+ async function fileCapture() {
441
474
  const json = Boolean(args.json);
442
475
  const fail = (code, error, extra = {}) => {
443
476
  if (json) console.log(JSON.stringify({ ...extra, status: "failed", complete: false, code, error }, null, 2));
@@ -502,15 +535,19 @@ function fileCapture() {
502
535
  const outcome = { appended: 0, skipped: false, held: 0, incomplete: 0, failed: 0, ignored: 0 };
503
536
  const issues = [];
504
537
  try {
505
- Object.assign(outcome, captureUnderLock(fileStore, fileOwner, [[args.format, [{ path, pinned }]]], ignore, outcome, issues));
538
+ Object.assign(outcome, await captureUnderLock(fileStore, fileOwner, [[args.format, [{ path, pinned }]]], ignore, outcome, issues, "file"));
506
539
  } catch (err) {
507
540
  // A failed pass may have appended part of the file: never claim a count for it.
508
- return fail("E_CAPTURE_FAILED", err.message || String(err), { ...where, sha256, appended: null });
541
+ // An interruption stops only between whole batches, so its count is confirmed.
542
+ return fail("E_CAPTURE_FAILED", err.message || String(err), { ...where, sha256, appended: err instanceof CaptureInterrupted ? outcome.appended : null });
509
543
  }
510
544
  if (process.exitCode) return fail("E_CAPTURE_FAILED", "capture lock release failed; see stderr for recovery", { ...where, sha256 });
511
545
 
512
546
  const stream = `${fileOwner}~${fmt.source}.${sessionId}`;
513
547
  const turns = withReceiptSummaries(fileStore, summary => summary(stream));
548
+ // The summaries are synchronous: a signal during them is still answered.
549
+ try { await safePoint("every batch completed"); }
550
+ catch (err) { return fail("E_CAPTURE_FAILED", err.message, { ...where, sha256, appended: outcome.appended }); }
514
551
  const status = statusOf(outcome);
515
552
  const { lock: _lock, ...counts } = outcome;
516
553
  const receipt = {
@@ -524,7 +561,7 @@ function fileCapture() {
524
561
  } finally { pinned.close(); }
525
562
  }
526
563
 
527
- if (args.file !== undefined || args.format !== undefined || args.json) return finish(fileCapture());
564
+ if (args.file !== undefined || args.format !== undefined || args.json) return finish(await observingSignals(fileCapture));
528
565
 
529
566
  if (args["install-hint"]) {
530
567
  const self = new URL("./capture-hook.mjs", import.meta.url).pathname;
@@ -565,7 +602,7 @@ if (args.status) {
565
602
  // as the OKF harvester can name what it read without timestamps, which tie
566
603
  // and which late capture appends behind. Output is JSON, always: this mode
567
604
  // exists for programs.
568
- if (args.home) {
605
+ if (args.home) await observingSignals(async () => {
569
606
  warnOnStrangerOwner();
570
607
  const unattributed = [];
571
608
  let found = [];
@@ -588,7 +625,7 @@ if (args.home) {
588
625
  if (!formats.has(s.source)) formats.set(s.source, []);
589
626
  formats.get(s.source).push(s);
590
627
  }
591
- Object.assign(outcome, captureUnderLock(store, owner, formats, ignore, outcome, issues));
628
+ Object.assign(outcome, await captureUnderLock(store, owner, formats, ignore, outcome, issues, "home"));
592
629
  withReceiptSummaries(store, summary => {
593
630
  for (const s of found) {
594
631
  const stream = `${owner}~${s.source}.${s.sessionId}`;
@@ -608,13 +645,18 @@ if (args.home) {
608
645
  });
609
646
  }
610
647
  });
648
+ // Summaries are synchronous: a signal that arrived during them is still a
649
+ // signal this command received before answering.
650
+ await safePoint("every batch completed");
611
651
  } catch (err) {
612
652
  error = err.message || String(err);
613
653
  console.error(`capture pass failed: ${error}`);
614
654
  outcome.failed++;
615
655
  // captureSessions can throw after appending part of a directory. Do not
616
656
  // claim zero (or a complete count) for a partially performed failed pass.
617
- outcome.appended = null;
657
+ // An interruption stops only between whole format batches: its count of
658
+ // completed batches is confirmed.
659
+ if (!(err instanceof CaptureInterrupted)) outcome.appended = null;
618
660
  process.exitCode = 1;
619
661
  }
620
662
  if (process.exitCode && !outcome.failed) {
@@ -626,7 +668,7 @@ if (args.home) {
626
668
  ...(error ? { error } : {}), ...(issues.length ? { issues } : {}), ...(unattributed.length ? { unattributed } : {}),
627
669
  }, null, 2));
628
670
  // Let stdout drain naturally, including large session-boundary receipts.
629
- } else {
671
+ }); else {
630
672
 
631
673
  warnOnStrangerOwner();
632
674
  try {
@@ -29,6 +29,7 @@ import { dirname, isAbsolute, join, resolve } from "node:path";
29
29
  import { fileURLToPath } from "node:url";
30
30
  import { captureDefaultRootPlan } from "../lib/capture-default-roots.mjs";
31
31
  import { captureCommandPass } from "../lib/capture-command-output.mjs";
32
+ import { captureCommandEntry } from "../lib/capture-command.mjs";
32
33
  import { IgnoreError, loadIgnore } from "../lib/ignore.mjs";
33
34
  import { preflightCaptureService, applyCaptureService, captureSetupSnapshot, recheckCaptureSetup, writeCaptureSetup } from "../lib/capture-service-install.mjs";
34
35
  import { captureRemedyCommand } from "../lib/capture-health.mjs";
@@ -249,7 +250,7 @@ try {
249
250
  console.log("running first capture pass (the initial one can take minutes)...");
250
251
  captureStarted = true;
251
252
  try {
252
- const pass = await captureCommandPass(root, { owner, plan, indexEnabled: true, trigger: "setup", retrySetAside: false });
253
+ const pass = await captureCommandPass(root, { owner, plan, indexEnabled: true, trigger: "setup", retrySetAside: false }, { entry: captureCommandEntry() });
253
254
  summary.firstPass = pass.skipped ? "skipped: another pass holds the record root" : `appended ${pass.appended}, pending ${pass.pending ? "yes" : "no"}`;
254
255
  } catch (error) { summary.firstPass = `failed: ${oneLine(error.message)}`; throw error; }
255
256
  }