@magicpixelart/cli 0.5.13 → 0.5.20

package/dist/commands/sync.js

@@ -1,11 +1,11 @@
 import kleur from 'kleur';
 import ora from 'ora';
-import { createHash } from 'node:crypto';
 import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
-import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.js';
+import { ensureEngineConnect } from '../util/engineConnect.js';
+import { fetchManifestSnapshot, fetchAssetBytes, ApiError, getLastProjectInfo, primeManifestEtags, manifestEtagsSnapshot } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
@@ -13,9 +13,9 @@ import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitInd
 import { assertPathInsideRoot, assertSafeIoPath } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
-import { collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
+import { aliasCollisionKeys, collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
-import { filterUnityManifest } from '../util/unityFilter.js';
+import { applyUnityPullPolicy, isWorkingSetEntry, workingSetPullKeys } from '../util/unityFilter.js';
 import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
@@ -24,7 +24,28 @@ import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
 import { formatWatchSpriteLine } from '../util/watchCopy.js';
+import { decidePull } from '../util/pullDecision.js';
+import { hasUnpushedLocalEdit } from '../util/localEdit.js';
+import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
+/** Did the push half of a run actually move bytes into MagicPixel? */
+export function pushWasActive(pushed) {
+    if (!pushed)
+        return false;
+    return pushed.created > 0 || pushed.updated > 0 || pushed.imported > 0;
+}
+/**
+ * Two consumers need the local PNG listing: the full-sync orphan sweep (no
+ * `since`) and the sha-based rename fallback (incremental, and only when
+ * something is download-bound). On an idle incremental tick — the common case
+ * now that unchanged manifests come back as a bodyless 304 — neither runs, so
+ * walking the whole output tree would be pure waste.
+ *
+ * Full syncs must ALWAYS walk: skipping there would silently disable pruning.
+ */
+export function needsLocalPngWalk(since, toDownloadCount) {
+    return !since || toDownloadCount > 0;
+}
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
     // crashed/killed CLI run before they pile up. Runs once per CLI invocation
@@ -32,10 +53,16 @@ export async function syncCommand(opts) {
     // never race a concurrent in-flight write. See util/tmpJanitor.ts.
     try {
         const cfg = await loadConfig();
-        await runTmpJanitor(cfg.outDir);
+        try {
+            await runTmpJanitor(cfg.outDir);
+        }
+        catch {
+            /* janitor is best-effort — never let it block a sync */
+        }
+        await ensureEngineConnect(cfg, process.cwd(), !opts.dryRun);
     }
     catch {
-        /* janitor is best-effort — never let it block a sync */
+        /* missing/invalid config is reported by runOnce / watchLoop */
     }
     if (opts.watch) {
         await watchLoop(opts);
@@ -94,17 +121,24 @@ async function watchLoop(opts) {
     // genuinely broken (revoked key) rather than transiently blipped.
     const MAX_AUTH_FAILURES = 5;
     let consecutiveAuthFailures = 0;
-    // Adaptive idle backoff: after a few minutes of nothing-to-do we slow the
-    // poll from intervalSec → 5s → 10s so a dev who walked away isn't hammering
-    // the manifest endpoint. ANY change OR error resets this back to intervalSec,
-    // so the "edit → see it" promise stays intact the moment the user comes
-    // back. Error backoff (2→60s) is separate and continues to win.
-    let consecutiveIdleTicks = 0;
-    // Thresholds in seconds (NOT ticks) so a `--watch 10` user gets the same
-    // ~3 min / ~15 min UX as a default `--watch 2` user. Previously these were
-    // tick counts (90 / 300) which made the slowdown timing scale with intervalSec.
-    const IDLE_SOFT_BACKOFF_SECONDS = 180;
-    const IDLE_HARD_BACKOFF_SECONDS = 900;
+    // Adaptive idle backoff: the fast interval is a "hot window" around actual
+    // work, not a steady state. After ~1 min of nothing-to-do we slow the poll
+    // from intervalSec → 5s, and after ~5 min → 10s, so a dev who walked away
+    // isn't polling the manifest hundreds of times an hour. ANY change (pulled
+    // OR pushed) or error resets this, so the "edit → see it" promise stays
+    // intact the moment the user comes back. Error backoff (2→60s) is separate
+    // and continues to win.
+    //
+    // Idle is measured in wall-clock seconds since the last change, not in
+    // ticks: once we've backed off, a "tick" is 5s or 10s long, so counting
+    // ticks × intervalSec would undercount elapsed time and push the 5-minute
+    // step far past 5 minutes.
+    let lastChangeAt = Date.now();
+    // Re-walk the game tree on this cadence so new PNGs are ingested without
+    // listing thousands of folders on every 2s tick.
+    const GAME_INDEX_TTL_MS = 30_000;
+    let gameIndexCache = header.gameIndex;
+    let gameIndexAt = Date.now();
     // Cancellable idle sleep — `onStopSignal` calls `wakeStop()` so the next
     // tick exits immediately instead of waiting out the full backoff (which can
     // be 60s at the error ceiling). Initialised to a no-op so the first
@@ -119,9 +153,11 @@ async function watchLoop(opts) {
         stopping = true;
         wakeStop();
         process.stdout.write('\x1b[2K\r');
+        const sig = signal === 'SIGTERM' ? 'SIGTERM' : 'SIGINT';
         if (inFlight) {
-            console.log(kleur.dim(`Still finishing this check… (${signal} again to stop now)`));
-            process.once(signal, () => process.exit(signal === 'SIGINT' ? 130 : 143));
+            const again = sig === 'SIGINT' ? 'Ctrl+C' : 'SIGTERM';
+            console.log(kleur.dim(`Still finishing this check… (${again} again to stop now)`));
+            process.once(sig, () => process.exit(sig === 'SIGINT' ? 130 : 143));
         }
         else {
             if (!opts.quiet)
@@ -143,7 +179,18 @@ async function watchLoop(opts) {
         };
         try {
             onStatus('Checking MagicPixel…');
-            const r = await runOnce({ ...opts, watch: false }, { watchMode: true, onStatus, gameIndex: header.gameIndex });
+            const reuseIndex = gameIndexCache && Date.now() - gameIndexAt < GAME_INDEX_TTL_MS
+                ? gameIndexCache
+                : undefined;
+            const r = await runOnce({ ...opts, watch: false }, {
+                watchMode: true,
+                onStatus,
+                gameIndex: reuseIndex,
+                onGameIndex: (idx) => {
+                    gameIndexCache = idx;
+                    gameIndexAt = Date.now();
+                },
+            });
             // Reset backoff on any successful tick. Resume message fires once when
             // we recover from an auth pause — `getApiKey()` re-reads
             // .magicpixel/credentials on every call, so a `magicpixel login` in
@@ -163,17 +210,16 @@ async function watchLoop(opts) {
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Back online — resuming.`);
             }
             const changedCount = r.added.length + r.modified.length + r.removed.length + r.renamed.length;
-            if (changedCount > 0) {
+            // Pushing a locally edited sprite is activity too — it just isn't part of
+            // the printed pull list. Without it, an artist working only in Unity
+            // would slide into the 10s idle poll while actively saving files.
+            if (changedCount > 0 || pushWasActive(r.pushed)) {
                 // Snap back to the fast interval the moment anything changes.
-                consecutiveIdleTicks = 0;
+                lastChangeAt = Date.now();
                 backoffSec = intervalSec;
             }
             else {
-                consecutiveIdleTicks++;
-                backoffSec = nextBackoffForIdle(consecutiveIdleTicks, intervalSec, {
-                    softSec: IDLE_SOFT_BACKOFF_SECONDS,
-                    hardSec: IDLE_HARD_BACKOFF_SECONDS,
-                });
+                backoffSec = nextBackoffForIdle((Date.now() - lastChangeAt) / 1000, intervalSec);
             }
             if (opts.quiet)
                 return;
@@ -194,7 +240,7 @@ async function watchLoop(opts) {
             const firstLine = err.message.split('\n')[0];
             process.stdout.write('\x1b[2K\r');
             // Any error breaks the idle streak so we come back fast once it clears.
-            consecutiveIdleTicks = 0;
+            lastChangeAt = Date.now();
             const decision = classifyTickError(err, {
                 backoffSec,
                 pausedForAuth,
@@ -242,7 +288,6 @@ async function watchLoop(opts) {
             }
         }
         finally {
-            header.gameIndex = undefined;
             inFlight = false;
         }
     };
@@ -287,13 +332,20 @@ function isNetworkError(err) {
         /\b(502|504)\b.*\b(bad gateway|gateway timeout)\b/i.test(msg));
 }
 /**
- * Pure helper: given how many consecutive idle ticks we've seen and the
- * configured poll interval, return the next backoff in seconds. Exported so
- * the watch-mode regression test can guard the "ticks vs seconds" bug fixed
- * in 0.4.0 without exercising the full watch loop.
+ * Idle thresholds (seconds of consecutive idleness) at which the watcher steps
+ * down from the configured interval to 5s, then to 10s. Single source of truth
+ * for both the watch loop and its regression tests.
+ */
+export const IDLE_BACKOFF_THRESHOLDS = { softSec: 60, hardSec: 300 };
+/**
+ * Pure helper: given how long we've been idle (wall-clock seconds since the
+ * last pulled or pushed change) and the configured poll interval, return the
+ * next backoff in seconds. Exported so the watch-mode regression test can guard
+ * the "ticks vs seconds" bug fixed in 0.4.0 without exercising the full watch
+ * loop. Callers pass elapsed time, not tick counts: once the watcher has backed
+ * off, ticks are longer than `intervalSec`.
  */
-export function nextBackoffForIdle(consecutiveIdleTicks, intervalSec, thresholds = { softSec: 180, hardSec: 900 }) {
-    const idleSeconds = consecutiveIdleTicks * intervalSec;
+export function nextBackoffForIdle(idleSeconds, intervalSec, thresholds = IDLE_BACKOFF_THRESHOLDS) {
     if (idleSeconds >= thresholds.hardSec)
         return Math.max(intervalSec, 10);
     if (idleSeconds >= thresholds.softSec)
@@ -354,6 +406,11 @@ async function loadWatchHeader(onProgress) {
 async function runOnce(opts, runOpts = {}) {
     const config = await loadConfig();
     const state = await loadState();
+    // Seed manifest validators persisted by the previous run so a one-shot sync
+    // can answer with a 304 on its very first poll (watchers already keep them
+    // in memory). A `--full` run intentionally sends no `since`, which is a
+    // different validator key, so it can't be short-circuited by a stale entry.
+    primeManifestEtags(state.manifestEtags);
     const startedAt = new Date().toISOString();
     const concurrency = Math.max(1, Math.min(opts.concurrency ?? 6, 16));
     const verbose = !opts.quiet && !runOpts.watchMode;
@@ -363,7 +420,13 @@ async function runOnce(opts, runOpts = {}) {
     if (verbose && config.endpoint) {
         console.log(kleur.yellow(`! using custom endpoint: ${config.endpoint}`));
     }
-    const since = opts.full ? undefined : state.lastSync;
+    // Incremental unless asked for a full run — or unless a full pass is due:
+    // permanently-deleted rows can't be reported incrementally (see reconcile.ts).
+    const reconcileDue = !opts.full && !!state.lastSync && shouldReconcile(state.lastReconcile, Date.now());
+    let since = opts.full || reconcileDue ? undefined : state.lastSync;
+    if (reconcileDue && verbose) {
+        console.log(kleur.dim('Running a full reconcile (periodic) to clear anything deleted in MagicPixel.'));
+    }
     const previousAssets = state.assets ?? {}; // id → key from prior sync
     const spinner = verbose
         ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
@@ -371,8 +434,27 @@ async function runOnce(opts, runOpts = {}) {
     if (!spinner)
         onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
+    // Composite keys the cloud reports as gone (document trashed / componentized)
+    // since our cursor. Empty on --full, where the manifest itself is the truth.
+    let removedRemoteKeys = [];
+    // Capture before the Unity filter drops rows — lastSync must not jump past
+    // an editor save whose `unity` flag was omitted on this tick.
+    let observedUpdatedAt = null;
     try {
-        manifest = await fetchAllManifest(config, since);
+        let snapshot = await fetchManifestSnapshot(config, since);
+        if (snapshot.removalsTruncated && since) {
+            // The server couldn't list every removal in this window. Trusting the
+            // partial list and advancing the cursor would strand the rest forever, so
+            // re-read the whole manifest and let the orphan sweep decide.
+            if (verbose) {
+                console.log(kleur.dim('Many sprites were removed at once — re-reading the full manifest to stay in sync.'));
+            }
+            since = undefined;
+            snapshot = await fetchManifestSnapshot(config, undefined);
+        }
+        manifest = snapshot.entries;
+        removedRemoteKeys = snapshot.removedKeys;
+        observedUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
@@ -421,8 +503,11 @@ async function runOnce(opts, runOpts = {}) {
                 },
             })
             : { files: [], capped: false });
+    if (!runOpts.gameIndex)
+        runOpts.onGameIndex?.(gameIndex);
     const connected = matchConnectGlobs(gameIndex, config.connect ?? []);
     const sourceByKey = collectSourceRelMap(connected.entries, state.synced);
+    aliasCollisionKeys(sourceByKey, manifest.map((e) => e.key));
     if (verbose && gameIndex.capped) {
         console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
     }
@@ -434,6 +519,7 @@ async function runOnce(opts, runOpts = {}) {
             (connected.capped ? ` of ${connected.total} matched` : '')));
     }
     const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
+    const workingSet = workingSetPullKeys(sourceByKey, state.synced);
     // Files whose artboard is no longer flagged for Unity. Deleted even in
     // incremental mode: un-checking the box in the editor must actually remove
     // the sprite from the game project, not leave a stale copy behind.
@@ -444,14 +530,25 @@ async function runOnce(opts, runOpts = {}) {
     // response must never delete art from someone's game project.
     const unknownFlagPaths = new Set();
     if (projectKind === 'Unity') {
-        const filtered = filterUnityManifest(manifest, { syncAll: config.unitySyncAll });
+        const filtered = applyUnityPullPolicy(manifest, {
+            syncAll: config.unitySyncAll,
+            alwaysPull: (entry) => isWorkingSetEntry(entry, workingSet),
+        });
         if (filtered.unknown.length > 0) {
-            console.log(kleur.yellow(`! ${filtered.unknown.length} artboard${filtered.unknown.length === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`));
-            console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+            const n = filtered.unknown.length;
+            const msg = `${n} artboard${n === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`;
+            if (verbose) {
+                console.log(kleur.yellow(`! ${msg}`));
+                console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+            }
+            else {
+                onStatus?.(msg);
+            }
         }
         const unknownSet = new Set(filtered.unknown);
+        const pullSet = new Set(filtered.entries);
         for (const entry of manifest) {
-            if (filtered.entries.includes(entry))
+            if (pullSet.has(entry))
                 continue;
             const p = pathForKey(entry.key);
             if (unknownSet.has(entry)) {
@@ -481,8 +578,20 @@ async function runOnce(opts, runOpts = {}) {
                 bytesIn: 0,
                 bytesSaved: 0,
                 renamed: [],
+                conflicts: [],
             };
-            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
+            // Persist validators even when the cursor didn't move, so the next
+            // one-shot run starts from a conditional GET.
+            const lastSync = observedUpdatedAt && !(state.lastSync && state.lastSync > observedUpdatedAt)
+                ? observedUpdatedAt
+                : state.lastSync;
+            await saveState({
+                ...state,
+                ...(lastSync ? { lastSync } : {}),
+                ...(since ? {} : { lastReconcile: startedAt }),
+                manifestEtags: manifestEtagsSnapshot(),
+            });
+            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
             return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
@@ -524,12 +633,61 @@ async function runOnce(opts, runOpts = {}) {
     const diffLimit = createLimit(concurrency);
     const shaByEntryId = new Map();
     const toDownload = [];
+    const conflicts = [];
     let bytesSaved = 0;
     let unchanged = 0;
+    const synced = state.synced ?? {};
+    const cloudShaByAssetId = new Map();
+    for (const s of Object.values(synced)) {
+        if (!s.assetId || !s.sha256)
+            continue;
+        const prev = cloudShaByAssetId.get(s.assetId);
+        if (prev && prev !== s.sha256)
+            cloudShaByAssetId.set(s.assetId, 'ambiguous');
+        else if (!prev)
+            cloudShaByAssetId.set(s.assetId, s.sha256);
+    }
+    const previousCloudSha = (entry) => {
+        const direct = synced[entry.key]?.sha256;
+        if (direct)
+            return direct;
+        for (const k of entry.previous_keys ?? []) {
+            const sha = synced[k]?.sha256;
+            if (sha)
+                return sha;
+        }
+        if (entry.asset_id) {
+            const sha = cloudShaByAssetId.get(entry.asset_id);
+            if (sha && sha !== 'ambiguous')
+                return sha;
+        }
+        return undefined;
+    };
     await Promise.all(manifest.map((entry) => diffLimit(async () => {
+        const previousCloudSha256 = previousCloudSha(entry);
+        const inWorkingSet = isWorkingSetEntry(entry, workingSet);
+        // Unchanged cloud composite: skip hashing the original PNG (it almost
+        // never matches) unless the file is gone and we need to restore it.
+        if (entry.sha256 && previousCloudSha256 === entry.sha256 && existsSync(pathFor(entry))) {
+            shaByEntryId.set(entry.id, null);
+            unchanged++;
+            if (entry.size_bytes)
+                bytesSaved += entry.size_bytes;
+            return;
+        }
         const localSha = await fileSha256(pathFor(entry));
         shaByEntryId.set(entry.id, localSha);
-        if (entry.sha256 && localSha && entry.sha256 === localSha) {
+        const decision = decidePull({
+            cloudSha256: entry.sha256,
+            localSha256: localSha,
+            previousCloudSha256,
+            lastPushedDiskSha256: synced[entry.key]?.diskSha256,
+            inWorkingSet,
+        });
+        if (decision === 'conflict') {
+            conflicts.push(entry.key);
+        }
+        else if (decision === 'skip') {
             unchanged++;
             if (entry.size_bytes)
                 bytesSaved += entry.size_bytes;
@@ -542,30 +700,32 @@ async function runOnce(opts, runOpts = {}) {
     // (Renames also produce a stale path on disk — collected separately below.)
     let orphans = [];
     const remoteDiskPaths = new Set(manifest.map((e) => pathFor(e)));
-    // We walk local PNGs even in incremental mode so the sha-based rename
-    // fallback below has something to match against. The full-orphan path is
-    // still gated on `!since` to preserve incremental-mode safety (we never
-    // delete files outside what the current manifest delta touches).
-    const localPngs = await walkOutDirPngs(config.outDir);
+    const remoteKeySet = new Set(manifest.map((e) => e.key));
+    const previousKeySet = new Set(Object.values(previousAssets));
+    const localPngs = needsLocalPngWalk(since, toDownload.length)
+        ? await walkOutDirPngs(config.outDir)
+        : [];
+    // Every key we have ever synced, indexed by the disk path it maps to. Used
+    // both for orphan tracking and to look up a prune candidate's edit baseline.
+    const keyByPath = new Map();
+    for (const key of Object.keys(state.synced ?? {}).concat(Object.values(previousAssets))) {
+        try {
+            const p = pathForKey(key);
+            if (!keyByPath.has(p))
+                keyByPath.set(p, key);
+        }
+        catch {
+            /* unusable key — nothing to track */
+        }
+    }
     // Sprites created in Unity (or any PNG we never pulled) are pending a
     // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
-        const trackedPaths = new Set(Object.keys(state.synced ?? {})
-            .concat(Object.values(previousAssets))
-            .map((key) => {
-            try {
-                return pathForKey(key);
-            }
-            catch {
-                return '';
-            }
-        })
-            .filter(Boolean));
         const policy = selectFullSyncOrphans({
             localPaths: localPngs.map((a) => a.abs),
             remoteDiskPaths,
             protectedPaths: unknownFlagPaths,
-            isTracked: (p) => trackedPaths.has(p),
+            isTracked: (p) => keyByPath.has(p),
         });
         orphans = policy.orphans;
     }
@@ -625,15 +785,20 @@ async function runOnce(opts, runOpts = {}) {
         }
     })
         .filter((p) => p && existsSync(p) && isPathInside(p, outRoot));
-    // De-duplicate vs the full-sync orphan list.
+    // Every prune candidate goes through `addOrphan`, so no source can bypass the
+    // local-edit guard applied below. De-duplicates vs the full-sync orphan list.
     const orphanSet = new Set(orphans);
+    const addOrphan = (p) => {
+        if (existsSync(p) && isPathInside(p, outRoot))
+            orphanSet.add(p);
+    };
     for (const p of renameStalePaths)
-        orphanSet.add(p);
+        addOrphan(p);
     // Un-checked "Sync to Unity" artboards: their PNG (and .meta) leaves the
     // Unity project on the next sync, incremental or not. Working-set originals
     // are never in this list.
     for (const p of deselectedPaths)
-        orphanSet.add(p);
+        addOrphan(p);
     // Server-side rename history. Each manifest entry carries the composite
     // keys this row was previously emitted under (populated by the editor when
     // a doc/artboard is renamed). For each prior key whose file is still on
@@ -646,16 +811,58 @@ async function runOnce(opts, runOpts = {}) {
         resolveDiskPath: (key) => pathForKey(key),
         fileExists: existsSync,
     });
-    for (const p of prevKeyResult.orphanPaths) {
-        if (isPathInside(p, outRoot))
-            orphanSet.add(p);
-    }
+    for (const p of prevKeyResult.orphanPaths)
+        addOrphan(p);
     for (const r of prevKeyResult.renames) {
         if (!renamed.some((x) => x.id === r.id && x.oldKey === r.oldKey)) {
             renamed.push(r);
         }
     }
-    orphans = [...orphanSet];
+    // Cloud-side removals (document trashed, or converted into a component
+    // master). These rows leave the manifest entirely, so an incremental run has
+    // no other way to learn about them — without this the PNG would live on in
+    // the game project forever. Only keys we pulled ourselves are eligible:
+    // a same-named sprite authored in Unity is pending push, not an orphan.
+    for (const key of removedRemoteKeys) {
+        if (remoteKeySet.has(key))
+            continue; // still live under another row
+        if (!synced[key] && !previousKeySet.has(key))
+            continue; // never ours
+        try {
+            addOrphan(pathForKey(key));
+        }
+        catch {
+            continue;
+        }
+    }
+    // A locally-edited file is never deleted, whatever put it in the prune set
+    // (deselected "Sync to Unity", trashed document, rename fallback,
+    // previous-key sweep): that edit is the only copy of the work until the user
+    // pushes it or discards it. Manifest-resident conflicts were already detected
+    // during the diff, so they skip the re-hash.
+    const conflictPaths = new Set();
+    for (const key of conflicts) {
+        try {
+            conflictPaths.add(pathForKey(key));
+        }
+        catch {
+            /* unusable key — nothing to protect */
+        }
+    }
+    orphans = [];
+    const keptFromPrune = [];
+    for (const p of orphanSet) {
+        if (conflictPaths.has(p))
+            continue;
+        const key = keyByPath.get(p);
+        if (key &&
+            (await hasUnpushedLocalEdit({ absPath: p, baselineDiskSha256: synced[key]?.diskSha256 }))) {
+            keptFromPrune.push(key);
+            continue;
+        }
+        orphans.push(p);
+    }
+    conflicts.push(...keptFromPrune);
     // Legacy-suffix folder sweep — always runs, even in incremental mode.
     //
     // Background: server-side slug uniqueness rules have changed over time
@@ -708,6 +915,12 @@ async function runOnce(opts, runOpts = {}) {
         }
         console.log();
     }
+    if (conflicts.length > 0) {
+        if (live) {
+            printConflicts(conflicts, new Set(keptFromPrune));
+        }
+        onStatus?.(`${conflicts.length} sprite${conflicts.length === 1 ? '' : 's'} changed in both places — kept your local copy.`);
+    }
     if (opts.dryRun) {
         if (verbose) {
             console.log(kleur.dim('--dry-run: no files written.'));
@@ -727,6 +940,7 @@ async function runOnce(opts, runOpts = {}) {
             failed: 0,
             bytesIn: 0,
             bytesSaved,
+            conflicts,
         };
     }
     const result = {
@@ -738,6 +952,7 @@ async function runOnce(opts, runOpts = {}) {
         failed: 0,
         bytesIn: 0,
         bytesSaved,
+        conflicts,
     };
     let progress = null;
     if (live && toDownload.length > 0) {
@@ -768,14 +983,9 @@ async function runOnce(opts, runOpts = {}) {
                     result.bytesSaved += entry.size_bytes;
             }
             else {
-                if (entry.sha256) {
-                    const actual = createHash('sha256').update(bytes).digest('hex');
-                    if (actual !== entry.sha256) {
-                        throw new Error(`sha256 mismatch (expected ${entry.sha256.slice(0, 12)}…, got ${actual.slice(0, 12)}…)`);
-                    }
-                }
-                // Wrap any of mkdir/writeFile so the user sees a friendly
-                // multi-line diagnostic instead of a raw `EACCES: permission denied`.
+                // Do not require bytes to match `entry.sha256`. Single-artboard
+                // downloads serve storage_path (so 2048/4096 Unity tiles do not
+                // 546 the isolate); that PNG can differ from a cached composite hash.
                 //
                 // NOTE: Asset PNGs deliberately use a direct writeFile rather than
                 // atomicWrite. Vite's chokidar watcher only suppresses atomic-rename
@@ -944,9 +1154,15 @@ async function runOnce(opts, runOpts = {}) {
     for (const key of result.removed)
         delete nextSynced[key];
     const writtenKeys = new Set([...result.added, ...result.modified]);
+    const conflictSet = new Set(conflicts);
     for (const entry of manifest) {
         if (!entry.asset_id)
             continue;
+        // Conflicted keys keep their old baselines: recording the new cloud sha
+        // (with the locally-edited disk sha) would make both halves believe they
+        // are in sync and freeze the divergence forever.
+        if (conflictSet.has(entry.key))
+            continue;
         const sha = entry.sha256 ?? (await fileSha256(pathFor(entry)));
         if (!sha)
             continue;
@@ -971,14 +1187,23 @@ async function runOnce(opts, runOpts = {}) {
             ...(sourceRel ? { sourceRel } : {}),
         };
     }
-    const nextState = { ...state, assets: nextAssets, synced: nextSynced };
-    if (result.failed === 0) {
+    const nextState = {
+        ...state,
+        assets: nextAssets,
+        synced: nextSynced,
+        manifestEtags: manifestEtagsSnapshot(),
+        // A completed full pass is the only run that can prove nothing is orphaned.
+        ...(!since && result.failed === 0 ? { lastReconcile: startedAt } : {}),
+    };
+    // Unresolved conflicts hold the cursor, exactly like a failed download: the
+    // next sync must see the same rows again and re-report them.
+    if (result.failed === 0 && conflicts.length === 0) {
         // Advance the cursor to the newest row we actually observed, NOT the
         // wall-clock time the sync started. Using startedAt silently skipped
         // rows whose `updated_at` lived in the gap between the manifest snapshot
         // and the next poll (notably when only metadata changed — e.g. artboard
         // renames — and the row updated between fetch start and save).
-        const maxUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
+        const maxUpdatedAt = observedUpdatedAt ?? maxIsoTimestamp(manifest.map((e) => e.updated_at));
         if (maxUpdatedAt) {
             // Take the later of: newest row we saw, or the prior cursor. Never
             // rewind — an incremental sync that returned 0 rows must keep the
@@ -996,9 +1221,14 @@ async function runOnce(opts, runOpts = {}) {
         }
         delete nextState.lastError;
     }
-    else {
+    else if (result.failed > 0) {
         nextState.lastError = `${result.failed} download${result.failed === 1 ? '' : 's'} failed at ${startedAt}`;
     }
+    else {
+        nextState.lastError =
+            `${conflicts.length} sprite${conflicts.length === 1 ? '' : 's'} changed both locally and in MagicPixel at ${startedAt}` +
+                ` (${conflicts.slice(0, 3).join(', ')}${conflicts.length > 3 ? ', …' : ''})`;
+    }
     // Emit typed index from the filesystem — never from the manifest. This
     // guarantees the barrel can never disagree with what bundlers see on disk,
     // and removes the silent-failure mode where a flaky manifest call left
@@ -1050,16 +1280,16 @@ async function runOnce(opts, runOpts = {}) {
             printRenames(renamed, { withHints: true });
     }
     onStatus?.('Checking your game files…');
-    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
+    const pushed = await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
     if (result.failed)
         process.exitCode = 1;
-    return result;
+    return { ...result, pushed };
 }
-async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus) {
     if (pushEnabled === false)
         return null;
     try {
-        return await runPush({ quiet: !verbose, gameIndex });
+        return await runPush({ quiet: !verbose, gameIndex, onStatus });
     }
     catch (e) {
         if (announceErrors) {
@@ -1127,6 +1357,23 @@ function humanTime(iso) {
         return iso;
     }
 }
+/**
+ * Both-sides-changed report. Printed on every run that has conflicts (also in
+ * watch mode) because the alternative — staying silent — is what makes a lost
+ * edit feel like a sync bug.
+ */
+function printConflicts(keys, removedRemotely = new Set()) {
+    console.log();
+    console.log(kleur.yellow(`${keys.length} sprite${keys.length === 1 ? '' : 's'} changed in both places — not overwritten:`));
+    for (const key of keys) {
+        const note = removedRemotely.has(key) ? kleur.dim(' (no longer synced from MagicPixel)') : '';
+        console.log(`  ${kleur.yellow('~')} ${key}${note}`);
+    }
+    console.log(kleur.dim(`  Keep the local edit: run \`${cmd('push')}\` (it will report the cloud change), or delete the PNG to accept MagicPixel's copy.`));
+    if (removedRemotely.size > 0) {
+        console.log(kleur.dim(`  Marked (no longer synced): re-check "Sync to Unity" (or restore the document) to push the edit up, or delete the PNG to accept the removal.`));
+    }
+}
 function printOrphans(orphans) {
     console.log();
     console.log(kleur.yellow(`Orphaned local files (not in manifest):`));