@omega.js/desktop 0.51.0 → 0.52.0

package/dist/vendor/config/index.js

@@ -43,7 +43,7 @@ const { resolveHook, loadHook } = require('./hooks.js');
 const { toSiteGlobal } = require('./site-global.js');
 const { PLATFORMS, FORMATS, enabledFormats, formatKeys, desktopProductName, sanitizeProductName, desktopArtifactName, desktopArtifactNames } = require('./platforms.js');
 const { resolveWinbackOffer, WINBACK_OFFER_DEFAULTS, WINBACK_DURATIONS } = require('./winback.js');
-const { REPO_PROVIDERS, HOSTING_PROVIDERS, repoBlock, sourceRepo, releasesRepo, websiteRepo, hostingProvider, pagesHost, brandVisibility } = require('./repo.js');
+const { REPO_PROVIDERS, HOSTING_PROVIDERS, repoBlock, sourceRepo, repoDrift, releasesRepo, websiteRepo, hostingProvider, pagesHost, brandVisibility } = require('./repo.js');
 const { isDemoProject } = require('./demo.js');
 const { deriveBundleIdPrefix, composeBundleId } = require('./bundle-id.js');
 const { DEV_FACT_CHANNEL, devFactMissing } = require('./dev-facts.js');
@@ -222,6 +222,10 @@ module.exports = {
   // The SOURCE monorepo `<brand.id>-omega`: the dispatch, the repo secrets, the
   // scaffolded workflows and the CMS commits all address this one
   sourceRepo,
+  // Whether the repo `origin` names IS that source repo (#934): the one
+  // comparison and the one drift line, stated at boot and refused on by the
+  // verbs that act on the derived repo
+  repoDrift,
   // The brand's ONE public releases repo `<brand.id>-releases`, always public:
   // the one home every release reader takes its address from
   releasesRepo,

package/dist/vendor/config/repo.js

@@ -108,6 +108,29 @@ function sourceRepo(config) {
   return derivedRepo(config, 'omega');
 }
 
+/**
+ * Whether the repo a brand's `origin` names IS the source repo its config
+ * derives ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)): the ONE
+ * comparison, and the ONE wording of its answer, for every reader that holds
+ * the two side by side. The boot prelude states it in one line; the manage walk
+ * and the deploy, which act ON the derived repo, refuse with it.
+ *
+ * The WHOLE slug is compared, case-insensitively (GitHub's own comparison), so
+ * a rename drifts as surely as a transfer: an owner-only compare let a renamed
+ * repo through while every reader kept deriving the old name.
+ *
+ * @param {string} originSlug - The origin's `Owner/name`.
+ * @param {object} config - Composed omega config.
+ * @returns {string|null} The drift line, or null when the two agree or the
+ *   config derives no source repo (no org, or no brand id: nothing to compare).
+ */
+function repoDrift(originSlug, config) {
+  const derived = sourceRepo(config);
+  if (!derived || derived.slug.toLowerCase() === originSlug.toLowerCase()) return null;
+
+  return `origin is ${originSlug} but config derives ${derived.slug}: fix repo.org in config/omega.json5 or move the repo`;
+}
+
 /**
  * The brand's ONE public releases repo: `<brand.id>-releases` under the same
  * org, ALWAYS public, because the desktop updater polls it with no token
@@ -256,6 +279,7 @@ module.exports = {
   HOSTING_PROVIDERS,
   repoBlock,
   sourceRepo,
+  repoDrift,
   releasesRepo,
   websiteRepo,
   hostingProvider,

package/dist/vendor/devkit/brand-version.js

@@ -21,12 +21,21 @@
  * mixed @omega.js FAMILY. Same verdict, different subject: that one is about
  * the framework packages a brand installed, this one about the brand's own
  * release number.
+ *
+ * Beside it, the LOCKFILE gate
+ * ([#938](https://github.com/Omega-JS-Stack/omega/issues/938)): the registry
+ * deploy lane ships the brand's own `package-lock.json`, and the runner's
+ * `npm ci` installs exactly what it says, so `assertBrandLockfile` refuses a
+ * lock that disagrees with the manifests' @omega.js specs before anything is
+ * pushed. `brandLockfileDrift` is the read both the gate and the lock
+ * regeneration (`lockfile.js`) share.
  */
 const path = require('path');
 const jetpack = require('fs-jetpack');
 
 const { resolveBrandRoot } = require('../config/index.js');
 const Logger = require('./logger.js');
+const { isRegistrySpec, resolveWanted } = require('./update.js');
 
 const defaultLogger = new Logger('brand-version');
 
@@ -261,4 +270,156 @@ function assertBrandVersion({ dir }) {
   return { brandRoot, name, version };
 }
 
-module.exports = { readBrandVersion, listTargetPackages, bumpBrandVersion, assertBrandVersion, KINDS };
+// The family's scope: the only dependencies the lockfile gate reads.
+const SCOPE = '@omega.js/';
+
+// A registry entry's `resolved` is a URL; a link target, a packed tarball or a
+// directory is a path, which a runner has nothing at.
+const REGISTRY_RESOLVED = /^https?:\/\//;
+
+/**
+ * The lock entry npm would use for `name` as declared by the manifest at
+ * `where`: its own nested copy first, then the hoisted one at the root, the
+ * order node resolves in.
+ *
+ * @param {object} packages - The lock's `packages` map.
+ * @param {string} where - The manifest's dir relative to the root ('' for the root).
+ * @param {string} name - The dependency name.
+ * @returns {string|null} The lock key, or null when neither slot exists.
+ */
+function lockKeyFor(packages, where, name) {
+  const keys = where ? [`${where}/node_modules/${name}`, `node_modules/${name}`] : [`node_modules/${name}`];
+  return keys.find((key) => packages[key]) || null;
+}
+
+/**
+ * Why a lock entry cannot satisfy a registry spec on a runner, or null when it
+ * does.
+ *
+ * @param {object|undefined} entry - The lock entry.
+ * @param {string} spec - The manifest's registry spec.
+ * @returns {string|null} The reason, worded to follow `<name> <spec> `.
+ */
+function entryDrift(entry, spec) {
+  if (!entry) return 'is not in the lock';
+  if (entry.link) return `is locked as a link to ${entry.resolved}`;
+  if (entry.resolved && !REGISTRY_RESOLVED.test(entry.resolved)) return `is locked at the path ${entry.resolved}`;
+  if (resolveWanted(spec, [entry.version]) !== entry.version) return `is locked at ${entry.version || 'no version'}`;
+  return null;
+}
+
+/**
+ * The lock's STALE path entries: a key that names a folder under the root (a
+ * workspace, or a link target) rather than a `node_modules/` slot, where that
+ * folder is not on disk. A renamed target leaves one behind (`targets/website`
+ * after the move to `targets/web`), and npm keeps honoring the dependencies it
+ * declares on every lock-only run.
+ *
+ * @param {object} options
+ * @param {string} options.root - The install root the lock's keys are relative to.
+ * @param {object} options.packages - The lock's `packages` map.
+ * @returns {string[]} The stale keys, nested ones included.
+ */
+function staleLockPaths({ root, packages }) {
+  return Object.keys(packages).filter((key) => key !== ''
+    && !key.split('/').includes('node_modules')
+    && !jetpack.exists(path.join(root, key)));
+}
+
+/**
+ * Every @omega.js registry spec in the brand's manifests (the root and each
+ * `targets/<name>/package.json`) that the brand's OWN lockfile does not
+ * satisfy. Read-only. `file:`/`link:`/git specs are the linked lane's, which
+ * regenerates its lock in the pack step, so only registry specs are read. A
+ * STALE lock entry (`staleLockPaths`) declaring an @omega.js spec that is NOT a
+ * registry one is drift too: npm would re-create the link it names on the next
+ * lock-only run.
+ *
+ * @param {object} options
+ * @param {string} options.root - The install root (a brand root, or a standalone target).
+ * @returns {{ lockPath: string, lock: object|null, drift: Array<{ manifest: string, name: string, spec: string, key: string|null, entry: object|undefined, reason: string }> }}
+ *   `lock` is null when the root has none; `manifest` is the declaring
+ *   manifest's dir relative to the root, `package.json` for the root itself.
+ */
+function brandLockfileDrift({ root }) {
+  const lockPath = path.join(root, 'package-lock.json');
+  const lock = jetpack.exists(lockPath) === 'file' ? jetpack.read(lockPath, 'json') : null;
+  const packages = (lock && lock.packages) || {};
+
+  const manifests = [
+    { where: '', file: path.join(root, 'package.json') },
+    ...listTargetPackages({ brandRoot: root }).map((target) => ({ where: `targets/${target.name}`, file: target.manifest })),
+  ];
+
+  const drift = [];
+
+  for (const { where, file } of manifests) {
+    const pkg = jetpack.read(file, 'json') || {};
+    const declared = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+
+    for (const [name, spec] of Object.entries(declared)) {
+      if (!name.startsWith(SCOPE) || !isRegistrySpec(spec)) continue;
+
+      const key = lockKeyFor(packages, where, name);
+      const entry = key ? packages[key] : undefined;
+      const reason = entryDrift(entry, spec);
+
+      if (reason) drift.push({ manifest: where || 'package.json', name, spec, key, entry, reason });
+    }
+  }
+
+  for (const stale of staleLockPaths({ root, packages })) {
+    const declared = { ...(packages[stale].dependencies || {}), ...(packages[stale].devDependencies || {}) };
+
+    for (const [name, spec] of Object.entries(declared)) {
+      if (!name.startsWith(SCOPE) || isRegistrySpec(spec)) continue;
+
+      // No key: nothing here is the dependency's own entry, and the pruning
+      // of stale paths (lockfile.js) is what removes this one.
+      drift.push({ manifest: stale, name, spec, key: null, entry: undefined, reason: `is declared by a stale lock entry (${stale} is not on disk)` });
+    }
+  }
+
+  return { lockPath, lock, drift };
+}
+
+/**
+ * The deploy gate on the registry lane: the brand's lockfile must exist and
+ * carry every @omega.js registry spec of its manifests as a registry entry at
+ * a version that satisfies it. Read-only, so a dry run runs it too. Agreement
+ * says nothing.
+ *
+ * @param {object} options
+ * @param {string} options.root - The brand root the lane snapshots.
+ * @returns {void}
+ * @throws {Error} A refusal naming each disagreeing entry and `omega i live`.
+ */
+function assertBrandLockfile({ root }) {
+  const { lockPath, lock, drift } = brandLockfileDrift({ root });
+  const fix = '  fix: run `omega i live` in the brand, which regenerates the brand\'s own lockfile from its manifests (#938)';
+
+  if (!lock) {
+    throw refusal(
+      `${root} has no package-lock.json, and the deploy runner installs with \`npm ci\`, which needs one.\n${fix}`,
+    );
+  }
+
+  if (drift.length) {
+    throw refusal(
+      `${lockPath} disagrees with the manifests, and the deploy runner's \`npm ci\` installs the lock:\n`
+      + drift.map((item) => `  ${item.manifest}: ${item.name} ${item.spec} ${item.reason}\n`).join('')
+      + fix,
+    );
+  }
+}
+
+module.exports = {
+  readBrandVersion,
+  listTargetPackages,
+  bumpBrandVersion,
+  assertBrandVersion,
+  staleLockPaths,
+  brandLockfileDrift,
+  assertBrandLockfile,
+  KINDS,
+};

package/dist/vendor/devkit/deploy.js

@@ -14,6 +14,7 @@ const { execSync, execFileSync } = require('node:child_process');
 
 const { findBrandRoot, discoverTargets, frameworkPackagesOf } = require('./local.js');
 const { stageLocalPackages, STAGING_DIR } = require('./pack-local.js');
+const { assertBrandLockfile } = require('./brand-version.js');
 const {
   pushSnapshot,
   pushWorkflowFiles,
@@ -27,7 +28,8 @@ const {
 } = require('./deploy-snapshot.js');
 // The remote-url parse this module published before the boot prelude needed it
 // too (#890): it lives in the remote boundary now, re-exported here unchanged.
-const { parseRemoteUrl } = require('./git-remote.js');
+// The origin gate (#934) lives there too, beside the one origin read.
+const { parseRemoteUrl, assertOriginMatches } = require('./git-remote.js');
 
 const API_BASE = 'https://api.github.com';
 
@@ -213,6 +215,8 @@ function laneLabel(lane, snapshot) {
 // `deploy-precheck` uses): the tests drive the order without a push, a pack or
 // a network call, and the defaults are the real modules.
 const LANE_STEPS = {
+  origin: (options) => assertOriginMatches({ dir: options.root }),
+  lockfile: assertBrandLockfile,
   defaultBranch: defaultBranchOf,
   heal: healDefaultBranch,
   behind: assertNotBehind,
@@ -223,6 +227,42 @@ const LANE_STEPS = {
   wait: waitForWorkflow,
 };
 
+/**
+ * The origin gate ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)):
+ * a brand whose `origin` names another repo than the source repo its config
+ * derives refuses, because every lane acts on the DERIVED repo (the snapshot
+ * push, the workflow compose, the dispatch). It runs on every lane, the
+ * dispatch-only one included: a brand outside git has no origin to disagree,
+ * which the gate answers as nothing to compare. Read-only, so the dry run runs
+ * it too.
+ *
+ * @param {object} lane - The resolved lane.
+ * @param {object} steps - The lane steps (`origin` is the gate).
+ * @returns {void}
+ * @throws {Error} The drift line, naming `repo.org`.
+ */
+function checkLaneOrigin(lane, steps) {
+  steps.origin({ root: lane.brandRoot });
+}
+
+/**
+ * The lockfile gate, where the lane ships the brand's OWN lock
+ * ([#938](https://github.com/Omega-JS-Stack/omega/issues/938)): a registry
+ * (unlinked) snapshot. A linked lane regenerates its lock in the pack step, and
+ * a lane with no snapshot ships nothing, so neither has a lock of its own to
+ * check. Read-only, so the dry run runs it too.
+ *
+ * @param {object} lane - The resolved lane.
+ * @param {object} steps - The lane steps (`lockfile` is the gate).
+ * @returns {void}
+ * @throws {Error} The gate's refusal, naming `omega i live`.
+ */
+function checkLaneLockfile(lane, steps) {
+  if (lane.mode === 'snapshot' && !lane.linked) {
+    steps.lockfile({ root: lane.brandRoot });
+  }
+}
+
 /**
  * The DELIVERY half of a lane: how this brand's code reaches GitHub before the
  * dispatch that runs it. ONE implementation for its two callers
@@ -233,6 +273,13 @@ const LANE_STEPS = {
  *
  * What the lane delivers, in order
  * ([#915](https://github.com/Omega-JS-Stack/omega/issues/915)):
+ * 0. on EVERY lane, the ORIGIN gate
+ *    ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)): a checkout
+ *    whose `origin` is not the derived source repo refuses before this lane
+ *    writes to that repo; then, on a registry (unlinked) lane, the LOCKFILE gate
+ *    ([#938](https://github.com/Omega-JS-Stack/omega/issues/938)): the runner's
+ *    `npm ci` installs the brand's lock as pushed, so one that disagrees with
+ *    the manifests refuses here, before a branch is healed or a file written;
  * 1. the DEFAULT branch read once, and healed when published output has taken
  *    it over ([#922](https://github.com/Omega-JS-Stack/omega/issues/922)): a
  *    `gh-pages` default moves back to `main` here, before step 2 writes a
@@ -271,10 +318,14 @@ async function deliverLane(options) {
   const steps = { ...LANE_STEPS, ...(options.steps || {}) };
   const ref = options.ref || lane.ref;
 
+  checkLaneOrigin(lane, steps);
+
   if (lane.mode !== 'snapshot') {
     return { sha: null };
   }
 
+  checkLaneLockfile(lane, steps);
+
   // Read ONCE, used twice: the branch a behind checkout is measured against,
   // and the branch the composed workflows are pushed to. Null is a repo GitHub
   // does not have yet, and the snapshot push below is where that says itself.
@@ -428,9 +479,19 @@ async function deployViaDispatch(options) {
     inputs: options.inputs,
   });
 
+  const steps = { ...LANE_STEPS, ...(options.steps || {}) };
+
   if (options.dryRun) {
+    // The origin and lockfile gates only read, so a dry run refuses what the
+    // real run would (#934, #938), as the version gate already does.
+    if (lane) {
+      checkLaneOrigin(lane, steps);
+      checkLaneLockfile(lane, steps);
+    }
+
     // The plan IS the dry run, the lane included: what would happen, with
-    // neither git nor the network touched. The workflow half of it is read off
+    // nothing written to git and the network untouched (the gates above only
+    // read). The workflow half of it is read off
     // DISK (the scaffold has already composed this run's files), so the preview
     // names them and the branch they would go to without asking GitHub which of
     // them differ (#915).
@@ -446,7 +507,6 @@ async function deployViaDispatch(options) {
   }
 
   const token = options.token || resolveToken({ env: options.env, execFn: options.execFn });
-  const steps = { ...LANE_STEPS, ...(options.steps || {}) };
 
   if (lane && lane.mode === 'snapshot' && options.snapshot) {
     // The brand root pushed this run's snapshot ONCE, before it spawned a
@@ -539,7 +599,7 @@ function findLocalSpecs(options = {}) {
  * - NESTED: the brand root is not the toplevel of the git repo it sits in (a
  *   brand inside this monorepo), so its git toplevel is somebody else's repo:
  *   the behind check has nothing to compare, and the secrets publisher skips
- *   its remote-mismatch guard.
+ *   its origin gate.
  * - LINKED: the brand tree carries a `file:` @omega.js spec anywhere. A runner
  *   can install none of those, so the packed tarballs have to travel with the
  *   snapshot.

package/dist/vendor/devkit/git-remote.js

@@ -6,7 +6,10 @@
  * pack and snapshot modules: 40ms nothing on the CLI BOOT path can spend for
  * one regex. The boot prelude that heals a redirected `origin` needs the parse
  * plus the two git calls around it, so the three live here, in one place, and
- * `deploy.js` re-exports the parse it already published.
+ * `deploy.js` re-exports the parse it already published. The brand's own origin,
+ * read once for the prelude, the manage walk and the deploy alike, and the
+ * refusal the latter two raise when it disagrees with the config, live here too
+ * ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
  *
  * Transport: `git` through execFile with an ARGV ARRAY, never a shell string,
  * so a remote url can never inject a command. Every call names its directory
@@ -15,7 +18,9 @@
  * remote.
  */
 
+const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const jetpack = require('fs-jetpack');
 
 /**
  * Parse a git remote URL into { owner, repo }.
@@ -87,9 +92,81 @@ function setRemoteUrl(options) {
   execFn('git', args, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
 }
 
+/**
+ * A brand's OWN `origin`, read and parsed: the one read the boot prelude, the
+ * manage walk and the deploy share
+ * ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
+ *
+ * The `.git` must sit AT the directory, answered by one stat before git is
+ * asked anything: a brand nested in another repo (a fixture brand inside this
+ * monorepo, a target checked out under someone else's tree) has no origin of
+ * its own, and reading the ENCLOSING repo's would compare, heal or refuse on a
+ * repo the brand is not. No origin, and an origin that is not a GitHub remote,
+ * are expected conditions (a checkout nobody has pushed yet, a brand hosted
+ * elsewhere), so each answers its reason rather than throwing.
+ *
+ * @param {object} options
+ * @param {string} options.dir - The brand root.
+ * @param {function} [options.execFn] - Injectable `(file, args, opts) => stdout` (tests).
+ * @returns {{ url: string, owner: string, repo: string, slug: string }|{ reason: 'no-git'|'no-origin'|'foreign-remote' }}
+ */
+function readOrigin(options) {
+  if (!jetpack.exists(path.join(options.dir, '.git'))) return { reason: 'no-git' };
+
+  let url;
+  try {
+    url = remoteUrl({ dir: options.dir, execFn: options.execFn });
+  } catch (e) {
+    return { reason: 'no-origin' };
+  }
+
+  const parsed = parseRemoteUrl(url);
+  if (!parsed) return { reason: 'foreign-remote' };
+
+  return { url, owner: parsed.owner, repo: parsed.repo, slug: `${parsed.owner}/${parsed.repo}` };
+}
+
+/**
+ * Refuse when the brand's `origin` names another repo than the source repo its
+ * config derives ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
+ * Called by the verbs that ACT on the derived repo (the manage walk's repo
+ * service, the deploy lane), which would otherwise ensure or push to a repo the
+ * checkout does not point at. The boot prelude only states the same line: it
+ * runs before every verb, and a fatal boot would lock out the verbs that fix it.
+ *
+ * Nothing to compare is no refusal: a brand with no origin of its own (see
+ * `readOrigin`), and a config that derives no source repo.
+ *
+ * @param {object} options
+ * @param {string} options.dir - The brand root.
+ * @param {object} [options.config] - The composed config. Omitted, the brand's
+ *   PRODUCTION config is loaded from `dir` (the one every deploy address reads,
+ *   [#856](https://github.com/Omega-JS-Stack/omega/issues/856)), and only once
+ *   an origin exists to compare it with.
+ * @param {function} [options.execFn] - Injectable git exec (tests).
+ * @returns {object} The `readOrigin` answer it compared (or had nothing to
+ *   compare with), so a caller that treats a missing origin its own way reads
+ *   the reason without a second read.
+ * @throws {Error} The drift line, from `@omega.js/config`'s `repoDrift`.
+ */
+function assertOriginMatches(options) {
+  const origin = readOrigin(options);
+  if (!origin.slug) return origin;
+
+  const { loadConfig, repoDrift } = require('../config/index.js');
+  const config = options.config || loadConfig(options.dir, null, { environment: 'production' }).config;
+  const drift = repoDrift(origin.slug, config);
+
+  if (drift) throw new Error(drift);
+
+  return origin;
+}
+
 module.exports = {
   parseRemoteUrl,
   retargetRemoteUrl,
   remoteUrl,
   setRemoteUrl,
+  readOrigin,
+  assertOriginMatches,
 };

package/dist/vendor/devkit/local.js

@@ -261,6 +261,33 @@ function relativeSpecPath(fromDir, target) {
   return path.relative(fs.realpathSync(fromDir), fs.realpathSync(target)).split(path.sep).join('/');
 }
 
+/**
+ * Regenerate the install root's OWN lockfile after a flip (#938): inside the
+ * omega monorepo the tree install climbs to the monorepo root and writes that
+ * lockfile, so the brand's would stay stale. Loaded here rather than at the top:
+ * this module runs at every CLI boot (freshnessBoot), and the lockfile read
+ * pulls in @omega.js/config, which the boot has no use for.
+ * @param {string} installRoot - The brand root (or standalone target).
+ * @param {object} [logger] - Logger with log (silent when omitted).
+ * @returns {Promise<void>}
+ */
+function regenerateBrandLockfile(installRoot, logger) {
+  const { regenerateLockfile } = require('./lockfile.js');
+  return regenerateLockfile({ root: installRoot, log: logger ? (line) => logger.log(line) : undefined });
+}
+
+/**
+ * Whether the install root's lockfile is missing or disagrees with its
+ * manifests' @omega.js registry specs: the deploy gate's own read (#938).
+ * @param {string} installRoot - The brand root (or standalone target).
+ * @returns {boolean}
+ */
+function brandLockfileStale(installRoot) {
+  const { brandLockfileDrift } = require('./brand-version.js');
+  const { lock, drift } = brandLockfileDrift({ root: installRoot });
+  return !lock || drift.length > 0;
+}
+
 /**
  * file:-install a brand's @omega.js dependencies from the local monorepo.
  *
@@ -275,7 +302,8 @@ function relativeSpecPath(fromDir, target) {
  * targets degenerate to themselves.
  *
  * Idempotent: dependencies already resolving to the monorepo copy are
- * skipped, and when nothing needs linking no install runs.
+ * skipped, and when nothing needs linking no install runs. An install is
+ * followed by the brand's OWN lockfile regeneration (#938).
  * @param {object} options
  * @param {string} options.dir - Target directory to link from (any target in the brand).
  * @param {string} options.monorepoRoot - Monorepo root path.
@@ -347,6 +375,11 @@ async function linkLocalPackages(options) {
       logger && logger.warn(`install failed — restored ${manifestBackups.size} manifest(s) to their pre-link specs`);
       throw error;
     }
+
+    // Outside the rollback: the install succeeded, so the manifests and the
+    // tree already agree, and restoring the manifests now would split them.
+    // A failed regeneration puts the lock back itself and throws as what it is.
+    await regenerateBrandLockfile(installRoot, logger);
   }
 
   return actions;
@@ -364,7 +397,9 @@ async function linkLocalPackages(options) {
  * @omega.js/client in one brand. An explicit `range` still wins verbatim — the
  * caller owns that string. Idempotent: registry-spec'd entries are untouched;
  * nothing to flip → no install. Same transactional manifest restore as the
- * linker when the install fails.
+ * linker when the install fails. Either way the brand's OWN lockfile ends up
+ * agreeing with the manifests (#938): regenerated after the install, and
+ * regenerated alone when nothing flipped but the lock still disagrees.
  * @param {object} options
  * @param {string} options.dir - Any directory inside the brand.
  * @param {object} [options.logger] - Logger with log/warn (silent when omitted).
@@ -416,7 +451,11 @@ async function restoreRegistrySpecs(options) {
     }
   }
 
-  if (installNeeded && !dryRun) {
+  if (dryRun) {
+    return actions;
+  }
+
+  if (installNeeded) {
     try {
       await safeInstall('npm install', { log: true, config: { cwd: installRoot } });
     } catch (error) {
@@ -426,6 +465,15 @@ async function restoreRegistrySpecs(options) {
       logger && logger.warn(`install failed — restored ${manifestBackups.size} manifest(s) to their file: specs`);
       throw error;
     }
+
+    // Outside the rollback, as in linkLocalPackages: the flipped manifests and
+    // the installed tree agree, so only the lock is left to heal.
+    await regenerateBrandLockfile(installRoot, logger);
+  } else if (brandLockfileStale(installRoot)) {
+    // Nothing to flip, but the lock still disagrees (the specs were flipped
+    // before the lock was ever regenerated): this verb is the fix the deploy's
+    // lockfile gate names, so it heals the lock here too (#938).
+    await regenerateBrandLockfile(installRoot, logger);
   }
 
   return actions;