overvues 0.0.1 → 0.4.10

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 (78) hide show
  1. package/README.md +58 -2
  2. package/dist/ansi.js +24 -0
  3. package/dist/attach-client.js +586 -0
  4. package/dist/auth-connect-browser.js +112 -0
  5. package/dist/auth-connect.js +306 -0
  6. package/dist/browser-bootstrap.js +190 -0
  7. package/dist/browser-loopback.js +289 -0
  8. package/dist/build-identity.js +6 -0
  9. package/dist/codex-reviewer-apparmor.json +4 -0
  10. package/dist/codex-reviewer-seccomp.json +1238 -0
  11. package/dist/codex-runtime-protocol.js +1 -0
  12. package/dist/codex-subscription.js +53 -0
  13. package/dist/config.js +297 -0
  14. package/dist/connect-comparison-code.js +26 -0
  15. package/dist/development-runner.js +109 -0
  16. package/dist/dns-doctor.js +390 -0
  17. package/dist/docker-names.js +47 -0
  18. package/dist/doctor.js +114 -0
  19. package/dist/gadget-job.js +804 -0
  20. package/dist/health-check.js +112 -0
  21. package/dist/help.js +71 -0
  22. package/dist/host-auth.js +22 -0
  23. package/dist/host-diagnostics.js +20 -0
  24. package/dist/host-runtime-identity.js +39 -0
  25. package/dist/host-runtime-metadata.js +56 -0
  26. package/dist/host-service.js +377 -0
  27. package/dist/host-stack.js +484 -0
  28. package/dist/host-supervisor.js +237 -0
  29. package/dist/host-update.js +387 -0
  30. package/dist/hub-address.js +100 -0
  31. package/dist/hub-client.js +459 -0
  32. package/dist/hub-kind.js +88 -0
  33. package/dist/identity.js +73 -0
  34. package/dist/index.js +185 -0
  35. package/dist/init.js +295 -0
  36. package/dist/isolated-run-cache.js +116 -0
  37. package/dist/local-stack.js +685 -0
  38. package/dist/machine-capacity.js +128 -0
  39. package/dist/managed-runner-image.js +13 -0
  40. package/dist/os-acted-record.js +49 -0
  41. package/dist/os-adapter.js +8190 -0
  42. package/dist/os-command.js +292 -0
  43. package/dist/os-handoff.js +274 -0
  44. package/dist/os-keychain.js +247 -0
  45. package/dist/os-machine.js +818 -0
  46. package/dist/os-owner.js +61 -0
  47. package/dist/os-private-file.js +98 -0
  48. package/dist/os-protocol.js +468 -0
  49. package/dist/os-session-store.js +133 -0
  50. package/dist/os-status.js +102 -0
  51. package/dist/picker.js +863 -0
  52. package/dist/portable-workspace-capability.js +60 -0
  53. package/dist/project-environment-capability.js +62 -0
  54. package/dist/project-environment.js +28 -0
  55. package/dist/project-preparation.js +134 -0
  56. package/dist/readiness.js +28 -0
  57. package/dist/redaction.js +27 -0
  58. package/dist/reviewer-isolation-capability.js +61 -0
  59. package/dist/runner-api-auth.js +80 -0
  60. package/dist/runner-command-fence.js +536 -0
  61. package/dist/runner-inspection.js +57 -0
  62. package/dist/runner-inventory.js +587 -0
  63. package/dist/runner-server.js +2520 -0
  64. package/dist/runner-session.js +470 -0
  65. package/dist/runner-slug-folder.js +39 -0
  66. package/dist/runner-slug.js +40 -0
  67. package/dist/setup.js +139 -0
  68. package/dist/shutdown.js +102 -0
  69. package/dist/splash.js +65 -0
  70. package/dist/staged-workspaces.js +441 -0
  71. package/dist/staging-disk.js +97 -0
  72. package/dist/terminal-lane.js +339 -0
  73. package/dist/terminal-recovery.js +502 -0
  74. package/licenses/capnweb.txt +23 -0
  75. package/licenses/moby-profiles.txt +212 -0
  76. package/licenses/ws.txt +22 -0
  77. package/package.json +28 -7
  78. package/cli.js +0 -2
@@ -0,0 +1,536 @@
1
+ import { existsSync, linkSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
2
+ import { resolve } from "node:path";
3
+ import { LOCAL_STATE_DIR } from "./config.js";
4
+ import { caseSafeSlugFolderName, findExactDirectoryEntry } from "./runner-slug-folder.js";
5
+ import { dockerNamePattern } from "./docker-names.js";
6
+ export const RUNNER_COMMAND_PROTOCOL = 1;
7
+ /** The names a slug's workspace volume may have: its default or a staged one. */
8
+ const WORKSPACE_VOLUME_NAME = dockerNamePattern("ws-[A-Za-z0-9_.-]{1,200}");
9
+ export function isWorkspaceVolumeName(value) {
10
+ return typeof value === "string" && WORKSPACE_VOLUME_NAME.test(value);
11
+ }
12
+ export class RunnerCommandFenceError extends Error {
13
+ code;
14
+ currentCommandGeneration;
15
+ status = 409;
16
+ constructor(message, code, currentCommandGeneration) {
17
+ super(message);
18
+ this.code = code;
19
+ this.currentCommandGeneration = currentCommandGeneration;
20
+ this.name = "RunnerCommandFenceError";
21
+ }
22
+ }
23
+ function isDesiredState(value) {
24
+ return value === "running" || value === "stopped" || value === "absent";
25
+ }
26
+ function normalizeRecord(value, expectedSlug) {
27
+ if (!value || typeof value !== "object") {
28
+ throw new RunnerCommandFenceError("Stored runner command fence is invalid.", "runner_command_conflict");
29
+ }
30
+ const record = value;
31
+ if (record.version !== 1
32
+ || typeof record.slug !== "string"
33
+ || (expectedSlug !== undefined && record.slug !== expectedSlug)
34
+ || !Number.isSafeInteger(record.commandGeneration)
35
+ || (record.commandGeneration ?? 0) <= 0
36
+ || typeof record.operationId !== "string"
37
+ || !record.operationId.trim()
38
+ || !isDesiredState(record.desiredState)
39
+ || (record.phase !== "accepted" && record.phase !== "applied")
40
+ || typeof record.updatedAt !== "string") {
41
+ throw new RunnerCommandFenceError("Stored runner command fence is invalid.", "runner_command_conflict");
42
+ }
43
+ return record;
44
+ }
45
+ /** The folder name runners before this one gave a slug's fence: the slug in base64url. */
46
+ function legacyFenceFolderName(slug) {
47
+ return Buffer.from(slug, "utf8").toString("base64url");
48
+ }
49
+ /** Whether a fence folder name is the `<lowercased slug>+<hash>` form rather than base64url. */
50
+ function isCaseSafeFolderName(name) {
51
+ return name.includes("+");
52
+ }
53
+ /**
54
+ * The slugs whose workspace volume record exists but cannot be read. A
55
+ * base64url folder names its slug; a `<lowercased slug>+<hash>` folder does
56
+ * not say which capitals the slug had, so a slug is matched by its folder name.
57
+ */
58
+ export class UnreadableFenceSlugs {
59
+ slugs;
60
+ folderNames;
61
+ constructor(slugs, folderNames) {
62
+ this.slugs = slugs;
63
+ this.folderNames = folderNames;
64
+ }
65
+ has(slug) {
66
+ return this.slugs.has(slug) || this.folderNames.has(caseSafeSlugFolderName(slug));
67
+ }
68
+ get size() {
69
+ return this.slugs.size + this.folderNames.size;
70
+ }
71
+ }
72
+ function normalizeWorkspaceSyncedStopProof(value, expectedSlug) {
73
+ if (!value || typeof value !== "object") {
74
+ throw new RunnerCommandFenceError("Stored workspace persistence proof is invalid.", "runner_command_conflict");
75
+ }
76
+ const proof = value;
77
+ const runnerGeneration = proof.runnerCommandGeneration ?? null;
78
+ if (proof.version !== 1
79
+ || typeof proof.slug !== "string"
80
+ || (expectedSlug !== undefined && proof.slug !== expectedSlug)
81
+ || !Number.isSafeInteger(proof.stopCommandGeneration)
82
+ || (proof.stopCommandGeneration ?? 0) <= 0
83
+ || typeof proof.stopOperationId !== "string"
84
+ || !proof.stopOperationId.trim()
85
+ || (runnerGeneration !== null && (!Number.isSafeInteger(runnerGeneration)
86
+ || runnerGeneration <= 0
87
+ || runnerGeneration >= (proof.stopCommandGeneration ?? 0)))
88
+ || (proof.containerId !== undefined
89
+ && (typeof proof.containerId !== "string" || !/^[0-9a-f]{64}$/.test(proof.containerId)))
90
+ || typeof proof.recordedAt !== "string") {
91
+ throw new RunnerCommandFenceError("Stored workspace persistence proof is invalid.", "runner_command_conflict");
92
+ }
93
+ if (proof.runnerCommandGeneration === undefined) {
94
+ proof.runnerCommandGeneration = null;
95
+ }
96
+ return proof;
97
+ }
98
+ function normalizeLaunchedRecord(value, expectedSlug) {
99
+ if (!value || typeof value !== "object") {
100
+ throw new RunnerCommandFenceError("Stored runner launch record is invalid.", "runner_command_conflict");
101
+ }
102
+ const record = value;
103
+ if (record.version !== 1
104
+ || typeof record.slug !== "string"
105
+ || (expectedSlug !== undefined && record.slug !== expectedSlug)
106
+ || !Number.isSafeInteger(record.commandGeneration)
107
+ || (record.commandGeneration ?? 0) <= 0
108
+ || typeof record.operationId !== "string"
109
+ || !record.operationId.trim()
110
+ || typeof record.containerId !== "string"
111
+ || !/^[0-9a-f]{64}$/.test(record.containerId)
112
+ || typeof record.launchedAt !== "string") {
113
+ throw new RunnerCommandFenceError("Stored runner launch record is invalid.", "runner_command_conflict");
114
+ }
115
+ return record;
116
+ }
117
+ function normalizeWorkspaceVolumeRecord(value, expectedSlug) {
118
+ const record = (value && typeof value === "object" ? value : {});
119
+ if (record.version !== 1
120
+ || typeof record.slug !== "string"
121
+ || (expectedSlug !== undefined && record.slug !== expectedSlug)
122
+ || !isWorkspaceVolumeName(record.volume)
123
+ || typeof record.recordedAt !== "string") {
124
+ throw new RunnerCommandFenceError("Stored workspace volume record is invalid.", "runner_command_conflict");
125
+ }
126
+ return record;
127
+ }
128
+ function writeFileAtomic(path, contents, mode) {
129
+ const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
130
+ writeFileSync(temporaryPath, contents, { encoding: "utf8", mode });
131
+ renameSync(temporaryPath, path);
132
+ }
133
+ function writeJsonAtomic(path, value) {
134
+ writeFileAtomic(path, `${JSON.stringify(value, null, 2)}\n`, 0o600);
135
+ }
136
+ export class RunnerCommandFenceStore {
137
+ rootPath;
138
+ constructor(localStateDir = LOCAL_STATE_DIR) {
139
+ this.rootPath = resolve(localStateDir, "runner-fences");
140
+ }
141
+ /**
142
+ * The slug's fence folder. Runners before this one named it after the slug
143
+ * in base64url, which is case-sensitive: on a disk that ignores case, two
144
+ * slugs whose encodings differ only in capitals shared one folder (and the
145
+ * stored slug check refused the second). Such a folder is used in place
146
+ * when an entry with exactly that name exists: it may be mounted into a
147
+ * running container, so it is not moved. Every other slug gets
148
+ * `<lowercased slug>+<32 hex of SHA-256>` (`runner-slug-folder.ts`).
149
+ */
150
+ directoryFor(slug) {
151
+ const legacy = legacyFenceFolderName(slug);
152
+ return resolve(this.rootPath, findExactDirectoryEntry(this.rootPath, [legacy]) ?? caseSafeSlugFolderName(slug));
153
+ }
154
+ statePath(slug) {
155
+ return resolve(this.directoryFor(slug), "state.json");
156
+ }
157
+ workspaceSyncedStopPath(slug) {
158
+ return resolve(this.directoryFor(slug), "workspace-synced-stop.json");
159
+ }
160
+ launchedPath(slug) {
161
+ return resolve(this.directoryFor(slug), "launched.json");
162
+ }
163
+ workspaceVolumePath(slug) {
164
+ return resolve(this.directoryFor(slug), "workspace-volume.json");
165
+ }
166
+ /**
167
+ * Records the volume that holds the slug's workspace and returns the
168
+ * recorded name. Create-exclusive: the first record wins, and a later call,
169
+ * with the same name or another, returns the existing record unchanged, so
170
+ * a retry or a racing create can never move a slug to a different volume.
171
+ * The record is linked into place complete, so it is never seen half-written.
172
+ */
173
+ writeWorkspaceVolume(slug, volume) {
174
+ if (!isWorkspaceVolumeName(volume)) {
175
+ throw new RunnerCommandFenceError("Invalid workspace volume name.", "runner_command_conflict");
176
+ }
177
+ mkdirSync(this.directoryFor(slug), { recursive: true, mode: 0o700 });
178
+ const path = this.workspaceVolumePath(slug);
179
+ const record = {
180
+ version: 1,
181
+ slug,
182
+ volume,
183
+ recordedAt: new Date().toISOString(),
184
+ };
185
+ const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
186
+ try {
187
+ writeFileSync(temporaryPath, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
188
+ linkSync(temporaryPath, path);
189
+ return volume;
190
+ }
191
+ catch (error) {
192
+ if (error.code !== "EEXIST")
193
+ throw error;
194
+ }
195
+ finally {
196
+ rmSync(temporaryPath, { force: true });
197
+ }
198
+ const existing = this.readWorkspaceVolume(slug);
199
+ if (!existing) {
200
+ throw new RunnerCommandFenceError(`The workspace volume record for ${slug} changed while it was written.`, "runner_command_conflict");
201
+ }
202
+ return existing;
203
+ }
204
+ /** The recorded workspace volume, or null for a slug with no record. */
205
+ readWorkspaceVolume(slug) {
206
+ const path = this.workspaceVolumePath(slug);
207
+ let text;
208
+ try {
209
+ text = readFileSync(path, "utf8");
210
+ }
211
+ catch (error) {
212
+ if (error.code === "ENOENT")
213
+ return null;
214
+ throw error;
215
+ }
216
+ try {
217
+ return normalizeWorkspaceVolumeRecord(JSON.parse(text), slug).volume;
218
+ }
219
+ catch {
220
+ // Fail closed: guessing the default could mount an empty volume over a
221
+ // workspace that lives elsewhere. Destroy still clears the slug.
222
+ throw new RunnerCommandFenceError(`Stored workspace volume record for ${slug} cannot be read.`, "runner_command_conflict");
223
+ }
224
+ }
225
+ removeWorkspaceVolume(slug) {
226
+ rmSync(this.workspaceVolumePath(slug), { force: true });
227
+ }
228
+ /**
229
+ * Every slug's workspace volume record, for the runner inventory, which
230
+ * mirrors these records and must leave their volumes alone. A slug whose
231
+ * record exists but cannot be read is listed in `unreadableSlugs`; its
232
+ * volume is unknown, so cleanup must keep whatever the inventory says it
233
+ * owns. A slug whose fence directory is gone appears in neither.
234
+ */
235
+ listWorkspaceVolumeRecords() {
236
+ const records = [];
237
+ const slugs = new Set();
238
+ const folderNames = new Set();
239
+ const unreadableSlugs = new UnreadableFenceSlugs(slugs, folderNames);
240
+ if (!existsSync(this.rootPath))
241
+ return { records, unreadableSlugs };
242
+ for (const entry of readdirSync(this.rootPath, { withFileTypes: true })) {
243
+ if (!entry.isDirectory())
244
+ continue;
245
+ const path = resolve(this.rootPath, entry.name, "workspace-volume.json");
246
+ const caseSafe = isCaseSafeFolderName(entry.name);
247
+ try {
248
+ const record = normalizeWorkspaceVolumeRecord(JSON.parse(readFileSync(path, "utf8")));
249
+ const expectedName = caseSafe ? caseSafeSlugFolderName(record.slug) : legacyFenceFolderName(record.slug);
250
+ if (expectedName !== entry.name)
251
+ throw new Error("The record names another slug");
252
+ records.push(record);
253
+ }
254
+ catch (error) {
255
+ if (error.code === "ENOENT")
256
+ continue;
257
+ if (caseSafe)
258
+ folderNames.add(entry.name);
259
+ else
260
+ slugs.add(Buffer.from(entry.name, "base64url").toString("utf8"));
261
+ console.error(`[runner] Ignoring unreadable workspace volume record at ${path}:`, error instanceof Error ? error.message : String(error));
262
+ }
263
+ }
264
+ return { records, unreadableSlugs };
265
+ }
266
+ /** Every volume a slug has recorded, for cleanup that must leave them alone. */
267
+ listWorkspaceVolumes() {
268
+ return new Set(this.listWorkspaceVolumeRecords().records.map((record) => record.volume));
269
+ }
270
+ launchFileName(commandGeneration) {
271
+ return `launch-${commandGeneration}.env`;
272
+ }
273
+ launchFilePath(slug, commandGeneration) {
274
+ return resolve(this.directoryFor(slug), this.launchFileName(commandGeneration));
275
+ }
276
+ /**
277
+ * Removes superseded running tokens and their launch files. Launch-file
278
+ * deletion lives here so that accepting any command drops the per-start
279
+ * values of every generation but the accepted one, and so that an exact
280
+ * retry (which keeps its own token) never deletes the file its in-flight
281
+ * execution just wrote.
282
+ */
283
+ clearRunningTokens(slug, keepCommandGeneration) {
284
+ const directory = this.directoryFor(slug);
285
+ if (!existsSync(directory))
286
+ return;
287
+ const keptToken = keepCommandGeneration === undefined
288
+ ? null
289
+ : `running-${keepCommandGeneration}`;
290
+ const keptLaunch = keepCommandGeneration === undefined
291
+ ? null
292
+ : this.launchFileName(keepCommandGeneration);
293
+ for (const entry of readdirSync(directory)) {
294
+ const isToken = entry.startsWith("running-") && entry !== keptToken;
295
+ const isLaunch = entry.startsWith("launch-") && entry.endsWith(".env") && entry !== keptLaunch;
296
+ if (isToken || isLaunch) {
297
+ rmSync(resolve(directory, entry), { force: true });
298
+ }
299
+ }
300
+ }
301
+ ensureToken(record) {
302
+ mkdirSync(this.directoryFor(record.slug), { recursive: true, mode: 0o700 });
303
+ if (record.desiredState !== "running") {
304
+ this.clearRunningTokens(record.slug);
305
+ return;
306
+ }
307
+ const tokenPath = resolve(this.directoryFor(record.slug), `running-${record.commandGeneration}`);
308
+ const expected = `${record.operationId}\n`;
309
+ let current = null;
310
+ try {
311
+ current = readFileSync(tokenPath, "utf8");
312
+ }
313
+ catch {
314
+ current = null;
315
+ }
316
+ if (current === expected) {
317
+ // An exact retry of an accepted Start: leave this generation's token and
318
+ // launch file untouched so a container reading the fence directory never
319
+ // observes them missing, and so an in-flight execution keeps its file.
320
+ this.clearRunningTokens(record.slug, record.commandGeneration);
321
+ return;
322
+ }
323
+ this.clearRunningTokens(record.slug);
324
+ writeFileAtomic(tokenPath, expected, 0o600);
325
+ }
326
+ /**
327
+ * Writes the per-start values this launch will boot with. Called from the
328
+ * serialized execution immediately before `docker start`, never at accept
329
+ * time.
330
+ */
331
+ writeLaunchFile(record, contents) {
332
+ this.assertCurrent(record);
333
+ if (record.desiredState !== "running") {
334
+ throw new RunnerCommandFenceError("Only a running command can write a launch file.", "runner_command_conflict");
335
+ }
336
+ mkdirSync(this.directoryFor(record.slug), { recursive: true, mode: 0o700 });
337
+ const path = this.launchFilePath(record.slug, record.commandGeneration);
338
+ writeFileAtomic(path, contents, 0o600);
339
+ return path;
340
+ }
341
+ removeLaunchFiles(slug) {
342
+ const directory = this.directoryFor(slug);
343
+ if (!existsSync(directory))
344
+ return;
345
+ for (const entry of readdirSync(directory)) {
346
+ if (entry.startsWith("launch-") && entry.endsWith(".env")) {
347
+ rmSync(resolve(directory, entry), { force: true });
348
+ }
349
+ }
350
+ }
351
+ /**
352
+ * Binds this command generation to the exact container it started. Written
353
+ * under the per-slug execution queue after `assertCurrent`, so a newer
354
+ * command accepted on the HTTP path cannot claim a container it did not
355
+ * start.
356
+ */
357
+ recordLaunched(record, containerId) {
358
+ this.assertCurrent(record);
359
+ if (record.desiredState !== "running") {
360
+ throw new RunnerCommandFenceError("Only a running command can record a launch.", "runner_command_conflict");
361
+ }
362
+ if (!/^[0-9a-f]{64}$/.test(containerId)) {
363
+ throw new RunnerCommandFenceError("A launch record requires the full container id.", "runner_command_conflict");
364
+ }
365
+ const launched = {
366
+ version: 1,
367
+ slug: record.slug,
368
+ commandGeneration: record.commandGeneration,
369
+ operationId: record.operationId,
370
+ containerId,
371
+ launchedAt: new Date().toISOString(),
372
+ };
373
+ mkdirSync(this.directoryFor(record.slug), { recursive: true, mode: 0o700 });
374
+ writeJsonAtomic(this.launchedPath(record.slug), launched);
375
+ return launched;
376
+ }
377
+ readLaunched(slug) {
378
+ const path = this.launchedPath(slug);
379
+ if (!existsSync(path))
380
+ return null;
381
+ try {
382
+ return normalizeLaunchedRecord(JSON.parse(readFileSync(path, "utf8")), slug);
383
+ }
384
+ catch {
385
+ // A launch record that cannot be read attributes nothing. Callers treat
386
+ // an unattributable container exactly as they treat a missing record.
387
+ return null;
388
+ }
389
+ }
390
+ removeLaunched(slug) {
391
+ rmSync(this.launchedPath(slug), { force: true });
392
+ }
393
+ read(slug) {
394
+ const path = this.statePath(slug);
395
+ if (!existsSync(path))
396
+ return null;
397
+ try {
398
+ return normalizeRecord(JSON.parse(readFileSync(path, "utf8")), slug);
399
+ }
400
+ catch (error) {
401
+ if (error instanceof RunnerCommandFenceError)
402
+ throw error;
403
+ throw new RunnerCommandFenceError(`Stored runner command fence for ${slug} cannot be read.`, "runner_command_conflict");
404
+ }
405
+ }
406
+ accept(slug, input, expectedDesiredState) {
407
+ if (!Number.isSafeInteger(input.commandGeneration)
408
+ || (input.commandGeneration ?? 0) <= 0
409
+ || typeof input.operationId !== "string"
410
+ || !input.operationId.trim()
411
+ || input.desiredState !== expectedDesiredState) {
412
+ throw new RunnerCommandFenceError("Runner command generation, operationId, and desiredState are required and must match the action.", "runner_command_conflict");
413
+ }
414
+ const commandGeneration = input.commandGeneration;
415
+ const operationId = input.operationId.trim();
416
+ const current = this.read(slug);
417
+ if (current) {
418
+ if (commandGeneration < current.commandGeneration) {
419
+ throw new RunnerCommandFenceError(`Runner command generation ${commandGeneration} was superseded by ${current.commandGeneration}.`, "runner_command_superseded_before_mutation", current.commandGeneration);
420
+ }
421
+ if (commandGeneration === current.commandGeneration) {
422
+ if (current.operationId !== operationId || current.desiredState !== expectedDesiredState) {
423
+ throw new RunnerCommandFenceError(`Runner command generation ${commandGeneration} belongs to another operation.`, "runner_command_conflict");
424
+ }
425
+ // An applied replay is observational: the caller must inspect the
426
+ // runner produced by this exact command instead of refreshing fence
427
+ // files or executing the mutation again. Accepted commands can still
428
+ // repair their token before joining the in-flight execution.
429
+ if (current.phase === "accepted") {
430
+ this.ensureToken(current);
431
+ }
432
+ return current;
433
+ }
434
+ if (current.operationId === operationId) {
435
+ throw new RunnerCommandFenceError(`Runner operation ${operationId} is already bound to generation ${current.commandGeneration}.`, "runner_command_conflict");
436
+ }
437
+ }
438
+ const record = {
439
+ version: 1,
440
+ slug,
441
+ commandGeneration,
442
+ operationId,
443
+ desiredState: expectedDesiredState,
444
+ phase: "accepted",
445
+ updatedAt: new Date().toISOString(),
446
+ };
447
+ mkdirSync(this.directoryFor(slug), { recursive: true, mode: 0o700 });
448
+ // Removing the running token first makes Stop/Destroy fail closed even if
449
+ // persistence is interrupted before the request can be acknowledged.
450
+ if (expectedDesiredState !== "running") {
451
+ this.clearRunningTokens(slug);
452
+ }
453
+ writeJsonAtomic(this.statePath(slug), record);
454
+ this.ensureToken(record);
455
+ return record;
456
+ }
457
+ assertCurrent(record) {
458
+ const current = this.read(record.slug);
459
+ if (!current
460
+ || current.commandGeneration !== record.commandGeneration
461
+ || current.operationId !== record.operationId
462
+ || current.desiredState !== record.desiredState) {
463
+ throw new RunnerCommandFenceError(`Runner command generation ${record.commandGeneration} was superseded.`, "runner_command_superseded");
464
+ }
465
+ }
466
+ markApplied(record) {
467
+ this.assertCurrent(record);
468
+ const applied = {
469
+ ...record,
470
+ phase: "applied",
471
+ updatedAt: new Date().toISOString(),
472
+ };
473
+ writeJsonAtomic(this.statePath(record.slug), applied);
474
+ return applied;
475
+ }
476
+ recordWorkspaceSyncedStop(record, runnerCommandGeneration, containerId) {
477
+ this.assertCurrent(record);
478
+ const attributed = runnerCommandGeneration !== null;
479
+ if (record.desiredState !== "stopped"
480
+ || (attributed && (!Number.isSafeInteger(runnerCommandGeneration)
481
+ || (runnerCommandGeneration ?? 0) <= 0
482
+ || (runnerCommandGeneration ?? 0) >= record.commandGeneration))
483
+ // An unattributed stop is only proof when it names the container it
484
+ // stopped; otherwise it proves nothing about any container.
485
+ || (!attributed && !containerId)
486
+ || (containerId !== undefined && !/^[0-9a-f]{64}$/.test(containerId))) {
487
+ throw new RunnerCommandFenceError("Workspace persistence proof does not match the stopped runner.", "runner_command_conflict");
488
+ }
489
+ const proof = {
490
+ version: 1,
491
+ slug: record.slug,
492
+ stopCommandGeneration: record.commandGeneration,
493
+ stopOperationId: record.operationId,
494
+ runnerCommandGeneration,
495
+ ...(containerId ? { containerId } : {}),
496
+ recordedAt: new Date().toISOString(),
497
+ };
498
+ writeJsonAtomic(this.workspaceSyncedStopPath(record.slug), proof);
499
+ return proof;
500
+ }
501
+ readWorkspaceSyncedStop(slug) {
502
+ const path = this.workspaceSyncedStopPath(slug);
503
+ if (!existsSync(path))
504
+ return null;
505
+ try {
506
+ return normalizeWorkspaceSyncedStopProof(JSON.parse(readFileSync(path, "utf8")), slug);
507
+ }
508
+ catch (error) {
509
+ if (error instanceof RunnerCommandFenceError)
510
+ throw error;
511
+ throw new RunnerCommandFenceError(`Stored workspace persistence proof for ${slug} cannot be read.`, "runner_command_conflict");
512
+ }
513
+ }
514
+ listAcceptedTerminalCommands() {
515
+ if (!existsSync(this.rootPath))
516
+ return [];
517
+ const records = [];
518
+ for (const entry of readdirSync(this.rootPath, { withFileTypes: true })) {
519
+ if (!entry.isDirectory())
520
+ continue;
521
+ const path = resolve(this.rootPath, entry.name, "state.json");
522
+ if (!existsSync(path))
523
+ continue;
524
+ try {
525
+ const record = normalizeRecord(JSON.parse(readFileSync(path, "utf8")));
526
+ if (record.phase === "accepted" && record.desiredState !== "running") {
527
+ records.push(record);
528
+ }
529
+ }
530
+ catch (error) {
531
+ console.error(`[runner] Ignoring unreadable command fence at ${path}:`, error instanceof Error ? error.message : String(error));
532
+ }
533
+ }
534
+ return records;
535
+ }
536
+ }
@@ -0,0 +1,57 @@
1
+ export function inspectRunnerState(slug, status, before, after, failedBeforeHarness,
2
+ /** No container was ever launched for this slug on this machine (see `RunnerCommandFenceStore.readLaunched`). */
3
+ neverLaunched = false,
4
+ /** The Stop that durably saved this stopped container, which has not run since. */
5
+ durableStop) {
6
+ const base = { version: 1, executionId: slug, command: after };
7
+ if (JSON.stringify(before) !== JSON.stringify(after))
8
+ return { ...base, state: "unknown", reason: "command-changed" };
9
+ if (after && after.slug !== slug)
10
+ return { ...base, state: "unknown", reason: "identity-mismatch" };
11
+ if (status === null) {
12
+ if (!after)
13
+ return {
14
+ ...base,
15
+ state: "unknown",
16
+ reason: "execution-unregistered",
17
+ allocationAvailable: true,
18
+ };
19
+ if (after?.phase === "applied" && after.desiredState === "absent")
20
+ return { ...base, state: "absent", reason: "retirement-confirmed" };
21
+ // A Stop that superseded the first start before Docker created anything:
22
+ // no container ever ran here, so there is nothing to keep.
23
+ if (after?.phase === "applied" && after.desiredState === "stopped" && neverLaunched)
24
+ return { ...base, state: "absent", reason: "never-launched" };
25
+ return { ...base, state: "unknown", reason: "absence-not-fenced" };
26
+ }
27
+ // A container Docker created but never started, left by a create that a
28
+ // Stop superseded before `docker start`: the applied Stop settled it, and
29
+ // nothing in it ever ran. The next Start replaces it.
30
+ if (status === "created" && after?.phase === "applied" && after.desiredState === "stopped")
31
+ return { ...base, state: "stopped-with-data", reason: "never-started" };
32
+ if (["running", "paused", "created", "restarting"].includes(status))
33
+ return { ...base, state: "live", reason: "container-observed" };
34
+ if (["exited", "dead", "stopped"].includes(status))
35
+ return {
36
+ ...base,
37
+ state: "stopped-with-data",
38
+ reason: "container-retained",
39
+ ...(failedBeforeHarness &&
40
+ after?.desiredState === "running" &&
41
+ after.commandGeneration === failedBeforeHarness.commandGeneration &&
42
+ after.operationId === failedBeforeHarness.operationId
43
+ ? {
44
+ safeReplacement: {
45
+ reason: "failed_before_harness",
46
+ ...failedBeforeHarness,
47
+ },
48
+ }
49
+ : {}),
50
+ ...(durableStop ? { durableStop: { ...durableStop } } : {}),
51
+ };
52
+ return {
53
+ ...base,
54
+ state: "unknown",
55
+ reason: "container-state-unknown",
56
+ };
57
+ }