unity-open-mcp 1.5.0 → 1.6.0

package/dist/playtest/session-store.js

@@ -0,0 +1,224 @@
+// Playtest session recorder — on-disk layout.
+//
+// A session is a deliberate on-disk record (not a cache): the review artifact
+// a human reads after an agent's playtest. It lives in the same platform
+// app-data root as the player-state snapshots, outside the project:
+//
+//   <app data>/unity-open-mcp/playtest-sessions/<company>/<product>/<session>/
+//     session.json      metadata (owner, device, snapshot, state, report path)
+//     log.jsonl         one JSON line per event, appended as it happens
+//     report/
+//       frames/         full-size captures (linked or copied when the call ends)
+//       thumbs/         downscaled previews (written by `end`)
+//       report.md       written by `end`
+//
+// `<app data>` mirrors the bridge's player-state root: ~/Library/Application
+// Support on macOS, %LOCALAPPDATA% on Windows, $XDG_DATA_HOME or ~/.local/share
+// elsewhere. Company / product are the project's Player Settings, made into one
+// path segment each with the same rule as the bridge.
+//
+// Every write is synchronous and small: a log line is appended with one
+// appendFileSync (open-write-close) the moment the event happens, so the log
+// survives a domain reload, an Editor crash and an MCP server restart; the
+// metadata file is replaced through a temp file + rename. A process that adopts
+// a session first ends a torn last line, so its own entries stay parseable.
+import { appendFileSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const SESSION_FORMAT = 1;
+export const SESSION_FILE = "session.json";
+export const LOG_FILE = "log.jsonl";
+export const REPORT_DIR = "report";
+export const FRAMES_DIR = "frames";
+export const THUMBS_DIR = "thumbs";
+export const REPORT_FILE = "report.md";
+/** The platform app-data folder (same rule as the bridge's player-state store). */
+export function appDataRoot(platform = process.platform, env = process.env, home = env.HOME ?? homedir()) {
+    let appData;
+    if (platform === "darwin")
+        appData = join(home, "Library", "Application Support");
+    else if (platform === "win32")
+        appData = env.LOCALAPPDATA && env.LOCALAPPDATA.length ? env.LOCALAPPDATA : join(home, "AppData", "Local");
+    else {
+        const xdg = env.XDG_DATA_HOME;
+        appData = xdg && xdg.startsWith("/") ? xdg : join(home, ".local", "share");
+    }
+    return join(appData, "unity-open-mcp");
+}
+export function sessionsRoot(platform, env, home) {
+    return join(appDataRoot(platform, env, home), "playtest-sessions");
+}
+/** A company / product name as one path segment (the bridge's SafeSegment rule). */
+export function safeSegment(value) {
+    if (!value)
+        return "_";
+    let out = "";
+    for (const c of value)
+        out += /[\\/:*?"<>|]/.test(c) || c.charCodeAt(0) < 32 ? "_" : c;
+    out = out.trim().replace(/\.+$/, "");
+    return out.length === 0 || out === "." || out === ".." ? "_" : out;
+}
+/** A session id: UTC stamp + a slug of the name + 4 hex, safe as a folder name. */
+export function sessionId(name, now, random) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\..*$/, "").replace("T", "-");
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32) || "playtest";
+    return `${stamp}-${slug}-${random}`;
+}
+export const SESSION_ID_PATTERN = /^[0-9]{8}-[0-9]{6}-[a-z0-9-]{1,40}$/;
+/**
+ * Company / product from ProjectSettings/ProjectSettings.asset — the fallback
+ * when the Editor cannot be asked (a restart with the Editor closed). Plain
+ * and quoted YAML scalars only; anything else falls back to Unity's defaults.
+ */
+export function readProjectIdentity(projectPath) {
+    let text;
+    try {
+        text = readFileSync(join(projectPath, "ProjectSettings", "ProjectSettings.asset"), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const scalar = (key) => {
+        const match = new RegExp(`^\\s*${key}:[ \\t]*(.*)$`, "m").exec(text);
+        if (!match)
+            return null;
+        const raw = match[1].trim();
+        if (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2)
+            return raw.slice(1, -1).replace(/''/g, "'");
+        if (raw.startsWith("\"") && raw.endsWith("\"") && raw.length >= 2) {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return raw.slice(1, -1);
+            }
+        }
+        return raw;
+    };
+    const company = scalar("companyName");
+    const product = scalar("productName");
+    if (company === null || product === null)
+        return null;
+    return { company, product };
+}
+export class SessionStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    productDir(company, product) {
+        return join(this.root, safeSegment(company), safeSegment(product));
+    }
+    dir(meta) {
+        return join(this.productDir(meta.company, meta.product), meta.id);
+    }
+    create(meta) {
+        const dir = this.dir(meta);
+        mkdirSync(join(dir, REPORT_DIR, FRAMES_DIR), { recursive: true });
+        this.writeMeta(meta);
+        writeFileSync(join(dir, LOG_FILE), "", { flag: "a" });
+        return dir;
+    }
+    writeMeta(meta) {
+        const dir = this.dir(meta);
+        const target = join(dir, SESSION_FILE);
+        const temp = `${target}.${process.pid}.tmp`;
+        writeFileSync(temp, JSON.stringify(meta, null, 2));
+        renameSync(temp, target);
+    }
+    readMeta(dir) {
+        try {
+            const meta = JSON.parse(readFileSync(join(dir, SESSION_FILE), "utf8"));
+            return meta && meta.format === SESSION_FORMAT && typeof meta.id === "string" ? meta : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    append(meta, entry) {
+        appendFileSync(join(this.dir(meta), LOG_FILE), JSON.stringify(entry) + "\n");
+    }
+    /**
+     * Every parseable line of a session log; a torn line (a crash mid-write) is
+     * skipped. Read in chunks, so a log larger than the longest JS string still
+     * yields its entries.
+     */
+    readLog(dir) {
+        let fd;
+        try {
+            fd = openSync(join(dir, LOG_FILE), "r");
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        const parse = (line) => {
+            const text = line.toString("utf8");
+            if (!text.trim())
+                return;
+            try {
+                out.push(JSON.parse(text));
+            }
+            catch { /* torn line */ }
+        };
+        try {
+            const chunk = Buffer.alloc(1 << 20);
+            let rest = Buffer.alloc(0);
+            for (let read = readSync(fd, chunk, 0, chunk.length, null); read > 0; read = readSync(fd, chunk, 0, chunk.length, null)) {
+                const data = rest.length ? Buffer.concat([rest, chunk.subarray(0, read)]) : chunk.subarray(0, read);
+                let start = 0;
+                for (let newline = data.indexOf(10); newline >= 0; newline = data.indexOf(10, start)) {
+                    parse(data.subarray(start, newline));
+                    start = newline + 1;
+                }
+                // Copied: `chunk` is reused by the next read.
+                rest = Buffer.from(data.subarray(start));
+            }
+            if (rest.length)
+                parse(rest);
+        }
+        catch { /* an unreadable tail: keep the entries read so far */ }
+        finally {
+            closeSync(fd);
+        }
+        return out;
+    }
+    /** End a torn last line, so the next appended entry starts a line of its own. */
+    terminateLog(dir) {
+        const file = join(dir, LOG_FILE);
+        let torn = false;
+        try {
+            const fd = openSync(file, "r");
+            try {
+                const size = fstatSync(fd).size;
+                const last = Buffer.alloc(1);
+                torn = size > 0 && readSync(fd, last, 0, 1, size - 1) === 1 && last[0] !== 10;
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        catch {
+            return;
+        }
+        if (torn)
+            appendFileSync(file, "\n");
+    }
+    /** Sessions of one product, newest first. */
+    list(company, product) {
+        const base = this.productDir(company, product);
+        if (!existsSync(base))
+            return [];
+        const out = [];
+        for (const name of readdirSync(base)) {
+            if (!SESSION_ID_PATTERN.test(name))
+                continue;
+            const dir = join(base, name);
+            const meta = this.readMeta(dir);
+            if (meta)
+                out.push({ dir, meta });
+        }
+        return out.sort((a, b) => b.meta.started_at.localeCompare(a.meta.started_at));
+    }
+}
+//# sourceMappingURL=session-store.js.map

package/dist/playtest/session-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.js","sourceRoot":"","sources":["../../src/playtest/session-store.ts"],"names":[],"mappings":"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"}

package/dist/skill/SKILL.md

@@ -32,6 +32,8 @@ Use exact schemas, scoped mutations, and gate evidence to work on the selected U
 - Before batching, interpreting a failed gate, or applying fixes: [Batch and gates](references/batch-and-gates.md).
 - Before file-level repair, YAML edits, or offline asset investigation: [YAML and offline work](references/yaml-and-offline-work.md).
 - Before screenshots, event capture, or test runs: [Senses and tests](references/senses-and-tests.md).
+- Before driving gameplay input (taps, drags, multi-second gestures — legacy Input Manager or Input System): activate `input-simulation` and follow its domain skill; read the reported `backend` array and refusals instead of reflecting into game input code.
+- To playtest the game (read the screen, tap by label, wait, capture, isolate the save, record a report for a human): follow [Playtest](#playtest) below.
 
 ### Project-owned commands
 
@@ -52,9 +54,12 @@ commands in `batch_execute`.
 
 Use the always-visible `unity_open_mcp_jobs` for explicitly supported asynchronous
 operations. `start` requires `tool_or_command`, adapter `args`, and an
-`idempotency_key`. Supported targets are `unity_senses_run_tests` (ordinary test
-filters, no caller `run_id`, cancellation unsupported) and available async project
-commands (`args: {args: {...}, gate, paths_hint}`). Read terminal project-job gate
+`idempotency_key` (optional for read-only targets). Supported targets are
+`unity_senses_run_tests` (ordinary test filters, no caller `run_id`, cancellation
+unsupported), available async project commands (`args: {args: {...}, gate,
+paths_hint}`), and play-mode operations (`unity_open_mcp_inputsim_gesture`,
+`unity_open_mcp_playtest_wait`, `unity_senses_capture_series`; the tool's own args;
+cancellable — cancel releases held input and restores a wait's time scale). Read terminal project-job gate
 results even on failure/cancellation. An unsupported target must not be retried as
 an arbitrary background tool.
 
@@ -68,3 +73,15 @@ before retrying. Records and keys expire 30 minutes after completion and are los
 on server restart. `job_busy` means a project job owns the Editor: mutations, Editor-state
 writes, test starts and every `execute_csharp` (even `read_only: true`) are refused.
 Wait on `error.job.jobId` via jobs (owner only), use typed reads meanwhile, retry once; never loop-retry. See [Routing and lifecycle](references/routing-and-lifecycle.md).
+
+## Playtest
+
+Activate `playtest` with `input-simulation` (`manage_tools` `activate_for`, intent "playtest …").
+
+1. **Prepare.** Device first: `game_view get` (note what to restore), then `set_device` (Simulator device + orientation; read `screen.safe_area` / `insets`) or `set_resolution`; continue only on `settled: true`. Isolate the state: `project_commands(action="list", query="playtest")` and invoke the project's `playtest.begin` when it exists; otherwise start the session with `snapshot: true`. Then `playtest_session {"action":"start","name":"…","device":"…"}` — from now your input / wait / capture / project-command calls are recorded with their frames and console errors (one open session per agent: a second start is `session_already_open`).
+2. **Boot** with `editor_set_state play` (then `editor_status` until playing) and the project's `playtest.boot` command. Never reflect into launchers, singletons or save systems.
+3. **Loop.** `ui_snapshot` (compact, paged) → act like a player: `target_text` on `inputsim_pointer` / `inputsim_touch` (resolve `ambiguous_target` with `index` / `under`, never by guessing names) or `inputsim_gesture` → one `playtest_wait` on a condition (`log` regex, `ui` query — `matches:false` for "gone", `object`, the project's read-only `project_command`, `frames`, `ms`, `all`/`any`) with a `timeout_ms`, never a polling loop of snapshots, steps or `execute_csharp`; read `fired`, on `timed_out` read `condition.last` → look: `unity_senses_capture_series` for anything animated (`start_on`, `contact_sheet: true`, `metric: "diff"` in a `metric_region`), a composed screenshot (no width/height; quote its `capturedAt`) for a static screen → `playtest_session {"action":"mark","label":"…","verdict":"ok|bug|suspicious","note":"…"}`.
+4. **Findings.** Every console exception or error is a finding of the step that caused it: read `since_last_mark.errors` on each mark; `fail_on: ["exception"]` stops a wait at the first one with its stack.
+5. **Finish.** `playtest_session {"action":"end"}` → report path + summary. Stop play mode; invoke `playtest.end`, or `player_state restore` (dry run: read `prefs.removed` / `files.removed`; then `confirm: true` with its `plan`, check `verified`) and `delete` the session's snapshot; put the Game view back (`set_resolution` with the `size_label` from `get`). Hand the report path and the bug / suspicious steps to the human.
+
+Traps: one frame lies about animation — use a series (a tap and what follows: `inputsim_gesture` `capture_at_ms`). Captures name their device: set it before capturing; a hidden Game view tab does not render. Never mutate project assets (scenes, prefabs, writing snippets) during a playtest. Restore overwrites PlayerPrefs and deletes `persistentDataPath` files not in the snapshot; never restore a snapshot you did not take for this session. Waits / series over 40 s return a `job_id` → `jobs wait`. After an MCP server restart, `playtest_session status` lists your session under `orphaned`: `end` (or `resume`) with `session: "<id>"`.

package/dist/skill/references/senses-and-tests.md

@@ -14,6 +14,9 @@
     Exit codes: `0` = all tests passed, `2` = test failures present (NOT a process error — do not treat 2 as a crash), `3` = test runner setup failure. Known **batchmode-only** red tests that pass in the GUI editor — don't try to "fix" these, validate them in the GUI editor instead: in-process HTTP-server lifecycle (socket-disposed), GPU/SceneView (no graphic device under `-nographics`), Unity-6's removed `LogEntries.GetEntries(List<LogEntry>)` internal API (console/capture), MSBuild/Roslyn `Microsoft.Build.Utilities.Core` host assembly load, and TimeManager SerializedProperty float access.
 - `**unity_senses_read_console`** — console entries via reflection. Filter `type: "error"` to confirm clean compile. `detail: "summary"` for messages only (saves tokens); `detail: "verbose"` includes Unity-internal frames.
 - `**unity_senses_screenshot**` — Scene / Game / **composed** / isolated 2×2 composite of one GameObject. `view: "game"` renders `Camera.main` **only** — Screen-Space Overlay UI and multi-camera compositions are NOT in the frame; use `view: "composed"` to verify UI edits (the full player frame: all cameras by depth + Overlay canvases).
+  - **Composed size.** Omit `width`/`height` to get the game's native resolution (the Game view size or the Device Simulator screen; no Editor chrome, no device bezel). A `width`/`height` of another aspect is padded (letterbox), never stretched — read `scaled_from` and `content_rect`. `overlay: "safe_area"` tints the unsafe band and outlines the safe area. Every game/composed response names what it was taken at in `capturedAt` (mode, device or size entry, orientation, screen) — quote it when reporting a frame.
+  - **Device first, then capture.** Put the game on the target resolution/device with `unity_open_mcp_game_view` (`playtest` group) and wait for `settled: true` before capturing; a frame taken while `not_settled` shows the old size.
+- `**unity_senses_capture_series**` (`playtest` group, play mode) — the composed frame at scheduled frames inside the player loop: `at_ms` / `every_ms`+`duration_ms` / `at_frames` (≤ 120), relative to the call or a `start_on` condition (playtest_wait shapes). Each entry names the `frame` / `play_time` its image shows; `unchanged` = same pixels as the previous capture (static screen or hidden Game view). `region` crop, `scale`, `metric` (`luminance` / `diff` inside `metric_region`) and `contact_sheet: true` (one tiled PNG labelled `#i F<frame> +<ms>MS`). Use it for anything animated — two one-shot frames cannot tell a pulse from a change. Long series return a `job_id`.
 - `**unity_senses_screenshot_camera**` — render from an arbitrary world-space pose (position + rotation + fov) without moving the scene/game camera; transient camera, scene camera untouched.
 - `**unity_senses_capture_inline**` — same targets as `screenshot` but returns the PNG as an inline base64 image (no temp file) for agents that don't read the filesystem.
 - `**unity_senses_visual_compare**` — visual regression: capture a named reference snapshot (`action: save`) from scene / game / isolated view, then `action: compare` a later capture against it to check whether an edit visually broke anything. Returns `pixelDiffPercent`, `mismatchedPixels`, `perceptualDistance` (8×8 average-hash Hamming distance — tolerates minor anti-aliasing drift), and `match` (true when `pixelDiffPercent <= sensitivity * 100`; default `sensitivity: 0.01` = 1%). On a non-zero diff, returns an inline diff image (mismatched pixels highlighted red over the current frame). References persist under `~/.unity-open-mcp/screenshots/references/`; `action: list` / `delete` manage them. The `compare` resamples the current capture to the reference dimensions if they differ, so the diff is resolution-stable.

package/dist/tool-router.d.ts

@@ -5,6 +5,7 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { Router } from "./router.js";
 import { LiveClient } from "./live-client.js";
 import type { BridgeEventStream } from "./event-stream.js";
+import { PlaytestRecorder } from "./playtest/recorder.js";
 export declare function resolveRouteLogEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare const ROUTE_LOG_ENABLED: boolean;
 /** Log a happy-path route trace iff the opt-in env flag is set. No-op by
@@ -74,6 +75,26 @@ export declare class ToolRouter implements Router {
     get jobs(): JobManager;
     closeJobs(): void;
     routeJobs(args: Record<string, unknown>, identity?: RequestIdentity): Promise<CallToolResult>;
+    /**
+     * Play-mode operations (`inputsim_gesture`, `playtest_wait`,
+     * `capture_series`): the bridge starts the operation on its shared play-mode
+     * scheduler and answers at once; this route polls POST /playmode-operations
+     * until the terminal result, inside the host-safe window. An operation whose
+     * worst case (`playmodeEstimateMs`: last keyframe / capture, the wait's
+     * timeout, a series' start_on wait + schedule + encoding) exceeds the inline
+     * budget is started as a `jobs` play-mode operation instead and the call
+     * returns that job id. One that outlives the inline poll anyway (gameplay
+     * time, a paused Editor) is cancelled — which releases held input and
+     * restores a wait's time scale — and the error points at the jobs route.
+     */
+    private routePlaymodeOperation;
+    /**
+     * `game_view`: set_resolution / set_device in play mode return once the game
+     * reports the new size — the bridge starts a settle watch on its play-mode
+     * scheduler and this route polls it (then re-reads `get`), or answers
+     * `not_settled`. get / list_devices and edit-mode changes pass through.
+     */
+    private routeGameView;
     private readonly modelCache;
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -120,7 +141,30 @@ export declare class ToolRouter implements Router {
      * request's agent id.
      */
     routeOverride(toolName: string, args: Record<string, unknown>, overrideLive: LiveClient, identity: RequestIdentity): Promise<CallToolResult>;
+    /**
+     * Every entry point funnels through here (direct, manage_tools invoke, port
+     * override). While the caller's agent owner has an open playtest session, a
+     * recorded call (input / wait / capture / project command / play-mode and
+     * Game view changes) is logged around its dispatch; everything else — and
+     * every call when no session is open — goes straight through. The recorder
+     * never changes a result and never fails a call.
+     */
     private routeCore;
+    /** The owner a request files sessions (and jobs) under. */
+    private ownerOf;
+    private playtestRecorder?;
+    /** The session recorder, created on first use and fed by the bridge event stream. */
+    get playtest(): PlaytestRecorder;
+    /** Install a recorder (tests use a temporary root). */
+    usePlaytestRecorder(recorder: PlaytestRecorder): void;
+    /**
+     * `unity_open_mcp_playtest_session` — local route. Bridge reads the session
+     * needs (company / product, the Game view state, a player-state snapshot or
+     * diff) go through the normal route as the same owner, and only when the
+     * bridge answers /ping; otherwise the recorder falls back to disk.
+     */
+    private routePlaytestSession;
+    private routeDispatch;
     private routeValidated;
     private routeUnchecked;
     private batchPingResult;

package/dist/tool-router.js

@@ -1,4 +1,7 @@
-import { testRunOperation, projectCommandOperation } from "./jobs/adapters.js";
+import { randomUUID } from "node:crypto";
+import { testRunOperation, projectCommandOperation, playmodeOperation, pollPlaymodeOperation, playmodeResult, toolOutput, toolResultBody, PLAYMODE_OPERATION_TOOLS, playmodeEstimateMs, playmodeFailureCode } from "./jobs/adapters.js";
+import { PLAYMODE_ROUTES } from "./playmode-routes.js";
+import { routeGameView as settleGameView } from "./game-view-settle.js";
 import { JobManager, JobManagerError } from "./jobs/job-manager.js";
 import { handleJobs } from "./jobs/handler.js";
 import { PROCESS_AGENT_ID, PROCESS_IDENTITY } from "./agent-identity.js";
@@ -29,8 +32,12 @@ import { generateSkill } from "./skill/generate-skill.js";
 import { getKnownClientKeys } from "./skill/client-paths.js";
 import { ALL_TOOLS } from "./tools/index.js";
 import { lockPath, readInstanceLock, classifyInstance, isPidAlive } from "./instance-discovery.js";
-import { PORT_ENV_VAR, EXPECTED_BRIDGE_WIRE_CONTRACT } from "./constants.js";
+import { PORT_ENV_VAR, EXPECTED_BRIDGE_WIRE_CONTRACT, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS } from "./constants.js";
 import { findUnityForProject, readProcessCommandLine } from "./running-unity.js";
+import { PlaytestRecorder, PlaytestError, PLAYTEST_SESSION_TOOL } from "./playtest/recorder.js";
+import { secretEnvValues } from "./playtest/redact.js";
+import { sessionsRoot } from "./playtest/session-store.js";
+import { PLAYTEST_SESSION_ACTION_KEYS } from "./tools/playtest-session.js";
 // M31-optimizations Plan 1 / L14 — opt-in route-logging gate. Resolved once at
 // module load into a boolean; the per-dispatch log sites read the boolean
 // (not process.env on every call) so the hot path stays a single branch.
@@ -573,6 +580,11 @@ export class ToolRouter {
                     if (!this.jobs.hasOperation(name))
                         this.jobs.register(name, testRunOperation(clientFor));
                 }
+                else if (PLAYMODE_OPERATION_TOOLS.has(name)) {
+                    // One generic adapter for every tool on the bridge's shared play-mode scheduler.
+                    if (!this.jobs.hasOperation(name))
+                        this.jobs.register(name, playmodeOperation(name, PLAYMODE_OPERATION_TOOLS.get(name), clientFor));
+                }
                 else if (name.startsWith("project.") && !(typeof key === "string" && this.jobs.hasKey(owner, key))) {
                     // A retry whose key already names a job gets that job (or
                     // idempotency_conflict) from start() without the catalog, which may
@@ -602,6 +614,80 @@ export class ToolRouter {
             return localError(error instanceof JobManagerError ? error.code : "invalid_arguments", error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * Play-mode operations (`inputsim_gesture`, `playtest_wait`,
+     * `capture_series`): the bridge starts the operation on its shared play-mode
+     * scheduler and answers at once; this route polls POST /playmode-operations
+     * until the terminal result, inside the host-safe window. An operation whose
+     * worst case (`playmodeEstimateMs`: last keyframe / capture, the wait's
+     * timeout, a series' start_on wait + schedule + encoding) exceeds the inline
+     * budget is started as a `jobs` play-mode operation instead and the call
+     * returns that job id. One that outlives the inline poll anyway (gameplay
+     * time, a paused Editor) is cancelled — which releases held input and
+     * restores a wait's time scale — and the error points at the jobs route.
+     */
+    async routePlaymodeOperation(name, args, live, identity) {
+        const spec = PLAYMODE_ROUTES[name];
+        const estimateMs = playmodeEstimateMs(name, args);
+        if (estimateMs > spec.inlineLimitMs) {
+            // The job owns the bridge operation id; a caller's operation_id keeps
+            // its retry meaning as the job's idempotency key.
+            const { operation_id: retryKey, ...jobArgs } = args;
+            const started = await this.routeJobs({ action: "start", tool_or_command: name, args: jobArgs,
+                ...(typeof retryKey === "string" ? { idempotency_key: retryKey } : {}) }, identity);
+            const body = toolResultBody(started);
+            if (started.isError || typeof body.job_id !== "string")
+                return started;
+            return sourceResult({ ...body, note: `${spec.label} can take ${Math.round(estimateMs)} ms (> ${spec.inlineLimitMs} ms inline budget); it runs as a job.`,
+                agentNextSteps: [`Call unity_open_mcp_jobs {"action":"wait","job_id":"${body.job_id}","timeout_ms":30000} until the state is terminal; the result holds ${spec.resultHint}.`] }, "local");
+        }
+        const operationId = typeof args.operation_id === "string" ? args.operation_id : randomUUID();
+        const start = await live.route(name, { ...args, operation_id: operationId });
+        const started = toolOutput(start);
+        if (start.isError || started.error || !started.operation)
+            return injectRouteMeta(start, { route: "live" });
+        const outcome = await pollPlaymodeOperation(live, operationId, {
+            deadlineMs: Math.min(estimateMs + 15_000, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS - 5_000),
+            pollIntervalMs: estimateMs < 2_000 ? 50 : 100,
+            unreachableMs: 10_000,
+        });
+        const meta = spec.startMeta(started);
+        // The poll's own deadline cancel, acknowledged: the operation stalled (a
+        // paused Editor never ticks it), it did not end by itself.
+        const stalled = outcome.kind === "deadline" || (outcome.kind === "terminal" && outcome.cancelSent && outcome.snapshot.state === "cancelled");
+        if (stalled) {
+            return sourceResult({ error: { code: spec.stalledCode, message: `The ${spec.noun} did not finish inside the inline window (a paused Editor, gameplay time, or a slow frame rate); it was cancelled and its cleanup ${spec.cleanup}.` },
+                operationId, last: outcome.snapshot, agentNextSteps: [`Check that play mode is running (not paused) and the Game view renders, then retry — or run it as a job: unity_open_mcp_jobs {"action":"start","tool_or_command":"${name}","args":{…}}, then wait on the job id.`] }, "live", true);
+        }
+        switch (outcome.kind) {
+            case "lost":
+                return sourceResult({ error: { code: "operation_lost", message: `The bridge lost the ${spec.noun} (domain reload or Editor restart); its cleanup ${spec.cleanup}.` }, operationId }, "live", true);
+            case "unreachable":
+                return sourceResult({ error: { code: "job_status_unavailable", message: outcome.error }, operationId }, "live", true);
+        }
+        if (outcome.kind !== "terminal")
+            throw new Error("unreachable play-mode poll outcome");
+        const snapshot = outcome.snapshot;
+        const result = { ...meta, ...playmodeResult(snapshot) };
+        if (snapshot.state === "succeeded")
+            return sourceResult({ status: "ok", ...result }, "live");
+        const code = playmodeFailureCode(snapshot, spec.failedCode);
+        // The operation's own `error` (a message string) becomes error.message.
+        return sourceResult({ ...result, error: { code, message: String(snapshot.result?.error ?? `${spec.label} ended ${snapshot.reason ?? snapshot.state}; its cleanup ${spec.cleanup}.`) },
+            ...(spec.failureNextSteps(code) ? { agentNextSteps: spec.failureNextSteps(code) } : {}) }, "live", true);
+    }
+    /**
+     * `game_view`: set_resolution / set_device in play mode return once the game
+     * reports the new size — the bridge starts a settle watch on its play-mode
+     * scheduler and this route polls it (then re-reads `get`), or answers
+     * `not_settled`. get / list_devices and edit-mode changes pass through.
+     */
+    async routeGameView(args, live) {
+        const outcome = await settleGameView(live, args);
+        if (outcome.kind === "passthrough")
+            return injectRouteMeta(outcome.result, { route: "live" });
+        return sourceResult(outcome.body, "live", outcome.isError);
+    }
     modelCache = new AssetModelCache();
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -628,6 +714,9 @@ export class ToolRouter {
             ["unity_open_mcp_generate_skill", (_l, a) => this.routeGenerateSkill(a)],
             ["unity_open_mcp_manage_tools", (l, a, id) => this.routeManageTools(a, l, id)],
             ["unity_open_mcp_project_commands", (l, a) => this.routeProjectCommands(a, l)],
+            // Playtest session recorder: the log lives here (the server sees every
+            // call); bridge reads go through the normal route as the same owner.
+            [PLAYTEST_SESSION_TOOL, (l, a, id) => this.routePlaytestSession(a, l, id)],
             // Live tool whose release lookups (npm latest, GitHub tag) run HERE so
             // the Editor main thread never blocks on the network.
             ["unity_open_mcp_upgrade", (l, a) => this.routeUpgrade(a, l)],
@@ -636,6 +725,15 @@ export class ToolRouter {
             // the process agent id, whatever _meta.agentId the call carried. Direct,
             // manage_tools(invoke) and port-override calls therefore share one owner.
             ["unity_open_mcp_jobs", (_l, a, id) => this.routeJobs(a, id)],
+            // Gestures, waits and capture series run on the bridge's play-mode
+            // scheduler: start, then poll the operation to its terminal result here
+            // (long ones become a job).
+            ["unity_open_mcp_inputsim_gesture", (l, a, id) => this.routePlaymodeOperation("unity_open_mcp_inputsim_gesture", a, l, id)],
+            ["unity_open_mcp_playtest_wait", (l, a, id) => this.routePlaymodeOperation("unity_open_mcp_playtest_wait", a, l, id)],
+            ["unity_senses_capture_series", (l, a, id) => this.routePlaymodeOperation("unity_senses_capture_series", a, l, id)],
+            // Game view / Simulator changes settle over play-mode frames: poll the
+            // bridge's settle watch here so set_* returns once the game sees the size.
+            ["unity_open_mcp_game_view", (l, a) => this.routeGameView(a, l)],
             ["unity_open_mcp_bridge_status", (l, a) => this.routeBridgeStatus(a, l)],
             // M31 Plan 3 — Editor fd-exhaustion operator surfaces. restart_editor
             // is the reactive kill half (acts AFTER the Editor is hung);
@@ -756,7 +854,142 @@ export class ToolRouter {
     async routeOverride(toolName, args, overrideLive, identity) {
         return this.routeCore(overrideLive, toolName, args, identity);
     }
+    /**
+     * Every entry point funnels through here (direct, manage_tools invoke, port
+     * override). While the caller's agent owner has an open playtest session, a
+     * recorded call (input / wait / capture / project command / play-mode and
+     * Game view changes) is logged around its dispatch; everything else — and
+     * every call when no session is open — goes straight through. The recorder
+     * never changes a result and never fails a call.
+     */
     async routeCore(live, toolName, args, identity) {
+        const recorder = this.playtestRecorder;
+        if (!recorder || recorder.openCount === 0 || toolName === PLAYTEST_SESSION_TOOL)
+            return this.routeDispatch(live, toolName, args, identity);
+        const owner = this.ownerOf(identity);
+        if (!recorder.isRecording(owner))
+            return this.routeDispatch(live, toolName, args, identity);
+        if (toolName === "unity_open_mcp_jobs" && (args.action === "wait" || args.action === "status")) {
+            const observed = await this.routeDispatch(live, toolName, args, identity);
+            try {
+                recorder.observeJob(owner, args, observed);
+            }
+            catch (error) {
+                console.error("[unity-open-mcp] playtest recorder:", error);
+            }
+            return observed;
+        }
+        let handle = null;
+        try {
+            handle = recorder.begin(owner, toolName, args);
+        }
+        catch (error) {
+            console.error("[unity-open-mcp] playtest recorder:", error);
+        }
+        if (!handle)
+            return this.routeDispatch(live, toolName, args, identity);
+        this.eventStream.reconnectNow?.call(this.eventStream);
+        let result;
+        try {
+            result = await this.routeDispatch(live, toolName, args, identity);
+        }
+        catch (error) {
+            try {
+                recorder.finish(handle, args, null, error);
+            }
+            catch (inner) {
+                console.error("[unity-open-mcp] playtest recorder:", inner);
+            }
+            throw error;
+        }
+        try {
+            recorder.finish(handle, args, result);
+        }
+        catch (error) {
+            console.error("[unity-open-mcp] playtest recorder:", error);
+        }
+        return result;
+    }
+    /** The owner a request files sessions (and jobs) under. */
+    ownerOf(identity) {
+        return { project: this.projectPath || "default", agent: identity.agent, ...(identity.port === undefined ? {} : { port: identity.port }) };
+    }
+    playtestRecorder;
+    /** The session recorder, created on first use and fed by the bridge event stream. */
+    get playtest() {
+        if (!this.playtestRecorder) {
+            this.usePlaytestRecorder(new PlaytestRecorder({
+                root: sessionsRoot(),
+                projectPath: this.projectPath || "default",
+                knownSecrets: [this.projectPath ? resolveAuthToken(this.projectPath) : undefined, ...secretEnvValues()],
+                streamConnected: () => this.eventStream.isConnected === true,
+            }));
+        }
+        return this.playtestRecorder;
+    }
+    /** Install a recorder (tests use a temporary root). */
+    usePlaytestRecorder(recorder) {
+        this.playtestRecorder = recorder;
+        this.eventStream.addListener?.call(this.eventStream, event => recorder.onEvent(event));
+    }
+    /**
+     * `unity_open_mcp_playtest_session` — local route. Bridge reads the session
+     * needs (company / product, the Game view state, a player-state snapshot or
+     * diff) go through the normal route as the same owner, and only when the
+     * bridge answers /ping; otherwise the recorder falls back to disk.
+     */
+    async routePlaytestSession(args, live, identity) {
+        const action = String(args.action ?? "");
+        const allowed = PLAYTEST_SESSION_ACTION_KEYS[action];
+        if (!allowed)
+            return localError("invalid_arguments", `Unknown action '${action}'.`);
+        const extra = Object.keys(args).filter(key => key !== "action" && !allowed.includes(key));
+        if (extra.length)
+            return localError("invalid_arguments", `Keys not used by ${action}: ${extra.join(", ")}.`);
+        const recorder = this.playtest;
+        const owner = this.ownerOf(identity);
+        let available;
+        const call = async (tool, toolArgs) => {
+            available ??= await live.isLiveAvailable(1_500);
+            if (!available)
+                return localError("bridge_unavailable", "The Unity bridge is not reachable.");
+            const definition = ALL_TOOLS.find(t => t.name === tool);
+            return this.routeDispatch(live, tool, definition ? withSchemaDefaults(definition, toolArgs) : toolArgs, identity);
+        };
+        const sessionArg = typeof args.session === "string" ? args.session : undefined;
+        try {
+            if (action !== "status" || recorder.isRecording(owner) === false)
+                await recorder.prepare(call);
+            if (action === "start" || action === "resume" || action === "end")
+                this.eventStream.ensureSubscription?.call(this.eventStream);
+            let body;
+            switch (action) {
+                case "start":
+                    body = await recorder.start(owner, args, call);
+                    break;
+                case "mark":
+                    body = recorder.mark(owner, args, sessionArg);
+                    break;
+                case "status":
+                    body = recorder.status(owner);
+                    break;
+                case "resume":
+                    body = recorder.resume(owner, sessionArg);
+                    break;
+                case "end":
+                    body = await recorder.end(owner, args, call);
+                    break;
+                default: body = recorder.list(owner, typeof args.limit === "number" ? args.limit : 10);
+            }
+            return sourceResult(body, "local");
+        }
+        catch (error) {
+            if (error instanceof PlaytestError)
+                return sourceResult({ error: { code: error.code, message: error.message }, ...error.detail }, "local", true);
+            return localError("internal_error", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async routeDispatch(live, toolName, args, identity) {
         // Every entry point funnels through here, so an explicit project_path is
         // retargeted before validation and wiring wherever the call came from.
         if ((toolName === "unity_open_mcp_capabilities" || toolName === "unity_open_mcp_bridge_status") && args.project_path !== undefined)