@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/app-interface/shell.js

@@ -1,81 +1,2607 @@
-import { exec } from "node:child_process";
-import { readFile } from "node:fs/promises";
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { exec, execFile } from "node:child_process";
+import { readFile as fsReadFile, mkdir, writeFile, access, rm, stat, readdir, } from "node:fs/promises";
 import * as path from "node:path";
+import { promisify } from "node:util";
+import { metrics } from "@opentelemetry/api";
 import { glob } from "glob";
-import { NpmInstallError } from "../types.js";
-export class AppShell {
-    appRootDirPath;
-    fsOperationQueue;
-    constructor({ appRootDirPath, fsOperationQueue, }) {
-        this.appRootDirPath = appRootDirPath;
-        this.fsOperationQueue = fsOperationQueue;
+import JSON5 from "json5";
+import { detect, resolveCommand } from "package-manager-detector";
+import semver from "semver";
+import { normalizePath } from "vite";
+import { isProtectedCorePackage, isValidNpmPackageName, isValidNpmVersionSpec, } from "@superblocksteam/library-shared/types";
+import { bucketNpmRegistryHost, recordNpmInstall, } from "@superblocksteam/telemetry";
+import { applyPackageJsonSubstitutions, readDeclaredDependencies, } from "../../npm/apply-package-json-substitutions.js";
+import { preparePackageJsonForCloudNpm } from "../../npm/prepare-package-json-for-cloud-npm.js";
+import { parseTsxModule } from "../../parsing/parse-tsx-module.js";
+import { getErrorMeta, getLogger } from "../../util/logger.js";
+import { ToolExecutionError } from "../agent/tools2/types.js";
+import llmobs from "../llmobs/index.js";
+import { fixLucideDynamicTypeImports, isFixableLucidePath, } from "../transform/lucide-dynamic-type-imports/transformer.js";
+import { NpmInstallBlocked, NpmInstallError, scrubSecrets, } from "../types.js";
+import { execCancellable } from "./cancellable-exec.js";
+import { CLARK_APP_BLACKLIST_PATTERNS, APPLICATION_FILE_PATTERNS, STANDARD_IGNORE_PATTERNS, } from "./constants.js";
+import { DraftManager, validateFileOperation, } from "./filesystem/index.js";
+import { Linter } from "./linter.js";
+import { parseNpmJsonDiagnostic, parseNpmJsonError, parseNpmJsonSuccess, } from "./npm-error-parser.js";
+import { prepareForPrivateRegistry, shouldIgnoreInstallScripts, } from "./npm-registry.js";
+import { applyPackageSubstitutions, runVulnerabilityGate, } from "./vulnerability-gate.js";
+const execPromise = promisify(exec);
+const execFilePromise = promisify(execFile);
+// `npm install --json` emits the full install summary on stdout. The default
+// 1 MiB exec buffer can be exceeded for fat dependency trees, which would
+// fail a successful install with ERR_CHILD_PROCESS_STDIO_MAXBUFFER and reach
+// `classifyNpmExecError` with truncated stdout — defeating the `--json`
+// error-envelope contract these entry points depend on. 4 MiB comfortably
+// covers real-world npm summaries (per-package entries are tiny) while
+// keeping the worst-case buffer + parsed-object peak bounded.
+const NPM_JSON_MAX_BUFFER = 4 * 1024 * 1024;
+/** Lowest version a declared range admits; skips `workspace:`/`file:`/`*`/git. */
+function declaredRangeFloor(range) {
+    if (range == null || semver.validRange(range) == null)
+        return null;
+    const floor = semver.minVersion(range);
+    if (floor == null)
+        return null;
+    // `*` floors to 0.0.0; an exact `0.0.0` pin is real.
+    if (floor.version === "0.0.0" && semver.valid(range) == null)
+        return null;
+    return floor.version;
+}
+function emitIndexUnavailableMetric() {
+    metrics
+        .getMeter("superblocks.clark.pkg_security")
+        .createCounter("superblocks.clark.pkg_security.index_unavailable", {
+        description: "Vulnerability index unavailable during Clark package-install gate",
+    })
+        .add(1);
+}
+function emitWriteTsxParseRejectedMetric(extension) {
+    metrics
+        .getMeter("superblocks.clark.write")
+        .createCounter("superblocks.clark.write.tsx_parse_rejected", {
+        description: "Clark write rejected because TypeScript source failed Babel parse",
+    })
+        .add(1, { extension });
+}
+/**
+ * npm `--json` stdout can be prefixed with non-JSON status lines on some
+ * versions (`add foo 1.2.3\n{...}`). Slice from the first `{`.
+ */
+function parseNpmJsonStdout(stdout) {
+    if (typeof stdout !== "string" || stdout.length === 0) {
+        throw new Error("npm --json stdout contained no JSON object");
     }
-    async readFiles(patterns, globOptions) {
-        return await this.fsOperationQueue.enqueue(async () => {
-            const files = await glob(patterns, {
-                ignore: ["node_modules/**", "dist/**", "build/**", ".superblocks/**"],
-                nodir: true,
-                cwd: this.appRootDirPath,
-                ...globOptions,
-            });
-            return await Promise.all(files.map(async (file) => ({
-                type: "file",
-                filePath: path.relative(this.appRootDirPath, file),
-                content: await readFile(file, "utf-8"),
-            })));
-        });
+    const start = stdout.indexOf("{");
+    if (start < 0) {
+        throw new Error("npm --json stdout contained no JSON object");
     }
-    async runTypecheck(abortSignal) {
-        const checkForErrors = new Promise((resolve) => {
-            exec([
-                "npx tsc",
-                "--noEmit",
-                // speed up marginal typecheck
-                "--incremental",
-                // expected format
-                "--pretty false",
-                // cache in separate file to avoid conflicts with vite or user ide
-                "--tsBuildInfoFile .superblocks/app.tsbuildinfo",
-            ].join(" "), {
-                cwd: this.appRootDirPath,
-                encoding: "utf-8",
-                signal: abortSignal,
-            }, (_error, stdout, stderr) => {
-                resolve(stdout || stderr);
-            });
-        });
-        const output = await checkForErrors;
-        if (!output || typeof output !== "string") {
-            return null;
-        }
-        const parsed = output.split("\n").reduce((acc, line) => {
-            const [filePath, _rest] = line.split("(");
-            if (filePath && filePath.trim() !== "") {
-                acc[filePath] = [...(acc[filePath] || []), line];
+    return JSON.parse(stdout.slice(start));
+}
+/** True for npm `--json` failure bodies (`{ "error": ... }`), not dry-run trees. */
+function isNpmErrorEnvelope(parsed) {
+    if (parsed == null || typeof parsed !== "object")
+        return false;
+    if (!("error" in parsed))
+        return false;
+    return parsed.error != null;
+}
+/**
+ * True for an npm dry-run entry installed into the app's own `node_modules`
+ * (`<app>/node_modules/lodash`) rather than nested under a dependency
+ * (`<app>/node_modules/@scope/library/node_modules/lodash`). npm omits `path`
+ * on some shapes; treat those as top-level so a missing field cannot hide a
+ * package from the top-level CVE checks.
+ */
+function isRootNodeModulesPath(entryPath) {
+    if (typeof entryPath !== "string" || entryPath.length === 0)
+        return true;
+    return entryPath.replace(/\\/g, "/").split("/node_modules/").length <= 2;
+}
+function packageNameFromLockPath(lockPath) {
+    if (!lockPath)
+        return undefined;
+    const marker = "node_modules/";
+    const idx = lockPath.lastIndexOf(marker);
+    if (idx < 0)
+        return undefined;
+    const name = lockPath.slice(idx + marker.length);
+    return name.length > 0 ? name : undefined;
+}
+function isPackageLookupResult(value) {
+    if (value == null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.name === "string" &&
+        typeof record.version === "string" &&
+        typeof record.hasMalware === "boolean" &&
+        Array.isArray(record.advisories));
+}
+/**
+ * Map an install failure to a value in the closed `npm.outcome` enum
+ * (APPS-4189). `NpmInstallBlocked` carries the structured reason from
+ * P1.2; anything else is bucketed as `other` at the metric boundary.
+ * `normalizeNpmOutcome` enforces the allowlist a second time downstream
+ * so a stray reason value cannot leak past the emit boundary.
+ */
+function outcomeFromInstallError(err) {
+    if (err instanceof NpmInstallBlocked)
+        return err.reason;
+    return "other";
+}
+/**
+ * Pick the registry URL the install actually targeted from the most-recent
+ * `prepareForPrivateRegistry` / `maybeWriteNpmrcForDir` result. Returns
+ * `undefined` (→ `registry_host=unknown`) when no configured row was in
+ * effect, including the `unreachable` and `not-configured` cases — those
+ * are deliberately reported as `unknown` rather than guessed at public
+ * npm, so the dashboard signal "did private-registry routing actually
+ * fire?" stays honest.
+ */
+function registryUrlFromFetchResult(result) {
+    if (!result)
+        return undefined;
+    if (!result.config.configured)
+        return undefined;
+    return result.config.default?.url;
+}
+const DEFAULT_COPY_DIRECTORY_EXCLUDES = new Set([
+    ".git",
+    ".next",
+    "build",
+    "dist",
+    "node_modules",
+]);
+/**
+ * AppShell provides the primary interface for the AI agent to interact
+ * with the application environment.
+ *
+ * It encapsulates:
+ * - File system operations (read, write, delete, list, rename)
+ * - Virtual file abstraction (APIs appear as single .ts files)
+ * - Draft management for undo/redo capability
+ * - Code quality tools (linting, type checking)
+ * - Package management
+ */
+let AppShell = (() => {
+    let _instanceExtraInitializers = [];
+    let _readFiles_decorators;
+    let _runTypecheck_decorators;
+    let _runLinter_decorators;
+    let _warmLinterCache_decorators;
+    let _runNpmInstall_decorators;
+    let _runPackageManagerInstall_decorators;
+    let _installSpecificPackages_decorators;
+    let _uninstallPackages_decorators;
+    let _saveGeneratedArtifact_decorators;
+    let _readFile_decorators;
+    let _writeFile_decorators;
+    let _copyFile_decorators;
+    let _copyDirectory_decorators;
+    let _deleteFile_decorators;
+    let _listFiles_decorators;
+    let _listFilesInternal_decorators;
+    let _renameFile_decorators;
+    return class AppShell {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _readFiles_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.readFiles" })];
+            _runTypecheck_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runTypecheck" })];
+            _runLinter_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runLinter" })];
+            _warmLinterCache_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.warmLinterCache" })];
+            _runNpmInstall_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runNpmInstall" })];
+            _runPackageManagerInstall_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.runPackageManagerInstall" })];
+            _installSpecificPackages_decorators = [llmobs.decorate({
+                    kind: "task",
+                    name: "AppShell.installSpecificPackages",
+                })];
+            _uninstallPackages_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.uninstallPackages" })];
+            _saveGeneratedArtifact_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.saveGeneratedArtifact" })];
+            _readFile_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.readFile" })];
+            _writeFile_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.writeFile" })];
+            _copyFile_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.copyFile" })];
+            _copyDirectory_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.copyDirectory" })];
+            _deleteFile_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.deleteFile" })];
+            _listFiles_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.listFiles" })];
+            _listFilesInternal_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.listFilesInternal" })];
+            _renameFile_decorators = [llmobs.decorate({ kind: "task", name: "AppShell.renameFile" })];
+            __esDecorate(this, null, _readFiles_decorators, { kind: "method", name: "readFiles", static: false, private: false, access: { has: obj => "readFiles" in obj, get: obj => obj.readFiles }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _runTypecheck_decorators, { kind: "method", name: "runTypecheck", static: false, private: false, access: { has: obj => "runTypecheck" in obj, get: obj => obj.runTypecheck }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _runLinter_decorators, { kind: "method", name: "runLinter", static: false, private: false, access: { has: obj => "runLinter" in obj, get: obj => obj.runLinter }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _warmLinterCache_decorators, { kind: "method", name: "warmLinterCache", static: false, private: false, access: { has: obj => "warmLinterCache" in obj, get: obj => obj.warmLinterCache }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _runNpmInstall_decorators, { kind: "method", name: "runNpmInstall", static: false, private: false, access: { has: obj => "runNpmInstall" in obj, get: obj => obj.runNpmInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _runPackageManagerInstall_decorators, { kind: "method", name: "runPackageManagerInstall", static: false, private: false, access: { has: obj => "runPackageManagerInstall" in obj, get: obj => obj.runPackageManagerInstall }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _installSpecificPackages_decorators, { kind: "method", name: "installSpecificPackages", static: false, private: false, access: { has: obj => "installSpecificPackages" in obj, get: obj => obj.installSpecificPackages }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _uninstallPackages_decorators, { kind: "method", name: "uninstallPackages", static: false, private: false, access: { has: obj => "uninstallPackages" in obj, get: obj => obj.uninstallPackages }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _saveGeneratedArtifact_decorators, { kind: "method", name: "saveGeneratedArtifact", static: false, private: false, access: { has: obj => "saveGeneratedArtifact" in obj, get: obj => obj.saveGeneratedArtifact }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _readFile_decorators, { kind: "method", name: "readFile", static: false, private: false, access: { has: obj => "readFile" in obj, get: obj => obj.readFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _writeFile_decorators, { kind: "method", name: "writeFile", static: false, private: false, access: { has: obj => "writeFile" in obj, get: obj => obj.writeFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _copyFile_decorators, { kind: "method", name: "copyFile", static: false, private: false, access: { has: obj => "copyFile" in obj, get: obj => obj.copyFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _copyDirectory_decorators, { kind: "method", name: "copyDirectory", static: false, private: false, access: { has: obj => "copyDirectory" in obj, get: obj => obj.copyDirectory }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _deleteFile_decorators, { kind: "method", name: "deleteFile", static: false, private: false, access: { has: obj => "deleteFile" in obj, get: obj => obj.deleteFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listFiles_decorators, { kind: "method", name: "listFiles", static: false, private: false, access: { has: obj => "listFiles" in obj, get: obj => obj.listFiles }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _listFilesInternal_decorators, { kind: "method", name: "listFilesInternal", static: false, private: false, access: { has: obj => "listFilesInternal" in obj, get: obj => obj.listFilesInternal }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _renameFile_decorators, { kind: "method", name: "renameFile", static: false, private: false, access: { has: obj => "renameFile" in obj, get: obj => obj.renameFile }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        appRootDirPath = __runInitializers(this, _instanceExtraInitializers);
+        fsOperationQueue;
+        linter;
+        messageSender;
+        draftManager;
+        templateRenderer;
+        virtualFs;
+        pathValidator;
+        enableDeletingLockfiles;
+        /**
+         * Resolves the per-org npm registry config at install time. The AiService
+         * always constructs one in production (SaaS, local dev, and ephemeral
+         * pods); the LD flag (`superblocks.npm-registry.enabled`) inside the
+         * client decides whether to short-circuit to "not-configured" without a
+         * server call. `undefined` here is the test-only path (or callers that
+         * deliberately opt out): every `.npmrc` helper becomes a no-op and the
+         * install runs against npm's default resolution.
+         */
+        npmRegistryClient;
+        /**
+         * Optional sink for npm-install-blocked audit events (APPS-4191 / P6.3).
+         * The AiService injects a reporter bound to the org/app socket connection;
+         * `undefined` (tests, callers that opt out) makes the audit emit a no-op.
+         * The reporter is fire-and-forget — see `maybeReportBlockedInstall`.
+         */
+        reportNpmInstallBlocked;
+        /**
+         * Optional sink for privacy-safe install-gate USER_EVENT reports. One call
+         * per gated AppShell install (`install_all` / `install_specific`) with
+         * outcome + runner only. Prefetch and uninstall never report.
+         */
+        reportNpmInstallOutcome;
+        /**
+         * Optional deps for the install-time vulnerability index lookup.
+         * When absent the malware/CVE gate is skipped (test fixtures / deliberate
+         * opt-out). Production AiService always wires these.
+         */
+        packageLookup;
+        /**
+         * Tracks files that must be read before they can be written.
+         * Used to enforce read-before-write pattern for AI safety.
+         */
+        requiredReads = new Set();
+        constructor({ appRootDirPath, fsOperationQueue, messageSender, draftInterface, templateRenderer, virtualFileSystem, pathValidator, enableDeletingLockfiles, npmRegistryClient, reportNpmInstallBlocked, reportNpmInstallOutcome, packageLookup, }) {
+            // Normalize path to handle Windows drive letter case
+            this.appRootDirPath = normalizePath(appRootDirPath);
+            this.fsOperationQueue = fsOperationQueue;
+            this.linter = new Linter(this.appRootDirPath);
+            this.messageSender = messageSender;
+            this.draftManager = draftInterface
+                ? new DraftManager(draftInterface)
+                : undefined;
+            this.templateRenderer = templateRenderer;
+            this.virtualFs = virtualFileSystem;
+            this.pathValidator = pathValidator;
+            this.enableDeletingLockfiles = enableDeletingLockfiles ?? false;
+            this.npmRegistryClient = npmRegistryClient;
+            this.reportNpmInstallBlocked = reportNpmInstallBlocked;
+            this.reportNpmInstallOutcome = reportNpmInstallOutcome;
+            this.packageLookup = packageLookup;
+        }
+        /**
+         * Toggle the API virtual-file projection. When disabled, reads to `apis/*`
+         * bypass the YAML→TS transformer and fall through to raw disk, which is what
+         * v2→v3 migration needs so Clark sees the original YAML sources.
+         */
+        setApiHandlerEnabled(enabled) {
+            this.virtualFs.setHandlerEnabled("api", enabled);
+        }
+        /**
+         * Enqueue a filesystem operation and annotate queue timing in llmobs.
+         * This helps separate queue contention from operation execution time.
+         */
+        async enqueueFsOperation(operationName, operation, metadata) {
+            const enqueuedAt = performance.now();
+            return await this.fsOperationQueue.enqueue(async () => {
+                const startedAt = performance.now();
+                const queueWaitMs = Math.round(startedAt - enqueuedAt);
+                try {
+                    return await operation();
+                }
+                finally {
+                    const executeMs = Math.round(performance.now() - startedAt);
+                    llmobs.annotate({
+                        metadata: {
+                            appShellQueueExecuteMs: executeMs,
+                            appShellQueueOperation: operationName,
+                            appShellQueueWaitMs: queueWaitMs,
+                            ...(metadata ?? {}),
+                        },
+                    });
+                }
+            });
+        }
+        async readFiles(patterns, globOptions, enableAppBlacklist = true) {
+            return await this.enqueueFsOperation("readFiles", async () => {
+                // Get file list with virtual path conversion (physical API paths → virtual paths)
+                const files = await this.listFilesInternal(patterns, globOptions);
+                // Compute blacklisted files (regular component files like Button, Input)
+                const blacklistedFiles = enableAppBlacklist
+                    ? new Set(await glob(Array.from(CLARK_APP_BLACKLIST_PATTERNS), {
+                        nodir: true,
+                        cwd: this.appRootDirPath,
+                        ignore: [...STANDARD_IGNORE_PATTERNS],
+                    }))
+                    : new Set();
+                return await Promise.all(files.map(async (file) => {
+                    const isBlacklisted = blacklistedFiles.has(file);
+                    const content = isBlacklisted
+                        ? "<… file contents omitted …>" // TODO(mark): could we just return the exported lines?
+                        : await this.readFileInternal(file);
+                    return {
+                        type: "file",
+                        filePath: file,
+                        content,
+                    };
+                }));
+            });
+        }
+        async runTypecheck(abortSignal) {
+            const output = await this.runTypecheckRawOutput(abortSignal);
+            if (!output) {
+                return null;
+            }
+            const parsed = output.split("\n").reduce((acc, line) => {
+                const [filePath, _rest] = line.split("(");
+                if (filePath && filePath.trim() !== "") {
+                    acc[filePath] = [...(acc[filePath] || []), line];
+                    return acc;
+                }
                 return acc;
+            }, {});
+            return Object.keys(parsed).length > 0 ? parsed : null;
+        }
+        async runTypecheckRawOutput(abortSignal) {
+            const command = process.env.SUPERBLOCKS_SERVER_ENV === "local"
+                ? "pnpm exec tsc"
+                : "npx tsc";
+            // Only apps whose root tsconfig declares project `references` need build
+            // mode. The fullstack (3.0) template uses a root "solution" tsconfig that
+            // includes only top-level *.ts files and delegates client/** and server/**
+            // to referenced composite projects. Plain `tsc --noEmit` never type-checks
+            // those referenced projects, so real build-breaking errors (e.g. a missing
+            // named export imported by client/root.tsx) slip through silently. `tsc -b`
+            // type-checks every referenced project in dependency order.
+            //
+            // We deliberately do NOT pass `--noEmit` with `-b`: the composite
+            // client/server projects use `emitDeclarationOnly` (the client consumes the
+            // server's emitted .d.ts), and build mode rejects `--noEmit` against a
+            // referenced project that emits with TS6310 ("Referenced project may not
+            // disable emit"). Build mode also rejects per-invocation flags such as
+            // --incremental, --noImplicitAny, and --tsBuildInfoFile (TS5094), so
+            // reference templates configure those in tsconfig instead.
+            //
+            // Because `tsc -b` must emit, we run it against generated "shadow" tsconfigs
+            // that extend the app's real configs but redirect every emit (outDir +
+            // tsBuildInfoFile) into the sync-excluded `.superblocks/tscheck/` scratch
+            // dir. This keeps build_debug honoring its read-only contract: nothing is
+            // written into the app workspace (client/, server/, a top-level dist/), only
+            // into `.superblocks/` — the same isolated area the non-build-mode command
+            // already uses for its `.tsbuildinfo` cache. tsc still reports diagnostics
+            // against the real source paths, and the persisted scratch buildinfo keeps
+            // builds incremental.
+            //
+            // If shadow-config generation fails for any reason (unparseable/missing
+            // referenced config, scratch-dir write failure, ...), we FAIL CLOSED to a
+            // non-emitting `tsc --noEmit` rather than a plain in-tree `tsc -b`: the
+            // latter would emit dist/** + *.tsbuildinfo into the app tree and break
+            // build_debug's read-only contract. `--noEmit` is guaranteed not to write
+            // (it overrides the composite projects' emit settings, and without `-b` it
+            // never builds referenced projects), and it still surfaces the underlying
+            // tsconfig problem as a diagnostic. We lose reference-following in this rare
+            // failure case, but never mutate the app workspace.
+            //
+            // Everything else (2.0 apps, flat shadcn-style apps, legacy apps) has no
+            // references, so the original command already type-checks every file. We
+            // keep it for those apps to preserve behavior build mode can't: `--noEmit`
+            // (no app-tree mutation), `--noImplicitAny false` (leniency for untyped
+            // AI-generated code, avoiding debug loops), and an isolated
+            // `--tsBuildInfoFile` cache.
+            let args;
+            if (await this.appUsesProjectReferences()) {
+                const shadowRootConfig = await this.prepareReferenceShadowConfigs();
+                args = shadowRootConfig
+                    ? ["-b", shadowRootConfig, "--pretty false"]
+                    : ["--noEmit", "--pretty false"];
             }
-            return acc;
-        }, {});
-        return Object.keys(parsed).length > 0 ? parsed : null;
-    }
-    async runNpmInstall(abortSignal) {
-        return await new Promise((resolve, reject) => {
-            const command = 
-            // if we're running in csb mock server, we need to avoid conflicts with the workspace
-            process.env.SUPERBLOCKS_SERVER_ENV === "local"
-                ? "pnpm install --config.confirmModulesPurge=false"
-                : "npm install";
-            exec(command, {
+            else {
+                args = [
+                    "--noEmit",
+                    // speed up marginal typecheck
+                    "--incremental",
+                    // expected format
+                    "--pretty false",
+                    // allow any
+                    "--noImplicitAny false",
+                    // cache in separate file to avoid conflicts with vite or user ide
+                    "--tsBuildInfoFile .superblocks/app.tsbuildinfo",
+                ];
+            }
+            // execCancellable, not exec: aborting an exec only signals the `/bin/sh`
+            // it spawned, leaving `npx` and the `tsc` compiler underneath it running
+            // and holding their heap. Cancelled checks therefore never freed memory,
+            // and overlapping compilers accumulated until the pod was OOMKilled.
+            const output = await execCancellable([command, ...args].join(" "), {
                 cwd: this.appRootDirPath,
-                timeout: 30_000,
                 signal: abortSignal,
-            }, (error, _stdout, stderr) => {
-                if (error) {
-                    return reject(new NpmInstallError(stderr));
+            });
+            if (!output) {
+                return null;
+            }
+            return output;
+        }
+        /**
+         * Returns true when the app's root tsconfig declares project `references`.
+         *
+         * Reference apps (the fullstack/3.0 template) must be type-checked with
+         * `tsc -b`, which follows references; non-reference apps use the original
+         * `tsc --noEmit ...` command. Parsed with JSON5 because tsconfig.json allows
+         * comments and trailing commas. On any read/parse failure we fall back to
+         * `false` (the proven non-build-mode command): the only templates that use
+         * references ship a well-formed tsconfig, and legacy/2.0 apps have none.
+         */
+        async appUsesProjectReferences() {
+            const tsconfigPath = path.join(this.appRootDirPath, "tsconfig.json");
+            try {
+                const raw = await fsReadFile(tsconfigPath, "utf-8");
+                const parsed = JSON5.parse(raw);
+                return Array.isArray(parsed.references) && parsed.references.length > 0;
+            }
+            catch (error) {
+                getLogger().warn("[ai-service] could not determine tsconfig project references; defaulting to non-build-mode typecheck", getErrorMeta(error));
+                return false;
+            }
+        }
+        /**
+         * Generate "shadow" tsconfigs under `.superblocks/tscheck/` that mirror the
+         * app's project-reference graph but redirect all emit into that scratch dir,
+         * and return the app-root-relative path of the shadow root config to pass to
+         * `tsc -b`. Returns `null` on any failure so the caller can fail closed to a
+         * non-emitting `tsc --noEmit` (never a plain in-tree `tsc -b`, which would
+         * emit into the app tree and break build_debug's read-only contract).
+         *
+         * Why this exists: `tsc -b` cannot run with `--noEmit` against composite
+         * projects that emit declarations (TS6310), and build mode rejects a CLI
+         * `--outDir`/`--tsBuildInfoFile` override (TS5094). The only way to relocate
+         * emit is per-project config. Each shadow:
+         *   - `extends` the original config (inheriting include/exclude/paths/etc.,
+         *     whose relative paths still resolve against the original's directory),
+         *   - sets `rootDir` to the app root so composite projects don't treat the
+         *     scratch dir as the source root (TS6059),
+         *   - overrides `outDir` + `tsBuildInfoFile` into the scratch dir,
+         *   - rewrites `references` to point at the corresponding shadow configs (so
+         *     building a referenced project also emits into the scratch dir, never the
+         *     app tree).
+         *
+         * `.superblocks/` is already excluded from dbfs sync, the vite watcher, and
+         * Clark's context, so confining emit there preserves the read-only contract.
+         */
+        async prepareReferenceShadowConfigs() {
+            try {
+                const appRoot = this.appRootDirPath;
+                const scratchDir = path.join(appRoot, ".superblocks", "tscheck");
+                const rootConfigAbs = path.join(appRoot, "tsconfig.json");
+                // Walk the reference graph from the root config, collecting every
+                // transitively referenced tsconfig and its (resolved) reference targets.
+                const originals = [];
+                const seen = new Set();
+                const refsByConfig = new Map();
+                const queue = [rootConfigAbs];
+                while (queue.length > 0) {
+                    const configAbs = queue.shift();
+                    if (seen.has(configAbs)) {
+                        continue;
+                    }
+                    seen.add(configAbs);
+                    originals.push(configAbs);
+                    const parsed = JSON5.parse(await fsReadFile(configAbs, "utf-8"));
+                    const refs = Array.isArray(parsed.references) ? parsed.references : [];
+                    const resolvedRefs = [];
+                    for (const ref of refs) {
+                        if (!ref?.path) {
+                            continue;
+                        }
+                        // A reference path may point at a tsconfig file or at a directory
+                        // (which implies `<dir>/tsconfig.json`), matching tsc's resolution.
+                        const refResolved = path.resolve(path.dirname(configAbs), ref.path);
+                        const refAbs = refResolved.endsWith(".json")
+                            ? refResolved
+                            : path.join(refResolved, "tsconfig.json");
+                        resolvedRefs.push(refAbs);
+                        queue.push(refAbs);
+                    }
+                    refsByConfig.set(configAbs, resolvedRefs);
                 }
-                return resolve();
+                // Deterministic, collision-free shadow filename per original config,
+                // derived from its app-root-relative path (e.g. `tsconfig.client.json` ->
+                // `tsconfig.client.json.sbcheck.json`, nested dirs flattened with `__`).
+                const shadowNameOf = (configAbs) => `${path.relative(appRoot, configAbs).split(path.sep).join("__")}.sbcheck.json`;
+                const toPosix = (p) => p.split(path.sep).join("/");
+                const rootDirRel = toPosix(path.relative(scratchDir, appRoot)) || ".";
+                // Exclude the migration backup (`<appRoot>/scratch/**`) from every shadow
+                // project. During a 2.0 -> 3.0 migration the original v2 app files are
+                // parked under `scratch/v2-backup/` until finalize deletes them; they are
+                // stale and routinely do not type-check under the 3.0 config, and must not
+                // surface as dev-server typecheck errors (APPS-5107). A shadow that
+                // declares `exclude` overrides (rather than merges with) the inherited
+                // one, so we reconstruct the config's *effective* exclude — remapped so
+                // its relative globs resolve to the same absolute paths tsc used — then
+                // append the scratch dir. When no `exclude` is declared anywhere in the
+                // `extends` chain, tsc falls back to implicit defaults (node_modules etc.)
+                // plus the config's own `outDir`, so we replicate those instead — the
+                // outDir part keeps a broad `include` from re-reading stale build output.
+                const defaultTsExcludes = [
+                    "node_modules",
+                    "bower_components",
+                    "jspm_packages",
+                ];
+                const scratchExcludeRel = toPosix(path.relative(scratchDir, path.join(appRoot, "scratch")));
+                const remapExclude = (entry, baseDir) => path.isAbsolute(entry)
+                    ? entry
+                    : toPosix(path.relative(scratchDir, path.resolve(baseDir, entry)));
+                // Resolve an `extends` target to an absolute path the way tsc does: only
+                // relative targets are followed (package/module extends are out of scope —
+                // the reference templates never use them), and a target may omit `.json`
+                // or point at a directory (implying `<dir>/tsconfig.json`).
+                const resolveExtendsTarget = async (fromDir, extendsValue) => {
+                    if (!extendsValue.startsWith(".")) {
+                        return null;
+                    }
+                    const resolved = path.resolve(fromDir, extendsValue);
+                    const candidates = resolved.endsWith(".json")
+                        ? [resolved]
+                        : [`${resolved}.json`, path.join(resolved, "tsconfig.json")];
+                    for (const candidate of candidates) {
+                        try {
+                            await access(candidate);
+                            return candidate;
+                        }
+                        catch (error) {
+                            // A missing candidate is expected (the extensionless/dir probes),
+                            // but a permission/IO error on a target that exists silently
+                            // truncates the walk and narrows the reconstructed exclude, so make
+                            // that case diagnosable.
+                            if (error?.code !== "ENOENT") {
+                                getLogger().debug(`[ai-service] extends target not accessible while resolving shadow tsconfig excludes: ${candidate}`, getErrorMeta(error));
+                            }
+                        }
+                    }
+                    return null;
+                };
+                // Walk a config's `extends` chain to find its effective `exclude` and
+                // `outDir` (the nearest declaration wins, matching tsc's override
+                // semantics). Each is paired with the directory of the config that
+                // declared it, so its relative paths remap correctly. Only single-string
+                // `extends` is followed — array-form `extends` is not (the template guard
+                // test enforces that migration templates never use it).
+                const resolveEffectiveConfig = async (configAbs) => {
+                    let current = configAbs;
+                    const guard = new Set();
+                    let exclude = null;
+                    let outDir = null;
+                    while (current && !guard.has(current)) {
+                        guard.add(current);
+                        let parsed;
+                        try {
+                            parsed = JSON5.parse(await fsReadFile(current, "utf-8"));
+                        }
+                        catch (error) {
+                            // A base config in the chain that can't be read/parsed truncates
+                            // the walk and narrows the reconstructed exclude; log so that
+                            // divergence is diagnosable rather than silent.
+                            getLogger().debug(`[ai-service] could not read/parse tsconfig while resolving shadow excludes: ${current}`, getErrorMeta(error));
+                            break;
+                        }
+                        const dir = path.dirname(current);
+                        if (!exclude && Array.isArray(parsed.exclude)) {
+                            exclude = { value: parsed.exclude, baseDir: dir };
+                        }
+                        if (!outDir && typeof parsed.compilerOptions?.outDir === "string") {
+                            outDir = { value: parsed.compilerOptions.outDir, baseDir: dir };
+                        }
+                        if (exclude && outDir) {
+                            break;
+                        }
+                        current =
+                            typeof parsed.extends === "string"
+                                ? await resolveExtendsTarget(dir, parsed.extends)
+                                : null;
+                    }
+                    return { exclude, outDir };
+                };
+                await mkdir(scratchDir, { recursive: true });
+                await Promise.all(originals.map(async (configAbs) => {
+                    const shadowName = shadowNameOf(configAbs);
+                    const emitName = shadowName.replace(/\.json$/, "");
+                    const effective = await resolveEffectiveConfig(configAbs);
+                    // With an explicit `exclude` (declared anywhere in the extends chain),
+                    // tsc does not auto-exclude `outDir`, so replicate exactly what it
+                    // declared. Without one, tsc's implicit defaults include the config's
+                    // own `outDir`, so add that back alongside node_modules et al.
+                    let inheritedExcludes;
+                    if (effective.exclude) {
+                        const { value: entries, baseDir } = effective.exclude;
+                        inheritedExcludes = entries.map((entry) => remapExclude(entry, baseDir));
+                    }
+                    else {
+                        inheritedExcludes = [
+                            ...defaultTsExcludes.map((entry) => remapExclude(entry, path.dirname(configAbs))),
+                            ...(effective.outDir
+                                ? [
+                                    remapExclude(effective.outDir.value, effective.outDir.baseDir),
+                                ]
+                                : []),
+                        ];
+                    }
+                    const shadow = {
+                        extends: toPosix(path.relative(scratchDir, configAbs)),
+                        compilerOptions: {
+                            rootDir: rootDirRel,
+                            outDir: `./emit/${emitName}`,
+                            tsBuildInfoFile: `./${emitName}.tsbuildinfo`,
+                        },
+                        // Exclude the shadow's own emit dir. Declaring an explicit `exclude`
+                        // defeats tsc's implicit auto-exclusion of `outDir`, so on a second+
+                        // run a broad inherited `include` could in principle re-consume the
+                        // previous run's emitted `.d.ts`. In practice tsc's wildcard include
+                        // skips dot-directories and emit lives under `.superblocks/`, so this
+                        // is defense-in-depth: it keeps correctness from resting on that
+                        // implicit heuristic. All shadows emit under `./emit/`.
+                        exclude: [...inheritedExcludes, scratchExcludeRel, "./emit"],
+                        references: (refsByConfig.get(configAbs) ?? []).map((refAbs) => ({
+                            path: `./${shadowNameOf(refAbs)}`,
+                        })),
+                    };
+                    await writeFile(path.join(scratchDir, shadowName), JSON.stringify(shadow, null, 2), "utf-8");
+                }));
+                const rootShadowAbs = path.join(scratchDir, shadowNameOf(rootConfigAbs));
+                return toPosix(path.relative(appRoot, rootShadowAbs));
+            }
+            catch (error) {
+                getLogger().warn("[ai-service] could not prepare isolated tsc -b scratch configs; failing closed to non-emitting tsc --noEmit", getErrorMeta(error));
+                return null;
+            }
+        }
+        async runLinter(filePaths, abortSignal) {
+            const absoluteFilePaths = filePaths.map((filePath) => path.join(this.appRootDirPath, filePath));
+            return await this.enqueueFsOperation("runLinter", async () => {
+                const { errors, fixedFiles } = await this.linter.lint(absoluteFilePaths, abortSignal);
+                // Mark auto-fixed files as requiring read before further writes
+                for (const fixedFile of fixedFiles) {
+                    this.requireRead(fixedFile);
+                }
+                if (Object.keys(errors).length > 0) {
+                    return errors;
+                }
+                return null;
+            }, {
+                appShellQueueFileCount: filePaths.length,
             });
-        });
-    }
-}
+        }
+        warmLinterCache() {
+            void this.linter.warmCache(["**/*.{tsx}"]);
+        }
+        /**
+         * Emit one `superblocks.npm.install.*` observation (APPS-4189 / P6.2) and
+         * annotate the active llmobs span with the same dimensions. Shared by
+         * every `AppShell` install and uninstall method so metric and span streams join on
+         * (runner, registry_host, outcome) without drift. Every value flows
+         * through the P6.1 sanitization helpers inside `recordNpmInstall`, so a
+         * raw registry hostname or token cannot reach an exported attribute even
+         * if an upstream caller forgot to scrub.
+         */
+        observeNpmInstall(runner, registryFetchResult, outcome, durationMs) {
+            const tags = recordNpmInstall({
+                runner,
+                registryHost: registryUrlFromFetchResult(registryFetchResult),
+                outcome,
+                configured: registryFetchResult?.config.configured ?? false,
+                durationMs,
+            });
+            // Record whether `--ignore-scripts` was added for this install on the span
+            // only, not as a metric label: the question is "did this one install skip
+            // scripts?", not a rate. It is read from the same `shouldIgnoreInstallScripts`
+            // the command builder uses, so the tag can never disagree with the flag we
+            // actually added. Turned into a string to match how the other tags are set.
+            llmobs.annotate({
+                tags: {
+                    ...tags,
+                    "npm.ignore_scripts_appended": String(shouldIgnoreInstallScripts(registryFetchResult)),
+                },
+            });
+            this.maybeReportInstallOutcome(runner, tags["npm.outcome"]);
+        }
+        /**
+         * Report a gated install outcome for Snowflake USER_EVENTs. Only
+         * `install_all` and `install_specific` run the vulnerability gate.
+         * Fire-and-forget: a reporting failure must never break the install.
+         */
+        maybeReportInstallOutcome(runner, outcome) {
+            if (runner !== "install_all" && runner !== "install_specific")
+                return;
+            if (!this.reportNpmInstallOutcome)
+                return;
+            try {
+                this.reportNpmInstallOutcome({ outcome, runner });
+            }
+            catch {
+                // USER_EVENT reporting is best-effort and must not affect the install.
+            }
+        }
+        /**
+         * Report a blocked controlled install to the server-side audit trail
+         * (APPS-4191 / P6.3). Only `NpmInstallBlocked` is auditable — any other
+         * failure (or success) is left to metrics (P6.2). The structured error
+         * already carries the audit-relevant fields (reason, packages, registry
+         * host, error code); the injected reporter adds org/app identity and the
+         * server throttles + sanitizes + persists. Fire-and-forget: a reporting
+         * failure must never surface to (or break) the install caller.
+         */
+        safeAudit(report) {
+            if (!this.reportNpmInstallBlocked)
+                return;
+            try {
+                this.reportNpmInstallBlocked(report);
+            }
+            catch {
+                // Audit reporting is best-effort and must not affect the install.
+            }
+        }
+        maybeReportBlockedInstall(err, runner) {
+            if (!(err instanceof NpmInstallBlocked))
+                return;
+            // Audit only real CVE/malware findings — index/probe failures are fail-closed
+            // blocks, not malware hits, and must not pollute SIEM as vulnerabilities.
+            const isAuditableFinding = (finding) => finding.kind === "cve" || finding.kind === "malware";
+            const vulnerabilities = err.findings?.filter(isAuditableFinding).map((finding) => ({
+                advisoryId: finding.advisoryId,
+                kind: finding.kind,
+                package: finding.package,
+                ...(finding.severity !== undefined
+                    ? { severity: finding.severity }
+                    : {}),
+                ...(finding.suggestedVersion !== undefined
+                    ? { suggestedVersion: finding.suggestedVersion }
+                    : {}),
+            }));
+            // A block whose findings are all index/probe outages still carries
+            // `reason: vulnerable_package`, so auditing it would file an outage as a
+            // CVE hit. The `index_unavailable` metric already covers those.
+            if (err.findings?.length && !vulnerabilities?.length)
+                return;
+            this.safeAudit({
+                reason: err.reason,
+                registryHost: err.registryHost,
+                packages: err.packages,
+                httpStatus: err.httpStatus,
+                npmErrorCode: err.npmErrorCode,
+                runner,
+                occurredAt: Date.now(),
+                ...(vulnerabilities?.length ? { vulnerabilities } : {}),
+            });
+        }
+        reportNpmTriageVerdict(verdict) {
+            this.safeAudit({
+                occurredAt: Date.now(),
+                packages: [verdict.package],
+                reason: "vulnerability_triaged",
+                runner: "install_specific",
+                triage: verdict,
+            });
+        }
+        reportNpmUserOverride(args) {
+            this.safeAudit({
+                occurredAt: Date.now(),
+                packages: args.packages,
+                reason: "vulnerability_user_override",
+                runner: "install_specific",
+                userOverride: {
+                    packages: args.packages,
+                    reason: args.reason,
+                },
+            });
+        }
+        /**
+         * Report silent CVE/quarantine substitutions to the same audit sink as
+         * blocked installs. Best-effort; never fails the install.
+         */
+        maybeReportSubstitutions(substitutions, runner) {
+            for (const entry of substitutions) {
+                this.safeAudit({
+                    reason: "package_substituted",
+                    packages: [`${entry.name}@${entry.fromVersion}`],
+                    runner,
+                    occurredAt: Date.now(),
+                    substitution: {
+                        fromVersion: entry.fromVersion,
+                        toVersion: entry.toVersion,
+                        reason: entry.reason,
+                    },
+                });
+            }
+        }
+        /** Mode 2: write gate substitutions into package.json. Audit is the caller's job after install succeeds (same as Mode 1). */
+        async applyDeclaredDependencyUpgrades(remediation) {
+            if (remediation.substitutions.length === 0)
+                return [];
+            const rewritten = await this.enqueueFsOperation("applyPackageJsonSubstitutions", () => applyPackageJsonSubstitutions({
+                appRootDirPath: this.appRootDirPath,
+                logger: getLogger(),
+                substitutions: remediation.substitutions,
+            }));
+            if (rewritten.length === 0)
+                return [];
+            const applied = new Set(rewritten);
+            return remediation.substitutions.filter((entry) => applied.has(entry.name));
+        }
+        async remediateDeclaredDependencies(abortSignal) {
+            // Kill switch / unwired lookup: do not short-circuit registry or rewrite
+            // package.json — startup must behave as pre-gate.
+            if (!this.packageLookup) {
+                return;
+            }
+            await this.withAuthFailedRetry(async (registryFetchResult) => {
+                this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                // Cloud: strip workspace: before Mode 2 dry-run malware scan.
+                await this.maybePreparePackageJsonForCloudNpm();
+                await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                    abortSignal,
+                    mode: "all",
+                }));
+            });
+        }
+        /**
+         * Env overlay for AppShell-spawned npm/pnpm installs in the live-edit
+         * pod. Routes npm's per-run debug log into `<app>/.superblocks/logs` via
+         * `NPM_CONFIG_LOGS_DIR` so a failed agent install leaves a collectable log
+         * in a predictable place — the same convention the CLI dev-server install
+         * uses (`buildInstallEnv` in the SDK). These execs otherwise inherit
+         * `process.env` implicitly, so we spread it before adding the override.
+         * pnpm has no equivalent logs-dir config and ignores the var (npm-only).
+         */
+        installLogEnv() {
+            return {
+                ...process.env,
+                NPM_CONFIG_LOGS_DIR: path.join(this.appRootDirPath, ".superblocks", "logs"),
+            };
+        }
+        /**
+         * Cloud edit pods force npm for agent-driven installs. npm rejects pnpm's
+         * `workspace:` protocol, so rewrite platform deps and strip any remaining
+         * workspace entries before spawning npm (APPS-3752 bootstrap does this on
+         * pod start; migration restructure and agent installs need the same guard).
+         */
+        async maybePreparePackageJsonForCloudNpm() {
+            if (process.env.SUPERBLOCKS_SERVER_ENV === "local") {
+                return;
+            }
+            await preparePackageJsonForCloudNpm({
+                appRootDirPath: this.appRootDirPath,
+                logger: getLogger(),
+            });
+        }
+        async runNpmInstall(abortSignal) {
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                // `withAuthFailedRetry` owns the `.npmrc` materialization (via
+                // `prepareForPrivateRegistry`) and the one-shot auth_failed retry —
+                // see its docstring. Telemetry is captured around it so a retry-then-
+                // succeed flow still records the right outcome.
+                await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: refuse to spawn npm when the registry server is
+                    // unreachable AND we have prior evidence (disk marker) that this org
+                    // was at some point configured with a private registry. See
+                    // `maybeShortCircuitForUnreachable` for the full rationale.
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                    await this.maybePreparePackageJsonForCloudNpm();
+                    const appliedSubstitutions = await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        mode: "all",
+                    }));
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    const isNpm = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    // prepare already ran above so Mode 2 cloud dry-run sees semver deps.
+                    // In csb mock server (local dev) we use pnpm to avoid lockfile / store
+                    // conflicts with the surrounding workspace; everywhere else we force npm
+                    // so the `--json` error contract — and therefore the registry-blocked
+                    // advice matrix — applies on this post-processing path too. When the
+                    // org has opted out via `allow_install_scripts=false`, append
+                    // `--ignore-scripts` (the flag is honored by both npm and pnpm).
+                    const baseCommand = isNpm
+                        ? "npm install --fund=false --audit=false --json"
+                        : "pnpm install --config.confirmModulesPurge=false";
+                    const command = ignoreScripts
+                        ? `${baseCommand} --ignore-scripts`
+                        : baseCommand;
+                    await new Promise((resolve, reject) => {
+                        exec(command, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            timeout: 30_000,
+                            signal: abortSignal,
+                            // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                            // default 1 MiB exec buffer on fat dep trees.
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        }, (error, stdout, stderr) => {
+                            if (error) {
+                                // Route the npm path through the same classifier as the agent-tool
+                                // install entry points so E404 / E401 / ENOTFOUND surface as a
+                                // `NpmInstallBlocked` (with row-aware advice) instead of a raw
+                                // `NpmInstallError(stderr)`. The pnpm path doesn't emit the
+                                // `--json` envelope, so the classifier falls through to the
+                                // legacy error for it — registry-blocked scenarios only matter
+                                // in cloud-edit (which is the npm branch).
+                                if (isNpm) {
+                                    return reject(this.classifyNpmExecError({ stdout, stderr, message: error.message }, undefined, registryFetchResult));
+                                }
+                                return reject(new NpmInstallError(stderr));
+                            }
+                            return resolve();
+                        });
+                    });
+                    // Audit only after the install succeeds: a selected substitution is
+                    // not an applied substitution if npm fails (same as Mode 1).
+                    this.maybeReportSubstitutions(appliedSubstitutions, "install_all");
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                this.maybeReportBlockedInstall(err, "install_all");
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart);
+            }
+        }
+        /**
+         * APPS-4370. If the `prepareForPrivateRegistry` result tells us the
+         * server is unreachable AND the per-org disk marker says this org has
+         * at some prior point successfully resolved a configured registry,
+         * throw `NpmInstallBlocked(registry_unreachable)` BEFORE spawning npm.
+         *
+         * Without this short-circuit the install spawns anyway and hits one of
+         * two failure modes:
+         *   1. A previous install left a managed `.npmrc` with rotated credentials
+         *      → npm 401s mid-deploy and `classifyNpmExecError` tags it
+         *      `registry_auth_failed`, pointing the user at the wrong remediation.
+         *   2. No managed `.npmrc` exists → install silently resolves through
+         *      public npm, defeating the privacy posture during the outage.
+         *
+         * Bypassed when:
+         *   - The fetch result is anything other than `unreachable` (the
+         *     existing code paths handle `configured` / `stale` / `not-configured`).
+         *   - `everConfigured` is `undefined` (no store wired in — older call
+         *     sites, test fixtures) or `false` (greenfield org / first install).
+         *
+         * `packages` flows onto the structured error so the agent loop can
+         * surface "we tried to install <these> and the registry was unreachable".
+         */
+        maybeShortCircuitForUnreachable(registryFetchResult, packages) {
+            if (!registryFetchResult || registryFetchResult.source !== "unreachable") {
+                return;
+            }
+            if (registryFetchResult.everConfigured !== true) {
+                return;
+            }
+            throw new NpmInstallBlocked({
+                reason: "registry_unreachable",
+                packages,
+                hasAnyRegistryConfigured: true,
+            });
+        }
+        /**
+         * POST `/api/v1/security/package-lookup` for a batch of `{name,version}`
+         * pairs. One request — the server cap is 5000. Throws on non-2xx / network
+         * / malformed body so the caller can apply malware fail-closed.
+         */
+        async lookupPackageVulnerabilities(packages) {
+            const deps = this.packageLookup;
+            if (!deps) {
+                return [];
+            }
+            if (packages.length === 0) {
+                return [];
+            }
+            const jwt = await deps.getJwt();
+            const base = deps.baseUrl.replace(/\/$/, "");
+            const url = `${base}/api/v1/security/package-lookup`;
+            const fetchFn = deps.fetch ?? globalThis.fetch;
+            const response = await fetchFn(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${jwt}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ packages }),
+            });
+            if (!response.ok) {
+                throw new Error(`package-lookup returned HTTP ${response.status}`);
+            }
+            const body = await response.json();
+            if (body == null ||
+                typeof body !== "object" ||
+                !("data" in body) ||
+                body.data == null ||
+                typeof body.data !== "object" ||
+                !("results" in body.data) ||
+                !Array.isArray(body.data.results)) {
+                throw new Error("package-lookup response missing data.results");
+            }
+            const results = [];
+            for (const entry of body.data.results) {
+                if (!isPackageLookupResult(entry)) {
+                    throw new Error("package-lookup response contained an off-shape result");
+                }
+                results.push(entry);
+            }
+            const checked = new Set(results.map((result) => `${result.name}@${result.version}`));
+            for (const pkg of packages) {
+                if (!checked.has(`${pkg.name}@${pkg.version}`)) {
+                    throw new Error(`package-lookup response missing result for ${pkg.name}@${pkg.version}`);
+                }
+            }
+            return results;
+        }
+        /**
+         * Mode 1: npm dry-run + lockfile.
+         * Mode 2: `topLevel` is always declared package.json floors (CVE remediations).
+         * Cloud malware tree = floors ∪ package-lock ∪ dry-run (after workspace:
+         * rewrite). Local stays floors-only — pnpm + lingering `workspace:*` mean
+         * full-tree coverage is not available there.
+         */
+        async resolveInstallTree(mode, packages, abortSignal) {
+            if (mode === "all") {
+                const topLevel = [];
+                for (const pkg of packages ?? []) {
+                    const version = declaredRangeFloor(pkg.version);
+                    if (version != null)
+                        topLevel.push({ name: pkg.name, version });
+                }
+                // Local: floors only. Cloud: union lockfile + dry-run for malware.
+                if (process.env.SUPERBLOCKS_SERVER_ENV === "local") {
+                    return { resolves: true, topLevel, tree: topLevel };
+                }
+                const fromLock = await this.readPackagesFromPackageLock();
+                let dryTree = [];
+                try {
+                    dryTree = (await this.resolveTreeViaNpmDryRun([], abortSignal)).tree;
+                }
+                catch (err) {
+                    // Do not continue remediation after cancel.
+                    if (abortSignal?.aborted ||
+                        (err instanceof Error && err.name === "AbortError")) {
+                        throw err;
+                    }
+                    // Unexpected probe failure (not ERESOLVE / error envelope) — still
+                    // malware-scan floors + lockfile instead of aborting the gate.
+                }
+                const byKey = new Map();
+                for (const pkg of [...(fromLock?.tree ?? []), ...dryTree, ...topLevel]) {
+                    byKey.set(`${pkg.name}@${pkg.version}`, pkg);
+                }
+                // Keep resolves:true so a failed dry-run cannot skip floor CVE swaps;
+                // malware still sees whatever floors/lock/dry contributed.
+                return { resolves: true, topLevel, tree: [...byKey.values()] };
+            }
+            const specs = (packages ?? []).map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+            const resolved = await this.resolveTreeViaNpmDryRun(specs, abortSignal);
+            // Prefer dry-run concrete pins for top-level. Never inject the raw
+            // requested range/`latest` string into the lookup tree — the index
+            // keys on concrete versions, and a range would fail coverage checks.
+            const topLevel = [];
+            for (const pkg of packages ?? []) {
+                // An exact pin is what npm puts at the root, so it needs no resolution —
+                // and looking it up in the dry-run tree risks matching some other copy of
+                // the same name. It stays checkable even when npm cannot resolve the full
+                // tree; the lockfile union below preserves malware coverage for the tree
+                // already on disk.
+                if (pkg.version && semver.valid(pkg.version)) {
+                    topLevel.push({ name: pkg.name, version: pkg.version });
+                    continue;
+                }
+                const fromDry = resolved.topLevel.find((entry) => entry.name === pkg.name);
+                if (fromDry)
+                    topLevel.push(fromDry);
+            }
+            // Lockfile entries come first so already-satisfied installs (empty
+            // dry-run `add`) still malware-scan locked transitives; dry-run pins and
+            // top-level overwrite on collision because they reflect what this
+            // install actually changes.
+            const fromLock = await this.readPackagesFromPackageLock();
+            const byKey = new Map();
+            for (const pkg of [
+                ...(fromLock?.tree ?? []),
+                ...resolved.tree,
+                ...topLevel,
+            ]) {
+                byKey.set(`${pkg.name}@${pkg.version}`, pkg);
+            }
+            return {
+                tree: [...byKey.values()],
+                topLevel,
+                resolves: resolved.resolves,
+            };
+        }
+        async resolveTreeViaNpmDryRun(specs, abortSignal) {
+            const args = [
+                "install",
+                "--dry-run",
+                "--json",
+                "--fund=false",
+                "--audit=false",
+                // `--` so a spec that looks like an option (`--registry=…`,
+                // `--userconfig=…`) is parsed as a package name instead of
+                // reconfiguring the probe: the gate scans the tree this resolves, so a
+                // redirected registry would vouch for packages the real install never
+                // fetches. npm rejects the name and we fail closed.
+                "--",
+                ...specs,
+            ];
+            try {
+                // execFile (no shell) so hostile package specs cannot inject shell
+                // metacharacters into the dry-run probe.
+                const { stdout } = await execFilePromise("npm", args, {
+                    cwd: this.appRootDirPath,
+                    env: this.installLogEnv(),
+                    signal: abortSignal,
+                    maxBuffer: NPM_JSON_MAX_BUFFER,
+                });
+                const parsed = parseNpmJsonStdout(stdout);
+                return this.treeFromNpmDryRunJson(parsed, specs);
+            }
+            catch (error) {
+                const err = error;
+                const combined = `${err.stdout ?? ""}\n${err.stderr ?? ""}\n${err.message ?? ""}`;
+                if (/ERESOLVE|EPEERINVALID/i.test(combined)) {
+                    return { tree: [], topLevel: [], resolves: false };
+                }
+                // Non-zero exit can still carry a usable dry-run body — or an `{ error }`
+                // envelope (EUNSUPPORTEDPROTOCOL / E404 / ETARGET). Treat the latter as
+                // unresolved so the gate fails closed instead of scanning an empty tree.
+                if (err.stdout && err.stdout.includes("{")) {
+                    try {
+                        const parsed = parseNpmJsonStdout(err.stdout);
+                        if (isNpmErrorEnvelope(parsed)) {
+                            return { tree: [], topLevel: [], resolves: false };
+                        }
+                        return this.treeFromNpmDryRunJson(parsed, specs);
+                    }
+                    catch {
+                        // fall through
+                    }
+                }
+                throw error;
+            }
+        }
+        treeFromNpmDryRunJson(parsed, specs) {
+            if (parsed == null || typeof parsed !== "object") {
+                return { tree: [], topLevel: [], resolves: true };
+            }
+            const record = parsed;
+            const tree = [];
+            const root = [];
+            const seen = new Set();
+            const push = (name, version, entryPath) => {
+                if (typeof name !== "string" || typeof version !== "string")
+                    return;
+                if (!name || !version)
+                    return;
+                const key = `${name}@${version}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    tree.push({ name, version });
+                }
+                if (isRootNodeModulesPath(entryPath))
+                    root.push({ name, version });
+            };
+            if (Array.isArray(record.add)) {
+                for (const entry of record.add) {
+                    if (entry == null || typeof entry !== "object")
+                        continue;
+                    const pkg = entry;
+                    push(pkg.name, pkg.version, pkg.path);
+                }
+            }
+            if (Array.isArray(record.change)) {
+                for (const entry of record.change) {
+                    if (entry == null || typeof entry !== "object")
+                        continue;
+                    const change = entry;
+                    if (change.to == null || typeof change.to !== "object")
+                        continue;
+                    const to = change.to;
+                    push(to.name, to.version, to.path);
+                }
+            }
+            const topLevelNames = new Set(specs.map((spec) => {
+                if (spec.startsWith("@")) {
+                    const at = spec.indexOf("@", 1);
+                    return at > 0 ? spec.slice(0, at) : spec;
+                }
+                return spec.split("@")[0] ?? spec;
+            }));
+            // Top-level is the copy npm puts at the app's own `node_modules/<name>`.
+            // A dependency's nested copy shares the requested name but is a different
+            // version, and vouching for it would let the requested one install
+            // unchecked.
+            const topLevel = root.filter((pkg) => topLevelNames.has(pkg.name));
+            return { tree, topLevel, resolves: true };
+        }
+        async readPackagesFromPackageLock() {
+            const lockPath = path.join(this.appRootDirPath, "package-lock.json");
+            let raw;
+            try {
+                raw = await fsReadFile(lockPath, "utf8");
+            }
+            catch {
+                return null;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+            if (parsed == null || typeof parsed !== "object") {
+                return null;
+            }
+            const lock = parsed;
+            const tree = [];
+            const seen = new Set();
+            const push = (name, version) => {
+                const key = `${name}@${version}`;
+                if (seen.has(key))
+                    return;
+                seen.add(key);
+                tree.push({ name, version });
+            };
+            if (lock.packages && typeof lock.packages === "object") {
+                for (const [lockPathKey, meta] of Object.entries(lock.packages)) {
+                    if (!meta || typeof meta.version !== "string")
+                        continue;
+                    // Only `node_modules/**` entries are installed packages. `packages[""]`
+                    // (and any workspace root) is first-party code carrying a
+                    // builder-chosen name, so scanning it would block every install by an
+                    // app that happens to be named after a malicious package.
+                    const pathName = packageNameFromLockPath(lockPathKey);
+                    if (!pathName)
+                        continue;
+                    // An aliased install (`"node_modules/alias": { name: "real" }`) fetches
+                    // `meta.name` from the registry; that is the name to scan.
+                    push(typeof meta.name === "string" && meta.name.length > 0
+                        ? meta.name
+                        : pathName, meta.version);
+                }
+            }
+            else if (lock.dependencies && typeof lock.dependencies === "object") {
+                // lockfileVersion 1: nested `dependencies` hold transitive pins.
+                const walkV1 = (deps) => {
+                    if (deps == null || typeof deps !== "object")
+                        return;
+                    for (const [name, meta] of Object.entries(deps)) {
+                        if (meta == null || typeof meta !== "object")
+                            continue;
+                        if (!("version" in meta) || typeof meta.version !== "string") {
+                            continue;
+                        }
+                        push(name, meta.version);
+                        if ("dependencies" in meta &&
+                            meta.dependencies != null &&
+                            typeof meta.dependencies === "object") {
+                            walkV1(meta.dependencies);
+                        }
+                    }
+                };
+                walkV1(lock.dependencies);
+            }
+            return { tree, topLevel: tree, resolves: true };
+        }
+        /**
+         * Vulnerability gate. Mode 1 remediates/blocks top-level CVEs; Mode 2
+         * silently rewrites declared deps (same major) and leaves the rest.
+         * No-op when `packageLookup` is unwired. Index failures → malware fail-closed.
+         */
+        async maybeRemediateVulnerabilities(args) {
+            const { abortSignal, cveUserOverride, mode } = args;
+            if (!this.packageLookup) {
+                return { substitutions: [] };
+            }
+            const packages = mode === "all"
+                ? await readDeclaredDependencies(this.appRootDirPath)
+                : args.packages;
+            return await runVulnerabilityGate({
+                abortSignal,
+                capabilities: {
+                    lookupPackages: async (resolved) => await this.lookupPackageVulnerabilities(resolved),
+                    onIndexUnavailable: ({ error, message }) => {
+                        emitIndexUnavailableMetric();
+                        getLogger().warn(message, getErrorMeta(error));
+                    },
+                    pickQuarantineHoldback: this.packageLookup.pickQuarantineHoldback,
+                    resolveInstallTree: async (resolveArgs) => await this.resolveInstallTree(resolveArgs.mode, resolveArgs.packages, resolveArgs.abortSignal),
+                    resolvePackageSpecs: async (resolveArgs) => await this.resolveTreeViaNpmDryRun(resolveArgs.specs, resolveArgs.abortSignal),
+                },
+                cveUserOverride,
+                mode,
+                packages,
+            });
+        }
+        /**
+         * Derive the `hasAnyRegistryConfigured` tri-state from the
+         * `NpmRegistryFetchResult` that the immediately-preceding
+         * `prepareForPrivateRegistry` call returned.
+         *
+         *   - `true`      — `configured` or `stale`. At least one row is known
+         *                   to exist (fresh fetch or last-known-good cache).
+         *   - `false`     — `not-configured`. The kill switch is off OR the
+         *                   server returned an empty list. A deliberate "no rows"
+         *                   observation.
+         *   - `undefined` — `prepareForPrivateRegistry` returned `undefined` (no
+         *                   client wired in) OR the client resolved to `unreachable`
+         *                   (server down with no usable cache). Both mean "we don't
+         *                   know"; `buildBlockedMessage` falls back to the default
+         *                   variant rather than asserting a row count.
+         *
+         * Kept narrow + private so the signal stays a single derivation site rather
+         * than something every catch handler reimplements.
+         */
+        static deriveHasAnyRegistryConfigured(result) {
+            if (!result)
+                return undefined;
+            switch (result.source) {
+                case "configured":
+                case "stale":
+                    return true;
+                case "not-configured":
+                    return false;
+                case "unreachable":
+                    return undefined;
+            }
+        }
+        /**
+         * Convert an exec failure from `npm --json` into a structured error.
+         *
+         * - When the stdout JSON matches a known registry-blocked condition (E404,
+         *   ENOTFOUND, E401, ...) we throw `NpmInstallBlocked` so the tool layer
+         *   can surface it to the agent as a structured result.
+         * - Otherwise we fall back to the legacy `NpmInstallError(stderr)` so any
+         *   pre-existing handler (e.g. agent-planning's POST_PROCESSING_ERRORED
+         *   branch) behaves exactly as it did before.
+         *
+         * Only used on the npm code path; pnpm continues to throw `NpmInstallError`
+         * directly because pnpm's `--json` error contract differs and the
+         * registry-blocked scenarios only matter in cloud-edit (which forces npm).
+         *
+         * `registryFetchResult` carries the most recent
+         * `prepareForPrivateRegistry` result so the structured error can encode
+         * whether the org had any configured registry rows at the moment of
+         * failure (used by `buildBlockedMessage` to choose between default and
+         * row-aware advice variants). The active llmobs span is annotated with the
+         * same data points so a downstream `npm.install_blocked.*` facet can
+         * correlate reason, host, and row presence.
+         */
+        classifyNpmExecError(error, requestedPackages, registryFetchResult) {
+            const stdout = error.stdout ?? "";
+            const hasAnyRegistryConfigured = AppShell.deriveHasAnyRegistryConfigured(registryFetchResult);
+            const blocked = parseNpmJsonError(stdout, {
+                requestedPackages,
+                hasAnyRegistryConfigured,
+            });
+            if (blocked) {
+                // Span tags for `superblocks.npm.install_blocked.*` faceting. Stringified
+                // because llmobs tag values are strings; `unknown` is used in lieu of
+                // `null`/`undefined` so the tag's cardinality stays bounded and a
+                // "field absent" datapoint is still queryable.
+                //
+                // `npm.install_blocked.registry_host` is routed through the P6.1
+                // `bucketNpmRegistryHost` sanitizer (same helper used by
+                // `recordNpmInstall`) so the tag value is a bounded enum
+                // (`public_npm` / `private` / `unknown`). `NpmInstallBlocked` only
+                // scrubs credentials and control characters — without the bucketer the
+                // raw customer registry hostname would land in llmobs tags, leaking
+                // customer-internal hosts and giving the tag unbounded cardinality.
+                llmobs.annotate({
+                    tags: {
+                        "npm.install_blocked.reason": blocked.reason,
+                        "npm.install_blocked.registry_host": bucketNpmRegistryHost(blocked.registryHost),
+                        "npm.install_blocked.npm_error_code": blocked.npmErrorCode ?? "unknown",
+                        "npm.install_blocked.has_any_registry_configured": hasAnyRegistryConfigured === undefined
+                            ? "unknown"
+                            : String(hasAnyRegistryConfigured),
+                    },
+                });
+                return blocked;
+            }
+            // Non-registry-blocked failure (ERESOLVE, EPEERINVALID, ETARGET, …).
+            // Prefer the JSON diagnostic from stdout because under `--json` stderr
+            // is sparse — preserving the diagnostic keeps agent-planning's
+            // POST_PROCESSING_ERRORED debug message useful instead of collapsing
+            // it to a generic exec-failure string.
+            const diagnostic = parseNpmJsonDiagnostic(stdout);
+            if (stdout && !diagnostic) {
+                // npm was invoked with `--json` but neither parser could extract
+                // anything from stdout. This silently bypasses the row-aware advice
+                // matrix, the structured warn log, and the llmobs span tags above —
+                // converting the silent fallback into a queryable signal so operators
+                // can find these (npm crash mid-output, stdout truncation, schema
+                // drift across npm versions, an interactive prompt sneaking past
+                // `--json`). Single line, debug-grade payload (truncated preview
+                // only) to keep log volume bounded.
+                //
+                // Scrub BEFORE slicing: raw npm `--json` stdout can contain registry
+                // URLs with userinfo or `_authToken=` lines from a leaked `.npmrc`,
+                // and slicing first could split a credential across the 200-char
+                // boundary so the regex no longer matches.
+                getLogger().warn("[npm] failed to extract structured error from `npm --json` stdout; falling back to legacy NpmInstallError", { stdoutPreview: scrubSecrets(stdout).slice(0, 200) });
+            }
+            return new NpmInstallError(diagnostic || error.stderr || error.message || "");
+        }
+        /**
+         * Wraps an install attempt so that a `registry_auth_failed` failure
+         * triggers one cache-invalidation + re-fetch + retry cycle before
+         * throwing. The helper owns the `.npmrc` materialisation so the retry
+         * picks up a freshly-fetched token without duplicating the prep call
+         * in every install method.
+         *
+         * Guard: only one retry per call — a second `registry_auth_failed`
+         * propagates unchanged.
+         */
+        async withAuthFailedRetry(attempt) {
+            const registryFetchResult = await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, this.npmRegistryClient));
+            try {
+                return await attempt(registryFetchResult);
+            }
+            catch (error) {
+                if (error instanceof NpmInstallBlocked &&
+                    error.reason === "registry_auth_failed" &&
+                    this.npmRegistryClient) {
+                    this.npmRegistryClient.invalidateCache();
+                    getLogger().info("[npm-registry] invalidated cache after registry_auth_failed; retrying install once");
+                    llmobs.annotate({
+                        tags: {
+                            "npm.registry.cache_invalidated_on_auth_failed": "true",
+                        },
+                    });
+                    const retryFetchResult = await this.enqueueFsOperation("maybeWriteNpmrc", () => prepareForPrivateRegistry(this.appRootDirPath, this.npmRegistryClient));
+                    return await attempt(retryFetchResult);
+                }
+                throw error;
+            }
+        }
+        async runPackageManagerInstall(abortSignal) {
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: short-circuit before any exec when server is unreachable
+                    // AND this org's marker says it was previously configured.
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, []);
+                    // In cloud edit mode, always use npm because pnpm is not available in the container.
+                    // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
+                    // from local editing, but we must use npm in cloud mode.
+                    const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    let packageManagerAgent;
+                    if (isCloudMode) {
+                        // Force npm in cloud mode; prepare before Mode 2 so dry-run malware
+                        // scan does not choke on workspace: protocol entries.
+                        packageManagerAgent = "npm";
+                        await this.maybePreparePackageJsonForCloudNpm();
+                    }
+                    else {
+                        // NOTE: this largely duplicates the logic in the CLI
+                        const packageManager = await detect({
+                            strategies: [
+                                "packageManager-field",
+                                "lockfile",
+                                "install-metadata",
+                                "devEngines-field",
+                            ],
+                            cwd: this.appRootDirPath,
+                        });
+                        if (!packageManager) {
+                            throw new Error("Could not detect package manager");
+                        }
+                        packageManagerAgent = packageManager.agent;
+                    }
+                    const appliedSubstitutions = await this.applyDeclaredDependencyUpgrades(await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        mode: "all",
+                    }));
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    const isNpm = packageManagerAgent === "npm";
+                    const baseInstallArgs = isNpm
+                        ? ["--fund=false", "--audit=false", "--json"]
+                        : [];
+                    const installArgs = ignoreScripts
+                        ? [...baseInstallArgs, "--ignore-scripts"]
+                        : baseInstallArgs;
+                    const installCommand = resolveCommand(packageManagerAgent, "install", installArgs);
+                    if (!installCommand) {
+                        throw new Error(`Could not determine install command for ${packageManagerAgent}, skipping package installation`);
+                    }
+                    const { command, args } = installCommand;
+                    try {
+                        const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            signal: abortSignal,
+                            // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                            // default 1 MiB exec buffer on fat dep trees.
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        });
+                        // Audit only after the install succeeds (same as Mode 1).
+                        this.maybeReportSubstitutions(appliedSubstitutions, "install_all");
+                        // On the npm path stdout is a JSON blob; translate to a compact
+                        // human-readable summary for the agent, falling back to raw stdout
+                        // when the JSON shape drifts.
+                        if (isNpm) {
+                            return parseNpmJsonSuccess(stdout) ?? stdout;
+                        }
+                        return stdout;
+                    }
+                    catch (error) {
+                        if (isNpm)
+                            throw this.classifyNpmExecError(error, undefined, registryFetchResult);
+                        throw new NpmInstallError(error.stderr || error.message);
+                    }
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                this.maybeReportBlockedInstall(err, "install_all");
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_all", capturedFetchResult, outcome, Date.now() - installStart);
+            }
+        }
+        async installSpecificPackages(packages, abortSignal, options) {
+            if (!packages || packages.length === 0) {
+                throw new Error("No packages specified for installation");
+            }
+            // Specs are interpolated into a command string that `/bin/sh -c` parses,
+            // so the name and version guards belong here rather than in each caller.
+            const invalidRequested = packages
+                .map((pkg) => pkg.name)
+                .filter((name) => !isValidNpmPackageName(name));
+            if (invalidRequested.length > 0) {
+                throw new Error(`Invalid package name(s): ${invalidRequested.join(", ")}.`);
+            }
+            const invalidVersions = packages
+                .filter((pkg) => pkg.version !== undefined && !isValidNpmVersionSpec(pkg.version))
+                .map((pkg) => pkg.name);
+            if (invalidVersions.length > 0) {
+                throw new Error(`Invalid package version(s) for: ${invalidVersions.join(", ")}.`);
+            }
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    // APPS-4370: short-circuit before exec when unreachable + everConfigured.
+                    // Pass through the requested package specs so the structured error
+                    // surfaces them to the agent ("we tried to install lodash and the
+                    // private registry was unreachable").
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, packages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name));
+                    // In cloud edit mode, always use npm because pnpm is not available in the container.
+                    // The user's project may have pnpm signals (pnpm-lock.yaml, packageManager field)
+                    // from local editing, but we must use npm in cloud mode. Prepare before the
+                    // Mode 1 dry-run so leftover workspace: entries cannot break malware coverage.
+                    const isCloudMode = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    let packageManagerAgent;
+                    if (isCloudMode) {
+                        // Force npm in cloud mode
+                        packageManagerAgent = "npm";
+                        await this.maybePreparePackageJsonForCloudNpm();
+                    }
+                    else {
+                        const packageManager = await detect({
+                            strategies: [
+                                "packageManager-field",
+                                "lockfile",
+                                "install-metadata",
+                                "devEngines-field",
+                            ],
+                            cwd: this.appRootDirPath,
+                        });
+                        if (!packageManager) {
+                            throw new Error("Could not detect package manager");
+                        }
+                        packageManagerAgent = packageManager.agent;
+                    }
+                    // Malware hard-block on the dry-run resolved tree (top-level +
+                    // transitive) before the real install runs. Mode 1 also returns
+                    // silent CVE substitutions applied to the install argv below.
+                    const remediation = await this.maybeRemediateVulnerabilities({
+                        abortSignal,
+                        cveUserOverride: options?.cveUserOverride,
+                        mode: "specific",
+                        packages,
+                    });
+                    const packagesToInstall = applyPackageSubstitutions(packages, remediation.substitutions);
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    const isNpm = packageManagerAgent === "npm";
+                    // Separate regular and dev dependencies
+                    const regularPackages = packagesToInstall.filter((pkg) => !pkg.dev);
+                    const devPackages = packagesToInstall.filter((pkg) => pkg.dev);
+                    const outputs = [];
+                    // Install regular dependencies
+                    if (regularPackages.length > 0) {
+                        const packageSpecs = regularPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+                        const baseArgs = isNpm
+                            ? ["--fund=false", "--audit=false", "--json", ...packageSpecs]
+                            : packageSpecs;
+                        const addCommand = resolveCommand(packageManagerAgent, "add", ignoreScripts ? ["--ignore-scripts", ...baseArgs] : baseArgs);
+                        if (!addCommand) {
+                            throw new Error(`Could not determine add command for ${packageManagerAgent}`);
+                        }
+                        const { command, args } = addCommand;
+                        try {
+                            const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                                cwd: this.appRootDirPath,
+                                env: this.installLogEnv(),
+                                signal: abortSignal,
+                                // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                                // default 1 MiB exec buffer on fat dep trees.
+                                maxBuffer: NPM_JSON_MAX_BUFFER,
+                            });
+                            outputs.push(isNpm ? (parseNpmJsonSuccess(stdout) ?? stdout) : stdout);
+                        }
+                        catch (error) {
+                            if (isNpm)
+                                throw this.classifyNpmExecError(error, regularPackages, registryFetchResult);
+                            throw new NpmInstallError(error.stderr || error.message);
+                        }
+                    }
+                    // Install dev dependencies
+                    if (devPackages.length > 0) {
+                        const packageSpecs = devPackages.map((pkg) => pkg.version ? `${pkg.name}@${pkg.version}` : pkg.name);
+                        const baseArgs = isNpm
+                            ? [
+                                "--save-dev",
+                                "--fund=false",
+                                "--audit=false",
+                                "--json",
+                                ...packageSpecs,
+                            ]
+                            : ["-D", ...packageSpecs];
+                        const addCommand = resolveCommand(packageManagerAgent, "add", ignoreScripts ? ["--ignore-scripts", ...baseArgs] : baseArgs);
+                        if (!addCommand) {
+                            throw new Error(`Could not determine add command for ${packageManagerAgent}`);
+                        }
+                        const { command, args } = addCommand;
+                        try {
+                            const { stdout } = await execPromise(`${command} ${args.join(" ")}`, {
+                                cwd: this.appRootDirPath,
+                                env: this.installLogEnv(),
+                                signal: abortSignal,
+                                // See `NPM_JSON_MAX_BUFFER` — `--json` summary can outgrow the
+                                // default 1 MiB exec buffer on fat dep trees.
+                                maxBuffer: NPM_JSON_MAX_BUFFER,
+                            });
+                            outputs.push(isNpm ? (parseNpmJsonSuccess(stdout) ?? stdout) : stdout);
+                        }
+                        catch (error) {
+                            if (isNpm)
+                                throw this.classifyNpmExecError(error, devPackages, registryFetchResult);
+                            throw new NpmInstallError(error.stderr || error.message);
+                        }
+                    }
+                    // Audit only after every install group succeeds: a selected
+                    // substitution is not an applied substitution if npm fails.
+                    this.maybeReportSubstitutions(remediation.substitutions, "install_specific");
+                    // Audited here, not at the tool layer: the gate is what consumed the
+                    // override, and the install has now actually landed.
+                    if (options?.cveUserOverride &&
+                        remediation.userOverridePackages?.length) {
+                        this.reportNpmUserOverride({
+                            packages: remediation.userOverridePackages,
+                            reason: options.cveUserOverride.reason,
+                        });
+                    }
+                    return outputs.join("\n");
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                this.maybeReportBlockedInstall(err, "install_specific");
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("install_specific", capturedFetchResult, outcome, Date.now() - installStart);
+            }
+        }
+        async uninstallPackages(packages, options) {
+            const invalidRequested = packages.filter((name) => !isValidNpmPackageName(name));
+            if (invalidRequested.length > 0) {
+                throw new Error(`Invalid package name(s): ${invalidRequested.join(", ")}.`);
+            }
+            // Core-package guard (APPS-4527): refuse to uninstall packages the
+            // platform itself depends on (`@superblocksteam/*`, react, react-router,
+            // vite, …). Removing one breaks the dev server, the bundle builder, or
+            // the app runtime — no caller has a legitimate reason. Checked before
+            // any registry work so the refusal is deterministic and offline.
+            const protectedRequested = packages.filter((p) => isProtectedCorePackage(p));
+            if (protectedRequested.length > 0) {
+                throw new Error(`Refusing to uninstall protected core package(s): ${protectedRequested.join(", ")}. ` +
+                    "These are required by the Superblocks platform (dev server, build pipeline, or app runtime) and must remain in the app.");
+            }
+            const installStart = Date.now();
+            let outcome = "success";
+            let capturedFetchResult;
+            // Uninstalls hit the same registry resolution rules as installs (the
+            // dependency-tree solver re-reifies the remaining tree and can re-fetch
+            // metadata), so they run through the SAME safety wrapper as every
+            // install path rather than a bespoke one-shot exec:
+            //
+            //   - `withAuthFailedRetry` owns the `.npmrc` materialization (via
+            //     `prepareForPrivateRegistry`, same serialization as `runNpmInstall`)
+            //     AND retries once on `registry_auth_failed` after invalidating the
+            //     registry cache, so an uninstall against a deployment whose
+            //     private-registry token was rotated mid-session recovers instead of
+            //     hard-failing on the stale `_authToken=` line.
+            //   - `maybeShortCircuitForUnreachable` (APPS-4370) refuses to spawn when
+            //     the config server is unreachable AND this org was previously
+            //     configured. Without it the uninstall escaped the fail-closed gate,
+            //     401'd against the stale token, and surfaced `registry_auth_failed`
+            //     (rotate-credentials advice) instead of `registry_unreachable`
+            //     (registry-down advice) — the wrong remediation.
+            //   - The npm path runs with `--json` and routes failures through
+            //     `classifyNpmExecError`, identical to `installSpecificPackages`, so
+            //     E404 / E401 / ENOTFOUND surface as a structured `NpmInstallBlocked`
+            //     (and the auth-failed case feeds the retry above).
+            //
+            // `shouldIgnoreInstallScripts` honours the org's `allowInstallScripts`
+            // policy on uninstall too — `preuninstall` / `postuninstall` lifecycle
+            // scripts are just as dangerous as install-time ones.
+            try {
+                return await this.withAuthFailedRetry(async (registryFetchResult) => {
+                    capturedFetchResult = registryFetchResult;
+                    this.maybeShortCircuitForUnreachable(registryFetchResult, packages);
+                    const ignoreScripts = shouldIgnoreInstallScripts(registryFetchResult);
+                    // pnpm in local dev (avoids store/lockfile conflicts with the
+                    // surrounding workspace); npm everywhere else so the `--json` error
+                    // contract — and therefore the registry-blocked advice matrix —
+                    // applies. Mirrors `runNpmInstall` / `installSpecificPackages`.
+                    const isNpm = process.env.SUPERBLOCKS_SERVER_ENV !== "local";
+                    const packageManager = isNpm ? "npm" : "pnpm";
+                    const uninstallCmd = isNpm ? "uninstall" : "remove";
+                    const jsonFlag = isNpm ? " --json" : "";
+                    const baseCommand = `${packageManager} ${uninstallCmd} ${packages.join(" ")}${jsonFlag}`;
+                    const command = ignoreScripts
+                        ? `${baseCommand} --ignore-scripts`
+                        : baseCommand;
+                    return await new Promise((resolve, reject) => {
+                        exec(command, {
+                            cwd: this.appRootDirPath,
+                            env: this.installLogEnv(),
+                            timeout: 30_000,
+                            signal: options?.abortSignal,
+                            // `--json` summary can outgrow the default 1 MiB exec buffer.
+                            maxBuffer: NPM_JSON_MAX_BUFFER,
+                        }, (error, stdout, stderr) => {
+                            if (error) {
+                                // Same classifier as the install paths: a registry block
+                                // (E404 / E401 / ENOTFOUND, ...) becomes a structured
+                                // `NpmInstallBlocked` (with row-aware advice + the
+                                // auth-failed retry signal consumed by `withAuthFailedRetry`);
+                                // anything else falls back to the legacy `NpmInstallError`.
+                                // pnpm doesn't emit the `--json` envelope, so it keeps the
+                                // raw-stderr error.
+                                if (isNpm) {
+                                    return reject(this.classifyNpmExecError({ stdout, stderr, message: error.message }, undefined, registryFetchResult));
+                                }
+                                return reject(new NpmInstallError(stderr || error.message));
+                            }
+                            // On the npm path stdout is a `--json` blob; collapse it to a
+                            // compact human-readable summary (same as
+                            // `installSpecificPackages`), falling back to raw stdout on
+                            // shape drift.
+                            return resolve({
+                                stdout: isNpm
+                                    ? (parseNpmJsonSuccess(stdout) ?? stdout)
+                                    : stdout,
+                                stderr,
+                            });
+                        });
+                    });
+                });
+            }
+            catch (err) {
+                outcome = outcomeFromInstallError(err);
+                this.maybeReportBlockedInstall(err, "uninstall");
+                throw err;
+            }
+            finally {
+                this.observeNpmInstall("uninstall", capturedFetchResult, outcome, Date.now() - installStart);
+            }
+        }
+        static MAX_GENERATION_RUNS = 10;
+        async saveGeneratedArtifact(artifact, stepId, runTimestamp) {
+            const stepPath = path.join(this.appRootDirPath, ".superblocks", "generations", runTimestamp, stepId, artifact.filePath);
+            await mkdir(path.dirname(stepPath), { recursive: true });
+            const relativeStepPath = path.relative(this.appRootDirPath, stepPath);
+            getLogger().debug(`[ai-service] Saving step file: ${relativeStepPath}`);
+            await writeFile(stepPath, artifact.content);
+            void this.pruneGenerations().catch((error) => {
+                getLogger().warn("[ai-service] Failed to prune generations", getErrorMeta(error));
+            });
+        }
+        async pruneGenerations(keepLast = AppShell.MAX_GENERATION_RUNS) {
+            const generationsDir = path.join(this.appRootDirPath, ".superblocks", "generations");
+            let entries;
+            try {
+                entries = await readdir(generationsDir);
+            }
+            catch (err) {
+                if (err?.code === "ENOENT")
+                    return;
+                throw err;
+            }
+            if (entries.length <= keepLast) {
+                return;
+            }
+            entries.sort();
+            const toDelete = entries.slice(0, entries.length - keepLast);
+            await Promise.all(toDelete.map((entry) => rm(path.join(generationsDir, entry), {
+                recursive: true,
+                force: true,
+            })));
+        }
+        async sendMessage(message) {
+            if (this.messageSender) {
+                await this.messageSender(message);
+            }
+            else {
+                getLogger().warn(`[ai-service] No message sender configured, cannot send message: ${message.type}`);
+            }
+        }
+        /** Check if a given path exists in the app dir. */
+        async pathExists(relativePath) {
+            const fullPath = path.join(this.appRootDirPath, relativePath);
+            try {
+                await access(fullPath); // F_OK is the default: "is it there?"
+                return true;
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return false; // path missing
+                throw err; // rethrow other errors (e.g., permissions)
+            }
+        }
+        /**
+         * Clears the scratch directory used for temporary API source files.
+         * This is typically called when a draft is rejected to clean up temporary artifacts.
+         */
+        async clearScratchDirectory() {
+            const scratchDir = path.join(this.appRootDirPath, ".superblocks", "scratch");
+            await this.enqueueFsOperation("clearScratchDirectory", async () => {
+                try {
+                    await rm(scratchDir, { recursive: true });
+                }
+                catch {
+                    // Ignore errors if directory doesn't exist or can't be deleted
+                }
+            });
+        }
+        // ============================================================================
+        // Filesystem Operations
+        // ============================================================================
+        /**
+         * Reads a single file's content from the application.
+         *
+         * Handles virtual path translation for files managed by the VirtualFileSystem:
+         * - Virtual paths are read via the appropriate handler
+         * - Regular files are read directly from disk
+         *
+         * @param relativePath - The virtual path relative to app root
+         * @param options - Optional read options
+         * @param options.offset - Line number to start reading from (1-indexed)
+         * @param options.limit - Number of lines to read
+         * @returns The file content as a string
+         * @throws Error if file does not exist or cannot be read
+         */
+        async readFile(relativePath, options) {
+            return await this.enqueueFsOperation("readFile", async () => {
+                const content = await this.readFileInternal(relativePath, options);
+                // Auto-track successful reads to allow subsequent writes
+                this.markRead(relativePath);
+                return content;
+            }, {
+                appShellQueueHasLimit: Boolean(options?.limit),
+                appShellQueueHasOffset: Boolean(options?.offset),
+                appShellQueuePath: relativePath,
+            });
+        }
+        /**
+         * Internal read implementation (no queue).
+         * Use this from other methods that are already enqueued to avoid deadlock.
+         */
+        async readFileInternal(relativePath, options) {
+            const logger = getLogger();
+            let content;
+            const isVirtual = this.virtualFs.isVirtualPath(relativePath);
+            logger.info(`[AppShell.readFileInternal] path="${relativePath}", isVirtual=${isVirtual}`);
+            // Try virtual filesystem first
+            if (isVirtual) {
+                logger.info(`[AppShell.readFileInternal] Reading via VirtualFileSystem: ${relativePath}`);
+                const virtualContent = await this.virtualFs.read(relativePath, {
+                    appRootDirPath: this.appRootDirPath,
+                    templateRenderer: this.templateRenderer,
+                });
+                if (virtualContent === undefined) {
+                    const info = this.virtualFs.parse(relativePath);
+                    const name = info?.params.apiName ?? relativePath;
+                    logger.warn(`[AppShell.readFileInternal] Virtual file not found: ${relativePath}`);
+                    throw new Error(`${name} not found. Use the appropriate tool to create it.`);
+                }
+                logger.info(`[AppShell.readFileInternal] Virtual file read success: ${relativePath} (${virtualContent.length} chars)`);
+                content = virtualContent;
+            }
+            else if (this.virtualFs.isPhysicalPath(relativePath)) {
+                // Block direct reads of physical API files
+                throw new Error(this.virtualFs.getBlockedReadError(relativePath));
+            }
+            else {
+                // Regular file read
+                logger.info(`[AppShell.readFileInternal] Reading from disk: ${relativePath}`);
+                const absolutePath = path.join(this.appRootDirPath, relativePath);
+                content = await fsReadFile(absolutePath, "utf-8");
+            }
+            // Apply offset and limit if provided
+            if (options?.offset || options?.limit) {
+                const lines = content.split("\n");
+                const startLine = options.offset ? options.offset - 1 : 0;
+                const endLine = options.limit ? startLine + options.limit : lines.length;
+                return lines.slice(startLine, endLine).join("\n");
+            }
+            return content;
+        }
+        /**
+         * Writes content to a file as a draft.
+         *
+         * Handles virtual path translation for files managed by the VirtualFileSystem:
+         * - Virtual paths are written via the appropriate handler
+         * - Regular files are written via the draft interface
+         *
+         * @param relativePath - Virtual path relative to app root
+         * @param content - File content to write
+         * @param options - Optional write options
+         * @param options.bypassRequireRead - Skip the read-before-write check (use for new files)
+         * @throws Error if path is blacklisted, restricted, or draft manager not configured
+         * @throws Error if file requires reading first (unless bypassed)
+         */
+        async writeFile(relativePath, content, options) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required to write files. Configure AppShell with a draftInterface.");
+            }
+            // Enforce read-before-write unless explicitly bypassed
+            if (!options?.bypassRequireRead && this.isReadRequired(relativePath)) {
+                throw new Error(`Cannot write to ${relativePath} without reading it first. Please read the file before attempting to write to it.`);
+            }
+            const executeStart = performance.now();
+            await this.writeFileInternal(relativePath, content);
+            llmobs.annotate({
+                metadata: {
+                    appShellQueueExecuteMs: Math.round(performance.now() - executeStart),
+                    appShellQueueOperation: "writeFile",
+                    appShellQueuePath: relativePath,
+                },
+            });
+        }
+        /**
+         * Internal write implementation.
+         * Called directly by writeFile (no queue wrapper needed since draftInterface queues).
+         */
+        async writeFileInternal(relativePath, rawContent) {
+            // Deterministic safety net: rewrite value imports of `lucide-react/dynamic`
+            // type-only exports (e.g. `IconName`) into type imports. A stray value
+            // import compiles but crashes the app at runtime and blanks the preview,
+            // which blocks UI verification (APPS-4518). Applied here — the shared sink
+            // for every persist path (write, copy, copyDirectory, rename) — so files
+            // brought in via copy are covered too. No-op for unaffected files; for
+            // Buffer content we only decode-and-replace when a fix actually applies.
+            let content = rawContent;
+            if (isFixableLucidePath(relativePath)) {
+                if (typeof content === "string") {
+                    content = fixLucideDynamicTypeImports(content);
+                }
+                else if (Buffer.isBuffer(content)) {
+                    const text = content.toString("utf8");
+                    const fixed = fixLucideDynamicTypeImports(text);
+                    if (fixed !== text) {
+                        content = fixed;
+                    }
+                }
+            }
+            const isVirtual = this.virtualFs.isVirtualPath(relativePath);
+            if (Buffer.isBuffer(content) && isVirtual) {
+                throw new Error(`Cannot write binary content to virtual file: ${relativePath}`);
+            }
+            if (!isVirtual) {
+                validateFileOperation("write", relativePath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+                if (relativePath.endsWith(".ts") || relativePath.endsWith(".tsx")) {
+                    try {
+                        parseTsxModule(typeof content === "string" ? content : content.toString("utf8"), relativePath);
+                    }
+                    catch (error) {
+                        getLogger().warn(`TSX parse validation rejected write: ${relativePath}`, getErrorMeta(error));
+                        emitWriteTsxParseRejectedMetric(relativePath.endsWith(".tsx") ? "tsx" : "ts");
+                        const message = error instanceof Error ? error.message : String(error);
+                        throw new ToolExecutionError(`${relativePath}: ${message}`);
+                    }
+                }
+            }
+            if (isVirtual) {
+                await this.virtualFs.write(relativePath, content, {
+                    appRootDirPath: this.appRootDirPath,
+                });
+                await this.draftManager.createDraftMarker(relativePath);
+                return;
+            }
+            const absolutePath = path.join(this.appRootDirPath, relativePath);
+            await mkdir(path.dirname(absolutePath), { recursive: true });
+            await this.draftManager.createDraft(relativePath, content);
+        }
+        resolveAppRelativePath(relativePath, direction) {
+            if (path.isAbsolute(relativePath)) {
+                throw new Error(`Cannot copy ${direction} outside the application root: ${relativePath}`);
+            }
+            const absolutePath = path.resolve(this.appRootDirPath, relativePath);
+            const relativeToRoot = path.relative(this.appRootDirPath, absolutePath);
+            if (relativeToRoot === ".." ||
+                relativeToRoot.startsWith(`..${path.sep}`) ||
+                path.isAbsolute(relativeToRoot)) {
+                throw new Error(`Cannot copy ${direction} outside the application root: ${relativePath}`);
+            }
+            return absolutePath;
+        }
+        createEmptyCopyResult(verbose) {
+            return {
+                copied: verbose ? [] : undefined,
+                copiedCount: 0,
+                rejected: verbose ? [] : undefined,
+                rejectedCount: 0,
+                skipped: verbose ? [] : undefined,
+                skippedCount: 0,
+            };
+        }
+        recordCopied(result, path) {
+            result.copiedCount += 1;
+            result.copied?.push(path);
+        }
+        recordSkipped(result, path, reason) {
+            result.skippedCount += 1;
+            result.skipped?.push({ path, reason });
+        }
+        recordRejected(result, path, reason) {
+            result.rejectedCount += 1;
+            result.rejected?.push({ path, reason });
+        }
+        finalizeCopyResult(result) {
+            if (result.copied === undefined) {
+                delete result.copied;
+            }
+            if (result.skipped === undefined) {
+                delete result.skipped;
+            }
+            if (result.rejected === undefined) {
+                delete result.rejected;
+            }
+            return result;
+        }
+        async copyFileInternal({ conflictStrategy = "fail", destinationPath, result, sourcePath, }) {
+            const absoluteSourcePath = this.resolveAppRelativePath(sourcePath, "from");
+            this.resolveAppRelativePath(destinationPath, "to");
+            validateFileOperation("write", destinationPath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+            const destinationExists = await this.pathExists(destinationPath);
+            if (destinationExists) {
+                if (conflictStrategy === "skip") {
+                    this.recordSkipped(result, destinationPath, "destination_exists");
+                    return;
+                }
+                if (conflictStrategy === "fail") {
+                    throw new Error(`Copy failed: ${destinationPath} already exists`);
+                }
+            }
+            const stats = await stat(absoluteSourcePath);
+            if (!stats.isFile()) {
+                throw new Error(`Copy failed: ${sourcePath} is not a file`);
+            }
+            const content = await fsReadFile(absoluteSourcePath);
+            await this.writeFileInternal(destinationPath, content);
+            this.recordCopied(result, destinationPath);
+        }
+        async preflightCopyFile({ destinationPath, sourcePath, }) {
+            const absoluteSourcePath = this.resolveAppRelativePath(sourcePath, "from");
+            this.resolveAppRelativePath(destinationPath, "to");
+            validateFileOperation("write", destinationPath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+            if (await this.pathExists(destinationPath)) {
+                throw new Error(`Copy failed: ${destinationPath} already exists`);
+            }
+            const stats = await stat(absoluteSourcePath);
+            if (!stats.isFile()) {
+                throw new Error(`Copy failed: ${sourcePath} is not a file`);
+            }
+        }
+        async copyFile(options) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required to copy files. Configure AppShell with a draftInterface.");
+            }
+            const executeStart = performance.now();
+            const result = this.createEmptyCopyResult(Boolean(options.verbose));
+            await this.copyFileInternal({
+                conflictStrategy: options.conflictStrategy,
+                destinationPath: options.destinationPath,
+                result,
+                sourcePath: options.sourcePath,
+            });
+            llmobs.annotate({
+                metadata: {
+                    appShellQueueExecuteMs: Math.round(performance.now() - executeStart),
+                    appShellQueueOperation: "copyFile",
+                    appShellQueuePath: options.destinationPath,
+                },
+            });
+            return this.finalizeCopyResult(result);
+        }
+        async collectDirectoryCopyEntries({ absoluteSourceDir, destinationDir, result, sourceDir, }) {
+            const entries = [];
+            const walk = async (currentAbsoluteDir, currentSourceDir, currentDestinationDir) => {
+                const dirEntries = await readdir(currentAbsoluteDir, {
+                    withFileTypes: true,
+                });
+                for (const entry of dirEntries) {
+                    const sourcePath = path.join(currentSourceDir, entry.name);
+                    const destinationPath = path.join(currentDestinationDir, entry.name);
+                    if (entry.isSymbolicLink()) {
+                        this.recordRejected(result, destinationPath, "Cannot copy symbolic links");
+                        continue;
+                    }
+                    if (entry.isDirectory()) {
+                        if (DEFAULT_COPY_DIRECTORY_EXCLUDES.has(entry.name)) {
+                            this.recordSkipped(result, destinationPath, "default_excluded");
+                            continue;
+                        }
+                        await walk(path.join(currentAbsoluteDir, entry.name), sourcePath, destinationPath);
+                        continue;
+                    }
+                    if (entry.isFile()) {
+                        entries.push({ destinationPath, sourcePath });
+                    }
+                }
+            };
+            await walk(absoluteSourceDir, sourceDir, destinationDir);
+            return entries;
+        }
+        async copyDirectory(options) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required to copy directories. Configure AppShell with a draftInterface.");
+            }
+            const executeStart = performance.now();
+            const result = this.createEmptyCopyResult(Boolean(options.verbose));
+            const absoluteSourceDir = this.resolveAppRelativePath(options.sourceDir, "from");
+            this.resolveAppRelativePath(options.destinationDir, "to");
+            const sourceStats = await stat(absoluteSourceDir);
+            if (!sourceStats.isDirectory()) {
+                throw new Error(`Copy failed: ${options.sourceDir} is not a directory`);
+            }
+            const entries = await this.collectDirectoryCopyEntries({
+                absoluteSourceDir,
+                destinationDir: options.destinationDir,
+                result,
+                sourceDir: options.sourceDir,
+            });
+            if ((options.conflictStrategy ?? "fail") === "fail") {
+                for (const entry of entries) {
+                    await this.preflightCopyFile(entry);
+                }
+            }
+            for (const entry of entries) {
+                await this.copyFileInternal({
+                    // The "fail" strategy is preflighted above so we avoid copying part of
+                    // a directory before discovering an existing destination. This is not
+                    // fully atomic: a destination could still appear between preflight and
+                    // write. Closing that race properly needs a reentrant fs-operation lock
+                    // so the whole directory copy can hold the lock while nested draft
+                    // writes reuse the parent lock instead of deadlocking.
+                    conflictStrategy: (options.conflictStrategy ?? "fail") === "fail"
+                        ? "replace"
+                        : options.conflictStrategy,
+                    destinationPath: entry.destinationPath,
+                    result,
+                    sourcePath: entry.sourcePath,
+                });
+            }
+            llmobs.annotate({
+                metadata: {
+                    appShellQueueExecuteMs: Math.round(performance.now() - executeStart),
+                    appShellQueueOperation: "copyDirectory",
+                    appShellQueuePath: options.destinationDir,
+                },
+            });
+            return this.finalizeCopyResult(result);
+        }
+        /**
+         * Deletes a file or directory as a draft operation.
+         *
+         * Handles virtual path translation for files managed by the VirtualFileSystem:
+         * - Virtual paths delete via the appropriate handler
+         * - Regular files/directories are deleted via the draft interface
+         *
+         * @param relativePath - Virtual path relative to app root
+         * @throws Error if path is protected or draft manager not configured
+         */
+        async deleteFile(relativePath) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required to delete files. Configure AppShell with a draftInterface.");
+            }
+            await this.deleteFileInternal(relativePath);
+        }
+        /**
+         * Internal delete implementation.
+         * Called directly by deleteFile (no queue wrapper needed since draftInterface queues).
+         */
+        async deleteFileInternal(relativePath) {
+            // Handle virtual paths
+            if (this.virtualFs.isVirtualPath(relativePath)) {
+                await this.virtualFs.delete(relativePath, {
+                    appRootDirPath: this.appRootDirPath,
+                    createDraftDelete: this.draftManager.createDraftDelete.bind(this.draftManager),
+                });
+                return;
+            }
+            // Validate the operation for non-virtual files
+            validateFileOperation("delete", relativePath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+            const absolutePath = path.join(this.appRootDirPath, relativePath);
+            // Check if path exists and what type it is
+            let stats;
+            try {
+                stats = await stat(absolutePath);
+            }
+            catch {
+                throw new Error(`File or directory ${relativePath} not found`);
+            }
+            if (stats.isDirectory()) {
+                // Recursively delete directory contents
+                await this.deleteDirectoryRecursive(absolutePath);
+                // Remove the directory itself
+                await rm(absolutePath, { recursive: true, force: true });
+            }
+            else {
+                // Single file deletion
+                await this.draftManager.createDraftDelete(relativePath);
+            }
+        }
+        /**
+         * Implementation of listFiles supporting both signatures.
+         */
+        async listFiles(patterns, options) {
+            return await this.enqueueFsOperation("listFiles", async () => {
+                const { includeMetadata, ...restOptions } = options ?? {};
+                // Get virtualized file paths
+                const allPaths = await this.listFilesInternal(patterns, restOptions);
+                // Return paths only if metadata not requested
+                if (!includeMetadata) {
+                    return allPaths;
+                }
+                // Gather metadata for each path
+                return await this.getFileMetadataList(allPaths);
+            }, {
+                appShellQueueIncludeMetadata: Boolean(options?.includeMetadata),
+                appShellQueuePatternCount: patterns?.length ?? 0,
+            });
+        }
+        /**
+         * Internal list implementation (no queue).
+         * Use this from other methods that are already enqueued to avoid deadlock.
+         *
+         * @param patterns - Glob patterns to match
+         * @param options - Glob options
+         * @returns Array of virtualized file paths (physical API paths converted to virtual)
+         */
+        async listFilesInternal(patterns, options) {
+            const patternsToUse = patterns ?? [...APPLICATION_FILE_PATTERNS];
+            const { includeDirs, ...globOptions } = options ?? {};
+            const files = await glob(patternsToUse, {
+                cwd: this.appRootDirPath,
+                absolute: false,
+                nodir: !includeDirs,
+                ignore: [...STANDARD_IGNORE_PATTERNS],
+                ...globOptions,
+            });
+            // Convert physical paths to virtual paths using VFS
+            const virtualPaths = this.virtualFs.toVirtualPaths(files);
+            // Discover virtual files from scratch (newly created, not yet persisted)
+            const scratchApiFiles = await glob(".superblocks/scratch/apis%2F*.ts", {
+                cwd: this.appRootDirPath,
+                absolute: false,
+                nodir: true,
+            });
+            const scratchVirtualPaths = scratchApiFiles
+                .map((f) => {
+                const match = f.match(/apis%2F(.+)\.ts$/);
+                return match ? `apis/${match[1]}.ts` : null;
+            })
+                .filter((f) => f !== null);
+            // Combine and deduplicate
+            return Array.from(new Set([...virtualPaths, ...scratchVirtualPaths]));
+        }
+        /**
+         * Gets metadata for a list of file paths.
+         *
+         * @param paths - Array of virtual paths to get metadata for
+         * @returns Array of FileMetadata objects (excludes paths that don't exist)
+         */
+        async getFileMetadataList(paths) {
+            const results = [];
+            for (const virtualPath of paths) {
+                const metadata = await this.getFileMetadata(virtualPath);
+                if (metadata) {
+                    results.push(metadata);
+                }
+            }
+            return results;
+        }
+        /**
+         * Gets metadata for a single file path.
+         *
+         * @param virtualPath - The virtual path to get metadata for
+         * @returns FileMetadata or undefined if file doesn't exist
+         */
+        async getFileMetadata(virtualPath) {
+            // Check if virtual file - use handler's getMetadata if available
+            if (this.virtualFs.isVirtualPath(virtualPath)) {
+                const handler = this.virtualFs.getHandler(virtualPath);
+                if (handler?.getMetadata) {
+                    return handler.getMetadata(virtualPath, {
+                        appRootDirPath: this.appRootDirPath,
+                    });
+                }
+                // Fallback: derive metadata from scratch file for API files
+                return this.getApiFileMetadata(virtualPath);
+            }
+            // Regular file - use fs.stat
+            const absolutePath = path.join(this.appRootDirPath, virtualPath);
+            try {
+                const stats = await stat(absolutePath);
+                return {
+                    path: virtualPath,
+                    size: stats.size,
+                    mtime: stats.mtime,
+                    isDirectory: stats.isDirectory(),
+                    isFile: stats.isFile(),
+                };
+            }
+            catch {
+                return undefined;
+            }
+        }
+        /**
+         * Gets metadata for a virtual API file.
+         * Checks scratch file first (for pending changes), then falls back to YAML.
+         *
+         * @param virtualPath - The virtual API path (e.g., "apis/MyAPI.ts")
+         * @returns FileMetadata or undefined if not found
+         */
+        async getApiFileMetadata(virtualPath) {
+            // Check scratch file first (for pending changes)
+            const scratchPath = `.superblocks/scratch/${encodeURIComponent(virtualPath)}`;
+            const absoluteScratchPath = path.join(this.appRootDirPath, scratchPath);
+            try {
+                const stats = await stat(absoluteScratchPath);
+                return {
+                    path: virtualPath,
+                    size: stats.size,
+                    mtime: stats.mtime,
+                    isDirectory: false,
+                    isFile: true,
+                };
+            }
+            catch {
+                // Fall back to YAML directory
+            }
+            // Try to find the API YAML file
+            const info = this.virtualFs.parse(virtualPath);
+            if (info?.params.apiName) {
+                const yamlPath = `apis/${info.params.apiName}/api.yaml`;
+                const absoluteYamlPath = path.join(this.appRootDirPath, yamlPath);
+                try {
+                    const stats = await stat(absoluteYamlPath);
+                    return {
+                        path: virtualPath,
+                        size: stats.size,
+                        mtime: stats.mtime,
+                        isDirectory: false,
+                        isFile: true,
+                    };
+                }
+                catch {
+                    return undefined;
+                }
+            }
+            return undefined;
+        }
+        /**
+         * Renames or moves a file.
+         *
+         * Implemented as read + write + delete to work with the draft system.
+         *
+         * @param oldPath - Current virtual path
+         * @param newPath - New virtual path
+         * @throws Error if old file doesn't exist or new path is invalid
+         * @throws Error if old file requires reading first
+         */
+        async renameFile(oldPath, newPath) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required to rename files. Configure AppShell with a draftInterface.");
+            }
+            // Validate both paths
+            validateFileOperation("rename", oldPath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+            validateFileOperation("write", newPath, this.appRootDirPath, undefined, this.pathValidator, this.getFileOperationBlacklistOptions());
+            // Enforce read-before-write on the source file
+            if (this.isReadRequired(oldPath)) {
+                throw new Error(`Cannot rename ${oldPath} without reading it first. Please read the file before attempting to rename it.`);
+            }
+            // Read content first (this is just fs read, no queue needed)
+            const content = await this.readFileInternal(oldPath);
+            await this.writeFileInternal(newPath, content);
+            await this.deleteFileInternal(oldPath);
+        }
+        // ============================================================================
+        // Draft Management
+        // ============================================================================
+        /**
+         * Checks if there are any pending draft changes.
+         *
+         * @returns true if there are uncommitted draft changes
+         */
+        async hasDraftChanges() {
+            if (!this.draftManager) {
+                return false;
+            }
+            return await this.draftManager.hasDraftChanges();
+        }
+        /**
+         * Gets a unified diff of pending draft changes.
+         *
+         * @param paths - Optional specific paths to diff. If empty, diffs all changes.
+         * @returns Unified diff string
+         */
+        async getDraftDiff(paths) {
+            if (!this.draftManager) {
+                return "";
+            }
+            return await this.draftManager.getDraftDiff(paths);
+        }
+        /**
+         * Gets categorized draft changes.
+         *
+         * @returns Object containing arrays of edited, added, and deleted paths
+         */
+        async getDraftChanges() {
+            if (!this.draftManager) {
+                return { edits: [], additions: [], deletions: [] };
+            }
+            return await this.draftManager.getDraftChanges();
+        }
+        /**
+         * Gets the underlying draft interface for direct access.
+         *
+         * This should only be used for advanced operations that require
+         * direct access to the draft interface. Prefer using the AppShell
+         * methods when possible.
+         *
+         * @internal
+         */
+        getDraftInterface() {
+            return this.draftManager?.getInterface();
+        }
+        // ============================================================================
+        // Read Tracking (Read-Before-Write Enforcement)
+        // ============================================================================
+        /**
+         * Check if a file must be read before it can be written.
+         *
+         * @param relativePath - The path to check
+         * @returns true if the file must be read before writing
+         */
+        isReadRequired(relativePath) {
+            return this.requiredReads.has(relativePath);
+        }
+        /**
+         * Mark a file as requiring a read before write.
+         *
+         * Call this when a file has been modified externally (e.g., by lint/format)
+         * to ensure the AI reads the updated content before making further changes.
+         *
+         * @param relativePath - The path to mark as requiring read
+         */
+        requireRead(relativePath) {
+            this.requiredReads.add(relativePath);
+        }
+        /**
+         * Mark a file as having been read, allowing subsequent writes.
+         * Called internally after successful read operations.
+         */
+        markRead(relativePath) {
+            this.requiredReads.delete(relativePath);
+        }
+        getFileOperationBlacklistOptions() {
+            return {
+                useLessProtectedPatterns: this.enableDeletingLockfiles,
+            };
+        }
+        // ============================================================================
+        // Private Helpers
+        // ============================================================================
+        /**
+         * Recursively deletes directory contents by creating draft deletes.
+         */
+        async deleteDirectoryRecursive(dirPath) {
+            if (!this.draftManager) {
+                throw new Error("DraftInterface is required for directory deletion");
+            }
+            const entries = await readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dirPath, entry.name);
+                const relativePath = path.relative(this.appRootDirPath, fullPath);
+                if (entry.isDirectory()) {
+                    await this.deleteDirectoryRecursive(fullPath);
+                }
+                else {
+                    await this.draftManager.createDraftDelete(relativePath);
+                }
+            }
+        }
+    };
+})();
+export { AppShell };
 //# sourceMappingURL=shell.js.map