@monoes/monodesign 1.2.0 → 1.2.2

package/cli/bin/commands/ignores.mjs

@@ -149,8 +149,8 @@ function list(cwd) {
   const local = readRawDetectionConfig(cwd, { local: true });
   return [
     'Monodesign detector ignores',
-    `  shared file: ${path.relative(cwd, getConfigPath(cwd)) || getConfigPath(cwd)}`,
-    `  local file:  ${path.relative(cwd, getLocalConfigPath(cwd)) || getLocalConfigPath(cwd)}`,
+    `  shared file: ${path.relative(cwd, getConfigPath(cwd)).split(path.sep).join('/') || getConfigPath(cwd)}`,
+    `  local file:  ${path.relative(cwd, getLocalConfigPath(cwd)).split(path.sep).join('/') || getLocalConfigPath(cwd)}`,
     '',
     formatConfig('Merged', merged),
     '',
@@ -203,7 +203,7 @@ function addRule(cwd, args) {
   const config = readScopeConfig(cwd, local);
   if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
   const target = writeScopeConfig(cwd, config, local);
-  return `Added ${rule} to ${local ? 'local' : 'shared'} detector ignoreRules (${path.relative(cwd, target) || target}).`;
+  return `Added ${rule} to ${local ? 'local' : 'shared'} detector ignoreRules (${path.relative(cwd, target).split(path.sep).join('/') || target}).`;
 }
 
 function addFile(cwd, args) {
@@ -213,7 +213,7 @@ function addFile(cwd, args) {
   const config = readScopeConfig(cwd, local);
   if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
   const target = writeScopeConfig(cwd, config, local);
-  return `Added ${glob} to ${local ? 'local' : 'shared'} detector ignoreFiles (${path.relative(cwd, target) || target}).`;
+  return `Added ${glob} to ${local ? 'local' : 'shared'} detector ignoreFiles (${path.relative(cwd, target).split(path.sep).join('/') || target}).`;
 }
 
 function addValue(cwd, args) {
@@ -236,7 +236,7 @@ function addValue(cwd, args) {
     config.ignoreValues.push(entry);
   }
   const target = writeScopeConfig(cwd, config, local);
-  return `Added ${parsed.rule}=${parsed.value} to ${local ? 'local' : 'shared'} detector ignoreValues (${path.relative(cwd, target) || target}).`;
+  return `Added ${parsed.rule}=${parsed.value} to ${local ? 'local' : 'shared'} detector ignoreValues (${path.relative(cwd, target).split(path.sep).join('/') || target}).`;
 }
 
 function removeFromScopes(cwd, args, remover) {
@@ -248,7 +248,7 @@ function removeFromScopes(cwd, args, remover) {
     const count = remover(config, rest);
     if (count > 0) {
       const target = writeScopeConfig(cwd, config, isLocal);
-      removed.push(`${count} from ${isLocal ? 'local' : 'shared'} (${path.relative(cwd, target) || target})`);
+      removed.push(`${count} from ${isLocal ? 'local' : 'shared'} (${path.relative(cwd, target).split(path.sep).join('/') || target})`);
     }
   }
   return removed.length ? `Removed ${removed.join(', ')}.` : 'No matching detector ignore found.';

package/cli/engine/detect-antipatterns-browser.js

@@ -3568,6 +3568,13 @@ function checkElementImageDimensions(el, style) {
 }
 
 function checkElementImageDimensionsDOM(el) {
+  // Only <img> can have this problem. The static engine gets this for free —
+  // it registers the rule with `selector: 'img'` (engines/static-html/
+  // detect-html.mjs) — but the DOM walker calls every check against every
+  // element, so the tag filter has to live here. Without it this rule fired on
+  // <head>, <meta>, <title> and <style>: a clean 84-line fixture reported 43
+  // findings, all of them "an <img> ships without width and height".
+  if (el.tagName !== 'IMG') return [];
   const hasWidthAttr = el.getAttribute('width') != null;
   const hasHeightAttr = el.getAttribute('height') != null;
   // Browser computed `height` always resolves to a used px value after layout,

package/cli/engine/fix/index.mjs

@@ -257,7 +257,7 @@ async function runFix(targets, options = {}) {
   const diffs = [];
   if (dryRun) {
     for (const [p, b] of changedFiles) {
-      diffs.push({ file: p, diff: unifiedDiff(b.original, b.content, path.relative(cwd, p) || p) });
+      diffs.push({ file: p, diff: unifiedDiff(b.original, b.content, path.relative(cwd, p).split(path.sep).join('/') || p) });
     }
   } else {
     for (const [p, b] of changedFiles) writeFileAtomic(p, b.content);

package/cli/engine/rules/checks.mjs

@@ -2845,6 +2845,13 @@ function checkElementImageDimensions(el, style) {
 }
 
 function checkElementImageDimensionsDOM(el) {
+  // Only <img> can have this problem. The static engine gets this for free —
+  // it registers the rule with `selector: 'img'` (engines/static-html/
+  // detect-html.mjs) — but the DOM walker calls every check against every
+  // element, so the tag filter has to live here. Without it this rule fired on
+  // <head>, <meta>, <title> and <style>: a clean 84-line fixture reported 43
+  // findings, all of them "an <img> ships without width and height".
+  if (el.tagName !== 'IMG') return [];
   const hasWidthAttr = el.getAttribute('width') != null;
   const hasHeightAttr = el.getAttribute('height') != null;
   // Browser computed `height` always resolves to a used px value after layout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monodesign",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Frontend design intelligence for AI agents \u2014 design tokens, antipattern detection, and the monodesign skill",
   "type": "module",
   "main": "./src/index.ts",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "node --experimental-strip-types --test 'tests/*.test.*' 'tests/lib/*.test.*'",
+    "test": "node scripts/run-tests.mjs",
     "sync": "node scripts/sync-skill.mjs",
     "prepare": "node scripts/sync-skill.mjs"
   },
@@ -45,7 +45,7 @@
     "marked": "^18.0.0"
   },
   "optionalDependencies": {
-    "@monoes/monobrowse": "^1.0.3",
+    "@monoes/monobrowse": "^1.0.6",
     "puppeteer": "^25.1.0"
   }
 }

package/skill/scripts/context-signals.mjs

@@ -93,7 +93,7 @@ function latestCritique(cwd) {
       p0: numKey('p0', 'p0_count'),
       p1: numKey('p1', 'p1_count'),
       timestamp: get('timestamp'),
-      file: path.relative(cwd, path.join(dir, newest)),
+      file: path.relative(cwd, path.join(dir, newest)).split(path.sep).join('/'),
       trend,
       openP0,
     };

package/skill/scripts/context.mjs

@@ -75,10 +75,10 @@ export function loadContext(cwd = process.cwd(), options = {}) {
   return {
     hasProduct: !!product,
     product,
-    productPath: productPath ? path.relative(absCwd, productPath) : null,
+    productPath: productPath ? path.relative(absCwd, productPath).split(path.sep).join('/') : null,
     hasDesign: !!design,
     design,
-    designPath: designPath ? path.relative(absCwd, designPath) : null,
+    designPath: designPath ? path.relative(absCwd, designPath).split(path.sep).join('/') : null,
     contextDir: resolved.contextDir,
     productContextDir: productPath ? path.dirname(productPath) : null,
     designContextDir: designPath ? path.dirname(designPath) : null,
@@ -186,7 +186,7 @@ function resolveProject(cwd = process.cwd(), options = {}) {
 }
 
 function isPathInside(candidate, root) {
-  const rel = path.relative(root, candidate);
+  const rel = path.relative(root, candidate).split(path.sep).join('/');
   return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
 }
 
@@ -339,9 +339,9 @@ function contextSourceStatus(filePath, repoRoot, projectRoot) {
 
 function contextSourcePath(filePath, repoRoot) {
   if (!filePath) return null;
-  const rel = path.relative(repoRoot, filePath);
+  const rel = path.relative(repoRoot, filePath).split(path.sep).join('/');
   if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) {
-    return rel.split(path.sep).join('/');
+    return rel;
   }
   return filePath;
 }
@@ -447,9 +447,13 @@ function findTargetExample(repoRoot, projectRoot) {
 }
 
 function resolveWorkspaceProjectRoot(repoRoot, targetDir) {
-  const rel = path.relative(repoRoot, targetDir);
+  const rel = path.relative(repoRoot, targetDir).split(path.sep).join('/');
   if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return repoRoot;
-  const relSegments = rel.split(path.sep).filter(Boolean);
+  // rel is POSIX-normalised above, so split on '/' — splitting on path.sep here
+  // returned the whole string as a single segment on Windows, no workspace
+  // pattern ever matched, and every child project silently resolved to the
+  // repo root instead.
+  const relSegments = rel.split('/').filter(Boolean);
   const patterns = readWorkspacePatterns(repoRoot);
   const excluded = isExcludedByWorkspacePattern(relSegments, patterns);
   if (!excluded) {

package/skill/scripts/critique-storage.mjs

@@ -64,7 +64,7 @@ export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
   // File path. Make it project-relative so two devs critiquing the same
   // checkout get the same slug regardless of where their repo is cloned.
   const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
-  let rel = path.relative(cwd, abs);
+  let rel = path.relative(cwd, abs).split(path.sep).join('/');
   // If the target is outside cwd, fall back to the basename so we still
   // produce a stable slug (vs the absolute path, which would include
   // home dirs / usernames).
@@ -231,7 +231,7 @@ export function mirrorToMemory({ slug, meta = {}, filePath, cwd = process.cwd(),
       p1: asFiniteNumber(meta.p1_count ?? meta.p1),
       date: now.toISOString(),
       slug,
-      path: filePath ? path.relative(cwd, filePath) : null,
+      path: filePath ? path.relative(cwd, filePath).split(path.sep).join('/') : null,
     };
     const project = kebab(path.basename(path.resolve(cwd))) || 'project';
     const key = `${project}-${slug}`;
@@ -340,7 +340,7 @@ export function formatRecall(recall, { cwd = process.cwd() } = {}) {
   if (!issues.p0.length && !issues.p1.length) {
     lines.push('- No open P0/P1 lines found in the latest snapshot.');
   }
-  lines.push(`- Snapshot: ${path.relative(cwd, latest.path)}`);
+  lines.push(`- Snapshot: ${path.relative(cwd, latest.path).split(path.sep).join('/')}`);
   return lines.join('\n');
 }
 

package/skill/scripts/detect-csp.mjs

@@ -186,7 +186,7 @@ function walk(root, dir, depth, visit) {
         body = buf.slice(0, n).toString('utf-8');
       } finally { fs.closeSync(fd); }
     } catch { continue; }
-    visit(abs, path.relative(root, abs), body);
+    visit(abs, path.relative(root, abs).split(path.sep).join('/'), body);
   }
 }
 

package/skill/scripts/hook-admin.mjs

@@ -275,9 +275,9 @@ function statusReport(cwd) {
   const cfg = readConfig(cwd);
   const envKill = process.env.MONODESIGN_HOOK_DISABLED;
   const envState = envKill ? `MONODESIGN_HOOK_DISABLED=${envKill}` : 'unset';
-  const cfgPath = path.relative(cwd, getConfigPath(cwd)) || '.monodesign/config.json';
-  const localPath = path.relative(cwd, getLocalConfigPath(cwd)) || '.monodesign/config.local.json';
-  const cachePath = path.relative(cwd, getCachePath(cwd)) || '.monodesign/hook.cache.json';
+  const cfgPath = path.relative(cwd, getConfigPath(cwd)).split(path.sep).join('/') || '.monodesign/config.json';
+  const localPath = path.relative(cwd, getLocalConfigPath(cwd)).split(path.sep).join('/') || '.monodesign/config.local.json';
+  const cachePath = path.relative(cwd, getCachePath(cwd)).split(path.sep).join('/') || '.monodesign/hook.cache.json';
   const fileState = (info, relPath, absent) => {
     if (info.malformed) return `${relPath} (malformed; ignored)`;
     if (info.exists) return relPath;
@@ -306,14 +306,14 @@ function setEnabled(cwd, value) {
   config.enabled = value;
   const target = writeHookConfig(cwd, config);
   if (!value) {
-    return `Design hook disabled for this project (wrote ${path.relative(cwd, target) || target}).`;
+    return `Design hook disabled for this project (wrote ${path.relative(cwd, target).split(path.sep).join('/') || target}).`;
   }
 
   const localTarget = writeHookConfig(cwd, { consent: 'accepted' }, { local: true });
   const repaired = repairHookManifests(cwd);
   const parts = [
-    `Design hook enabled for this project (wrote ${path.relative(cwd, target) || target}).`,
-    `Recorded local hook consent in ${path.relative(cwd, localTarget) || localTarget}.`,
+    `Design hook enabled for this project (wrote ${path.relative(cwd, target).split(path.sep).join('/') || target}).`,
+    `Recorded local hook consent in ${path.relative(cwd, localTarget).split(path.sep).join('/') || localTarget}.`,
   ];
   if (repaired.written.length > 0) {
     parts.push(`Installed or repaired hook manifests for: ${repaired.written.join(', ')}.`);
@@ -323,7 +323,7 @@ function setEnabled(cwd, value) {
     parts.push('No installed provider skill folders found to repair.');
   }
   if (repaired.backups.length > 0) {
-    parts.push(`Backed up malformed manifest(s): ${repaired.backups.map((filePath) => path.relative(cwd, filePath) || filePath).join(', ')}.`);
+    parts.push(`Backed up malformed manifest(s): ${repaired.backups.map((filePath) => path.relative(cwd, filePath).split(path.sep).join('/') || filePath).join(', ')}.`);
   }
   return parts.join(' ');
 }
@@ -596,7 +596,7 @@ function addIgnoreValue(cwd, args) {
 
   const target = writeDetectorConfig(cwd, config, { local });
   const scope = local ? 'local detector.ignoreValues' : 'shared detector.ignoreValues';
-  return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
+  return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target).split(path.sep).join('/') || target}).`;
 }
 
 function reset(cwd) {
@@ -613,7 +613,7 @@ function reset(cwd) {
       } else {
         fs.writeFileSync(filePath, JSON.stringify(rest, null, 2) + '\n');
       }
-      removed.push(path.relative(cwd, filePath) || filePath);
+      removed.push(path.relative(cwd, filePath).split(path.sep).join('/') || filePath);
     } catch { /* ignore */ }
   }
   // State files are wholly ours; delete outright.
@@ -621,7 +621,7 @@ function reset(cwd) {
     try {
       if (fs.existsSync(filePath)) {
         fs.unlinkSync(filePath);
-        removed.push(path.relative(cwd, filePath) || filePath);
+        removed.push(path.relative(cwd, filePath).split(path.sep).join('/') || filePath);
       }
     } catch { /* ignore */ }
   }

package/skill/scripts/hook-before-edit.mjs

@@ -320,7 +320,7 @@ function escapeRegExp(value) {
 
 function relativePath(filePath, cwd) {
   try {
-    const rel = path.relative(cwd, filePath);
+    const rel = path.relative(cwd, filePath).split(path.sep).join('/');
     if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return filePath;
     return rel.split(path.sep).join('/');
   } catch {
@@ -330,7 +330,7 @@ function relativePath(filePath, cwd) {
 
 function isInsideProject(filePath, cwd) {
   try {
-    const rel = path.relative(cwd, filePath);
+    const rel = path.relative(cwd, filePath).split(path.sep).join('/');
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
   } catch {
     return false;

package/skill/scripts/hook-lib.mjs

@@ -1015,7 +1015,7 @@ function quoteCommandArg(value) {
 
 function relativize(filePath, cwd) {
   try {
-    const rel = path.relative(cwd, filePath);
+    const rel = path.relative(cwd, filePath).split(path.sep).join('/');
     if (!rel || rel.startsWith('..')) return filePath;
     return rel.split(path.sep).join('/');
   } catch {
@@ -1226,7 +1226,7 @@ function hasPathTraversal(filePath) {
 function isInsideProject(filePath, projectCwd) {
   if (!filePath || !projectCwd || hasPathTraversal(filePath)) return false;
   try {
-    const rel = path.relative(projectCwd, filePath);
+    const rel = path.relative(projectCwd, filePath).split(path.sep).join('/');
     return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
   } catch {
     return false;

package/skill/scripts/live/manual-apply.mjs

@@ -338,7 +338,7 @@ export function normalizeManualApplyEvidencePath(evidencePath, cwd = process.cwd
   if (!evidencePath || typeof evidencePath !== 'string') return null;
   const fullPath = path.isAbsolute(evidencePath) ? evidencePath : path.resolve(cwd, evidencePath);
   const evidenceDir = manualApplyEvidenceDir(cwd);
-  const relative = path.relative(evidenceDir, fullPath);
+  const relative = path.relative(evidenceDir, fullPath).split(path.sep).join('/');
   if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
   if (path.extname(relative) !== '.json') return null;
   return fullPath;
@@ -837,7 +837,7 @@ export function collectManualApplyFiles(batch, extraFiles = [], cwd = process.cw
 function normalizeProjectFile(file, cwd = process.cwd()) {
   if (!file || typeof file !== 'string') return null;
   const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
-  const relative = path.relative(cwd, absolute);
+  const relative = path.relative(cwd, absolute).split(path.sep).join('/');
   if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
   return relative;
 }
@@ -927,7 +927,7 @@ export function summarizeManualDiagnostics(items, cwd = process.cwd()) {
 export function summarizeManualLogFile(file, cwd = process.cwd()) {
   if (!file || typeof file !== 'string') return undefined;
   if (!path.isAbsolute(file)) return file;
-  const relative = path.relative(cwd, file);
+  const relative = path.relative(cwd, file).split(path.sep).join('/');
   return relative && !relative.startsWith('..') && !path.isAbsolute(relative) ? relative : file;
 }
 

package/skill/scripts/live/svelte-component.mjs

@@ -265,7 +265,7 @@ export function resolveSourceFile(sourceFile, cwd = process.cwd()) {
     throw new Error('Invalid svelte-component source file');
   }
   const full = path.resolve(cwd, sourceFile);
-  const rel = path.relative(cwd, full);
+  const rel = path.relative(cwd, full).split(path.sep).join('/');
   if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
     throw new Error('Svelte-component source file escapes project root');
   }

package/skill/scripts/live-accept.mjs

@@ -119,7 +119,7 @@ Output (JSON):
   }
 
   const { file: targetFile, content, lines } = found;
-  const relFile = path.relative(process.cwd(), targetFile);
+  const relFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
   const previewBlock = findMarkerBlock(id, lines);
   const sourceShadowPreview = previewBlock
     ? readSourceShadowPreviewMeta(content, id)

package/skill/scripts/live-commit-manual-edits.mjs

@@ -224,7 +224,7 @@ function buildRepairBatch(batch, repair) {
 function normalizeProjectSourcePath(cwd, file, opts = {}) {
   if (!file || typeof file !== 'string') return null;
   const absolute = path.isAbsolute(file) ? file : path.resolve(cwd, file);
-  const relative = path.relative(cwd, absolute);
+  const relative = path.relative(cwd, absolute).split(path.sep).join('/');
   if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return null;
   if (opts.requireExists && !fs.existsSync(absolute)) return null;
   if (isGeneratedFile(absolute, { cwd })) return null;
@@ -622,7 +622,7 @@ function scanRollbackDir(dir, cwd, out, seenDirs, seenFiles, depth) {
     try { realFile = fs.realpathSync(absolute); } catch { continue; }
     if (seenFiles.has(realFile)) continue;
     seenFiles.add(realFile);
-    const relative = path.relative(cwd, absolute);
+    const relative = path.relative(cwd, absolute).split(path.sep).join('/');
     if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) continue;
     out.push(relative);
   }

package/skill/scripts/live-copy-edit-agent.mjs

@@ -534,7 +534,7 @@ function runAgentProcess(command, args, stdin, { cwd, env, logPath, timeoutMs, m
 }
 
 function isPathInsideOrEqual(cwd, file) {
-  const relative = path.relative(path.resolve(cwd), path.resolve(file));
+  const relative = path.relative(path.resolve(cwd), path.resolve(file)).split(path.sep).join('/');
   return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
 }
 

package/skill/scripts/live-insert.mjs

@@ -166,7 +166,7 @@ Output (JSON):
     console.error(JSON.stringify({
       error: 'file_is_generated',
       fallback: 'agent-driven',
-      file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)),
+      file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)).split(path.sep).join('/'),
     }));
     process.exit(1);
   }
@@ -179,7 +179,7 @@ Output (JSON):
     console.error(JSON.stringify({
       error: 'element_ambiguous',
       fallback: 'agent-driven',
-      file: path.relative(process.cwd(), targetFile),
+      file: path.relative(process.cwd(), targetFile).split(path.sep).join('/'),
       candidates: resolved.candidates.map((c) => ({
         startLine: c.startLine + 1,
         endLine: c.endLine + 1,

package/skill/scripts/live-manual-edit-evidence.mjs

@@ -64,7 +64,7 @@ export function buildManualEditEvidence({ cwd = process.cwd(), pageUrl = null }
     ops,
     context: {
       cwd,
-      bufferPath: path.relative(cwd, getBufferPath(cwd)),
+      bufferPath: path.relative(cwd, getBufferPath(cwd)).split(path.sep).join('/'),
       totalEntries: entries.length,
       totalOps: opCount,
     },
@@ -157,7 +157,7 @@ function analyzeSourceHint(op, cwd) {
   const hint = normalizeSourceHint(op.sourceHint);
   if (!hint.file) return null;
   const file = path.resolve(cwd, hint.file);
-  const relativeFile = path.relative(cwd, file);
+  const relativeFile = path.relative(cwd, file).split(path.sep).join('/');
   if (!isPathInsideOrEqual(cwd, file)) {
     return { ...hint, status: 'outside_cwd', relativeFile: hint.file };
   }
@@ -254,7 +254,7 @@ function maybeAddSearchFile(file, cwd, seenFiles, out) {
   if (isGeneratedFile(file, { cwd })) return;
   let content;
   try { content = fs.readFileSync(file, 'utf-8'); } catch { return; }
-  out.push({ file, relativeFile: path.relative(cwd, file), content, lines: content.split('\n') });
+  out.push({ file, relativeFile: path.relative(cwd, file).split(path.sep).join('/'), content, lines: content.split('\n') });
 }
 
 function findLiteralMatches(searchFiles, needle, { max }) {
@@ -340,7 +340,7 @@ function matchForIndex(file, index, kind, needle) {
 }
 
 function isPathInsideOrEqual(cwd, file) {
-  const rel = path.relative(path.resolve(cwd), path.resolve(file));
+  const rel = path.relative(path.resolve(cwd), path.resolve(file)).split(path.sep).join('/');
   return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 }
 

package/skill/scripts/live-server.mjs

@@ -789,7 +789,7 @@ function sessionFileMetadataFromPollReply(file) {
   let full;
   try {
     full = path.resolve(process.cwd(), normalized);
-    const rel = path.relative(process.cwd(), full);
+    const rel = path.relative(process.cwd(), full).split(path.sep).join('/');
     if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return base;
   } catch {
     return base;
@@ -1112,7 +1112,8 @@ applyLegacyDeferredAcceptsOnStartup();
 restorePendingEventsFromStore();
 manualApply.pruneStaleEvidence();
 const portArg = args.find(a => a.startsWith('--port='));
-state.port = portArg ? parseInt(portArg.split('=')[1], 10) : await findOpenPort();
+const explicitPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
+state.port = explicitPort ?? await findOpenPort();
 // Annotation screenshots live in the project root so the agent's Read tool
 // doesn't trip a per-file permission prompt. Sessioned by token so concurrent
 // projects (or quick restarts) don't collide.
@@ -1123,7 +1124,43 @@ state.sessionDir = fs.mkdtempSync(path.join(annotRoot, 'session-'));
 const { detectScript, liveScriptParts } = loadBrowserScripts();
 httpServer = http.createServer(createRequestHandler({ detectScript, liveScriptParts }));
 
+// findOpenPort() probes a port, closes the probe socket, and only then does the
+// real server bind it. Another process scanning the same range can take the
+// port inside that gap, which surfaced as an intermittent
+// "EADDRINUSE 127.0.0.1:8405" — about one run in five of the test suite, where
+// several server-starting test files run in parallel.
+//
+// Retry on the next port when we picked it ourselves. An explicit --port is
+// never silently moved: the caller asked for that port, so a conflict there
+// must be an error they can see.
+const MAX_PORT_RETRIES = 25;
+let portRetries = 0;
+
+httpServer.on('error', (err) => {
+  if (err?.code !== 'EADDRINUSE') throw err;
+
+  if (explicitPort !== null) {
+    console.error(`\nPort ${state.port} is already in use.`);
+    console.error('Another live server may be running — stop it, or pass a different --port.');
+    process.exit(1);
+  }
+
+  if (portRetries >= MAX_PORT_RETRIES) {
+    console.error(`\nCould not find a free port after ${MAX_PORT_RETRIES} attempts (last tried ${state.port}).`);
+    process.exit(1);
+  }
+
+  portRetries++;
+  state.port++;
+  httpServer.listen(state.port, '127.0.0.1');
+});
+
 httpServer.listen(state.port, '127.0.0.1', () => {
+  // Trust the address the OS actually bound over the one we asked for — after
+  // a retry above, state.port and the bound port must not drift apart.
+  const boundAddr = httpServer.address();
+  if (boundAddr && typeof boundAddr === 'object') state.port = boundAddr.port;
+
   writeLiveServerInfo(process.cwd(), { pid: process.pid, port: state.port, token: state.token });
   const url = `http://localhost:${state.port}`;
   console.log(`\nMonodesign live server running on ${url}`);

package/skill/scripts/live-wrap.mjs

@@ -102,7 +102,7 @@ The agent should insert variant HTML at insertLine.`);
         console.error(JSON.stringify({
           error: 'element_not_in_source',
           fallback: 'agent-driven',
-          generatedMatch: path.relative(process.cwd(), generatedHit),
+          generatedMatch: path.relative(process.cwd(), generatedHit).split(path.sep).join('/'),
           hint: 'Element found only in a generated file. See "Handle fallback" in live.md.',
         }));
       } else {
@@ -119,7 +119,7 @@ The agent should insert variant HTML at insertLine.`);
       console.error(JSON.stringify({
         error: 'file_is_generated',
         fallback: 'agent-driven',
-        file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)),
+        file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)).split(path.sep).join('/'),
         hint: 'Explicit --file points at a generated file. Writing here gets wiped by the next build. See "Handle fallback" in live.md.',
       }));
       process.exit(1);
@@ -172,7 +172,7 @@ The agent should insert variant HTML at insertLine.`);
         console.error(JSON.stringify({
           error: 'element_ambiguous',
           fallback: 'agent-driven',
-          file: path.relative(process.cwd(), targetFile),
+          file: path.relative(process.cwd(), targetFile).split(path.sep).join('/'),
           candidates: filtered.map((c) => ({
             startLine: c.startLine + 1,
             endLine: c.endLine + 1,