@indigoai-us/hq-cloud 5.32.0 → 5.34.0

package/src/bin/sync-runner.ts

@@ -89,6 +89,7 @@ import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
 import { collectAndSendTelemetry } from "../telemetry.js";
 import { describeError } from "../lib/describe-error.js";
+import { getOrCreateMachineId } from "../lib/machine-id.js";
 import {
   TreeWatcher,
   WatchPushDriver,
@@ -258,6 +259,15 @@ export type RunnerEvent =
        */
       filesTombstoned: number;
       filesRefusedStale: number;
+      /**
+       * Paths corresponding to `filesRefusedStale`, capped at 50 (mirrors
+       * `newFiles` cap). Surfaced on the `complete` event so operators
+       * can triage the recurring `filesRefusedStale: 205` signal that
+       * the 5.33.0 deep-test flagged as untriageable — the count alone
+       * is impossible to investigate after the per-file
+       * `delete-refused-stale-etag` events scroll off.
+       */
+      filesRefusedStalePaths: string[];
       filesExcludedByPolicy: number;
     } & SyncResult)
   | {
@@ -593,24 +603,17 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
 async function defaultCollectTelemetry(
   client: VaultClientSurface,
   clientIsStub: boolean,
+  hqRoot: string,
 ): Promise<void> {
   if (clientIsStub) return;
   try {
-    // machineId: prefer ~/.hq/menubar.json (set by the menubar app on first
-    // launch). When absent — e.g. fresh CLI-only install — fall back to a
-    // value that makes the row identifiable as "unattributed" rather than
-    // crashing or spoofing another machine's id.
-    const menubarPath = path.join(os.homedir(), ".hq", "menubar.json");
-    let machineId = "unknown";
-    try {
-      const raw = await fs.promises.readFile(menubarPath, "utf-8");
-      const parsed = JSON.parse(raw) as { machineId?: unknown };
-      if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
-        machineId = parsed.machineId;
-      }
-    } catch {
-      // No menubar.json — proceed with "unknown".
-    }
+    // machineId: hq-cloud owns provisioning via `<hqRoot>/.hq/machine-id`
+    // (see `src/lib/machine-id.ts`). The resolver migrates forward from
+    // any legacy `~/.hq/menubar.json` value on first call, then becomes
+    // self-sufficient. On a clean Linux outpost (no menubar app), a fresh
+    // UUID is generated + persisted, so this row is attributable rather
+    // than collapsing onto the legacy `"unknown"` sentinel.
+    const machineId = getOrCreateMachineId(hqRoot);
 
     // installerVersion: callers (the Tauri menubar) set this when spawning
     // the runner so the historical `installerVersion` dimension on
@@ -954,6 +957,7 @@ export async function runRunner(
         filesDeleted: 0,
         filesTombstoned: 0,
         filesRefusedStale: 0,
+        filesRefusedStalePaths: [],
         filesExcludedByPolicy: 0,
         conflictPaths: [],
         aborted: false,
@@ -967,6 +971,8 @@ export async function runRunner(
         aborted: false,
         newFiles: [],
         newFilesCount: 0,
+        filesExcludedByPolicy: 0,
+        filesTombstoned: 0,
       };
 
       // Push first so a subsequent pull doesn't overwrite files we were about
@@ -1094,13 +1100,24 @@ export async function runRunner(
         });
       }
 
-      // Concat push + pull conflict paths into a single per-company list.
-      // Both arrays are always present (defaulted to []) so consumers can
-      // treat `conflictPaths` as authoritative without a falsy check.
-      const mergedConflictPaths = [
-        ...pullResult.conflictPaths,
-        ...pushResult.conflictPaths,
-      ];
+      // Concat push + pull conflict paths into a single per-company list,
+      // then dedupe — a key that legitimately conflicts on both halves of
+      // a bidirectional run (e.g. `.hq/install-manifest.json` round-trip
+      // before Fix #1) appears twice in the concat but represents a single
+      // logical conflict for the operator. Bug #3 in the 5.33.0 deep-test:
+      // every round produced `conflictPaths: [X, X]` and `conflicts: 2`,
+      // double-counting the conflict in every metric downstream. The push
+      // and pull halves each emit a `conflict` event in their own direction
+      // (preserved on the event stream for tracing); only the merged
+      // result list is collapsed. Stable first-seen order is preserved so
+      // consumers can rely on the pull entry coming before its push twin.
+      const seenConflictPaths = new Set<string>();
+      const mergedConflictPaths: string[] = [];
+      for (const p of [...pullResult.conflictPaths, ...pushResult.conflictPaths]) {
+        if (seenConflictPaths.has(p)) continue;
+        seenConflictPaths.add(p);
+        mergedConflictPaths.push(p);
+      }
       const aborted = pullResult.aborted || pushResult.aborted;
 
       // Overwrite the progress-derived counts with the authoritative numbers
@@ -1131,9 +1148,28 @@ export async function runRunner(
         // from the legacy-engine `None` and useful when the UI wants to
         // distinguish "engine ran, nothing tombstoned" from "engine
         // didn't report".
-        filesTombstoned: pushResult.filesTombstoned,
+        // Tombstones now flow on both legs:
+        //   - push side: `ShareResult.filesTombstoned` (remote was already
+        //     404 at HEAD time, journal entry dropped).
+        //   - pull side: `SyncResult.filesTombstoned` (Bug #9 — journal-
+        //     known key missing from remote LIST, applied as local delete).
+        // Sum them so the menubar's `SyncCompleteEvent` reflects the total
+        // delete-propagation activity for that company across the run.
+        filesTombstoned: pushResult.filesTombstoned + pullResult.filesTombstoned,
         filesRefusedStale: pushResult.filesRefusedStale,
-        filesExcludedByPolicy: pushResult.filesExcludedByPolicy,
+        // Bonus diagnostic: surface the paths so operators can triage the
+        // recurring `filesRefusedStale: N` signal — the count alone was
+        // untriageable per the 5.33.0 deep-test report's "205 issue".
+        // Pre-capped at 50 by share() itself.
+        filesRefusedStalePaths: pushResult.filesRefusedStalePaths,
+        // Pull side now reports an `filesExcludedByPolicy` too (Bug #2 —
+        // ephemeral conflict-mirror refusals in the pull walker). Sum
+        // both legs so the `complete` event reports total excluded across
+        // the full bidirectional pass; pre-fix the pull half silently
+        // pushed legacy `.conflict-*` litter into clean trees with the
+        // same counter showing 0.
+        filesExcludedByPolicy:
+          pushResult.filesExcludedByPolicy + pullResult.filesExcludedByPolicy,
         // Sourced from the merged path list so push-side conflicts are
         // counted too — `ShareResult` doesn't expose a numeric counter,
         // and using `pullResult.conflicts` alone silently dropped any
@@ -1180,6 +1216,7 @@ export async function runRunner(
         // throw.
         filesTombstoned: 0,
         filesRefusedStale: 0,
+        filesRefusedStalePaths: [],
         filesExcludedByPolicy: 0,
         conflicts: 0,
         conflictPaths: [],
@@ -1245,7 +1282,7 @@ export async function runRunner(
   // which naturally bounds the outer wait.
   const telemetryFn =
     deps.collectTelemetry ??
-    (() => defaultCollectTelemetry(client, deps.createVaultClient !== undefined));
+    (() => defaultCollectTelemetry(client, deps.createVaultClient !== undefined, parsed.hqRoot));
   await telemetryFn().catch(() => undefined);
 
   emit({

package/src/cli/share.test.ts

@@ -378,6 +378,95 @@ describe("share", () => {
     });
   });
 
+  it("first-time-upload-with-cloud-collision: emits conflict + writes mirror under --on-conflict keep (Bug #7)", async () => {
+    // Bug #7 (data-loss class) from the 5.33.0 deep test: when a file has
+    // NO prior journal entry (fresh upload from this machine) but the
+    // remote already has a different object at that key (a peer pushed
+    // first), the previous detector required \`!!journalEntry\` for BOTH
+    // localChanged and remoteChanged, so the whole \`localChanged &&
+    // remoteChanged\` predicate evaluated false. Push fell through to
+    // an unconditional PUT, silently overwriting the peer's content
+    // without recording a conflict event or writing a mirror.
+    //
+    // The verification report's V7 isolated the mechanism: the bug is
+    // independent of \`--on-conflict\` mode — the conflict-detection
+    // branch is keyed on "do I have a prior journal entry?", not on the
+    // policy flag. \`s13-conflict.txt\` (had a journal entry) correctly
+    // aborted under --on-conflict abort; \`v7b-fresh-collision.txt\`
+    // (no journal entry) was never even reported.
+    //
+    // Fix: even on first-time upload, if HEAD shows remote exists and
+    // its content (etag) differs from what we'd put, emit a conflict.
+    // Under keep, the existing pull-side mirror routine downloads the
+    // remote bytes to \`<orig>.conflict-<ts>-<short>\` so both versions
+    // survive on disk; under abort, the company aborts before PUT.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "v7b-fresh.txt");
+    fs.writeFileSync(testFile, "macos-fresh-collision-content");
+
+    // Remote exists with a different etag — and there is NO journal
+    // entry for this path (this is the first push from this machine).
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"remote-version-etag"',
+      size: 40,
+    });
+
+    // No journal file written — first-time upload contract.
+    const events: unknown[] = [];
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "keep",
+      onEvent: (e) => events.push(e),
+    });
+
+    expect(result.conflictPaths).toEqual(["v7b-fresh.txt"]);
+    // Under keep, local stays as-is (no upload) and the mirror records
+    // the remote bytes so neither version is lost.
+    expect(result.filesUploaded).toBe(0);
+    const conflicts = events.filter(
+      (e): e is { type: "conflict"; path: string } =>
+        typeof e === "object" && e !== null && (e as { type?: string }).type === "conflict",
+    );
+    expect(conflicts).toHaveLength(1);
+    expect(conflicts[0].path).toBe("v7b-fresh.txt");
+    // Local file unmodified — it must still contain the local content.
+    expect(fs.readFileSync(testFile, "utf-8")).toBe("macos-fresh-collision-content");
+  });
+
+  it("first-time-upload-with-cloud-collision: aborts company under --on-conflict abort (Bug #7)", async () => {
+    // Symmetric to the keep case: when --on-conflict abort is passed, a
+    // first-time-upload-with-cloud-collision must abort the share leg
+    // before the PUT (preserving remote intact) and surface
+    // \`aborted: true\` + \`conflicts: 1\` in the result.
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "v7b-abort.txt");
+    fs.writeFileSync(testFile, "local-version");
+
+    vi.mocked(headRemoteFile).mockResolvedValueOnce({
+      lastModified: new Date(),
+      etag: '"different-remote"',
+      size: 99,
+    });
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onConflict: "abort",
+    });
+
+    expect(result.aborted).toBe(true);
+    expect(result.conflictPaths).toEqual(["v7b-abort.txt"]);
+    expect(result.filesUploaded).toBe(0);
+  });
+
   it("uploads (no conflict) when only the local side changed since last sync", async () => {
     // Regression for hq-cloud#<conflict-detection>: a local edit to a file
     // that exists on S3 used to trigger a push conflict because the
@@ -2454,6 +2543,23 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["foo.conflict-2026-05-19T17-05-56Z-deadbeef.md", true],
     // Non-markdown extensions also valid (sh scripts, ts files, etc.).
     ["foo.sh.conflict-2026-05-19T17-05-56Z-abc123.sh", true],
+    // ── extensionless originals (regression: `path.extname('.gitignore')`
+    //    returns '' in Node, so `buildConflictPath` produces no trailing
+    //    `.<ext>` segment for hidden-but-extensionless files).
+    [".gitignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".hqignore.conflict-2026-05-23T19-51-38Z-4dff71", true],
+    [".agents/skills.conflict-2026-05-19T17-07-01Z-0a513b", true],
+    // ── legacy "unknown" machine token (regression: hosts without
+    //    `~/.hq/menubar.json` pre-Fix-3 fell through to the literal string
+    //    `"unknown"`, which `[a-f0-9]+` refused. Producer side is closed in
+    //    `../lib/machine-id.ts`, but the regex still must filter the
+    //    already-on-disk legacy files so the next push removes them).
+    [".gitignore.conflict-2026-05-15T15-10-35Z-unknown", true],
+    [".agents/skills.conflict-2026-05-15T15-10-35Z-unknown", true],
+    ["notes.md.conflict-2026-05-15T15-10-35Z-unknown.md", true],
+    [".hq/install-manifest.json.conflict-2026-05-15T15-11-58Z-unknown.json", true],
+    // Multi-dot extension (e.g., archive tarballs that conflicted).
+    ["dump.conflict-2026-05-13T19-40-40Z-abc.tar.gz", true],
   ])("matches conflict mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });
@@ -2467,17 +2573,20 @@ describe("isEphemeralPath (conflict-mirror pattern contract)", () => {
     ["conflict-resolution.md", false],
     ["my-conflict.md", false],
     ["foo.conflict-handler.md", false],
-    // Date-shaped but missing the trailing dot + extension (real conflicts
-    // always carry a file extension; the trailing `\.` in the pattern is the
-    // safety against bare-substring false positives).
-    ["foo.conflict-2026-05-13T19-40-40Z-abc", false],
-    // Wrong-case or non-hex machine hash.
+    // Wrong-case or non-hex/non-"unknown" machine hash.
     ["foo.conflict-2026-05-13T19-40-40Z-ZZZZZZ.md", false],
     // Wrong timestamp format (real conflicts use UTC ISO with Z suffix).
     ["foo.conflict-2026-05-13-abc123.md", false],
-    // Missing leading dot before "conflict" (this protects against legitimate
+    // Missing leading dot before "conflict" (protects against legitimate
     // files that happen to contain the word "conflict" mid-name).
     ["fooconflict-2026-05-13T19-40-40Z-abc.md", false],
+    // Extra trailing segments after the machine hash — the `$` anchor +
+    // `[^/]*` ext class ensure a conflict marker can't appear mid-path.
+    ["foo.conflict-2026-05-13T19-40-40Z-abc/extra/path", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-abc-then-more-text", false],
+    // Bare "unknown"-like tokens that aren't the literal sentinel.
+    ["foo.conflict-2026-05-13T19-40-40Z-unknowing.md", false],
+    ["foo.conflict-2026-05-13T19-40-40Z-UNKNOWN.md", false],
   ])("rejects non-mirror: %s", (p, expected) => {
     expect(isEphemeralPath(p)).toBe(expected);
   });

package/src/cli/share.ts

@@ -9,7 +9,8 @@ import * as fs from "fs";
 import * as path from "path";
 import type { EntityContext, VaultServiceConfig, SyncJournal } from "../types.js";
 import { resolveEntityContext, isExpiringSoon, refreshEntityContext } from "../context.js";
-import { uploadFile, uploadSymlink, headRemoteFile, deleteRemoteFile } from "../s3.js";
+import { uploadFile, uploadSymlink, headRemoteFile, deleteRemoteFile, downloadFile } from "../s3.js";
+import * as crypto from "crypto";
 import type { UploadAuthor } from "../s3.js";
 import {
   readJournal,
@@ -28,12 +29,21 @@ import {
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
 import type { SyncProgressEvent } from "./sync.js";
+import {
+  buildConflictId,
+  buildConflictPath,
+  readShortMachineId,
+} from "../lib/conflict-file.js";
+import { appendConflictEntry } from "../lib/conflict-index.js";
 
 /**
  * Local-only ephemeral artifacts: conflict-mirror files written by the pull
  * leg whenever a 3-way merge keeps local AND wants to preserve the remote
- * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>.<ext>`
- * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`).
+ * version for inspection. Format: `<orig>.conflict-<ISO-utc>-<machineHash>[.ext]`
+ * (e.g. `.claude/CLAUDE.md.conflict-2026-05-13T19-40-40Z-e5797a.md`,
+ * or `.gitignore.conflict-2026-05-13T19-40-40Z-e5797a` — extensionless
+ * originals produce no trailing dot, see `buildConflictPath` in
+ * `../lib/conflict-file.ts`).
  *
  * These files MUST never round-trip to S3 — they're local-only safety backups
  * the user reviews and deletes once the merge is resolved. Pre-fix, the push
@@ -42,21 +52,46 @@ import type { SyncProgressEvent } from "./sync.js";
  * deleted them locally (because pull-confirmation had stamped them as
  * `direction: "down"`). Net effect: a permanent litter ratchet on remote.
  *
+ * Two known producer-shapes the regex must accommodate (both observed on
+ * affected user trees prior to this fix):
+ *
+ *   1. **`unknown` machine token.** Pre-`<hqRoot>/.hq/machine-id`
+ *      provisioning (see `../lib/machine-id.ts`), hosts without
+ *      `~/.hq/menubar.json` — every Linux HQ Pro Outpost, every fresh CLI
+ *      install — fell through to the literal string `"unknown"` from the
+ *      old `readShortMachineId()` fallback. The letters `k`, `n`, `o`, `w`
+ *      live outside `[a-f]`, so the pre-fix `[a-f0-9]+` class refused those
+ *      filenames. They round-tripped to S3 as ordinary files (which IS the
+ *      "permanent litter ratchet" this module's contract was supposed to
+ *      prevent). The new machine-id provisioning closes the producer side,
+ *      but we still accept `unknown` here so legacy files already on disk
+ *      are filtered out by the next push.
+ *
+ *   2. **Extensionless originals.** `path.extname('.gitignore')` returns
+ *      `''` in Node, so `buildConflictPath` produces no trailing `.<ext>`
+ *      segment for hidden-but-extensionless files like `.gitignore`,
+ *      `.hqignore`, or any `.agents/skills`-style entry. The pre-fix `\.`
+ *      tail was mandatory, so those names slipped through.
+ *
  * Wire-points: (1) push walker — `collectFiles` / `walkDir` skip these so
  * they never upload; (2) `computeDeletePlan` — skip these so an already-
  * journaled mirror that's been deleted locally doesn't get included in the
  * regular delete plan (the dedicated reconcile path handles existing litter).
  */
-const EPHEMERAL_PATH_PATTERN =
-  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-[a-f0-9]+\./;
+export const EPHEMERAL_PATH_PATTERN =
+  /\.conflict-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}Z-(?:[a-f0-9]+|unknown)(?:\.[^/]*)?$/;
 
 /**
  * Cheap pure check — pass the relative key OR a basename; either works. Used
  * in both the file walker (basename matching) and the delete-plan walker
- * (relative-key matching). The regex matches anywhere in the string, which is
- * fine: the `.conflict-<ISO>-<hash>.` token is unambiguous.
+ * (relative-key matching), and also by the pull walker in sync.ts to refuse
+ * downloading legacy conflict-mirror files that still live in cloud staging
+ * (Bug #2 in the 5.33.0 deep-test report — push-side filtered them since
+ * 5.33.0 but pull-side downloaded them freely until this export). The regex
+ * matches anywhere in the string, which is fine: the
+ * `.conflict-<ISO>-<hash>.` token is unambiguous.
  */
-function isEphemeralPath(p: string): boolean {
+export function isEphemeralPath(p: string): boolean {
   return EPHEMERAL_PATH_PATTERN.test(p);
 }
 
@@ -416,6 +451,16 @@ export interface ShareResult {
    * `currency-gated`.
    */
   filesRefusedStale: number;
+  /**
+   * Paths corresponding to `filesRefusedStale`, capped at 50 to keep the
+   * event payload bounded (mirrors `newFiles` capping). Surfaces *which*
+   * paths were refused so operators can triage the recurring
+   * \`filesRefusedStale: 205\` signal flagged in the 5.33.0 deep-test —
+   * the count alone is impossible to investigate because the per-file
+   * \`delete-refused-stale-etag\` events vanish from the event stream
+   * once the runner has folded them into the totals.
+   */
+  filesRefusedStalePaths: string[];
   /**
    * Number of paths blocked by `PERSONAL_VAULT_DEFAULT_EXCLUSIONS` during this
    * run (push leg, personalMode=true). Includes both files that would have
@@ -544,6 +589,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   // propagateDeletes=false path.
   let filesTombstoned = 0;
   let filesRefusedStale = 0;
+  // Capped at 50 to bound event payload size — `newFiles` uses the same cap.
+  const REFUSED_STALE_PATH_CAP = 50;
+  const filesRefusedStalePaths: string[] = [];
   const conflictPaths: string[] = [];
 
   // Collect all files to share
@@ -668,13 +716,58 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // the current remote ETag against the one captured at last sync; when
     // missing (legacy entries), we fall back to the same `lastModified >
     // syncedAt` heuristic the pull side uses.
+    //
+    // Bug #7 (data-loss class — see workspace/reports/hq-cloud-5.33.0-
+    // deep-test.md): for a path with NO prior journal entry (first push
+    // from this machine), the localChanged/remoteChanged predicates above
+    // both evaluate FALSE (their guards require `!!journalEntry`). Push
+    // fell through to an unconditional PUT, silently clobbering any
+    // peer's content already at that key. The verification report's V7
+    // isolated this — the bug is independent of \`--on-conflict\` mode;
+    // it's keyed on "do I have a prior journal entry?" not on the flag.
+    //
+    // Fresh-collision branch: when remoteMeta exists and there's no
+    // journal entry, hash the local body (MD5 for parity with S3's
+    // single-part etag) and compare. Match → no conflict, silently skip
+    // the PUT (the bytes are already there). Mismatch → treat as a
+    // conflict in the same shared branch below.
     const remoteMeta = await headRemoteFile(ctx, relativePath);
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
       const localChanged = !!journalEntry && journalEntry.hash !== localHash;
       const remoteChanged = !!journalEntry && hasRemoteChanged(remoteMeta, journalEntry);
 
-      if (localChanged && remoteChanged) {
+      let isFreshCollision = false;
+      if (!journalEntry && item.kind === "file") {
+        // Single-part S3 PUT etag is MD5 of the body. Multipart uploads
+        // produce \`<md5>-<partCount>\`; we treat any non-single-part etag
+        // as ambiguous and DO classify as a conflict (safer for the
+        // first-time path — false positives prompt the operator, false
+        // negatives lose data). 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.
+        const remoteEtagNormalized = normalizeEtag(remoteMeta.etag);
+        const isMultipart = /-\d+$/.test(remoteEtagNormalized);
+        if (!isMultipart) {
+          const localBody = fs.readFileSync(absolutePath);
+          const localMd5 = crypto.createHash("md5").update(localBody).digest("hex");
+          if (localMd5 !== remoteEtagNormalized) {
+            isFreshCollision = true;
+          }
+          // Match → bytes are already there; fall through to upload
+          // path which is idempotent (S3 will overwrite with identical
+          // content + carry our metadata). Cheap, no behavior change.
+        } else {
+          // Multipart object pre-exists with unknown body shape — assume
+          // collision rather than risk a silent overwrite. The operator
+          // can resolve via the standard conflict prompt.
+          isFreshCollision = true;
+        }
+      }
+
+      if ((localChanged && remoteChanged) || isFreshCollision) {
         conflictPaths.push(relativePath);
 
         const resolution = await resolveConflict(
@@ -705,6 +798,10 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
             // ShareResult shape stable for consumers that destructure.
             filesTombstoned,
             filesRefusedStale,
+            // Always present so consumers can destructure without a
+            // defaulting fallback. Empty on the abort path because the
+            // delete-plan execution loop is short-circuited.
+            filesRefusedStalePaths,
             // Exclusions are computed during the upload walk which has
             // already completed by the time we hit a per-file conflict-
             // abort, so the count is meaningful here. No event emit on
@@ -716,6 +813,45 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
           };
         }
         if (resolution === "keep" || resolution === "skip") {
+          // Bug #7 mirror branch: when the resolution is keep/skip on a
+          // FRESH collision (no prior journal entry), download the
+          // remote bytes to \`<orig>.conflict-<ts>-<short>\` so both
+          // versions survive on disk. Mirrors the pull-side mirror-write
+          // routine in sync.ts exactly. Skipped for stale-journal
+          // conflicts (the pre-Bug-#7 codepath) — those already produce
+          // a pull-side mirror on the next sync cycle.
+          if (isFreshCollision) {
+            try {
+              const detectedAt = new Date().toISOString();
+              const machineId = readShortMachineId(hqRoot);
+              const originalRelative = path.relative(hqRoot, absolutePath);
+              const conflictRelative = buildConflictPath(
+                originalRelative,
+                detectedAt,
+                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),
+              });
+            } catch (mirrorErr) {
+              emit({
+                type: "error",
+                path: relativePath,
+                message: `conflict mirror write failed: ${
+                  mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)
+                }`,
+              });
+            }
+          }
           filesSkipped++;
           continue;
         }
@@ -838,6 +974,9 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   for (const refused of deletePlan.refusedStale) {
     if (decommissionedSet && decommissionedSet.has(refused.key)) continue;
     filesRefusedStale++;
+    if (filesRefusedStalePaths.length < REFUSED_STALE_PATH_CAP) {
+      filesRefusedStalePaths.push(refused.key);
+    }
     emit({
       type: "delete-refused-stale-etag",
       path: refused.key,
@@ -877,6 +1016,7 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     filesDeleted,
     filesTombstoned,
     filesRefusedStale,
+    filesRefusedStalePaths,
     filesExcludedByPolicy: excludedSet.size,
     conflictPaths,
     aborted: false,