Skip to content

ShipfoxHQ/shipfox / .github/skills/impeccable

impeccable

Flagged

Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.

FileKindSize
SKILL.mdskill md10.4 KB
reference/adapt.mdmarkdown10.1 KB
reference/adapt.native.mdmarkdown3.8 KB
reference/android.mdmarkdown3.2 KB
reference/animate.mdmarkdown4.7 KB
reference/audit.mdmarkdown7.7 KB
reference/audit.native.mdmarkdown8.2 KB
reference/bolder.mdmarkdown3.1 KB
reference/clarify.mdmarkdown4.5 KB
reference/colorize.mdmarkdown4.4 KB
reference/craft-floor.mdmarkdown3.7 KB
reference/craft.mdmarkdown555 B
reference/critique.mdmarkdown39.0 KB
reference/delight.mdmarkdown3.6 KB
reference/distill.mdmarkdown5.5 KB
reference/doctor.mdmarkdown4.6 KB
reference/document.mdmarkdown26.8 KB
reference/extract.mdmarkdown3.3 KB
reference/harden.mdmarkdown8.3 KB
reference/hooks.mdmarkdown11.6 KB
reference/init.mdmarkdown8.6 KB
reference/ios.mdmarkdown2.9 KB
reference/layout.mdmarkdown5.0 KB
reference/live-setup.mdmarkdown7.2 KB
reference/live.mdmarkdown34.8 KB
reference/new-work.mdmarkdown27.2 KB
reference/onboard.mdmarkdown7.6 KB
reference/operate.mdmarkdown4.0 KB
reference/optimize.mdmarkdown7.4 KB
reference/overdrive.mdmarkdown8.6 KB
reference/polish.mdmarkdown5.1 KB
reference/quieter.mdmarkdown4.7 KB
reference/routing.mdmarkdown2.8 KB
reference/shape.mdmarkdown3.5 KB
reference/typeset.mdmarkdown5.1 KB
reference/visualize.mdmarkdown10.2 KB
scripts/command-metadata.jsonconfig7.7 KB
scripts/concept-seed.mjsscript27.0 KB
scripts/context-signals.mjsscript14.0 KB
scripts/context.mjsscript58.4 KB
scripts/critique-storage.mjsscript7.9 KB
scripts/detect-csp.mjsscript6.6 KB
scripts/detect.mjsscript620 B
scripts/detector/browser/injected/index.mjsscript79.6 KB
scripts/detector/cli/main.mjsscript18.8 KB
scripts/detector/design-system.mjsscript34.3 KB
scripts/detector/detect-antipatterns-browser.jsscript358.1 KB
scripts/detector/detect-antipatterns.mjsscript1.8 KB
scripts/detector/engines/browser/detect-url.mjsscript14.1 KB
scripts/detector/engines/regex/detect-text.mjsscript34.5 KB
scripts/detector/engines/static-html/css-cascade.mjsscript42.7 KB
scripts/detector/engines/static-html/detect-html.mjsscript11.7 KB
scripts/detector/engines/visual/screenshot-contrast.mjsscript6.4 KB
scripts/detector/findings.mjsscript766 B
scripts/detector/node/file-system.mjsscript7.6 KB
scripts/detector/profile/profiler.mjsscript4.4 KB
scripts/detector/registry/antipatterns.mjsscript27.2 KB
scripts/detector/rules/checks.mjsscript246.3 KB
scripts/detector/shared/color.mjsscript4.4 KB
scripts/detector/shared/constants.mjsscript4.6 KB
scripts/detector/shared/fonts.mjsscript852 B
scripts/detector/shared/inline-ignores.mjsscript6.0 KB
scripts/detector/shared/page.mjsscript252 B
scripts/doctor.mjsscript11.6 KB
scripts/embed-prompt.mjsscript5.8 KB
scripts/generate-image.mjsscript9.6 KB
scripts/hook-admin.mjsscript28.4 KB
scripts/hook-before-edit.mjsscript18.3 KB
scripts/hook-lib.mjsscript81.4 KB
scripts/hook.mjsscript2.6 KB
scripts/lib/artifact-schema.mjsscript3.8 KB
scripts/lib/composition-catalog.mjsscript10.0 KB
scripts/lib/concept-catalog.mjsscript17.4 KB
scripts/lib/design-parser.mjsscript25.2 KB
scripts/lib/impeccable-config.mjsscript22.2 KB
scripts/lib/impeccable-paths.mjsscript4.9 KB
scripts/lib/is-generated.mjsscript2.2 KB
scripts/lib/provider.mjsscript327 B
scripts/lib/roll-selection.mjsscript16.9 KB
scripts/lib/staleness-deep.mjsscript19.6 KB
scripts/lib/staleness-notice.mjsscript6.5 KB
scripts/lib/staleness.mjsscript19.0 KB
scripts/lib/surface-briefs.mjsscript6.1 KB
scripts/lib/target-args.mjsscript1.1 KB
scripts/lib/target-slug.mjsscript1.0 KB
scripts/lib/template-extensions.mjsscript5.3 KB
scripts/live-accept.mjsscript35.5 KB
scripts/live-browser-dom.jsscript4.2 KB
scripts/live-browser-session.jsscript3.2 KB
scripts/live-browser.jsscript489.1 KB
scripts/live-commit-manual-edits.mjsscript41.2 KB
scripts/live-complete.mjsscript4.7 KB
scripts/live-copy-edit-agent.mjsscript28.2 KB
scripts/live-discard-manual-edits.mjsscript1.6 KB
scripts/live-inject.mjsscript18.1 KB
scripts/live-insert.mjsscript9.8 KB
scripts/live-manual-edit-evidence.mjsscript11.6 KB
scripts/live-poll.mjsscript15.7 KB
scripts/live-resume.mjsscript6.0 KB
scripts/live-server.mjsscript66.1 KB
scripts/live-status.mjsscript2.6 KB
scripts/live-target.mjsscript934 B
scripts/live-wrap.mjsscript38.2 KB
scripts/live.mjsscript13.1 KB
scripts/live/accept-css.mjsscript22.0 KB
scripts/live/accept-verify.mjsscript2.7 KB
scripts/live/browser-script-parts.mjsscript2.1 KB
scripts/live/completion.mjsscript1.4 KB
scripts/live/event-validation.mjsscript9.4 KB
scripts/live/frameworks/astro.mjsscript1.7 KB
scripts/live/frameworks/detect-utils.mjsscript2.1 KB
scripts/live/frameworks/index.mjsscript5.7 KB
scripts/live/frameworks/journal.mjsscript7.0 KB
scripts/live/frameworks/nextjs.mjsscript1.7 KB
scripts/live/frameworks/nuxt.mjsscript5.1 KB
scripts/live/frameworks/script-src.mjsscript699 B
scripts/live/frameworks/static-html.mjsscript656 B
scripts/live/frameworks/sveltekit.mjsscript1.8 KB
scripts/live/frameworks/tag-strategy.mjsscript10.6 KB
scripts/live/frameworks/tanstack-start.mjsscript1.6 KB
scripts/live/frameworks/vite-generic.mjsscript1.3 KB
scripts/live/generation-preflight.mjsscript5.8 KB
scripts/live/insert-ui.mjsscript15.3 KB
scripts/live/instructions.mjsscript12.9 KB
scripts/live/manual-apply.mjsscript34.1 KB
scripts/live/manual-edit-routes.mjsscript14.6 KB
scripts/live/manual-edits-buffer.mjsscript5.0 KB
scripts/live/poll-lanes.mjsscript759 B
scripts/live/roots.mjsscript20.4 KB
scripts/live/session-store.mjsscript22.4 KB
scripts/live/source-lock.mjsscript3.6 KB
scripts/live/source-search.mjsscript4.2 KB
scripts/live/svelte-ast.mjsscript37.7 KB
scripts/live/svelte-component.mjsscript49.6 KB
scripts/live/sveltekit-adapter.mjsscript11.1 KB
scripts/live/tanstack-adapter.mjsscript9.5 KB
scripts/live/ui-core.mjsscript5.4 KB
scripts/live/vocabulary.mjsscript7.0 KB
scripts/modern-screenshot.umd.jsscript28.6 KB
scripts/palette.mjsscript55.5 KB
scripts/pin.mjsscript6.3 KB
scripts/serve-question.mjsscript60.2 KB
scripts/surface-brief.mjsscript2.5 KB

scripts/live/session-store.mjs

View on GitHub
import fs from 'node:fs';
import path from 'node:path';
import { getLegacyLiveSessionsDir, getLiveSessionsDir, safeSessionId } from '../lib/impeccable-paths.mjs';
import { COMPLETED_SESSION_PHASES, GENERATION_FENCED_SESSION_PHASES } from './vocabulary.mjs';

const COMPLETED_PHASES = new Set(COMPLETED_SESSION_PHASES);
export const GENERATION_FENCED_PHASES = new Set(GENERATION_FENCED_SESSION_PHASES);

// The snapshot file carries two bookkeeping fields the snapshot itself does not
// own: how large the journal was when the snapshot was written, and the next
// sequence number. Both are stripped before a snapshot is handed to a caller.
// The byte count is what makes a cached snapshot verifiable — the journal is
// append-only, so a matching size means no event has landed since.
const META_JOURNAL_BYTES = '__journalBytes';
const META_NEXT_SEQ = '__nextSeq';

// TODO(revision-unification): `checkpointRevision`, `browserCheckpointRevision`,
// and `publicationCheckpointRevision` are three counters for two domains.
// `checkpointRevision` is a compatibility mirror of the browser counter kept for
// older readers. Collapsing them means changing what a resumed browser compares
// its local revision against, so it belongs in a pass that owns resume ordering,
// not in a caching change.

export function createLiveSessionStore({ cwd = process.cwd(), sessionId } = {}) {
  const rootDir = getLiveSessionsDir(cwd);
  const legacyRootDir = getLegacyLiveSessionsDir(cwd);
  fs.mkdirSync(rootDir, { recursive: true });

  // Derived state per session, keyed by what the journal looked like when it was
  // derived. Publisher/complete helpers append from other processes, so the key
  // is the journal's own (path, size, mtime) rather than a trusted local write
  // count: an append this process did not make invalidates the entry and the
  // next read replays. Without the cache every append and every read replayed
  // the whole journal, which made a long session quadratic in its own length.
  /** @type {Map<string, { snapshot: object, nextSeq: number, journalPath: string, size: number, mtimeMs: number }>} */
  const derived = new Map();

  function getReadableJournalPath(id) {
    const primary = getJournalPath(rootDir, id);
    if (fs.existsSync(primary)) return primary;
    const legacy = getJournalPath(legacyRootDir, id);
    if (fs.existsSync(legacy)) return legacy;
    return primary;
  }

  /**
   * The current derived state for a session, from the in-memory cache when the
   * journal has not moved, from the snapshot file when that file is provably
   * current, and from a full replay otherwise.
   */
  function readState(id, { allowSnapshotFile = true } = {}) {
    const journalPath = getReadableJournalPath(id);
    const stat = statOrNull(journalPath);
    const size = stat ? stat.size : -1;
    const mtimeMs = stat ? stat.mtimeMs : -1;

    const cached = derived.get(id);
    if (cached && cached.journalPath === journalPath && cached.size === size && cached.mtimeMs === mtimeMs) {
      return cached;
    }

    if (allowSnapshotFile && stat) {
      const hydrated = readSnapshotFile(getSnapshotPath(rootDir, id), id, size);
      if (hydrated) {
        const entry = { ...hydrated, journalPath, size, mtimeMs };
        derived.set(id, entry);
        return entry;
      }
    }

    const rebuilt = rebuildSnapshotFromJournal(journalPath, id);
    const entry = { snapshot: rebuilt.snapshot, nextSeq: rebuilt.nextSeq, journalPath, size, mtimeMs };
    derived.set(id, entry);
    return entry;
  }

  function persist(id, snapshot, nextSeq) {
    const snapshotPath = getSnapshotPath(rootDir, id);
    const journalPath = getReadableJournalPath(id);
    const stat = statOrNull(journalPath);
    writeSnapshot(snapshotPath, snapshot, { journalBytes: stat ? stat.size : -1, nextSeq });
    derived.set(id, {
      snapshot,
      nextSeq,
      journalPath,
      size: stat ? stat.size : -1,
      mtimeMs: stat ? stat.mtimeMs : -1,
    });
  }

  return {
    rootDir,
    legacyRootDir,
    appendEvent(event) {
      const normalized = normalizeEvent(event, sessionId);
      const journalPath = getJournalPath(rootDir, normalized.id);
      const legacyJournalPath = getJournalPath(legacyRootDir, normalized.id);
      if (!fs.existsSync(journalPath) && fs.existsSync(legacyJournalPath)) {
        fs.copyFileSync(legacyJournalPath, journalPath);
        // The readable path just moved from legacy to primary; anything derived
        // against the old path describes a file this session no longer reads.
        derived.delete(normalized.id);
      }
      // Reuse the derived state when the journal has not changed under us, and
      // apply the new event on top of it. Correctness still comes from the
      // journal: any append from another process invalidates the entry above
      // and this replays before writing, so sequence numbers and phase fences
      // are never taken from a stale copy.
      const prior = readState(normalized.id);
      const entry = {
        seq: prior.nextSeq,
        id: normalized.id,
        type: normalized.type,
        ts: new Date().toISOString(),
        event: normalized,
      };
      fs.appendFileSync(journalPath, JSON.stringify(entry) + '\n');
      const next = applyEvent(prior.snapshot, entry);
      persist(normalized.id, next, prior.nextSeq + 1);
      return next;
    },
    /**
     * True when a journal exists for the id in either root. appendEvent
     * CREATES a journal for any id it is handed, so callers that should only
     * ever touch existing sessions (browser checkpoints, mount acks) check
     * here first — otherwise a stale id from another project's browser
     * storage materializes a ghost session in this store.
     */
    has(id) {
      if (!id || typeof id !== 'string') return false;
      return fs.existsSync(getJournalPath(rootDir, id))
        || fs.existsSync(getJournalPath(legacyRootDir, id));
    },
    /**
     * Read-only. `live-status` and `live-resume` call this against a session a
     * running server owns; writing the snapshot file here made every read a
     * write and let a reader's replay of a half-written journal land on disk.
     * Snapshot files are written by appendEvent and by flush().
     */
    getSnapshot(id = sessionId, opts = {}) {
      if (!id) throw new Error('session id required');
      const { snapshot } = readState(id);
      if (!opts.includeCompleted && COMPLETED_PHASES.has(snapshot.phase)) return null;
      return snapshot;
    },
    /**
     * Write the snapshot file for a session without appending an event. The
     * durable truth is the journal, so this only refreshes the read cache other
     * processes use; callers that need the state itself should use getSnapshot.
     */
    flush(id = sessionId) {
      if (!id) throw new Error('session id required');
      const state = readState(id, { allowSnapshotFile: false });
      persist(id, state.snapshot, state.nextSeq);
      return state.snapshot;
    },
    listActiveSessions() {
      const ids = new Set();
      for (const dir of [legacyRootDir, rootDir]) {
        if (!fs.existsSync(dir)) continue;
        for (const name of fs.readdirSync(dir)) {
          if (name.endsWith('.jsonl')) ids.add(name.slice(0, -'.jsonl'.length));
        }
      }
      // Each id goes through readState, so a session whose journal has not moved
      // since it was last derived costs a stat and nothing more. The server calls
      // this on every /status and on every SSE connect.
      return [...ids]
        .sort()
        .map((id) => this.getSnapshot(id))
        .filter(Boolean);
    },
  };
}

function statOrNull(filePath) {
  try {
    return fs.statSync(filePath);
  } catch {
    return null;
  }
}

/**
 * Hydrate derived state from a snapshot file, but only when it provably
 * describes the journal as it stands right now. Anything short of an exact byte
 * match on an append-only file means events landed after the snapshot was
 * written, and the caller replays instead.
 */
function readSnapshotFile(snapshotPath, id, journalBytes) {
  let parsed;
  try {
    parsed = JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'));
  } catch {
    return null;
  }
  if (!parsed || typeof parsed !== 'object') return null;
  if (parsed[META_JOURNAL_BYTES] !== journalBytes) return null;
  if (!Number.isInteger(parsed[META_NEXT_SEQ])) return null;
  const nextSeq = parsed[META_NEXT_SEQ];
  delete parsed[META_JOURNAL_BYTES];
  delete parsed[META_NEXT_SEQ];
  // The journal owns identity; a snapshot file copied between session ids is
  // not a reason to answer with the wrong id.
  if (parsed.id !== id) return null;
  return { snapshot: { ...baseSnapshot(id), ...parsed }, nextSeq };
}

function normalizeEvent(event, fallbackId) {
  if (!event || typeof event !== 'object') throw new Error('event object required');
  const id = event.id || fallbackId;
  if (!id || typeof id !== 'string') throw new Error('event id required');
  if (!event.type || typeof event.type !== 'string') throw new Error('event type required');
  return { ...event, id };
}

function getJournalPath(rootDir, id) {
  return path.join(rootDir, safeSessionId(id) + '.jsonl');
}

function getSnapshotPath(rootDir, id) {
  return path.join(rootDir, safeSessionId(id) + '.snapshot.json');
}

function baseSnapshot(id) {
  return {
    id,
    phase: 'new',
    pageUrl: null,
    sourceFile: null,
    previewFile: null,
    previewMode: null,
    expectedVariants: 0,
    arrivedVariants: 0,
    visibleVariant: null,
    paramValues: {},
    pendingEventSeq: null,
    pendingEvent: null,
    deliveryLease: null,
    checkpointRevision: 0,
    browserCheckpointRevision: 0,
    publicationCheckpointRevision: 0,
    activeOwner: null,
    sourceMarkers: {},
    fallbackMode: null,
    generationPhase: null,
    generationCompletedAt: null,
    generationTimings: {},
    variantPlan: null,
    generationCanceled: false,
    generationCanceledAt: null,
    cancelReason: null,
    annotationArtifacts: [],
    // Render truth. `arrivedVariants` says what the agent published; these say
    // what the browser actually got on screen. They are kept alongside the
    // published counters rather than replacing them so older readers keep
    // working, but they are the only fields that answer "did the user ever see
    // a variant".
    mountedVariants: [],
    mountFailures: [],
    renderState: null,
    diagnostics: [],
    updatedAt: null,
  };
}

// How many mount failures a session keeps. The card in the browser shows the
// newest one; the agent needs enough history to spot a variant that fails
// every republish, not the whole retry storm.
const MOUNT_FAILURE_HISTORY = 5;

/**
 * `pending` = the agent published and nothing has acked yet, `mounted` = at
 * least one variant reached the DOM, `failed` = the browser reported failures
 * and nothing ever mounted. A single success outranks any number of failures:
 * the user is looking at something.
 */
function deriveRenderState(snapshot) {
  if (snapshot.mountedVariants.length > 0) return 'mounted';
  if (snapshot.mountFailures.length > 0) return 'failed';
  if (snapshot.generationCompletedAt) return 'pending';
  return null;
}

function rebuildSnapshotFromJournal(journalPath, id) {
  let snapshot = baseSnapshot(id);
  const diagnostics = [];
  let nextSeq = 1;
  if (!fs.existsSync(journalPath)) return { snapshot, diagnostics, nextSeq };

  const lines = fs.readFileSync(journalPath, 'utf-8').split('\n');
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (!line.trim()) continue;
    try {
      const entry = JSON.parse(line);
      if (!entry || typeof entry !== 'object') throw new Error('entry is not object');
      if (Number.isInteger(entry.seq)) nextSeq = Math.max(nextSeq, entry.seq + 1);
      snapshot = applyEvent(snapshot, entry);
    } catch (err) {
      diagnostics.push({
        error: 'journal_parse_failed',
        line: i + 1,
        message: err.message,
      });
    }
  }
  snapshot.diagnostics = [...snapshot.diagnostics, ...diagnostics];
  return { snapshot, diagnostics, nextSeq };
}

function applyEvent(snapshot, entry) {
  const event = entry.event || entry;
  const next = {
    ...snapshot,
    paramValues: { ...(snapshot.paramValues || {}) },
    sourceMarkers: { ...(snapshot.sourceMarkers || {}) },
    generationTimings: { ...(snapshot.generationTimings || {}) },
    variantPlan: snapshot.variantPlan || null,
    annotationArtifacts: [...(snapshot.annotationArtifacts || [])],
    mountedVariants: [...(snapshot.mountedVariants || [])],
    mountFailures: [...(snapshot.mountFailures || [])],
    renderState: snapshot.renderState ?? null,
    diagnostics: [...(snapshot.diagnostics || [])],
    updatedAt: entry.ts || new Date().toISOString(),
  };

  switch (event.type) {
    case 'generate':
      next.phase = 'generate_requested';
      next.pageUrl = event.pageUrl ?? next.pageUrl;
      next.expectedVariants = event.count ?? next.expectedVariants;
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      next.variantPlan = null;
      // A new cycle publishes new files: everything the browser told us about
      // the previous batch is now about modules that no longer exist.
      next.mountedVariants = [];
      next.mountFailures = [];
      next.renderState = null;
      if (event.screenshotPath) upsertArtifact(next.annotationArtifacts, { type: 'screenshot', path: event.screenshotPath });
      break;
    case 'variant_plan':
      if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
        next.variantPlan = event.plan ?? next.variantPlan;
      }
      break;
    case 'detector_waivers':
      if (!next.generationCanceled && !GENERATION_FENCED_PHASES.has(next.phase)) {
        next.detectorWaivers = [
          ...(next.detectorWaivers || []),
          ...(Array.isArray(event.waivers) ? event.waivers : []),
        ];
      }
      break;
    case 'agent_phase':
      next.generationPhase = event.phase ?? next.generationPhase;
      if (event.phase) {
        next.generationTimings[event.phase] = {
          at: event.at ?? (Date.parse(entry.ts || '') || null),
          durationMs: event.durationMs ?? null,
        };
      }
      break;
    case 'variants_ready':
    case 'agent_done':
      if ((next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase))
          && !(event.type === 'agent_done' && event.carbonize === true && next.phase === 'accept_requested')) {
        next.diagnostics.push({
          error: 'late_generation_event_ignored',
          type: event.type,
          phase: next.phase,
        });
        break;
      }
      next.phase = event.carbonize === true ? 'carbonize_required' : 'variants_ready';
      // Durable completion marker: later browser checkpoints (a resumed page
      // reporting phase "generating") regress `phase`, but generation staying
      // finished is monotone — the live server keys missed-`done` redelivery
      // on this field.
      next.generationCompletedAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
      next.previewFile = event.previewFile ?? next.previewFile;
      next.previewMode = event.previewMode ?? next.previewMode;
      next.arrivedVariants = event.arrivedVariants ?? (next.expectedVariants || next.arrivedVariants || 0);
      next.pendingEventSeq = null;
      next.pendingEvent = null;
      if (event.carbonize === true) {
        next.diagnostics.push({
          error: 'carbonize_cleanup_required',
          file: event.file || null,
          message: 'Accepted variant still has carbonize markers that must be folded into source CSS.',
        });
      }
      next.renderState = deriveRenderState(next);
      break;
    case 'variant_mounted': {
      const variant = Number(event.variant);
      if (!Number.isInteger(variant) || variant < 1) {
        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
        break;
      }
      if (!next.mountedVariants.includes(variant)) {
        next.mountedVariants = [...next.mountedVariants, variant].sort((a, b) => a - b);
      }
      next.renderState = deriveRenderState(next);
      break;
    }
    case 'variant_mount_failed': {
      const variant = Number(event.variant);
      if (!Number.isInteger(variant) || variant < 1) {
        next.diagnostics.push({ error: 'malformed_mount_ack', type: event.type, variant: event.variant ?? null });
        break;
      }
      next.mountFailures = [
        ...next.mountFailures,
        {
          variant,
          url: typeof event.url === 'string' ? event.url : null,
          error: typeof event.error === 'string' ? event.error : null,
          at: event.at ?? (Date.parse(entry.ts || '') || Date.now()),
        },
      ].slice(-MOUNT_FAILURE_HISTORY);
      next.renderState = deriveRenderState(next);
      // The failure needs an agent reply, so it must survive a helper
      // restart the same way a generate does. Never clobber a still-pending
      // generate: a progressive publish can fail an early mount while the
      // generate event itself is still leased.
      if (!next.pendingEvent) {
        next.pendingEvent = toPendingEvent(event);
      }
      break;
    }
    case 'checkpoint':
      if (next.generationCanceled || GENERATION_FENCED_PHASES.has(next.phase)) {
        next.diagnostics.push({ error: 'checkpoint_after_terminal_ignored', phase: event.phase ?? null, revision: event.revision ?? null });
        break;
      }
      {
        const revisionDomain = event.revisionDomain === 'publication'
          || (event.reason === 'variants_progress' && !event.owner)
          ? 'publication'
          : 'browser';
        const revisionField = revisionDomain === 'publication'
          ? 'publicationCheckpointRevision'
          : 'browserCheckpointRevision';
        const currentRevision = next[revisionField]
          ?? (revisionDomain === 'browser' ? next.checkpointRevision : 0)
          ?? 0;
        if ((event.revision ?? 0) >= currentRevision) {
          next.phase = event.phase ?? next.phase;
          next[revisionField] = event.revision ?? currentRevision;
          if (revisionDomain === 'browser') {
            next.checkpointRevision = event.revision ?? next.checkpointRevision;
            next.activeOwner = event.owner ?? next.activeOwner;
          }
          next.arrivedVariants = event.arrivedVariants ?? next.arrivedVariants;
          if (revisionDomain === 'browser') next.visibleVariant = event.visibleVariant ?? next.visibleVariant;
          next.sourceFile = event.sourceFile ?? next.sourceFile;
          next.previewFile = event.previewFile ?? next.previewFile;
          next.previewMode = event.previewMode ?? next.previewMode;
          if (revisionDomain === 'browser' && event.paramValues) next.paramValues = { ...event.paramValues };
        } else {
          next.diagnostics.push({ error: 'stale_checkpoint_ignored', revision: event.revision, revisionDomain });
        }
      }
      break;
    case 'accept':
    case 'accept_intent':
      next.phase = 'accept_requested';
      next.generationCanceled = true;
      next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
      next.cancelReason = 'accept';
      next.visibleVariant = Number(event.variantId ?? next.visibleVariant);
      if (event.paramValues) next.paramValues = { ...event.paramValues };
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
    case 'manual_edit_apply':
      next.phase = 'manual_edit_apply_requested';
      next.pageUrl = event.pageUrl ?? next.pageUrl;
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
    case 'steer':
      next.phase = 'steer_requested';
      next.pageUrl = event.pageUrl ?? next.pageUrl;
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
    case 'carbonize_cleanup':
      next.phase = 'carbonize_cleanup_requested';
      next.sourceFile = event.file ?? next.sourceFile;
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
    case 'steer_done':
      next.phase = 'steer_done';
      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
      next.previewFile = event.previewFile ?? next.previewFile;
      next.previewMode = event.previewMode ?? next.previewMode;
      next.message = event.message ?? next.message;
      next.pendingEventSeq = null;
      next.pendingEvent = null;
      break;
    case 'discard':
      next.phase = 'discard_requested';
      next.generationCanceled = true;
      next.generationCanceledAt = event.at ?? (Date.parse(entry.ts || '') || Date.now());
      next.cancelReason = 'discard';
      next.pendingEventSeq = entry.seq ?? next.pendingEventSeq;
      next.pendingEvent = toPendingEvent(event);
      break;
    case 'discarded':
      next.phase = 'discarded';
      next.pendingEventSeq = null;
      next.pendingEvent = null;
      break;
    case 'complete':
      next.phase = 'completed';
      next.sourceFile = event.sourceFile ?? event.file ?? next.sourceFile;
      next.previewFile = event.previewFile ?? next.previewFile;
      next.previewMode = event.previewMode ?? next.previewMode;
      next.pendingEventSeq = null;
      next.pendingEvent = null;
      break;
    case 'agent_error':
      if (next.generationCanceled && event.sourceEventType === 'generate') {
        next.diagnostics.push({ error: 'late_generation_event_ignored', type: event.type, phase: next.phase });
        break;
      }
      next.phase = 'agent_error';
      next.pendingEventSeq = null;
      next.pendingEvent = null;
      next.diagnostics.push({ error: 'agent_error', message: event.message || 'unknown agent error' });
      break;
    default:
      next.diagnostics.push({ error: 'unknown_event_type', type: event.type });
      break;
  }
  return next;
}

function toPendingEvent(event) {
  const pending = { ...event };
  delete pending.token;
  return pending;
}

function upsertArtifact(artifacts, artifact) {
  if (!artifacts.some((existing) => existing.path === artifact.path && existing.type === artifact.type)) {
    artifacts.push(artifact);
  }
}

function writeSnapshot(snapshotPath, snapshot, meta) {
  const payload = {
    ...snapshot,
    [META_JOURNAL_BYTES]: meta?.journalBytes ?? -1,
    [META_NEXT_SEQ]: meta?.nextSeq ?? 1,
  };
  fs.writeFileSync(snapshotPath, JSON.stringify(payload, null, 2) + '\n');
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall