@indigoai-us/hq-cloud 6.18.87 → 6.18.89

package/dist/cli/share.js

@@ -4,6 +4,7 @@
  * Broadcasts local file(s) to the company's S3 vault bucket.
  * Refuses to overwrite a newer remote version without prompting.
  */
+import { localLinkWarning, rememberLinkWarning, brokenLinkSkipEvent, LinkWarningCollector, LOCAL_LINK_REMEDY } from "../local-link-warning.js";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -29,6 +30,7 @@ import { claimNeverSyncedLocalNotice, formatSecretsNotSyncedLine, isNeverSyncedV
 import { getActiveFullPassDecodeWindow, getActiveFullPassUnitSize, } from "../sync/full-pass-caps.js";
 import { isGeneratedCoreMirrorKey, isPersonalVaultDeletionExcluded, isSessionLogDeletionKey, purgeExcludedPersonalVaultJournalEntries, } from "../personal-vault.js";
 import { pickWinner, resolveConflict, usesVersionAwareWinner } from "./conflict.js";
+import { createHumanSkipLineLog, formatReconcileSkipLine, isUpToDateSkipReason, } from "./reconcile-skip-reason.js";
 import { fetchFileTombstones, } from "./tombstones.js";
 import { compileScopeMatcher, } from "../prefix-coalesce.js";
 import { hasRemoteChanged, isAccessDenied, resolveActiveCompany, resolveTransferConcurrency, resolveUploadByteBudget, readHostLoad, } from "../sync-core.js";
@@ -490,6 +492,32 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat, onto
                 const localHash = hashSymlinkTarget(entry.target);
                 const journalEntry = journalRows(journal).get(relativePath);
                 const portable = portablePushSymlinkTarget(absolutePath, relativePath, entry.target, journalEntry?.wireSymlinkTarget, symlinkContext);
+                // Skip-unchanged runs before the link check: a dangling link already
+                // synced under this exact target is settled state, not a new warning
+                // every pass. A refused target never reaches this gate, as before.
+                if (skipUnchanged && !portable.refused) {
+                    const existing = skipFingerprint(journal, relativePath);
+                    // `!localDiverges`: see the regular-file gate below — a divergent entry
+                    // stores the current LOCAL hash, so hash equality here proves only that
+                    // local has not moved since the pull-side hold, never that it matches remote.
+                    if (existing && existing.hash === localHash && !existing.localDiverges) {
+                        omittedSkips += 1;
+                        continue;
+                    }
+                }
+                const warning = localLinkWarning(symlinkContext?.syncRoot ?? path.dirname(absolutePath), absolutePath, relativePath);
+                // A journaled link whose target string changed is still an upload, even
+                // when the new target does not exist yet. Skipping that retarget drops
+                // the edit and warns on every later pass. A never-synced broken link, a
+                // loop, and an unreadable link stay skips.
+                const uploadMissingRetarget = warning?.reason === "missing_target" &&
+                    !portable.refused &&
+                    journalEntry?.hash !== undefined &&
+                    journalEntry.hash !== localHash;
+                if (warning && !uploadMissingRetarget && (!portable.refused || warning.reason === "loop")) {
+                    items.push({ action: "skip-local-link", absolutePath, relativePath, warning });
+                    continue;
+                }
                 if (portable.refused) {
                     items.push({
                         action: "refuse-unsafe-symlink",
@@ -500,16 +528,6 @@ function computePushPlan(filesToShare, journal, skipUnchanged, onHeartbeat, onto
                     });
                     continue;
                 }
-                if (skipUnchanged) {
-                    const existing = skipFingerprint(journal, relativePath);
-                    // `!localDiverges`: see the regular-file gate below — a divergent entry
-                    // stores the current LOCAL hash, so hash equality here proves only that
-                    // local has not moved since the pull-side hold, never that it matches remote.
-                    if (existing && existing.hash === localHash && !existing.localDiverges) {
-                        omittedSkips += 1;
-                        continue;
-                    }
-                }
                 items.push({
                     action: "upload",
                     kind: "symlink",
@@ -1087,6 +1105,14 @@ export async function share(options) {
 }
 async function shareOnce(options) {
     const run = await createPushRunContext(options);
+    try {
+        return await runShareOnce(options, run);
+    }
+    finally {
+        run.humanSkipLines?.flush();
+    }
+}
+async function runShareOnce(options, run) {
     const counters = createShareCounters();
     const filesRefusedStalePaths = [];
     const conflictPaths = [];
@@ -1149,7 +1175,9 @@ async function shareOnce(options) {
     // A reconcile cursor is an all-or-nothing boundary for this bounded apply
     // slice. Upload and delete errors are intentionally reported per-path so an
     // ordinary runner can continue, but none of those retryable outcomes may
-    // move the cursor beyond the failed mutation.
+    // move the cursor beyond the failed mutation. Broken links are deliberate
+    // skips: their current slice is settled without claiming a file transfer,
+    // and a repaired link remains eligible in a later discovery epoch.
     if (!uploadResult.hadUploadFailure &&
         uploadResult.workerErrors.length === 0 &&
         !pathResults.some((result) => result.status === "refused")) {
@@ -1220,7 +1248,9 @@ async function createPushRunContext(options) {
     // load average and self-trip the busy step-down to 32.
     const hostLoadAtStart = readHostLoad();
     const propagateDeletePolicy = options.propagateDeletePolicy ?? "owned-only";
-    const baseEmit = options.onEvent ?? defaultConsoleLogger;
+    const humanSkipLines = options.onEvent ? undefined : createHumanSkipLineLog();
+    const baseEmit = options.onEvent
+        ?? ((event) => defaultConsoleLogger(event, humanSkipLines));
     if (vaultConfig && entityContext) {
         throw new Error("share() requires exactly one of `vaultConfig` or `entityContext`, not both. " +
             "Pass `vaultConfig` to vend credentials internally, or `entityContext` to use pre-vended ones.");
@@ -1306,6 +1336,7 @@ async function createPushRunContext(options) {
             : ctx.slug,
         phase: "push",
     });
+    const linkWarnings = new LinkWarningCollector();
     const emit = (event) => {
         baseEmit(event);
         recordProgress(event);
@@ -1429,6 +1460,8 @@ async function createPushRunContext(options) {
         personalConnectorSettingsSync,
         symlinkTargetRefusal,
         reportedUnsafeSymlinkPaths: new Set(),
+        linkWarnings,
+        unreadableLinks: 0,
         skillRegistrationFallbacks: 0,
         paths,
         message,
@@ -1440,6 +1473,7 @@ async function createPushRunContext(options) {
         propagateDeletes,
         propagateDeletePolicy,
         emit,
+        humanSkipLines,
         companyRef,
         ctx,
         privateFolderMatcher,
@@ -1532,6 +1566,9 @@ function createShareCounters() {
         filesUploaded: 0,
         bytesUploaded: 0,
         filesSkipped: 0,
+        filesSkippedUpToDate: 0,
+        filesSkippedConflict: 0,
+        filesSkippedBrokenLink: 0,
         filesDeleted: 0,
         filesTombstoned: 0,
         filesRefusedStale: 0,
@@ -2139,6 +2176,14 @@ async function buildSharePlans(run) {
                 run.unreachablePaths.set(namedPath, reason);
             }
         },
+        onUnreadableLink: (key) => {
+            const warning = { path: key, reason: "unreadable_link", remedy: LOCAL_LINK_REMEDY };
+            if (run.linkWarnings.has(warning.path))
+                return;
+            run.unreadableLinks++;
+            if (rememberLinkWarning(run.linkWarnings, warning))
+                run.emit(brokenLinkSkipEvent(warning));
+        },
         onLinkedSubtree: (rel) => run.linkedSubtreeSet.add(rel),
         onHeartbeat: run.options.onHeartbeat,
         cooperativeCheckpoint: run.options.cooperativeCheckpoint,
@@ -2249,6 +2294,10 @@ async function buildSharePlans(run) {
     const deletePlan = run.propagateDeletes === true
         ? await computeDeletePlan(run.journal, run.syncRoot, deleteScopeRoots, run.shouldSync, run.propagateDeletePolicy, run.ctx, run.options.personalMode !== true, run.skipSecretPaths, run.quarantinedPaths)
         : { toDelete: [], toTombstone: [], refusedStale: [] };
+    for (const warning of deletePlan.brokenLinkSkipped ?? []) {
+        if (rememberLinkWarning(run.linkWarnings, warning))
+            run.emit(brokenLinkSkipEvent(warning));
+    }
     const decommissionPlan = !run.scopedJournal && (run.options.decommissionPrefixes ?? []).length > 0
         ? computeDecommissionPlan(run.journal, run.options.decommissionPrefixes ?? [], run.propagateDeletePolicy, new Set([...deletePlan.toDelete.map((item) => item.key), ...deletePlan.toTombstone]), run.skipSecretPaths)
         : [];
@@ -2456,6 +2505,8 @@ function debugPlanLimit(fields) {
 }
 async function executeUploads(run, pushPlan, counters, conflictPaths) {
     counters.filesSkipped += pushPlan.preplannedFilesSkipped;
+    counters.filesSkippedUpToDate += pushPlan.preplannedFilesSkipped;
+    run.shareCounters = counters;
     const TRANSFER_CONCURRENCY = resolveTransferConcurrency(run.hostLoadAtStart, run.options.transferPriority ?? "chore");
     let conflictPromptChain = Promise.resolve();
     const resolveConflictSerialized = (info) => {
@@ -2645,12 +2696,27 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 emitServerOwnedRefusal(run, item.relativePath);
             }
         }
+        else if (item.action === "skip-local-link") {
+            counters.filesSkippedBrokenLink++;
+            if (rememberLinkWarning(run.linkWarnings, item.warning)) {
+                run.emit(brokenLinkSkipEvent(item.warning));
+            }
+        }
         else if (item.action === "refuse-unsafe-symlink") {
+            // One event per refused link: skip-unsafe-symlink-target carries the
+            // remedy, so a broken outside-root link is recorded in linkWarnings but
+            // never also emitted as skip-broken-link (which double-counted progress).
+            const warning = localLinkWarning(run.syncRoot, item.absolutePath, item.relativePath);
+            if (warning) {
+                counters.filesSkippedBrokenLink++;
+                rememberLinkWarning(run.linkWarnings, warning);
+            }
             run.emit({
                 type: "skip-unsafe-symlink-target",
                 path: item.relativePath,
                 classification: item.classification,
                 shape: item.shape,
+                ...(warning ? { remedy: warning.remedy } : {}),
             });
         }
         else if (item.action === "skip-size-limit") {
@@ -2678,6 +2744,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     size: item.restamp.size,
                 });
             }
+            emitPushSkip(run, item.relativePath, "already_up_to_date");
         }
         counters.filesSkipped++;
     };
@@ -2710,6 +2777,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
             });
             if (refreshed === null) {
                 counters.filesSkipped++;
+                emitPushSkip(run, relativePath, "vanished_before_upload");
                 return null;
             }
             if (refreshed.action !== "upload") {
@@ -2726,6 +2794,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
             // cannot monopolise a worker; the next sync pass will try it again.
             if (replanAttempts >= 3) {
                 counters.filesSkipped++;
+                emitPushSkip(run, relativePath, "retry_budget_exhausted");
                 return;
             }
             await processUploadItem(refreshed, replanAttempts + 1, samePathHold);
@@ -2876,8 +2945,11 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
             !entityIsFreshForCreate(fs.readFileSync(absolutePath, "utf8"), Date.now());
         if ((cloudWinsEntity && !remoteMeta && journalEntry) || staleEntityCreate) {
             counters.filesSkipped++;
-            if (journalEntry && journalEntry.hash === localHash)
+            if (journalEntry && journalEntry.hash === localHash) {
+                emitPushSkip(run, relativePath, "vault_deleted_local_unchanged");
                 return;
+            }
+            counters.filesSkippedConflict++;
             conflictPaths.push(relativePath);
             if (!isMaterializationPathStillContained(run.syncRoot, item.absolutePath)) {
                 run.emit({ type: "conflict", path: relativePath, direction: "push", resolution: "skip" });
@@ -2910,6 +2982,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 // explicit `overwrite` — consent given with the deletion in view — falls
                 // through to the create below.
                 counters.filesSkipped++;
+                counters.filesSkippedConflict++;
+                emitPushSkip(run, relativePath, "remote_deleted_not_recreated");
                 return;
             }
         }
@@ -2932,7 +3006,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     preserveSyncedAt: true,
                 });
                 checkpointShareJournal(run);
-                run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+                emitPushSkip(run, relativePath, "already_up_to_date");
                 counters.filesSkipped++;
                 return;
             }
@@ -2949,6 +3023,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 conflictPaths.push(relativePath);
                 run.emit({ type: "conflict", path: relativePath, direction: "push", resolution: "skip" });
                 counters.filesSkipped++;
+                counters.filesSkippedConflict++;
                 return;
             }
             // Every path below that needs the remote BODY — the no-row equality
@@ -2983,6 +3058,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         wireSymlinkTarget: remoteTarget,
                     });
                     flushShareJournal(run);
+                    emitPushSkip(run, relativePath, "already_up_to_date");
                     counters.filesSkipped++;
                     return;
                 }
@@ -3058,7 +3134,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     settleLandedReconcile(run, relativePath, outcome);
                 }
                 checkpointShareJournal(run);
-                run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+                emitPushSkip(run, relativePath, "already_landed");
                 counters.filesSkipped++;
                 return;
             }
@@ -3086,6 +3162,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     // upload drops nothing. Leave the journal alone; the next pass retries.
                     boardProbe.discard();
                     counters.filesSkipped++;
+                    emitPushSkip(run, relativePath, "remote_body_unreadable");
                     return;
                 }
                 const outcome = mergeAppendOnlyPushConflict(run, item, boardProbe, normalizeEtag(remoteMeta.etag), mergeBoardJson, replaceIfUnchanged);
@@ -3094,8 +3171,10 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     fenceOnObservedRemote = true;
                 }
                 else if (outcome !== "not-mergeable") {
-                    if (outcome === "write-failed")
+                    if (outcome === "write-failed") {
+                        // The merge already emitted the error. A second skip line repeats it.
                         hadUploadFailure = true;
+                    }
                     counters.filesSkipped++;
                     return;
                 }
@@ -3111,6 +3190,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     run.emit({ type: "conflict", path: relativePath, direction: "push", resolution: "keep" });
                     await adoptRemoteOnPush(run, item, normalizeEtag(remoteMeta.etag), undefined);
                     counters.filesSkipped++;
+                    counters.filesSkippedConflict++;
                     return;
                 }
                 // Version-aware winner (strategy unset or `keep`): fetch the remote
@@ -3149,8 +3229,10 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         if (conflictIndex >= 0)
                             conflictPaths.splice(conflictIndex, 1);
                         if (outcome !== "publish-local") {
-                            if (outcome === "write-failed")
+                            if (outcome === "write-failed") {
+                                // The merge already emitted the error. A second skip line repeats it.
                                 hadUploadFailure = true;
+                            }
                             counters.filesSkipped++;
                             return;
                         }
@@ -3192,6 +3274,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                             // so the conflict is retried next pass.
                             winnerProbe?.discard();
                             counters.filesSkipped++;
+                            counters.filesSkippedConflict++;
+                            emitPushSkip(run, relativePath, "held_for_next_pass");
                             return;
                         }
                         recordPushConflict(run, item, {
@@ -3228,12 +3312,14 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         // tree, never as a sibling twin.
                         await adoptRemoteOnPush(run, item, normalizeEtag(remoteMeta.etag), decision, winnerProbe);
                         counters.filesSkipped++;
+                        counters.filesSkippedConflict++;
                         return;
                     }
                 }
                 if (resolution === "skip") {
                     // Leave both sides alone; no sibling mirror is written any more.
                     counters.filesSkipped++;
+                    counters.filesSkippedConflict++;
                     return;
                 }
                 // `publish-local` on a FRESH two-sided conflict must fence on the etag
@@ -3458,6 +3544,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         : undefined;
                     if (builtOnThisPut) {
                         adoptLandedSamePathUpload(run, item, builtOnThisPut);
+                        if (alreadyCurrent)
+                            emitPushSkip(run, relativePath, "already_up_to_date");
                         return;
                     }
                     // A row on disk at an etag this process has since replaced came from
@@ -3471,6 +3559,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                             journalRows(run.journal).set(relativePath, latestEntry);
                         else
                             journalRows(run.journal).delete(relativePath);
+                        if (alreadyCurrent)
+                            emitPushSkip(run, relativePath, "already_up_to_date");
                         return;
                     }
                 }
@@ -3514,7 +3604,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                     bytes: size,
                 });
                 if (alreadyCurrent) {
-                    run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+                    emitPushSkip(run, relativePath, "already_up_to_date");
                 }
                 else {
                     run.emit({
@@ -3565,6 +3655,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         await adoptRemoteOnPush(run, item, normalizeEtag(latest.etag), undefined);
                     }
                     counters.filesSkipped++;
+                    counters.filesSkippedConflict++;
                     return;
                 }
                 if (usesVersionAwareWinner(run.onConflict)) {
@@ -3601,7 +3692,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                                 preserveSyncedAt: true,
                             });
                             checkpointShareJournal(run);
-                            run.emit({ type: "reconciled", path: relativePath, direction: "push" });
+                            emitPushSkip(run, relativePath, "already_up_to_date");
                             counters.filesSkipped++;
                             return;
                         }
@@ -3616,8 +3707,14 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                             const conflictIndex = conflictPaths.lastIndexOf(relativePath);
                             if (conflictIndex >= 0)
                                 conflictPaths.splice(conflictIndex, 1);
-                            if (outcome === "write-failed")
+                            if (outcome === "write-failed") {
+                                // The merge already emitted the error. A second skip line repeats it.
                                 hadUploadFailure = true;
+                            }
+                            else if (outcome === "publish-local") {
+                                counters.filesSkippedConflict++;
+                                emitPushSkip(run, relativePath, "held_for_next_pass");
+                            }
                             counters.filesSkipped++;
                             return;
                         }
@@ -3638,6 +3735,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                             // newer remote until its body has been safely parked.
                             probe.discard();
                             counters.filesSkipped++;
+                            counters.filesSkippedConflict++;
+                            emitPushSkip(run, relativePath, "held_for_next_pass");
                             return;
                         }
                         recordPushConflict(run, item, {
@@ -3684,6 +3783,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                                 return;
                             if (isPreconditionFailed(retryErr)) {
                                 counters.filesSkipped++;
+                                counters.filesSkippedConflict++;
+                                emitPushSkip(run, relativePath, "held_for_next_pass");
                                 return;
                             }
                             hadUploadFailure = true;
@@ -3709,6 +3810,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                             // both copies and the journal unchanged until the next pass.
                             probe.discard();
                             counters.filesSkipped++;
+                            counters.filesSkippedConflict++;
+                            emitPushSkip(run, relativePath, "held_for_next_pass");
                             return;
                         }
                         recordPushConflict(run, item, {
@@ -3724,6 +3827,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                         // Deliberately NOT `type: "error"` (a hold is a benign per-file
                         // skip; the conflict event + index row above already record it).
                         counters.filesSkipped++;
+                        counters.filesSkippedConflict++;
                         return;
                     }
                     await adoptRemoteOnPush(run, item, latest?.etag
@@ -3765,6 +3869,8 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 // non-interactive strategy returns — stays fenced.
                 if (resolution === "publish-local") {
                     counters.filesSkipped++;
+                    counters.filesSkippedConflict++;
+                    emitPushSkip(run, relativePath, "body_changed_during_decision");
                     return;
                 }
                 if (resolution === "overwrite") {
@@ -3799,6 +3905,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 }
                 // `skip` and `diff`: leave both sides for the next pass.
                 counters.filesSkipped++;
+                counters.filesSkippedConflict++;
                 return;
             }
             if (isAccessDenied(err)) {
@@ -3908,6 +4015,7 @@ async function executeUploads(run, pushPlan, counters, conflictPaths) {
                 if (item === null) {
                     queue.shift();
                     counters.filesSkipped++;
+                    emitPushSkip(run, previewItem.relativePath, "vanished_before_upload");
                     skippedSinceCooperativeCheckpoint++;
                     continue;
                 }
@@ -4405,9 +4513,11 @@ function mergeAppendOnlyPushConflict(run, item, probe, remoteEtag, merge = merge
         });
         return "write-failed";
     }
-    if (appended === "changed")
+    if (appended === "changed") {
+        emitPushSkip(run, item.relativePath, "body_changed_during_decision");
         return "local-changed";
-    run.emit({ type: "reconciled", path: item.relativePath, direction: "push" });
+    }
+    emitPushSkip(run, item.relativePath, merged.equals(remoteBody) ? "already_up_to_date" : "merged_with_remote");
     if (!merged.equals(remoteBody))
         return "merged-locally";
     const lstat = fs.lstatSync(item.absolutePath);
@@ -4493,6 +4603,7 @@ async function adoptRemoteOnPush(run, item, remoteHash, decision, probe) {
                 symlinkTargetLinkPath: run.options.personalMode === true
                     ? personalSymlinkTargetLinkPath(item.relativePath)
                     : `companies/${run.ctx.slug}/${item.relativePath}`,
+                syncRoot: run.syncRoot,
             });
         }
         remoteAdopted = true;
@@ -5190,7 +5301,10 @@ function buildShareResult(run, counters, filesRefusedStalePaths, conflictPaths,
     return {
         filesUploaded: counters.filesUploaded,
         bytesUploaded: counters.bytesUploaded,
-        filesSkipped: counters.filesSkipped,
+        linkWarnings: run.linkWarnings.warnings,
+        linkWarningsOmitted: run.linkWarnings.omitted,
+        filesSkipped: counters.filesSkipped + run.unreadableLinks,
+        filesSkippedDetail: skipDetail(counters, run.unreadableLinks),
         filesDeleted: counters.filesDeleted,
         filesTombstoned: counters.filesTombstoned,
         filesRefusedStale: counters.filesRefusedStale,
@@ -5213,11 +5327,24 @@ function buildShareResult(run, counters, filesRefusedStalePaths, conflictPaths,
         aborted,
     };
 }
+function skipDetail(counters, unreadableLinks) {
+    const upToDate = counters.filesSkippedUpToDate;
+    const conflict = counters.filesSkippedConflict;
+    const brokenLink = counters.filesSkippedBrokenLink + unreadableLinks;
+    const other = Math.max(0, counters.filesSkipped + unreadableLinks - upToDate - conflict - brokenLink);
+    return { upToDate, conflict, brokenLink, other };
+}
+function emitPushSkip(run, filePath, reason) {
+    run.emit({ type: "reconciled", path: filePath, direction: "push", reason });
+    if (run.shareCounters && isUpToDateSkipReason(reason)) {
+        run.shareCounters.filesSkippedUpToDate++;
+    }
+}
 /**
  * Default human-readable share output. Preserves the exact format the CLI
  * emitted before `onEvent` was added — tty users see no change.
  */
-function defaultConsoleLogger(event) {
+function defaultConsoleLogger(event, humanSkipLines) {
     if (event.type === "plan") {
         if (event.filesToUpload > 0) {
             console.log(`Plan: ${event.filesToUpload} to upload (${event.bytesToUpload} bytes), ${event.filesToSkip} unchanged`);
@@ -5245,6 +5372,12 @@ function defaultConsoleLogger(event) {
     else if (event.type === "conflict") {
         console.error(`  ⚠ conflict (${event.direction}): ${event.path} — ${event.resolution}`);
     }
+    else if (event.type === "reconciled") {
+        if (humanSkipLines)
+            humanSkipLines.note(event.path, event.reason, event.direction);
+        else
+            console.log(formatReconcileSkipLine(event.path, event.reason, event.direction));
+    }
     else if (event.type === "push-refused-server-owned") {
         const nextStep = event.nextStep === "use-source-ingestion"
             ? "Add the source through its supported integration or ingestion flow, then run hq sync pull."
@@ -5259,6 +5392,9 @@ function defaultConsoleLogger(event) {
             console.warn(`    ... and ${event.count - event.samplePaths.length} more`);
         }
     }
+    else if (event.type === "skip-broken-link") {
+        console.warn(`  ! ${event.path} skipped — ${event.message}`);
+    }
     else if (event.type === "error") {
         console.error(`  ✗ ${event.path} — ${event.message}`);
     }
@@ -5728,6 +5864,8 @@ async function collectFiles(paths, hqRoot, syncRoot, filter, hooks = {}) {
             const target = readlinkOrNull(absolutePath);
             if (target === null) {
                 console.error(`  Warning: ${p} is an unreadable symbolic link, skipping.`);
+                if (hooks.onUnreadableLink)
+                    hooks.onUnreadableLink(relativePath);
                 hooks.onUnreachablePath?.(p, "unreadable-link");
                 continue;
             }
@@ -5829,6 +5967,8 @@ async function walkDir(dir, syncRoot, filter, results, hooks = {}, cooperativeWo
             const target = readlinkOrNull(absolutePath);
             if (target === null) {
                 console.error(`  Warning: ${linkRelative} is an unreadable symbolic link, skipping.`);
+                if (hooks.onUnreadableLink)
+                    hooks.onUnreadableLink(linkRelative);
                 hooks.onUnreachablePath?.(linkRelative, "unreadable-link");
                 continue;
             }
@@ -6253,6 +6393,8 @@ companyScoped = true, skipSecretPaths = false, excludedPaths = new Set()) {
     // of roots; test each row by walking its ancestors, never rows x roots.
     const scopeRootSet = new Set(scopeRoots);
     const everyRowInScope = scopeRootSet.has("");
+    const linkInspectCache = new Map();
+    const brokenLinkPaths = new Set();
     for (const [relativeKey, entry] of journalRows(journal).entries()) {
         if (excludedPaths.has(relativeKey))
             continue;
@@ -6302,20 +6444,43 @@ companyScoped = true, skipSecretPaths = false, excludedPaths = new Set()) {
         inScopeJournalEntries++;
         const localPath = localPathForVaultKey(syncRoot, relativeKey);
         let presentLocally = true;
+        let lstatError;
         try {
             fs.lstatSync(localPath);
         }
         catch (err) {
-            if (err &&
-                typeof err === "object" &&
-                "code" in err &&
-                err.code === "ENOENT") {
+            const code = err && typeof err === "object" && "code" in err
+                ? err.code
+                : undefined;
+            // ELOOP and ENOTDIR come from a directory link above the key (a loop,
+            // or a link that no longer resolves to a directory). They are settled
+            // below only when that link is broken; otherwise they still throw.
+            if (code === "ENOENT" || code === "ELOOP" || code === "ENOTDIR") {
                 presentLocally = false;
+                if (code !== "ENOENT")
+                    lstatError = err;
             }
             else {
                 throw err;
             }
         }
+        // A missing child under a broken directory link (dangling or looping)
+        // means the link hides the file, not that the user deleted it. Record one
+        // warning per link and keep the key out of both sides of the
+        // bulk-asymmetry ratio, like a tombstone.
+        if (!presentLocally) {
+            const linkWarning = localLinkWarning(syncRoot, path.dirname(localPath), path.posix.dirname(relativeKey), linkInspectCache);
+            if (!linkWarning && lstatError !== undefined)
+                throw lstatError;
+            if (linkWarning) {
+                inScopeJournalEntries--;
+                if (!brokenLinkPaths.has(linkWarning.path)) {
+                    brokenLinkPaths.add(linkWarning.path);
+                    (plan.brokenLinkSkipped ??= []).push(linkWarning);
+                }
+                continue;
+            }
+        }
         const materializedKnowledgeDir = presentLocally &&
             isMaterializedKnowledgeDirectory(localPath, relativeKey, entry, companyScoped);
         if (presentLocally && !materializedKnowledgeDir)