@indigoai-us/hq-cloud 6.16.51 → 6.16.52

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.
@@ -617,11 +617,15 @@ function recoverSnapshots(cfg, out, err) {
617
617
  const blocked = inventory.protected.filter((item) => item.reason === "recovery-required-no-later-good");
618
618
  const retainedByGrace = inventory.protected.filter((item) => item.entry.manifest.status === "recovery-required" &&
619
619
  item.reason !== "recovery-required-no-later-good");
620
+ const incomplete = inventory.entries.filter((entry) => entry.manifest.status === "incomplete");
620
621
  const laterGoodFor = (completedMs, name) => inventory.entries.find((entry) => entry.manifest.status === "completed-good" &&
621
622
  (entry.completedMs > completedMs ||
622
623
  (entry.completedMs === completedMs && entry.name > name)))?.name;
623
624
  out(`==> Safety snapshot recovery inspection: ${cfg.backupRoot}\n`);
624
- if (verified.length === 0 && blocked.length === 0 && retainedByGrace.length === 0) {
625
+ if (verified.length === 0 &&
626
+ blocked.length === 0 &&
627
+ retainedByGrace.length === 0 &&
628
+ incomplete.length === 0) {
625
629
  out(" No recovery-required snapshots need action.\n");
626
630
  return { status: 0 };
627
631
  }
@@ -635,6 +639,16 @@ function recoverSnapshots(cfg, out, err) {
635
639
  for (const item of retainedByGrace) {
636
640
  out(` retained ${item.entry.name}: a later completed-good snapshot exists, but normal retention still keeps this newest recovery snapshot.\n`);
637
641
  }
642
+ for (const entry of incomplete) {
643
+ out(` incomplete ${entry.name}: skipped ${formatSkippedSnapshotPaths(entry.manifest)}; it cannot restore every captured root.\n`);
644
+ }
645
+ if (verified.length === 0 &&
646
+ blocked.length === 0 &&
647
+ retainedByGrace.length === 0 &&
648
+ incomplete.length > 0) {
649
+ out("==> Snapshot recovery inspection complete: incomplete snapshots were retained and cannot restore every captured root.\n");
650
+ return { status: 0 };
651
+ }
638
652
  if (verified.length > 0) {
639
653
  if (cfg.dryRun) {
640
654
  for (const item of verified) {
@@ -665,8 +679,12 @@ function recoverSnapshots(cfg, out, err) {
665
679
  if (unresolved.length > 0) {
666
680
  err("error: snapshot recovery refused: the interrupted updates are not proven superseded.\n");
667
681
  err(" HQ retained every unverified snapshot. A later completed-good rescue for this same HQ root is the only automatic proof.\n");
668
- err(" Restore one listed snapshot, then verify it before one retry is permitted:\n");
682
+ err(" Restore one listed complete snapshot, then verify it before one retry is permitted:\n");
669
683
  for (const item of unresolved) {
684
+ if (hasSkippedSnapshotEntries(item.entry.manifest)) {
685
+ err(` ${item.entry.name} is incomplete: skipped ${formatSkippedSnapshotPaths(item.entry.manifest)} and cannot restore every captured root.\n`);
686
+ continue;
687
+ }
670
688
  err(` restore ${item.entry.name}: ${formatSnapshotRestoreCommand(hqRoot, cfg.backupRoot, item.entry.name)}\n`);
671
689
  err(` verify ${item.entry.name}: ${formatRecoveryCommand(hqRoot, cfg.backupRoot, item.entry.name)}\n`);
672
690
  }
@@ -687,6 +705,10 @@ function restoreRecoverySnapshot(cfg, hqRoot, entries, protectedEntries, out, er
687
705
  err(`error: ${cfg.restoreSnapshot} is not an unresolved recovery-required snapshot for this HQ root.\n`);
688
706
  return { status: 1 };
689
707
  }
708
+ if (hasSkippedSnapshotEntries(entry.manifest)) {
709
+ err(`error: ${cfg.restoreSnapshot} is incomplete: skipped ${formatSkippedSnapshotPaths(entry.manifest)} and cannot restore every captured root.\n`);
710
+ return { status: 1 };
711
+ }
690
712
  if (cfg.dryRun) {
691
713
  out(`==> Dry run would restore every captured root and recorded symlink from ${entry.name}.\n`);
692
714
  return { status: 0 };
@@ -712,6 +734,10 @@ function verifyRestoredSnapshot(cfg, hqRoot, entries, protectedEntries, out, err
712
734
  err(`error: ${cfg.verifyRestoredSnapshot} is not an unresolved recovery-required snapshot for this HQ root.\n`);
713
735
  return { status: 1 };
714
736
  }
737
+ if (hasSkippedSnapshotEntries(entry.manifest)) {
738
+ err(`error: ${cfg.verifyRestoredSnapshot} is incomplete: skipped ${formatSkippedSnapshotPaths(entry.manifest)} and cannot verify every captured root.\n`);
739
+ return { status: 1 };
740
+ }
715
741
  const mismatch = snapshotTreeMismatch(path.join(cfg.backupRoot, entry.name), hqRoot, entry.manifest.includedRoots, entry.manifest.symlinks);
716
742
  if (mismatch) {
717
743
  err(`error: restored tree does not match snapshot ${entry.name}: ${mismatch}\n`);
@@ -1433,6 +1459,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1433
1459
  out,
1434
1460
  decisions: [],
1435
1461
  actions: [],
1462
+ skippedSnapshotRels: [],
1436
1463
  };
1437
1464
  // --- Walk + classify (PHASE 1: read-only) ---
1438
1465
  // Classification mutates nothing on disk: every outcome is recorded as a
@@ -1530,7 +1557,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1530
1557
  // unchanged versus before the two-phase split.
1531
1558
  const overlayProtect = [];
1532
1559
  if (fs.statSync(unchangedList).size > 0) {
1533
- overlayProtect.push(`--exclude-from=${unchangedList}`);
1560
+ overlayProtect.push("--from0", `--exclude-from=${unchangedList}`);
1534
1561
  }
1535
1562
  const overlayArgs = [
1536
1563
  "-a",
@@ -1561,91 +1588,144 @@ function doRescue(cfg, env, out, err, setTmp) {
1561
1588
  // backup space.
1562
1589
  let backupDir = "";
1563
1590
  let mutationStarted = false;
1564
- const hasDestructivePaths = ctx.actions.some((action) => action.affectedRels.length > 0);
1565
- if (cfg.doBackup &&
1566
- !cfg.dryRun &&
1567
- wipeToplevel.length !== 0 &&
1568
- hasDestructivePaths) {
1569
- const prePlan = pruneManagedBackups(cfg, hqRoot, out, false);
1570
- const unresolved = prePlan.protected.filter((x) => x.reason === "recovery-required-no-later-good");
1571
- if (unresolved.length >= 2) {
1572
- const postRestore = consumePostRestorePermit(cfg, hqRoot);
1573
- if (postRestore.used) {
1574
- out(`==> Verified post-restore permit for ${postRestore.snapshotName}; allowing one rescue attempt.\n`);
1575
- out(" The permit was consumed before mutation. If this attempt fails, the circuit breaker is armed again.\n");
1576
- }
1577
- else {
1578
- if (postRestore.problem) {
1579
- err(`error: post-restore permit is not usable: ${postRestore.problem}\n`);
1591
+ let snapshotSkippedEntries = [];
1592
+ try {
1593
+ const hasDestructivePaths = ctx.actions.some((action) => action.affectedRels.length > 0);
1594
+ if (cfg.doBackup &&
1595
+ !cfg.dryRun &&
1596
+ wipeToplevel.length !== 0 &&
1597
+ hasDestructivePaths) {
1598
+ const prePlan = pruneManagedBackups(cfg, hqRoot, out, false);
1599
+ const unresolved = prePlan.protected.filter((x) => x.reason === "recovery-required-no-later-good");
1600
+ if (unresolved.length >= 2) {
1601
+ const postRestore = consumePostRestorePermit(cfg, hqRoot);
1602
+ if (postRestore.used) {
1603
+ out(`==> Verified post-restore permit for ${postRestore.snapshotName}; allowing one rescue attempt.\n`);
1604
+ out(" The permit was consumed before mutation. If this attempt fails, the circuit breaker is armed again.\n");
1605
+ }
1606
+ else {
1607
+ if (postRestore.problem) {
1608
+ err(`error: post-restore permit is not usable: ${postRestore.problem}\n`);
1609
+ }
1610
+ const snapshotNames = unresolved.map((x) => x.entry.name);
1611
+ writeRescueBlockedMarker(hqRoot, snapshotNames);
1612
+ err("HQ_RESCUE_FAILURE_KIND=snapshot-recovery-circuit-breaker\n");
1613
+ err("error: safety snapshot circuit breaker is open: two interrupted updates still need recovery proof.\n");
1614
+ err(" HQ kept their pre-update snapshots because those updates started changing the release-managed tree but did not finish.\n");
1615
+ err(" It will not overwrite or delete that evidence without proof that a later rescue completed successfully.\n");
1616
+ err(` Inspect safely: ${formatRecoveryCommand(hqRoot, cfg.backupRoot)}\n`);
1617
+ err(" It deletes only snapshots with a later completed-good rescue. For unresolved snapshots, use --restore-snapshot to restore every captured root and recorded link, then run its verification command before retrying.\n");
1618
+ throw new ExitError(1);
1580
1619
  }
1581
- const snapshotNames = unresolved.map((x) => x.entry.name);
1582
- writeRescueBlockedMarker(hqRoot, snapshotNames);
1583
- err("HQ_RESCUE_FAILURE_KIND=snapshot-recovery-circuit-breaker\n");
1584
- err("error: safety snapshot circuit breaker is open: two interrupted updates still need recovery proof.\n");
1585
- err(" HQ kept their pre-update snapshots because those updates started changing the release-managed tree but did not finish.\n");
1586
- err(" It will not overwrite or delete that evidence without proof that a later rescue completed successfully.\n");
1587
- err(` Inspect safely: ${formatRecoveryCommand(hqRoot, cfg.backupRoot)}\n`);
1588
- err(" It deletes only snapshots with a later completed-good rescue. For unresolved snapshots, use --restore-snapshot to restore every captured root and recorded link, then run its verification command before retrying.\n");
1589
- throw new ExitError(1);
1590
1620
  }
1591
- }
1592
- requireBackupCapacity(cfg, hqRoot, wipeToplevel, env, err);
1593
- fs.mkdirSync(cfg.backupRoot, { recursive: true });
1594
- const runId = `${process.pid}-${Date.now().toString(36)}`;
1595
- backupDir = allocateSnapshotDir(cfg.backupRoot, RUN_TS, canonicalRootHash(hqRoot), runId);
1596
- out("\n");
1597
- out(`==> Safety snapshot -> ${backupDir}\n`);
1598
- const snapshotSymlinks = [];
1599
- try {
1600
- fs.mkdirSync(backupDir, { recursive: false });
1601
- writeSnapshotManifest(backupDir, snapshotManifest("copying", hqRoot, runId, cfg, srcSha, wipeToplevel));
1602
- for (const rootRel of wipeToplevel) {
1603
- const srcAbs = path.join(hqRoot, rootRel);
1604
- if (isRescueTransientDirectory(rootRel))
1605
- continue;
1606
- cpAToFiltered(srcAbs, path.join(backupDir, rootRel), rootRel, hqRoot, snapshotSymlinks);
1621
+ requireBackupCapacity(cfg, hqRoot, wipeToplevel, env, err);
1622
+ fs.mkdirSync(cfg.backupRoot, { recursive: true });
1623
+ const runId = `${process.pid}-${Date.now().toString(36)}`;
1624
+ backupDir = allocateSnapshotDir(cfg.backupRoot, RUN_TS, canonicalRootHash(hqRoot), runId);
1625
+ out("\n");
1626
+ out(`==> Safety snapshot -> ${backupDir}\n`);
1627
+ const snapshotSymlinks = [];
1628
+ const snapshotSkippedErrors = [];
1629
+ try {
1630
+ fs.mkdirSync(backupDir, { recursive: false });
1631
+ writeSnapshotManifest(backupDir, snapshotManifest("copying", hqRoot, runId, cfg, srcSha, wipeToplevel));
1632
+ const attemptedRoots = wipeToplevel.filter((rootRel) => !isRescueTransientDirectory(rootRel));
1633
+ const failedRoots = [];
1634
+ for (const rootRel of wipeToplevel) {
1635
+ const srcAbs = path.join(hqRoot, rootRel);
1636
+ if (isRescueTransientDirectory(rootRel))
1637
+ continue;
1638
+ try {
1639
+ const copy = cpAToFiltered(srcAbs, path.join(backupDir, rootRel), rootRel, hqRoot, snapshotSymlinks, snapshotSkippedErrors);
1640
+ if (!copy.captured) {
1641
+ const failure = copy.firstFailure ??
1642
+ new SnapshotCopyError(rootRel, "metadata", new Error("snapshot root contains no capturable entries"), srcAbs);
1643
+ if (!copy.firstFailure)
1644
+ snapshotSkippedErrors.push(failure);
1645
+ failedRoots.push(failure);
1646
+ }
1647
+ }
1648
+ catch (error) {
1649
+ if (error instanceof SnapshotCopyError) {
1650
+ snapshotSkippedErrors.push(error);
1651
+ failedRoots.push(error);
1652
+ continue;
1653
+ }
1654
+ throw error;
1655
+ }
1656
+ }
1657
+ snapshotSkippedEntries = snapshotSkippedErrors.map(snapshotCopyFailure);
1658
+ if (attemptedRoots.length > 0 &&
1659
+ failedRoots.length === attemptedRoots.length) {
1660
+ const failure = failedRoots[0];
1661
+ updateSnapshotStatus(backupDir, "failed-pre-mutation", undefined, {
1662
+ symlinks: snapshotSymlinks,
1663
+ copyFailure: snapshotCopyFailure(failure),
1664
+ skippedEntries: snapshotSkippedEntries,
1665
+ });
1666
+ reportSnapshotCopyFailure(failure, err);
1667
+ throw new ExitError(1);
1668
+ }
1669
+ for (const error of snapshotSkippedErrors) {
1670
+ reportSkippedSnapshotCopy(error, err);
1671
+ }
1672
+ protectSkippedSnapshotPaths(ctx, snapshotSkippedEntries);
1673
+ updateSnapshotStatus(backupDir, snapshotSkippedEntries.length > 0 ? "incomplete" : "ready", undefined, {
1674
+ symlinks: snapshotSymlinks,
1675
+ skippedEntries: snapshotSkippedEntries,
1676
+ });
1607
1677
  }
1608
- updateSnapshotStatus(backupDir, "ready", undefined, {
1609
- symlinks: snapshotSymlinks,
1610
- });
1611
- }
1612
- catch (error) {
1613
- if (error instanceof SnapshotCopyError) {
1678
+ catch (error) {
1679
+ if (error instanceof SnapshotCopyError) {
1680
+ updateSnapshotStatus(backupDir, "failed-pre-mutation", undefined, {
1681
+ symlinks: snapshotSymlinks,
1682
+ copyFailure: snapshotCopyFailure(error),
1683
+ skippedEntries: snapshotSkippedEntries,
1684
+ });
1685
+ reportSnapshotCopyFailure(error, err);
1686
+ throw new ExitError(1);
1687
+ }
1614
1688
  updateSnapshotStatus(backupDir, "failed-pre-mutation", undefined, {
1615
1689
  symlinks: snapshotSymlinks,
1616
- copyFailure: snapshotCopyFailure(error),
1690
+ skippedEntries: snapshotSkippedEntries,
1617
1691
  });
1618
- reportSnapshotCopyFailure(error, err);
1619
- throw new ExitError(1);
1692
+ throw error;
1693
+ }
1694
+ pruneManagedBackups(cfg, hqRoot, out, true);
1695
+ if (snapshotSkippedEntries.length > 0) {
1696
+ out(" snapshot incomplete: skipped files were left untouched and this snapshot cannot restore every captured root.\n");
1697
+ }
1698
+ else {
1699
+ out(" snapshot ready (complete recovery is available through --recover-snapshots).\n");
1620
1700
  }
1621
- updateSnapshotStatus(backupDir, "failed-pre-mutation", undefined, {
1622
- symlinks: snapshotSymlinks,
1623
- });
1624
- throw error;
1625
1701
  }
1626
- pruneManagedBackups(cfg, hqRoot, out, true);
1627
- out(" snapshot ready (complete recovery is available through --recover-snapshots).\n");
1628
- }
1629
- else if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
1630
- out("\n==> Safety snapshot skipped (classification found no destructive paths).\n");
1631
- }
1632
- try {
1633
- mutationStarted = true;
1634
- applyClassifiedActions(ctx, backupDir);
1702
+ else if (cfg.doBackup && !cfg.dryRun && wipeToplevel.length !== 0) {
1703
+ out("\n==> Safety snapshot skipped (classification found no destructive paths).\n");
1704
+ }
1635
1705
  // --- Back up preserve-subpaths to a mktemp shuttle ---
1706
+ // This runs after the snapshot but before classified mutations, so a normal
1707
+ // preserve-subpath remains available even if an action removes its parent.
1636
1708
  const shuttle = path.join(tmpdir, "preserve");
1637
- fs.mkdirSync(shuttle, { recursive: true });
1638
1709
  const preserveMap = [];
1639
- let shuttleId = 0;
1640
- for (const sp of cfg.preserveSubpaths) {
1641
- const src = path.join(hqRoot, sp);
1642
- if (lexists(src)) {
1643
- shuttleId += 1;
1644
- cpA(src, shuttle, String(shuttleId));
1645
- preserveMap.push({ id: shuttleId, rel: sp });
1646
- out(`==> Backed up ${sp} -> shuttle/${shuttleId}\n`);
1710
+ if (cfg.preserveSubpaths.length > 0) {
1711
+ fs.mkdirSync(shuttle, { recursive: true });
1712
+ let shuttleId = 0;
1713
+ for (const sp of cfg.preserveSubpaths) {
1714
+ if (snapshotSkippedEntries.some((entry) => rescuePathsOverlap(sp, entry.relativePath))) {
1715
+ out(`==> Left ${sp} in place because it contains a skipped snapshot path\n`);
1716
+ continue;
1717
+ }
1718
+ const src = path.join(hqRoot, sp);
1719
+ if (lexists(src)) {
1720
+ shuttleId += 1;
1721
+ cpA(src, shuttle, String(shuttleId));
1722
+ preserveMap.push({ id: shuttleId, rel: sp });
1723
+ out(`==> Backed up ${sp} -> shuttle/${shuttleId}\n`);
1724
+ }
1647
1725
  }
1648
1726
  }
1727
+ mutationStarted = true;
1728
+ applyClassifiedActions(ctx, backupDir);
1649
1729
  out("\n");
1650
1730
  out(`==> Walk complete (user-only: ${counts.userOnly}, unchanged: ${counts.unchanged}, user-edit-rescued: ${counts.userEdit}, conflict-quarantined: ${counts.userConflict}, overwrite-safe: ${counts.userOverwrite}, kept-local: ${counts.userKeptLocal}, cloud-symlink-reconciled: ${counts.cloudSymlinkReconciled}, symlinks-dropped: ${counts.symlinkDropped})\n`);
1651
1731
  // --- Overlay source onto HQ root ---
@@ -1658,6 +1738,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1658
1738
  const overlayRunArgs = fs.statSync(unchangedList).size > 0
1659
1739
  ? [
1660
1740
  "-a",
1741
+ "--from0",
1661
1742
  `--exclude-from=${unchangedList}`,
1662
1743
  ...rsyncExcludes,
1663
1744
  toCygwinRsyncPath(srcDir + "/"),
@@ -1694,7 +1775,7 @@ function doRescue(cfg, env, out, err, setTmp) {
1694
1775
  // machine env.PATH onto the release baseline and relocates genuine user drift
1695
1776
  // (vs the last-sync floor) into settings.local.json so the effective merged
1696
1777
  // settings are preserved. No-op in narrow mode that excludes .claude.
1697
- if (claudeSettingsInScope) {
1778
+ if (claudeSettingsInScope && !isSkippedSnapshotPath(ctx, claudeSettingsRel)) {
1698
1779
  reconcileClaudeSettings({
1699
1780
  hqRoot,
1700
1781
  srcDir,
@@ -1704,12 +1785,15 @@ function doRescue(cfg, env, out, err, setTmp) {
1704
1785
  preserveSubpaths: cfg.preserveSubpaths,
1705
1786
  }, preRescueSettingsJson, out, err);
1706
1787
  }
1788
+ else if (claudeSettingsInScope) {
1789
+ out("==> Skipped .claude/settings.json reconcile because its safety snapshot entry was skipped\n");
1790
+ }
1707
1791
  // --- Restore executable bit on shipped shebang scripts (defense-in-depth) ---
1708
1792
  // rsync -a already propagated each file's upstream git tree mode; this guards
1709
1793
  // the case where upstream itself committed an executable script as 0644 -- a
1710
1794
  // hook the runtime exec's then dies with EACCES and is silently disabled. A
1711
1795
  // shebang is an unambiguous "meant to be run" marker. See restoreShebangExecBits.
1712
- const execBitFixes = restoreShebangExecBits(srcDir, hqRoot, env);
1796
+ const execBitFixes = restoreShebangExecBits(srcDir, hqRoot, env, ctx.skippedSnapshotRels);
1713
1797
  if (execBitFixes > 0) {
1714
1798
  out(`==> Restored executable bit on ${execBitFixes} shipped shebang script(s) lacking +x\n`);
1715
1799
  }
@@ -1720,13 +1804,19 @@ function doRescue(cfg, env, out, err, setTmp) {
1720
1804
  // unparseable commit timestamp skips the stamp entirely — a nondeterministic
1721
1805
  // stamp is worse than no stamp (it re-creates cross-machine conflict mirrors).
1722
1806
  const srcCommitDate = new Date(srcCommitIsoRaw);
1807
+ const coreYamlSkipped = isSkippedSnapshotPath(ctx, "core/core.yaml");
1808
+ if (coreYamlSkipped) {
1809
+ out("==> Skipped core/core.yaml stamp because its safety snapshot entry was skipped\n");
1810
+ }
1723
1811
  if (cfg.narrowPaths.length === 0 &&
1724
1812
  isFileFollow(coreYaml) &&
1813
+ !coreYamlSkipped &&
1725
1814
  Number.isNaN(srcCommitDate.getTime())) {
1726
1815
  err(` WARN: could not parse source commit timestamp (${JSON.stringify(srcCommitIsoRaw)}); skipping core/core.yaml stamp to keep it deterministic\n`);
1727
1816
  }
1728
1817
  if (cfg.narrowPaths.length === 0 &&
1729
1818
  isFileFollow(coreYaml) &&
1819
+ !coreYamlSkipped &&
1730
1820
  !Number.isNaN(srcCommitDate.getTime())) {
1731
1821
  const nowUtc = utcStamp(srcCommitDate, "colon");
1732
1822
  if (yqAvailable) {
@@ -1870,10 +1960,19 @@ function doRescue(cfg, env, out, err, setTmp) {
1870
1960
  lines.push("", "## Restore");
1871
1961
  lines.push("This directory holds the release-managed wipe set as it was before the update; reproducible worktrees and build caches are intentionally excluded.");
1872
1962
  const snapshotName = path.basename(backupDir);
1873
- lines.push("Restore every captured root and recorded symlink:");
1874
- lines.push(` ${formatSnapshotRestoreCommand(hqRoot, cfg.backupRoot, snapshotName)}`);
1875
- lines.push("Then verify the restored tree before retrying:");
1876
- lines.push(` ${formatRecoveryCommand(hqRoot, cfg.backupRoot, snapshotName)}`);
1963
+ if (snapshotSkippedEntries.length > 0) {
1964
+ lines.push("This snapshot is incomplete and cannot restore every captured root.");
1965
+ lines.push("The following paths were not backed up and were left untouched by the update:");
1966
+ for (const entry of snapshotSkippedEntries) {
1967
+ lines.push(` ${entry.relativePath} (${entry.operation}, ${entry.code})`);
1968
+ }
1969
+ }
1970
+ else {
1971
+ lines.push("Restore every captured root and recorded symlink:");
1972
+ lines.push(` ${formatSnapshotRestoreCommand(hqRoot, cfg.backupRoot, snapshotName)}`);
1973
+ lines.push("Then verify the restored tree before retrying:");
1974
+ lines.push(` ${formatRecoveryCommand(hqRoot, cfg.backupRoot, snapshotName)}`);
1975
+ }
1877
1976
  lines.push("", `Retention: ${cfg.backupRetentionDays} days and ${cfg.backupRetentionCount} completed snapshots (latest recovery floor retained).`);
1878
1977
  try {
1879
1978
  fs.writeFileSync(path.join(backupDir, "RECOVERY.md"), lines.join("\n") + "\n");
@@ -1881,9 +1980,9 @@ function doRescue(cfg, env, out, err, setTmp) {
1881
1980
  catch {
1882
1981
  /* best-effort, matches `|| true` */
1883
1982
  }
1884
- updateSnapshotStatus(backupDir, "completed-good", RUN_TS);
1983
+ updateSnapshotStatus(backupDir, snapshotSkippedEntries.length > 0 ? "incomplete" : "completed-good", RUN_TS);
1885
1984
  out("\n");
1886
- out(`==> Pre-update snapshot + recovery manifest: ${backupDir}\n`);
1985
+ out(`==> Pre-update ${snapshotSkippedEntries.length > 0 ? "incomplete " : ""}snapshot + recovery manifest: ${backupDir}\n`);
1887
1986
  pruneManagedBackups(cfg, hqRoot, out, true);
1888
1987
  }
1889
1988
  out("\n");
@@ -1891,9 +1990,19 @@ function doRescue(cfg, env, out, err, setTmp) {
1891
1990
  out(" User-edited files were rescued under personal/ (see scan output above).\n");
1892
1991
  out(" User-only files (created by you, unknown to upstream) were left untouched.\n");
1893
1992
  if (cfg.doBackup && backupDir) {
1894
- out(` A filtered pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
1993
+ if (snapshotSkippedEntries.length > 0) {
1994
+ out(` An incomplete pre-update snapshot is at ${backupDir}; skipped files were left untouched (RECOVERY.md explains its limits).\n`);
1995
+ }
1996
+ else {
1997
+ out(` A filtered pre-update snapshot is at ${backupDir} (RECOVERY.md explains restore).\n`);
1998
+ }
1999
+ }
2000
+ if (isSkippedSnapshotPath(ctx, RESCUE_BLOCKED_MARKER_REL)) {
2001
+ out("==> Left the rescue recovery marker in place because its safety snapshot entry was skipped\n");
2002
+ }
2003
+ else {
2004
+ clearRescueBlockedMarker(hqRoot);
1895
2005
  }
1896
- clearRescueBlockedMarker(hqRoot);
1897
2006
  return { status: 0 };
1898
2007
  }
1899
2008
  catch (error) {
@@ -2019,6 +2128,10 @@ function rollbackCompletedActions(ctx, completed, backupDir) {
2019
2128
  }
2020
2129
  }
2021
2130
  function writeApplyFailureManifest(ctx, backupDir, failedAction, completed, restored, rollbackFailures, err) {
2131
+ if (isSkippedSnapshotPath(ctx, ".hq/rescue-recovery")) {
2132
+ ctx.out("warning: did not write the rescue recovery manifest because its safety snapshot entry was skipped\n");
2133
+ return null;
2134
+ }
2022
2135
  const message = err instanceof Error ? err.message : String(err);
2023
2136
  const completedLines = completed.length === 0
2024
2137
  ? [" (none)"]
@@ -2713,7 +2826,7 @@ export function reconcileClaudeSettings(ctx, preRescueSettingsJson, out, err) {
2713
2826
  * EPERM) is swallowed, matching the rest of rescue's posture. Returns the count
2714
2827
  * of files whose mode was changed, for the run summary.
2715
2828
  */
2716
- function restoreShebangExecBits(srcDir, hqRoot, env) {
2829
+ function restoreShebangExecBits(srcDir, hqRoot, env, skippedSnapshotRels) {
2717
2830
  let listing;
2718
2831
  try {
2719
2832
  const r = spawnSync("git", ["-C", srcDir, "ls-files", "-z"], {
@@ -2732,6 +2845,9 @@ function restoreShebangExecBits(srcDir, hqRoot, env) {
2732
2845
  for (const rel of listing.split("\0")) {
2733
2846
  if (!rel)
2734
2847
  continue;
2848
+ if (skippedSnapshotRels.some((skippedRel) => rescuePathsOverlap(rel, skippedRel))) {
2849
+ continue;
2850
+ }
2735
2851
  const dest = path.join(hqRoot, rel);
2736
2852
  let st;
2737
2853
  try {
@@ -3064,7 +3180,7 @@ function buildRescueActions(ctx) {
3064
3180
  // `unchangedList` makes it an `--exclude-from` entry for the overlay
3065
3181
  // rsync, so the release copy is never laid over the local one.
3066
3182
  add(`keep local: ${decision.rel}`, [], () => {
3067
- fs.appendFileSync(ctx.unchangedList, `/${decision.rel}\n`);
3183
+ appendLiteralRsyncExclude(ctx.unchangedList, decision.rel);
3068
3184
  ctx.counts.userKeptLocal += 1;
3069
3185
  ctx.out(` kept local: ${decision.rel} (machine-local ignore file; your edits win, overlay skipped)\n`);
3070
3186
  ctx.appendLog(`kept-local\t${decision.rel}\t(machine-local ignore file; user edit wins, overlay excluded)\n`);
@@ -3080,7 +3196,7 @@ function buildRescueActions(ctx) {
3080
3196
  break;
3081
3197
  case "unchanged-preserve":
3082
3198
  add(`preserve unchanged: ${decision.rel}`, [], () => {
3083
- fs.appendFileSync(ctx.unchangedList, `/${decision.rel}\n`);
3199
+ appendLiteralRsyncExclude(ctx.unchangedList, decision.rel);
3084
3200
  ctx.appendLog(`unchanged\t${decision.rel}\t(identical to upstream; left in place, mtime preserved)\n`);
3085
3201
  });
3086
3202
  break;
@@ -3841,6 +3957,14 @@ function snapshotCopyFailure(error) {
3841
3957
  occurredAt: new Date().toISOString(),
3842
3958
  };
3843
3959
  }
3960
+ function hasSkippedSnapshotEntries(manifest) {
3961
+ return (manifest.skippedEntries?.length ?? 0) > 0;
3962
+ }
3963
+ function formatSkippedSnapshotPaths(manifest) {
3964
+ return (manifest.skippedEntries ?? [])
3965
+ .map((entry) => entry.relativePath)
3966
+ .join(", ");
3967
+ }
3844
3968
  function reportSnapshotCopyFailure(error, err) {
3845
3969
  const kind = error.operation === "read"
3846
3970
  ? "snapshot-copy-unreadable"
@@ -3857,6 +3981,62 @@ function reportSnapshotCopyFailure(error, err) {
3857
3981
  err(" HQ did not begin the update. Repair access to the reported path or backup location, then retry.\n");
3858
3982
  }
3859
3983
  }
3984
+ function reportSkippedSnapshotCopy(error, err) {
3985
+ const kind = error.operation === "read"
3986
+ ? "snapshot-copy-unreadable"
3987
+ : "snapshot-copy-failed";
3988
+ err(`HQ_RESCUE_SKIPPED_KIND=${kind}\n`);
3989
+ err(`HQ_RESCUE_SNAPSHOT_COPY_CODE=${error.code}\n`);
3990
+ err(`warning: snapshot skipped ${error.path}. It was not backed up and was left untouched. The update continued.\n`);
3991
+ if (error.operation === "read") {
3992
+ err("warning: If this file is stored in iCloud Drive or another cloud provider, download it locally, then retry later.\n");
3993
+ }
3994
+ }
3995
+ function rescuePathsOverlap(first, second) {
3996
+ return (first === second ||
3997
+ first.startsWith(`${second}/`) ||
3998
+ second.startsWith(`${first}/`));
3999
+ }
4000
+ function isSkippedSnapshotPath(ctx, rel) {
4001
+ return ctx.skippedSnapshotRels.some((skippedRel) => rescuePathsOverlap(rel, skippedRel));
4002
+ }
4003
+ function appendLiteralRsyncExclude(excludeList, rel) {
4004
+ let pattern = rel;
4005
+ if (/[\\*?[]/.test(pattern)) {
4006
+ pattern = pattern
4007
+ .replace(/\\/g, "\\\\")
4008
+ .replace(/([*?[])/g, "\\$1");
4009
+ }
4010
+ fs.appendFileSync(excludeList, `/${pattern}\0`);
4011
+ }
4012
+ /**
4013
+ * A skipped snapshot path cannot enter the preserve shuttle because copying it
4014
+ * is exactly what failed. Reuse the existing overlay exclusion and action plan
4015
+ * instead: leave it in place, keep rsync off it, and remove every planned
4016
+ * mutation that could touch it or one of its parents.
4017
+ */
4018
+ function protectSkippedSnapshotPaths(ctx, skippedEntries) {
4019
+ const skippedRels = skippedEntries.map((entry) => entry.relativePath);
4020
+ ctx.skippedSnapshotRels = skippedRels;
4021
+ const protectedRels = [
4022
+ ...new Set([
4023
+ ...skippedRels,
4024
+ ...ctx.cfg.preserveSubpaths.filter((preserveRel) => skippedRels.some((skippedRel) => rescuePathsOverlap(preserveRel, skippedRel))),
4025
+ ]),
4026
+ ];
4027
+ if (protectedRels.length === 0)
4028
+ return;
4029
+ for (const rel of protectedRels) {
4030
+ appendLiteralRsyncExclude(ctx.unchangedList, rel);
4031
+ }
4032
+ ctx.actions = ctx.actions.filter((action) => {
4033
+ const protectedAction = action.affectedRels.some((rel) => protectedRels.some((protectedRel) => rescuePathsOverlap(rel, protectedRel)));
4034
+ if (protectedAction) {
4035
+ ctx.out(` left untouched after incomplete snapshot: ${action.affectedRels.join(", ")}\n`);
4036
+ }
4037
+ return !protectedAction;
4038
+ });
4039
+ }
3860
4040
  function pathIsInside(root, candidate, allowRoot = false) {
3861
4041
  const relative = path.relative(root, candidate);
3862
4042
  return ((allowRoot || relative !== "") &&
@@ -3971,7 +4151,7 @@ function copySymlinkFileRepresentationForSnapshot(src, dest, rel) {
3971
4151
  preserveSnapshotMetadata(dest, targetStats);
3972
4152
  }
3973
4153
  /** Snapshot copy that preserves metadata while pruning canonical transient directories. */
3974
- function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
4154
+ function cpAToFiltered(src, dest, rel, hqRoot, symlinks, skippedEntries) {
3975
4155
  let st;
3976
4156
  try {
3977
4157
  st = fs.lstatSync(src);
@@ -3979,8 +4159,9 @@ function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
3979
4159
  catch (error) {
3980
4160
  throw new SnapshotCopyError(rel, "read", error, src);
3981
4161
  }
3982
- if (st.isDirectory() && isRescueTransientDirectory(rel))
3983
- return;
4162
+ if (st.isDirectory() && isRescueTransientDirectory(rel)) {
4163
+ return { captured: true };
4164
+ }
3984
4165
  if (st.isSymbolicLink()) {
3985
4166
  let target;
3986
4167
  try {
@@ -3998,7 +4179,7 @@ function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
3998
4179
  copySymlinkFileRepresentationForSnapshot(src, dest, rel);
3999
4180
  }
4000
4181
  symlinks.push({ path: rel, target, ...(representation ? { representation } : {}) });
4001
- return;
4182
+ return { captured: true };
4002
4183
  }
4003
4184
  if (st.isDirectory()) {
4004
4185
  try {
@@ -4014,8 +4195,22 @@ function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
4014
4195
  catch (error) {
4015
4196
  throw new SnapshotCopyError(rel, "read", error, src);
4016
4197
  }
4198
+ let captured = names.length === 0;
4199
+ let firstFailure;
4017
4200
  for (const name of names) {
4018
- cpAToFiltered(path.join(src, name), path.join(dest, name), path.posix.join(rel, name), hqRoot, symlinks);
4201
+ try {
4202
+ const child = cpAToFiltered(path.join(src, name), path.join(dest, name), path.posix.join(rel, name), hqRoot, symlinks, skippedEntries);
4203
+ captured ||= child.captured;
4204
+ firstFailure ??= child.firstFailure;
4205
+ }
4206
+ catch (error) {
4207
+ if (error instanceof SnapshotCopyError) {
4208
+ skippedEntries.push(error);
4209
+ firstFailure ??= error;
4210
+ continue;
4211
+ }
4212
+ throw error;
4213
+ }
4019
4214
  }
4020
4215
  try {
4021
4216
  fs.chmodSync(dest, st.mode);
@@ -4024,7 +4219,7 @@ function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
4024
4219
  catch {
4025
4220
  /* metadata preservation is best-effort */
4026
4221
  }
4027
- return;
4222
+ return { captured, ...(firstFailure ? { firstFailure } : {}) };
4028
4223
  }
4029
4224
  if (!st.isFile()) {
4030
4225
  throw new SnapshotCopyError(rel, "metadata", new Error("unsupported filesystem entry"));
@@ -4043,6 +4238,7 @@ function cpAToFiltered(src, dest, rel, hqRoot, symlinks) {
4043
4238
  catch {
4044
4239
  /* metadata preservation is best-effort */
4045
4240
  }
4241
+ return { captured: true };
4046
4242
  }
4047
4243
  /** Synchronous single-line read from stdin (mirrors bash `read -r`). */
4048
4244
  function readLineSync() {