@lightcone-ai/daemon 0.22.1 → 0.23.0

package/src/_vendor/video/recorder/plan-executor.js

@@ -1,480 +1,278 @@
-import { resolveDurationMs } from './phase-duration.js';
+// V6 plan executor.
+//
+// Drives plan.sections[].operations[] over the recorded Chromium page.
+// Each section's operations[] is a flat sequence of atom calls (scroll_to /
+// hold / cursor_focus). No macros, no aliases, no V5 action vocabulary.
+//
+// Inputs from V5 — `action`, `target_y`, `target_y_content_label`,
+// `focus_region`, `transition_ms`, `phase.beats[]`, agent-written `dwell_ms`
+// — are deliberately rejected with `phase_v5_fields_removed` so plans
+// migrated incorrectly fail loudly instead of silently degrading.
+//
+// Safe-region check: every scroll_to.y / cursor_focus.y is validated against
+// page_understanding.unsafe_regions before the atom executes. Out-of-range
+// or unsafe coordinates throw — no silent skipping.
+
 import { ATOMS, ATOM_NAMES } from './atoms.js';
-import { MACROS, resolveMacroName } from './macros.js';
+import { findOverlappingUnsafeRegion } from '../understanding/schema.js';
 import { getCdpSession } from '../cdp-touch.js';
 
-function normalizeText(value) {
-  if (typeof value !== 'string') return '';
-  return value.trim();
-}
-
-function normalizeInteger(value, fallback = null) {
-  const parsed = Number.parseInt(String(value ?? ''), 10);
-  if (!Number.isFinite(parsed)) return fallback;
-  return parsed;
-}
-
-function normalizeRange(value) {
-  if (!Array.isArray(value) || value.length !== 2) return null;
-  const start = Number(value[0]);
-  const end = Number(value[1]);
-  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
-  const low = Math.round(Math.min(start, end));
-  const high = Math.round(Math.max(start, end));
-  return [low, high];
-}
-
-// Canonical action vocabulary = atoms + macros. Macros are the day-to-day
-// names plans should use; atoms are exposed for sequencing via phase.beats[]
-// when a macro doesn't fit. The legacy V2 names (smooth_scroll, fast_scroll,
-// linear_scroll_during, scroll_back) are still accepted via ACTION_ALIASES
-// in macros.js so existing plans keep running, but new plans should pick
-// from the canonical list.
-//
-// "hold" is its own canonical action (not a macro) because it's the leaf
-// case — pure pause — and the agent shouldn't have to know whether it's
-// implemented as macro or atom.
-export const SUPPORTED_PHASE_ACTIONS = Object.freeze([
-  // macros (recommended for most sections)
-  'scroll_to_dwell',     // fast transition + dwell with micro-motion (default)
-  'narrated_pan',        // continuous linear scroll (long lists)
-  'focal_arc',           // cursor across N focal points (short pages)
-  // atoms (for power use — usually inside phase.beats[])
-  'scroll_to',
-  'hold',
-  'micro_oscillate',
-  'cursor_focus',
-  // legacy V2 names — kept for backward compat
-  'smooth_scroll',
-  'fast_scroll',
-  'linear_scroll_during',
-  'scroll_back',
-]);
-
-// Common spellings authors reach for, mapped onto the canonical action above.
-// Note: scroll_down / scroll_up are intentionally NOT aliased — there is no blind
-// scroll; an unrecognised action raises phase_action_unsupported so the plan gets
-// fixed rather than silently degraded.
-const PHASE_ACTION_ALIASES = new Map([
-  ['scroll_to', 'scroll_to_dwell'],
-  ['scrollto', 'scroll_to_dwell'],
-  ['scroll', 'scroll_to_dwell'],
-  ['scroll_to_region', 'scroll_to_dwell'],
-  ['scroll_to_y', 'scroll_to_dwell'],
-  ['dwell', 'scroll_to_dwell'],
-  ['focus_hold', 'scroll_to_dwell'],
-  ['pan', 'linear_scroll_during'],
-  ['narrated_pan', 'linear_scroll_during'],
-  ['linear_scroll', 'linear_scroll_during'],
-  ['scroll_during', 'linear_scroll_during'],
-  ['scroll_while_narrating', 'linear_scroll_during'],
-  ['return', 'scroll_back'],
-  ['return_anchor', 'scroll_back'],
-  ['back', 'scroll_back'],
-  ['scroll_to_top', 'scroll_back'],
-  ['wait', 'hold'],
-  ['pause', 'hold'],
-  ['stay', 'hold'],
-  ['focus', 'cursor_focus'],
-  ['highlight', 'cursor_focus'],
+const V5_FIELDS_ON_SECTION = Object.freeze([
+  'action',
+  'target_y',
+  'target_y_content_label',
+  'targetYContentLabel',
+  'focus_region',
+  'focusRegion',
+  'transition_ms',
+  'transition_ratio',
+  'beats',
+  'visual_action',
+  'camera_motion',
 ]);
 
-function normalizeActionName(rawValue) {
-  const name = normalizeText(rawValue).toLowerCase();
-  if (!name) return '';
-  if (SUPPORTED_PHASE_ACTIONS.includes(name)) return name;
-  return PHASE_ACTION_ALIASES.get(name) || name;
+function nowMs(getNowMs) {
+  return Number(getNowMs?.()) || Date.now();
 }
 
-// `visual_action` may be a string (the action name) or an object ({type, target_y, ...}).
-function visualActionObject(section = {}) {
-  const va = section?.visual_action;
-  if (va && typeof va === 'object') return va;
-  if (typeof va === 'string' && va.trim()) return { type: va.trim() };
-  return {};
+function normalizeText(value) {
+  if (typeof value !== 'string') return '';
+  return value.trim();
 }
 
-function inferActionFromCameraMotion(phase = {}) {
-  const motion = normalizeText(phase.camera_motion ?? phase.cameraMotion).toLowerCase();
-  if (motion === 'narrated_pan') return 'linear_scroll_during';
-  if (motion === 'return_anchor') return 'scroll_back';
-  if (motion === 'cursor_focus') return 'cursor_focus';
-  if (motion === 'focus_hold') return 'scroll_to_dwell';
-  return '';
+function resolveSectionId(section, index) {
+  return normalizeText(section?.id ?? section?.phase_id ?? section?.name) || `section_${index + 1}`;
 }
 
-function pickFirstNumber(...values) {
-  for (const value of values) {
-    if (value == null) continue;
-    const parsed = Number(value);
-    if (Number.isFinite(parsed)) return Math.round(parsed);
+function assertNoV5Fields(section, sectionId) {
+  for (const field of V5_FIELDS_ON_SECTION) {
+    if (section && Object.prototype.hasOwnProperty.call(section, field)) {
+      const error = new Error(
+        `phase_v5_fields_removed: section "${sectionId}" carries V5 field "${field}". `
+        + 'V6 plans use only `text`, `audio_path`, `dwell_ms` (set by plan_video_segments), '
+        + 'and `operations[]` (each: {atom, duration_ms, ...atom-specific}).',
+      );
+      error.code = 'PHASE_V5_FIELDS_REMOVED';
+      throw error;
+    }
   }
-  return null;
-}
-
-function normalizeSectionAsPhase(section = {}, index = 0) {
-  const phaseId = normalizeText(section.id ?? section.phase_id ?? section.name) || `phase_${index + 1}`;
-  const visualAction = visualActionObject(section);
-  const focusRegion = normalizeRange(
-    section.focus_region
-    ?? section.focusRegion
-    ?? visualAction.focus_region
-    ?? visualAction.focusRegion
-  );
-  const explicitAction = normalizeActionName(section.action ?? visualAction.type ?? visualAction.action);
-  const inferred = explicitAction || inferActionFromCameraMotion(section);
-  const targetY = pickFirstNumber(
-    section.target_y, section.to_y, section.y, section.scroll_y,
-    visualAction.target_y, visualAction.to_y, visualAction.y, visualAction.scroll_y,
-  );
-  const hasTarget = focusRegion != null || targetY != null;
-  const action = inferred || (hasTarget ? 'scroll_to_dwell' : 'hold');
-
-  return {
-    ...section,
-    id: phaseId,
-    phase_id: phaseId,
-    action,
-    focus_region: focusRegion ?? null,
-    visual_action: visualAction,
-    target_y: targetY,
-    from_y: pickFirstNumber(section.from_y, visualAction.from_y),
-    to_y: pickFirstNumber(section.to_y, visualAction.to_y, section.y, visualAction.y),
-    transition_ms: section.transition_ms ?? visualAction.transition_ms ?? visualAction.duration_ms ?? null,
-    duration_ms: section.duration_ms ?? section.dwell_ms ?? section.audio_duration_ms
-      ?? (section.presentation && Number.isFinite(Number(section.presentation.duration))
-        ? Math.round(Number(section.presentation.duration) * 1000)
-        : null),
-  };
 }
 
-export function normalizePlanPhases(plan = {}) {
-  const topLevelPhases = Array.isArray(plan?.phases) ? plan.phases : [];
-  if (topLevelPhases.length > 0) {
-    return topLevelPhases.map((phase, index) => normalizeSectionAsPhase(phase, index));
-  }
-
-  const sections = Array.isArray(plan?.sections) ? plan.sections : [];
-  if (sections.length > 0) {
-    const flattened = [];
-    sections.forEach((section, sectionIndex) => {
-      const nested = Array.isArray(section?.phases) ? section.phases : null;
-      if (nested && nested.length > 0) {
-        const prefix = normalizeText(section.id ?? section.phase_id ?? section.name) || `s${sectionIndex + 1}`;
-        nested.forEach((subPhase, subIndex) => {
-          const merged = {
-            ...subPhase,
-            id: subPhase.id ?? subPhase.phase_id ?? subPhase.name ?? `${prefix}_${subIndex + 1}`,
-          };
-          flattened.push(normalizeSectionAsPhase(merged, flattened.length));
-        });
-      } else {
-        flattened.push(normalizeSectionAsPhase(section, flattened.length));
-      }
-    });
-    return flattened;
+// scroll_to / cursor_focus have `y` (cursor_focus has it as part of x,y); validate against
+// page_understanding.full_height_px + unsafe_regions before dispatch.
+function assertYWithinBounds(y, { fullHeightPx, atomName, sectionId, operationIndex }) {
+  if (!Number.isFinite(y)) {
+    const error = new Error(
+      `operations_invalid: section "${sectionId}" operations[${operationIndex}].y is missing or not a number (atom=${atomName}).`,
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
   }
-
-  const error = new Error('plan_phases_required');
-  error.code = 'PLAN_PHASES_REQUIRED';
-  throw error;
-}
-
-function resolvePhaseAction(phase = {}) {
-  const explicit = normalizeActionName(
-    phase.action ?? phase.visual_action?.type ?? phase.visual_action?.action
-  );
-  if (explicit) return explicit;
-  return inferActionFromCameraMotion(phase);
-}
-
-function resolvePhaseId(phase = {}, index = 0) {
-  return normalizeText(phase.id ?? phase.phase_id ?? phase.name) || `phase_${index + 1}`;
-}
-
-function nowMs(getNowMs) {
-  return Number(getNowMs?.()) || Date.now();
-}
-
-function resolveTransitionMs(phase, fallback) {
-  const parsed = normalizeInteger(phase?.transition_ms, null);
-  if (parsed !== null && parsed >= 0) return parsed;
-  return fallback;
-}
-
-function resolveTargetY(phase, fallback = null) {
-  const explicit = pickFirstNumber(
-    phase?.target_y, phase?.to_y, phase?.y, phase?.scroll_y,
-    phase?.visual_action?.target_y, phase?.visual_action?.to_y,
-    phase?.visual_action?.y, phase?.visual_action?.scroll_y,
-  );
-  if (explicit != null) return explicit;
-
-  const focusRegion = normalizeRange(
-    phase?.focus_region
-    ?? phase?.focusRegion
-    ?? phase?.highlight?.y_range
-    ?? phase?.semantic_focus_region
-    ?? phase?.semanticFocusRegion
-    ?? phase?.visual_action?.focus_region
-    ?? phase?.visual_action?.focusRegion
-  );
-  if (focusRegion) {
-    return Math.round((focusRegion[0] + focusRegion[1]) / 2);
+  if (Number.isFinite(fullHeightPx) && fullHeightPx > 0) {
+    if (y < 0 || y > fullHeightPx) {
+      const error = new Error(
+        `y_out_of_range: section "${sectionId}" operations[${operationIndex}].y=${y} is outside [0, ${fullHeightPx}].`,
+      );
+      error.code = 'Y_OUT_OF_RANGE';
+      throw error;
+    }
   }
-  return fallback;
 }
 
-function requireTargetY(phase, action) {
-  const targetY = resolveTargetY(phase, null);
-  if (targetY == null) {
+function assertYNotInUnsafeRegion(y, { unsafeRegions, atomName, sectionId, operationIndex }) {
+  const hit = findOverlappingUnsafeRegion(unsafeRegions, y);
+  if (hit) {
     const error = new Error(
-      `phase_target_y_required: phase "${resolvePhaseId(phase)}" uses "${action}" but has no `
-      + 'target_y / to_y / y or focus_region — every scroll phase must say where it lands '
-      + '(there is no blind scroll)',
+      `y_in_unsafe_region: section "${sectionId}" operations[${operationIndex}].y=${y} (atom=${atomName}) `
+      + `falls in unsafe_regions[y=${hit.y_top}-${hit.y_bottom}, reason=${hit.reason}]. `
+      + 'Rewrite operation to land outside this range or remove the region from page_understanding '
+      + 'if the agent verified with the user it is safe.',
     );
-    error.code = 'PHASE_TARGET_Y_REQUIRED';
+    error.code = 'Y_IN_UNSAFE_REGION';
     throw error;
   }
-  return targetY;
-}
-
-function resolveFromY(phase, fallback = null) {
-  const raw = phase?.from_y ?? phase?.visual_action?.from_y;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return fallback;
-  return Math.round(parsed);
 }
 
-// ── beat dispatch ─────────────────────────────────────────────────────────
-// A "beat" is one entry in the atom sequence run during a phase. Either:
-//   { atom: 'scroll_to', params: {...} }   — leaf, dispatched directly
-//   { macro: 'scroll_to_dwell', params }   — expanded to atoms then run
-// plan-executor stays thin: turn phase into beats, then run beats.
-
-// Build the atom-sequence for a phase. Two modes:
-//   1. phase.beats[] given — used as-is (agent composing arbitrary sequences).
-//   2. phase.action given — resolved to macro (incl. legacy aliases) or
-//      single atom, phase params get passed through.
-function phaseToBeats(phase, { fallbackFromY = 0 } = {}) {
-  if (Array.isArray(phase?.beats) && phase.beats.length > 0) {
-    return { beats: phase.beats, anchorY: null };
+function validateOperation(op, { sectionId, operationIndex, fullHeightPx, unsafeRegions }) {
+  if (!op || typeof op !== 'object' || Array.isArray(op)) {
+    const error = new Error(
+      `operations_invalid: section "${sectionId}" operations[${operationIndex}] is not an object.`,
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
   }
-
-  const action = resolvePhaseAction(phase);
-
-  if (ATOM_NAMES.includes(action)) {
-    const params = paramsForAtom(action, phase, fallbackFromY);
-    const beat = { atom: action, params };
-    const anchorY = action === 'scroll_to' && Number.isFinite(Number(params.target_y))
-      ? Number(params.target_y)
-      : null;
-    return { beats: [beat], anchorY };
+  const atomName = normalizeText(op.atom);
+  if (!atomName || !ATOM_NAMES.includes(atomName)) {
+    const error = new Error(
+      `operations_invalid: section "${sectionId}" operations[${operationIndex}].atom="${atomName}" is not a known atom. `
+      + `Allowed: ${ATOM_NAMES.join(', ')}.`,
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
   }
 
-  const macroName = resolveMacroName(action);
-  if (macroName) {
-    const macroFn = MACROS[macroName];
-    const params = paramsForMacro(macroName, phase, fallbackFromY);
-    const expanded = macroFn(params, { fromY: fallbackFromY });
-    return { beats: expanded.beats, anchorY: expanded.anchorY };
+  const duration = Number(op.duration_ms);
+  if (!Number.isFinite(duration) || duration <= 0) {
+    const error = new Error(
+      `operations_invalid: section "${sectionId}" operations[${operationIndex}].duration_ms must be a positive number (got ${op.duration_ms}).`,
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
   }
 
-  if (action === 'hold') {
-    return {
-      beats: [{ atom: 'hold', params: { duration_ms: resolveDurationMs(phase, 0) } }],
-      anchorY: null,
-    };
+  if (atomName === 'scroll_to') {
+    assertYWithinBounds(Number(op.y), { fullHeightPx, atomName, sectionId, operationIndex });
+    assertYNotInUnsafeRegion(Number(op.y), { unsafeRegions, atomName, sectionId, operationIndex });
+  } else if (atomName === 'cursor_focus') {
+    assertYWithinBounds(Number(op.y), { fullHeightPx, atomName, sectionId, operationIndex });
+    assertYNotInUnsafeRegion(Number(op.y), { unsafeRegions, atomName, sectionId, operationIndex });
+    if (!Number.isFinite(Number(op.x))) {
+      const error = new Error(
+        `operations_invalid: section "${sectionId}" operations[${operationIndex}].x is missing or not a number (atom=cursor_focus).`,
+      );
+      error.code = 'OPERATIONS_INVALID';
+      throw error;
+    }
   }
-
-  const error = new Error(
-    `phase_action_unsupported:${action || 'empty'} — supported actions: ${SUPPORTED_PHASE_ACTIONS.join(', ')}`
-    + ' (there is no blind scroll_down/scroll_up; pick a macro or write phase.beats[] from atoms)',
-  );
-  error.code = 'PHASE_ACTION_UNSUPPORTED';
-  throw error;
+  return atomName;
 }
 
-// Phase fields → atom params. Atom-specific shape; missing fields fall back
-// to the same derivations the old executors did (resolveDurationMs, etc).
-function paramsForAtom(atomName, phase, fallbackFromY) {
-  const durationMs = resolveDurationMs(phase, null);
+function operationToAtomParams(op, atomName, anchorY) {
   if (atomName === 'scroll_to') {
     return {
-      target_y: requireTargetY(phase, 'scroll_to'),
-      duration_ms: durationMs ?? resolveTransitionMs(phase, 600),
-      curve: phase.curve || phase.motion_curve || 'easeInOutQuad',
-      jitter_px: Number.isFinite(Number(phase.jitter_px)) ? Number(phase.jitter_px) : 2,
-      from_y: resolveFromY(phase, fallbackFromY),
+      target_y: Number(op.y),
+      duration_ms: Number(op.duration_ms),
+      curve: op.curve || 'easeInOutQuad',
+      jitter_px: Number.isFinite(Number(op.jitter_px)) ? Number(op.jitter_px) : 2,
+      from_y: anchorY,
+      mode: op.mode || 'auto',
     };
   }
   if (atomName === 'hold') {
-    return { duration_ms: durationMs ?? 0 };
-  }
-  if (atomName === 'micro_oscillate') {
-    return {
-      amplitude_px: Number(phase.amplitude_px) || 30,
-      duration_ms: durationMs ?? 0,
-      period_ms: Number(phase.period_ms) || 1400,
-    };
+    return { duration_ms: Number(op.duration_ms) };
   }
   if (atomName === 'cursor_focus') {
     return {
-      x: Number(phase.x ?? phase.cursor_x),
-      y: Number(phase.y ?? phase.cursor_y),
-      duration_ms: durationMs ?? 0,
+      x: Number(op.x),
+      y: Number(op.y),
+      duration_ms: Number(op.duration_ms),
     };
   }
-  return { ...phase };
+  return {};
 }
 
-// Phase fields → macro params. Macros validate their own inputs.
-// Number(null) === 0 (a JS gotcha) — guard explicitly so a normalize step
-// that fills missing fields with `null` (see normalizeSectionAsPhase) doesn't
-// trick `Number.isFinite` into accepting a phantom zero.
-function optionalFiniteNumber(value) {
-  if (value == null) return undefined;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : undefined;
+function normalizeSection(section, index) {
+  if (!section || typeof section !== 'object' || Array.isArray(section)) {
+    const error = new Error(`plan_sections_required: sections[${index}] is not an object`);
+    error.code = 'PLAN_SECTIONS_REQUIRED';
+    throw error;
+  }
+  const id = resolveSectionId(section, index);
+  assertNoV5Fields(section, id);
+  if (!Array.isArray(section.operations) || section.operations.length === 0) {
+    const error = new Error(
+      `operations_invalid: section "${id}" missing operations[] array. `
+      + 'Every section must specify a non-empty operations sequence (e.g. [{atom:"scroll_to",...},{atom:"hold",...}]).',
+    );
+    error.code = 'OPERATIONS_INVALID';
+    throw error;
+  }
+  return { ...section, id, phase_id: id };
 }
 
-function paramsForMacro(macroName, phase, fallbackFromY) {
-  const durationMs = resolveDurationMs(phase, null);
-  const targetY = resolveTargetY(phase, null);
-  const fromY = resolveFromY(phase, fallbackFromY);
-  const base = {
-    target_y: targetY,
-    duration_ms: durationMs,
-    from_y: fromY,
-    transition_ms: optionalFiniteNumber(phase.transition_ms),
-    transition_ratio: optionalFiniteNumber(phase.transition_ratio),
-    transition_curve: phase.transition_curve,
-    amplitude_px: phase.amplitude_px,
-    oscillate_period_ms: phase.oscillate_period_ms,
-  };
-  if (macroName === 'focal_arc') {
-    return { ...base, points: Array.isArray(phase.points) ? phase.points : [] };
-  }
-  if (macroName === 'scroll_to_dwell') {
-    // The legacy fast_scroll alias maps to scroll_to_dwell, but with a
-    // shorter default transition_ratio so the snap feels closer to the
-    // original fast_scroll behavior.
-    const isFastScrollAlias = String(phase.action || '').toLowerCase() === 'fast_scroll';
-    if (isFastScrollAlias && base.transition_ratio === undefined) {
-      base.transition_ratio = 0.1;
-    }
+export function normalizePlanSections(plan = {}) {
+  const sections = Array.isArray(plan?.sections) ? plan.sections
+    : Array.isArray(plan?.phases) ? plan.phases
+    : null;
+  if (!sections || sections.length === 0) {
+    const error = new Error(
+      'plan_sections_required: plan.sections must be a non-empty array. '
+      + 'Each section is { id?, text?, audio_path?, dwell_ms?, operations: [{atom, duration_ms, ...}] }.',
+    );
+    error.code = 'PLAN_SECTIONS_REQUIRED';
+    throw error;
   }
-  return base;
+  return sections.map((section, index) => normalizeSection(section, index));
 }
 
-// Run an atom-sequence in order. Each beat is either:
-//   - an atom (run directly through ATOMS[name])
-//   - a macro reference (expand to atoms inline; one level of nesting only —
-//     macros calling macros breaks the "shortcut for common atom combo"
-//     mental model).
-async function executeBeats(page, ctx, beats, { fallbackFromY = 0 } = {}) {
-  let anchorY = fallbackFromY;
-  for (const beat of beats) {
-    if (!beat || typeof beat !== 'object') continue;
-    if (beat.macro) {
-      const macroFn = MACROS[beat.macro] || MACROS[resolveMacroName(beat.macro)];
-      if (!macroFn) {
-        const error = new Error(`beat_macro_unsupported:${beat.macro}`);
-        error.code = 'BEAT_MACRO_UNSUPPORTED';
-        throw error;
-      }
-      const expanded = macroFn(beat.params ?? {}, { fromY: anchorY });
-      const sub = await executeBeats(page, ctx, expanded.beats, { fallbackFromY: anchorY });
-      if (sub?.anchorY != null) anchorY = sub.anchorY;
-      else if (expanded.anchorY != null) anchorY = expanded.anchorY;
-      continue;
-    }
-    const atomName = beat.atom;
+async function runOperations(page, ctx, operations, {
+  fullHeightPx,
+  unsafeRegions,
+  sectionId,
+  fallbackAnchorY,
+}) {
+  let anchorY = fallbackAnchorY;
+  for (let i = 0; i < operations.length; i += 1) {
+    const op = operations[i];
+    const atomName = validateOperation(op, {
+      sectionId,
+      operationIndex: i,
+      fullHeightPx,
+      unsafeRegions,
+    });
+    const params = operationToAtomParams(op, atomName, anchorY);
     const atomFn = ATOMS[atomName];
-    if (!atomFn) {
-      const error = new Error(`beat_atom_unsupported:${atomName || 'missing'}`);
-      error.code = 'BEAT_ATOM_UNSUPPORTED';
-      throw error;
-    }
-    const params = { ...(beat.params ?? {}) };
-    // Pre-fill scroll_to's from_y from the running anchor so sequences can
-    // chain naturally without the agent recomputing positions.
-    if (atomName === 'scroll_to' && params.from_y == null) params.from_y = anchorY;
     const result = await atomFn(page, ctx, params);
     if (result?.anchorY != null) anchorY = result.anchorY;
   }
   return { anchorY };
 }
 
-async function executePhase(page, phase, {
-  lastAnchorY = null,
-  initialAnchorY = 0,
-} = {}) {
-  const fallbackFromY = lastAnchorY ?? initialAnchorY;
-  const { beats, anchorY: macroAnchor } = phaseToBeats(phase, { fallbackFromY });
-
-  // One CDP session per phase, threaded to atoms via ctx (cached on page by
-  // cdp-touch.js so this is cheap on repeat calls). Tests pass a mock page
-  // that throws here; we swallow and let atoms that need CDP fail on demand.
-  let cdp = null;
-  try { cdp = await getCdpSession(page); } catch { /* mock pages may not expose context() */ }
-  const ctx = { cdp, fromY: fallbackFromY };
-
-  const { anchorY } = await executeBeats(page, ctx, beats, { fallbackFromY });
-  return { anchorY: anchorY ?? macroAnchor ?? null };
-}
-
-function createEvent({ tMs, action, phaseId, phaseAction, detail = {} }) {
+function createEvent({ tMs, action, sectionId, detail = {} }) {
   return {
     t_ms: Math.max(0, Math.round(tMs)),
     action,
-    phase_id: phaseId,
-    phase_action: phaseAction,
+    phase_id: sectionId,
+    section_id: sectionId,
     ...detail,
   };
 }
 
 export async function executePlanPhases(page, plan, {
+  pageUnderstanding = null,
   getNowMs = () => Date.now(),
   onEvent = null,
 } = {}) {
-  const phases = normalizePlanPhases(plan);
+  const sections = normalizePlanSections(plan);
+  const fullHeightPx = Number(pageUnderstanding?.full_height_px) || null;
+  const unsafeRegions = Array.isArray(pageUnderstanding?.unsafe_regions)
+    ? pageUnderstanding.unsafe_regions
+    : [];
+
   const startedAt = nowMs(getNowMs);
   const eventsLog = [];
   let lastAnchorY = 0;
 
-  for (let index = 0; index < phases.length; index += 1) {
-    const phase = phases[index];
-    const phaseId = resolvePhaseId(phase, index);
-    const phaseAction = resolvePhaseAction(phase);
+  for (let index = 0; index < sections.length; index += 1) {
+    const section = sections[index];
+    const sectionId = section.id;
 
     const startEvent = createEvent({
       tMs: nowMs(getNowMs) - startedAt,
       action: 'phase_start',
-      phaseId,
-      phaseAction,
+      sectionId,
     });
     eventsLog.push(startEvent);
     if (typeof onEvent === 'function') onEvent(startEvent);
 
+    let cdp = null;
+    try { cdp = await getCdpSession(page); } catch { /* mock pages may not expose context() */ }
+    const ctx = { cdp };
+
     try {
-      const executionResult = await executePhase(page, phase, {
-        lastAnchorY,
-        initialAnchorY: 0,
+      const result = await runOperations(page, ctx, section.operations, {
+        fullHeightPx,
+        unsafeRegions,
+        sectionId,
+        fallbackAnchorY: lastAnchorY,
       });
-      const anchorY = Number(executionResult?.anchorY);
-      if (Number.isFinite(anchorY)) {
-        lastAnchorY = Math.round(anchorY);
-      }
+      if (Number.isFinite(result.anchorY)) lastAnchorY = result.anchorY;
     } catch (error) {
       const errorEvent = createEvent({
         tMs: nowMs(getNowMs) - startedAt,
         action: 'phase_error',
-        phaseId,
-        phaseAction,
-        detail: {
-          error: error?.message ?? 'unknown_error',
-        },
+        sectionId,
+        detail: { error: error?.message ?? 'unknown_error', code: error?.code ?? null },
       });
       eventsLog.push(errorEvent);
       if (typeof onEvent === 'function') onEvent(errorEvent);
@@ -484,8 +282,7 @@ export async function executePlanPhases(page, plan, {
     const endEvent = createEvent({
       tMs: nowMs(getNowMs) - startedAt,
       action: 'phase_end',
-      phaseId,
-      phaseAction,
+      sectionId,
     });
     eventsLog.push(endEvent);
     if (typeof onEvent === 'function') onEvent(endEvent);