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

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

@@ -0,0 +1,2461 @@
+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 { bucketNpmRegistryHost, NPM_REGISTRY_SPAN, NPM_REGISTRY_SPAN_ATTR, npmRegistryEmitter, withNpmRegistrySpan, } from "@superblocksteam/telemetry";
+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 http(s)) are the
+ * CLI's last line of defense against a malicious admin or buggy server. The
+ * scheme is intentionally not pinned to https here: `isSuperblocksNpmProxyUrl`
+ * requires the row's origin to equal the client's own `baseUrl` before the
+ * login token is stamped, so an http proxy URL is only ever accepted when the
+ * client already reaches its server over http (cloud-prem's internal cluster
+ * service URL, local dev, the E2E fixture), never a foreign host.
+ * 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://") || s.startsWith("http://"), "registryUrl must be http(s)"),
+    // No token on the wire. `registryUrl` is the Superblocks npm proxy URL the
+    // server rewrites each row to (see the server's `/npm-registry/config`
+    // route); the CLI authenticates to the proxy with the machine's own login
+    // token, which it stamps in locally (see `registriesToConfig`). The
+    // customer's upstream registry password is held only on the server. Any
+    // `token` field an older server still emits is ignored: this schema strips
+    // unknown keys rather than rejecting them.
+});
+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();
+/**
+ * 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.
+ */
+export function shouldIgnoreInstallScripts(result) {
+    return result?.config.allowInstallScripts === false;
+}
+/**
+ * Map a fresh `getConfig` fetch result to the `config.lookup_total` outcome: a
+ * populated `configured` result is a cache `miss`; an empty `not-configured`
+ * is `not_configured`; `stale` (still serving the cached registry during an
+ * outage) is its own `stale` result; `unreachable` (no usable cache during an
+ * outage) is `error`. Throws that hard-fail are recorded as `error` at the
+ * call site, and cache hits within the TTL as `hit`.
+ */
+function configLookupFromFetch(result) {
+    switch (result.source) {
+        case "configured":
+            return "miss";
+        case "not-configured":
+            return "not_configured";
+        case "stale":
+            return "stale";
+        case "unreachable":
+            return "error";
+        default: {
+            // Exhaustiveness guard: adding a new `NpmRegistryFetchResult.source`
+            // variant makes this assignment a compile error, forcing it to be mapped
+            // above rather than silently returning `undefined` (which would fold to
+            // `error` and mask the real outcome — this package lacks
+            // `noImplicitReturns`).
+            const exhaustive = result;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * 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.
+ *
+ * `authToken` is the machine's own Superblocks login token. The server's
+ * `/config` route points every `registryUrl` at the Superblocks npm proxy and
+ * returns no upstream password, so the same login token authenticates every
+ * proxied registry. It is stamped onto each entry here (rather than threaded
+ * through `writeNpmrc` / the package-lookup path) so those consumers keep
+ * reading `config.*.token` unchanged. Omitted only in tests that render URLs
+ * without auth.
+ *
+ * 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.
+ */
+/**
+ * Path the server mounts the npm proxy under for an org. Mirrors the server's
+ * `npmProxyUrlPrefix`
+ * (`packages/server/src/controllers/v1/orgNpmRegistry/proxy.ts`): every
+ * `registryUrl` the `/config` route returns lives at
+ * `<external server URL>/api/v1/organizations/<orgId>/npm-proxy` (default) or
+ * a `…/npm-proxy/_scope/<scope>` sub-path. A server-side path change is a
+ * coordinated server+client change; until then this is the one client-side
+ * source of truth for "is this URL our proxy?".
+ */
+function superblocksNpmProxyPathPrefix(organizationId) {
+    return `/api/v1/organizations/${organizationId}/npm-proxy`;
+}
+/**
+ * True only when `registryUrl` is genuinely the Superblocks npm proxy for THIS
+ * org on THIS server (matching origin AND the org-scoped `/npm-proxy` path).
+ *
+ * The client stamps the machine's own Superblocks login token onto every row
+ * `/config` returns. That is only safe if every row really is our proxy: a
+ * version-skewed or misconfigured server could return a customer's upstream
+ * registry URL (or a broken one built from an empty external-server URL), and
+ * blindly stamping the login token onto that would leak a Superblocks
+ * credential to a third-party host. So the client proves the proxy invariant
+ * before stamping and fails closed when it does not hold.
+ *
+ * Compares parsed origin + pathname (not a raw string prefix) so trailing
+ * slashes and default ports can't cause a false negative, and requires a path
+ * boundary so a lookalike like `…/npm-proxyEVIL` can't slip through. Also
+ * rejects anything the canonical proxy URL never carries — embedded
+ * userinfo (`https://user:pass@host/…` shares the host's `origin` but is not
+ * our proxy URL) and any query/fragment — so a crafted URL can't satisfy the
+ * origin check while smuggling something else into `.npmrc`.
+ */
+export function isSuperblocksNpmProxyUrl(registryUrl, baseUrl, organizationId) {
+    let registry;
+    let base;
+    try {
+        registry = new URL(registryUrl);
+        base = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    if (registry.origin !== base.origin) {
+        return false;
+    }
+    if (registry.username || registry.password) {
+        return false;
+    }
+    if (registry.search || registry.hash) {
+        return false;
+    }
+    const prefix = superblocksNpmProxyPathPrefix(organizationId);
+    return (registry.pathname === prefix || registry.pathname.startsWith(`${prefix}/`));
+}
+/**
+ * True when on-disk `.npmrc` / `.npmrc.default` content routes installs
+ * through this org's Superblocks npm proxy.
+ *
+ * Origin is intentionally NOT required: live-edit pods write
+ * cluster-local hosts (`server.superblocks.svc.cluster.local`) while the
+ * client `baseUrl` is often the public URL. Path + org id is the durable
+ * ownership signal for both rewrite and delete. Path boundary required so
+ * a lookalike like `…/npm-proxyEVIL` cannot match.
+ *
+ * Scans every occurrence (a first lookalike must not hide a later genuine
+ * line). Requires the hit to sit on a non-comment `registry=` /
+ * `@scope:registry=` / `:_authToken=` line so a comment mentioning the
+ * path does not classify a customer file as ours.
+ *
+ * Used by `maybeWriteNpmrcForDir` to decide whether a project-dir file is
+ * safe to reconcile (stale PVC `.npmrc` after registry delete or expired
+ * JWT).
+ */
+export function isSuperblocksAuthoredNpmrcContent(content, organizationId) {
+    const prefix = superblocksNpmProxyPathPrefix(organizationId);
+    let from = 0;
+    while (from < content.length) {
+        const idx = content.indexOf(prefix, from);
+        if (idx < 0) {
+            return false;
+        }
+        const next = content[idx + prefix.length];
+        const boundaryOk = next === undefined || next === "/" || next === ":" || /\s/.test(next);
+        if (boundaryOk && isSuperblocksProxyHitOnAuthLine(content, idx)) {
+            return true;
+        }
+        from = idx + 1;
+    }
+    return false;
+}
+function isSuperblocksProxyHitOnAuthLine(content, hitIndex) {
+    const lineStart = hitIndex === 0 ? 0 : content.lastIndexOf("\n", hitIndex - 1) + 1;
+    const lineEnd = content.indexOf("\n", hitIndex);
+    const line = content
+        .slice(lineStart, lineEnd < 0 ? undefined : lineEnd)
+        .trimStart();
+    if (line.startsWith(";") || line.startsWith("#")) {
+        return false;
+    }
+    return (/^registry\s*=/i.test(line) ||
+        /^@[^\s:]+:registry\s*=/i.test(line) ||
+        /^\/\/.+:_authToken\s*=/i.test(line));
+}
+export function registriesToConfig(entries, allowInstallScripts, authToken) {
+    if (entries.length === 0) {
+        return {
+            configured: false,
+            ...(allowInstallScripts !== undefined ? { allowInstallScripts } : {}),
+        };
+    }
+    let defaultReg;
+    const scopes = {};
+    for (const entry of entries) {
+        const value = {
+            url: entry.registryUrl,
+            ...(authToken ? { token: authToken } : {}),
+        };
+        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 {
+        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 }),
+    });
+}
+/**
+ * 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 unreachable(allowInstallScripts) {
+    if (allowInstallScripts === undefined) {
+        return UNREACHABLE;
+    }
+    return Object.freeze({
+        source: "unreachable",
+        config: Object.freeze({ configured: false, allowInstallScripts }),
+    });
+}
+/**
+ * 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 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,
+        };
+    }
+    /**
+     * Organization id this client serves. Read-only; surfaced so the
+     * `npm_registry.prepare_for_private_registry` span (APPS-4378) can carry
+     * `org_id` without the standalone `prepareForPrivateRegistry` helper having
+     * to thread it through its signature.
+     */
+    get organizationId() {
+        return this.deps.organizationId;
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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),
+            });
+        }
+    }
+    /**
+     * Drop the marker when a fresh fetch proves the org has no registry rows.
+     * Mirrors `markPolicyConfigured`: best-effort, warns on failure, never
+     * propagates. A store that cannot clear leaves today's fail-closed
+     * behaviour in place.
+     */
+    async clearPolicyConfigured() {
+        const store = this.deps.lastKnownPolicyStore;
+        if (!store) {
+            return;
+        }
+        try {
+            await store.clearConfigured();
+        }
+        catch (err) {
+            getLogger().warn("[npm-registry] lastKnownPolicyStore.clearConfigured() failed; ignoring", {
+                orgId: this.deps.organizationId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * 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;
+        }
+    }
+    /**
+     * Resolve the current npm registry configuration for the active org. See
+     * the class docstring for the full state machine.
+     *
+     * `forceRefresh` bypasses the TTL cache-hit return below so a just-in-time
+     * caller (the `.npmrc` writer before an install, a package lookup, the
+     * home-npmrc sync) observes an admin clearing or changing the registry
+     * immediately instead of waiting out the TTL. `forceRefreshMaxAgeMs` lets a
+     * high-frequency caller (the package lookup) keep a small freshness floor so
+     * a tight sequential batch collapses onto one fetch; left at 0 (install /
+     * home sync) a forced read always re-fetches. It does NOT touch the cache
+     * before fetching: `serveStaleOrUnconfigured` still needs the last-known-good
+     * entries to fall back to during a 5xx/network outage. The flag-off
+     * short-circuit, inflight dedup, and all hard-fail branches behave
+     * identically.
+     */
+    async getConfig(options = {}) {
+        // Captured up front so every config.lookup emit carries the time getConfig
+        // spent resolving (~0 for a cache hit, the network round-trip for a miss).
+        const start = this.deps.now();
+        const forceRefresh = options.forceRefresh === true;
+        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"). `forceRefresh`
+            // does not change this: flag off means no config regardless.
+            npmRegistryEmitter.recordConfigLookup("not_configured", this.deps.now() - start, forceRefresh);
+            return NOT_CONFIGURED;
+        }
+        const now = this.deps.now();
+        // A forced read may still be served from the cache if it is younger than
+        // the caller's freshness floor (default 0 = always re-fetch). An unforced
+        // read uses the full TTL.
+        const maxAgeMs = forceRefresh
+            ? (options.forceRefreshMaxAgeMs ?? 0)
+            : this.deps.ttlMs;
+        if (this.cache && now - this.cache.fetchedAt < maxAgeMs) {
+            // 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) {
+                npmRegistryEmitter.recordConfigLookup("not_configured", this.deps.now() - start, forceRefresh);
+                return notConfigured(this.cache.npmAllowInstallScripts);
+            }
+            await this.markPolicyConfigured();
+            npmRegistryEmitter.recordConfigLookup("hit", this.deps.now() - start, forceRefresh);
+            return this.renderConfigured(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()
+            .then((result) => {
+            // Cache miss → fresh fetch. configured ⇒ miss; empty/404 ⇒
+            // not_configured; stale/unreachable ⇒ error. Deduped concurrent
+            // callers share this single emit, so the counter tracks fetch rate.
+            npmRegistryEmitter.recordConfigLookup(configLookupFromFetch(result), this.deps.now() - start, forceRefresh);
+            return result;
+        })
+            .catch((err) => {
+            // Hard-fail throws (double-401, refresh reject, other-4xx, schema
+            // parse) surface as `error`.
+            npmRegistryEmitter.recordConfigLookup("error", this.deps.now() - start, forceRefresh);
+            throw err;
+        })
+            .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 {
+            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();
+                }
+                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;
+            }
+        }
+        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.
+            this.signalPolicyFallback(this.cache?.npmAllowInstallScripts, "not_configured_404");
+            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;
+        // Prove every row is genuinely our proxy before trusting the payload.
+        // `renderConfig` stamps the machine's Superblocks login token onto each
+        // row's URL; if a version-skewed or misconfigured server returned a
+        // customer's upstream registry URL (or a broken one) we'd leak that login
+        // token to a third-party host. A row that fails the invariant means the
+        // payload is untrustworthy, so we treat it like a schema failure: don't
+        // cache it, and fail closed through `serveStaleOrUnconfigured` (serves
+        // last-known-good if we have it, else `unreachable`).
+        const nonProxyEntry = entries.find((entry) => !isSuperblocksNpmProxyUrl(entry.registryUrl, this.deps.baseUrl, this.deps.organizationId));
+        if (nonProxyEntry) {
+            const invariantError = new Error(`[npm-registry] server returned a registryUrl that is not the Superblocks npm proxy for this org (org ${this.deps.organizationId}); refusing to stamp the login token onto it`);
+            getLogger().error(invariantError.message, {
+                error: {
+                    kind: "NpmRegistryProxyInvariantViolated",
+                    message: invariantError.message,
+                },
+            });
+            return this.serveStaleOrUnconfigured(invariantError);
+        }
+        this.cache = {
+            entries,
+            npmAllowInstallScripts,
+            fetchedAt: this.deps.now(),
+        };
+        this.lastKnownPolicy = npmAllowInstallScripts;
+        if (entries.length === 0) {
+            // Drop the marker when a fresh fetch proves the org has no registry rows.
+            await this.clearPolicyConfigured();
+            return notConfigured(npmAllowInstallScripts);
+        }
+        await this.markPolicyConfigured();
+        return this.renderConfigured(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(/\/$/, "");
+        // `/config` returns each registry row with its `registryUrl` rewritten to
+        // the Superblocks npm proxy. No upstream tokens cross the wire anymore;
+        // the caller stamps the machine's own login token onto every row to auth
+        // against the proxy. Restricted to superblocks_jwt + access_token callers;
+        // the plain list route is redacted-only and serves the dashboard.
+        const url = `${base}/api/v1/organizations/${encodeURIComponent(this.deps.organizationId)}/npm-registry/config`;
+        return await this.deps.fetch(url, {
+            method: "GET",
+            headers: {
+                accept: "application/json",
+                authorization: `Bearer ${jwt}`,
+            },
+        });
+    }
+    /**
+     * Signal when `lastKnownPolicy` supplied the install-scripts policy that the
+     * in-memory cache could not (`cachePolicy == null && lastKnownPolicy !=
+     * null`). That combination means an earlier auth-failure or 4xx branch wiped
+     * the cache and we fell back to the surviving policy, which is a sign
+     * something went wrong. Emit a WARN (with `orgId` and which branch ran) plus
+     * a low-cardinality counter so it can be alerted on from a dashboard without
+     * digging through logs or traces. `cachePolicy` is passed in (not re-read)
+     * because the 404 branch overwrites `this.cache` before this runs.
+     */
+    signalPolicyFallback(cachePolicy, branch) {
+        if (cachePolicy == null && this.lastKnownPolicy != null) {
+            getLogger().warn("[npm-registry] fell back to the last known install-scripts policy because the cache had been cleared by an earlier auth or 4xx failure", { orgId: this.deps.organizationId, branch });
+            npmRegistryEmitter.recordPolicyFallback(branch);
+        }
+    }
+    /**
+     * Render cached/fetched entries into a config, stamping the machine's current
+     * Superblocks login token onto every proxied registry (`registryUrl` is the
+     * proxy URL the server rewrote each row to). Read fresh each call so the
+     * `.npmrc` the caller writes right after carries a current token. `getJwt()`
+     * resolves immediately when a token is already primed, so this stays cheap on
+     * the cache-hit fast path; it throws only when no token is available, in
+     * which case there is no way to build a working proxy `.npmrc`.
+     */
+    async renderConfig(entries, allowInstallScripts) {
+        const authToken = await this.deps.getJwt();
+        return registriesToConfig(entries, allowInstallScripts, authToken);
+    }
+    /**
+     * Build a `configured` result, but route a JWT-read failure through the same
+     * fail-closed path as `serveStaleOrUnconfigured`. `renderConfig` reads the
+     * login token via `getJwt()`, which can reject (no token primed). A missing
+     * token is the same "we can't build a working proxy `.npmrc`" condition the
+     * stale path already treats as `unreachable`, so both the cache-hit and the
+     * fresh-fetch success paths must resolve it the same way rather than throwing
+     * out of `getConfig()`. With a warm cache this serves last-known-good; with
+     * no usable cache it reports `unreachable`.
+     */
+    async renderConfigured(entries, allowInstallScripts) {
+        let config;
+        try {
+            config = await this.renderConfig(entries, allowInstallScripts);
+        }
+        catch (jwtError) {
+            return this.serveStaleOrUnconfigured(jwtError);
+        }
+        return { source: "configured", config };
+    }
+    async serveStaleOrUnconfigured(error) {
+        if (this.cache && this.cache.entries.length > 0) {
+            const ageMs = this.deps.now() - this.cache.fetchedAt;
+            // Render before logging "serving last-known-good": the proxy config
+            // needs the machine's login token stamped onto every row, and that
+            // read can fail (no JWT). A tokenless proxy `.npmrc` is useless —
+            // every install would 401 against the proxy — so on that failure we
+            // fail closed by falling through to the unreachable path below rather
+            // than handing back a config that can't authenticate.
+            let config;
+            try {
+                config = await this.renderConfig(this.cache.entries, this.cache.npmAllowInstallScripts);
+            }
+            catch (jwtError) {
+                getLogger().warn("[npm-registry] server unreachable and no login token available to render last-known-good config; treating as unreachable", {
+                    ageMs,
+                    error: jwtError instanceof Error ? jwtError.message : String(jwtError),
+                });
+            }
+            if (config) {
+                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,
+                };
+            }
+        }
+        // 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) });
+        this.signalPolicyFallback(this.cache?.npmAllowInstallScripts, "unreachable");
+        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,
+        });
+    }
+}
+/**
+ * Extracts the host portion of a registry URL for use in npm auth lines, e.g.
+ * `https://artifactory.example.com/api/npm/npm-virtual/` ->
+ *   `//artifactory.example.com/api/npm/npm-virtual/`.
+ *
+ * npm matches `_authToken` lines by URL prefix (sans scheme), so we keep the
+ * full path. Trailing slash is normalized. Returns undefined for unparseable
+ * URLs OR URLs that carry userinfo (`user:pass@host`) — userinfo would make
+ * the `registry=` and `_authToken=` lines disagree under npm's URL-prefix
+ * matching rule and would also leak credentials into process logs.
+ */
+function toNpmAuthOrigin(registryUrl) {
+    try {
+        const u = new URL(registryUrl);
+        if (u.username || u.password) {
+            return;
+        }
+        const pathname = u.pathname.endsWith("/") ? u.pathname : `${u.pathname}/`;
+        return `//${u.host}${pathname}`;
+    }
+    catch {
+        return;
+    }
+}
+/**
+ * Normalizes a registry URL to end in exactly one trailing slash so the
+ * `registry=` line and the `_authToken=` host prefix line match exactly under
+ * npm's URL-prefix matching rule. Mirrors the shell script behavior.
+ */
+function normalizeRegistryUrl(registryUrl) {
+    return registryUrl.endsWith("/") ? registryUrl : `${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.
+ *
+ * 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 = {};
+    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, 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;
+            }
+        }
+    }
+    // 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 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()}`;
+    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";
+    }
+}
+/**
+ * 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).
+ *
+ * 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 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;
+    }
+    // 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 });
+}
+/**
+ * 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=<the machine's Superblocks login token>` at the app
+ * root. That token authenticates to the Superblocks npm proxy; the
+ * customer's upstream registry password is held server-side and never
+ * reaches disk. It is still a Superblocks credential, so it must not be
+ * committed. 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 that login `_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, client) {
+    if (!client) {
+        return undefined;
+    }
+    // Force-refresh: this is the `.npmrc` synthesis / install write boundary,
+    // so it must observe an admin clearing or changing the registry
+    // immediately rather than waiting out the TTL. A cleared
+    // registry resolves fresh as `not-configured`, which the branch below
+    // tears down the project `.npmrc` for. The last-known-good fallback on a
+    // server outage still applies — only the cache-hit read is bypassed.
+    const result = await client.getConfig({ forceRefresh: true });
+    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("[project-npmrc] server unreachable with no cached config; .npmrc left unchanged", { path: path.join(dir, ".npmrc") });
+        npmRegistryEmitter.recordSyncProjectNpmrc("skipped-unreachable");
+        return result;
+    }
+    const npmrcPath = path.join(dir, ".npmrc");
+    const backupPath = path.join(dir, NPMRC_DEFAULT_FILENAME);
+    const orgId = client.organizationId;
+    if (!result.config.configured) {
+        // A Superblocks-authored `.npmrc.default` is poisoned (blind snapshot
+        // of our own rewrite), not a safe restore baseline. Drop it before
+        // any restore so we do not re-apply the proxy URL + JWT.
+        const backupRead = await readUtf8File(backupPath);
+        const existingRead = await readUtf8File(npmrcPath);
+        if (backupRead.status === "error" || existingRead.status === "error") {
+            npmRegistryEmitter.recordSyncProjectNpmrc("error");
+            return result;
+        }
+        const backup = backupRead.status === "ok" ? backupRead.content : undefined;
+        const existing = existingRead.status === "ok" ? existingRead.content : undefined;
+        const ours = existing !== undefined &&
+            isSuperblocksAuthoredNpmrcContent(existing, orgId);
+        const cleanBackup = backup !== undefined && !isSuperblocksAuthoredNpmrcContent(backup, orgId);
+        await maybeUnlinkPoisonedNpmrcBackup(backupPath, orgId);
+        // Only restore from a clean (non-Superblocks) backup. Never call restore
+        // when the backup is missing or poisoned: a failed poison unlink would
+        // otherwise re-apply proxy credentials onto ours OR overwrite a
+        // customer-authored file (Bugbot).
+        let outcome;
+        if (ours && !cleanBackup) {
+            await tryUnlinkPath(npmrcPath, "stale Superblocks-authored .npmrc");
+            outcome = await outcomeAfterNotConfiguredMutation({
+                npmrcPath,
+                organizationId: orgId,
+                successOutcome: "deleted-not-configured",
+            });
+        }
+        else if (cleanBackup) {
+            await restoreInitialNpmrc(npmrcPath, backupPath, {
+                // Only unlink when the target is ours. A customer-authored file
+                // without a backup must stay (template / artifactory cases).
+                unlinkTargetWhenBackupMissing: ours,
+            });
+            if (ours) {
+                outcome = await outcomeAfterNotConfiguredMutation({
+                    npmrcPath,
+                    organizationId: orgId,
+                    successOutcome: "restored-not-configured",
+                });
+            }
+            else {
+                outcome = "restored-not-configured";
+            }
+        }
+        else {
+            // !ours && !cleanBackup: leave customer file alone.
+            outcome = "restored-not-configured";
+        }
+        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.
+            //
+            // 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);
+        }
+        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),
+                    });
+                }
+            }
+        }
+        npmRegistryEmitter.recordSyncProjectNpmrc(outcome);
+        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 });
+        npmRegistryEmitter.recordSyncProjectNpmrc("error");
+        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).
+    //
+    // Never snapshot a Superblocks-authored file as the baseline, and drop
+    // a poisoned `.npmrc.default` left by a prior blind snapshot so a later
+    // not-configured restore cannot re-apply credentials.
+    await maybeUnlinkPoisonedNpmrcBackup(backupPath, orgId);
+    const existingForSnapshot = await readUtf8File(npmrcPath);
+    if (existingForSnapshot.status === "error") {
+        npmRegistryEmitter.recordSyncProjectNpmrc("error");
+        return result;
+    }
+    if (existingForSnapshot.status === "ok" &&
+        isSuperblocksAuthoredNpmrcContent(existingForSnapshot.content, orgId)) {
+        getLogger().info("[project-npmrc] refused to snapshot Superblocks-authored .npmrc as baseline", { path: npmrcPath });
+    }
+    else {
+        await snapshotInitialNpmrc(npmrcPath, backupPath);
+    }
+    await writeNpmrc(npmrcPath, result.config);
+    npmRegistryEmitter.recordSyncProjectNpmrc("written");
+    return result;
+}
+/**
+ * Classify on-disk state after a not-configured delete/restore. A non-ENOENT
+ * re-read failure is `error`, not success: absent and "not ours" are the
+ * only success shapes.
+ */
+async function outcomeAfterNotConfiguredMutation(args) {
+    const { npmrcPath, organizationId, successOutcome } = args;
+    const after = await readUtf8File(npmrcPath);
+    if (after.status === "error") {
+        return "error";
+    }
+    if (after.status === "ok" &&
+        isSuperblocksAuthoredNpmrcContent(after.content, organizationId)) {
+        return "error";
+    }
+    return successOutcome;
+}
+async function readUtf8File(filePath) {
+    try {
+        return { status: "ok", content: await readFile(filePath, "utf-8") };
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return { status: "absent" };
+        }
+        getLogger().warn("[project-npmrc] failed to read file; treating as unreadable", {
+            path: filePath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { status: "error" };
+    }
+}
+async function tryUnlinkPath(filePath, label) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return;
+        }
+        getLogger().warn(`[project-npmrc] failed to remove ${label}`, {
+            path: filePath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+async function maybeUnlinkPoisonedNpmrcBackup(backupPath, organizationId) {
+    const backup = await readUtf8File(backupPath);
+    // Absent or unreadable: leave alone. Only unlink when we can confirm
+    // Superblocks authorship.
+    if (backup.status !== "ok" ||
+        !isSuperblocksAuthoredNpmrcContent(backup.content, organizationId)) {
+        return;
+    }
+    await tryUnlinkPath(backupPath, "poisoned Superblocks-authored .npmrc.default");
+}
+/**
+ * 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) 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
+ *     restored after install.
+ *   - `integrity` is preserved (see `stripResolvedFromLockfile`), so any
+ *     cross-registry tarball drift surfaces as a clean `EINTEGRITY` failure
+ *     rather than silent corruption.
+ *
+ * The strip is per-boot, not persisted: a stripped lockfile only reaches DBFS
+ * if the surrounding flow runs an upload. Pods that boot, strip, and exit
+ * without uploading still find the same poisoned lockfile in DBFS on the
+ * next boot. The CI fix in `build-db-migrations.yaml` and `build-dev-server.yaml`
+ * (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 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, client) {
+    return withNpmRegistrySpan(NPM_REGISTRY_SPAN.PREPARE_FOR_PRIVATE_REGISTRY, client?.organizationId
+        ? { [NPM_REGISTRY_SPAN_ATTR.ORG_ID]: client.organizationId }
+        : {}, async (span) => {
+        const result = await maybeWriteNpmrcForDir(dir, client);
+        await stripResolvedFromLockfile(dir);
+        if (result) {
+            span.setAttributes({
+                [NPM_REGISTRY_SPAN_ATTR.SOURCE]: result.source,
+                [NPM_REGISTRY_SPAN_ATTR.REGISTRY_CONFIGURED]: result.config.configured,
+                [NPM_REGISTRY_SPAN_ATTR.REGISTRY_HOST]: bucketNpmRegistryHost(result.config.default?.url),
+                // Tri-valued: true | false | "unknown" (LD flag off / server omitted).
+                [NPM_REGISTRY_SPAN_ATTR.ALLOW_INSTALL_SCRIPTS]: result.config.allowInstallScripts ?? "unknown",
+            });
+        }
+        return result;
+    });
+}
+/**
+ * Removes the `resolved` field from every entry in `.packages` of an npm v2+
+ * lockfile. TS-side counterpart to `scripts/strip-lockfile-resolved.sh`.
+ *
+ * Same goal: npm honors `resolved` URLs verbatim, so a lockfile whose entries
+ * point at registry.npmjs.org keeps fetching from npmjs even after we've
+ * written a private `registry=` line to `.npmrc`. Stripping forces npm to
+ * re-resolve through the active registry.
+ *
+ * Use at runtime for *brownfield* apps — apps imported into Superblocks with
+ * a lockfile baked at customer-side npm install time (typically against
+ * npmjs.org). Greenfield template lockfiles are stripped at image-build time
+ * by the bash script; this function handles the rest.
+ *
+ * Behavior:
+ *   - Strips both `<dir>/package-lock.json` and the hidden
+ *     `<dir>/node_modules/.package-lock.json` if present.
+ *   - No-op when neither file exists (brownfield apps may not have a
+ *     lockfile yet).
+ *   - Idempotent: a second call against an already-stripped file is a no-op.
+ *   - Malformed JSON or wrong shape -> logged warning, file left untouched.
+ *     We don't throw because the consuming `npm install` will surface a
+ *     clearer error on the same lockfile, and an unrelated parse bug here
+ *     should not block the user's install.
+ *   - Atomic: writes via tmp + rename to avoid leaving a partial lockfile on
+ *     crash mid-write.
+ */
+export async function stripResolvedFromLockfile(dir) {
+    await Promise.all([
+        stripResolvedFromLockfilePath(path.join(dir, "package-lock.json")),
+        stripResolvedFromLockfilePath(path.join(dir, "node_modules", ".package-lock.json")),
+    ]);
+}
+export async function stripResolvedFromLockfilePath(lockfilePath) {
+    let raw;
+    try {
+        raw = await readFile(lockfilePath, "utf-8");
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            return;
+        }
+        getLogger().warn("[npm-registry] failed to read lockfile for resolved-strip; skipping", {
+            path: lockfilePath,
+            code,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        getLogger().warn("[npm-registry] lockfile is not valid JSON; skipping resolved-strip", {
+            path: lockfilePath,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        getLogger().warn("[npm-registry] lockfile root is not a JSON object; skipping resolved-strip", { path: lockfilePath });
+        return;
+    }
+    const lockfile = parsed;
+    const packages = lockfile.packages;
+    // npm v1 lockfiles have no .packages object; nothing to strip. Some custom
+    // shapes may also omit it (e.g. fixture lockfiles). Skip silently.
+    if (packages === undefined) {
+        return;
+    }
+    if (!packages || typeof packages !== "object" || Array.isArray(packages)) {
+        getLogger().warn("[npm-registry] lockfile .packages is not an object; skipping resolved-strip", { path: lockfilePath });
+        return;
+    }
+    let mutated = false;
+    for (const entry of Object.values(packages)) {
+        if (entry &&
+            typeof entry === "object" &&
+            !Array.isArray(entry) &&
+            "resolved" in entry) {
+            delete entry.resolved;
+            mutated = true;
+        }
+    }
+    if (!mutated) {
+        return;
+    }
+    // Preserve a trailing newline if the original had one (npm writes its
+    // lockfiles with a trailing newline; matching it minimizes spurious diffs
+    // when the file is later committed back from a customer-side workflow).
+    const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+    const next = JSON.stringify(lockfile, null, 2) + trailingNewline;
+    // Atomic write: tmp + rename. Inherit the original mode where possible so
+    // we don't widen perms on a customer-owned lockfile (npm typically writes
+    // 0644, but we don't assume). If `writeFile` succeeds but `chmod` or
+    // `rename` fails (ENOSPC, EROFS, EXDEV, EACCES), the tmp file gets cleaned
+    // up so successive boots don't accumulate orphans.
+    const tmpPath = `${lockfilePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        await writeFile(tmpPath, next, "utf-8");
+        try {
+            const original = await stat(lockfilePath);
+            await chmod(tmpPath, original.mode & 0o777);
+        }
+        catch {
+            // Best-effort mode parity only; the rewrite itself is what matters.
+        }
+        await rename(tmpPath, lockfilePath);
+    }
+    catch (error) {
+        await unlink(tmpPath).catch(() => { });
+        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", {
+                    error: err instanceof Error ? err.message : String(err),
+                    orgId: opts.organizationId,
+                    path: markerPath,
+                });
+            }
+        },
+        async clearConfigured() {
+            try {
+                await unlink(markerPath);
+                getLogger().info("[npm-registry] removed registry-policy marker", {
+                    orgId: opts.organizationId,
+                    path: markerPath,
+                });
+            }
+            catch (err) {
+                const code = err?.code;
+                if (code !== "ENOENT") {
+                    // The marker may still be on disk, so leave the write guard set.
+                    getLogger().warn("[npm-registry] failed to remove registry-policy marker; ignoring", {
+                        code,
+                        error: err instanceof Error ? err.message : String(err),
+                        orgId: opts.organizationId,
+                        path: markerPath,
+                    });
+                    return;
+                }
+            }
+            // Re-arm the once-per-process write guard so a later `configured`
+            // resolution writes the marker again.
+            marked = false;
+        },
+        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