What causes "[impeccable] Variant wrapper not found in source file." in pbakaus/impeccable?

Wait a moment — the script retries up to 3 times (1.2s apart) in case an HMR patch or agent rewrite is in flight.

[impeccable] Variant wrapper not found in source file.

Error message

[impeccable] Variant wrapper not found in source file.

What it means

While re-injecting variants from the source file (HTML path), the script parses the fetched source and queries for the [data-impeccable-variants="<sessionId>"] wrapper. When it is absent this warning fires: the resumed cycling session's wrapper is gone from source, making the session an ORPHAN that no reload/HMR/restart can complete. If orphanDiscard is set, the script retries the read a few times (an agent rewrite or HMR patch may be mid-flight) before calling discardOrphanedSession.

Source

Thrown at skill/scripts/live-browser.js:6414

      }
      return;
    }
    const url = 'http://localhost:' + PORT + '/source?token=' + TOKEN + '&path=' + encodeURIComponent(filePath);
    fetch(url)
      .then(r => { if (!r.ok) throw new Error(r.status); return r.text(); })
      .then(html => {
        const parser = new DOMParser();
        const startMark = '<!-- impeccable-variants-start ' + sessionId + ' -->';
        const endMark = '<!-- impeccable-variants-end ' + sessionId + ' -->';
        const startIdx = html.indexOf(startMark);
        const endIdx = html.indexOf(endMark);
        const block = startIdx !== -1 && endIdx !== -1 && endIdx > startIdx
          ? html.slice(startIdx + startMark.length, endIdx).trim()
          : html;
        const doc = parser.parseFromString(block, 'text/html');
        const srcWrapper = doc.querySelector('[data-impeccable-variants="' + sessionId + '"]');
        if (!srcWrapper) {
          console.warn('[impeccable] Variant wrapper not found in source file.');
          // A resumed cycling session whose wrapper is gone from source is an
          // ORPHAN: the file was edited or regenerated out from under it, so
          // no reload, HMR push, or server restart can ever complete it, and
          // the frozen picker it leaves behind used to need a manual
          // live-complete --discarded. Retry a few reads first (an agent
          // rewrite or HMR patch may be mid-flight), then self-discard and
          // hand the surface back to the picker.
          if (opts.orphanDiscard && sessionId === currentSessionId) {
            const attempt = opts._orphanAttempt || 0;
            if (attempt < COMPLETED_SOURCE_FALLBACK_RETRIES) {
              setTimeout(() => {
                if (sessionId !== currentSessionId) return;
                if (state !== 'GENERATING' && state !== 'CYCLING') return;
                injectVariantsFromSource(filePath, sessionId, { ...opts, _orphanAttempt: attempt + 1 });
              }, COMPLETED_SOURCE_FALLBACK_RETRY_MS);
            } else {
              discardOrphanedSession('variant wrapper missing from source');
            }

View on GitHub (pinned to 2bc2879276)

Solutions

Wait a moment — the script retries up to 3 times (1.2s apart) in case an HMR patch or agent rewrite is in flight.
If the session self-discards, pick an element to start a fresh session.
Restore the file state containing the impeccable-variants wrapper markers if the removal was accidental.
Stop editors/formatters from stripping the HTML comment markers in source files during live sessions.

Defensive patterns

Strategy: retry

Validate before calling

const res = await fetch(srcUrl);
if (res.ok) {
  const html = await res.text();
  const hasWrapper = html.indexOf('data-impeccable-variants="' + sessionId + '"') !== -1;
  if (!hasWrapper) { /* retry up to 3x at 1.2s before discarding */ }
}

Prevention

Wait through the built-in retry window (3 x 1.2s) — an HMR patch or agent rewrite may be mid-flight.
Do not rewrite the target file wholesale during an active variant session; preserve the wrapper markers.
Revert accidental file edits (git checkout) before the session exhausts its retry budget.
Resume saved sessions against the same file revision they were created from.

When it happens

Trigger: injectVariantsFromSource fetched the source successfully but the parsed HTML contains no wrapper matching the current sessionId — the file was edited, regenerated, reverted, or the wrapper markers were stripped after the session started.

Common situations: Git revert or checkout replaced the file; an agent rewrite rewrote the whole file without the markers; HMR patch dropped the scaffolding; resuming a saved session against a changed file; comment markers removed by a formatter/minifier.

Related errors

AI-assisted analysis of pbakaus/impeccable@2bc2879276 (2026-09-08). Data as JSON: /api/errors/ea4299ebd1ba5e8c. Report an issue: GitHub.