emdash-emit 0.1.13 → 0.1.15

package/dist/sync/doctor.js

@@ -24,29 +24,88 @@ import path from 'node:path';
 import yaml from 'js-yaml';
 import { getPackageVersion } from '../utils/version.js';
 import { parseMarkdown, lenientRepairMarkdownFrontmatter } from '../utils/frontmatter.js';
+import { storageKeyToMarkdownRef } from '../utils/naming.js';
 import { listConflicts } from './conflicts.js';
 import { getWorkspaceStatus } from './status.js';
 import { calculateHash } from './pull.js';
+import { collectRemoteStorageKeys, storageKeyFromMediaMeta, } from './media.js';
 import { checkMcpProcess } from '../mcp/heartbeat.js';
+import { VALID_MEDIA_FILE_KEY, MEDIA_FILE_ROUTE_PREFIX, FENCE_POLICY, isCodeFenceDelimiter, } from '../utils/media-refs.js';
+/**
+ * Counts the media assets this workspace actually mirrors: canonical binaries under `media/`, excluding
+ * `drafts/` staging and the `legacy_*` residue that backs no real record.
+ */
+function countMirroredMedia(mediaDir) {
+    if (!fs.existsSync(mediaDir))
+        return 0;
+    let count = 0;
+    for (const file of fs.readdirSync(mediaDir)) {
+        if (file.endsWith('.yaml') || file.startsWith('legacy_'))
+            continue;
+        if (!fs.statSync(path.join(mediaDir, file)).isFile())
+            continue;
+        count++;
+    }
+    return count;
+}
+/** Any storageKey-style ULID appearing inside a media file URL. */
+const MEDIA_ULID_IN_URL = /[0-9A-HJ-NP-Z]{26}/g;
+/** True when the captured image markup sits inside an inline code span on the same line. */
+function isInlineCodeSpan(line, matchText, matchIndex) {
+    if (line.includes('`' + matchText))
+        return true;
+    const first = line.indexOf('`');
+    return first !== -1 && first < matchIndex && matchIndex < line.lastIndexOf('`');
+}
+/**
+ * Classify a captured media URL. Anything that cannot name a real asset (template placeholders, or
+ * a key polluted by leaked markup) is reported separately so it never counts as missing media.
+ */
+function classifyMediaUrl(url) {
+    if (url.includes('<') || url.includes('>') || url.includes('${'))
+        return 'placeholder';
+    const keyMatch = url.match(/(?:^|\/)media\/file\/([^?#]*)/);
+    if (!keyMatch)
+        return 'valid'; // a plain local path: resolved by filesystem checks instead
+    if (VALID_MEDIA_FILE_KEY.test(keyMatch[1]))
+        return 'valid';
+    // A ULID is present but the captured key is polluted by leaked markup, as in the real legacy
+    // body line `![alt](/_emdash/api/media/file/<ULID>.jpg" control=true)`. The asset itself still
+    // resolves through the ULID, so only the surrounding capture is treated as residue.
+    return MEDIA_ULID_IN_URL.test(keyMatch[1]) ? 'valid' : 'invalid';
+}
 /**
  * Scans article markdown to separate standard body image references from
- * informational references (code blocks, inline code, HTML comments, or placeholder URLs).
+ * informational references (code blocks, inline code, HTML comments, opaque custom-block fences,
+ * or placeholder URLs) and from structurally invalid captures.
  */
 export function scanArticleMediaDetailed(bodyMarkdown) {
     const normalRefs = new Set();
     const informationalRefs = new Set();
+    const invalidRefs = new Set();
     const lines = bodyMarkdown.split('\n');
     let inFence = false;
     let fenceDelimiter = '';
+    // EmDash serializes unknown Portable Text blocks as single-line opaque fences
+    // (`<!--ec:block {...} -->`). Their embedded JSON may contain media URLs that belong to the
+    // remote block, not to editable markdown, so they must never be reported as missing.
+    let inOpaqueFence = false;
     for (const line of lines) {
         const trimmed = line.trim();
+        if (/^<!--ec:block\s/.test(trimmed)) {
+            inOpaqueFence = !/^.*-->$/.test(trimmed);
+            continue;
+        }
+        if (inOpaqueFence)
+            continue;
         // Note: Doctor treats both backticks and tildes (~~~) as fences for diagnostic
         // reporting to avoid false warnings on code examples, whereas push guards (G5/G11)
         // strictly exempt only backtick fences per AGENTS.md.
-        if (trimmed.startsWith('```') || trimmed.startsWith('~~~')) {
+        const delim = isCodeFenceDelimiter(trimmed, FENCE_POLICY.diagnostic);
+        if (delim) {
             if (!inFence) {
                 inFence = true;
-                fenceDelimiter = trimmed.slice(0, 3);
+                fenceDelimiter = delim;
                 continue;
             }
             else if (trimmed.startsWith(fenceDelimiter)) {
@@ -60,12 +119,13 @@ export function scanArticleMediaDetailed(bodyMarkdown) {
         while ((match = mdRegex.exec(line)) !== null) {
             const url = match[1].trim();
             if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('data:')) {
-                const isPlaceholder = url.includes('<') && url.includes('>');
-                const isInlineCode = line.includes('`' + match[0]) ||
-                    (line.indexOf('`') !== -1 &&
-                        line.indexOf('`') < match.index &&
-                        match.index < line.lastIndexOf('`'));
-                if (inFence || isInlineCode || isPlaceholder) {
+                const kind = classifyMediaUrl(url);
+                if (kind === 'invalid') {
+                    invalidRefs.add(url);
+                }
+                else if (inFence ||
+                    isInlineCodeSpan(line, match[0], match.index) ||
+                    kind === 'placeholder') {
                     informationalRefs.add(url);
                 }
                 else {
@@ -78,8 +138,11 @@ export function scanArticleMediaDetailed(bodyMarkdown) {
         while ((match = htmlRegex.exec(line)) !== null) {
             const url = match[1].trim();
             if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('data:')) {
-                const isPlaceholder = url.includes('<') && url.includes('>');
-                if (inFence || isPlaceholder || line.includes('<!--')) {
+                const kind = classifyMediaUrl(url);
+                if (kind === 'invalid') {
+                    invalidRefs.add(url);
+                }
+                else if (inFence || kind === 'placeholder' || line.includes('<!--')) {
                     informationalRefs.add(url);
                 }
                 else {
@@ -87,10 +150,22 @@ export function scanArticleMediaDetailed(bodyMarkdown) {
                 }
             }
         }
+        // Legacy WordPress-derived custom container lines that survived the migration, e.g.
+        // `[dimage url="/_emdash/api/media/file/<ULID>.jpg" control=true]`. The URL is quoted inside
+        // the line, so the regexes above cannot capture it; a trailing attribute or bracket marks the
+        // capture as markup residue rather than a real asset reference.
+        const legacyContainerRegex = /\[([a-z]+)\s+url=["']?([^"'\s\]]+)["']?[^\]]*\]/gi;
+        while ((match = legacyContainerRegex.exec(line)) !== null) {
+            const url = match[2].trim();
+            if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('data:')) {
+                informationalRefs.add(url);
+            }
+        }
     }
     return {
         normalRefs: Array.from(normalRefs).sort(),
         informationalRefs: Array.from(informationalRefs).sort(),
+        invalidRefs: Array.from(invalidRefs).sort(),
     };
 }
 /**
@@ -138,6 +213,7 @@ export async function runWorkspaceDoctor(options) {
     }
     // 3. Frontmatter Syntax & Schema Integrity Check
     const invalidFiles = [];
+    const healableFiles = [];
     let totalArticles = 0;
     for (const status of ['draft', 'published']) {
         const dir = path.join(options.workspaceRoot, collection, status);
@@ -157,6 +233,7 @@ export async function runWorkspaceDoctor(options) {
                     const healed = lenientRepairMarkdownFrontmatter(content);
                     if (healed) {
                         parseMarkdown(healed);
+                        healableFiles.push(path.join(collection, status, file));
                     }
                     else {
                         throw new Error('Unrecoverable parse error');
@@ -177,6 +254,15 @@ export async function runWorkspaceDoctor(options) {
             details: invalidFiles,
         });
     }
+    else if (healableFiles.length > 0) {
+        checks.push({
+            id: 'frontmatter_integrity',
+            name: 'Frontmatter Integrity',
+            status: 'warning',
+            message: `${healableFiles.length} article(s) have invalid frontmatter YAML that Emit can repair automatically. Run "emit pull" (syntax-only re-quoting; local body is strictly preserved).`,
+            details: healableFiles,
+        });
+    }
     else {
         checks.push({
             id: 'frontmatter_integrity',
@@ -210,44 +296,109 @@ export async function runWorkspaceDoctor(options) {
             message: `No unresolved conflicts or rescue backups in ${collection}/conflicts/.`,
         });
     }
-    // 4b. Taxonomy Conflict Pending Alignment
+    // 4b. Conflict Pending Alignment & Auditing
     const allStates = options.cache.getAllSyncStates();
-    const pendingStates = allStates.filter((s) => s.conflictPending === 1);
-    const autoClearedSlugs = [];
-    const manualResolutionRequired = [];
-    for (const state of pendingStates) {
-        const hasConflictCopy = conflictItems.some((c) => c.id === state.id || c.slug === state.slug);
+    const autoClearedBodySlugs = [];
+    const autoClearedTaxSlugs = [];
+    const manualBodySlugs = [];
+    const manualTaxSlugs = [];
+    const conflictMarkerRegex = /^<{7}\s|^={7}$|^>{7}\s/m;
+    for (const state of allStates) {
         const fullPath = path.join(options.workspaceRoot, state.localFilePath);
+        let diskContent = null;
         let hasDivergence = true;
+        let hasBodyMarkers = false;
         if (fs.existsSync(fullPath)) {
-            const diskHash = calculateHash(fs.readFileSync(fullPath, 'utf8'));
+            diskContent = fs.readFileSync(fullPath, 'utf8');
+            const diskHash = calculateHash(diskContent);
             hasDivergence = diskHash !== state.localHash;
+            hasBodyMarkers = conflictMarkerRegex.test(diskContent);
         }
-        if (!hasConflictCopy && !hasDivergence) {
-            // Auto-clear: no conflict copy and no divergence
-            options.cache.setConflictPending(state.id, false);
-            autoClearedSlugs.push(state.slug);
+        // Check body conflict pending
+        if (state.bodyConflictPending === 1) {
+            const hasConflictCopy = conflictItems.some((c) => (c.id === state.id || c.slug === state.slug) &&
+                (c.type === 'conflict' ||
+                    c.type === 'dropped' ||
+                    c.filePath.endsWith('.conflict.md') ||
+                    c.filePath.endsWith('.local-dropped.md')));
+            if (!hasConflictCopy && !hasDivergence && !hasBodyMarkers) {
+                options.cache.clearConflictsByKind(state.id, 'body');
+                autoClearedBodySlugs.push(state.slug);
+            }
+            else {
+                manualBodySlugs.push(state.slug);
+            }
         }
-        else {
-            manualResolutionRequired.push(state.slug);
+        // Check taxonomy conflict pending
+        if (state.taxonomyConflictPending === 1) {
+            const hasConflictCopy = conflictItems.some((c) => c.id === state.id || c.slug === state.slug);
+            if (!hasConflictCopy && !hasDivergence) {
+                options.cache.clearConflictsByKind(state.id, 'taxonomy');
+                autoClearedTaxSlugs.push(state.slug);
+            }
+            else {
+                manualTaxSlugs.push(state.slug);
+            }
         }
     }
-    if (autoClearedSlugs.length > 0) {
+    const totalAutoCleared = autoClearedBodySlugs.length + autoClearedTaxSlugs.length;
+    if (totalAutoCleared > 0) {
         checks.push({
             id: 'conflict_pending_autoclear',
             name: 'Conflict Pending Auto-Clear',
             status: 'ok',
-            message: `Automatically cleared stale conflict_pending flag for ${autoClearedSlugs.length} article(s) (no conflict copies and no divergence).`,
-            details: autoClearedSlugs,
+            message: `Automatically cleared stale conflict_pending flag for ${totalAutoCleared} pending record(s) (no conflict copies and no divergence).`,
+            details: [...new Set([...autoClearedBodySlugs, ...autoClearedTaxSlugs])],
+        });
+    }
+    if (manualBodySlugs.length > 0) {
+        checks.push({
+            id: 'body_conflict_pending_manual',
+            name: 'Body Conflict Pending',
+            status: 'warning',
+            message: `${manualBodySlugs.length} article(s) have pending body conflicts. Resolve conflict markers in the file or run "emit conflicts diff / resolve".`,
+            details: manualBodySlugs,
         });
     }
-    if (manualResolutionRequired.length > 0) {
+    if (manualTaxSlugs.length > 0) {
         checks.push({
             id: 'conflict_pending_manual',
             name: 'Taxonomy Conflict Pending',
             status: 'warning',
-            message: `${manualResolutionRequired.length} article(s) have pending taxonomy conflicts with existing rescue copies or unpushed edits. Run "emit push <file> --resolve-taxonomy=union|local|remote" to resolve.`,
-            details: manualResolutionRequired,
+            message: `${manualTaxSlugs.length} article(s) have pending taxonomy conflicts with existing rescue copies or unpushed edits. Run "emit push <file> --resolve-taxonomy=union|local|remote" to resolve.`,
+            details: manualTaxSlugs,
+        });
+    }
+    // 4c. Taxonomy Apply Pending Check
+    const taxApplyPendingStates = allStates.filter((s) => s.taxonomyApplyPending === 1);
+    if (taxApplyPendingStates.length > 0) {
+        checks.push({
+            id: 'taxonomy_apply_pending',
+            name: 'Taxonomy Apply Pending',
+            status: 'warning',
+            message: `${taxApplyPendingStates.length} article(s) have unapplied taxonomy terms from a previous failed sync.`,
+            suggestion: 'Run "emit pull-taxonomies", verify the terms exist on remote (missing terms or permission errors must be fixed there first), then "emit push <file>".',
+            details: taxApplyPendingStates.map((s) => ({
+                id: s.id,
+                slug: s.slug,
+                filePath: s.localFilePath,
+            })),
+        });
+    }
+    // 4d. Delete Pending Check
+    const deletePendingStates = allStates.filter((s) => s.deletePending === 1);
+    if (deletePendingStates.length > 0) {
+        checks.push({
+            id: 'delete_pending',
+            name: 'Delete Pending Articles',
+            status: 'warning',
+            message: `${deletePendingStates.length} article(s) are marked as delete_pending (unconfirmed remote deletion).`,
+            suggestion: 'Confirm the remote deletion, then "emit delete <file>" to finish local cleanup, or "emit push <file> --revive" to intentionally revive.',
+            details: deletePendingStates.map((s) => ({
+                id: s.id,
+                slug: s.slug,
+                filePath: s.localFilePath,
+            })),
         });
     }
     // 5. Sync Status & Pending Modifications Check
@@ -276,32 +427,56 @@ export async function runWorkspaceDoctor(options) {
         });
     }
     // 6. Media References Integrity Check
-    // Index all local media companion YAMLs and files to resolve both local paths and storageKey URLs (D1)
+    // Index every local resolution source so a body URL can be matched even when the companion YAML
+    // is missing its storageKey field, which is common for legacy corpora (D1)
     const mediaDir = path.join(options.workspaceRoot, 'media');
     const knownStorageKeys = new Set();
     const knownMediaIds = new Set();
     const knownLocalFiles = new Set();
+    // StorageKey-derived stems of mirrored assets. A body URL carries the storageKey, and a mirror is now
+    // named after exactly that key, so the stem — not a filename tail parsed out of an id-based name — is
+    // what lets `/_emdash/api/media/file/<storageKey>` resolve to a file on disk.
+    const knownMediaStems = new Set();
     if (fs.existsSync(mediaDir)) {
         const mediaFiles = fs.readdirSync(mediaDir);
         for (const f of mediaFiles) {
             knownLocalFiles.add(f);
             knownLocalFiles.add(path.posix.join('media', f));
+            if (f.startsWith('legacy_')) {
+                // Leftover mirrors from the removed file-route fallback must never feed the known-storageKey
+                // or known-media-id sets: they back no real media record, so a body referencing them stays a
+                // missing-file warning and `--check-media-urls` can still downgrade it to a served note.
+                continue;
+            }
             if (f.endsWith('.yaml')) {
                 try {
                     const doc = yaml.load(fs.readFileSync(path.join(mediaDir, f), 'utf8'));
                     if (doc) {
-                        if (typeof doc.storageKey === 'string' && doc.storageKey) {
-                            knownStorageKeys.add(doc.storageKey);
-                        }
                         if (typeof doc.id === 'string' && doc.id) {
                             knownMediaIds.add(doc.id);
                         }
+                        // The storageKey field is missing on older mirrors, but their `url:` still names the key,
+                        // so both forms count as confirmed local metadata.
+                        const metaKey = storageKeyFromMediaMeta(doc);
+                        if (metaKey)
+                            knownStorageKeys.add(metaKey);
                     }
                 }
                 catch {
                     // ignore corrupted individual yaml
                 }
             }
+            else {
+                // media/<markdownRef>.<ext>: the stem is the sanitized storageKey, so it is recorded whole and
+                // matched against the key a body URL carries. Legacy id-based names stay readable too, because a
+                // workspace that has not been re-pulled yet still holds them.
+                const stem = f.replace(/\.[^.]+$/, '');
+                knownMediaStems.add(stem);
+                knownMediaStems.add(stem.replace(/^\d{8}_/, ''));
+                const dash = stem.indexOf('-');
+                if (dash !== -1)
+                    knownMediaStems.add(stem.slice(dash + 1));
+            }
         }
         const draftsDir = path.join(mediaDir, 'drafts');
         if (fs.existsSync(draftsDir)) {
@@ -311,8 +486,48 @@ export async function runWorkspaceDoctor(options) {
             }
         }
     }
+    // Cache-backed fallbacks: media_state records the confirmed storageKey of every asset Emit
+    // uploaded, and base snapshots preserve the remote featured_image object (which carries
+    // meta.storageKey) for articles whose local frontmatter only holds the media record id.
+    for (const record of options.cache.listMediaStates()) {
+        if (record.storageKey)
+            knownStorageKeys.add(record.storageKey);
+        if (record.mediaId)
+            knownMediaIds.add(record.mediaId);
+    }
+    const knownFeaturedStorageKeys = new Set();
+    for (const state of options.cache.getAllSyncStates()) {
+        const snapshot = options.cache.getBaseSnapshot(state.id);
+        if (!snapshot?.frontmatterYaml)
+            continue;
+        try {
+            const fm = JSON.parse(snapshot.frontmatterYaml);
+            const fi = fm.featuredImage ?? fm.featured_image;
+            const meta = fi?.meta;
+            if (typeof meta?.storageKey === 'string' && meta.storageKey) {
+                knownFeaturedStorageKeys.add(meta.storageKey);
+            }
+        }
+        catch {
+            // baseline frontmatter is JSON-encoded by contract; ignore unreadable snapshots
+        }
+    }
     const missingMedia = [];
+    // References that survived every local fallback yet are still served by the public file route. The
+    // live HEAD (only when --check-media-urls is set) proves the R2 object exists; it says nothing about
+    // whether a D1 record exists, because the probe addresses the storageKey and not the primary key.
+    const verifiedFileRouteOnly = [];
+    const unreachableFileRoute = [];
     const informationalUnresolved = [];
+    const invalidMediaRefs = [];
+    // Candidates that survived every local fallback; probed live only when checkMediaUrls is enabled.
+    const pendingRemoteProbes = [];
+    const probeKey = (ref) => {
+        const m = ref.match(/(?:^|\/)media\/file\/([^?#]+)/);
+        if (!m)
+            return null;
+        return VALID_MEDIA_FILE_KEY.test(m[1]) ? m[1] : null;
+    };
     for (const status of ['draft', 'published']) {
         const dir = path.join(options.workspaceRoot, collection, status);
         if (!fs.existsSync(dir))
@@ -327,38 +542,160 @@ export async function runWorkspaceDoctor(options) {
                     const storageKeyMatch = ref.match(/(?:^|\/)media\/file\/([^?#]+)/);
                     if (storageKeyMatch) {
                         const key = storageKeyMatch[1];
-                        return knownStorageKeys.has(key);
+                        if (knownStorageKeys.has(key))
+                            return true;
+                        // The body URL may carry the media record id instead of the storageKey, or a key whose
+                        // companion YAML lacks the field: resolve by ULID, then by the mirror stem that names the key.
+                        const ulidMatch = key.match(/[0-9A-HJ-NP-Z]{26}/);
+                        if (ulidMatch && knownMediaIds.has(ulidMatch[0].toUpperCase()))
+                            return true;
+                        const keyStem = storageKeyToMarkdownRef(key);
+                        if (keyStem && knownMediaStems.has(keyStem))
+                            return true;
+                        for (const stem of knownMediaStems) {
+                            if (key.endsWith(stem))
+                                return true;
+                        }
+                        return knownFeaturedStorageKeys.has(key);
                     }
                     // Check 2: Direct relative or local filesystem path
                     const cleanRef = ref.replace(/^[./]+/, '');
                     const directFull = path.isAbsolute(ref) ? ref : path.join(options.workspaceRoot, ref);
-                    return (fs.existsSync(directFull) || knownLocalFiles.has(ref) || knownLocalFiles.has(cleanRef));
+                    if (fs.existsSync(directFull) ||
+                        knownLocalFiles.has(ref) ||
+                        knownLocalFiles.has(cleanRef)) {
+                        return true;
+                    }
+                    // Check 3: A local mirror reference (`../../media/<storageKey>` or the older depth-free
+                    // `media/<storageKey>`) names the key outright, so a collision-suffixed or truncated mirror stem
+                    // leaves no file at that exact path. Resolve it through
+                    // the same confirmed-key and stem indexes Check 1 uses instead of reporting a mirrored asset missing.
+                    const localKeyMatch = cleanRef.match(/^media\/([^?#]+)/);
+                    if (localKeyMatch) {
+                        const key = localKeyMatch[1];
+                        if (knownStorageKeys.has(key))
+                            return true;
+                        const keyStem = storageKeyToMarkdownRef(key);
+                        if (keyStem && knownMediaStems.has(keyStem))
+                            return true;
+                    }
+                    return false;
                 };
                 for (const ref of detailed.normalRefs) {
-                    if (!checkRef(ref)) {
-                        missingMedia.push(`${ref} (referenced by ${path.join(collection, status, file)})`);
+                    if (checkRef(ref))
+                        continue;
+                    const source = path.join(collection, status, file);
+                    const key = options.checkMediaUrls ? probeKey(ref) : null;
+                    if (key) {
+                        pendingRemoteProbes.push({ ref, key, source });
+                    }
+                    else {
+                        missingMedia.push(`${ref} (referenced by ${source})`);
                     }
                 }
                 for (const ref of detailed.informationalRefs) {
                     if (!checkRef(ref)) {
-                        informationalUnresolved.push(`${ref} (code-example/placeholder in ${path.join(collection, status, file)})`);
+                        informationalUnresolved.push(`${ref} (code-example/custom-block in ${path.join(collection, status, file)})`);
                     }
                 }
+                for (const ref of detailed.invalidRefs) {
+                    invalidMediaRefs.push(`${ref} (malformed reference in ${path.join(collection, status, file)})`);
+                }
             }
             catch {
                 // Skip unreadable files
             }
         }
     }
+    // Live file-route probe: legacy migrated assets can still be served by /_emdash/api/media/file/
+    // even though their media record returns 404, so confirm them against the origin instead of
+    // reporting them as missing files that pull-media cannot fetch.
+    if (options.checkMediaUrls && pendingRemoteProbes.length > 0) {
+        const origin = options.profileOrigin || options.config.origin;
+        const probeFetch = options.fetchFn || globalThis.fetch;
+        const reachableByKey = new Map();
+        for (const candidate of pendingRemoteProbes) {
+            if (reachableByKey.has(candidate.key))
+                continue;
+            let reachable = false;
+            try {
+                const url = new URL(`${MEDIA_FILE_ROUTE_PREFIX}${candidate.key}`, origin).toString();
+                const res = await probeFetch(url, { method: 'HEAD' });
+                reachable = res.ok;
+            }
+            catch {
+                reachable = false;
+            }
+            reachableByKey.set(candidate.key, reachable);
+        }
+        for (const candidate of pendingRemoteProbes) {
+            if (reachableByKey.get(candidate.key)) {
+                verifiedFileRouteOnly.push(`${candidate.ref} (served by the file route but matched by no local mirror or record lookup; referenced by ${candidate.source})`);
+            }
+            else {
+                unreachableFileRoute.push(`${candidate.ref} (referenced by ${candidate.source})`);
+            }
+        }
+    }
+    missingMedia.push(...unreachableFileRoute);
+    // Remote library census: the list operation is the only handle that reaches migrated assets, because
+    // it is the one endpoint that reports each record's own storageKey and exposes no key filter. A
+    // complete walk turns "447 references have no local file" into "the library holds M records, this
+    // workspace mirrors K of them", which is what tells a user to widen the window instead of chase data
+    // loss. Credentials are required, so plain doctor runs stay offline and skip this block.
+    let remoteLibrary = null;
+    if (options.checkMediaLibrary) {
+        const origin = options.profileOrigin || options.config.origin;
+        try {
+            const index = await collectRemoteStorageKeys({
+                workspaceRoot: options.workspaceRoot,
+                origin,
+                token: options.token || '',
+                refreshToken: options.refreshToken,
+                fetchFn: options.fetchFn,
+            });
+            // Live EmDash sends no `totalCount`, so the walk itself is the only library figure available.
+            remoteLibrary = {
+                totalCount: index.totalCount ?? (index.complete ? index.scannedCount : null),
+                complete: index.complete,
+                mirroredCount: countMirroredMedia(mediaDir),
+            };
+        }
+        catch {
+            // An unreachable or unauthenticated library is not a workspace defect; doctor stays silent.
+        }
+    }
     if (missingMedia.length > 0) {
+        const coverage = remoteLibrary
+            ? remoteLibrary.complete
+                ? ` The remote library walk reached ${remoteLibrary.totalCount ?? 'no'} media record(s), and this workspace mirrors ${remoteLibrary.mirroredCount} of them, so most of these references were simply never downloaded.`
+                : ` The remote library is larger than the walk that could be completed here, and this workspace mirrors ${remoteLibrary.mirroredCount} record(s), so most of these references were simply never downloaded.`
+            : '';
         checks.push({
             id: 'media_references',
             name: 'Media References',
             status: 'warning',
-            message: `${missingMedia.length} referenced media file(s) are missing from disk.`,
+            message: `${missingMedia.length} referenced media file(s) are missing from disk.${coverage} ` +
+                `Run "emit pull-media --article <id>" for the specific article, or "emit doctor --check-media-library" ` +
+                `to size the remote library (metadata-only walk). Reserve "emit pull-media --all" for deliberate full offline backups. ` +
+                `Body URLs carry R2 storage keys, so a missing local file does not mean the remote asset is broken: see docs/media-id-spaces.md.`,
+            suggestion: options.checkMediaUrls
+                ? 'These keys are R2 storage keys, not media record ids, so a file-route hit proves only that the object exists. The full library index is reachable without binary downloads through "emit doctor --check-media-library" (or "emit pull-media --all" for complete offline backup), which reports every storageKey the server holds without any server-side query. Confirm by storageKey before registering anything — a blind INSERT can duplicate an existing record. Emit mirrors records, never repairs server data.'
+                : undefined,
             details: missingMedia,
         });
     }
+    else if (remoteLibrary) {
+        const notes = [
+            `Remote media library holds ${remoteLibrary.totalCount ?? 'an unknown number of'} record(s); this workspace mirrors ${remoteLibrary.mirroredCount}`,
+        ];
+        checks.push({
+            id: 'media_references',
+            name: 'Media References',
+            status: 'ok',
+            message: notes.join('; '),
+        });
+    }
     else if (options.strictMedia && informationalUnresolved.length > 0) {
         checks.push({
             id: 'media_references',
@@ -369,15 +706,26 @@ export async function runWorkspaceDoctor(options) {
         });
     }
     else {
-        const infoNote = informationalUnresolved.length > 0
-            ? ` (${informationalUnresolved.length} informational/placeholder reference(s) ignored)`
-            : '';
+        const notes = [];
+        if (verifiedFileRouteOnly.length > 0) {
+            notes.push(`${verifiedFileRouteOnly.length} reference(s) served by the remote file route that no local mirror or record lookup matched`);
+        }
+        if (informationalUnresolved.length > 0) {
+            notes.push(`${informationalUnresolved.length} informational/custom-block reference(s) ignored`);
+        }
+        if (invalidMediaRefs.length > 0) {
+            notes.push(`${invalidMediaRefs.length} malformed reference(s) skipped (not valid media file keys)`);
+        }
         checks.push({
             id: 'media_references',
             name: 'Media References',
             status: 'ok',
-            message: `All referenced local media files exist on disk.${infoNote}`,
-            ...(informationalUnresolved.length > 0 ? { details: informationalUnresolved } : {}),
+            message: `All referenced local media files exist on disk.${notes.length ? ` (${notes.join('; ')})` : ''}`,
+            ...(verifiedFileRouteOnly.length > 0 ||
+                informationalUnresolved.length > 0 ||
+                invalidMediaRefs.length > 0
+                ? { details: [...verifiedFileRouteOnly, ...informationalUnresolved, ...invalidMediaRefs] }
+                : {}),
         });
     }
     // 7. MCP Process Check