@superblocksteam/vite-plugin-file-sync 2.0.123 → 2.0.124-next.0

package/dist/ai-service/app-interface/npm-registry.js

@@ -1,6 +1,82 @@
-import { chmod, mkdir, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { constants as fsConstants } from "node:fs";
+import { chmod, link, mkdir, open, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
 import * as path from "node:path";
+import { promisify } from "node:util";
+import ini from "ini";
+import { z } from "zod";
 import { getLogger } from "../../util/logger.js";
+const execFileAsync = promisify(execFile);
+/**
+ * Wire schema for the `{ registries: [...] }` envelope returned by
+ * `GET /api/v1/organizations/:orgId/npm-registry`. Used by the client's
+ * defensive parse so a malformed payload routes to `serveStale…` instead
+ * of crashing the install path.
+ *
+ * The refinements (no embedded C0 control chars in any string that flows
+ * into `.npmrc`, scope matches npm's grammar, registry URL is https) are
+ * the CLI's last line of defense against a malicious admin or buggy server.
+ * The server validates the same shape on write, but `.npmrc` synthesis is
+ * security-sensitive enough that we re-validate at read time too.
+ */
+// eslint-disable-next-line no-control-regex
+const noControlChars = (s) => !/[\x00-\x1f]/.test(s);
+// Mirrors the server's npm scope grammar: must start with `@`, then a
+// lowercase letter/digit, then up to 254 lowercase letters/digits/`._-`.
+const NPM_SCOPE_RE = /^@[a-z0-9][a-z0-9._-]{0,254}$/;
+const registryEntrySchema = z.object({
+    id: z.string().uuid(),
+    scope: z
+        .string()
+        .refine(noControlChars, "scope contains a C0 control character")
+        .refine((s) => NPM_SCOPE_RE.test(s), "scope is not a valid npm scope")
+        .nullable(),
+    registryUrl: z
+        .string()
+        .url()
+        .refine(noControlChars, "registryUrl contains a C0 control character")
+        .refine((s) => s.startsWith("https://"), "registryUrl must be https"),
+    // Matches the server's `OrgNpmRegistryDto.token` (see
+    // `packages/server/src/controllers/v1/orgNpmRegistry/handlers.ts`),
+    // which is documented as `string | null` but in practice may also be
+    // omitted from the wire payload entirely on older server builds.
+    // `.nullish()` accepts `null` AND missing/undefined; the transform
+    // coalesces both to `null` so downstream code keeps the canonical
+    // `NpmRegistryEntry.token: string | null` shape and never sees
+    // `undefined`. An absent token is a legitimate "unauthenticated
+    // registry" state, NOT wire-shape drift — treating it as drift would
+    // route through `serveStaleOrUnconfigured` and brick the install
+    // path on orgs whose registry intentionally has no token.
+    token: z
+        .string()
+        .refine(noControlChars, "token contains a C0 control character")
+        .nullish()
+        .transform((v) => v ?? null),
+});
+const registryListSchema = z.object({
+    registries: z.array(registryEntrySchema),
+    /**
+     * Org-level npm policy field from APPS-4250. Optional on the wire because
+     * the server only includes it when the `superblocks.npm-registry.enabled`
+     * LD flag is on; an older server or a flag-off response just omits the
+     * field. Treated as `undefined` everywhere downstream so consumers can
+     * default to "scripts allowed" (today's behaviour) without a special
+     * code path.
+     */
+    npmAllowInstallScripts: z.boolean().optional(),
+});
+/**
+ * Wire envelope every Superblocks server endpoint wraps its JSON response in
+ * (`ResponseDto` in `packages/server/src/dto/response.ts`). We only need
+ * `data` here; `responseMeta` is unused for this endpoint and intentionally
+ * passes through unparsed. The outer `passthrough()` lets future
+ * `responseMeta`-shape drift not break the npm-registry path.
+ */
+const envelopeSchema = z
+    .object({
+    data: z.unknown(),
+})
+    .passthrough();
 /**
  * Scopes whose existing `<scope>:registry=` lines in a project / pod `.npmrc`
  * must survive `writeNpmrc` calls. Shared between AppShell, TemplateRenderer,
@@ -12,123 +88,605 @@ import { getLogger } from "../../util/logger.js";
  */
 export const PRESERVE_NPMRC_SCOPES = ["@superblocksteam"];
 /**
- * Returns true iff the value contains an embedded CR or LF, which would inject
- * additional directives into the rendered `.npmrc`.
+ * Resolves the org `allow_install_scripts` policy from a `prepareForPrivateRegistry`
+ * (or `maybeWriteNpmrcForDir`) result. `false` means "the org has explicitly
+ * disabled npm install scripts" — install entrypoints append `--ignore-scripts`.
+ * `true` or `undefined` (server omitted the field, LD flag off, no client wired
+ * up) keeps today's behaviour.
+ *
+ * Shared by AppShell install entrypoints (shell.ts) and the dev-server startup
+ * install (sdk/cli-replacement/dev.mts) so both paths interpret the policy
+ * identically.
  */
-function hasEmbeddedNewline(value) {
-    return /[\r\n]/.test(value);
+export function shouldIgnoreInstallScripts(result) {
+    return result?.config.allowInstallScripts === false;
 }
 /**
- * Returns a log-safe rendering of a registry URL. Strips userinfo so an
- * operator who accidentally inlined credentials in `SUPERBLOCKS_NPM_REGISTRY`
- * (`https://user:pass@host/...`) doesn't have those credentials surfaced to
- * centralized logging when validation rejects the value. Best-effort: if the
- * input is unparseable we still return a placeholder rather than the raw
- * value.
+ * Translates a list of server-shaped registry entries into the renderable
+ * `NpmRegistryConfig`. Centralised so `writeNpmrc`, tests, and any future
+ * consumer all interpret the wire shape the same way.
+ *
+ * Multiple `scope === null` entries should never happen — the server's
+ * UNIQUE (organization_id, scope) constraint forbids it — but we are
+ * defensive: the FIRST default wins, subsequent ones are logged and
+ * discarded so a server-side bug never silently rotates the default URL
+ * mid-fetch.
+ *
+ * Duplicate scoped entries (same `scope` string) follow the same rule:
+ * first wins.
  */
-function redactRegistryForLog(value) {
-    try {
-        const u = new URL(value);
-        if (u.username || u.password) {
-            u.username = "";
-            u.password = "";
-            return `${u.toString()} (userinfo redacted)`;
+export function registriesToConfig(entries, allowInstallScripts) {
+    if (entries.length === 0) {
+        return {
+            configured: false,
+            ...(allowInstallScripts !== undefined ? { allowInstallScripts } : {}),
+        };
+    }
+    let defaultReg;
+    const scopes = {};
+    for (const entry of entries) {
+        const value = {
+            url: entry.registryUrl,
+            ...(entry.token ? { token: entry.token } : {}),
+        };
+        if (entry.scope === null) {
+            if (defaultReg) {
+                getLogger().warn("[npm-registry] server returned multiple default registry entries; keeping the first", { ignoredId: entry.id });
+                continue;
+            }
+            defaultReg = value;
+        }
+        else {
+            if (scopes[entry.scope]) {
+                getLogger().warn("[npm-registry] server returned multiple entries for the same scope; keeping the first", { scope: entry.scope, ignoredId: entry.id });
+                continue;
+            }
+            scopes[entry.scope] = value;
         }
-        return u.toString();
     }
-    catch {
-        return "<unparseable URL — value redacted>";
+    return {
+        configured: true,
+        ...(defaultReg ? { default: defaultReg } : {}),
+        ...(Object.keys(scopes).length > 0 ? { scopes } : {}),
+        ...(allowInstallScripts !== undefined ? { allowInstallScripts } : {}),
+    };
+}
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+// Deep-frozen so the `return NOT_CONFIGURED` sites can hand back the same
+// reference without risking cross-caller contamination. Mutation attempts
+// (e.g., a future caller doing `result.config.scopes = {...}` to "augment"
+// before forwarding) throw a TypeError in strict mode rather than silently
+// corrupting every subsequent caller for the process lifetime.
+//
+// Used only when the policy field is unknown (LD flag off on the client OR
+// no cache to fall back to). When the policy IS known (e.g. server returned
+// `npmAllowInstallScripts: false` alongside an empty `registries` list), the
+// helper below builds a fresh result so the policy still reaches AppShell.
+const NOT_CONFIGURED = Object.freeze({
+    source: "not-configured",
+    config: Object.freeze({ configured: false }),
+});
+// Same deep-freeze rationale as NOT_CONFIGURED. Returned only when the
+// server is unreachable AND we have no usable cache, so the caller can
+// distinguish "we don't know" from a deliberate `not-configured`
+// observation.
+const UNREACHABLE = Object.freeze({
+    source: "unreachable",
+    config: Object.freeze({ configured: false }),
+});
+/**
+ * Build a "not-configured" result that still carries the org policy when
+ * the server returned one. Falls back to the frozen `NOT_CONFIGURED`
+ * singleton when the policy is unknown so cold-path callers keep allocating
+ * zero objects.
+ *
+ * The result and its `config` are both frozen for the same reason as
+ * `NOT_CONFIGURED`: a downstream caller doing `result.config.scopes = {...}`
+ * to "augment before forwarding" throws a TypeError in strict mode rather
+ * than silently producing a result that doesn't match what we returned.
+ */
+function notConfigured(allowInstallScripts) {
+    if (allowInstallScripts === undefined) {
+        return NOT_CONFIGURED;
     }
+    return Object.freeze({
+        source: "not-configured",
+        config: Object.freeze({ configured: false, allowInstallScripts }),
+    });
 }
 /**
- * Parses the `SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY` truthy-flag value.
+ * Same shape as `notConfigured(policy)` but for the "unreachable" branch:
+ * server didn't respond AND we have no usable cache. Destructive cleanup
+ * paths (the home-npmrc writer in `cli-replacement/dev.mts`) branch on the
+ * `unreachable` discriminator to refuse acting on a transient outage. The
+ * optional `allowInstallScripts` mirrors the `notConfigured` policy
+ * preservation invariant so AppShell still honors a known `--ignore-scripts`
+ * policy during the outage.
  */
-function parseRequireFlag(env) {
-    const raw = env.SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY?.trim().toLowerCase();
-    return raw === "true" || raw === "1" || raw === "yes" || raw === "on";
+function unreachable(allowInstallScripts) {
+    if (allowInstallScripts === undefined) {
+        return UNREACHABLE;
+    }
+    return Object.freeze({
+        source: "unreachable",
+        config: Object.freeze({ configured: false, allowInstallScripts }),
+    });
 }
 /**
- * Reads the npm registry env contract and returns a typed config, or undefined
- * when `SUPERBLOCKS_NPM_REGISTRY` is unset or invalid (preserves SaaS / local
- * behavior). Invalid values are logged as warnings and treated as unset rather
- * than half-broken (avoids landing a `.npmrc` with a malformed `registry=`
- * line and no `_authToken=`).
- *
- * Env contract:
- * - SUPERBLOCKS_NPM_REGISTRY: full registry URL
- * - SUPERBLOCKS_NPM_REGISTRY_TOKEN: optional auth token
- * - SUPERBLOCKS_NPM_REGISTRY_SCOPES_JSON: optional JSON map of scope -> URL
- * - SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY: opt-in strict mode (default off)
+ * Fetches per-org npm registry configuration from the server, caching the
+ * result in-memory with a short TTL. Designed so callers do not have to
+ * think about the LaunchDarkly flag, JWT lifecycle, or transient server
+ * outages — they just `await client.getConfig()` and get back a renderable
+ * shape (or "not configured").
+ *
+ * Lifecycle invariants (see APPS-4230 scope):
+ *
+ *   1. **Flag off → short-circuit**: returns `{ configured: false }` with
+ *      no network I/O. Lets us dark-ship LinkedIn first without hammering
+ *      the API for the rest of the fleet.
+ *   2. **Cache hit within TTL → no fetch**: avoids per-install round-trips
+ *      against the server.
+ *   3. **401 → await `refreshJwt` then retry once with a fresh
+ *      `getJwt()` read**: any push-based JWT refresh (auth-hot-reload)
+ *      that landed between the original request and the retry is picked
+ *      up. The cache is preserved across the retry so a failed retry
+ *      can still fall back to last-known-good. Two disjoint failure
+ *      modes:
+ *        - The retry itself returns 401 → hard throw. We deliberately do
+ *          not keep retrying because the only way a freshly-read JWT also
+ *          401s is a true re-auth failure.
+ *        - `refreshJwt` itself throws or times out (e.g. the push channel
+ *          hung) → route through `serveStaleOrUnconfigured` (same as a 5xx
+ *          / network outage). A flaky refresh channel must not crash the
+ *          install path, and we never reach the second `attempt()`.
+ *   4. **Other 4xx (403/400/…) → clear the cache and throw**: these are
+ *      deliberate denials (RBAC revocation, malformed request), not
+ *      transient outages. Serving stale would extend the revocation
+ *      window beyond the cache TTL. The error propagates to the caller
+ *      (typically `AppShell` / `TemplateRenderer`), which decides
+ *      whether to fail the install or fall back to public npm.
+ *   5. **5xx or network unreachable + cached value → return cache +
+ *      `logger.warn`**: install workflows continue against the
+ *      last-known-good registry while we surface the outage; strictly
+ *      better than falling back to `registry.npmjs.org` mid-deploy.
+ *   6. **5xx or network unreachable + no usable cache → return
+ *      `source: "unreachable"` with `{ configured: false }`**: cold start
+ *      or only an empty-list cache. `config.configured: false` so
+ *      write-side consumers continue to no-op, but the distinct source
+ *      keeps destructive cleanup paths (home-npmrc unlink) from acting on
+ *      a transient outage.
+ *
+ * The class is intentionally a thin wrapper around a single Map cell — the
+ * cache key is `(organizationId)` since one client serves one org. Sharing
+ * one client across orgs would require per-org cache keys; we don't do
+ * that today because the dev-server pod is single-tenant.
  */
-export function getNpmRegistryConfig(env = process.env) {
-    const url = env.SUPERBLOCKS_NPM_REGISTRY?.trim();
-    if (!url) {
-        // The public name `SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY` promises strict
-        // mode; until the enforcement branch (#17) lands, surface a warning when
-        // an operator opts in but forgot to also set the registry URL — otherwise
-        // they silently fall back to public npm and assume they're protected.
-        if (parseRequireFlag(env)) {
-            getLogger().warn("[npm-registry] SUPERBLOCKS_REQUIRE_PRIVATE_REGISTRY is set but " +
-                "SUPERBLOCKS_NPM_REGISTRY is unset; falling back to default " +
-                "registry-resolution. Strict-mode enforcement is deferred to a " +
-                "follow-up; set SUPERBLOCKS_NPM_REGISTRY to take effect today.");
-        }
-        return;
+export class NpmRegistryClient {
+    deps;
+    /**
+     * Last successful fetch + when it landed. Source of both the TTL check
+     * and the last-known-good fallback. We deliberately store the entries as
+     * received (not the rendered `NpmRegistryConfig`) so future readers can
+     * apply different render policies without a re-fetch.
+     *
+     * `npmAllowInstallScripts` rides alongside because the server returns it
+     * on the same envelope and AppShell wants the same TTL/fallback semantics
+     * for both. `undefined` here means the server omitted the field (LD flag
+     * off on the server side, or older server); we propagate that as
+     * `allowInstallScripts: undefined` rather than defaulting to `true` so
+     * the consumer can distinguish "policy known, scripts allowed" from
+     * "policy unknown".
+     */
+    cache;
+    /**
+     * Inflight `fetchWithRefresh()` promise, if any. Used to deduplicate
+     * concurrent `getConfig()` callers during a cache miss (or stale-after-
+     * TTL re-fetch): rather than firing N network requests for N callers
+     * we share the single in-flight request. Cleared in a `.finally()` so a
+     * resolved or rejected fetch never sticks around.
+     *
+     * Without this, a burst of installs that all hit cold cache would race
+     * to the server, the first one's 401 would clear the cache for itself
+     * before the others observe their own 401s — and the others would
+     * then have no last-known-good to fall back to.
+     */
+    inflight;
+    /**
+     * Last `npmAllowInstallScripts` value observed from a successful server
+     * response, retained across hard-fail cache invalidations (refreshJwt
+     * rejection, double-401, other 4xx). Registry credentials and the
+     * security policy live on the same envelope but have different
+     * security semantics: serving stale credentials to a revoked caller
+     * extends a deliberate denial, but dropping a known `false` policy
+     * silently weakens `--ignore-scripts` enforcement — strictly the
+     * wrong direction. So `this.cache` is cleared on hard-fail (revoke
+     * stale credentials), but this field survives so the next call's
+     * fall-through `serveStaleOrUnconfigured` still propagates the
+     * org's policy to AppShell.
+     */
+    lastKnownPolicy;
+    constructor(deps) {
+        this.deps = {
+            isFlagEnabled: deps.isFlagEnabled,
+            getJwt: deps.getJwt,
+            refreshJwt: deps.refreshJwt,
+            organizationId: deps.organizationId,
+            baseUrl: deps.baseUrl,
+            fetch: deps.fetch ?? globalThis.fetch,
+            ttlMs: deps.ttlMs ?? DEFAULT_TTL_MS,
+            now: deps.now ?? Date.now,
+            lastKnownPolicyStore: deps.lastKnownPolicyStore,
+        };
     }
-    if (hasEmbeddedNewline(url)) {
-        getLogger().warn("[npm-registry] SUPERBLOCKS_NPM_REGISTRY contains a newline; ignoring");
-        return;
+    /**
+     * Clears the in-memory cache so the next `getConfig()` re-fetches from
+     * the server. Called by AppShell install retry when
+     * `registry_auth_failed` indicates a stale Artifactory token.
+     *
+     * `lastKnownPolicy` survives invalidation (same as the auth-failure
+     * branches in `fetchWithRefresh`) so `--ignore-scripts` enforcement
+     * is not weakened during the re-fetch.
+     */
+    invalidateCache() {
+        this.cache = undefined;
     }
-    // Validate the URL upfront so we never emit a half-broken .npmrc (e.g.
-    // `registry=` line with no matching `_authToken=`). Also rejects userinfo
-    // (`user:pass@host`) — tokens belong on a `_authToken=` line, never in the
-    // URL itself; URL-embedded credentials end up in HTTP request logs.
-    if (!toNpmAuthOrigin(url)) {
-        getLogger().warn("[npm-registry] SUPERBLOCKS_NPM_REGISTRY is not a valid registry URL " +
-            "(must be parseable and must not contain user:pass@ userinfo); ignoring", { url: redactRegistryForLog(url) });
-        return;
+    /**
+     * Persist the "ever configured" marker, AWAITED so the write is durable
+     * before the caller hands back a `configured` / `stale` resolution. Used
+     * on every such resolution so a subsequent server outage can fail closed
+     * instead of silently resolving through public npm.
+     *
+     * Awaited (not fire-and-forget) because the marker must be on disk before
+     * `getConfig()` returns: a crash in the gap between returning `configured`
+     * and an un-awaited write landing would lose the marker and silently break
+     * the "once configured, always fail-closed on unreachable" invariant. The
+     * write stays async (`fs/promises`, per the ai-service no-sync-fs rule);
+     * the disk store guards itself so the write happens at most once per
+     * process (see `createDiskRegistryPolicyStore`), keeping the awaited write
+     * off the hot path after the first configured resolution.
+     *
+     * Logs a warning on write failure but never propagates the error: a broken
+     * store is a strict superset of today's no-marker behaviour, and the
+     * install path must stay healthy when disk is full or the marker directory
+     * is unwritable.
+     */
+    async markPolicyConfigured() {
+        const store = this.deps.lastKnownPolicyStore;
+        if (!store) {
+            return;
+        }
+        try {
+            await store.markConfigured();
+        }
+        catch (err) {
+            getLogger().warn("[npm-registry] lastKnownPolicyStore.markConfigured() failed; ignoring", {
+                orgId: this.deps.organizationId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
     }
-    let token = env.SUPERBLOCKS_NPM_REGISTRY_TOKEN?.trim() || undefined;
-    if (token && hasEmbeddedNewline(token)) {
-        getLogger().warn("[npm-registry] SUPERBLOCKS_NPM_REGISTRY_TOKEN contains a newline; ignoring token");
-        token = undefined;
+    /**
+     * Read the disk-backed marker that AppShell uses to decide whether to
+     * fail closed on `unreachable`. Treats a read failure as `false` so a
+     * transient store IO error preserves current behaviour (proceed) rather
+     * than degrading to a fail-closed install.
+     */
+    async readEverConfigured() {
+        const store = this.deps.lastKnownPolicyStore;
+        if (!store) {
+            return undefined;
+        }
+        try {
+            return await store.hasEverBeenConfigured();
+        }
+        catch (err) {
+            getLogger().warn("[npm-registry] lastKnownPolicyStore.hasEverBeenConfigured() failed; treating as false", {
+                orgId: this.deps.organizationId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return false;
+        }
     }
-    const require = parseRequireFlag(env);
-    let scopes;
-    const scopesJson = env.SUPERBLOCKS_NPM_REGISTRY_SCOPES_JSON?.trim();
-    if (scopesJson) {
+    /**
+     * Resolve the current npm registry configuration for the active org. See
+     * the class docstring for the full state machine.
+     */
+    async getConfig() {
+        if (!this.deps.isFlagEnabled()) {
+            // Short-circuit BEFORE inspecting the cache: a flag flip to "off"
+            // must not keep serving from a previously-fetched config. The
+            // ticket explicitly calls this out ("Flag off → return
+            // {configured: false} immediately, no server call").
+            return NOT_CONFIGURED;
+        }
+        const now = this.deps.now();
+        if (this.cache && now - this.cache.fetchedAt < this.deps.ttlMs) {
+            // A cached empty list (from a prior 404 or `registries: []` response)
+            // must surface as `not-configured` on every hit within the TTL, not
+            // `configured` with `config.configured: false`. The discriminator's
+            // "configured" branch is documented as "at least one registry row
+            // exists" — preserving that invariant matters for callers branching
+            // on `source` for observability. We still surface any cached policy
+            // alongside the not-configured result so AppShell can honor
+            // `--ignore-scripts` even when there are no registry rows.
+            if (this.cache.entries.length === 0) {
+                return notConfigured(this.cache.npmAllowInstallScripts);
+            }
+            await this.markPolicyConfigured();
+            return {
+                source: "configured",
+                config: registriesToConfig(this.cache.entries, this.cache.npmAllowInstallScripts),
+            };
+        }
+        // Deduplicate concurrent cache-miss callers onto a single network
+        // request so we don't multiply 401-refresh storms or lose last-known-
+        // good fallback for racing callers.
+        if (this.inflight) {
+            return this.inflight;
+        }
+        const pending = this.fetchWithRefresh().finally(() => {
+            // Always clear inflight on resolve OR reject so a transient error
+            // doesn't pin the slot and starve subsequent callers.
+            if (this.inflight === pending) {
+                this.inflight = undefined;
+            }
+        });
+        this.inflight = pending;
+        return pending;
+    }
+    async fetchWithRefresh() {
+        let response;
         try {
-            const parsed = JSON.parse(scopesJson);
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                scopes = {};
-                for (const [scope, scopeUrl] of Object.entries(parsed)) {
-                    if (typeof scopeUrl !== "string") {
-                        continue;
-                    }
-                    // Validate both the scope key and the scope URL value for embedded
-                    // newlines — a key containing `\n` (valid in JSON strings) would
-                    // inject an extra line into the rendered `.npmrc` (e.g.
-                    // `"@x\n_authToken=stolen"`). Mirror the existing URL-value check.
-                    if (hasEmbeddedNewline(scope)) {
-                        getLogger().warn("[npm-registry] SUPERBLOCKS_NPM_REGISTRY_SCOPES_JSON scope key contains a newline; ignoring entry");
-                        continue;
-                    }
-                    const trimmed = scopeUrl.trim();
-                    if (trimmed === "" || hasEmbeddedNewline(trimmed)) {
-                        continue;
-                    }
-                    scopes[scope] = trimmed;
+            response = await this.attempt();
+        }
+        catch (err) {
+            return this.serveStaleOrUnconfigured(err);
+        }
+        if (response.status === 401) {
+            // Do NOT clear `this.cache` here: if the retry fails,
+            // `serveStaleOrUnconfigured` still needs the last-known-good
+            // entries to fall back to. Concurrent callers are serialised on
+            // `this.inflight`, so they won't observe a stale value during the
+            // retry window.
+            //
+            // Await `refreshJwt` (if wired) so the retry has a fair chance
+            // of seeing a freshly-rotated token. A refresh-channel error
+            // combined with a 401 from the registry endpoint is ambiguous —
+            // it can be a transient outage OR a terminal revocation
+            // (refresh token rejected, account disabled). We cannot tell
+            // from out here, and serving last-known-good in the revocation
+            // case would let a revoked caller continue installing from a
+            // private registry until TTL expiry. Treat refresh failure as a
+            // hard fail: clear the cache and surface the error, mirroring
+            // the deliberate-denial 4xx branch below.
+            if (this.deps.refreshJwt) {
+                try {
+                    await this.deps.refreshJwt();
                 }
-                if (Object.keys(scopes).length === 0) {
-                    scopes = undefined;
+                catch (err) {
+                    this.cache = undefined;
+                    const refreshFailError = new Error(`[npm-registry] refreshJwt failed after HTTP 401 from the npm registry endpoint: ${err instanceof Error ? err.message : String(err)}`);
+                    getLogger().error(`[npm-registry] hard-fail: refreshJwt rejected after HTTP 401 (org ${this.deps.organizationId}); cache cleared`, {
+                        error: {
+                            kind: "NpmRegistryRefreshFail",
+                            message: refreshFailError.message,
+                        },
+                    });
+                    throw refreshFailError;
                 }
             }
+            try {
+                response = await this.attempt();
+            }
+            catch (err) {
+                return this.serveStaleOrUnconfigured(err);
+            }
+            if (response.status === 401) {
+                // A second 401 after a successful refreshJwt is stronger evidence
+                // of revocation than either the refreshJwt-rejection branch above
+                // or the deliberate-denial 4xx branch below: the refresh channel
+                // worked, but the freshly-issued JWT is still rejected. Clear the
+                // cache so a subsequent 5xx/network error cannot fall back through
+                // `serveStaleOrUnconfigured` and serve last-known-good config to
+                // a potentially-revoked user until TTL expiry. We surface this
+                // rather than swallowing it because "silently fall back to public
+                // npm" is precisely the failure mode this whole feature exists
+                // to prevent.
+                this.cache = undefined;
+                const doubleAuthFailError = new Error("[npm-registry] re-authenticated and still received HTTP 401 from the npm registry endpoint");
+                getLogger().error(`[npm-registry] hard-fail: HTTP 401 persisted after refreshJwt (org ${this.deps.organizationId}); cache cleared`, {
+                    error: {
+                        kind: "NpmRegistryDoubleAuthFail",
+                        message: doubleAuthFailError.message,
+                    },
+                });
+                throw doubleAuthFailError;
+            }
         }
-        catch (error) {
-            getLogger().warn("[npm-registry] Failed to parse SUPERBLOCKS_NPM_REGISTRY_SCOPES_JSON; ignoring", { error: error instanceof Error ? error.message : String(error) });
+        if (response.status === 404) {
+            // The route exists but the org has no registry rows (or the
+            // sibling endpoint returned 404 for a transient reason — deploy
+            // window, route mis-mount, brief org-deactivation race). Treat
+            // the same as an empty list response — `{ configured: false }`.
+            // We still cache "empty" so we don't poll the 404 path on every
+            // install.
+            //
+            // We preserve any previously-observed `npmAllowInstallScripts`
+            // policy rather than overwriting it with `undefined`: a transient
+            // 404 against a freshly-deployed server (or an envoy mis-route)
+            // would otherwise silently disable an org's `--ignore-scripts`
+            // enforcement for the rest of the TTL window. The 404 payload
+            // doesn't carry a fresh policy, but a previously-observed policy
+            // is the best estimate we have until the next successful fetch.
+            //
+            // Fall back to `lastKnownPolicy` when `this.cache` itself was
+            // hard-cleared by an earlier auth-failure branch — the policy
+            // survives independently of the registry credentials it rode in
+            // with, and reading from cache alone would clobber it back to
+            // `undefined` here.
+            const preservedPolicy = this.cache?.npmAllowInstallScripts ?? this.lastKnownPolicy;
+            this.cache = {
+                entries: [],
+                npmAllowInstallScripts: preservedPolicy,
+                fetchedAt: this.deps.now(),
+            };
+            this.lastKnownPolicy = preservedPolicy;
+            return notConfigured(preservedPolicy);
+        }
+        if (response.status >= 400 &&
+            response.status < 500 &&
+            response.status !== 401 &&
+            response.status !== 404) {
+            // Other 4xx ("the request is bad" or "you specifically can't do
+            // this") are deliberate denials, not transient outages. Examples:
+            //   - 403 after org RBAC permission revocation
+            //   - 400 from a malformed Authorization header
+            // Serving stale here would let a revoked-access install run with
+            // a cached registry token until TTL expiry — exactly the staleness
+            // window we want to avoid. Clear the cache and surface the error
+            // so the caller decides; the inflight slot is cleared by the
+            // outer `.finally()` so a subsequent call can re-attempt.
+            this.cache = undefined;
+            const hardFailError = new Error(`[npm-registry] server returned HTTP ${response.status} from the npm registry endpoint`);
+            getLogger().error(`[npm-registry] hard-fail HTTP ${response.status} from npm registry endpoint (org ${this.deps.organizationId}); cache cleared`, {
+                error: {
+                    kind: "NpmRegistryHardFail",
+                    message: hardFailError.message,
+                },
+            });
+            throw hardFailError;
+        }
+        if (!response.ok) {
+            // 5xx is treated as a transient outage. Last-known-good if we
+            // have one, otherwise `not-configured`.
+            return this.serveStaleOrUnconfigured(new Error(`[npm-registry] server returned HTTP ${response.status} from the npm registry endpoint`));
+        }
+        // Read the body AND unwrap the standard Superblocks `ResponseDto`
+        // envelope (`{ data, responseMeta }`) the server wraps every JSON
+        // response in. The UI client uses `callServer` (which delegates to
+        // `unwrapResponseDto` in `@superblocksteam/shared`) for the same shape;
+        // here we keep raw `fetch` (preserves the DI surface the test harness
+        // mocks) and unwrap inline so the registry-payload schema below mirrors
+        // the inner shape, not the wire envelope. JSON-parse failures and
+        // envelope-shape failures both route to `serveStale…` — single try.
+        let payload;
+        try {
+            const body = await response.json();
+            const envelopeParse = envelopeSchema.safeParse(body);
+            if (!envelopeParse.success) {
+                const envelopeError = new Error(`[npm-registry] server returned a payload that did not match the expected ResponseDto envelope (org ${this.deps.organizationId}): ${JSON.stringify(envelopeParse.error.issues)}`);
+                getLogger().error(envelopeError.message, {
+                    error: {
+                        kind: "NpmRegistryEnvelopeParseFailed",
+                        message: envelopeError.message,
+                    },
+                });
+                throw envelopeError;
+            }
+            payload = envelopeParse.data.data;
+        }
+        catch (err) {
+            return this.serveStaleOrUnconfigured(err);
+        }
+        const parsed = registryListSchema.safeParse(payload);
+        if (!parsed.success) {
+            // Log schema issues at error level (distinct from the generic
+            // serveStale warn) so a malformed payload is visible in the absence
+            // of a network outage — most likely a server-side validation bug
+            // or a hostile push. The Zod issue list is folded into the message
+            // because the `error` logger only accepts `ErrorMeta` shape.
+            const schemaError = new Error(`[npm-registry] server returned a payload that did not match the expected { registries: [...] } shape (org ${this.deps.organizationId}): ${JSON.stringify(parsed.error.issues)}`);
+            getLogger().error(schemaError.message, {
+                error: {
+                    kind: "NpmRegistrySchemaParseFailed",
+                    message: schemaError.message,
+                },
+            });
+            return this.serveStaleOrUnconfigured(schemaError);
+        }
+        const entries = parsed.data.registries;
+        const npmAllowInstallScripts = parsed.data.npmAllowInstallScripts;
+        this.cache = {
+            entries,
+            npmAllowInstallScripts,
+            fetchedAt: this.deps.now(),
+        };
+        this.lastKnownPolicy = npmAllowInstallScripts;
+        if (entries.length === 0) {
+            return notConfigured(npmAllowInstallScripts);
+        }
+        await this.markPolicyConfigured();
+        return {
+            source: "configured",
+            config: registriesToConfig(entries, npmAllowInstallScripts),
+        };
+    }
+    /**
+     * One full fetch attempt with the current JWT. Throws on getJwt failure
+     * OR network failure so the caller's single try/catch handles both.
+     */
+    async attempt() {
+        const jwt = await this.deps.getJwt();
+        const base = this.deps.baseUrl.replace(/\/$/, "");
+        const url = `${base}/api/v1/organizations/${encodeURIComponent(this.deps.organizationId)}/npm-registry`;
+        return await this.deps.fetch(url, {
+            method: "GET",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${jwt}`,
+            },
+        });
+    }
+    async serveStaleOrUnconfigured(error) {
+        if (this.cache && this.cache.entries.length > 0) {
+            const ageMs = this.deps.now() - this.cache.fetchedAt;
+            getLogger().warn("[npm-registry] server unreachable; serving last-known-good config", {
+                ageMs,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // APPS-4370: stale serves a known-configured org, so refresh the
+            // disk marker too. A long outage that spans a pod recycle would
+            // otherwise lose the signal: the next cold-boot would see `unreachable`
+            // with no marker and proceed instead of failing closed.
+            await this.markPolicyConfigured();
+            return {
+                source: "stale",
+                config: registriesToConfig(this.cache.entries, this.cache.npmAllowInstallScripts),
+            };
         }
+        // No usable cache: either nothing was ever fetched successfully (cold
+        // start) or the only successful fetch returned an empty list. Both
+        // mean we don't actually know the org's current registry state, so
+        // we surface `unreachable` rather than `not-configured`. Consumers
+        // with destructive cleanup paths (e.g. the home-npmrc writer
+        // unlinking a previously-written `~/.npmrc`) need that distinction to
+        // avoid acting on a transient outage; read-only consumers branch on
+        // `config.configured` and continue to no-op safely either way.
+        //
+        // A cached `npmAllowInstallScripts` policy IS useful and survives the
+        // outage: AppShell still honors a known `--ignore-scripts` policy
+        // when the server is down. Falls back to `lastKnownPolicy` when
+        // `this.cache` itself was hard-cleared by an auth-failure branch
+        // above — the policy survives independently of the registry
+        // credentials it rode in with.
+        getLogger().warn("[npm-registry] server unreachable and no usable cached config; treating as unreachable", { error: error instanceof Error ? error.message : String(error) });
+        const base = unreachable(this.cache?.npmAllowInstallScripts ?? this.lastKnownPolicy);
+        // APPS-4370: consult the disk-backed marker so AppShell can decide
+        // whether to fail closed. Only attach the field when a store is
+        // wired in — `undefined` is the documented "no opinion" signal.
+        const everConfigured = await this.readEverConfigured();
+        if (everConfigured === undefined) {
+            return base;
+        }
+        // `base` may be the frozen UNREACHABLE singleton; build a fresh
+        // object so adding `everConfigured` doesn't try to mutate a frozen
+        // value (TypeError in strict mode).
+        return Object.freeze({
+            source: "unreachable",
+            config: base.config,
+            everConfigured,
+        });
     }
-    return { url, token, scopes, require };
 }
 /**
  * Extracts the host portion of a registry URL for use in npm auth lines, e.g.
@@ -165,28 +723,68 @@ function normalizeRegistryUrl(registryUrl) {
 /**
  * Renders the npm registry config to an `.npmrc` file at `targetPath`.
  *
+ * Uses `ini.stringify` (the same library `@npmcli/config` uses to read and
+ * write `.npmrc`) so the file is guaranteed to round-trip through
+ * `ini.parse`. This handles value-quoting for `=`, `\r`, `\n`, leading `[`,
+ * leading/trailing whitespace, and escapes `;` / `#` so they're not treated
+ * as comments.
+ *
+ * Validation NOT covered by `ini`:
+ *   - `noControlChars` Zod refinement: `ini.safe` JSON-quotes `\r`/`\n`
+ *     rather than rejecting them, and accepts other C0 control bytes
+ *     (`\x00..\x1f`) unchanged — so we reject the entire C0 range at the
+ *     wire-schema layer instead.
+ *   - Scope grammar (`@scope` must match npm's regex): `@npmcli/config`
+ *     does not validate scope names.
+ *   - https-only registry URLs: npm itself accepts http.
+ *
  * When `preserveScopeLines` is provided, any existing `<scope>:registry=`
- * lines for those scopes are preserved verbatim (so EE-baked
+ * keys for those scopes are preserved (so EE-baked
  * `@superblocksteam:registry=https://npm.pkg.github.com/` survives) UNLESS
- * the same scope is explicitly overridden in `config.scopes`.
+ * the same scope is explicitly overridden in `config.scopes`. The
+ * preserved value is read via `ini.parse` from the existing file, so
+ * `ini`'s own quoting rules apply (rather than our older line-grep that
+ * could mis-handle quoted values).
  *
  * Idempotent: rewrites the file in full each call. Writes are atomic (tmp +
  * rename) and the file mode is restricted to 0600 because the file may carry
  * an auth token.
+ *
+ * Requires `config.configured === true` OR `config.allowInstallScripts === false`
+ * (so the writer can emit a policy-only `.npmrc` with just `ignore-scripts=true`
+ * even when no registry rows are configured). A scoped-only config (no `default`
+ * entry) is valid — only scope `:registry=` lines are emitted, and unscoped
+ * packages fall through to public npm. This matches the server contract
+ * (the `(org, scope)` unique constraint allows scoped-only rows) and is
+ * the right shape for customers who only want to override one `@scope`
+ * without redirecting the rest of npm.
  */
 export async function writeNpmrc(targetPath, config, options = {}) {
+    const needsIgnoreScripts = config.allowInstallScripts === false;
+    if (!config.configured && !needsIgnoreScripts) {
+        throw new Error("[npm-registry] writeNpmrc requires a configured config");
+    }
+    const hasDefault = !!config.default;
+    const hasScopes = !!config.scopes && Object.keys(config.scopes).length > 0;
+    if (!hasDefault && !hasScopes && !needsIgnoreScripts) {
+        throw new Error("[npm-registry] writeNpmrc requires at least one registry entry (default or scoped)");
+    }
+    // Flat key -> value map. `.npmrc` uses no `ini` sections at the registry
+    // layer (all keys are top-level), so `ini.stringify` on a flat object
+    // produces the exact wire format npm expects.
+    const obj = {};
     const preserveScopes = options.preserveScopeLines ?? [];
-    // Map of scope -> verbatim line, so we both dedup correctly and preserve the
-    // exact bytes (whitespace, trailing comments) the operator wrote.
-    const preservedScopeLines = new Map();
     if (preserveScopes.length > 0) {
-        let existing = "";
+        let existing;
         try {
             existing = await readFile(targetPath, "utf-8");
         }
         catch (error) {
-            // ENOENT is the expected case (no pre-existing .npmrc). EACCES / EIO /
-            // EBUSY are not — surface them so we don't silently drop a load-bearing
+            // ENOENT is the expected case on first write — every other code
+            // (EACCES, EISDIR, EIO) we surface as a warning rather than throw
+            // because preserve-scope is a best-effort fallback and we'd rather
+            // emit a fresh `.npmrc` than fail the whole install path. The
+            // tradeoff: a transient read error could silently lose a baked
             // `@superblocksteam:registry=` line (the exact failure class APPS-2053
             // was meant to prevent).
             const code = error?.code;
@@ -199,80 +797,1121 @@ export async function writeNpmrc(targetPath, config, options = {}) {
             }
         }
         if (existing) {
-            const lines = existing.split(/\r?\n/);
+            // `ini.parse` skips lines it cannot decode rather than throwing
+            // (CRLF artifacts, partial writes, hand-edits with stray bytes —
+            // see ini@6 `decode`'s regex-or-continue loop). Guard with try/catch
+            // for future versions that may throw, and treat any unrecognised
+            // result as "no preserved value" — but warn so an operator can repair
+            // a malformed `.npmrc` instead of silently shipping without the
+            // EE-baked `@superblocksteam:registry=` line.
+            let parsedExisting = {};
+            try {
+                parsedExisting = ini.parse(existing);
+            }
+            catch (err) {
+                getLogger().warn("[npm-registry] failed to parse existing .npmrc for scope preservation; proceeding without preserve", {
+                    path: targetPath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
             for (const scope of preserveScopes) {
-                // Skip preservation if config explicitly overrides this scope.
+                // Skip preservation if config explicitly overrides this scope —
+                // the override will be written below and we don't want to emit
+                // two `<scope>:registry=` lines (or have the preserved value
+                // shadow the explicit one). The override-wins symmetry also
+                // applies to the auth-family lines for the old origin: dropping
+                // the registry line while keeping a `//old-origin/:_authToken=`
+                // around would leave a dangling secret pointed at no registry
+                // entry in the rendered file.
                 if (config.scopes && config.scopes[scope]) {
                     continue;
                 }
-                const prefix = `${scope}:registry=`;
-                for (const line of lines) {
-                    const trimmed = line.trim();
-                    if (trimmed.startsWith(prefix)) {
-                        preservedScopeLines.set(scope, trimmed);
-                        break;
+                const key = `${scope}:registry`;
+                const value = parsedExisting[key];
+                if (typeof value === "string") {
+                    obj[key] = value;
+                    // Also preserve every auth-family key keyed on the same
+                    // `//<origin>/` prefix as the preserved registry URL. Without
+                    // this, EE-baked `.npmrc` files that ship both
+                    // `@superblocksteam:registry=https://npm.pkg.github.com/` AND
+                    // `//npm.pkg.github.com/:_authToken=<ghpr-token>` lose the
+                    // token on the first `writeNpmrc` call, and every
+                    // `@superblocksteam/*` install 401s against GHPR (APPS-4300).
+                    //
+                    // npm/pnpm support multiple auth shapes against the same
+                    // origin: bearer (`_authToken`), Basic (`_password` +
+                    // `username` + `email`), and the legacy base64 (`_auth`).
+                    // We preserve all of them so a future EE image change that
+                    // swaps from bearer to Basic doesn't silently regress to the
+                    // same failure mode.
+                    //
+                    // `always-auth` is deliberately NOT preserved: npm removed it
+                    // as a recognized key in npm 7+, and npm 11 (the dev-server's
+                    // pinned version) emits `npm warn Unknown user config
+                    // "always-auth" … This will stop working in the next major
+                    // version of npm` on every invocation that reads it — auth
+                    // still attaches from the sibling `_authToken`, so carrying it
+                    // forward is a no-op that only generates stderr noise today and
+                    // risks a hard error once we move to npm 12. Dropping it from
+                    // the preserve set means a customer `.npmrc` that happens to
+                    // carry `//origin/:always-auth` simply loses a dead key (APPS-4430).
+                    //
+                    // Each `parsedExisting[copyKey]` returns the same `unknown`
+                    // shape as the registry line above; only string values are
+                    // safe to round-trip back through `ini.stringify`. Non-string
+                    // values follow the same drop+warn handling.
+                    const preservedAuthOrigin = toNpmAuthOrigin(value);
+                    if (preservedAuthOrigin) {
+                        const authFamilyKeys = [
+                            "_authToken",
+                            "_password",
+                            "username",
+                            "email",
+                            "_auth",
+                        ];
+                        for (const authKey of authFamilyKeys) {
+                            const copyKey = `${preservedAuthOrigin}:${authKey}`;
+                            const authValue = parsedExisting[copyKey];
+                            // `ini.parse` coerces a bare `true`/`false`/numeric value to
+                            // its JS primitive equivalent. The auth-family keys above are
+                            // all string-valued, but coerce back to a string defensively
+                            // so `ini.stringify` emits a valid line (it accepts strings,
+                            // booleans, and numbers, but our internal `obj` map is typed
+                            // `Record<string, string>` for the registry/auth lines
+                            // elsewhere in this writer, so the cast is contained).
+                            if (typeof authValue === "string" ||
+                                typeof authValue === "boolean" ||
+                                typeof authValue === "number") {
+                                obj[copyKey] = String(authValue);
+                            }
+                            else if (authValue !== undefined) {
+                                getLogger().warn("[npm-registry] preserve-scope auth-family key parsed to unsupported type; dropping", {
+                                    path: targetPath,
+                                    scope,
+                                    authKey,
+                                    valueType: typeof authValue,
+                                });
+                            }
+                        }
                     }
                 }
+                else if (value !== undefined) {
+                    // Key parsed but value is not a string — e.g. a bare key (`true`),
+                    // a section header above it, or a quoted value whose `JSON.parse`
+                    // failed inside `ini`. We're about to silently drop the preserve
+                    // target, so surface so the operator can repair the file.
+                    getLogger().warn("[npm-registry] preserve-scope key parsed to non-string; dropping", {
+                        path: targetPath,
+                        scope,
+                        valueType: typeof value,
+                    });
+                }
+                // value === undefined is the normal case when the existing .npmrc
+                // simply doesn't list this scope — silent on that.
             }
         }
     }
-    const normalizedUrl = normalizeRegistryUrl(config.url);
-    const lines = [];
-    lines.push(`registry=${normalizedUrl}`);
-    const authOrigin = toNpmAuthOrigin(normalizedUrl);
-    if (config.token && authOrigin) {
-        lines.push(`${authOrigin}:_authToken=${config.token}`);
+    if (config.default) {
+        const normalizedDefaultUrl = normalizeRegistryUrl(config.default.url);
+        obj["registry"] = normalizedDefaultUrl;
+        const defaultAuthOrigin = toNpmAuthOrigin(normalizedDefaultUrl);
+        if (config.default.token && defaultAuthOrigin) {
+            obj[`${defaultAuthOrigin}:_authToken`] = config.default.token;
+        }
     }
     if (config.scopes) {
-        for (const [scope, scopeUrl] of Object.entries(config.scopes)) {
-            lines.push(`${scope}:registry=${scopeUrl}`);
-            // Explicit scope override wins; drop the preserved line for the same
-            // scope so we don't emit two `<scope>:registry=` lines.
-            preservedScopeLines.delete(scope);
+        for (const [scope, scopedReg] of Object.entries(config.scopes)) {
+            const normalizedScopeUrl = normalizeRegistryUrl(scopedReg.url);
+            obj[`${scope}:registry`] = normalizedScopeUrl;
+            const scopeAuthOrigin = toNpmAuthOrigin(normalizedScopeUrl);
+            if (scopedReg.token && scopeAuthOrigin) {
+                obj[`${scopeAuthOrigin}:_authToken`] = scopedReg.token;
+            }
         }
     }
-    for (const line of preservedScopeLines.values()) {
-        lines.push(line);
+    // Bake the org's ignore-scripts policy into the rendered `.npmrc` so any
+    // npm/pnpm invocation in this directory (or `$HOME`) honours the policy
+    // regardless of whether it was launched by AppShell. Covers tools like
+    // patch-package, husky, simple-git-hooks, and ad-hoc `bash npm install`.
+    if (needsIgnoreScripts) {
+        obj["ignore-scripts"] = "true";
+    }
+    // `ini.stringify` returns a trailing-newline-terminated string. Trim and
+    // re-add a single `\n` so the file is normalised regardless of the
+    // version of `ini`.
+    const body = `${ini.stringify(obj).trim()}\n`;
+    let content = body;
+    if (options.header !== undefined) {
+        if (/[\r\n]/.test(options.header)) {
+            throw new Error("[npm-registry] writeNpmrc options.header must not contain newlines");
+        }
+        content = `; ${options.header}\n${body}`;
     }
-    const content = lines.join("\n") + "\n";
+    const mode = options.mode ?? 0o600;
     await mkdir(path.dirname(targetPath), { recursive: true });
     // Atomic write: render to a sibling tmp file with restrictive perms, then
     // rename. Avoids leaving a partial/empty .npmrc on crash mid-write, and
     // narrows the window where the token might be readable at the default umask.
+    // The atomic rename replaces the target file's inode regardless of the
+    // target's current mode (rename is governed by parent-dir perms), so callers
+    // that pass a write-stripped `mode` (e.g. 0o400) can still rewrite the file
+    // on subsequent syncs.
+    //
+    // We write the tmp file at 0o600 (owner-writable) first so any internal
+    // mode-restricting steps work, then chmod to the requested `mode` right
+    // before the rename so the final file lands with the requested bits set
+    // atomically with the contents.
     const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
-    await writeFile(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
-    // `mode` only applies on creation; explicit chmod handles the case where the
-    // tmp path was preexisting (e.g. crash recovery).
-    await chmod(tmpPath, 0o600);
-    await rename(tmpPath, targetPath);
+    try {
+        await writeFile(tmpPath, content, { encoding: "utf-8", mode: 0o600 });
+        // `mode` only applies on creation; explicit chmod handles the case where the
+        // tmp path was preexisting (e.g. crash recovery).
+        await chmod(tmpPath, mode);
+        await rename(tmpPath, targetPath);
+    }
+    catch (error) {
+        // Clean up the tmp file on any failure of write/chmod/rename so we
+        // don't leave `.npmrc.tmp-<pid>-<ts>` siblings accumulating across
+        // boots (especially in `~/` for the home writer). Best-effort: if the
+        // tmp file was never created (writeFile threw) or was already
+        // consumed by the rename, the unlink is a no-op we swallow.
+        await unlink(tmpPath).catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Filename of the on-disk backup of the baked-in `.npmrc` that ships with the
+ * dev-server image. Captured once per pod boot by `maybeWriteNpmrcForDir`
+ * before the first `writeNpmrc` rewrite, then used as the restore source when
+ * the org transitions back to `not-configured` (e.g. the last
+ * `org_npm_registry` row was deleted). Lives sibling to `.npmrc` in the same
+ * directory writes target.
+ */
+export const NPMRC_DEFAULT_FILENAME = ".npmrc.default";
+/**
+ * Snapshot `targetPath` to `backupPath` exactly once if the backup does
+ * not already exist. Lets a subsequent `writeNpmrc`-style rewrite of
+ * `targetPath` happen non-destructively: a restore path has a baked-in
+ * source to copy back when the org transitions to `not-configured`.
+ *
+ * Uses `link(2)` rather than read + write so the snapshot is concurrency-
+ * safe. Two properties matter:
+ *
+ *   - The kernel serializes hardlink creation: only one of N concurrent
+ *     callers wins; the rest see EEXIST. No read-then-write window where
+ *     a slow caller could observe a `writeNpmrc`-rewritten target and
+ *     poison the backup with the private registry content.
+ *   - `writeNpmrc` rewrites the target via tmp + rename, which gives it
+ *     a fresh inode. The hardlink at `backupPath` keeps the original
+ *     inode (with the baked-in content) alive — that's the whole point.
+ *
+ * Silently no-ops in two cases:
+ *   - `backupPath` is already present (subsequent boots, or a second
+ *     call in the same boot after the first capture landed). Important so
+ *     a later `writeNpmrc`-rewritten target is never mistaken for the
+ *     baked-in baseline.
+ *   - `targetPath` does not exist (image without a baked-in `.npmrc`,
+ *     or a brownfield app dir that never had one). The natural "restore"
+ *     state is "no file", which the restore path handles by treating an
+ *     absent backup as "no file" too — for that case `restoreInitialNpmrc`
+ *     unlinks the target if asked, otherwise leaves it alone.
+ *
+ * Other errors degrade to a warning + no-op rather than throwing — the
+ * capture is a best-effort safety net for the restore path, not a
+ * precondition for the install path itself.
+ *
+ * Returns a `SnapshotInitialNpmrcOutcome` so a caller can tell whether a
+ * usable backup now exists. This matters for the destructive restore path:
+ * a silent `failed` (e.g. EXDEV) leaves no backup behind, so a later
+ * `not-configured` transition must NOT mistake the absent backup for
+ * "nothing to preserve" and unlink a real baked-in userconfig (APPS-4428).
+ * Still never throws — the outcome is advisory, not an error channel.
+ *
+ * Shared with the home-npmrc writer (CLI startup, target =
+ * `~/.superblocks/npmrc`) so both project-dir and home flows agree on the
+ * snapshot/restore semantics.
+ */
+export async function snapshotInitialNpmrc(targetPath, backupPath) {
+    try {
+        await link(targetPath, backupPath);
+        return "created";
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "EEXIST") {
+            // Snapshot already taken (prior boot or concurrent caller): a usable
+            // backup exists even though this call didn't write it.
+            return "exists";
+        }
+        if (code === "ENOENT") {
+            // No baked-in target to snapshot; the restore baseline is "no file".
+            return "no-source";
+        }
+        getLogger().warn("[npm-registry] failed to capture .npmrc backup; restore path will be unavailable until next pod boot", {
+            target: targetPath,
+            backup: backupPath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return "failed";
+    }
 }
 /**
- * Convenience: invoke `writeNpmrc` against `<dir>/.npmrc` if registry config is
- * present in the env. No-op when unset (preserves today's behavior for SaaS /
- * local dev).
+ * Restore `targetPath` from `backupPath` when the org has transitioned
+ * back to `not-configured` (e.g. last `org_npm_registry` row deleted).
+ * Without this, a file previously rewritten by `writeNpmrc` stays in
+ * place pointing at a registry the customer just removed — the exact
+ * case APPS-4320 closes for project `.npmrc`, and APPS-4328 closes for
+ * the home-level userconfig.
+ *
+ * Best-effort, never throws. The project-dir caller
+ * (`maybeWriteNpmrcForDir` → `prepareForPrivateRegistry`) needs to fall
+ * through to `stripResolvedFromLockfile` even when the restore can't
+ * run; the home-level caller (`syncHomeNpmrc`) needs to finish dev-server
+ * startup. Any error here degrades to a warn + no-op so the surrounding
+ * install path stays alive.
+ *
+ * Skips the rewrite (without a warning) in three harmless cases:
+ *   - `targetPath` does not exist. The baked-in baseline for this dir is
+ *     "no file"; there is nothing to restore to.
+ *   - `backupPath` is missing AND `options.unlinkTargetWhenBackupMissing`
+ *     is not set. Expected on pods that never had `org_npm_registry`
+ *     configured (snapshot is gated on the configured branch), AND on
+ *     older pods whose target was rewritten before this commit landed.
+ *     In both cases the running file is what the pod has lived with —
+ *     leave it alone.
+ *   - `targetPath` already byte-matches `backupPath`. Avoids a no-op
+ *     rewrite that would bump mtime for downstream watchers (e.g. Tilt /
+ *     Vite file-sync).
  *
- * Returns the loaded config when an `.npmrc` was written, otherwise `undefined`.
+ * When `options.unlinkTargetWhenBackupMissing` is true and the backup is
+ * absent but the target exists, the target is unlinked — see the option
+ * comment.
  */
-export async function maybeWriteNpmrcForDir(dir, options = {}, env = process.env) {
-    const config = getNpmRegistryConfig(env);
-    if (!config) {
+export async function restoreInitialNpmrc(targetPath, backupPath, options = {}) {
+    let current;
+    try {
+        current = await readFile(targetPath, "utf-8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return;
+        }
+        getLogger().warn("[npm-registry] failed to read target for restore comparison; skipping", {
+            path: targetPath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    let baked;
+    try {
+        baked = await readFile(backupPath, "utf-8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            if (options.unlinkTargetWhenBackupMissing) {
+                // The caller owns the target file and there is no image-baked
+                // baseline to fall back to. Leaving a stale rewrite in place is
+                // worse than removing the file: subsequent npm/pnpm invocations
+                // pinned at this userconfig will fall through to public npm
+                // rather than an old configured-org registry/token.
+                try {
+                    await unlink(targetPath);
+                    getLogger().info("[npm-registry] removed Superblocks-owned userconfig after org transitioned to not-configured (no backup to restore)", { path: targetPath });
+                }
+                catch (unlinkError) {
+                    const unlinkCode = unlinkError
+                        ?.code;
+                    if (unlinkCode === "ENOENT") {
+                        return;
+                    }
+                    getLogger().warn("[npm-registry] failed to remove Superblocks-owned userconfig with no backup; leaving file in place", {
+                        path: targetPath,
+                        code: unlinkCode,
+                        error: unlinkError instanceof Error
+                            ? unlinkError.message
+                            : String(unlinkError),
+                    });
+                }
+                return;
+            }
+            // Two harmless overlapping cases produce this for project-dir
+            // callers:
+            //   1. Pod never had `org_npm_registry` rows, so capture (gated on
+            //      the configured branch) never fired. The target is still the
+            //      baked-in image content — nothing to restore.
+            //   2. Pod was configured-then-deconfigured before this commit
+            //      landed, so the target is a stale rewrite with no companion
+            //      snapshot. A recycle is required to recover, but per-install
+            //      logging here would be noisy and not actionable.
+            // Either way, no-op silently.
+            return;
+        }
+        getLogger().warn("[npm-registry] failed to read .npmrc backup for restore; skipping", {
+            path: backupPath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    if (current === baked) {
         return;
     }
-    await writeNpmrc(path.join(dir, ".npmrc"), config, options);
-    return config;
+    // Atomic copy: tmp + rename, mirroring `writeNpmrc`'s strategy so a
+    // crash mid-restore cannot leave a half-written file that fails
+    // `npm install` with a parse error.
+    const tmpPath = `${targetPath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        await writeFile(tmpPath, baked, { encoding: "utf-8", mode: 0o600 });
+        await chmod(tmpPath, 0o600);
+        await rename(tmpPath, targetPath);
+    }
+    catch (error) {
+        await unlink(tmpPath).catch(() => { });
+        // Swallow + warn rather than rethrow: the project-dir caller chains
+        // into `stripResolvedFromLockfile` (APPS-4300), which is the actual
+        // durable safety net for poisoned lockfiles. Propagating the restore
+        // failure would skip that strip and leave the install path worse off
+        // than pre-APPS-4320.
+        getLogger().warn("[npm-registry] failed to restore .npmrc from backup; leaving current file in place", {
+            path: targetPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    getLogger().info("[npm-registry] restored .npmrc from backup after org transitioned to not-configured", { path: targetPath });
 }
 /**
- * Materializes the private-registry `.npmrc` (when the env contract is set)
- * AND unconditionally strips `resolved` URLs from any lockfile present in
- * `dir`, so a subsequent `npm install` is guaranteed to re-resolve through
- * the active registry.
+ * Marker on the appended ignore block so we can detect a prior append and
+ * skip the work. Read-side checks are by exact-line match, not by this
+ * marker, so a customer who hand-edits the file (deletes the marker, keeps
+ * the `.npmrc` line) still gets the no-op behaviour they want.
+ */
+const NPMRC_GITIGNORE_MARKER = "# Superblocks: prevent committing private npm registry credentials";
+/**
+ * True iff `<dir>` looks like a native-git checkout. Detects both regular
+ * repos (`.git/` directory) and worktrees / submodules (`.git` file containing
+ * a `gitdir:` pointer). Any stat error other than ENOENT is logged and the
+ * function returns true, so a permission glitch fails closed (we will then
+ * refuse to write the token-bearing `.npmrc` rather than assume "safe,
+ * not a git checkout").
+ *
+ * Note: this only checks for `<dir>/.git` literally. `isInsideGitWorkTree`
+ * is the broader check that also catches nested-repo layouts where `<dir>`
+ * has no `.git` but a parent does — we need both because the parent-repo
+ * case is also a `git add .` leak path (cursor[bot] review on PR #19642).
+ */
+async function dirHasNativeGit(dir) {
+    const gitPath = path.join(dir, ".git");
+    try {
+        await stat(gitPath);
+        return true;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return false;
+        }
+        getLogger().warn("[npm-registry] failed to stat .git; assuming native-git for safety", {
+            path: gitPath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return true;
+    }
+}
+/**
+ * True iff `<dir>` is inside any git working tree — either because it has
+ * its own `.git` (regular repo, worktree, submodule) OR because a parent
+ * directory does. The nested-repo case is a real leak path: an app dir
+ * with no local `.git` but a parent that does will be staged by
+ * `git add .` run from the parent, and the `.npmrc` token would land in
+ * the parent's commit history.
+ *
+ * Implementation: `git rev-parse --is-inside-work-tree` walks up from
+ * `<dir>` and exits 0 inside a work tree, non-zero (128) outside. Uses
+ * the same `runGit` scrubbed-env wrapper so a caller spawned by a git
+ * hook can't poison the verdict via `GIT_*` env vars. If git itself is
+ * missing or the invocation times out (`runGit` returns `code: null`),
+ * returns false — there is no git to stage anything with, so the
+ * non-native branch handles it via the proactively-created `.gitignore`.
+ */
+async function isInsideGitWorkTree(dir) {
+    if (await dirHasNativeGit(dir)) {
+        return true;
+    }
+    const result = await runGit(dir, ["rev-parse", "--is-inside-work-tree"]);
+    if (result.code === 0) {
+        return true;
+    }
+    if (result.code === 128) {
+        // Canonical "not a git repository" exit. Definitively outside any
+        // work tree — the non-native-git branch is correct.
+        return false;
+    }
+    if (result.code === null) {
+        // git binary missing or invocation timed out (`runGit` returns
+        // `code: null` for any non-exit failure: ENOENT for `git`, ETIMEDOUT
+        // after `GIT_VERIFY_TIMEOUT_MS`, signal kills, etc.).
+        //
+        // Returning `false` here routes us into the non-native-git branch,
+        // which is the SAFER choice in every realistic scenario:
+        //
+        //   1. Local-`.git` case is unreachable here: `dirHasNativeGit` short-
+        //      circuited above when `<dir>/.git` exists, so we never hit
+        //      `rev-parse` for a regular repo at `<dir>`.
+        //
+        //   2. Nested-parent-repo case (the cursor[bot] concern): the parent
+        //      has `.git` but the app dir doesn't. If git is missing, the
+        //      customer cannot run `git add .` from the parent either — there
+        //      is no git binary to stage anything with. The fail-closed
+        //      requirement only matters when a working git is present, and a
+        //      working git would have returned `0` (or `128`), not `null`.
+        //      For the timeout case, a hung `rev-parse --is-inside-work-tree`
+        //      on a real repo would be unprecedented (the command only walks
+        //      parent directories looking for `.git`); a timeout in practice
+        //      means a broken environment where `git add` would also fail.
+        //
+        //   3. The non-native-git branch we route into still calls
+        //      `appendNpmrcIgnore` on `<dir>/.gitignore`. If that succeeds,
+        //      a future `git init` (or `git` reappearing on PATH) finds the
+        //      ignore entry already in place and is future-safe. If
+        //      `appendNpmrcIgnore` fails, `ensureNpmrcGitignored` returns
+        //      `{ignored:false, hasGit:false}` and the caller refuses to write
+        //      the credential-bearing `.npmrc`.
+        //
+        // Returning `true` here instead would force the per-clone exclude
+        // fallback, but that fallback also calls `verifyNpmrcIgnoredByGit`
+        // (same `runGit`) which would also return `code: null` and fail —
+        // ending in the same fail-closed state but with an extra useless
+        // attempt and a misleading "inside-repo" log line.
+        return false;
+    }
+    // Unexpected non-zero from git. Assume inside-a-repo for safety; the
+    // downstream verification will either confirm or fail closed.
+    getLogger().warn("[npm-registry] git rev-parse --is-inside-work-tree returned unexpected exit code; assuming inside-repo for safety", { dir, code: result.code, stderr: result.stderr });
+    return true;
+}
+/**
+ * Returns true if the LAST matching rule for `.npmrc` in `text` is a
+ * positive ignore (vs. a `!.npmrc` negation). Gitignore semantics are
+ * "last matching pattern wins": a file containing `.npmrc` followed later
+ * by `!.npmrc` re-includes the file, so a naive "does any line match
+ * `.npmrc`?" check is a false positive that would let the append be
+ * skipped and the credential-bearing `.npmrc` later staged on `git add .`.
+ * Walk the file in order and remember the most recent verdict; return true
+ * only when that verdict is a positive ignore.
+ *
+ * Matches npm/git's own grammar for our specific filename: a line is the
+ * literal `.npmrc` (anchored anywhere) or `/.npmrc` (anchored to repo
+ * root), with optional `!` negation prefix. We do NOT try to interpret
+ * glob patterns like `*.rc` — false negatives just append a redundant
+ * line (always safe under last-match), false positives would leak
+ * credentials.
+ *
+ * Leading whitespace is NOT trimmed: in gitignore grammar leading spaces
+ * are significant, so `  .npmrc` matches a file literally named `  .npmrc`,
+ * NOT `.npmrc`. Trimming here would be a false positive (we'd skip the
+ * append, but git would still stage `.npmrc`). Only two normalisations
+ * happen, both to match git's own pattern parser exactly:
+ *
+ *   - Trailing CR from CRLF line endings is stripped (CR is not part of
+ *     the path).
+ *   - UNESCAPED trailing spaces are stripped (`trim_trailing_spaces` in
+ *     git's `dir.c`). `.npmrc   ` is the pattern `.npmrc`; `!.npmrc   `
+ *     is the negation `!.npmrc`. This is the gpoulios-sb PR #19642
+ *     re-re-review case: a stray trailing space on `!.npmrc` made git
+ *     treat the line as a negation while a naive textual check still
+ *     matched the earlier `.npmrc` positive, so the helper declared the
+ *     file "ignored" and `maybeWriteNpmrcForDir` proceeded to write
+ *     credentials that a later `git init && git add .` would stage.
+ *     Tabs are NOT trimmed (git only trims spaces); `\<space>` escapes
+ *     a literal trailing space and is preserved.
+ *
+ * Other gitignore exotica (globs, character classes, `**`, backslash
+ * escapes, leading `\!`, UTF-8 BOM, etc.) are NOT interpreted. All of
+ * those cases fail the exact-match comparison below, so the textual
+ * verdict is "not ignored" — the helper then appends a fresh positive
+ * `.npmrc` rule and last-match-wins semantics make the file genuinely
+ * ignored. False negatives are safe (one redundant line); false
+ * positives leak credentials, so we err on the side of appending.
+ *
+ * This is the authoritative non-native-git check (gpoulios-sb PR #19642
+ * re-review): the non-git branch in `ensureNpmrcGitignored` has no
+ * `git check-ignore` follow-up, so the textual verdict must itself be
+ * future-safe against order-sensitive negations — otherwise a later
+ * `git init && git add .` in the same dir would stage a token-bearing
+ * `.npmrc` that the helper had blessed.
+ *
+ * For native-git checkouts textual presence is still necessary but NOT
+ * sufficient — `verifyNpmrcIgnoredByGit` is the authoritative check
+ * because:
+ *
+ *   - A negation in a DESCENDANT `.gitignore` (not just this file) can
+ *     re-include `.npmrc`; the textual check sees only the current file.
+ *   - An already-tracked `.npmrc` is staged on every commit regardless of
+ *     ignore rules; the textual check has no view of the index.
+ */
+function textIgnoresNpmrc(text) {
+    let lastVerdict;
+    for (const raw of text.split("\n")) {
+        const line = trimTrailingGitignoreSpaces(raw.replace(/\r$/, ""));
+        if (line === ".npmrc" || line === "/.npmrc") {
+            lastVerdict = true;
+        }
+        else if (line === "!.npmrc" || line === "!/.npmrc") {
+            lastVerdict = false;
+        }
+    }
+    return lastVerdict === true;
+}
+/**
+ * Strip trailing unescaped spaces from a gitignore pattern, matching
+ * git's `trim_trailing_spaces` (in `dir.c`) exactly.
+ *
+ * Algorithm (mirrors git's left-to-right walk):
+ *   - Track the position of the first trailing space.
+ *   - A `\<space>` pair is an escaped space and resets the tracker
+ *     (the space is part of the pattern).
+ *   - Any non-space character resets the tracker.
+ *   - Truncate at the first tracked trailing space.
+ *
+ * Only ASCII spaces (0x20) are trimmed. Tabs, NBSP, and other
+ * whitespace are preserved — that's what git does. The CR strip happens
+ * separately in `textIgnoresNpmrc`'s split loop because git treats CR as
+ * a line-ending artefact, not a pattern character.
+ *
+ * Examples (matching git's behaviour):
+ *   "!.npmrc "    → "!.npmrc"      (trailing space trimmed)
+ *   "!.npmrc   "  → "!.npmrc"      (multiple trailing spaces trimmed)
+ *   "!.npmrc\\ "  → "!.npmrc\\ "   (escaped space preserved)
+ *   "!.npmrc\\t"  → "!.npmrc\\t"   (tab preserved; not a space)
+ *   "  .npmrc"    → "  .npmrc"     (leading whitespace preserved)
+ */
+function trimTrailingGitignoreSpaces(line) {
+    let lastSpace = -1;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (ch === "\\" && line[i + 1] === " ") {
+            // Escaped space: skip the pair AND reset the tracker so the
+            // escaped space cannot anchor a truncation.
+            i++;
+            lastSpace = -1;
+        }
+        else if (ch === " ") {
+            if (lastSpace === -1) {
+                lastSpace = i;
+            }
+        }
+        else {
+            lastSpace = -1;
+        }
+    }
+    return lastSpace === -1 ? line : line.slice(0, lastSpace);
+}
+/**
+ * Timeout (ms) for the `git` invocations in `verifyNpmrcIgnoredByGit`.
+ * Generous enough for any realistic working tree (these commands scan only
+ * the index and ignore rules, not the working tree), short enough that a
+ * hung git invocation can't stall the install path.
+ */
+const GIT_VERIFY_TIMEOUT_MS = 5000;
+/**
+ * Build a `process.env` copy with every `GIT_*` variable removed. Used by
+ * `runGit` to insulate the helper from outer-process git state. See the
+ * comment in `runGit` for the leak path this guards against.
+ */
+function scrubbedGitEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (!key.startsWith("GIT_")) {
+            env[key] = value;
+        }
+    }
+    return env;
+}
+/**
+ * Run `git <args>` in `cwd`, returning the exit code without throwing. Any
+ * non-spawn error (timeout, ENOENT for `git`, etc.) returns `{ code: null }`
+ * so the caller fails closed. We use `execFile` (no shell) so the file
+ * arguments cannot be reinterpreted as shell syntax.
+ */
+async function runGit(cwd, args) {
+    try {
+        const { stderr } = await execFileAsync("git", args, {
+            cwd,
+            timeout: GIT_VERIFY_TIMEOUT_MS,
+            // Even if git emits a lot of stderr (unlikely for these tiny
+            // commands), bound the buffer so we don't OOM the install path.
+            maxBuffer: 1024 * 1024,
+            // Scrub `GIT_*` env vars before invoking git. If a caller's process
+            // was itself spawned by git (e.g. a `pre-commit` hook), git will
+            // have exported `GIT_DIR`, `GIT_INDEX_FILE`, `GIT_WORK_TREE`,
+            // `GIT_PREFIX`, etc. pointing at the OUTER repo. Those would
+            // override `cwd` discovery and make `check-ignore` / `ls-files`
+            // query the wrong repository, producing wrong fail-closed
+            // verdicts. The npm install path is not normally invoked from a
+            // git hook, but stripping these is cheap insurance.
+            env: scrubbedGitEnv(),
+        });
+        return { code: 0, stderr };
+    }
+    catch (error) {
+        // Promisified `execFile` throws an ExecException for both non-zero
+        // exits and spawn failures. Distinguish them via `code`:
+        //   - number → process exited with that code
+        //   - string ('ENOENT', 'ETIMEDOUT', etc.) → spawn / signal failure
+        const err = error;
+        const code = err?.code;
+        const stderr = err?.stderr ?? "";
+        if (typeof code === "number") {
+            return { code, stderr };
+        }
+        return { code: null, stderr };
+    }
+}
+/**
+ * Use git itself to verify that `.npmrc` is BOTH effectively ignored AND
+ * not already tracked from `dir`. Closes two leak paths that a textual
+ * `.gitignore` check cannot:
+ *
+ *   1. Negated ignore rules. `.npmrc` followed later by `!.npmrc` (or by
+ *      `!.npmrc` in a descendant `.gitignore`) makes the file trackable.
+ *      `textIgnoresNpmrc` would still report true.
+ *   2. Already-tracked `.npmrc`. Ignore rules do NOT protect files that
+ *      are already in the index — the next commit stages the rewrite. A
+ *      brownfield app that committed an empty `.npmrc` before the
+ *      private-registry feature is the canonical case.
+ *
+ * Returns true ONLY when both checks positively prove safety:
+ *   - `git check-ignore -q .npmrc` exits 0 (file is effectively ignored)
+ *   - `git ls-files --error-unmatch .npmrc` exits 1 (file is NOT tracked)
+ *
+ * Any other outcome — file not ignored, file tracked, git missing, not a
+ * real repo, timeout, unexpected exit code — returns false. The caller
+ * fails closed and refuses to write the credential-bearing `.npmrc`.
+ */
+async function verifyNpmrcIgnoredByGit(dir) {
+    const checkIgnore = await runGit(dir, ["check-ignore", "-q", "--", ".npmrc"]);
+    if (checkIgnore.code !== 0) {
+        if (checkIgnore.code === 1) {
+            getLogger().warn("[npm-registry] git check-ignore reports .npmrc is NOT effectively ignored (likely a `!.npmrc` negation downstream); refusing to write credential-bearing .npmrc", { dir });
+        }
+        else {
+            getLogger().warn("[npm-registry] git check-ignore failed (not a real git repo, git missing, or timeout); refusing to write credential-bearing .npmrc", { dir, code: checkIgnore.code, stderr: checkIgnore.stderr });
+        }
+        return false;
+    }
+    const lsFiles = await runGit(dir, [
+        "ls-files",
+        "--error-unmatch",
+        "--",
+        ".npmrc",
+    ]);
+    if (lsFiles.code === 0) {
+        // File is in the index. Even with `.gitignore` containing `.npmrc`,
+        // rewriting the file with `_authToken=…` will stage on the next
+        // commit because git tracks file content for already-tracked files
+        // regardless of the ignore list.
+        getLogger().warn("[npm-registry] .npmrc is already tracked by git; refusing to write credentials (next commit would stage the token)", { dir });
+        return false;
+    }
+    if (lsFiles.code !== 1) {
+        // 1 is the canonical "not tracked" exit (`error: pathspec '.npmrc' did
+        // not match any file(s) known to git`). Other non-zero codes mean
+        // something is wrong with the repo / our invocation — fail closed.
+        getLogger().warn("[npm-registry] git ls-files returned an unexpected exit code; refusing to write credential-bearing .npmrc", { dir, code: lsFiles.code, stderr: lsFiles.stderr });
+        return false;
+    }
+    return true;
+}
+/**
+ * Append (or create) an ignore file at `targetPath` so that `.npmrc` is
+ * excluded. Returns true on success, false on any I/O failure. `createIfMissing`
+ * controls whether an absent file is created. All `ensureNpmrcGitignored`
+ * call sites pass `true` (so a missing `.gitignore` or `.git/info/exclude`
+ * is materialised before the credential write); the parameter is preserved
+ * so future callers can opt into a strict "only append, never create"
+ * behaviour without touching the body.
+ */
+async function appendNpmrcIgnore(targetPath, createIfMissing) {
+    // Refuse to follow a symlink at the leaf path component on BOTH the read
+    // and the write. `targetPath` is `<dir>/.gitignore` or
+    // `<dir>/.git/info/exclude`; a crafted workspace could point either at a
+    // file outside the app root. `readFile`/`writeFile` follow symlinks, so
+    // without `O_NOFOLLOW` our ~70-byte ignore fragment could be written
+    // through the link to an external target (cursor[bot] MEDIUM, colinhicks
+    // review on PR #19642). Opening with `O_NOFOLLOW` fails with `ELOOP` when
+    // the leaf is a symlink; we treat that as fail-closed (return false) so
+    // `ensureNpmrcGitignored` refuses the credential write — same boundary
+    // discipline as `persisted-checklist-store.ts` / PR #19495, but TOCTOU-free
+    // because the kernel checks atomically at open time. `O_NOFOLLOW` is POSIX;
+    // `?? 0` degrades to a plain open where it is absent (the dev-server runs
+    // on Linux, where it is always defined).
+    const noFollow = fsConstants.O_NOFOLLOW ?? 0;
+    let existing;
+    let readHandle;
+    try {
+        readHandle = await open(targetPath, fsConstants.O_RDONLY | noFollow);
+        existing = await readHandle.readFile("utf-8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ELOOP") {
+            getLogger().warn("[npm-registry] ignore file is a symlink; refusing to follow it for .npmrc enforcement", { path: targetPath });
+            return false;
+        }
+        if (code !== "ENOENT") {
+            getLogger().warn("[npm-registry] failed to read ignore file; skipping .npmrc enforcement", {
+                path: targetPath,
+                code,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+        if (!createIfMissing) {
+            return false;
+        }
+        existing = undefined;
+    }
+    finally {
+        await readHandle?.close();
+    }
+    if (existing !== undefined && textIgnoresNpmrc(existing)) {
+        return true;
+    }
+    // Separate the appended block from any existing content with a blank line.
+    // For an empty / freshly-created file start at column 0 with no leading
+    // blank line (cosmetic, colinhicks review on PR #19642). For non-empty
+    // content the byte output is unchanged.
+    const base = existing ?? "";
+    const sep = base.length === 0 ? "" : base.endsWith("\n") ? "\n" : "\n\n";
+    const appended = `${base}${sep}${NPMRC_GITIGNORE_MARKER}\n.npmrc\n`;
+    let writeHandle;
+    try {
+        // `O_TRUNC` is safe: we re-serialise the full file (existing content +
+        // appended block), so truncation never drops data. `O_NOFOLLOW` closes
+        // the TOCTOU window where the leaf is swapped for a symlink between the
+        // read above and this write. Mode 0o666 matches the previous `writeFile`
+        // default (umask trims it to 0o644) and is ignored when the file already
+        // exists.
+        writeHandle = await open(targetPath, fsConstants.O_WRONLY |
+            fsConstants.O_CREAT |
+            fsConstants.O_TRUNC |
+            noFollow, 0o666);
+        await writeHandle.writeFile(appended, "utf-8");
+        getLogger().info("[npm-registry] appended .npmrc to ignore file to prevent credential commit", { path: targetPath });
+        return true;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ELOOP") {
+            getLogger().warn("[npm-registry] ignore file became a symlink before write; refusing to write through it", { path: targetPath });
+            return false;
+        }
+        getLogger().warn("[npm-registry] failed to append .npmrc to ignore file", {
+            path: targetPath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+    finally {
+        await writeHandle?.close();
+    }
+}
+/**
+ * Ensure `.npmrc` is git-ignored from `<dir>` before any credential-bearing
+ * `.npmrc` is written.
+ *
+ * Why this matters: `maybeWriteNpmrcForDir` writes a `.npmrc` containing
+ * `//host/:_authToken=<customer token>` at the app root. The DBFS sync
+ * already excludes `.npmrc` from upload (`codeModeExcludedFiles` in
+ * `file-system-helpers.ts`), but the native-git path calls `git.add(".")`
+ * (socket-manager `gitCommitLocal`/`gitPull`, agent `git`/`git_raw` tools)
+ * which stages everything not listed in the app's on-disk ignore. Without
+ * this enforcement, a customer with a configured private registry pushes
+ * their `_authToken` to their external git remote on the next commit. The
+ * template `.gitignore` covers new apps; this helper covers the existing
+ * fleet whose `.gitignore` predates the registry feature.
+ *
+ * Behaviour, in three layers:
+ *
+ *   1. Non-native-git (`<dir>/.git` does not exist):
+ *      - Append `.npmrc` to `<dir>/.gitignore`, or create the file if
+ *        it doesn't exist. We create `.gitignore` here (not just when
+ *        `.git` already exists) so a subsequent `git init` in the same
+ *        directory is future-safe: a customer who later turns on native
+ *        git for an app where a credential-bearing `.npmrc` already
+ *        sits on disk would otherwise stage the token on their first
+ *        `git add .` before any install path re-runs this helper.
+ *      - On success return `{ ignored: true, hasGit: false }`. On a
+ *        read or write failure (`.gitignore` is a directory, disk full,
+ *        permission denied) return `{ ignored: false, hasGit: false }`.
+ *        The caller MUST refuse to write the credential-bearing
+ *        `.npmrc` in that case: even though no native git checkout
+ *        exists today, a later `git init` (or wiring this dir into an
+ *        existing repo) would find the on-disk token and stage it on
+ *        the first `git add .` — exactly the future-git leak path
+ *        gpoulios-sb flagged in code review.
+ *
+ *   2. Native-git (`<dir>/.git` exists), `.gitignore` path:
+ *      - Read or create `.gitignore`, append `.npmrc` if missing. After
+ *        the append, verify with git itself (`verifyNpmrcIgnoredByGit`)
+ *        that the file is effectively ignored AND not already tracked.
+ *        Only then return `ignored: true`.
+ *
+ *   3. Native-git, `.git/info/exclude` fallback:
+ *      - Only attempted when the `.gitignore` write failed AND `.git` is a
+ *        directory (regular repo). `.git/info/exclude` is the per-clone
+ *        ignore file: not synced to remotes, but exactly as effective as
+ *        `.gitignore` at preventing `git add` from staging the file. The
+ *        fallback lets us still fail-closed when the working tree is
+ *        read-only but the local clone metadata is writable. After the
+ *        exclude append, the same `verifyNpmrcIgnoredByGit` check runs.
+ *
+ * Why git verification, not just text: a `.gitignore` containing `.npmrc`
+ * is necessary but not sufficient. Two real leak paths bypass a naive
+ * "any line matches" textual check:
+ *   - A later `!.npmrc` re-includes the file (gitignore is order-sensitive).
+ *     `textIgnoresNpmrc` is already negation-aware (returns true only when
+ *     the LAST matching rule is positive), so for this case the textual
+ *     check correctly reports "not ignored" and `appendNpmrcIgnore` writes
+ *     a fresh positive `.npmrc` line that becomes the new last-match.
+ *     This is the gpoulios-sb PR #19642 re-review "always append" remedy,
+ *     applied uniformly to both branches (non-native-git relies on it as
+ *     the authoritative check; native-git double-checks with git below).
+ *   - An already-tracked `.npmrc` stages on every commit regardless of
+ *     ignore rules. No textual check sees the index, so for native-git
+ *     `git ls-files --error-unmatch` is the only catch.
+ *
+ * Returns `{ ignored, hasGit }`. The caller's fail-closed signal is
+ * `ignored === false` regardless of `hasGit`: any state in which we cannot
+ * guarantee `.npmrc` is ignored from `<dir>` blocks the credential write,
+ * because either the current native git checkout would stage the token on
+ * the next `git add .`, or a future `git init` in the same dir would find
+ * the token on disk and stage it on the first `git add .`. `hasGit` is
+ * retained for logging only — it lets the warning distinguish the
+ * "tomorrow's risk" case from the "today's risk" case.
+ */
+export async function ensureNpmrcGitignored(dir) {
+    // `hasGit` covers BOTH the local-`.git` and nested-repo (parent has
+    // `.git`) cases. The nested-repo case was the cursor[bot] PR #19642
+    // review concern: an app dir inside a parent git repo has no local
+    // `.git`, so a bare `dirHasNativeGit` check would treat it as
+    // non-native-git and let credentials through; `git add .` run from the
+    // parent would then stage `<dir>/.npmrc`. The local-`.git`-only check
+    // is still needed for the `.git/info/exclude` fallback below (that
+    // path only exists for regular repos, not nested-only layouts).
+    const hasGit = await isInsideGitWorkTree(dir);
+    const hasLocalDotGit = await dirHasNativeGit(dir);
+    const gitignorePath = path.join(dir, ".gitignore");
+    // Always create `.gitignore` if missing — even when `!hasGit` — so a
+    // later `git init` in this dir finds the `.npmrc` entry already in
+    // place and the first `git add .` cannot stage a credential file that
+    // was written between the two events. See the layer-1 comment in this
+    // function's docstring for the future-safe rationale.
+    if (await appendNpmrcIgnore(gitignorePath, true)) {
+        if (!hasGit) {
+            return { ignored: true, hasGit: false };
+        }
+        if (await verifyNpmrcIgnoredByGit(dir)) {
+            return { ignored: true, hasGit: true };
+        }
+        // Textual append succeeded but git disagrees: a downstream `!.npmrc`
+        // negation, an already-tracked `.npmrc`, or `git` is unable to verify
+        // (missing, broken repo, timeout). Fall through to the per-clone
+        // exclude fallback — it can override `.gitignore` negations (exclude
+        // rules are evaluated last) AND covers the "no git binary / bad repo"
+        // case in the same way (the fallback verifies too, and fails closed).
+    }
+    if (!hasGit) {
+        // Non-native-git, no parent repo either: the `.gitignore` append/create
+        // failed (rare — disk full, permission denied, or `.gitignore` was a
+        // directory). Fail-closed: the future-git leak path is still open.
+        return { ignored: false, hasGit: false };
+    }
+    // Inside a git work tree: `.gitignore` enforcement failed (or git
+    // verification rejected it). Try the per-clone exclude file as a
+    // fallback. Only valid when `<dir>/.git` is a directory (regular repo
+    // rooted here); for a nested-repo case (`hasGit` but no local
+    // `.git`) we have no path to the parent's `.git/info/exclude` without
+    // a `git rev-parse --git-dir`, and the same exclude in the parent
+    // won't anchor to `<dir>` anyway. Fail closed in those cases.
+    const dotGit = path.join(dir, ".git");
+    let dotGitIsDir = false;
+    if (hasLocalDotGit) {
+        try {
+            const st = await stat(dotGit);
+            dotGitIsDir = st.isDirectory();
+        }
+        catch {
+            // Already covered by `dirHasNativeGit` — if we got here, the path
+            // existed at the time of that check. A subsequent disappearance is
+            // odd but we still fail closed.
+        }
+    }
+    if (!dotGitIsDir) {
+        getLogger().warn("[npm-registry] native-git checkout has no writable .gitignore and .git is not a regular directory; refusing to write .npmrc", { path: gitignorePath });
+        return { ignored: false, hasGit: true };
+    }
+    const infoDir = path.join(dotGit, "info");
+    try {
+        await mkdir(infoDir, { recursive: true });
+    }
+    catch (error) {
+        getLogger().warn("[npm-registry] failed to create .git/info directory for exclude fallback", {
+            path: infoDir,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { ignored: false, hasGit: true };
+    }
+    const excludePath = path.join(infoDir, "exclude");
+    if (await appendNpmrcIgnore(excludePath, true)) {
+        // Verify with git again. The exclude file is evaluated LAST in git's
+        // ignore precedence, so it overrides a `!.npmrc` negation in
+        // `.gitignore`. But it still cannot un-track an already-tracked file,
+        // so `ls-files --error-unmatch` is still the gate.
+        if (await verifyNpmrcIgnoredByGit(dir)) {
+            return { ignored: true, hasGit: true };
+        }
+    }
+    return { ignored: false, hasGit: true };
+}
+/**
+ * Convenience: invoke `writeNpmrc` against `<dir>/.npmrc` when the client
+ * resolves to a configured (or stale) registry config. No-op when:
+ *
+ *   - `client` is undefined (test-only opt-out — production code paths
+ *     always pass a client constructed by AiService); or
+ *   - the resolved config is `source: "unreachable"` (transient cold-cache
+ *     outage — we leave `.npmrc` whatever it currently is and reconcile on
+ *     the next successful fetch, rather than clobbering a last-known-good
+ *     private-registry `.npmrc` back to baseline during the outage window);
+ *     or
+ *   - the resolved config is `source: "not-configured"` (deliberate unset
+ *     observation). If a previously-written `.npmrc` exists that no longer
+ *     matches the baked-in `.npmrc.default`, restore it — see APPS-4320.
+ *
+ * On the first call per pod boot for `<dir>`, captures `<dir>/.npmrc` to
+ * `<dir>/.npmrc.default` before any rewrite so the restore path above has
+ * a source to copy back from.
+ *
+ * Returns the resolved fetch result so callers can branch on `source` for
+ * observability, or `undefined` when no client was provided.
+ */
+export async function maybeWriteNpmrcForDir(dir, options = {}, client) {
+    if (!client) {
+        return undefined;
+    }
+    const result = await client.getConfig();
+    if (result.source === "unreachable") {
+        // Transient cold-cache outage. We do NOT know the org's current
+        // registry state, so we refuse to act on this signal — neither
+        // rewrite (no config to render) nor restore (would clobber a
+        // last-known-good private-registry `.npmrc` back to the baked-in
+        // baseline exactly during the outage window where the customer
+        // needs us to fail closed). Next successful fetch will reconcile.
+        // Symmetric with `syncHomeNpmrc`'s `skipped-unreachable` branch in
+        // `home-npmrc.mts`.
+        getLogger().warn("[npm-registry] server unreachable with no cached config; .npmrc left unchanged", { path: path.join(dir, ".npmrc") });
+        return result;
+    }
+    const npmrcPath = path.join(dir, ".npmrc");
+    const backupPath = path.join(dir, NPMRC_DEFAULT_FILENAME);
+    if (!result.config.configured) {
+        await restoreInitialNpmrc(npmrcPath, backupPath);
+        if (result.config.allowInstallScripts === false) {
+            // Even without registry rows the org policy disallows install
+            // scripts.  Bake `ignore-scripts=true` into the project `.npmrc`
+            // so any npm/pnpm invocation (patch-package, husky, ad-hoc
+            // `bash npm install`) honours the policy.  `writeNpmrc` with a
+            // policy-only config preserves existing scope lines (e.g. the
+            // EE-baked `@superblocksteam:registry=`) via `preserveScopeLines`.
+            //
+            // Skip `snapshotInitialNpmrc`: on a repeated sync the target
+            // already contains our policy file; snapshotting it would poison
+            // the backup so a later flip to allowInstallScripts=true could
+            // never restore the original baked content.
+            await writeNpmrc(npmrcPath, result.config, options);
+        }
+        else {
+            // Clean up a stale policy-only `.npmrc` left by a previous call
+            // when the dir had no baked-in file to snapshot.  In that case
+            // `restoreInitialNpmrc` cannot restore the "no file" baseline
+            // because `.npmrc.default` was never created.  We detect the stale
+            // file by checking that it contains only the policy line (no
+            // registry entries) and remove it.
+            try {
+                const content = await readFile(npmrcPath, "utf-8");
+                if (content.trim() === "ignore-scripts=true") {
+                    await unlink(npmrcPath);
+                }
+            }
+            catch (e) {
+                if (e?.code !== "ENOENT") {
+                    getLogger().warn("[npm-registry] failed to clean up stale policy-only .npmrc", {
+                        path: npmrcPath,
+                        error: e instanceof Error ? e.message : String(e),
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    // Ensure `.npmrc` is git-ignored from `<dir>` BEFORE we write the
+    // credential-bearing file. Fail-closed in BOTH the native-git and
+    // non-native-git cases:
+    //
+    //   - Native-git, no writable ignore (neither `<dir>/.gitignore` nor
+    //     `<dir>/.git/info/exclude`): the next `git add .` would stage the
+    //     token and push it to the customer's external remote.
+    //
+    //   - Non-native-git, `<dir>/.gitignore` could not be created (rare —
+    //     disk full, permission denied, or the path is a directory): no
+    //     immediate native-git leak, but a later `git init` in the same
+    //     dir would find the on-disk token with no ignore rule and stage
+    //     it on the first `git add .`. This is the exact future-git leak
+    //     path called out in PR #19642 code review.
+    //
+    // See `ensureNpmrcGitignored` for the full decision matrix.
+    const ignoreResult = await ensureNpmrcGitignored(dir);
+    if (!ignoreResult.ignored) {
+        getLogger().warn(ignoreResult.hasGit
+            ? "[npm-registry] refusing to write .npmrc with credentials: native-git checkout has no writable ignore (neither .gitignore nor .git/info/exclude); would leak token on next `git add .`"
+            : "[npm-registry] refusing to write .npmrc with credentials: could not create or update .gitignore (write failed); a later `git init` in this dir would stage the token on first `git add .`", { path: npmrcPath, dir, hasGit: ignoreResult.hasGit });
+        return result;
+    }
+    // Snapshot the baked-in `.npmrc` before the first rewrite so the
+    // not-configured branch above has a restore source. Gated on the
+    // configured branch so a pod whose org was configured-then-deconfigured
+    // before this commit landed (so `.npmrc` is already a rewritten value
+    // with no companion `.npmrc.default`) does not snapshot the rewritten
+    // file as the baked-in baseline. In that pre-existing-rewrite case
+    // the restore path correctly no-ops; recovery requires a pod recycle.
+    //
+    // Snapshot AFTER the gitignore check (we don't need a backup if we're
+    // refusing to write).
+    await snapshotInitialNpmrc(npmrcPath, backupPath);
+    await writeNpmrc(npmrcPath, result.config, options);
+    return result;
+}
+/**
+ * Materializes the private-registry `.npmrc` AND unconditionally strips
+ * `resolved` URLs from any lockfile present in `dir`, so a subsequent
+ * `npm install` is guaranteed to re-resolve through the active registry.
+ * The `.npmrc` write is gated on whether the client resolves to a configured
+ * registry; the lockfile strip runs regardless.
  *
  * Why the strip is unconditional (decoupled from the `.npmrc` write):
- *   - SaaS dev-server pods (staging/prod) run without `SUPERBLOCKS_NPM_REGISTRY`
- *     set, but their lockfiles can still be poisoned with cross-registry
- *     `resolved` URLs via DBFS state (APPS-4300). Gating the strip on the
- *     env meant the only safety net never fired in the exact environment
- *     where it mattered. Always stripping closes that read path.
+ *   - SaaS dev-server pods (staging/prod) often run without a configured
+ *     org npm registry, but their lockfiles can still be poisoned with
+ *     cross-registry `resolved` URLs via DBFS state (APPS-4300). Gating
+ *     the strip on the client's configured-ness meant the only safety net
+ *     never fired in the exact environment where it mattered. Always
+ *     stripping closes that read path.
  *   - The mutation is transient: `npm install` rewrites `resolved` with
  *     URLs from the active `.npmrc` registry on the very next line, so a
  *     local dev whose lockfile pointed at npmjs.org sees the same URLs
@@ -288,13 +1927,14 @@ export async function maybeWriteNpmrcForDir(dir, options = {}, env = process.env
  * (only configure GHPR scope for ephemeral builds) is the actual durable
  * fix; this strip is the runtime safety net for already-poisoned DBFS state.
  *
- * Returns the loaded config when an `.npmrc` was written, otherwise
- * `undefined`. The lockfile strip happens in both cases.
+ * Returns the resolved fetch result when a client is provided (so callers
+ * can branch on `source` for observability), or `undefined` when no client
+ * was provided. The lockfile strip happens in both cases.
  */
-export async function prepareForPrivateRegistry(dir, options = {}, env = process.env) {
-    const config = await maybeWriteNpmrcForDir(dir, options, env);
+export async function prepareForPrivateRegistry(dir, options = {}, client) {
+    const result = await maybeWriteNpmrcForDir(dir, options, client);
     await stripResolvedFromLockfile(dir);
-    return config;
+    return result;
 }
 /**
  * Removes the `resolved` field from every entry in `.packages` of an npm v2+
@@ -329,7 +1969,7 @@ export async function stripResolvedFromLockfile(dir) {
         stripResolvedFromLockfilePath(path.join(dir, "node_modules", ".package-lock.json")),
     ]);
 }
-async function stripResolvedFromLockfilePath(lockfilePath) {
+export async function stripResolvedFromLockfilePath(lockfilePath) {
     let raw;
     try {
         raw = await readFile(lockfilePath, "utf-8");
@@ -412,4 +2052,93 @@ async function stripResolvedFromLockfilePath(lockfilePath) {
         throw error;
     }
 }
+/**
+ * APPS-4370. Build a disk-backed `LastKnownRegistryPolicyStore` rooted at
+ * `<rootDir>/.superblocks/orgs/<orgId>/.registry-was-configured`.
+ *
+ * The marker's PRESENCE is the semantic signal; its content is informal
+ * (an ISO timestamp for forensics — "when was this org first seen with a
+ * configured registry"). Writes are best-effort: a write failure (EACCES
+ * on a 0o500 parent, ENOSPC) is logged and swallowed. Reads return false
+ * on any error so a transient IO problem doesn't degrade today's
+ * "proceed" behaviour into a fail-closed install.
+ *
+ * APPS-4427: `markConfigured` is AWAITED by its caller
+ * (`NpmRegistryClient.markPolicyConfigured`) before a `configured` / `stale`
+ * resolution is handed back, so the marker is durably on disk before that
+ * result is used — closing the crash window an un-awaited write would leave
+ * open. The write stays async (`fs/promises`, per the ai-service no-sync-fs
+ * rule) and is guarded to run at most once per process, so awaiting it stays
+ * off the install hot path after the first configured resolution.
+ *
+ * The `rootDir` is injected (rather than hard-coded to `os.homedir()`)
+ * so tests can isolate to a tmp directory and so the dev-server can
+ * point the store at the same disk it already manages
+ * (`~/.superblocks/...`). The per-org path keeps multiple orgs running
+ * against the same machine from contaminating each other's marker state.
+ */
+export function createDiskRegistryPolicyStore(opts) {
+    const orgDir = path.join(opts.rootDir, ".superblocks", "orgs", opts.organizationId);
+    const markerPath = path.join(orgDir, ".registry-was-configured");
+    // APPS-4427: write at most once per process. The marker's PRESENCE is the
+    // signal, so re-writing on every `configured`/`stale` resolution is pure
+    // overhead — and since the caller now AWAITS the write, guarding here keeps
+    // it off the install hot path after the first configured resolution. Only
+    // set on a SUCCESSFUL write, so a transient failure is retried next call.
+    let marked = false;
+    return {
+        async markConfigured() {
+            if (marked) {
+                return;
+            }
+            try {
+                // Async (`fs/promises`) per the ai-service no-sync-fs rule. Durability
+                // comes from the caller awaiting this before handing back the
+                // `configured`/`stale` resolution (see `markPolicyConfigured`), not
+                // from blocking the event loop with a sync write.
+                await mkdir(orgDir, { recursive: true });
+                // An ISO timestamp is enough to debug "when did we first see this
+                // org configured" without growing the file's semantic surface
+                // (presence is the signal).
+                await writeFile(markerPath, new Date().toISOString() + "\n", "utf-8");
+                marked = true;
+            }
+            catch (err) {
+                getLogger().warn("[npm-registry] failed to write registry-policy marker; ignoring", {
+                    path: markerPath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+        async hasEverBeenConfigured() {
+            try {
+                await stat(markerPath);
+                return true;
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code === "ENOENT") {
+                    // No marker → never been configured. The common case; not a
+                    // log-worthy event.
+                    return false;
+                }
+                // Anything else (EACCES on a clamped-perms dir, EIO) gets
+                // surfaced at warn level so a misconfigured deployment is
+                // visible, but we still resolve to false so the install path
+                // preserves current behaviour.
+                getLogger().warn("[npm-registry] failed to read registry-policy marker; treating as not-configured", {
+                    path: markerPath,
+                    code,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+    };
+}
+// Re-export the npm/pnpm install-error classifier + structured error types so
+// consumers of the `/npm-registry` entry (e.g. the CLI dev server) can classify
+// installs without reaching into ai-service internals. APPS-4450.
+export { parseNpmJsonError, parseNpmJsonDiagnostic, classifyNpmExecStderr, } from "./npm-error-parser.js";
+export { NpmInstallBlocked, NpmInstallError, scrubSecrets } from "../types.js";
 //# sourceMappingURL=npm-registry.js.map