@indigoai-us/hq-cloud 6.11.11 → 6.11.12

package/src/cli/rescue-core.ts

@@ -813,7 +813,7 @@ function doRescue(
   // Actions run in classification (walk) order — the same order the old
   // interleaved walk mutated in — so per-file output and on-disk results are
   // unchanged versus before the two-phase split.
-  for (const act of ctx.actions) act();
+  applyClassifiedActions(ctx, backupDir);
 
   // --- Back up preserve-subpaths to a mktemp shuttle ---
   const shuttle = path.join(tmpdir, "preserve");
@@ -1095,7 +1095,7 @@ interface WalkCtx {
   // fail-safe — a throw mid-classify aborts before a single file is mutated, so
   // the wipe is never left half-applied (DEV-1767). Dry-run never fills this (it
   // returns after classification), so live + dry-run share one classify path.
-  actions: Array<() => void>;
+  actions: RescueAction[];
   counts: {
     userOnly: number;
     unchanged: number;
@@ -1112,6 +1112,157 @@ interface WalkCtx {
   out: (s: string) => void;
 }
 
+interface RescueAction {
+  label: string;
+  affectedRels: string[];
+  run: () => void;
+}
+
+function queueAction(
+  ctx: WalkCtx,
+  label: string,
+  affectedRels: string[],
+  runAction: () => void,
+): void {
+  ctx.actions.push({ label, affectedRels, run: runAction });
+}
+
+function applyClassifiedActions(ctx: WalkCtx, backupDir: string): void {
+  const completed: RescueAction[] = [];
+  for (const action of ctx.actions) {
+    try {
+      action.run();
+      completed.push(action);
+    } catch (err) {
+      const restored = rollbackCompletedActions(ctx, completed, backupDir);
+      const manifest = writeApplyFailureManifest(
+        ctx,
+        backupDir,
+        action,
+        completed,
+        restored,
+        err,
+      );
+      ctx.out("\n");
+      ctx.out(`error: rescue apply failed during '${action.label}'.\n`);
+      if (restored.length > 0) {
+        ctx.out(`==> Rolled back ${restored.length} prior action path(s) from the safety snapshot.\n`);
+      }
+      if (manifest) {
+        ctx.out(`==> Recovery manifest: ${manifest}\n`);
+      }
+      throw err;
+    }
+  }
+}
+
+function rollbackCompletedActions(
+  ctx: WalkCtx,
+  completed: RescueAction[],
+  backupDir: string,
+): string[] {
+  if (!backupDir || !isDir(backupDir)) return [];
+
+  const rels: string[] = [];
+  const seen = new Set<string>();
+  for (let i = completed.length - 1; i >= 0; i--) {
+    const action = completed[i];
+    for (let j = action.affectedRels.length - 1; j >= 0; j--) {
+      const rel = action.affectedRels[j];
+      if (rel && !seen.has(rel)) {
+        seen.add(rel);
+        rels.push(rel);
+      }
+    }
+  }
+
+  const restored: string[] = [];
+  for (const rel of rels) {
+    const snapshotPath = path.join(backupDir, rel);
+    if (!lexists(snapshotPath)) continue;
+    const dest = path.join(ctx.hqRoot, rel);
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.rmSync(dest, { recursive: true, force: true });
+      cpATo(snapshotPath, dest);
+      restored.push(rel);
+    } catch {
+      // Recovery manifest below records any path that could not be restored.
+    }
+  }
+  return restored;
+}
+
+function writeApplyFailureManifest(
+  ctx: WalkCtx,
+  backupDir: string,
+  failedAction: RescueAction,
+  completed: RescueAction[],
+  restored: string[],
+  err: unknown,
+): string | null {
+  const message = err instanceof Error ? err.message : String(err);
+  const completedLines =
+    completed.length === 0
+      ? ["  (none)"]
+      : completed.map((action) => {
+          const paths = action.affectedRels.length > 0 ? action.affectedRels.join(", ") : "(no filesystem path)";
+          return `  - ${action.label}: ${paths}`;
+        });
+  const restoredSet = new Set(restored);
+  const unrestored = completed
+    .flatMap((action) => action.affectedRels)
+    .filter((rel, idx, arr) => rel && arr.indexOf(rel) === idx && !restoredSet.has(rel));
+
+  const lines: string[] = [];
+  lines.push("# HQ rescue apply recovery", "");
+  lines.push(`Created: ${ctx.runTs}`);
+  lines.push(`HQ root: ${ctx.hqRoot}`);
+  lines.push(`Source: ${ctx.cfg.sourceRepo}@${ctx.cfg.ref} (${ctx.srcSha})`);
+  lines.push(`Failed action: ${failedAction.label}`);
+  lines.push(`Error: ${message}`);
+  lines.push("");
+  lines.push("## Completed Before Failure");
+  lines.push(...completedLines);
+  lines.push("");
+  lines.push("## Failed Action Paths");
+  if (failedAction.affectedRels.length > 0) {
+    for (const rel of failedAction.affectedRels) lines.push(`  - ${rel}`);
+  } else {
+    lines.push("  (no filesystem path)");
+  }
+  lines.push("");
+  lines.push("## Rollback");
+  if (restored.length > 0) {
+    lines.push("Restored from the pre-op safety snapshot:");
+    for (const rel of restored) lines.push(`  - ${rel}`);
+  } else {
+    lines.push("No completed action paths were restored automatically.");
+  }
+  if (unrestored.length > 0) {
+    lines.push("", "Completed action paths still requiring review:");
+    for (const rel of unrestored) lines.push(`  - ${rel}`);
+  }
+  if (backupDir && isDir(backupDir)) {
+    lines.push("");
+    lines.push("Manual restore examples:");
+    lines.push(`  cp "${backupDir}/<relpath>" "${ctx.hqRoot}/<relpath>"`);
+    lines.push(`  rsync -a "${backupDir}/" "${ctx.hqRoot}/"`);
+  } else {
+    lines.push("", "No pre-op safety snapshot was available for automatic restore.");
+  }
+
+  const manifestDir = path.join(ctx.hqRoot, ".hq", "rescue-recovery");
+  const manifestPath = path.join(manifestDir, `rescue-apply-failure-${ctx.runTs}.md`);
+  try {
+    fs.mkdirSync(manifestDir, { recursive: true });
+    fs.writeFileSync(manifestPath, lines.join("\n") + "\n");
+    return manifestPath;
+  } catch {
+    return null;
+  }
+}
+
 // --- Rescue-target mapping ---
 function mapRescueTarget(rel: string): string {
   if (rel === ".claude/CLAUDE.md") return "personal/CLAUDE.md";
@@ -1431,7 +1582,9 @@ function processOne(ctx: WalkCtx, rel: string): void {
     if (cfg.dryRun) {
       ctx.out(`    drop conflict artifact: ${rel}\n`);
     } else {
-      ctx.actions.push(() => fs.rmSync(localPath, { force: true }));
+      queueAction(ctx, `drop conflict artifact: ${rel}`, [rel], () =>
+        fs.rmSync(localPath, { force: true }),
+      );
     }
     return;
   }
@@ -1441,7 +1594,9 @@ function processOne(ctx: WalkCtx, rel: string): void {
     if (cfg.dryRun) {
       ctx.out(`    skip script-managed (rewrites at stamp step): ${rel}\n`);
     } else {
-      ctx.actions.push(() => fs.rmSync(localPath, { force: true }));
+      queueAction(ctx, `drop script-managed: ${rel}`, [rel], () =>
+        fs.rmSync(localPath, { force: true }),
+      );
     }
     return;
   }
@@ -1460,7 +1615,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
         }
         ctx.out(`    drop reindex symlink: ${rel}  ->  ${tgt}\n`);
       } else {
-        ctx.actions.push(() => {
+        queueAction(ctx, `drop reindex symlink: ${rel}`, [rel], () => {
           fs.rmSync(localPath, { force: true });
           ctx.appendLog(`symlink-dropped\t${rel}\t(reindex regenerable)\n`);
         });
@@ -1530,7 +1685,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
         `    cloud-symlink reconciled (unchanged): ${rel}  (hq-symlink: marker matches upstream target)\n`,
       );
     } else {
-      ctx.actions.push(() => {
+      queueAction(ctx, `cloud-symlink reconciled: ${rel}`, [rel], () => {
         fs.rmSync(localPath, { force: true });
         ctx.appendLog(
           `cloud-symlink-reconciled\t${rel}\t(hq-symlink: marker matches upstream target; overlay re-lays symlink)\n`,
@@ -1546,7 +1701,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
     if (cfg.dryRun) {
       ctx.out(`    drift reconciled (identical to upstream HEAD; no rescue): ${rel}\n`);
     } else {
-      ctx.actions.push(() => {
+      queueAction(ctx, `drift reconciled: ${rel}`, [rel], () => {
         fs.rmSync(localPath, { force: true });
         ctx.appendLog(
           `drift-reconciled\t${rel}\t(identical to upstream HEAD; drifted from floor only — no personal/ copy)\n`,
@@ -1573,17 +1728,21 @@ function processOne(ctx: WalkCtx, rel: string): void {
       }
     } else {
       if (rel === ".claude/CLAUDE.md") {
-        ctx.actions.push(() => rescueOne(ctx, rel));
+        queueAction(ctx, `rescue diff-append: ${rel}`, [rel], () =>
+          rescueOne(ctx, rel),
+        );
       } else if (isOverwriteSafe(rel)) {
-        ctx.actions.push(() => {
+        queueAction(ctx, `overwrite-safe: ${rel}`, [rel], () => {
           fs.rmSync(localPath, { force: true });
           ctx.counts.userOverwrite += 1;
           ctx.appendLog(`overwritten\t${rel}\t(overwrite-safe; upstream wins, no copy preserved)\n`);
         });
       } else if (isConflictClass(rel)) {
-        ctx.actions.push(() => conflictOne(ctx, rel));
+        queueAction(ctx, `conflict quarantine: ${rel}`, [rel], () =>
+          conflictOne(ctx, rel),
+        );
       } else {
-        ctx.actions.push(() => rescueOne(ctx, rel));
+        queueAction(ctx, `rescue: ${rel}`, [rel], () => rescueOne(ctx, rel));
       }
     }
   } else {
@@ -1593,7 +1752,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
       if (cfg.dryRun) {
         ctx.out(`    unchanged (preserved in place): ${rel}\n`);
       } else {
-        ctx.actions.push(() => {
+        queueAction(ctx, `preserve unchanged: ${rel}`, [], () => {
           fs.appendFileSync(ctx.unchangedList, `/${rel}\n`);
           ctx.appendLog(`unchanged\t${rel}\t(identical to upstream; left in place, mtime preserved)\n`);
         });
@@ -1602,7 +1761,7 @@ function processOne(ctx: WalkCtx, rel: string): void {
       if (cfg.dryRun) {
         ctx.out(`    unchanged (delete + replace): ${rel}\n`);
       } else {
-        ctx.actions.push(() => {
+        queueAction(ctx, `delete unchanged: ${rel}`, [rel], () => {
           fs.rmSync(localPath, { force: true });
           ctx.appendLog(`deleted\t${rel}\t(unchanged vs baseline; re-laid by overlay if still upstream)\n`);
         });
@@ -1727,7 +1886,7 @@ function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
     if (cfg.dryRun) {
       ctx.out("    wholesale-replace: companies/_template (template carve-out)\n");
     } else {
-      ctx.actions.push(() =>
+      queueAction(ctx, "wholesale-replace: companies/_template", [rootRel], () =>
         fs.rmSync(path.join(ctx.hqRoot, "companies", "_template"), {
           recursive: true,
           force: true,
@@ -1752,7 +1911,7 @@ function walkAndProcess(ctx: WalkCtx, rootRel: string): void {
         }
         ctx.out(`    drop reindex symlink: ${rootRel}  ->  ${tgt}\n`);
       } else {
-        ctx.actions.push(() => {
+        queueAction(ctx, `drop reindex symlink: ${rootRel}`, [rootRel], () => {
           fs.rmSync(rootAbs, { force: true });
           ctx.appendLog(`symlink-dropped\t${rootRel}\t(reindex regenerable)\n`);
         });

package/src/cli/share.test.ts

@@ -3108,6 +3108,44 @@ describe("share", () => {
     // zero-byte object with x-amz-meta-hq-symlink-target carrying the
     // readlink string verbatim.
 
+    it("F32: first-sync symlink refuses to clobber an existing remote object", async () => {
+      const companyRoot = path.join(tmpDir, "companies", "acme");
+      fs.mkdirSync(companyRoot, { recursive: true });
+      fs.writeFileSync(path.join(companyRoot, "target.md"), "local target");
+      const link = path.join(companyRoot, "link.md");
+      fs.symlinkSync("target.md", link);
+
+      // No journal entry: this machine is seeing link.md for the first time.
+      // A remote object already exists at the same key, and HEAD alone does
+      // not prove it is the same symlink target, so the safe behavior is to
+      // surface a push conflict instead of replacing the remote object.
+      vi.mocked(headRemoteFile).mockResolvedValueOnce({
+        lastModified: new Date(),
+        etag: '"remote-existing-etag"',
+        size: 42,
+      });
+
+      const events: Array<{ type?: string; path?: string; direction?: string }> = [];
+      const result = await share({
+        paths: [link],
+        company: "acme",
+        vaultConfig: mockConfig,
+        hqRoot: tmpDir,
+        onConflict: "abort",
+        onEvent: (e) => events.push(e as { type?: string; path?: string; direction?: string }),
+      });
+
+      expect(result.aborted).toBe(true);
+      expect(result.filesUploaded).toBe(0);
+      expect(result.conflictPaths).toEqual(["link.md"]);
+      expect(uploadSymlink).not.toHaveBeenCalled();
+      expect(
+        events.some(
+          (e) => e.type === "conflict" && e.path === "link.md" && e.direction === "push",
+        ),
+      ).toBe(true);
+    });
+
     it("uploads a top-level symlink as a symlink record (not the target's bytes)", async () => {
       const companyRoot = path.join(tmpDir, "companies", "acme");
       fs.mkdirSync(companyRoot, { recursive: true });

package/src/cli/share.ts

@@ -46,7 +46,11 @@ import {
   fetchCompanyTombstones,
   type CompanyTombstone,
 } from "./tombstones.js";
-import { isCoveredByAny, isDirInScope } from "../prefix-coalesce.js";
+import {
+  isCoveredByAny,
+  isDirInScope,
+  type ScopePrefixInput,
+} from "../prefix-coalesce.js";
 import {
   buildConflictId,
   buildConflictPath,
@@ -637,7 +641,7 @@ export interface ShareOptions {
    * filter — full access. An empty array means "no granted prefixes" → every
    * path is out of scope (mirrors the pull side's `isCoveredByAny([])`).
    */
-  prefixSet?: string[];
+  prefixSet?: ScopePrefixInput[];
   /**
    * Pre-fetched FILE_TOMBSTONE map (POSIX key → tombstone) for the push-side
    * delete-resync consult. When omitted, share() fetches it itself via
@@ -778,7 +782,7 @@ function isPreconditionFailed(err: unknown): boolean {
 function wrapFilterWithScope(
   underlying: (absPath: string, isDir?: boolean) => boolean,
   syncRoot: string,
-  prefixSet: readonly string[],
+  prefixSet: readonly ScopePrefixInput[],
   onScopeExcluded: (rel: string) => void,
 ): (absPath: string, isDir?: boolean) => boolean {
   return (absPath: string, isDir?: boolean) => {
@@ -1279,13 +1283,15 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       let isFreshCollision = false;
       let multipartConverged = false;
-      if (!journalEntry && item.kind === "file") {
+      if (!journalEntry && item.kind === "symlink") {
+        // A HEAD on an existing object does not expose the symlink target.
+        // On a first sync, treat the existing remote as a fresh collision
+        // instead of replacing it with the local link record.
+        isFreshCollision = true;
+      } else if (!journalEntry && item.kind === "file") {
         // Single-part S3 PUT etag is MD5 of the body. Multipart uploads
-        // produce \`<md5>-<partCount>\`. Symlink records (\`kind: "symlink"\`)
-        // skip the check entirely — the wire body shape (\`hq-symlink:\`
-        // prefix + target) isn't a pure byte mirror and would mis-
-        // classify; symlink overwrites are rare and an audit pass after
-        // the broader bug-cleanup wave can extend coverage if needed.
+        // produce `<md5>-<partCount>`. Symlink records cannot be classified
+        // from HEAD alone, so the branch above fails closed.
         const remoteEtagNormalized = normalizeEtag(remoteMeta.etag);
         const isMultipart = /-\d+$/.test(remoteEtagNormalized);
         if (!isMultipart) {
@@ -1392,17 +1398,25 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
                 machineId,
               );
               const conflictAbs = path.join(hqRoot, conflictRelative);
-              await downloadFile(ctx, relativePath, conflictAbs);
-              appendConflictEntry(hqRoot, {
-                id: buildConflictId(originalRelative, detectedAt),
-                originalPath: originalRelative,
-                conflictPath: conflictRelative,
-                detectedAt,
-                side: "push",
-                machineId,
-                localHash,
-                remoteHash: normalizeEtag(remoteMeta.etag),
-              });
+              if (!isMaterializationPathStillContained(syncRoot, conflictAbs)) {
+                emit({
+                  type: "error",
+                  path: relativePath,
+                  message: "conflict mirror skipped: local parent escaped the sync root",
+                });
+              } else {
+                await downloadFile(ctx, relativePath, conflictAbs);
+                appendConflictEntry(hqRoot, {
+                  id: buildConflictId(originalRelative, detectedAt),
+                  originalPath: originalRelative,
+                  conflictPath: conflictRelative,
+                  detectedAt,
+                  side: "push",
+                  machineId,
+                  localHash,
+                  remoteHash: normalizeEtag(remoteMeta.etag),
+                });
+              }
             } catch (mirrorErr) {
               emit({
                 type: "error",
@@ -1539,20 +1553,28 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
             machineId,
           );
           const conflictAbs = path.join(hqRoot, conflictRelative);
-          await downloadFile(ctx, relativePath, conflictAbs);
-          appendConflictEntry(hqRoot, {
-            id: buildConflictId(originalRelative, detectedAt),
-            originalPath: originalRelative,
-            conflictPath: conflictRelative,
-            detectedAt,
-            side: "push",
-            machineId,
-            localHash,
-            // remoteMeta (if any) predates the racing write that fired the
-            // fence — record what we knew ("" when the key was believed
-            // absent); the mirror file carries the authoritative remote bytes.
-            remoteHash: remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
-          });
+          if (!isMaterializationPathStillContained(syncRoot, conflictAbs)) {
+            emit({
+              type: "error",
+              path: relativePath,
+              message: "conflict mirror skipped: local parent escaped the sync root",
+            });
+          } else {
+            await downloadFile(ctx, relativePath, conflictAbs);
+            appendConflictEntry(hqRoot, {
+              id: buildConflictId(originalRelative, detectedAt),
+              originalPath: originalRelative,
+              conflictPath: conflictRelative,
+              detectedAt,
+              side: "push",
+              machineId,
+              localHash,
+              // remoteMeta (if any) predates the racing write that fired the
+              // fence — record what we knew ("" when the key was believed
+              // absent); the mirror file carries the authoritative remote bytes.
+              remoteHash: remoteMeta ? normalizeEtag(remoteMeta.etag) : "",
+            });
+          }
         } catch (mirrorErr) {
           emit({
             type: "error",
@@ -2082,6 +2104,11 @@ function isWithin(parent: string, child: string): boolean {
   return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
+function isPathWithin(parent: string, child: string): boolean {
+  const rel = path.relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
 function realpathSafe(p: string): string {
   try {
     return fs.realpathSync.native(p);
@@ -2090,6 +2117,48 @@ function realpathSafe(p: string): string {
   }
 }
 
+function deepestExistingAncestor(start: string): string | null {
+  let current = start;
+  for (;;) {
+    try {
+      fs.lstatSync(current);
+      return current;
+    } catch (err: unknown) {
+      const code =
+        err && typeof err === "object" && "code" in err
+          ? (err as { code?: string }).code
+          : undefined;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return null;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function isMaterializationPathStillContained(root: string, localPath: string): boolean {
+  const resolvedRoot = path.resolve(root);
+  const resolvedLocal = path.resolve(localPath);
+  if (!isPathWithin(resolvedRoot, resolvedLocal)) return false;
+
+  let realRoot: string;
+  try {
+    realRoot = fs.realpathSync.native(resolvedRoot);
+  } catch {
+    return false;
+  }
+
+  const existingAncestor = deepestExistingAncestor(path.dirname(resolvedLocal));
+  if (existingAncestor === null) return false;
+  try {
+    const realAncestor = fs.realpathSync.native(existingAncestor);
+    return isPathWithin(realRoot, realAncestor);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Containment check tailored for symlinks. Canonicalizes the link's
  * PARENT DIR (which is a real dir, not the link), then compares the