modwright 0.1.1 → 0.1.3

package/dist/index.js

@@ -8,7 +8,7 @@ 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 ?? 30_000);
+const RETIRE_GRACE_MS = Number(process.env.MODWRIGHT_RETIRE_GRACE_MS ?? 15 * 60_000);
 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;
@@ -68,15 +68,31 @@ class ServerProcess {
         this.child.on("exit", () => {
             this.exited = true;
         });
+        this.child.stdin.on("error", (err) => {
+            this.stdinBroken = true;
+            log(`server generation ${this.generation}: stdin ${err.code ?? err.message}; treating it as gone`);
+        });
+        this.child.on("error", (err) => {
+            this.exited = true;
+            log(`server generation ${this.generation}: ${err.message}`);
+        });
     }
+    stdinBroken = false;
     onMessage(listener) {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
     send(raw) {
-        if (this.exited || !this.child.stdin || this.child.stdin.destroyed)
+        if (this.exited || this.stdinBroken || !this.child.stdin || this.child.stdin.destroyed)
             return false;
-        this.child.stdin.write(`${raw}\n`);
+        try {
+            this.child.stdin.write(`${raw}\n`);
+        }
+        catch (err) {
+            this.stdinBroken = true;
+            log(`server generation ${this.generation}: write failed (${err.message}); treating it as gone`);
+            return false;
+        }
         return true;
     }
     kill() {
@@ -100,7 +116,6 @@ class Supervisor {
     swapQueued = false;
     closing = false;
     initializeRaw;
-    initializeId;
     initializedSeen = false;
     routes = new Map();
     serverRequests = new Map();
@@ -135,7 +150,6 @@ class Supervisor {
         const active = this.active;
         if (msg.method === "initialize" && msg.id !== undefined && msg.id !== null) {
             this.initializeRaw = raw;
-            this.initializeId = msg.id;
         }
         else if (msg.method === "notifications/initialized") {
             this.initializedSeen = true;
@@ -157,7 +171,7 @@ class Supervisor {
                 }
             }
         }
-        if (!active || active.exited) {
+        const answerNotRunning = () => {
             if (msg.id !== undefined && msg.id !== null && msg.method !== undefined) {
                 const response = {
                     jsonrpc: "2.0",
@@ -171,14 +185,23 @@ class Supervisor {
                 };
                 process.stdout.write(`${JSON.stringify(response)}\n`);
             }
+        };
+        if (!active || active.exited) {
+            answerNotRunning();
             return;
         }
-        if (msg.id !== undefined && msg.id !== null && msg.method !== undefined) {
-            const key = idKey(msg.id);
+        const key = msg.id !== undefined && msg.id !== null && msg.method !== undefined ? idKey(msg.id) : undefined;
+        if (key !== undefined) {
             this.routes.set(key, active);
             active.pending.add(key);
         }
-        active.send(raw);
+        if (!active.send(raw)) {
+            if (key !== undefined) {
+                this.routes.delete(key);
+                active.pending.delete(key);
+            }
+            answerNotRunning();
+        }
     }
     fromServer(server, msg, raw) {
         if (msg.id !== undefined && msg.id !== null && msg.method === undefined) {
@@ -285,6 +308,7 @@ class Supervisor {
             }
             if (this.initializedSeen) {
                 process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}\n`);
+                process.stdout.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/prompts/list_changed" })}\n`);
             }
         }
         finally {

package/dist/server.js

@@ -3,10 +3,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { pathExists, tail } from "./core/fsutil.js";
-import { describeProject, findProjectFile, loadProject } from "./core/project/index.js";
+import { describeProject, findProjectFile, loadProject, locateProjectFile } from "./core/project/index.js";
 import { userDataDir } from "./core/home.js";
 import { applyDataFetch, applyManagedInstall, checkToolchain, featureReadiness, locateTool, planDataFetch, planDataMemory, planManagedInstall, planToolMemory, readinessSummary, TOOL_SPECS, toolsToLocate } from "./core/toolchain/index.js";
 import { loadUserConfig } from "./core/userconfig.js";
+import { describeNeeds, isProjectTrusted, planTrust, projectTrustNeeds, trustRefusal } from "./core/trust.js";
 import { runCompat } from "./core/compat/check.js";
 import { SignatureRegistry, triageLogs } from "./core/logs/index.js";
 import { buildContext, createValidatorRegistry, runValidators } from "./core/validate/index.js";
@@ -16,12 +17,13 @@ import { armBridge, bridgeCandidateDirs, bridgeStatus, cetLogCandidates, listPen
 import { runTestPlan } from "./core/testplan/index.js";
 import { applyBuildLedgerHook, applyClaimTransition, applyDecisionRecord, applyValidateLedgerHook, checkLedger, claimsFilePath, listClaims, loadClaims, loadDecisions, saveClaims, saveDecisions, showClaim, } from "./core/ledger/index.js";
 import { IndexStore, defaultCacheDir, findLegacyIndex, indexFile, legacyIndexHint, loadKnowledge, resolveIndexFile, searchFacts, } from "./core/knowledge/index.js";
-import { pathExists as fileExists } from "./core/fsutil.js";
 import { executePlan, listBackups, restoreBackup } from "./core/safety/index.js";
 import { readTextIfExists } from "./core/fsutil.js";
 import * as path from "node:path";
 import { promises as fs } from "node:fs";
 import { crossCheckIdentities, findConflicts, listMods, sharedIdentities } from "./core/mods.js";
+import { buildOwnershipIndex, lookupOwnership, managerConflicts } from "./core/ownership/index.js";
+import { collectWrites, contestedKeys, duplicateCopies, whatTouches, whoTouches } from "./core/writes/index.js";
 import { resolveLogs, resolveRoots } from "./core/surfaceutil.js";
 import { SURFACES, getSurface, installGameVersion, resolveInstall, surfaceIds } from "./surfaces/index.js";
 import { CONVERTERS, convert as runConvert, defaultLocateTool as defaultTextLocateTool, extractTemplate, fieldDiff, getTemplate, invalidateTemplate, listTemplates, } from "./core/text/index.js";
@@ -183,8 +185,12 @@ server.registerTool("find_conflicts", {
         installPath: installPathArg,
         rootIds: z.array(z.string()).optional().describe("Restrict to these mod root ids."),
         limit: z.number().int().positive().default(100).describe("Max conflicts to return."),
+        mo2Instance: z
+            .string()
+            .optional()
+            .describe("A portable Mod Organizer 2 instance (its folder or ModOrganizer.ini); global instances are found automatically."),
     },
-}, async ({ game, installPath, rootIds, limit }) => {
+}, async ({ game, installPath, rootIds, limit, mo2Instance }) => {
     const surface = getSurface(game);
     if (!surface)
         return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
@@ -202,10 +208,22 @@ server.registerTool("find_conflicts", {
         identityUnreadableCount = scanned.unreadable.length;
         identityUnreadable = scanned.unreadable.slice(0, IDENTITY_UNREADABLE_LIMIT);
     }
+    let managed;
+    if (surface.managedDataDir !== undefined) {
+        const index = await buildOwnershipIndex(surface, install, mo2Instance ? { mo2Instance } : {});
+        const mo2 = index.sources.find((src) => src.id === "mo2");
+        if (mo2?.active) {
+            const found = managerConflicts(index, limit);
+            managed = { source: mo2.detail, total: found.total, conflicts: found.conflicts };
+            if (found.total > limit)
+                managed.truncated = true;
+        }
+    }
     return json({
         game: surface.id,
         modsAnalyzed: mods.length,
         conflictCount: conflicts.length,
+        managerConflicts: managed,
         skippedRoots,
         suppressedNoiseFiles,
         truncated: conflicts.length > limit,
@@ -215,10 +233,108 @@ server.registerTool("find_conflicts", {
         identityUnreadable,
         identityUnreadableTruncated: identityUnreadableCount > IDENTITY_UNREADABLE_LIMIT ? true : undefined,
         note: "File-level analysis, and only for roots where mods share one deploy tree. " +
-            "See skippedRoots for what was excluded and why.",
+            "See skippedRoots for what was excluded and why." +
+            (managed
+                ? " managerConflicts are between Mod Organizer 2's mod folders, each with the winner the game sees and the mods it overrides."
+                : ""),
         guidance: surface.guidance,
     });
 });
+server.registerTool("owner_of", {
+    title: "Which mod owns this file",
+    description: "Say which installed mod a file comes from, and which copy the game actually sees when several provide it. " +
+        "Accepts absolute paths, paths relative to the game folder, a trailing part of a path (SKSE/Plugins/foo.dll), " +
+        "or a bare file name — e.g. a DLL named in a crash log, a path from triage_logs. Sources: the game's own mod " +
+        "roots (a mod folder owns what is under it), Mod Organizer 2 (the active profile's mod folders in priority " +
+        "order, plus Overwrite; for games where the mapping is known), and Vortex deployment manifests. Each result " +
+        "says how the winner was decided; `sources` says what each source could see, and `unattributedRoots` lists " +
+        "loose-file folders whose files no source can attribute. Files inside packed archives are not indexed yet.",
+    inputSchema: {
+        game: gameArg,
+        installPath: installPathArg,
+        paths: z.array(z.string().min(1)).min(1).max(50).describe("Files to attribute."),
+        mo2Instance: z
+            .string()
+            .optional()
+            .describe("A portable Mod Organizer 2 instance (its folder or ModOrganizer.ini); global instances are found automatically."),
+        limit: z.number().int().positive().max(200).default(20).describe("Max matches per path (a bare file name can match many)."),
+    },
+}, async ({ game, installPath, paths, mo2Instance, limit }) => {
+    const surface = getSurface(game);
+    if (!surface)
+        return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
+    const install = await resolveInstall(surface, installPath);
+    if (!install)
+        return fail(`No install detected for ${surface.name}.`);
+    const index = await buildOwnershipIndex(surface, install, mo2Instance ? { mo2Instance } : {});
+    return json({
+        game: surface.id,
+        install: install.root,
+        sources: index.sources,
+        indexedPaths: index.entries.size,
+        unattributedRoots: index.unattributedRoots.length > 0 ? index.unattributedRoots : undefined,
+        results: paths.map((p) => lookupOwnership(index, p, limit)),
+        note: "Owners come only from what is on disk: a mod folder, a manager's own records. Nothing is inferred from " +
+            "file names. A path no mod claims is reported as such, with the likely reasons.",
+    });
+});
+server.registerTool("who_touches", {
+    title: "Which mods write this record or asset",
+    description: "Read every installed mod's data and report who writes a given key — at the level the game merges on, not the " +
+        "file level: a TweakDB record or flat (Cyberpunk 2077, TweakXL YAML and .tweak files), a stats entry or field " +
+        "(Baldur's Gate 3, inside paks and unpacked mods), an asset or data entry/field (Stardew Valley Content Patcher " +
+        "packs, Includes followed). Give `key` for who writes it (a record returns its flats too; an asset its entries), " +
+        "`mod` for everything one mod writes and where another mod writes the same key, or neither for every key two or " +
+        "more mods contend for. This says who touches a key, not who wins: the winner depends on the game's load order. " +
+        "Writes behind a Content Patcher When, or with {{tokens}}, are marked conditional.",
+    inputSchema: {
+        game: gameArg,
+        installPath: installPathArg,
+        key: z.string().min(1).optional().describe("A record, flat, stats entry, asset or entry, e.g. Items.Preset_Masamune_Default, stats:Projectile_Fireball, Data/Objects#128."),
+        mod: z.string().min(1).optional().describe("A mod (or unit) id or name, for what it writes."),
+        rootIds: z.array(z.string()).optional().describe("Restrict to these mod root ids."),
+        limit: z.number().int().positive().max(500).default(50).describe("Max keys (or writes per mod) to return."),
+    },
+}, async ({ game, installPath, key, mod, rootIds, limit }) => {
+    const surface = getSurface(game);
+    if (!surface)
+        return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
+    const install = await resolveInstall(surface, installPath);
+    if (!install)
+        return fail(`No install detected for ${surface.name}.`);
+    if (!surface.extractWrites) {
+        return json({
+            game: surface.id,
+            supported: false,
+            note: `No write-set extraction for ${surface.name} yet (supported: Cyberpunk 2077 tweaks, Baldur's Gate 3 stats, Stardew Valley Content Patcher).`,
+        });
+    }
+    const collection = await collectWrites(surface, install, rootIds ? { rootIds } : {});
+    const { errors, ...coverage } = collection.coverage;
+    const copies = duplicateCopies(collection);
+    const result = key
+        ? { mode: "key", ...whoTouches(collection, key, limit) }
+        : mod
+            ? { mode: "mod", query: mod, writers: whatTouches(collection, mod, limit) }
+            : { mode: "contested", ...contestedKeys(collection, limit) };
+    return json({
+        game: surface.id,
+        install: install.root,
+        coverage: {
+            ...coverage,
+            writers: collection.writers.length,
+            errorCount: errors.length,
+            errors: errors.slice(0, 25),
+        },
+        ...(copies.length > 0 ? { duplicateCopies: copies } : {}),
+        ...result,
+        note: "Static: read from the mods' files, never from the running game. 'contested' means two or more mods write the " +
+            "key and not only by appending; which one the game ends up with depends on load order, which this tool does " +
+            "not decide. A mod the game does not load (marked 'inactive') is listed but never contests, and copies of one " +
+            "mod ('duplicateCopies') count once: the game loads one of them. Code that writes at runtime (redscript, CET, " +
+            "SMAPI C# mods, Script Extender Lua) is not seen here.",
+    });
+});
 server.registerTool("load_order", {
     title: "Read load order",
     description: "Read the game's explicit load order and cross-check it against what is " +
@@ -340,9 +456,7 @@ server.registerTool("project_info", {
 }, async ({ path: start }) => {
     const from = start ?? process.cwd();
     try {
-        const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json")
-            ? from
-            : await findProjectFile(from);
+        const file = await locateProjectFile(from);
         if (!file) {
             return json({
                 found: false,
@@ -368,9 +482,11 @@ server.registerTool("check_toolchain", {
         "with data=<id> fetches a data folder ModWright can fetch (Stardew Valley's wiki pages) and remembers it; " +
         "action 'remember' records a tool's path in the " +
         "per-user config so every session finds it (no environment variable, no restart); " +
-        "'forget' drops it. Both are dry-run unless mode is 'apply'.",
+        "'forget' drops it. 'trust' records a project root (projectPath) as allowed to run its own toolchain overrides and " +
+        "exec build steps; until then an applied build, convert, template extract or index build that would run them is " +
+        "refused. 'untrust' removes it. All of these are dry-run unless mode is 'apply'.",
     inputSchema: {
-        action: z.enum(["check", "remember", "forget", "install"]).default("check").describe("check (default) reports; remember/forget change the per-user config; install fetches a pinned tool into ModWright's tools folder (dry-run shows the file, source, size and sha256 first), or with data a fetchable data folder (dry-run lists every URL first)."),
+        action: z.enum(["check", "remember", "forget", "install", "trust", "untrust"]).default("check").describe("check (default) reports; remember/forget change the per-user config; trust/untrust change the trusted-projects list for projectPath; install fetches a pinned tool into ModWright's tools folder (dry-run shows the file, source, size and sha256 first), or with data a fetchable data folder (dry-run lists every URL first)."),
         game: gameArg.optional().describe("Restrict to tools used by this game (check only)."),
         projectPath: z
             .string()
@@ -380,9 +496,47 @@ server.registerTool("check_toolchain", {
         toolPath: z.string().optional().describe("remember: absolute path to the executable, or the folder that directly holds it."),
         data: z.string().optional().describe("remember/forget/install: a data folder id instead of a tool, e.g. 'valheim.jotunn' (a Jotunn checkout) or 'stardewvalley.wiki' (saved wiki pages); check_toolchain game=<id> lists the ones a game reads."),
         dataPath: z.string().optional().describe("remember with data: absolute path to that folder. install with data: where to save it (default: ModWright's per-user data folder)."),
-        mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("remember/forget: dry-run shows the config change; apply writes it (backing up the old file)."),
+        mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("remember/forget/trust/untrust: dry-run shows the config change; apply writes it (backing up the old file)."),
     },
 }, async ({ action, game, projectPath, tool, toolPath, data, dataPath, mode }) => {
+    if (action === "trust" || action === "untrust") {
+        if (tool || toolPath || data || dataPath)
+            return fail(`${action} takes projectPath only.`);
+        if (!projectPath)
+            return fail(`${action} needs projectPath: the mod project's modwright.json or its folder.`);
+        let resolved;
+        try {
+            resolved = await resolveProject(projectPath);
+        }
+        catch (error) {
+            return fail(`Could not load project: ${error.message}`);
+        }
+        const planned = await planTrust(action, resolved.root, resolved.project.name);
+        if (!planned.ok)
+            return fail(planned.error);
+        const report = await executePlan(planned.plan, {
+            mode,
+            confidence: { level: "high", assumptions: ["The trusted-projects list is ModWright's own file; nothing in a game or a project is touched."] },
+        });
+        const needs = projectTrustNeeds(resolved.project);
+        return json({
+            action,
+            project: resolved.project.name,
+            root: planned.root,
+            mode,
+            applied: report.applied,
+            file: planned.file,
+            runs: { exec: needs.exec, toolchain: Object.fromEntries(needs.toolchain.map((id) => [id, resolved.project.toolchain?.[id]])) },
+            ...(planned.previous ? { previous: planned.previous } : {}),
+            operations: report.operations,
+            ...(report.backupDir ? { backupDir: report.backupDir } : {}),
+            note: report.applied
+                ? action === "trust"
+                    ? `Trusted. Applied builds, converts, extracts and index builds may now run this project's exec steps and toolchain overrides.`
+                    : `No longer trusted. Its exec steps and toolchain overrides are refused until it is trusted again.`
+                : `Dry run: nothing written. Read what it runs (runs) first; repeat with mode 'apply' to ${action} it.`,
+        });
+    }
     if ((action === "remember" || action === "forget") && data) {
         if (tool)
             return fail("Give either tool or data, not both.");
@@ -501,9 +655,12 @@ server.registerTool("check_toolchain", {
     }
     let projectOverrides;
     let project;
+    let projectRoot;
     if (projectPath) {
         try {
-            project = (await loadProject(projectPath)).project;
+            const loaded = await loadProject(projectPath);
+            project = loaded.project;
+            projectRoot = loaded.root;
             projectOverrides = project.toolchain;
         }
         catch (error) {
@@ -521,11 +678,13 @@ server.registerTool("check_toolchain", {
             if (spec && !located.has(id))
                 located.set(id, await locateTool(spec, { projectOverrides, probe: "trusted", userTools: userConfig.config.tools }));
         }
-        const indexBuilt = surface.index ? await fileExists(resolveIndexFile(surface.id).file) : undefined;
+        const indexBuilt = surface.index ? await pathExists(resolveIndexFile(surface.id).file) : undefined;
         features = featureReadiness(surface, [...located.values()], { ...(project ? { project } : {}), ...(indexBuilt !== undefined ? { indexBuilt } : {}), userData: userConfig.config.data });
     }
+    const trusted = projectRoot ? await isProjectTrusted(projectRoot) : undefined;
     return json({
         game: surfaceId,
+        ...(projectRoot ? { project: { root: projectRoot, trusted, ...(trusted ? {} : { note: "Not trusted: an applied build, convert, extract or index build refuses to run its exec steps or toolchain overrides until check_toolchain action=trust." }) } } : {}),
         ...(features ? { summary: readinessSummary(features), features } : {}),
         found: tools.filter((t) => t.found).length,
         missing: tools.filter((t) => !t.found).map((t) => t.id),
@@ -556,7 +715,11 @@ server.registerTool("triage_logs", {
         "which failed and why, with the first error's explanation and usual fix. Pass the " +
         "returned offsets and offsetKeys back as offsets/offsetKeys for incremental triage after " +
         "the next launch (the keys let a re-created log of identical size be read again). " +
-        "Stale and zero-byte logs are reported as such rather than trusted.",
+        "Stale and zero-byte logs are reported as such rather than trusted. Where a framework " +
+        "logs who did what (SMAPI's 'X edited Data/Objects', TweakXL's file read order, ArchiveXL " +
+        "merges and localization overwrites, Red Hot Tools' missing resources), the verdict's " +
+        "`attribution` groups those lines by subject, contested subjects first: the log's own answer " +
+        "to 'which mod is doing this'. Pass attributionFor to narrow it to one asset, record or mod.",
     inputSchema: {
         game: gameArg,
         installPath: installPathArg,
@@ -574,15 +737,20 @@ server.registerTool("triage_logs", {
             .describe("Per log id file identities (offsetKeys) from the same previous result."),
         maxLines: z.number().int().positive().max(20000).optional(),
         includeFindings: z.boolean().default(true),
+        attributionFor: z
+            .string()
+            .optional()
+            .describe("Keep only attribution entries whose subject, actor or content pack contains this text " +
+            "(case-insensitive): an asset or record for 'who touched this', a mod name for 'what did it touch'."),
     },
-}, async ({ game, installPath, since, offsets, offsetKeys, maxLines, includeFindings }) => {
+}, async ({ game, installPath, since, offsets, offsetKeys, maxLines, includeFindings, attributionFor }) => {
     const surface = getSurface(game);
     if (!surface)
         return fail(`Unknown game "${game}". Known: ${surfaceIds().join(", ")}`);
     const install = await resolveInstall(surface, installPath);
     if (!install)
         return fail(`No install detected for ${surface.name}.`);
-    const verdict = await triageLogs(surface, install, registry, { since, offsets, offsetKeys, maxLines });
+    const verdict = await triageLogs(surface, install, registry, { since, offsets, offsetKeys, maxLines }, { attributionFor });
     return json({
         ...verdict,
         signatureCount: registry.forGame(surface.id).length,
@@ -632,7 +800,7 @@ server.registerTool("load_order_diff", {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         let snapshotDir = path.join(userDataDir(), "snapshots");
         if (projectPath) {
-            const projectFile = (await pathExists(projectPath)) && projectPath.toLowerCase().endsWith(".json") ? projectPath : await findProjectFile(projectPath);
+            const projectFile = await locateProjectFile(projectPath);
             if (!projectFile)
                 return fail(`No modwright.json found at or above ${projectPath}.`);
             snapshotDir = path.join(path.dirname(path.resolve(projectFile)), ".modwright", "snapshots");
@@ -686,7 +854,7 @@ function getStore(gameId, reopen = false) {
             legacyStores.set(gameId, legacy);
         else
             legacyStores.delete(gameId);
-        pending = fileExists(file).then((exists) => (exists ? IndexStore.open(file) : undefined));
+        pending = pathExists(file).then((exists) => (exists ? IndexStore.open(file) : undefined));
         stores.set(gameId, pending);
     }
     return pending;
@@ -867,10 +1035,15 @@ server.registerTool("build_index", {
     let toolOverrides;
     if (projectPath) {
         try {
-            const file = (await pathExists(projectPath)) && projectPath.toLowerCase().endsWith(".json") ? projectPath : await findProjectFile(projectPath);
+            const file = await locateProjectFile(projectPath);
             if (!file)
                 return fail(`No modwright.json found at or above ${projectPath}.`);
-            toolOverrides = (await loadProject(file)).project.toolchain;
+            const loaded = await loadProject(file);
+            toolOverrides = loaded.project.toolchain;
+            const used = Object.keys(toolOverrides ?? {}).filter((id) => TOOL_SPECS.find((s) => s.id === id)?.usedBy.includes(surface.id));
+            if (used.length > 0 && !(await isProjectTrusted(loaded.root))) {
+                return fail(trustRefusal(loaded.root, `its modwright.json overrides the tool path(s) for ${used.join(", ")}`));
+            }
         }
         catch (error) {
             return fail(`Could not load project for tool overrides: ${error.message}`);
@@ -881,7 +1054,7 @@ server.registerTool("build_index", {
     if (legacy) {
         return json({ game: surface.id, rebuilt: false, file: legacy.file, legacyIndex: legacy.file, note: `${legacyIndexHint(surface.id, legacy)} lookup already uses it. Pass force to build a fresh index in the new location instead.` });
     }
-    if (!force && (await fileExists(file))) {
+    if (!force && (await pathExists(file))) {
         const existing = await surface.index.info(install);
         if (!existing.stale)
             return json({ ...existing, note: "Index already exists; pass force to rebuild." });
@@ -960,7 +1133,10 @@ server.registerTool("validate", {
     });
     const findings = includeInfo ? report.findings : report.findings.filter((finding) => finding.severity !== "info");
     const blockingFiles = report.findings.filter((f) => f.severity === "block" && !f.suppressedBy).map((f) => f.file);
-    const ledger = await applyValidateLedgerHook(resolved.root, blockingFiles, changedFiles, "validate");
+    const narrowed = Boolean(ids?.length) || Boolean(groups?.length) || cheapOnly;
+    const ledger = narrowed
+        ? { skipped: true, applied: [], refused: [], reason: "a run narrowed by rule, groups or cheapOnly never promotes a claim; run the full set" }
+        : await applyValidateLedgerHook(resolved.root, blockingFiles, changedFiles, "validate");
     return json({
         ...report,
         findings: findings.slice(0, 200),
@@ -1025,7 +1201,13 @@ server.registerTool("build", {
     const ledger = mode === "apply" && !result.failed && result.manifestPath
         ? await applyBuildLedgerHook(resolved.root, result.manifestPath, "build")
         : { skipped: true, applied: [], refused: [] };
-    return json({ ...result, summary, ledger });
+    let trust;
+    if (mode === "dry-run") {
+        const what = describeNeeds(projectTrustNeeds(resolved.project));
+        if (what && !(await isProjectTrusted(resolved.root)))
+            trust = { trusted: false, note: trustRefusal(resolved.root, what) };
+    }
+    return json({ ...result, summary, ledger, ...(trust ? { trust } : {}) });
 });
 const RELOAD_PATH_LIMIT = 200;
 function trimReload(reload) {
@@ -1113,13 +1295,19 @@ server.registerTool("rollback", {
         "purpose, entry count, how many of those entries are junction pointers rather than content, and total " +
         "size. With a backupId it restores that backup: dry-run by default, and every file's sha256 is re-checked " +
         "against the manifest immediately before it is written back. A junction is recreated as a junction, never " +
-        "as a copy of what it pointed at.",
+        "as a copy of what it pointed at. A restore writes only under the project and the game's detected mod roots unless " +
+        "allowOutsideRoots is set.",
     inputSchema: {
         path: z.string().optional().describe("modwright.json path or a directory to search from. Default: current directory."),
         backupId: z.string().optional().describe("The stamp naming one backup directory under .modwright/backups (from this tool's own listing). Omit to list."),
         mode: z.enum(["dry-run", "apply"]).default("dry-run").describe("dry-run reports what would be restored without writing a byte."),
+        installPath: installPathArg,
+        allowOutsideRoots: z
+            .boolean()
+            .default(false)
+            .describe("Restore entries outside the project and the game's mod roots too. Off by default: a backup that names any other path is refused whole."),
     },
-}, async ({ path: start, backupId, mode }) => {
+}, async ({ path: start, backupId, mode, installPath, allowOutsideRoots }) => {
     const resolved = await projectOrFail(start);
     if ("isError" in resolved)
         return resolved;
@@ -1141,17 +1329,30 @@ server.registerTool("rollback", {
     if (!(await pathExists(backupDir))) {
         return fail(`No backup "${backupId}" under ${backupRoot}. Call rollback with no backupId to list what is there.`);
     }
+    let confineTo;
+    let noInstall = false;
+    if (!allowOutsideRoots) {
+        const surface = getSurface(resolved.project.game);
+        const install = surface ? await resolveInstall(surface, installPath).catch(() => undefined) : undefined;
+        noInstall = !install;
+        confineTo = [resolved.root, ...(surface && install ? surface.modRoots(install).map((r) => r.path) : [])];
+    }
     try {
-        const report = await restoreBackup(backupDir, { mode });
-        return json({ ...report, backupId, backupDir });
+        const report = await restoreBackup(backupDir, { mode, ...(confineTo ? { confineTo } : {}) });
+        const operations = report.operations.map(({ op, ...rest }) => ({
+            ...rest,
+            op: "content" in op ? { kind: op.kind, path: op.path, bytes: rest.sizeBytes } : op,
+        }));
+        return json({ ...report, operations, backupId, backupDir });
     }
     catch (error) {
-        return fail(`rollback failed: ${error.message}`);
+        const hint = noInstall ? " The game's install was not detected, so only the project counts; pass installPath to add its mod roots." : "";
+        return fail(`rollback failed: ${error.message}${hint}`);
     }
 });
 server.registerTool("reload_plan", {
     title: "Classify what a set of deployed paths needs to take effect",
-    description: "Map deployed paths to a reload recommendation — hot, hot-degraded, save-reload, restart or unknown — " +
+    description: "Map deployed paths to a reload recommendation — hot, hot-degraded, save-reload, restart or unknown (none when nothing was written) — " +
         "using the project's own reload.rules first and then the per-surface table, and reduce them to the single " +
         "most conservative answer with its caveats. An unmatched path is reported as unknown ('restart to be sure'), " +
         "never promoted. ModWright never launches the game and never sends a reload command; this is a " +
@@ -1234,12 +1435,18 @@ server.registerTool("bridge", {
         timeoutSeconds: z.number().positive().max(300).optional().describe("'poll': override the computed budget; still capped at 300s."),
     },
 }, async ({ action, game, installPath, path: start, mode, probes, armForSeconds, grant, allowMutate, windowSeconds, planId, planPath, runId, id, nonce, probeCount, timeoutSeconds }) => {
+    const planFields = { planId, planPath, runId };
+    const givenPlan = Object.entries(planFields).filter(([, v]) => v !== undefined);
+    if (givenPlan.length > 0 && givenPlan.length < 3) {
+        const missing = Object.entries(planFields).filter(([, v]) => v === undefined).map(([k]) => k);
+        return fail(`planId, planPath and runId go together; ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} missing.`);
+    }
     let projectGame;
     let projectRoot;
     if (start) {
         try {
             const from = start;
-            const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json") ? from : await findProjectFile(from);
+            const file = await locateProjectFile(from);
             if (!file)
                 return fail(`No modwright.json found at or above ${from}.`);
             const loaded = await loadProject(file);
@@ -1540,7 +1747,7 @@ const TEMPLATE_SURFACES = ["baldursgate3", "cyberpunk2077"];
 const TEMPLATE_PERMISSIONS = ["never-redistribute", "maintainer-own", "declared-dependency"];
 async function resolveProject(start) {
     const from = start ?? process.cwd();
-    const file = (await pathExists(from)) && from.toLowerCase().endsWith(".json") ? from : await findProjectFile(from);
+    const file = await locateProjectFile(from);
     if (!file)
         throw new NoProjectError(`No modwright.json found at or above ${from}.`);
     return loadProject(file);
@@ -1566,15 +1773,24 @@ server.registerTool("convert", {
     },
 }, async ({ conversionId, source, dest, mode, verifyRoundTrip, path: projectPath }) => {
     let overrides;
-    if (projectPath) {
+    let projectTrust;
+    let backupRoot;
+    const projectStart = projectPath ?? (path.isAbsolute(dest) ? (await findProjectFile(path.dirname(dest))) : undefined);
+    if (projectStart) {
         try {
-            overrides = (await resolveProject(projectPath)).project.toolchain;
+            const resolved = await resolveProject(projectStart);
+            backupRoot = path.join(resolved.root, ".modwright", "backups");
+            if (projectPath) {
+                overrides = resolved.project.toolchain;
+                if (overrides && Object.keys(overrides).length > 0)
+                    projectTrust = { root: resolved.root, trusted: await isProjectTrusted(resolved.root) };
+            }
         }
         catch {
         }
     }
     try {
-        const report = await runConvert(conversionId, source, dest, { mode, verifyRoundTrip, locateTool: defaultTextLocateTool(overrides, mode === "apply" ? "all" : "none") });
+        const report = await runConvert(conversionId, source, dest, { mode, verifyRoundTrip, locateTool: defaultTextLocateTool(overrides, mode === "apply" ? "all" : "none", projectTrust), ...(backupRoot ? { backupRoot } : {}) });
         return json(report);
     }
     catch (error) {
@@ -1667,7 +1883,9 @@ server.registerTool("template", {
     catch (error) {
         return fail(`Could not load project: ${error.message}`);
     }
-    const locateTool = defaultTextLocateTool(resolved.project.toolchain, action === "extract" && mode === "apply" ? "all" : action === "extract" ? "none" : "trusted");
+    const overrides = resolved.project.toolchain;
+    const projectTrust = action === "extract" && overrides && Object.keys(overrides).length > 0 ? { root: resolved.root, trusted: await isProjectTrusted(resolved.root) } : undefined;
+    const locateTool = defaultTextLocateTool(overrides, action === "extract" && mode === "apply" ? "all" : action === "extract" ? "none" : "trusted", projectTrust);
     const templateGameVersion = async (surfaceId) => {
         const gameSurface = getSurface(surfaceId);
         if (!gameSurface)

package/dist/surfaces/baldursgate3/surface.js

@@ -6,6 +6,7 @@ import { dedupeByRoot, logs, roots } from "../../core/surfaceutil.js";
 import { bg3Index } from "./index/index.js";
 import { scanModIdentities as scanBg3ModIdentities } from "./identity.js";
 import { SIGNATURES } from "./logs.js";
+import { extractBg3Writes } from "./writes.js";
 import { describeModSettingsDiff, diffModSettings, parseModSettings } from "./modsettings.js";
 import { BRIDGE_VALIDATORS } from "./validators/bridge.js";
 import { FILE_VALIDATORS } from "./validators/files.js";
@@ -112,6 +113,8 @@ export const baldursgate3 = {
         };
     },
     logSignatures: SIGNATURES,
+    extractWrites: (mod, root) => extractBg3Writes(mod, root),
+    looseUnitOf: (rootId, rel) => (rootId === "loose" ? /^(?:Mods|Public|Generated\/Public)\/([^/]+)\//i.exec(rel)?.[1] : undefined),
     index: bg3Index,
     validators: [
         ...ITEM_VALIDATORS,

package/dist/surfaces/baldursgate3/validators/story.js

@@ -228,8 +228,9 @@ const osirisNamingConvention = {
         const base = path.posix.basename(lower(ctx.target.path), ".txt");
         if (!/^[a-z0-9]+(_[a-z0-9]+){2,}$/i.test(base)) {
             findings.push(finding(osirisNamingConvention.id, "info", ctx.target.path, `Goal file name '${path.basename(ctx.target.path)}' does not obviously follow the Act_Region_Situation convention. ` +
-                `This is a naming convention, not a known build failure — no fact in knowledge/baldursgate3/ confirms a missing ` +
-                `prefix disables the story component (still an open question), so this stays informational.`, osirisNamingConvention.evidence));
+                `This is a naming convention, not a known build failure: LSLib's story compiler only warns on a name missing ` +
+                `its DB/PROC/QRY prefix (bg3.dialogue.osiris-goals.prefix-convention-is-a-compiler-warning-in-lslib), ` +
+                `so this stays informational.`, osirisNamingConvention.evidence));
         }
         const text = stripBom(await ctx.readText(ctx.target.path)).replace(/\r\n/g, "\n");
         const badPrefixRe = /\b(?!DB_|QRY_|PROC_)([A-Za-z][A-Za-z0-9_]*)\s*\(/g;
@@ -482,7 +483,6 @@ const questAddQuestCloseDiscouraged = {
         return goal.questAddClose.map((occ) => finding(questAddQuestCloseDiscouraged.id, "info", targetPath, `${occ.name}(...) is used here. The documentation recommends relying on QuestUpdate instead of manually adding/closing quests.`, questAddQuestCloseDiscouraged.evidence, { line: occ.line }));
     },
 };
-const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 function collectOrigins(doc) {
     const origins = [];
     for (const region of doc.regions) {