nccgs 2.1.1 → 3.0.0-rc.2

package/runtime/unity/assets.mjs

@@ -0,0 +1,51 @@
+// Import-setting check against the art bible: one `script eval` reads each TextureImporter and returns
+// the fields; mismatches are computed here. No .meta parsing, no hand-typed values.
+import { evalCode } from "./unity.mjs";
+
+const FIELDS = ["pixelsPerUnit", "filterMode", "textureType", "maxTextureSize", "spritePivot", "mipmapEnabled", "width", "height"];
+
+export function assetScript(paths) {
+  const list = paths.map(p => JSON.stringify(p)).join(", ");
+  return `var sb = new System.Text.StringBuilder(); sb.Append("[");
+var paths = new string[]{ ${list} }; bool first = true;
+foreach (var p in paths) {
+  if (!first) sb.Append(","); first = false;
+  var imp = UnityEditor.AssetImporter.GetAtPath(p) as UnityEditor.TextureImporter;
+  if (imp == null) { sb.Append("{\\"path\\":" + Q(p) + ",\\"missing\\":true}"); continue; }
+  var tex = UnityEditor.AssetDatabase.LoadAssetAtPath<UnityEngine.Texture2D>(p);
+  var s = imp.spritePivot;
+  sb.Append("{\\"path\\":" + Q(p) + ",\\"pixelsPerUnit\\":" + imp.spritePixelsPerUnit.ToString("R", System.Globalization.CultureInfo.InvariantCulture)
+    + ",\\"filterMode\\":" + Q(imp.filterMode.ToString()) + ",\\"textureType\\":" + Q(imp.textureType.ToString()) + ",\\"maxTextureSize\\":" + imp.maxTextureSize
+    + ",\\"spritePivot\\":[" + s.x.ToString("R", System.Globalization.CultureInfo.InvariantCulture) + "," + s.y.ToString("R", System.Globalization.CultureInfo.InvariantCulture) + "]"
+    + ",\\"mipmapEnabled\\":" + (imp.mipmapEnabled ? "true" : "false") + ",\\"width\\":" + (tex == null ? -1 : tex.width) + ",\\"height\\":" + (tex == null ? -1 : tex.height) + "}");
+}
+sb.Append("]"); return sb.ToString();
+string Q(string v) { return "\\"" + v.Replace("\\\\", "\\\\\\\\").Replace("\\"", "\\\\\\"") + "\\""; }`;
+}
+
+export function compare(expected, actual) {
+  const mismatches = [];
+  for (const e of expected) {
+    const a = actual.find(x => x.path === e.path);
+    if (!a) { mismatches.push({ path: e.path, field: "path", expected: "present", actual: "not read" }); continue; }
+    if (a.missing) { mismatches.push({ path: e.path, field: "importer", expected: "TextureImporter", actual: "missing" }); continue; }
+    for (const f of FIELDS) {
+      if (!(f in e)) continue;
+      const ev = e[f], av = a[f];
+      const same = Array.isArray(ev) ? Array.isArray(av) && ev.length === av.length && ev.every((v, i) => Math.abs(v - av[i]) < 1e-4) : typeof ev === "number" ? Math.abs(ev - av) < 1e-4 : String(ev).toLowerCase() === String(av).toLowerCase();
+      if (!same) mismatches.push({ path: e.path, field: f, expected: ev, actual: av });
+    }
+  }
+  return mismatches;
+}
+
+export async function checkAssets(root, spec) {
+  const expected = spec.assets ?? [];
+  if (!expected.length) return { ok: false, errors: [{ message: "spec.assets is empty" }], assets: [], mismatches: [] };
+  const r = await evalCode(root, assetScript(expected.map(a => a.path)), 60);
+  const raw = r.result?.result ?? r.result;
+  if (!r.ok || typeof raw !== "string") return { ok: false, errors: r.errors?.length ? r.errors : [{ message: `unexpected eval result: ${String(JSON.stringify(raw)).slice(0, 200)}` }], assets: [], mismatches: [] };
+  let actual; try { actual = JSON.parse(raw); } catch (e) { return { ok: false, errors: [{ message: `cannot parse importer data: ${e.message}` }], assets: [], mismatches: [] }; }
+  const mismatches = compare(expected, actual);
+  return { ok: true, assets: actual, mismatches, errors: [] };
+}

package/runtime/unity/playtest.mjs

@@ -0,0 +1,145 @@
+// Scripted playtest with telemetry, run entirely inside the Editor by one `script eval`.
+// A spec says what to press when, which game members to sample and how often; the Editor writes a CSV
+// of samples (10 Hz by default) and this module turns it into a measurement artifact with a summary
+// (final values, first change of each boolean, min/max of each number, key presses). The playtester
+// agent reads that artifact to judge feel; criteria can assert on the summary.
+//
+// spec = {
+//   name: "space-every-0.9s", durationS: 30, sampleMs: 100, holdS: 1,
+//   keys: [{ at: 0.9, key: "Space", holdMs: 60 }, ...]            // explicit timeline, or
+//   pattern: { key: "Space", everyS: 0.9, fromS: 0.5, holdMs: 60 } // expanded into keys
+//   probes: [{ name: "distance", expr: "Runner.Instance.DistanceTravelled" }, { name: "alive", expr: "GameState.IsRunning" }],
+//   stopWhen: "!GameState.IsRunning",                               // optional C# expression, ends the run early
+//   reset: "UnityEngine.SceneManagement.SceneManager.LoadScene(UnityEngine.SceneManagement.SceneManager.GetActiveScene().name)",
+//   settleS: 0.5,                                                   // reset runs at schedule time; the timeline starts settleS later
+//   rules: [{ name: "jump-near-hazard", when: "<C# bool expr>", key: "Space", holdMs: 60, cooldownS: 0.3 }]
+//                                                                   // reactive input: pressed whenever `when` holds (a bot, not a metronome)
+// }
+// The schedule lands 2-3 s after Play (Pipeline round trips), so without `reset` the game is already
+// mid-run; `gameTime` (Time.timeSinceLevelLoad) is sampled beside `t` to make that visible.
+import fs from "node:fs";
+import path from "node:path";
+import { exists } from "../core/fs.mjs";
+import { playStart, playStop, evalCode, waitReady, runInBackground, consoleGet } from "./unity.mjs";
+import { sleep } from "../core/process-tree.mjs";
+
+const q = v => JSON.stringify(String(v));
+const INV = "System.Globalization.CultureInfo.InvariantCulture";
+
+export function expandKeys(spec) {
+  if (Array.isArray(spec.keys) && spec.keys.length) return spec.keys.map(k => ({ at: Number(k.at), key: String(k.key), holdMs: Number(k.holdMs ?? 60) })).sort((a, b) => a.at - b.at);
+  const p = spec.pattern;
+  if (!p?.key || !(p.everyS > 0)) return [];
+  const keys = [];
+  for (let t = Number(p.fromS ?? 0.5); t < Number(spec.durationS ?? 30); t += Number(p.everyS)) keys.push({ at: Number(t.toFixed(3)), key: String(p.key), holdMs: Number(p.holdMs ?? 60) });
+  return keys;
+}
+
+export function playtestScript(spec, { csvFile, doneFile }) {
+  const K = "UnityEngine.InputSystem";
+  const keys = expandKeys(spec);
+  const probes = spec.probes ?? [];
+  const sampleS = ((spec.sampleMs ?? 100) / 1000).toFixed(3);
+  const duration = Number(spec.durationS ?? 30).toFixed(3);
+  // each probe: value or "ERR" (the game may not have the object yet)
+  const probeCode = probes.map(p => `try { var v = (object)(${p.expr}); cells.Add(v is float f ? f.ToString("R", ${INV}) : v is double d ? d.ToString("R", ${INV}) : System.Convert.ToString(v, ${INV})); } catch (System.Exception) { cells.Add("ERR"); }`).join(" ");
+  const keyTimes = keys.map(k => `new double[]{${k.at.toFixed(3)}, ${(k.at + k.holdMs / 1000).toFixed(3)}}`).join(", ");
+  const keyNames = keys.map(k => `${K}.Key.${k.key}`).join(", ");
+  const stopWhen = spec.stopWhen ? `try { if (${spec.stopWhen}) stop = true; } catch (System.Exception) {}` : "";
+  const rules = (spec.rules ?? []).map((r, i) => `try { if (ruleDown[${i}] < 0 && dt >= ruleNext[${i}] && (${r.when})) { ${K}.InputSystem.QueueStateEvent(${K}.Keyboard.current, new ${K}.LowLevel.KeyboardState(${K}.Key.${r.key ?? "Space"})); ruleDown[${i}] = dt; ruleHits[${i}]++; presses++; } else if (ruleDown[${i}] >= 0 && dt >= ruleDown[${i}] + ${((r.holdMs ?? 60) / 1000).toFixed(3)}) { ${K}.InputSystem.QueueStateEvent(${K}.Keyboard.current, new ${K}.LowLevel.KeyboardState()); ruleDown[${i}] = -1; ruleNext[${i}] = dt + ${Number(r.cooldownS ?? 0.3).toFixed(3)}; } } catch (System.Exception) {}`).join(" ");
+  const ruleCount = (spec.rules ?? []).length;
+  const reset = spec.reset ? `try { ${spec.reset}; } catch (System.Exception e) { return "reset failed: " + e.Message; }` : "";
+  const settle = Number(spec.reset ? (spec.settleS ?? 0.5) : 0).toFixed(3);
+  return `var kb = ${K}.Keyboard.current; if (kb == null) return "no keyboard";
+${reset}
+var header = "t,gameTime,${probes.map(p => p.name).join(",")}";
+var lines = new System.Collections.Generic.List<string>(); lines.Add(header);
+var keyTimes = new double[][]{ ${keyTimes} }; var keyNames = new ${K}.Key[]{ ${keyNames} };
+var keyState = new int[keyTimes.Length]; int presses = 0;
+var ruleDown = new double[${ruleCount}]; var ruleNext = new double[${ruleCount}]; var ruleHits = new int[${ruleCount}]; for (int i = 0; i < ruleDown.Length; i++) ruleDown[i] = -1;
+double tSched = UnityEditor.EditorApplication.timeSinceStartup; double t0 = tSched + ${settle}; double nextSample = 0; bool stop = false; bool finished = false;
+UnityEditor.EditorApplication.CallbackFunction cb = null;
+cb = () => {
+  if (finished) return;
+  double dt = UnityEditor.EditorApplication.timeSinceStartup - t0;
+  if (dt < 0) return;
+  for (int i = 0; i < keyTimes.Length; i++) {
+    if (keyState[i] == 0 && dt >= keyTimes[i][0]) { ${K}.InputSystem.QueueStateEvent(${K}.Keyboard.current, new ${K}.LowLevel.KeyboardState(keyNames[i])); keyState[i] = 1; presses++; }
+    else if (keyState[i] == 1 && dt >= keyTimes[i][1]) { ${K}.InputSystem.QueueStateEvent(${K}.Keyboard.current, new ${K}.LowLevel.KeyboardState()); keyState[i] = 2; }
+  }
+  ${rules}
+  if (dt >= nextSample) { nextSample += ${sampleS}; var cells = new System.Collections.Generic.List<string>(); cells.Add(dt.ToString("F3", ${INV})); cells.Add(UnityEngine.Time.timeSinceLevelLoad.ToString("F3", ${INV})); ${probeCode} lines.Add(string.Join(",", cells)); }
+  ${stopWhen}
+  if (stop || dt >= ${duration}) {
+    { var cells = new System.Collections.Generic.List<string>(); cells.Add(dt.ToString("F3", ${INV})); cells.Add(UnityEngine.Time.timeSinceLevelLoad.ToString("F3", ${INV})); ${probeCode} lines.Add(string.Join(",", cells)); }
+    finished = true; UnityEditor.EditorApplication.update -= cb;
+    System.IO.File.WriteAllLines(${q(csvFile)}, lines);
+    System.IO.File.WriteAllText(${q(doneFile)}, "presses=" + presses + ";stopped=" + stop + ";t=" + dt.ToString("F3", ${INV}) + ";rules=" + string.Join("|", ruleHits));
+  }
+};
+UnityEditor.EditorApplication.update += cb; return "scheduled";`;
+}
+
+export function parseCsv(text) {
+  const [head, ...rows] = text.trim().split(/\r?\n/);
+  const names = head.split(",");
+  return rows.filter(Boolean).map(r => { const c = r.split(","); const o = {}; names.forEach((n, i) => { const v = c[i]; o[n] = v === "True" ? true : v === "False" ? false : v === "ERR" || v === undefined ? null : Number.isFinite(Number(v)) ? Number(v) : v; }); return o; });
+}
+
+export function summarize(samples, probes) {
+  const summary = { samples: samples.length, durationS: samples.at(-1)?.t ?? 0, gameTimeStartS: samples[0]?.gameTime ?? null, gameTimeEndS: samples.at(-1)?.gameTime ?? null };
+  for (const p of probes) {
+    const vals = samples.map(s => s[p.name]).filter(v => v !== null && v !== undefined);
+    if (!vals.length) { summary[p.name] = null; continue; }
+    const last = vals.at(-1);
+    if (typeof last === "boolean") {
+      const first = samples.find(s => s[p.name] !== null && s[p.name] !== vals[0]);
+      summary[p.name] = { final: last, initial: vals[0], changedAtS: first ? first.t : null };
+    } else if (typeof last === "number") {
+      summary[p.name] = { final: last, min: Math.min(...vals), max: Math.max(...vals) };
+    } else summary[p.name] = { final: last };
+  }
+  return summary;
+}
+
+async function waitFor(file, timeoutMs) {
+  const until = Date.now() + timeoutMs;
+  while (Date.now() < until) { if (exists(file)) return true; await sleep(300); }
+  return exists(file);
+}
+
+export async function playtest(root, spec, { outDir, holdMs = 1000 } = {}) {
+  const outcome = { name: spec.name ?? "playtest", enteredPlayMode: false, exitedPlayMode: false, keys: expandKeys(spec).length, errors: [], samples: [], summary: null, console: null };
+  fs.mkdirSync(outDir, { recursive: true });
+  const csvFile = path.resolve(outDir, `${outcome.name}.csv`), doneFile = path.resolve(outDir, `${outcome.name}.done`);
+  for (const f of [csvFile, doneFile]) try { fs.rmSync(f, { force: true }); } catch {}
+  const rib = await runInBackground(root, true);
+  const mark = await consoleGet(root, { tail: 1, level: "log" });
+  const since = mark.ok ? { since: mark.result?.cursor, since_session: mark.result?.session } : {};
+  const started = await playStart(root);
+  if (!started.ok) { outcome.errors.push(started.errors?.[0]?.message ?? "play start failed"); return outcome; }
+  outcome.enteredPlayMode = true;
+  await sleep(Number(spec.holdS ?? 1) * 1000 || holdMs);
+  const r = await evalCode(root, playtestScript(spec, { csvFile, doneFile }), 60);
+  const value = r.result?.result ?? r.result;
+  if (!r.ok || value !== "scheduled") outcome.errors.push(`playtest not scheduled: ${r.errors?.[0]?.message ?? JSON.stringify(value).slice(0, 300)}`);
+  else {
+    const ok = await waitFor(doneFile, (Number(spec.durationS ?? 30) + 15) * 1000);
+    if (!ok) outcome.errors.push("playtest did not finish in time");
+    else {
+      const done = Object.fromEntries(fs.readFileSync(doneFile, "utf8").split(";").map(kv => kv.split("=")));
+      outcome.presses = Number(done.presses); outcome.stoppedEarly = done.stopped === "True"; outcome.ranS = Number(done.t); outcome.stoppedAtS = done.stopped === "True" ? Number(done.t) : null;
+      outcome.rulePresses = (spec.rules ?? []).map((r, i) => ({ name: r.name ?? `rule${i}`, presses: Number((done.rules ?? "").split("|")[i] ?? 0) }));
+      outcome.samples = exists(csvFile) ? parseCsv(fs.readFileSync(csvFile, "utf8")) : [];
+      outcome.summary = summarize(outcome.samples, spec.probes ?? []);
+      outcome.csv = csvFile;
+    }
+  }
+  const con = await consoleGet(root, { tail: 300, level: "log", ...since });   // the game's own log lines ([Runner] jump, dead …) are part of the telemetry
+  if (con.ok) outcome.console = { counts: con.result?.counts ?? null, entries: (con.result?.entries ?? []).slice(-100).map(e => ({ time: e.time ?? e.timestamp ?? null, level: e.level ?? null, message: String(e.message ?? e.text ?? "").slice(0, 200) })) };
+  const stopped = await playStop(root);
+  outcome.exitedPlayMode = stopped.ok;
+  await waitReady(root, { timeoutMs: 10000 });
+  if (rib.ok) await runInBackground(root, false);
+  return outcome;
+}

package/runtime/unity/unity.mjs

@@ -0,0 +1,350 @@
+// Unity CLI + Pipeline wrapper. Every call goes through here so the rest of the
+// runtime never spells a Pipeline command name: names are discovered at runtime
+// (`unity command --detail compact`) and cached per package version.
+//
+// Verified on 2026-11-04 against Unity CLI 1.0.0-beta.14 and com.unity.pipeline 0.9.x
+// with Editors 6000.3.17f1 and 6000.6.7f1 (see docs/EVIDENCE-VERIFICATION.md).
+import path from "node:path";
+import fs from "node:fs";
+import { run, sleep } from "../core/process-tree.mjs";
+import { readJson, writeJson, exists } from "../core/fs.mjs";
+import { at, editorVersion, pipelineVersion } from "../core/project.mjs";
+import { diag } from "../core/diag.mjs";
+
+export const UNITY_BIN = process.env.NCCGS_UNITY_BIN || "unity";
+// Test seam: NCCGS_UNITY_ARGS prepends fixed arguments (used to point NCCGS_UNITY_BIN=node at a fake CLI).
+const PREFIX = process.env.NCCGS_UNITY_ARGS ? process.env.NCCGS_UNITY_ARGS.split("|") : [];
+export const unityArgv = args => [...PREFIX, ...args];
+
+function parseEnvelope(result) {
+  const text = (result.stdout || "").replace(/^/, "").trim();
+  let json = null;
+  try { json = JSON.parse(text); } catch {}
+  return { ...result, json, text };
+}
+
+// `unity test` / `unity build` start a batch Editor that must not outlive the command (ownTree);
+// `unity open` starts an Editor that must. Everything else is a short-lived CLI call.
+export async function cli(args, { cwd, timeoutMs = 120000 } = {}) {
+  const ownTree = ["test", "build"].includes(args[0]);
+  const result = await run(UNITY_BIN, unityArgv([...args, "--format", "json"]), { cwd, timeoutMs, ownTree });
+  const env = parseEnvelope(result);
+  if (result.timedOut || result.error || (env.json && env.json.success === false) || (!env.json && result.code !== 0)) {
+    const i = args.indexOf("--project-path");
+    const shown = i >= 0 ? [...args.slice(0, i), ...args.slice(i + 2)] : args;
+    diag(i >= 0 ? args[i + 1] : (process.env.NCCGS_PROJECT_ROOT ?? process.cwd()), "unity.failed", { args: shown.map(a => String(a).slice(0, 200)), code: result.code, timedOut: result.timedOut, errors: env.json?.errors ?? null, stderr: result.stderr?.slice(-500) ?? null, jobObject: result.jobObject });
+  }
+  return env;
+}
+
+export async function cliVersion() {
+  const r = await run(UNITY_BIN, unityArgv(["--version"]), { timeoutMs: 30000 });
+  return r.code === 0 ? r.stdout.trim() : null;
+}
+
+// ---- Editor instances ------------------------------------------------------
+
+export async function status() {
+  const r = await cli(["status"], { timeoutMs: 30000 });
+  return r.json?.data?.instances ?? [];
+}
+
+export async function instanceFor(root) {
+  const want = path.resolve(root).toLowerCase();
+  return (await status()).find(i => path.resolve(i.projectPath || i.project || "").toLowerCase() === want) ?? null;
+}
+
+// Poll until the project's Pipeline server reports `ready`. Entering Play Mode on 6.3
+// reloads the domain and drops the server for ~3 s, so every post-playmode call waits here.
+export async function waitReady(root, { timeoutMs = 15000, intervalMs = 1000 } = {}) {
+  const started = Date.now();
+  let last = null;
+  while (Date.now() - started < timeoutMs) {
+    last = await instanceFor(root);
+    if (last?.state === "ready") return last;
+    await sleep(intervalMs);
+  }
+  return last;
+}
+
+// ---- Pipeline commands -----------------------------------------------------
+
+export async function command(root, name, params = {}, { timeoutMs = 120000, retries = 2 } = {}) {
+  const args = ["command", ...name.split(" ")];
+  for (const [k, v] of Object.entries(params)) { if (v !== undefined && v !== null) args.push(`--${k}`, String(v)); }
+  args.push("--project-path", root);
+  let r;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    r = await cli(args, { timeoutMs });
+    const code = r.json?.errors?.[0]?.code;
+    if (code !== "EDITOR_NOT_RUNNING" || attempt === retries) break;
+    await waitReady(root, { timeoutMs: 8000 });
+  }
+  const ok = r.json?.success === true;
+  return { ok, result: r.json?.data?.result, errors: r.json?.errors ?? [], raw: r.json, code: r.code, stderr: r.stderr };
+}
+
+// Discover the command catalog; cached under .nccgs/cache keyed by pipeline version.
+export async function catalog(root, { refresh = false } = {}) {
+  const version = pipelineVersion(root) || "unknown";
+  const file = path.join(at(root, "cache"), `pipeline-commands-${version.replace(/[^\w.-]/g, "_")}.json`);
+  if (!refresh && exists(file)) return readJson(file);
+  const r = await cli(["command", "--detail", "compact", "--limit", "500", "--project-path", root], { timeoutMs: 60000 });
+  const commands = r.json?.data?.commands ?? [];
+  if (!commands.length) return { version, commands: [], discoveredAt: null, error: r.json?.errors?.[0]?.message ?? "no commands" };
+  const value = { version, discoveredAt: new Date().toISOString(), commands: commands.map(c => ({ command: c.command, group: c.group, name: c.name, description: c.description })) };
+  writeJson(file, value);
+  return value;
+}
+
+// Resolve a capability to the real command name (handles renames between Pipeline versions).
+const CAPABILITIES = {
+  playStart: [/^editor\.playmode start$/, /^editor_play$/],
+  playStop: [/^editor\.playmode stop$/, /^editor_stop$/],
+  screenshot: [/^capture screenshot$/, /^screenshot$/],
+  consoleGet: [/^console get$/, /^get_console$/],
+  consoleStatus: [/^console status$/],
+  consoleClear: [/^console clear$/],
+  eval: [/^script eval$/, /^eval$/],
+  testRun: [/^test run$/, /^run_tests$/],
+  testStatus: [/^test status$/, /^test_status$/],
+  runInBackground: [/^editor\.playmode set_run_in_background$/],
+  testList: [/^test list$/],
+  simulateKey: [/^runtime simulate_key$/],
+  performance: [/^diagnostics get_performance$/],
+  hierarchy: [/^scene get_hierarchy$/, /^get_scene_hierarchy$/],
+  recompile: [/^script recompile$/, /^recompile$/],
+  recompileStatus: [/^script recompile_status$/]
+};
+
+export async function resolve(root, capability) {
+  const cat = await catalog(root);
+  const patterns = CAPABILITIES[capability];
+  if (!patterns) throw new Error(`Unknown capability ${capability}`);
+  const hit = cat.commands.find(c => patterns.some(p => p.test(c.command)));
+  return hit?.command ?? null;
+}
+
+async function call(root, capability, params, options) {
+  const name = await resolve(root, capability);
+  if (!name) return { ok: false, errors: [{ code: "CAPABILITY_MISSING", message: `No Pipeline command for ${capability}` }] };
+  return command(root, name, params, options);
+}
+
+// ---- High-level operations used by `task verify` -------------------------------
+
+export async function playStart(root) {
+  const r = await call(root, "playStart", {});
+  if (r.ok) await waitReady(root, { timeoutMs: 15000 });
+  return r;
+}
+export const playStop = root => call(root, "playStop", {});
+// Play Mode freezes when the Editor loses focus unless Run In Background is on; the Pipeline override
+// restores the project's own value when disabled. Best effort: an older Pipeline without it is fine.
+export const runInBackground = (root, enable) => call(root, "runInBackground", { enable }).catch(() => ({ ok: false }));
+export const simulateKey = (root, key, action = "press") => call(root, "simulateKey", { key, action });
+export const evalCode = (root, code, timeout = 30) => call(root, "eval", { code, timeout });
+export const performance = root => call(root, "performance", {});
+export const hierarchy = root => call(root, "hierarchy", {});
+
+export async function screenshot(root, output, { view = "game", width = 1280, height = 720 } = {}) {
+  fs.mkdirSync(path.dirname(output), { recursive: true });
+  const r = await call(root, "screenshot", { view, output, width, height });
+  return { ...r, path: r.ok ? (r.result?.path ?? output) : null, bytes: exists(output) ? fs.statSync(output).size : 0 };
+}
+
+export const consoleStatus = root => call(root, "consoleStatus", {});
+export const consoleGet = (root, { tail = 100, level = "warn", since, since_session } = {}) =>
+  call(root, "consoleGet", { tail, level, since, since_session });
+
+// Tests inside the live Editor. Returns the Pipeline summary normalised to tests.json shape.
+// The command envelope can succeed while the run itself failed (result.success false + result.error);
+// that is a failed run, never "ok with 0 tests".
+export async function testRunLive(root, { mode = "editor", filter, timeout = 600 } = {}) {
+  if (mode === "playmode") return testRunLiveAsync(root, { mode, filter, timeout });
+  const r = await call(root, "testRun", { mode, filter: filter || undefined, timeout }, { timeoutMs: (timeout + 60) * 1000 });
+  if (!r.ok) return { ok: false, errors: r.errors };
+  if (r.result?.success === false) return runFailed(mode, r.result.error ?? r.result.message);
+  const s = r.result?.Summary ?? {};
+  const results = r.result?.Results ?? [];
+  return {
+    ok: true,
+    source: "pipeline",
+    mode: r.result?.Mode ?? mode,
+    total: s.Total ?? 0, passed: s.Passed ?? 0, failed: s.Failed ?? 0, skipped: s.Skipped ?? 0, inconclusive: s.Inconclusive ?? 0,
+    durationSec: r.result?.Duration ?? null,
+    failures: results.filter(t => /fail/i.test(t.Result ?? t.Outcome ?? t.Status ?? "")).map(t => ({ name: t.Name ?? t.FullName, message: t.Message ?? "" }))
+  };
+}
+
+// PlayMode cannot run synchronously over HTTP: entering Play Mode reloads the domain and drops the request.
+// Start it async and poll `test status`. Starting a run deletes the previous status file, so a
+// "completed" status read after a successful start belongs to this run.
+async function testRunLiveAsync(root, { mode, filter, timeout }) {
+  const started = await call(root, "testRun", { mode, filter: filter || undefined, async_tests: true, timeout });
+  if (!started.ok) return { ok: false, source: "pipeline", mode, errors: started.errors };
+  if (started.result?.success === false) return runFailed(mode, started.result.error ?? started.result.message);
+  const deadline = Date.now() + (timeout + 60) * 1000;
+  let st = null;
+  while (Date.now() < deadline) {
+    await sleep(2000);
+    const r = await call(root, "testStatus", {});
+    st = r.ok ? r.result : null; // null while the domain reloads or before the request is registered
+    if (st && st.status !== "running") break;
+  }
+  if (st?.status !== "completed") return runFailed(mode, st?.message ?? `test status: ${st?.status ?? "timed out"}`);
+  const s = st.summary ?? {};
+  const results = st.results ?? [];
+  return {
+    ok: true,
+    source: "pipeline",
+    mode: "PlayMode",
+    total: s.total ?? 0, passed: s.passed ?? 0, failed: s.failed ?? 0, skipped: s.skipped ?? 0, inconclusive: s.inconclusive ?? 0,
+    durationSec: st.duration ?? null,
+    failures: results.filter(t => /fail/i.test(t.Status ?? "")).map(t => ({ name: t.FullName ?? t.Name, message: t.Message ?? "" }))
+  };
+}
+
+function runFailed(mode, message) {
+  return { ok: false, source: "pipeline", mode, errors: [{ code: "TEST_RUN_FAILED", message: message ?? "test run failed" }] };
+}
+
+// Tests through a batch Editor (no live Editor on this project). Pins the project's own Editor version.
+export async function testRunBatch(root, { mode = "EditMode", filter, timeout = 900, output } = {}) {
+  const version = editorVersion(root);
+  const xml = output || path.join(at(root, "measurements"), `${mode.toLowerCase()}-results.xml`);
+  const args = ["test", root, "--mode", mode, "--output", xml, "--timeout", String(timeout)];
+  if (filter) args.push("--filter", filter);
+  if (version) args.push("--editor-version", version);
+  const r = await cli(args, { timeoutMs: (timeout + 120) * 1000 });
+  const errorCode = r.json?.errors?.[0]?.code ?? null;
+  if (!exists(xml)) return { ok: false, source: "batch", exitCode: r.code, errorCode, errors: r.json?.errors ?? [{ message: r.stderr.slice(0, 400) }] };
+  return { ok: true, source: "batch", exitCode: r.code, mode, xml, ...parseNUnit(fs.readFileSync(xml, "utf8")) };
+}
+
+// Minimal NUnit3 reader: run-level counts plus failed test cases. No XML dependency.
+export function parseNUnit(text) {
+  const attr = (tag, name) => Number(text.match(new RegExp(`<${tag}[^>]*\\b${name}="(\\d+)"`))?.[1] ?? 0);
+  const failures = [];
+  for (const m of text.matchAll(/<test-case\b([^>]*)result="Failed"([^>]*)>([\s\S]*?)<\/test-case>/g)) {
+    const head = m[1] + m[2];
+    const name = head.match(/fullname="([^"]*)"/)?.[1] ?? head.match(/name="([^"]*)"/)?.[1] ?? "unknown";
+    const message = m[3].match(/<message><!\[CDATA\[([\s\S]*?)\]\]><\/message>/)?.[1]?.trim() ?? "";
+    failures.push({ name, message: message.slice(0, 500) });
+  }
+  return { total: attr("test-run", "total"), passed: attr("test-run", "passed"), failed: attr("test-run", "failed"), skipped: attr("test-run", "skipped"), inconclusive: attr("test-run", "inconclusive"), durationSec: Number(text.match(/<test-run[^>]*duration="([\d.]+)"/)?.[1] ?? 0), failures };
+}
+
+// Pick live when the project has a ready Editor, batch otherwise. A run that executed no test is not ok:
+// it means a wrong mode/filter or a run that never started, and must not read as a green 0/0.
+export async function testRun(root, options = {}) {
+  const live = await instanceFor(root);
+  const r = live?.state === "ready"
+    ? await testRunLive(root, { mode: options.mode === "PlayMode" ? "playmode" : options.mode === "EditMode" ? "editor" : (options.mode ?? "editor"), filter: options.filter, timeout: options.timeout })
+    : await testRunBatch(root, { mode: options.mode === "playmode" ? "PlayMode" : options.mode === "editor" ? "EditMode" : (options.mode ?? "EditMode"), filter: options.filter, timeout: options.timeout, output: options.output });
+  if (r.ok && (r.total ?? 0) === 0) return { ...r, ok: false, errors: [...(r.errors ?? []), { code: "NO_TESTS_RAN", message: `no ${r.mode ?? "test"} tests ran${options.filter ? ` for filter '${options.filter}'` : ""}` }] };
+  return r;
+}
+
+// Observe: enter Play Mode, wait, optionally press keys, capture screenshots, read the console, exit.
+// Keys are pressed once, after the first hold and before frame 1 (so frame 1 shows the reaction and frame 2
+// the settled state); `keysEveryFrame` repeats them before every frame. `matchLog` (regex) counts the
+// Play Mode log entries that match it, so a criterion can assert "one log line per press".
+// Timed mode (`shotsMs` given): one `script eval` schedules everything inside the Editor on
+// EditorApplication.update — key down at t=0 through the Input System's low-level queue, key up after
+// `holdKeyMs`, ScreenCapture.CaptureScreenshot at each offset in `shotsMs`. Every Pipeline round trip costs
+// ~0.9 s, so this is the only way to photograph anything that happens within a second of a key press
+// (a 0.75 s jump landed before the first `capture screenshot` ever returned). Frames are the Game view's
+// own size. Needs com.unity.inputsystem; with no keyboard device the eval returns "no keyboard".
+const q = v => JSON.stringify(String(v));
+function timedScript({ keys, holdKeyMs, shots, timingFile }) {
+  const K = "UnityEngine.InputSystem";
+  const keyList = keys.map(k => `${K}.Key.${k}`).join(", ");
+  const press = keys.length ? `${K}.InputSystem.QueueStateEvent(kb, new ${K}.LowLevel.KeyboardState(${keyList}));` : "";
+  const release = keys.length ? `if (!released && dt > ${(holdKeyMs / 1000).toFixed(3)}) { ${K}.InputSystem.QueueStateEvent(${K}.Keyboard.current, new ${K}.LowLevel.KeyboardState()); released = true; }` : "";
+  const captures = shots.map((sh, i) => `if (!done[${i}] && dt > ${(sh.ms / 1000).toFixed(3)}) { UnityEngine.ScreenCapture.CaptureScreenshot(${q(sh.path)}); done[${i}] = true; gameTimes[${i}] = UnityEngine.Time.timeSinceLevelLoad; }`).join(" ");
+  const last = ((shots.at(-1)?.ms ?? 0) / 1000 + 0.5).toFixed(3);
+  const timing = `System.IO.File.WriteAllText(${q(timingFile)}, g0.ToString("R", System.Globalization.CultureInfo.InvariantCulture) + ";" + string.Join(",", System.Array.ConvertAll(gameTimes, x => x.ToString("R", System.Globalization.CultureInfo.InvariantCulture))));`;
+  return `var kb = ${K}.Keyboard.current; if (kb == null) return "no keyboard"; ${press} double t0 = UnityEditor.EditorApplication.timeSinceStartup; float g0 = UnityEngine.Time.timeSinceLevelLoad; bool released = false; var done = new bool[${shots.length}]; var gameTimes = new float[${shots.length}]; UnityEditor.EditorApplication.CallbackFunction cb = null; cb = () => { double dt = UnityEditor.EditorApplication.timeSinceStartup - t0; ${release} ${captures} if (dt > ${last}) { UnityEditor.EditorApplication.update -= cb; ${timing} } }; UnityEditor.EditorApplication.update += cb; return "scheduled";`;
+}
+
+function parseTiming(text) {
+  const [g0, rest = ""] = text.trim().split(";");
+  const n = v => { const x = Number(v); return Number.isFinite(x) ? x : null; };
+  return { scheduledAtGameTime: n(g0), captureGameTimes: rest.split(",").map(n) };
+}
+
+async function waitForFiles(files, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const sizes = {};
+  while (Date.now() < deadline) {
+    let ready = true;
+    for (const f of files) {
+      const size = exists(f) ? fs.statSync(f).size : 0;
+      if (!size || sizes[f] !== size) ready = false;
+      sizes[f] = size;
+    }
+    if (ready) return true;
+    await sleep(300);
+  }
+  return files.every(f => exists(f) && fs.statSync(f).size > 0);
+}
+
+export async function observe(root, { screensDir, frames = 2, keys = [], holdMs = 1500, width = 1280, height = 720, keysEveryFrame = false, matchLog = null, shotsMs = null, holdKeyMs = 60 } = {}) {
+  const outcome = { enteredPlayMode: false, exitedPlayMode: false, screens: [], keys: [], console: null, performance: null, errors: [], logMatches: null, timed: Array.isArray(shotsMs) && shotsMs.length > 0 };
+  const rib = await runInBackground(root, true);
+  outcome.runInBackground = rib.ok === true;
+  const mark = await consoleGet(root, { tail: 1, level: "log" });   // cursor: only entries after this count
+  const since = mark.ok ? { since: mark.result?.cursor, since_session: mark.result?.session } : {};
+  const started = await playStart(root);
+  if (!started.ok) { outcome.errors.push(started.errors?.[0]?.message ?? "play start failed"); return outcome; }
+  const playStartedAt = Date.now();
+  outcome.enteredPlayMode = true;
+  await sleep(holdMs);
+  if (outcome.timed) {
+    fs.mkdirSync(screensDir, { recursive: true });
+    const shots = shotsMs.map((ms, i) => ({ ms, path: path.resolve(screensDir, `${String(i + 1).padStart(2, "0")}.png`) }));
+    for (const sh of shots) { try { fs.rmSync(sh.path, { force: true }); } catch {} }
+    const timingFile = path.resolve(screensDir, "timing.json");
+    try { fs.rmSync(timingFile, { force: true }); } catch {}
+    const scheduledAt = Date.now();
+    const r = await evalCode(root, timedScript({ keys, holdKeyMs, shots, timingFile }));
+    outcome.scheduleDelayMs = Date.now() - playStartedAt;   // wall-clock from Play start to the schedule: frames are atMs after this
+    const value = r.result?.result ?? r.result;
+    if (!r.ok || value !== "scheduled") outcome.errors.push(`timed observe not scheduled: ${r.errors?.[0]?.message ?? JSON.stringify(value).slice(0, 200)}`);
+    else {
+      for (const key of keys) outcome.keys.push({ key, ok: true, holdMs: holdKeyMs });
+      const ok = await waitForFiles([...shots.map(s => s.path), timingFile], (shots.at(-1).ms) + 8000);
+      const timing = exists(timingFile) ? parseTiming(fs.readFileSync(timingFile, "utf8")) : null;
+      outcome.scheduledAtGameTime = timing?.scheduledAtGameTime ?? null;
+      for (const [i, sh] of shots.entries()) outcome.screens.push({ path: exists(sh.path) ? sh.path : null, bytes: exists(sh.path) ? fs.statSync(sh.path).size : 0, ok: exists(sh.path), atMs: sh.ms, gameTimeS: timing?.captureGameTimes?.[i] ?? null });
+      if (!ok) outcome.errors.push("timed observe: not every screenshot was written");
+    }
+  }
+  for (let i = 0; !outcome.timed && i < Math.max(1, frames); i++) {
+    if (i === 0 || keysEveryFrame) {
+      for (const key of keys) { const k = await simulateKey(root, key); outcome.keys.push({ key, ok: k.ok }); }
+      if (keys.length) await sleep(400);
+    }
+    const file = path.join(screensDir, `${String(i + 1).padStart(2, "0")}.png`);
+    const shot = await screenshot(root, file, { width, height });
+    outcome.screens.push({ path: shot.path, bytes: shot.bytes, ok: shot.ok });
+    if (!shot.ok) outcome.errors.push(shot.errors?.[0]?.message ?? "screenshot failed");
+    if (i + 1 < frames) await sleep(holdMs);
+  }
+  const perf = await performance(root);
+  if (perf.ok) outcome.performance = perf.result;
+  const con = await consoleGet(root, { tail: 50, level: "warn" });
+  if (con.ok) outcome.console = { counts: con.result?.counts ?? null, groundTruth: con.result?.groundTruth ?? null, entries: (con.result?.entries ?? []).slice(-20) };
+  if (matchLog) {
+    const all = await consoleGet(root, { tail: 500, level: "log", ...since });
+    const re = new RegExp(matchLog);
+    outcome.logMatches = all.ok ? (all.result?.entries ?? []).filter(e => re.test(e.message ?? e.text ?? "")).length : null;
+  }
+  const stopped = await playStop(root);
+  outcome.exitedPlayMode = stopped.ok;
+  if (!stopped.ok) outcome.errors.push(stopped.errors?.[0]?.message ?? "play stop failed");
+  await waitReady(root, { timeoutMs: 10000 });
+  if (outcome.runInBackground) await runInBackground(root, false);
+  return outcome;
+}

package/scripts/check-job-object.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Windows only: prove the Job Object kills a re-parented grandchild that taskkill /T would miss.
+// Spawns powershell -> Start-Process ping (detached), terminates the tree, counts ping.exe before/after.
+import { spawnSync } from "node:child_process";
+import { run, terminate } from "../runtime/core/process-tree.mjs";
+import { available } from "../runtime/core/job-object.mjs";
+const count = () => (spawnSync("tasklist", ["/FI", "IMAGENAME eq ping.exe", "/NH"], { encoding: "utf8" }).stdout.match(/ping\.exe/gi) || []).length;
+const before = count();
+const jobAvailable = await available();
+const started = run("powershell", ["-NoProfile", "-Command", "Start-Process ping -ArgumentList '-n','40','127.0.0.1' -WindowStyle Hidden; Start-Sleep 40"], { timeoutMs: 6000 });
+await new Promise(r => setTimeout(r, 3500));
+const during = count();
+const result = await started;   // the timeout fires terminate() with the job
+await new Promise(r => setTimeout(r, 1000));
+const after = count();
+const out = { jobAvailable, jobObject: result.jobObject, timedOut: result.timedOut, pingBefore: before, pingDuring: during, pingAfter: after, grandchildKilled: during > before && after <= before };
+console.log(JSON.stringify(out, null, 2));
+process.exit(out.grandchildKilled ? 0 : 1);