@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/src/run/visit.js

@@ -0,0 +1,693 @@
+"use strict";
+/**
+ * 가상 사용자 한 명의 한 방문 — 자유 탐방.
+ *
+ * 길을 정해주지 않는다. 사람과 목적만 주고, 화면에 보이는 것만 보고 다음 행동을 스스로 고른다.
+ * 길을 박아두면 30명이 같은 화면만 보고 사람도 그 화면을 열 만한 부류로만 뽑힌다(2026-09-18 확인).
+ *
+ * 도중에 질문 카드가 뜨면 그 사람으로서 답하거나 닫는다(answer.js). 그게 이 방문의 산출물이고,
+ * 걸음마다 남긴 이유가 나중에 사람이 확인할 근거다.
+ *
+ * **판단과 몸을 가른다.** `Visit` 이 몸이다 — 화면 보기·사람 손으로 누르기·쉬기·카드 누르기·떠나기.
+ * 판단(무엇을 누를까·답할까)은 밖에서 준다. 누가 주느냐가 두 가지다:
+ * - `runVisit`: 우리가 AI(`ask`)에 물어 준다. 우리 내부 테스트·자동 실행
+ * - MCP 한 걸음 도구: 고객의 AI 도구(Claude Code 서브에이전트)가 그 사람이 되어 준다(PLAN.md)
+ * 둘이 같은 몸을 써야 사람처럼 움직이는 방식·막는 선이 갈라지지 않는다.
+ *
+ * 의존성 없음. Playwright page 를 받는다.
+ */
+const fs = require("fs");
+const path = require("path");
+const { listControls, visibleText, handleAt, clickBlocked } = require("../browser/page.js");
+const { readCard, waitCard, screenText, answerCard, noteReason, sleep, waitForSdk } = require("../browser/card.js");
+const hand = require("../browser/hand.js");
+const answer = require("./answer.js");
+const diag = require("./diag.js");
+
+const STEP_PROMPT_FILE = path.join(__dirname, "..", "prompts", "step.md");
+
+const STEP_SCHEMA = {
+  type: "object",
+  properties: {
+    why: { type: "string" },
+    action: { type: "string", enum: ["click", "type", "scroll", "scroll_up", "read", "back", "leave"] },
+    index: { type: "integer" },
+    text: { type: "string" },
+    done: { type: "boolean" },
+    times: { type: "integer" },
+  },
+  required: ["why", "action", "index", "text", "done", "times"],
+};
+
+/** 같은 조작을 연달아 몇 번까지. 굴리며 훑기·안 눌려서 거듭 누르기 */
+const MAX_TIMES = { click: 4, scroll: 5, scroll_up: 5 };
+
+/**
+ * 클릭 뒤 화면이 자리 잡기를 기다린다. 사람도 눌렀으면 뜰 때까지 본다.
+ * 안 기다리면 느린 화면이 "눌러도 안 열린다" 로 읽힌다 — 10/13 bluetags 에서 카드가 "안 열린다 → 조금 뒤 열렸다".
+ */
+async function settle(page, before, net) {
+  // 주소가 바뀔 때까지 보되, 아무것도 안 불러오고 있으면 거기서 끝난 것이다(정말 안 눌린 것).
+  // Next.js 같은 사이트는 다음 화면 데이터를 다 받은 뒤에야 주소를 바꾼다. 1.5초로 끊었더니 10/13 0.1.8 에서
+  // "안 열린다" 가 69번 — 그중 38번은 같은 걸 다시 누르자 열렸다. networkidle 은 이미 연 문서에서는 바로 끝나 소용없다
+  const t0 = Date.now();
+  let quietSince = null;
+  let moved = false;
+  // 화면을 불러오는 중이면 30초까지 본다. 10초로 끊었더니 개발 서버에서 카드가 "안 열렸다" 가 되고,
+  // 다시 누르자 그새 넘어가 "없어졌다" 가 됐다(10/15 실험실 p16)
+  while (Date.now() - t0 < (net && net.navPending() ? 30000 : 10000)) {
+    // 새 탭으로 열린 같은 사이트 화면을 이 탭으로 옮기는 중이다(hub). 그 이동이 끝날 때까지 본다
+    if (page.__ebPendingNav) {
+      await Promise.race([page.__ebPendingNav, sleep(30000)]);
+      moved = page.url() !== before;
+      break;
+    }
+    if (page.url() !== before) {
+      moved = true;
+      break;
+    }
+    const busy = net ? net.busy() : 0;
+    if (busy) quietSince = null;
+    else if (quietSince === null) quietSince = Date.now();
+    if (Date.now() - t0 > 800 && quietSince !== null && Date.now() - quietSince > 600) break;
+    await sleep(100);
+  }
+  if (moved) {
+    await page.waitForLoadState("domcontentloaded", { timeout: 10000 }).catch(() => {});
+    await page.waitForLoadState("networkidle", { timeout: 4000 }).catch(() => {});
+    // 뒤로 가기는 주소가 먼저 바뀌고, 그다음에 새 화면 데이터를 받아 그린다(Next.js). 위 두 대기는 이미 연 문서라 바로 끝난다 —
+    // 주소는 "/" 인데 화면은 아직 커뮤니티였다(10/14 bluetags p15: 옛 화면의 버튼을 눌러 "없다"·"안 된다").
+    // 조작이 시작한 요청이 다 끝날 때까지 본다
+    if (net) {
+      const t1 = Date.now();
+      let quiet = null;
+      while (Date.now() - t1 < 8000) {
+        if (net.busy()) quiet = null;
+        else if (quiet === null) quiet = Date.now();
+        if (quiet !== null && Date.now() - quiet > 400) break;
+        await sleep(100);
+      }
+    }
+  }
+  // 30초를 다 기다렸는데도 화면을 불러오는 중이었다 — 진단으로 남긴다
+  return { navTimeout: !moved && !!(net && net.navPending()) };
+}
+
+/** 조작 뒤 불러오고 있는 요청 수. 웹소켓·스트림은 끝나지 않으니 뺀다 */
+function watchNet(page) {
+  const live = new Set();
+  const on = (r) => {
+    if (!["websocket", "eventsource", "media"].includes(r.resourceType())) live.add(r);
+  };
+  const off = (r) => live.delete(r);
+  page.on("request", on);
+  page.on("requestfinished", off);
+  page.on("requestfailed", off);
+  return {
+    busy: () => live.size,
+    /** 이 탭의 화면 자체를 불러오는 중인가(문서 요청). 개발 서버는 처음 여는 화면을 만드느라 10초를 넘긴다 */
+    navPending: () => [...live].some((r) => {
+      try {
+        return r.isNavigationRequest() && r.frame() === page.mainFrame();
+      } catch {
+        return false;
+      }
+    }),
+    stop() {
+      page.off("request", on);
+      page.off("requestfinished", off);
+      page.off("requestfailed", off);
+    },
+  };
+}
+
+/** 링크가 사이트 밖이면 그 호스트. www 만 다른 것은 같은 사이트다 */
+function offsiteHost(href, here) {
+  if (!href || !/^https?:\/\//i.test(href)) return null;
+  try {
+    const bare = (h) => h.replace(/^www\./, "");
+    const to = new URL(href);
+    return bare(to.host) === bare(new URL(here).host) ? null : to.host;
+  } catch {
+    return null;
+  }
+}
+
+/** 들어와서 처음 손대기까지. 훑는 사람은 금방, 읽는 사람은 한참 본다 */
+/**
+ * Playwright 의 클릭 오류를 사람이 겪는 말로. "elementHandle.click: Timeout 8000ms exceeded" 를 그대로 주면
+ * 방문자는 화면이 멈췄다고 읽는다(10/14 bluetags p4)
+ */
+function humanClickError(e) {
+  const m = String((e && e.message) || "");
+  if (/intercepts pointer events/.test(m)) return "something else on the screen is on top of it";
+  if (/not enabled|disabled/.test(m)) return "it is greyed out and does not respond";
+  if (/not visible|outside of the viewport/.test(m)) return "it is not visible on the screen right now";
+  if (/detached|not attached/.test(m)) return "no longer there";
+  return "nothing happened when you clicked it";
+}
+
+/** 파일 고르는 창. 사람에게는 컴퓨터의 파일 창이 뜬다 — 자동 브라우저에서는 조용히 사라져 "안 열린다" 가 된다(10/14 p24) */
+function fileWindowNote(fc) {
+  const accept = fc.accept || "";
+  const kind = /image/.test(accept) ? "an image" : /video/.test(accept) ? "a video" : /pdf/.test(accept) ? "a PDF" : "a file";
+  return `A window opened asking you to choose ${kind} from your device. You have nothing ready to pick for this visit, so you closed that window without choosing.`;
+}
+
+function firstLookMs(attention) {
+  const [lo, hi] = { skims: [800, 6000], reads: [2500, 15000], studies: [5000, 25000] }[attention] || [2500, 15000];
+  // 짧은 쪽에 몰리고 가끔 길다
+  return Math.round(lo + (hi - lo) * Math.pow(Math.random(), 1.8));
+}
+
+/** 한 방문 걸음 수의 절대 상한. 판단을 누가 하든 이 이상은 안 걷는다 */
+const HARD_STEP_CAP = 60;
+
+function stepPrompt() {
+  return fs.readFileSync(STEP_PROMPT_FILE, "utf8");
+}
+
+/** 지금 화면을 글로. 사람 소개 없이 화면만 — MCP 에이전트는 자기가 누구인지 이미 안다 */
+function renderScreen(look) {
+  const { view, text } = look;
+  return [
+    "## Where you are",
+    `- path: ${view.path}`,
+    `- scrolled ${view.scrollY} of ${Math.max(0, view.height - view.viewport)} px`,
+    "",
+    "## On the screen",
+    "```",
+    text,
+    "```",
+    "",
+    "## Things you can use (number · what it says · where)",
+    ...view.items.map((it) => `[${it.i}] ${it.label || "(no text)"}${it.href ? ` → ${it.href}` : ""}${it.dim ? " · looks greyed out" : ""}${it.edge ? " · cut off at the edge of the screen" : ""} · ${it.where}`),
+    // 화면 안에 있는데 목록에 못 넣은 것. "아래에 더 있다" 고 하면 내려 봐도 못 찾는다
+    // 화면 안에서 빠진 것과 지나온 위쪽에서 빠진 것을 따로 말한다 — 한 숫자로 말하면 "화면에 너무 많다" 가 거짓이 된다
+    ...(view.droppedInView
+      ? [view.droppedInView <= (view.droppedIcons || 0)
+          ? `(${view.droppedInView} more small icons or repeated images on this screen are not listed.)`
+          : `(${view.droppedInView} more things on this screen are not listed — there is too much in view.)`]
+      : view.dropped
+        ? [`(${view.dropped} more things further up the page are not listed — scroll up to use them.)`]
+        : []),
+    // 아래에 더 있다는 것만. 무엇인지는 내려 봐야 안다
+    ...(view.below
+      ? [`(The page goes on below. Scroll down to see what is there.)`]
+      : view.height - view.viewport - view.scrollY > 40
+        ? ["(There is more of the page below.)"]
+        : ["(This is the bottom of the page.)"]),
+  ].join("\n");
+}
+
+/**
+ * 그 사람이 누구인가. **두 길이 같은 글을 쓴다** — 우리 AI 의 걸음 판단(buildStepMessage)과
+ * MCP 의 `open_visit`(고객 Claude 서브에이전트가 받는 자기소개).
+ * 9/21 에 MCP 쪽이 이름만 받고 걸었다 — 목적도 상태도 모른 채 이름에 붙은 꼬리표로 짐작해 움직였다.
+ *
+ * @param card  카드를 다루는 쪽에도 쓰이나(설문 습관·쓰는 버릇까지). 걸음만 정할 때는 필요 없다
+ */
+const SURVEY_HABIT = {
+  ignores: "you usually ignore them",
+  sometimes: "you sometimes answer them",
+  willing: "you are usually happy to answer them",
+};
+
+function renderPerson(person, { card = false } = {}) {
+  const lines = [
+    `- on ${person.device}`,
+    `- ${person.background}`,
+    `- what you came for: ${person.goal}`,
+    `- right now: ${person.moment ?? "(not given)"}`,
+    `- you take in a page by: ${person.attention ?? "reads"}`,
+  ];
+  if (card) {
+    // 값이 동사 하나(ignores·sometimes·willing)라 그대로 끼우면 "you usually sometimes them" 이 됐다(10/14 실험실)
+    lines.push(`- survey cards that pop up: ${SURVEY_HABIT[person.surveyHabit] || SURVEY_HABIT.sometimes}`);
+    lines.push(`- when you type, you are ${person.writing ?? "careful"}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * @param visited  이번 방문에 들른 경로와 횟수 [{path, n}]. 최근 8걸음만 보여주면 앞에서 본 것을 잊고 같은 길을 돈다
+ *                 (9/21: 39걸음 동안 같은 네 쪽을 세 바퀴 돌았다). 고객 Claude(MCP)는 방문 전체를 기억하니 이 길에만 필요하다
+ */
+function buildStepMessage(person, siteAbout, view, history, pageText, visited = []) {
+  const lines = [
+    "## Website",
+    siteAbout,
+    "",
+    "## You",
+    renderPerson(person),
+    "",
+    renderScreen({ view, text: pageText }),
+    "",
+  ];
+  if (visited.length) {
+    lines.push("## Pages you have already been to on this visit (steps you spent there)");
+    visited.forEach((v) => lines.push(`- ${v.path} ×${v.n}`));
+    lines.push("");
+  }
+  if (history.length) {
+    lines.push("## What you have done so far");
+    if (history.length > 8) lines.push(`(${history.length - 8} earlier steps not shown)`);
+    history.slice(-8).forEach((h, i) => lines.push(`${i + 1}. ${h}`));
+    lines.push("");
+  }
+  lines.push("What do you do next?");
+  return lines.join("\n");
+}
+
+/**
+ * 한 방문의 몸. 사이트가 이미 열린 page 를 받는다.
+ * 순서: begin() → [ look() → (카드면 answer(), 아니면 act()) ]* → act({action:"leave"}) → (떠날 때 카드면 answer())
+ */
+class Visit {
+  /**
+   * @param person  people.js PERSON_FIELDS
+   * @param rhythm  persona.Rhythm (조작 사이 간격). 없으면 짧게 쉰다
+   * @param shape   persona.drawShape 가 뽑은 이번 방문 모양(튕김·훑기·깊게). 인내심 표시에 쓴다
+   * @param offsite 사이트 밖으로 가려던 주소가 쌓이는 배열(guard.js onOffsite 가 채운다)
+   */
+  constructor(page, person, { rhythm = null, shape = null, allowAccounts = false, policy = null, offsite = [], notSent = [], external = [], log = () => {} } = {}) {
+    this.page = page;
+    this.person = person;
+    /** 방문 시작 — 걸음마다 몇 초째인지(t) 적는다 */
+    this.t0 = Date.now();
+    this.rhythm = rhythm;
+    this.shape = shape;
+    this.allowAccounts = allowAccounts;
+    /** 고객이 정한 금지 구역(browser/policy.js). 누를 것·칠 것을 가린다 */
+    this.policy = policy;
+    this.offsite = offsite;
+    /** 사이트에 쓰려다 방어선이 끊은 요청(hub 가 채운다) */
+    this.notSent = notSent;
+    this.external = external;
+    // 알린 바깥 서버. 소켓은 몇 초마다 다시 붙으려 해서, 한 번만 알린다
+    this.externalTold = new Set();
+    /** 도구가 하지 못한 것들 — 방문이 끝나면 hub 가 서버로 보낸다(diag.js). 사이트 글자는 없다 */
+    this.diag = [];
+    this.log = log;
+    // 손은 방문 내내 이어진다 — 커서가 있던 자리에서 다음 곳으로 간다
+    this.handState = { rhythm, mouse: null };
+    this.steps = [];
+    this.history = [];
+    this.seenPaths = new Set();
+    this.card = null; // 처리한 카드(한 방문에 하나)
+    this.pending = null; // 떴는데 아직 답 안 한 카드
+    this.lastView = null; // act 의 번호는 마지막 look 의 화면 기준이다
+    this.lastAction = null;
+    /**
+     * 다음 조작을 해도 되는 때. **사람 박자는 여기서 정한다.**
+     * 전에는 조작 뒤에 쉬고 나서 화면을 돌려줬다 — 그 뒤 AI 가 생각하는 시간이 또 붙어 늘 8~30초 간격이 됐다
+     * (10/13 bluetags 105명, 첫 조작은 거의 다 3~4초). 이제 화면은 바로 돌려주고, 다음 조작 때 이 시각까지 기다린다.
+     * AI 가 더 오래 생각했으면 기다리지 않는다 — 간격은 둘 중 긴 쪽이다.
+     */
+    this.nextAt = 0;
+    this.ended = false;
+    this.sdk = null;
+    // 파일 고르는 창이 열렸나. 듣고 있으면 Playwright 가 창을 띄우지 않는다 — 고르지 않은 채 닫은 것과 같다
+    this.fileWindow = null;
+    page.on("filechooser", (fc) => {
+      this.fileWindow = { accept: "" };
+      fc.element()
+        .getAttribute("accept")
+        .then((a) => (this.fileWindow = { accept: a || "" }))
+        .catch(() => {});
+    });
+  }
+
+  /**
+   * **첫 걸음을 떼기 전에 SDK 가 붙기를 기다린다.**
+   * 광고·트래커가 많은 사이트는 SDK 가 늦게 붙는데, 그 사이의 조작은 기록에 안 남는다.
+   * 방문은 성공한 것처럼 끝나고 기록만 앞부분이 잘려서 **조용히 틀린 데이터**가 된다.
+   * (2026-09-21 사람인: goto 60초 타임아웃 뒤에 붙었다. 블루태그스는 로컬이라 빨라서 안 드러났다.)
+   */
+  async begin() {
+    this.sdk = await waitForSdk(this.page);
+    if (!this.sdk.ready) {
+      // 기다려도 안 붙었으면 이 방문의 기록은 못 믿는다. 조용히 넘기지 않는다
+      this.log(`⚠ The SDK did not start within ${Math.round(this.sdk.ms / 1000)}s — this visit's behaviour record will be empty or partial`);
+    } else if (this.sdk.ms > 3000) {
+      this.log(`SDK started after ${(this.sdk.ms / 1000).toFixed(1)}s`);
+    }
+    this.nextAt = Date.now() + firstLookMs(this.person.attention);
+    return this.sdk;
+  }
+
+  /** 이 화면을 보고 다음에 손대기까지. 새로 보이는 글이 많을수록 길다(persona.js Rhythm.gap) */
+  gapFor(view, text) {
+    if (!this.rhythm) return 1200;
+    const g = this.rhythm.gap({ sig: view.path, chars: text.length, media: 1, top: view.scrollY, vh: view.viewport, cmd: this.lastAction || "look" });
+    return Math.min(45000, Math.max(250, g.ms));
+  }
+
+  /** 정해 둔 때까지 기다린다. AI 가 그보다 오래 생각했으면 바로 간다 */
+  async waitTurn() {
+    const ms = this.nextAt - Date.now();
+    if (ms > 0) await sleep(ms);
+  }
+
+  /** 이번 방문에 걸었던 마음만큼 봤나. 여기서부터는 나갈 결심이 선다 */
+  get patienceSpent() {
+    return !!(this.shape && this.seenPaths.size > this.shape.screens && !this.card);
+  }
+
+  /**
+   * 지금 무엇이 보이나. 카드가 떠 있으면 카드부터 돌려준다 — 이게 이 방문의 산출물이다.
+   * **보이는 만큼만.** 글도 조작도 화면 안의 것이다 — 아래는 내려 봐야 안다.
+   * @returns { card } 또는 { view, text }
+   */
+  async look() {
+    if (this.ended) return { ended: true };
+    if (!this.card && !this.pending) {
+      const shown = await waitCard(this.page, 500);
+      if (shown) this.pending = shown;
+    }
+    // 카드 판단에는 페이지 전체를 준다 — 이 방문에서 본 것을 다 기억하는 사람이다
+    if (this.pending) return { card: this.pending, text: await screenText(this.page) };
+    const view = await listControls(this.page);
+    // 위쪽만 빠진 것은 넘침이 아니다 — 굴려 올리면 다시 나온다
+    if (view.droppedInView > (view.droppedIcons || 0)) this.diag.push({ kind: "controls_overflow", detail: `dropped ${view.droppedInView - (view.droppedIcons || 0)}` });
+    const text = await visibleText(this.page, 2500);
+    this.seenPaths.add(view.path);
+    this.lastView = view;
+    this.nextAt = Math.max(this.nextAt, Date.now() + this.gapFor(view, text));
+    return { view, text };
+  }
+
+  /**
+   * 카드에 답한다(또는 닫는다). decision 은 answer.js DECISION_SCHEMA 모양.
+   * 이유를 SDK 에 먼저 남긴 뒤 누른다 — SDK 가 보낼 때 읽는다.
+   */
+  async answer(decision) {
+    const shown = this.pending;
+    if (!shown) throw new Error("No card is showing");
+    const act = answer.toAction(decision, shown);
+    // 카드를 읽고 정하는 시간. 닫는 건 금방, 쓰는 건 치는 만큼
+    await sleep(act.kind === "close" ? 600 + Math.random() * 1800 : 1500 + Math.random() * 3000);
+    await noteReason(this.page, decision.bothered ? decision.why : decision.botheredWhy);
+    await answerCard(this.page, act).catch(() => {});
+    this.card = {
+      question: shown.question,
+      choices: shown.choices,
+      bothered: decision.bothered,
+      botheredWhy: decision.botheredWhy,
+      why: decision.why,
+      result: act.kind === "close" ? "close" : act.kind,
+      answer: act.kind === "choose" ? shown.choices[act.index] : act.kind === "other" ? act.text : null,
+      t: Date.now() - this.t0,
+      path: (() => {
+        try {
+          return new URL(this.page.url()).pathname;
+        } catch {
+          return null;
+        }
+      })(),
+    };
+    this.pending = null;
+    this.history.push(`A survey card appeared and you ${this.card.result === "close" ? "closed it" : "answered it"}.`);
+    this.log(`Card: ${this.card.result}${this.card.answer ? ` — ${this.card.answer}` : ""}`);
+    this.nextAt = Date.now() + 800 + Math.random() * 2500;
+    return this.card;
+  }
+
+  /**
+   * 한 걸음. decision 은 STEP_SCHEMA 모양({ why, action, index, text, done, times }).
+   * 번호는 마지막 look() 화면 기준이다. 떠나면 끝나고, 떠나는 순간 뜬 카드가 있으면 pending 에 남는다.
+   * 보고 있던 사이에 카드가 떴으면 하려던 걸 하지 않고 { interrupted: true } 를 돌려준다 — 카드부터 본다.
+   */
+  async act(decision) {
+    if (this.ended) throw new Error("This visit has already ended");
+    if (this.pending) throw new Error("A card is showing — answer or close it first");
+    await this.waitTurn();
+    if (!this.card) {
+      const c = await readCard(this.page);
+      if (c && c.visible) {
+        this.pending = c;
+        return { interrupted: true };
+      }
+    }
+    if (this.steps.length >= HARD_STEP_CAP) decision = { ...decision, action: "leave", why: `(${HARD_STEP_CAP}-step limit) ${decision.why}` };
+    const page = this.page;
+    const view = this.lastView || (await listControls(page));
+    const item = view.items[decision.index];
+    const record = { step: this.steps.length + 1, t: Date.now() - this.t0, path: view.path, action: decision.action, why: decision.why, label: item?.label ?? null };
+    const times = Math.max(1, Math.min(MAX_TIMES[decision.action] || 1, Math.round(Number(decision.times) || 1)));
+    if (times > 1) record.times = times;
+    const before = page.url();
+    const offsiteBefore = this.offsite.length;
+    const notSentBefore = this.notSent.length;
+    const externalBefore = this.external.length;
+    this.fileWindow = null;
+    this.lastAction = decision.action;
+
+    if (decision.action === "leave") {
+      record.done = !!decision.done;
+      this.steps.push(record);
+      this.log(`${record.step}. left — ${decision.why}`);
+      // 떠나는 모양도 사람처럼. 데스크톱은 커서가 창 위로 빠져나간다
+      if (this.person.device !== "mobile") {
+        await page.mouse.move(600, 120, { steps: 4 }).catch(() => {});
+        await page.mouse.move(600, 2, { steps: 6 }).catch(() => {});
+        await page.mouse.move(600, -8, { steps: 2 }).catch(() => {});
+      }
+      this.ended = true;
+      // 떠나려는 순간에 뜨는 카드가 있다. 모바일은 SDK 가 멈춤으로 대신 보므로 더 기다린다
+      if (!this.card) {
+        const parting = await waitCard(page, this.person.device === "mobile" ? 16000 : 6000);
+        if (parting) this.pending = parting;
+      }
+      return record;
+    }
+
+    const net = watchNet(page);
+    let diagEl = null; // 진단에 생김새를 남길 요소
+    if (decision.action === "read") {
+      // 가만히 읽는 시간. 사람은 계속 누르지 않는다 — 이게 없으면 "N초 머묾" 같은 조건이 영영 안 걸린다.
+      // 기다리는 건 다음 조작 때(waitTurn). 그 사이 카드가 뜨면 다음 조작 전에 본다
+      const base = { skims: 6000, reads: 14000, studies: 24000 }[this.person.attention ?? "reads"] ?? 14000;
+      record.readMs = Math.round(base * (0.6 + Math.random() * 0.8));
+      this.nextAt = Date.now() + record.readMs;
+    } else if (decision.action === "scroll" || decision.action === "scroll_up") {
+      // 훑으며 연달아 굴린다. 사이는 짧다 — 멈춰서 읽을 거면 따로 read 한다
+      record.scrolled = 0;
+      for (let i = 0; i < times; i++) {
+        if (i) await sleep(300 + Math.random() * 1500);
+        record.scrolled += await hand.scrollLikePerson(page, this.handState, decision.action === "scroll_up" ? -1 : 1);
+      }
+      await sleep(250);
+    } else if (decision.action === "back") {
+      await page.goBack({ waitUntil: "domcontentloaded" }).catch(() => {});
+      if ((await settle(page, before, net)).navTimeout) this.diag.push({ kind: "nav_timeout", action: "back" });
+    } else if (decision.action === "type") {
+      // 개인정보가 들어갈 칸(이메일·전화·카드 등)에는 치지 않는다. 고객 정책이 더 막거나 열 수 있다
+      const fieldOff = this.policy && this.policy.fieldBlocked(item?.label || "");
+      const el = fieldOff ? null : item ? await handleAt(page, decision.index) : null;
+      diagEl = el;
+      // 방문자에게는 사람의 선택으로 알린다. "field blocked by policy" 를 그대로 주면 방문자가 "칸이 입력을 안 받는다" 고
+      // 적어 사이트 결함처럼 읽혔다(10/14 실험실 p26, 비밀번호 찾기 이메일 칸)
+      if (fieldOff) record.personalField = item?.label ?? "";
+      else if (!el) record.skipped = "no longer there";
+      else {
+        // 칸을 먼저 누르고 친다. 칸에 남는 글자는 언제나 원래 치려던 것이다(오타는 스스로 고친다)
+        await hand.clickLikePerson(page, this.handState, el).catch((e) => (record.skipped = e.human ? `you could not get into that field: ${e.human}` : "you could not get into that field"));
+        // 칸에 전에 친 글이 남아 있으면 지우고 친다 — 사람은 새 검색어를 옛 것 뒤에 잇지 않는다.
+        // 안 지우면 "PolygonPolygon" 이 되고 그게 사이트 문제로 보고된다(10/13 bluetags 3명)
+        const typed = String(decision.text || "").slice(0, 80);
+        const value = await el.evaluate((n) => String(n.value ?? n.textContent ?? "")).catch(() => "");
+        const multiline = await el.evaluate((n) => n.tagName === "TEXTAREA" || n.isContentEditable).catch(() => false);
+        /**
+         * Enter 는 사람이 누를 때만. 여러 줄 칸(댓글·답글)에서 Enter 는 줄바꿈이고, 사람은 Post 를 누른다.
+         * 치는 대로 결과가 걸러지는 칸에서는 사람은 Enter 없이 결과를 본다 — 그 칸이 <form> 안이면 Enter 가 폼을 보내
+         * 페이지가 다시 열리고 검색이 사라졌다(10/15 실험실 x40, bluetags 커뮤니티 검색).
+         * 그때는 Enter 를 안 눌렀다고 알리고, 같은 글을 또 치면 Enter 만 누른다(추천 목록이 뜨는 검색칸에서 결과 화면으로 가려는 사람)
+         */
+        if (!multiline && typed && value === typed && this.heldEnter === typed) {
+          await page.keyboard.press("Enter").catch(() => {});
+          this.heldEnter = null;
+        } else {
+          if (value.length) {
+            // 칸에 전에 친 글이 남아 있으면 지우고 친다 — 사람은 새 검색어를 옛 것 뒤에 잇지 않는다.
+            // 안 지우면 "PolygonPolygon" 이 되고 그게 사이트 문제로 보고된다(10/13 bluetags 3명)
+            await page.keyboard.press("ControlOrMeta+A").catch(() => {});
+            await sleep(120 + Math.random() * 300);
+            await page.keyboard.press("Backspace").catch(() => {});
+            await sleep(150 + Math.random() * 350);
+          }
+          // 치기 전 화면. 치는 대로 걸러 주는 칸이면 친 뒤 화면이 이미 바뀌어 있다
+          const shownBefore = multiline ? "" : await visibleText(page, 2500);
+          record.typos = await hand.typeLikePerson(page, this.handState, typed).catch(() => 0);
+          let changed = false;
+          if (!multiline) {
+            await sleep(500 + Math.random() * 400);
+            const strip = (t) => t.split(typed).join("");
+            changed = strip(await visibleText(page, 2500)) !== strip(shownBefore);
+          }
+          if (!multiline && !changed) await page.keyboard.press("Enter").catch(() => {});
+          this.heldEnter = !multiline && changed ? typed : null;
+          if (this.heldEnter) record.heldEnter = true;
+        }
+        if ((await settle(page, before, net)).navTimeout) this.diag.push({ kind: "nav_timeout", action: "type" });
+        diagEl = el;
+      }
+    } else {
+      const blocked = item ? clickBlocked(item, { allowAccounts: this.allowAccounts, policy: this.policy }) : "that number is not on the screen";
+      if (blocked) record.skipped = blocked;
+      else {
+        const el = await handleAt(page, decision.index);
+        diagEl = el;
+        if (!el) record.skipped = "no longer there";
+        else {
+          // 같은 사이트를 새 탭으로 여는 링크는 이 탭에서 열게 한다. 사람은 열린 탭에서 이어 보고, 방문은 한 탭이다.
+          // 새 탭을 잡아 옮기는 건(hub) 브라우저가 새 탭을 늦게, 주소 없이 알려 줘서 놓쳤다 —
+          // 방문자는 "안 열린다" 를 보고 다시 누르면 "없어졌다" 가 됐다(10/14 실험실 p3, 첫 화면 카드)
+          await el
+            .evaluate((n) => {
+              const a = n.closest("a[target]");
+              if (a && a.target !== "_self" && a.href && new URL(a.href, location.href).origin === location.origin) a.target = "_self";
+            })
+            .catch(() => {});
+          // 사람 손이라 빗나갈 수 있다. 빈 곳을 누르면 아무 일도 안 일어난다 — 그게 헛클릭이다
+          const clicked = await hand
+            .clickLikePerson(page, this.handState, el)
+            .catch((e) => ((record.skipped = e.human || humanClickError(e)), { missed: false }));
+          if (clicked.missed) {
+            record.missed = true;
+            this.history.push("Your click landed just outside it and nothing happened.");
+          }
+          // 잘려 있던 것을 줄째 옆으로 밀어 가져와 눌렀다
+          if (clicked.swiped) record.swiped = true;
+          // 떠 있던 창 바깥(막)을 눌러 창이 닫혔다. 버튼에는 안 닿았다
+          if (clicked.closedOverlay && page.url() === before) {
+            record.closedOverlay = true;
+            this.history.push("Your click closed what was open on top of the page; it did not reach the thing you clicked.");
+          }
+          // 안 눌린다 싶어 거듭 누른다. 화면이 바뀌면 멈춘다
+          for (let i = 1; i < times && !record.skipped && this.handState.mouse; i++) {
+            await sleep(150 + Math.random() * 450);
+            if (page.url() !== before || this.offsite.length > offsiteBefore) break;
+            await page.mouse.click(this.handState.mouse.x, this.handState.mouse.y).catch(() => {});
+          }
+          if ((await settle(page, before, net)).navTimeout) this.diag.push({ kind: "nav_timeout", action: "click", shape: await diag.shapeOf(el) });
+        }
+      }
+    }
+
+    net.stop();
+
+    // 조작 뒤 탭이 빈 페이지(about:blank 등)가 됐다 — 앱을 여는 링크(kakaolink:, intent:, tel:)를 브라우저가 못 열 때 그렇다.
+    // 뒤로 가기로도 안 돌아와 방문자가 빈 화면에 갇혔다(10/15 실험실 p28, 모바일 공유 창). 원래 화면으로 돌려놓는다
+    if (/^https?:/i.test(before) && !/^https?:/i.test(page.url())) {
+      await page.goto(before, { waitUntil: "domcontentloaded", timeout: 30000 }).catch(() => {});
+      await page.waitForLoadState("networkidle", { timeout: 8000 }).catch(() => {});
+      record.openedApp = true;
+      this.diag.push({ kind: "left_to_blank", action: decision.action, shape: null });
+    }
+
+    // 사이트 밖으로 가는 링크였다. 끊었으니 방문자는 그대로 이 화면에 있다.
+    // 새 탭으로 여는 링크(target=_blank)는 방어선을 안 지나고 열린다 — 누른 링크 주소로도 본다(탭은 hub 가 닫는다)
+    const hrefOff = decision.action === "click" && !record.skipped ? offsiteHost(item?.href, before) : null;
+    if (this.offsite.length > offsiteBefore) {
+      try {
+        record.offsite = new URL(this.offsite[this.offsite.length - 1]).host;
+      } catch {
+        record.offsite = "another site";
+      }
+    } else if (hrefOff) record.offsite = hrefOff;
+
+    // 쓰려다 끊겼다. 방문자가 이걸 사이트가 안 된다로 읽지 않게 알린다
+    // 다른 화면으로 넘어갔으면 그 사이 끊긴 것은 화면을 열며 저절로 나간 것이다(읽음 표시·조회수) — 방문자가 보낸 게 아니다.
+    // 그걸 "저장·게시를 안 보냈다" 로 알리면 카드를 열었을 뿐인데 무엇을 보내려 한 줄 안다(10/14 실험실 p6, POST /api/bluecards/user-read).
+    // 기록에는 남긴다
+    if (this.notSent.length > notSentBefore) {
+      if (page.url() !== before) record.notSentQuiet = this.notSent.slice(notSentBefore);
+      else record.notSent = this.notSent.slice(notSentBefore);
+    }
+    const ext = [...new Set(this.external.slice(externalBefore))].filter((h) => !this.externalTold.has(h));
+    if (ext.length) {
+      ext.forEach((h) => this.externalTold.add(h));
+      record.external = ext;
+    }
+    if (this.fileWindow) record.fileWindow = fileWindowNote(this.fileWindow);
+    await this.noteDiag(record, decision, diagEl);
+
+    this.steps.push(record);
+    this.history.push(
+      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}`,
+    );
+    this.log(`${record.step}. ${decision.action}${item ? ` "${String(item.label).slice(0, 30)}"` : ""}${record.skipped ? ` · ${record.skipped}` : ""} — ${decision.why}`);
+    this.lastView = null;
+    return record;
+  }
+
+  /**
+   * 이 걸음에서 도구가 하지 못한 것을 진단에 남긴다. 글자는 넣지 않는다 — 종류와 요소의 생김새만
+   * 같은 것을 같은 자리에서 바로 또 눌렀다(화면이 안 바뀌었다)도 남긴다 — 사이트 탓일 수도, 우리가 못 본 것일 수도 있다
+   */
+  async noteDiag(record, decision, el) {
+    const kind = diag.kindOf(record.skipped);
+    const action = decision.action;
+    if (kind) this.diag.push({ kind, action, shape: await diag.shapeOf(el) });
+    if (record.swiped) this.diag.push({ kind: "swiped", action, shape: await diag.shapeOf(el) });
+    if (record.closedOverlay) this.diag.push({ kind: "popup_backdrop", action });
+    if (record.missed) this.diag.push({ kind: "missed", action });
+    const prev = this.steps[this.steps.length - 1];
+    if (action === "click" && !record.skipped && prev && prev.action === "click" && prev.label === record.label && prev.path === record.path && !prev.skipped)
+      this.diag.push({ kind: "reclick_same", action, shape: await diag.shapeOf(el) });
+  }
+
+  /** 카드 판단에 넘길 "이번 방문에 한 일" */
+  pathText() {
+    return this.history.length ? this.history.slice(-6).join(" / ") : "just arrived";
+  }
+
+  result() {
+    return { steps: this.steps, card: this.card, shape: this.shape };
+  }
+}
+
+/**
+ * 우리가 AI 에 물어 가며 한 방문을 끝까지 돈다(자동 실행).
+ * @param opts.ask  async (systemPrompt, jsonSchema, message) => object
+ * @returns { steps: [...], card: {...}|null, shape }
+ */
+async function runVisit(page, person, { siteAbout, ask, rhythm = null, shape = null, maxStepsCap = 40, allowAccounts = false, log = () => {} } = {}) {
+  /**
+   * 몇 쪽이나 볼지는 그 사람이 정한다. 방문 모양(shape)은 **인내심 표시**로만 쓰고 걸음 수로 자르지 않는다.
+   * 전에는 모양에서 걸음 상한을 뽑아(튕김이면 3걸음) 잘랐다 — 9/21 MCP 비교에서 8명 중 3명이
+   * "더 내려 볼게요" 하는 중에 잘려 떠나지도 못한 채 끝났다. MCP 길(고객 Claude)은 표시만 받으니 두 길의 규칙이 달랐다.
+   * 이제 둘 다 같다: 인내심 표시(`patienceSpent`) + 절대 상한(maxStepsCap, HARD_STEP_CAP).
+   */
+  const maxSteps = Math.min(maxStepsCap, HARD_STEP_CAP);
+  const v = new Visit(page, person, { rhythm, shape, allowAccounts, log });
+  await v.begin();
+
+  const decideCard = async (shown) => {
+    const screen = await screenText(page);
+    return ask(answer.systemPrompt(), answer.DECISION_SCHEMA, answer.buildMessage(person, siteAbout, v.pathText(), screen, shown));
+  };
+
+  for (let step = 1; step <= maxSteps && !v.ended; step++) {
+    const look = await v.look();
+    if (look.card) {
+      await v.answer(await decideCard(look.card));
+      continue;
+    }
+    if (v.patienceSpent) v.history.push("Your patience is running low. Unless what is in front of you is getting you closer to what you came for, this is about where you would give up.");
+    const counts = {};
+    for (const s of v.steps) counts[s.path] = (counts[s.path] || 0) + 1;
+    const visited = Object.entries(counts).map(([path, n]) => ({ path, n }));
+    const decision = await ask(stepPrompt(), STEP_SCHEMA, buildStepMessage(person, siteAbout, look.view, v.history, look.text, visited));
+    await v.act(decision);
+  }
+  // 떠나는 순간 뜬 카드
+  if (v.pending) {
+    const c = await v.answer(await decideCard(v.pending));
+    log(`Card (on leaving): ${c.result}${c.answer ? ` — ${c.answer}` : ""}`);
+  }
+  return v.result();
+}
+
+module.exports = { STEP_SCHEMA, STEP_PROMPT_FILE, HARD_STEP_CAP, stepPrompt, buildStepMessage, renderScreen, renderPerson, Visit, runVisit, settle, watchNet };