npm - @hamp10/agentforge - Versions diffs - 0.2.23 → 0.2.25 - Mend

@hamp10/agentforge 0.2.23 → 0.2.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json +1 -1
package/scripts/check-task-semantics.js +125 -14
package/src/OpenClawCLI.js +251 -44
package/src/browser.js +45 -1
package/src/preview-server.js +11 -1
package/src/taskSemantics.js +37 -2
package/src/worker.js +79 -15

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hamp10/agentforge",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "description": "AgentForge worker — connect your machine to agentforge.ai",
   "type": "module",
   "bin": {

package/scripts/check-task-semantics.js CHANGED Viewed

@@ -6,7 +6,7 @@ import { existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, readlinkSy
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { deflateSync } from 'node:zlib';
-import { extractExplicitScope } from '../src/taskSemantics.js';
+import { extractExplicitScope, scopeSlugAliases, scopeSlugsMatchingText } from '../src/taskSemantics.js';
 import { AgentForgeWorker } from '../src/worker.js';
 import { OpenClawCLI } from '../src/OpenClawCLI.js';
@@ -23,6 +23,12 @@ const cases = [
     absent: ['example-com', 'visual', 'quality'],
     pageOnly: true,
   },
+  {
+    text: 'Work on the Example.com listing pages for AlphaBoard.ai and BetaMatch.ai. Make them visually excellent and consistent with the rest of Example.com. Only change those two listing pages.',
+    slugs: ['alphaboard-ai', 'betamatch-ai'],
+    absent: ['example-com', 'visual', 'excellent'],
+    pageOnly: true,
+  },
   {
     text: 'Work on the Example.com listing pages for AlphaBoard and BetaMatch. Delete and rebuild those two listing page implementations from a clean start, preserving the same URLs and site conventions. Fix the readability and design issues. Only change those two listing pages.',
     slugs: ['alphaboard', 'betamatch'],
@@ -85,6 +91,17 @@ for (const item of cases) {
   }
 }
+assert.deepEqual(
+  scopeSlugAliases('AgentBoard.ai'),
+  ['agentboard-ai', 'agentboard'],
+  'domain/page scope aliases should let page-owned assets omit the public suffix'
+);
+assert.deepEqual(
+  scopeSlugsMatchingText('public_html/css/agentboard.css', ['agentboard-ai']),
+  ['agentboard-ai'],
+  'scoped ownership should match page-owned assets named after the product, not only exact domain slugs'
+);
 const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: 'pipe' }).trim();
 const writeRgbPng = (filePath, width, height, sample) => {
@@ -382,9 +399,19 @@ try {
   assert.match(
     worker._formatScopeDriftNudge(worker._findScopeDriftRepoChanges(baseline, message)),
     /domain-detail\.css/i,
-    'shared stylesheet files should still be reported as out-of-scope for scoped page work'
+    'new shared-looking stylesheet files should be reported as out-of-scope until scoped pages own/link them'
+  );
+  writeFileSync(
+    alphaFixturePath,
+    alphaFixtureCurrent.replace('</head>', '<link rel="stylesheet" href="../css/domain-detail.css">\n</head>')
+  );
+  assert.equal(
+    worker._findScopeDriftRepoChanges(baseline, message).some(w => w.files.includes('public_html/css/domain-detail.css')),
+    false,
+    'new stylesheet files linked only by scoped pages should be treated as page-owned scoped assets'
   );
   rmSync(sharedCssFile, { force: true });
+  writeFileSync(alphaFixturePath, alphaFixtureCurrent);
   const directOldHtml = '<!doctype html><html><body><main><section class="hero"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
   const directInlineStyleHtml = '<!doctype html><html><body><main><section class="hero" style="padding: 4rem; color: white;"><h1>Alpha</h1><p>Existing body copy.</p></section></main></body></html>';
   assert.throws(
@@ -579,6 +606,14 @@ try {
     ),
     'scoped shell touch should allow page-owned CSS files'
   );
+  assert.doesNotThrow(
+    () => cli._guardDirectBashCommand(
+      'touch public_html/css/alpha.css',
+      fixture.repo,
+      { task: 'Work on the Example.com listing pages for Alpha.ai and Beta.ai. Only change those listing pages and directly owned assets.' }
+    ),
+    'scoped shell touch should allow page-owned CSS files that use the product name without the domain suffix'
+  );
   assert.doesNotThrow(
     () => cli._guardDirectBashCommand(
       "sed -i '' 's/Existing/Updated/g' public_html/domains/alpha.html",
@@ -587,14 +622,23 @@ try {
     ),
     'scoped shell sed should ignore the substitution script and allow canonical target page edits'
   );
-  assert.throws(
+  assert.doesNotThrow(
     () => cli._guardDirectBashCommand(
       'touch public_html/css/domain-detail.css',
       fixture.repo,
       { task: message }
     ),
-    /outside the requested task scope/i,
-    'scoped shell touch should reject shared CSS files outside the target names'
+    'direct scoped work should allow creating a new page-owned CSS asset before the target page links it'
+  );
+  const staleLinkedCssHtml = '<!doctype html><html><head><link rel="stylesheet" href="css/alpha.css"></head><body><main><section><h1>Alpha</h1><p>Fresh page body copy with rebuilt structure.</p></section></main></body></html>';
+  assert.throws(
+    () => cli._validateDirectUiFileContent(
+      path.join(fixture.repo, 'public_html', 'domains', 'alpha.html'),
+      staleLinkedCssHtml,
+      { task: 'Delete and rebuild the listing pages for Alpha.ai and Beta.ai from a clean start. Only change those listing pages and directly owned assets.' }
+    ),
+    /still links unchanged old page-owned stylesheet/i,
+    'clean-start HTML rebuilds should not keep linking unchanged old page-owned stylesheets'
   );
   const seamPng = path.join(fixture.repo, 'dominant-seam.png');
   writeRgbPng(seamPng, 900, 600, (x, y) => (
@@ -604,8 +648,8 @@ try {
   ));
   assert.match(
     cli._detectScreenshotVisualDiscontinuities(seamPng).join('\n'),
-    /hard-edged/i,
-    'screenshot discontinuity scan should catch large hard-edged rectangular seams'
+    /screenshot continuity break/i,
+    'screenshot discontinuity scan should catch large rectangular visual discontinuities'
   );
   const subtlePartialSurfacePng = path.join(fixture.repo, 'subtle-partial-surface.png');
   writeRgbPng(subtlePartialSurfacePng, 1000, 700, (x, y) => {
@@ -614,8 +658,8 @@ try {
   });
   assert.match(
     cli._detectScreenshotVisualDiscontinuities(subtlePartialSurfacePng).join('\n'),
-    /partial-surface hard-edged background\/tint block edge/i,
-    'screenshot discontinuity scan should catch large subtle partial-surface tint blocks'
+    /partial-surface screenshot continuity break/i,
+    'screenshot discontinuity scan should catch large subtle partial-surface visual discontinuities'
   );
 } finally {
   rmSync(fixture.repo, { recursive: true, force: true });
@@ -625,6 +669,8 @@ const openClawSource = readFileSync(new URL('../src/OpenClawCLI.js', import.meta
 const workerSource = readFileSync(new URL('../src/worker.js', import.meta.url), 'utf-8');
 const workerBinSource = readFileSync(new URL('../bin/agentforge.js', import.meta.url), 'utf-8');
 const defaultGuidesSource = readFileSync(new URL('../src/default-task-guides.js', import.meta.url), 'utf-8');
+const browserSource = readFileSync(new URL('../src/browser.js', import.meta.url), 'utf-8');
+const previewServerSource = readFileSync(new URL('../src/preview-server.js', import.meta.url), 'utf-8');
 const serverSource = readFileSync(new URL('../../../src/web-server-auth.js', import.meta.url), 'utf-8');
 const dashboardSource = readFileSync(new URL('../../../public/dashboard.js', import.meta.url), 'utf-8');
 assert.match(
@@ -644,13 +690,13 @@ assert.match(
 );
 assert.match(
   openClawSource,
-  /large hard-edged rectangular background\/overlay boundary across a dominant UI surface/i,
-  'screenshot discontinuity detection should fail large hard-edged visual breaks'
+  /visible screenshot continuity break across a dominant UI surface/i,
+  'screenshot discontinuity detection should fail large visual continuity breaks'
 );
 assert.match(
   openClawSource,
-  /partial-surface hard-edged background\/tint block edge/i,
-  'screenshot discontinuity detection should fail subtle partial-surface tint blocks'
+  /partial-surface screenshot continuity break/i,
+  'screenshot discontinuity detection should fail subtle partial-surface visual continuity breaks'
 );
 assert.match(
   openClawSource,
@@ -822,6 +868,26 @@ assert.match(
   /requiresComparableVisualContextForMutation/i,
   'scoped UI work should require visual reference context when local peer pages can be opened'
 );
+assert.match(
+  openClawSource,
+  /comparableSourceContextCountForMutation[\s\S]*item\.kind === 'source'/i,
+  'scoped UI comparable context should require source/code inspection, not count browser-only views as source context'
+);
+assert.match(
+  openClawSource,
+  /localBrowserContextUrls[\s\S]*directReferenceInspections[\s\S]*kind === 'browser'[\s\S]*sourceCandidateUrlPaths/i,
+  'comparable visual context should use local browser reference URLs, not only already-opened target URLs'
+);
+assert.match(
+  openClawSource,
+  /if \(!invalidScopedLoad\) rememberLocalScopedUrl/i,
+  'target pages with design warnings should still seed local peer URL discovery for visual context'
+);
+assert.match(
+  openClawSource,
+  /public_html[\s\S]*rootMappedUrl/i,
+  'visual peer URL suggestions should map static roots like public_html to browser paths'
+);
 assert.match(
   openClawSource,
   /_directUiContextByTask/i,
@@ -844,7 +910,42 @@ assert.match(
 );
 assert.match(
   openClawSource,
-  /open at least one nearby peer page from the same app\/site and inspect it visually/i,
+  /Network\.setCacheDisabled[\s\S]*waitForRequestedDocument/i,
+  'direct browser verification should bypass stale local cache and wait for the requested page before judging UI'
+);
+assert.match(
+  openClawSource,
+  /__agentforge_verify/i,
+  'direct browser verification should cache-bust local verification URLs'
+);
+assert.match(
+  openClawSource,
+  /forgetLocalScopedUrl[\s\S]*rendered page content did not identify target|rendered page content did not identify target[\s\S]*forgetLocalScopedUrl/i,
+  'wrong-page scoped browser results should invalidate remembered local preview URLs'
+);
+assert.match(
+  browserSource,
+  /setCacheEnabled\(false\)[\s\S]*waitForPageReady/i,
+  'AgentForge browser tool should bypass stale localhost cache and wait for local navigation readiness'
+);
+assert.match(
+  browserSource,
+  /__agentforge_verify/i,
+  'AgentForge browser tool should cache-bust localhost navigations'
+);
+assert.match(
+  previewServerSource,
+  /extname\(urlPath\)[\s\S]*writeHead\(404[\s\S]*no-store/i,
+  'preview server should not silently SPA-fallback explicit missing asset/page requests'
+);
+assert.match(
+  previewServerSource,
+  /Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate'/,
+  'preview server responses should disable browser/proxy caching during visual QA'
+);
+assert.match(
+  openClawSource,
+  /Open at least one nearby peer page from the same app\/site in the browser and inspect it visually/i,
   'comparable UI context guidance should require visual inspection, not source-only matching'
 );
 assert.doesNotMatch(
@@ -857,6 +958,16 @@ assert.match(
   /const minRatio = isLargeText \? 3 : 4\.5;/,
   'control/link contrast checks should use text-size-aware WCAG thresholds'
 );
+assert.match(
+  dashboardSource,
+  /typingEl\.dataset\.startedAt\s*=\s*startedAt/,
+  'live guide insertion should preserve the active feed start time for chronological reload ordering'
+);
+assert.match(
+  dashboardSource,
+  /time:\s*startedAt/,
+  'completed live feeds should save with their start time so guide bubbles appear after the feed they interrupted'
+);
 assert.match(
   defaultGuidesSource,
   /anything that reads as rendering damage rather than deliberate design/i,

package/src/OpenClawCLI.js CHANGED Viewed

@@ -11,6 +11,7 @@ import {
   extractExplicitScope,
   extractNamedPageScopeSlugs,
   hasExplicitScopeRestriction,
+  scopeSlugsMatchingText,
   scopeSlug,
 } from './taskSemantics.js';
 import treeKill from 'tree-kill';
@@ -588,6 +589,10 @@ export class OpenClawCLI extends EventEmitter {
     return scopeSlug(value);
   }
+  _directScopeSlugsMatchingText(value, slugs) {
+    return scopeSlugsMatchingText(value, slugs);
+  }
   _addDirectScopeCandidate(candidates, value) {
     return addScopeCandidate(candidates, value);
   }
@@ -604,10 +609,22 @@ export class OpenClawCLI extends EventEmitter {
     return /\.(html?|jsx?|tsx?|vue|svelte|astro|mdx?|css|scss|sass|less)$/i.test(String(relativePath || ''));
   }
+  _isDirectPageAssetPath(relativePath) {
+    return /\.(css|scss|sass|less|jsx?|tsx?)$/i.test(String(relativePath || ''));
+  }
   _isDirectHtmlPagePath(relativePath) {
     return /\.(?:html?|xhtml|astro|mdx?)$/i.test(String(relativePath || ''));
   }
+  _isDirectNewPageOwnedAssetPath(filePath, workDir, relativePath, pageOnly) {
+    if (!pageOnly || !this._isDirectPageAssetPath(relativePath)) return false;
+    if (existsSync(filePath)) return false;
+    const relative = path.relative(workDir, filePath);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) return false;
+    return true;
+  }
   _directTaskScopeAllowsPath(filePath, workDir, task) {
     const { slugs, pageOnly } = this._extractDirectExplicitScope(task);
     if (slugs.length === 0) return true;
@@ -616,8 +633,10 @@ export class OpenClawCLI extends EventEmitter {
       ? filePath
       : relative;
     const lower = String(scopePath || '').toLowerCase();
-    const slugAllowed = slugs.some(slug => lower.includes(slug));
-    if (!slugAllowed) return false;
+    const slugAllowed = this._directScopeSlugsMatchingText(lower, slugs).length > 0;
+    if (!slugAllowed) {
+      return this._isDirectNewPageOwnedAssetPath(filePath, workDir, scopePath, pageOnly);
+    }
     return !pageOnly || this._isDirectPageSourcePath(scopePath);
   }
@@ -645,7 +664,7 @@ export class OpenClawCLI extends EventEmitter {
         if (!entry.isFile() || !this._isDirectPageSourcePath(entry.name)) continue;
         const rel = path.relative(workDir, fullPath) || fullPath;
         const lower = rel.toLowerCase();
-        if (slugs.some(slug => lower.includes(slug)) && !results.includes(rel)) results.push(rel);
+        if (this._directScopeSlugsMatchingText(lower, slugs).length > 0 && !results.includes(rel)) results.push(rel);
       }
 	    };
 	    walk(workDir, 0);
@@ -670,7 +689,8 @@ export class OpenClawCLI extends EventEmitter {
       `Requested path: ${relative || filePath}`,
       `Allowed scope tokens: ${slugs.join(', ')}${pageOnly ? ' (page/source files only)' : ''}.`,
       candidateText.trim(),
-      'Use a target file inside the requested scope, or restore out-of-scope changes with git if you are cleaning up a previous mistake.',
+      'Use a target file inside the requested scope, a page-local <style> block, or a new page-owned CSS/JS asset that is linked only from the requested target pages.',
+      'Do not edit shared/global files such as universal, base, reset, layout, or component styles unless the user explicitly asks for shared-site changes.',
     ].filter(Boolean).join(' ');
   }
@@ -806,7 +826,7 @@ export class OpenClawCLI extends EventEmitter {
       throw this._directScopeViolationError(this._formatDirectScopeError(filePath, workDir, options.task));
     }
     if (pageOnly && slugs.length > 0 && this._isDirectHtmlPagePath(relativePath)) {
-      const matchedSlugs = slugs.filter(slug => lowerRelativePath.includes(slug));
+      const matchedSlugs = this._directScopeSlugsMatchingText(lowerRelativePath, slugs);
       const isTrackedTarget = this._gitTracksExactPath(workDir, relativePath);
       if (matchedSlugs.length > 0 && !existsSync(filePath) && !isTrackedTarget) {
         const existingPages = this._directScopeFileCandidates(workDir, matchedSlugs, 20)
@@ -924,7 +944,7 @@ export class OpenClawCLI extends EventEmitter {
     const { slugs, pageOnly } = this._extractDirectExplicitScope(options?.task);
     if (!pageOnly || slugs.length === 0) return;
     const lowerPath = String(filePath || '').toLowerCase();
-    const matchingSlugs = slugs.filter(slug => lowerPath.includes(slug));
+    const matchingSlugs = this._directScopeSlugsMatchingText(lowerPath, slugs);
     if (matchingSlugs.length === 0) return;
     const root = this._gitRootForPath(filePath);
@@ -942,7 +962,7 @@ export class OpenClawCLI extends EventEmitter {
     const targetPageFiles = trackedFiles.filter(rel => {
       const lower = rel.toLowerCase();
       if (!/\.(?:html?|xhtml|jsx?|tsx?|vue|svelte|astro|mdx?)$/i.test(lower)) return false;
-      return matchingSlugs.some(slug => lower.includes(slug));
+      return scopeSlugsMatchingText(lower, matchingSlugs).length > 0;
     });
     if (targetPageFiles.length === 0) return;
@@ -1011,10 +1031,77 @@ export class OpenClawCLI extends EventEmitter {
     }
   }
+  _validateDirectCleanStartHtmlDoesNotReuseOldPageStylesheet(filePath, content, options = {}) {
+    if (!this._isDirectBroadUiQualityTask(options?.task)) return;
+    if (!/\.(?:html?|xhtml|astro|mdx?)$/i.test(String(filePath || ''))) return;
+    const taskText = String(options?.task || '');
+    const isCleanStartTask = /\b(?:delete|rebuild|clean start|from scratch|start over|fresh|remake)\b/i.test(taskText);
+    if (!isCleanStartTask) return;
+    const { slugs, pageOnly } = this._extractDirectExplicitScope(options?.task);
+    if (!pageOnly || slugs.length === 0) return;
+    const matchingSlugs = this._directScopeSlugsMatchingText(filePath, slugs);
+    if (matchingSlugs.length === 0) return;
+    const root = this._gitRootForPath(filePath);
+    if (!root) return;
+    let pageDir = path.dirname(filePath);
+    try {
+      pageDir = path.dirname(realpathSync(filePath));
+    } catch {}
+    const staleLinks = [];
+    const html = String(content || '');
+    for (const tagMatch of html.matchAll(/<link\b[^>]*>/gi)) {
+      const tag = tagMatch[0] || '';
+      if (!/\brel\s*=\s*["'][^"']*\bstylesheet\b[^"']*["']/i.test(tag)) continue;
+      const href = tag.match(/\bhref\s*=\s*["']([^"']+)["']/i)?.[1] || '';
+      if (!href || /^(?:https?:|data:|blob:|\/\/)/i.test(href)) continue;
+      const cleanHref = href.split(/[?#]/)[0];
+      if (!cleanHref || !/\.css$/i.test(cleanHref)) continue;
+      const absolute = path.resolve(pageDir, cleanHref);
+      const rel = path.relative(root, absolute).replace(/\\/g, '/');
+      if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+      if (this._directScopeSlugsMatchingText(rel, matchingSlugs).length === 0) continue;
+      let headCss = null;
+      try {
+        headCss = String(execFileSync('git', ['-C', root, 'show', `HEAD:${rel}`], {
+          encoding: 'utf-8',
+          maxBuffer: 5 * 1024 * 1024,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        }) || '');
+      } catch {
+        continue;
+      }
+      if (!existsSync(absolute)) continue;
+      let currentCss = '';
+      try {
+        currentCss = readFileSync(absolute, 'utf-8');
+      } catch {
+        continue;
+      }
+      if (this._cssComparableLines(headCss).join('\n') === this._cssComparableLines(currentCss).join('\n')) {
+        staleLinks.push(rel);
+      }
+    }
+    if (staleLinks.length === 0) return;
+    const err = new Error([
+      'Rejected clean-start page rebuild because the new HTML still links unchanged old page-owned stylesheet(s).',
+      `Stale stylesheet(s): ${[...new Set(staleLinks)].slice(0, 4).join(', ')}.`,
+      'For clean-start scoped page work, delete or materially rewrite old page-owned stylesheets, or move the design into a fresh page-local style block before linking the rebuilt page.',
+    ].join(' '));
+    err.code = 'AGENTFORGE_UI_STALE_PAGE_STYLESHEET';
+    throw err;
+  }
   _validateDirectUiImplementationArtifacts(filePath, content, options = {}) {
     if (!this._isDirectBroadUiQualityTask(options?.task)) return;
     if (!/\.(?:html?|xhtml|css|s[ac]ss|jsx?|tsx?|vue|svelte|astro|mdx?)$/i.test(String(filePath || ''))) return;
     this._validateDirectPageOwnedStylesheetIsFresh(filePath, content, options);
+    this._validateDirectCleanStartHtmlDoesNotReuseOldPageStylesheet(filePath, content, options);
     const oldText = String(options?.oldContent || '');
     const headText = this._gitHeadContentForPath(filePath);
@@ -1220,7 +1307,7 @@ export class OpenClawCLI extends EventEmitter {
       .filter(line => {
         if (slugs.length === 0) return true;
         const lower = line.toLowerCase();
-        return slugs.some(slug => lower.includes(slug));
+        return scopeSlugsMatchingText(lower, slugs).length > 0;
       });
     if (scopedLines.length === 0) return '';
@@ -2662,6 +2749,29 @@ export class OpenClawCLI extends EventEmitter {
         return String(value || '').replace(/\/$/, '');
       }
     };
+    const stripAgentForgeCacheBust = (value) => {
+      try {
+        const parsed = new URL(value);
+        parsed.searchParams.delete('__agentforge_verify');
+        return parsed.href.replace(/\/$/, '');
+      } catch {
+        return String(value || '').replace(/([?&])__agentforge_verify=[^&#]+&?/, '$1').replace(/[?&]$/, '').replace(/\/$/, '');
+      }
+    };
+    const normalizeForNavigationCompare = (value) => stripAgentForgeCacheBust(normalize(value));
+    const isLocalHttpUrl = (value) =>
+      /^https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)/i.test(String(value || ''));
+    const withVerificationCacheBust = (value) => {
+      if (!value || !isLocalHttpUrl(value)) return value;
+      try {
+        const parsed = new URL(value);
+        parsed.searchParams.set('__agentforge_verify', `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+        return parsed.href;
+      } catch {
+        const sep = String(value).includes('?') ? '&' : '?';
+        return `${value}${sep}__agentforge_verify=${Date.now()}`;
+      }
+    };
     const listResp = await fetch(`${cdpBase}/json/list`, { signal: AbortSignal.timeout(5_000) });
     if (!listResp.ok) throw new Error(`CDP list failed: HTTP ${listResp.status}`);
@@ -2674,6 +2784,9 @@ export class OpenClawCLI extends EventEmitter {
       /^https?:\/\/agentforgeai-production\.up\.railway\.app\/dashboard(?:[/?#]|$)/i.test(String(value || ''));
     const rememberedUrl = this._directBrowserLastUrlByAgent.get(agentId) || null;
     const effectiveRequestedUrl = requestedUrl || rememberedUrl || null;
+    const navigationRequestedUrl = options?.afterMutation
+      ? withVerificationCacheBust(effectiveRequestedUrl)
+      : effectiveRequestedUrl;
     const usablePages = !taskIsAboutAgentForge
       ? pages.filter(p => !isAgentForgeControlSurface(p.url))
       : pages;
@@ -2690,7 +2803,7 @@ export class OpenClawCLI extends EventEmitter {
     }
     if (!page) {
-      const newUrl = effectiveRequestedUrl || 'about:blank';
+      const newUrl = navigationRequestedUrl || effectiveRequestedUrl || 'about:blank';
       const newResp = await fetch(`${cdpBase}/json/new?${encodeURIComponent(newUrl)}`, {
         method: 'PUT',
         signal: AbortSignal.timeout(5_000),
@@ -2749,12 +2862,42 @@ export class OpenClawCLI extends EventEmitter {
     try {
       await cdp('Page.enable');
       await cdp('Runtime.enable');
-      if (effectiveRequestedUrl && normalize(page.url) !== normalize(effectiveRequestedUrl)) {
-        await cdp('Page.navigate', { url: effectiveRequestedUrl });
-        await new Promise(r => setTimeout(r, 2_000));
+      await cdp('Network.enable').catch(() => null);
+      await cdp('Network.setCacheDisabled', { cacheDisabled: true }).catch(() => null);
+      const waitForRequestedDocument = async (expectedUrl) => {
+        const expectedComparable = expectedUrl ? normalizeForNavigationCompare(expectedUrl) : '';
+        let lastState = null;
+        for (let i = 0; i < 45; i++) {
+          try {
+            const stateResult = await cdp('Runtime.evaluate', {
+              expression: `(() => ({ href: location.href, readyState: document.readyState, bodyLength: document.body ? document.body.innerText.length : 0 }))()`,
+              awaitPromise: true,
+              returnByValue: true,
+            });
+            lastState = stateResult?.result?.value || null;
+            const currentComparable = normalizeForNavigationCompare(lastState?.href || '');
+            const urlReady = !expectedComparable || currentComparable === expectedComparable;
+            const documentReady = lastState?.readyState && lastState.readyState !== 'loading';
+            if (urlReady && documentReady) return lastState;
+          } catch {
+            // The old page context can disappear while the new document commits.
+          }
+          await new Promise(r => setTimeout(r, 200));
+        }
+        if (options?.afterMutation && expectedComparable && lastState?.href) {
+          const currentComparable = normalizeForNavigationCompare(lastState.href);
+          if (currentComparable !== expectedComparable) {
+            throw new Error(`Browser failed to load requested verification URL ${stripAgentForgeCacheBust(expectedUrl)}; current tab is ${stripAgentForgeCacheBust(lastState.href)}`);
+          }
+        }
+        return lastState;
+      };
+      if (effectiveRequestedUrl && normalizeForNavigationCompare(page.url) !== normalizeForNavigationCompare(effectiveRequestedUrl)) {
+        await cdp('Page.navigate', { url: navigationRequestedUrl || effectiveRequestedUrl });
+        await waitForRequestedDocument(effectiveRequestedUrl);
       } else if (effectiveRequestedUrl) {
         await cdp('Page.reload', { ignoreCache: true });
-        await new Promise(r => setTimeout(r, 1_500));
+        await waitForRequestedDocument(effectiveRequestedUrl);
       }
       if (effectiveRequestedUrl) {
         await cdp('Runtime.evaluate', {
@@ -2985,7 +3128,7 @@ export class OpenClawCLI extends EventEmitter {
           horizontal.y < height * 0.94;
         if (!awayFromViewportEdge) continue;
         warnings.push([
-          `large hard-edged rectangular background/overlay boundary across a dominant UI surface near x=${vertical.x}, y=${horizontal.y}`,
+          `visible screenshot continuity break across a dominant UI surface near x=${vertical.x}, y=${horizontal.y}`,
           `(vertical span y=${vertical.minY}-${vertical.maxY}, horizontal span x=${horizontal.minX}-${horizontal.maxX})`,
         ].join(' '));
         break;
@@ -3001,7 +3144,7 @@ export class OpenClawCLI extends EventEmitter {
         edge.average >= 38
       );
       if (dominantVertical) {
-        warnings.push(`large hard-edged vertical background/overlay seam across a dominant UI surface near x=${dominantVertical.x} spanning y=${dominantVertical.minY}-${dominantVertical.maxY}`);
+        warnings.push(`visible vertical screenshot continuity break across a dominant UI surface near x=${dominantVertical.x} spanning y=${dominantVertical.minY}-${dominantVertical.maxY}`);
       }
     }
@@ -3054,7 +3197,7 @@ export class OpenClawCLI extends EventEmitter {
       }
       if (partialHorizontal) {
-        warnings.push(`large partial-surface hard-edged background/tint block edge near y=${partialHorizontal.y}, running from x=${partialHorizontal.start} to x=${partialHorizontal.end}. This often indicates an unintended rectangular overlay, cropped layer, or mismatched background plane.`);
+        warnings.push(`visible partial-surface screenshot continuity break near y=${partialHorizontal.y}, running from x=${partialHorizontal.start} to x=${partialHorizontal.end}`);
       }
     }
@@ -3106,7 +3249,7 @@ export class OpenClawCLI extends EventEmitter {
       }
       if (partialVertical) {
-        warnings.push(`large partial-surface hard-edged background/tint block edge near x=${partialVertical.x}, running from y=${partialVertical.start} to y=${partialVertical.end}. This often indicates an unintended rectangular overlay, cropped layer, or mismatched background plane.`);
+        warnings.push(`visible partial-surface screenshot continuity break near x=${partialVertical.x}, running from y=${partialVertical.start} to y=${partialVertical.end}`);
       }
     }
     return warnings;
@@ -3554,7 +3697,7 @@ export class OpenClawCLI extends EventEmitter {
         try { return new URL(summaryUrl || requestedUrl || 'http://invalid.local/').pathname || ''; } catch { return ''; }
       })();
       const isAssetBrowserTarget = /\.(?:png|jpe?g|gif|webp|svg|ico|css|js|mjs|json|map|pdf|txt|xml|woff2?|ttf|otf)(?:$|[?#])/i.test(browserPathText);
-      const matchedScopedSlugs = explicitScopeSlugs.filter(slug => browserScopeUrlText.includes(slug));
+      const matchedScopedSlugs = scopeSlugsMatchingText(browserScopeUrlText, explicitScopeSlugs);
       const isScopedBrowserTarget =
         explicitScopeSlugs.length === 0 ||
         matchedScopedSlugs.length > 0;
@@ -3707,7 +3850,7 @@ export class OpenClawCLI extends EventEmitter {
         ? `${visualWarningPrefix}: ${summary.brokenImages.length} visible image(s) failed to load: ${summary.brokenImages.map(img => img.alt || img.src || '(unlabeled image)').join(', ')}. ${visualWarningTail}`
         : '';
       const screenshotDiscontinuityWarning = screenshotDiscontinuityWarnings.length > 0
-        ? `${visualWarningPrefix}: screenshot shows ${screenshotDiscontinuityWarnings.slice(0, 2).join('; ')}. Rework the affected layout/background/layering so the changed screen reads as intentional, then verify the page again. ${visualWarningTail}`
+        ? `${visualWarningPrefix}: screenshot pixel scan flagged visible continuity issue(s): ${screenshotDiscontinuityWarnings.slice(0, 2).join('; ')}. Inspect the screenshot and source to identify the actual rendering cause, then rework the affected layout/background/layering so the changed screen reads as intentional. Verify the page again. ${visualWarningTail}`
         : '';
       const reportLowContrastControls = options?.afterMutation && isScopedBrowserTarget && explicitScopeSlugs.length > 0
         ? (summary.lowContrastControls || []).filter(c => !c.chrome)
@@ -4091,8 +4234,7 @@ export class OpenClawCLI extends EventEmitter {
       return resolveDirectToolPath(args?.path || args?.file_path);
     };
     const scopeSlugsInText = (value) => {
-      const text = String(value || '').toLowerCase();
-      return explicitScopeSlugsForTask.filter(slug => text.includes(slug));
+      return scopeSlugsMatchingText(value, explicitScopeSlugsForTask);
     };
     const uiSourcePathInfo = (inputPath) => {
       const candidate = String(inputPath || '').trim();
@@ -4160,20 +4302,20 @@ export class OpenClawCLI extends EventEmitter {
       const candidates = comparableSiblingSourceCandidates(fileWriteTarget);
       return candidates.length >= 2 ? 2 : 1;
     };
-    const comparableUiContextCountForMutation = (fileWriteTarget = null) => {
+    const comparableSourceContextCountForMutation = (fileWriteTarget = null) => {
       rememberTargetUiSource(fileWriteTarget);
       const dirsWithSiblings = [...directTargetUiSourceDirs].filter(hasComparableSiblingSource);
       if (dirsWithSiblings.length > 0) {
         const matching = directReferenceInspections.filter(item => {
           if (item.kind === 'source' && dirsWithSiblings.includes(item.dir)) return true;
-          if (item.kind === 'browser' && item.urlPathDir) {
-            return dirsWithSiblings.some(dir => dir.replace(/\\/g, '/').endsWith(item.urlPathDir));
-          }
           return false;
         });
-        return new Set(matching.map(item => `${item.kind}:${item.value}`)).size;
+        return new Set(matching.map(item => item.value)).size;
       }
-      return new Set(directReferenceInspections.map(item => `${item.kind}:${item.value}`)).size;
+      return new Set(directReferenceInspections.filter(item => item.kind === 'source').map(item => item.value)).size;
+    };
+    const comparableUiContextCountForMutation = (fileWriteTarget = null) => {
+      return comparableSourceContextCountForMutation(fileWriteTarget);
     };
     const comparableVisualContextCountForMutation = (fileWriteTarget = null) => {
       rememberTargetUiSource(fileWriteTarget);
@@ -4185,11 +4327,39 @@ export class OpenClawCLI extends EventEmitter {
       });
       return new Set(matching.map(item => item.value)).size;
     };
+    const localBrowserContextUrls = () => {
+      const urls = [...directLocalScopedUrls];
+      for (const item of directReferenceInspections) {
+        if (item.kind === 'browser' && isLocalUiUrl(item.value) && !urls.includes(item.value)) {
+          urls.push(item.value);
+        }
+      }
+      return urls;
+    };
+    const sourceCandidateUrlPaths = (candidate) => {
+      const rel = String(candidate || '').replace(/\\/g, '/').replace(/^\/+/, '');
+      const paths = [];
+      const add = (value) => {
+        const normalized = `/${String(value || '').replace(/^\/+/, '')}`;
+        if (!paths.includes(normalized)) paths.push(normalized);
+      };
+      for (const root of ['public_html', 'public', 'static', 'dist', 'build']) {
+        if (rel === root || rel.startsWith(`${root}/`)) {
+          add(rel.slice(root.length).replace(/^\/+/, ''));
+        }
+        const marker = `/${root}/`;
+        const idx = rel.indexOf(marker);
+        if (idx >= 0) add(rel.slice(idx + marker.length));
+      }
+      add(path.basename(rel));
+      return paths;
+    };
     const comparableBrowserUrlCandidates = (fileWriteTarget = null) => {
       const sourceCandidates = comparableSiblingSourceCandidates(fileWriteTarget);
-      if (!sourceCandidates.length || directLocalScopedUrls.length === 0) return [];
+      const baseUrls = localBrowserContextUrls();
+      if (!sourceCandidates.length || baseUrls.length === 0) return [];
       const urls = [];
-      for (const knownUrl of [...directLocalScopedUrls].reverse()) {
+      for (const knownUrl of [...baseUrls].reverse()) {
         let parsed = null;
         try { parsed = new URL(knownUrl); } catch { parsed = null; }
         if (!parsed) continue;
@@ -4197,18 +4367,27 @@ export class OpenClawCLI extends EventEmitter {
         const basePath = slash >= 0 ? parsed.pathname.slice(0, slash + 1) : '/';
         for (const candidate of sourceCandidates) {
           parsed.pathname = `${basePath}${path.basename(candidate)}`;
-          const next = parsed.href;
-          if (!urls.includes(next)) urls.push(next);
+          parsed.search = '';
+          parsed.hash = '';
+          const sameDirUrl = parsed.href;
+          if (!urls.includes(sameDirUrl)) urls.push(sameDirUrl);
+          for (const urlPath of sourceCandidateUrlPaths(candidate)) {
+            parsed.pathname = urlPath;
+            parsed.search = '';
+            parsed.hash = '';
+            const rootMappedUrl = parsed.href;
+            if (!urls.includes(rootMappedUrl)) urls.push(rootMappedUrl);
+          }
           if (urls.length >= 4) return urls;
         }
       }
       return urls;
     };
     const requiresComparableVisualContextForMutation = (fileWriteTarget = null) => {
-      return directLocalScopedUrls.length > 0 && comparableSiblingSourceCandidates(fileWriteTarget).length > 0;
+      return localBrowserContextUrls().length > 0 && comparableSiblingSourceCandidates(fileWriteTarget).length > 0;
     };
     const hasComparableUiContextForMutation = (fileWriteTarget = null) => {
-      const hasSourceContext = comparableUiContextCountForMutation(fileWriteTarget) >= requiredComparableUiContextCount(fileWriteTarget);
+      const hasSourceContext = comparableSourceContextCountForMutation(fileWriteTarget) >= requiredComparableUiContextCount(fileWriteTarget);
       if (!hasSourceContext) return false;
       if (!requiresComparableVisualContextForMutation(fileWriteTarget)) return true;
       return comparableVisualContextCountForMutation(fileWriteTarget) >= 1;
@@ -4246,17 +4425,18 @@ export class OpenClawCLI extends EventEmitter {
     const missingComparableUiContextMessage = (fileWriteTarget = null) => {
       const siblingCandidates = comparableSiblingSourceCandidates(fileWriteTarget);
       const requiredCount = requiredComparableUiContextCount(fileWriteTarget);
-      const currentCount = comparableUiContextCountForMutation(fileWriteTarget);
+      const currentSourceCount = comparableSourceContextCountForMutation(fileWriteTarget);
+      const currentVisualCount = comparableVisualContextCountForMutation(fileWriteTarget);
       const candidateText = siblingCandidates.length > 0
         ? ` Read ${requiredCount === 1 ? 'one nearby peer source file' : 'at least two nearby peer source files'} first, for example: ${siblingCandidates.join(', ')}.`
         : '';
       const browserCandidates = comparableBrowserUrlCandidates(fileWriteTarget);
       const needsVisualContext = requiresComparableVisualContextForMutation(fileWriteTarget);
       const visualContextText = needsVisualContext
-        ? ` Also open at least one nearby peer page from the same app/site and inspect it visually before editing. Current comparable visual context: ${comparableVisualContextCountForMutation(fileWriteTarget)}/1.${browserCandidates.length > 0 ? ` Example local peer URL(s): ${browserCandidates.join(', ')}.` : ''}`
+        ? ` Open at least one nearby peer page from the same app/site in the browser and inspect it visually before editing. Current comparable visual context: ${currentVisualCount}/1.${browserCandidates.length > 0 ? ` Example local peer URL(s): ${browserCandidates.join(', ')}.` : ''}`
         : '';
       return [
-        `Before editing scoped UI pages, inspect ${requiredCount === 1 ? 'at least one comparable local UI surface' : 'at least two comparable local UI surfaces'} from this project. Current comparable page-level context: ${currentCount}/${requiredCount}.`,
+        `Before editing scoped UI pages, inspect ${requiredCount === 1 ? 'at least one comparable local UI surface' : 'at least two comparable local UI surfaces'} from this project. Current comparable source context: ${currentSourceCount}/${requiredCount}.`,
         'When comparable sibling pages/components exist near the target source, use one of those as read-only design-system context.',
         'Do not count the site homepage, index/listing pages, header/footer partials, or shared/global CSS as the required page-level comparable context.',
         'Shared/global CSS can supplement peer context, but it is not enough by itself for page-level design work.',
@@ -4304,7 +4484,15 @@ export class OpenClawCLI extends EventEmitter {
     };
     const browserResultUrl = (result) => {
       const match = String(result || '').match(/^URL:\s*(.+)$/mi);
-      return match?.[1]?.trim() || '';
+      const url = match?.[1]?.trim() || '';
+      if (!url) return '';
+      try {
+        const parsed = new URL(url);
+        parsed.searchParams.delete('__agentforge_verify');
+        return parsed.href;
+      } catch {
+        return url.replace(/([?&])__agentforge_verify=[^&#]+&?/, '$1').replace(/[?&]$/, '');
+      }
     };
     const isLocalUiUrl = (url) =>
       /^(?:https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)|file:)/i.test(String(url || ''));
@@ -4326,6 +4514,15 @@ export class OpenClawCLI extends EventEmitter {
       if (directLocalScopedUrls.length > 8) directLocalScopedUrls.shift();
       persistDirectUiContext();
     };
+    const forgetLocalScopedUrl = (slug, url = '') => {
+      if (slug && directLocalUrlsByScope.get(slug) === url) directLocalUrlsByScope.delete(slug);
+      if (url) {
+        for (let i = directLocalScopedUrls.length - 1; i >= 0; i--) {
+          if (directLocalScopedUrls[i] === url) directLocalScopedUrls.splice(i, 1);
+        }
+      }
+      persistDirectUiContext();
+    };
     const missingScopedVerificationSlugs = () =>
       [...directScopeLastMutationCounts.keys()]
         .filter(slug => (directScopeLastVerificationCounts.get(slug) || 0) < (directScopeLastMutationCounts.get(slug) || 0));
@@ -4425,6 +4622,9 @@ export class OpenClawCLI extends EventEmitter {
         directBrowserUsed = true;
         const visualWarning = extractVisualWarning(result);
         if (visualWarning) {
+          if (/rendered page content did not identify target|local server returned a fallback\/index page|Browser failed to load/i.test(visualWarning)) {
+            forgetLocalScopedUrl(slug, url);
+          }
           visualWarnings.push(`${slug}: ${visualWarning}`);
           recordDirectToolSummary('browser', result);
           continue;
@@ -4450,7 +4650,7 @@ export class OpenClawCLI extends EventEmitter {
       const urlText = match?.[1]?.trim() || '';
       if (!urlText) return false;
       const { slugs } = this._extractDirectExplicitScope(task);
-      if (slugs.length > 0 && !slugs.some(slug => urlText.toLowerCase().includes(slug))) return false;
+      if (slugs.length > 0 && scopeSlugsMatchingText(urlText, slugs).length === 0) return false;
       return /^(?:https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)|file:)/i.test(urlText);
     };
     const extractVisualWarning = (result) => {
@@ -4809,7 +5009,7 @@ export class OpenClawCLI extends EventEmitter {
               const message = missingComparableUiContextMessage(fileWriteTarget);
               directComparableContextBlockCount += 1;
               comparableContextBlockThisBatch = message;
-              emitDirectThought('AgentForge blocked the first scoped UI edit because comparable project UI context has not been inspected yet.');
+              emitDirectThought('AgentForge blocked a scoped UI edit because comparable project UI context has not been inspected yet.');
               this.emit('tool_activity', {
                 agentId,
                 event: 'tool_error',
@@ -4884,7 +5084,14 @@ export class OpenClawCLI extends EventEmitter {
               if (name === 'browser') {
                 directBrowserUsed = true;
                 const visualWarning = extractVisualWarning(result);
-                if (!visualWarning) rememberLocalScopedUrl(browserResultUrl(result));
+                const resultUrl = browserResultUrl(result);
+                const invalidScopedLoad = /rendered page content did not identify target|local server returned a fallback\/index page|Browser failed to load/i.test(visualWarning || '');
+                if (!invalidScopedLoad) rememberLocalScopedUrl(resultUrl || args?.url || '');
+                else {
+                  for (const slug of scopeSlugsInText(`${resultUrl}\n${args?.url || ''}`)) {
+                    forgetLocalScopedUrl(slug, resultUrl || args?.url || '');
+                  }
+                }
                 if (directMutationCount > 0) {
                   if (visualWarning) {
                     lastDirectVisualWarning = visualWarning;
@@ -4931,7 +5138,7 @@ export class OpenClawCLI extends EventEmitter {
                 text: [
                   'The previous write was rejected because it was outside the requested task scope.',
                   scopeViolationThisBatch,
-                  'Do not retry shared, global, or reference files. Implement the required UI changes inside the named target files or their directly owned assets only. If styling is needed, use page-local styles in those target files.',
+                  'Do not retry shared, global, or reference files. Implement the required UI changes inside the named target files or their directly owned assets only. If styling is needed, use page-local styles in those target files or page-owned scoped stylesheets whose names clearly match the target page.',
                 ].join(' '),
               }],
             });
@@ -4940,9 +5147,9 @@ export class OpenClawCLI extends EventEmitter {
           if (comparableContextBlockThisBatch) {
             if (directComparableContextBlockCount >= 3) {
               return directStopResponse([
-                'The model repeatedly tried to edit scoped UI before inspecting a non-target peer UI source.',
+                'The model repeatedly tried to edit scoped UI before inspecting non-target peer UI context.',
                 comparableContextBlockThisBatch,
-                'This is not complete. Continue in a fresh iteration by reading one non-target sibling page/component first, then edit only the requested target files.',
+                'This is not complete. Continue in a fresh iteration by reading non-target sibling page/component source and opening a nearby peer page in the browser when a local preview is available, then edit only the requested target files.',
               ].join(' '), true);
             }
             contents.push({
@@ -4951,7 +5158,7 @@ export class OpenClawCLI extends EventEmitter {
                 text: [
                   'The previous edit was rejected because comparable project UI context has not been inspected yet.',
                   comparableContextBlockThisBatch,
-                  'Reading another requested target page does not satisfy this requirement. Read one non-target sibling page/component source from the candidate list first, then edit only the requested target files.',
+                  'Reading another requested target page does not satisfy this requirement. Read non-target sibling page/component source from the candidate list and, when a local peer URL is provided, open that peer page in the browser before editing only the requested target files.',
                 ].join(' '),
               }],
             });

package/src/browser.js CHANGED Viewed

@@ -54,6 +54,47 @@ async function getPage(agentId, preferUrl) {
 const _wait = (ms) => new Promise(r => setTimeout(r, ms));
+function isLocalHttpUrl(value) {
+  return /^https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(?::\d+)?(?:\/|$)/i.test(String(value || ''));
+}
+function withLocalCacheBust(value) {
+  if (!isLocalHttpUrl(value)) return value;
+  try {
+    const parsed = new URL(value);
+    parsed.searchParams.set('__agentforge_verify', `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    return parsed.href;
+  } catch {
+    const sep = String(value).includes('?') ? '&' : '?';
+    return `${value}${sep}__agentforge_verify=${Date.now()}`;
+  }
+}
+async function waitForPageReady(page, expectedUrl) {
+  const stripCacheBust = (value) => {
+    try {
+      const parsed = new URL(value);
+      parsed.searchParams.delete('__agentforge_verify');
+      return parsed.href.replace(/\/$/, '');
+    } catch {
+      return String(value || '').replace(/([?&])__agentforge_verify=[^&#]+&?/, '$1').replace(/[?&]$/, '').replace(/\/$/, '');
+    }
+  };
+  const expected = expectedUrl ? stripCacheBust(expectedUrl) : '';
+  for (let i = 0; i < 45; i++) {
+    try {
+      const state = await page.evaluate(() => ({
+        href: location.href,
+        readyState: document.readyState,
+      }));
+      if ((!expected || stripCacheBust(state.href) === expected) && state.readyState !== 'loading') return;
+    } catch {
+      // Page contexts can disappear while navigation commits.
+    }
+    await _wait(200);
+  }
+}
 // Take a structured snapshot of a page — content + interactive elements + all inputs
 async function _snapshot(page, agentId) {
   const url = page.url();
@@ -160,9 +201,11 @@ async function _browserActionInner(input, agentId, browser) {
       case 'open': {
         const url = input.url || input.targetUrl;
         const page = await getPage(agentId);
+        await page.setCacheEnabled(false).catch(() => null);
+        const navigationUrl = withLocalCacheBust(url);
         // Use Promise.race to enforce a hard 20s cap — page.goto timeout option can hang
         const navResult = await Promise.race([
-          page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 }),
+          page.goto(navigationUrl, { waitUntil: 'domcontentloaded', timeout: 20000 }),
           new Promise((_, rej) => setTimeout(() => rej(new Error(`Navigation hard-timeout (20s): ${url}`)), 20000)),
         ]).catch(err => ({ __navError: err.message }));
         if (navResult && navResult.__navError) {
@@ -171,6 +214,7 @@ async function _browserActionInner(input, agentId, browser) {
         }
         _agentPages.set(agentId, page);
         // Brief pause for initial render, then snapshot
+        await waitForPageReady(page, url);
         await _wait(400);
         return await _snapshot(page, agentId);
       }

package/src/preview-server.js CHANGED Viewed

@@ -225,6 +225,11 @@ const server = createServer(async (req, res) => {
   }
   if (!existsSync(filePath)) {
+    if (extname(urlPath)) {
+      res.writeHead(404, { 'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate' });
+      res.end('Not found');
+      return;
+    }
     // SPA fallback
     const fallback = join(serveDir, 'index.html');
     if (existsSync(fallback)) filePath = fallback;
@@ -245,7 +250,12 @@ const server = createServer(async (req, res) => {
       content = html;
     }
-    res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'no-cache' });
+    res.writeHead(200, {
+      'Content-Type': mime,
+      'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+      'Pragma': 'no-cache',
+      'Expires': '0',
+    });
     res.end(content);
   } catch (e) {
     res.writeHead(500); res.end('Server error');

package/src/taskSemantics.js CHANGED Viewed

@@ -1,6 +1,9 @@
 const PAGE_KIND_RE = /\b(?:pages?|screens?|routes?|views?|listings?)\b/i;
 const PAGE_KIND_WORD_RE = /^(?:listing|listings|page|pages|screen|screens|route|routes|view|views|site|website|app)$/i;
 const ACTION_WORD_RE = /^(?:add|build|change|create|edit|fix|implement|improve|make|redesign|update|work)$/i;
+const COMMON_DOMAIN_SUFFIXES = new Set([
+  'ai', 'app', 'co', 'com', 'dev', 'gg', 'io', 'net', 'org', 'so', 'xyz',
+]);
 const GENERIC_SCOPE_WORDS = new Set([
   'a', 'an', 'the', 'and', 'or', 'page', 'pages', 'screen', 'screens',
@@ -28,6 +31,31 @@ export function scopeSlug(value) {
     .replace(/^-+|-+$/g, '');
 }
+export function scopeSlugAliases(value) {
+  const slug = scopeSlug(value);
+  if (!slug) return [];
+  const aliases = new Set([slug]);
+  const parts = slug.split('-').filter(Boolean);
+  const suffix = parts.at(-1);
+  if (parts.length > 1 && COMMON_DOMAIN_SUFFIXES.has(suffix)) {
+    const withoutSuffix = parts.slice(0, -1).join('-');
+    if (withoutSuffix.length >= 3 && !GENERIC_SCOPE_WORDS.has(withoutSuffix)) {
+      aliases.add(withoutSuffix);
+      const compact = withoutSuffix.replace(/-/g, '');
+      if (compact.length >= 4 && !GENERIC_SCOPE_WORDS.has(compact)) aliases.add(compact);
+    }
+  }
+  return [...aliases];
+}
+export function scopeSlugsMatchingText(value, slugs) {
+  const text = String(value || '').toLowerCase();
+  return (Array.isArray(slugs) ? slugs : [])
+    .filter(slug => scopeSlugAliases(slug).some(alias => alias && text.includes(alias)));
+}
 export function scopeExtractionText(message) {
   const raw = String(message || '');
   const taskMatches = [...raw.matchAll(/\b(?:The task is|Continue with the task):\s*"([^"]{1,4000})"/gi)];
@@ -116,11 +144,18 @@ export function extractExplicitScopeSlugs(message) {
   }
   const candidates = new Set();
+  const namedPageScopeSlugs = extractNamedPageScopeSlugs(text);
+  const pageContainerSlugs = new Set();
   for (const match of text.matchAll(/\b[a-z0-9]+(?:[.-][a-z0-9]+)+\b/gi)) {
-    if (followedByNamedPageTargets(text, match)) continue;
+    if (followedByNamedPageTargets(text, match)) {
+      const slug = scopeSlug(match[0]);
+      if (!namedPageScopeSlugs.includes(slug)) pageContainerSlugs.add(slug);
+      continue;
+    }
+    if (pageContainerSlugs.has(scopeSlug(match[0]))) continue;
     addScopeCandidate(candidates, match[0]);
   }
-  for (const slug of extractNamedPageScopeSlugs(text)) {
+  for (const slug of namedPageScopeSlugs) {
     candidates.add(slug);
   }
   return [...candidates];

package/src/worker.js CHANGED Viewed

@@ -9,6 +9,7 @@ import {
   extractExplicitScopeSlugs,
   extractNamedPageScopeSlugs,
   hasExplicitScopeRestriction,
+  scopeSlugsMatchingText,
   scopeSlug,
 } from './taskSemantics.js';
@@ -606,6 +607,10 @@ export class AgentForgeWorker extends EventEmitter {
     return scopeSlug(value);
   }
+  _scopeSlugsMatchingText(value, slugs) {
+    return scopeSlugsMatchingText(value, slugs);
+  }
   _addScopeCandidate(candidates, value) {
     return addScopeCandidate(candidates, value);
   }
@@ -626,6 +631,74 @@ export class AgentForgeWorker extends EventEmitter {
     return /\.(html?|jsx?|tsx?|vue|svelte|astro|mdx?|css|scss|sass|less)$/i.test(String(relativePath || ''));
   }
+  _isPageAssetPath(relativePath) {
+    return /\.(css|scss|sass|less|jsx?|tsx?)$/i.test(String(relativePath || ''));
+  }
+  _fileMentionsAsset(content, sourceRel, assetRel) {
+    const source = String(content || '');
+    const assetUnix = String(assetRel || '').replace(/\\/g, '/');
+    const assetBase = path.basename(assetUnix);
+    const relativeFromSource = path.relative(path.dirname(sourceRel || ''), assetRel || '').replace(/\\/g, '/');
+    const candidates = [
+      assetBase,
+      assetUnix,
+      `/${assetUnix}`,
+      relativeFromSource,
+      relativeFromSource && !relativeFromSource.startsWith('.') ? `./${relativeFromSource}` : '',
+    ].filter(Boolean);
+    return candidates.some(candidate => source.includes(candidate));
+  }
+  _allCurrentPageSourceFiles(repo) {
+    const names = new Set();
+    const add = (output) => {
+      for (const rel of String(output || '').split('\n').map(line => line.trim()).filter(Boolean)) {
+        if (this._isPageSourcePath(rel)) names.add(rel);
+      }
+    };
+    add(this._gitOutput(repo, ['ls-files'], 30000));
+    add(this._gitOutput(repo, ['ls-files', '--others', '--exclude-standard'], 30000));
+    add(this._parseGitStatusPaths(this._gitStatusPorcelain(repo, 10000)).join('\n'));
+    return [...names].sort();
+  }
+  _isNewScopedPageOwnedAsset(baseline, rel, allowedSlugs, pageOnly) {
+    if (!baseline?.root || !pageOnly || !Array.isArray(allowedSlugs) || allowedSlugs.length === 0) return false;
+    if (!this._isPageAssetPath(rel)) return false;
+    if (this._scopeSlugsMatchingText(String(rel || '').toLowerCase(), allowedSlugs).length > 0) return true;
+    if (this._gitPathExistsAtRef(baseline.root, baseline.head || 'HEAD', rel)) return false;
+    const sourceFiles = this._allCurrentPageSourceFiles(baseline.root).filter(file => file !== rel);
+    const scopedSources = [];
+    const outOfScopeMentions = [];
+    for (const sourceRel of sourceFiles) {
+      const fullPath = path.join(baseline.root, sourceRel);
+      let content = '';
+      try {
+        content = readFileSync(fullPath, 'utf-8');
+      } catch {
+        continue;
+      }
+      if (!this._fileMentionsAsset(content, sourceRel, rel)) continue;
+      if (this._scopeSlugsMatchingText(String(sourceRel || '').toLowerCase(), allowedSlugs).length > 0) {
+        scopedSources.push(sourceRel);
+      } else {
+        outOfScopeMentions.push(sourceRel);
+      }
+    }
+    return scopedSources.length > 0 && outOfScopeMentions.length === 0;
+  }
+  _scopeAllowsChangedPath(baseline, rel, allowedSlugs, pageOnly) {
+    const lower = String(rel || '').toLowerCase();
+    const slugAllowed = this._scopeSlugsMatchingText(lower, allowedSlugs).length > 0;
+    if (slugAllowed) return !pageOnly || this._isPageSourcePath(rel);
+    return this._isNewScopedPageOwnedAsset(baseline, rel, allowedSlugs, pageOnly);
+  }
   _findScopeDriftRepoChanges(repoBaselines, userMessage) {
     if (!Array.isArray(repoBaselines) || repoBaselines.length === 0) return [];
     const { slugs: allowedSlugs, pageOnly } = this._extractExplicitScope(userMessage);
@@ -652,12 +725,7 @@ export class AgentForgeWorker extends EventEmitter {
       const initialDirty = new Set(baseline.initialDirtyPaths || []);
       const outOfScope = [...names]
         .filter(rel => !initialDirty.has(rel))
-        .filter(rel => {
-          const lower = rel.toLowerCase();
-          const slugAllowed = allowedSlugs.some(slug => lower.includes(slug));
-          if (!slugAllowed) return true;
-          return pageOnly && !this._isPageSourcePath(rel);
-        })
+        .filter(rel => !this._scopeAllowsChangedPath(baseline, rel, allowedSlugs, pageOnly))
         .sort();
       if (outOfScope.length > 0) {
         warnings.push({ repo: baseline.root, head: baseline.head, allowedSlugs, pageOnly, files: outOfScope });
@@ -723,11 +791,7 @@ export class AgentForgeWorker extends EventEmitter {
       const initialDirty = new Set(baseline.initialDirtyPaths || []);
       const files = [...names]
         .filter(rel => resetPreexistingScopedTargets || !initialDirty.has(rel))
-        .filter(rel => {
-          const lower = rel.toLowerCase();
-          if (!allowedSlugs.some(slug => lower.includes(slug))) return false;
-          return !pageOnly || this._isPageSourcePath(rel);
-        })
+        .filter(rel => this._scopeAllowsChangedPath(baseline, rel, allowedSlugs, pageOnly))
         .sort();
       if (files.length === 0) continue;
@@ -799,7 +863,7 @@ export class AgentForgeWorker extends EventEmitter {
         const pathName = rel.includes(' -> ') ? rel.split(' -> ').pop() : rel;
         const lower = String(pathName || '').toLowerCase();
         if (!this._isPageSourcePath(lower)) continue;
-        if (!allowedSlugs.some(slug => lower.includes(slug))) continue;
+        if (this._scopeSlugsMatchingText(lower, allowedSlugs).length === 0) continue;
         deleted.push(pathName);
       }
       if (deleted.length > 0) {
@@ -997,7 +1061,7 @@ export class AgentForgeWorker extends EventEmitter {
         }
         if (!currentFile || !uiFileRe.test(currentFile)) continue;
         const lowerPath = currentFile.toLowerCase();
-        if (allowedSlugs.length > 0 && !allowedSlugs.some(slug => lowerPath.includes(slug))) continue;
+        if (allowedSlugs.length > 0 && this._scopeSlugsMatchingText(lowerPath, allowedSlugs).length === 0) continue;
         if (!/^[+-][^+-]/.test(line)) continue;
         const raw = line.slice(1).trim();
         if (!raw || /^(?:\/\*|\*|\/\/|<!--|-->|})$/.test(raw)) continue;
@@ -1178,7 +1242,7 @@ export class AgentForgeWorker extends EventEmitter {
         }
         if (!currentFile || !uiFileRe.test(currentFile)) continue;
         const lower = currentFile.toLowerCase();
-        if (allowedSlugs.length > 0 && !allowedSlugs.some(slug => lower.includes(slug))) continue;
+        if (allowedSlugs.length > 0 && this._scopeSlugsMatchingText(lower, allowedSlugs).length === 0) continue;
         const addedLine = line.slice(1);
         const newSourceComment = (() => {
           commentTextRe.lastIndex = 0;
@@ -1289,7 +1353,7 @@ export class AgentForgeWorker extends EventEmitter {
       for (const filePath of changedFiles) {
         const lower = String(filePath || '').toLowerCase();
         for (const slug of allowedSlugs) {
-          if (lower.includes(slug)) touchedSlugs.add(slug);
+          if (this._scopeSlugsMatchingText(lower, [slug]).length > 0) touchedSlugs.add(slug);
         }
       }