owenloop 0.2.1 → 0.4.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.
package/dist/add.js ADDED
@@ -0,0 +1,999 @@
1
+ /**
2
+ * Pure helpers for the `owenloop add <owner>/<repo>[@ref]` CLI verb (workflow
3
+ * distribution Stage 1 — see the design doc this implements,
4
+ * `docs/workflow-distribution.md` §3 in the companion hub repo).
5
+ *
6
+ * These are the network-free, filesystem-adjacent pieces: spec parsing, URL
7
+ * building, lockfile read/write, and file installation. The network fetch and
8
+ * arg glue live in `src/cli.ts` (`dispatchAdd`) so this module stays trivially
9
+ * unit-testable and `cli.ts` doesn't widen its export surface just to reuse
10
+ * `Args`/`CliError`/etc.
11
+ */
12
+ import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
13
+ import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
14
+ import { createHash, randomBytes } from 'node:crypto';
15
+ import { hostname } from 'node:os';
16
+ import { setTimeout as sleep } from 'node:timers/promises';
17
+ /** Max length for an in-archive relative path we are willing to join and write. */
18
+ const MAX_ARCHIVE_PATH_LENGTH = 1024;
19
+ /**
20
+ * Returns `undefined` if `relPath` is safe to `join()` under a destination
21
+ * directory, else a human-readable reason it must be rejected. This is
22
+ * reject-don't-normalize: a synthetic archive entry like
23
+ * `workflows/../../victim` is refused outright, never canonicalized into a
24
+ * "safe" path. Part of SEC-1 — an unnormalized entry name must never escape
25
+ * the staging or install directory.
26
+ */
27
+ export function archivePathViolation(relPath) {
28
+ if (relPath === '')
29
+ return 'empty path';
30
+ if (relPath.includes('\0'))
31
+ return 'contains a NUL byte';
32
+ if (isAbsolute(relPath) || /^[\\/]/.test(relPath) || /^[A-Za-z]:/.test(relPath)) {
33
+ return 'is an absolute path';
34
+ }
35
+ // Split on both separators so '..\\' tricks and doubled separators can't
36
+ // smuggle a traversal segment past the check.
37
+ const segments = relPath.split(/[\\/]+/);
38
+ if (segments.some((s) => s === '.' || s === '..')) {
39
+ return "contains a '.' or '..' segment";
40
+ }
41
+ if (relPath.length > MAX_ARCHIVE_PATH_LENGTH) {
42
+ return `exceeds ${MAX_ARCHIVE_PATH_LENGTH}-char path length limit`;
43
+ }
44
+ return undefined;
45
+ }
46
+ /**
47
+ * Returns `undefined` if `relPath` is a safe SINGLE-SEGMENT lockfile install
48
+ * path, else a human-readable reason it must be rejected. Stricter than
49
+ * {@link archivePathViolation}: a lockfile entry's `path` is one on-disk path
50
+ * segment by construction — both the current `<owner>-<repo>-<hash>` scheme and
51
+ * the only legacy scheme this tool ever wrote (`<owner>-<repo>`, see
52
+ * {@link installFolder}) — so ANY separator is refused outright. That single
53
+ * rule makes `..` traversal, `.owenloop/../../x`, and nested escape shapes
54
+ * unrepresentable before any `join`/`rename` ever touches the path. Like
55
+ * `archivePathViolation` this is reject-don't-normalize: a bad path is refused,
56
+ * never canonicalized into a "safe" one.
57
+ */
58
+ export function lockfilePathViolation(relPath) {
59
+ // Reuse the shared checks (empty, NUL, absolute, '.'/'..' segments, length).
60
+ const base = archivePathViolation(relPath);
61
+ if (base)
62
+ return base;
63
+ // A lockfile install path additionally must be a single segment: no
64
+ // separators at all, so a multi-segment on-disk path like 'legacy/olddir'
65
+ // (which passes archivePathViolation) is still refused here.
66
+ if (/[\\/]/.test(relPath))
67
+ return 'contains a path separator';
68
+ return undefined;
69
+ }
70
+ /** Parse `owner/repo` or `owner/repo@ref` into its parts; `ref` defaults to `'HEAD'`. */
71
+ export function parseRepoSpec(spec) {
72
+ const atIdx = spec.lastIndexOf('@');
73
+ const ownerRepo = atIdx >= 0 ? spec.slice(0, atIdx) : spec;
74
+ const ref = atIdx >= 0 ? spec.slice(atIdx + 1) : 'HEAD';
75
+ const slashIdx = ownerRepo.indexOf('/');
76
+ if (slashIdx < 0) {
77
+ throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
78
+ }
79
+ const owner = ownerRepo.slice(0, slashIdx);
80
+ const repo = ownerRepo.slice(slashIdx + 1);
81
+ if (!owner || !repo) {
82
+ throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
83
+ }
84
+ if (repo.includes('/')) {
85
+ throw new Error(`malformed repo spec '${spec}' — expected owner/repo[@ref]`);
86
+ }
87
+ if (!ref) {
88
+ throw new Error(`malformed repo spec '${spec}' — empty ref after '@'`);
89
+ }
90
+ // Owner and repo become a single on-disk path segment (see `installFolder`),
91
+ // so restrict them to the GitHub-legal charset (a superset — letters, digits,
92
+ // '.', '_', '-'). This guarantees no '/', '\\', or NUL can reach the folder
93
+ // name on any platform — defense-in-depth alongside `archivePathViolation`.
94
+ if (!REPO_NAME_RE.test(owner) || !REPO_NAME_RE.test(repo)) {
95
+ throw new Error(`malformed repo spec '${spec}' — owner and repo may only contain letters, digits, '.', '_', '-'`);
96
+ }
97
+ return { owner, repo, ref };
98
+ }
99
+ /** GitHub-legal (superset) charset for an owner/repo name — see `parseRepoSpec`. */
100
+ const REPO_NAME_RE = /^[A-Za-z0-9._-]+$/;
101
+ /**
102
+ * The single-path-segment install folder for a package, derived from its
103
+ * `owner/repo` identity: `<owner>-<repo>-<sha256(owner/repo)[:8]>`. The 8-hex
104
+ * suffix makes the (owner,repo)→folder mapping injective in practice — the old
105
+ * `<owner>-<repo>` scheme collided (`a-b/c` and `a/b-c` both mapped to
106
+ * `a-b-c`, and the second install clobbered the first). Keying on the source
107
+ * (matching the lockfile key) keeps the folder STABLE across versions, so a
108
+ * user's documented `--defs workflows/<folder>` pointer survives upgrades.
109
+ */
110
+ export function installFolder(owner, repo) {
111
+ const hash = createHash('sha256').update(`${owner}/${repo}`).digest('hex').slice(0, 8);
112
+ return `${owner}-${repo}-${hash}`;
113
+ }
114
+ export function githubShaUrl(owner, repo, ref) {
115
+ return `https://api.github.com/repos/${owner}/${repo}/commits/${ref}`;
116
+ }
117
+ export function githubTarballUrl(owner, repo, sha) {
118
+ return `https://api.github.com/repos/${owner}/${repo}/tarball/${sha}`;
119
+ }
120
+ /** A 40-char hex commit sha (case-insensitive), as GitHub returns. */
121
+ const SHA_HEX_RE = /^[0-9a-f]{40}$/i;
122
+ function isPlainObject(value) {
123
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
124
+ }
125
+ /**
126
+ * Structurally validate a parsed `installed.json`, fail-closed. A
127
+ * parseable-but-schema-invalid lockfile is a hard error naming the offending
128
+ * entry+field — never silently reset to `{}` (which would erase ownership
129
+ * records and re-enable the clobbering {@link installFolder} was hardened
130
+ * against) and never normalized. This is the trust boundary for the lockfile:
131
+ * downstream code (`dispatchAdd`, `parkOldNameDir`) may only act on entries
132
+ * that have passed through here. Critically, EVERY entry is validated, not just
133
+ * the one being installed — `dispatchAdd` re-serializes the whole lockfile on
134
+ * success, so acting while carrying a poisoned sibling entry would re-persist
135
+ * it. Unknown extra keys (on the lockfile or an entry) are tolerated for
136
+ * forward compatibility; required shape is enforced, additions are not
137
+ * forbidden. Returns the value narrowed to {@link Lockfile}. `path` appears
138
+ * only in error messages.
139
+ */
140
+ export function validateLockfile(parsed, path) {
141
+ const fail = (detail) => {
142
+ throw new Error(`invalid lockfile at ${path}: ${detail} — fix or remove it manually`);
143
+ };
144
+ if (!isPlainObject(parsed))
145
+ return fail('top-level value is not an object');
146
+ if (parsed.version !== 1) {
147
+ return fail(`unsupported lockfile version ${JSON.stringify(parsed.version)} (expected 1)`);
148
+ }
149
+ if (!isPlainObject(parsed.installed))
150
+ return fail("'installed' is not an object");
151
+ for (const [key, entry] of Object.entries(parsed.installed)) {
152
+ const at = (field) => `installed[${JSON.stringify(key)}].${field}`;
153
+ if (!isPlainObject(entry))
154
+ return fail(`installed[${JSON.stringify(key)}] is not an object`);
155
+ if (typeof entry.source !== 'string' || entry.source === '') {
156
+ return fail(`${at('source')} is not a non-empty string`);
157
+ }
158
+ if (entry.source !== key) {
159
+ return fail(`${at('source')} '${entry.source}' does not match its key '${key}'`);
160
+ }
161
+ if (typeof entry.ref !== 'string' || entry.ref === '') {
162
+ return fail(`${at('ref')} is not a non-empty string`);
163
+ }
164
+ if (typeof entry.sha !== 'string' || !SHA_HEX_RE.test(entry.sha)) {
165
+ return fail(`${at('sha')} is not a 40-char hex commit sha`);
166
+ }
167
+ if (typeof entry.installedAt !== 'number' || !Number.isFinite(entry.installedAt)) {
168
+ return fail(`${at('installedAt')} is not a finite number`);
169
+ }
170
+ if (typeof entry.path !== 'string')
171
+ return fail(`${at('path')} is not a string`);
172
+ const pathViolation = lockfilePathViolation(entry.path);
173
+ if (pathViolation)
174
+ return fail(`${at('path')} ${pathViolation}`);
175
+ if (!Array.isArray(entry.files))
176
+ return fail(`${at('files')} is not an array`);
177
+ entry.files.forEach((file, i) => {
178
+ if (typeof file !== 'string')
179
+ return fail(`${at(`files[${i}]`)} is not a string`);
180
+ const fileViolation = archivePathViolation(file);
181
+ if (fileViolation)
182
+ return fail(`${at(`files[${i}]`)} ${fileViolation}`);
183
+ });
184
+ }
185
+ return parsed;
186
+ }
187
+ /**
188
+ * Read `.owenloop/installed.json`; a missing file is an empty lockfile, not an
189
+ * error. A file that exists but does not parse is a hard error naming the path
190
+ * — never silently reset to `{}`, which would erase ownership records and
191
+ * re-enable the clobbering `installFolder` was hardened against. A file that
192
+ * parses but is structurally invalid (bad version, malformed entry, a `path`
193
+ * that is not a safe single segment, a bad `sha`/`files`) is likewise a
194
+ * fail-closed hard error — see {@link validateLockfile}. The lockfile is never
195
+ * trusted for filesystem paths.
196
+ */
197
+ export function readLockfile(path) {
198
+ if (!existsSync(path))
199
+ return { version: 1, installed: {} };
200
+ const raw = readFileSync(path, 'utf8');
201
+ let parsed;
202
+ try {
203
+ parsed = JSON.parse(raw);
204
+ }
205
+ catch (e) {
206
+ throw new Error(`corrupt lockfile at ${path}: ${e.message} — fix or remove it manually`);
207
+ }
208
+ return validateLockfile(parsed, path);
209
+ }
210
+ /**
211
+ * Serialize `value` as pretty JSON into a sibling temp file, then `renameSync`
212
+ * over `path` — the same atomic tmp+rename discipline {@link writeLockfile} has
213
+ * always used, extracted so the crash-recovery journal writer
214
+ * ({@link writeAddJournal}) shares one implementation of it (and its
215
+ * double-fault cleanup semantics) rather than duplicating the seam. A crash or
216
+ * a concurrent reader never sees a half-written file (rename is atomic within a
217
+ * directory).
218
+ *
219
+ * If the final `renameSync` throws (EACCES, EISDIR on `path`, a full disk), the
220
+ * temp sibling is removed on a best-effort basis before the error propagates so
221
+ * a failed write cannot leak a `<path>.tmp.<pid>` file. The original rename
222
+ * error is surfaced unchanged — never swallowed, and never masked by a failure
223
+ * of that cleanup removal (if the removal itself throws, that error is swallowed
224
+ * and the tmp sibling may remain in that double fault).
225
+ */
226
+ function writeJsonAtomic(path, value, opts = {}) {
227
+ const rm = opts.rm ?? ((p, o) => rmSync(p, o));
228
+ mkdirSync(dirname(path), { recursive: true });
229
+ const tmp = `${path}.tmp.${process.pid}`;
230
+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
231
+ try {
232
+ renameSync(tmp, path);
233
+ }
234
+ catch (e) {
235
+ // Best-effort cleanup: the temp sibling should not leak on a failed write,
236
+ // but if the removal ITSELF throws (e.g. unlink EACCES) we must not let that
237
+ // replace the original rename error — swallow the cleanup error and rethrow
238
+ // `e`. A tmp sibling may survive in that double fault.
239
+ try {
240
+ rm(tmp, { force: true });
241
+ }
242
+ catch {
243
+ // ignore — surfacing the original rename error matters more than cleanup.
244
+ }
245
+ throw e;
246
+ }
247
+ }
248
+ export function writeLockfile(path, lf, opts = {}) {
249
+ writeJsonAtomic(path, lf, opts);
250
+ }
251
+ // ---- staging + atomic commit -----------------------------------------------
252
+ /** The staging root under a defs dir where installs are assembled + validated. */
253
+ export const STAGING_DIRNAME = '.owenloop-staging';
254
+ /**
255
+ * Write `files` (relative path → bytes) into `targetDir` (a staging dir), NOT
256
+ * the final install destination. Unlike a direct install, this never clears a
257
+ * live folder: the caller stages here, validates, then `commitInstall`s with an
258
+ * atomic rename, so a failure mid-write can only ever corrupt throwaway staging
259
+ * content. Returns the sorted list of relative paths written.
260
+ */
261
+ export function stageFiles(targetDir, files) {
262
+ const written = [];
263
+ for (const [relPath, bytes] of files) {
264
+ // Defense-in-depth: this function is exported and writes whole directory
265
+ // trees, so it must not trust its caller to have validated keys.
266
+ const violation = archivePathViolation(relPath);
267
+ if (violation) {
268
+ throw new Error(`refusing to write unsafe archive path '${relPath}': ${violation}`);
269
+ }
270
+ const full = join(targetDir, relPath);
271
+ mkdirSync(dirname(full), { recursive: true });
272
+ writeFileSync(full, bytes);
273
+ written.push(relPath);
274
+ }
275
+ return written.sort();
276
+ }
277
+ /**
278
+ * Thrown by `commitInstall` when the atomic swap fails AND the rollback of it
279
+ * fails too — a near-impossible same-filesystem double-fault. Carries the path
280
+ * where the previous version was left so the caller can preserve it (its
281
+ * `preservedAt` sits under the staging root, which the caller would otherwise
282
+ * clean up as debris). A distinguishable type so the caller can tell this
283
+ * "must-preserve" double-fault apart from an ordinary swap failure.
284
+ */
285
+ export class RollbackFailedError extends Error {
286
+ preservedAt;
287
+ constructor(message, preservedAt) {
288
+ super(message);
289
+ this.name = 'RollbackFailedError';
290
+ this.preservedAt = preservedAt;
291
+ }
292
+ }
293
+ /**
294
+ * Atomically swap a validated `stagingDir` into place at `defsDir/folder`,
295
+ * rolling back to the previous install if the swap itself fails. Both dirs live
296
+ * on the same filesystem by construction (staging is under `defsDir`), so the
297
+ * renames are atomic and `EXDEV` is impossible.
298
+ *
299
+ * Two-phase commit: unlike a one-shot swap, this does NOT delete the displaced
300
+ * previous install on success — it returns an {@link InstallCommitHandle} whose
301
+ * `backupDir` still holds it. The caller must then either
302
+ * {@link finalizeInstallCommit} (discard the backup, making the swap permanent)
303
+ * once its follow-on work — the lockfile write — has durably succeeded, or
304
+ * {@link rollbackInstallCommit} to restore the previous directory state if that
305
+ * work fails. This is what lets "commit the directory + write the lockfile" be
306
+ * one recoverable operation.
307
+ *
308
+ * Sequence: back up any existing install (rename dest → `<stagingDir>-old`) — if
309
+ * that fails nothing has changed; rename staging → dest; on failure rename the
310
+ * backup back (throwing {@link RollbackFailedError} if even that fails, so the
311
+ * caller can preserve the named copy).
312
+ */
313
+ export function commitInstall(defsDir, folder, stagingDir) {
314
+ mkdirSync(defsDir, { recursive: true });
315
+ const dest = join(defsDir, folder);
316
+ const backupDir = `${stagingDir}-old`;
317
+ const undoDir = `${stagingDir}-undo`;
318
+ let backedUp = false;
319
+ if (existsSync(dest)) {
320
+ // Ownership is verified by the caller before we get here. If this rename
321
+ // throws, nothing has changed — dest is still the previous install.
322
+ renameSync(dest, backupDir);
323
+ backedUp = true;
324
+ }
325
+ try {
326
+ renameSync(stagingDir, dest);
327
+ }
328
+ catch (e) {
329
+ if (backedUp) {
330
+ try {
331
+ renameSync(backupDir, dest);
332
+ }
333
+ catch (rollbackErr) {
334
+ // Near-impossible (same dir, same fs), but if even the rollback fails,
335
+ // name the backup so the previous version is recoverable by hand — and
336
+ // signal (via the type) that the caller must preserve it.
337
+ throw new RollbackFailedError(`install of '${folder}' failed and rollback failed too; ` +
338
+ `previous version preserved at ${backupDir}: ${rollbackErr.message}`, backupDir);
339
+ }
340
+ }
341
+ throw e;
342
+ }
343
+ return { dest, backupDir: backedUp ? backupDir : undefined, undoDir };
344
+ }
345
+ /**
346
+ * Migrate a source off its old `<owner>-<repo>` install directory by PARKING it
347
+ * (rename → `<stagingDir>-undo-oldname`) instead of deleting it, so a later
348
+ * rollback can put it back where the (still-unchanged) lockfile expects it.
349
+ * Records the move on `handle.oldName`. If the old dir does not exist on disk
350
+ * (the lockfile names a path that is already gone), records nothing — matching
351
+ * the previous `rmSync(..., { force: true })` tolerance of absence.
352
+ *
353
+ * Defense-in-depth (Layer 3): even though `readLockfile`/`validateLockfile` and
354
+ * the use-site in `dispatchAdd` already constrain `oldRelPath` to a safe single
355
+ * segment, the authoritative containment check is re-asserted HERE, at the
356
+ * mutation site, before any rename — a poisoned `existing.path` must never move
357
+ * a directory outside `defsDir` (which `finalizeInstallCommit` would then
358
+ * recursively delete). Following this project's TOCTOU discipline, the check
359
+ * that matters is the one at the filesystem operation, not only up front:
360
+ * `oldRelPath` must be a single segment AND resolve under `defsDir`, and the
361
+ * target must be a real directory — a symlink at the legacy path is refused (a
362
+ * symlinked segment must never be parked/finalized, since finalize deletes it).
363
+ * Deliberate behavior change vs. the old `existsSync` probe: a DANGLING symlink
364
+ * at the old path was previously silently ignored (existsSync follows links);
365
+ * it is now refused, which is fail-closed and correct.
366
+ */
367
+ export function parkOldNameDir(handle, defsDir, oldRelPath) {
368
+ const violation = lockfilePathViolation(oldRelPath);
369
+ if (violation) {
370
+ throw new Error(`refusing old-name migration path '${oldRelPath}': ${violation}`);
371
+ }
372
+ const originalPath = join(defsDir, oldRelPath);
373
+ // Resolved-path containment: '..'-free by the single-segment rule above, but
374
+ // recompute at the rename site so no path outside defsDir can ever be moved.
375
+ if (!resolve(originalPath).startsWith(resolve(defsDir) + sep)) {
376
+ throw new Error(`refusing old-name migration path '${oldRelPath}': escapes the defs directory`);
377
+ }
378
+ let st;
379
+ try {
380
+ st = lstatSync(originalPath); // lstat, not stat: never follow a symlink here.
381
+ }
382
+ catch (e) {
383
+ if (e.code === 'ENOENT')
384
+ return; // already gone — nothing to park
385
+ throw e;
386
+ }
387
+ if (st.isSymbolicLink()) {
388
+ throw new Error(`refusing old-name migration: '${originalPath}' is a symlink`);
389
+ }
390
+ if (!st.isDirectory()) {
391
+ throw new Error(`refusing old-name migration: '${originalPath}' is not a directory`);
392
+ }
393
+ const parkedAt = `${handle.undoDir}-oldname`;
394
+ renameSync(originalPath, parkedAt);
395
+ handle.oldName = { originalPath, parkedAt };
396
+ }
397
+ /**
398
+ * Make the commit permanent: discard the retained previous install and any
399
+ * parked old-name dir. Call ONLY after the follow-on lockfile write has durably
400
+ * succeeded — this is the point of no return.
401
+ */
402
+ export function finalizeInstallCommit(handle) {
403
+ if (handle.backupDir)
404
+ rmSync(handle.backupDir, { recursive: true, force: true });
405
+ if (handle.oldName)
406
+ rmSync(handle.oldName.parkedAt, { recursive: true, force: true });
407
+ }
408
+ /**
409
+ * Undo a `commitInstall` (plus any `parkOldNameDir`), restoring the pre-commit
410
+ * directory state. Order matters:
411
+ * 1. park the new content out of `dest` (rename dest → undoDir) — for a fresh
412
+ * install, this alone restores "nothing installed";
413
+ * 2. if a previous install was displaced, rename its backup back over `dest`;
414
+ * 3. if an old-name dir was parked, rename it back to where the lockfile says.
415
+ * The parked new content under `undoDir` is left for the caller's staging-root
416
+ * cleanup to dispose of. Any throw propagates to the caller.
417
+ *
418
+ * Safe to call from a FAILED `parkOldNameDir`: that helper records
419
+ * `handle.oldName` only after its single rename succeeds, so a park failure
420
+ * leaves `oldName` unset and step 3 self-skips — there is no "park partially
421
+ * happened" state to reconcile (the park is one atomic rename).
422
+ */
423
+ export function rollbackInstallCommit(handle) {
424
+ renameSync(handle.dest, handle.undoDir);
425
+ if (handle.backupDir)
426
+ renameSync(handle.backupDir, handle.dest);
427
+ if (handle.oldName)
428
+ renameSync(handle.oldName.parkedAt, handle.oldName.originalPath);
429
+ }
430
+ // ---- per-project install lock ----------------------------------------------
431
+ /** Default wait/stale/poll timings for the install lock (overridable in tests). */
432
+ const LOCK_WAIT_MS = 10_000;
433
+ const LOCK_STALE_MS = 10 * 60_000;
434
+ const LOCK_POLL_MS = 100;
435
+ /** `true` if a process with `pid` exists (signal 0 probes without delivering). */
436
+ function defaultIsPidAlive(pid) {
437
+ try {
438
+ process.kill(pid, 0);
439
+ return true;
440
+ }
441
+ catch (e) {
442
+ // EPERM: the process exists but we may not signal it — treat as alive.
443
+ // ESRCH (and anything else): no such process — dead.
444
+ return e.code === 'EPERM';
445
+ }
446
+ }
447
+ /** Read the lock file's raw bytes, or `null` if it is gone/unreadable. */
448
+ function readLockRaw(lockPath) {
449
+ try {
450
+ return readFileSync(lockPath, 'utf8');
451
+ }
452
+ catch {
453
+ return null;
454
+ }
455
+ }
456
+ /** Parse raw lock bytes into a holder, or `null` if absent/unparseable. */
457
+ function parseLockHolder(raw) {
458
+ if (raw === null)
459
+ return null;
460
+ try {
461
+ return JSON.parse(raw);
462
+ }
463
+ catch {
464
+ return null;
465
+ }
466
+ }
467
+ /** Read + parse the lock file in one step (fresh read). Used off the hot loop. */
468
+ function readLockHolder(lockPath) {
469
+ return parseLockHolder(readLockRaw(lockPath));
470
+ }
471
+ /**
472
+ * Decide whether the lock described by `holder` (parsed from a raw read) may be
473
+ * reclaimed, given the current host. Liveness-aware, not age-based:
474
+ *
475
+ * 1. `statSync` fails — the lock vanished mid-judgment → treat as reclaimable
476
+ * (the acquire loop re-verifies and simply retries the exclusive create).
477
+ * 2. Holder records a `host` that differs from ours → NOT stale, ever. A
478
+ * foreign PID space means `process.kill(pid, 0)` proves nothing; a shared
479
+ * filesystem could be locked by another machine. Held; caller refuses.
480
+ * 3. Holder has a numeric `pid` and either matches our host or omits `host`
481
+ * (a legacy same-machine payload) → stale iff that pid is dead. Age never
482
+ * reclaims a live-pid lock — this is the core safety policy.
483
+ * 4. Unparseable, or parses without a numeric pid → fail closed: held until
484
+ * `now() - mtimeMs > staleMs` (age is the only abandonment signal left).
485
+ */
486
+ function lockIsStale(lockPath, holder, staleMs, isPidAlive, now, currentHost) {
487
+ let mtimeMs;
488
+ try {
489
+ mtimeMs = statSync(lockPath).mtimeMs;
490
+ }
491
+ catch {
492
+ // Vanished between the EEXIST and here — someone else reclaimed it; retry.
493
+ return true;
494
+ }
495
+ // Case 2: recorded on a different host — its pid tells us nothing. Held.
496
+ if (holder && typeof holder.host === 'string' && holder.host !== currentHost) {
497
+ return false;
498
+ }
499
+ // Case 3: same host (or legacy no-host payload) with a numeric pid — liveness decides.
500
+ if (holder && typeof holder.pid === 'number') {
501
+ return !isPidAlive(holder.pid);
502
+ }
503
+ // Case 4: no attributable live owner — age is the only abandonment signal.
504
+ return now() - mtimeMs > staleMs;
505
+ }
506
+ /**
507
+ * Acquire the per-project install lock at `lockPath` (an exclusive-create of the
508
+ * file, `openSync(..,'wx')` — the O_EXCL create is the real serialization point).
509
+ * The payload carries an ownership token, the owner pid, a start timestamp, and
510
+ * the host. If another process holds it: reclaim it only when liveness-aware
511
+ * staleness says its owner is gone (see `lockIsStale`), otherwise poll until it
512
+ * frees, and if it does not free within `waitMs` fail cleanly with a clear
513
+ * in-progress message. Always pair with `releaseInstallLock` in a `finally`.
514
+ */
515
+ export async function acquireInstallLock(lockPath, opts = {}) {
516
+ const waitMs = opts.waitMs ?? LOCK_WAIT_MS;
517
+ const staleMs = opts.staleMs ?? LOCK_STALE_MS;
518
+ const pollMs = opts.pollMs ?? LOCK_POLL_MS;
519
+ const isPidAlive = opts.isPidAlive ?? defaultIsPidAlive;
520
+ const now = opts.now ?? Date.now;
521
+ const host = (opts.hostname ?? hostname)();
522
+ mkdirSync(dirname(lockPath), { recursive: true });
523
+ const deadline = now() + waitMs;
524
+ for (;;) {
525
+ try {
526
+ const fd = openSync(lockPath, 'wx');
527
+ const token = randomBytes(16).toString('hex');
528
+ try {
529
+ writeFileSync(fd, JSON.stringify({ pid: process.pid, startedAt: now(), token, host }));
530
+ }
531
+ finally {
532
+ closeSync(fd);
533
+ }
534
+ return { lockPath, acquired: true, token };
535
+ }
536
+ catch (e) {
537
+ if (e.code !== 'EEXIST')
538
+ throw e;
539
+ }
540
+ // Judge staleness from a single captured raw read...
541
+ const raw = readLockRaw(lockPath);
542
+ const holder = parseLockHolder(raw);
543
+ if (lockIsStale(lockPath, holder, staleMs, isPidAlive, now, host)) {
544
+ // ...then re-verify the bytes are unchanged immediately before deleting.
545
+ // Between judging stale and rmSync a third process could reclaim and
546
+ // re-create the lock; deleting then would destroy a *fresh* owner's lock.
547
+ // Residual window is a few syscalls (read-compare-delete) rather than the
548
+ // poll interval — and the `wx` create below is the true arbiter: if two
549
+ // reclaimers race, one wins the create and the other loops on EEXIST. A
550
+ // rename-based reclaim was rejected: POSIX rename clobbers its target, so
551
+ // any "rename back on mismatch" arm can itself destroy a newer lock.
552
+ const raw2 = readLockRaw(lockPath);
553
+ if (raw2 !== null && raw2 === raw) {
554
+ rmSync(lockPath, { force: true });
555
+ continue; // reclaimed — retry the exclusive create
556
+ }
557
+ // Bytes changed under us, or the lock is stat-able but unreadable (a
558
+ // root-owned 0600 lock: statSync needs only dir perms, readFileSync
559
+ // EACCES → raw/raw2 null). Do NOT delete — fall through to the deadline
560
+ // check and poll sleep below. Never `continue` here: with an unreadable,
561
+ // backdated lock this branch would otherwise spin sleeplessly, starving
562
+ // the event loop and never enforcing `waitMs`.
563
+ }
564
+ if (now() >= deadline) {
565
+ throw new Error(inProgressMessage(lockPath, holder, waitMs));
566
+ }
567
+ await sleep(pollMs);
568
+ }
569
+ }
570
+ /** Build the clear "another add is in progress" timeout error, with graceful fallbacks. */
571
+ function inProgressMessage(lockPath, holder, waitMs) {
572
+ const who = typeof holder?.pid === 'number' ? `pid ${holder.pid}` : 'another process';
573
+ // Lock content is untrusted input: a finite `startedAt` outside the ECMAScript
574
+ // Date range (|t| > 8.64e15 ms) makes `new Date(t).toISOString()` throw
575
+ // RangeError. Only render held-since when the value is a valid time value;
576
+ // otherwise omit it (same graceful fallback as an absent startedAt).
577
+ const heldSince = typeof holder?.startedAt === 'number' &&
578
+ Number.isFinite(holder.startedAt) &&
579
+ Math.abs(holder.startedAt) <= 8.64e15
580
+ ? `, held since ${new Date(holder.startedAt).toISOString()}`
581
+ : '';
582
+ const s = Math.round(waitMs / 1000);
583
+ return `another owenloop add is in progress (${who}${heldSince}) — holds ${lockPath}; timed out waiting after ${s}s`;
584
+ }
585
+ /**
586
+ * Release a lock acquired by `acquireInstallLock`. Token-checked and
587
+ * best-effort: a no-op if not acquired, if the lock is already gone/unparseable,
588
+ * or if its token no longer matches this handle (someone else legitimately
589
+ * re-acquired it — deleting would steal *their* lock). Never throws; it runs in
590
+ * `dispatchAdd`'s `finally` and must not mask the real error.
591
+ */
592
+ export function releaseInstallLock(handle) {
593
+ if (!handle.acquired)
594
+ return;
595
+ try {
596
+ const holder = readLockHolder(handle.lockPath);
597
+ if (!holder || holder.token !== handle.token)
598
+ return;
599
+ rmSync(handle.lockPath, { force: true });
600
+ }
601
+ catch {
602
+ // Already reclaimed/replaced, or an unexpected fs error — swallow.
603
+ }
604
+ }
605
+ // ---- crash-recovery journal ------------------------------------------------
606
+ //
607
+ // A process that dies (crash, SIGKILL — see docs/cli.md on power-loss limits)
608
+ // partway through the destructive part of an install — the `commitInstall` swap,
609
+ // the old-name park, or the ledger write — must leave `.owenloop` recoverable to a consistent
610
+ // (defs-on-disk ⇔ ledger) state by the NEXT `add`, never a half-applied tree.
611
+ // Today's failure arms in `dispatchAdd` only cover IN-PROCESS failures (a throw
612
+ // we catch and roll back); a hard kill skips them entirely. This journal closes
613
+ // that gap: `dispatchAdd` writes a one-record intent file before the first
614
+ // destructive step and advances/removes it as the install progresses, and the
615
+ // next `add` runs `recoverInterruptedInstall` under the same A3 install lock,
616
+ // BEFORE the stale-staging cleanup, to roll a leftover install forward or back.
617
+ //
618
+ // The journal is attacker-influenceable input, exactly like the lockfile (a
619
+ // hostile checkout can ship a crafted `.owenloop/add.journal`). It is validated
620
+ // fail-closed with the A1 discipline (`lockfilePathViolation` on every path
621
+ // field, single-segment ⇒ traversal unrepresentable), every mutation path is
622
+ // re-derived from the CURRENT run's resolved `defsDir` plus those validated
623
+ // segments — never from a recorded absolute path — and A2's symlink rule is
624
+ // re-asserted at each mutation site. Any bad shape, unknown phase, defsDir
625
+ // mismatch, or contradictory disk state REFUSES with no filesystem mutation and
626
+ // leaves the journal in place as evidence.
627
+ /** Journal filename under `.owenloop/` (sibling of `installed.json`/`add.lock`). */
628
+ export const ADD_JOURNAL_FILENAME = 'add.journal';
629
+ /**
630
+ * Structurally validate a parsed `add.journal`, fail-closed — the trust
631
+ * boundary for the journal, mirroring {@link validateLockfile}. A
632
+ * parseable-but-invalid journal is a hard error naming the file and the manual
633
+ * remedy; recovery NEVER acts on a field that has not passed through here. Every
634
+ * path field must be a safe single segment so a crafted journal cannot represent
635
+ * traversal before any `join`/`rename`. Unknown extra keys are tolerated
636
+ * (forward compatibility, same as the lockfile). `ref`/`startedAt` are
637
+ * diagnostics: validated for type when present, but not required. `path`
638
+ * appears only in error messages.
639
+ */
640
+ export function validateAddJournal(parsed, path) {
641
+ const fail = (detail) => {
642
+ throw new Error(`invalid crash-recovery journal at ${path}: ${detail} — ` +
643
+ `inspect and remove it manually, then re-run add`);
644
+ };
645
+ if (!isPlainObject(parsed))
646
+ return fail('top-level value is not an object');
647
+ if (parsed.version !== 1) {
648
+ return fail(`unsupported journal version ${JSON.stringify(parsed.version)} (expected 1)`);
649
+ }
650
+ if (parsed.phase !== 'applying' && parsed.phase !== 'finalizing') {
651
+ return fail(`unknown phase ${JSON.stringify(parsed.phase)} (expected 'applying' or 'finalizing')`);
652
+ }
653
+ if (typeof parsed.source !== 'string' || parsed.source === '') {
654
+ return fail("'source' is not a non-empty string");
655
+ }
656
+ if (typeof parsed.sha !== 'string' || !SHA_HEX_RE.test(parsed.sha)) {
657
+ return fail("'sha' is not a 40-char hex commit sha");
658
+ }
659
+ const segment = (field, value) => {
660
+ if (typeof value !== 'string')
661
+ fail(`'${field}' is not a string`);
662
+ const violation = lockfilePathViolation(value);
663
+ if (violation)
664
+ fail(`'${field}' ${violation}`);
665
+ };
666
+ segment('folder', parsed.folder);
667
+ segment('stagingId', parsed.stagingId);
668
+ if (parsed.oldNamePath !== undefined)
669
+ segment('oldNamePath', parsed.oldNamePath);
670
+ if (typeof parsed.hadDest !== 'boolean')
671
+ return fail("'hadDest' is not a boolean");
672
+ if (typeof parsed.defsDir !== 'string' || parsed.defsDir === '') {
673
+ return fail("'defsDir' is not a non-empty string");
674
+ }
675
+ if (parsed.ref !== undefined && typeof parsed.ref !== 'string')
676
+ return fail("'ref' is not a string");
677
+ if (parsed.startedAt !== undefined && typeof parsed.startedAt !== 'number') {
678
+ return fail("'startedAt' is not a number");
679
+ }
680
+ return parsed;
681
+ }
682
+ /**
683
+ * Read `.owenloop/add.journal`. Absent ⇒ `null` (the happy path — no
684
+ * interrupted install to recover). Present-but-unparseable ⇒ a hard error;
685
+ * present-but-schema-invalid ⇒ a hard error via {@link validateAddJournal}.
686
+ * Never silently ignores a malformed journal (that would let a crafted file
687
+ * quietly disable recovery) and never trusts it for filesystem paths.
688
+ */
689
+ export function readAddJournal(path) {
690
+ if (!existsSync(path))
691
+ return null;
692
+ const raw = readFileSync(path, 'utf8');
693
+ let parsed;
694
+ try {
695
+ parsed = JSON.parse(raw);
696
+ }
697
+ catch (e) {
698
+ throw new Error(`corrupt crash-recovery journal at ${path}: ${e.message} — ` +
699
+ `inspect and remove it manually, then re-run add`);
700
+ }
701
+ return validateAddJournal(parsed, path);
702
+ }
703
+ /** Write the journal atomically (tmp+rename), same discipline as the lockfile. */
704
+ export function writeAddJournal(path, journal, opts = {}) {
705
+ writeJsonAtomic(path, journal, opts);
706
+ }
707
+ /** Remove the journal (force: absence is not an error — clean-completion / idempotent). */
708
+ export function removeAddJournal(path) {
709
+ rmSync(path, { force: true });
710
+ }
711
+ /** Build a fail-closed recovery-refusal error naming the journal + manual remedy. */
712
+ function recoveryRefusal(journalPath, detail) {
713
+ return new Error(`refusing crash-recovery: ${detail} — inspect ${journalPath} and the defs dir, ` +
714
+ `resolve the state by hand, then re-run add`);
715
+ }
716
+ /**
717
+ * `lstat`-probe a recovery path: `'dir'` if it is a real directory, `'absent'`
718
+ * if it does not exist. Fail-closed on anything else — a symlink (A2 rule: a
719
+ * symlinked segment must never be renamed/rm'd, since finalize/rollback would
720
+ * act through it) or a non-directory file is refused. `lstat`, never `stat`, so
721
+ * a symlink is seen as a symlink, not followed to its target.
722
+ *
723
+ * The PARENT is checked too, not just the leaf: `lstat` on the leaf sees a
724
+ * symlinked leaf, but a symlinked *parent* directory would be silently followed
725
+ * by the `rename`/`rm` that acts on the leaf, redirecting the whole mutation
726
+ * outside `defsDir` (a hostile checkout planting `.owenloop-staging` as a
727
+ * symlink is exactly this). Refuse a symlinked immediate parent before trusting
728
+ * the leaf probe. (Absent parent ⇒ the leaf is absent too; nothing to refuse.)
729
+ */
730
+ function probeRecoveryDir(p, journalPath, label) {
731
+ const parent = dirname(p);
732
+ const parentSt = lstatSync(parent, { throwIfNoEntry: false });
733
+ if (parentSt?.isSymbolicLink()) {
734
+ throw recoveryRefusal(journalPath, `${label} parent '${parent}' is a symlink`);
735
+ }
736
+ let st;
737
+ try {
738
+ st = lstatSync(p);
739
+ }
740
+ catch (e) {
741
+ if (e.code === 'ENOENT')
742
+ return 'absent';
743
+ throw e;
744
+ }
745
+ if (st.isSymbolicLink())
746
+ throw recoveryRefusal(journalPath, `${label} at '${p}' is a symlink`);
747
+ if (!st.isDirectory())
748
+ throw recoveryRefusal(journalPath, `${label} at '${p}' is not a directory`);
749
+ return 'dir';
750
+ }
751
+ /** Re-assert resolved-path containment at a mutation target (belt-and-braces). */
752
+ function assertUnderDefs(p, defsDir, journalPath) {
753
+ if (!resolve(p).startsWith(resolve(defsDir) + sep)) {
754
+ throw recoveryRefusal(journalPath, `path '${p}' escapes the defs directory`);
755
+ }
756
+ }
757
+ /**
758
+ * Bring an interrupted install back to a consistent (defs ⇔ ledger) state, then
759
+ * remove the journal. Called by `dispatchAdd` under the A3 install lock,
760
+ * BEFORE the stale-staging cleanup (the backups a rollback needs live under the
761
+ * staging root). No journal ⇒ returns immediately (happy path unchanged).
762
+ *
763
+ * Roll-forward vs roll-back rule: the durable ledger write is the commit point.
764
+ * At or past it, roll FORWARD (finish the discard); before it, roll BACK
765
+ * (restore the previous state). Concretely:
766
+ *
767
+ * 1. `finalizing` ⇒ roll forward: the ledger is durably new; only finalize's
768
+ * discards may be missing. Clear the retained backup + parked old-name and
769
+ * the staging root. Trivially idempotent.
770
+ * 2. `applying` + the ledger already records this source at `journal.sha`/
771
+ * `journal.folder` ⇒ the commit MAY have landed, but the ledger match alone
772
+ * does not prove it — branch on disk: dest present ⇒ the swap completed ⇒
773
+ * roll forward; dest ABSENT ⇒ a same-sha re-add crashed inside commitInstall's
774
+ * dest→backup / staging→dest window and backupDir holds the only copy ⇒ roll
775
+ * back (restore it) rather than discarding it (which would be silent data
776
+ * loss against a ledger that still records the install).
777
+ * 3. `applying`, no ledger match (or ledger match with dest absent) ⇒ roll back
778
+ * through the guarded, idempotent decision table below (mirroring
779
+ * `rollbackInstallCommit`'s order) — EXCEPT the case-(c) fresh-install
780
+ * discard, which acts on the journal alone (staging + backup both absent) and
781
+ * so requires LEDGER corroboration of an interrupted old-name migration
782
+ * (`installed.path === journal.oldNamePath`) before it will delete an
783
+ * existing dest; uncorroborated ⇒ refuse fail-closed, mutate nothing, leave
784
+ * the journal and dest in place (the journal is repo-committable, so a forged
785
+ * one must never drive a deletion).
786
+ *
787
+ * Crash-safety of recovery itself: the journal is removed LAST, after all
788
+ * restore/discard renames, and every step is a single atomic rename guarded by
789
+ * existence probes — so a crash mid-recovery leaves the journal intact and a
790
+ * strict subset of the work done; the next attempt re-derives state from disk
791
+ * and continues (the dest-absent arm of case (b), the touch-nothing arm of
792
+ * case (c), and the case-(c) uncorroborated refusal ARE the mid-rollback resume
793
+ * / fail-closed states). Running it twice is a no-op the second time.
794
+ *
795
+ * Any refusal (invalid journal, defsDir mismatch, symlink where a directory is
796
+ * expected, contradictory disk state) throws WITHOUT mutating anything and
797
+ * leaves the journal in place; `dispatchAdd` sets `preserveStagingRoot` so its
798
+ * `finally` cannot then destroy the backups a later attempt needs.
799
+ */
800
+ export function recoverInterruptedInstall(args) {
801
+ const { defsDir, journalPath, lockfilePath } = args;
802
+ const journal = readAddJournal(journalPath);
803
+ if (journal === null)
804
+ return 'no-journal'; // no interrupted install — happy path, unchanged.
805
+ // An interrupted install in a DIFFERENT defs tree: recovering "here" would act
806
+ // on paths this invocation was never pointed at, and trusting the recorded
807
+ // absolute path would let a crafted journal point mutations anywhere. Fail
808
+ // closed — the operator must re-run with the same --defs/OWENLOOP_DEFS.
809
+ if (resolve(journal.defsDir) !== resolve(defsDir)) {
810
+ throw recoveryRefusal(journalPath, `journal records defs dir '${journal.defsDir}', but this add resolved '${resolve(defsDir)}' ` +
811
+ `(re-run add with the same --defs/OWENLOOP_DEFS)`);
812
+ }
813
+ // Every mutation path is derived HERE from the current defsDir + the validated
814
+ // single segments — never from the recorded absolute defsDir. These are
815
+ // exactly the derivations commitInstall/parkOldNameDir use.
816
+ const stagingRoot = join(defsDir, STAGING_DIRNAME);
817
+ const stagingDir = join(stagingRoot, journal.stagingId);
818
+ const backupDir = `${stagingDir}-old`;
819
+ const undoDir = `${stagingDir}-undo`;
820
+ const parkedOldName = `${undoDir}-oldname`;
821
+ const dest = join(defsDir, journal.folder);
822
+ const oldNameOriginal = journal.oldNamePath !== undefined ? join(defsDir, journal.oldNamePath) : undefined;
823
+ // Symlink-guard the staging ROOT itself before deriving any mutation from it.
824
+ // `dispatchAdd`'s `mkdirRefusingSymlink` guards `.owenloop` and the default
825
+ // defsDir, but NOT `<defsDir>/.owenloop-staging` — and stagingDir/backupDir/
826
+ // undoDir/parkedOldName all hang off it, so a hostile checkout that ships
827
+ // `.owenloop-staging` as a symlink would make every rename/rm below act
828
+ // through it, moving/deleting dirs OUTSIDE defsDir. `lstat` (never `stat`) so
829
+ // the link is seen as a link; a non-dir squatting there is refused too; absent
830
+ // is fine (a fresh recovery mkdirs it). This runs BEFORE any fs mutation, and
831
+ // recovery now precedes dispatchAdd's `rmSync(stagingRoot)`, so nothing else
832
+ // clears it first.
833
+ const stagingRootSt = lstatSync(stagingRoot, { throwIfNoEntry: false });
834
+ if (stagingRootSt?.isSymbolicLink()) {
835
+ throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is a symlink`);
836
+ }
837
+ if (stagingRootSt && !stagingRootSt.isDirectory()) {
838
+ throw recoveryRefusal(journalPath, `staging root '${stagingRoot}' is not a directory`);
839
+ }
840
+ // Belt-and-braces containment: re-assert that EVERY rename/rm source and target
841
+ // resolves under defsDir — not just dest/oldNameOriginal, but every staging-
842
+ // root-derived path too (a crafted journal + a symlinked staging root must not
843
+ // drive a mutation outside the tree). Single-segment folder/oldNamePath/
844
+ // stagingId already make lexical traversal unrepresentable; this is the extra
845
+ // guard the review asked for on the staging-derived paths.
846
+ for (const p of [stagingRoot, stagingDir, backupDir, undoDir, parkedOldName, dest]) {
847
+ assertUnderDefs(p, defsDir, journalPath);
848
+ }
849
+ if (oldNameOriginal !== undefined)
850
+ assertUnderDefs(oldNameOriginal, defsDir, journalPath);
851
+ // Roll forward: the ledger is durably new; discard the retained backup + parked
852
+ // old-name dir and clear the staging root, then drop the journal. Symlink-
853
+ // guarded before each rm; both dirs live under the staging root, so the final
854
+ // clear is the real cleanup — the explicit rms honor "refuse a symlink" first.
855
+ const rollForward = () => {
856
+ if (probeRecoveryDir(backupDir, journalPath, 'backup dir') === 'dir') {
857
+ rmSync(backupDir, { recursive: true, force: true });
858
+ }
859
+ if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
860
+ rmSync(parkedOldName, { recursive: true, force: true });
861
+ }
862
+ rmSync(stagingRoot, { recursive: true, force: true });
863
+ removeAddJournal(journalPath);
864
+ };
865
+ if (journal.phase === 'finalizing') {
866
+ rollForward();
867
+ return 'rolled-forward';
868
+ }
869
+ // phase === 'applying': the ledger write may or may not have landed. Read it
870
+ // (fail-closed validation applies — a corrupt ledger aborts the add exactly as
871
+ // it does today) and check whether it already records this exact install.
872
+ const lf = readLockfile(lockfilePath);
873
+ const installed = lf.installed[journal.source];
874
+ if (installed && installed.sha === journal.sha && installed.path === journal.folder) {
875
+ // The ledger records this exact source@sha — but a ledger match ALONE does
876
+ // NOT prove the commit swap landed. Branch on ACTUAL disk state:
877
+ // - dest PRESENT ⇒ the swap completed (a crash in the writeLockfile→phase-
878
+ // rewrite window, or a same-sha re-add already past the swap): dest holds
879
+ // that sha's content, so (defs ⇔ ledger) is consistent ⇒ roll forward
880
+ // (discard the now-stale backup).
881
+ // - dest ABSENT ⇒ we are inside commitInstall's 4a→4b window of a SAME-sha
882
+ // re-add (dest was renamed to backupDir, and the staging→dest swap never
883
+ // ran). backupDir now holds the ONLY copy of the content. Rolling forward
884
+ // would `rmSync` it — silent data loss, leaving the ledger claiming an
885
+ // install that is gone from disk. Fall THROUGH to the roll-back table,
886
+ // which restores backupDir → dest; the ledger already records this sha, so
887
+ // the restored state is consistent. The two cases are distinguishable by
888
+ // disk, so branch on it rather than trusting the ledger match alone.
889
+ if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
890
+ rollForward();
891
+ return 'rolled-forward';
892
+ }
893
+ }
894
+ // ROLL BACK — restore the pre-commit directory state. Guarded idempotent
895
+ // renames mirroring rollbackInstallCommit's order; a symlinked source is
896
+ // refused fail-closed at each probe.
897
+ mkdirSync(stagingRoot, { recursive: true }); // ensure undo/backup renames have a home
898
+ const stagingState = probeRecoveryDir(stagingDir, journalPath, 'staging dir');
899
+ const backupState = probeRecoveryDir(backupDir, journalPath, 'backup dir');
900
+ if (stagingState === 'dir') {
901
+ // (a) Swap 4b (staging → dest) never happened.
902
+ if (backupState === 'dir') {
903
+ // Crash between 4a (dest → backup) and 4b: dest is necessarily absent.
904
+ // Restore the backup. Fail closed if dest unexpectedly exists too.
905
+ if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
906
+ throw recoveryRefusal(journalPath, `both the backup dir and destination '${dest}' exist`);
907
+ }
908
+ renameSync(backupDir, dest);
909
+ }
910
+ // else backup absent: dest still holds the original (upgrade, pre-backup) or
911
+ // is absent (fresh install, pre-swap) — already consistent, nothing to move.
912
+ }
913
+ else if (backupState === 'dir') {
914
+ // (b) Staging gone, backup present — an upgrade crashed AFTER the swap.
915
+ if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
916
+ // Park the new content aside, then restore the backup over dest.
917
+ if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
918
+ throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
919
+ }
920
+ renameSync(dest, undoDir);
921
+ renameSync(backupDir, dest);
922
+ }
923
+ else {
924
+ // dest absent: a prior rollback/recovery died between its two renames (the
925
+ // new content is already parked under undoDir) — just restore the backup.
926
+ renameSync(backupDir, dest);
927
+ }
928
+ }
929
+ else {
930
+ // (c) Staging gone, backup gone.
931
+ if (!journal.hadDest) {
932
+ // Fresh install: the swap may have put new content at dest. Discarding it
933
+ // (rename → undoDir, then rm with the staging root at step (e)) is the ONLY
934
+ // destructive arm that acts on the word of the journal alone — staging and
935
+ // backup are both absent by definition of case (c), so the journal is the
936
+ // only thing asserting this dir is a crash orphan. But the journal lives in
937
+ // repository-controlled content (`.owenloop/add.journal` is committable), so
938
+ // a hostile checkout can forge a schema-VALID `applying`/`hadDest:false`
939
+ // journal naming an existing UNRELATED workflow dir and drive its deletion.
940
+ // Fail closed: only delete when the LEDGER corroborates that this dest is a
941
+ // fresh hashed dir left by an interrupted OLD-NAME MIGRATION — i.e. the
942
+ // ledger still records `journal.source` at the migration's old-name path
943
+ // (`installed.path === journal.oldNamePath`). That is exactly the state of
944
+ // the corroborated old-name-migration crash; the parked old-name dir is NOT
945
+ // required as evidence (a crash in the swap→park window legitimately has no
946
+ // parked dir yet). Anything else — no ledger entry, or an entry at some
947
+ // other path (including `journal.folder` itself, which contradicts
948
+ // `hadDest:false`) — is uncorroborated: refuse, mutate nothing, leave the
949
+ // journal AND dest in place as evidence.
950
+ //
951
+ // Deliberate, documented regression: the genuine fresh-install crash between
952
+ // the swap and the ledger write (dest present, no ledger, no staging, no
953
+ // backup) is on-disk INDISTINGUISHABLE from the forgery — every
954
+ // distinguishing artifact is itself repo-committable and therefore forgeable
955
+ // — so it now fails closed here instead of auto-discarding. The error names
956
+ // the manual remedy. Raising the bar from "journal alone" to "journal +
957
+ // corroborating ledger" is the scope; moving/authenticating recovery state
958
+ // OUTSIDE repository-controlled content is the tracked follow-up (an attacker
959
+ // who forges BOTH the journal and a matching ledger old-name entry — or a
960
+ // backup dir, reaching case (b) — can still drive destructive recovery).
961
+ if (probeRecoveryDir(dest, journalPath, 'destination') === 'dir') {
962
+ const migrationCorroborated = journal.oldNamePath !== undefined &&
963
+ installed !== undefined &&
964
+ installed.path === journal.oldNamePath;
965
+ if (!migrationCorroborated) {
966
+ throw recoveryRefusal(journalPath, `journal claims an interrupted fresh install of '${journal.folder}', but nothing ` +
967
+ `corroborates it (no ledger entry for this source at the journal's old-name path, ` +
968
+ `no staging dir, no backup) while '${dest}' exists — refusing to discard that ` +
969
+ `directory. If you did not run an interrupted add in this checkout, remove the ` +
970
+ `journal; if a fresh install really was interrupted, remove '${dest}' as well`);
971
+ }
972
+ if (probeRecoveryDir(undoDir, journalPath, 'undo dir') === 'dir') {
973
+ throw recoveryRefusal(journalPath, `undo dir '${undoDir}' already exists`);
974
+ }
975
+ renameSync(dest, undoDir);
976
+ }
977
+ }
978
+ // hadDest === true: the backup was already restored (a completed in-process
979
+ // rollback whose journal-remove failed, or a prior recovery attempt) — dirs
980
+ // are consistent; touch nothing.
981
+ }
982
+ // (d) Restore a parked old-name dir to where the (unchanged) ledger expects it.
983
+ if (oldNameOriginal !== undefined) {
984
+ if (probeRecoveryDir(parkedOldName, journalPath, 'parked old-name dir') === 'dir') {
985
+ if (probeRecoveryDir(oldNameOriginal, journalPath, 'old-name original') === 'dir') {
986
+ // Both present is contradictory — unreachable under the single-writer
987
+ // lock, so don't guess which to keep.
988
+ throw recoveryRefusal(journalPath, `both the parked old-name dir and its original '${oldNameOriginal}' exist`);
989
+ }
990
+ renameSync(parkedOldName, oldNameOriginal);
991
+ }
992
+ // parked absent ⇒ already restored (idempotent re-run) — skip.
993
+ }
994
+ // (e) The undo/backup leftovers are debris now; clear the staging root and
995
+ // remove the journal LAST so a crash before this leaves everything replayable.
996
+ rmSync(stagingRoot, { recursive: true, force: true });
997
+ removeAddJournal(journalPath);
998
+ return 'rolled-back';
999
+ }