modwright 0.1.3 → 0.1.5

package/README.md

@@ -153,7 +153,7 @@ Epic paths where they apply. Override with `installPath` on any tool, or set
 | `deploy` | Copy a built mod into the game's mod roots as one write plan. It refuses an artifact the build did not produce or one older than its sources, prunes what a previous build left behind, and defers a file the running game holds locked. Every overwrite and delete is backed up first. |
 | `rollback` | List the deploy backups under a project's `.modwright/backups/`, or restore one, re-checking every file's hash first. |
 | `reload_plan` | Classify deployed changes into hot / hot-degraded / save-reload / restart / unknown, with the caveat for each and the single most conservative recommendation. |
-| `bridge` | The in-game bridge (BG3 Script Extender, Cyberpunk 2077 CET): `stage` the bridge into a project, check its heartbeat with `status`, `arm` a probe request and `poll` for its result. |
+| `bridge` | The in-game bridge (BG3 Script Extender, Cyberpunk 2077 CET): `stage` the bridge into a project, check its heartbeat with `status`, `arm` a probe request and `poll` for its result, and `remove` it from the game when you are done. |
 | `run_tests` | Run a mod's in-game test plan (`<mod>/tests/*.yaml`) through the bridge. Probe rows are armed and polled; manual rows become a checklist. Results are written back into the plan. |
 | `ledger` | Track claims and decisions across a fix (`<mod>/ledger/`). A claim moves `authored → checker-clean → built → verified \| contradicted`, and nothing is verified without evidence. |
 | `convert` | Run one registered conversion: BG3 lsx↔lsf and xml↔loca through divine, Cyberpunk cr2w↔json through WolvenKit CLI. Each one checks its own round trip. |
@@ -305,7 +305,7 @@ What it runs, and where it writes:
 - **The in-game bridges.** While a verification bridge is deployed and the
   game runs, anything that can write the bridge's request folder can run Lua
   in the game. There is no token. Deploy a bridge only while you verify,
-  remove it afterwards, and never ship it (the release validators block a
+  remove it afterwards (`bridge action=remove`), and never ship it (the release validators block a
   build that contains it). The bridge READMEs under `bridges/` describe each
   one's trust model.
 

package/bridges/bg3-se/README.md

@@ -93,8 +93,9 @@ from running again; they do not say who wrote it. So:
 
 - deploy the bridge only to a machine and a profile you control, and only while you are
   verifying a mod;
-- remove `Mods/ModWrightBridge` from the profile when you are done, before playing normally
-  or sharing the profile;
+- remove it when you are done, before playing normally or sharing the profile:
+  `bridge action=remove path=<project> mode=apply` deletes every folder the project's
+  `withBridge` targets deployed, with a backup (a dry run first shows which);
 - never ship it. `bg3.history.bridge-never-ships` blocks a release build that contains it.
 
 ## What this bridge never does

package/bridges/bg3-se/bridge.json

@@ -17,7 +17,7 @@
     "prune": [
       "ModWrightBridge/**"
     ],
-    "note": "The deploy target a shipped SE mod uses, verbatim: `bridge stage` adds it to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit. A deploy WITHOUT `--variant withBridge` prunes the folder back out, with backup."
+    "note": "The deploy target a shipped SE mod uses, verbatim: `bridge stage` adds it to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit. A deploy without `--variant withBridge` leaves an installed bridge where it is: a variant's prune runs only in a deploy that writes that variant. Take it out with `bridge action=remove path=<project> mode=apply` when you are done verifying (dry-run first; backed up)."
   },
   "sha256": {
     "algorithm": "sha256",

package/bridges/cp2077-cet/ModWrightBridge/probes.lua

@@ -1048,6 +1048,114 @@ Probes.handlers = {
             }
         end,
     },
+    -- Workbench probes: session-tier mutations that put the world into a testable state, so
+    -- a common setup is a catalogue row rather than hand-written Lua each time. Listed in
+    -- Probes.MUTATING_KINDS below and gated on the `session` tier like the other mutating rows.
+
+    -- attested 2026-10-04: this row ran live and the entity appeared. The call:
+    --   exEntitySpawner.Spawn('base\characters\entities\gang\gang__wraith_ma.ent',
+    --                         Game.GetPlayer():GetWorldTransform(), '')
+    -- returned a userdata handle, and Game.FindEntityByID(handle) resolved the entity.
+    -- Despawn takes the RESOLVED object, not the handle, and the handle does not persist across
+    -- bridge calls, so a despawn belongs in the same cp2077.lua.eval as its spawn.
+    ["cp2077.world.spawn"] = {
+        attestation = "attested 2026-10-04 (ran live; the entity appeared)",
+        citation = "exEntitySpawner.Spawn(entPath, GetPlayer():GetWorldTransform(), appearance), a CET-added native (RTTIExtender.cpp)",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            if p.entPath == nil then
+                return errored("params.entPath is required, e.g. \"base\\characters\\entities\\gang\\gang__wraith_ma.ent\"")
+            end
+            local entPath = tostring(p.entPath)
+            local appearance = p.appearance ~= nil and tostring(p.appearance) or ""
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local pl = player()
+            if pl == nil then return failed("Game.GetPlayer() returned nil — load a save first", nil, { entPath = entPath }) end
+
+            local spawner
+            local okG = pcall(function() spawner = exEntitySpawner end)
+            if not okG or spawner == nil then
+                return missingAttested("`exEntitySpawner`", "exEntitySpawner.Spawn", { entPath = entPath })
+            end
+
+            local transform
+            local okT, e = pcall(function() transform = pl:GetWorldTransform() end)
+            if not okT then return errored("GetPlayer():GetWorldTransform() raised: " .. tostring(e), { entPath = entPath }) end
+
+            local handle
+            local okS, e2 = pcall(function() handle = exEntitySpawner.Spawn(entPath, transform, appearance) end)
+            local evidence = {
+                entPath = entPath,
+                appearance = appearance,
+                spawnedAtPlayerTransform = true,
+                note = "spawned at the player's own transform: the player is inside the entity until they separate. " ..
+                    "The entity arrives after this call returns, so `resolved` is normally false here. " ..
+                    "The id handle does not persist across bridge calls; despawn within one eval (cp2077.lua.eval) or re-find the entity.",
+            }
+            if not okS then return errored("exEntitySpawner.Spawn raised: " .. tostring(e2), evidence) end
+            evidence.handle = handle ~= nil and tostring(handle) or nil
+            if handle == nil then return failed("exEntitySpawner.Spawn returned nil for \"" .. entPath .. "\"", nil, evidence) end
+            local ent
+            pcall(function() ent = Game.FindEntityByID(handle) end)
+            evidence.resolved = ent ~= nil
+            return ok(tostring(handle), evidence)
+        end,
+    },
+
+    -- attested 2026-10-04: a teleport to x+4 moved the player by exactly that.
+    --   Game.GetTeleportationFacility():Teleport(GetPlayer(), Vector4, EulerAngles)
+    ["cp2077.player.teleport"] = {
+        attestation = "attested 2026-10-04 (ran live, read back)",
+        citation = "Game.GetTeleportationFacility():Teleport(player, Vector4, EulerAngles), from the CET wiki",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            local x, y, z = tonumber(p.x), tonumber(p.y), tonumber(p.z)
+            if x == nil or y == nil or z == nil then
+                return errored("params.x, params.y and params.z (numbers) are required")
+            end
+            local yaw = tonumber(p.yaw) or 0.0
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local pl = player()
+            if pl == nil then return failed("Game.GetPlayer() returned nil — load a save first") end
+            local evidence = {
+                x = x, y = y, z = z, yaw = yaw,
+                call = "Game.GetTeleportationFacility():Teleport(player, Vector4.new(x,y,z,1), EulerAngles.new(0,0,yaw))",
+                note = "the call and the Vector4/EulerAngles construction from the CET wiki; confirmed live 2026-10-04.",
+            }
+            local okTp, e = pcall(function()
+                Game.GetTeleportationFacility():Teleport(pl, Vector4.new(x, y, z, 1.0), EulerAngles.new(0.0, 0.0, yaw))
+            end)
+            if not okTp then return errored("Teleport raised: " .. tostring(e), evidence) end
+            return ok(true, evidence)
+        end,
+    },
+
+    -- attested 2026-10-04: the level followed 15 -> 16 -> 15, read back each time.
+    --   Game.SetLevel(kind, n, 1)   (kind defaults to "Level")
+    ["cp2077.player.level"] = {
+        attestation = "attested 2026-10-04 (ran live, read back)",
+        citation = "Game.SetLevel(kind, level, 1), from the CET wiki",
+        effect = "mutate",
+        mutates = true,
+        run = function(probe)
+            local p = params(probe)
+            local lvl = tonumber(p.level)
+            if lvl == nil then return errored("params.level (a number) is required") end
+            local kind = p.kind ~= nil and tostring(p.kind) or "Level"
+            if not have("Game") then return absent("the `Game` global", "design §8 step 4") end
+            local evidence = {
+                level = lvl, kind = kind, call = "Game.SetLevel(kind, level, 1)",
+                note = "from the CET wiki; confirmed live 2026-10-04 (level read back).",
+            }
+            local okL, e = pcall(function() Game.SetLevel(kind, lvl, 1) end)
+            if not okL then return errored("Game.SetLevel raised: " .. tostring(e), evidence) end
+            return ok(true, evidence)
+        end,
+    },
 }
 -- MODWRIGHT-PROBE-TABLE-END
 
@@ -1138,7 +1246,13 @@ end
 --- The ids allowed to mutate anything: the inventory row it always had, and
 --- (since 2026-09-11) the eval row. Named
 --- as a constant so the gate below reads as the rule it enforces.
-Probes.MUTATING_KINDS = { ["cp2077.inventory.add"] = true, ["cp2077.lua.eval"] = true }
+Probes.MUTATING_KINDS = {
+    ["cp2077.inventory.add"] = true,
+    ["cp2077.lua.eval"] = true,
+    ["cp2077.world.spawn"] = true,
+    ["cp2077.player.teleport"] = true,
+    ["cp2077.player.level"] = true,
+}
 
 --- Run one probe. NEVER throws: one probe failing can never abort the batch, and a handler
 --- that raises is reported as `error` with the raised message.

package/bridges/cp2077-cet/README.md

@@ -167,8 +167,9 @@ the request grants the `session` tier. There is no token. The nonce and the requ
 only stop a consumed or stale request from running again; they do not say who wrote it. So:
 
 - deploy the bridge only to an install you control, and only while you are verifying a mod;
-- remove `bin/x64/plugins/cyber_engine_tweaks/mods/ModWrightBridge` when you are done,
-  before playing normally;
+- remove it when you are done, before playing normally:
+  `bridge action=remove path=<project> mode=apply` deletes every folder the project's
+  `withBridge` targets deployed, with a backup (a dry run first shows which);
 - never ship it. `cp2077.history.bridge-never-ships` blocks a release build that contains it.
 
 ## What this bridge never does

package/bridges/cp2077-cet/bridge.json

@@ -26,7 +26,7 @@
     "prune": [
       "ModWrightBridge/**"
     ],
-    "note": "The deploy target `bridge stage` adds to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit; paste it in yourself only if you want it there before staging. A deploy WITHOUT `--variant withBridge` prunes the folder back out, with backup."
+    "note": "The deploy target `bridge stage` adds to the project's deploy targets when no target already names this rootId, into and variant, so a fresh project deploys the bridge without a hand edit; paste it in yourself only if you want it there before staging. A deploy without `--variant withBridge` leaves an installed bridge where it is: a variant's prune runs only in a deploy that writes that variant. Take it out with `bridge action=remove path=<project> mode=apply` when you are done verifying (dry-run first; backed up)."
   },
   "sha256": {
     "algorithm": "sha256",
@@ -43,7 +43,7 @@
     },
     {
       "path": "ModWrightBridge/probes.lua",
-      "sha256": "169a31b158edcefda6721c3b90656c59fd9f7d7bf928a96d03ef3645a5eb1991"
+      "sha256": "759015ac7c1167faecbc5d29e91f567d7c45446164544ad7d72029c115a60df6"
     },
     {
       "path": "ModWrightBridge/protocol.lua",

package/dist/core/bridge/remove.js

@@ -0,0 +1,48 @@
+import * as path from "node:path";
+import { pathExists } from "../fsutil.js";
+import { escapesRoot } from "../project/outside-root.js";
+import { executePlan, planDelete } from "../safety/index.js";
+export const BRIDGE_VARIANT = "withBridge";
+export async function planRemoveBridge(project, roots) {
+    const removals = [];
+    const operations = [];
+    for (const target of project.project.deploy?.targets ?? []) {
+        if (target.variant !== BRIDGE_VARIANT || !target.into)
+            continue;
+        const base = { rootId: target.rootId, into: target.into };
+        if (escapesRoot(target.into)) {
+            removals.push({ ...base, action: "outside-root" });
+            continue;
+        }
+        const root = roots.find((r) => r.id === target.rootId);
+        if (!root) {
+            removals.push({ ...base, action: "unknown-root" });
+            continue;
+        }
+        const dest = path.join(root.path, target.into);
+        if (await pathExists(dest)) {
+            operations.push(planDelete(dest));
+            removals.push({ ...base, path: dest, action: "remove" });
+        }
+        else {
+            removals.push({ ...base, path: dest, action: "absent" });
+        }
+    }
+    return {
+        plan: {
+            purpose: `remove the deployed bridge of ${project.project.name}`,
+            operations,
+            backupRoot: path.join(project.root, ".modwright", "backups"),
+        },
+        removals,
+    };
+}
+export async function removeBridge(project, roots, options = {}) {
+    const { plan, removals } = await planRemoveBridge(project, roots);
+    const report = await executePlan(plan, {
+        mode: options.mode ?? "dry-run",
+        ...(options.now ? { now: options.now } : {}),
+        confidence: { level: "high", assumptions: [], verifiedBy: ["the project's withBridge deploy targets", "the game's mod roots"] },
+    });
+    return { ...report, removals };
+}

package/dist/core/build/run.js

@@ -5,6 +5,7 @@ import { normalizeBuildSteps } from "../project/build-steps.js";
 import { outsideRootPaths } from "../project/outside-root.js";
 import { locateTool as coreLocateTool, TOOL_SPECS } from "../toolchain/index.js";
 import { describeNeeds, isProjectTrusted, trustRefusal } from "../trust.js";
+import { pruneDated, STAGE_RETENTION } from "../safety/retention.js";
 import { buildContext, runValidators } from "../validate/index.js";
 import { runAssertAbsentStep, runAssertPresentStep, runExecStep, runZipStep } from "./steps/core.js";
 import { runBlenderExportStep, runVerifyArchiveListingStep, runWolvenkitImportStep, runWolvenkitPackStep, } from "./steps/cyberpunk.js";
@@ -187,6 +188,7 @@ export async function runBuild(project, surface, options) {
         ? path.resolve(project.root, project.build.staging)
         : path.join(project.root, ".modwright", "cache", "build");
     const stageRoot = path.join(stagingDir, buildStamp());
+    const stagesPruned = options.mode === "apply" ? (await pruneDated(stagingDir, "stage", STAGE_RETENTION, { mode: "apply" })).expired : [];
     const outDirAbs = project.build.absOutDir;
     const locateTool = options.locateTool ?? defaultLocateTool(project, options.mode);
     const projectExclude = project.build.exclude ?? [];
@@ -310,6 +312,7 @@ export async function runBuild(project, surface, options) {
             failureReason,
             ...(failedStep ? { failedStep } : {}),
             skippedOptional,
+            ...(stagesPruned.length > 0 ? { stagesPruned } : {}),
             ...(options.mode === "dry-run" ? { skippedVariant } : {}),
             outDirAbs,
         };
@@ -323,6 +326,7 @@ export async function runBuild(project, surface, options) {
             plan: dryRunPlan,
             failed: false,
             skippedOptional,
+            ...(stagesPruned.length > 0 ? { stagesPruned } : {}),
             skippedVariant,
             outDirAbs,
         };
@@ -351,6 +355,7 @@ export async function runBuild(project, surface, options) {
         manifestPath,
         failed: false,
         skippedOptional,
+        ...(stagesPruned.length > 0 ? { stagesPruned } : {}),
         outDirAbs,
     };
 }

package/dist/core/deploy/plan.js

@@ -3,6 +3,7 @@ import * as path from "node:path";
 import { isDirectory, pathExists, walk } from "../fsutil.js";
 import { globToRegExp, isExcludedByGlobs } from "../validate/index.js";
 import { outsideRootPaths } from "../project/outside-root.js";
+import { BACKUP_RETENTION, countBackupRuns } from "../safety/retention.js";
 import { findRunningProcesses } from "../process.js";
 import { executePlan, isIdenticalFile, planCopy, planDelete, planJunction, planMkdir, planUnlink, sha256File } from "../safety/index.js";
 import { classifyReload } from "./reload.js";
@@ -116,8 +117,14 @@ export async function planDeploy(inputs) {
     const mode = inputs.mode ?? "dry-run";
     const deployMode = inputs.deployMode ?? "pak";
     const backupRoot = path.join(project.root, ".modwright", "backups");
+    const backupRuns = await countBackupRuns(backupRoot);
+    const backupWarning = backupRuns > BACKUP_RETENTION.keepRuns
+        ? `${backupRuns} backup runs under ${backupRoot}; rollback action=prune keeps the newest ${BACKUP_RETENTION.keepRuns} and anything under ${BACKUP_RETENTION.maxAgeDays} days old.`
+        : undefined;
     const blocked = [];
     const warnings = [];
+    if (backupWarning)
+        warnings.push(backupWarning);
     const assumptions = [];
     const verifiedBy = [];
     const targets = [];
@@ -535,6 +542,17 @@ export async function planDeploy(inputs) {
         ...toWrite.filter((t) => !t.locked).flatMap((t) => t.copies.map((c) => planCopy(c.from, c.to))),
         ...toWrite.filter((t) => t.locked).flatMap((t) => t.copies.map((c) => planCopy(c.from, c.to))),
     ];
+    const throughLinks = await writesThroughLinks(operations, roots, junctions.map((j) => j.linkPath));
+    if (throughLinks.size > 0) {
+        blocked.push({
+            code: "write-through-link",
+            message: `${[...throughLinks.keys()].join(", ")} ${throughLinks.size === 1 ? "is a link" : "are links"} inside a mod root, and this deploy would write through ` +
+                `${throughLinks.size === 1 ? "it" : "them"} into wherever ${throughLinks.size === 1 ? "it points" : "they point"} ` +
+                `(${[...throughLinks.values()].flat().slice(0, 3).join(", ")}${[...throughLinks.values()].flat().length > 3 ? ", ..." : ""}). ` +
+                `Remove the link, or declare it under deploy.junctions if the project owns it.`,
+            detail: { links: Object.fromEntries([...throughLinks].map(([link, paths]) => [link, paths.slice(0, 20)])) },
+        });
+    }
     const confidence = {
         level: assumptions.length > 0 ? "medium" : "high",
         assumptions,
@@ -562,6 +580,49 @@ export async function planDeploy(inputs) {
         backupRoot,
     };
 }
+async function writesThroughLinks(operations, roots, allowed) {
+    const isLink = new Map();
+    const linkAt = async (dir) => {
+        const key = normalizeForCompare(dir);
+        let known = isLink.get(key);
+        if (known === undefined) {
+            try {
+                known = (await fs.lstat(dir)).isSymbolicLink();
+            }
+            catch {
+                known = false;
+            }
+            isLink.set(key, known);
+        }
+        return known;
+    };
+    const allowedKeys = new Set(allowed.map(normalizeForCompare));
+    const rootPaths = roots.map((r) => path.resolve(r.path));
+    const found = new Map();
+    for (const op of operations) {
+        const dest = op.kind === "copy" ? op.to : "path" in op ? op.path : undefined;
+        if (!dest || op.kind === "junction" || op.kind === "unlink")
+            continue;
+        const abs = path.resolve(dest);
+        const root = rootPaths.find((r) => {
+            const rel = path.relative(r, abs);
+            return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+        });
+        if (!root)
+            continue;
+        for (let dir = path.dirname(abs); dir !== root && dir.length > root.length; dir = path.dirname(dir)) {
+            if (allowedKeys.has(normalizeForCompare(dir)))
+                break;
+            if (await linkAt(dir)) {
+                const list = found.get(dir) ?? [];
+                list.push(abs);
+                found.set(dir, list);
+                break;
+            }
+        }
+    }
+    return found;
+}
 function copyKey(from, to) {
     return `${normalizeForCompare(from)}\0${normalizeForCompare(to)}`;
 }

package/dist/core/safety/retention.js

@@ -0,0 +1,76 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+const BACKUP_NAME = /^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})(?:-\d+)?$/;
+const STAGE_NAME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-\d{3}Z$/;
+export const BACKUP_RETENTION = { keepRuns: 20, maxAgeDays: 14 };
+export const STAGE_RETENTION = { keepRuns: 3, maxAgeDays: 0 };
+function runOf(name, kind) {
+    const m = (kind === "backup" ? BACKUP_NAME : STAGE_NAME).exec(name);
+    if (!m)
+        return undefined;
+    const time = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]), Number(m[6]));
+    return { run: kind === "backup" ? name.slice(0, 15) : name, time };
+}
+export function selectExpired(names, kind, policy, now = new Date()) {
+    const byRun = new Map();
+    const ignored = [];
+    for (const name of names) {
+        const r = runOf(name, kind);
+        if (!r) {
+            ignored.push(name);
+            continue;
+        }
+        const entry = byRun.get(r.run) ?? { time: r.time, names: [] };
+        entry.names.push(name);
+        byRun.set(r.run, entry);
+    }
+    const runs = [...byRun.values()].sort((a, b) => b.time - a.time);
+    const cutoff = now.getTime() - policy.maxAgeDays * 24 * 60 * 60 * 1000;
+    const expired = [];
+    const kept = [];
+    runs.forEach((run, i) => {
+        const keep = i < policy.keepRuns || (policy.maxAgeDays > 0 && run.time >= cutoff);
+        (keep ? kept : expired).push(...run.names);
+    });
+    return { expired: expired.sort(), kept: kept.sort(), ignored: ignored.sort(), runs: runs.length };
+}
+async function folderNames(root) {
+    try {
+        return (await fs.readdir(root, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+export async function pruneDated(root, kind, policy, options = {}) {
+    const mode = options.mode ?? "dry-run";
+    const selection = selectExpired(await folderNames(root), kind, policy, options.now);
+    const report = {
+        mode,
+        root,
+        applied: false,
+        policy,
+        runs: selection.runs,
+        expired: selection.expired,
+        keptCount: selection.kept.length,
+        ignored: selection.ignored,
+    };
+    if (mode !== "apply")
+        return report;
+    const failed = [];
+    for (const name of selection.expired) {
+        try {
+            await fs.rm(path.join(root, name), { recursive: true, force: true });
+        }
+        catch (error) {
+            failed.push({ name, error: error.message });
+        }
+    }
+    report.applied = true;
+    if (failed.length > 0)
+        report.failed = failed;
+    return report;
+}
+export async function countBackupRuns(root) {
+    return selectExpired(await folderNames(root), "backup", { keepRuns: Infinity, maxAgeDays: 0 }).runs;
+}

package/dist/core/testplan/registry.js

@@ -355,6 +355,39 @@ const CP2077_PROBES = [
             "loot-container template does carry a gameTargetingComponent), and whether the game marks TSF_* isExec. Never " +
             "run in game; stays unverified until a live run exercises it.",
     },
+    {
+        kind: "cp2077.world.spawn",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Spawn an entity from a resource path at the player's transform (exEntitySpawner.Spawn), returning the entity id handle; Game.FindEntityByID resolves it.",
+        citation: "cp2077.world.spawn; exEntitySpawner is a CET-added native (RTTIExtender.cpp); attested 2026-10-04",
+        paramsSchema: z.object({ entPath: str(), appearance: z.string().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (request req-muugz1b6-94911e04, game 3.0.80.51928): spawning base\\characters\\entities\\gang\\gang__wraith_ma.ent returned a handle and the NPC appeared where the player stood. Game.FindEntityByID(handle) in the same call returned nothing: the entity arrives after the call returns, so resolved:false is the normal result, not a failure.",
+    },
+    {
+        kind: "cp2077.player.teleport",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Teleport the player to a world position (Game.GetTeleportationFacility():Teleport). Optional yaw.",
+        citation: "cp2077.player.teleport (CET wiki); attested 2026-10-04",
+        paramsSchema: z.object({ x: z.number(), y: z.number(), z: z.number(), yaw: z.number().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (request req-muugz2is-a30b1095, game 3.0.80.51928): a teleport to x+4 moved the player from -2249.30,2790.43,7.00 to -2245.30,2790.43,7.01, read back through cp2077.lua.eval.",
+    },
+    {
+        kind: "cp2077.player.level",
+        game: "cyberpunk2077",
+        context: "cet",
+        effect: "mutate",
+        status: "attested",
+        summary: "Set a player progression level (Game.SetLevel(kind, n, 1)); kind defaults to \"Level\".",
+        citation: "cp2077.player.level (CET wiki); attested 2026-10-04",
+        paramsSchema: z.object({ level: z.number().int(), kind: z.string().optional() }).strict(),
+        evidence: "Ran live 2026-10-04 (requests req-muugz2is-a30b1095 and req-muugz457-1ded47cb, game 3.0.80.51928): Game.SetLevel(\"Level\", n, 1) moved the player level 15 to 16 and back to 15, each read back with StatsSystem.GetStatValue(player, gamedataStatType.Level).",
+    },
 ];
 export const PROBE_CATALOG = [...BG3_PROBES, ...CP2077_PROBES];
 const BY_KIND = new Map(PROBE_CATALOG.map((entry) => [entry.kind, entry]));

package/dist/core/writes/index.js

@@ -47,6 +47,15 @@ export async function collectWrites(surface, install, options = {}) {
         }
         for (const err of extraction.errors)
             collection.coverage.errors.push({ writerId: mod.id, ...err });
+        for (const r of extraction.repeatedKeys ?? []) {
+            (collection.repeatedKeys ??= []).push({
+                writerId: r.unit ? `${mod.id}/${r.unit}` : mod.id,
+                name: r.unit ?? mod.name,
+                file: r.file,
+                key: r.key,
+                lines: r.lines,
+            });
+        }
         for (const write of extraction.writes) {
             const writerId = write.unit ? `${mod.id}/${write.unit}` : mod.id;
             scanned.add(writerId);

package/dist/index.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
-import { promises as fs, watchFile, unwatchFile } from "node:fs";
+import { appendFileSync, mkdirSync, promises as fs, watchFile, unwatchFile } from "node:fs";
 import * as path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
+import { userDataDir } from "./core/home.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const SERVER_ENTRY = process.env.MODWRIGHT_SERVER_ENTRY ?? path.join(here, "server.js");
 const STAMP_FILE = process.env.MODWRIGHT_BUILD_STAMP ?? path.join(here, ".build-stamp");
 const STAMP_POLL_MS = Number(process.env.MODWRIGHT_STAMP_POLL_MS ?? 2000);
 const RETIRE_GRACE_MS = Number(process.env.MODWRIGHT_RETIRE_GRACE_MS ?? 15 * 60_000);
+const SHUTDOWN_GRACE_MS = Number(process.env.MODWRIGHT_SHUTDOWN_GRACE_MS ?? 5000);
 const INIT_TIMEOUT_MS = 20_000;
 const RESTART_BASE_MS = Number(process.env.MODWRIGHT_RESTART_BASE_MS ?? 500);
 const RESTART_MAX_DELAY_MS = 30_000;
@@ -17,6 +19,16 @@ const SUPERVISOR_INIT_ID = "modwright-supervisor-initialize";
 function log(msg) {
     process.stderr.write(`[modwright supervisor] ${msg}\n`);
 }
+function incident(msg) {
+    log(msg);
+    try {
+        const dir = userDataDir();
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(path.join(dir, "supervisor-incidents.log"), `${new Date().toISOString()} ${msg}\n`);
+    }
+    catch {
+    }
+}
 function idKey(id) {
     return `${typeof id}:${String(id)}`;
 }
@@ -49,6 +61,10 @@ class ServerProcess {
     child;
     generation;
     pending = new Set();
+    pendingMethod = new Map();
+    pendingMethods() {
+        return [...this.pending].map((k) => this.pendingMethod.get(k) ?? "?");
+    }
     retired = false;
     exited = false;
     splitter = new LineSplitter();
@@ -115,6 +131,7 @@ class Supervisor {
     swapping = false;
     swapQueued = false;
     closing = false;
+    retiredServers = new Set();
     initializeRaw;
     initializedSeen = false;
     routes = new Map();
@@ -194,11 +211,13 @@ class Supervisor {
         if (key !== undefined) {
             this.routes.set(key, active);
             active.pending.add(key);
+            active.pendingMethod.set(key, msg.method);
         }
         if (!active.send(raw)) {
             if (key !== undefined) {
                 this.routes.delete(key);
                 active.pending.delete(key);
+                active.pendingMethod.delete(key);
             }
             answerNotRunning();
         }
@@ -212,6 +231,7 @@ class Supervisor {
             const key = idKey(msg.id);
             this.routes.delete(key);
             server.pending.delete(key);
+            server.pendingMethod.delete(key);
             process.stdout.write(`${raw}\n`);
             if (server.retired && server.pending.size === 0)
                 server.kill();
@@ -239,6 +259,7 @@ class Supervisor {
             process.stdout.write(`${JSON.stringify(response)}\n`);
         }
         server.pending.clear();
+        server.pendingMethod.clear();
         if (this.closing || server.retired || server !== this.active)
             return;
         log(`server exited unexpectedly (code ${code ?? "null"}, signal ${signal ?? "none"}); restarting`);
@@ -301,6 +322,7 @@ class Supervisor {
             log(`swapped to server generation ${next.generation} (${reason})`);
             if (previous && previous !== next) {
                 previous.retired = true;
+                this.retiredServers.add(previous);
                 if (previous.pending.size === 0)
                     previous.kill();
                 else
@@ -356,7 +378,25 @@ class Supervisor {
             clearTimeout(this.restartTimer);
         unwatchFile(STAMP_FILE);
         this.active?.kill();
-        setTimeout(() => process.exit(0), 2500).unref();
+        const busy = [...this.retiredServers].filter((s) => !s.exited && s.pending.size > 0);
+        for (const s of this.retiredServers)
+            if (!busy.includes(s))
+                s.kill();
+        for (const s of busy) {
+            incident(`shutdown: retired server generation ${s.generation} still answering ${s.pending.size} request(s) (${s.pendingMethods().join(", ")}); ` +
+                `killing it in ${SHUTDOWN_GRACE_MS} ms`);
+        }
+        if (busy.length > 0) {
+            setTimeout(() => {
+                for (const s of busy) {
+                    if (s.exited)
+                        continue;
+                    incident(`shutdown: retired server generation ${s.generation} killed with ${s.pending.size} request(s) unanswered`);
+                    s.kill();
+                }
+            }, SHUTDOWN_GRACE_MS);
+        }
+        setTimeout(() => process.exit(0), Math.max(2500, busy.length > 0 ? SHUTDOWN_GRACE_MS + 500 : 0)).unref();
     }
 }
 async function readStamp() {