@dboio/cli 0.15.1 → 0.15.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.15.1",
+  "version": "0.15.3",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/plugins/claude/dbo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbo",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"

package/src/commands/clone.js

@@ -349,7 +349,7 @@ export function resolveEntityDirPaths(entityName, record, dirName) {
  * Resolve companion filename collisions within a shared BinID directory.
  *
  * Mutates the `filename` field in each entry to apply collision suffixes:
- *   - Content vs media same name → media gets "(media)" before extension
+ *   - Content vs media same name → media gets "_media" before extension
  *   - Same entity type duplicates → 2nd+ get "-1", "-2", ... suffix
  *
  * Companion files never contain ~UID. The metadata @reference stores the
@@ -373,12 +373,12 @@ export function resolveFilenameCollisions(entries) {
     const contentGroup = group.filter(e => e.entity === 'content');
     const mediaGroup = group.filter(e => e.entity === 'media');
 
-    // Content wins: media gets (media) suffix
+    // Content wins: media gets _media suffix
     if (contentGroup.length > 0 && mediaGroup.length > 0) {
       for (const m of mediaGroup) {
         const ext = extname(m.filename);
         const base = basename(m.filename, ext);
-        m.filename = `${base}(media)${ext}`;
+        m.filename = `${base}_media${ext}`;
       }
     }
 
@@ -588,7 +588,7 @@ async function buildFileRegistry(appJson, structure, placementPrefs) {
   }
 
   // Auto-resolve content vs media collisions and same-entity duplicates
-  // (content wins, media gets "(media)" suffix; same-entity duplicates get "-N" suffix)
+  // (content wins, media gets "_media" suffix; same-entity duplicates get "-N" suffix)
   resolveFilenameCollisions(allEntries);
 
   // Build registry with resolved filenames
@@ -2432,8 +2432,13 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   for (const record of mediaRecords) {
     if (skipUIDs.has(record.UID)) continue;
 
-    const { metaPath: scanMetaPath } = resolveMediaPaths(record, structure);
-    const scanExists = await fileExists(scanMetaPath);
+    const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
+    // Use collision-resolved filename for metadata path when available (e.g. "_media" suffix)
+    const resolvedName = resolvedFilenames.get(record.UID);
+    const effectiveMetaPath = resolvedName
+      ? join(scanDir, buildMetaFilename(resolvedName, String(record.UID || record._id || 'untitled')))
+      : scanMetaPath;
+    const scanExists = await fileExists(effectiveMetaPath);
 
     if (!scanExists) {
       // New file — always needs download
@@ -2444,13 +2449,13 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     } else {
       // Existing file — check if server is newer
       const configWithTz = { ...config, ServerTimezone: serverTz };
-      const localSyncTime = await getLocalSyncTime(scanMetaPath);
+      const localSyncTime = await getLocalSyncTime(effectiveMetaPath);
       const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz, 'media', record.UID);
       if (serverNewer) {
         needsDownload.push(record);
       } else {
         // Up to date — still need ref for app.json
-        upToDateRefs.push({ uid: record.UID, metaPath: scanMetaPath });
+        upToDateRefs.push({ uid: record.UID, metaPath: effectiveMetaPath });
       }
     }
   }
@@ -2525,9 +2530,8 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const uid = String(record.UID || record._id || 'untitled');
     const finalFilename = resolvedFilenames.get(record.UID) || sanitizeFilename(filename);
     const filePath = join(dir, finalFilename);
-    // Metadata: name.ext.metadata~uid.json
-    const naturalMediaBase = `${name}.${ext}`;
-    const metaPath = join(dir, buildMetaFilename(naturalMediaBase, uid));
+    // Metadata: use collision-resolved filename as base (e.g. "env_media.js" → "env_media.js.metadata~uid.json")
+    const metaPath = join(dir, buildMetaFilename(finalFilename, uid));
     // usedNames retained for tracking
     const fileKey = `${dir}/${name}.${ext}`;
     usedNames.set(fileKey, (usedNames.get(fileKey) || 0) + 1);
@@ -3744,15 +3748,22 @@ async function writeManifestJson(appJson, contentRefs) {
       const contentRef = meta.Content;
       if (contentRef && String(contentRef).startsWith('@')) {
         const refFile = String(contentRef).substring(1);
-        const contentPath = refFile.startsWith('/')
-          ? join(process.cwd(), refFile)
-          : join(dirname(ref.metaPath), refFile);
-        try {
-          const content = await readFile(contentPath, 'utf8');
+        // Try root-relative first, then sibling of metadata, then project root fallback
+        const candidates = refFile.startsWith('/')
+          ? [join(process.cwd(), refFile)]
+          : [join(dirname(ref.metaPath), refFile), join(process.cwd(), refFile)];
+        let content;
+        for (const candidate of candidates) {
+          try {
+            content = await readFile(candidate, 'utf8');
+            break;
+          } catch { /* try next */ }
+        }
+        if (content !== undefined) {
           await writeFile('manifest.json', content);
           log.dim('  manifest.json written to project root (from server content)');
-        } catch (err) {
-          log.warn(`  Could not write manifest.json from server content: ${err.message}`);
+        } else {
+          log.warn(`  Could not find manifest.json companion file`);
         }
       }
       return;

package/src/commands/push.js

@@ -22,16 +22,6 @@ import { checkToeStepping } from '../lib/toe-stepping.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 // AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
 
-function _getMetaCompanionPaths(meta, metaPath) {
-  const dir = dirname(metaPath);
-  const paths = [];
-  for (const col of (meta._contentColumns || [])) {
-    const ref = meta[col];
-    if (ref && String(ref).startsWith('@')) paths.push(join(dir, String(ref).substring(1)));
-  }
-  return paths;
-}
-
 /**
  * Resolve an @reference file path to an absolute filesystem path.
  * "@filename.ext"         → relative to the metadata file's directory (existing behaviour)
@@ -368,7 +358,8 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
     const baseline = await loadAppJsonBaseline();
     if (baseline) {
       const appConfig = await loadAppConfig();
-      const result = await checkToeStepping([{ meta, metaPath }], client, baseline, options, appConfig?.AppShortName);
+      const cfg = await loadConfig();
+      const result = await checkToeStepping([{ meta, metaPath }], client, baseline, options, appConfig?.AppShortName, cfg.ServerTimezone);
       if (result === false || result instanceof Set) return;
     }
   }
@@ -547,6 +538,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   // Collect metadata with detected changes
   const toPush = [];
   const outputCompoundFiles = [];
+  const seenUIDs = new Map(); // UID → metaPath (deduplicate same-UID metadata in different dirs)
   let skipped = 0;
 
   for (const metaPath of metaFiles) {
@@ -565,6 +557,16 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       continue;
     }
 
+    // Deduplicate: skip if another metadata file for the same UID was already processed.
+    // This happens when the same server record has stale metadata in a previous directory
+    // (e.g. after a BinID change on the server). The first match wins.
+    if (meta.UID && seenUIDs.has(meta.UID)) {
+      log.dim(`  Skipping duplicate UID ${meta.UID} at ${basename(metaPath)} (already seen at ${basename(seenUIDs.get(meta.UID))})`);
+      skipped++;
+      continue;
+    }
+    if (meta.UID) seenUIDs.set(meta.UID, metaPath);
+
     // AUTO-ADD DISABLED: justAddedUIDs skip removed (server-first workflow)
 
     // Output hierarchy entities: only push compound output files (root with inline children).
@@ -641,7 +643,8 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     const toCheck = toPush.filter(item => !item.isNew);
     if (toCheck.length > 0) {
       const appConfig = await loadAppConfig();
-      const result = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      const cfg = await loadConfig();
+      const result = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName, cfg.ServerTimezone);
       if (result === false) return; // user cancelled entirely
       if (result instanceof Set) {
         // Filter out skipped UIDs
@@ -850,11 +853,9 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     await updateBaselineAfterPush(baseline, successfulPushes);
   }
 
-  // Re-tag successfully pushed files as Synced (best-effort)
-  for (const { meta, metaPath } of successfulPushes) {
-    for (const filePath of _getMetaCompanionPaths(meta, metaPath)) {
-      setFileTag(filePath, 'synced').catch(() => {});
-    }
+  // Re-tag successfully pushed metadata files as Synced (best-effort)
+  for (const { metaPath } of successfulPushes) {
+    setFileTag(metaPath, 'synced').catch(() => {});
   }
 
   log.info(`Push complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped`);
@@ -946,7 +947,8 @@ async function pushByUIDs(uids, client, options, modifyKey = null, transactionKe
     }
     if (toCheck.length > 0) {
       const appConfig = await loadAppConfig();
-      const result = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      const cfg3 = await loadConfig();
+      const result = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName, cfg3.ServerTimezone);
       if (result === false) return; // user cancelled entirely
       if (result instanceof Set) {
         // Filter out skipped UIDs from matches

package/src/lib/delta.js

@@ -2,6 +2,7 @@ import { readFile, stat } from 'fs/promises';
 import { join, dirname } from 'path';
 import { log } from './logger.js';
 import { loadAppJsonBaseline, saveAppJsonBaseline } from './config.js';
+import { parseServerDate } from './timestamps.js';
 
 /**
  * Load the baseline file from disk.
@@ -164,15 +165,28 @@ export async function detectChangedColumns(metaPath, baseline) {
     }
   }
 
-  // Check _mediaFile for binary file changes (media entities)
+  // Check _mediaFile for binary file changes (media entities).
+  // Compare the media file's mtime against the baseline's _LastUpdated (the sync point)
+  // rather than the metadata file's mtime, because migrations and other operations can
+  // rewrite metadata without touching the companion, skewing the mtime relationship.
   if (metadata._mediaFile && isReference(metadata._mediaFile)) {
     const mediaPath = resolveReferencePath(metadata._mediaFile, metaDir);
     try {
       const mediaStat = await stat(mediaPath);
-      const metaStat = await stat(metaPath);
-      // Media file modified more recently than metadata = local change
-      if (mediaStat.mtimeMs > metaStat.mtimeMs + 2000) {
-        changedColumns.push('_mediaFile');
+      const baselineDate = baselineEntry?._LastUpdated
+        ? parseServerDate(baselineEntry._LastUpdated)
+        : null;
+      if (baselineDate) {
+        // Media file modified after baseline sync point = local change
+        if (mediaStat.mtimeMs > baselineDate.getTime() + 2000) {
+          changedColumns.push('_mediaFile');
+        }
+      } else {
+        // No baseline date — fall back to metadata mtime comparison
+        const metaStat = await stat(metaPath);
+        if (mediaStat.mtimeMs > metaStat.mtimeMs + 2000) {
+          changedColumns.push('_mediaFile');
+        }
       }
     } catch { /* missing file, skip */ }
   }
@@ -245,7 +259,16 @@ export function normalizeValue(value) {
     return JSON.stringify(value);
   }
 
-  return String(value).trim();
+  const str = String(value).trim();
+
+  // Normalize ISO date strings: strip trailing Z so that
+  // "2026-03-11T03:12:35" and "2026-03-11T03:12:35Z" compare as equal.
+  // Both values come from the same server timezone — only the Z suffix differs.
+  if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(str)) {
+    return str.replace(/Z$/, '');
+  }
+
+  return str;
 }
 
 // ─── Compound Output Delta Detection ────────────────────────────────────────

package/src/lib/tagging.js

@@ -80,12 +80,15 @@ export async function tagProjectFiles(options = {}) {
   const counts = { synced: 0, modified: 0, untracked: 0, conflict: 0, trashed: 0 };
 
   if (clearAll) {
-    const companions = (await Promise.all(metaPaths.map(mp => _getCompanionPaths(mp)))).flat();
-    await _bulkApplyTags(companions.map(fp => ({ filePath: fp, clear: true })));
+    // Clear tags from ALL files in the project: metadata, companions, and any
+    // legacy-tagged content files (from old untracked detection).
+    const contentFiles = await _collectContentFiles(dir, ig);
+    const allFiles = [...metaPaths, ...contentFiles];
+    await _bulkApplyTags(allFiles.map(fp => ({ filePath: fp, clear: true })));
     return null;
   }
-
-  // Collect file→status pairs from metadata
+  // Tag metadata files — the source of truth for sync status.
+  // Companion files are dependent artifacts and should not carry their own tags.
   const toTag = [];
   for (const metaPath of metaPaths) {
     const inTrash = metaPath.replace(/\\/g, '/').includes('/trash/');
@@ -93,20 +96,9 @@ export async function tagProjectFiles(options = {}) {
       ? 'trashed'
       : (await hasLocalModifications(metaPath, config).catch(() => false)) ? 'modified'
       : 'synced';
-    const companions = await _getCompanionPaths(metaPath);
-    for (const filePath of companions) {
-      toTag.push({ filePath, status });
-      counts[status]++;
-      if (verbose) console.log(`  ${status.padEnd(10)} ${relative(dir, filePath)}`);
-    }
-  }
-
-  // Detect untracked files (content files without any metadata)
-  const untrackedFiles = await _findUntrackedFiles(dir, ig, metaPaths);
-  for (const filePath of untrackedFiles) {
-    toTag.push({ filePath, status: 'untracked' });
-    counts.untracked++;
-    if (verbose) console.log(`  untracked  ${relative(dir, filePath)}`);
+    toTag.push({ filePath: metaPath, status });
+    counts[status]++;
+    if (verbose) console.log(`  ${status.padEnd(10)} ${relative(dir, metaPath)}`);
   }
 
   await _bulkApplyTags(toTag);
@@ -132,6 +124,11 @@ async function _getCompanionPaths(metaPath) {
         try { await stat(candidate); paths.push(candidate); } catch { /* missing */ }
       }
     }
+    // Check _mediaFile (single media companion reference)
+    if (meta._mediaFile && String(meta._mediaFile).startsWith("@")) {
+      const candidate = join(dir, String(meta._mediaFile).substring(1));
+      try { await stat(candidate); paths.push(candidate); } catch { /* missing */ }
+    }
     for (const col of (meta._mediaColumns || [])) {
       const ref = meta[col];
       if (ref && String(ref).startsWith('@')) {

package/src/lib/ticketing.js

@@ -13,7 +13,7 @@ function ticketingPath() {
   return join(dboDir(), TICKETING_FILE);
 }
 
-const DEFAULT_TICKETING = { ticket_id: null, ticketing_required: false, records: [] };
+const DEFAULT_TICKETING = { ticket_id: null, ticketing_required: false, ticket_confirmed: false, records: [] };
 
 /**
  * Load ticketing.local.json. Returns default structure if missing or corrupted.
@@ -31,6 +31,7 @@ export async function loadTicketing() {
     return {
       ticket_id: data.ticket_id || null,
       ticketing_required: !!data.ticketing_required,
+      ticket_confirmed: !!data.ticket_confirmed,
       records: Array.isArray(data.records) ? data.records : [],
     };
   } catch (err) {
@@ -74,6 +75,7 @@ export async function getRecordTicket(uid) {
 export async function setGlobalTicket(ticketId) {
   const data = await loadTicketing();
   data.ticket_id = ticketId;
+  data.ticket_confirmed = false; // reset confirmation when ticket changes
   await saveTicketing(data);
 }
 
@@ -123,6 +125,7 @@ export async function isTicketingRequired() {
 export async function clearGlobalTicket() {
   const data = await loadTicketing();
   data.ticket_id = null;
+  data.ticket_confirmed = false;
   await saveTicketing(data);
 }
 
@@ -231,6 +234,12 @@ export async function checkStoredTicket(options, context = '') {
     return { useTicket: true, clearTicket: false, cancel: false, overrideTicket: ticket };
   }
 
+  // Stored ticket exists and confirmed — auto-use without prompting
+  if (data.ticket_confirmed) {
+    log.info(`Using confirmed ticket "${data.ticket_id}"`);
+    return { useTicket: true, clearTicket: false, cancel: false };
+  }
+
   // Stored ticket exists — prompt to use, change, or clear
   const { action } = await inquirer.prompt([{
     type: 'list',
@@ -238,6 +247,7 @@ export async function checkStoredTicket(options, context = '') {
     message: `Use stored Ticket ID "${data.ticket_id}" for this submission?${suffix}`,
     choices: [
       { name: `Yes, use "${data.ticket_id}"`, value: 'use' },
+      { name: `Yes, use "${data.ticket_id}" for all future submissions (don't ask again)`, value: 'use_confirmed' },
       { name: 'Use a different ticket for this submission only', value: 'alt_once' },
       { name: 'Use a different ticket for this and future submissions', value: 'alt_save' },
       { name: 'No, clear stored ticket', value: 'clear' },
@@ -245,6 +255,12 @@ export async function checkStoredTicket(options, context = '') {
     ],
   }]);
 
+  if (action === 'use_confirmed') {
+    await saveTicketing({ ...data, ticket_confirmed: true });
+    log.dim(`  Ticket "${data.ticket_id}" confirmed — will auto-apply without prompting`);
+    return { useTicket: true, clearTicket: false, cancel: false };
+  }
+
   if (action === 'alt_once' || action === 'alt_save') {
     const { altTicket } = await inquirer.prompt([{
       type: 'input',
@@ -257,7 +273,7 @@ export async function checkStoredTicket(options, context = '') {
       return { useTicket: false, clearTicket: false, cancel: true };
     }
     if (action === 'alt_save') {
-      await saveTicketing({ ...data, ticket_id: ticket });
+      await saveTicketing({ ...data, ticket_id: ticket, ticket_confirmed: false });
       log.dim(`  Stored ticket updated to "${ticket}"`);
     }
     return { useTicket: true, clearTicket: false, cancel: false, overrideTicket: ticket };

package/src/lib/toe-stepping.js

@@ -5,6 +5,7 @@ import { findBaselineEntry, shouldSkipColumn, normalizeValue, isReference, resol
 import { resolveContentValue } from '../commands/clone.js';
 import { computeLineDiff, formatDiff } from './diff.js';
 import { parseMetaFilename } from './filenames.js';
+import { parseServerDate } from './timestamps.js';
 import { log } from './logger.js';
 
 /**
@@ -285,10 +286,11 @@ function findOldestBaselineDate(records, baseline) {
  * @param {Object} baseline - Loaded baseline from .dbo/.app_baseline.json
  * @param {Object} options  - Commander options (options.yes used for auto-accept)
  * @param {string} [appShortName] - App short name for bulk fetch (optional)
+ * @param {string} [serverTz] - Server timezone from config (e.g. "America/Chicago")
  * @returns {Promise<boolean|Set<string>>} - true = proceed with all,
  *   false = user cancelled entirely, Set<string> = UIDs to skip (proceed with rest)
  */
-export async function checkToeStepping(records, client, baseline, options, appShortName) {
+export async function checkToeStepping(records, client, baseline, options, appShortName, serverTz) {
   // Build list of records to check (skip new records without UID)
   const requests = [];
   for (const { meta } of records) {
@@ -350,9 +352,10 @@ export async function checkToeStepping(records, client, baseline, options, appSh
 
     if (!serverTs || !baselineTs) continue; // missing timestamps — skip safely
 
-    // Parse both as dates (ISO 8601 strings or server-format timestamps)
-    const serverDate = new Date(serverTs);
-    const baselineDate = new Date(baselineTs);
+    // Parse both dates using server timezone from config — server dates
+    // may arrive without Z suffix and represent the server's local time
+    const serverDate = parseServerDate(serverTs, serverTz);
+    const baselineDate = parseServerDate(baselineTs, serverTz);
 
     if (isNaN(serverDate) || isNaN(baselineDate)) continue; // unparseable — skip
     if (serverDate <= baselineDate) continue; // server is same or older — no conflict

package/src/migrations/009-fix-media-collision-metadata-names.js

@@ -0,0 +1,161 @@
+import { readdir, readFile, rename, unlink, access } from 'fs/promises';
+import { join, basename, dirname, extname } from 'path';
+import { log } from '../lib/logger.js';
+import { parseMetaFilename, buildMetaFilename } from '../lib/filenames.js';
+
+export const description = 'Fix media collision suffix: rename (media) → _media and fix mismatched metadata filenames';
+
+/**
+ * Migration 009 — Fix media metadata/companion files with wrong collision suffix.
+ *
+ * Two issues addressed:
+ *
+ * 1. Metadata filename mismatch: media records with collision-resolved names had their
+ *    metadata created as "env.js.metadata~uid.json" instead of matching the companion.
+ *    Detection: _mediaFile @reference base differs from metadata filename base.
+ *
+ * 2. (media) → _media rename: the old "(media)" suffix causes zsh glob issues.
+ *    Renames both companion files and metadata files, and updates @references.
+ */
+export default async function run(_options) {
+  const cwd = process.cwd();
+  let totalFixed = 0;
+  let totalOrphansDeleted = 0;
+  let totalParenRenamed = 0;
+
+  const metaFiles = await findAllMetadataFiles(cwd);
+  if (metaFiles.length === 0) return;
+
+  for (let metaPath of metaFiles) {
+    try {
+      let content = JSON.parse(await readFile(metaPath, 'utf8'));
+      const filename = basename(metaPath);
+      const parsed = parseMetaFilename(filename);
+      if (!parsed) continue;
+
+      // ── Phase 1: Rename (media) → _media in companion files and @references ──
+
+      // Check media @reference for (media) pattern
+      if (content._entity === 'media' && content._mediaFile) {
+        const ref = String(content._mediaFile);
+        if (ref.startsWith('@') && ref.includes('(media)')) {
+          const oldCompanion = ref.substring(1);
+          const ext = extname(oldCompanion);
+          const base = basename(oldCompanion, ext);
+          const newCompanion = `${base.replace('(media)', '_media')}${ext}`;
+          const dir = dirname(metaPath);
+
+          // Rename companion file on disk (or delete old if new already exists)
+          const oldCompanionPath = join(dir, oldCompanion);
+          const newCompanionPath = join(dir, newCompanion);
+          try {
+            await access(oldCompanionPath);
+            let newExists = false;
+            try { await access(newCompanionPath); newExists = true; } catch { /* */ }
+            if (newExists) {
+              // New file already exists (from re-clone) — delete the old orphan
+              await unlink(oldCompanionPath);
+              log.dim(`  Deleted old companion: ${oldCompanion}`);
+              totalOrphansDeleted++;
+            } else {
+              await rename(oldCompanionPath, newCompanionPath);
+              log.dim(`  ${oldCompanion} → ${newCompanion}`);
+            }
+          } catch { /* companion doesn't exist or already renamed */ }
+
+          // Update @reference in metadata
+          content._mediaFile = `@${newCompanion}`;
+          await import('fs/promises').then(fs => fs.writeFile(metaPath, JSON.stringify(content, null, 2) + '\n'));
+          totalParenRenamed++;
+        }
+      }
+
+      // Check content @references for (media) — shouldn't happen but be safe
+      if (content._contentColumns) {
+        for (const col of content._contentColumns) {
+          const ref = content[col];
+          if (ref && String(ref).startsWith('@') && String(ref).includes('(media)')) {
+            const oldName = String(ref).substring(1);
+            const ext = extname(oldName);
+            const base = basename(oldName, ext);
+            content[col] = `@${base.replace('(media)', '_media')}${ext}`;
+            await import('fs/promises').then(fs => fs.writeFile(metaPath, JSON.stringify(content, null, 2) + '\n'));
+          }
+        }
+      }
+
+      // Rename metadata file itself if it contains (media)
+      if (parsed.naturalBase.includes('(media)')) {
+        const newBase = parsed.naturalBase.replace('(media)', '_media');
+        const newMetaFilename = buildMetaFilename(newBase, parsed.uid);
+        const newMetaPath = join(dirname(metaPath), newMetaFilename);
+        try { await access(newMetaPath); } catch {
+          await rename(metaPath, newMetaPath);
+          log.dim(`  ${filename} → ${newMetaFilename}`);
+          metaPath = newMetaPath; // update for phase 2
+          totalParenRenamed++;
+        }
+        // Re-read parsed after rename
+        content = JSON.parse(await readFile(metaPath, 'utf8'));
+      }
+
+      // ── Phase 2: Fix metadata filename not matching @reference ──
+
+      if (content._entity !== 'media') continue;
+      const mediaRef = content._mediaFile;
+      if (!mediaRef || !String(mediaRef).startsWith('@')) continue;
+
+      const refFilename = String(mediaRef).substring(1);
+      const currentParsed = parseMetaFilename(basename(metaPath));
+      if (!currentParsed) continue;
+
+      // Already correct
+      if (currentParsed.naturalBase === refFilename) continue;
+
+      const correctFilename = buildMetaFilename(refFilename, currentParsed.uid);
+      const correctPath = join(dirname(metaPath), correctFilename);
+
+      // If correct metadata already exists, this one is an orphan
+      try {
+        await access(correctPath);
+        await unlink(metaPath);
+        log.dim(`  Deleted orphan: ${basename(metaPath)}`);
+        totalOrphansDeleted++;
+        continue;
+      } catch { /* correct file doesn't exist — rename */ }
+
+      await rename(metaPath, correctPath);
+      log.dim(`  ${basename(metaPath)} → ${correctFilename}`);
+      totalFixed++;
+    } catch { /* skip unreadable files */ }
+  }
+
+  if (totalParenRenamed > 0) {
+    log.dim(`  Renamed ${totalParenRenamed} file(s) from (media) to _media`);
+  }
+  if (totalFixed > 0) {
+    log.dim(`  Renamed ${totalFixed} media metadata file(s) to match companion names`);
+  }
+  if (totalOrphansDeleted > 0) {
+    log.dim(`  Deleted ${totalOrphansDeleted} orphaned media metadata file(s)`);
+  }
+}
+
+const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+
+async function findAllMetadataFiles(dir) {
+  const results = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await findAllMetadataFiles(full));
+      } else if (entry.name.includes('.metadata~') && entry.name.endsWith('.json')) {
+        results.push(full);
+      }
+    }
+  } catch { /* skip unreadable dirs */ }
+  return results;
+}

package/src/migrations/010-delete-paren-media-orphans.js

@@ -0,0 +1,61 @@
+import { readdir, unlink, access } from 'fs/promises';
+import { join, basename, extname } from 'path';
+import { log } from '../lib/logger.js';
+
+export const description = 'Delete orphaned (media) companion and metadata files replaced by _media';
+
+/**
+ * Migration 010 — Clean up leftover (media) files.
+ *
+ * Migration 009 renamed (media) → _media but did not delete the old files
+ * when the new _media versions already existed. This migration finds any
+ * remaining files with "(media)" in their name and deletes them if the
+ * corresponding _media version exists.
+ */
+export default async function run(_options) {
+  const cwd = process.cwd();
+  let totalDeleted = 0;
+
+  const parenFiles = await findParenMediaFiles(cwd);
+  if (parenFiles.length === 0) return;
+
+  for (const filePath of parenFiles) {
+    const filename = basename(filePath);
+    // Build the _media equivalent
+    const newFilename = filename.replace(/\(media\)/g, '_media');
+    const newPath = join(filePath, '..', newFilename);
+
+    // Only delete if the _media replacement exists
+    try {
+      await access(newPath);
+      await unlink(filePath);
+      log.dim(`  Deleted: ${filename}`);
+      totalDeleted++;
+    } catch {
+      // No _media replacement — leave alone (might be a legitimate filename)
+    }
+  }
+
+  if (totalDeleted > 0) {
+    log.dim(`  Removed ${totalDeleted} orphaned (media) file(s)`);
+  }
+}
+
+const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+
+async function findParenMediaFiles(dir) {
+  const results = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await findParenMediaFiles(full));
+      } else if (entry.name.includes('(media)')) {
+        results.push(full);
+      }
+    }
+  } catch { /* skip unreadable dirs */ }
+  return results;
+}