@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.
- package/dist/backup-prune.d.ts +3 -1
- package/dist/backup-prune.d.ts.map +1 -1
- package/dist/backup-prune.js +30 -5
- package/dist/backup-prune.js.map +1 -1
- package/dist/backup-prune.test.js +11 -0
- package/dist/backup-prune.test.js.map +1 -1
- package/dist/cli/rescue-core.d.ts.map +1 -1
- package/dist/cli/rescue-core.js +290 -94
- package/dist/cli/rescue-core.js.map +1 -1
- package/dist/cli/rescue-snapshot-copy.test.js +218 -26
- package/dist/cli/rescue-snapshot-copy.test.js.map +1 -1
- package/package.json +1 -1
package/dist/cli/rescue-core.js
CHANGED
|
@@ -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 &&
|
|
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
|
-
|
|
1565
|
-
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
const
|
|
1573
|
-
if (
|
|
1574
|
-
|
|
1575
|
-
|
|
1576
|
-
|
|
1577
|
-
|
|
1578
|
-
|
|
1579
|
-
|
|
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
|
-
|
|
1593
|
-
|
|
1594
|
-
|
|
1595
|
-
|
|
1596
|
-
|
|
1597
|
-
|
|
1598
|
-
|
|
1599
|
-
|
|
1600
|
-
|
|
1601
|
-
|
|
1602
|
-
|
|
1603
|
-
const
|
|
1604
|
-
|
|
1605
|
-
|
|
1606
|
-
|
|
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
|
-
|
|
1609
|
-
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
|
|
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
|
-
|
|
1690
|
+
skippedEntries: snapshotSkippedEntries,
|
|
1617
1691
|
});
|
|
1618
|
-
|
|
1619
|
-
|
|
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
|
-
|
|
1627
|
-
|
|
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
|
-
|
|
1640
|
-
|
|
1641
|
-
|
|
1642
|
-
|
|
1643
|
-
|
|
1644
|
-
|
|
1645
|
-
|
|
1646
|
-
|
|
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
|
-
|
|
1874
|
-
|
|
1875
|
-
|
|
1876
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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() {
|