@gakim-digital/dexter-bridge 0.11.0 → 0.11.1

package/src/framerAgentTools.js

@@ -1,20 +1,62 @@
 import crypto from 'node:crypto';
+import fs from 'node:fs';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
+import path from 'node:path';
+import {
+  BEHAVIOR_ACTIVATIONS,
+  BEHAVIOR_LAYOUT_EFFECTS,
+  BEHAVIOR_MECHANISMS,
+  BEHAVIOR_PRESENTATIONS,
+  canonicalIdMappings,
+  evidenceNodeIds,
+  mergeBehaviorPlans,
+  normalizeBehaviorEvidence,
+  normalizeBehaviorPlan,
+  summarizeFramerChanges,
+  verifyBehaviorEvidence,
+} from './framerBehaviorContract.js';
 
 const require = createRequire(import.meta.url);
 const MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+const MAX_MODEL_RESULT_BYTES = 120 * 1024;
 const DEFAULT_COMMAND_TIMEOUT_MS = 5 * 60_000;
 const SESSION_TIMEOUT_MS = 10 * 60_000;
-const AUTHORIZATION_TIMEOUT_MS = 10 * 60_000;
-const AUTHORIZATION_POLL_MS = 2_000;
-const PROJECT_ID_PATTERN = /^[A-Za-z0-9_-]{1,200}$/;
+const MAX_UNSAFE_WRITE_FAILURES = 2;
+const MAX_LOW_LEVEL_WRITE_FAILURES = 3;
+const MAX_GUIDANCE_BYTES = 180 * 1024;
+const MAX_GUIDANCE_FILE_BYTES = 48 * 1024;
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9]{20}$/;
+const PROJECT_SEGMENT_PATTERN =
+  /^(?:.+--)?([A-Za-z0-9]+)(?:-[A-Za-z0-9]+)?$/;
+const FRAMER_PROJECT_HOST_PATTERN = /(^|\.)framer(?:local)?\.com$/i;
 const PAGE_PATH_PATTERN = /^\/[^\0\r\n]{0,499}$/;
 const UNSAFE_EXEC_PATTERN =
   /\b(?:process|globalThis|global|require|import\s*\(|child_process|worker_threads|fs|os|net|tls|dgram|http|https|fetch|WebSocket|eval|Function)\b/;
 const MUTATING_EXEC_PATTERN =
   /\.(?:set|add|create|remove|delete|update|insert|move|clone|duplicate|upload|publish|deploy|switch|merge|rename|join|leave|apply)[A-Za-z0-9_]*\s*\(/;
-
+const TASK_DOMAINS = [
+  'visual',
+  'content',
+  'links',
+  'interactions',
+  'responsive',
+  'data',
+  'code',
+  'structure',
+];
+const VERIFICATION_CHECKS = [
+  'structural',
+  'visual',
+  'links',
+  'interactions',
+  'responsive',
+  'code',
+  'data',
+];
+const GENERIC_VERIFICATION_CHECKS = VERIFICATION_CHECKS.filter(
+  (check) => check !== 'interactions',
+);
 const EMPTY_SCHEMA = {
   type: 'object',
   properties: {},
@@ -25,7 +67,7 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'progress_update',
     description:
-      'Tell the user what you are doing and why it matters in one or two natural first-person sentences. Call this before the first Framer inspection or edit and at meaningful phase changes.',
+      'Tell the user what you are about to do or are doing now in one or two natural first-person sentences. Name the specific page area, component, or behavior and the concrete change; optionally say what you will check next. Avoid generic updates such as "working on the next step", "thinking", "loading", or "making changes". Call this before the first Framer inspection or edit and at meaningful phase changes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -38,8 +80,18 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_instructions',
     description:
-      'Load Framer’s official agent command reference. Call this before the first canvas change unless the current session already established the command syntax.',
-    inputSchema: EMPTY_SCHEMA,
+      'Get concise Framer Agent guidance, or request targeted official API documentation when an exact method or type is unclear. Most runs should rely on the tool descriptions and call this only when needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        queries: {
+          type: 'array',
+          maxItems: 8,
+          items: { type: 'string', minLength: 1, maxLength: 120 },
+        },
+      },
+      additionalProperties: false,
+    },
   },
   {
     name: 'framer_context',
@@ -61,11 +113,275 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
           items: { type: 'object', additionalProperties: true },
         },
         pagePath: { type: 'string', maxLength: 500, default: '/' },
+        verifies: {
+          type: 'array',
+          uniqueItems: true,
+          maxItems: 6,
+          items: { type: 'string', enum: GENERIC_VERIFICATION_CHECKS },
+          description:
+            'Verification evidence this read is intended to establish after mutations. Interaction verification requires framer_verify_interactions.',
+        },
       },
       required: ['queries'],
       additionalProperties: false,
     },
   },
+  {
+    name: 'framer_plan_task',
+    description:
+      'After inspecting the live Framer target and before the first mutation, declare your semantic understanding, observable behavior requirements, chosen implementation mechanisms, and completion evidence. Dexter does not classify the request or choose mechanisms for you.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: {
+          type: 'string',
+          minLength: 10,
+          maxLength: 1000,
+        },
+        domains: {
+          type: 'array',
+          minItems: 1,
+          uniqueItems: true,
+          items: { type: 'string', enum: TASK_DOMAINS },
+        },
+        verification: {
+          type: 'array',
+          minItems: 1,
+          uniqueItems: true,
+          items: { type: 'string', enum: VERIFICATION_CHECKS },
+        },
+        behaviors: {
+          type: 'array',
+          maxItems: 20,
+          description:
+            'Required for interaction work. Describe observable behavior independently from its implementation.',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', minLength: 1, maxLength: 120 },
+              description: { type: 'string', minLength: 5, maxLength: 500 },
+              triggerDescription: {
+                type: 'string',
+                minLength: 3,
+                maxLength: 300,
+              },
+              activation: {
+                type: 'string',
+                enum: BEHAVIOR_ACTIVATIONS,
+              },
+              presentation: {
+                type: 'string',
+                enum: BEHAVIOR_PRESENTATIONS,
+              },
+              stateChange: { type: 'boolean' },
+              layoutEffect: {
+                type: 'string',
+                enum: BEHAVIOR_LAYOUT_EFFECTS,
+              },
+              reversible: { type: 'boolean' },
+              repeatable: { type: 'boolean' },
+              expectedTargets: {
+                type: 'integer',
+                minimum: 1,
+                maximum: 50,
+              },
+              expectedContent: {
+                type: 'array',
+                maxItems: 20,
+                items: { type: 'string', minLength: 1, maxLength: 500 },
+              },
+              initialState: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+              activatedState: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+            },
+            required: [
+              'id',
+              'description',
+              'triggerDescription',
+              'activation',
+              'presentation',
+              'stateChange',
+              'layoutEffect',
+              'reversible',
+              'repeatable',
+              'expectedTargets',
+              'initialState',
+              'activatedState',
+            ],
+            additionalProperties: false,
+          },
+        },
+        mechanisms: {
+          type: 'array',
+          maxItems: 20,
+          description:
+            'Required for every declared behavior. Choose the mechanism from live project capabilities and explain why it satisfies the behavior.',
+          items: {
+            type: 'object',
+            properties: {
+              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
+              mechanism: {
+                type: 'string',
+                enum: BEHAVIOR_MECHANISMS,
+              },
+              rationale: {
+                type: 'string',
+                minLength: 10,
+                maxLength: 800,
+              },
+              representativeFirst: { type: 'boolean', default: true },
+            },
+            required: ['behaviorId', 'mechanism', 'rationale'],
+            additionalProperties: false,
+          },
+        },
+        rejectedMechanisms: {
+          type: 'array',
+          maxItems: 30,
+          description:
+            'Mechanisms already disproven by user-observed failure or prior verification. Do not silently reuse them.',
+          items: {
+            type: 'object',
+            properties: {
+              behaviorId: { type: 'string', minLength: 1, maxLength: 120 },
+              behaviorSignature: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 128,
+              },
+              mechanism: {
+                type: 'string',
+                enum: BEHAVIOR_MECHANISMS,
+              },
+              reason: { type: 'string', minLength: 5, maxLength: 800 },
+              source: {
+                type: 'string',
+                enum: ['user_reported_failure', 'verification_failure'],
+              },
+            },
+            required: ['mechanism', 'reason'],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['summary', 'domains', 'verification'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_verify_interactions',
+    description:
+      'Verify the observable behavior contract from the live Framer tree. The runtime derives the required action and invariants from the planned behavior and mechanism; supply only canonical evidence node IDs. This is the only tool that can satisfy interaction verification.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pagePath: { type: 'string', maxLength: 500, default: '/' },
+        checks: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 20,
+          items: {
+            type: 'object',
+            properties: {
+              description: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 300,
+              },
+              behaviorId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 120,
+              },
+              triggerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              event: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 80,
+              },
+              targetNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              componentNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              instanceNodeIds: {
+                type: 'array',
+                maxItems: 50,
+                uniqueItems: true,
+                items: {
+                  type: 'string',
+                  minLength: 1,
+                  maxLength: 200,
+                },
+              },
+              openVariantNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              closedVariantNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              openAnswerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+              closedAnswerNodeId: {
+                type: 'string',
+                minLength: 1,
+                maxLength: 200,
+              },
+            },
+            required: [
+              'behaviorId',
+              'triggerNodeId',
+              'event',
+            ],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ['checks'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'framer_query_images',
+    description:
+      'Search Framer Agent’s approved image source for real-world imagery. Use this only when the design needs a concrete photo or editorial image and no suitable user attachment or existing project image is available.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', minLength: 2, maxLength: 200 },
+        count: { type: 'integer', minimum: 1, maximum: 8, default: 4 },
+        orientation: {
+          type: 'string',
+          enum: ['landscape', 'portrait', 'squarish'],
+        },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+  },
   {
     name: 'framer_apply_changes',
     description:
@@ -88,6 +404,14 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
       type: 'object',
       properties: {
         code: { type: 'string', minLength: 1, maxLength: 200_000 },
+        verifies: {
+          type: 'array',
+          uniqueItems: true,
+          maxItems: 6,
+          items: { type: 'string', enum: GENERIC_VERIFICATION_CHECKS },
+          description:
+            'Verification evidence this read is intended to establish after mutations. Interaction verification requires framer_verify_interactions.',
+        },
       },
       required: ['code'],
       additionalProperties: false,
@@ -96,13 +420,20 @@ export const FRAMER_AGENT_TOOL_DEFINITIONS = [
   {
     name: 'framer_write',
     description:
-      'Execute project-scoped JavaScript with the official Framer Agent connection for mutations not covered by applyChanges, such as code files, localization, redirects, assets, CMS, or branch operations. Publishing is disabled unless Dexter explicitly authorizes it.',
+      'Execute project-scoped JavaScript with the official Framer Agent connection for mutations not covered by applyChanges, such as code files, localization, redirects, assets, CMS, or branch operations. Publishing is disabled unless Dexter explicitly authorizes it. If a write is rejected as unsafe, do not retry JavaScript variants; switch to framer_apply_changes or report the concrete blocker.',
     inputSchema: {
       type: 'object',
       properties: {
         code: { type: 'string', minLength: 1, maxLength: 200_000 },
+        reason: {
+          type: 'string',
+          minLength: 10,
+          maxLength: 500,
+          description:
+            'Explain the specific Framer capability needed and why framer_apply_changes cannot perform it.',
+        },
       },
-      required: ['code'],
+      required: ['code', 'reason'],
       additionalProperties: false,
     },
   },
@@ -131,6 +462,67 @@ function boundedText(value, maximum) {
   return `${text.slice(0, maximum)}\n...[output clipped]`;
 }
 
+function hasInstalledFramerSkill(env) {
+  const home = String(env?.HOME || '').trim();
+  if (!home) return false;
+  return [
+    path.join(home, '.agents', 'skills', 'framer', 'SKILL.md'),
+    path.join(home, '.claude', 'skills', 'framer', 'SKILL.md'),
+  ].some((skillPath) => fs.existsSync(skillPath));
+}
+
+function framerSkillRoot(env) {
+  const home = String(env?.HOME || '').trim();
+  if (!home) return null;
+  return [
+    path.join(home, '.agents', 'skills', 'framer'),
+    path.join(home, '.claude', 'skills', 'framer'),
+  ].find((root) => fs.existsSync(path.join(root, 'SKILL.md'))) || null;
+}
+
+function installedFramerAgentVersion() {
+  try {
+    let current = path.dirname(resolveFramerAgentCli());
+    for (let depth = 0; depth < 8; depth += 1) {
+      const packagePath = path.join(current, 'package.json');
+      if (fs.existsSync(packagePath)) {
+        const manifest = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+        if (manifest?.name === '@framer/agent') {
+          return String(manifest.version || '').trim() || null;
+        }
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  } catch {
+    // Version telemetry must never block a run.
+  }
+  return null;
+}
+
+function readGuidanceFile(projectRoot, relativePath, remainingBytes) {
+  const normalized = relativePath.replaceAll('\\', '/');
+  if (
+    normalized.startsWith('/')
+    || normalized.split('/').some((segment) => segment === '..')
+  ) return null;
+  const absolutePath = path.resolve(projectRoot, normalized);
+  if (
+    absolutePath !== projectRoot
+    && !absolutePath.startsWith(`${projectRoot}${path.sep}`)
+  ) return null;
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    return null;
+  }
+  const maximum = Math.min(MAX_GUIDANCE_FILE_BYTES, remainingBytes);
+  if (maximum <= 0) return null;
+  return {
+    path: normalized,
+    content: boundedText(fs.readFileSync(absolutePath, 'utf8'), maximum),
+  };
+}
+
 function normalizeProjectId(value) {
   const projectId = String(value || '').trim();
   if (!PROJECT_ID_PATTERN.test(projectId)) {
@@ -142,6 +534,55 @@ function normalizeProjectId(value) {
   return projectId;
 }
 
+function projectIdFromUrl(url) {
+  const segments = url.pathname.split('/').filter(Boolean);
+  if (
+    segments.length !== 2
+    || segments[0]?.toLowerCase() !== 'projects'
+    || !segments[1]
+  ) return '';
+  try {
+    const projectId = decodeURIComponent(segments[1])
+      .match(PROJECT_SEGMENT_PATTERN)?.[1] || '';
+    return PROJECT_ID_PATTERN.test(projectId) ? projectId : '';
+  } catch {
+    return '';
+  }
+}
+
+function normalizeProjectUrl(value, expectedProjectId) {
+  let url;
+  try {
+    url = new URL(String(value || '').trim());
+  } catch {
+    throw toolError(
+      'FRAMER_AGENT_PROJECT_URL_INVALID',
+      'The exact Framer project URL is missing or invalid.',
+    );
+  }
+  if (
+    url.protocol !== 'https:'
+    || !FRAMER_PROJECT_HOST_PATTERN.test(url.hostname)
+    || url.username
+    || url.password
+  ) {
+    throw toolError(
+      'FRAMER_AGENT_PROJECT_URL_INVALID',
+      'The exact Framer project URL is missing or invalid.',
+    );
+  }
+  const projectId = projectIdFromUrl(url);
+  if (!projectId || projectId !== expectedProjectId) {
+    throw toolError(
+      'FRAMER_AGENT_PROJECT_MISMATCH',
+      'The Framer project URL does not match the project selected in Dexter.',
+      409,
+    );
+  }
+  url.hash = '';
+  return url.toString();
+}
+
 function normalizePagePath(value) {
   const pagePath = String(value || '/').trim() || '/';
   if (!PAGE_PATH_PATTERN.test(pagePath)) {
@@ -164,6 +605,156 @@ function uniqueStrings(values, maximum = 500) {
   ).slice(0, maximum);
 }
 
+function normalizeVerificationValues(values, allowed) {
+  return uniqueStrings(Array.isArray(values) ? values : [])
+    .filter((value) => allowed.includes(value));
+}
+
+function normalizeTaskPlan(rawArguments, inheritedRejectedMechanisms = []) {
+  const summary = String(rawArguments.summary || '').trim().slice(0, 1000);
+  const domains = normalizeVerificationValues(
+    rawArguments.domains,
+    TASK_DOMAINS,
+  );
+  const requestedVerification = normalizeVerificationValues(
+    rawArguments.verification,
+    VERIFICATION_CHECKS,
+  );
+  if (summary.length < 10 || domains.length === 0) {
+    throw toolError(
+      'FRAMER_HARNESS_PLAN_INVALID',
+      'Describe the understood task and declare at least one task domain.',
+    );
+  }
+  const verification = new Set(['structural', ...requestedVerification]);
+  if (
+    domains.some((domain) =>
+      ['visual', 'interactions', 'responsive'].includes(domain))
+  ) verification.add('visual');
+  if (domains.includes('links')) verification.add('links');
+  if (domains.includes('interactions')) verification.add('interactions');
+  if (domains.includes('responsive')) verification.add('responsive');
+  if (domains.includes('code')) verification.add('code');
+  if (domains.includes('data')) verification.add('data');
+  const behaviorPlan = normalizeBehaviorPlan(
+    rawArguments,
+    inheritedRejectedMechanisms,
+  );
+  if (
+    domains.includes('interactions')
+    && behaviorPlan.behaviors.length === 0
+  ) {
+    throw toolError(
+      'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
+      'Interaction work requires observable behaviors and one compatible mechanism decision per behavior.',
+    );
+  }
+  if (behaviorPlan.behaviors.length > 0) {
+    if (!domains.includes('interactions')) domains.push('interactions');
+    verification.add('interactions');
+  }
+  return {
+    summary,
+    domains,
+    verification: [...verification],
+    ...behaviorPlan,
+  };
+}
+
+function workingPreferencesFromAssignment(assignment) {
+  const context = isRecord(assignment?.context) ? assignment.context : {};
+  const grant = isRecord(context.contextGrant) ? context.contextGrant : {};
+  const supplied = isRecord(context.workingPreferences)
+    ? context.workingPreferences
+    : {};
+  const selectedNodeIds = uniqueStrings([
+    ...(Array.isArray(context.selectedNodeIds)
+      ? context.selectedNodeIds
+      : []),
+    ...(Array.isArray(grant.selectedNodeIds)
+      ? grant.selectedNodeIds
+      : []),
+  ]);
+  const selectionFirst =
+    supplied.focus === 'selection-first'
+    || (
+      selectedNodeIds.length > 0
+      && grant.writeScope === 'selection'
+    );
+  return {
+    mode: selectionFirst ? 'selection-first' : 'standard',
+    writeScope: String(
+      supplied.writeScope || grant.writeScope || 'none',
+    ).trim() || 'none',
+    selectionFirst,
+    preferBatchedMutations: supplied.preferBatchedMutations !== false,
+    avoidRepeatedInspection: supplied.avoidRepeatedInspection !== false,
+    expandScopeOnlyWhenNeeded:
+      supplied.expandScopeOnlyWhenNeeded !== false,
+  };
+}
+
+function toolDefinitionsForPreferences(requestedTools, preferences) {
+  return FRAMER_AGENT_TOOL_DEFINITIONS
+    .filter((tool) => requestedTools.has(tool.name))
+    .map((tool) => {
+      if (!preferences.selectionFirst) return tool;
+      if (tool.name === 'framer_context') {
+        return {
+          ...tool,
+          description:
+            'Read broad project context only when the selected subtree lacks a concrete dependency required for the request. Do not use this as the default first inspection.',
+        };
+      }
+      if (tool.name === 'framer_read_project') {
+        return {
+          ...tool,
+          description:
+            'Run supported Framer readProject queries, especially screenshots. For node-tree inspection, prefer framer_read with framer.agent.getNode({ id }), getNodes({ ids }), serialize, or other focused node APIs. Batch related queries when practical.',
+        };
+      }
+      if (tool.name === 'framer_apply_changes') {
+        return {
+          ...tool,
+          description:
+            'Apply related changes inside the authorized selection in coherent batches when practical. Read the returned diagnostics, verify the result, and make any further repair batches the work requires.',
+        };
+      }
+      if (tool.name === 'framer_read') {
+        return {
+          ...tool,
+          description:
+            'Use focused JavaScript for node-tree inspection and Framer capabilities not covered by readProject. Start with the selected nodes, reuse prior evidence, and expand only when a concrete dependency requires it.',
+        };
+      }
+      if (tool.name === 'framer_write') {
+        return {
+          ...tool,
+          description:
+            'Use project-scoped JavaScript only when framer_apply_changes cannot perform the required authorized capability. Explain that limitation in reason, prefer cohesive operations, and keep mutations within the authorized write scope. Do not retry JavaScript variants after a safety rejection.',
+        };
+      }
+      return tool;
+    });
+}
+
+function boundedStructuredValue(value, maximum = MAX_MODEL_RESULT_BYTES) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    return {
+      truncated: true,
+      output: '[Framer result could not be serialized.]',
+    };
+  }
+  if (Buffer.byteLength(serialized, 'utf8') <= maximum) return value;
+  return {
+    truncated: true,
+    output: boundedText(serialized, maximum),
+  };
+}
+
 function authoritativeNodeIdsFromAssignment(assignment) {
   const context = isRecord(assignment?.context) ? assignment.context : {};
   const grant = isRecord(context.contextGrant) ? context.contextGrant : {};
@@ -237,89 +828,6 @@ function abortError() {
   });
 }
 
-function wait(delayMs, signal) {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(abortError());
-      return;
-    }
-    const onAbort = () => {
-      clearTimeout(timer);
-      reject(abortError());
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, Math.max(0, delayMs));
-    timer.unref?.();
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
-}
-
-function authorizationUrl(value) {
-  let parsed;
-  try {
-    parsed = new URL(String(value || ''));
-  } catch {
-    throw toolError(
-      'FRAMER_AGENT_AUTHORIZATION_URL_INVALID',
-      'Dexter received an invalid Framer authorization URL.',
-      502,
-    );
-  }
-  const hostname = parsed.hostname.toLowerCase();
-  const trusted =
-    hostname === 'framer.com'
-    || hostname.endsWith('.framer.com')
-    || hostname === 'framerlocal.com'
-    || hostname.endsWith('.framerlocal.com');
-  if (
-    parsed.protocol !== 'https:'
-    || parsed.username
-    || parsed.password
-    || !trusted
-  ) {
-    throw toolError(
-      'FRAMER_AGENT_AUTHORIZATION_URL_INVALID',
-      'Dexter blocked an untrusted Framer authorization URL.',
-      502,
-    );
-  }
-  return parsed.toString();
-}
-
-export function openFramerAuthorizationUrl(
-  value,
-  {
-    platform = process.platform,
-    spawnImpl = spawn,
-  } = {},
-) {
-  const url = authorizationUrl(value);
-  const command =
-    platform === 'darwin'
-      ? '/usr/bin/open'
-      : platform === 'win32'
-        ? 'rundll32.exe'
-        : 'xdg-open';
-  const args =
-    platform === 'win32'
-      ? ['url.dll,FileProtocolHandler', url]
-      : [url];
-  return new Promise((resolve, reject) => {
-    const child = spawnImpl(command, args, {
-      stdio: 'ignore',
-      detached: true,
-      windowsHide: true,
-    });
-    child.once?.('error', (error) => reject(error));
-    child.once?.('spawn', () => {
-      child.unref?.();
-      resolve(true);
-    });
-  });
-}
-
 function parseStructuredOutput(value) {
   const text = String(value || '').trim();
   if (!text) return null;
@@ -470,8 +978,7 @@ function sessionIdFromOutput(value) {
 function isAuthorizationFailure(error) {
   return (
     error?.code === 'FRAMER_AGENT_AUTHORIZATION_REQUIRED'
-    || error?.code === 'FRAMER_AGENT_PROJECT_NOT_FOUND'
-    || /authoriz|log in|login|api key|project not found|session expired/i.test(
+    || /authoriz|log in|login|api key|does not have access|session expired/i.test(
       String(error?.message || ''),
     )
   );
@@ -481,7 +988,14 @@ function projectConnectionError(error) {
   if (/project not found/i.test(String(error?.message || ''))) {
     return toolError(
       'FRAMER_AGENT_PROJECT_NOT_FOUND',
-      'Framer could not authorize this project. Make sure the browser is signed into an account with access to the open project, then reconnect it in Dexter.',
+      'The project key passed Server API verification, but Framer Agent could not find the authoritative project ID. Reopen the project in Framer, reconnect it in Dexter, and try again.',
+      409,
+    );
+  }
+  if (isAuthorizationFailure(error)) {
+    return toolError(
+      'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
+      'The project key passed Server API verification, but Framer Agent rejected it while creating the editing session. Reconnect the open project in Dexter with a current key from General → API Keys, then try again.',
       409,
     );
   }
@@ -496,20 +1010,36 @@ export function createFramerAgentToolRuntime({
   onActivity,
   runCli = runFramerAgentCli,
   authorizeProject,
-  openAuthorizationUrl = openFramerAuthorizationUrl,
-  authorizationTimeoutMs = AUTHORIZATION_TIMEOUT_MS,
+  verifyProjectAuthorization,
 } = {}) {
   const projectId = normalizeProjectId(assignment?.context?.framerProjectId);
+  const projectUrl = normalizeProjectUrl(
+    assignment?.context?.framerProjectUrl,
+    projectId,
+  );
+  const sessionCacheKey = projectId;
   const requestedTools = Array.isArray(assignment?.toolProtocol?.tools)
     ? assignment.toolProtocol.tools
     : FRAMER_AGENT_TOOL_DEFINITIONS.map((tool) => tool.name);
   const allowedToolNames = new Set(
     requestedTools.filter((name) => TOOL_BY_NAME.has(name)),
   );
-  const definitions = FRAMER_AGENT_TOOL_DEFINITIONS.filter((tool) =>
-    allowedToolNames.has(tool.name),
+  const workingPreferences = workingPreferencesFromAssignment(assignment);
+  const definitions = toolDefinitionsForPreferences(
+    allowedToolNames,
+    workingPreferences,
   );
   const allowPublishing = assignment?.context?.permissions?.publish === true;
+  const inheritedRejectedMechanisms =
+    assignment?.context?.repairContext?.rejectedMechanisms
+    || assignment?.repairContext?.rejectedMechanisms
+    || [];
+  const authorizedInstanceContainerIds = uniqueStrings(
+    assignment?.context?.permissions?.scopedComponentArtifacts
+      ?.instanceContainerNodeIds
+      || assignment?.context?.contextGrant?.writableNodeIds
+      || [],
+  );
   const activePagePath = normalizePagePath(
     assignment?.context?.activePagePath,
   );
@@ -523,9 +1053,53 @@ export function createFramerAgentToolRuntime({
   let closed = false;
   let serial = Promise.resolve();
   let mutationCalls = 0;
+  let applyChangesCalls = 0;
+  let lowLevelWriteCalls = 0;
+  let imageSearchCalls = 0;
   let readCalls = 0;
+  let progressCalls = 0;
+  let toolCallCount = 0;
+  const toolCalls = [];
+  let repeatedFailureFingerprint = null;
+  let repeatedFailureCount = 0;
+  let repeatedFailureStops = 0;
+  let unsafeWriteFailures = 0;
+  let lowLevelWriteFailures = 0;
+  let lowLevelWriteDisabled = false;
+  let lowLevelWriteBlockedCalls = 0;
+  let instructionFallbacks = 0;
+  let instructionLookupUnavailable = false;
   let branchChange = null;
   let lastInspectionAt = null;
+  let lastMutationAt = null;
+  let screenshotCalls = 0;
+  let interactionVerificationCalls = 0;
+  let interactionVerification = {
+    completed: false,
+    verificationLevel: 'unverified',
+    checks: [],
+    behaviors: [],
+    verifiedAt: null,
+  };
+  const representativeVerifiedBehaviorIds = new Set();
+  const repeatedBehaviorVerificationFailures = new Map();
+  const mutationReceipts = [];
+  let screenshotBeforeMutation = false;
+  let lastScreenshotSequence = 0;
+  let taskPlan = null;
+  const verificationEvidence = new Map();
+  let guidanceMetadata = {
+    loaded: false,
+    contentHash: null,
+    projectContextHash: null,
+    files: [],
+    bytes: 0,
+  };
+  let promptMetadata = {
+    doctrineLoaded: false,
+    doctrineVersion: null,
+  };
+  const framerAgentVersion = installedFramerAgentVersion();
   let operationSequence = 0;
   let lastMutationSequence = 0;
   let lastInspectionSequence = 0;
@@ -553,6 +1127,7 @@ export function createFramerAgentToolRuntime({
 
   const ensureHostedSetup = async () => {
     if (env.DEXTER_HOSTED_FRAMER_AUTO_SETUP !== 'true') return;
+    if (hasInstalledFramerSkill(env)) return;
     if (!hostedSetupPromise) {
       reportActivity({
         kind: 'status_update',
@@ -578,7 +1153,7 @@ export function createFramerAgentToolRuntime({
     );
   };
 
-  const acquireProjectAuthorization = async ({ forceRefresh = false } = {}) => {
+  const resolveProjectAuthorization = async () => {
     if (typeof authorizeProject !== 'function') {
       throw toolError(
         'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
@@ -589,7 +1164,7 @@ export function createFramerAgentToolRuntime({
     let authorization = await authorizeProject({
       projectId,
       initiate: true,
-      forceRefresh,
+      forceRefresh: false,
       signal: abortController.signal,
     });
     if (authorization?.framerProjectId !== projectId) {
@@ -600,52 +1175,17 @@ export function createFramerAgentToolRuntime({
       );
     }
     if (authorization?.status === 'authorization_required') {
-      const url = authorizationUrl(authorization.authUrl);
       reportActivity({
         kind: 'status_update',
         source: 'framer-agent',
         message:
-          'Approve access to this Framer project in the browser. Dexter will continue automatically.',
+          'This Framer project needs a project API key before Dexter can continue.',
       });
-      try {
-        await openAuthorizationUrl(url);
-      } catch {
-        throw toolError(
-          'FRAMER_AGENT_AUTHORIZATION_OPEN_FAILED',
-          'Dexter could not open Framer authorization in the browser. Reconnect this project from Dexter settings.',
-          409,
-        );
-      }
-      const configuredExpiry = new Date(
-        String(authorization.expiresAt || ''),
-      ).getTime();
-      const deadline = Math.min(
-        Number.isFinite(configuredExpiry)
-          ? configuredExpiry
-          : Date.now() + authorizationTimeoutMs,
-        Date.now() + authorizationTimeoutMs,
+      throw toolError(
+        'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
+        'Connect this Framer project in Dexter by adding a project API key, then retry.',
+        409,
       );
-      while (
-        authorization?.status === 'authorization_required'
-        && Date.now() < deadline
-      ) {
-        await wait(
-          Math.max(
-            500,
-            Math.min(
-              5_000,
-              Number(authorization.pollIntervalMs) || AUTHORIZATION_POLL_MS,
-            ),
-          ),
-          abortController.signal,
-        );
-        authorization = await authorizeProject({
-          projectId,
-          initiate: false,
-          forceRefresh: false,
-          signal: abortController.signal,
-        });
-      }
     }
     const apiKey = String(authorization?.apiKey || '').trim();
     if (authorization?.status !== 'ready' || !apiKey) {
@@ -655,13 +1195,21 @@ export function createFramerAgentToolRuntime({
         409,
       );
     }
-    await executeCli(['project', 'auth', projectId, apiKey], {
+    const authorizedProjectUrl = normalizeProjectUrl(
+      authorization.framerProjectUrl,
+      projectId,
+    );
+    return { ...authorization, apiKey, framerProjectUrl: authorizedProjectUrl };
+  };
+
+  const installProjectAuthorization = async (authorization) => {
+    await executeCli(['project', 'auth', projectId, authorization.apiKey], {
       timeoutMs: 30_000,
     });
     reportActivity({
       kind: 'status_update',
       source: 'framer-agent',
-      message: 'This Framer project is authorized for the local harness.',
+      message: 'This Framer project is authorized for the coding harness.',
     });
   };
 
@@ -671,14 +1219,55 @@ export function createFramerAgentToolRuntime({
     });
   };
 
+  const reportRejectedAuthorization = async (authorization, error) => {
+    if (
+      typeof verifyProjectAuthorization !== 'function'
+      || !authorization?.credentialVersion
+    ) return;
+    await verifyProjectAuthorization({
+      status: 'rejected',
+      framerProjectId: projectId,
+      framerProjectUrl: projectUrl,
+      credentialVersion: authorization.credentialVersion,
+      errorCode: String(error?.code || 'FRAMER_AGENT_AUTHORIZATION_REJECTED')
+        .slice(0, 120),
+      signal: abortController.signal,
+    }).catch(() => undefined);
+  };
+
+  const verifyConnectedProject = async (activeSessionId, authorization) => {
+    const result = await executeCli(['exec', '-s', activeSessionId], {
+      input: [
+        'const [project, branch] = await Promise.all([',
+        '  framer.getProjectInfo(),',
+        '  framer.agent.getActiveBranch(),',
+        ']);',
+        'console.log(JSON.stringify({ projectName: project?.name ?? null, projectUrl: branch?.url ?? null }));',
+      ].join('\n'),
+      timeoutMs: 30_000,
+    });
+    const observed = parseStructuredOutput(result.stdout);
+    const observedProjectUrl = normalizeProjectUrl(
+      observed?.projectUrl,
+      projectId,
+    );
+    if (
+      typeof verifyProjectAuthorization === 'function'
+      && authorization?.credentialVersion
+    ) {
+      await verifyProjectAuthorization({
+        status: 'verified',
+        framerProjectId: projectId,
+        framerProjectUrl: observedProjectUrl,
+        credentialVersion: authorization.credentialVersion,
+        signal: abortController.signal,
+      });
+    }
+  };
+
   const ensureSession = async () => {
     await ensureHostedSetup();
     if (sessionId) return sessionId;
-    const cached = sessionsByProject.get(projectId);
-    if (cached) {
-      sessionId = cached;
-      return sessionId;
-    }
     if (sessionPromise) return sessionPromise;
     sessionPromise = (async () => {
       reportActivity({
@@ -686,23 +1275,49 @@ export function createFramerAgentToolRuntime({
         source: 'framer-agent',
         message: 'Connecting the coding harness to this Framer project.',
       });
-      if (!(await projectIsAuthorizedLocally())) {
-        await acquireProjectAuthorization();
+      let authorization = null;
+      if (typeof authorizeProject === 'function') {
+        authorization = await resolveProjectAuthorization();
+      }
+
+      const cached = sessionsByProject.get(sessionCacheKey);
+      if (
+        cached
+        && (
+          typeof authorizeProject !== 'function'
+          || (
+            authorization?.verificationStatus === 'verified'
+            && cached.credentialVersion === authorization.credentialVersion
+          )
+        )
+      ) {
+        sessionId = cached.sessionId;
+        return sessionId;
+      }
+      if (cached) {
+        await executeCli(['session', 'destroy', cached.sessionId], {
+          timeoutMs: 10_000,
+        }).catch(() => undefined);
+        sessionsByProject.delete(sessionCacheKey);
+      }
+      if (!authorization && !(await projectIsAuthorizedLocally())) {
+        throw toolError(
+          'FRAMER_AGENT_AUTHORIZATION_REQUIRED',
+          'This Framer project needs to be connected before Dexter can use it.',
+          409,
+        );
       }
       let created;
       try {
+        if (authorization) {
+          await installProjectAuthorization(authorization);
+        }
         created = await createSession();
       } catch (error) {
         if (isAuthorizationFailure(error)) {
-          await acquireProjectAuthorization({ forceRefresh: true });
-          try {
-            created = await createSession();
-          } catch (retryError) {
-            throw projectConnectionError(retryError);
-          }
-        } else {
-          throw projectConnectionError(error);
+          await reportRejectedAuthorization(authorization, error);
         }
+        throw projectConnectionError(error);
       }
       sessionId = sessionIdFromOutput(created.stdout);
       if (!sessionId) {
@@ -721,7 +1336,25 @@ export function createFramerAgentToolRuntime({
           503,
         );
       }
-      sessionsByProject.set(projectId, sessionId);
+      try {
+        await verifyConnectedProject(sessionId, authorization);
+      } catch (error) {
+        await executeCli(['session', 'destroy', sessionId], {
+          timeoutMs: 10_000,
+        }).catch(() => undefined);
+        sessionId = null;
+        if (
+          isAuthorizationFailure(error)
+          || error?.code === 'FRAMER_AGENT_PROJECT_MISMATCH'
+        ) {
+          await reportRejectedAuthorization(authorization, error);
+        }
+        throw projectConnectionError(error);
+      }
+      sessionsByProject.set(sessionCacheKey, {
+        sessionId,
+        credentialVersion: authorization?.credentialVersion || null,
+      });
       reportActivity({
         kind: 'status_update',
         source: 'framer-agent',
@@ -734,6 +1367,86 @@ export function createFramerAgentToolRuntime({
     return sessionPromise;
   };
 
+  const loadProjectGuidance = async () => {
+    await ensureSession();
+    const skillRoot = framerSkillRoot(env);
+    if (!skillRoot) return { content: '', ...guidanceMetadata };
+    const projectRoot = path.join(skillRoot, 'projects', projectId);
+    if (!fs.existsSync(projectRoot)) {
+      return { content: '', ...guidanceMetadata };
+    }
+    const requestedFiles = [
+      { root: skillRoot, path: 'SKILL.md', label: 'SKILL.md' },
+      { root: projectRoot, path: 'index.md', label: 'project/index.md' },
+      {
+        root: projectRoot,
+        path: 'project-inventory.md',
+        label: 'project/project-inventory.md',
+      },
+      { root: projectRoot, path: 'prompt/core-principles.md' },
+      { root: projectRoot, path: 'prompt/core-examples.md' },
+      { root: projectRoot, path: 'prompt/implementation-strategy.md' },
+      { root: projectRoot, path: 'prompt/updating-the-project.md' },
+      { root: projectRoot, path: 'prompt/tools.md' },
+      { root: projectRoot, path: 'prompt/overview.md' },
+      { root: projectRoot, path: 'prompt/guardrails.md' },
+      { root: projectRoot, path: 'prompt/critical-reminders.md' },
+      ...(visualVerificationRequired
+        ? [
+            { root: projectRoot, path: 'prompt/design-rules.md' },
+            { root: projectRoot, path: 'prompt/how-projects-work.md' },
+          ]
+        : []),
+    ];
+    const files = [];
+    let remainingBytes = MAX_GUIDANCE_BYTES;
+    for (const requestedFile of requestedFiles) {
+      const loaded = readGuidanceFile(
+        requestedFile.root,
+        requestedFile.path,
+        remainingBytes,
+      );
+      if (!loaded) continue;
+      files.push({
+        ...loaded,
+        path: requestedFile.label || requestedFile.path,
+      });
+      remainingBytes -= Buffer.byteLength(loaded.content, 'utf8');
+      if (remainingBytes <= 0) break;
+    }
+    const content = files
+      .map((file) => `## ${file.path}\n\n${file.content}`)
+      .join('\n\n');
+    const inventory = files.find(
+      (file) => file.path.endsWith('project-inventory.md'),
+    )?.content || '';
+    guidanceMetadata = {
+      loaded: Boolean(content),
+      contentHash: content
+        ? crypto.createHash('sha256').update(content).digest('hex')
+        : null,
+      projectContextHash: inventory
+        ? crypto.createHash('sha256').update(inventory).digest('hex')
+        : null,
+      files: files.map((file) => file.path),
+      bytes: Buffer.byteLength(content, 'utf8'),
+    };
+    return { content, ...guidanceMetadata };
+  };
+
+  const configurePromptContext = ({
+    doctrineLoaded = false,
+    doctrineVersion = null,
+  } = {}) => {
+    promptMetadata = {
+      doctrineLoaded: doctrineLoaded === true,
+      doctrineVersion:
+        typeof doctrineVersion === 'string' && doctrineVersion.trim()
+          ? doctrineVersion.trim().slice(0, 160)
+          : null,
+    };
+  };
+
   const execCode = async (code, { timeoutMs } = {}) => {
     let activeSessionId = await ensureSession();
     try {
@@ -750,7 +1463,7 @@ export function createFramerAgentToolRuntime({
       ) {
         throw error;
       }
-      sessionsByProject.delete(projectId);
+      sessionsByProject.delete(sessionCacheKey);
       sessionId = null;
       activeSessionId = await ensureSession();
       return executeCli(['exec', '-s', activeSessionId], {
@@ -816,7 +1529,9 @@ export function createFramerAgentToolRuntime({
   const normalizedResult = (result) => {
     const parsed = parseStructuredOutput(result.stdout);
     return {
-      ...(parsed === null ? { output: boundedText(result.stdout, 200_000) } : { result: parsed }),
+      ...(parsed === null
+        ? { output: boundedText(result.stdout, MAX_MODEL_RESULT_BYTES) }
+        : { result: boundedStructuredValue(parsed) }),
       ...(result.stderr.trim()
         ? { diagnostics: boundedText(result.stderr, 20_000) }
         : {}),
@@ -824,19 +1539,315 @@ export function createFramerAgentToolRuntime({
     };
   };
 
-  const markInspection = () => {
+  const markInspection = ({ visual = false, verifies = [] } = {}) => {
     operationSequence += 1;
     lastInspectionSequence = operationSequence;
     lastInspectionAt = new Date().toISOString();
+    verificationEvidence.set('structural', operationSequence);
+    if (visual) {
+      screenshotCalls += 1;
+      lastScreenshotSequence = operationSequence;
+      verificationEvidence.set('visual', operationSequence);
+      if (lastMutationSequence === 0) screenshotBeforeMutation = true;
+    }
+    for (const check of normalizeVerificationValues(
+      verifies,
+      GENERIC_VERIFICATION_CHECKS,
+    )) {
+      verificationEvidence.set(check, operationSequence);
+    }
   };
 
   const markMutation = () => {
     operationSequence += 1;
     lastMutationSequence = operationSequence;
+    lastMutationAt = new Date().toISOString();
   };
 
+  const requiredVerificationChecks = () =>
+    taskPlan?.verification || [];
+  const taskPlanSnapshot = () => {
+    if (!taskPlan) return null;
+    return {
+      summary: taskPlan.summary,
+      domains: [...taskPlan.domains],
+      verification: [...taskPlan.verification],
+      ...(taskPlan.behaviors.length > 0
+        ? {
+            behaviors: taskPlan.behaviors.map((behavior) => ({
+              ...behavior,
+              expectedContent: [...behavior.expectedContent],
+            })),
+            mechanisms: taskPlan.mechanisms.map((decision) => ({
+              ...decision,
+            })),
+            rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
+              ...entry,
+            })),
+            compatibility: taskPlan.compatibility.map((entry) => ({
+              ...entry,
+              requiredCapabilities: [...entry.requiredCapabilities],
+            })),
+          }
+        : {}),
+    };
+  };
   const synchronized = () =>
     mutationCalls === 0 || lastInspectionSequence > lastMutationSequence;
+  const verificationCheckCompleted = (check) => {
+    if (mutationCalls === 0) return true;
+    if (check === 'structural') return synchronized();
+    if (check === 'visual') {
+      return (
+        screenshotBeforeMutation
+        && lastScreenshotSequence > lastMutationSequence
+      );
+    }
+    return Number(verificationEvidence.get(check) || 0) > lastMutationSequence;
+  };
+  const visualVerificationRequired = () =>
+    applyChangesCalls > 0
+    || requiredVerificationChecks().includes('visual');
+  const visualVerificationCompleted = () =>
+    !visualVerificationRequired()
+    || mutationCalls === 0
+    || (
+      screenshotBeforeMutation
+      && lastScreenshotSequence > lastMutationSequence
+    );
+  const missingVerificationChecks = () => {
+    if (mutationCalls === 0) return [];
+    const missing = [];
+    if (!taskPlan) missing.push('task-plan');
+    const required = new Set([
+      'structural',
+      ...requiredVerificationChecks(),
+      ...(applyChangesCalls > 0 ? ['visual'] : []),
+    ]);
+    for (const check of required) {
+      if (!verificationCheckCompleted(check)) missing.push(check);
+    }
+    return missing;
+  };
+  const verification = () => ({
+    ownedBy: 'harness',
+    required: mutationCalls > 0,
+    completed: missingVerificationChecks().length === 0,
+    structuralCompleted: synchronized(),
+    visualRequired: visualVerificationRequired() && mutationCalls > 0,
+    visualCompleted: visualVerificationCompleted(),
+    screenshotCalls,
+    ...(requiredVerificationChecks().includes('interactions')
+      || interactionVerificationCalls > 0
+      ? {
+          interactionVerificationCalls,
+          interactionVerification: {
+            completed: verificationCheckCompleted('interactions'),
+            verificationLevel:
+              verificationCheckCompleted('interactions')
+                ? interactionVerification.verificationLevel
+                : 'unverified',
+            checks: interactionVerification.checks.map((check) => ({
+              ...check,
+              failures: [...check.failures],
+            })),
+            behaviors: interactionVerification.behaviors.map((behavior) => ({
+              ...behavior,
+              failures: [...behavior.failures],
+            })),
+            verifiedAt: interactionVerification.verifiedAt,
+          },
+        }
+      : {}),
+    taskPlan: taskPlanSnapshot(),
+    requiredChecks: [
+      ...new Set([
+        'structural',
+        ...requiredVerificationChecks(),
+        ...(applyChangesCalls > 0 ? ['visual'] : []),
+      ]),
+    ],
+    completedChecks: [
+      ...new Set([
+        'structural',
+        ...requiredVerificationChecks(),
+        ...(applyChangesCalls > 0 ? ['visual'] : []),
+      ]),
+    ].filter(verificationCheckCompleted),
+    missingChecks: missingVerificationChecks(),
+    lastMutationAt,
+    lastInspectionAt,
+  });
+
+  const inspectFinalState = async () => {
+    await serial;
+    return {
+      synchronized: synchronized(),
+      sourceHash: null,
+      changed: mutationCalls > 0,
+      mutationCalls,
+      readCalls,
+      branch: branchChange,
+      lastInspectionAt,
+      lastMutationAt,
+      taskPlan: taskPlanSnapshot(),
+      verification: verification(),
+    };
+  };
+
+  const finalizeCompletion = (completion) => {
+    if (
+      completion?.status !== 'completed'
+      || mutationCalls === 0
+      || verification().completed
+    ) {
+      return completion;
+    }
+    const missing = missingVerificationChecks().map((check) => {
+      if (check === 'task-plan') return 'a harness task and verification plan';
+      if (check === 'structural') return 'a final structural read';
+      if (check === 'visual') return 'before-and-after screenshot verification';
+      return `post-mutation ${check} verification`;
+    });
+    const reason =
+      `The harness ended before completing ${missing.join(' and ')}.`;
+    return {
+      ...completion,
+      status: 'failed',
+      summary: `${String(completion?.summary || '').trim()} ${reason}`.trim(),
+      checks: [
+        ...(Array.isArray(completion?.checks) ? completion.checks : []),
+        {
+          command: 'Harness-owned final verification',
+          status: 'failed',
+          output: reason,
+        },
+      ],
+      blockedReason: null,
+    };
+  };
+
+  const verificationRepairPrompt = () => {
+    const current = verification();
+    if (current.completed || mutationCalls === 0) return null;
+    const missing = [];
+    for (const check of current.missingChecks || []) {
+      if (check === 'task-plan') {
+        missing.push(
+          'declare the task domains and verification plan with framer_plan_task',
+        );
+      } else if (check === 'structural') {
+        missing.push('perform a focused live read after the latest mutation');
+      } else if (check === 'visual') {
+        missing.push(
+          screenshotBeforeMutation
+            ? 'capture and inspect the affected canvas after the latest mutation'
+            : 'report that the required baseline screenshot was missed; do not claim visual verification',
+        );
+      } else {
+        missing.push(
+          check === 'interactions'
+            ? 'call framer_verify_interactions with canonical evidence node IDs for every declared behavior and chosen mechanism'
+            : `perform a focused read tagged with verifies:["${check}"] after the latest mutation`,
+        );
+      }
+    }
+    return [
+      'Continue the same Framer task from its current project state.',
+      'Do not redo successful work.',
+      `Before returning, ${missing.join(' and ')}.`,
+      'Repair only concrete problems you observe, then return the required JSON outcome.',
+    ].join(' ');
+  };
+
+  const builtInInstructions = (documentationUnavailable = false) => ({
+    stdout: JSON.stringify({
+      source: documentationUnavailable
+        ? 'built-in-fallback'
+        : 'built-in',
+      guidance: [
+        'Use framer_read with framer.agent.getNode({ id }) or getNodes({ ids }) for node inspection.',
+        'Use framer_read_project for supported project queries such as screenshots.',
+        'Use framer_query_images for approved stock imagery only after checking user attachments and suitable existing project images.',
+        'Use framer_apply_changes for layout and styling. Read its diagnostics, verify the result, and repair concrete issues.',
+        'If framer_write is rejected as unsafe, do not retry JavaScript variants. Switch to framer_apply_changes or report the concrete blocker.',
+        'Batch related work when practical, reuse evidence already collected, and stop when the requested outcome is satisfied.',
+      ],
+      documentationUnavailable,
+    }),
+    stderr: '',
+  });
+
+  const reserveToolCall = (name, category) => {
+    toolCallCount += 1;
+    if (category === 'progress') progressCalls += 1;
+    if (category === 'read') readCalls += 1;
+    const call = {
+      sequence: toolCallCount,
+      name,
+      category,
+      status: 'failed',
+      durationMs: 0,
+    };
+    toolCalls.push(call);
+    return call;
+  };
+
+  const callFingerprint = (name, rawArguments) =>
+    crypto
+      .createHash('sha256')
+      .update(`${name}\n${JSON.stringify(rawArguments)}`)
+      .digest('hex');
+
+  const requireTaskPlanForMutation = ({ canvas = false } = {}) => {
+    if (!taskPlan) {
+      throw toolError(
+        'FRAMER_HARNESS_PLAN_REQUIRED',
+        'Inspect the live Framer target, then call framer_plan_task before making a mutation.',
+      );
+    }
+    if (
+      (canvas || taskPlan.verification.includes('visual'))
+      && !screenshotBeforeMutation
+    ) {
+      throw toolError(
+        'FRAMER_HARNESS_BASELINE_SCREENSHOT_REQUIRED',
+        'Capture and inspect a screenshot of the affected canvas before the first visual mutation.',
+      );
+    }
+    const rejectedSelectedMechanisms = taskPlan.behaviors.filter((behavior) => {
+      const selected = taskPlan.mechanisms.find((decision) =>
+        decision.behaviorId === behavior.id);
+      return selected && taskPlan.rejectedMechanisms.some((rejected) =>
+        rejected.mechanism === selected.mechanism
+        && (
+          rejected.behaviorId === behavior.id
+          || rejected.behaviorSignature === behavior.signature
+        ));
+    });
+    if (rejectedSelectedMechanisms.length > 0) {
+      throw toolError(
+        'FRAMER_BEHAVIOR_MECHANISM_REPLAN_REQUIRED',
+        `Choose a different mechanism for ${rejectedSelectedMechanisms.map((behavior) => behavior.id).join(', ')} before making another mutation.`,
+      );
+    }
+    if (mutationCalls > 0) {
+      const pendingRepresentative = taskPlan.behaviors
+        .filter((behavior) => behavior.expectedTargets > 1)
+        .filter((behavior) =>
+          taskPlan.mechanisms.find((decision) =>
+            decision.behaviorId === behavior.id
+            && decision.representativeFirst))
+        .filter((behavior) =>
+          !representativeVerifiedBehaviorIds.has(behavior.id));
+      if (pendingRepresentative.length > 0) {
+        throw toolError(
+          'FRAMER_BEHAVIOR_REPRESENTATIVE_VERIFICATION_REQUIRED',
+          `Verify one representative implementation for ${pendingRepresentative.map((behavior) => behavior.id).join(', ')} before batching further mutations.`,
+        );
+      }
+    }
+  };
 
   async function invokeUnsafe(name, rawArguments = {}) {
     if (closed) {
@@ -857,6 +1868,25 @@ export function createFramerAgentToolRuntime({
         'Framer Agent tool arguments must be an object.',
       );
     }
+    const mutation =
+      name === 'framer_apply_changes' || name === 'framer_write';
+    const category =
+      name === 'framer_plan_task'
+        ? 'plan'
+        : mutation
+          ? 'mutation'
+          : 'read';
+    const fingerprint = callFingerprint(name, rawArguments);
+    if (
+      repeatedFailureFingerprint === fingerprint
+      && repeatedFailureCount >= 5
+    ) {
+      repeatedFailureStops += 1;
+      throw toolError(
+        'FRAMER_AGENT_REPEATED_CALL_LOOP',
+        'The same Framer tool call has failed five times in a row. Change the approach or report the concrete blocker.',
+      );
+    }
     if (name === 'progress_update') {
       const message = String(rawArguments.message || '').trim().slice(0, 500);
       if (!message) {
@@ -865,15 +1895,20 @@ export function createFramerAgentToolRuntime({
           'A progress message is required.',
         );
       }
+      const toolCall = reserveToolCall(name, 'progress');
       reportActivity({
         kind: 'status_update',
         source: 'harness',
         message,
       });
+      repeatedFailureFingerprint = null;
+      repeatedFailureCount = 0;
+      toolCall.status = 'succeeded';
       return { acknowledged: true };
     }
 
     const startedAt = Date.now();
+    const toolCall = reserveToolCall(name, category);
     reportActivity({
       kind: 'tool_active',
       source: 'framer-agent',
@@ -882,17 +1917,48 @@ export function createFramerAgentToolRuntime({
       message:
         name === 'framer_apply_changes' || name === 'framer_write'
           ? 'Updating the Framer project'
+          : name === 'framer_plan_task'
+            ? 'Planning the Framer work and verification'
           : 'Inspecting the Framer project',
     });
     try {
       let result;
-      if (name === 'framer_instructions') {
-        readCalls += 1;
-        result = await execCode(
-          'console.log(await framer.agent.getSystemPrompt())',
+      if (name === 'framer_write' && lowLevelWriteDisabled) {
+        lowLevelWriteBlockedCalls += 1;
+        throw toolError(
+          'FRAMER_AGENT_WRITE_FALLBACK_REQUIRED',
+          'Low-level JavaScript writes are disabled for this run after repeated safety rejections. Use framer_apply_changes, inspect the project, or report the concrete blocker.',
         );
+      } else if (name === 'framer_instructions') {
+        const queries = Array.isArray(rawArguments.queries)
+          ? uniqueStrings(rawArguments.queries, 8)
+          : [];
+        if (queries.length > 0 && !instructionLookupUnavailable) {
+          try {
+            result = await executeCli(
+              ['docs', ...queries],
+              { timeoutMs: 30_000 },
+            );
+          } catch (error) {
+            instructionFallbacks += 1;
+            instructionLookupUnavailable = true;
+            trace?.warn?.('framer_agent_docs_fallback', {
+              code: error?.code,
+              message: error?.message,
+            });
+            reportActivity({
+              kind: 'status_update',
+              source: 'framer-agent',
+              message:
+                'Targeted Framer documentation is unavailable, so I am continuing with the built-in harness guidance.',
+            });
+            result = builtInInstructions(true);
+          }
+        } else {
+          if (queries.length > 0) instructionFallbacks += 1;
+          result = builtInInstructions(queries.length > 0);
+        }
       } else if (name === 'framer_context') {
-        readCalls += 1;
         result = await execCode(
           [
             'const [context, branch] = await Promise.all([',
@@ -903,8 +1969,210 @@ export function createFramerAgentToolRuntime({
           ].join('\n'),
         );
         markInspection();
+      } else if (name === 'framer_plan_task') {
+        if (lastInspectionSequence === 0) {
+          throw toolError(
+            'FRAMER_HARNESS_INSPECTION_REQUIRED',
+            'Inspect the live Framer target before declaring the task and verification plan.',
+          );
+        }
+        const nextPlan = normalizeTaskPlan(
+          rawArguments,
+          inheritedRejectedMechanisms,
+        );
+        if (
+          mutationCalls > 0
+          && nextPlan.verification.includes('visual')
+          && !screenshotBeforeMutation
+        ) {
+          throw toolError(
+            'FRAMER_HARNESS_BASELINE_SCREENSHOT_REQUIRED',
+            'Visual verification cannot be added after mutations when no baseline screenshot was captured.',
+          );
+        }
+        const previousMechanisms = new Map(
+          (taskPlan?.mechanisms || []).map((decision) => [
+            decision.behaviorId,
+            decision.mechanism,
+          ]),
+        );
+        const behaviorPlan = mergeBehaviorPlans(taskPlan, nextPlan);
+        taskPlan = {
+          summary: nextPlan.summary,
+          domains: uniqueStrings([
+            ...(taskPlan?.domains || []),
+            ...nextPlan.domains,
+          ]),
+          verification: uniqueStrings([
+            ...(taskPlan?.verification || []),
+            ...nextPlan.verification,
+          ]),
+          ...behaviorPlan,
+        };
+        for (const decision of taskPlan.mechanisms) {
+          const prior = previousMechanisms.get(decision.behaviorId);
+          if (prior && prior !== decision.mechanism) {
+            representativeVerifiedBehaviorIds.delete(decision.behaviorId);
+          }
+        }
+        result = {
+          stdout: JSON.stringify({
+            plan: {
+              summary: taskPlan.summary,
+              domains: [...taskPlan.domains],
+              verification: [...taskPlan.verification],
+              behaviors: taskPlan.behaviors.map((behavior) => ({
+                ...behavior,
+                expectedContent: [...behavior.expectedContent],
+              })),
+              mechanisms: taskPlan.mechanisms.map((decision) => ({
+                ...decision,
+              })),
+              compatibility: taskPlan.compatibility.map((entry) => ({
+                ...entry,
+                requiredCapabilities: [...entry.requiredCapabilities],
+              })),
+              rejectedMechanisms: taskPlan.rejectedMechanisms.map((entry) => ({
+                ...entry,
+              })),
+            },
+            instruction:
+              'Implement one representative first when required, verify it, then complete coverage and gather every derived verification result after the final mutation.',
+          }),
+          stderr: '',
+        };
+      } else if (name === 'framer_verify_interactions') {
+        if (mutationCalls === 0) {
+          throw toolError(
+            'FRAMER_HARNESS_INTERACTION_MUTATION_REQUIRED',
+            'Verify interactions only after the relevant Framer mutation has succeeded.',
+          );
+        }
+        if (!taskPlan?.behaviors?.length) {
+          throw toolError(
+            'FRAMER_BEHAVIOR_CONTRACT_REQUIRED',
+            'Declare observable behaviors and compatible mechanisms with framer_plan_task before interaction verification.',
+          );
+        }
+        const checks = normalizeBehaviorEvidence(
+          rawArguments.checks,
+          taskPlan,
+        );
+        const pagePath = normalizePagePath(rawArguments.pagePath);
+        const requestedIds = evidenceNodeIds(checks);
+        const liveResult = await execCode(
+          [
+            `const requestedIds = ${JSON.stringify(requestedIds)};`,
+            'const nodes = await Promise.all(requestedIds.map(async (id) => ({',
+            '  id,',
+            '  node: await framer.agent.serialize({ id, depth: 8 },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).catch(() => null),`,
+            '  parentId: await framer.agent.getParentNode({ id },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).then((node) => node?.id ?? null).catch(() => null),`,
+            '  ancestorIds: await framer.agent.getAncestors({ id },',
+            `    { pagePath: ${JSON.stringify(pagePath)} }).then((nodes) => Array.isArray(nodes) ? nodes.map((node) => node?.id).filter(Boolean) : []).catch(() => []),`,
+            '})));',
+            'console.log(JSON.stringify({ nodes }, null, 2));',
+          ].join('\n'),
+        );
+        const parsed = parseStructuredOutput(liveResult.stdout);
+        const nodesById = new Map(
+          (Array.isArray(parsed?.nodes) ? parsed.nodes : [])
+            .filter((entry) => isRecord(entry) && typeof entry.id === 'string')
+            .map((entry) => [entry.id, {
+              node: entry.node || null,
+              parentId:
+                typeof entry.parentId === 'string'
+                  ? entry.parentId
+                  : null,
+              ancestorIds: Array.isArray(entry.ancestorIds)
+                ? entry.ancestorIds
+                : [],
+            }]),
+        );
+        const verified = verifyBehaviorEvidence({
+          plan: taskPlan,
+          checks,
+          snapshots: nodesById,
+          context: {
+            lowLevelWriteCalls,
+            authorizedInstanceContainerIds,
+          },
+        });
+        markInspection();
+        interactionVerificationCalls += 1;
+        interactionVerification = {
+          ...verified,
+          verifiedAt: new Date().toISOString(),
+        };
+        for (const behaviorResult of verified.behaviors) {
+          const failedChecks = verified.checks.filter((check) =>
+            check.behaviorId === behaviorResult.behaviorId && !check.passed);
+          if (failedChecks.length === 0) {
+            repeatedBehaviorVerificationFailures.delete(
+              behaviorResult.behaviorId,
+            );
+            continue;
+          }
+          const failureFingerprint = crypto
+            .createHash('sha256')
+            .update(JSON.stringify({
+              mechanism: behaviorResult.mechanism,
+              failures: failedChecks
+                .flatMap((check) => check.failures)
+                .sort(),
+            }))
+            .digest('hex');
+          const prior = repeatedBehaviorVerificationFailures.get(
+            behaviorResult.behaviorId,
+          );
+          const count =
+            prior?.fingerprint === failureFingerprint
+              ? prior.count + 1
+              : 1;
+          repeatedBehaviorVerificationFailures.set(
+            behaviorResult.behaviorId,
+            { fingerprint: failureFingerprint, count },
+          );
+          if (count < 2 || !behaviorResult.mechanism) continue;
+          const alreadyRejected = taskPlan.rejectedMechanisms.some((rejected) =>
+            rejected.mechanism === behaviorResult.mechanism
+            && (
+              rejected.behaviorId === behaviorResult.behaviorId
+              || rejected.behaviorSignature
+                === behaviorResult.behaviorSignature
+            ));
+          if (alreadyRejected) continue;
+          taskPlan = {
+            ...taskPlan,
+            rejectedMechanisms: [
+              ...taskPlan.rejectedMechanisms,
+              {
+                behaviorId: behaviorResult.behaviorId,
+                behaviorSignature: behaviorResult.behaviorSignature,
+                mechanism: behaviorResult.mechanism,
+                reason:
+                  `Repeated structural verification failed: ${failedChecks
+                    .flatMap((check) => check.failures)
+                    .join('; ')
+                    .slice(0, 700)}`,
+                source: 'verification_failure',
+              },
+            ],
+          };
+        }
+        verified.representativeBehaviorIds.forEach((behaviorId) =>
+          representativeVerifiedBehaviorIds.add(behaviorId));
+        if (interactionVerification.completed) {
+          verificationEvidence.set('interactions', operationSequence);
+        } else {
+          verificationEvidence.delete('interactions');
+        }
+        result = {
+          stdout: JSON.stringify(interactionVerification),
+          stderr: liveResult.stderr,
+        };
       } else if (name === 'framer_read_project') {
-        readCalls += 1;
         const queries = Array.isArray(rawArguments.queries)
           ? rawArguments.queries.slice(0, 50)
           : [];
@@ -921,7 +2189,41 @@ export function createFramerAgentToolRuntime({
             'console.log(JSON.stringify(result, null, 2));',
           ].join('\n'),
         );
-        markInspection();
+        markInspection({
+          visual: queries.some((query) => query.type === 'screenshot'),
+          verifies: rawArguments.verifies,
+        });
+      } else if (name === 'framer_query_images') {
+        const query = String(rawArguments.query || '').trim();
+        if (query.length < 2) {
+          throw toolError(
+            'FRAMER_AGENT_IMAGE_QUERY_INVALID',
+            'A specific image-search query is required.',
+          );
+        }
+        const count = Math.max(
+          1,
+          Math.min(8, Math.floor(Number(rawArguments.count) || 4)),
+        );
+        const orientation = ['landscape', 'portrait', 'squarish']
+          .includes(rawArguments.orientation)
+          ? rawArguments.orientation
+          : undefined;
+        result = await execCode(
+          [
+            'const result = await framer.agent.queryImages({',
+            '  source: "unsplash",',
+            `  query: ${JSON.stringify(query)},`,
+            `  count: ${count},`,
+            ...(orientation
+              ? [`  orientation: ${JSON.stringify(orientation)},`]
+              : []),
+            '});',
+            'console.log(JSON.stringify(result, null, 2));',
+          ].join('\n'),
+          { timeoutMs: 30_000 },
+        );
+        imageSearchCalls += 1;
       } else if (name === 'framer_apply_changes') {
         const changes = String(rawArguments.changes || '').trim();
         if (!changes) {
@@ -930,6 +2232,7 @@ export function createFramerAgentToolRuntime({
             'Framer Agent changes are required.',
           );
         }
+        requireTaskPlanForMutation({ canvas: true });
         const pagePath = normalizePagePath(rawArguments.pagePath);
         result = await execCode(
           [
@@ -938,31 +2241,58 @@ export function createFramerAgentToolRuntime({
           ].join('\n'),
         );
         mutationCalls += 1;
+        applyChangesCalls += 1;
         markMutation();
+        const parsedResult = parseStructuredOutput(result.stdout);
+        mutationReceipts.push({
+          sequence: operationSequence,
+          kind: 'framer_apply_changes',
+          pagePath,
+          ...summarizeFramerChanges(changes),
+          renamedIds: canonicalIdMappings(parsedResult),
+        });
       } else if (name === 'framer_read') {
-        readCalls += 1;
         result = await execCode(
           validateCode(rawArguments.code, {
             write: false,
             allowPublishing,
           }),
         );
-        markInspection();
+        markInspection({ verifies: rawArguments.verifies });
       } else if (name === 'framer_write') {
-        result = await execCode(
-          validateCode(rawArguments.code, {
-            write: true,
-            allowPublishing,
-          }),
-        );
+        const code = validateCode(rawArguments.code, {
+          write: true,
+          allowPublishing,
+        });
+        const reason = String(rawArguments.reason || '').trim();
+        if (reason.length < 10) {
+          throw toolError(
+            'FRAMER_AGENT_WRITE_REASON_REQUIRED',
+            'Explain why this operation cannot be completed with framer_apply_changes before using framer_write.',
+          );
+        }
+        requireTaskPlanForMutation();
+        result = await execCode(code);
         mutationCalls += 1;
+        lowLevelWriteCalls += 1;
         markMutation();
+        mutationReceipts.push({
+          sequence: operationSequence,
+          kind: 'framer_write',
+          reason: reason.slice(0, 500),
+          codeHash: crypto.createHash('sha256').update(code).digest('hex'),
+        });
       } else {
         throw toolError(
           'FRAMER_AGENT_TOOL_UNKNOWN',
           `Unknown Framer Agent tool: ${name}`,
         );
       }
+      const durationMs = Date.now() - startedAt;
+      repeatedFailureFingerprint = null;
+      repeatedFailureCount = 0;
+      toolCall.status = 'succeeded';
+      toolCall.durationMs = durationMs;
       reportActivity({
         kind: 'tool_active',
         source: 'framer-agent',
@@ -972,10 +2302,54 @@ export function createFramerAgentToolRuntime({
           name === 'framer_apply_changes' || name === 'framer_write'
             ? 'Updated the Framer project'
             : 'Finished inspecting the Framer project',
-        durationMs: Date.now() - startedAt,
+        durationMs,
       });
       return normalizedResult(result);
     } catch (error) {
+      if (
+        name === 'framer_write'
+        && error?.code === 'FRAMER_AGENT_CODE_UNSAFE'
+      ) {
+        unsafeWriteFailures += 1;
+        if (
+          !lowLevelWriteDisabled
+          && unsafeWriteFailures >= MAX_UNSAFE_WRITE_FAILURES
+        ) {
+          lowLevelWriteDisabled = true;
+          reportActivity({
+            kind: 'status_update',
+            source: 'framer-agent',
+            message:
+              'Repeated low-level writes were rejected by the safety boundary, so I switched the run to the safer Framer change path.',
+          });
+        }
+      }
+      if (
+        name === 'framer_write'
+        && error?.code === 'FRAMER_AGENT_COMMAND_FAILED'
+      ) {
+        lowLevelWriteFailures += 1;
+        if (
+          !lowLevelWriteDisabled
+          && lowLevelWriteFailures >= MAX_LOW_LEVEL_WRITE_FAILURES
+        ) {
+          lowLevelWriteDisabled = true;
+          reportActivity({
+            kind: 'status_update',
+            source: 'framer-agent',
+            message:
+              'Repeated low-level Framer writes failed, so I switched the run back to semantic Framer changes and focused inspection.',
+          });
+        }
+      }
+      if (repeatedFailureFingerprint === fingerprint) {
+        repeatedFailureCount += 1;
+      } else {
+        repeatedFailureFingerprint = fingerprint;
+        repeatedFailureCount = 1;
+      }
+      toolCall.durationMs = Date.now() - startedAt;
+      toolCall.errorCode = error?.code || 'FRAMER_AGENT_TOOL_FAILED';
       trace?.warn?.('framer_agent_tool_failed', {
         name,
         code: error?.code,
@@ -1061,31 +2435,96 @@ export function createFramerAgentToolRuntime({
     definitions,
     toolNames: definitions.map((definition) => definition.name),
     preflight: validateAuthoritativeNodeIds,
+    loadProjectGuidance,
+    configurePromptContext,
     invoke,
     startGateway,
-    synchronize: async () => ({
-      synchronized: synchronized(),
-      sourceHash: null,
-      changed: mutationCalls > 0,
-    }),
-    inspect: async () => ({
-      synchronized: synchronized(),
-      sourceHash: null,
-      changed: mutationCalls > 0,
-      mutationCalls,
-      readCalls,
-      branch: branchChange,
-      lastInspectionAt,
-    }),
+    synchronize: inspectFinalState,
+    inspect: inspectFinalState,
+    finalizeCompletion,
+    verificationRepairPrompt,
     sourceHash: () => null,
     hasPendingChanges: () => false,
     directWorkspace: true,
     summary: () => ({
       projectId,
+      projectUrl,
       mutationCalls,
+      applyChangesCalls,
+      lowLevelWriteCalls,
+      imageSearchCalls,
+      interactionVerificationCalls,
+      mutationReceipts: mutationReceipts.map((receipt) => ({
+        ...receipt,
+        ...(Array.isArray(receipt.commands)
+          ? {
+              commands: receipt.commands.map((command) => ({
+                ...command,
+                ...(Array.isArray(command.eventActions)
+                  ? {
+                      eventActions: command.eventActions.map((action) => ({
+                        ...action,
+                      })),
+                    }
+                  : {}),
+              })),
+            }
+          : {}),
+        ...(receipt.renamedIds
+          ? { renamedIds: { ...receipt.renamedIds } }
+          : {}),
+      })),
       readCalls,
+      progressCalls,
+      toolCallCount,
+      toolDurationMs: toolCalls.reduce(
+        (total, call) => total + call.durationMs,
+        0,
+      ),
+      toolCalls: toolCalls.map((call) => ({ ...call })),
+      workingPreferences: {
+        focus: workingPreferences.mode,
+        writeScope: workingPreferences.writeScope,
+        preferBatchedMutations:
+          workingPreferences.preferBatchedMutations,
+        avoidRepeatedInspection:
+          workingPreferences.avoidRepeatedInspection,
+        expandScopeOnlyWhenNeeded:
+          workingPreferences.expandScopeOnlyWhenNeeded,
+      },
+      loopProtection: {
+        identicalFailureLimit: 5,
+        blockedCalls: repeatedFailureStops,
+        unsafeWriteFailureLimit: MAX_UNSAFE_WRITE_FAILURES,
+        unsafeWriteFailures,
+        lowLevelWriteFailureLimit: MAX_LOW_LEVEL_WRITE_FAILURES,
+        lowLevelWriteFailures,
+        lowLevelWriteDisabled,
+        lowLevelWriteBlockedCalls,
+        instructionFallbacks,
+      },
       branch: branchChange,
       lastInspectionAt,
+      lastMutationAt,
+      taskPlan: taskPlanSnapshot(),
+      verification: verification(),
+      framerAgentVersion,
+      framerGuidanceLoaded: guidanceMetadata.loaded,
+      doctrineLoaded: promptMetadata.doctrineLoaded,
+      guidanceHash: guidanceMetadata.contentHash,
+      projectContextHash: guidanceMetadata.projectContextHash,
+      visualVerificationRequired:
+        verification().visualRequired,
+      visualVerificationCompleted:
+        verification().visualCompleted,
+      guidance: {
+        loaded: guidanceMetadata.loaded,
+        contentHash: guidanceMetadata.contentHash,
+        projectContextHash: guidanceMetadata.projectContextHash,
+        files: [...guidanceMetadata.files],
+        bytes: guidanceMetadata.bytes,
+      },
+      doctrine: { ...promptMetadata },
     }),
     fatalInfrastructureError: () => null,
     waitForFatalInfrastructure: () => new Promise(() => undefined),