@usercase/mcp 0.2.11 → 0.2.12

package/agents/condition.md

@@ -2,7 +2,7 @@ A condition has a `page` (the screen the visitor is on when the card appears), `
 
 Step kinds (`do`): `arrive` · `back` · `click` · `input` · `submit` · `scroll` · `idle` · `hide` (tab hidden) · `error` (a JavaScript error).
 Options on a step: `page`, `from` (arrive/back), `target` (click/input/submit), `atLeast`, `percent` (scroll), `seconds` (idle: a pause between two actions), `cleared` (input: typed then deleted), `absent` (this did not happen between the previous step and the moment).
-Moment: `on_match` (as soon as the steps are met) · `idle` with `seconds` (then that long with no click, typing or page change; scrolling and reading still count as a pause) · `leave` (about to leave; on phones, a long pause instead).
+Moment: `on_match` (as soon as the steps are met) · `idle` with `seconds` (then that long with no click, typing or page change; scrolling and reading still count as a pause) · `leave` (when they leave that screen: moving to another page, closing the tab on a computer, or coming back from another tab; phones cannot tell when a tab closes). When the card shows on the next screen it carries the line "About the previous page", so a leave question should not say "this page" — name what they were looking at. With an absent click step, moving to another page never matches, because moving is a click.
 
 Globs: `*` matches anything including `/`; `:name` matches one path segment (`/project/:slug`). Use the route parameter names from the code. Never put `?` or `#` in a glob.
 

package/agents/fix.md

@@ -8,7 +8,7 @@ A Usercase research watched people (or virtual users) do tasks on this site. Its
 
 ## 1. Read the finding
 
-Call `report_finding` with the research id, the finding key and the report. If no finding key is given above, call `report_findings` first, show the user the list (key, severity, title, and whether someone is already fixing it), and ask which one to fix.
+Call `report_finding` with the research (its id, or the name the user gave — if the server lists several or none, ask the user which one), the finding key and the report. If no finding key is given above, call `report_findings` first, show the user the list (key, severity, title, and whether someone is already fixing it), and ask which one to fix.
 
 Read all of it: the title and why, who it hit, the screen checks (what the page really showed — these come from the recordings, not from opinions), the paths people took, the groups of what they wrote, and the suggested changes. The suggested changes were written without seeing the code; treat them as a direction, not a spec.
 

package/agents/new-research.md

@@ -40,6 +40,10 @@ Let the user pick one or change it.
 
 One research is **one flow a participant can walk in one sitting**: 1–4 tasks, about 5–10 minutes in all.
 
+**Purpose and hypotheses**
+- `purpose` is read by participants on the invite card and at the start. One or two sentences in their words on what they will help with. It never carries the evidence, the problem you suspect, or anything that hints at an answer.
+- `hypotheses` are for the team only. Write what you expect to go wrong, one per item, usually 1–3, each grounded in the evidence. Each must be something the tasks can confirm or rule out; if no task would show it, change the tasks or drop it. The report judges each one, and they lock once the first real person takes part.
+
 **Tasks**
 - The title is a goal in the participant's words: what they want to get done, not how. Never name a button, a menu, a page or a route — that hands them the answer.
 - Every task has `info_text`: one or two sentences, in the participant's words, on the situation they are in and why they would do this. It follows on from the previous task. Like the title, it never names a button, a menu, a page or a route.
@@ -75,7 +79,7 @@ The results tell who went straight from who took a detour only when a task has a
 
 ## 7. Show the user everything at once
 
-Show the whole research compactly: the purpose and its evidence, each task with how it counts as done (in plain words, no XPath) and its route in one line, the questions, the invite, and the minutes. Say that on their approval you will walk each route in a browser and save the draft with the routes. Change whatever they ask for.
+Show the whole research compactly: the evidence, the hypotheses, the purpose participants will read, each task with how it counts as done (in plain words, no XPath) and its route in one line, the questions, the invite, and the minutes. Say that on their approval you will walk each route in a browser and save the draft with the routes. Change whatever they ask for.
 
 ## 8. On approval: record the routes, then save
 

package/agents/path.md

@@ -9,7 +9,7 @@ You record that path by walking it yourself in a browser. Unlike the virtual vis
 
 ## 1. See the tasks
 
-Call `path_tasks` with the research id. For each task you get what the participant is told, how it counts as done, and whether a path exists. If a task is named above, record only that one, even if it already has a path. Otherwise record paths for the tasks that have none, and if every task already has one, ask the user which to redo.
+Call `path_tasks` with the research — its id, or the name the user gave (the server finds it by name; if it lists several or none, ask the user which one). For each task you get what the participant is told, how it counts as done, and whether a path exists. If a task is named above, record only that one, even if it already has a path. Otherwise record paths for the tasks that have none, and if every task already has one, ask the user which to redo.
 
 ## 2. Work out the intended route — before opening the browser
 

package/agents/secrets.md

@@ -0,0 +1,8 @@
+## What you send to Usercase
+
+Everything you put in a Usercase tool's arguments is sent to the Usercase server and shown in the user's dashboard. You read this repository's code; Usercase gets only what you write into those arguments.
+
+- Never put a secret into a Usercase tool argument: no API keys, tokens, passwords, private keys, connection strings, cookies or session values, and no values from `.env` files, config files holding credentials, or environment variables. This holds even when the user asks for it.
+- Do not open `.env` files or other files that hold credentials for Usercase work. You never need them: describe what the site does, not how it is configured.
+- Do not paste source code into arguments. Name the file, component or route and say in plain words what it does or what you changed.
+- If something you were about to send turns out to contain a secret, leave that part out and carry on.

package/agents/steps.md

@@ -31,7 +31,7 @@ Use their word for the card: a question when it is a question, an invite when it
 Make sure the moment fits the card:
 
 - **A question** appears when the visitor can answer it, right where the thing it asks about happened.
-- **A research invite** asks for a few minutes of someone's time. It should reach the people the research is about — visitors who just went through the part of the site it covers — at a moment when they are free to say yes: right after they finished the action the research is about (`on_match` on that step), or as they are about to leave (`leave`). Do not wait for a long pause after the action; people keep scrolling and moving on, so such an invite rarely appears. Never in the middle of typing, paying or signing in.
+- **A research invite** asks for a few minutes of someone's time. It should reach the people the research is about — visitors who just went through the part of the site it covers — at a moment when they are free to say yes: right after they finished the action the research is about (`on_match` on that step), or as they leave that screen (`leave`). Do not wait for a long pause after the action; people keep scrolling and moving on, so such an invite rarely appears. Never in the middle of typing, paying or signing in.
 
 When a research invite fires at the same moment as a live question, that is expected, not a conflict. A visitor sees only one card at a time and the question comes first; anyone who answers it is offered the research right after, in the same card, and the invite card reaches the visitors the question no longer reaches. Mention the overlap as information only. Never suggest turning a question off to make room for an invite.
 

package/agents/study.md

@@ -15,7 +15,7 @@ Show the user the tasks in one short list before casting, so they know what the
 **Step 3 — cast participants for this research.** Each person is someone who really comes to this site and who would accept this research's invitation — people its purpose is about. Their `goal` is still their own reason for being on the site, in their own words; **do not write the tasks into the goal or anywhere else**. The visitors read the tasks themselves in the study panel, as real participants do — a visitor told the task by you knows more than a participant would, and the research loses its value.
 - Vary them the way real participants vary: devices, how familiar they are with the site, patience, how carefully they read. Some will finish every task, some will get stuck — that is what the research is for.
 - Give each person a `landing` page where the research's invitation would meet them: the page the first task starts from, if the tasks or the code make it clear; otherwise where they would arrive on their own.
-- Pass `research: "{{research}}"` to `save_people`. Only people saved with it take part.
+- Pass `research` to `save_people` as the research **id** `path_tasks` showed (not a name). Only people saved with it take part.
 - Leave out `feature` spreading over the whole feature map — the research decides what the visit is about.
 
 **Step 4 — unchanged.** Each visitor accepts the invitation and agrees to the recording automatically (they are participants who said yes), then does the tasks from the study panel. Do not tell the visitors anything about the research.

package/mcp/hub.js

@@ -14,8 +14,9 @@ const persona = require("../src/persona/persona.js");
 const { personKey } = require("../src/persona/people.js");
 const entry = require("../src/run/entry.js");
 const { Visit, renderScreen, renderPerson } = require("../src/run/visit.js");
-const { iconPicture } = require("../src/browser/page.js");
-const { createGuard } = require("../src/browser/guard.js");
+const { iconPicture, screenPicture } = require("../src/browser/page.js");
+const crypto = require("crypto");
+const { createGuard, isSameSite } = require("../src/browser/guard.js");
 const policyMod = require("../src/browser/policy.js");
 const { loadRobots } = require("../src/browser/robots.js");
 const { launchBrowser, openVisit } = require("../src/browser/open.js");
@@ -63,6 +64,59 @@ const AGENT = "qa-explore";
 const MAX_OPEN = 5;
 /** 서브에이전트가 죽으면 방문이 열린 채 남는다. 이만큼 조용하면 닫는다 */
 const IDLE_MS = 10 * 60 * 1000;
+// 페이지를 새로 불러온 뒤 SDK 를 기다리는 시간. 스니펫은 load 뒤에 SDK 를 부른다
+const SDK_PAGE_WAIT_MS = 8000;
+
+/**
+ * 이 페이지에 Usercase SDK 가 있나 — 페이지마다 본다. waitForSdk(card.js)의 sessionStorage 는 같은 사이트의
+ * 앞 페이지에서 남아 있어 SDK 없는 페이지에서도 "있다" 가 된다. 스니펫이 세우는 표시(UsercaseInitialized,
+ * 이름 바꾸기 전 EarningbirdsInitialized)나 SDK 가 띄운 패널을 본다
+ */
+// 새 페이지에서 리서치 패널이 다시 뜨기를 기다리는 시간(같은 세션으로 다시 붙는 데 보통 1~2초)
+const STUDY_PANEL_WAIT_MS = 10000;
+/** 리서치 패널이 진행 중 상태로 뜨나 */
+async function waitStudyActive(page, ms) {
+  for (let t = 0; ; t += 400) {
+    const s = await study.readStudy(page).catch(() => null);
+    if (s && STUDY_ACTIVE.has(s.state)) return true;
+    if (t >= ms) return false;
+    await sleep(400);
+  }
+}
+
+async function pageHasSdk(page, ms = SDK_PAGE_WAIT_MS) {
+  for (let t = 0; ; t += 300) {
+    const ok = await page
+      .evaluate(() => !!(window.UsercaseInitialized || window.EarningbirdsInitialized || document.getElementById("eb-plugin")))
+      .catch(() => null);
+    if (ok) return true;
+    if (t >= ms) return ok === null ? null : false;
+    await sleep(300);
+  }
+}
+/** SDK 가 없던(missing) · 있는데 서버가 막은(not_connected) 페이지 주소를 방문에 남긴다. 쿼리 · 해시는 뺀다 */
+function noSdkPage(rec, kind) {
+  let url;
+  try {
+    const u = new URL(rec.page.url());
+    if (!/^https?:$/.test(u.protocol)) return;
+    url = u.origin + u.pathname;
+  } catch {
+    return;
+  }
+  rec.noSdkPages = rec.noSdkPages || [];
+  if (rec.noSdkPages.length < 20 && !rec.noSdkPages.some((p) => p.url === url)) rec.noSdkPages.push({ url, kind });
+}
+// 진행 중인 방문 — 걸음마다 디스크에 적는다. MCP 가 강제로 꺼져도(세션 종료) 다음에 켜질 때 끝나지 않은 방문으로 올린다
+const OPEN_DIR = require("path").join(ws.DIR, "open-visits");
+const pidAlive = (pid) => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+};
 
 /**
  * 쓰기를 허용할 경로(정규식, 쉼표로). 로그인 뒤 화면은 조회도 POST 로 하는 사이트가 많다(GraphQL 등).
@@ -104,6 +158,52 @@ class Hub {
     // 시작할 때 비밀값을 한 번 검사한다 — 잘못된 값이 방문 도중 조용히 넘어가지 않게
     this.keySet = !!agentKey();
     setInterval(() => this.sweep(), 60 * 1000).unref();
+    this.recoverOpen();
+  }
+
+  journalPath(rec) {
+    return require("path").join(OPEN_DIR, `${process.pid}-${rec.startedAt}-${rec.id}.json`);
+  }
+
+  /** 이 방문이 지금까지 한 것을 디스크에 적는다. 끝난 방문이면 지운다 */
+  journal(id) {
+    const rec = this.visits.get(id);
+    if (!rec) return;
+    try {
+      const file = this.journalPath(rec);
+      if (rec.closed) {
+        if (fs.existsSync(file)) fs.unlinkSync(file);
+        return;
+      }
+      fs.mkdirSync(OPEN_DIR, { recursive: true });
+      fs.writeFileSync(file, JSON.stringify({ pid: process.pid, row: this.visitRow(rec, { abandoned: true }), person: rec.person, startedAt: rec.startedAt }));
+    } catch {}
+  }
+
+  /** 지난번 MCP 가 끝내지 못한 방문(그 프로세스가 이미 없다) — 로컬 기록과 outbox 에 넣는다. 다음 방문이 끝날 때 대시보드로 간다 */
+  recoverOpen() {
+    let n = 0;
+    try {
+      if (!fs.existsSync(OPEN_DIR)) return;
+      for (const name of fs.readdirSync(OPEN_DIR)) {
+        const file = require("path").join(OPEN_DIR, name);
+        try {
+          const j = JSON.parse(fs.readFileSync(file, "utf8"));
+          if (j.pid && j.pid !== process.pid && pidAlive(j.pid)) continue;
+          ws.appendRun(j.row);
+          report.queueVisit(j.row, j.person, j.startedAt);
+          n++;
+        } catch {}
+        try {
+          fs.unlinkSync(file);
+        } catch {}
+      }
+    } catch {}
+    if (n) {
+      process.stderr.write(`Recovered ${n} visit(s) the last session did not finish — kept in the outbox for the dashboard
+`);
+      setTimeout(() => report.flushOutbox().catch(() => {}), 0);
+    }
   }
 
   browser() {
@@ -132,7 +232,7 @@ class Hub {
   arm(s) {
     s.policy = policyNow();
     // robots 는 나중에 읽는다(네트워크). 함수로 넘겨 읽히는 대로 반영되게
-    s.guard = createGuard({ site: s.origin, inject: this.inject, allowWritePaths: ALLOW_WRITE_PATHS, policy: s.policy, robots: () => s.robots });
+    s.guard = createGuard({ site: s.origin, inject: this.inject, allowWritePaths: ALLOW_WRITE_PATHS, policy: s.policy, robots: () => s.robots, robotsFor: (o) => this.robotsFor(s, o) });
   }
 
   /** 사이트에 쓰는 것을 보낼지. 사용자가 고른다 */
@@ -158,6 +258,23 @@ class Hub {
     return s.robots;
   }
 
+  /** 하위 도메인의 robots.txt — 처음 갈 때 한 번 읽는다. 사이트 것과 같은 머리로(자기를 밝힌다) */
+  robotsFor(s, origin) {
+    if (!s.subRobots) s.subRobots = new Map();
+    if (!s.subRobots.has(origin)) {
+      const key = agentKey();
+      const headers = { [AGENT_HEADER]: AGENT, "User-Agent": uaWith(AGENT, "Mozilla/5.0 (compatible)"), ...(key ? { [KEY_HEADER]: key } : {}) };
+      s.subRobots.set(
+        origin,
+        loadRobots(origin, { headers }).then((rb) => {
+          process.stderr.write(`${origin} ${rb.describe()}\n`);
+          return rb;
+        }),
+      );
+    }
+    return s.subRobots.get(origin);
+  }
+
   async context(s, opts = {}) {
     return openVisit(await this.browser(), playwright.devices, { agent: AGENT, site: s.origin, guard: s.guard, ...opts });
   }
@@ -290,6 +407,9 @@ class Hub {
 
   /** 가상 사용자 한 명의 방문을 연다. 그 사람이 누구인지와 첫 화면을 돌려준다 */
   async open(who) {
+    // 방문 기록이 요금제로 막혔다 — 브라우저를 더 띄우지 않는다(report.js)
+    const plan = report.planBlocked("visits");
+    if (plan) return { stop: true, text: report.planStopText(plan) };
     const doc = ws.loadPeople();
     if (!doc.site) throw new Error("people.json has no site. Create people with save_people first.");
     const p = doc.people.find((x) => x.id === who);
@@ -368,10 +488,8 @@ class Hub {
           }
           return;
         }
-        let same = false;
-        try {
-          same = new URL(u).origin === s.origin;
-        } catch {}
+        // 같은 사이트 — www · 하위 도메인까지(guard 와 같은 기준). 전에는 origin 이 똑같아야 해서 사이트 주소가 bluetags.app 이면 www 새 탭도 "다른 사이트" 였다
+        const same = isSameSite(s.origin, u);
         if (!same) return void offsite.push(u);
         // 같은 사이트를 새 탭으로 여는 링크. 사람은 열린 탭에서 이어 본다 — 닫기만 하면 "눌러도 안 열린다" 가 된다
         // (10/14 0.1.9 bluetags 프로젝트 카드 "See more" 가 target=_blank). 탭을 하나로 두려고 보던 탭을 그 주소로 옮긴다
@@ -408,8 +526,10 @@ class Hub {
     }
     const how = entry.chooseEntry(landingOff ? { ...p, landing: undefined } : p, links);
     if (landingOff) process.stderr.write(`${p.id}: landing ${p.landing} is off limits (${landingOff}) — entering elsewhere\n`);
-    const rec = { id, person: p, site: s, ctx, page, how, startedAt: Date.now(), touched: Date.now(), closed: false, visit: null };
+    const rec = { id, person: p, site: s, ctx, page, how, startedAt: Date.now(), touched: Date.now(), closed: false, visit: null, loads: 0, noSdk: [] };
     this.visits.set(id, rec);
+    // 페이지를 새로 불러올 때마다 센다 — 그 뒤에 SDK 가 그 페이지에도 있는지 본다(sdkGone)
+    page.on("load", () => rec.loads++);
 
     await page.goto(s.origin + how.path, { waitUntil: "domcontentloaded", referer: how.referer || undefined, timeout: 60000 }).catch(() => {});
     // 화면이 보여도 사이트 코드가 아직 안 붙었으면 버튼이 안 먹는다. 바로 상세·달력으로 들어오면 첫 클릭이 그렇게 사라졌다
@@ -442,6 +562,7 @@ class Hub {
     }
     rec.account = account ? account.account : null;
     rec.visit = new Visit(page, p, {
+      siteOrigin: s.origin,
       rhythm,
       shape,
       policy: s.policy,
@@ -495,8 +616,14 @@ class Hub {
       lines.push(
         "This study has a voice: you allowed your microphone, and a voice may talk to you during the study (you see its words as a caption). When it asks you something, you answer out loud — with answer_card.",
       );
-    if (!sdk.ready) lines.push("(note for whoever runs this: the Usercase SDK did not start on this page — this visit may not be recorded)");
+    if (!sdk.ready) {
+      lines.push("(note for whoever runs this: the Usercase SDK did not start on this page — this visit may not be recorded)");
+      rec.noSdk.push(pageName(rec));
+      const has = await pageHasSdk(page, 0);
+      if (has !== null) noSdkPage(rec, has ? "not_connected" : "missing");
+    }
     lines.push("", await this.screen(rec));
+    this.journal(id);
     return { id, text: lines.join("\n") };
   }
 
@@ -518,7 +645,7 @@ class Hub {
     // 사람은 막히면 계속 찾아본다. 그러다 실패 시간이 지나면 SDK 가 묻는 창을 띄우고, 다음 화면에서 그 창이 먼저 보인다
     // 브라우저 창(confirm 등)이 떠 있다. 페이지는 멈춰 있다 — 아이콘 그림·위치는 안 본다
     if (look.view.dialog) {
-      this.pictures.set(rec.id, null);
+      this.pictures.set(rec.id, []);
       return renderScreen(look);
     }
     const lines = [];
@@ -537,8 +664,23 @@ class Hub {
     lines.push(renderScreen(look));
     if (st && st.panel) lines.push("", st.panel);
     // 이름 없는 아이콘은 그림으로 같이 준다 — 좌표만으로는 사진 첨부와 보내기를 못 갈랐다(10/21 bluetags 2b72)
-    const pic = await iconPicture(v.page, look.view.items, await this.browser().catch(() => null)).catch(() => null);
-    this.pictures.set(rec.id, pic);
+    const browser = await this.browser().catch(() => null);
+    const pics = [];
+    // 화면 전체 그림. 글자 목록만으로는 사진·색·배치를 못 봐 "그림이 없다"·"색이 안 적혀 있다" 를 지어내고
+    // 생김새로 고르는 사람은 포기했다. 그림을 주니 사람처럼 골랐고 깨진 상품 이미지도 찾았다 — 걸음당 비용 +20%쯤(11/11 bluetags·데모 쇼핑몰 48방문).
+    // 지난번에 준 그림과 똑같으면 다시 안 준다(눌렀는데 그대로인 화면). 걸음마다 쌓여 다시 읽히는 몫이 크다
+    const shot = await screenPicture(v.page, browser).catch(() => null);
+    const sum = shot && crypto.createHash("sha1").update(shot).digest("hex");
+    if (shot && sum !== rec.lastShot) {
+      rec.lastShot = sum;
+      pics.push({ data: shot, mime: "image/jpeg" });
+      lines.push("(A small picture of the screen as you see it is attached. Use it to see the images, the layout and what stands out — the list above is still how you click.)");
+    } else if (shot) {
+      lines.push("(The screen looks the same as in your last picture.)");
+    }
+    const pic = await iconPicture(v.page, look.view.items, browser).catch(() => null);
+    if (pic) pics.push({ data: pic, mime: "image/png" });
+    this.pictures.set(rec.id, pics);
     if (pic) lines.push("(A picture of the unlabelled icons on this screen is attached — each is marked with its number from the list above. Look at their shapes the way a person would.)");
     // 인내심이 다 됐다는 단정이 아니라 조건이다. "볼 만큼 봤다" 고 하면 방문자가 그 자리에서 나갔다 — 진전이 있으면 이어 간다(10/14)
     // 리서치 참여자는 과제를 하러 왔다 — 둘러보다 지치는 인내심 표시는 맞지 않는다
@@ -755,10 +897,10 @@ class Hub {
   }
 
   /** 마지막 화면에 붙일 아이콘 그림. 한 번 가져가면 지운다(다음 화면은 새로 만든다) */
-  takePicture(id) {
-    const pic = this.pictures.get(id) || null;
+  takePictures(id) {
+    const pics = this.pictures.get(id) || [];
     this.pictures.delete(id);
-    return pic;
+    return pics;
   }
 
   get(id) {
@@ -771,6 +913,14 @@ class Hub {
 
   /** 한 걸음. 끝나면 기록하고 닫는다 */
   async act(id, decision) {
+    try {
+      return await this.step(id, decision);
+    } finally {
+      this.journal(id);
+    }
+  }
+
+  async step(id, decision) {
     const rec = this.get(id);
     const v = rec.visit;
     // 리서치 질문이 페이지를 덮고 있다 — 먼저 답해야 한다
@@ -790,7 +940,13 @@ class Hub {
     rec.lastAction = decision.action;
     const a0 = Date.now();
     v.lastWaitMs = 0;
+    const loadsBefore = rec.loads;
     const r = await v.act(decision);
+    // 새 페이지로 왔다 — 거기에도 SDK 가 있나. 리서치 참여 중인데 없으면 방문을 멈추고 알린다
+    if (rec.loads !== loadsBefore && !v.ended) {
+      const gone = await this.sdkGone(rec);
+      if (gone) return gone;
+    }
     if (TRACE) trace(rec, { ev: "act", action: decision.action, study: r && r.study, actMs: Date.now() - a0, waitTurnMs: v.lastWaitMs || 0, sdk: await sdkSnap(rec.page) });
     // 패널의 건너뛰기를 눌렀다 — 그 과제를 건너뛴 것으로 남긴다
     if (r && r.study === "skip" && !r.skipped && rec.study) rec.study.skipped.push(rec.study.lastTask);
@@ -837,8 +993,49 @@ class Hub {
     return [...said, ...(said.length ? [""] : []), shown].join("\n");
   }
 
+  /**
+   * 새로 불러온 페이지에 SDK 가 없다 — 그 페이지를 적는다. 리서치에 참여 중이면 거기서는 녹화도 과제 패널도 없어
+   * 더 다녀도 쓸 데이터가 안 나온다 → 방문을 멈추고 코디네이터가 사용자에게 알리게 한다. 리서치가 아니면 적기만 한다
+   * (걸음은 MCP 가 기록한다). @returns 방문자에게 줄 글(멈췄을 때), 아니면 null
+   */
+  async sdkGone(rec) {
+    const url = rec.page.url();
+    // 끝난 뒤 설문은 우리 설문 사이트 — SDK 가 없는 게 맞다. 시작 주소만이 아니라 그 사이트 전체를 뺀다
+    if (!/^https?:/.test(url) || study.isSurveyUrl(url) || /^https?:\/\/survey\.(usercase\.io|localhost)(:\d+)?\//i.test(url)) return null;
+    const has = await pageHasSdk(rec.page);
+    if (has === null) return null; // 페이지를 못 읽었다(이동 중) — 모르면 멈추지 않는다
+    const inStudy = !!rec.study && !rec.study.over;
+    // SDK 는 있는데 리서치 패널이 안 뜬다 — 서버가 이 도메인을 거절했다(프로젝트 도메인 설정에 없는 하위 도메인, 4003).
+    // 서버는 이유 없이 연결만 닫아서 페이지에서는 알 수 없다. 패널이 안 뜨면 studyLook 이 "과제가 다 끝났다" 로 잘못 읽었다(11/10 about.bluetags.app)
+    const notConnected = has === true && inStudy && !(await waitStudyActive(rec.page, STUDY_PANEL_WAIT_MS));
+    if (has === true && !notConnected) return null;
+    const where = pageName(rec);
+    const label = notConnected ? `${where} (the SDK is there but did not connect — is this domain allowed in the project's settings?)` : where;
+    if (!rec.noSdk.includes(label)) rec.noSdk.push(label);
+    noSdkPage(rec, notConnected ? "not_connected" : "missing");
+    if (!inStudy) return null;
+    const sum = await this.finish(rec, { stopped: notConnected ? "sdk_not_connected" : "no_sdk" });
+    return [
+      notConnected
+        ? `The Usercase SDK on this page (${where}) did not connect to the study — the study panel did not come back, so nothing is recorded here. This domain is probably not allowed in the project's settings. The visit was stopped.`
+        : `The Usercase SDK is not on this page (${where}), so the study cannot go on here — nothing is recorded and the study panel is gone. The visit was stopped.`,
+      "",
+      sum,
+      "",
+      "→ Reply to the coordinator with exactly the first line above, and stop.",
+    ].join("\n");
+  }
+
   /** 카드에 답하거나 닫는다 */
   async answer(id, decision) {
+    try {
+      return await this.answerCard(id, decision);
+    } finally {
+      this.journal(id);
+    }
+  }
+
+  async answerCard(id, decision) {
     const rec = this.get(id);
     if (rec.studyPending) return this.studyAnswer(rec, decision);
     const v = rec.visit;
@@ -854,10 +1051,8 @@ class Hub {
     return [done, "", await this.screen(rec)].join("\n");
   }
 
-  /** 방문을 닫고 기록을 남긴다. 사람 파일에 쓴 날을 적는다 */
-  async finish(rec, extra = {}) {
-    if (rec.closed) return "";
-    rec.closed = true;
+  /** 방문 기록 한 줄(runs · 대시보드) */
+  visitRow(rec, extra = {}) {
     const res = rec.visit ? rec.visit.result() : { steps: [], card: null, shape: null };
     const row = {
       at: new Date().toISOString(),
@@ -872,6 +1067,10 @@ class Hub {
       card: res.card,
       ms: Date.now() - rec.startedAt,
       sdkReady: rec.visit ? !!rec.visit.sdk?.ready : null,
+      // SDK 가 없던 페이지 — 거기서는 녹화도 리서치 패널도 없다. results 가 사용자에게 알리게 한다
+      ...(rec.noSdk && rec.noSdk.length ? { noSdk: rec.noSdk } : {}),
+      // 같은 것을 주소로 — 서버가 대시보드 Connection 체크리스트("스크립트 없음")에 쓴다
+      ...(rec.noSdkPages && rec.noSdkPages.length ? { noSdkPages: rec.noSdkPages } : {}),
       ...(rec.account ? { account: rec.account } : {}),
       // 리서치 참여 — 어느 과제까지 갔고, 무엇을 건너뛰고, 과제 질문에 무엇을 답했나. 참여 기록 자체는 SDK 가 서버에 올린다
       ...(rec.study
@@ -890,17 +1089,31 @@ class Hub {
       ...(rec.visit && rec.visit.diag && rec.visit.diag.length ? { diag: rec.visit.diag.map(({ kind, action, shape, detail }) => ({ kind, action, shape, detail })) } : {}),
       ...extra,
     };
-    ws.appendRun(row);
-    // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
-    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt, rec.visit ? rec.visit.screens : []).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
-    // 도구가 하지 못한 것들 — 우리 쪽 진단으로(화면·HTML 포함, 고객 대시보드에는 안 보인다). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
-    if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device, rec.visit.diagShots).catch(() => 0);
+    return row;
+  }
+
+  /** 사람 파일에 이 사람을 쓴 날을 적는다 */
+  markUsed(rec, at) {
     const doc = ws.loadPeople();
     const p = doc.people.find((x) => x.id === rec.person.id);
     if (p) {
-      p.usedAt = row.at;
+      p.usedAt = at;
       ws.savePeople(doc);
     }
+  }
+
+  /** 방문을 닫고 기록을 남긴다. 사람 파일에 쓴 날을 적는다 */
+  async finish(rec, extra = {}) {
+    if (rec.closed) return "";
+    rec.closed = true;
+    const row = this.visitRow(rec, extra);
+    ws.appendRun(row);
+    this.journal(rec.id);
+    // 대시보드로 — 키가 없으면 건너뛴다. 실패해도 방문은 끝낸다
+    const uploaded = await report.sendVisit(row, rec.person, rec.startedAt, rec.visit ? rec.visit.screens : []).catch((e) => `⚠ Could not upload to the dashboard (${e.message})`);
+    // 도구가 하지 못한 것들 — 우리 쪽 진단으로(화면·HTML 포함, 고객 대시보드에는 안 보인다). 기본으로 켜져 있다, USERCASE_DIAGNOSTICS=off 로 끈다
+    if (rec.visit && rec.visit.diag && rec.visit.diag.length) await report.sendDiagnostics(rec.visit.diag, rec.person.device, rec.visit.diagShots).catch(() => 0);
+    this.markUsed(rec, row.at);
     await new Promise((r) => setTimeout(r, 1500));
     await rec.ctx.close().catch(() => {});
     return [summarize(row), uploaded].filter(Boolean).join("\n");
@@ -1091,8 +1304,24 @@ class Hub {
     return lines.join("\n");
   }
 
+  /**
+   * MCP 가 꺼진다(세션 끝) — 곧 프로세스가 끝날 수 있다. 끝나지 않은 방문을 하나씩 finish 하면(올리기 · 1.5초 · 창 닫기)
+   * 첫 방문을 하는 사이에 끊겨 나머지는 기록조차 안 남았다(11/05 bluetags 74). 그래서 먼저 전부 디스크에 적고(runs · outbox),
+   * 그다음 한꺼번에 보낸다. 못 보낸 것은 다음 방문이 끝날 때 간다
+   */
   async close() {
-    for (const rec of this.visits.values()) if (!rec.closed) await this.finish(rec, { abandoned: true }).catch(() => {});
+    const open = [...this.visits.values()].filter((r) => !r.closed);
+    for (const rec of open) {
+      try {
+        rec.closed = true;
+        const row = this.visitRow(rec, { abandoned: true });
+        ws.appendRun(row);
+        report.queueVisit(row, rec.person, rec.startedAt);
+        this.journal(rec.id);
+        this.markUsed(rec, row.at);
+      } catch {}
+    }
+    if (open.length) await Promise.race([report.flushOutbox().catch(() => null), sleep(8000)]);
     if (this.browserP) await (await this.browserP).close().catch(() => {});
     if (this.loginBrowser) await this.loginBrowser.close().catch(() => {});
     if (this.loginReal) await this.loginReal.close().catch(() => {});
@@ -1228,6 +1457,17 @@ function studyLine(s) {
 }
 
 /** 방문 한 줄 요약 — 메인 에이전트가 모아서 사용자에게 보여준다 */
+/** 지금 페이지 — 사이트 안이면 경로, 하위 도메인이면 호스트까지 */
+function pageName(rec) {
+  try {
+    const u = new URL(rec.page.url());
+    const bare = (h) => h.replace(/^www\./, "");
+    return bare(u.host) === bare(new URL(rec.site.origin).host) ? u.pathname || "/" : u.host + u.pathname;
+  } catch {
+    return rec.page.url();
+  }
+}
+
 function summarize(row) {
   const last = row.steps[row.steps.length - 1];
   const card = row.card ? `Card "${row.card.question}" → ${row.card.result === "close" ? "closed" : row.card.answer}` : "No card";
@@ -1236,6 +1476,7 @@ function summarize(row) {
     row.pages?.length ? `Pages: ${row.pages.join(" → ")}` : "",
     card,
     row.study ? studyLine(row.study) : "",
+    row.noSdk && row.noSdk.length ? `⚠ Usercase SDK missing or not connected on: ${row.noSdk.join(", ")}${/^(no_sdk|sdk_not_connected)$/.test(row.stopped || "") ? " — the visit was stopped there" : " — not recorded there"}` : "",
     last ? `Last: ${last.action} — ${last.why}` : row.blocked ? "Stopped at a block page" : "",
   ]
     .filter(Boolean)

package/mcp/path.js

@@ -151,7 +151,7 @@ class PathRecorder {
     const cond = (t) =>
       t.condition === "url_entry" ? `done on reaching ${t.targetUrl || "(no page set)"}` : t.condition === "element_click" ? `done on clicking an element on ${t.xpathUrl || "?"}` : `done after ${t.timer}s`;
     return [
-      `Research "${r.research.title}" (${r.research.status})${r.research.website ? ` — site ${r.research.website}` : ""}`,
+      `Research "${r.research.title}" (${r.research.status}) — id ${r.research.id}${r.research.website ? ` — site ${r.research.website}` : ""}`,
       r.research.purpose ? `Purpose: ${r.research.purpose}` : "",
       "",
       ...r.tasks.map((t) =>

package/mcp/report.js

@@ -40,6 +40,43 @@ const setClient = (name) => {
 };
 const toolName = () => client || (process.env.USERCASE_CLIENT === "codex" ? "codex" : "claude-code");
 
+/**
+ * 요금제 한도 — 서버가 402 와 { code: "plan_limit", error, feature, upgradeUrl } 로 막는다.
+ * 401 은 키 문제(다시 연결)라 쓰지 않는다. 지금(11/10)은 다 무료라 아무것도 402 를 보내지 않지만,
+ * 고객 PC 의 MCP 는 오래 남으니 받는 쪽을 미리 둔다.
+ * 막힌 기능(feature, 없으면 "all")은 10분 동안 기억한다 — 그동안 새 방문을 열지 않는다. 결제하면 10분 뒤 다시 된다
+ */
+const PLAN_MEMORY_MS = 10 * 60 * 1000;
+const planBlocks = new Map();
+function planLimitError(status, json) {
+  const feature = (json && typeof json.feature === "string" && json.feature) || "all";
+  const info = {
+    feature,
+    message: (json && json.error) || "This needs a paid Usercase plan.",
+    upgradeUrl: (json && typeof json.upgradeUrl === "string" && json.upgradeUrl) || dashboardUrl("/"),
+    at: Date.now(),
+  };
+  planBlocks.set(feature, info);
+  return Object.assign(new Error(info.message), { status, planLimit: info });
+}
+/** 이 기능(또는 전체)이 최근에 요금제로 막혔으면 그 내용 */
+function planBlocked(feature) {
+  for (const k of [feature, "all"]) {
+    const b = planBlocks.get(k);
+    if (b && Date.now() - b.at < PLAN_MEMORY_MS) return b;
+    if (b) planBlocks.delete(k);
+  }
+  return null;
+}
+/** 에이전트에게 — 오류가 아니라 멈출 일이다. 우회 · 재시도 금지, 사용자에게 그대로 */
+const planStopText = (b) =>
+  [
+    `STOP — Usercase plan limit: ${b.message}`,
+    `Upgrade: ${b.upgradeUrl}`,
+    "",
+    "This is not an error to work around. Do not retry, do not try other tools, other ids or a different approach to get around it, and do not run more visits. Tell the user the message and the link above in your own words, then stop the current command.",
+  ].join("\n");
+
 /** @param key  이 키로 부른다(연결 API). 없으면 지금 쓰는 키 */
 async function call(method, route, body, timeoutMs = 15000, key) {
   const cur = key === undefined ? conn.current() : null;
@@ -56,6 +93,7 @@ async function call(method, route, body, timeoutMs = 15000, key) {
     json = JSON.parse(text);
   } catch {}
   if (!res.ok) {
+    if (res.status === 402 || (json && json.code === "plan_limit")) throw planLimitError(res.status, json);
     // 키가 거절됐다 — 연결로 받은 키면 지우고, 직접 넣은 키면 이번 세션엔 안 쓴다. 다음 호출이 브라우저 연결로 간다
     if (res.status === 401 && cur && cur.source !== "none") {
       conn.rejected(cur.source);
@@ -104,6 +142,8 @@ async function describeKey(sdkProject, retried = false) {
     const m = await getMe();
     if (sdkProject && m.projectId !== sdkProject)
       return `⚠ Connected to the "${m.title}" project, but the SDK on this site sends to another project (${sdkProject}). Visits and card answers would land in different projects. Call the \`connect\` tool to pick the right project`;
+    // 연결 전에 돈 방문이 남아 있으면 지금 올린다
+    if (readOutbox().length) await flushOutbox(m.projectId).catch(() => null);
     return connected || `✓ Connected — visits are sent to the "${m.title}" project. To use another project, call the \`connect\` tool`;
   } catch (e) {
     // 키가 거절됐다 — call 이 지웠으니 한 번만 다시(브라우저 연결로)
@@ -197,11 +237,42 @@ async function sendScreens(item, screens) {
  * @returns 요약에 붙일 한 줄, 키가 없으면 null
  */
 async function sendVisit(row, person, startedAt, screens = []) {
-  if (!KEY_RE.test(apiKey())) return null;
+  // 이 폴더가 아직 Usercase 프로젝트에 연결되지 않았다 — 전에는 말없이 건너뛰어 대시보드에 없는 줄 몰랐다(11/10).
+  // 버리지 않고 outbox 에 둔다. check_site 로 연결하면 그때 올라간다(사진은 다시 안 보낸다)
+  if (!KEY_RE.test(apiKey())) {
+    writeOutbox([...readOutbox(), { ...payload(row, person, startedAt), _project: null }]);
+    return NOT_CONNECTED_LINE;
+  }
   // 기록마다 어느 프로젝트로 가야 했는지 붙여 둔다 — 다시 연결하며 다른 프로젝트를 골라도 엉뚱한 곳에 들어가지 않게
   const project = await getMe().then((m) => m.projectId).catch(() => null);
   const fresh = { ...(await sendScreens(payload(row, person, startedAt), screens)), _project: project };
-  const queue = [...readOutbox(), fresh];
+  // 보내기 전에 outbox 에 먼저 적는다 — 보내는 도중 MCP 가 꺼져도 다음에 간다(서버는 같은 id 를 한 번만 받는다)
+  writeOutbox([...readOutbox(), fresh]);
+  return flushOutbox(project);
+}
+
+/**
+ * 방문 하나를 지금 바로 outbox 에 적는다(기다리지 않는다) — MCP 가 꺼지는 중이라 보낼 시간이 없을 수 있다.
+ * 프로젝트는 이미 알면 붙인다. 키가 없으면 false
+ */
+function queueVisit(row, person, startedAt) {
+  // 연결 전이어도 남긴다 — 연결하면 올라간다
+  writeOutbox([...readOutbox(), { ...payload(row, person, startedAt), _project: me ? me.projectId : null }]);
+  return KEY_RE.test(apiKey());
+}
+
+const NOT_CONNECTED_LINE = `⚠ Not sent to the dashboard — this folder is not connected to a Usercase project. The visit is kept in ${OUTBOX} and uploads once check_site connects this folder.`;
+
+/** 이 폴더가 Usercase 프로젝트에 연결돼 있나(키가 있나) */
+const connected = () => KEY_RE.test(apiKey());
+/** 아직 못 올린 방문 수 */
+const pendingCount = () => readOutbox().length;
+
+/** outbox 를 보낸다. 다른 프로젝트 것은 남긴다. @returns 요약에 붙일 한 줄, 키가 없으면 null */
+async function flushOutbox(project) {
+  if (!KEY_RE.test(apiKey())) return null;
+  if (project === undefined) project = await getMe().then((m) => m.projectId).catch(() => null);
+  const queue = readOutbox();
   const left = [];
   let sent = 0;
   let other = 0;
@@ -225,6 +296,7 @@ async function sendVisit(row, person, startedAt, screens = []) {
   writeOutbox(left);
   const otherLine = other ? ` · ${other} from another project kept in ${OUTBOX} until you connect that project again` : "";
   if (left.length === other) return `· Sent to the dashboard${sent > 1 ? ` (${sent} including earlier ones)` : ""}${otherLine}`;
+  if (lastErr && lastErr.planLimit) return `⛔ Not uploaded — ${planStopText(lastErr.planLimit)}\n(${left.length - other} kept in ${OUTBOX}; they upload once the plan allows it.)`;
   return `⚠ Could not upload to the dashboard (${lastErr?.status === 401 ? "connection rejected — run check_site to connect again" : lastErr?.message}) — ${left.length - other} kept in ${OUTBOX}, will retry next time${otherLine}`;
 }
 
@@ -313,6 +385,10 @@ module.exports = {
   reconnect,
   getInstall,
   sendVisit,
+  connected,
+  pendingCount,
+  queueVisit,
+  flushOutbox,
   sendDiagnostics,
   getResearchTasks,
   savePath,
@@ -330,5 +406,7 @@ module.exports = {
   getIssues,
   getIssue,
   saveIssueFix,
+  planBlocked,
+  planStopText,
   dashboardUrl,
 };

package/mcp/server.js

@@ -26,7 +26,19 @@ const peopleRules = require("../src/persona/people.js");
 const { PathRecorder, patternOf } = require("./path.js");
 
 const hub = new Hub();
-const server = new McpServer({ name: "usercase", version: require("../package.json").version });
+// 서버 안내문 — 도구 설명과 달리 AI 에게 처음부터 보인다(Claude Code 는 MCP 도구를 이름만 보여 주고 설명은 찾아야 보인다).
+// 말로 부탁받았을 때 지시문(instructions 도구)부터 받게 한다. 11/10 시험: 안내문 없이 "방문자한테 물어볼 질문 만들어줘" → Usercase 를 안 쓰고 대화로 질문만 썼다
+const server = new McpServer(
+  { name: "usercase", version: require("../package.json").version },
+  {
+    instructions:
+      "Usercase is connected: virtual users that visit this site, research with real visitors, and questions shown to visitors on the site. " +
+      "When the user asks for any of these — in a command or in their own words — call the Usercase `instructions` tool first with the matching command and follow what it returns: " +
+      "test or get feedback on the site with virtual users (research); plan or create a research or usability study (new-research); add or install Usercase on the site (install); " +
+      "make a question to ask visitors (question); write the steps for the question open in the dashboard (steps); record the paths of a research's tasks (path); " +
+      "fix a finding from a research report or an issue from Issues (fix); connect this repository to another Usercase project (connect).",
+  },
+);
 
 // Claude Code 플러그인(plugin/)으로 떴는지. 플러그인의 .mcp.json 이 USERCASE_PLUGIN=1 을 준다.
 // 플러그인에서는 방문자 에이전트가 플러그인에 들어 있어 이름이 usercase:usercase-visitor 이고(도구도 mcp__plugin_usercase_usercase__*),
@@ -45,14 +57,18 @@ const cmd = (name) => (CODEX ? `$usercase:${name}` : PLUGIN ? `/usercase:${name}
 const SPAWN = CODEX ? " (with `fork_turns` set to `none`, so it starts without this conversation)" : "";
 
 const text = (t) => ({ content: [{ type: "text", text: String(t) }] });
-/** 방문 화면 + 그 화면의 이름 없는 아이콘 그림(있으면). 방문자는 그림을 보고 모양으로 안다 */
+/** 방문 화면 + 그 화면의 그림들(화면 전체·이름 없는 아이콘, 있으면). 방문자는 그림을 보고 사람처럼 안다 */
 const screen = (t, visitId) => {
-  const pic = visitId ? hub.takePicture(visitId) : null;
   const out = text(t);
-  if (pic) out.content.push({ type: "image", data: pic.toString("base64"), mimeType: "image/png" });
+  for (const p of visitId ? hub.takePictures(visitId) : []) out.content.push({ type: "image", data: p.data.toString("base64"), mimeType: p.mime });
   return out;
 };
-const fail = (e) => ({ content: [{ type: "text", text: `Error: ${e.message}` }], isError: true });
+// 요금제 한도(402)는 오류가 아니라 멈출 일 — 우회하지 말고 사용자에게 그대로 (report.js planLimitError)
+/** 말로 부탁받은 AI 가 지시문을 건너뛰고 바로 부르는 도구들 — 지시문(instructions)부터 읽게 한다(11/10 시험: 고쳐줘 → issue_read 로 바로 갔다) */
+const PROC = (c) => ` If you have not read the ${c} procedure yet, call the instructions tool with command ${c} first.`;
+/** 리서치는 id 또는 이름 — 말로 부탁하면 이름이 온다. 서버가 이름으로 찾는다(11/10) */
+const RESEARCH_REF = "The research id, or its name as the user said it (the server finds it by name; if several or none match, it lists them — ask the user which one)";
+const fail = (e) => ({ content: [{ type: "text", text: e && e.planLimit ? report.planStopText(e.planLimit) : `Error: ${e.message}` }], isError: true });
 const wrap = (fn) => async (args) => {
   try {
     return await fn(args);
@@ -67,7 +83,7 @@ server.registerTool(
   "check_site",
   {
     description:
-      "Open the site once as a virtual user and report: does it load, is the Usercase SDK running (which project), is a firewall/bot protection blocking us (and how to unblock, per vendor), is the secret key set. Always run this before starting visits. If it reports a block, stop and tell the user.",
+      "Open the site once as a virtual user and report: does it load, is the Usercase SDK running (which project), is a firewall/bot protection blocking us (and how to unblock, per vendor), is the secret key set. Always run this before starting visits. If it reports a block, stop and tell the user." + PROC("research"),
     inputSchema: { url: z.string().url().describe("The site to test, e.g. https://staging.example.com") },
   },
   wrap(async ({ url }) => text(await hub.checkSite(url))),
@@ -90,7 +106,7 @@ server.registerTool(
   "install_snippet",
   {
     description:
-      "Get the Usercase script for the connected project, with where to put it per framework. If nothing is connected yet, it opens the browser to connect and says what to tell the user. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked.",
+      "Get the Usercase script for the connected project, with where to put it per framework. If nothing is connected yet, it opens the browser to connect and says what to tell the user. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked." + PROC("install"),
     inputSchema: {},
   },
   wrap(async () => {
@@ -184,7 +200,7 @@ server.registerTool(
       research: z
         .string()
         .optional()
-        .describe("Only when the run takes part in a research (the research command's research id): everyone saved in this call takes part in it"),
+        .describe("Only when the run takes part in a research — its id, as path_tasks shows it: everyone saved in this call takes part in it"),
     },
   },
   wrap(async ({ site, site_about, people, research }) => {
@@ -242,9 +258,18 @@ server.registerTool(
     const rows = ws.recentRuns(limit);
     const { summarize } = require("./hub.js");
     const lines = rows.map((r) => summarize(r)).join("\n\n");
+    // SDK 가 없던 페이지 — 사이트 설정 문제라 사용자에게 알린다(도구 문제가 아니다)
+    const noSdk = [...new Set(rows.flatMap((r) => r.noSdk || []))];
+    const sdkLine = noSdk.length
+      ? `⚠ Pages where the Usercase SDK was missing or did not connect: ${noSdk.join(", ")}. Visits are not recorded there, and research visits that reached one were stopped. Tell the user this in plain words: where the script is missing, adding the Usercase script to those pages (or that subdomain) fixes it; where it did not connect, add that domain to the project's allowed domains in Usercase settings (a wildcard such as *.example.com covers every subdomain).`
+      : "";
+    // 이 폴더가 연결되지 않아 대시보드에 안 올라간 방문 — 사용자는 대시보드에서 찾다가 없는 줄 안다(11/10)
+    const keyLine = !report.connected() && report.pendingCount()
+      ? `⚠ This folder is not connected to a Usercase project, so ${report.pendingCount()} visit(s) are not on the dashboard yet (kept locally). Tell the user, and run check_site to connect — they upload as soon as it is connected.`
+      : "";
     const st = hub.status();
     const next = runStatus();
-    return text([lines || "No visits yet.", st ? `\n---\n${st}` : "", next ? `\n---\n${next}` : ""].join("\n"));
+    return text([lines || "No visits yet.", keyLine ? `\n---\n${keyLine}` : "", sdkLine ? `\n---\n${sdkLine}` : "", st ? `\n---\n${st}` : "", next ? `\n---\n${next}` : ""].join("\n"));
   }),
 );
 
@@ -409,7 +434,7 @@ const QCondition = z.object({
   page: z.string().describe("Path glob of the screen the visitor is on when the question appears"),
   steps: z.array(QStep).describe("What happened, in order. Other actions may happen in between"),
   moment: z.object({
-    type: z.enum(["on_match", "idle", "leave"]).describe("on_match = as soon as the steps are met · idle = after that, N seconds with no click, typing or page change (scrolling still counts as a pause) · leave = when about to leave"),
+    type: z.enum(["on_match", "idle", "leave"]).describe("on_match = as soon as the steps are met · idle = after that, N seconds with no click, typing or page change (scrolling still counts as a pause) · leave = when they leave that screen: moving to another page, closing the tab on a computer, or coming back from another tab (phones cannot tell a tab closing)"),
     seconds: z.number().optional(),
   }),
 });
@@ -438,7 +463,7 @@ server.registerTool(
   "question_context",
   {
     description:
-      "Screens and element words from this project's recent real visits. Call first in the question procedure, before writing a condition — page globs and click targets must match what visitors actually saw.",
+      "Screens and element words from this project's recent real visits. Call first in the question procedure, before writing a condition — page globs and click targets must match what visitors actually saw." + PROC("question"),
     inputSchema: {},
   },
   wrap(async () => {
@@ -507,7 +532,7 @@ server.registerTool(
 server.registerTool(
   "steps_brief",
   {
-    description: "What is in the user's Several steps window: whether the card is a question or a research invite, the page under Where, and the words they wrote. Call first in the steps procedure.",
+    description: "What is in the user's Several steps window: whether the card is a question or a research invite, the page under Where, and the words they wrote. Call first in the steps procedure." + PROC("steps"),
     inputSchema: { session: z.string().describe("The window id from the dashboard command") },
   },
   wrap(async ({ session }) => {
@@ -565,8 +590,8 @@ server.registerTool(
   "report_findings",
   {
     description:
-      "List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key.",
-    inputSchema: { research: z.string().describe("The research id"), audience: audienceArg },
+      "List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key." + PROC("fix"),
+    inputSchema: { research: z.string().describe(RESEARCH_REF), audience: audienceArg },
   },
   wrap(async ({ research, audience }) => {
     const r = await report.getReport(research, audience);
@@ -589,8 +614,8 @@ server.registerTool(
   "report_finding",
   {
     description:
-      "Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code.",
-    inputSchema: { research: z.string().describe("The research id"), finding: z.string().describe("Finding key, e.g. F1"), audience: audienceArg },
+      "Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code." + PROC("fix"),
+    inputSchema: { research: z.string().describe(RESEARCH_REF), finding: z.string().describe("Finding key, e.g. F1"), audience: audienceArg },
   },
   wrap(async ({ research, finding, audience }) => {
     const r = await report.getFinding(research, finding, audience);
@@ -630,7 +655,7 @@ server.registerTool(
     description:
       "Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). If the last fix of this finding is already live on the site, this starts the next fix (fix 2, 3 …); otherwise it adds to the current one. The report compares people after each fix goes live with the version right before it.",
     inputSchema: {
-      research: z.string().describe("The research id"),
+      research: z.string().describe(RESEARCH_REF),
       finding: z.string().describe("Finding key, e.g. F1"),
       audience: audienceArg,
       status: z.enum(["fixing", "fixed"]),
@@ -652,7 +677,7 @@ const issueFixLine = (f) => (f ? ` — ${f.status === "fixed" ? "fixed" : "being
 server.registerTool(
   "issue_list",
   {
-    description: "List the open issues of the Usercase project (problems found from visitors' answers to questions on the site): id, title, where, whether it is a clear fix, and whether one is being fixed. Use when the fix command has no issue id.",
+    description: "List the open issues of the Usercase project (problems found from visitors' answers to questions on the site): id, title, where, whether it is a clear fix, and whether one is being fixed. Use when the fix command has no issue id." + PROC("fix"),
     inputSchema: {},
   },
   wrap(async () => {
@@ -675,7 +700,7 @@ server.registerTool(
   "issue_read",
   {
     description:
-      "Read one issue of the Usercase project with all its evidence: the question and page, what people chose, what they wrote, the AI's reading, other issues with the same cause, and earlier fixes. Read it before looking for the code.",
+      "Read one issue of the Usercase project with all its evidence: the question and page, what people chose, what they wrote, the AI's reading, other issues with the same cause, and earlier fixes. Read it before looking for the code." + PROC("fix"),
     inputSchema: { issue: z.string().describe("The issue id, as in the dashboard command") },
   },
   wrap(async ({ issue }) => {
@@ -728,8 +753,8 @@ server.registerTool(
 server.registerTool(
   "path_tasks",
   {
-    description: "List the tasks of a Usercase research (from the dashboard) and whether each already has an expected path. Call first in the path procedure.",
-    inputSchema: { research: z.string().describe("The research id, as shown in the dashboard command") },
+    description: "List the tasks of a Usercase research (from the dashboard) and whether each already has an expected path. Call first in the path procedure." + PROC("path"),
+    inputSchema: { research: z.string().describe(RESEARCH_REF) },
   },
   wrap(async ({ research }) => {
     const out = await recorder.tasks(research);
@@ -829,7 +854,7 @@ server.registerTool(
   "research_context",
   {
     description:
-      "What this project's data says is worth researching: open findings, where real visitors and virtual users left, what virtual users said when they left without getting what they came for, and the researches and drafts that already exist. Call first in the new-research procedure.",
+      "What this project's data says is worth researching: open findings, where real visitors and virtual users left, what virtual users said when they left without getting what they came for, and the researches and drafts that already exist. Call first in the new-research procedure." + PROC("new-research"),
     inputSchema: {},
   },
   wrap(async () => {
@@ -873,7 +898,8 @@ server.registerTool(
       "Save the research as a DRAFT in the dashboard Inbox, after the user approved it. It becomes a research only when someone creates it there. Paths are page paths starting with / (no host), with :name for the parts that change. Expected paths recorded and saved beforehand as plan-<n> (n = the task's position in tasks, from 1) are uploaded with it.",
     inputSchema: {
       title: z.string().describe("Short, for the team"),
-      purpose: z.string().describe("What the team wants to learn and why — the evidence it came from"),
+      purpose: z.string().describe("Shown to participants (invite card and start of the study): one or two sentences, in their words, on what they will help with. Never the team's evidence, suspicions or hypotheses"),
+      hypotheses: z.array(z.string()).max(5).optional().describe("Team only, never shown to participants: what the team expects to go wrong, one per item, 1–3 usually. The report judges each one. Each must be something these tasks can confirm or rule out"),
       start_screen: z.object({ title: z.string(), subtitle: z.string() }).optional().describe("What participants read before the first task"),
       tasks: z
         .array(
@@ -1143,7 +1169,7 @@ const COMMANDS = {
       research: z
         .string()
         .optional()
-        .describe("A research id from the dashboard: the people take part in that research — its tasks and questions — instead of exploring freely"),
+        .describe("A research from the dashboard (its id, or its name): the people take part in that research — its tasks and questions — instead of exploring freely"),
     },
     body: ({ url, count, focus, research }) => {
       const plan = researchPlan(count);
@@ -1193,10 +1219,10 @@ const COMMANDS = {
   path: {
     description: "Record the expected path of a Usercase research's tasks",
     // 대시보드 과제 화면의 명령은 과제 id 를 붙인다 — 그 과제만, 경로가 있어도 다시
-    argsSchema: { research: z.string().optional(), task: z.string().optional() },
+    argsSchema: { research: z.string().optional().describe(RESEARCH_REF), task: z.string().optional() },
     body: ({ research, task }) =>
       doc("path.md")
-        .replace("{{research}}", research || "(ask the user — the dashboard shows it)")
+        .replace("{{research}}", research || "(not given — ask the user which research; its name is enough)")
         .replace("{{task}}", task ? `Task: ${task} — record this task only, and record it again even if it already has a path.` : "Task: all tasks of the research"),
   },
   // 인자를 두지 않는다 — Claude Code 는 명령어 인자를 공백으로 나눠 문장을 못 싣는다. 무엇을 물을지는 대화로 묻는다
@@ -1228,7 +1254,7 @@ const COMMANDS = {
   fix: {
     description: "Fix a finding from a Usercase research report, or an issue from Issues, in this repository's code",
     argsSchema: {
-      research: z.string().optional(),
+      research: z.string().optional().describe(RESEARCH_REF),
       finding: z.string().optional(),
       audience: z.string().optional(),
       issue: z.string().optional().describe("An issue id from the dashboard's Issues — fixes that issue instead of a report finding"),
@@ -1238,7 +1264,7 @@ const COMMANDS = {
       issue || String(research || "").trim().toLowerCase() === "issue"
         ? agentDoc("fix-issue.md", { issue: String(issue || "").trim() || "(not given — list the open issues and ask)", research_cmd: cmd("research") })
         : agentDoc("fix.md", {
-        research: research || "(ask the user — the dashboard Report shows the command)",
+        research: research || "(not given — ask the user which research; its name is enough)",
         finding: finding ? String(finding).toUpperCase() : "(not given — list the findings and ask)",
         audience: audience === "real" ? "real (the report of real people)" : "virtual (the report of virtual users)",
         check:
@@ -1254,12 +1280,31 @@ const COMMANDS = {
   },
 };
 
-if (PLUGIN || CODEX || OTHER) {
+// 코드를 읽는 명령은 모두 끝에 "Usercase 로 무엇을 보내는가" 규칙을 붙인다 — 에이전트가 읽은 키·.env 값을 도구 인자에 실어
+// 우리 서버로 보내지 않게. 명령마다 따로 쓰면 빠지는 데가 생겨 한 벌(agents/secrets.md)만 둔다. connect 는 코드를 안 읽는다
+const NO_SECRETS = new Set(["connect"]);
+const commandText = (name, args) => {
+  const c = COMMANDS[name];
+  const body = c.body(byName(args, c.argsSchema)).trimEnd();
+  return NO_SECRETS.has(name) ? body : `${body}\n\n${doc("secrets.md").trim()}\n`;
+};
+
+// 지시문은 어느 연결에서든 도구로도 준다. 사용자는 명령 대신 말로("새 리서치 만들어줘") 부탁하는데, AI 는 프롬프트를 스스로 열지 못한다 —
+// 플러그인 없이 붙인 Claude Code 에서 말로 부탁하면 지시문 없이 도구를 짐작으로 불렀다(11/10 시험). 프롬프트(/mcp__usercase__이름)는 그대로 둔다
+{
   server.registerTool(
     "instructions",
     {
       description:
-        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect, fix — a report finding, or an issue with `issue`). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
+        "Start here for any Usercase work — whether the user typed a command or just asked in their own words. Returns the step-by-step procedure; follow it as the user's request, and call this before the other Usercase tools. Commands: " +
+        "research (test or get feedback on the site with virtual users; `research` id to have them take part in a research), " +
+        "new-research (plan or create a research / usability study), " +
+        "install (add or install the Usercase script on the site), " +
+        "question (make a question to ask visitors at a moment on the site), " +
+        "steps (write the steps for the question open in the dashboard; `session` = its window id), " +
+        "path (record the expected paths of a research's tasks; `research` id, optional `task`), " +
+        "fix (fix a finding from a research report: `research` id + `finding` key like F1, `audience` real for the real-people report; or an issue from Issues: `issue` id), " +
+        "connect (connect this repository to another Usercase project).",
       inputSchema: {
         command: z.enum(Object.keys(COMMANDS)),
         ...COMMANDS.research.argsSchema,
@@ -1268,12 +1313,13 @@ if (PLUGIN || CODEX || OTHER) {
         ...COMMANDS.fix.argsSchema,
       },
     },
-    wrap(async ({ command, ...args }) => text(COMMANDS[command].body(byName(args, COMMANDS[command].argsSchema)))),
+    wrap(async ({ command, ...args }) => text(commandText(command, args))),
   );
-} else {
+}
+if (!(PLUGIN || CODEX || OTHER)) {
   for (const [name, c] of Object.entries(COMMANDS)) {
     const meta = c.argsSchema ? { description: c.description, argsSchema: c.argsSchema } : { description: c.description };
-    server.registerPrompt(name, meta, (args = {}) => ({ messages: [{ role: "user", content: { type: "text", text: c.body(byName(args, c.argsSchema)) } }] }));
+    server.registerPrompt(name, meta, (args = {}) => ({ messages: [{ role: "user", content: { type: "text", text: commandText(name, args) } }] }));
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",
@@ -35,6 +35,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "playwright": "^1.58.2",
+    "tldts": "^7.4.19",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/browser/guard.js

@@ -31,6 +31,14 @@ const SURVEY = /^https?:\/\/survey\.(usercase\.io|localhost)(:\d+)?$/;
 
 const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
 
+const { getDomain } = require("tldts");
+/**
+ * 같은 사이트의 뿌리 도메인. www.about.bluetags.app → bluetags.app.
+ * 공용 접미사 목록의 개인 도메인(vercel.app · github.io 등)까지 본다 — foo.vercel.app 과 bar.vercel.app 은 남이다.
+ * IP · localhost 는 뿌리가 없다(null) — 그 주소만 같은 사이트다
+ */
+const rootOf = (host) => getDomain(host, { allowPrivateDomains: true }) || null;
+
 /** 새 탭·창도 그 자체로 최상위다. 페이지 안 iframe(영상·지도)은 사이트 밖이어도 그냥 둔다 */
 function isMainFrame(req) {
   try {
@@ -48,7 +56,10 @@ const isLocal = (site) => /^https?:\/\/(localhost|127\.0\.0\.1)(:|\/|$)/.test(si
  * @param blockTrackers  분석 도구를 막나(기본 true)
  * @param allowWritePaths  쓰기를 허용할 경로 정규식들. 로그인 뒤 조회를 POST 로 하는 사이트용(PLAN.md "로그인")
  */
-function createGuard({ site, inject = null, blockTrackers = true, allowWritePaths = [], policy = null, robots = null } = {}) {
+/**
+ * @param robotsFor   하위 도메인 origin → 그 robots(비동기, 한 번 읽어 둔다). 없으면 하위 도메인은 robots 를 안 본다
+ */
+function createGuard({ site, inject = null, blockTrackers = true, allowWritePaths = [], policy = null, robots = null, robotsFor = null } = {}) {
   const origin = new URL(site).origin;
   const local = isLocal(site);
   /** 우리가 심은 SDK 와 그 서버. 이건 막지 않는다 */
@@ -69,19 +80,26 @@ function createGuard({ site, inject = null, blockTrackers = true, allowWritePath
    */
   const bare = (h) => h.replace(/^www\./, "");
   const siteHost = bare(new URL(origin).host);
-  const sameSite = (u) => u.origin === origin || bare(u.host) === siteHost;
+  /**
+   * 같은 사이트 — 같은 뿌리 도메인의 하위 도메인까지(www · app · about …). 사람처럼 사이트의 다른 하위 도메인으로 넘어간다.
+   * 전에는 www 만 같은 사이트로 봐서 소개는 www, 제품은 app 인 사이트에서 "시작하기" 가 막혔다.
+   * 하위 도메인에 SDK 가 없으면 hub 가 그 페이지를 알린다(리서치 방문은 멈춘다, sdkGone)
+   */
+  const siteRoot = local ? null : rootOf(new URL(origin).hostname);
+  const sameSite = (u) => u.origin === origin || bare(u.host) === siteHost || (!!siteRoot && /^https?:$/.test(u.protocol) && rootOf(u.hostname) === siteRoot);
 
   function writeAllowed(pathname) {
     if (writeOk.some((rx) => rx.test(pathname))) return true;
     return !!(policy && policy.nonGetAllowed(pathname));
   }
 
-  function navBlocked(u) {
-    if (u.origin !== origin) return null; // 사이트 밖은 아래에서 따로 다룬다
+  async function navBlocked(u) {
+    if (!sameSite(u)) return null; // 사이트 밖은 아래에서 따로 다룬다
+    // 고객이 정한 금지 경로는 하위 도메인에도 같다
     const byPolicy = policy ? policy.pathReason(u.pathname) : null;
     if (byPolicy) return byPolicy;
-    // robots 는 나중에 읽혀 들어올 수 있다(네트워크). 함수로 받으면 그때그때 최신을 본다
-    const rb = typeof robots === "function" ? robots() : robots;
+    // robots 는 나중에 읽혀 들어올 수 있다(네트워크). 함수로 받으면 그때그때 최신을 본다. 하위 도메인은 그 도메인의 robots.txt
+    const rb = u.origin === origin ? (typeof robots === "function" ? robots() : robots) : robotsFor ? await robotsFor(u.origin).catch(() => null) : null;
     const byRobots = rb ? rb.blocked(u.pathname) : null;
     return byRobots ? `robots.txt Disallow ${byRobots}` : null;
   }
@@ -91,7 +109,7 @@ function createGuard({ site, inject = null, blockTrackers = true, allowWritePath
    * @param onWrite    사이트에 쓰는 요청을 끊었을 때 "METHOD /path" 로 부른다. 방문자가 "안 된다" 로 읽지 않게 알린다
    */
   async function apply(ctx, { onOffsite = null, onWrite = null, onExternal = null } = {}) {
-    await ctx.route("**/*", (r) => {
+    await ctx.route("**/*", async (r) => {
       const req = r.request();
       let u;
       try {
@@ -121,8 +139,8 @@ function createGuard({ site, inject = null, blockTrackers = true, allowWritePath
        * 금지 구역으로 **옮겨 가는 것**만 막는다(클릭은 막지 않는다 — SDK 가 그 클릭을 봐야 한다).
        * 화면 안에서 쓰는 요청(XHR 등)까지 이걸로 막으면 멀쩡한 사이트가 안 돈다.
        */
-      if (u.origin === origin && req.isNavigationRequest()) {
-        const why = navBlocked(u);
+      if (sameSite(u) && req.isNavigationRequest()) {
+        const why = await navBlocked(u);
         if (why) {
           const k = `${u.pathname} — ${why}`;
           stats.paths.set(k, (stats.paths.get(k) || 0) + 1);
@@ -135,7 +153,8 @@ function createGuard({ site, inject = null, blockTrackers = true, allowWritePath
        * 전에는 아래 로컬 분기가 localhost 를 먼저 통과시켜 로컬에서는 쓰기가 한 번도 안 막혔다(10/14 발견).
        * 개발 서버 자체 요청(/_next/, /__nextjs)은 사이트 데이터가 아니다
        */
-      const siteReq = u.origin === origin || (local && /^https?:\/\/(localhost|127\.0\.0\.1)/.test(u.origin) && !/^\/(_next|__nextjs)/.test(u.pathname));
+      // 하위 도메인도 그 사이트다 — app. 에서 가입 · 글쓰기가 실제로 나가면 안 된다
+      const siteReq = sameSite(u) || (local && /^https?:\/\/(localhost|127\.0\.0\.1)/.test(u.origin) && !/^\/(_next|__nextjs)/.test(u.pathname));
       if (siteReq && !READ_METHODS.has(req.method()) && !writeAllowed(u.pathname)) {
         const k = `${req.method()} ${u.pathname}`;
         stats.writes.set(k, (stats.writes.get(k) || 0) + 1);
@@ -216,4 +235,22 @@ function injectSdk({ project, src }) {
   }
 }
 
-module.exports = { createGuard, isLocal, TRACKERS };
+/**
+ * 두 주소가 같은 사이트인가 — guard 의 sameSite 와 같은 기준(www 무시, 같은 뿌리 도메인의 하위 도메인까지).
+ * 방문(visit.js "다른 사이트로 가는 링크" 알림)과 새 탭 처리(hub)가 같이 쓴다. 로컬 · IP 는 호스트가 같아야 한다
+ */
+function isSameSite(a, b) {
+  try {
+    const ua = new URL(a);
+    const ub = new URL(b);
+    const bare = (h) => h.replace(/^www\./, "");
+    if (bare(ua.host) === bare(ub.host)) return true;
+    if (!/^https?:$/.test(ub.protocol) || isLocal(ua.origin) || isLocal(ub.origin)) return false;
+    const ra = rootOf(ua.hostname);
+    return !!ra && ra === rootOf(ub.hostname);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { createGuard, isLocal, isSameSite, TRACKERS };

package/src/browser/page.js

@@ -644,4 +644,29 @@ async function iconPicture(page, items, browser, max = 16) {
   }
 }
 
-module.exports = { OWN_SEL, listControls, visibleText, handleAt, clickBlocked, iconPicture };
+/**
+ * 지금 보이는 화면 전체를 작게 한 장. 사람은 사진·배너·배치·눈에 띄는 것을 보고 고르는데, 방문자는 글자 목록만 받아
+ * 이미지 속 내용을 몰랐다(11/11). 글자는 목록으로 이미 받으니 긴 변 640px 로 줄여 사진과 배치만 알아볼 만큼 — 한 장 300 토큰쯤.
+ * 줄이는 판은 방문과 따로 연 빈 창이라 사이트에 아무것도 안 보낸다. 못 찍으면 null
+ */
+async function screenPicture(page, browser, long = 640) {
+  if (!browser) return null;
+  const vp = page.viewportSize() || { width: 1280, height: 720 };
+  const png = await page.screenshot({ type: "png", scale: "css", animations: "disabled", timeout: 5000 }).catch(() => null);
+  if (!png) return null;
+  const k = Math.min(1, long / Math.max(vp.width, vp.height));
+  const w = Math.round(vp.width * k);
+  const h = Math.round(vp.height * k);
+  const ctx = await browser.newContext({ viewport: { width: w, height: h } });
+  try {
+    const sheet = await ctx.newPage();
+    await sheet.setContent(`<!doctype html><html><body style="margin:0"><img style="display:block" width="${w}" height="${h}" src="data:image/png;base64,${png.toString("base64")}"></body></html>`);
+    return await sheet.screenshot({ type: "jpeg", quality: 70, timeout: 5000 });
+  } catch {
+    return null;
+  } finally {
+    await ctx.close().catch(() => {});
+  }
+}
+
+module.exports = { OWN_SEL, listControls, visibleText, handleAt, clickBlocked, iconPicture, screenPicture };

package/src/run/visit.js

@@ -22,6 +22,7 @@ const { randomUUID } = require("crypto");
 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 { isSameSite } = require("../browser/guard.js");
 const answer = require("./answer.js");
 const diag = require("./diag.js");
 
@@ -240,13 +241,15 @@ function watchNet(page) {
   };
 }
 
-/** 링크가 사이트 밖이면 그 호스트. www 만 다른 것은 같은 사이트다 */
-function offsiteHost(href, here) {
+/**
+ * 링크가 사이트 밖이면 그 호스트. www 만 다른 것, 같은 뿌리 도메인의 하위 도메인은 같은 사이트다(guard.js isSameSite).
+ * @param site  사이트 주소. 없으면 지금 페이지 기준
+ */
+function offsiteHost(href, here, site) {
   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;
+    return isSameSite(site || here, href) || isSameSite(here, href) ? null : to.host;
   } catch {
     return null;
   }
@@ -409,8 +412,10 @@ class Visit {
    * @param study   리서치에 참여 중인 방문이면 { press(key) } — 위젯 단추(과제 건너뛰기)를 누른다(hub · browser/study.js).
    *                그 방문에서 리서치 초대 카드는 질문 카드로 다루지 않는다
    */
-  constructor(page, person, { rhythm = null, shape = null, allowAccounts = false, policy = null, offsite = [], notSent = [], external = [], study = null, log = () => {} } = {}) {
+  constructor(page, person, { rhythm = null, shape = null, allowAccounts = false, policy = null, offsite = [], notSent = [], external = [], study = null, siteOrigin = null, log = () => {} } = {}) {
     this.page = page;
+    /** 사이트 주소 — 하위 도메인 페이지는 경로 앞에 호스트를 붙여 적는다(about.bluetags.app/docs) */
+    this.siteOrigin = siteOrigin;
     this.study = study;
     this.person = person;
     /** 방문 시작 — 걸음마다 몇 초째인지(t) 적는다 */
@@ -509,10 +514,22 @@ class Visit {
     return c && !(this.study && c.invite) ? c : null;
   }
 
+  /** 하위 도메인이면 호스트를 붙인 경로 — 사이트의 "/" 와 섞이지 않게 */
+  hostPath(p) {
+    try {
+      const u = new URL(this.page.url());
+      // www 는 같은 곳이다(사이트 주소가 bluetags.app 이어도 페이지는 www.bluetags.app)
+      const bare = (h) => h.replace(/^www\./, "");
+      return this.siteOrigin && /^https?:$/.test(u.protocol) && bare(u.host) !== bare(new URL(this.siteOrigin).host) ? u.host + p : p;
+    } catch {
+      return p;
+    }
+  }
+
   pathNow() {
     try {
       const u = new URL(this.page.url());
-      return u.pathname + u.search;
+      return this.hostPath(u.pathname + u.search);
     } catch {
       return "";
     }
@@ -647,6 +664,7 @@ class Visit {
     // 카드 판단에는 페이지 전체를 준다 — 이 방문에서 본 것을 다 기억하는 사람이다
     if (this.pending) return { card: this.pending, text: await screenText(this.page) };
     const view = await listControls(this.page);
+    view.path = this.hostPath(view.path);
     // 위쪽만 빠진 것은 넘침이 아니다 — 굴려 올리면 다시 나온다
     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);
@@ -679,7 +697,7 @@ class Visit {
       t: Date.now() - this.t0,
       path: (() => {
         try {
-          return new URL(this.page.url()).pathname;
+          return this.hostPath(new URL(this.page.url()).pathname);
         } catch {
           return null;
         }
@@ -761,9 +779,10 @@ class Visit {
         await page.mouse.move(600, -8, { steps: 2 }).catch(() => {});
       }
       this.ended = true;
-      // 떠나려는 순간에 뜨는 카드가 있다. 모바일은 SDK 가 멈춤으로 대신 보므로 더 기다린다
-      if (!this.card) {
-        const parting = this.asCard(await waitCard(page, this.person.device === "mobile" ? 16000 : 6000));
+      // 떠나려는 순간에 뜨는 카드가 있다(데스크톱 커서). 휴대폰은 사이트 밖으로 나가는 순간을 SDK 가 못 잡는다 —
+      // 예전엔 15초 멈춤으로 대신해 16초를 기다렸다(core #68 에서 뺐다). 화면을 옮길 때 뜨는 카드는 다음 조작에서 본다
+      if (!this.card && this.person.device !== "mobile") {
+        const parting = this.asCard(await waitCard(page, 6000));
         if (parting) this.pending = parting;
       }
       return record;
@@ -945,7 +964,7 @@ class Visit {
 
     // 사이트 밖으로 가는 링크였다. 끊었으니 방문자는 그대로 이 화면에 있다.
     // 새 탭으로 여는 링크(target=_blank)는 방어선을 안 지나고 열린다 — 누른 링크 주소로도 본다(탭은 hub 가 닫는다)
-    const hrefOff = decision.action === "click" && !record.skipped ? offsiteHost(item?.href, before) : null;
+    const hrefOff = decision.action === "click" && !record.skipped ? offsiteHost(item?.href, before, this.siteOrigin) : null;
     if (this.offsite.length > offsiteBefore) {
       try {
         record.offsite = new URL(this.offsite[this.offsite.length - 1]).host;