@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/node_modules/playwright/lib/mcp/skyramp/traceRecordingBackend.js

@@ -55,6 +55,11 @@ var import_resultCode = require("./resultCode");
 var import_mouseActionTool = require("./mouseActionTool");
 var import_visualSnapshotTool = require("./visualSnapshotTool");
 var import_gojsTool = require("./gojsTool");
+var import_dataSafetyGuard = require("./dataSafetyGuard");
+var import_dataSafetySession = require("./dataSafetySession");
+var import_finishTestSetupTool = require("./finishTestSetupTool");
+var import_recordingPhase = require("./recordingPhase");
+var import_mouseActions = require("./common/mouseActions");
 var import_cssValue = require("./common/cssValue");
 var import_visualSnapshot = require("./common/visualSnapshot");
 var import_snapshotLocators = require("./snapshotLocators");
@@ -63,6 +68,7 @@ var import_tableSelectorBuilder = require("./tableSelectorBuilder");
 var import_types = require("./types");
 var import_dynamicId = require("../../dom-analyzer/dynamicId");
 const traceDebug = (0, import_utilsBundle.debug)("pw:mcp:trace");
+const PASSIVE_TOOLS = /* @__PURE__ */ new Set(["browser_snapshot", "browser_wait_for", "browser_take_screenshot", "browser_console_messages", "browser_network_requests"]);
 function selectorIdentity(s) {
   if (!s)
     return null;
@@ -89,11 +95,11 @@ const REF_RESOLVE_TIMEOUT_MS = 1e3;
 const MAX_ANCESTOR_HOVERS = 8;
 const ANCESTOR_WALK_BUDGET_MS = 1e4;
 class TraceRecordingBackend {
-  // per-type baseline filename counter
   constructor(options) {
     // The attribute getByTestId() resolves against (configured or the default).
     this._testIdAttribute = "data-testid";
     this._trackedActions = [];
+    this._recordingPhase = new import_recordingPhase.RecordingPhaseState();
     this._droppedActions = [];
     this._initialized = false;
     this._pageCount = 0;
@@ -105,10 +111,48 @@ class TraceRecordingBackend {
     this._reloading = false;
     // true while page.reload() is in progress — suppresses spurious popup tracking
     this._visualSnapshotCounters = { page: 0, element: 0, region: 0, gojsDiagram: 0 };
+    this._dataSafetyReady = false;
+    // Action ids of passive tool calls (see PASSIVE_TOOLS) in this recording:
+    // a create that started during one came from the app on its own.
+    this._passiveActionIds = /* @__PURE__ */ new Set();
     this._options = options || {};
     this._outputDir = options?.outputDir || process.cwd();
     this._tempDir = import_fs.default.mkdtempSync(import_path.default.join(import_os.default.tmpdir(), "skyramp-trace-"));
     this._harPath = import_path.default.join(this._tempDir, "skyramp_network.har");
+    const dataSafety = (0, import_dataSafetyGuard.parseDataSafetyConfig)(this._options.dataSafety, process.env.SKYRAMP_DATA_SAFETY);
+    const ledgerDir = dataSafety.ledgerDir;
+    let ledgerSeq = 0;
+    const nextLedgerPath = ledgerDir ? () => import_path.default.join(ledgerDir, `dataSafetyLedger-${process.pid}-${Date.now()}-${ledgerSeq++}.json`) : void 0;
+    this._guard = new import_dataSafetyGuard.DataSafetyGuard(
+      dataSafety,
+      nextLedgerPath ? nextLedgerPath() : import_path.default.join(this._tempDir, "dataSafetyLedger.json"),
+      () => this._recordingPhase.setupCompleted,
+      nextLedgerPath
+    );
+    this._session = new import_dataSafetySession.DataSafetySession(this._guard, () => this._recordingPhase.requestProvenance());
+  }
+  /**
+   * An unusable data-safety config part, or a ledger that cannot be
+   * written, fails every tool call: recording without it would be looser
+   * than the caller asked for, and a ledgerDir caller has no other record.
+   * Checked on the first call (no I/O in the constructor) and again until
+   * it passes, and again after any ledger write fails mid-session: the
+   * check rewrites the full in-memory ledger, so recovery loses nothing.
+   */
+  _checkDataSafetyStartup() {
+    if (this._dataSafetyReady && !this._guard.persistFailed)
+      return void 0;
+    if (!this._session.active && !this._guard.config.startupError) {
+      this._dataSafetyReady = true;
+      return void 0;
+    }
+    try {
+      this._guard.ensureLedgerWritable();
+      this._dataSafetyReady = true;
+      return void 0;
+    } catch (e) {
+      return e instanceof Error ? e.message : String(e);
+    }
   }
   get trackedActions() {
     return this._trackedActions;
@@ -175,6 +219,8 @@ class TraceRecordingBackend {
       channel: config.browser.launchOptions?.channel
     });
     this._browserBackend.context.onBrowserContextCreated = async (browserContext) => {
+      (0, import_dataSafetySession.assertNoNetworkPolicyCollision)(config.network, this._session.active);
+      await this._session.install(browserContext);
       this._installPopupListener(browserContext);
       const ctx = this._browserBackend.context;
       if (ctx && !ctx.sessionLog) {
@@ -198,40 +244,156 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertHiddenTool.assertHiddenMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)(), (0, import_tableAssertTool.tableAssertMcpTool)(), (0, import_visualSnapshotTool.visualSnapshotMcpTool)(), (0, import_gojsTool.gojsAddNodeMcpTool)(), (0, import_gojsTool.gojsLinkMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_finishTestSetupTool.finishTestSetupMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertHiddenTool.assertHiddenMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)(), (0, import_tableAssertTool.tableAssertMcpTool)(), (0, import_visualSnapshotTool.visualSnapshotMcpTool)(), (0, import_gojsTool.gojsAddNodeMcpTool)(), (0, import_gojsTool.gojsLinkMcpTool)()];
   }
+  /**
+   * Thin wrapper around _callToolInner so every tool call — not just
+   * the browser-tool common path — gets any pending data-safety block notice
+   * appended to ITS OWN result. Several browser-interaction tools return early
+   * from deep inside _callToolInner (browser_select_option and its combobox
+   * fallback, the browser_fill_form→select retry, the same-URL navigate→reload
+   * branch) and can each trigger network requests the guard blocks; draining
+   * notices here — once, after every call resolves — ensures a block is always
+   * attributed to the call that caused it, never delayed onto a later,
+   * unrelated tool result or dropped if no later call ever runs. Applies even
+   * when isError is true: a blocked navigation routinely surfaces as an error
+   * result, and that's exactly the case the notice needs to explain.
+   *
+   * _callToolInner can also THROW (e.g. exportZipSchema.inputSchema.parse
+   * on bad args) instead of returning a CallToolResult — without a catch here
+   * that path skipped consumeBlockNotices() entirely, leaving the pending
+   * notice to be silently re-attributed to whatever call happened to succeed
+   * next (or dropped if none ever did). The catch drains notices for the
+   * throwing call too and folds them into a synthesized error result;
+   * re-throws untouched when there's nothing to attribute.
+   */
   async callTool(name, args, progress) {
+    try {
+      const result = await this._callToolInner(name, args, progress);
+      const notice = this._guard.consumeBlockNotices();
+      if (notice)
+        result.content = [...result.content ?? [], { type: "text", text: notice }];
+      return result;
+    } catch (e) {
+      const notice = this._guard.consumeBlockNotices();
+      if (notice)
+        return { content: [{ type: "text", text: `### Error
+${String(e)}${notice}` }], isError: true };
+      throw e;
+    }
+  }
+  async _callToolInner(name, args, progress) {
     if (!this._initialized)
       return { content: [{ type: "text", text: "### Error\nBackend not initialized. Call initialize() first." }], isError: true };
+    const dataSafetyError = this._checkDataSafetyStartup();
+    if (dataSafetyError)
+      return { content: [{ type: "text", text: `### Error
+${dataSafetyError}
+No browser action was run.` }], isError: true };
+    if (name === import_finishTestSetupTool.finishTestSetupSchema.name) {
+      import_finishTestSetupTool.finishTestSetupSchema.inputSchema.parse(args || {});
+      if (!this._recordingPhase.setupCompleted && this._guard.teardownStarted) {
+        return {
+          content: [{ type: "text", text: "### Error\nskyramp_finish_test_setup must be called before the scenario steps. Data safety teardown already ran for this recording and deleted the records it created, so the boundary cannot be set now. Finish skyramp_export_zip (it refuses the recording and resets it), then record again from the start: setup steps, skyramp_finish_test_setup, then the scenario." }],
+          isError: true
+        };
+      }
+      const changed = this._recordingPhase.finishSetup();
+      if (changed && this._session.active)
+        this._guard.flush();
+      return {
+        content: [{
+          type: "text",
+          text: changed ? "### Result\nScenario recording started." : "### Result\nScenario recording had already started."
+        }]
+      };
+    }
     if (name === import_exportTool.exportZipSchema.name) {
       const parsed = import_exportTool.exportZipSchema.inputSchema.parse(args || {});
-      const closePromise = this._browserBackend.callTool("browser_close", {}).catch(() => {
-      });
-      let closeTimer;
-      const closeTimeout = new Promise((resolve) => {
-        closeTimer = setTimeout(() => {
-          traceDebug("export: browser_close did not finish within 20s; proceeding with HAR as-is");
-          resolve();
-        }, 2e4);
-      });
-      await Promise.race([closePromise, closeTimeout]);
-      clearTimeout(closeTimer);
+      const prep = await this._session.prepareExport();
+      if (prep.kind === "capture-pending") {
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety could not settle ${prep.urls.length} in-flight create response(s) before export \u2014 the following request(s) were still being captured when the settle timeout elapsed:
+${prep.manifest}
+The recording was NOT exported. Retry skyramp_export_zip once the response(s) complete, or check dataSafetyLedger.json for the audit trail.` }],
+          isError: true
+        };
+      }
+      if (prep.kind === "context-closed") {
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety teardown could not run: the browser context is already closed, so ${prep.pending.length} created entities could not be verified as deleted:
+${prep.manifest}
+Re-open the target with browser_navigate (to restore an authenticated session) and retry skyramp_export_zip, or delete these records manually.` }],
+          isError: true
+        };
+      }
+      if (prep.kind === "leftovers") {
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety teardown could not delete every entity created during recording. The following records were left behind in the target environment:
+${prep.manifest}
+The recording was NOT exported. Delete these records manually or re-record against an ephemeral target.` }],
+          isError: true
+        };
+      }
+      const unverified = this._guard.unparsedCreates.filter((u) => u.rule === "capture-timeout" || u.rule === "capture-failed");
+      if (unverified.length && !parsed.acknowledgeUnverifiedCreates) {
+        const manifest = (0, import_dataSafetyGuard.renderCappedList)(unverified.map((u) => `- POST ${u.url} [${u.rule}]`), "unverified create(s) \u2014 see dataSafetyLedger.json.");
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety: ${unverified.length} create request(s) may have reached the server, but their responses could not be recorded, so teardown could not delete what they created:
+${manifest}
+The recording was NOT exported. Tell the user these requests may have left records behind, then retry skyramp_export_zip with acknowledgeUnverifiedCreates: true.` }],
+          isError: true
+        };
+      }
+      this._resolveSourceActions();
+      const provenance2 = (0, import_exportTool.validateResourceProvenance)(this._trackedActions, this._guard.ledger, this._recordingPhase.setupCompleted);
+      if (!provenance2.ok)
+        return this._refuseAndResetRecording(provenance2.message);
+      await this._closeBrowserForExport();
+      const lateSettle = await this._session.settleBodyReads();
+      if (lateSettle.timedOut) {
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety: ${lateSettle.unsettled} create response(s) were still being captured after the browser closed.
+The recording was NOT exported. Retry skyramp_export_zip once the response(s) complete, or check dataSafetyLedger.json for the audit trail.` }],
+          isError: true
+        };
+      }
+      const lateCreates = this._guard.ledger.filter((e) => !e.tornDown);
+      if (lateCreates.length) {
+        const manifest = (0, import_dataSafetyGuard.renderCappedList)(lateCreates.map((e) => `- ${e.entityUrl} (id ${e.id})`), "left-behind entities \u2014 see dataSafetyLedger.json.");
+        return {
+          content: [{ type: "text", text: `### Error
+Data safety: ${lateCreates.length} record(s) were created while the browser was closing, so teardown could not delete them:
+${manifest}
+The recording was NOT exported. Delete these records manually.` }],
+          isError: true
+        };
+      }
       this._consumeRecorderSelectors();
+      this._resolveSourceActions();
+      const serializedProvenance = (0, import_exportTool.validateResourceProvenance)(this._trackedActions, this._guard.ledger, this._recordingPhase.setupCompleted);
+      if (!serializedProvenance.ok)
+        return this._refuseAndResetRecording(serializedProvenance.message);
       const handler = (0, import_exportTool.createExportZipHandler)({
         trackedActions: this._trackedActions,
         droppedActions: this._droppedActions,
         harPath: this._harPath,
-        outputDir: this._outputDir
+        outputDir: this._outputDir,
+        // The ledger (and unparsedCreates advisory) rides the trace zip
+        // whenever the guard could have done something (strict, or
+        // offLimits blocks even in mode 'off'). By this point prepareExport()
+        // already returned 'clean', so this is never the leftovers/dead-context
+        // manifest — just the audit trail for a successful export.
+        dataSafety: this._session.active ? { ledgerJson: this._guard.ledgerJson(this._recordingPhase.setupCompleted), unparsedCreates: this._guard.unparsedCreates } : void 0
       });
       const exportResult = await handler(parsed);
-      if (!exportResult.isError) {
-        this._trackedActions = [];
-        this._droppedActions = [];
-        const ra = this._browserBackend.context?.recorderActions;
-        if (ra)
-          ra.length = 0;
-        this._cleanupTempDir(true);
-      }
+      if (!exportResult.isError)
+        this._resetRecording();
       return exportResult;
     }
     if (name === import_loadTraceTool.loadTraceSchema.name) {
@@ -244,47 +406,56 @@ class TraceRecordingBackend {
     }
     if (name === import_visualSnapshotTool.visualSnapshotSchema.name) {
       const parsed = import_visualSnapshotTool.visualSnapshotSchema.inputSchema.parse(args || {});
-      return this._handleVisualSnapshot(parsed);
+      return this._withActionProvenance((provenance2) => this._handleVisualSnapshot(parsed, provenance2));
     }
     if (name === import_assertTool.assertToolSchema.name) {
       const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
-      if (parsed.type === "order")
-        return this._handleAssertOrder(parsed);
-      return this._handleAssert({ ...parsed, type: parsed.type });
+      if (parsed.type === "order") {
+        const orderParams = parsed;
+        return this._withActionProvenance((provenance2) => this._handleAssertOrder(orderParams, provenance2));
+      }
+      const assertParams = { ...parsed, type: parsed.type };
+      return this._withActionProvenance((provenance2) => this._handleAssert(assertParams, provenance2));
     }
     if (name === import_assertHiddenTool.assertHiddenToolSchema.name) {
       const parsed = import_assertHiddenTool.assertHiddenToolSchema.inputSchema.parse(args || {});
-      return this._handleAssertHidden(parsed, Date.now());
+      return this._withActionProvenance((provenance2) => this._handleAssertHidden(parsed, Date.now(), provenance2));
     }
     if (name === import_assertApiRequestTool.assertApiRequestSchema.name) {
-      this._trackedActions.push({
-        toolName: "browser_assert_api_request",
-        args: {},
-        code: "",
-        timestamp: Date.now(),
-        pageAlias: this._currentPageAlias
+      return this._withActionProvenance(async (provenance2) => {
+        this._recordAction({
+          toolName: "browser_assert_api_request",
+          args: {},
+          code: "",
+          timestamp: Date.now(),
+          pageAlias: this._currentPageAlias
+        }, provenance2);
+        traceDebug("Assert API request marker recorded");
+        return {
+          content: [{ type: "text", text: "### Result\nAPI request assertion marker recorded. The next action that triggers a network request will have its payload captured for validation in the generated test." }]
+        };
       });
-      traceDebug("Assert API request marker recorded");
-      return {
-        content: [{ type: "text", text: "### Result\nAPI request assertion marker recorded. The next action that triggers a network request will have its payload captured for validation in the generated test." }]
-      };
     }
     if (name === import_tableAssertTool.tableAssertToolSchema.name) {
       const parsed = import_tableAssertTool.tableAssertToolSchema.inputSchema.parse(args || {});
-      return this._handleAssertTableCell(parsed);
+      return this._withActionProvenance((provenance2) => this._handleAssertTableCell(parsed, provenance2));
     }
     if (name === import_gojsTool.gojsAddNodeSchema.name) {
       const parsed = import_gojsTool.gojsAddNodeSchema.inputSchema.parse(args || {});
-      return this._handleGoJSAddNode(parsed);
+      return this._withActionProvenance((provenance2) => this._handleGoJSAddNode(parsed, provenance2));
     }
     if (name === import_gojsTool.gojsLinkSchema.name) {
       const parsed = import_gojsTool.gojsLinkSchema.inputSchema.parse(args || {});
-      return this._handleGoJSLink(parsed);
+      return this._withActionProvenance((provenance2) => this._handleGoJSLink(parsed, provenance2));
     }
     if (name === "browser_select_option") {
       const result2 = await this._handleSelectOption(args || {});
       return result2;
     }
+    if (name === "browser_fill_form")
+      return this._handleFillForm(args || {});
+    if ((name === "browser_type" || name === "browser_press_sequentially") && args?.submit)
+      return this._handleTypeWithSubmit(name, args || {});
     if (name === "browser_tabs" && ["select", "switch"].includes(args?.action)) {
       const index = args?.index ?? 0;
       const targetUrl = this._browserBackend.context?.tabs()[index]?.page.url();
@@ -302,21 +473,26 @@ class TraceRecordingBackend {
         const ts = Date.now();
         const reloadAlias = this._currentPageAlias;
         const tab = this._browserBackend.context.currentTab();
-        this._reloading = true;
+        const provenance2 = this._recordingPhase.beginAction();
         try {
-          await tab.page.reload({ waitUntil: "domcontentloaded" });
+          this._reloading = true;
+          try {
+            await tab.page.reload({ waitUntil: "domcontentloaded" });
+          } finally {
+            this._reloading = false;
+            this._currentPageAlias = reloadAlias;
+            this._pendingPopupAlias = null;
+          }
+          this._recordAction({
+            toolName: "browser_navigate",
+            args: { url: currentUrl },
+            code: "",
+            timestamp: ts,
+            pageAlias: this._currentPageAlias
+          }, provenance2);
         } finally {
-          this._reloading = false;
-          this._currentPageAlias = reloadAlias;
-          this._pendingPopupAlias = null;
+          this._recordingPhase.endAction(provenance2.actionId);
         }
-        this._trackedActions.push({
-          toolName: "browser_navigate",
-          args: { url: currentUrl },
-          code: "",
-          timestamp: ts,
-          pageAlias: this._currentPageAlias
-        });
         await this._enableFlutterAccessibility();
         const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
         return {
@@ -332,6 +508,7 @@ Reloaded current page: ${currentUrl}
     const timestampBeforeAction = Date.now();
     const pageAliasBeforeAction = this._currentPageAlias;
     const stripRestore = await this._maybeStripWrapperRoles(name, args);
+    const provenance = this._recordingPhase.beginAction();
     let preClickHoverCode = null;
     let preClickSnapshot = null;
     let preClickLocatorCount = 0;
@@ -407,37 +584,38 @@ Reloaded current page: ${currentUrl}
       }
       result = await this._browserBackend.callTool(name, args);
     } finally {
-      if (stripRestore)
-        await stripRestore();
+      try {
+        if (stripRestore)
+          await stripRestore();
+      } finally {
+        this._recordingPhase.endAction(provenance.actionId);
+      }
     }
     if (name === "browser_navigate" && !result.isError) {
       await this._enableFlutterAccessibility();
     }
     result = await this._improveActionSelector(name, args || {}, result, preClickHoverCode, preClickSnapshot, preClickLocatorCount, preClickParentChain);
-    if (name === "browser_fill_form" && result.isError) {
-      const resultText = result.content?.[0]?.type === "text" ? result.content[0].text : "";
-      if (resultText.includes("not a <select> element") || resultText.includes("selectOption") && resultText.includes("Timeout")) {
-        const fields = args?.fields;
-        if (fields) {
-          const comboField = fields.find((f) => f.type === "combobox");
-          if (comboField) {
-            traceDebug("fill_form failed on combobox field, retrying with select fallback");
-            this._maybeTrackAction(name, args || {}, { content: result.content, isError: false }, timestampBeforeAction, pageAliasBeforeAction);
-            const selectResult = await this._handleSelectOption({
-              element: comboField.name || "dropdown",
-              ref: comboField.ref,
-              values: [comboField.value]
-            });
-            return selectResult;
-          }
-        }
-      }
-    }
-    this._maybeTrackAction(name, args || {}, result, timestampBeforeAction, pageAliasBeforeAction);
+    if (PASSIVE_TOOLS.has(name) && !result.isError)
+      this._passiveActionIds.add(provenance.actionId);
+    this._maybeTrackAction(name, args || {}, result, provenance, timestampBeforeAction, pageAliasBeforeAction);
     return result;
   }
+  /**
+   * The MCP SDK's server 'close' listener calls this synchronously
+   * (`ServerBackend.serverClosed?(server): void` — sdk/server.ts's
+   * `addServerListener(server, 'close', () => backend.serverClosed?.(server))`
+   * never awaits it), so the underlying work is unavoidably fire-and-forget
+   * from THAT caller's perspective. What was missing is any way for
+   * anything else — tests, or a future dispose/close path this class grows
+   * — to observe when the work actually finishes: the promise is now
+   * captured on the instance instead of discarded.
+   */
   serverClosed() {
-    void this._autoExportAndClose().catch(import_log.logUnhandledError);
+    this._autoExportPromise = this._autoExportAndClose().catch(import_log.logUnhandledError);
+  }
+  /** The in-flight (or settled) promise from the most recent serverClosed() call, if any — see the field comment. */
+  get autoExportPromise() {
+    return this._autoExportPromise;
   }
   /**
    * Execute a coordinate-based mouse action and track each decomposed sub-action
@@ -448,23 +626,85 @@ Reloaded current page: ${currentUrl}
    */
   async _handleMouseAction(params) {
     const page = this._browserBackend.context?.currentTab()?.page;
+    const built = (0, import_mouseActions.mouseActionToJsonl)(params);
+    if ("error" in built)
+      return { content: [{ type: "text", text: `### Error
+${built.error}` }], isError: true };
+    if (!page)
+      return { content: [{ type: "text", text: "### Error\nNo open page. Call browser_navigate first." }], isError: true };
     const timestamp = Date.now();
     const pageAlias = this._currentPageAlias;
-    const { result, actions } = await (0, import_mouseActionTool.executeMouseAction)(page, params);
-    if (result.isError)
-      return result;
-    actions.forEach((a, i) => {
-      this._trackedActions.push({
+    const recorded = [];
+    const code = [];
+    try {
+      for (const action of built.actions) {
+        const provenance = this._recordingPhase.beginAction();
+        try {
+          code.push(...(0, import_mouseActions.mouseJsonlToCode)(action));
+          await this._runMouseSubAction(page, action);
+          recorded.push({ action, provenance });
+        } finally {
+          this._recordingPhase.endAction(provenance.actionId);
+        }
+      }
+    } catch (e) {
+      return { content: [{ type: "text", text: `### Error
+Mouse action failed: ${e.message}` }], isError: true };
+    }
+    recorded.forEach(({ action, provenance }, i) => {
+      this._recordAction({
         toolName: "browser_mouse_action",
-        args: a,
+        args: action,
         code: "",
         // Stagger timestamps so a decomposed drag keeps its move<down<move<up order.
         timestamp: timestamp + i,
         pageAlias
-      });
+      }, provenance);
     });
-    traceDebug(`Tracked ${actions.length} mouse sub-action(s) for "${params.action}" on ${pageAlias}`);
-    return result;
+    traceDebug(`Tracked ${recorded.length} mouse sub-action(s) for "${params.action}" on ${pageAlias}`);
+    return { content: [{ type: "text", text: `### Ran Playwright code
+${code.join("\n")}` }] };
+  }
+  async _runMouseSubAction(page, action) {
+    const withModifiers = async (mask, operation) => {
+      const keys = (0, import_mouseActions.decodeModifierKeys)(mask);
+      for (const key of keys)
+        await page.keyboard.down(key);
+      try {
+        await operation();
+      } finally {
+        for (const key of [...keys].reverse())
+          await page.keyboard.up(key);
+      }
+    };
+    switch (action.name) {
+      case "mouse.move":
+        if (action.steps === void 0)
+          await page.mouse.move(action.position.x, action.position.y);
+        else
+          await page.mouse.move(action.position.x, action.position.y, { steps: action.steps });
+        return;
+      case "mouse.down":
+        if (action.button && action.button !== "left")
+          await page.mouse.down({ button: action.button });
+        else
+          await page.mouse.down();
+        return;
+      case "mouse.up":
+        if (action.button && action.button !== "left")
+          await page.mouse.up({ button: action.button });
+        else
+          await page.mouse.up();
+        return;
+      case "mouse.wheel":
+        await withModifiers(action.modifiers, () => page.mouse.wheel(action.deltaX, action.deltaY));
+        return;
+      case "click": {
+        const options = action.button !== "left" || action.clickCount !== 1 ? { button: action.button, clickCount: action.clickCount } : void 0;
+        await withModifiers(action.modifiers, () => options ? page.mouse.click(action.position.x, action.position.y, options) : page.mouse.click(action.position.x, action.position.y));
+        return;
+      }
+    }
   }
   /**
    * Handle browser_visual_snapshot: record a `visualSnapshot` marker that
@@ -486,7 +726,7 @@ Reloaded current page: ${currentUrl}
    * (same machinery as the GoJS tools). Iframe-element snapshots from the recorder
    * remain out of scope here (see common/visualSnapshot.ts).
    */
-  async _handleVisualSnapshot(params) {
+  async _handleVisualSnapshot(params, provenance) {
     const timestamp = Date.now();
     const pageAlias = this._currentPageAlias;
     const input = {
@@ -522,13 +762,13 @@ GoJS diagram "${diagramSelector}" is not inside an iframe; the gojsDiagram snaps
 ${built.error}` }], isError: true };
     this._visualSnapshotCounters[params.snapshotType]++;
     this._advanceSnapshotCounterFor(params.snapshotType, input.filename);
-    this._trackedActions.push({
+    this._recordAction({
       toolName: "browser_visual_snapshot",
       args: built.action,
       code: "",
       timestamp,
       pageAlias
-    });
+    }, provenance);
     traceDebug(`Tracked visualSnapshot (${params.snapshotType}) "${input.filename}" on ${pageAlias}`);
     const targetDesc = params.snapshotType === "element" ? ` (${input.selector})` : params.snapshotType === "region" && params.clip ? ` (clip ${params.clip.width}x${params.clip.height} at ${params.clip.x},${params.clip.y})` : params.snapshotType === "gojsDiagram" ? ` (${input.diagramSelector} via ${input.iframeSelectors?.length ?? 0} iframe(s))` : params.fullPage ? " (full page)" : "";
     return { content: [{ type: "text", text: `### Visual snapshot recorded
@@ -686,11 +926,17 @@ The selected range acts on tab "${a.frame.pageAlias}" but the step that opens th
     if (seedPage)
       claimedTabs.add(seedPage);
     let tabsBefore = [];
+    const replayProvenance = /* @__PURE__ */ new Map();
+    let activeReplayProvenance;
     let result;
     try {
       result = await (0, import_loadTraceTool.replayActions)(loadedActions, {
         pageForAlias: (alias) => remap.get(alias)?.page ?? this._pageForAlias(alias),
-        beforeAction: () => {
+        beforeAction: (action) => {
+          if (activeReplayProvenance)
+            this._recordingPhase.endAction(activeReplayProvenance.actionId);
+          activeReplayProvenance = this._recordingPhase.beginAction();
+          replayProvenance.set(action, activeReplayProvenance);
           tabsBefore = liveTabs();
         },
         afterAction: async (action) => {
@@ -709,11 +955,18 @@ The selected range acts on tab "${a.frame.pageAlias}" but the step that opens th
             claimedTabs.add(fresh);
             remap.set(signal.popupAlias, { page: fresh, liveAlias: this._currentPageAlias });
           }
+          if (activeReplayProvenance) {
+            this._recordingPhase.endAction(activeReplayProvenance.actionId);
+            activeReplayProvenance = void 0;
+          }
         }
       }, params);
     } catch (e) {
       return { content: [{ type: "text", text: `### Error
 Replay failed: ${e.message}` }], isError: true };
+    } finally {
+      if (activeReplayProvenance)
+        this._recordingPhase.endAction(activeReplayProvenance.actionId);
     }
     for (let i = result.startIndex; i < result.stopIndex; i++) {
       const a = loadedActions[i];
@@ -721,7 +974,10 @@ Replay failed: ${e.message}` }], isError: true };
       if (liveAlias && liveAlias !== a.frame.pageAlias)
         a.frame = { ...a.frame, pageAlias: liveAlias };
       const before = this._trackedActions.length;
-      this._seedTrackedAction(a);
+      const provenance = replayProvenance.get(a);
+      if (!provenance)
+        continue;
+      this._seedTrackedAction(a, provenance);
       const popupSignal = a.action.signals.find((s) => s.name === "popup");
       if (popupSignal && this._trackedActions.length > before)
         this._trackedActions[this._trackedActions.length - 1].popupAlias = remap.get(popupSignal.popupAlias)?.liveAlias ?? popupSignal.popupAlias;
@@ -774,17 +1030,17 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
    * re-derives the JSONL selector from the `code` field, so we regenerate clean
    * Playwright code from the stored internal: selector via asLocator.
    */
-  _seedTrackedAction(action) {
+  _seedTrackedAction(action, provenance) {
     const a = action.action;
     const pageAlias = action.frame.pageAlias || "page";
     if (a.name === "navigate") {
-      this._trackedActions.push({
+      this._recordAction({
         toolName: "browser_navigate",
         args: { url: a.url },
         code: "",
         timestamp: action.startTime,
         pageAlias
-      });
+      }, provenance);
       return;
     }
     const locatorExpr = a.selector ? (0, import_utils.asLocator)("javascript", a.selector) : "";
@@ -793,12 +1049,12 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
       return;
     if (seeded.toolName === "browser_visual_snapshot")
       this._advanceSnapshotCounterFor(seeded.args.snapshotType, seeded.args.filename);
-    this._trackedActions.push({
+    this._recordAction({
       ...seeded,
       timestamp: action.startTime,
       pageAlias,
       framePath: action.frame.framePath?.length ? action.frame.framePath : void 0
-    });
+    }, provenance);
   }
   /**
    * Bump the per-type snapshot counter to at least the number embedded in a
@@ -1028,7 +1284,9 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
    *    take a snapshot to find the options, then click the matching option.
    */
   async _handleSelectOption(args) {
-    const result = await this._browserBackend.callTool("browser_select_option", args);
+    const { result, provenance } = await this._runActionOperation(
+      () => this._browserBackend.callTool("browser_select_option", args)
+    );
     const resultText = result.content?.[0]?.type === "text" ? result.content[0].text : "";
     if (!result.isError) {
       const code = (0, import_response.parseResponse)(result)?.code ?? "";
@@ -1050,18 +1308,18 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
               const selectCode = `await page.${locatorExpr}.selectOption(${JSON.stringify(values2.length === 1 ? values2[0] : values2)});`;
               traceDebug(`Improved select selector: ${selectCode}`);
               const timestamp = Date.now();
-              this._trackedActions.push({
+              this._recordAction({
                 toolName: "browser_select_option",
                 args,
                 code: selectCode,
                 timestamp
-              });
+              }, provenance);
               return result;
             }
           }
         }
       }
-      this._maybeTrackAction("browser_select_option", args, result);
+      this._maybeTrackAction("browser_select_option", args, result, provenance);
       return result;
     }
     const shouldFallback = resultText.includes("not a <select> element") || resultText.includes("selectOption") && resultText.includes("Timeout") || resultText.includes("not found in the current page snapshot");
@@ -1080,11 +1338,13 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
       const comboboxes = [...snapText.matchAll(/combobox[^\n]*\[ref=(\w+)\]/g)];
       const clickableCombo = comboboxes.find((m) => m[0].includes("cursor=pointer"));
       const comboRef = clickableCombo?.[1] || args.ref;
-      const clickResult = await this._browserBackend.callTool("browser_click", { element: args.element || "dropdown", ref: comboRef });
+      const { result: clickResult, provenance: clickProvenance } = await this._runActionOperation(
+        () => this._browserBackend.callTool("browser_click", { element: args.element || "dropdown", ref: comboRef })
+      );
       if (clickResult.isError)
         return { content: [{ type: "text", text: `### Error
 Failed to open custom dropdown. The dropdown modal may not be visible yet. Try calling browser_snapshot first to check the page state, then ensure the form/modal is open before selecting an option.` }], isError: true };
-      this._maybeTrackAction("browser_click", { element: args.element || "dropdown", ref: comboRef }, clickResult);
+      this._maybeTrackAction("browser_click", { element: args.element || "dropdown", ref: comboRef }, clickResult, clickProvenance);
       const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
       if (snapResult.isError)
         return snapResult;
@@ -1102,15 +1362,19 @@ Failed to open custom dropdown. The dropdown modal may not be visible yet. Try c
       const pattern1 = new RegExp(`option\\s+"${escaped}"[^\\n]*\\[ref=(\\w+)\\]`, "i");
       const match1 = snapText.match(pattern1);
       if (match1) {
-        const optionClickResult = await this._browserBackend.callTool("browser_click", { element: `${candidate} option`, ref: match1[1] });
-        this._maybeTrackAction("browser_click", { element: `${candidate} option`, ref: match1[1] }, optionClickResult);
+        const { result: optionClickResult, provenance: optionProvenance } = await this._runActionOperation(
+          () => this._browserBackend.callTool("browser_click", { element: `${candidate} option`, ref: match1[1] })
+        );
+        this._maybeTrackAction("browser_click", { element: `${candidate} option`, ref: match1[1] }, optionClickResult, optionProvenance);
         return optionClickResult;
       }
       const pattern2 = new RegExp(`option[^\\n]*\\[ref=(\\w+)\\][^\\n]*${escaped}`, "i");
       const match2 = snapText.match(pattern2);
       if (match2) {
-        const optionClickResult = await this._browserBackend.callTool("browser_click", { element: `${candidate} option`, ref: match2[1] });
-        this._maybeTrackAction("browser_click", { element: `${candidate} option`, ref: match2[1] }, optionClickResult);
+        const { result: optionClickResult, provenance: optionProvenance } = await this._runActionOperation(
+          () => this._browserBackend.callTool("browser_click", { element: `${candidate} option`, ref: match2[1] })
+        );
+        this._maybeTrackAction("browser_click", { element: `${candidate} option`, ref: match2[1] }, optionClickResult, optionProvenance);
         return optionClickResult;
       }
     }
@@ -1119,6 +1383,82 @@ Failed to open custom dropdown. The dropdown modal may not be visible yet. Try c
 Opened the custom dropdown but could not find a matching option for "${targetValue}". Available options:
 ${optionLines}` }], isError: true };
   }
+  async _handleFillForm(args) {
+    const fields = args.fields;
+    if (!fields?.length)
+      return this._browserBackend.callTool("browser_fill_form", args);
+    const content = [];
+    for (const field of fields) {
+      const fieldArgs = { fields: [field] };
+      const timestamp = Date.now();
+      const pageAlias = this._currentPageAlias;
+      const { result, provenance } = await this._runActionOperation(
+        () => this._browserBackend.callTool("browser_fill_form", fieldArgs)
+      );
+      if (result.isError) {
+        const resultText = result.content?.[0]?.type === "text" ? result.content[0].text : "";
+        if (field.type === "combobox" && (resultText.includes("not a <select> element") || resultText.includes("selectOption") && resultText.includes("Timeout"))) {
+          const selectResult = await this._handleSelectOption({
+            element: field.name || "dropdown",
+            ref: field.ref,
+            values: [field.value]
+          });
+          if (selectResult.isError)
+            return { ...selectResult, content: [...content, ...selectResult.content ?? []] };
+          content.push(...selectResult.content ?? []);
+          continue;
+        }
+        return { ...result, content: [...content, ...result.content ?? []] };
+      }
+      this._maybeTrackAction("browser_fill_form", fieldArgs, result, provenance, timestamp, pageAlias);
+      content.push(...result.content ?? []);
+    }
+    return { content };
+  }
+  async _handleTypeWithSubmit(name, args) {
+    const tab = this._browserBackend.context?.currentTab();
+    let submitTarget;
+    const typeArgs = { ...args, submit: false };
+    const typeTimestamp = Date.now();
+    const typePageAlias = this._currentPageAlias;
+    const { result: rawTypeResult, provenance: typeProvenance } = await this._runActionOperation(
+      async () => {
+        if (name === "browser_type" && tab) {
+          try {
+            submitTarget = await tab.refLocator({ element: args.element, ref: args.ref });
+          } catch (error) {
+            return { content: [{ type: "text", text: `### Error
+${String(error)}` }], isError: true };
+          }
+        }
+        return this._browserBackend.callTool(name, typeArgs);
+      }
+    );
+    const typeResult = await this._improveActionSelector(name, typeArgs, rawTypeResult, null, null, 0, null);
+    this._maybeTrackAction(name, typeArgs, typeResult, typeProvenance, typeTimestamp, typePageAlias);
+    if (typeResult.isError)
+      return typeResult;
+    const pressArgs = { key: "Enter" };
+    const pressTimestamp = Date.now();
+    const pressPageAlias = this._currentPageAlias;
+    const { result: pressResult, provenance: pressProvenance } = await this._runActionOperation(
+      async () => {
+        if (!submitTarget || !tab)
+          return this._browserBackend.callTool("browser_press_key", pressArgs);
+        const response = import_response.Response.create(tab.context, "browser_press_key", pressArgs);
+        response.setIncludeSnapshot();
+        response.addCode(`await page.${submitTarget.resolved}.press('Enter');`);
+        try {
+          await tab.waitForCompletion(() => submitTarget.locator.press("Enter"));
+        } catch (error) {
+          response.addError(String(error));
+        }
+        return response.build();
+      }
+    );
+    this._maybeTrackAction("browser_press_key", pressArgs, pressResult, pressProvenance, pressTimestamp, pressPageAlias);
+    return { ...pressResult, content: [...typeResult.content ?? [], ...pressResult.content ?? []] };
+  }
   /**
    * Find the Playwright Frame whose document hosts a GoJS diagram in the given
    * container div (walks all frames; GoJS lives in nested same-origin iframes).
@@ -1197,7 +1537,7 @@ ${optionLines}` }], isError: true };
    * record a diagramNodeAdd action carrying the semantic fields skyramp codegen
    * consumes.
    */
-  async _handleGoJSAddNode(params) {
+  async _handleGoJSAddNode(params, provenance) {
     const timestamp = Date.now();
     const { frame, error: frameError } = await this._findGoJSFrame(params.diagramSelector);
     if (!frame)
@@ -1275,13 +1615,13 @@ GoJS add node failed: ${result ? result.err : "unknown"}` }], isError: true };
       anchorDocX: result.anchorDocX,
       anchorDocY: result.anchorDocY
     };
-    this._trackedActions.push({
+    this._recordAction({
       toolName: import_gojsTool.gojsAddNodeSchema.name,
       args,
       code: "",
       timestamp,
       framePath
-    });
+    }, provenance);
     traceDebug(`GoJS add node: ${params.category} key=${result.key} anchor=${params.anchorKey ?? "-"}`);
     return { content: [{ type: "text", text: `### Result
 Added GoJS node "${params.category}" (key ${result.key})${params.anchorKey ? ` near ${params.anchorKey}` : ""}.` }] };
@@ -1290,7 +1630,7 @@ Added GoJS node "${params.category}" (key ${result.key})${params.anchorKey ? ` n
    * Handle browser_gojs_link: connect two GoJS nodes via the model API
    * (mirroring the GoJSDiagram helper) and record a diagramLinkAdd action.
    */
-  async _handleGoJSLink(params) {
+  async _handleGoJSLink(params, provenance) {
     const timestamp = Date.now();
     const { frame, error: frameError } = await this._findGoJSFrame(params.diagramSelector);
     if (!frame)
@@ -1336,13 +1676,13 @@ GoJS link failed: ${result ? result.err : "unknown"}` }], isError: true };
       fromPort: params.fromPort,
       toPort: params.toPort
     };
-    this._trackedActions.push({
+    this._recordAction({
       toolName: import_gojsTool.gojsLinkSchema.name,
       args,
       code: "",
       timestamp,
       framePath
-    });
+    }, provenance);
     traceDebug(`GoJS link: ${params.fromKey} -> ${params.toKey} (${params.fromPort}->${params.toPort})`);
     return { content: [{ type: "text", text: `### Result
 Linked GoJS nodes ${params.fromKey} \u2192 ${params.toKey} (${params.fromPort}\u2192${params.toPort}).` }] };
@@ -1356,7 +1696,7 @@ Linked GoJS nodes ${params.fromKey} \u2192 ${params.toKey} (${params.fromPort}\u
    * dispatched to _handleAssertOrder instead: two refs, a live boundingBox()
    * comparison, no pointer-off read. Only passing assertions are recorded.
    */
-  async _handleAssert(params) {
+  async _handleAssert(params, provenance) {
     const timestamp = Date.now();
     if (!params.expected && (params.type === "text" || params.type === "value" || params.type === "count"))
       return { content: [{ type: "text", text: '### Error\n"expected" parameter is required.' }], isError: true };
@@ -1620,8 +1960,8 @@ Could not count "${refRole}" elements: ${e.message}` }], isError: true };
           break;
       }
       if (unhoverMove)
-        this._trackedActions.push({ toolName: "browser_mouse_action", args: { name: "mouse.move", position: unhoverMove }, code: "", timestamp: timestamp - 1, pageAlias: this._currentPageAlias });
-      this._trackedActions.push({ toolName: "browser_assert", args, code, timestamp, pageAlias: this._currentPageAlias });
+        this._recordAction({ toolName: "browser_mouse_action", args: { name: "mouse.move", position: unhoverMove }, code: "", timestamp: timestamp - 1, pageAlias: this._currentPageAlias }, provenance);
+      this._recordAction({ toolName: "browser_assert", args, code, timestamp, pageAlias: this._currentPageAlias }, provenance);
       traceDebug(`Assert: ${assertName} with selector ${args.selector}`);
     }
     return {
@@ -1640,7 +1980,7 @@ ${details}` }]
    * above/below — compared strictly. It says where each element STARTS, not
    * that one lies wholly beyond the other.
    */
-  async _handleAssertOrder(params) {
+  async _handleAssertOrder(params, provenance) {
     const timestamp = Date.now();
     const error = (text) => ({ content: [{ type: "text", text: `### Error
 ${text}` }], isError: true });
@@ -1700,7 +2040,7 @@ ${details}` }] };
       otherLocator: b.parsed.locator,
       relation
     };
-    this._trackedActions.push({ toolName: "browser_assert", args, code: `assertOrder:${a.selector}:${relation}:${b.selector}`, timestamp, pageAlias: this._currentPageAlias });
+    this._recordAction({ toolName: "browser_assert", args, code: `assertOrder:${a.selector}:${relation}:${b.selector}`, timestamp, pageAlias: this._currentPageAlias }, provenance);
     traceDebug(`Assert: assertOrder ${a.selector} ${relation} ${b.selector}`);
     return { content: [{ type: "text", text: `### Assertion Passed
 ${details}${a.note}${b.note}` }] };
@@ -1711,7 +2051,7 @@ ${details}${a.note}${b.note}` }] };
    * action. Column is 1-based over DATA columns (A=1); the leading row-number
    * <th> is skipped via td:nth-child(column + 1). Row is the 1-based visible row.
    */
-  async _handleAssertTableCell(params) {
+  async _handleAssertTableCell(params, provenance) {
     const timestamp = Date.now();
     const tablePrefix = params.table ? `${params.table} ` : "";
     const selector = `${tablePrefix}tbody tr:nth-child(${params.row}) td:nth-child(${params.column + 1})`;
@@ -1770,7 +2110,7 @@ No cell at row ${params.row}, column ${params.column} (selector: ${selector}).`
       isInput: !!cell.isInput
     });
     if (passed) {
-      this._trackedActions.push({
+      this._recordAction({
         toolName: import_tableAssertTool.tableAssertToolSchema.name,
         // Record the active page so assertions on popup/secondary tabs are
         // attributed correctly (mirrors _handleAssertApiRequest).
@@ -1785,7 +2125,7 @@ No cell at row ${params.row}, column ${params.column} (selector: ${selector}).`
         },
         code: "",
         timestamp
-      });
+      }, provenance);
       traceDebug(`AssertTableCell: ${selector} \u2192 "${params.expected}" (isInput=${cell.isInput})`);
     }
     return {
@@ -1870,7 +2210,7 @@ The current page (${url}) is not a loaded application page; navigate to the app
    * assertActionToJsonl and the re-seed path share one shape with the other
    * assertions.
    */
-  async _handleAssertHidden(params, timestamp) {
+  async _handleAssertHidden(params, timestamp, provenance) {
     const err = (text) => ({ content: [{ type: "text", text: `### Error
 ${text}` }], isError: true });
     const given = [params.testId, params.role, params.text, params.attribute].filter((v) => typeof v === "string" && v.trim() !== "");
@@ -1927,7 +2267,7 @@ ${text}` }], isError: true });
     let details;
     if (passed) {
       details = `Hidden assertion passed: "${params.element}" is absent or not visible.`;
-      this._trackedActions.push({ toolName: "browser_assert", args: { type: "hidden", selector, locator }, code: `assertHidden:${selector}`, timestamp, pageAlias: this._currentPageAlias });
+      this._recordAction({ toolName: "browser_assert", args: { type: "hidden", selector, locator }, code: `assertHidden:${selector}`, timestamp, pageAlias: this._currentPageAlias }, provenance);
       traceDebug(`Assert: assertHidden with selector ${selector}`);
     } else {
       const count = await tab.page.locator(selector).count().catch(() => -1);
@@ -2683,7 +3023,87 @@ ${parsed.selector} does not pick out "${opts.element}" on the live page: ${pinFa
       }
     };
   }
-  _maybeTrackAction(toolName, args, result, timestamp, pageAliasBeforeAction) {
+  async _withActionProvenance(operation) {
+    const provenance = this._recordingPhase.beginAction();
+    try {
+      return await operation(provenance);
+    } finally {
+      this._recordingPhase.endAction(provenance.actionId);
+    }
+  }
+  async _runActionOperation(operation) {
+    const provenance = this._recordingPhase.beginAction();
+    try {
+      return { result: await operation(), provenance };
+    } finally {
+      this._recordingPhase.endAction(provenance.actionId);
+    }
+  }
+  _recordAction(action, provenance) {
+    this._trackedActions.push({ ...action, ...provenance });
+  }
+  /**
+   * Close the browser context to flush the HAR file to disk (Playwright
+   * writes HAR on context close). Bounded: a heavy page (e.g. a
+   * nested-iframe GoJS canvas with live timers) can stall context close
+   * indefinitely. The HAR flush is best-effort; the JSONL trace (what
+   * codegen consumes) is complete regardless.
+   */
+  async _closeBrowserForExport() {
+    const closePromise = this._browserBackend.callTool("browser_close", {}).catch(() => {
+    });
+    let closeTimer;
+    const closeTimeout = new Promise((resolve) => {
+      closeTimer = setTimeout(() => {
+        traceDebug("export: browser_close did not finish within 20s; proceeding with HAR as-is");
+        resolve();
+      }, 2e4);
+    });
+    await Promise.race([closePromise, closeTimeout]);
+    clearTimeout(closeTimer);
+  }
+  /**
+   * End the recording: the next one starts fresh. A successful export ends
+   * the data-safety session too — the next recording's ledger must contain
+   * only its own entries and blocks, and its teardown must not re-DELETE
+   * this session's entities. The temp dir and HAR path stay stable so
+   * recordHar stays in sync (SKYR-3830).
+   */
+  _resetRecording() {
+    this._trackedActions = [];
+    this._droppedActions = [];
+    const ra = this._browserBackend.context?.recorderActions;
+    if (ra)
+      ra.length = 0;
+    this._recordingPhase.reset();
+    this._passiveActionIds.clear();
+    this._guard.resetSession();
+    this._cleanupTempDir(true);
+  }
+  /**
+   * A recording whose resource provenance is invalid can never export: its
+   * records are already deleted and the phases of its creates are fixed.
+   * Close the browser (so the next HAR holds only the new attempt) and reset
+   * the recording, so recording again from the start can export.
+   */
+  async _refuseAndResetRecording(reason) {
+    const created = this._guard.ledger.length;
+    await this._closeBrowserForExport();
+    this._resetRecording();
+    const deleted = created ? ` Data safety teardown already deleted the ${created} record(s) this attempt created, setup data included.` : "";
+    return {
+      content: [{ type: "text", text: `### Error
+${reason}
+The recording was NOT exported, and it was reset.${deleted} The browser was closed. Record again from the start: browser_navigate, the setup steps, skyramp_finish_test_setup, then the scenario steps.` }],
+      isError: true
+    };
+  }
+  /** See resolveSourceActions: a create's source action must have a JSONL line. */
+  _resolveSourceActions() {
+    for (const [entry, actionId] of (0, import_exportTool.resolveSourceActions)(this._trackedActions, this._guard.ledger, this._passiveActionIds))
+      this._guard.setSourceAction(entry, actionId);
+  }
+  _maybeTrackAction(toolName, args, result, provenance, timestamp, pageAliasBeforeAction) {
     if (result.isError) {
       const errParsed = (0, import_response.parseResponse)(result);
       const errText = (errParsed?.error ?? errParsed?.text ?? "unknown error").replace(/\s+/g, " ").trim().slice(0, 300);
@@ -2699,14 +3119,14 @@ ${parsed.selector} does not pick out "${opts.element}" on the live page: ${pinFa
       const popupAlias = this._pendingPopupAlias ?? void 0;
       this._pendingPopupAlias = null;
       const pageAlias = popupAlias ? pageAliasBeforeAction ?? this._currentPageAlias : this._currentPageAlias;
-      this._trackedActions.push({
+      this._recordAction({
         toolName,
         args,
         code,
         timestamp: timestamp ?? Date.now(),
         pageAlias,
         popupAlias
-      });
+      }, provenance);
       traceDebug(`Tracked action: ${toolName} on ${pageAlias}${popupAlias ? ` \u2192 popup:${popupAlias}` : ""} (total: ${this._trackedActions.length})`);
     }
   }
@@ -2799,18 +3219,69 @@ ${parsed.selector} does not pick out "${opts.element}" on the live page: ${pinFa
     }
   }
   async _autoExportAndClose() {
+    let { teardownClean } = await this._session.settleAndTeardownBestEffort();
+    const guardActive = this._session.active;
+    const hasAudit = guardActive && (this._guard.ledger.length > 0 || this._guard.blocks.length > 0 || this._guard.unparsedCreates.length > 0);
+    let zipWritten = false;
     if (this._trackedActions.length) {
       try {
         this._consumeRecorderSelectors();
+        this._resolveSourceActions();
+        const provenance = (0, import_exportTool.validateResourceProvenance)(this._trackedActions, this._guard.ledger, this._recordingPhase.setupCompleted);
+        if (!provenance.ok)
+          process.stderr.write(`[skyramp] Auto-export: the recording's resource provenance is invalid, so test generation will refuse it: ${provenance.message}
+`);
         const outputZip = import_path.default.resolve(this._outputDir, "skyramp_export.zip");
-        const { jsonl: jsonlContent, actionCount } = (0, import_skyRampExport.buildJsonlContent)(this._trackedActions, "chromium", this._harPath);
-        await (0, import_skyRampExport.writeSkyrampZip)(outputZip, jsonlContent, this._harPath);
-        process.stderr.write(`[skyramp] Auto-exported ${actionCount} actions to ${outputZip}
+        const { jsonl: jsonlContent, actionCount } = (0, import_skyRampExport.buildJsonlContent)(this._trackedActions, "chromium", this._harPath, void 0, void 0, this._guard.ledger);
+        await (0, import_skyRampExport.writeSkyrampZip)(
+          outputZip,
+          jsonlContent,
+          this._harPath,
+          guardActive ? [{ name: "dataSafetyLedger.json", content: this._guard.ledgerJson(this._recordingPhase.setupCompleted) }] : void 0
+        );
+        zipWritten = true;
+        const incompleteReasons = [];
+        if (!teardownClean)
+          incompleteReasons.push("teardown left entities behind \u2014 see dataSafetyLedger.json");
+        const unparsedCount = this._guard.unparsedCreates.length;
+        if (unparsedCount > 0)
+          incompleteReasons.push(`${unparsedCount} unidentified create(s) \u2014 see dataSafetyLedger.json`);
+        const incompleteNote = incompleteReasons.length ? ` (data-safety-incomplete: ${incompleteReasons.join("; ")})` : "";
+        process.stderr.write(`[skyramp] Auto-exported ${actionCount} actions to ${outputZip}${incompleteNote}
+`);
+      } catch (e) {
+        process.stderr.write(`[skyramp] Auto-export failed: ${String(e)}
 `);
-      } catch {
       }
     }
     this._browserBackend?.serverClosed();
+    if (guardActive) {
+      const late = await this._session.settleBodyReads();
+      if (late.timedOut || this._guard.pendingTeardownCount > 0)
+        teardownClean = false;
+    }
+    const mustPreserve = !teardownClean || hasAudit && !zipWritten;
+    const callerLedger = guardActive && this._guard.config.ledgerDir && (hasAudit || import_fs.default.existsSync(this._guard.ledgerPath)) ? this._guard.ledgerPath : void 0;
+    let preserve = "not-needed";
+    if (mustPreserve || callerLedger) {
+      try {
+        const preservedPath = callerLedger ?? import_path.default.join(this._outputDir, `dataSafetyLedger-${Date.now()}.json`);
+        (0, import_dataSafetyGuard.writeLedgerFile)(preservedPath, this._guard.ledgerJson(this._recordingPhase.setupCompleted));
+        if (mustPreserve)
+          process.stderr.write(`[skyramp] Data safety: ${teardownClean ? "audit trail" : "teardown incomplete"} \u2014 ledger preserved at ${preservedPath}
+`);
+        preserve = "done";
+      } catch (e) {
+        process.stderr.write(`[skyramp] Data safety: failed to preserve ledger (${String(e)}) \u2014 dumping inline so the record survives:
+${this._guard.ledgerJson(this._recordingPhase.setupCompleted)}
+`);
+        preserve = "failed";
+      }
+    }
+    traceDebug(`data safety abnormal-end preserve outcome: ${preserve}`);
+    this._recordingPhase.reset();
+    this._passiveActionIds.clear();
+    this._guard.resetSession();
     this._cleanupTempDir(false);
   }
 }