@omega.js/desktop 0.51.0 → 0.52.0

package/dist/vendor/devkit/lockfile.js

@@ -0,0 +1,127 @@
+/**
+ * lockfile: regenerate an install root's OWN package-lock.json
+ * ([#938](https://github.com/Omega-JS-Stack/omega/issues/938)).
+ *
+ * ONE helper for its three callers: the pack step (`pack-local`, the staged
+ * shape), `omega i local` (`linkLocalPackages`) and `omega i live`
+ * (`restoreRegistrySpecs`).
+ *
+ * Two things a plain `npm install` gets wrong here, and this answers both:
+ *   - `--prefix` makes npm treat `root` as the install root. Without it, npm in
+ *     a directory that is itself a WORKSPACE of an outer root (every in-repo
+ *     brand, under the omega monorepo's `brands/*`) climbs to that outer root
+ *     and writes ITS lockfile, leaving the brand's own untouched.
+ *   - npm KEEPS a locked link whose target's version satisfies a registry spec,
+ *     so a lock from the local era (`link: true` into a checkout already at the
+ *     published number) would survive the flip. Every @omega.js entry the
+ *     deploy gate would refuse (`brandLockfileDrift`) is dropped first, with its
+ *     link target, so npm resolves those afresh and keeps every other pin.
+ *   - npm also honors a STALE path entry, a folder the lock names that is no
+ *     longer on disk (a renamed target), and re-creates whatever link its
+ *     dependencies declare. Those entries go first, with everything under them
+ *     and every `node_modules/` link pointing into them.
+ *
+ * Transactional: a failed npm run writes the lock back byte for byte.
+ */
+const fs = require('fs');
+const path = require('path');
+const jetpack = require('fs-jetpack');
+
+const { safeInstall } = require('./safe-install.js');
+const { brandLockfileDrift, staleLockPaths } = require('./brand-version.js');
+
+/** A path equal to base, or nested beneath it. */
+const under = (value, base) => value === base || value.startsWith(`${base}/`);
+
+/**
+ * Drop every stale path entry (`staleLockPaths`), everything nested under it,
+ * and every `node_modules/` entry whose `resolved` points into it.
+ *
+ * @param {object} lock - The parsed lock (mutated).
+ * @param {string} root - The install root the keys are relative to.
+ * @returns {string[]} The stale paths dropped (the outermost of each tree).
+ */
+function dropStalePaths(lock, root) {
+  const stale = staleLockPaths({ root, packages: lock.packages });
+  const outermost = stale.filter((key) => !stale.some((other) => other !== key && under(key, other)));
+
+  for (const [key, entry] of Object.entries(lock.packages)) {
+    const pointsInto = entry && typeof entry.resolved === 'string' && outermost.some((base) => under(entry.resolved, base));
+    if (outermost.some((base) => under(key, base)) || pointsInto) delete lock.packages[key];
+  }
+
+  return outermost;
+}
+
+/**
+ * Drop every lock entry `drift` names, plus a dropped link's target entry and
+ * everything nested under it (the checkout's own dependencies).
+ *
+ * @param {object} lock - The parsed lock (mutated).
+ * @param {Array<{ key: string|null, entry: object|undefined }>} drift - What the gate refused.
+ * @returns {string[]} The names whose entries were dropped.
+ */
+function dropDrift(lock, drift) {
+  const dropped = [];
+
+  for (const { name, key, entry } of drift) {
+    // An absent entry has nothing to drop (npm adds it from the manifest), and
+    // one inside a stale path is already gone with it.
+    if (!key || !lock.packages[key]) continue;
+
+    delete lock.packages[key];
+    dropped.push(name);
+
+    if (entry.link && entry.resolved) {
+      for (const other of Object.keys(lock.packages)) {
+        if (under(other, entry.resolved)) delete lock.packages[other];
+      }
+    }
+  }
+
+  return dropped;
+}
+
+/**
+ * Regenerate `root`'s package-lock.json from its manifests, lock-only: no
+ * scripts, no node_modules writes.
+ *
+ * @param {object} options
+ * @param {string} options.root - The install root whose lock is regenerated.
+ * @param {function} [options.log] - Line sink (silent when omitted).
+ * @returns {Promise<void>}
+ */
+async function regenerateLockfile({ root, log }) {
+  const { lockPath, lock, drift } = brandLockfileDrift({ root });
+  const original = lock ? jetpack.read(lockPath) : null;
+
+  if (lock && lock.packages) {
+    const pruned = dropStalePaths(lock, root);
+    const dropped = dropDrift(lock, drift);
+
+    if (pruned.length || dropped.length) {
+      jetpack.write(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+    }
+    if (log && pruned.length) log(`Pruned the lock entries of folders no longer on disk (${pruned.join(', ')}) so npm stops honoring what they declare`);
+    if (log && dropped.length) log(`Dropped the stale lock entries of ${dropped.join(', ')} so npm resolves them from the manifests`);
+  }
+
+  if (log) log(`Regenerating ${path.basename(root)}/package-lock.json...`);
+
+  // The REAL path: npm writes a link's `resolved` relative to the physical
+  // directory, so a prefix spelled through an alias (macOS /var for
+  // /private/var, a symlinked brand dir) reads those paths from the wrong place.
+  const prefix = fs.realpathSync(root);
+
+  try {
+    await safeInstall(
+      `npm install --package-lock-only --ignore-scripts --no-audit --no-fund --prefix "${prefix}"`,
+      { log: false, config: { cwd: prefix } },
+    );
+  } catch (error) {
+    if (original !== null) jetpack.write(lockPath, original);
+    throw error;
+  }
+}
+
+module.exports = { regenerateLockfile };

package/dist/vendor/devkit/pack-local.js

@@ -47,6 +47,7 @@ const path = require('path');
 const jetpack = require('fs-jetpack');
 const powertools = require('node-powertools');
 const chalk = require('chalk').default;
+const { regenerateLockfile } = require('./lockfile.js');
 
 // Constants
 const STAGING_DIR = 'omega_modules';
@@ -369,15 +370,11 @@ async function stageLocalPackages({ dir, log = () => {} }) {
     }
 
     // A remote install runs `npm ci`, so the uploaded lockfile must match the
-    // staged shape. `--prefix` is what makes npm treat THIS dir as the install
-    // root: run inside a workspace it would otherwise climb to the workspace
-    // root and write that one's lockfile instead.
+    // staged shape, regenerated from scratch (the one helper keeps it THIS
+    // dir's lock, never an enclosing workspace root's).
     log(`  ${chalk.dim('→')} Regenerating package-lock.json for the staged shape...`);
     jetpack.remove(lockPath);
-    await powertools.execute(
-      `npm install --package-lock-only --ignore-scripts --no-audit --no-fund --prefix "${root}"`,
-      { log: false, config: { cwd: root } },
-    );
+    await regenerateLockfile({ root });
   } catch (error) {
     // Loud and clean: the deploy stops here, and the tree goes back exactly as
     // it was rather than sitting half-staged.

package/dist/vendor/devkit/preludes/origin-heal.js

@@ -32,21 +32,22 @@
  *   - anything else: the remote is rewritten to the answered `full_name`,
  *     keeping its own url form, and the heal is stated in one line.
  *
- * Then DRIFT, on whatever the answer was: `repo.org` stays the one typed value
- * in `config/omega.json5`, and an owner GitHub reports that differs from it is
- * stated in one line and nothing more. The prelude never writes config: which
- * of the two is wrong (the config, or where the repo lives) is a human's call,
- * and the manager's repo service only ensures repos UNDER `repo.org`.
+ * Then DRIFT, on whatever the answer was: the WHOLE slug GitHub answers against
+ * the source repo the config derives (`@omega.js/config`'s `repoDrift`, so a
+ * rename drifts as surely as a transfer,
+ * [#934](https://github.com/Omega-JS-Stack/omega/issues/934)), stated in one
+ * line and nothing more. Never fatal: this runs before every verb, and a fatal
+ * boot would lock out the verbs that fix the mismatch. The verbs that ACT on
+ * the derived repo (the manage walk, the deploy) refuse on the same line
+ * instead. The prelude never writes config: which of the two is wrong (the
+ * config, or where the repo lives) is a human's call.
  *
  * The WRITE is the one thing that fails loudly: a `git remote set-url` refused
  * after a `get-url` just answered is not an external condition, it is a broken
  * invariant, and the runner stops the boot on it.
  */
 
-const path = require('node:path');
-const jetpack = require('fs-jetpack');
-
-const { parseRemoteUrl, retargetRemoteUrl, remoteUrl, setRemoteUrl } = require('../git-remote.js');
+const { readOrigin, retargetRemoteUrl, setRemoteUrl } = require('../git-remote.js');
 const github = require('../github-repo.js');
 
 // The one network read runs on EVERY verb boot, so a network that hangs (a
@@ -61,7 +62,7 @@ const GITHUB_READ_TIMEOUT_MS = 10000;
  * @param {function} [context.execFn] - Injectable git exec (tests).
  * @param {function} [context.resolveRepo] - Injectable `(owner, name) => repo|null` (tests).
  * @param {function} [context.log] - Injectable line printer (tests).
- * @returns {{ healed: boolean, reason?: string, from?: string, to?: string, drift?: { owner: string, org: string } }}
+ * @returns {{ healed: boolean, reason?: string, from?: string, to?: string, drift?: { origin: string, derived: string } }}
  */
 function run(context = {}) {
   const { brandRoot, execFn } = context;
@@ -72,21 +73,12 @@ function run(context = {}) {
 
   if (!brandRoot) return { healed: false, reason: 'no-brand' };
 
-  // One stat, before anything else: most boots in this monorepo's own trees and
-  // in every fixture brand end here.
-  if (!jetpack.exists(path.join(brandRoot, '.git'))) return { healed: false, reason: 'no-git' };
+  // One stat before anything else (most boots in this monorepo's own trees and
+  // in every fixture brand end there), then the remote itself.
+  const current = readOrigin({ dir: brandRoot, execFn });
+  if (!current.slug) return { healed: false, reason: current.reason };
 
-  let url;
-  try {
-    url = remoteUrl({ dir: brandRoot, execFn });
-  } catch (e) {
-    return { healed: false, reason: 'no-origin' };
-  }
-
-  const current = parseRemoteUrl(url);
-  if (!current) return { healed: false, reason: 'foreign-remote' };
-
-  const from = `${current.owner}/${current.repo}`;
+  const { url, slug: from } = current;
 
   // The ONE network read, on the slug the checkout carries: GitHub follows its
   // own redirect and names where that repo lives now.
@@ -109,44 +101,38 @@ function run(context = {}) {
     result = { healed: true, from, to };
   }
 
-  const drift = configDrift(brandRoot, context.config, to.split('/')[0]);
+  const config = composedConfig(brandRoot, context.config);
+  const { repoDrift, sourceRepo } = require('../../config/index.js');
+  const drift = config ? repoDrift(to, config) : null;
+
   if (drift) {
-    log(`omega: origin lives under ${drift.owner} but repo.org is ${drift.org}: fix repo.org in config/omega.json5 or move the repo`);
-    result.drift = drift;
+    log(`omega: ${drift}`);
+    result.drift = { origin: to, derived: sourceRepo(config).slug };
   }
 
   return result;
 }
 
 /**
- * The gap between where the repo LIVES and the org the config types, or null
- * when there is none to state. The config is loaded here when the caller has
- * none, and an unloadable one answers "no drift": a config the boot cannot read
- * is the VERB's failure to report, in its own words, never a prelude's. A brand
- * declaring no `repo` block types no org, so there is nothing to disagree with.
+ * The composed config the drift is read against: the caller's when it has one,
+ * else loaded here, and an unloadable one answers null ("no drift"): a config
+ * the boot cannot read is the VERB's failure to report, in its own words, never
+ * a prelude's.
  *
  * @param {string} brandRoot - The brand root.
  * @param {object} [config] - The composed config, when the caller has it.
- * @param {string} owner - The owner GitHub resolved the repo under.
- * @returns {{ owner: string, org: string }|null}
+ * @returns {object|null}
  */
-function configDrift(brandRoot, config, owner) {
-  const { loadConfig, repoBlock } = require('../../config/index.js');
+function composedConfig(brandRoot, config) {
+  if (config) return config;
 
-  let block;
-  if (config) {
-    block = repoBlock(config);
-  } else {
-    try {
-      block = repoBlock(loadConfig(brandRoot).config);
-    } catch (e) {
-      return null;
-    }
-  }
-
-  if (!block || block.org.toLowerCase() === owner.toLowerCase()) return null;
+  const { loadConfig } = require('../../config/index.js');
 
-  return { owner, org: block.org };
+  try {
+    return loadConfig(brandRoot).config;
+  } catch (e) {
+    return null;
+  }
 }
 
 module.exports = {

package/dist/vendor/devkit/target-secrets.js

@@ -31,7 +31,10 @@
  *      config (`repo.org`, the SOURCE repo). An inferred git remote is not proof: a
  *      target vendored into a framework/test monorepo, a cloned starter still
  *      pointing at the template author, or any fork would publish this brand's
- *      `.env` to a stranger's Actions.
+ *      `.env` to a stranger's Actions. A checkout that could be the brand's own
+ *      and whose origin names another repo REFUSES on `repoDrift`'s one line
+ *      ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)), the
+ *      same refusal the deploy lane and the manage walk make.
  *   4. PUBLISH — each collected key becomes a repo Actions secret via devkit's
  *      `gh` boundary (values on stdin, never logged).
  *
@@ -70,11 +73,12 @@
  * sends nothing. The refusal still THROWS in a dry run: a plan that cannot be
  * made is loud.
  */
-const { composeTargetEnv, loadConfig } = require('../config/index.js');
+const { composeTargetEnv, loadConfig, sourceRepo } = require('../config/index.js');
 const { publishSecretKeys } = require('../config/env-delivery.js');
 const { checkEnvRules } = require('../config/env-rules.js');
 const { publishActionsSecrets } = require('./actions-secrets.js');
-const { resolveRepo, resolveDeployLane } = require('./deploy.js');
+const { assertOriginMatches } = require('./git-remote.js');
+const { findBrandRoot } = require('./local.js');
 const { targetSeams } = require('./target-seams.js');
 
 /**
@@ -200,26 +204,18 @@ function missingRequiredSecrets(options) {
 }
 
 /**
- * The brand's SOURCE repo as `owner/name`, from the target's resolved config:
- * the one the workflows and their secrets live on, derived as
- * `<brand.id>-omega` under `repo.org` (#883). Null when the config declares
- * nothing usable or doesn't load.
+ * The target's resolved PRODUCTION config, like every other read this publish
+ * makes (#895): the repo a release's secrets belong to is the one the
+ * production config names. Null when it doesn't load.
  *
  * @param {object} options
  * @param {string} options.targetDir - The target root.
  * @param {string} options.target - Target name ('web', 'extension', …).
- * @returns {string|null}
+ * @returns {object|null}
  */
-function declaredBrandRepo(options) {
+function productionConfig(options) {
   try {
-    const { loadConfig, sourceRepo } = require('../config/index.js');
-    // PRODUCTION, like every other read this publish makes (#895): the repo a
-    // release's secrets belong to is the one the production config names.
-    const { config } = loadConfig(options.targetDir, options.target, { environment: 'production' });
-    if (!config) return null;
-
-    const source = sourceRepo(config);
-    return source ? source.slug : null;
+    return loadConfig(options.targetDir, options.target, { environment: 'production' }).config || null;
   } catch (e) {
     return null;
   }
@@ -241,7 +237,6 @@ function declaredBrandRepo(options) {
  * @param {Object<string, string>} [options.extraSecrets] - Override for the
  *   target's already-valued keys, merged OVER the composed set (tests).
  * @param {function} [options.execFn] - Injectable `gh` exec (tests).
- * @param {function} [options.gitExecFn] - Injectable `git` exec for remote discovery (tests).
  * @returns {{ skipped: string }|{ planned: string[] }|{ published: string[], failed: Array<object> }}
  */
 function publishTargetSecrets(options) {
@@ -297,38 +292,32 @@ function publishTargetSecrets(options) {
     return { skipped: 'no-secrets' };
   }
 
-  const declared = declaredBrandRepo({ targetDir, target });
-  if (!declared) {
+  const config = productionConfig({ targetDir, target });
+  const source = config ? sourceRepo(config) : null;
+  if (!source) {
     logger.warn('Skipping secret publication: this brand names no GitHub repo in config (repo.org). Set it, then re-run `omega deploy`.');
     return { skipped: 'no-declared-repo' };
   }
 
-  // A NESTED brand (its root is not the toplevel of the git repo it sits in)
-  // has a remote that answers the ENCLOSING repo by construction, and its
-  // deploy pushes a snapshot to the DECLARED repo regardless
-  // ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)), so the
-  // mismatch guard would only ever skip a publish that is correct. Every other
-  // guard stays: what the guard protects against is a checkout that COULD have
-  // been the brand's own and is not.
-  const { nested } = resolveDeployLane({ dir: targetDir, execFn: options.gitExecFn });
-  const repo = declared;
-
-  if (!nested) {
-    let remote;
-    try {
-      const { owner, repo: name } = resolveRepo({ cwd: targetDir, execFn: options.gitExecFn });
-      remote = `${owner}/${name}`;
-    } catch (e) {
-      logger.warn(`Skipping secret publication — no GitHub remote here (${e.message})`);
-      return { skipped: 'no-remote' };
-    }
-
-    if (declared.toLowerCase() !== remote.toLowerCase()) {
-      logger.warn(`Skipping secret publication — the git remote here is ${remote}, but this brand's repo is ${declared}. Run \`omega deploy\` from the brand's own checkout.`);
-      return { skipped: 'repo-mismatch' };
-    }
+  // The ONE origin gate the deploy lane and the manage walk use
+  // ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)): the brand
+  // root's own origin (the local remote, which the boot prelude has already
+  // healed onto GitHub's redirect) must BE the derived source repo, or the
+  // publish REFUSES on the one drift line, because arming a repo that is not
+  // the derived one is the harm itself. No `.git` AT the brand root is nothing
+  // to compare: a NESTED brand's remote is the enclosing repo's by
+  // construction, and its deploy pushes to the derived repo regardless
+  // ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). A checkout
+  // with no GitHub origin (nobody pushed it yet, or it is hosted elsewhere) has
+  // no repo to arm, so it skips.
+  const origin = assertOriginMatches({ dir: findBrandRoot(targetDir), config });
+  if (origin.reason === 'no-origin' || origin.reason === 'foreign-remote') {
+    logger.warn(`Skipping secret publication: no GitHub remote here (${origin.reason})`);
+    return { skipped: 'no-remote' };
   }
 
+  const repo = source.slug;
+
   // The PLAN, and nothing else (#895): what the composition answered, by NAME.
   // It runs after the refusal and the two guards above on purpose, so a dry run
   // is a real preview of whether the deploy would publish at all: every one of
@@ -347,4 +336,4 @@ function publishTargetSecrets(options) {
   return result;
 }
 
-module.exports = { collectTargetSecrets, declaredBrandRepo, missingRequiredSecrets, publishTargetSecrets };
+module.exports = { collectTargetSecrets, missingRequiredSecrets, publishTargetSecrets };

package/docs/index.md

@@ -305,7 +305,7 @@ API references for each subsystem live in `docs/`. **Whenever you make a behavio
 - [docs/installer-options.md](../docs/installer-options.md) — per-target installer config, defaults table
 - [docs/signing.md](../docs/signing.md) — code signing for macOS + Windows
 - [docs/releasing.md](../docs/releasing.md) — end-to-end release walkthrough
-- [docs/runner.md](../docs/runner.md): Windows EV-token signing runner. The listener runs with a private HOME (`%LOCALAPPDATA%\omega-runner\home`, holding a real `.gitconfig`), written at install and healed by `start`/`restart`, so a job's `actions/checkout` never copies the box's symlinked `~/.gitconfig` into a junction it cannot read ([#807](https://github.com/Omega-JS-Stack/omega/issues/807)). The same install writes the box's JOB GUARD ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): a job-started hook beside the runner, pointed at through each registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED`, that fails any job whose event is not a dispatch or whose repository or actor is not on the box's own allow lists
+- [docs/runner.md](../docs/runner.md): Windows EV-token signing runner. The listener runs with a private HOME (`%LOCALAPPDATA%\omega-runner\home`, holding a real `.gitconfig`), written at install and healed by `start`/`restart`, so a job's `actions/checkout` never copies the box's symlinked `~/.gitconfig` into a junction it cannot read ([#807](https://github.com/Omega-JS-Stack/omega/issues/807)). The same install writes the box's JOB GUARD ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): a job-started hook beside the runner, pointed at through each registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED`, that fails any job whose event is not a dispatch or whose repository or actor is not on the box's own allow lists. `start` is the one command a box operator runs ([#937](https://github.com/Omega-JS-Stack/omega/issues/937)): it installs a bare box, refreshes a stale actions/runner download in place, and registers any admin org the box does not serve yet before bringing every org online
 - [docs/test-framework.md](../docs/test-framework.md) — writing tests, running them, layers
 - [docs/test-boot-layer.md](../docs/test-boot-layer.md) — the `boot` test layer: consumer end-to-end smoke + @omega.js/desktop's framework self-test from the repo via the bundled fixture (`src/test/fixtures/consumer-app/`) + `OMEGA_TEST_BOOT_PROJECT` (@omega.js/desktop's analog of @omega.js/backend/BXM/UJM `*_TEST_BOOT_PROJECT`)
 - [docs/build-system.md](../docs/build-system.md) — gulp, esbuild, electron-builder pipeline

package/docs/releasing.md

@@ -92,7 +92,7 @@ Every verb runs `ensureTarget()` first ([#675](https://github.com/Omega-JS-Stack
 `npx omega deploy` adds the network half as a precheck (`--no-secrets` opts out):
 
 - Validates signing prereqs (warns if missing — non-fatal).
-- Pushes the composed `.env` → GitHub Actions secrets over the `gh` CLI (`gh auth login`; a CI run, an empty cascade, no remote, or a checkout that is not the brand's declared repo skips loudly).
+- Pushes the composed `.env` → GitHub Actions secrets over the `gh` CLI (`gh auth login`; a CI run, an empty cascade, or no GitHub remote skips loudly, and a checkout whose `origin` is not the derived source repo refuses on the one drift line, `origin is <slug> but config derives <derived>: fix repo.org in config/omega.json5 or move the repo`, [#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
 
 Now drop your cert files:
 
@@ -174,7 +174,9 @@ build             needs setup; matrix over the resolved OSes: npm ci, then
                   `npm run release:local` on mac and linux (sign, notarize, and
                   electron-builder publishes the DRAFT release in the brand's releases
                   repo), and `npm run package` on windows, whose unsigned output uploads
-                  as the `windows-unsigned` artifact
+                  as the `windows-unsigned` artifact, a one-day intermediate that
+                  windows-sign consumes in the same run (the releases repo is the
+                  durable home)
 windows-strategy  needs [setup, build]; reads platforms.windows.signing.strategy from config
                   (only when windows is in the matrix)
 windows-sign      the self-hosted EV-token box, hosted windows-latest for the cloud

package/docs/runner.md

@@ -56,7 +56,7 @@ Then, in a normal (non-elevated) PowerShell:
 
 Then the orgs: a checkbox of every org your token administers, in alphabetical order. Ticked by default are the orgs this box already answered for — the saved `OMEGA_RUNNER_ORGS`, else the orgs it actually registered, else NOTHING. A token that administers 35 orgs must never register 35 runners on one Enter. Ticking nothing is refused too — a runner registered against no org is not a runner. Off a TTY the walk asks nothing: `config` says so and stops (edit the file instead), `install` refuses only when a required key is missing, and a blank org list still means every org the token administers, because CI has no keyboard.
 
-`start` is the exception, deliberately: it asks only for MISSING required keys, never the checkbox, and warns when the file's org list is not the one this install registered.
+`start` is the exception, deliberately: it asks only for MISSING required keys, never the checkbox, and warns when the file's org list is not the one this install registered. On a bare box (nothing installed yet) `start` runs install itself, so there it is install's full walk, checkbox included.
 
 Orgs in `OMEGA_RUNNER_ORGS` you do not administer are named in a warning and skipped.
 
@@ -64,13 +64,13 @@ Orgs in `OMEGA_RUNNER_ORGS` you do not administer are named in a warning and ski
 
 ```powershell
 npx omega runner status            # registered orgs, Startup shortcuts, live listeners, legacy leftovers
-npx omega runner start             # bring EVERY registered org's runner up, detached (idempotent: an org already alive is skipped)
+npx omega runner start             # the one command: install a bare box, else heal HOME and the job guard, refresh a stale actions/runner in place,
+                                   # register any admin org not served yet, then bring EVERY registered org up, detached (an org already alive is skipped)
 npx omega runner restart           # stop, wait for the listeners to go, then start
 npx omega runner stop              # kill every Runner.Listener.exe under the runner home
-npx omega runner install           # idempotent full setup — tears down first, so re-running is safe
+npx omega runner install           # the explicit clean rebuild: tears down first, so re-running is safe
 npx omega runner config            # the same full walk install runs — every key, current values as the defaults, plus the orgs
 npx omega runner register-org <org># register one specific org
-npx omega runner self-update       # npm i -g @omega.js/desktop@latest
 npx omega runner uninstall         # remove everything, legacy services, tasks and the em-runner install included
 npx omega runner monitor           # tail the signing event log
 ```
@@ -79,13 +79,13 @@ Notes worth knowing before you use them:
 
 - **`config` is `install`'s configuration step, alone.** Same walk, same defaults, same order — it just does not go on to register anything. A saved org your token no longer administers is named before the checkbox, since it cannot appear in it. Windows-only, and terminal-only (with nothing to ask with it stops and names the file). When the orgs you pick are not the ones this install registered, it says to re-run `install`.
 - **Every subcommand tees its output to `<runner home>\logs\runner.log`**, and so does `npx omega sign-windows` — including inside a `windows-sign` job, which is exactly when the box's own record is wanted (the log lives in the runner home, never in a workspace, so the usual "no logs in CI" rule does not apply to it). `runner status` prints the path on its own line. It APPENDS, because more than one process writes it: `start` returns as soon as the runners are spawned, and every `sign-windows` those listeners go on to run adds to the same file. Each run stamps its own `# omega log` header; nothing rotates it, so delete the file when you want a clean one. `uninstall` keeps `.env` and `logs\`, since the log it is writing while it runs is the trail of that uninstall.
-- **A refusal writes nothing.** Off Windows every subcommand but `self-update` and `monitor` stops at the platform check before the log file is opened, so running one on a Mac by accident leaves no `.gh-runners/` in the directory you were standing in.
+- **A refusal writes nothing.** Off Windows every subcommand but `monitor` stops at the platform check before the log file is opened, so running one on a Mac by accident leaves no `.gh-runners/` in the directory you were standing in.
 - **The box verbs ignore the project's `.env` cascade.** `runner` and `sign-windows` read the shell and `<runner home>\.env`, nothing else, so running them from inside a brand folder can never hand a brand's `GH_TOKEN` to the box ([#337](https://github.com/Omega-JS-Stack/omega/issues/337)). Every other verb keeps the cascade.
-- **`start` brings up EVERY registered org, detached.** It walks the Startup shortcuts in order and spawns one hidden runner per org, so the terminal comes straight back and nothing is lost by not watching it: the listener's output is the JSONL log `monitor` tails. Running it again is safe, which is the point of it: an org whose listener is already alive is named with its PID and skipped, never duplicated and never a refusal. Exit 0 when every org ends up online, 1 when a spawn failed. A listener sitting in session 0 is skipped too, but loudly: it is alive and will fail every job it picks up, so the line names the session and points at `restart`. Killing a listener is `stop`'s job, never a start's.
+- **`start` brings up EVERY registered org, detached.** It walks the Startup shortcuts in order and spawns one hidden runner per org, so the terminal comes straight back and nothing is lost by not watching it: the listener's output is the JSONL log `monitor` tails. Running it again is safe, which is the point of it: an org whose listener is already alive is named with its PID and skipped, never duplicated and never a refusal. Exit 0 when every org ends up online, 1 when a spawn or a registration failed. A listener sitting in session 0 is skipped too, but loudly: it is alive and will fail every job it picks up, so the line names the session and points at `restart`. Killing a listener is `stop`'s job, never a start's.
 - **`restart` is `stop` then `start`**, in that order, for the loop you would otherwise run by hand after a config change. It settles two things the two commands typed in sequence do not: the box config walk runs FIRST, so a box missing a required key is refused before anything is killed rather than left stopped, and each org's dir is polled (5 seconds) until no listener stands in it, because `taskkill` returns before the process is gone and a start that raced it would read the dying listener as "already running". A listener still standing after the wait is reported and that org is left alone, exit 1.
 - **`stop` leaves the Startup shortcuts in place**, so a logout/login brings the runner back. For a permanent stop, run `uninstall`.
-- **Every subcommand except `self-update` and `monitor` refuses on non-Windows.** `OMEGA_RUNNER_FORCE=1` overrides it, for framework tests only.
-- **A test process cannot touch a real box.** Every subcommand that changes the machine — `install`, `config`, `register-org`, `start`, `restart`, `stop`, `uninstall`, `self-update` — refuses, before the platform check and naming `OMEGA_TEST_RUNNER`, whenever the run is a test (`omega test` sets that variable; `OMEGA_TEST_MODE` counts too, the marker a sibling framework's runner or a consumer's own test script sets) and a home it could act on is not a scratch one, under a `.temp` directory or the OS temp dir. BOTH homes are checked, the passed one and the module-level `RUNNER_HOME`, because the box's `.env` was already read into the process from the latter when the command module was required; the refusal names whichever is real. The marker is read from the process environment only — an injected environment is a fixture for the config walk, never an answer to "am I a test". The Startup folder is the THIRD surface checked, because no home scopes it — `uninstall` sweeps every `omega-runner-*.cmd` in the folder whatever home it was given, and a case whose two homes were both scratch deleted the box's three real shortcuts. It has its own scratch seam, `OMEGA_RUNNER_STARTUP_DIR`, and a test run against the real folder refuses naming both. The surfaces that no path can redirect at all — the watcher service, the legacy logon tasks, the `actions.runner.*` services, and the legacy `em-runner` homes — are simply not swept under a test run; `uninstall` says so on one line instead. A test run also never kills a process whose ExecutablePath it cannot read: that path belongs to another account, and matching it scopes to no home at all, so `stop` and `uninstall` drop the clause instead of `taskkill /F`-ing a stranger's runner. And it never deregisters on its own: `deregisterOrgRunners` mints a real removal token and runs each org directory's `config.cmd`, neither of them home-scoped, so with a roster to remove a test run refuses, naming the seam, unless `exec` is injected and, while `GH_TOKEN` is set, `getRemoveToken` too. A framework suite that wants to drive these points `OMEGA_RUNNER_HOME` and `OMEGA_RUNNER_STARTUP_DIR` at scratches *before* the command module is required, since both are resolved once, at require time. `sign-windows` follows the same rule for its log: from a test run pointed at a real home it tees nowhere rather than write the box's own record. This exists because a suite once ran a real `install` on the box and registered 34 orgs.
+- **Every subcommand except `monitor` refuses on non-Windows.** `OMEGA_RUNNER_FORCE=1` overrides it, for framework tests only.
+- **A test process cannot touch a real box.** Every subcommand that changes the machine (`install`, `config`, `register-org`, `start`, `restart`, `stop`, `uninstall`) refuses, before the platform check and naming `OMEGA_TEST_RUNNER`, whenever the run is a test (`omega test` sets that variable; `OMEGA_TEST_MODE` counts too, the marker a sibling framework's runner or a consumer's own test script sets) and a home it could act on is not a scratch one, under a `.temp` directory or the OS temp dir. BOTH homes are checked, the passed one and the module-level `RUNNER_HOME`, because the box's `.env` was already read into the process from the latter when the command module was required; the refusal names whichever is real. The marker is read from the process environment only — an injected environment is a fixture for the config walk, never an answer to "am I a test". The Startup folder is the THIRD surface checked, because no home scopes it — `uninstall` sweeps every `omega-runner-*.cmd` in the folder whatever home it was given, and a case whose two homes were both scratch deleted the box's three real shortcuts. It has its own scratch seam, `OMEGA_RUNNER_STARTUP_DIR`, and a test run against the real folder refuses naming both. The surfaces that no path can redirect at all — the watcher service, the legacy logon tasks, the `actions.runner.*` services, and the legacy `em-runner` homes — are simply not swept under a test run; `uninstall` says so on one line instead. A test run also never kills a process whose ExecutablePath it cannot read: that path belongs to another account, and matching it scopes to no home at all, so `stop` and `uninstall` drop the clause instead of `taskkill /F`-ing a stranger's runner. And it never deregisters on its own: `deregisterOrgRunners` mints a real removal token and runs each org directory's `config.cmd`, neither of them home-scoped, so with a roster to remove a test run refuses, naming the seam, unless `exec` is injected and, while `GH_TOKEN` is set, `getRemoveToken` too. `start` and `restart` skip their org check the same way, on one line, unless both `_discoverOrgs` and `_registerOrg` are injected: registering acts on GitHub, never on a home. A framework suite that wants to drive these points `OMEGA_RUNNER_HOME` and `OMEGA_RUNNER_STARTUP_DIR` at scratches *before* the command module is required, since both are resolved once, at require time. `sign-windows` follows the same rule for its log: from a test run pointed at a real home it tees nowhere rather than write the box's own record. This exists because a suite once ran a real `install` on the box and registered 34 orgs.
 - **`uninstall` deregisters on the GitHub side first, and keeps whatever did not come off.** It walks every `actions-runner-<org>\` directory under the runner home and runs that directory's own `config.cmd remove` before anything is deleted. If a removal exits non-zero — or `GH_TOKEN` is not set, so no removal token can be minted — that runner is still registered, so its directory SURVIVES the uninstall and the summary names the org. Re-running `uninstall` retries it. Belt and braces: `register-org` also deletes every org-side runner starting with this host's prefix before it registers a new one.
 
 ## Upgrading from the electron-manager runner
@@ -102,7 +102,9 @@ So the upgrade on the box is the ordinary one: `npx omega runner install` with `
 
 ## Adding a new org
 
-Nothing happens automatically — no process is watching for new orgs. Run `npx omega runner install` again (it is idempotent and re-registers everything), or register just the one org:
+No process watches for new orgs, but `start` checks every time it runs: `npx omega runner start` lists the orgs your `GH_TOKEN` administers, narrows them by `OMEGA_RUNNER_ORGS` when it is set, registers each one this box does not serve yet (Startup shortcut included), and brings it online with the rest. Orgs registered outside the list stay registered; `npx omega runner install` is the command that reshapes the box to the list exactly. An org check that cannot reach GitHub is one warn line, and `start` carries on and brings every registered org online.
+
+To register one specific org alone:
 
 ```powershell
 npx omega runner register-org <org-name>
@@ -280,7 +282,7 @@ The SafeNet driver sometimes detaches after a major OS update. Open the SafeNet
 
 ## Upgrading the actions/runner binary
 
-`ACTIONS_RUNNER_VERSION` in `src/commands/runner.js` pins it. Bump the constant, ship a new `@omega.js/desktop`, then on the box: `npx omega runner self-update` followed by `npx omega runner install`. The install tears down the old tree and lays the new version down cleanly.
+`ACTIONS_RUNNER_VERSION` in `src/commands/runner.js` pins it. Bump the constant, ship, then on the box run `npx omega runner start`. It sees that the version `config.json` recorded is not the pinned one, re-downloads `_template` in place, and copies it over each org dir whose listener is not running. `.runner`, `.credentials` and `.env` are not in the template, so every registration survives, and nothing is torn down. An org whose listener IS running has its binaries locked: it is skipped with one line naming `npx omega runner restart`, and the new version is recorded only once every org dir took it, so a `restart` (which stops first) finishes the job. `npx omega runner install` remains the clean rebuild when you want one.
 
 ## Related
 

package/docs/shared/brands.md

@@ -16,7 +16,7 @@ Fixture for the AUTOMATED corpus/e2e suites: offline, `demo-*` Firebase, determi
 
 ### `brands/playground-omega` — "OMEGA Playground", the standing live test brand
 
-Renamed from omega-brand (Ian 2026-07-11, zero ambiguity). Born through the real wizard: id `playground` (shortened on 2026-09-10, [#808](https://github.com/Omega-JS-Stack/omega/issues/808), so the `<brand.id>-<role>` rule derives clean repo names off it), url playground.omegajs.dev, a SUBDOMAIN so derived surfaces never claim the real omegajs.dev. Its THREE repos all derive from that id, none of them typed ([#883](https://github.com/Omega-JS-Stack/omega/issues/883), all under the one `repo: { provider: 'github', org: 'Omega-JS-Stack' }` block): `playground-omega` (the PRIVATE source repo, and the folder name here, whose `main` every `omega deploy` snapshots this folder onto, [docs/shared/deploys.md](deploys.md)), `playground-releases` (public: the desktop installers, the extension zips and the autoupdater feed), and `playground-web` (public: the BUILT site alone, one force-orphan commit on `gh-pages`, served by Pages at playground.omegajs.dev, which is what lets the source repo stay private on a free org). The third, the private `playground-rehearsal` snapshot, retired with the rehearsal itself ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). Points at the real-but-throwaway Firebase project `omegajs-playground` (ITW-org-owned since 2026-07-11; sanctioned for live proofs: Blaze it, break it, delete it; it is TEST INFRASTRUCTURE, never production).
+Renamed from omega-brand (Ian 2026-07-11, zero ambiguity). Born through the real wizard: id `playground` (shortened on 2026-09-10, [#808](https://github.com/Omega-JS-Stack/omega/issues/808), so the `<brand.id>-<role>` rule derives clean repo names off it), url playground.omegajs.dev, a SUBDOMAIN so derived surfaces never claim the real omegajs.dev. Its THREE repos all derive from that id, none of them typed ([#883](https://github.com/Omega-JS-Stack/omega/issues/883), all under the one `repo: { provider: 'github', org: 'Omega-JS-Stack' }` block): `playground-omega` (the PUBLIC source repo since 2026-09-24, so its Actions runs never count against the org storage allowance; the folder name here, whose `main` every `omega deploy` snapshots this folder onto, [docs/shared/deploys.md](deploys.md)), `playground-releases` (public: the desktop installers, the extension zips and the autoupdater feed), and `playground-web` (public: the BUILT site alone, one force-orphan commit on `gh-pages`, served by Pages at playground.omegajs.dev, which is what let the source repo stay private on a free org before it went public). The third, the private `playground-rehearsal` snapshot, retired with the rehearsal itself ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). Points at the real-but-throwaway Firebase project `omegajs-playground` (ITW-org-owned since 2026-07-11; sanctioned for live proofs: Blaze it, break it, delete it; it is TEST INFRASTRUCTURE, never production).
 
 REBRANDED **OMEGA Playground** (Ian 2026-08-21, [#433](https://github.com/Omega-JS-Stack/omega/issues/433) — REVERSES the 2026-07-19 fiction ruling, whose invented brand read as a real product in the ad and analytics consoles). The doctrine now: the playground is openly the OMEGA test surface — "we can mess around here, nothing live actually matters" — so drift from the real omegajs.dev site reads as a demo doing its job, never as a broken copy. Infra identity unchanged (id, url, green accent, classy theme); name and voice are the only things that moved, and the catalog's display names stay placeholder demo copy. Cloud-side display names (the Meta pixel, the GA property + streams, the GCP project name) are the manager's follow-up.
 

package/docs/shared/config.md

@@ -1433,6 +1433,13 @@ of any kind exists: a repo name that must differ is a brand id that must differ.
 | Releases | `releasesRepo(config)` → `<repo.org>/<brand.id>-releases` | always public (the desktop updater polls it with no token) | every target's built artifacts: desktop installers, the extension's zips, tagged per target |
 | Website, one per GitHub-hosted web target | `websiteRepo(config, name)` → `<repo.org>/<brand.id>-<target name>` | private only when the brand is private AND the org's plan allows Pages from a private repo, else public, and the manage walk says which | the BUILT site only, one force-orphan commit on `gh-pages`, served by Pages at the target's url |
 
+**`repoDrift(originSlug, config)`** is the one comparison of a checkout's `origin` with
+the source repo ([#934](https://github.com/Omega-JS-Stack/omega/issues/934)): the whole
+slug, case-insensitive, null when they agree or the config derives no source repo, else
+the line `origin is <slug> but config derives <derived>: fix repo.org in
+config/omega.json5 or move the repo`. The boot prelude prints it; `omega manage` and
+`omega deploy` refuse with it ([deploys.md](deploys.md#the-origin-gate-934)).
+
 **Visibility lives in the brand root's `package.json`**, never in omega.json5
 (`brandVisibility(brandRoot)`): `private: true` or the field ABSENT is a private brand
 (every brand monorepo is private by default, Ian 2026-09-11), and only a literal `false`