@awebai/oats 0.65.0 → 0.67.1

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 (75) hide show
  1. package/README.md +11 -5
  2. package/bin/oats.mjs +74 -20
  3. package/docs/capabilities.md +4 -4
  4. package/docs/capability-manifest.schema.json +1 -1
  5. package/docs/desktop-cli-api.md +222 -10
  6. package/docs/desktop.md +101 -22
  7. package/docs/implementation.md +16 -6
  8. package/docs/integrations.md +1 -1
  9. package/docs/official-catalog.md +2 -2
  10. package/docs/packages.md +7 -7
  11. package/docs/release-lane.md +16 -0
  12. package/docs/release-notes/v0.66.0.md +183 -0
  13. package/docs/release-notes/v0.67.0.md +366 -0
  14. package/docs/release-notes/v0.67.1.md +64 -0
  15. package/docs/servers.md +5 -4
  16. package/docs/souls-and-instances.md +20 -3
  17. package/docs/tui.md +658 -143
  18. package/docs/upgrading.md +107 -25
  19. package/docs/workspaces.md +9 -2
  20. package/lib/capability-contract.mjs +2 -2
  21. package/lib/core.mjs +126 -54
  22. package/lib/deployments.mjs +21 -5
  23. package/lib/instance-color.mjs +58 -0
  24. package/lib/instance-inspect.mjs +107 -23
  25. package/lib/instance-lifecycle.mjs +21 -1
  26. package/lib/instance-naming.mjs +187 -0
  27. package/lib/instance-resolution.mjs +5 -1
  28. package/lib/materialize.mjs +62 -11
  29. package/lib/servers.mjs +15 -6
  30. package/lib/soul-composition.mjs +7 -3
  31. package/package-catalog.json +2 -2
  32. package/package.json +1 -1
  33. package/packages/client/cli-adapter.mjs +37 -5
  34. package/packages/client/cli-locator.mjs +2 -2
  35. package/packages/client/composed-gate.mjs +10 -2
  36. package/packages/client/deployment-data.mjs +5 -0
  37. package/packages/client/deployment-identity.mjs +40 -0
  38. package/packages/client/deployment-panel.mjs +3 -1
  39. package/packages/client/inspect-boundary.mjs +11 -7
  40. package/packages/client/inspect-cache.mjs +2 -2
  41. package/packages/client/instance-name.mjs +28 -0
  42. package/packages/client/instance-presentation.mjs +11 -0
  43. package/packages/client/keymap.mjs +99 -11
  44. package/packages/client/keys-file.mjs +122 -0
  45. package/packages/client/machine-contract.mjs +1 -5
  46. package/packages/client/own-codes.mjs +4 -2
  47. package/packages/client/panel-views.mjs +62 -9
  48. package/packages/client/spawn-naming.mjs +31 -0
  49. package/packages/client/spawn-preview-cli.mjs +22 -7
  50. package/packages/client/spawn-preview-contract.mjs +24 -0
  51. package/packages/client/spawn-preview-facts.mjs +8 -4
  52. package/packages/client/spawn-preview.mjs +47 -2
  53. package/packages/record/bin/setup.mjs +10 -2
  54. package/packages/record/docs/capture-service.md +45 -6
  55. package/packages/record/lib/capture-service-install.mjs +6 -95
  56. package/packages/record/lib/capture-setup-write.mjs +233 -0
  57. package/packages/tui/README.md +9 -8
  58. package/packages/tui/lib/actions.mjs +108 -64
  59. package/packages/tui/lib/client.mjs +8 -3
  60. package/packages/tui/lib/config.mjs +208 -26
  61. package/packages/tui/lib/main.mjs +91 -20
  62. package/packages/tui/lib/model.mjs +167 -61
  63. package/packages/tui/lib/read.mjs +53 -1
  64. package/packages/tui/lib/store.mjs +156 -47
  65. package/packages/tui/lib/term/keys.mjs +150 -34
  66. package/packages/tui/lib/term/kitty.mjs +223 -0
  67. package/packages/tui/lib/term/through.mjs +174 -27
  68. package/packages/tui/lib/term/tty.mjs +43 -12
  69. package/packages/tui/lib/views/frame.mjs +158 -79
  70. package/packages/tui/lib/views/help.mjs +143 -21
  71. package/packages/tui/lib/views/instances.mjs +59 -20
  72. package/packages/tui/lib/views/palette.mjs +14 -4
  73. package/packages/tui/lib/views/souls.mjs +2 -2
  74. package/packages/tui/lib/views/switcher.mjs +6 -1
  75. package/skills/oats-getting-started/SKILL.md +107 -34
@@ -8,99 +8,10 @@ import { basename, dirname, isAbsolute, join } from "node:path";
8
8
  import { CAPTURE_POLICY } from "./capture-budget.mjs";
9
9
  import { capturePendingActivationName, captureServiceDefinition, captureServiceLabel, captureServiceUnit, captureServiceTimer } from "./capture-service-definition.mjs";
10
10
  import { captureServiceOwnership, captureServiceArgvOwnership } from "./capture-service-ownership.mjs";
11
+ import { captureSetupSnapshot, recheckCaptureSetup, recheckCaptureSetupParents, writeCaptureSetup } from "./capture-setup-write.mjs";
12
+ export { captureSetupSnapshot, recheckCaptureSetup, writeCaptureSetup } from "./capture-setup-write.mjs";
11
13
 
12
14
  export const serviceShellWord = value => /^[A-Za-z0-9_./:@%+,-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
13
- const identity = stat => [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
14
- function parents(path) {
15
- const records = [];
16
- for (let directory = dirname(path); ; directory = dirname(directory)) {
17
- let stat;
18
- try { stat = fs.lstatSync(directory); }
19
- catch (error) { if (error.code !== "ENOENT") throw error; }
20
- if (stat) {
21
- let target = null;
22
- if (stat.isSymbolicLink()) {
23
- try { target = fs.statSync(directory); }
24
- catch (error) { if (error.code !== "ENOENT") throw error; }
25
- }
26
- // Even a dangling ancestor link has an identity to retain. Its missing
27
- // target must not turn a later retargeting into ordinary directory creation.
28
- records.push([directory, `${stat.dev}:${stat.ino}:${stat.mode}`, stat.isSymbolicLink() ? fs.readlinkSync(directory) : null,
29
- target ? `${target.dev}:${target.ino}:${target.mode}` : null]);
30
- } else records.push([directory, null, null, null]);
31
- if (dirname(directory) === directory) return records;
32
- }
33
- }
34
-
35
- export function captureSetupSnapshot(path) {
36
- const ancestry = parents(path);
37
- let stat;
38
- try { stat = fs.lstatSync(path); }
39
- catch (error) { if (error.code === "ENOENT") return { path, kind: "absent", parents: ancestry }; throw error; }
40
- const before = identity(stat);
41
- let bytes, link;
42
- if (stat.isSymbolicLink()) link = fs.readlinkSync(path);
43
- else {
44
- if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error(`refusing nonregular or oversized setup target ${path}`);
45
- const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
46
- try {
47
- if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while opening ${path}`);
48
- bytes = fs.readFileSync(fd);
49
- if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while reading ${path}`);
50
- } finally { fs.closeSync(fd); }
51
- }
52
- if (identity(fs.lstatSync(path)) !== before) throw new Error(`setup target changed while reading ${path}`);
53
- return { path, kind: link === undefined ? "file" : "link", identity: before, bytes, link, parents: ancestry };
54
- }
55
-
56
- function recheckParents(snapshot, current, createdParents = new Map()) {
57
- if (snapshot.parents.some(record => {
58
- const expected = record[1] === null ? createdParents.get(record[0]) ?? record : record;
59
- return !current.parents.some(now => JSON.stringify(now) === JSON.stringify(expected));
60
- }))
61
- throw new Error(`setup target parent changed since preflight: ${snapshot.path}; re-run setup`);
62
- }
63
- export function recheckCaptureSetup(snapshot, createdParents = new Map()) {
64
- recheckParents(snapshot, { parents: parents(snapshot.path) }, createdParents);
65
- const current = captureSetupSnapshot(snapshot.path);
66
- recheckParents(snapshot, current, createdParents);
67
- if (current.kind !== snapshot.kind || current.identity !== snapshot.identity || current.link !== snapshot.link ||
68
- (snapshot.bytes && !snapshot.bytes.equals(current.bytes))) throw new Error(`setup target changed since preflight: ${snapshot.path}; re-run setup`);
69
- }
70
-
71
- export function writeCaptureSetup(snapshot, contents, createdParents = new Map()) {
72
- recheckCaptureSetup(snapshot, createdParents);
73
- // A missing ancestor is evidence, not permission to follow whatever appears
74
- // there later. Create one level at a time, refusing EEXIST, and share only
75
- // this apply's observed non-link directory identities with subsequent writes.
76
- for (const record of [...snapshot.parents].reverse()) {
77
- if (record[1] !== null || createdParents.has(record[0])) continue;
78
- recheckCaptureSetup(snapshot, createdParents);
79
- fs.mkdirSync(record[0]);
80
- const stat = fs.lstatSync(record[0]);
81
- if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`setup created parent changed: ${record[0]}; re-run setup`);
82
- createdParents.set(record[0], [record[0], `${stat.dev}:${stat.ino}:${stat.mode}`, null, null]);
83
- }
84
- recheckCaptureSetup(snapshot, createdParents);
85
- const temporary = `${snapshot.path}.tmp-${randomUUID()}`;
86
- let temporaryIdentity;
87
- try {
88
- fs.writeFileSync(temporary, contents, { flag: "wx", mode: 0o600 });
89
- temporaryIdentity = identity(fs.lstatSync(temporary));
90
- recheckCaptureSetup(snapshot, createdParents);
91
- fs.renameSync(temporary, snapshot.path);
92
- } finally {
93
- // A refused ancestor replacement also revokes cleanup through that path.
94
- // Leave the original scratch file rather than unlink an unrelated target.
95
- let safe = false;
96
- try {
97
- recheckParents(snapshot, { parents: parents(snapshot.path) }, createdParents);
98
- safe = temporaryIdentity !== undefined && identity(fs.lstatSync(temporary)) === temporaryIdentity;
99
- } catch { /* absent scratch or changed ancestry: no pathname cleanup */ }
100
- if (safe) fs.unlinkSync(temporary);
101
- }
102
- }
103
-
104
15
  const detail = result => [result.error?.message, result.signal && `signal ${result.signal}`, result.stderr?.trim(),
105
16
  result.status !== null && result.status !== undefined && `exit ${result.status}`].filter(Boolean).join("; ") || "no exit status returned";
106
17
  const manager = (command, argv) => spawnSync(command, argv, { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024 });
@@ -249,7 +160,7 @@ export function preflightCaptureService({ platform, node, request, setupCommand,
249
160
  export function applyCaptureService(plan, createdParents = new Map()) {
250
161
  const applied = [];
251
162
  try { return applyCaptureServiceSteps(plan, createdParents, applied); }
252
- catch (error) { if (applied.length) error.applied = [...applied]; throw error; }
163
+ catch (error) { if (applied.length) error.applied = [...applied, ...(error.applied ?? [])]; throw error; }
253
164
  }
254
165
 
255
166
  function applyCaptureServiceSteps(plan, createdParents, applied) {
@@ -309,7 +220,7 @@ function applyCaptureServiceSteps(plan, createdParents, applied) {
309
220
  if (plan.platform === "darwin") {
310
221
  if (plan.changed && current.registered) command("launchctl", ["bootout", plan.target]);
311
222
  for (const file of files) if (file.changed) writeDefinition(file);
312
- recheckParents(files[0].snapshot, { parents: parents(files[0].path) }, createdParents);
223
+ recheckCaptureSetupParents(files[0].snapshot, createdParents);
313
224
  fs.mkdirSync(join(plan.request.plan.home, "Library", "Logs"), { recursive: true });
314
225
  if (plan.disabled) command("launchctl", ["enable", plan.target]);
315
226
  if (plan.changed || !current.registered) command("launchctl", ["bootstrap", plan.domain, files[0].path]);
@@ -334,7 +245,7 @@ function applyCaptureServiceSteps(plan, createdParents, applied) {
334
245
  for (const file of files) {
335
246
  if (plan.disabled && file.snapshot.kind === "link" && file.snapshot.link === "/dev/null") {
336
247
  const now = captureSetupSnapshot(file.path);
337
- recheckParents(file.snapshot, now, createdParents);
248
+ recheckCaptureSetupParents(file.snapshot, createdParents, now);
338
249
  if (now.kind === "absent") file.snapshot = now;
339
250
  }
340
251
  if (file.changed) writeDefinition(file);
@@ -351,7 +262,7 @@ function applyCaptureServiceSteps(plan, createdParents, applied) {
351
262
  }
352
263
  for (const file of files) {
353
264
  const final = captureSetupSnapshot(file.path);
354
- recheckParents(file.snapshot, final, createdParents);
265
+ recheckCaptureSetupParents(file.snapshot, createdParents, final);
355
266
  if (final.kind !== "file" || !final.bytes.equals(Buffer.from(file.contents))) throw new Error(`capture definition changed during activation: ${file.path}; re-run setup`);
356
267
  }
357
268
  if (marked || plan.pending && !plan.pending.stale) {
@@ -0,0 +1,233 @@
1
+ // Checked publication for setup-owned files. Kept separate from service policy
2
+ // so other setup callers can share preflight, ancestry and durability guards.
3
+ import fs from "node:fs";
4
+ import { randomUUID } from "node:crypto";
5
+ import { dirname } from "node:path";
6
+
7
+ const identity = stat => [stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeMs, stat.ctimeMs].join(":");
8
+ function parents(path) {
9
+ const records = [];
10
+ for (let directory = dirname(path); ; directory = dirname(directory)) {
11
+ let stat;
12
+ try { stat = fs.lstatSync(directory); }
13
+ catch (error) { if (error.code !== "ENOENT") throw error; }
14
+ if (stat) {
15
+ let target = null;
16
+ if (stat.isSymbolicLink()) {
17
+ try { target = fs.statSync(directory); }
18
+ catch (error) { if (error.code !== "ENOENT") throw error; }
19
+ }
20
+ // Even a dangling ancestor link has an identity to retain. Its missing
21
+ // target must not turn a later retargeting into ordinary directory creation.
22
+ records.push([directory, `${stat.dev}:${stat.ino}:${stat.mode}`, stat.isSymbolicLink() ? fs.readlinkSync(directory) : null,
23
+ target ? `${target.dev}:${target.ino}:${target.mode}` : null]);
24
+ } else records.push([directory, null, null, null]);
25
+ if (dirname(directory) === directory) return records;
26
+ }
27
+ }
28
+
29
+ export function captureSetupSnapshot(path) {
30
+ const ancestry = parents(path);
31
+ let stat;
32
+ try { stat = fs.lstatSync(path); }
33
+ catch (error) { if (error.code === "ENOENT") return { path, kind: "absent", parents: ancestry }; throw error; }
34
+ const before = identity(stat);
35
+ let bytes, link;
36
+ if (stat.isSymbolicLink()) link = fs.readlinkSync(path);
37
+ else {
38
+ if (!stat.isFile() || stat.size > 1024 * 1024) throw new Error(`refusing nonregular or oversized setup target ${path}`);
39
+ const fd = fs.openSync(path, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
40
+ let failure;
41
+ try {
42
+ if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while opening ${path}`);
43
+ bytes = fs.readFileSync(fd);
44
+ if (identity(fs.fstatSync(fd)) !== before) throw new Error(`setup target changed while reading ${path}`);
45
+ } catch (error) { failure = error; }
46
+ try { fs.closeSync(fd); }
47
+ catch (error) {
48
+ if (failure) throw new AggregateError([failure, error], `${failure.message}; setup target close failed: ${error.message}`, { cause: failure });
49
+ throw error;
50
+ }
51
+ if (failure) throw failure;
52
+ }
53
+ if (identity(fs.lstatSync(path)) !== before) throw new Error(`setup target changed while reading ${path}`);
54
+ return { path, kind: link === undefined ? "file" : "link", identity: before, bytes, link, parents: ancestry };
55
+ }
56
+
57
+ function recheckParents(snapshot, current, createdParents = new Map()) {
58
+ if (snapshot.parents.some(record => {
59
+ const expected = record[1] === null ? createdParents.get(record[0]) ?? record : record;
60
+ return !current.parents.some(now => JSON.stringify(now) === JSON.stringify(expected));
61
+ }))
62
+ throw new Error(`setup target parent changed since preflight: ${snapshot.path}; re-run setup`);
63
+ }
64
+ export function recheckCaptureSetup(snapshot, createdParents = new Map()) {
65
+ recheckParents(snapshot, { parents: parents(snapshot.path) }, createdParents);
66
+ const current = captureSetupSnapshot(snapshot.path);
67
+ recheckParents(snapshot, current, createdParents);
68
+ if (current.kind !== snapshot.kind || current.identity !== snapshot.identity || current.link !== snapshot.link ||
69
+ (snapshot.bytes && !snapshot.bytes.equals(current.bytes))) throw new Error(`setup target changed since preflight: ${snapshot.path}; re-run setup`);
70
+ }
71
+
72
+ // Service apply also checks ancestry after its own expected target changes.
73
+ export function recheckCaptureSetupParents(snapshot, createdParents = new Map(), current = { parents: parents(snapshot.path) }) {
74
+ recheckParents(snapshot, current, createdParents);
75
+ }
76
+
77
+ const directoryIdentity = stat => `${stat.dev}:${stat.ino}:${stat.mode}`;
78
+ // Rename may change ctime. The final path must still name the written inode,
79
+ // mode, size and mtime; pre-rename checks retain the complete identity.
80
+ const publishedIdentity = stat => [directoryIdentity(stat), stat.size, stat.mtimeMs].join(":");
81
+
82
+ // The fourth argument is private fs-operation fault injection. Production has
83
+ // no switch for it. Snapshots and createdParents retain their caller semantics.
84
+ export function writeCaptureSetup(snapshot, contents, createdParents = new Map(), operations = fs) {
85
+ let stage = "preflight recheck", published = false, cause;
86
+ let temporary, temporaryIdentity, temporaryPublishedIdentity, temporaryNode, fileFd = null, directoryFd = null, writing = false;
87
+ const cleanupErrors = [], madeParents = [];
88
+ const recheck = () => recheckCaptureSetup(snapshot, createdParents);
89
+ const recheckAncestry = () => recheckCaptureSetupParents(snapshot, createdParents);
90
+ const changed = path => new Error(`setup publication identity changed: ${path}; re-run setup`);
91
+ // Detach before close: a close error does not authorize retrying a descriptor
92
+ // whose state may be unknown (and whose number might since have been reused).
93
+ const closeFile = () => { const fd = fileFd; fileFd = null; operations.closeSync(fd); };
94
+ const closeDirectory = () => { const fd = directoryFd; directoryFd = null; operations.closeSync(fd); };
95
+ const checkDirectory = path => {
96
+ recheckAncestry();
97
+ const descriptor = operations.fstatSync(directoryFd), current = operations.statSync(path);
98
+ if (!descriptor.isDirectory() || directoryIdentity(descriptor) !== directoryIdentity(current)) throw changed(path);
99
+ recheckAncestry();
100
+ };
101
+ const openDirectory = path => {
102
+ recheckAncestry();
103
+ // Existing approved ancestor links remain allowed: both their link and
104
+ // resolved identities are retained by the ancestry recheck.
105
+ directoryFd = operations.openSync(path, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY);
106
+ checkDirectory(path);
107
+ };
108
+ const checkTemporary = () => {
109
+ recheckAncestry();
110
+ const descriptor = operations.fstatSync(fileFd);
111
+ let current;
112
+ try { current = operations.lstatSync(temporary); }
113
+ catch (error) { if (error.code === "ENOENT") throw changed(temporary); throw error; }
114
+ if (!descriptor.isFile() || (descriptor.mode & 0o777) !== 0o600 ||
115
+ directoryIdentity(descriptor) !== temporaryNode || identity(descriptor) !== identity(current)) throw changed(temporary);
116
+ temporaryIdentity = identity(descriptor);
117
+ temporaryPublishedIdentity = publishedIdentity(descriptor);
118
+ recheckAncestry();
119
+ };
120
+ try {
121
+ recheck();
122
+ // Missing ancestors are evidence, not permission to adopt an intervening
123
+ // mkdir/link. Publish each new directory entry durably before its child.
124
+ for (const record of [...snapshot.parents].reverse()) {
125
+ if (record[1] !== null || createdParents.has(record[0])) continue;
126
+ stage = `create parent ${record[0]}`;
127
+ recheck();
128
+ operations.mkdirSync(record[0]);
129
+ madeParents.push(record[0]);
130
+ const stat = operations.lstatSync(record[0]);
131
+ if (!stat.isDirectory() || stat.isSymbolicLink()) throw changed(record[0]);
132
+ createdParents.set(record[0], [record[0], directoryIdentity(stat), null, null]);
133
+ try {
134
+ const parent = dirname(record[0]);
135
+ stage = `created-parent directory open ${parent}`;
136
+ openDirectory(parent);
137
+ stage = `created-parent directory fsync ${parent}`;
138
+ operations.fsyncSync(directoryFd);
139
+ checkDirectory(parent);
140
+ stage = `created-parent directory close ${parent}`;
141
+ closeDirectory();
142
+ } catch (error) {
143
+ // A failed durability step must not silently authorize another caller
144
+ // to reuse this directory through the shared per-apply map.
145
+ createdParents.delete(record[0]);
146
+ throw error;
147
+ }
148
+ }
149
+ stage = "temporary recheck";
150
+ recheck();
151
+ temporary = `${snapshot.path}.tmp-${randomUUID()}`;
152
+ stage = "temporary open";
153
+ fileFd = operations.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
154
+ const opened = operations.fstatSync(fileFd);
155
+ temporaryNode = directoryIdentity(opened);
156
+ temporaryIdentity = identity(opened);
157
+ checkTemporary();
158
+ recheck();
159
+ stage = "temporary write";
160
+ writing = true;
161
+ operations.writeFileSync(fileFd, contents);
162
+ checkTemporary();
163
+ writing = false;
164
+ stage = "file fsync";
165
+ operations.fsyncSync(fileFd);
166
+ checkTemporary();
167
+ recheck();
168
+ stage = "file close";
169
+ closeFile();
170
+ stage = "publication directory open";
171
+ openDirectory(dirname(snapshot.path));
172
+ stage = "rename recheck";
173
+ recheck();
174
+ if (identity(operations.lstatSync(temporary)) !== temporaryIdentity) throw changed(temporary);
175
+ checkDirectory(dirname(snapshot.path));
176
+ stage = "rename";
177
+ operations.renameSync(temporary, snapshot.path);
178
+ published = true;
179
+ stage = "directory fsync";
180
+ checkDirectory(dirname(snapshot.path));
181
+ if (publishedIdentity(operations.lstatSync(snapshot.path)) !== temporaryPublishedIdentity) throw changed(snapshot.path);
182
+ operations.fsyncSync(directoryFd);
183
+ checkDirectory(dirname(snapshot.path));
184
+ if (publishedIdentity(operations.lstatSync(snapshot.path)) !== temporaryPublishedIdentity) throw changed(snapshot.path);
185
+ stage = "directory close";
186
+ closeDirectory();
187
+ } catch (error) {
188
+ cause = error;
189
+ if (stage === "rename" && !published) {
190
+ // A refused rename normally leaves the saved target intact. If that
191
+ // cannot be re-established, report uncertainty rather than rollback.
192
+ try { recheck(); } catch { published = true; }
193
+ }
194
+ } finally {
195
+ // Capture partial-write identity through the still-owned descriptor before
196
+ // closing, so a write fault can clean its own scratch without adopting a
197
+ // substituted pathname. Do not refresh identity after a completed write.
198
+ if (fileFd !== null) {
199
+ if (writing) {
200
+ try {
201
+ const stat = operations.fstatSync(fileFd);
202
+ if (directoryIdentity(stat) === temporaryNode) temporaryIdentity = identity(stat);
203
+ } catch (error) { cleanupErrors.push(error); }
204
+ }
205
+ try { closeFile(); } catch (error) { cleanupErrors.push(error); }
206
+ }
207
+ if (directoryFd !== null) {
208
+ try { closeDirectory(); } catch (error) { cleanupErrors.push(error); }
209
+ }
210
+ if (!published && temporaryIdentity !== undefined) {
211
+ let safe = false;
212
+ // A refused ancestor replacement revokes pathname cleanup. Never remove
213
+ // the new target after rename, even if a later sync/close/recheck failed.
214
+ try { recheckAncestry(); safe = true; }
215
+ catch (error) { cleanupErrors.push(error); } // cleanup was refused, not silently successful
216
+ if (safe) {
217
+ try {
218
+ if (identity(operations.lstatSync(temporary)) === temporaryIdentity) operations.unlinkSync(temporary);
219
+ } catch (error) { if (error.code !== "ENOENT") cleanupErrors.push(error); }
220
+ }
221
+ }
222
+ }
223
+ if (cause || cleanupErrors.length) {
224
+ const primary = cause ?? cleanupErrors.shift();
225
+ const state = published ? "publication may have occurred; durability was not established" : "target was not published by this write";
226
+ const cleanup = cleanupErrors.length ? `; cleanup failed: ${cleanupErrors.map(error => error.message).join("; ")}` : "";
227
+ const error = new Error(`setup write failed for ${snapshot.path} at ${stage}: ${primary.message}; ${state}${cleanup}`, { cause: primary });
228
+ Object.assign(error, { path: snapshot.path, stage, published, cleanupErrors,
229
+ applied: [...madeParents.map(path => `created setup parent ${path} (write failed at ${stage}; inspect its durability)`),
230
+ ...(published ? [`${snapshot.path}: publication may have occurred at ${stage}; durability was not established`] : [])] });
231
+ throw error;
232
+ }
233
+ }
@@ -21,21 +21,22 @@ never does.
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
23
  | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList` |
24
- | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one |
25
- | `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
24
+ | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
+ | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
27
  | `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
28
- | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
28
+ | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the identity reads of this computer's listed deployments the run has not opened (`createIdentityReads`: one at a time, under a budget, never on a timer), the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), the one look at the file system the switcher needs (whether a picked row is a deployment), and `startExec`, the exec of the list's read before the terminal is taken |
29
29
  | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
30
- | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
31
- | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
30
+ | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows (a workspace and a line per deployment of it, matched by the shared `listedViews` over the served deployments and the identities the reads learned), by calling the shared readers: pure, no cell position |
31
+ | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock; under the kitty keyboard protocol it reads a `CSI … u` key as its legacy bytes read, a chord as its own id |
32
+ | `lib/term/kitty.mjs` | the kitty keyboard protocol: the flags asked for, a `CSI … u` key read, and the bytes the same key sends without the protocol (`legacyBytes`), which is what an agent is typed |
32
33
  | `lib/term/width.mjs` | the cells a grapheme takes |
33
34
  | `lib/term/text.mjs` | safe text, the only thing the screen draws: `lit()` and `shown()` |
34
35
  | `lib/term/style.mjs` | style values: the TUI's own (the sixteen ANSI colours and four attributes) and an agent's (its colours, 256 and RGB included, and attributes, from a capture) |
35
36
  | `lib/term/capture.mjs` | a pane's capture (`capture-pane -e -N`) to rows of cells: characters and an allowlist of SGR, every other sequence and control dropped |
36
- | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
37
+ | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key, a chord and a bracketed paste out of them and, under the kitty keyboard protocol, types every other key as its legacy bytes |
37
38
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
38
- | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
39
+ | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame; the kitty keyboard protocol pushed, asked about and popped on every way out |
39
40
  | `lib/views/` | pure functions from the model and a size to rows of spans: the frame (the sidebar: its title, the accordion of the three views and the cheat sheet; the main area beside it), the list, the detail, the Capabilities view (`capabilities.mjs`), the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
40
41
 
41
42
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
@@ -46,7 +47,7 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
46
47
  one dynamic import where `bin/oats.mjs` dispatches the word.
47
48
  - Only `term/screen.mjs` and `term/tty.mjs` write an ESC byte in a string,
48
49
  and only they write to the terminal. `term/through.mjs` (the back key's
49
- bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
50
+ bytes), `term/kitty.mjs` (a key's legacy bytes) and `lib/panel.mjs` (the paste marks it types into the agent's
50
51
  pane) hold theirs as numbers. Views are pure: no IO, no clock, no escape
51
52
  bytes.
52
53
  - No function of this package decodes a kernel answer, groups or orders