@magicpixelart/cli 0.5.20 → 0.5.22

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.22] — 2026-09-14
+
+- Raised the daily sprite download allowance from 1 GiB to 10 GiB for large
+  projects.
+- Daily allowance exhaustion now stops the current request with its UTC reset
+  time instead of sleeping inside `sync --watch` and appearing frozen. Short
+  burst limits continue to retry automatically.
+- `sync --watch` now reports an exhausted allowance once, with a countdown to
+  the reset, then re-checks every 15 minutes instead of retrying every minute
+  all night (each retry counted against the daily request allowance).
+- Allowance messages now say "API allowance" — the same limit covers requests
+  as well as downloaded bytes.
+
+## [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

package/dist/api.js

@@ -1,5 +1,5 @@
 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';
 /**
@@ -75,14 +75,21 @@ export class ApiError extends Error {
     status;
     requestId;
     retryAfterMs;
-    constructor(status, message, requestId, retryAfterMs) {
+    code;
+    constructor(status, message, requestId, retryAfterMs, code) {
         super(message);
         this.status = status;
         this.requestId = requestId;
         this.retryAfterMs = retryAfterMs;
+        this.code = code;
     }
 }
-function friendly(status, body, context) {
+export const DAILY_QUOTA_ERROR_CODE = 'daily_quota_exceeded';
+/** Stable API error code; the response body retains legacy text for old CLIs. */
+export function errorCodeFromResponse(res) {
+    return res.headers.get('x-magicpixel-error-code') ?? undefined;
+}
+export function friendlyApiError(status, body, context, code) {
     if (status === 401 || status === 403) {
         return (`${context}: ${status} — API key rejected.\n` +
             `  Fix: regenerate at https://magicpixel.art/settings and re-run \`${cmd('login')}\`.`);
@@ -92,6 +99,9 @@ function friendly(status, body, context) {
             `  Fix: check the "endpoint" field in magicpixel.json, or remove it to use the default.`);
     }
     if (status === 429) {
+        if (code === DAILY_QUOTA_ERROR_CODE) {
+            return `${context}: daily MagicPixel API allowance reached. Resets at 00:00 UTC.`;
+        }
         return `${context}: 429 — rate limited. Retry shortly.`;
     }
     if (status === 546) {
@@ -194,7 +204,8 @@ export async function fetchManifestPage(opts) {
             return data;
         }
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'manifest'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, 'manifest', errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     }, { max546Attempts: 7 });
 }
 const defaultRetrySleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -224,6 +235,10 @@ export async function retryTransient(context, fn, opts = {}) {
             if (err instanceof ApiError) {
                 if (err.status < 500 && err.status !== 429)
                     throw err;
+                // A daily allowance cannot recover during this request. In particular,
+                // never honour its hours-long Retry-After inside a single watch tick.
+                if (err.code === DAILY_QUOTA_ERROR_CODE)
+                    throw err;
                 lastErr = err;
                 nextDelayMs = err.retryAfterMs ?? 0;
             }
@@ -275,8 +290,13 @@ function compareSemver(a, b) {
     }
     return 0;
 }
-/** Full manifest walk, including the cloud's removal list. */
-export async function fetchManifestSnapshot(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;
@@ -292,6 +312,8 @@ export async function fetchManifestSnapshot(config, since) {
     for (let page = 0; page < MAX_PAGES; page++) {
         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)
@@ -328,7 +350,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.
@@ -338,7 +360,8 @@ export async function fetchAssetBytes(config, key, knownSha) {
         if (res.ok)
             return await readBodyWithLimit(res, MAX_ASSET_BYTES);
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, `download ${key}`), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, `download ${key}`, errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     });
 }
 /**
@@ -372,11 +395,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());
@@ -387,7 +409,8 @@ export async function pushSprites(sprites, retryOpts) {
             return results;
         }
         const bodyText = await res.text();
-        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'push'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, 'push', errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
     }, retryOpts);
 }
 function isTransientPushError(e) {

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 { fetchManifestSnapshot, fetchAssetBytes, ApiError, getLastProjectInfo, primeManifestEtags, manifestEtagsSnapshot } from '../api.js';
+import { fetchManifestSnapshot, fetchAssetBytes, ApiError, DAILY_QUOTA_ERROR_CODE, 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';
@@ -15,7 +15,7 @@ import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
 import { aliasCollisionKeys, collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
-import { applyUnityPullPolicy, isWorkingSetEntry, workingSetPullKeys } from '../util/unityFilter.js';
+import { applyUnityPullPolicy, isWorkingSetEntry, partitionWithheldEntries, workingSetPullKeys } from '../util/unityFilter.js';
 import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
@@ -23,7 +23,7 @@ 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 { 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';
@@ -116,6 +116,8 @@ async function watchLoop(opts) {
     // "back online" recovery line. Without this flag a user who walked away
     // during an outage has no signal that things are healthy again.
     let pausedForNetwork = false;
+    // Same idea for the daily API allowance: say it once, then wait quietly.
+    let pausedForQuota = false;
     // After this many consecutive 401/403s we give up and exit non-zero so a
     // parent process (Vite plugin, systemd, pm2) can tell the watcher is
     // genuinely broken (revoked key) rather than transiently blipped.
@@ -177,14 +179,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;
@@ -197,9 +216,11 @@ async function watchLoop(opts) {
             // another terminal is picked up automatically by the next tick.
             const wasPausedForAuth = pausedForAuth;
             const wasPausedForNetwork = pausedForNetwork;
+            const wasPausedForQuota = pausedForQuota;
             backoffSec = intervalSec;
             pausedForAuth = false;
             pausedForNetwork = false;
+            pausedForQuota = false;
             consecutiveAuthFailures = 0;
             if (wasPausedForAuth && !opts.quiet) {
                 process.stdout.write('\x1b[2K\r');
@@ -209,6 +230,10 @@ async function watchLoop(opts) {
                 process.stdout.write('\x1b[2K\r');
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Back online — resuming.`);
             }
+            if (wasPausedForQuota && !wasPausedForAuth && !wasPausedForNetwork && !opts.quiet) {
+                process.stdout.write('\x1b[2K\r');
+                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Daily allowance available again — resuming.`);
+            }
             const changedCount = r.added.length + r.modified.length + r.removed.length + r.renamed.length;
             // 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
@@ -245,6 +270,7 @@ async function watchLoop(opts) {
                 backoffSec,
                 pausedForAuth,
                 pausedForNetwork,
+                pausedForQuota,
                 consecutiveAuthFailures,
                 maxAuthFailures: MAX_AUTH_FAILURES,
             });
@@ -280,6 +306,17 @@ async function watchLoop(opts) {
                 pausedForNetwork = true;
                 backoffSec = decision.nextBackoffSec;
             }
+            else if (decision.kind === 'quota') {
+                consecutiveAuthFailures = 0;
+                if (decision.printMessage) {
+                    const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
+                    console.log(`${kleur.dim(timestamp())} ${kleur.yellow('!')} Daily MagicPixel API allowance reached. ` +
+                        `Sprites you already have still work. Resets in ${formatQuotaReset(decision.resetSec)} ` +
+                        `(00:00 UTC); checking again every ${Math.max(1, Math.round(decision.nextBackoffSec / 60))} min.${idSuffix}`);
+                }
+                pausedForQuota = true;
+                backoffSec = decision.nextBackoffSec;
+            }
             else {
                 consecutiveAuthFailures = 0;
                 const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
@@ -288,6 +325,8 @@ async function watchLoop(opts) {
             }
         }
         finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
             inFlight = false;
         }
     };
@@ -352,6 +391,19 @@ export function nextBackoffForIdle(idleSeconds, intervalSec, thresholds = IDLE_B
         return Math.max(intervalSec, 5);
     return intervalSec;
 }
+/**
+ * Longest quiet wait while the daily allowance is exhausted. The allowance
+ * resets at UTC midnight, but we re-check periodically so a raised cap (or a
+ * clock/timezone surprise) is picked up without restarting the watcher.
+ */
+export const QUOTA_RECHECK_MAX_SEC = 900;
+/** Human reset countdown: "42 min" / "3h 05m". */
+export function formatQuotaReset(resetSec) {
+    const mins = Math.max(1, Math.round(resetSec / 60));
+    if (mins < 60)
+        return `${mins} min`;
+    return `${Math.floor(mins / 60)}h ${String(mins % 60).padStart(2, '0')}m`;
+}
 /**
  * Pure helper: classify a per-tick error and compute the next backoff +
  * counter updates. Extracted so the auth-failure watchdog and the
@@ -372,6 +424,17 @@ export function classifyTickError(err, state) {
             giveUp: next >= state.maxAuthFailures,
         };
     }
+    if (apiErr?.code === DAILY_QUOTA_ERROR_CODE) {
+        // Nothing recovers until the allowance resets, so stop hammering: each
+        // retry still burns a request against the daily request allowance.
+        const resetSec = Math.max(1, Math.round((apiErr.retryAfterMs ?? 0) / 1000));
+        return {
+            kind: 'quota',
+            nextBackoffSec: Math.min(QUOTA_RECHECK_MAX_SEC, resetSec),
+            printMessage: !state.pausedForQuota,
+            resetSec,
+        };
+    }
     if (isNetworkError(err)) {
         const nextBackoffSec = Math.min(state.backoffSec * 2, 60);
         // Print on the first offline tick, then again whenever backoff changes —
@@ -434,14 +497,25 @@ async function runOnce(opts, runOpts = {}) {
     if (!spinner)
         onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
+    /** In-scope documents withheld by the server (unreleased edits): hold-only. */
+    let withheldEntries = [];
     // 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 {
-        let snapshot = await fetchManifestSnapshot(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
@@ -450,11 +524,18 @@ async function runOnce(opts, runOpts = {}) {
                 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);
+            snapshot = await fetchManifestSnapshot(config, undefined, onManifestProgress);
         }
-        manifest = snapshot.entries;
+        // Documents the user hasn't released with the editor's Sync button are
+        // listed but not syncable: they stay out of every pull/prune decision and
+        // only protect what's already on disk (see `withheldDirs` below).
+        const partitioned = partitionWithheldEntries(snapshot.entries);
+        manifest = partitioned.entries;
+        withheldEntries = partitioned.withheld;
         removedRemoteKeys = snapshot.removedKeys;
-        observedUpdatedAt = maxIsoTimestamp(manifest.map((e) => e.updated_at));
+        // Cursor advances past withheld rows too — they are re-listed whenever the
+        // user presses Sync (the release bumps `updated_at`).
+        observedUpdatedAt = maxIsoTimestamp(snapshot.entries.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
@@ -519,6 +600,18 @@ async function runOnce(opts, runOpts = {}) {
             (connected.capped ? ` of ${connected.total} matched` : '')));
     }
     const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
+    // Every folder on disk that belongs to a withheld document. Anything already
+    // written there is held as-is: unreleased edits must never pull, and a full
+    // reconcile must never read the absence of these entries as "deleted".
+    const withheldDirs = new Set();
+    for (const entry of withheldEntries) {
+        try {
+            withheldDirs.add(dirname(pathForKey(entry.key)));
+        }
+        catch {
+            /* unusable key — nothing to protect */
+        }
+    }
     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
@@ -721,10 +814,17 @@ async function runOnce(opts, runOpts = {}) {
     // Sprites created in Unity (or any PNG we never pulled) are pending a
     // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
+        const protectedPaths = new Set(unknownFlagPaths);
+        if (withheldDirs.size > 0) {
+            for (const local of localPngs) {
+                if (withheldDirs.has(dirname(local.abs)))
+                    protectedPaths.add(local.abs);
+            }
+        }
         const policy = selectFullSyncOrphans({
             localPaths: localPngs.map((a) => a.abs),
             remoteDiskPaths,
-            protectedPaths: unknownFlagPaths,
+            protectedPaths,
             isTracked: (p) => keyByPath.has(p),
         });
         orphans = policy.orphans;
@@ -789,6 +889,9 @@ async function runOnce(opts, runOpts = {}) {
     // local-edit guard applied below. De-duplicates vs the full-sync orphan list.
     const orphanSet = new Set(orphans);
     const addOrphan = (p) => {
+        // Withheld documents are held whole: no prune source may touch them.
+        if (withheldDirs.has(dirname(p)))
+            return;
         if (existsSync(p) && isPathInside(p, outRoot))
             orphanSet.add(p);
     };
@@ -889,6 +992,12 @@ async function runOnce(opts, runOpts = {}) {
         if (e.folder)
             knownFolderSlugs.add(e.folder.split('/')[0]);
     }
+    // Withheld docs are absent from `manifest` — without their slugs a sibling
+    // folder like `tiles-2/` would read as a legacy suffix collision.
+    for (const e of withheldEntries) {
+        if (e.folder)
+            knownFolderSlugs.add(e.folder.split('/')[0]);
+    }
     for (const key of Object.values(previousAssets)) {
         const top = key.split('/')[0];
         if (top)

package/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
-import { ApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
+import { ApiError, errorCodeFromResponse, friendlyApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 export async function whoamiCommand() {
@@ -32,9 +32,10 @@ export async function whoamiCommand() {
         }
         if (res.status >= 500 || res.status === 429) {
             const bodyText = await res.text();
+            const errorCode = errorCodeFromResponse(res);
             // Pass Retry-After through so retryTransient honours server back-pressure
             // (matches fetchManifestPage / fetchAssetBytes).
-            throw new ApiError(res.status, bodyText.slice(0, 200), serverRequestId, retryAfterMsFromResponse(res));
+            throw new ApiError(res.status, friendlyApiError(res.status, bodyText, 'whoami', errorCode), serverRequestId, retryAfterMsFromResponse(res), errorCode);
         }
         if (!res.ok) {
             const bodyText = await res.text();

package/dist/util/auth.js

@@ -1,5 +1,5 @@
 import { resolveEndpoint } from '../config.js';
-import { ApiError, retryTransient } from '../api.js';
+import { ApiError, errorCodeFromResponse, friendlyApiError, retryAfterMsFromResponse, retryTransient } from '../api.js';
 import { safeFetch, readBodyWithLimit } from './security.js';
 import { authHeaders } from './authHeaders.js';
 /**
@@ -32,9 +32,10 @@ export async function assertKeyValid(key, config) {
             // we ultimately surface.
             const bodyBytes = await readBodyWithLimit(res, 16 * 1024).catch(() => new Uint8Array());
             const body = new TextDecoder().decode(bodyBytes);
+            const errorCode = errorCodeFromResponse(res);
             // 5xx + 429 retry through retryTransient; other 4xx bubble immediately.
-            throw new ApiError(res.status, `Server returned ${res.status}: ${body.slice(0, 120)}\n` +
-                `  (request id: ${serverRequestId})`, serverRequestId);
+            throw new ApiError(res.status, `${friendlyApiError(res.status, body, 'validate key', errorCode)}\n` +
+                `  (request id: ${serverRequestId})`, serverRequestId, retryAfterMsFromResponse(res), errorCode);
         }
         await res.body?.cancel();
     });

package/dist/util/security.js

@@ -88,14 +88,46 @@ 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' });
+        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)

package/dist/util/unityFilter.js

@@ -18,14 +18,27 @@
  * layer JSON dropped `syncToUnity`). Those saves must still write back to
  * the original PNG.
  */
+/**
+ * Split the manifest into syncable entries and withheld ones. Withheld entries
+ * are never pull candidates (not even under `unitySyncAll`) and carry no bytes;
+ * callers use them only to protect what's already on disk from pruning.
+ */
+export function partitionWithheldEntries(manifest) {
+    const withheld = [];
+    const entries = [];
+    for (const e of manifest)
+        (e.withheld === true ? withheld : entries).push(e);
+    return { entries, withheld };
+}
 export function filterUnityManifest(manifest, opts = {}) {
+    const syncable = partitionWithheldEntries(manifest).entries;
     if (opts.syncAll)
-        return { entries: manifest, noneFlagged: false, unknown: [] };
-    const entries = manifest.filter((e) => e.unity === true);
-    const unknown = manifest.filter((e) => typeof e.unity !== 'boolean');
+        return { entries: syncable, noneFlagged: false, unknown: [] };
+    const entries = syncable.filter((e) => e.unity === true);
+    const unknown = syncable.filter((e) => typeof e.unity !== 'boolean');
     return {
         entries,
-        noneFlagged: manifest.length > 0 && entries.length === 0,
+        noneFlagged: syncable.length > 0 && entries.length === 0,
         unknown,
     };
 }
@@ -65,7 +78,9 @@ export function applyUnityPullPolicy(manifest, opts = {}) {
     if (opts.syncAll || !opts.alwaysPull)
         return filtered;
     const already = new Set(filtered.entries);
-    const extra = manifest.filter((e) => !already.has(e) && opts.alwaysPull(e));
+    // Withheld entries stay out: a working-set sprite the user hasn't released
+    // must not be pulled over the copy in the game project.
+    const extra = partitionWithheldEntries(manifest).entries.filter((e) => !already.has(e) && opts.alwaysPull(e));
     if (extra.length === 0)
         return filtered;
     const extraSet = new Set(extra);

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.20",
+  "version": "0.5.22",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {