@indigoai-us/hq-cloud 6.16.50 → 6.16.51-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (147) hide show
  1. package/dist/bin/rescue-runner.js +1 -2
  2. package/dist/bin/rescue-runner.js.map +1 -1
  3. package/dist/bin/sync-runner-company.d.ts +6 -0
  4. package/dist/bin/sync-runner-company.d.ts.map +1 -1
  5. package/dist/bin/sync-runner-company.js +30 -1
  6. package/dist/bin/sync-runner-company.js.map +1 -1
  7. package/dist/bin/sync-runner-company.test.js +55 -0
  8. package/dist/bin/sync-runner-company.test.js.map +1 -1
  9. package/dist/bin/sync-runner-planning.d.ts +12 -3
  10. package/dist/bin/sync-runner-planning.d.ts.map +1 -1
  11. package/dist/bin/sync-runner-planning.js +65 -3
  12. package/dist/bin/sync-runner-planning.js.map +1 -1
  13. package/dist/bin/sync-runner-planning.test.js +108 -1
  14. package/dist/bin/sync-runner-planning.test.js.map +1 -1
  15. package/dist/bin/sync-runner-watch-loop.d.ts +48 -2
  16. package/dist/bin/sync-runner-watch-loop.d.ts.map +1 -1
  17. package/dist/bin/sync-runner-watch-loop.js +281 -113
  18. package/dist/bin/sync-runner-watch-loop.js.map +1 -1
  19. package/dist/bin/sync-runner.d.ts +33 -5
  20. package/dist/bin/sync-runner.d.ts.map +1 -1
  21. package/dist/bin/sync-runner.js +34 -4
  22. package/dist/bin/sync-runner.js.map +1 -1
  23. package/dist/bin/sync-runner.test.js +555 -78
  24. package/dist/bin/sync-runner.test.js.map +1 -1
  25. package/dist/cli/onepass-pull-planner-regressions.test.d.ts +2 -0
  26. package/dist/cli/onepass-pull-planner-regressions.test.d.ts.map +1 -0
  27. package/dist/cli/onepass-pull-planner-regressions.test.js +300 -0
  28. package/dist/cli/onepass-pull-planner-regressions.test.js.map +1 -0
  29. package/dist/cli/onepass-pull-planner.test.d.ts +2 -0
  30. package/dist/cli/onepass-pull-planner.test.d.ts.map +1 -0
  31. package/dist/cli/onepass-pull-planner.test.js +266 -0
  32. package/dist/cli/onepass-pull-planner.test.js.map +1 -0
  33. package/dist/cli/rescue-core.d.ts +0 -31
  34. package/dist/cli/rescue-core.d.ts.map +1 -1
  35. package/dist/cli/rescue-core.js +63 -596
  36. package/dist/cli/rescue-core.js.map +1 -1
  37. package/dist/cli/rescue-rsync-preflight.test.js +4 -256
  38. package/dist/cli/rescue-rsync-preflight.test.js.map +1 -1
  39. package/dist/cli/rescue.d.ts +0 -4
  40. package/dist/cli/rescue.d.ts.map +1 -1
  41. package/dist/cli/rescue.js +1 -20
  42. package/dist/cli/rescue.js.map +1 -1
  43. package/dist/cli/rescue.test.js +1 -16
  44. package/dist/cli/rescue.test.js.map +1 -1
  45. package/dist/cli/share-presign-transport.test.js +0 -2
  46. package/dist/cli/share-presign-transport.test.js.map +1 -1
  47. package/dist/cli/share.d.ts +19 -0
  48. package/dist/cli/share.d.ts.map +1 -1
  49. package/dist/cli/share.js +57 -37
  50. package/dist/cli/share.js.map +1 -1
  51. package/dist/cli/share.test.js +87 -93
  52. package/dist/cli/share.test.js.map +1 -1
  53. package/dist/cli/streaming-pull-planner.bench.test.d.ts +15 -0
  54. package/dist/cli/streaming-pull-planner.bench.test.d.ts.map +1 -0
  55. package/dist/cli/streaming-pull-planner.bench.test.js +273 -0
  56. package/dist/cli/streaming-pull-planner.bench.test.js.map +1 -0
  57. package/dist/cli/sync-scope.test.js +8 -0
  58. package/dist/cli/sync-scope.test.js.map +1 -1
  59. package/dist/cli/sync.d.ts +12 -0
  60. package/dist/cli/sync.d.ts.map +1 -1
  61. package/dist/cli/sync.js +226 -118
  62. package/dist/cli/sync.js.map +1 -1
  63. package/dist/cli/sync.test.js +215 -2
  64. package/dist/cli/sync.test.js.map +1 -1
  65. package/dist/cli/watch-event-push-conflict.test.js +0 -2
  66. package/dist/cli/watch-event-push-conflict.test.js.map +1 -1
  67. package/dist/cognito-auth.d.ts +0 -30
  68. package/dist/cognito-auth.d.ts.map +1 -1
  69. package/dist/cognito-auth.js +0 -175
  70. package/dist/cognito-auth.js.map +1 -1
  71. package/dist/index.d.ts +2 -2
  72. package/dist/index.d.ts.map +1 -1
  73. package/dist/index.js +1 -1
  74. package/dist/index.js.map +1 -1
  75. package/dist/journal-store.test.js +130 -7
  76. package/dist/journal-store.test.js.map +1 -1
  77. package/dist/journal.d.ts +9 -1
  78. package/dist/journal.d.ts.map +1 -1
  79. package/dist/journal.js +30 -21
  80. package/dist/journal.js.map +1 -1
  81. package/dist/lib/exit-codes.d.ts +15 -0
  82. package/dist/lib/exit-codes.d.ts.map +1 -1
  83. package/dist/lib/exit-codes.js +15 -0
  84. package/dist/lib/exit-codes.js.map +1 -1
  85. package/dist/machine-auth.test.js +0 -295
  86. package/dist/machine-auth.test.js.map +1 -1
  87. package/dist/object-io.d.ts +2 -2
  88. package/dist/object-io.d.ts.map +1 -1
  89. package/dist/object-io.js +3 -18
  90. package/dist/object-io.js.map +1 -1
  91. package/dist/personal-vault.d.ts.map +1 -1
  92. package/dist/personal-vault.js +10 -3
  93. package/dist/personal-vault.js.map +1 -1
  94. package/dist/personal-vault.test.js +35 -0
  95. package/dist/personal-vault.test.js.map +1 -1
  96. package/dist/remote-pull.d.ts.map +1 -1
  97. package/dist/remote-pull.js +9 -2
  98. package/dist/remote-pull.js.map +1 -1
  99. package/dist/remote-pull.test.js +59 -2
  100. package/dist/remote-pull.test.js.map +1 -1
  101. package/dist/s3.d.ts +1 -18
  102. package/dist/s3.d.ts.map +1 -1
  103. package/dist/s3.js +24 -47
  104. package/dist/s3.js.map +1 -1
  105. package/dist/s3.list-cost.test.d.ts +2 -0
  106. package/dist/s3.list-cost.test.d.ts.map +1 -0
  107. package/dist/s3.list-cost.test.js +51 -0
  108. package/dist/s3.list-cost.test.js.map +1 -0
  109. package/dist/s3.test.js +1 -27
  110. package/dist/s3.test.js.map +1 -1
  111. package/dist/sync/realtime-telemetry.d.ts +1 -1
  112. package/dist/sync/realtime-telemetry.d.ts.map +1 -1
  113. package/dist/sync/realtime-telemetry.js +14 -6
  114. package/dist/sync/realtime-telemetry.js.map +1 -1
  115. package/dist/sync/realtime-telemetry.test.js +136 -16
  116. package/dist/sync/realtime-telemetry.test.js.map +1 -1
  117. package/dist/sync/remote-file-spool.d.ts +16 -0
  118. package/dist/sync/remote-file-spool.d.ts.map +1 -0
  119. package/dist/sync/remote-file-spool.js +91 -0
  120. package/dist/sync/remote-file-spool.js.map +1 -0
  121. package/dist/sync/remote-file-spool.test.d.ts +2 -0
  122. package/dist/sync/remote-file-spool.test.d.ts.map +1 -0
  123. package/dist/sync/remote-file-spool.test.js +77 -0
  124. package/dist/sync/remote-file-spool.test.js.map +1 -0
  125. package/dist/sync-core.d.ts +4 -6
  126. package/dist/sync-core.d.ts.map +1 -1
  127. package/dist/sync-core.js +4 -10
  128. package/dist/sync-core.js.map +1 -1
  129. package/dist/sync-core.test.js +1 -25
  130. package/dist/sync-core.test.js.map +1 -1
  131. package/package.json +2 -1
  132. package/dist/cli/rescue-breaker.test.d.ts +0 -2
  133. package/dist/cli/rescue-breaker.test.d.ts.map +0 -1
  134. package/dist/cli/rescue-breaker.test.js +0 -334
  135. package/dist/cli/rescue-breaker.test.js.map +0 -1
  136. package/dist/cli/rescue-realpath.test.d.ts +0 -2
  137. package/dist/cli/rescue-realpath.test.d.ts.map +0 -1
  138. package/dist/cli/rescue-realpath.test.js +0 -109
  139. package/dist/cli/rescue-realpath.test.js.map +0 -1
  140. package/dist/cli/rescue-snapshot-recovery.test.d.ts +0 -2
  141. package/dist/cli/rescue-snapshot-recovery.test.d.ts.map +0 -1
  142. package/dist/cli/rescue-snapshot-recovery.test.js +0 -260
  143. package/dist/cli/rescue-snapshot-recovery.test.js.map +0 -1
  144. package/dist/cli/rescue-source-switch-floor.test.d.ts +0 -2
  145. package/dist/cli/rescue-source-switch-floor.test.d.ts.map +0 -1
  146. package/dist/cli/rescue-source-switch-floor.test.js +0 -210
  147. package/dist/cli/rescue-source-switch-floor.test.js.map +0 -1
@@ -148,26 +148,10 @@ function boundedDiagnostic(value, limit) {
148
148
  function pathEntries(pathValue) {
149
149
  return pathValue ? pathValue.split(path.delimiter) : [];
150
150
  }
151
- const DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS = [".COM", ".EXE", ".BAT", ".CMD"];
152
- function rsyncCandidateNames(env) {
153
- if (process.platform !== "win32")
154
- return ["rsync", "rsync.exe"];
155
- const configuredExtensions = envValue(env, "PATHEXT")
156
- ?.split(";")
157
- .map((extension) => extension.trim())
158
- .filter((extension) => /^\.[A-Za-z0-9]+$/.test(extension));
159
- const extensions = [
160
- ...(configuredExtensions?.length
161
- ? configuredExtensions
162
- : DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS),
163
- ...DEFAULT_WINDOWS_EXECUTABLE_EXTENSIONS,
164
- ];
165
- return [...new Set(["rsync", ...extensions.map((extension) => `rsync${extension.toLowerCase()}`)])];
166
- }
167
- export function findRsyncOnPath(entries, env) {
151
+ function findRsyncOnPath(entries) {
168
152
  let firstUnexecutable;
169
153
  for (const entry of entries) {
170
- for (const name of rsyncCandidateNames(env)) {
154
+ for (const name of ["rsync", "rsync.exe"]) {
171
155
  const candidate = path.resolve(entry || ".", name);
172
156
  try {
173
157
  if (!fs.statSync(candidate).isFile())
@@ -190,22 +174,14 @@ export function findRsyncOnPath(entries, env) {
190
174
  : undefined;
191
175
  }
192
176
  /** The overlay requires rsync; do not allocate a recovery copy when it cannot run. */
193
- export function requireWorkingRsync(env, err) {
177
+ function requireWorkingRsync(env, err) {
194
178
  const resolvedPath = envValue(env, "PATH");
195
179
  const entries = pathEntries(resolvedPath);
196
- const foundRsync = findRsyncOnPath(entries, env);
197
- // Node documents that Windows .cmd/.bat files require cmd.exe rather than a
198
- // direct child-process launch. Keep the path and fixed argument as distinct
199
- // arguments instead of enabling shell:true for a constructed command string.
200
- const launcher = process.platform === "win32" && /\.(?:cmd|bat)$/i.test(foundRsync?.path ?? "")
201
- ? { command: "cmd.exe", leadingArgs: ["/d", "/s", "/c", foundRsync.path] }
202
- : { command: "rsync", leadingArgs: [] };
203
- const probe = runWithSpawnError(launcher.command, [...launcher.leadingArgs, "--version"], {
204
- env,
205
- });
180
+ const foundRsync = findRsyncOnPath(entries);
181
+ const probe = runWithSpawnError("rsync", ["--version"], { env });
206
182
  const output = `${probe.stdout}\n${probe.stderr}`;
207
183
  if (probe.status === 0 && /\brsync\b.*\bversion\b/i.test(output))
208
- return launcher;
184
+ return;
209
185
  err("error: rsync preflight failed before any safety snapshot was allocated.\n");
210
186
  if (probe.error) {
211
187
  const errorDetail = "code" in probe.error && typeof probe.error.code === "string"
@@ -327,8 +303,6 @@ export function parseRescueArgs(argv) {
327
303
  backupRoot: process.env.HQ_BACKUP_DIR || path.join(os.homedir(), ".hq", "backups"),
328
304
  backupRetentionDays: process.env.HQ_BACKUP_RETENTION_DAYS || "7",
329
305
  backupRetentionCount: process.env.HQ_BACKUP_RETENTION_COUNT || "2",
330
- recoverSnapshots: false,
331
- verifyRestoredSnapshot: "",
332
306
  };
333
307
  const usage = () => {
334
308
  // The legacy script printed its comment header here; we emit a concise
@@ -337,8 +311,7 @@ export function parseRescueArgs(argv) {
337
311
  " [--preserve PATH]... [--preserve-subpath REL]...\n" +
338
312
  " [--hq-root DIR] [--no-history-check] [--floor-sha SHA]\n" +
339
313
  " [--no-backup] [--backup-dir DIR] [--cloud-update]\n" +
340
- " [--dry-run] [--yes] [--recover-snapshots]\n" +
341
- " [--verify-restored-snapshot SNAPSHOT]\n");
314
+ " [--dry-run] [--yes]\n");
342
315
  throw new ExitError(1);
343
316
  };
344
317
  let narrowCsv = "";
@@ -387,16 +360,6 @@ export function parseRescueArgs(argv) {
387
360
  case "--backup-dir":
388
361
  cfg.backupRoot = need(a);
389
362
  break;
390
- case "--recover-snapshots":
391
- cfg.recoverSnapshots = true;
392
- break;
393
- case "--verify-restored-snapshot":
394
- cfg.verifyRestoredSnapshot = need(a);
395
- if (!cfg.verifyRestoredSnapshot) {
396
- process.stderr.write("error: --verify-restored-snapshot requires a snapshot name.\n");
397
- throw new ExitError(2);
398
- }
399
- break;
400
363
  case "--dry-run":
401
364
  cfg.dryRun = true;
402
365
  break;
@@ -457,10 +420,6 @@ export function parseRescueArgs(argv) {
457
420
  throw new ExitError(2);
458
421
  }
459
422
  }
460
- if (cfg.verifyRestoredSnapshot && !cfg.recoverSnapshots) {
461
- process.stderr.write("error: --verify-restored-snapshot requires --recover-snapshots.\n");
462
- throw new ExitError(2);
463
- }
464
423
  return cfg;
465
424
  }
466
425
  /**
@@ -494,8 +453,6 @@ export function runRescue(argv, opts = {}) {
494
453
  }
495
454
  };
496
455
  try {
497
- if (cfg.recoverSnapshots)
498
- return recoverSnapshots(cfg, out, err);
499
456
  return doRescue(cfg, env, out, err, (d) => {
500
457
  tmpdir = d;
501
458
  });
@@ -509,8 +466,38 @@ export function runRescue(argv, opts = {}) {
509
466
  cleanup();
510
467
  }
511
468
  }
512
- /** Resolve and sanity-check the HQ root before either rescue mode can touch it. */
513
- function resolveHqRoot(cfg, err) {
469
+ /**
470
+ * True when `root` is usable as a rescue target: an absolute path that is not
471
+ * a bare drive letter. Pure + exported for tests; `platformPath` defaults to
472
+ * the host `path` module so Windows and POSIX runtimes each apply their own
473
+ * absoluteness rules (tests pass `path.win32` / `path.posix` explicitly).
474
+ *
475
+ * Rejecting bare `C:` matters even though `path.win32.isAbsolute("C:")` is
476
+ * already false — the explicit pattern documents the exact field failure and
477
+ * guards against a future helper swap that treats drive-relative paths as
478
+ * absolute.
479
+ */
480
+ export function isUsableRescueRoot(root, platformPath = path) {
481
+ if (/^[A-Za-z]:$/.test(root))
482
+ return false;
483
+ return platformPath.isAbsolute(root);
484
+ }
485
+ /**
486
+ * `fs.realpathSync` that converts failure into the rescue's clean error path
487
+ * (message + ExitError) instead of an uncaught exception. An uncaught throw
488
+ * here is what turned one bad `--hq-root` into a daily crash-loop on Windows.
489
+ */
490
+ function realpathOrExit(p, err) {
491
+ try {
492
+ return fs.realpathSync(p);
493
+ }
494
+ catch (e) {
495
+ err(`error: cannot resolve --hq-root ${p}: ${e instanceof Error ? e.message : String(e)}\n`);
496
+ throw new ExitError(1);
497
+ }
498
+ }
499
+ function doRescue(cfg, env, out, err, setTmp) {
500
+ // --- Resolve HQ root ---
514
501
  let hqRoot;
515
502
  if (cfg.hqRootOverride) {
516
503
  // Windows field failure (2026-08-02): the menubar app's daily background
@@ -557,264 +544,11 @@ function resolveHqRoot(cfg, err) {
557
544
  err(" pass --hq-root <dir> if the script is not at personal/skills/<skill>/.\n");
558
545
  throw new ExitError(3);
559
546
  }
560
- return hqRoot;
561
- }
562
- /**
563
- * Explicit recovery surface for a previously interrupted rescue.
564
- *
565
- * A recovery-required snapshot is evidence that a rescue started changing the
566
- * release-managed tree and then failed. It is safe to delete only when the
567
- * retention model has a later `completed-good` snapshot for this same canonical
568
- * HQ root. That later manifest is the durable proof that a subsequent rescue
569
- * completed; an age, an empty current tree, or a manually edited sync stamp is
570
- * deliberately not accepted as proof.
571
- */
572
- function recoverSnapshots(cfg, out, err) {
573
- const hqRoot = resolveHqRoot(cfg, err);
574
- const retention = {
575
- keepGood: Number(cfg.backupRetentionCount),
576
- maxAgeDays: Number(cfg.backupRetentionDays),
577
- };
578
- const isCopyingOwnerLive = (m) => {
579
- try {
580
- process.kill(m.creatorPid, 0);
581
- return true;
582
- }
583
- catch {
584
- return false;
585
- }
586
- };
587
- const inventory = inventoryManagedSnapshots(cfg.backupRoot, hqRoot, isCopyingOwnerLive, retention);
588
- if (inventory.unmanaged.some((item) => item.reason === "backup-root-unreadable")) {
589
- err(`error: cannot inspect safety snapshots: backup root is unreadable: ${cfg.backupRoot}\n`);
590
- return { status: 1 };
591
- }
592
- if (cfg.verifyRestoredSnapshot) {
593
- return verifyRestoredSnapshot(cfg, hqRoot, inventory.entries, inventory.protected, out, err);
594
- }
595
- const verified = inventory.candidates.filter((item) => item.entry.manifest.status === "recovery-required" &&
596
- item.reason === "recovery-required-superseded");
597
- const blocked = inventory.protected.filter((item) => item.reason === "recovery-required-no-later-good");
598
- const retainedByGrace = inventory.protected.filter((item) => item.entry.manifest.status === "recovery-required" &&
599
- item.reason !== "recovery-required-no-later-good");
600
- const laterGoodFor = (completedMs, name) => inventory.entries.find((entry) => entry.manifest.status === "completed-good" &&
601
- (entry.completedMs > completedMs ||
602
- (entry.completedMs === completedMs && entry.name > name)))?.name;
603
- out(`==> Safety snapshot recovery inspection: ${cfg.backupRoot}\n`);
604
- if (verified.length === 0 && blocked.length === 0 && retainedByGrace.length === 0) {
605
- out(" No recovery-required snapshots need action.\n");
606
- return { status: 0 };
607
- }
608
- for (const item of verified) {
609
- const laterGood = laterGoodFor(item.entry.completedMs, item.entry.name);
610
- out(` verified ${item.entry.name}: later completed-good snapshot ${laterGood ?? "(revalidated during delete)"} proves this recovery evidence is superseded.\n`);
611
- }
612
- for (const item of blocked) {
613
- out(` retained ${item.entry.name}: no later completed-good snapshot exists for this HQ root.\n`);
614
- }
615
- for (const item of retainedByGrace) {
616
- out(` retained ${item.entry.name}: a later completed-good snapshot exists, but normal retention still keeps this newest recovery snapshot.\n`);
617
- }
618
- if (verified.length > 0) {
619
- if (cfg.dryRun) {
620
- for (const item of verified) {
621
- out(` would resolve ${item.entry.name}: verified superseded recovery snapshot would be retained during this dry run.\n`);
622
- }
623
- }
624
- else {
625
- const result = applyBackupPrune(cfg.backupRoot, hqRoot, { candidates: verified, protected: [], unmanaged: [] }, retention);
626
- for (const name of result.deleted) {
627
- out(` resolved ${name}: verified superseded recovery snapshot deleted.\n`);
628
- }
629
- for (const failure of result.failures) {
630
- err(`error: could not resolve verified snapshot (retained): ${failure}\n`);
631
- }
632
- if (result.failures.length > 0)
633
- return { status: 1 };
634
- }
635
- }
636
- if (cfg.dryRun && blocked.length === 0) {
637
- out("==> Snapshot recovery dry run complete: no snapshot was changed.\n");
638
- return { status: 0 };
639
- }
640
- // Re-inventory after an apply because another process might have created or
641
- // changed a snapshot while the prune lock was held. Nothing unverified has
642
- // been deleted, and the updated inventory is the report we return to users.
643
- const remaining = inventoryManagedSnapshots(cfg.backupRoot, hqRoot, isCopyingOwnerLive, retention);
644
- const unresolved = remaining.protected.filter((item) => item.reason === "recovery-required-no-later-good");
645
- if (unresolved.length > 0) {
646
- err("error: snapshot recovery refused: the interrupted updates are not proven superseded.\n");
647
- err(" HQ retained every unverified snapshot. A later completed-good rescue for this same HQ root is the only automatic proof.\n");
648
- err(" Restore every captured root from one snapshot, then verify that restored tree before one retry is permitted:\n");
649
- for (const item of unresolved) {
650
- err(` ${item.entry.name}: ${formatRecoveryCommand(hqRoot, cfg.backupRoot, item.entry.name)}\n`);
651
- }
652
- return { status: 1 };
653
- }
654
- out("==> Snapshot recovery complete: every eligible recovery snapshot was positively verified before deletion.\n");
655
- return { status: 0 };
656
- }
657
- /** A live tree must still match the selected recovery snapshot at permit use. */
658
- function verifyRestoredSnapshot(cfg, hqRoot, entries, protectedEntries, out, err) {
659
- const entry = entries.find((item) => item.name === cfg.verifyRestoredSnapshot);
660
- const unresolved = protectedEntries.find((item) => item.entry.name === cfg.verifyRestoredSnapshot &&
661
- item.reason === "recovery-required-no-later-good");
662
- if (!entry || !unresolved || entry.manifest.status !== "recovery-required") {
663
- err(`error: ${cfg.verifyRestoredSnapshot} is not an unresolved recovery-required snapshot for this HQ root.\n`);
664
- return { status: 1 };
665
- }
666
- const mismatch = snapshotTreeMismatch(path.join(cfg.backupRoot, entry.name), hqRoot, entry.manifest.includedRoots);
667
- if (mismatch) {
668
- err(`error: restored tree does not match snapshot ${entry.name}: ${mismatch}\n`);
669
- err(" No post-restore permit was written; the circuit breaker remains armed.\n");
670
- return { status: 1 };
671
- }
672
- if (cfg.dryRun) {
673
- out(`==> Dry run verified restored snapshot ${entry.name}; no post-restore permit was written.\n`);
674
- return { status: 0 };
675
- }
676
- try {
677
- writePostRestorePermit(hqRoot, entry);
678
- }
679
- catch (error) {
680
- err(`error: verified snapshot ${entry.name}, but could not write the post-restore permit: ${error instanceof Error ? error.message : String(error)}\n`);
681
- return { status: 1 };
682
- }
683
- out(`==> Verified restored snapshot ${entry.name}; one rescue attempt is now permitted.\n`);
684
- out(" That permit is rechecked and consumed before rescue changes files. If the attempt fails, the circuit breaker is armed again.\n");
685
- return { status: 0 };
686
- }
687
- /** Return a precise mismatch instead of treating a partial restore as evidence. */
688
- function snapshotTreeMismatch(snapshotRoot, hqRoot, includedRoots) {
689
- if (includedRoots.length === 0) {
690
- return "snapshot manifest records no captured roots to verify";
691
- }
692
- const seen = new Set();
693
- for (const root of includedRoots) {
694
- if (!root ||
695
- root === "." ||
696
- root === ".." ||
697
- root.includes("/") ||
698
- root.includes("\\") ||
699
- isRescueTransientDirectory(root) ||
700
- seen.has(root)) {
701
- return `snapshot manifest has an unsafe captured root ${JSON.stringify(root)}`;
702
- }
703
- seen.add(root);
704
- if (rescuePathKind(path.join(snapshotRoot, root)) === "missing") {
705
- return `snapshot does not contain captured root ${root}`;
706
- }
707
- const mismatch = snapshotPathMismatch(path.join(snapshotRoot, root), path.join(hqRoot, root), root);
708
- if (mismatch)
709
- return mismatch;
710
- }
711
- return null;
712
- }
713
- function snapshotPathMismatch(snapshotPath, livePath, rel) {
714
- const snapshotKind = rescuePathKind(snapshotPath);
715
- const liveKind = rescuePathKind(livePath);
716
- if (snapshotKind !== liveKind) {
717
- return `${rel} is ${liveKind} but the snapshot records ${snapshotKind}`;
718
- }
719
- if (snapshotKind === "missing")
720
- return null;
721
- if (snapshotKind === "file") {
722
- return bytesEqual(snapshotPath, livePath)
723
- ? null
724
- : `${rel} has different file contents`;
725
- }
726
- if (snapshotKind === "symlink") {
727
- try {
728
- return fs.readlinkSync(snapshotPath) === fs.readlinkSync(livePath)
729
- ? null
730
- : `${rel} has a different symlink target`;
731
- }
732
- catch (error) {
733
- return `${rel} could not read a symlink target: ${error instanceof Error ? error.message : String(error)}`;
734
- }
735
- }
736
- if (snapshotKind !== "directory") {
737
- return `${rel} has unsupported path type ${snapshotKind}`;
738
- }
739
- let snapshotNames;
740
- let liveNames;
741
- try {
742
- snapshotNames = fs
743
- .readdirSync(snapshotPath)
744
- .filter((name) => !isRescueTransientDirectory(path.posix.join(rel, name)))
745
- .sort();
746
- liveNames = fs
747
- .readdirSync(livePath)
748
- .filter((name) => !isRescueTransientDirectory(path.posix.join(rel, name)))
749
- .sort();
750
- }
751
- catch (error) {
752
- return `${rel} could not be read: ${error instanceof Error ? error.message : String(error)}`;
753
- }
754
- if (snapshotNames.length !== liveNames.length ||
755
- snapshotNames.some((name, index) => name !== liveNames[index])) {
756
- return `${rel} has different entries`;
757
- }
758
- for (const name of snapshotNames) {
759
- const mismatch = snapshotPathMismatch(path.join(snapshotPath, name), path.join(livePath, name), path.posix.join(rel, name));
760
- if (mismatch)
761
- return mismatch;
762
- }
763
- return null;
764
- }
765
- /**
766
- * True when `root` is usable as a rescue target: an absolute path that is not
767
- * a bare drive letter. Pure + exported for tests; `platformPath` defaults to
768
- * the host `path` module so Windows and POSIX runtimes each apply their own
769
- * absoluteness rules (tests pass `path.win32` / `path.posix` explicitly).
770
- *
771
- * Rejecting bare `C:` matters even though `path.win32.isAbsolute("C:")` is
772
- * already false — the explicit pattern documents the exact field failure and
773
- * guards against a future helper swap that treats drive-relative paths as
774
- * absolute.
775
- */
776
- export function isUsableRescueRoot(root, platformPath = path) {
777
- if (/^[A-Za-z]:$/.test(root))
778
- return false;
779
- return platformPath.isAbsolute(root);
780
- }
781
- /**
782
- * Canonicalize the rescue root without treating a known-good directory as
783
- * unusable when Node's JavaScript realpath walker cannot inspect a Windows
784
- * drive prefix. Prefer the native syscall, retain the JS walker as a fallback,
785
- * and use an absolute path only after stat confirms it is a directory.
786
- */
787
- export function realpathOrExit(p, err) {
788
- try {
789
- return fs.realpathSync.native(p);
790
- }
791
- catch {
792
- try {
793
- return fs.realpathSync(p);
794
- }
795
- catch (realpathError) {
796
- const resolved = path.resolve(p);
797
- try {
798
- if (!fs.statSync(resolved).isDirectory()) {
799
- throw new Error("resolved path is not a directory");
800
- }
801
- }
802
- catch {
803
- err(`error: cannot resolve --hq-root ${p}: ${realpathError instanceof Error ? realpathError.message : String(realpathError)}\n`);
804
- throw new ExitError(1);
805
- }
806
- err("warning: could not canonicalize --hq-root; using a normalized absolute path.\n");
807
- return resolved;
808
- }
809
- }
810
- }
811
- function doRescue(cfg, env, out, err, setTmp) {
812
- const hqRoot = resolveHqRoot(cfg, err);
813
547
  const RUN_TS = utcStamp(new Date(), "dash");
814
548
  // Both the release overlay and a restorable snapshot require rsync. A shim
815
549
  // which merely starts but exits non-zero used to trigger an enormous cp -a
816
550
  // fallback, then fail later at overlay. Stop before classification/allocation.
817
- const rsyncLauncher = requireWorkingRsync(env, err);
551
+ requireWorkingRsync(env, err);
818
552
  // --- Capture the pre-rescue .claude/settings.json (BEFORE the wipe) ---
819
553
  // This is `ours` for the post-overlay settings reconcile. It must be read now
820
554
  // because the overlay-safe classification deletes/overwrites it before
@@ -848,9 +582,8 @@ function doRescue(cfg, env, out, err, setTmp) {
848
582
  prevSyncRef = yq('.replaced_from_source.ref // .replaced_from_staging.ref // ""');
849
583
  prevSyncAt = yq('.replaced_from_source.last_sync_at // .replaced_from_staging.last_sync_at // ""');
850
584
  }
851
- // An explicit caller floor is the recovery path for a missing or stale stamp.
852
- // It remains safe because the selected release clone must still contain it.
853
- if (cfg.floorShaOverride) {
585
+ // Caller override (--floor-sha) wins only when the on-disk stamp is empty.
586
+ if (!prevSyncSha && cfg.floorShaOverride) {
854
587
  prevSyncSha = cfg.floorShaOverride;
855
588
  prevSyncSource = cfg.sourceRepo;
856
589
  prevSyncRef = "(caller-supplied floor)";
@@ -859,8 +592,12 @@ function doRescue(cfg, env, out, err, setTmp) {
859
592
  out(`==> HQ root: ${hqRoot}\n`);
860
593
  out(`==> Source: https://github.com/${cfg.sourceRepo} @ ${cfg.ref}\n`);
861
594
  if (prevSyncSha) {
862
- const sourceLabel = prevSyncSource || "(source not recorded)";
863
- out(`==> Prior sync: ${prevSyncSha} from ${sourceLabel}@${prevSyncRef} (${prevSyncAt}) — checking cloned release history for floor\n`);
595
+ if (prevSyncSource === cfg.sourceRepo) {
596
+ out(`==> Prior sync: ${prevSyncSha} from ${prevSyncSource}@${prevSyncRef} (${prevSyncAt}) — will use as history floor\n`);
597
+ }
598
+ else {
599
+ out(`==> Prior sync: ${prevSyncSha} from ${prevSyncSource} (different source — ignoring as floor)\n`);
600
+ }
864
601
  }
865
602
  if (cfg.narrowPaths.length !== 0) {
866
603
  out("==> Mode: narrow (--paths)\n");
@@ -1016,22 +753,21 @@ function doRescue(cfg, env, out, err, setTmp) {
1016
753
  // --- Resolve history floor ---
1017
754
  let historyFloor = "";
1018
755
  let baselineMode = "head_compare";
1019
- if (cfg.historyCheck && prevSyncSha) {
756
+ if (cfg.historyCheck && prevSyncSha && prevSyncSource === cfg.sourceRepo) {
1020
757
  if (run("git", ["cat-file", "-e", prevSyncSha], { cwd: srcDir, env })
1021
758
  .status === 0) {
1022
759
  historyFloor = prevSyncSha;
1023
760
  baselineMode = "history_floor";
1024
761
  }
1025
762
  else {
1026
- out(` WARN: prior-sync SHA ${prevSyncSha} is not reachable in the cloned release history; falling back to head_compare\n`);
763
+ out(` prior-sync SHA ${prevSyncSha} not reachable in clone (rebased/dropped?); falling back to head_compare\n`);
1027
764
  }
1028
765
  }
1029
766
  if (baselineMode === "history_floor") {
1030
767
  out(`==> Baseline: ${historyFloor} (last-sync floor reachable)\n`);
1031
768
  }
1032
769
  else {
1033
- out("==> Baseline: HEAD compare (no usable reachable last-sync floor)\n");
1034
- out("==> WARNING: retired release files cannot be detected or removed in head_compare mode. Re-run with history checking and --floor-sha <sha> for a reachable baseline.\n");
770
+ out("==> Baseline: HEAD compare (no usable last-sync stamp; first-ever run or stamp mismatch)\n");
1035
771
  }
1036
772
  // --- Build wipe/overlay arg sets per mode ---
1037
773
  const pruneNames = [];
@@ -1156,7 +892,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1156
892
  if (cfg.dryRun) {
1157
893
  out("\n");
1158
894
  out("==> DRY RUN classification summary:\n");
1159
- out(` user-only (left in place under release-managed roots): ${counts.userOnly} files\n`);
895
+ out(` user-only (leave in place): ${counts.userOnly} files\n`);
1160
896
  out(` unchanged (preserved/re-laid): ${counts.unchanged} files\n`);
1161
897
  out(` user-edit (rescue / diff-append): ${counts.userEdit} files\n`);
1162
898
  out(` user-edit (conflict quarantine): ${counts.userConflict} files\n`);
@@ -1232,21 +968,12 @@ function doRescue(cfg, env, out, err, setTmp) {
1232
968
  ];
1233
969
  // Exercise the exact overlay command before any classified delete/move. A
1234
970
  // Cygwin path conversion or filter failure therefore leaves the root intact.
1235
- const overlayPreflight = run(rsyncLauncher.command, [...rsyncLauncher.leadingArgs, "--dry-run", ...overlayArgs], { env });
971
+ const overlayPreflight = run("rsync", ["--dry-run", ...overlayArgs], { env });
1236
972
  if (overlayPreflight.status !== 0) {
1237
973
  err(overlayPreflight.stderr);
1238
974
  throw new ExitError(overlayPreflight.status || 1);
1239
975
  }
1240
976
  ctx.actions = buildRescueActions(ctx);
1241
- // Permission preflight is deliberately before snapshot allocation. A
1242
- // root-owned release tree (EACCES on rename/delete) used to allocate a
1243
- // snapshot, fail apply twice, and then freeze rescue behind the
1244
- // recovery-required circuit breaker. Fail closed with no snapshot instead.
1245
- const unwritable = collectUnwritableRescueMutationPaths(hqRoot, ctx.actions);
1246
- if (unwritable.length > 0) {
1247
- reportUnwritableRescuePaths(hqRoot, unwritable, err);
1248
- throw new ExitError(1);
1249
- }
1250
977
  // Snapshot allocation is deliberately after the entire read-only walk and
1251
978
  // action-plan build. A no-op (or a classifier fault above) cannot consume
1252
979
  // backup space.
@@ -1260,25 +987,9 @@ function doRescue(cfg, env, out, err, setTmp) {
1260
987
  const prePlan = pruneManagedBackups(cfg, hqRoot, out, false);
1261
988
  const unresolved = prePlan.protected.filter((x) => x.reason === "recovery-required-no-later-good");
1262
989
  if (unresolved.length >= 2) {
1263
- const postRestore = consumePostRestorePermit(cfg, hqRoot);
1264
- if (postRestore.used) {
1265
- out(`==> Verified post-restore permit for ${postRestore.snapshotName}; allowing one rescue attempt.\n`);
1266
- out(" The permit was consumed before mutation. If this attempt fails, the circuit breaker is armed again.\n");
1267
- }
1268
- else {
1269
- if (postRestore.problem) {
1270
- err(`error: post-restore permit is not usable: ${postRestore.problem}\n`);
1271
- }
1272
- const snapshotNames = unresolved.map((x) => x.entry.name);
1273
- writeRescueBlockedMarker(hqRoot, snapshotNames);
1274
- err("HQ_RESCUE_FAILURE_KIND=snapshot-recovery-circuit-breaker\n");
1275
- err("error: safety snapshot circuit breaker is open: two interrupted updates still need recovery proof.\n");
1276
- err(" HQ kept their pre-update snapshots because those updates started changing the release-managed tree but did not finish.\n");
1277
- err(" It will not overwrite or delete that evidence without proof that a later rescue completed successfully.\n");
1278
- err(` Inspect safely: ${formatRecoveryCommand(hqRoot, cfg.backupRoot)}\n`);
1279
- err(" It deletes only snapshots with a later completed-good rescue. For unresolved snapshots, restore one listed snapshot and run its verification command before retrying.\n");
1280
- throw new ExitError(1);
1281
- }
990
+ err("error: safety snapshot circuit breaker is open: two unresolved recovery-required snapshots exist.\n");
991
+ err(" Inspect/restore those snapshots and repair the release source before retrying (operator override required).\n");
992
+ throw new ExitError(1);
1282
993
  }
1283
994
  requireBackupCapacity(cfg, hqRoot, wipeToplevel, env, err);
1284
995
  fs.mkdirSync(cfg.backupRoot, { recursive: true });
@@ -1342,7 +1053,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1342
1053
  toCygwinRsyncPath(hqRoot + "/"),
1343
1054
  ]
1344
1055
  : overlayArgs;
1345
- const overlay = run(rsyncLauncher.command, [...rsyncLauncher.leadingArgs, ...overlayRunArgs], { env });
1056
+ const overlay = run("rsync", overlayRunArgs, { env });
1346
1057
  if (overlay.status !== 0) {
1347
1058
  // bash runs under set -e: a failed rsync aborts with its status.
1348
1059
  err(overlay.stderr);
@@ -1483,7 +1194,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1483
1194
  }
1484
1195
  out("\n");
1485
1196
  out("==> Classification:\n");
1486
- out(` user-only (left in place under release-managed roots): ${counts.userOnly} files\n`);
1197
+ out(` user-only (left in place): ${counts.userOnly} files\n`);
1487
1198
  out(` unchanged (preserved/re-laid): ${counts.unchanged} files\n`);
1488
1199
  out(` user-edits (rescued): ${counts.userEdit} files\n`);
1489
1200
  out(` user-edits (conflict quarantine): ${counts.userConflict} files\n`);
@@ -1518,7 +1229,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1518
1229
  lines.push("Baseline: head_compare (no last-sync stamp; first run or floor unreachable)");
1519
1230
  }
1520
1231
  lines.push("", "## What the rescue did");
1521
- lines.push(` user-only (left in place under release-managed roots): ${counts.userOnly}`);
1232
+ lines.push(` user-only (left in place): ${counts.userOnly}`);
1522
1233
  lines.push(` unchanged (preserved/re-laid): ${counts.unchanged}`);
1523
1234
  lines.push(` user-edit (rescued into personal/): ${counts.userEdit}`);
1524
1235
  lines.push(` user-edit (conflict quarantine): ${counts.userConflict}`);
@@ -1570,7 +1281,6 @@ function doRescue(cfg, env, out, err, setTmp) {
1570
1281
  if (cfg.doBackup && backupDir) {
1571
1282
  out(` A filtered pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
1572
1283
  }
1573
- clearRescueBlockedMarker(hqRoot);
1574
1284
  return { status: 0 };
1575
1285
  }
1576
1286
  catch (error) {
@@ -2662,11 +2372,10 @@ function renderDryRunDecision(ctx, decision) {
2662
2372
  }
2663
2373
  function buildRescueActions(ctx) {
2664
2374
  const actions = [];
2665
- const add = (label, affectedRels, runAction, destParentRels = []) => {
2375
+ const add = (label, affectedRels, runAction) => {
2666
2376
  actions.push({
2667
2377
  label,
2668
2378
  affectedRels,
2669
- destParentRels,
2670
2379
  expectedPaths: affectedRels.map((rel) => ({
2671
2380
  rel,
2672
2381
  kind: rescuePathKind(path.join(ctx.hqRoot, rel)),
@@ -2705,7 +2414,7 @@ function buildRescueActions(ctx) {
2705
2414
  });
2706
2415
  break;
2707
2416
  case "user-edit-diff-append":
2708
- add(`rescue diff-append: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel), [path.posix.dirname(mapRescueTarget(decision.rel))]);
2417
+ add(`rescue diff-append: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel));
2709
2418
  break;
2710
2419
  case "user-edit-overwrite-safe":
2711
2420
  add(`overwrite-safe: ${decision.rel}`, [decision.rel], () => {
@@ -2726,12 +2435,10 @@ function buildRescueActions(ctx) {
2726
2435
  });
2727
2436
  break;
2728
2437
  case "user-edit-conflict":
2729
- add(`conflict quarantine: ${decision.rel}`, [decision.rel], () => conflictOne(ctx, decision.rel), [
2730
- path.posix.dirname(`.hq-conflicts/rescue-${ctx.runTs}/${decision.rel}`),
2731
- ]);
2438
+ add(`conflict quarantine: ${decision.rel}`, [decision.rel], () => conflictOne(ctx, decision.rel));
2732
2439
  break;
2733
2440
  case "user-edit-rescue":
2734
- add(`rescue: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel), [path.posix.dirname(mapRescueTarget(decision.rel))]);
2441
+ add(`rescue: ${decision.rel}`, [decision.rel], () => rescueOne(ctx, decision.rel));
2735
2442
  break;
2736
2443
  case "unchanged-preserve":
2737
2444
  add(`preserve unchanged: ${decision.rel}`, [], () => {
@@ -3004,246 +2711,6 @@ function restoreMtimesFromGit(srcDir, env, out) {
3004
2711
  }
3005
2712
  }
3006
2713
  }
3007
- const RESCUE_BLOCKED_MARKER_REL = ".hq/rescue-blocked.json";
3008
- const RESCUE_BLOCKED_REASON = "recovery-snapshot-breaker";
3009
- const POST_RESTORE_PERMIT_REL = ".hq/rescue-post-restore.json";
3010
- function posixShellQuote(value) {
3011
- return `'${value.replace(/'/g, `'\\''`)}'`;
3012
- }
3013
- /** Format the exact safe command presented in a breaker diagnostic. */
3014
- export function formatRecoveryCommand(hqRoot, backupRoot, verifyRestoredSnapshot) {
3015
- const args = [
3016
- "npx",
3017
- "-y",
3018
- "--package=@indigoai-us/hq-cloud@latest",
3019
- "hq-rescue",
3020
- "--recover-snapshots",
3021
- "--hq-root",
3022
- posixShellQuote(hqRoot),
3023
- "--backup-dir",
3024
- posixShellQuote(backupRoot),
3025
- ];
3026
- if (verifyRestoredSnapshot) {
3027
- args.push("--verify-restored-snapshot", posixShellQuote(verifyRestoredSnapshot));
3028
- }
3029
- return args.join(" ");
3030
- }
3031
- function posixRelFromRoot(hqRoot, abs) {
3032
- const root = path.resolve(hqRoot);
3033
- const resolved = path.resolve(abs);
3034
- if (resolved === root)
3035
- return ".";
3036
- const prefix = root.endsWith(path.sep) ? root : root + path.sep;
3037
- if (resolved.startsWith(prefix)) {
3038
- return resolved.slice(prefix.length).split(path.sep).join("/");
3039
- }
3040
- return resolved;
3041
- }
3042
- function firstExistingAncestor(abs) {
3043
- let current = abs;
3044
- for (;;) {
3045
- if (lexists(current))
3046
- return current;
3047
- const parent = path.dirname(current);
3048
- if (parent === current)
3049
- return null;
3050
- current = parent;
3051
- }
3052
- }
3053
- function canWrite(abs) {
3054
- try {
3055
- fs.accessSync(abs, fs.constants.W_OK);
3056
- return true;
3057
- }
3058
- catch {
3059
- return false;
3060
- }
3061
- }
3062
- function topLevelRel(rel) {
3063
- const normalized = rel.replace(/\\/g, "/").replace(/^\.\//, "");
3064
- if (normalized === "." || normalized === "")
3065
- return ".";
3066
- return normalized.split("/")[0] ?? ".";
3067
- }
3068
- /**
3069
- * Paths the current process cannot write among the action plan's rename/delete
3070
- * sources (and their parents) plus rename destination parents. Empty means the
3071
- * plan is writable; a non-empty result must refuse before allocating a snapshot.
3072
- */
3073
- export function collectUnwritableRescueMutationPaths(hqRoot, actions) {
3074
- const failed = new Set();
3075
- const note = (abs) => {
3076
- failed.add(posixRelFromRoot(hqRoot, abs));
3077
- };
3078
- const checkParent = (abs) => {
3079
- const existing = firstExistingAncestor(abs);
3080
- if (!existing || !canWrite(existing))
3081
- note(existing ?? abs);
3082
- };
3083
- for (const action of actions) {
3084
- for (const rel of action.affectedRels) {
3085
- if (!rel)
3086
- continue;
3087
- const abs = path.join(hqRoot, rel);
3088
- const st = lstatOrNull(abs);
3089
- if (st && !st.isSymbolicLink() && !canWrite(abs))
3090
- note(abs);
3091
- checkParent(path.dirname(abs));
3092
- }
3093
- for (const rel of action.destParentRels ?? []) {
3094
- if (!rel || rel === ".")
3095
- continue;
3096
- checkParent(path.join(hqRoot, rel));
3097
- }
3098
- }
3099
- return [...failed].sort();
3100
- }
3101
- function reportUnwritableRescuePaths(hqRoot, unwritable, err) {
3102
- const shown = unwritable.slice(0, 10);
3103
- err("error: cannot write the paths rescue would rename or delete (permission denied).\n");
3104
- err(" Refusing before a safety snapshot is allocated so this cannot trip the recovery-snapshot circuit breaker.\n");
3105
- err(unwritable.length > 10
3106
- ? ` Unwritable paths (showing 10 of ${unwritable.length}):\n`
3107
- : " Unwritable paths:\n");
3108
- for (const rel of shown)
3109
- err(` ${rel}\n`);
3110
- const uid = typeof process.getuid === "function" ? String(process.getuid()) : "<uid>";
3111
- const gid = typeof process.getgid === "function" ? String(process.getgid()) : "<gid>";
3112
- const tops = [
3113
- ...new Set(unwritable.map((rel) => topLevelRel(rel)).filter((top) => top !== ".")),
3114
- ].sort();
3115
- err(" Repair ownership, then retry:\n");
3116
- if (tops.length === 0) {
3117
- err(` chown -R ${uid}:${gid} ${hqRoot}\n`);
3118
- }
3119
- else {
3120
- for (const top of tops) {
3121
- err(` chown -R ${uid}:${gid} ${path.join(hqRoot, top)}\n`);
3122
- }
3123
- }
3124
- }
3125
- function rescueBlockedMarkerPath(hqRoot) {
3126
- return path.join(hqRoot, RESCUE_BLOCKED_MARKER_REL);
3127
- }
3128
- function postRestorePermitPath(hqRoot) {
3129
- return path.join(hqRoot, POST_RESTORE_PERMIT_REL);
3130
- }
3131
- function writePostRestorePermit(hqRoot, entry) {
3132
- const permit = {
3133
- schemaVersion: 1,
3134
- canonicalHqRoot: hqRoot,
3135
- rootHash: canonicalRootHash(hqRoot),
3136
- snapshotName: entry.name,
3137
- snapshotRunId: entry.manifest.runId,
3138
- verifiedAt: new Date().toISOString(),
3139
- };
3140
- const target = postRestorePermitPath(hqRoot);
3141
- const temporary = `${target}.${process.pid}.tmp`;
3142
- fs.mkdirSync(path.dirname(target), { recursive: true });
3143
- fs.writeFileSync(temporary, JSON.stringify(permit, null, 2) + "\n", {
3144
- mode: 0o600,
3145
- });
3146
- fs.renameSync(temporary, target);
3147
- }
3148
- function readPostRestorePermit(hqRoot) {
3149
- let raw;
3150
- try {
3151
- raw = fs.readFileSync(postRestorePermitPath(hqRoot), "utf8");
3152
- }
3153
- catch (error) {
3154
- if (error.code === "ENOENT") {
3155
- return { permit: null };
3156
- }
3157
- return {
3158
- permit: null,
3159
- problem: `could not read ${POST_RESTORE_PERMIT_REL}: ${error instanceof Error ? error.message : String(error)}`,
3160
- };
3161
- }
3162
- try {
3163
- const value = JSON.parse(raw);
3164
- if (value.schemaVersion !== 1 ||
3165
- typeof value.canonicalHqRoot !== "string" ||
3166
- typeof value.rootHash !== "string" ||
3167
- typeof value.snapshotName !== "string" ||
3168
- typeof value.snapshotRunId !== "string" ||
3169
- typeof value.verifiedAt !== "string") {
3170
- return { permit: null, problem: `${POST_RESTORE_PERMIT_REL} is malformed` };
3171
- }
3172
- return { permit: value };
3173
- }
3174
- catch (error) {
3175
- return {
3176
- permit: null,
3177
- problem: `${POST_RESTORE_PERMIT_REL} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
3178
- };
3179
- }
3180
- }
3181
- function consumePostRestorePermit(cfg, hqRoot) {
3182
- const read = readPostRestorePermit(hqRoot);
3183
- if (!read.permit) {
3184
- return { used: false, ...(read.problem ? { problem: read.problem } : {}) };
3185
- }
3186
- const permit = read.permit;
3187
- if (permit.canonicalHqRoot !== hqRoot ||
3188
- permit.rootHash !== canonicalRootHash(hqRoot)) {
3189
- return { used: false, problem: "permit belongs to a different HQ root" };
3190
- }
3191
- const inventory = inventoryManagedSnapshots(cfg.backupRoot, hqRoot, () => false, {
3192
- keepGood: Number(cfg.backupRetentionCount),
3193
- maxAgeDays: Number(cfg.backupRetentionDays),
3194
- });
3195
- if (inventory.unmanaged.some((item) => item.reason === "backup-root-unreadable")) {
3196
- return { used: false, problem: `backup root is unreadable: ${cfg.backupRoot}` };
3197
- }
3198
- const entry = inventory.entries.find((item) => item.name === permit.snapshotName &&
3199
- item.manifest.runId === permit.snapshotRunId &&
3200
- item.manifest.status === "recovery-required");
3201
- const unresolved = inventory.protected.some((item) => item.entry.name === permit.snapshotName &&
3202
- item.reason === "recovery-required-no-later-good");
3203
- if (!entry || !unresolved) {
3204
- return { used: false, problem: "referenced snapshot is no longer unresolved recovery evidence" };
3205
- }
3206
- const mismatch = snapshotTreeMismatch(path.join(cfg.backupRoot, entry.name), hqRoot, entry.manifest.includedRoots);
3207
- if (mismatch) {
3208
- return { used: false, problem: `live tree no longer matches ${entry.name}: ${mismatch}` };
3209
- }
3210
- try {
3211
- fs.unlinkSync(postRestorePermitPath(hqRoot));
3212
- }
3213
- catch (error) {
3214
- return {
3215
- used: false,
3216
- problem: `could not consume the single-use permit: ${error instanceof Error ? error.message : String(error)}`,
3217
- };
3218
- }
3219
- return { used: true, snapshotName: entry.name };
3220
- }
3221
- function writeRescueBlockedMarker(hqRoot, snapshots) {
3222
- const body = {
3223
- at: new Date().toISOString(),
3224
- reason: RESCUE_BLOCKED_REASON,
3225
- failureKind: "snapshot-recovery-circuit-breaker",
3226
- snapshots,
3227
- hint: "Run hq-rescue --recover-snapshots to inspect the snapshots. It deletes only snapshots proved superseded by a later completed-good rescue; otherwise restore the needed files, repair the release source, and retry.",
3228
- };
3229
- try {
3230
- fs.mkdirSync(path.dirname(rescueBlockedMarkerPath(hqRoot)), {
3231
- recursive: true,
3232
- });
3233
- fs.writeFileSync(rescueBlockedMarkerPath(hqRoot), JSON.stringify(body, null, 2) + "\n");
3234
- }
3235
- catch {
3236
- /* stderr remains the operator-facing signal if .hq is unwritable */
3237
- }
3238
- }
3239
- function clearRescueBlockedMarker(hqRoot) {
3240
- try {
3241
- fs.unlinkSync(rescueBlockedMarkerPath(hqRoot));
3242
- }
3243
- catch {
3244
- /* absent is the success state */
3245
- }
3246
- }
3247
2714
  function allocateSnapshotDir(backupRoot, runTs, rootHash, runId) {
3248
2715
  return path.join(backupRoot, `pre-update-${runTs}-${rootHash}-${runId}`);
3249
2716
  }