@indigoai-us/hq-cloud 6.18.108 → 6.18.110

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 (148) hide show
  1. package/dist/bin/area-ledger-migration.d.ts.map +1 -1
  2. package/dist/bin/area-ledger-migration.js +5 -3
  3. package/dist/bin/area-ledger-migration.js.map +1 -1
  4. package/dist/bin/backup-prune-runner.js +2 -2
  5. package/dist/bin/backup-prune-runner.js.map +1 -1
  6. package/dist/bin/runner-output-guard.d.ts +39 -0
  7. package/dist/bin/runner-output-guard.d.ts.map +1 -0
  8. package/dist/bin/runner-output-guard.js +104 -0
  9. package/dist/bin/runner-output-guard.js.map +1 -0
  10. package/dist/bin/sync-runner-company.d.ts +9 -0
  11. package/dist/bin/sync-runner-company.d.ts.map +1 -1
  12. package/dist/bin/sync-runner-company.js +76 -6
  13. package/dist/bin/sync-runner-company.js.map +1 -1
  14. package/dist/bin/sync-runner.d.ts +37 -1
  15. package/dist/bin/sync-runner.d.ts.map +1 -1
  16. package/dist/bin/sync-runner.js +37 -3
  17. package/dist/bin/sync-runner.js.map +1 -1
  18. package/dist/cli/conflict.d.ts +30 -1
  19. package/dist/cli/conflict.d.ts.map +1 -1
  20. package/dist/cli/conflict.js +69 -3
  21. package/dist/cli/conflict.js.map +1 -1
  22. package/dist/cli/reconcile-skip-reason.d.ts +1 -1
  23. package/dist/cli/reconcile-skip-reason.d.ts.map +1 -1
  24. package/dist/cli/reconcile-skip-reason.js +2 -0
  25. package/dist/cli/reconcile-skip-reason.js.map +1 -1
  26. package/dist/cli/reindex.d.ts.map +1 -1
  27. package/dist/cli/reindex.js +228 -43
  28. package/dist/cli/reindex.js.map +1 -1
  29. package/dist/cli/rescue-core.d.ts +160 -1
  30. package/dist/cli/rescue-core.d.ts.map +1 -1
  31. package/dist/cli/rescue-core.js +681 -162
  32. package/dist/cli/rescue-core.js.map +1 -1
  33. package/dist/cli/rescue-native-copy.d.ts +88 -0
  34. package/dist/cli/rescue-native-copy.d.ts.map +1 -0
  35. package/dist/cli/rescue-native-copy.js +823 -0
  36. package/dist/cli/rescue-native-copy.js.map +1 -0
  37. package/dist/cli/rescue.d.ts.map +1 -1
  38. package/dist/cli/rescue.js +37 -9
  39. package/dist/cli/rescue.js.map +1 -1
  40. package/dist/cli/share.d.ts +35 -8
  41. package/dist/cli/share.d.ts.map +1 -1
  42. package/dist/cli/share.js +437 -32
  43. package/dist/cli/share.js.map +1 -1
  44. package/dist/cli/sync.d.ts +70 -5
  45. package/dist/cli/sync.d.ts.map +1 -1
  46. package/dist/cli/sync.js +439 -77
  47. package/dist/cli/sync.js.map +1 -1
  48. package/dist/cognito-auth.d.ts +10 -0
  49. package/dist/cognito-auth.d.ts.map +1 -1
  50. package/dist/cognito-auth.js +162 -1
  51. package/dist/cognito-auth.js.map +1 -1
  52. package/dist/ignore.d.ts +5 -1
  53. package/dist/ignore.d.ts.map +1 -1
  54. package/dist/ignore.js +75 -23
  55. package/dist/ignore.js.map +1 -1
  56. package/dist/index.d.ts +4 -3
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +7 -2
  59. package/dist/index.js.map +1 -1
  60. package/dist/journal-row-store.d.ts +3 -0
  61. package/dist/journal-row-store.d.ts.map +1 -1
  62. package/dist/journal-row-store.js +21 -0
  63. package/dist/journal-row-store.js.map +1 -1
  64. package/dist/journal-snapshot-decoder.js +2 -0
  65. package/dist/journal-snapshot-decoder.js.map +1 -1
  66. package/dist/journal-snapshot-v4.d.ts.map +1 -1
  67. package/dist/journal-snapshot-v4.js +6 -1
  68. package/dist/journal-snapshot-v4.js.map +1 -1
  69. package/dist/journal.d.ts +1 -1
  70. package/dist/journal.d.ts.map +1 -1
  71. package/dist/journal.js +20 -20
  72. package/dist/journal.js.map +1 -1
  73. package/dist/lib/append-log-merge.d.ts +43 -0
  74. package/dist/lib/append-log-merge.d.ts.map +1 -0
  75. package/dist/lib/append-log-merge.js +424 -0
  76. package/dist/lib/append-log-merge.js.map +1 -0
  77. package/dist/lib/same-path-upload-lock.d.ts +27 -1
  78. package/dist/lib/same-path-upload-lock.d.ts.map +1 -1
  79. package/dist/lib/same-path-upload-lock.js +32 -1
  80. package/dist/lib/same-path-upload-lock.js.map +1 -1
  81. package/dist/object-io.d.ts +36 -1
  82. package/dist/object-io.d.ts.map +1 -1
  83. package/dist/object-io.js +93 -12
  84. package/dist/object-io.js.map +1 -1
  85. package/dist/operation-lock.d.ts +27 -1
  86. package/dist/operation-lock.d.ts.map +1 -1
  87. package/dist/operation-lock.js +94 -8
  88. package/dist/operation-lock.js.map +1 -1
  89. package/dist/outposts/client.d.ts +19 -6
  90. package/dist/outposts/client.d.ts.map +1 -1
  91. package/dist/outposts/client.js +16 -5
  92. package/dist/outposts/client.js.map +1 -1
  93. package/dist/outposts/command.d.ts +2 -1
  94. package/dist/outposts/command.d.ts.map +1 -1
  95. package/dist/outposts/command.js +81 -13
  96. package/dist/outposts/command.js.map +1 -1
  97. package/dist/outposts/self-deploy.d.ts.map +1 -1
  98. package/dist/outposts/self-deploy.js +3 -0
  99. package/dist/outposts/self-deploy.js.map +1 -1
  100. package/dist/private-folder-transport.d.ts +0 -2
  101. package/dist/private-folder-transport.d.ts.map +1 -1
  102. package/dist/private-folder-transport.js +17 -16
  103. package/dist/private-folder-transport.js.map +1 -1
  104. package/dist/push-identity-fence.d.ts +116 -3
  105. package/dist/push-identity-fence.d.ts.map +1 -1
  106. package/dist/push-identity-fence.js +625 -62
  107. package/dist/push-identity-fence.js.map +1 -1
  108. package/dist/qmd-reindex.d.ts.map +1 -1
  109. package/dist/qmd-reindex.js +3 -2
  110. package/dist/qmd-reindex.js.map +1 -1
  111. package/dist/s3.d.ts +30 -9
  112. package/dist/s3.d.ts.map +1 -1
  113. package/dist/s3.js +110 -82
  114. package/dist/s3.js.map +1 -1
  115. package/dist/sync/area-ledger-migration.d.ts +17 -0
  116. package/dist/sync/area-ledger-migration.d.ts.map +1 -1
  117. package/dist/sync/area-ledger-migration.js +37 -3
  118. package/dist/sync/area-ledger-migration.js.map +1 -1
  119. package/dist/sync/scattered-delete-burst.d.ts +61 -0
  120. package/dist/sync/scattered-delete-burst.d.ts.map +1 -0
  121. package/dist/sync/scattered-delete-burst.js +111 -0
  122. package/dist/sync/scattered-delete-burst.js.map +1 -0
  123. package/dist/sync/unattended-delete-hold.d.ts +102 -0
  124. package/dist/sync/unattended-delete-hold.d.ts.map +1 -0
  125. package/dist/sync/unattended-delete-hold.js +164 -0
  126. package/dist/sync/unattended-delete-hold.js.map +1 -0
  127. package/dist/sync-core.d.ts +5 -6
  128. package/dist/sync-core.d.ts.map +1 -1
  129. package/dist/sync-core.js +5 -6
  130. package/dist/sync-core.js.map +1 -1
  131. package/dist/types.d.ts +13 -2
  132. package/dist/types.d.ts.map +1 -1
  133. package/dist/vault-client.d.ts +6 -0
  134. package/dist/vault-client.d.ts.map +1 -1
  135. package/dist/vault-client.js +53 -8
  136. package/dist/vault-client.js.map +1 -1
  137. package/dist/vault-key-grammar.d.ts +44 -0
  138. package/dist/vault-key-grammar.d.ts.map +1 -0
  139. package/dist/vault-key-grammar.js +158 -0
  140. package/dist/vault-key-grammar.js.map +1 -0
  141. package/dist/watcher.d.ts.map +1 -1
  142. package/dist/watcher.js +4 -1
  143. package/dist/watcher.js.map +1 -1
  144. package/dist/windows-extended-path.d.ts +22 -0
  145. package/dist/windows-extended-path.d.ts.map +1 -0
  146. package/dist/windows-extended-path.js +55 -0
  147. package/dist/windows-extended-path.js.map +1 -0
  148. package/package.json +1 -1
@@ -8,9 +8,11 @@
8
8
  * `git` (clone/checkout/hash-object/cat-file/ls-tree/show/log) and `rsync`
9
9
  * (the overlay) — are still invoked as subprocesses. YAML stamp reads and
10
10
  * writes are handled in-process so a rescue does not depend on optional YAML
11
- * executables being present. Reimplementing git's blob hashing or rsync's
12
- * include/exclude filter engine in pure JS would *increase* the risk of
13
- * behavioural drift, so the port reuses those exact tools and argument vectors.
11
+ * executables being present. Reimplementing git's blob hashing in pure JS
12
+ * would *increase* the risk of behavioural drift, so the port reuses git's
13
+ * exact commands. When rsync is not on PATH (a stock Windows install), the
14
+ * overlay runs the built-in copy in ./rescue-native-copy.ts with the same
15
+ * rsync argument vector; see {@link selectOverlayCopyEngine}.
14
16
  *
15
17
  * Behaviour (classification outcomes, on-disk results, log lines, exit codes)
16
18
  * is preserved 1:1 with the legacy script. See the original script's header in
@@ -38,6 +40,7 @@ import { assertRescuePathTypeUnchanged, isRescueTransientDirectory, rescueSnapsh
38
40
  import { applyBackupPrune, canonicalRootHash, inventoryManagedSnapshots, isManagedSnapshotManifest, } from "../backup-prune.js";
39
41
  import { makeRestoreProbePath, makeRestoreStagePath, } from "../restore-staging.js";
40
42
  import { readCoreSourceStamp, writeCoreSourceStamp } from "./core-source-stamp.js";
43
+ import { compileRsyncPattern, rsyncFilterRuleMatches, runNativeOverlay, } from "./rescue-native-copy.js";
41
44
  import { chooseRescueGit, GIT_VERSION_PROBE_TIMEOUT_MS, gitTooOldMessage, parseGitVersion, pinGitFirstOnPath, RESCUE_MIN_GIT_VERSION, } from "./rescue-git.js";
42
45
  const MAX_CLONE_FILES_PER_BATCH = 200;
43
46
  const MAX_CLONE_BATCH_PATH_BYTES = 64 * 1024;
@@ -133,6 +136,7 @@ function runWithSpawnError(cmd, args, opts = {}) {
133
136
  input: opts.input,
134
137
  encoding: "utf-8",
135
138
  ...(typeof opts.timeout === "number" ? { timeout: opts.timeout } : {}),
139
+ ...(typeof opts.maxBuffer === "number" ? { maxBuffer: opts.maxBuffer } : {}),
136
140
  });
137
141
  return {
138
142
  status: res.status ?? (res.error ? 127 : 1),
@@ -142,6 +146,57 @@ function runWithSpawnError(cmd, args, opts = {}) {
142
146
  signal: res.signal,
143
147
  };
144
148
  }
149
+ export const GIT_BATCH_CHUNK_SIZE = 4096;
150
+ const GIT_BATCH_MAX_BUFFER = 256 * 1024 * 1024;
151
+ export class GitBatchError extends Error {
152
+ args;
153
+ result;
154
+ chunkStart;
155
+ chunkLength;
156
+ constructor(args, result, chunkStart, chunkLength) {
157
+ const detail = result.error?.message ??
158
+ (result.signal ? `killed by ${result.signal}` : `exit ${result.status}`);
159
+ super(`git ${args.join(" ")} failed on inputs ${chunkStart}..${chunkStart + chunkLength - 1}: ${detail}${result.stderr.trim() ? `\n${result.stderr.trim()}` : ""}`);
160
+ this.args = args;
161
+ this.result = result;
162
+ this.chunkStart = chunkStart;
163
+ this.chunkLength = chunkLength;
164
+ }
165
+ }
166
+ /**
167
+ * Feed `inputs` to a line-oriented git batch command and return exactly one
168
+ * output line per input, in order. Inputs are sent in chunks so no single
169
+ * child ever produces more output than spawnSync will buffer, and any chunk
170
+ * that fails (non-zero exit, signal, spawn error, short output) throws instead
171
+ * of returning a partial result.
172
+ */
173
+ export function runGitBatch(args, inputs, opts = {}) {
174
+ const chunkSize = Math.max(1, opts.chunkSize ?? GIT_BATCH_CHUNK_SIZE);
175
+ const lines = [];
176
+ for (let start = 0; start < inputs.length; start += chunkSize) {
177
+ const chunk = inputs.slice(start, start + chunkSize);
178
+ const res = run("git", args, {
179
+ cwd: opts.cwd,
180
+ env: opts.env,
181
+ input: chunk.join("\n") + "\n",
182
+ maxBuffer: GIT_BATCH_MAX_BUFFER,
183
+ });
184
+ if (res.status !== 0 || res.error || res.signal) {
185
+ throw new GitBatchError(args, res, start, chunk.length);
186
+ }
187
+ const out = res.stdout.endsWith("\n") ? res.stdout.slice(0, -1) : res.stdout;
188
+ const got = out === "" ? [] : out.split("\n");
189
+ if (got.length !== chunk.length) {
190
+ throw new GitBatchError(args, {
191
+ ...res,
192
+ stderr: `expected ${chunk.length} output lines, got ${got.length}`,
193
+ }, start, chunk.length);
194
+ }
195
+ for (const line of got)
196
+ lines.push(line);
197
+ }
198
+ return lines;
199
+ }
145
200
  /** Read an environment value without relying on Windows' case-insensitive proxy. */
146
201
  export function envValue(env, name) {
147
202
  for (const [key, value] of Object.entries(env)) {
@@ -265,6 +320,12 @@ function classifyGitFailure(result) {
265
320
  if (isMissingMacCommandLineTools(diagnostic)) {
266
321
  return "missing-dependency";
267
322
  }
323
+ // A dead or unresolvable http.proxy in git config is not a flaky network.
324
+ // Retrying it three times only delays the same error, and blaming the
325
+ // Internet connection hides the setting that caused it.
326
+ if (diagnostic.includes("could not resolve proxy")) {
327
+ return "proxy-config";
328
+ }
268
329
  // Interrupted transfers are retryable. Corrupt packs, checksum mismatches,
269
330
  // and other integrity failures are not: retrying those three times hides the
270
331
  // real error and can write a bad clone more than once.
@@ -273,7 +334,6 @@ function classifyGitFailure(result) {
273
334
  const transientNetworkSignals = [
274
335
  "resolving timed out",
275
336
  "could not resolve host",
276
- "could not resolve proxy",
277
337
  "temporary failure in name resolution",
278
338
  "network is unreachable",
279
339
  "connection timed out",
@@ -490,24 +550,137 @@ function buildRsyncLauncher(candidatePath) {
490
550
  }
491
551
  return { command: "rsync", leadingArgs: [] };
492
552
  }
493
- /** The overlay requires rsync; do not allocate a recovery copy when it cannot run. */
494
- export function requireWorkingRsync(env, err) {
553
+ /** The `rsync --version` probe may not hang the rescue; a hung shim fails closed. */
554
+ export const RSYNC_PROBE_TIMEOUT_MS = 15_000;
555
+ /** Error code for a Windows shim path that cmd.exe cannot be trusted to parse. */
556
+ export const RSYNC_UNSAFE_SHIM_PATH = "EUNSAFEPATH";
557
+ /**
558
+ * True when a `.cmd`/`.bat` path can be passed to `cmd.exe /d /c` as one
559
+ * argument. Node quotes an argument only for spaces and quotes, and cmd.exe
560
+ * still expands `%VAR%` and treats `& | < > ^ ( ) @ !` specially, so a path
561
+ * with any of them is refused rather than launched.
562
+ */
563
+ export function isCmdSafeShimPath(candidatePath) {
564
+ return !/[&|<>^%!"()@]/.test(candidatePath);
565
+ }
566
+ /** Find rsync on PATH and run `rsync --version` through the overlay's launcher. */
567
+ function probeRsync(env) {
495
568
  const resolvedPath = envValue(env, "PATH");
496
569
  const entries = pathEntries(resolvedPath);
497
570
  const foundRsync = findRsyncOnPath(entries, env);
498
571
  const launcher = buildRsyncLauncher(foundRsync?.path);
572
+ if (process.platform === "win32" &&
573
+ foundRsync &&
574
+ isWindowsShimPath(foundRsync.path) &&
575
+ !isCmdSafeShimPath(foundRsync.path)) {
576
+ // cmd.exe would re-parse these characters inside the path, so the shim
577
+ // is never launched (here or by the overlay).
578
+ const error = Object.assign(new Error("rsync shim path contains characters cmd.exe would interpret"), { code: RSYNC_UNSAFE_SHIM_PATH });
579
+ const probe = { status: 126, stdout: "", stderr: "", error, signal: null };
580
+ return { launcher, foundRsync, entries, resolvedPath, probe, output: "\n", working: false };
581
+ }
499
582
  const probe = runWithSpawnError(launcher.command, [...launcher.leadingArgs, "--version"], {
500
583
  env,
584
+ timeout: RSYNC_PROBE_TIMEOUT_MS,
501
585
  });
502
586
  const output = `${probe.stdout}\n${probe.stderr}`;
503
- if (probe.status === 0 && /\brsync\b.*\bversion\b/i.test(output))
504
- return launcher;
587
+ const working = probe.status === 0 && /\brsync\b.*\bversion\b/i.test(output);
588
+ return { launcher, foundRsync, entries, resolvedPath, probe, output, working };
589
+ }
590
+ /**
591
+ * rsync is absent, not broken: no candidate on PATH and the launch failed
592
+ * with ENOENT. A present but unexecutable, failing, or unrecognised rsync is
593
+ * not "absent" and still stops the rescue.
594
+ */
595
+ /**
596
+ * On Windows, the rsync on PATH plainly cannot run: it could not be spawned
597
+ * (ENOENT, EACCES), its shim path is unsafe for cmd.exe, or it exited non-zero
598
+ * with no output at all. A timeout, a signal, unrecognised version output or
599
+ * a non-zero exit that printed something is not "cannot run" and still stops
600
+ * the rescue, so a misconfigured rsync the user installed stays loud.
601
+ */
602
+ export function rsyncCannotRunOnWindows(result) {
603
+ const code = result.probe.error && "code" in result.probe.error
604
+ ? result.probe.error.code
605
+ : undefined;
606
+ if (code === "ENOENT" || code === "EACCES" || code === RSYNC_UNSAFE_SHIM_PATH)
607
+ return true;
608
+ if (result.probe.error || result.probe.signal)
609
+ return false;
610
+ return result.probe.status !== 0 && result.output.trim() === "";
611
+ }
612
+ /** One-line reason for the log when the Windows fallback is taken. */
613
+ function rsyncProbeFailureSummary(result) {
614
+ const error = result.probe.error;
615
+ if (error)
616
+ return error.code ?? error.name;
617
+ return `exit ${result.probe.status}, no output`;
618
+ }
619
+ function rsyncIsMissing(result) {
620
+ const code = result.probe.error && "code" in result.probe.error
621
+ ? result.probe.error.code
622
+ : undefined;
623
+ return result.foundRsync === undefined && code === "ENOENT";
624
+ }
625
+ /** The rsync overlay; do not allocate a recovery copy when it cannot run. */
626
+ export function requireWorkingRsync(env, err) {
627
+ const result = probeRsync(env);
628
+ if (result.working)
629
+ return result.launcher;
630
+ return reportRsyncPreflightFailure(result, err);
631
+ }
632
+ /** Environment variable that forces an overlay engine: `native` or `rsync`. */
633
+ export const COPY_ENGINE_ENV = "HQ_RESCUE_COPY_ENGINE";
634
+ /**
635
+ * Choose the overlay copy engine before any snapshot is allocated.
636
+ *
637
+ * A working rsync is used as before. When rsync is not on PATH at all, the
638
+ * overlay uses the built-in file copy (./rescue-native-copy.ts) with the same
639
+ * filters, instead of failing with exit 127. On Windows an rsync that is on
640
+ * PATH but plainly cannot run (see rsyncCannotRunOnWindows) also uses the
641
+ * built-in copy; any other broken rsync still fails the preflight. `HQ_RESCUE_COPY_ENGINE=rsync`
642
+ * keeps the old rsync-only behaviour; `HQ_RESCUE_COPY_ENGINE=native` uses
643
+ * the built-in copy even when rsync works.
644
+ */
645
+ export function selectOverlayCopyEngine(env, out, err) {
646
+ const forced = (envValue(env, COPY_ENGINE_ENV) ?? "").trim().toLowerCase();
647
+ if (forced === "native") {
648
+ out(`==> Copy engine: built-in file copy (${COPY_ENGINE_ENV}=native)\n`);
649
+ return { kind: "native" };
650
+ }
651
+ if (forced !== "" && forced !== "rsync") {
652
+ err(`error: ${COPY_ENGINE_ENV} must be "native" or "rsync" (got ${JSON.stringify(boundedDiagnostic(forced, 64))}).\n`);
653
+ throw new ExitError(2);
654
+ }
655
+ const result = probeRsync(env);
656
+ if (result.working)
657
+ return { kind: "rsync", launcher: result.launcher };
658
+ if (forced === "" && rsyncIsMissing(result)) {
659
+ out("==> Copy engine: built-in file copy (rsync not found on PATH)\n");
660
+ return { kind: "native" };
661
+ }
662
+ // On Windows an rsync that is on PATH but plainly cannot run (a .cmd shim
663
+ // whose target is gone, an MSYS rsync missing its DLLs) is common and not
664
+ // something the user chose. Use the built-in copy there too, and say why.
665
+ // Any other probe failure, every failure off Windows, and
666
+ // HQ_RESCUE_COPY_ENGINE=rsync still stop the rescue.
667
+ if (forced === "" && process.platform === "win32" && rsyncCannotRunOnWindows(result)) {
668
+ const where = result.foundRsync?.path ?? "PATH";
669
+ out(`==> Copy engine: built-in file copy (rsync at ${boundedDiagnostic(where, 256)} could not run: ${boundedDiagnostic(rsyncProbeFailureSummary(result), 128)})\n`);
670
+ return { kind: "native" };
671
+ }
672
+ return reportRsyncPreflightFailure(result, err);
673
+ }
674
+ /** Print the rsync preflight diagnostic and stop the rescue. */
675
+ function reportRsyncPreflightFailure({ foundRsync, entries, resolvedPath, probe, output }, err) {
505
676
  err("error: rsync preflight failed before any safety snapshot was allocated.\n");
506
677
  if (probe.error) {
507
678
  const errorDetail = "code" in probe.error && typeof probe.error.code === "string"
508
679
  ? probe.error.code
509
680
  : probe.error.name;
510
- err(` rsync was not found or could not be executed (${errorDetail}).\n`);
681
+ err(errorDetail === "ETIMEDOUT"
682
+ ? ` rsync --version did not finish within ${RSYNC_PROBE_TIMEOUT_MS / 1000}s (ETIMEDOUT).\n`
683
+ : ` rsync was not found or could not be executed (${errorDetail}).\n`);
511
684
  }
512
685
  else if (probe.signal) {
513
686
  err(` rsync was terminated by signal ${probe.signal}.\n`);
@@ -531,7 +704,7 @@ export function requireWorkingRsync(env, err) {
531
704
  : "(none)";
532
705
  err(` rsync found at: ${foundRsyncDiagnostic}\n`);
533
706
  err(` resolved PATH: ${boundedDiagnostic(resolvedPath ?? "(unset)", 1024)}\n`);
534
- err(" Install or repair rsync and retry. On Windows, install the Cygwin rsync package with the Cygwin installer and add its bin directory to PATH.\n");
707
+ err(" Install or repair rsync and retry. Or set HQ_RESCUE_COPY_ENGINE=native to use the built-in file copy instead. On Windows, install the Cygwin rsync package with the Cygwin installer and add its bin directory to PATH.\n");
535
708
  throw new ExitError(probe.status || 127);
536
709
  }
537
710
  // fs predicates mirroring bash test operators.
@@ -817,7 +990,15 @@ export function parseRescueArgs(argv) {
817
990
  " [--no-backup] [--backup-dir DIR] [--cloud-update]\n" +
818
991
  " [--dry-run] [--yes] [--recover-snapshots]\n" +
819
992
  " [--verify-restored-snapshot SNAPSHOT]\n" +
820
- " [--restore-snapshot SNAPSHOT]\n");
993
+ " [--restore-snapshot SNAPSHOT]\n" +
994
+ "\n" +
995
+ "environment:\n" +
996
+ " HQ_RESCUE_COPY_ENGINE=native|rsync\n" +
997
+ " How the release is copied into the HQ root. Unset: rsync when it\n" +
998
+ " works, the built-in file copy when rsync is not on PATH; a broken\n" +
999
+ " rsync stops the update. rsync: require rsync (exit 127 when it is\n" +
1000
+ " missing). native: always use the built-in file copy. Any other\n" +
1001
+ " value exits 2.\n");
821
1002
  throw new ExitError(1);
822
1003
  };
823
1004
  let narrowCsv = "";
@@ -1635,10 +1816,12 @@ export function realpathOrExit(p, err) {
1635
1816
  }
1636
1817
  }
1637
1818
  }
1638
- function reportRsyncFailure(status, phase, stderr, err) {
1819
+ function reportRsyncFailure(status, phase, stderr, err, engine = "rsync") {
1639
1820
  if (stderr)
1640
1821
  err(stderr);
1641
- err(`rsync status ${status} during ${phase}\n`);
1822
+ // The built-in copy returns rsync's status codes (23 = some entries were
1823
+ // not copied), so the failure kinds and the restore path stay the same.
1824
+ err(`${engine === "native" ? "built-in file copy" : "rsync"} status ${status} during ${phase}\n`);
1642
1825
  err(`HQ_RESCUE_FAILURE_KIND=${status === 23 || status === 24 ? "rsync-partial" : "rsync-failed"}\n`);
1643
1826
  }
1644
1827
  function hashRecoveryTree(root, rootRel) {
@@ -1803,66 +1986,6 @@ export function rsyncWindowsEnv(env, platform = process.platform) {
1803
1986
  }
1804
1987
  return next;
1805
1988
  }
1806
- /** One `--include=`/`--exclude=` rule as rsync's receiver filter applies it. */
1807
- function rsyncFilterRuleMatches(rawPattern, rel, isDir) {
1808
- let pattern = rawPattern;
1809
- let tripleStar = false;
1810
- if (pattern.endsWith("/***")) {
1811
- tripleStar = true;
1812
- pattern = pattern.slice(0, -4);
1813
- }
1814
- else if (pattern.endsWith("/")) {
1815
- if (!isDir)
1816
- return false;
1817
- pattern = pattern.replace(/\/+$/, "");
1818
- }
1819
- const anchored = pattern.startsWith("/");
1820
- if (anchored)
1821
- pattern = pattern.replace(/^\/+/, "");
1822
- if (pattern.length === 0)
1823
- return false;
1824
- let body = "";
1825
- for (let i = 0; i < pattern.length; i++) {
1826
- const ch = pattern[i];
1827
- if (ch === "*") {
1828
- if (pattern[i + 1] === "*") {
1829
- body += ".*";
1830
- i++;
1831
- }
1832
- else {
1833
- body += "[^/]*";
1834
- }
1835
- }
1836
- else if (ch === "?") {
1837
- body += "[^/]";
1838
- }
1839
- else if (ch === "[") {
1840
- const close = pattern.indexOf("]", i + 1);
1841
- if (close < 0) {
1842
- body += "\\[";
1843
- }
1844
- else {
1845
- body += pattern.slice(i, close + 1).replace(/\\/g, "\\\\");
1846
- i = close;
1847
- }
1848
- }
1849
- else {
1850
- body += ch.replace(/[.+^${}()|\\]/g, "\\$&");
1851
- }
1852
- }
1853
- if (tripleStar)
1854
- body += "(/.*)?";
1855
- const hasSlash = pattern.includes("/") || tripleStar;
1856
- let source;
1857
- if (anchored)
1858
- source = `^${body}$`;
1859
- else if (hasSlash)
1860
- source = `^(.*/)?${body}$`;
1861
- else
1862
- source = `^${body}$`;
1863
- const subject = !anchored && !hasSlash ? rel.slice(rel.lastIndexOf("/") + 1) : rel;
1864
- return new RegExp(source).test(subject);
1865
- }
1866
1989
  /**
1867
1990
  * The rsync filter list for the full (preserve-list) overlay.
1868
1991
  *
@@ -1897,6 +2020,144 @@ export function fullOverlayRsyncFilters(extraPreserve = []) {
1897
2020
  filters.push(`--exclude=${p}`);
1898
2021
  return filters;
1899
2022
  }
2023
+ /**
2024
+ * The full overlay filter list for a rescue run. rsync and the native copy
2025
+ * engine apply the first rule that matches, so the order is:
2026
+ * 1. `--preserve` entries (full mode), so a preserved path is never written,
2027
+ * even when a kept install rule below names it;
2028
+ * 2. the install exclusions (kept rules, then excluded ones), in both modes;
2029
+ * 3. the mode's own rules: the narrow-path includes, or the full overlay list.
2030
+ */
2031
+ export function overlayRsyncFilters(narrowPaths, extraPreserve) {
2032
+ if (narrowPaths.length !== 0) {
2033
+ const filters = [...installExcludedRsyncFilters()];
2034
+ for (const n of narrowPaths) {
2035
+ filters.push(`--include=/${n}`, `--include=/${n}/***`);
2036
+ }
2037
+ filters.push("--exclude=/*");
2038
+ return filters;
2039
+ }
2040
+ return [
2041
+ ...extraPreserve.map((p) => `--exclude=${p}`),
2042
+ ...installExcludedRsyncFilters(),
2043
+ ...fullOverlayRsyncFilters([...extraPreserve]),
2044
+ ];
2045
+ }
2046
+ /**
2047
+ * Test and build files of a release that an install does not receive.
2048
+ *
2049
+ * The release tree (hq-core, and hq-core-staging on the staging channel) keeps
2050
+ * its tests, fixtures and hook corpora, because its own CI runs them. An
2051
+ * install runs none of them, so the overlay does not copy them and the
2052
+ * classifier treats them as absent from the release.
2053
+ *
2054
+ * The list is explicit, in rsync filter syntax. A name with no `/` matches at
2055
+ * any depth, a trailing `/` matches directories only, and a leading `/`
2056
+ * anchors the pattern at the release root. It was derived from the files the
2057
+ * hq-core-staging promotion carried on 2026-11-13:
2058
+ * - `tests/`, `__tests__/`, `__fixtures__/`, `__snapshots__/`: test folders
2059
+ * at any depth (core/scripts/tests, .claude/hooks/tests, skill and worker
2060
+ * test folders, the root `tests/`).
2061
+ * - the anchored folders: the root `test/`, the hook corpus, and two
2062
+ * fixture folders with other names.
2063
+ * - `*.test.<ext>` and `*.spec.<ext>` for code extensions, and `test_*.py`:
2064
+ * test files that sit beside the code they test.
2065
+ * - the anchored files: test runners whose names do not fit a pattern.
2066
+ *
2067
+ * No pattern matches on `-test.` or `test-` alone: worker skill documents such
2068
+ * as `keyboard-test.md`, `screen-reader-test.md`, `write-test.md` and
2069
+ * `load-test.md` are shipped content. `core/hook-tests/` is not listed either:
2070
+ * `hq doctor --deep` reads those hook cases on an install.
2071
+ */
2072
+ const INSTALL_TEST_EXTENSIONS = ["sh", "bash", "mjs", "cjs", "js", "ts", "tsx", "py", "ps1"];
2073
+ export const INSTALL_EXCLUDED_PATTERNS = [
2074
+ // Everything in core/scripts/tests that INSTALL_KEPT_PATTERNS does not name.
2075
+ "/core/scripts/tests/*",
2076
+ "tests/",
2077
+ "__tests__/",
2078
+ "__fixtures__/",
2079
+ "__snapshots__/",
2080
+ "/test/",
2081
+ "/core/scripts/hook-corpus/",
2082
+ "/core/workers/public/content-shared/test/",
2083
+ "/.claude/skills/daily-brief/scripts/fixtures/",
2084
+ ...INSTALL_TEST_EXTENSIONS.flatMap((ext) => [`*.test.${ext}`, `*.spec.${ext}`]),
2085
+ "test_*.py",
2086
+ "/core/scripts/test-codex-hook-adapter.sh",
2087
+ "/core/scripts/anywhere-parity-test.sh",
2088
+ "/core/scripts/anywhere-vm-test.sh",
2089
+ "/.claude/skills/outpost-host/test-guard.sh",
2090
+ ];
2091
+ /**
2092
+ * Release paths that match a pattern above and are still installed, because a
2093
+ * shipped script runs them. A kept pattern wins over an excluded one. Remove
2094
+ * an entry when its caller stops shipping.
2095
+ */
2096
+ export const INSTALL_KEPT_PATTERNS = [
2097
+ // core/workers/public/qa-tester/src/runner.ts runs these Playwright specs
2098
+ // against a target site. They are the worker's payload.
2099
+ "/core/workers/public/qa-tester/tests/***",
2100
+ // The folder itself, so the files named below can be reached.
2101
+ "/core/scripts/tests/",
2102
+ // core/scripts/check-skill-edit.sh runs these six.
2103
+ "/core/scripts/tests/skill-script-refs.test.sh",
2104
+ "/core/scripts/tests/skill-core-script-references.test.sh",
2105
+ "/core/scripts/tests/skill-body-positional-placeholders.test.sh",
2106
+ "/core/scripts/tests/skill-company-bind-before-read.test.sh",
2107
+ "/core/scripts/tests/agent-runtime-skill-metadata.test.sh",
2108
+ "/core/scripts/tests/agent-runtime-permissions.test.sh",
2109
+ // core/scripts/ci/run-shell-smoke-timeout-tests.sh runs these two.
2110
+ "/core/scripts/tests/hook-timeout-sentry.test.sh",
2111
+ "/core/scripts/tests/hook-timeout-watchdog-attribution.test.sh",
2112
+ ];
2113
+ /** The install exclusions as overlay filters. They go first: the first match wins. */
2114
+ export function installExcludedRsyncFilters() {
2115
+ return [
2116
+ ...INSTALL_KEPT_PATTERNS.map((pattern) => `--include=${pattern}`),
2117
+ ...INSTALL_EXCLUDED_PATTERNS.map((pattern) => `--exclude=${pattern}`),
2118
+ ];
2119
+ }
2120
+ const INSTALL_KEPT_MATCHERS = INSTALL_KEPT_PATTERNS.map(compileRsyncPattern);
2121
+ const INSTALL_EXCLUDED_MATCHERS = INSTALL_EXCLUDED_PATTERNS.map(compileRsyncPattern);
2122
+ /**
2123
+ * True when `rel` (POSIX separators, relative to the HQ root) is a release
2124
+ * file that an install does not receive. Every ancestor folder is checked, as
2125
+ * rsync does, and a kept pattern wins over an excluded one at each level.
2126
+ */
2127
+ export function isInstallExcluded(rel) {
2128
+ const segments = rel.split("/").filter((segment) => segment.length > 0);
2129
+ for (let depth = 1; depth <= segments.length; depth++) {
2130
+ const prefix = segments.slice(0, depth).join("/");
2131
+ const isDir = depth < segments.length;
2132
+ if (INSTALL_KEPT_MATCHERS.some((matches) => matches(prefix, isDir)))
2133
+ continue;
2134
+ if (INSTALL_EXCLUDED_MATCHERS.some((matches) => matches(prefix, isDir)))
2135
+ return true;
2136
+ }
2137
+ return false;
2138
+ }
2139
+ /**
2140
+ * True when the folder that holds `rel` is the physical folder that path names
2141
+ * under the HQ root. A folder on the way that is a link makes this false,
2142
+ * whether the link points inside or outside the HQ root, so a release file is
2143
+ * never removed through a link.
2144
+ */
2145
+ export function installPathIsInsideRoot(hqRoot, rel) {
2146
+ const parentSegments = rel
2147
+ .split("/")
2148
+ .filter((segment) => segment.length > 0)
2149
+ .slice(0, -1);
2150
+ if (path.isAbsolute(rel) || rel.split("/").includes(".."))
2151
+ return false;
2152
+ try {
2153
+ const root = fs.realpathSync.native(hqRoot);
2154
+ const parent = fs.realpathSync.native(path.join(hqRoot, ...parentSegments));
2155
+ return parent === path.join(root, ...parentSegments);
2156
+ }
2157
+ catch {
2158
+ return false;
2159
+ }
2160
+ }
1900
2161
  /**
1901
2162
  * True when rsync's overlay, run with `filters` (the rescue's `--include=` and
1902
2163
  * `--exclude=` list), would transfer `rel`. Every ancestor directory is
@@ -2179,7 +2440,21 @@ function releaseLinkPointsAtStaging(destination, srcDir) {
2179
2440
  return true;
2180
2441
  return absolutePathIsInside(path.resolve(path.dirname(destination), linkText), srcDir);
2181
2442
  }
2182
- function recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, rsyncLauncher, rsyncExcludes, env) {
2443
+ /**
2444
+ * Run one overlay call. `args` is the full rsync argument vector, ending with
2445
+ * the Cygwin-form source and destination. The built-in copy reads the same
2446
+ * options and filters and takes the native `srcDir` and `hqRoot` paths.
2447
+ */
2448
+ function runOverlayCopy(engine, args, srcDir, hqRoot, env) {
2449
+ if (engine.kind === "rsync") {
2450
+ return run(engine.launcher.command, [...engine.launcher.leadingArgs, ...args], {
2451
+ env: rsyncWindowsEnv(env),
2452
+ });
2453
+ }
2454
+ const result = runNativeOverlay(srcDir, hqRoot, args.slice(0, -2));
2455
+ return { ...result, error: undefined, signal: null };
2456
+ }
2457
+ function recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, copyEngine, rsyncExcludes, env) {
2183
2458
  const newest = [...unresolved].sort((left, right) => right.entry.completedMs - left.entry.completedMs ||
2184
2459
  right.entry.createdMs - left.entry.createdMs ||
2185
2460
  right.entry.name.localeCompare(left.entry.name))[0];
@@ -2190,8 +2465,7 @@ function recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, rsyncLauncher, r
2190
2465
  newest.entry.manifest.sourceSha !== srcSha) {
2191
2466
  failures.push("sha");
2192
2467
  }
2193
- const releaseProof = run(rsyncLauncher.command, [
2194
- ...rsyncLauncher.leadingArgs,
2468
+ const releaseProof = runOverlayCopy(copyEngine, [
2195
2469
  "-a",
2196
2470
  "--checksum",
2197
2471
  "--no-times",
@@ -2201,7 +2475,7 @@ function recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, rsyncLauncher, r
2201
2475
  ...rsyncWindowsReceiverArgs(),
2202
2476
  toCygwinRsyncPath(srcDir + "/"),
2203
2477
  toCygwinRsyncPath(hqRoot + "/"),
2204
- ], { env: rsyncWindowsEnv(env) });
2478
+ ], srcDir, hqRoot, env);
2205
2479
  if (releaseProof.status !== 0 ||
2206
2480
  !rsyncOutputHasOnlyDirectoryChanges(`${releaseProof.stdout}\n${releaseProof.stderr}`)) {
2207
2481
  failures.push("release-bytes");
@@ -2243,10 +2517,11 @@ function assertClaudeSettingsAdmission(hqRoot, err) {
2243
2517
  function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTimeoutMs = GIT_REACHABILITY_PROBE_TIMEOUT_MS, stampWriter = writeCoreSourceStamp, restoreOnRsyncFailure = false, setupPathSettingsLocal = false, backupCapacityStatfsSync = fs.statfsSync, backupCapacityCloneProbe, backupCapacityStatSync = fs.statSync, pathSep = path.sep, snapshotClonePlatform = process.platform, snapshotCloneRunner = runDarwinClone) {
2244
2518
  const hqRoot = resolveHqRoot(cfg, err);
2245
2519
  const RUN_TS = utcStamp(new Date(), "dash");
2246
- // Both the release overlay and a restorable snapshot require rsync. A shim
2247
- // which merely starts but exits non-zero used to trigger an enormous cp -a
2248
- // fallback, then fail later at overlay. Stop before classification/allocation.
2249
- const rsyncLauncher = requireWorkingRsync(env, err);
2520
+ // Choose the overlay engine before classification/allocation. No rsync at
2521
+ // all (stock Windows) uses the built-in copy, and so does a Windows rsync
2522
+ // that plainly cannot run. Any other broken rsync stops here, before an
2523
+ // enormous snapshot is allocated, rather than failing later at overlay.
2524
+ const copyEngine = selectOverlayCopyEngine(env, out, err);
2250
2525
  // The release clone uses `--filter=blob:none`, which needs git 2.19+. Check
2251
2526
  // before the prompt so an old git fails with a plain message instead of a
2252
2527
  // clone usage dump. A newer git later on PATH is pinned after the scratch
@@ -2437,7 +2712,11 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2437
2712
  err(`git ${gitResult.command} did not finish${bound} and was stopped ` +
2438
2713
  `(${gitResult.attempts} attempt${gitResult.attempts === 1 ? "" : "s"}).\n`);
2439
2714
  }
2440
- if (gitResult.failureKind === "network-unreachable") {
2715
+ if (gitResult.failureKind === "proxy-config") {
2716
+ err("HQ_RESCUE_FAILURE_KIND=proxy-config\n");
2717
+ err("error: Git could not resolve the http.proxy setting. Check git config http.proxy (including the HQ root's local .git/config), then retry. Nothing was changed.\n");
2718
+ }
2719
+ else if (gitResult.failureKind === "network-unreachable") {
2441
2720
  err("HQ_RESCUE_FAILURE_KIND=network-unreachable\n");
2442
2721
  err("error: HQ could not reach GitHub after retries. Check your Internet connection, then retry. Nothing was changed.\n");
2443
2722
  }
@@ -2451,18 +2730,19 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2451
2730
  throw new ExitError(5);
2452
2731
  };
2453
2732
  // One bounded ls-remote per update, not per clone or checkout attempt.
2454
- // Only network-unreachable and missing-dependency stop the rescue here;
2455
- // any other probe error is left for the clone to report, so a successful
2456
- // probe cannot mask a later clone failure.
2457
- const probeResult = runGitWithNetworkRetry(["ls-remote", "--exit-code", cloneUrl, cfg.ref], { env, timeout: gitReachabilityProbeTimeoutMs }, out);
2733
+ // network-unreachable, missing-dependency, and proxy-config stop the rescue
2734
+ // here; any other probe error is left for the clone to report, so a
2735
+ // successful probe cannot mask a later clone failure.
2736
+ const probeResult = runGitWithNetworkRetry(["ls-remote", "--exit-code", cloneUrl, cfg.ref], { cwd: tmpdir, env, timeout: gitReachabilityProbeTimeoutMs }, out);
2458
2737
  if (probeResult.failureKind === "network-unreachable" ||
2459
- probeResult.failureKind === "missing-dependency") {
2738
+ probeResult.failureKind === "missing-dependency" ||
2739
+ probeResult.failureKind === "proxy-config") {
2460
2740
  reportFatalGitFailure(probeResult, "error: clone failed\n");
2461
2741
  }
2462
2742
  out("\n");
2463
2743
  if (cfg.historyCheck) {
2464
2744
  out(`==> Cloning ${cloneUrlDisplay} @${cfg.ref} (full history, blob:none filter) ...\n`);
2465
- const cloneResult = runGitWithNetworkRetry(["clone", "--filter=blob:none", cloneUrl, srcDir], { env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2745
+ const cloneResult = runGitWithNetworkRetry(["clone", "--filter=blob:none", cloneUrl, srcDir], { cwd: tmpdir, env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2466
2746
  if (cloneResult.result.status !== 0) {
2467
2747
  reportFatalGitFailure(cloneResult, "error: clone failed\n");
2468
2748
  }
@@ -2473,7 +2753,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2473
2753
  }
2474
2754
  else {
2475
2755
  out(`==> Cloning ${cloneUrlDisplay} @${cfg.ref} (shallow) ...\n`);
2476
- const shallowCloneResult = runGitWithNetworkRetry(["clone", "--depth", "1", "--branch", cfg.ref, cloneUrl, srcDir], { env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2756
+ const shallowCloneResult = runGitWithNetworkRetry(["clone", "--depth", "1", "--branch", cfg.ref, cloneUrl, srcDir], { cwd: tmpdir, env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2477
2757
  if (shallowCloneResult.result.status !== 0) {
2478
2758
  if (shouldStopAfterShallowCloneFailure(shallowCloneResult)) {
2479
2759
  reportFatalGitFailure(shallowCloneResult, "error: clone failed\n");
@@ -2481,7 +2761,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2481
2761
  reportGitFailure(shallowCloneResult.result);
2482
2762
  out(" (shallow branch clone failed; trying full clone + checkout)\n");
2483
2763
  fs.rmSync(srcDir, { recursive: true, force: true });
2484
- const cloneResult = runGitWithNetworkRetry(["clone", cloneUrl, srcDir], { env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2764
+ const cloneResult = runGitWithNetworkRetry(["clone", cloneUrl, srcDir], { cwd: tmpdir, env }, out, () => fs.rmSync(srcDir, { recursive: true, force: true }));
2485
2765
  if (cloneResult.result.status !== 0) {
2486
2766
  reportFatalGitFailure(cloneResult, "error: clone failed\n");
2487
2767
  }
@@ -2535,20 +2815,12 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2535
2815
  }
2536
2816
  // --- Build wipe/overlay arg sets per mode ---
2537
2817
  const pruneNames = [];
2538
- let rsyncExcludes = [];
2539
- if (cfg.narrowPaths.length !== 0) {
2540
- for (const n of cfg.narrowPaths) {
2541
- rsyncExcludes.push(`--include=/${n}`);
2542
- rsyncExcludes.push(`--include=/${n}/***`);
2543
- }
2544
- rsyncExcludes.push("--exclude=/*");
2545
- }
2546
- else {
2818
+ if (cfg.narrowPaths.length === 0) {
2547
2819
  pruneNames.push(...ALWAYS_PRESERVED_NAMES);
2548
2820
  for (const p of cfg.extraPreserve)
2549
2821
  pruneNames.push(p);
2550
- rsyncExcludes = fullOverlayRsyncFilters(cfg.extraPreserve);
2551
2822
  }
2823
+ const rsyncExcludes = overlayRsyncFilters(cfg.narrowPaths, cfg.extraPreserve);
2552
2824
  // --- Compute the wipe-set top-level roots ---
2553
2825
  const wipeToplevel = [];
2554
2826
  if (cfg.narrowPaths.length !== 0) {
@@ -2584,6 +2856,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2584
2856
  userConflict: 0,
2585
2857
  userOverwrite: 0,
2586
2858
  userKeptLocal: 0,
2859
+ installExcludedKept: 0,
2587
2860
  claudeDiffAppend: 0,
2588
2861
  symlinkDropped: 0,
2589
2862
  cloudSymlinkReconciled: 0,
@@ -2628,6 +2901,11 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2628
2901
  }
2629
2902
  else {
2630
2903
  out(`==> Walking wipe set, classifying vs. ${cfg.sourceRepo}@${cfg.ref} ...\n`);
2904
+ const packDirs = installedSkillPackDirs(hqRoot, releaseSkillNames(ctx));
2905
+ if (packDirs.length > 0) {
2906
+ ctx.skipDirs = new Set(packDirs);
2907
+ out(`==> Leaving ${packDirs.length} installed skill pack${packDirs.length === 1 ? "" : "s"} from ${SKILLS_LOCK_FILE} in place without classifying: ${packDirs.map((d) => d.slice(SKILLS_DIR.length + 1)).join(", ")}\n`);
2908
+ }
2631
2909
  // Batch the per-file git facts (hashes + floor lookups) up front so the
2632
2910
  // walk below is map lookups, not ~3 git spawns per file.
2633
2911
  precomputeGitMaps(ctx, wipeToplevel);
@@ -2645,6 +2923,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2645
2923
  out(` user-edit (conflict quarantine): ${counts.userConflict} files\n`);
2646
2924
  out(` user-edit (overwrite-safe): ${counts.userOverwrite} files\n`);
2647
2925
  out(` user-edit (kept local): ${counts.userKeptLocal} files\n`);
2926
+ out(` release test files kept (not installed): ${counts.installExcludedKept} files\n`);
2648
2927
  out(` cloud-symlink reconciled: ${counts.cloudSymlinkReconciled} files\n`);
2649
2928
  out(` drift reconciled (== upstream): ${counts.driftReconciled} files\n`);
2650
2929
  out(` reindex symlinks dropped: ${counts.symlinkDropped} entries\n`);
@@ -2716,9 +2995,9 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2716
2995
  ];
2717
2996
  // Exercise the exact overlay command before any classified delete/move. A
2718
2997
  // Cygwin path conversion or filter failure therefore leaves the root intact.
2719
- const overlayPreflight = run(rsyncLauncher.command, [...rsyncLauncher.leadingArgs, "--dry-run", ...overlayArgs], { env: rsyncWindowsEnv(env) });
2998
+ const overlayPreflight = runOverlayCopy(copyEngine, ["--dry-run", ...overlayArgs], srcDir, hqRoot, env);
2720
2999
  if (overlayPreflight.status !== 0) {
2721
- reportRsyncFailure(overlayPreflight.status, "dry-run", overlayPreflight.stderr, err);
3000
+ reportRsyncFailure(overlayPreflight.status, "dry-run", overlayPreflight.stderr, err, copyEngine.kind);
2722
3001
  throw new ExitError(overlayPreflight.status || 1);
2723
3002
  }
2724
3003
  ctx.actions = buildRescueActions(ctx);
@@ -2780,7 +3059,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2780
3059
  if (postRestore.problem) {
2781
3060
  err(`error: post-restore permit is not usable: ${postRestore.problem}\n`);
2782
3061
  }
2783
- const proof = recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, rsyncLauncher, rsyncExcludes, env);
3062
+ const proof = recoveryProof(unresolved, cfg, hqRoot, srcDir, srcSha, copyEngine, rsyncExcludes, env);
2784
3063
  if (proof.eligible && proof.failures.length === 0) {
2785
3064
  out("==> Recovery proof passed: interrupted update matches the release and preserved paths; continuing.\n");
2786
3065
  err("HQ_RESCUE_NOTE=recovery-proof-passed\n");
@@ -2966,7 +3245,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2966
3245
  mutationStarted = true;
2967
3246
  applyClassifiedActions(ctx, backupDir);
2968
3247
  out("\n");
2969
- 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`);
3248
+ 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}, release-test-kept: ${counts.installExcludedKept}, cloud-symlink-reconciled: ${counts.cloudSymlinkReconciled}, symlinks-dropped: ${counts.symlinkDropped})\n`);
2970
3249
  // --- Overlay source onto HQ root ---
2971
3250
  out("==> Overlaying source onto HQ root ...\n");
2972
3251
  // `unchangedList` is only populated during applyClassifiedActions above, so
@@ -2985,10 +3264,10 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
2985
3264
  toCygwinRsyncPath(hqRoot + "/"),
2986
3265
  ]
2987
3266
  : overlayArgs;
2988
- const overlay = run(rsyncLauncher.command, [...rsyncLauncher.leadingArgs, ...overlayRunArgs], { env: rsyncWindowsEnv(env) });
3267
+ const overlay = runOverlayCopy(copyEngine, overlayRunArgs, srcDir, hqRoot, env);
2989
3268
  if (overlay.status !== 0) {
2990
3269
  // bash runs under set -e: a failed rsync aborts with its status.
2991
- reportRsyncFailure(overlay.status, "overlay", overlay.stderr, err);
3270
+ reportRsyncFailure(overlay.status, "overlay", overlay.stderr, err, copyEngine.kind);
2992
3271
  if (restoreOnRsyncFailure) {
2993
3272
  const manifest = backupDir ? readSnapshotManifest(backupDir, hqRoot) : null;
2994
3273
  if (!manifest || hasSkippedSnapshotEntries(manifest)) {
@@ -3150,6 +3429,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
3150
3429
  out(` user-edits (conflict quarantine): ${counts.userConflict} files\n`);
3151
3430
  out(` user-edits (overwrite-safe): ${counts.userOverwrite} files\n`);
3152
3431
  out(` user-edit (kept local): ${counts.userKeptLocal} files\n`);
3432
+ out(` release test files kept (not installed): ${counts.installExcludedKept} files\n`);
3153
3433
  out(` cloud-symlink reconciled: ${counts.cloudSymlinkReconciled} files\n`);
3154
3434
  out(` drift reconciled (== upstream): ${counts.driftReconciled} files\n`);
3155
3435
  out(` reindex symlinks dropped: ${counts.symlinkDropped} entries\n`);
@@ -3185,6 +3465,7 @@ function doRescue(cfg, env, out, err, setTmp, retainTmp, gitReachabilityProbeTim
3185
3465
  lines.push(` user-edit (conflict quarantine): ${counts.userConflict}`);
3186
3466
  lines.push(` user-edit (overwrite-safe): ${counts.userOverwrite}`);
3187
3467
  lines.push(` user-edit (kept local, ignore file): ${counts.userKeptLocal}`);
3468
+ lines.push(` release test files kept (not installed): ${counts.installExcludedKept}`);
3188
3469
  lines.push(` cloud-symlink reconciled: ${counts.cloudSymlinkReconciled}`);
3189
3470
  lines.push(` drift reconciled (== upstream HEAD): ${counts.driftReconciled}`);
3190
3471
  lines.push(` reindex symlinks dropped: ${counts.symlinkDropped}`);
@@ -3328,6 +3609,9 @@ function recordDecision(ctx, decision) {
3328
3609
  case "user-only":
3329
3610
  ctx.counts.userOnly += 1;
3330
3611
  return;
3612
+ case "install-excluded-kept":
3613
+ ctx.counts.installExcludedKept += 1;
3614
+ return;
3331
3615
  case "cloud-symlink-reconciled":
3332
3616
  ctx.counts.cloudSymlinkReconciled += 1;
3333
3617
  return;
@@ -3937,6 +4221,24 @@ export function applyArrayRemovals(theirs, ours, base) {
3937
4221
  }
3938
4222
  }
3939
4223
  }
4224
+ /**
4225
+ * True when every array element that `release` and `ours` share (at the same
4226
+ * path) is also present in `candidate`. Used to find how far back an older
4227
+ * release settings.json can be while still being one the local file could have
4228
+ * been laid from: a version missing an element the local file has from the
4229
+ * release is older than the version the local file was laid from.
4230
+ */
4231
+ export function holdsSharedArrayEntries(candidate, ours, release) {
4232
+ if (Array.isArray(release) && Array.isArray(ours)) {
4233
+ const cand = Array.isArray(candidate) ? candidate : [];
4234
+ return release.every((e) => !ours.some((o) => jsonDeepEqual(o, e)) || cand.some((c) => jsonDeepEqual(c, e)));
4235
+ }
4236
+ if (isPlainObject(release) && isPlainObject(ours)) {
4237
+ const cand = isPlainObject(candidate) ? candidate : {};
4238
+ return Object.keys(release).every((k) => holdsSharedArrayEntries(cand[k], ours[k], release[k]));
4239
+ }
4240
+ return true;
4241
+ }
3940
4242
  /**
3941
4243
  * Re-compose the machine env.PATH for the freshly-overlaid release template.
3942
4244
  * Runs the SAME composer setup.sh uses (core/scripts/compose-settings-path.sh)
@@ -4256,18 +4558,70 @@ export function reconcileClaudeSettings(ctx, preRescueSettingsJson, out, err) {
4256
4558
  // realBase = settings.json at the last-sync floor (only trustworthy in
4257
4559
  // history_floor mode). Removals require it; additions fall back to theirs.
4258
4560
  let realBase;
4561
+ let removalBase;
4259
4562
  if (baselineMode === "history_floor" && historyFloor) {
4260
- const show = run("git", ["show", `${historyFloor}:.claude/settings.json`], {
4261
- cwd: srcDir,
4262
- env,
4263
- });
4264
- if (show.status === 0)
4265
- realBase = jsonParseOrNull(show.stdout);
4563
+ const settingsAt = (rev) => {
4564
+ const show = run("git", ["show", `${rev}:.claude/settings.json`], {
4565
+ cwd: srcDir,
4566
+ env,
4567
+ });
4568
+ return show.status === 0 ? jsonParseOrNull(show.stdout) : undefined;
4569
+ };
4570
+ const revParse = (rev) => {
4571
+ const r = run("git", ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], {
4572
+ cwd: srcDir,
4573
+ env,
4574
+ });
4575
+ return r.status === 0 ? r.stdout.trim() : "";
4576
+ };
4577
+ realBase = settingsAt(historyFloor);
4578
+ removalBase = realBase;
4579
+ const floorCommit = revParse(historyFloor);
4580
+ if (isPlainObject(realBase) && floorCommit !== "" && floorCommit === revParse("HEAD")) {
4581
+ // DEV-6811: the floor IS the release being applied, so its settings.json
4582
+ // is the release file itself and every release entry missing locally
4583
+ // (e.g. a hook a recent release added that never got wired in) would
4584
+ // look like a user removal. Walk back through older versions of
4585
+ // settings.json while each still holds every release array entry the
4586
+ // local file has: the local file was laid from such a version or an
4587
+ // older one, so entries added after it were never there to remove.
4588
+ // Removals are then detected against the oldest such version. When the
4589
+ // previous version already lacks an entry the local file has, the base
4590
+ // stays the release file (a repeat run at the same release).
4591
+ const changes = run("git", ["log", "-n", "50", "--format=%H", "HEAD", "--", ".claude/settings.json"], { cwd: srcDir, env });
4592
+ const changeShas = changes.status === 0 ? changes.stdout.split("\n").map((s) => s.trim()).filter(Boolean) : [];
4593
+ let readFailed = changes.status !== 0;
4594
+ for (const sha of changeShas) {
4595
+ const older = settingsAt(`${sha}^`);
4596
+ if (!isPlainObject(older)) {
4597
+ // The tree is local in a blob:none clone, so a path that exists but
4598
+ // whose content could not be read (failed blob fetch) or parsed is
4599
+ // a read failure. A path that does not exist ends the walk normally.
4600
+ const exists = run("git", ["rev-parse", "--verify", "--quiet", `${sha}^:.claude/settings.json`], {
4601
+ cwd: srcDir,
4602
+ env,
4603
+ });
4604
+ if (exists.status === 0)
4605
+ readFailed = true;
4606
+ break;
4607
+ }
4608
+ if (!holdsSharedArrayEntries(older, ours, realBase))
4609
+ break;
4610
+ removalBase = older;
4611
+ }
4612
+ if (readFailed) {
4613
+ // Fall back to the floor file, as before this fix. The drift may stay
4614
+ // unfixed this run, but a user's deliberate removals are never undone
4615
+ // (undoing them would be permanent: the next run sees them as kept).
4616
+ removalBase = realBase;
4617
+ err(" WARN: could not read an older release version of .claude/settings.json; kept the previous behavior\n");
4618
+ }
4619
+ }
4266
4620
  }
4267
- // Removals: only with a REAL floor base (never theirs — release-only entries
4268
- // would look like removals).
4269
- if (isPlainObject(realBase)) {
4270
- applyArrayRemovals(theirs, ours, realBase);
4621
+ // Removals: only with a REAL older-release base (never theirs — release-only
4622
+ // entries would look like removals).
4623
+ if (isPlainObject(removalBase)) {
4624
+ applyArrayRemovals(theirs, ours, removalBase);
4271
4625
  }
4272
4626
  // Additions drift: base = realBase when available, else theirs (conservative
4273
4627
  // head_compare fallback — never loses a customization). See design note.
@@ -4609,8 +4963,10 @@ function classifyOne(ctx, filesystemRel) {
4609
4963
  }
4610
4964
  return { kind: "skip", rel };
4611
4965
  }
4612
- // Is path in upstream HEAD?
4613
- const inHead = existsFollow(srcPath) ? 1 : 0;
4966
+ // Is path in upstream HEAD? A test or build file of the release counts as
4967
+ // absent: the release tree holds it and the install does not receive it.
4968
+ const installExcluded = isInstallExcluded(rel);
4969
+ const inHead = !installExcluded && existsFollow(srcPath) ? 1 : 0;
4614
4970
  // Is path in last-sync floor? Read the batched precompute (floorShas); fall
4615
4971
  // back to a per-file probe for any rel not represented there. A non-null
4616
4972
  // entry both proves presence (inFloor=1) and carries the baseline blob SHA,
@@ -4636,6 +4992,26 @@ function classifyOne(ctx, filesystemRel) {
4636
4992
  if (inHead === 0 && inFloor === 0) {
4637
4993
  return { kind: "user-only", rel };
4638
4994
  }
4995
+ // A release test file the previous release installed. Remove it only when
4996
+ // it is byte-identical to that released copy and no folder on its path is a
4997
+ // link. Anything else is kept in place and reported. Without a
4998
+ // floor (head_compare) inFloor is 0 and the file was left as user-only above.
4999
+ if (installExcluded) {
5000
+ if (!installPathIsInsideRoot(ctx.hqRoot, rel)) {
5001
+ return { kind: "install-excluded-kept", rel, reason: "linked-folder" };
5002
+ }
5003
+ const localSha = ctx.localShas?.get(rel) ??
5004
+ run("git", ["hash-object", localPath], { env: ctx.env }).stdout.trim();
5005
+ const floorSha = baselineSha ??
5006
+ run("git", ["rev-parse", `${ctx.historyFloor}:${rel}`], {
5007
+ cwd: ctx.srcDir,
5008
+ env: ctx.env,
5009
+ }).stdout.trim();
5010
+ if (!localSha || !floorSha || localSha !== floorSha) {
5011
+ return { kind: "install-excluded-kept", rel, reason: "edited" };
5012
+ }
5013
+ return { kind: "unchanged-delete", rel };
5014
+ }
4639
5015
  // Path is/was in upstream. Determine if user edited it.
4640
5016
  let userEdited = 0;
4641
5017
  // Set only by the floor comparison below — the one arm that proves the local
@@ -4762,6 +5138,9 @@ function renderDryRunDecision(ctx, decision) {
4762
5138
  ctx.out(` unchanged (delete; absent upstream): ${decision.rel}\n`);
4763
5139
  }
4764
5140
  break;
5141
+ case "install-excluded-kept":
5142
+ ctx.out(` ${installExcludedKeptLine(decision)}\n`);
5143
+ break;
4765
5144
  case "wholesale-replace-template":
4766
5145
  ctx.out(" wholesale-replace: companies/_template (template carve-out)\n");
4767
5146
  break;
@@ -4904,6 +5283,13 @@ function buildRescueActions(ctx) {
4904
5283
  });
4905
5284
  }
4906
5285
  break;
5286
+ case "install-excluded-kept":
5287
+ // Nothing moves or is deleted, and the overlay never writes here.
5288
+ add(`keep release test file: ${decision.rel}`, [], () => {
5289
+ ctx.out(` ${installExcludedKeptLine(decision)}\n`);
5290
+ ctx.appendLog(`kept-release-test-file\t${decision.rel}\t(${decision.reason === "edited" ? "differs from the released copy" : "a folder on its path is a link"}; no longer installed, left in place)\n`);
5291
+ });
5292
+ break;
4907
5293
  case "wholesale-replace-template":
4908
5294
  add("wholesale-replace: companies/_template", [decision.rel], () => fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), {
4909
5295
  recursive: true,
@@ -4915,8 +5301,16 @@ function buildRescueActions(ctx) {
4915
5301
  return actions;
4916
5302
  }
4917
5303
  function unchangedDeletePathExistsUpstream(ctx, rel) {
5304
+ // The release clone still holds its test files; the install does not get them.
5305
+ if (isInstallExcluded(normalizeRescueRelativePath(rel, ctx.pathSep)))
5306
+ return false;
4918
5307
  return lexists(path.join(ctx.srcDir, rel));
4919
5308
  }
5309
+ export function installExcludedKeptLine(decision) {
5310
+ return decision.reason === "edited"
5311
+ ? `kept (release test file you changed; HQ no longer installs it, delete it by hand): ${decision.rel}`
5312
+ : `kept (release test file reached through a linked folder; rescue does not delete through a link): ${decision.rel}`;
5313
+ }
4920
5314
  /** Make rsync's size+mtime quick check notice changed bytes in the same second. */
4921
5315
  function ensureRsyncDetectsChangedFile(localPath, upstreamPath) {
4922
5316
  const local = lstatOrNull(localPath);
@@ -4957,7 +5351,7 @@ function precomputeGitMaps(ctx, wipeToplevel) {
4957
5351
  const rels = lst.isFile()
4958
5352
  ? [rootRel]
4959
5353
  : lst.isDirectory()
4960
- ? findFilesAndSymlinks(rootAbs, ctx.hqRoot)
5354
+ ? findFilesAndSymlinks(rootAbs, ctx.hqRoot, ctx.skipDirs)
4961
5355
  : [];
4962
5356
  for (const filesystemRel of rels) {
4963
5357
  // A path containing a newline can't survive line-delimited batch stdin;
@@ -4980,31 +5374,26 @@ function precomputeGitMaps(ctx, wipeToplevel) {
4980
5374
  ctx.localShas = new Map();
4981
5375
  return;
4982
5376
  }
4983
- // Pass 1: floor existence + blob SHA for every rel, in one process.
4984
- // `cat-file --batch-check` prints "<sha> <type> <size>" for a present object
4985
- // or "<input> missing" otherwise, one line per input in order. This single
4986
- // pass replaces BOTH the per-file `cat-file -e` (existence) and `rev-parse`
4987
- // (sha). It reads only the git object DB — never local file contents — so it
4988
- // stays cheap even on a 100k-file wipe set.
4989
5377
  const floorShas = new Map();
4990
5378
  if (allRels.length > 0) {
4991
- const res = run("git", ["cat-file", "--batch-check"], {
4992
- cwd: ctx.srcDir,
4993
- env: ctx.env,
4994
- input: allRels.map((rel) => `${ctx.historyFloor}:${rel}`).join("\n") + "\n",
4995
- });
4996
- if (res.status === 0) {
4997
- const lines = res.stdout.split("\n");
4998
- for (let i = 0; i < allRels.length; i++) {
4999
- const line = lines[i] ?? "";
5000
- if (line === "" || line.endsWith(" missing")) {
5001
- floorShas.set(allRels[i], null);
5002
- }
5003
- else {
5004
- const sha = line.split(" ")[0];
5005
- floorShas.set(allRels[i], sha || null);
5006
- }
5007
- }
5379
+ let tree;
5380
+ try {
5381
+ tree = readTreeObjectShas(ctx.historyFloor, {
5382
+ cwd: ctx.srcDir,
5383
+ env: ctx.env,
5384
+ });
5385
+ }
5386
+ catch (e) {
5387
+ if (!(e instanceof GitBatchError))
5388
+ throw e;
5389
+ process.stderr.write(`\nERROR: listing the last-synced release failed while classifying ${allRels.length} paths; aborting before any file is touched.\n${e.message}\n`);
5390
+ throw new ExitError(1);
5391
+ }
5392
+ for (const [rel, sha] of tree)
5393
+ floorShas.set(rel, sha);
5394
+ for (const rel of allRels) {
5395
+ if (!floorShas.has(rel))
5396
+ floorShas.set(rel, null);
5008
5397
  }
5009
5398
  }
5010
5399
  ctx.floorShas = floorShas;
@@ -5023,22 +5412,70 @@ function precomputeGitMaps(ctx, wipeToplevel) {
5023
5412
  hashAbs.push(fileAbs[i]);
5024
5413
  }
5025
5414
  }
5026
- if (hashAbs.length > 0) {
5027
- const res = run("git", ["hash-object", "--stdin-paths"], {
5028
- env: ctx.env,
5029
- input: hashAbs.join("\n") + "\n",
5030
- });
5031
- if (res.status === 0) {
5032
- const lines = res.stdout.split("\n");
5033
- for (let i = 0; i < hashRels.length; i++) {
5034
- const sha = (lines[i] ?? "").trim();
5035
- if (sha)
5036
- localShas.set(hashRels[i], sha);
5037
- }
5038
- }
5415
+ const hashes = hashLocalFilesInChunks(hashAbs, ctx.env, (msg) => process.stderr.write(msg));
5416
+ for (let i = 0; i < hashRels.length; i++) {
5417
+ const sha = hashes[i];
5418
+ if (sha)
5419
+ localShas.set(hashRels[i], sha);
5039
5420
  }
5040
5421
  ctx.localShas = localShas;
5041
5422
  }
5423
+ /**
5424
+ * Blob SHA for each local file, in order; "" where the file could not be
5425
+ * hashed. `git hash-object --stdin-paths` stops at the first file it cannot
5426
+ * open (a cloud placeholder, a permission-denied file, one deleted mid-walk),
5427
+ * so a chunk that fails is retried one file at a time. That bounds the
5428
+ * per-file spawns to one chunk, and an unhashable file simply stays out of
5429
+ * the map, which classifyOne treats as a local edit.
5430
+ */
5431
+ export function hashLocalFilesInChunks(absPaths, env, warn, chunkSize = GIT_BATCH_CHUNK_SIZE) {
5432
+ const out = [];
5433
+ for (let start = 0; start < absPaths.length; start += chunkSize) {
5434
+ const chunk = absPaths.slice(start, start + chunkSize);
5435
+ let lines;
5436
+ try {
5437
+ lines = runGitBatch(["hash-object", "--stdin-paths"], chunk, {
5438
+ env,
5439
+ chunkSize,
5440
+ });
5441
+ }
5442
+ catch (e) {
5443
+ if (!(e instanceof GitBatchError))
5444
+ throw e;
5445
+ warn(`warning: batched hash of ${chunk.length} files failed (${e.message.split("\n").slice(-1)[0]}); hashing them one at a time\n`);
5446
+ lines = chunk.map((abs) => run("git", ["hash-object", abs], { env }).stdout);
5447
+ }
5448
+ for (const line of lines)
5449
+ out.push(line.trim());
5450
+ }
5451
+ return out;
5452
+ }
5453
+ /**
5454
+ * Object SHA for every blob, symlink and tree path in `ref`, keyed by its
5455
+ * repo-relative path. Reads tree objects only, so a `--filter=blob:none`
5456
+ * clone answers it from its local object store with no promisor fetch.
5457
+ */
5458
+ export function readTreeObjectShas(ref, opts) {
5459
+ const args = ["ls-tree", "-r", "-t", "-z", "--full-tree", ref];
5460
+ const res = run("git", args, {
5461
+ cwd: opts.cwd,
5462
+ env: opts.env,
5463
+ maxBuffer: GIT_BATCH_MAX_BUFFER,
5464
+ });
5465
+ if (res.status !== 0 || res.error || res.signal) {
5466
+ throw new GitBatchError(args, res, 0, 1);
5467
+ }
5468
+ const shas = new Map();
5469
+ for (const entry of res.stdout.split("\0")) {
5470
+ const tab = entry.indexOf("\t");
5471
+ if (tab < 0)
5472
+ continue;
5473
+ const [, type, sha] = entry.slice(0, tab).split(" ");
5474
+ if (type === "blob" || type === "tree")
5475
+ shas.set(entry.slice(tab + 1), sha);
5476
+ }
5477
+ return shas;
5478
+ }
5042
5479
  function walkAndProcess(ctx, rootRel) {
5043
5480
  const rootAbs = path.join(ctx.hqRoot, rootRel);
5044
5481
  if (!lexists(rootAbs))
@@ -5088,7 +5525,7 @@ function walkAndProcess(ctx, rootRel) {
5088
5525
  return;
5089
5526
  }
5090
5527
  // Top-level directory: recursive walk, pruning canonical transient state.
5091
- for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot)) {
5528
+ for (const rel of findFilesAndSymlinks(rootAbs, ctx.hqRoot, ctx.skipDirs)) {
5092
5529
  recordDecision(ctx, classifyOne(ctx, rel));
5093
5530
  }
5094
5531
  }
@@ -5097,7 +5534,7 @@ function walkAndProcess(ctx, rootRel) {
5097
5534
  * transient directories and never descending into directory symlinks. Order is
5098
5535
  * deterministic so classification and apply plans remain reproducible.
5099
5536
  */
5100
- function findFilesAndSymlinks(rootAbs, hqRoot) {
5537
+ function findFilesAndSymlinks(rootAbs, hqRoot, skipDirs = EMPTY_SKIP_DIRS) {
5101
5538
  const found = [];
5102
5539
  const walk = (dir) => {
5103
5540
  let entries;
@@ -5126,6 +5563,8 @@ function findFilesAndSymlinks(rootAbs, hqRoot) {
5126
5563
  const rel = abs.slice(hqRoot.length + 1);
5127
5564
  if (isRescueTransientDirectory(rel))
5128
5565
  continue;
5566
+ if (skipDirs.size > 0 && skipDirs.has(rel.replace(/\\/g, "/")))
5567
+ continue;
5129
5568
  walk(abs);
5130
5569
  continue;
5131
5570
  }
@@ -5137,6 +5576,75 @@ function findFilesAndSymlinks(rootAbs, hqRoot) {
5137
5576
  walk(rootAbs);
5138
5577
  return found;
5139
5578
  }
5579
+ const EMPTY_SKIP_DIRS = new Set();
5580
+ const SKILLS_LOCK_FILE = "skills-lock.json";
5581
+ const SKILLS_DIR = ".claude/skills";
5582
+ /**
5583
+ * Skill packs the operator installed from a third-party source are recorded
5584
+ * in `<hqRoot>/skills-lock.json` and copied under `.claude/skills/<name>`.
5585
+ * The release never ships them, so every file inside classifies as user-only
5586
+ * and is left in place; walking them only costs time (one Shopify toolkit is
5587
+ * 27k files). Return the `.claude/skills/<name>` directories that are safe to
5588
+ * leave out of the walk: listed in the lock file, a real directory locally,
5589
+ * and absent from both the release HEAD and the baseline floor, so no file
5590
+ * inside can be release content.
5591
+ */
5592
+ export function installedSkillPackDirs(hqRoot, releaseSkillNames) {
5593
+ let lock;
5594
+ try {
5595
+ lock = JSON.parse(fs.readFileSync(path.join(hqRoot, SKILLS_LOCK_FILE), "utf-8"));
5596
+ }
5597
+ catch {
5598
+ return [];
5599
+ }
5600
+ const skills = lock && typeof lock === "object" ? lock.skills : undefined;
5601
+ if (!skills || typeof skills !== "object" || Array.isArray(skills))
5602
+ return [];
5603
+ const dirs = [];
5604
+ for (const name of Object.keys(skills).sort()) {
5605
+ if (name === "" ||
5606
+ name === "." ||
5607
+ name === ".." ||
5608
+ name.includes("/") ||
5609
+ name.includes("\\") ||
5610
+ name.includes("\n")) {
5611
+ continue;
5612
+ }
5613
+ if (releaseSkillNames.has(name))
5614
+ continue;
5615
+ const st = lstatOrNull(path.join(hqRoot, SKILLS_DIR, name));
5616
+ if (!st || !st.isDirectory())
5617
+ continue;
5618
+ dirs.push(`${SKILLS_DIR}/${name}`);
5619
+ }
5620
+ return dirs;
5621
+ }
5622
+ /** Skill directory names present in the release HEAD and, when there is one, the baseline floor. */
5623
+ function releaseSkillNames(ctx) {
5624
+ const names = new Set();
5625
+ let headEntries = [];
5626
+ try {
5627
+ headEntries = fs.readdirSync(path.join(ctx.srcDir, SKILLS_DIR));
5628
+ }
5629
+ catch {
5630
+ headEntries = [];
5631
+ }
5632
+ for (const name of headEntries)
5633
+ names.add(name);
5634
+ if (ctx.baselineMode === "history_floor") {
5635
+ const res = run("git", ["ls-tree", "--name-only", `${ctx.historyFloor}:${SKILLS_DIR}`], {
5636
+ cwd: ctx.srcDir,
5637
+ env: ctx.env,
5638
+ });
5639
+ if (res.status === 0) {
5640
+ for (const line of res.stdout.split("\n")) {
5641
+ if (line !== "")
5642
+ names.add(line);
5643
+ }
5644
+ }
5645
+ }
5646
+ return names;
5647
+ }
5140
5648
  // --- restore file mtimes from git commit history ---
5141
5649
  function restoreMtimesFromGit(srcDir, env, out) {
5142
5650
  // Deepen a shallow clone so per-file commit times are real.
@@ -6369,12 +6877,23 @@ function rescuePathsOverlap(first, second) {
6369
6877
  function isSkippedSnapshotPath(ctx, rel) {
6370
6878
  return ctx.skippedSnapshotRels.some((skippedRel) => rescuePathsOverlap(rel, skippedRel));
6371
6879
  }
6372
- function appendLiteralRsyncExclude(excludeList, rel, recursive = false) {
6880
+ /**
6881
+ * Protect one path from the overlay with an exact rsync exclude. rsync reads
6882
+ * backslash escapes only in a pattern that holds a wildcard (`*`, `?`, `[`,
6883
+ * or the `/***` suffix of a recursive entry), so escape only then; a plain
6884
+ * name with a backslash is compared literally and must stay as it is.
6885
+ * A backslash inside an escaped entry is written as a bracket class holding
6886
+ * one escaped backslash, because openrsync ignores a doubled backslash there.
6887
+ */
6888
+ export function appendLiteralRsyncExclude(excludeList, rel, recursive = false) {
6373
6889
  let pattern = rel;
6374
- if (/[\\*?[]/.test(pattern)) {
6375
- pattern = pattern
6376
- .replace(/\\/g, "\\\\")
6377
- .replace(/([*?[])/g, "\\$1");
6890
+ if (recursive || /[*?[]/.test(pattern)) {
6891
+ // A backslash becomes a bracket class holding one escaped backslash, not a
6892
+ // doubled backslash. GNU rsync reads both, but openrsync (the /usr/bin/rsync
6893
+ // on macOS) does not honour the doubled form and would leave the path
6894
+ // unprotected. The bracket form matches a literal backslash in GNU rsync,
6895
+ // openrsync, and the built-in copy.
6896
+ pattern = pattern.replace(/[\\*?[]/g, (ch) => ch === "\\" ? "[\\\\]" : `\\${ch}`);
6378
6897
  }
6379
6898
  fs.appendFileSync(excludeList, `/${pattern}${recursive ? "/***" : ""}\0`);
6380
6899
  }