@magicpixelart/cli 0.5.14 → 0.5.21

package/CHANGELOG.md

@@ -7,6 +7,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.21] — 2026-09-14
+
+- `sync --watch` can no longer hang forever: every network request now has a
+  deadline (45s for manifest/JSON calls, 120s for sprite downloads and pushes),
+  and a stalled request is retried like any other network blip.
+- A slow tick prints a heartbeat with elapsed time instead of a frozen line, and
+  the first big pull reports its running sprite count page by page.
+- Timeout errors now end with a "check your internet connection" hint, matching
+  every other CLI error.
+- The heartbeat line no longer prints a stray ellipsis before the sprite count.
+
+## 0.5.20
+
+- `sync` no longer deletes a PNG that was edited in your project when the sprite
+  leaves the manifest — un-checking "Sync to Unity", trashing the document, or a
+  rename/previous-key sweep now keep the local edit and report it instead.
+
+## 0.5.19
+
+- `sync` no longer overwrites a PNG that changed both on disk and in MagicPixel. Such sprites are reported as conflicts, kept on disk, never pruned, and re-reported until you `push` them or delete the local file.
+- A full reconcile is promoted automatically every 15 minutes (and whenever the server reports it truncated its removal list), so sprites deleted permanently in MagicPixel stop lingering in the game project.
+
+## [0.5.18] — 2026-08-27
+
+### Fixed
+- Trashed documents (and documents converted into component masters) no longer
+  linger in the game project. The manifest now excludes them, and incremental
+  syncs receive an explicit `removed_keys` list so previously pulled sprites are
+  pruned on the next run. Sprites authored in Unity are still never touched.
+- Renaming a folder or toggling its "Sync to Unity" flag now invalidates the
+  manifest cache, so the CLI stops receiving a stale `304 Not Modified`.
+
+## [0.5.17] — 2026-08-27
+
+### Fixed
+- Watch-mode idle backoff now measures wall-clock seconds since the last change
+  instead of `ticks x interval`. Once the watcher had stepped down to 5s/10s
+  ticks the old estimate undercounted elapsed time, so the 5-minute step landed
+  well past 5 minutes.
+- Pushing a locally edited sprite counts as activity again: a run that only
+  pushes (an artist working entirely inside their engine) resets the hot window
+  to the fast interval instead of sliding to the 10s idle poll.
+
+### Changed
+- Idle incremental ticks no longer walk the whole output directory. The listing
+  is only needed by the full-sync orphan sweep and the rename fallback, so it is
+  now computed lazily — an unchanged (304) tick does no filesystem scan.
+
+## [0.5.16] — 2026-08-27
+
+### Changed
+- Manifest validators are persisted in `.magicpixel/state.json`, so a one-shot
+  `sync` (CI, cron, a manual run) gets the same idle `304 Not Modified` a
+  watcher already got on its second tick. Validators are keyed by endpoint plus
+  exact query, so a staging/self-hosted swap or an edited `connect`/`exclude`
+  glob can never be answered from a stale validator.
+
+## [0.5.15] — 2026-08-26
+
+### Changed
+- `sync --watch` sends conditional manifest requests (`If-None-Match`), so an
+  idle tick costs a `304` with no body instead of a full manifest render.
+  Validators are only used on incremental fetches — a full fetch, which prune
+  compares against, always reads the body.
+- Idle backoff is now a hot window: the configured interval applies for ~1 min
+  after the last change, then steps to 5s, then to 10s after ~5 min idle
+  (previously ~3 min / ~15 min).
+
+### Fixed
+- `safeFetch` no longer treated `304` as a malformed redirect. This made every
+  conditional asset download retry five times and then fail as a network error,
+  so unchanged PNGs were re-downloaded in full.
+
+
 ## [0.5.14] — 2026-08-26
 
 ### Fixed

package/dist/api.js

@@ -1,7 +1,53 @@
 import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
-import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, validateEndpointUrl, } from './util/security.js';
+import { ASSET_TIMEOUT_MS, etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, validateEndpointUrl, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
 import { cmd } from './util/invoke.js';
+/**
+ * Manifest validators, so an idle poll costs a conditional GET (304, no body)
+ * instead of a full manifest render. Keyed by endpoint + exact query string: a
+ * different `since`/glob set — or a different server — is a different
+ * projection and must not reuse a validator.
+ *
+ * Bounded so a long-lived watcher walking many `since` values can't grow it
+ * without limit; eviction is FIFO and only costs one non-conditional GET.
+ *
+ * `sync` persists this map into state.json (see `manifestEtagsSnapshot` /
+ * `primeManifestEtags`) so one-shot runs — CI, cron, a manual `sync` — get the
+ * same 304 as a watcher's second tick.
+ */
+const manifestEtags = new Map();
+const MAX_MANIFEST_ETAGS = 32;
+function rememberManifestEtag(key, etag) {
+    manifestEtags.delete(key);
+    manifestEtags.set(key, etag);
+    while (manifestEtags.size > MAX_MANIFEST_ETAGS) {
+        const oldest = manifestEtags.keys().next().value;
+        if (oldest === undefined)
+            break;
+        manifestEtags.delete(oldest);
+    }
+}
+/**
+ * Seed validators persisted by an earlier run. Ignores non-string junk so a
+ * hand-edited state.json can't inject a bogus header value; a wrong-but-typed
+ * validator is harmless (the server just answers 200 with a body).
+ */
+export function primeManifestEtags(entries) {
+    if (!entries || typeof entries !== 'object' || Array.isArray(entries))
+        return;
+    for (const [key, etag] of Object.entries(entries)) {
+        if (typeof etag === 'string' && etag)
+            rememberManifestEtag(key, etag);
+    }
+}
+/** Snapshot of the current validators, for persisting into state.json. */
+export function manifestEtagsSnapshot() {
+    return Object.fromEntries(manifestEtags);
+}
+/** Test seam: drop cached manifest validators between cases. */
+export function __resetManifestEtagsForTesting() {
+    manifestEtags.clear();
+}
 /**
  * Last-seen project metadata from any manifest response this process made.
  * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
@@ -84,17 +130,32 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('cursor', opts.cursor);
     if (opts.limit)
         url.searchParams.set('limit', String(opts.limit));
+    // Conditional GET: an unchanged scope comes back as a 304 with no body.
+    // Only for un-paginated requests — the server doesn't validate cursor pages.
+    // Key includes the origin+path so a persisted validator can't be replayed
+    // against a different endpoint (self-hosted / staging swap).
+    const etagKey = opts.conditional && !opts.cursor ? `${url.origin}${url.pathname}${url.search}` : null;
+    const knownEtag = etagKey ? manifestEtags.get(etagKey) : undefined;
     // Reuse the same transient-failure policy as asset downloads, with extra
     // 546 attempts so first-run can ride out a worker recycle without stalling
     // every PNG download for ~30s.
     return retryTransient(`manifest`, async () => {
-        const { headers, requestId } = buildHeaders();
+        const { headers, requestId } = buildHeaders(knownEtag ? { 'If-None-Match': knownEtag } : undefined);
         const res = await safeFetch(url.href, { headers });
         const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status === 304) {
+            const minCli = res.headers.get('x-magicpixel-min-cli-version');
+            if (minCli)
+                maybeWarnStaleCli(minCli);
+            return { items: [], nextCursor: null, count: 0 };
+        }
         if (res.status >= 200 && res.status < 300) {
             const minCli = res.headers.get('x-magicpixel-min-cli-version');
             if (minCli)
                 maybeWarnStaleCli(minCli);
+            const etag = res.headers.get('etag');
+            if (etagKey && etag)
+                rememberManifestEtag(etagKey, etag);
             const data = (await res.json());
             // Shape-guard the response. A malformed edge response (null,
             // {items: null}, nextCursor: 42, etc.) would otherwise either crash
@@ -214,18 +275,40 @@ function compareSemver(a, b) {
     }
     return 0;
 }
-export async function fetchAllManifest(config, since) {
+/**
+ * Full manifest walk, including the cloud's removal list.
+ *
+ * `onProgress` fires after each page with the running entry count, so a big
+ * first pull shows movement instead of one frozen status line.
+ */
+export async function fetchManifestSnapshot(config, since, onProgress) {
     const out = [];
+    const removed = new Set();
+    let removalsTruncated = false;
     let cursor;
+    // Conditional GETs only on incremental fetches. An incremental 304 means
+    // "nothing changed since `since`", which is indistinguishable from the empty
+    // incremental page callers already handle. A full fetch (`since` unset) is
+    // the cloud truth that prune compares against, so it always reads the body.
+    const conditional = !!since;
     // Cycle guard: caps total pages so a buggy server cursor can't hang the CLI.
     // At 500 entries/page this is 100k assets — well past any realistic project.
     const MAX_PAGES = 200;
     for (let page = 0; page < MAX_PAGES; page++) {
-        const res = await fetchManifestPage({ config, since, cursor, limit: 500 });
+        const res = await fetchManifestPage({ config, since, cursor, limit: 500, conditional });
         out.push(...res.items);
+        if (out.length > 0)
+            onProgress?.(out.length);
+        if (Array.isArray(res.removed_keys)) {
+            for (const k of res.removed_keys)
+                if (typeof k === 'string' && k)
+                    removed.add(k);
+        }
+        if (res.removals_truncated === true)
+            removalsTruncated = true;
         const nextCursor = res.nextCursor ?? undefined;
         if (!nextCursor)
-            return out;
+            return { entries: out, removedKeys: [...removed], removalsTruncated };
         // Detect a stuck cursor (server returns the same token it just received)
         // in O(1) round-trips instead of burning the full page budget.
         if (nextCursor === cursor) {
@@ -237,6 +320,10 @@ export async function fetchAllManifest(config, since) {
     throw new Error(`manifest: pagination exceeded ${MAX_PAGES} pages — possible server cursor loop.\n` +
         `  Fix: re-run with --full, or report at https://github.com/magicpixel/cli/issues.`);
 }
+/** Entries only — for read-only commands (`list`, `status`). */
+export async function fetchAllManifest(config, since) {
+    return (await fetchManifestSnapshot(config, since)).entries;
+}
 /**
  * Download a single asset by key. Returns null on 304 (not modified).
  * Shares the retryTransient policy with manifest fetches — including
@@ -248,7 +335,7 @@ export async function fetchAssetBytes(config, key, knownSha) {
     const conditional = knownSha ? { 'If-None-Match': etagForSha256(knownSha) } : undefined;
     return retryTransient(`download ${key}`, async () => {
         const { headers, requestId } = buildHeaders(conditional);
-        const res = await safeFetch(url.href, { headers });
+        const res = await safeFetch(url.href, { headers }, { timeoutMs: ASSET_TIMEOUT_MS });
         const serverRequestId = res.headers.get('x-request-id') ?? requestId;
         if (res.status === 304) {
             // Drain so undici can return the socket to the keep-alive pool.
@@ -292,11 +379,10 @@ export async function pushSprites(sprites, retryOpts) {
     const url = resolveIngestEndpoint();
     return retryTransient('push', async () => {
         const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
-        const res = await safeFetch(url, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify({ sprites }),
-        });
+        const res = await safeFetch(url, { method: 'POST', headers, body: JSON.stringify({ sprites }) }, 
+        // A push batch carries PNG bytes; give it the asset deadline, not the
+        // shorter JSON one.
+        { timeoutMs: ASSET_TIMEOUT_MS });
         const serverRequestId = res.headers.get('x-request-id') ?? requestId;
         if (res.ok) {
             const data = (await res.json());

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
 import { ensureEngineConnect } from '../util/engineConnect.js';
-import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.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';
@@ -23,9 +23,29 @@ import { maxIsoTimestamp } from '../util/iso.js';
 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 { shouldPullEntry } from '../util/pullDecision.js';
+import { formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } 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
@@ -101,17 +121,19 @@ 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;
@@ -155,14 +177,31 @@ async function watchLoop(opts) {
                 return;
             process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} ${msg}`)}`);
         };
+        // Heartbeat: a tick that legitimately takes minutes (huge first pull, slow
+        // link) must not look like the silent hang a timeout-less fetch used to
+        // cause. Requests now have deadlines, so a live counter here means "slow",
+        // not "stuck".
+        const tickStartedAt = Date.now();
+        let lastStatus = '';
+        const wrappedStatus = (msg) => {
+            lastStatus = msg;
+            onStatus(msg);
+        };
+        const heartbeat = opts.quiet
+            ? null
+            : setInterval(() => {
+                const elapsedSec = Math.round((Date.now() - tickStartedAt) / 1000);
+                onStatus(formatSlowTickLine(elapsedSec, lastStatus));
+            }, SLOW_TICK_HEARTBEAT_MS);
+        heartbeat?.unref?.();
         try {
-            onStatus('Checking MagicPixel…');
+            wrappedStatus('Checking MagicPixel…');
             const reuseIndex = gameIndexCache && Date.now() - gameIndexAt < GAME_INDEX_TTL_MS
                 ? gameIndexCache
                 : undefined;
             const r = await runOnce({ ...opts, watch: false }, {
                 watchMode: true,
-                onStatus,
+                onStatus: wrappedStatus,
                 gameIndex: reuseIndex,
                 onGameIndex: (idx) => {
                     gameIndexCache = idx;
@@ -188,17 +227,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;
@@ -219,7 +257,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,
@@ -267,6 +305,8 @@ async function watchLoop(opts) {
             }
         }
         finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
             inFlight = false;
         }
     };
@@ -311,13 +351,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 function nextBackoffForIdle(consecutiveIdleTicks, intervalSec, thresholds = { softSec: 180, hardSec: 900 }) {
-    const idleSeconds = consecutiveIdleTicks * intervalSec;
+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(idleSeconds, intervalSec, thresholds = IDLE_BACKOFF_THRESHOLDS) {
     if (idleSeconds >= thresholds.hardSec)
         return Math.max(intervalSec, 10);
     if (idleSeconds >= thresholds.softSec)
@@ -378,6 +425,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;
@@ -387,7 +439,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()
@@ -395,11 +453,35 @@ 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;
+    // Page-by-page progress: a first pull of thousands of sprites walks several
+    // pages, and a single static status line reads as a hang.
+    const onManifestProgress = (n) => {
+        const count = n.toLocaleString('en-US');
+        if (spinner)
+            spinner.text = `Fetching manifest… (${count})`;
+        else
+            onStatus?.(`Fetching your sprites from MagicPixel… (${count})`);
+    };
     try {
-        manifest = await fetchAllManifest(config, since);
+        let snapshot = await fetchManifestSnapshot(config, since, onManifestProgress);
+        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, onManifestProgress);
+        }
+        manifest = snapshot.entries;
+        removedRemoteKeys = snapshot.removedKeys;
         observedUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
         const projectSuffix = projectInfo && verbose
@@ -524,11 +606,19 @@ async function runOnce(opts, runOpts = {}) {
                 bytesIn: 0,
                 bytesSaved: 0,
                 renamed: [],
+                conflicts: [],
             };
-            if (observedUpdatedAt) {
-                const lastSync = state.lastSync && state.lastSync > observedUpdatedAt ? state.lastSync : observedUpdatedAt;
-                await saveState({ ...state, lastSync });
-            }
+            // 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;
         }
@@ -571,6 +661,7 @@ 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 ?? {};
@@ -614,13 +705,17 @@ async function runOnce(opts, runOpts = {}) {
         }
         const localSha = await fileSha256(pathFor(entry));
         shaByEntryId.set(entry.id, localSha);
-        const pull = shouldPullEntry({
+        const decision = decidePull({
             cloudSha256: entry.sha256,
             localSha256: localSha,
             previousCloudSha256,
+            lastPushedDiskSha256: synced[entry.key]?.diskSha256,
             inWorkingSet,
         });
-        if (!pull) {
+        if (decision === 'conflict') {
+            conflicts.push(entry.key);
+        }
+        else if (decision === 'skip') {
             unchanged++;
             if (entry.size_bytes)
                 bytesSaved += entry.size_bytes;
@@ -633,30 +728,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;
     }
@@ -716,15 +813,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
@@ -737,16 +839,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
@@ -799,6 +943,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.'));
@@ -818,6 +968,7 @@ async function runOnce(opts, runOpts = {}) {
             failed: 0,
             bytesIn: 0,
             bytesSaved,
+            conflicts,
         };
     }
     const result = {
@@ -829,6 +980,7 @@ async function runOnce(opts, runOpts = {}) {
         failed: 0,
         bytesIn: 0,
         bytesSaved,
+        conflicts,
     };
     let progress = null;
     if (live && toDownload.length > 0) {
@@ -1030,9 +1182,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;
@@ -1057,8 +1215,17 @@ 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
@@ -1082,9 +1249,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
@@ -1136,10 +1308,10 @@ async function runOnce(opts, runOpts = {}) {
             printRenames(renamed, { withHints: true });
     }
     onStatus?.('Checking your game files…');
-    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus);
+    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, onStatus) {
     if (pushEnabled === false)
@@ -1213,6 +1385,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):`));

package/dist/index.js

@@ -87,7 +87,7 @@ program
     .option('--no-prune', 'Keep local files not in the manifest (pruning is now on by default)')
     .option('--dry-run', 'Print the plan without writing files')
     .option('--full', 'Ignore lastSync state; re-fetch the full manifest')
-    .option('-w, --watch [seconds]', 'Poll for changes (default 2s; auto-slows to 5s after ~3min idle, 10s after ~15min)', parseWatchInterval)
+    .option('-w, --watch [seconds]', 'Poll for changes (default 2s; auto-slows to 5s after ~1min idle, 10s after ~5min)', parseWatchInterval)
     .option('-q, --quiet', 'Minimal output (for CI)')
     .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
     .addHelpText('after', '\nExamples:\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')

package/dist/util/localEdit.js

@@ -0,0 +1,29 @@
+/**
+ * "Was this PNG edited in the game project since we last wrote or pushed it?"
+ *
+ * The single definition of a local edit, used by two callers:
+ *
+ *   - `pullDecision` — an entry still in the manifest whose disk bytes diverged
+ *     is a conflict, not a download target.
+ *   - the prune sweep in `sync` — a path that LEFT the manifest (deselected
+ *     "Sync to Unity", trashed document, rename/previous-key cruft) must not be
+ *     deleted while it holds work MagicPixel has never seen.
+ *
+ * Without a recorded baseline (`state.synced[key].diskSha256`) we can't tell an
+ * edit from a file we never wrote, so we report "no edit" and let the caller's
+ * existing rules apply unchanged.
+ */
+import { fileSha256 } from './hash.js';
+/** Pure comparison — no filesystem access, safe for decision unit tests. */
+export function isLocalEdit(baselineDiskSha256, localSha256) {
+    if (!baselineDiskSha256 || !localSha256)
+        return false;
+    return baselineDiskSha256 !== localSha256;
+}
+/** Hashes `absPath` only when a baseline exists (nothing else can be an edit). */
+export async function hasUnpushedLocalEdit({ absPath, baselineDiskSha256, knownSha256, }) {
+    if (!baselineDiskSha256)
+        return false;
+    const sha = knownSha256 !== undefined ? knownSha256 : await fileSha256(absPath);
+    return isLocalEdit(baselineDiskSha256, sha);
+}

package/dist/util/pullDecision.js

@@ -6,25 +6,40 @@
  * library on every catch-up and overwrite the originals. Pull only when the
  * cloud composite actually changed since we last recorded it, or when there
  * is no local file to protect.
+ *
+ * Third outcome: `conflict`. `sync` pulls before it pushes, so a PNG edited on
+ * disk *and* in MagicPixel since the last sync would be overwritten before
+ * `push` ever sees it — the local edit would vanish with no message. When the
+ * disk bytes diverge from the fingerprint we recorded when we last wrote/pushed
+ * that file, the entry is reported instead of downloaded.
  */
-export function shouldPullEntry(opts) {
+import { isLocalEdit } from './localEdit.js';
+export function decidePull(opts) {
     const cloud = opts.cloudSha256 ?? null;
     const local = opts.localSha256;
     const prev = opts.previousCloudSha256;
     // Missing on disk → restore from cloud (MagicPixel-only art and deletions).
     if (!local)
-        return true;
+        return 'pull';
     if (cloud && cloud === local)
-        return false;
+        return 'skip';
     // Cloud composite unchanged since last pull/push — keep the original PNG.
     if (cloud && prev && cloud === prev)
-        return false;
+        return 'skip';
     if (opts.inWorkingSet) {
         // Never recorded a cloud hash: disk is the source of truth (connect/ingest).
         if (!prev)
-            return false;
+            return 'skip';
         // Editor save often nulls the cached hash; treat that as a cloud change.
-        return true;
+        return localEdit(opts) ? 'conflict' : 'pull';
     }
-    return true;
+    return localEdit(opts) ? 'conflict' : 'pull';
+}
+/**
+ * Disk bytes changed since we recorded them → someone edited the PNG in the
+ * game project. Without a recorded baseline we can't tell an edit from a file
+ * we never wrote, so we stay out of the way and let the pull proceed.
+ */
+function localEdit(opts) {
+    return isLocalEdit(opts.lastPushedDiskSha256, opts.localSha256);
 }

package/dist/util/reconcile.js

@@ -0,0 +1,23 @@
+/**
+ * When to promote an incremental sync to a full reconcile.
+ *
+ * `removed_keys` can only describe rows that still exist (trashed /
+ * componentized). A permanent delete ("Empty Trash") leaves nothing to report,
+ * so an incremental client keeps the PNG in the game project indefinitely. A
+ * periodic full pass — the manifest itself is the truth there — closes that
+ * without tombstone tables or per-tick cost.
+ */
+/** 15 minutes: bounded orphan lifetime, ~4 full manifests/hour worst case. */
+export const RECONCILE_INTERVAL_MS = 15 * 60 * 1000;
+export function shouldReconcile(lastReconcile, nowMs, intervalMs = RECONCILE_INTERVAL_MS) {
+    if (!lastReconcile)
+        return true;
+    const then = Date.parse(lastReconcile);
+    if (!Number.isFinite(then))
+        return true;
+    // Clock moved backwards (machine sleep / NTP step): reconcile rather than
+    // waiting out a bogus future timestamp.
+    if (then > nowMs)
+        return true;
+    return nowMs - then >= intervalMs;
+}

package/dist/util/security.js

@@ -88,15 +88,49 @@ export function tmpPathFor(diskPath) {
     const suffix = randomBytes(8).toString('hex');
     return `${diskPath}.${process.pid}.${suffix}.tmp`;
 }
+/**
+ * Deadline for a single request (JSON APIs: manifest, push, whoami, key
+ * validation). Without a deadline a stalled socket — sleeping laptop, dropped
+ * Wi-Fi, dead keep-alive connection — makes `fetch` hang forever, so
+ * `sync --watch` sits silently on one tick and never retries.
+ */
+export const REQUEST_TIMEOUT_MS = 45_000;
+/** Deadline for a PNG body, which can legitimately take much longer. */
+export const ASSET_TIMEOUT_MS = 120_000;
+function isAbortError(err) {
+    const name = err?.name;
+    return name === 'AbortError' || name === 'TimeoutError';
+}
 /**
  * Follow redirects only within the same origin as the initial request (prevents API key leak).
+ *
+ * Each hop gets a fresh deadline. The signal stays armed after the response
+ * headers arrive, so a stalled *body* read aborts too — that abort surfaces
+ * raw here and is relabelled as a transient network failure by `retryTransient`
+ * one layer up; only the connection attempt gets the friendly "didn't respond
+ * in time" wording. Callers that pass their own `init.signal` own their timing
+ * (e.g. `doctor`'s 5s probe).
  */
-export async function safeFetch(url, init = {}) {
+export async function safeFetch(url, init = {}, opts = {}) {
     const origin = new URL(url).origin;
+    const timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
     let current = url;
     for (let hop = 0; hop < 5; hop++) {
-        const res = await fetch(current, { ...init, redirect: 'manual' });
-        if (res.status < 300 || res.status >= 400)
+        const signal = init.signal ?? AbortSignal.timeout(timeoutMs);
+        let res;
+        try {
+            res = await fetch(current, { ...init, signal, redirect: 'manual' });
+        }
+        catch (e) {
+            if (!init.signal && isAbortError(e)) {
+                throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s — MagicPixel didn't respond in time.\n` +
+                    `  Fix: check your internet connection and that the MagicPixel API is reachable.`, { cause: e });
+            }
+            throw e;
+        }
+        // 304 lives in the 3xx range but is a conditional-request answer, not a
+        // redirect: it carries no Location and callers handle it directly.
+        if (res.status < 300 || res.status >= 400 || res.status === 304)
             return res;
         const location = res.headers.get('location');
         await res.body?.cancel();

package/dist/util/watchCopy.js

@@ -19,3 +19,23 @@ export function formatWatchSpriteLine(c) {
         return `   Sprites:  ${fmt(set)} in your game`;
     return `   Sprites:  ${fmt(pulled)}`;
 }
+/** How long a single watch tick may run before the heartbeat starts printing. */
+export const SLOW_TICK_HEARTBEAT_MS = 60_000;
+/**
+ * Heartbeat line for a tick that has outlived `SLOW_TICK_HEARTBEAT_MS`. Keeps
+ * the last status text so the user sees *what* is slow, not just that
+ * something is. Requests carry their own deadlines, so this always means slow.
+ */
+export function formatSlowTickLine(elapsedSec, lastStatus) {
+    const secs = Math.max(0, Math.round(elapsedSec));
+    const elapsed = secs >= 120 ? `${Math.round(secs / 60)}m` : `${secs}s`;
+    // "Fetching sprites… (1,200)" → "Fetching sprites (1,200)": the ellipsis and
+    // the heartbeat suffix would otherwise both claim the end of the line.
+    const what = lastStatus
+        ?.trim()
+        .replace(/[.…]+(\s*\([^()]*\))?$/, '$1')
+        .trim();
+    return what
+        ? `${what} — still working (${elapsed})`
+        : `Still working (${elapsed})`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.14",
+  "version": "0.5.21",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {