@indigoai-us/hq-cloud 6.14.6 → 6.14.8

package/scripts/vault-rebaseline.sh

@@ -91,12 +91,17 @@ AWS_ARGS=()
 [ -n "$AWS_PROFILE_OVERRIDE" ] && AWS_ARGS+=(--profile "$AWS_PROFILE_OVERRIDE")
 AWS_ARGS+=(--region "$AWS_REGION_OVERRIDE")
 
+command -v jq >/dev/null || {
+  echo "error: jq is required to preserve existing S3 metadata during hq-mode repair" >&2
+  exit 2
+}
+
 # Tmp dirs.
 BASELINE="$(mktemp -d -t hq-rebaseline-baseline-XXXXXX)"
 STAGING="$(mktemp -d -t hq-rebaseline-stage-XXXXXX)"
 
 cleanup() {
-  local rc=$?
+  local rc="${1:-$?}"
   if [ "$KEEP_TMP" = "1" ]; then
     echo "==> --keep-tmp set; preserving $BASELINE and $STAGING" >&2
   else
@@ -212,6 +217,48 @@ SYNC_ARGS=("s3" "sync" "$STAGING/" "s3://$BUCKET/" "--size-only")
 
 aws "${AWS_ARGS[@]}" "${SYNC_ARGS[@]}"
 
+# `aws s3 sync` carries bytes but does not derive hq-cloud's per-file hq-mode
+# metadata. Re-upload ONLY regular objects that lack a valid mode, taking the
+# permission bits from this freshly cloned release tree (the canonical git
+# manifest). This is the one-time repair for legacy objects: a fresh pull can
+# now restore shipped hooks/scripts from metadata rather than guessing from
+# content. Existing user metadata is retained, including created-by fields.
+n_mode_backfilled=0
+MODE_META_DIR="$(mktemp -d -t hq-rebaseline-mode-meta-XXXXXX)"
+cleanup_mode_meta() { rm -rf "${MODE_META_DIR:-}"; }
+trap 'rc=$?; cleanup_mode_meta; cleanup "$rc"' EXIT
+mode_index=0
+while IFS= read -r -d '' src; do
+  rel="${src#"$STAGING/"}"
+  # Symlink records intentionally have no hq-mode (their mode is OS-owned).
+  grep -Fqx -- "$rel" "$SYMLIST" && continue
+
+  mode="$(stat -c '%a' "$src")"
+  head_json="$MODE_META_DIR/$mode_index.head.json"
+  metadata_json="$MODE_META_DIR/$mode_index.metadata.json"
+  mode_index=$((mode_index + 1))
+  aws "${AWS_ARGS[@]}" s3api head-object \
+    --bucket "$BUCKET" --key "$rel" --output json > "$head_json"
+  existing_mode="$(jq -r '.Metadata["hq-mode"] // empty' "$head_json")"
+  if [[ "$existing_mode" =~ ^[0-7]{1,4}$ ]]; then
+    continue
+  fi
+
+  jq -c --arg mode "$mode" \
+    '(.Metadata // {}) + {"hq-mode": $mode}' \
+    "$head_json" > "$metadata_json"
+  content_type="$(jq -r '.ContentType // empty' "$head_json")"
+  if [ "$DRY_RUN" = "1" ]; then
+    echo "    would backfill hq-mode=$mode: $rel" >&2
+  else
+    PUT_ARGS=(s3api put-object --bucket "$BUCKET" --key "$rel" --body "$src" --metadata "file://$metadata_json")
+    [ -n "$content_type" ] && PUT_ARGS+=(--content-type "$content_type")
+    aws "${AWS_ARGS[@]}" "${PUT_ARGS[@]}" >/dev/null
+    echo "    backfilled hq-mode=$mode: $rel" >&2
+  fi
+  n_mode_backfilled=$((n_mode_backfilled + 1))
+done < <(find "$STAGING" -type f -print0)
+
 # Stamp the hq-symlink-target metadata header on every marker so the menubar
 # pull materializes them as real symlinks (apps/hq-cloud/src/s3.ts:466-468
 # prefers header detection; body sniff is fallback).
@@ -271,5 +318,6 @@ echo "    version:       $VERSION ($SOURCE_REPO@$REF)" >&2
 echo "    pushed:        $n_files files, $n_syms symlinks (gross — preserved excluded)" >&2
 echo "    user-state preserved: $n_preserved files" >&2
 echo "    stamped:       $n_stamped" >&2
+echo "    hq-mode backfilled: $n_mode_backfilled" >&2
 echo "    deleted:       $n_deleted (v14 cruft)" >&2
 exit 0

package/scripts/vault-rescue.sh

@@ -120,6 +120,11 @@ AWS_ARGS=()
 [ -n "$AWS_PROFILE_OVERRIDE" ] && AWS_ARGS+=(--profile "$AWS_PROFILE_OVERRIDE")
 AWS_ARGS+=(--region "$AWS_REGION_OVERRIDE")
 
+command -v jq >/dev/null || {
+  echo "error: jq is required to preserve existing S3 metadata during hq-mode repair" >&2
+  exit 2
+}
+
 # Tmp dir setup.
 if [ -n "$TMP_DIR_OVERRIDE" ]; then
   TMP_DIR="$TMP_DIR_OVERRIDE"
@@ -201,8 +206,9 @@ echo "==> [3/3] push $TMP_DIR/  ->  s3://$BUCKET/" >&2
 # per apps/hq-cloud/src/s3.ts:417). Skip a minimal denylist that should
 # never round-trip through S3.
 STAGING="$(mktemp -d -t hq-vault-rescue-stage-XXXXXX)"
+MODE_META_DIR="$(mktemp -d -t hq-vault-rescue-mode-meta-XXXXXX)"
 add_staging_cleanup() {
-  rm -rf "${STAGING:-}"
+  rm -rf "${STAGING:-}" "${MODE_META_DIR:-}"
 }
 # Chain cleanup: existing trap removes TMP_DIR; we also need STAGING gone.
 trap '{ add_staging_cleanup; cleanup; }' EXIT
@@ -261,6 +267,40 @@ echo "    staged files=$n_files symlinks=$n_symlinks skipped=$n_skipped" >&2
 echo "    aws s3 sync $STAGING/ -> s3://$BUCKET/ --size-only --delete" >&2
 aws "${AWS_ARGS[@]}" s3 sync "$STAGING/" "s3://$BUCKET/" --size-only --delete
 
+# The AWS CLI moves bytes without hq-cloud's hq-mode metadata. Re-upload only
+# regular objects that need the one-time repair, preserving existing S3 user
+# metadata. For release-shipped files the rescue overlay supplied these modes
+# from the trusted hq-core git tree, so a fresh pull restores hooks/scripts
+# from canonical metadata instead of trying to infer executability from bytes.
+n_mode_backfilled=0
+mode_index=0
+while IFS= read -r -d '' src; do
+  rel="${src#"$STAGING/"}"
+  # Symlink records intentionally have no hq-mode (their mode is OS-owned).
+  grep -Fqx -- "$rel" "$SYMLINK_LIST" && continue
+
+  mode="$(stat -c '%a' "$src")"
+  head_json="$MODE_META_DIR/$mode_index.head.json"
+  metadata_json="$MODE_META_DIR/$mode_index.metadata.json"
+  mode_index=$((mode_index + 1))
+  aws "${AWS_ARGS[@]}" s3api head-object \
+    --bucket "$BUCKET" --key "$rel" --output json > "$head_json"
+  existing_mode="$(jq -r '.Metadata["hq-mode"] // empty' "$head_json")"
+  if [[ "$existing_mode" =~ ^[0-7]{1,4}$ ]]; then
+    continue
+  fi
+
+  jq -c --arg mode "$mode" \
+    '(.Metadata // {}) + {"hq-mode": $mode}' \
+    "$head_json" > "$metadata_json"
+  content_type="$(jq -r '.ContentType // empty' "$head_json")"
+  PUT_ARGS=(s3api put-object --bucket "$BUCKET" --key "$rel" --body "$src" --metadata "file://$metadata_json")
+  [ -n "$content_type" ] && PUT_ARGS+=(--content-type "$content_type")
+  aws "${AWS_ARGS[@]}" "${PUT_ARGS[@]}" >/dev/null
+  echo "    backfilled hq-mode=$mode: $rel" >&2
+  n_mode_backfilled=$((n_mode_backfilled + 1))
+done < <(find "$STAGING" -type f -print0)
+
 # Stamp the hq-symlink metadata header on every symlink-marker object so
 # the menubar pull materializes them as real symlinks (apps/hq-cloud/src/
 # s3.ts:466-468 prefers header detection; body-sniff is fallback).
@@ -288,4 +328,5 @@ echo "    version:   $VERSION ($SOURCE_REPO@$REF)" >&2
 echo "    files:     $n_files" >&2
 echo "    symlinks:  $n_symlinks" >&2
 echo "    stamped:   $n_stamped" >&2
+echo "    hq-mode backfilled: $n_mode_backfilled" >&2
 echo "    skipped:   $n_skipped" >&2

package/src/backup-prune.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  applyBackupPrune,
+  canonicalRootHash,
+  inventoryManagedSnapshots,
+  planBackupPrune,
+  type BackupEntry,
+  type SnapshotStatus,
+} from "./backup-prune.js";
+
+const DAY = 86_400_000;
+const now = Date.UTC(2026, 6, 15, 12);
+const rootA = "/tmp/hq-a";
+const rootB = "/tmp/hq-b";
+function entry(name: string, age: number, status: SnapshotStatus, root = rootA): BackupEntry {
+  const at = new Date(now - age * DAY).toISOString();
+  return { name, createdMs: now - age * DAY, completedMs: now - age * DAY, bytes: 1,
+    manifest: { schemaVersion: 1, status, canonicalHqRoot: root, rootHash: canonicalRootHash(root), runId: name,
+      creatorPid: 1, creatorStartedAt: at, source: "source", ref: "main", sourceSha: "sha", createdAt: at,
+      completedAt: at, includedRoots: ["core"], fileCount: 1, byteCount: 1 } };
+}
+const names = (x: ReturnType<typeof planBackupPrune>) => x.candidates.map((c) => c.entry.name).sort();
+const protectedNames = (x: ReturnType<typeof planBackupPrune>) => x.protected.map((p) => `${p.entry.name}:${p.reason}`).sort();
+
+describe("planBackupPrune", () => {
+  it("keeps the newest two known-good snapshots per canonical root", () => {
+    const p = planBackupPrune([entry("a1", 0, "completed-good"), entry("a2", 1, "completed-good"), entry("a3", 2, "completed-good"), entry("a4", 3, "completed-good"), entry("b1", 0, "completed-good", rootB)], now);
+    expect(names(p)).toEqual(["a3", "a4"]);
+    expect(protectedNames(p)).toContain("a1:newest-good");
+    expect(protectedNames(p)).toContain("b1:newest-good");
+  });
+
+  it("never selects the sole, old known-good snapshot", () => {
+    const p = planBackupPrune([entry("only", 30, "completed-good")], now);
+    expect(names(p)).toEqual([]);
+    expect(protectedNames(p)).toEqual(["only:newest-good"]);
+  });
+
+  it("retains copying and unsuperseded recovery evidence", () => {
+    const p = planBackupPrune([entry("copy", 40, "copying"), entry("recovery", 40, "recovery-required")], now);
+    expect(names(p)).toEqual([]);
+    expect(protectedNames(p)).toContain("copy:copying-not-superseded");
+    expect(protectedNames(p)).toContain("recovery:recovery-required-no-later-good");
+  });
+
+  it("requires a later good run before pruning recovery-required snapshots", () => {
+    const p = planBackupPrune([entry("recovery-old", 30, "recovery-required"), entry("recovery-new", 2, "recovery-required"), entry("good", 1, "completed-good")], now);
+    expect(names(p)).toEqual(["recovery-old"]);
+    expect(protectedNames(p)).toContain("recovery-new:newest-recovery-required-grace");
+  });
+
+  it("only prunes failed-pre-mutation snapshots after a newer ready/good snapshot", () => {
+    const noSuccess = planBackupPrune([entry("failure", 20, "failed-pre-mutation")], now);
+    expect(names(noSuccess)).toEqual([]);
+    const p = planBackupPrune([entry("failure-new", 1, "failed-pre-mutation"), entry("failure-old", 2, "failed-pre-mutation"), entry("ready", 0, "ready")], now);
+    expect(names(p)).toEqual(["failure-old"]);
+  });
+
+  it("clamps malformed retention so the newest good is still protected", () => {
+    const p = planBackupPrune([entry("one", 30, "completed-good"), entry("two", 31, "completed-good"), entry("three", 32, "completed-good")], now, { keepGood: 0, maxAgeDays: Number.NaN });
+    expect(names(p)).toEqual(["three"]);
+    expect(protectedNames(p)).toContain("one:newest-good");
+  });
+});
+
+describe("managed snapshot filesystem boundary", () => {
+  it("does not select prefix matches, mcp, symlinks, malformed metadata, or changed candidates", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-root-"));
+    const backup = fs.mkdtempSync(path.join(os.tmpdir(), "hq-prune-backup-"));
+    try {
+      const make = (name: string, age: number) => {
+        const dir = path.join(backup, name); fs.mkdirSync(dir);
+        const at = new Date(now - age * DAY).toISOString();
+        fs.writeFileSync(path.join(dir, "SNAPSHOT.json"), JSON.stringify({ ...entry(name, age, "completed-good", root).manifest, runId: name, createdAt: at, completedAt: at }));
+        return dir;
+      };
+      const good1 = make("pre-update-2026-07-15T12-00-00Z-" + canonicalRootHash(root) + "-one", 0);
+      const good2 = make("pre-update-2026-07-14T12-00-00Z-" + canonicalRootHash(root) + "-two", 1);
+      const old = make("pre-update-2026-07-13T12-00-00Z-" + canonicalRootHash(root) + "-three", 2);
+      fs.mkdirSync(path.join(backup, "mcp"));
+      fs.mkdirSync(path.join(backup, "pre-update-not-managed"));
+      fs.symlinkSync(good1, path.join(backup, "pre-update-2026-07-12T12-00-00Z-" + canonicalRootHash(root) + "-symlink"));
+      const inventory = inventoryManagedSnapshots(backup, root);
+      expect(inventory.candidates.map((x) => x.entry.name)).toEqual([path.basename(old)]);
+      expect(inventory.unmanaged.map((x) => x.name)).toEqual(expect.arrayContaining(["mcp", "pre-update-not-managed"]));
+      // A changed manifest invalidates the dry-run identity and cannot be removed.
+      fs.writeFileSync(path.join(old, "SNAPSHOT.json"), JSON.stringify({ ...entry("replacement", 2, "completed-good", root).manifest }));
+      const result = applyBackupPrune(backup, root, inventory);
+      expect(result.deleted).toEqual([]);
+      expect(fs.existsSync(old)).toBe(true);
+      expect(fs.existsSync(path.join(backup, "mcp"))).toBe(true);
+      expect(fs.existsSync(good2)).toBe(true);
+    } finally { fs.rmSync(root, { recursive: true, force: true }); fs.rmSync(backup, { recursive: true, force: true }); }
+  });
+});

package/src/backup-prune.ts

@@ -0,0 +1,182 @@
+/**
+ * Safety-first inventory and retention policy for HQ rescue snapshots.
+ *
+ * This file deliberately separates policy from filesystem access.  In
+ * particular, `planBackupPrune` cannot remove, create, or mutate anything.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+
+export const SNAPSHOT_SCHEMA_VERSION = 1;
+export const SNAPSHOT_FILE = "SNAPSHOT.json";
+export const MANAGED_SNAPSHOT_RE = /^pre-update-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]{16}-[A-Za-z0-9_-]+$/;
+export type SnapshotStatus = "copying" | "ready" | "completed-good" | "failed-pre-mutation" | "recovery-required";
+
+export interface SnapshotManifest {
+  schemaVersion: 1;
+  status: SnapshotStatus;
+  canonicalHqRoot: string;
+  rootHash: string;
+  runId: string;
+  creatorPid: number;
+  creatorStartedAt: string;
+  source: string;
+  ref: string;
+  sourceSha: string;
+  createdAt: string;
+  completedAt?: string;
+  includedRoots: string[];
+  fileCount: number;
+  byteCount: number;
+}
+
+export interface BackupEntry {
+  name: string;
+  manifest: SnapshotManifest;
+  createdMs: number;
+  completedMs: number;
+  bytes: number;
+  identity?: { dev: number; ino: number };
+  copyingOwnerLive?: boolean;
+}
+export interface ProtectedEntry { entry: BackupEntry; reason: string }
+export interface DeletionCandidate { entry: BackupEntry; reason: string }
+export interface BackupPrunePlan { candidates: DeletionCandidate[]; protected: ProtectedEntry[]; unmanaged: { name: string; reason: string }[] }
+export interface RetentionConfig { keepGood: number; keepFailedPreMutation: number; maxAgeDays: number }
+
+export const DEFAULT_RETENTION: RetentionConfig = { keepGood: 2, keepFailedPreMutation: 1, maxAgeDays: 7 };
+const day = 24 * 60 * 60 * 1000;
+
+export function canonicalRootHash(root: string): string {
+  return crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+}
+
+export function safeRetention(input: Partial<RetentionConfig> = {}): RetentionConfig {
+  const integer = (value: unknown, fallback: number, minimum: number) =>
+    typeof value === "number" && Number.isInteger(value) && value >= minimum ? value : fallback;
+  return {
+    keepGood: integer(input.keepGood, DEFAULT_RETENTION.keepGood, 1),
+    keepFailedPreMutation: integer(input.keepFailedPreMutation, DEFAULT_RETENTION.keepFailedPreMutation, 1),
+    maxAgeDays: integer(input.maxAgeDays, DEFAULT_RETENTION.maxAgeDays, 0),
+  };
+}
+
+const newestFirst = (a: BackupEntry, b: BackupEntry) => b.completedMs - a.completedMs || b.createdMs - a.createdMs || b.name.localeCompare(a.name);
+
+/** Every managed entry receives either a retention reason or a deletion reason. */
+export function planBackupPrune(entries: BackupEntry[], nowMs: number, input: Partial<RetentionConfig> = {}): BackupPrunePlan {
+  const cfg = safeRetention(input);
+  const candidates: DeletionCandidate[] = [];
+  const protectedEntries: ProtectedEntry[] = [];
+  const byRoot = new Map<string, BackupEntry[]>();
+  for (const entry of entries) {
+    const group = byRoot.get(entry.manifest.canonicalHqRoot) ?? [];
+    group.push(entry);
+    byRoot.set(entry.manifest.canonicalHqRoot, group);
+  }
+  for (const group of byRoot.values()) {
+    const good = group.filter((e) => e.manifest.status === "completed-good").sort(newestFirst);
+    const readyOrGood = group.filter((e) => e.manifest.status === "ready" || e.manifest.status === "completed-good").sort(newestFirst);
+    const laterGood = (e: BackupEntry) => good.some((g) => g.completedMs > e.completedMs || (g.completedMs === e.completedMs && g.name > e.name));
+    const newestRecovery = group.filter((e) => e.manifest.status === "recovery-required").sort(newestFirst)[0];
+    for (const entry of group) {
+      const status = entry.manifest.status;
+      if (status === "copying") {
+        protectedEntries.push({ entry, reason: entry.copyingOwnerLive ? "copying-owner-live" : "copying-not-superseded" });
+        continue;
+      }
+      if (status === "completed-good") {
+        const rank = good.indexOf(entry);
+        if (rank < cfg.keepGood) {
+          protectedEntries.push({ entry, reason: rank === 0 ? "newest-good" : "keep-newest-good" });
+        } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day) {
+          candidates.push({ entry, reason: "completed-good-age-and-rank" });
+        } else {
+          candidates.push({ entry, reason: "completed-good-rank" });
+        }
+        continue;
+      }
+      if (status === "failed-pre-mutation") {
+        const failures = group.filter((e) => e.manifest.status === status).sort(newestFirst);
+        const rank = failures.indexOf(entry);
+        const superseded = readyOrGood.some((other) => newestFirst(other, entry) < 0);
+        if (rank < cfg.keepFailedPreMutation || !superseded) protectedEntries.push({ entry, reason: !superseded ? "failed-pre-mutation-not-superseded" : "keep-failed-pre-mutation" });
+        else candidates.push({ entry, reason: "failed-pre-mutation-superseded" });
+        continue;
+      }
+      // A recovery-required copy is recovery evidence until a later known-good run.
+      if (!laterGood(entry)) {
+        protectedEntries.push({ entry, reason: "recovery-required-no-later-good" });
+      } else if (entry === newestRecovery && nowMs - entry.completedMs < cfg.maxAgeDays * day) {
+        protectedEntries.push({ entry, reason: "newest-recovery-required-grace" });
+      } else if (nowMs - entry.completedMs >= cfg.maxAgeDays * day || entry !== newestRecovery) {
+        candidates.push({ entry, reason: "recovery-required-superseded" });
+      } else {
+        protectedEntries.push({ entry, reason: "recovery-required-grace" });
+      }
+    }
+  }
+  return { candidates, protected: protectedEntries, unmanaged: [] };
+}
+
+function validManifest(value: unknown, canonicalRoot: string): value is SnapshotManifest {
+  const x = value as Partial<SnapshotManifest>;
+  return !!x && x.schemaVersion === SNAPSHOT_SCHEMA_VERSION && typeof x.canonicalHqRoot === "string" &&
+    x.canonicalHqRoot === canonicalRoot && x.rootHash === canonicalRootHash(canonicalRoot) &&
+    typeof x.runId === "string" && /^[A-Za-z0-9_-]+$/.test(x.runId) &&
+    ["copying", "ready", "completed-good", "failed-pre-mutation", "recovery-required"].includes(x.status ?? "") &&
+    typeof x.createdAt === "string" && Array.isArray(x.includedRoots) && typeof x.fileCount === "number" && typeof x.byteCount === "number";
+}
+
+export function inventoryManagedSnapshots(backupRoot: string, canonicalRoot: string, isCopyingOwnerLive: (m: SnapshotManifest) => boolean = () => false, retention: Partial<RetentionConfig> = {}): BackupPrunePlan & { entries: BackupEntry[] } {
+  const entries: BackupEntry[] = [];
+  const unmanaged: { name: string; reason: string }[] = [];
+  let names: string[] = [];
+  try { names = fs.readdirSync(backupRoot); } catch { return { entries, candidates: [], protected: [], unmanaged: [{ name: backupRoot, reason: "backup-root-unreadable" }] }; }
+  for (const name of names.sort()) {
+    // Never descend into categories such as mcp/; only direct, exact names qualify.
+    if (!MANAGED_SNAPSHOT_RE.test(name)) { unmanaged.push({ name, reason: "not-managed-snapshot-name" }); continue; }
+    const abs = path.join(backupRoot, name);
+    let st: fs.Stats;
+    try { st = fs.lstatSync(abs); } catch { unmanaged.push({ name, reason: "lstat-failed" }); continue; }
+    if (!st.isDirectory() || st.isSymbolicLink()) { unmanaged.push({ name, reason: "not-real-directory" }); continue; }
+    let manifest: unknown;
+    try { manifest = JSON.parse(fs.readFileSync(path.join(abs, SNAPSHOT_FILE), "utf8")); } catch { unmanaged.push({ name, reason: "missing-or-invalid-metadata" }); continue; }
+    if (!validManifest(manifest, canonicalRoot)) { unmanaged.push({ name, reason: "metadata-does-not-match-canonical-root" }); continue; }
+    const m = manifest;
+    const createdMs = Date.parse(m.createdAt);
+    const completedMs = Date.parse(m.completedAt ?? m.createdAt);
+    if (!Number.isFinite(createdMs) || !Number.isFinite(completedMs)) { unmanaged.push({ name, reason: "invalid-metadata-timestamp" }); continue; }
+    entries.push({ name, manifest: m, createdMs, completedMs, bytes: m.byteCount, identity: { dev: st.dev, ino: st.ino }, copyingOwnerLive: m.status === "copying" && isCopyingOwnerLive(m) });
+  }
+  const plan = planBackupPrune(entries, Date.now(), retention);
+  return { entries, ...plan, unmanaged: [...unmanaged, ...plan.unmanaged] };
+}
+
+/** Revalidates strict identity then renames before recursively removing it. */
+export function applyBackupPrune(backupRoot: string, canonicalRoot: string, plan: BackupPrunePlan, retention: Partial<RetentionConfig> = {}): { deleted: string[]; failures: string[] } {
+  const deleted: string[] = [], failures: string[] = [];
+  const lockPath = path.join(backupRoot, ".hq-backup-prune.lock");
+  let lockFd: number | undefined;
+  try { lockFd = fs.openSync(lockPath, "wx"); fs.writeSync(lockFd, `${process.pid}\n`); }
+  catch { return { deleted, failures: ["backup-root-lock-busy-or-unwritable"] }; }
+  try {
+    // This is deliberately after acquiring the backup-root lock and immediately
+    // before rename: a dry-run plan is never trusted across a filesystem race.
+    const fresh = inventoryManagedSnapshots(backupRoot, canonicalRoot, () => false, retention);
+    const freshByName = new Map(fresh.entries.map((e) => [e.name, e]));
+    const stillCandidates = new Set(fresh.candidates.map((e) => e.entry.name));
+    for (const candidate of plan.candidates) {
+      const current = freshByName.get(candidate.entry.name);
+      if (!current || !stillCandidates.has(candidate.entry.name) || current.manifest.runId !== candidate.entry.manifest.runId || current.identity?.dev !== candidate.entry.identity?.dev || current.identity?.ino !== candidate.entry.identity?.ino || current.manifest.status === "copying") { failures.push(`${candidate.entry.name}: changed-or-in-use`); continue; }
+      const from = path.join(backupRoot, current.name);
+      const tombstone = path.join(backupRoot, `.deleting-${current.manifest.runId}`);
+      try { fs.renameSync(from, tombstone); fs.rmSync(tombstone, { recursive: true, force: false }); deleted.push(current.name); }
+      catch (error) { failures.push(`${current.name}: ${error instanceof Error ? error.message : String(error)}`); }
+    }
+  } finally {
+    try { if (lockFd !== undefined) fs.closeSync(lockFd); fs.unlinkSync(lockPath); } catch { /* retained errors are safer than a delete race */ }
+  }
+  return { deleted, failures };
+}

package/src/bin/backup-prune-runner.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/** Explicit, local-only retention command. Defaults to dry-run. */
+import * as fs from "fs";
+import * as path from "path";
+import { applyBackupPrune, inventoryManagedSnapshots } from "../backup-prune.js";
+import { acquireOperationLock, OperationLockedError } from "../operation-lock.js";
+
+const args = process.argv.slice(2);
+const value = (flag: string) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+const rootArg = value("--hq-root");
+const backupArg = value("--backup-dir");
+const mode = value("--mode") ?? "dry-run";
+if (!rootArg || !["dry-run", "apply"].includes(mode)) {
+  process.stderr.write("usage: hq-backup-prune --hq-root DIR [--backup-dir DIR] [--mode dry-run|apply]\n");
+  process.exit(2);
+}
+const root = fs.realpathSync(rootArg);
+const backupRoot = backupArg ? path.resolve(backupArg) : path.join(process.env.HOME ?? "", ".hq", "backups");
+let lock;
+try { lock = acquireOperationLock(root, "backup-prune", { timeoutSec: 0, onWaitStart: () => undefined }); }
+catch (error) {
+  if (error instanceof OperationLockedError) { process.stderr.write("hq-backup-prune: skipped-in-use\n"); process.exit(0); }
+  throw error;
+}
+try {
+  const inventory = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
+  const plan = { candidates: inventory.candidates, protected: inventory.protected, unmanaged: inventory.unmanaged };
+  process.stdout.write(JSON.stringify({ mode, candidates: plan.candidates.map((x) => ({ name: x.entry.name, rootHash: x.entry.manifest.rootHash, status: x.entry.manifest.status, bytes: x.entry.bytes, reason: x.reason })), protected: plan.protected.map((x) => ({ name: x.entry.name, reason: x.reason })), unmanaged: plan.unmanaged }) + "\n");
+  if (mode === "apply") {
+    const result = applyBackupPrune(backupRoot, root, plan);
+    if (result.failures.length) { process.stderr.write(result.failures.join("\n") + "\n"); process.exitCode = 1; }
+  }
+} finally { lock.release(); }

package/src/bin/sync-runner-watch-loop.ts

@@ -1,4 +1,5 @@
 import * as path from "path";
+import { inventoryManagedSnapshots } from "../backup-prune.js";
 import { VaultClient } from "../index.js";
 import { pickCanonicalPersonEntity } from "../vault-client.js";
 import {
@@ -98,6 +99,15 @@ export async function runWatchLoop(
   const eventPush = argv.includes("--event-push");
   const companiesMode = argv.includes("--companies");
   const hqRoot = parsed.hqRoot;
+  // Delayed and daily: this must never be attached to the 15s poll cadence.
+  // Stage 0 remains dry-run only; the standalone hq-backup-prune command is
+  // the explicitly-gated apply surface.
+  let nextBackupPruneAt = Date.now() + 60_000;
+  const runBackupPrune = deps.runBackupPrune ?? (async (root: string) => {
+    const backupRoot = path.join(process.env.HOME ?? "", ".hq", "backups");
+    const plan = inventoryManagedSnapshots(backupRoot, root, (m) => { try { process.kill(m.creatorPid, 0); return true; } catch { return false; } });
+    process.stderr.write(`hq-sync-runner: backup retention dry-run — ${plan.candidates.length} candidate(s), ${plan.protected.length} protected\n`);
+  });
 
   const passArgv = argv.filter((a, i) => {
     if (a === "--watch") return false;
@@ -510,6 +520,14 @@ export async function runWatchLoop(
       } else if (result !== 0) {
         return result;
       }
+      if (Date.now() >= nextBackupPruneAt) {
+        // Advance before invoking: a failed/unavailable backstop cannot become
+        // an every-tick retry loop. It is diagnostic only and never restarts
+        // the sync daemon.
+        nextBackupPruneAt = Date.now() + 24 * 60 * 60 * 1000;
+        try { await runBackupPrune(hqRoot); }
+        catch (error) { process.stderr.write(`hq-sync-runner: backup retention dry-run failed — ${error instanceof Error ? error.message : String(error)}\n`); }
+      }
       await Promise.race([sleep(pollMs), stoppedSignal]);
     }
     return 0;

package/src/bin/sync-runner.ts

@@ -1649,6 +1649,8 @@ export interface RunnerLoopDeps {
    * `deps` and forwards just the argv to `runRunner`.
    */
   runPass?: (passArgv: string[]) => Promise<number>;
+  /** Stage-0 backup retention backstop: a dry-run only, never a sync-tick action. */
+  runBackupPrune?: (hqRoot: string) => Promise<void>;
   /**
    * Clock seam for the event-push watcher's debounce window. Defaults to
    * {@link systemClock}; tests inject a `FakeClock` to advance the window

package/src/cli/reindex.ts

@@ -32,6 +32,7 @@ import {
   type CloudTelemetryClient,
   type TelemetryClaims,
 } from "../telemetry-events.js";
+import { decodeLocalVaultSegment, encodeLocalVaultSegment } from "../local-path-codec.js";
 
 export interface ReindexOptions {
   /** HQ root to operate on. Defaults to process.cwd(). */
@@ -565,7 +566,7 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
       if (skillName.startsWith("_")) continue;
       if (!isFile(path.join(skillPath, "SKILL.md"))) continue;
 
-      const wrapperName = `${ns}:${skillName}`;
+      const wrapperName = encodeLocalVaultSegment(`${ns}:${skillName}`);
       const wrapper = path.join(root, ".claude", "skills", wrapperName);
       expectedWrappers.add(wrapperName);
 
@@ -641,13 +642,14 @@ export function reindex(opts: ReindexOptions = {}): ReindexResult {
     const entryPath = path.join(skillsDir, entry);
     const lst = lstatOrNull(entryPath);
     if (!lst) continue; // accept broken symlinks (lstat still succeeds)
-    if (!entry.includes(":")) continue; // not a namespaced wrapper
+    const canonicalEntry = decodeLocalVaultSegment(entry);
+    if (!canonicalEntry.includes(":")) continue; // not a namespaced wrapper
     if (expectedWrappers.has(entry)) continue; // maintained this run
 
     // A wrapper is "managed" only when its namespace prefix matches the
     // namespace encoded in its symlink target — this distinguishes
     // script-produced wrappers from hand-authored composite wrappers.
-    const ns = entry.slice(0, entry.indexOf(":"));
+    const ns = canonicalEntry.slice(0, canonicalEntry.indexOf(":"));
     const matchTarget = (t: string | null, p: string): boolean => {
       if (!t) return false;
       if (t.startsWith(`${p}/personal/skills/`)) return ns === "personal";