@omega.js/desktop 0.51.0 → 0.53.0

package/dist/commands/runner.js

@@ -14,18 +14,20 @@
 //                        the defaults — and the orgs it serves. How a value that
 //                        is already there gets changed.
 //   register-org <org>   Register the runner against one specific GH org.
-//   start                Bring EVERY registered org's runner online, detached,
-//                        in Startup-shortcut order. An org already alive is
-//                        named and skipped; the terminal is never taken over.
+//   start                The one command: installs a bare box, refreshes a stale
+//                        actions/runner download in place, registers any admin
+//                        org the box does not serve yet, then brings EVERY
+//                        registered org online, detached, in Startup-shortcut
+//                        order. An org already alive is named and skipped; the
+//                        terminal is never taken over.
 //   restart              stop, wait for every listener to go, then start.
 //   stop                 Kill every Runner.Listener.exe under RUNNER_HOME.
 //   status               Registered orgs, Startup shortcuts, live listeners.
 //   uninstall            Remove everything — legacy services and tasks, and the
-//                        electron-manager era's em-runner install, included.
-//   self-update          Force an immediate self-update of @omega.js/desktop (npm i -g @omega.js/desktop@latest).
+//                        legacy em-runner install, included.
 //   monitor              Tail the JSONL signing event log, pretty-printed.
 //
-// Every subcommand except `self-update` and `monitor` refuses on non-Windows
+// Every subcommand except `monitor` refuses on non-Windows
 // (set OMEGA_RUNNER_FORCE=1 to override — testing only).
 
 const path     = require('path');
@@ -33,9 +35,8 @@ const fs       = require('fs');
 const os       = require('os');
 const jetpack  = require('fs-jetpack');
 
-const Manager  = new (require('../build.js'));
-const logger   = Manager.logger('runner');
-const { safeInstall } = require('../utils/safe-install');
+const build  = require('../build.js');
+const logger   = build.logger('runner');
 
 const RUNNER_LABELS = ['self-hosted', 'windows', 'ev-token'];
 
@@ -62,7 +63,7 @@ const attachLogFile = require('../utils/attach-log-file.js');
 const RUNNER_HOME = process.env.OMEGA_RUNNER_HOME || defaultRunnerHome();
 loadRunnerEnv({ home: RUNNER_HOME });
 
-// The electron-manager era of this command (`em runner`) laid the same design
+// The legacy generation of this command (`em runner`) laid the same design
 // down under other names: the home was %LOCALAPPDATA%\em-runner (C:\actions-runners
 // before that), and the Startup shortcuts and the GitHub-side runners were
 // `em-runner-<host>-<org>`. An upgraded box still has all of it — live, and
@@ -103,8 +104,8 @@ function orgRunnerDir(org, home) {
 }
 const ACTIONS_RUNNER_VERSION = '2.319.1';   // pinned; bump intentionally
 
-// The subcommands, and the two of them that run on any platform: self-update is
-// an npm install, monitor only reads a log file. Every other one is the box's.
+// The subcommands, and the one of them that runs on any platform: monitor only
+// reads a log file. Every other one is the box's.
 const SUBCOMMANDS = {
   'install':      install,
   'config':       configureRunner,
@@ -114,17 +115,16 @@ const SUBCOMMANDS = {
   'stop':         stopServices,
   'status':       statusServices,
   'uninstall':    uninstall,
-  'self-update':  selfUpdate,
   'monitor':      monitor,
 };
-const ANY_PLATFORM_SUBCOMMANDS = new Set(['self-update', 'monitor']);
+const ANY_PLATFORM_SUBCOMMANDS = new Set(['monitor']);
 
 // The ones that CHANGE the machine: they register, deregister, download, delete,
-// kill listeners, rewrite the box's own configuration, or run a global npm
-// install. A test process may only point these at a scratch home
+// kill listeners, or rewrite the box's own configuration. A test process may
+// only point these at a scratch home
 // ([#337](https://github.com/Omega-JS-Stack/omega/issues/337) — the suite once
 // ran a real install against the box). `status` and `monitor` only read.
-const MUTATING_SUBCOMMANDS = new Set(['install', 'config', 'register-org', 'start', 'restart', 'stop', 'uninstall', 'self-update']);
+const MUTATING_SUBCOMMANDS = new Set(['install', 'config', 'register-org', 'start', 'restart', 'stop', 'uninstall']);
 
 module.exports = async function (options) {
   options = options || {};
@@ -207,7 +207,7 @@ async function install(options) {
   // the calling terminal at normal user privilege.
 
   // Idempotent by replacement: always tear down any prior install before starting —
-  // the omega one, or the electron-manager one an upgraded box still runs.
+  // the omega one, or the legacy em-runner one an upgraded box still runs.
   if (jetpack.exists(home) || listLegacyRunnerHomes({ home }).length > 0 || listLegacyRunnerStartupShortcuts().length > 0) {
     logger.log(`Existing runner installation detected — uninstalling first for a clean re-install...`);
     try {
@@ -261,7 +261,7 @@ async function install(options) {
   // admin orgs on a tick ran as NT AUTHORITY\NETWORK SERVICE in Session 0, so
   // the runners it spawned could not see the user's cert store and the Startup
   // shortcuts it wrote landed in the wrong profile. Adding a new org is a
-  // `mgr runner install` away; uninstall() still tears down any leftover
+  // `npx omega runner start` away; uninstall() still tears down any leftover
   // watcher service from an older install.
 
   // 5. Save install metadata.
@@ -304,7 +304,7 @@ async function install(options) {
     logger.log('');
     logger.log(`Bringing every registered runner (${succeeded.length}) online in the background. 'npx omega runner status' shows them, 'npx omega runner monitor' tails the log.`);
     logger.log('');
-    await startServices({ ...options, _home: home });
+    await startServices({ ...options, _home: home, _reconcileDone: true });
   }
 }
 
@@ -369,8 +369,8 @@ async function registerOrg(options) {
   // THIS host. Without this, re-running install accumulates orphaned runners (one per
   // failed/aborted install, one per host rename, etc.) which causes actions/runner to
   // auto-suffix the new runner's name (e.g. `-2872`) and breaks our ability to predict
-  // service names. Match prefix is `omega-runner-<host>-<org>` — and the electron-manager
-  // era's `em-runner-<host>-<org>`, the same box's older registration — so we never touch
+  // service names. Match prefix is `omega-runner-<host>-<org>` — and the legacy
+  // `em-runner-<host>-<org>`, the same box's older registration — so we never touch
   // user-created runners or runners from other hosts.
   //
   // We do this BEFORE fetching the registration token because the token is one-shot
@@ -416,7 +416,7 @@ async function registerOrg(options) {
   const runnerDir   = orgRunnerDir(org, home);
   const templateDir = options._templateDir || path.join(home, '_template');
   if (!jetpack.exists(path.join(templateDir, 'config.cmd'))) {
-    throw new Error(`actions/runner template not found at ${templateDir}. Run 'npx omega runner install' first.`);
+    throw new Error(`actions/runner template not found at ${templateDir}. Run 'npx omega runner start' first.`);
   }
   if (jetpack.exists(runnerDir)) {
     logger.log(`  Removing stale actions-runner-${org.toLowerCase()}/ before re-clone…`);
@@ -528,7 +528,8 @@ async function registerOrg(options) {
 // What `start` settles before it touches a listener: the box's required keys —
 // asked in a terminal and refused without one, exactly like install — and then
 // the orgs the .env names against the orgs this install actually registered.
-// start registers nothing; it names the command that would.
+// start only ever ADDS a named admin org (reconcileRunnerInstall); reshaping the
+// box to the list is install's, so the mismatch names it.
 async function startPreflight(options) {
   const { home, env = process.env, logger: log = logger, prompt, interactive } = options || {};
   await ensureRunnerConfig({ home, env, logger: log, prompt, interactive });
@@ -557,7 +558,7 @@ async function startPreflight(options) {
   const named      = parseRunnerOrgs(env.OMEGA_RUNNER_ORGS);
   const registered = readConfig(home).registeredOrgs || [];
   if (named.length > 0 && !sameRunnerOrgs(named, registered)) {
-    log.warn(`OMEGA_RUNNER_ORGS names ${named.join(', ')} but this install registered ${registered.join(', ') || '(none)'}. Run \`npx omega runner install\` to apply.`);
+    log.warn(`OMEGA_RUNNER_ORGS names ${named.join(', ')} but this install registered ${registered.join(', ') || '(none)'}. \`start\` registers a named admin org it does not serve yet and keeps the rest; \`npx omega runner install\` reshapes the box to the list.`);
   }
 }
 
@@ -574,6 +575,92 @@ function runnerStartupTargets(home) {
   });
 }
 
+// What `start` settles between the preflight and the spawns
+// ([#937](https://github.com/Omega-JS-Stack/omega/issues/937)), so a box never
+// needs a second verb to catch up:
+//  1. a stale actions/runner download is refreshed IN PLACE: the template is
+//     re-downloaded and laid over each org dir whose listener is down. The
+//     registration (`.runner`, `.credentials`, `.env`) is never in the
+//     template, so it survives the copy. A live listener holds its binaries
+//     open, so that org is skipped and named with `restart`, and the new
+//     version is recorded only once every org dir took it. No teardown. A
+//     download or a copy that fails is one warn and a skipped refresh, never
+//     a failed start: the next start tries again.
+//  2. an admin org the box does not serve yet (OMEGA_RUNNER_ORGS honoured) is
+//     registered, Startup shortcut and all. The only step that needs GitHub,
+//     so discovery that fails is one line and the box still comes online.
+//     GH_TOKEN is never missing here: it is a required key, and the preflight
+//     refuses a box without one. Orgs registered outside the filter stay;
+//     reshaping the box to the list is install's.
+//
+// `_download`, `_discoverOrgs` and `_registerOrg` are the tests' seams, the way
+// `_spawn` is. Registration is not home-scoped (it acts on GitHub with the real
+// token, whatever scratch home a case made), so a test run that has not
+// injected both GitHub seams skips the org check instead of reaching it.
+async function reconcileRunnerInstall(options) {
+  const home        = options._home;
+  const env         = options._env;
+  const log         = options._logger;
+  const listen      = options._listeners;
+  const download    = options._download || downloadActionsRunner;
+  const templateDir = path.join(home, '_template');
+
+  const installed = readConfig(home).actionsRunnerVersion;
+  if (installed !== ACTIONS_RUNNER_VERSION) {
+    log.log(`actions/runner ${installed || '(unrecorded)'} is installed and ${ACTIONS_RUNNER_VERSION} is pinned: refreshing in place.`);
+    let downloaded = true;
+    try {
+      await download(templateDir, home);
+    } catch (e) {
+      log.warn(`✗ actions/runner ${ACTIONS_RUNNER_VERSION} download failed (${e.message}): refresh skipped until the next start.`);
+      downloaded = false;
+    }
+    if (downloaded) {
+      let skipped = 0;
+      for (const { org, dir } of listOrgRunnerDirs(home)) {
+        if (listen(dir).length > 0) {
+          log.warn(`· ${org} is running, so its actions/runner files are locked and were not refreshed. Run \`npx omega runner restart\` to refresh it.`);
+          skipped++;
+          continue;
+        }
+        try {
+          jetpack.copy(templateDir, dir, { overwrite: true });
+          log.log(`✓ ${org} refreshed to actions/runner ${ACTIONS_RUNNER_VERSION}`);
+        } catch (e) {
+          log.warn(`✗ ${org} was not refreshed (${e.message}): the next start tries again.`);
+          skipped++;
+        }
+      }
+      if (skipped === 0) saveConfig({ actionsRunnerVersion: ACTIONS_RUNNER_VERSION }, home);
+    }
+  }
+
+  if (isTestRun() && !(options._discoverOrgs && options._registerOrg)) {
+    log.log('Org check skipped: a test run never asks GitHub unless both _discoverOrgs and _registerOrg are injected.');
+    return;
+  }
+  const discover = options._discoverOrgs || discoverAdminOrgs;
+  const register = options._registerOrg || registerOrg;
+  let adminOrgs;
+  try {
+    adminOrgs = await discover();
+  } catch (e) {
+    log.warn(`Org check skipped: could not list your admin orgs (${e.message}).`);
+    return;
+  }
+  const { orgs } = selectRunnerOrgs(adminOrgs, env.OMEGA_RUNNER_ORGS);
+  const served   = new Set((readConfig(home).registeredOrgs || []).map((org) => org.toLowerCase()));
+  for (const org of orgs.filter((o) => !served.has(o.toLowerCase()))) {
+    log.log(`Registering ${org}: an admin org this box does not serve yet.`);
+    try {
+      await register({ ...options, _: ['runner', 'register-org', org], _templateDir: templateDir });
+    } catch (e) {
+      log.warn(`✗ register ${org}: ${e.message}`);
+      process.exitCode = 1;
+    }
+  }
+}
+
 // Every registered org, brought online detached, in Startup-shortcut order.
 //
 // A box registers one runner per org, and `start` used to bring up exactly ONE
@@ -589,7 +676,15 @@ function runnerStartupTargets(home) {
 // `_spawn` and `_listeners` are injected by the tests, the same way `_home` and
 // `_logger` are: neither cmd.exe nor the process scan exists off Windows.
 // `_preflightDone` is `restart`'s: it settles the box config BEFORE it kills
-// anything, so the walk must not run a second time here.
+// anything, so the walk must not run a second time here. The reconcile is NOT
+// gated on it: after restart's stop is exactly when nothing is locked.
+// `_reconcileDone` is install's alone: it just downloaded and registered, so the
+// reconcile is skipped there.
+//
+// A bare box (no template to clone from) is handed to install, `_install` in
+// the tests, which ends by calling this function again with the template in
+// place. A test run without `_install` refuses: the real install downloads,
+// discovers and registers against GitHub, and no scratch home scopes that.
 async function startServices(options) {
   options = options || {};
   ensureWindows();
@@ -597,8 +692,23 @@ async function startServices(options) {
   const log     = options._logger || logger;
   const spawnIt = options._spawn || spawnRunnerDetached;
   const listen  = options._listeners || listRunnerListenerProcessesUnder;
+  if (!jetpack.exists(path.join(home, '_template', 'config.cmd'))) {
+    if (isTestRun() && !options._install) {
+      throw new Error(
+        `Refusing to install onto the bare runner home ${home}: this is a test run `
+        + '(OMEGA_TEST_RUNNER / OMEGA_TEST_MODE) and the call did not inject `_install`. The real install '
+        + 'downloads actions/runner and registers every admin org against GitHub with GH_TOKEN.',
+      );
+    }
+    log.log(`No runner install under ${home}: running the full install.`);
+    return (options._install || install)(options);
+  }
+  const env = options._env || process.env;
   if (!options._preflightDone) {
-    await startPreflight({ home, env: options._env || process.env, logger: log, prompt: options._prompt, interactive: options._interactive });
+    await startPreflight({ home, env, logger: log, prompt: options._prompt, interactive: options._interactive });
+  }
+  if (!options._reconcileDone) {
+    await reconcileRunnerInstall({ ...options, _home: home, _env: env, _logger: log, _listeners: listen });
   }
   const targets = runnerStartupTargets(home);
   if (targets.length === 0) {
@@ -762,7 +872,7 @@ async function statusServices(options) {
   logger.log('');
   const report = orgRunnerReport({ home });
   if (report.length === 0) {
-    logger.warn('No orgs registered. Run `npx omega runner install`.');
+    logger.warn('No orgs registered. Run `npx omega runner start`.');
   } else {
     logger.log(`Per-org runner state (${report.length}):`);
     for (const { state, lines } of report) {
@@ -790,7 +900,7 @@ async function statusServices(options) {
     }
   }
 
-  // The electron-manager era's install (`em runner`): its home, its Startup
+  // The legacy install (`em runner`): its home, its Startup
   // shortcuts, and any listener still running out of it. None of it answers to
   // the omega names above, so it is named here and torn down by `uninstall`.
   const legacyHomes     = listLegacyRunnerHomes({ home });
@@ -879,7 +989,7 @@ async function uninstall(options) {
   // handles asynchronously after stop).
   await removeRunnerHomeWithRetry(new Set(failed.map((f) => f.dir)), home);
 
-  // The electron-manager era's install, when this box still has one: the same
+  // The legacy em-runner install, when this box still has one: the same
   // teardown, org by org, so its GitHub-side registrations come off too.
   const legacy = await uninstallLegacyRunnerInstalls(home);
   const stillRegistered = [...failed, ...legacy.failed];
@@ -892,7 +1002,7 @@ async function uninstall(options) {
   logger.warn(`  Their directories were kept — re-run 'npx omega runner uninstall' to retry, or delete them under each org's Settings → Actions → Runners.`);
 }
 
-// Tear down the electron-manager era's runner install: its `em-runner-*`
+// Tear down the legacy runner install: its `em-runner-*`
 // Startup shortcuts, then each legacy home — deregister every org dir through
 // its own config.cmd, kill what runs out of it, remove it. A registration that
 // did not come off keeps its directory, exactly as the omega home's does.
@@ -1161,19 +1271,6 @@ function identifyHandleHolders(targetPath) {
   }
 }
 
-// ─── self-update ────────────────────────────────────────────────────────────────
-async function selfUpdate() {
-  const { execute } = require('node-powertools');
-  logger.log('Updating @omega.js/desktop to latest…');
-  try {
-    const out = await safeInstall('npm i -g @omega.js/desktop@latest');
-    logger.log(out);
-    logger.log('✓ @omega.js/desktop updated.');
-  } catch (e) {
-    logger.warn(`Self-update failed: ${e.message}`);
-  }
-}
-
 // ─── helpers ────────────────────────────────────────────────────────────────────
 
 const WATCHER_SERVICE_NAME = 'omega-runner-watcher';
@@ -1560,7 +1657,7 @@ function listRunnerStartupShortcuts(startupDir) {
   return listStartupShortcuts('omega-runner-', startupDir);
 }
 
-// The electron-manager era's: `em-runner-<host>-<org>`, which `status` names
+// The legacy shortcuts: `em-runner-<host>-<org>`, which `status` names
 // and `uninstall` removes — never anything `start` would launch.
 function listLegacyRunnerStartupShortcuts(startupDir) {
   return listStartupShortcuts(LEGACY_RUNNER_PREFIX, startupDir);
@@ -1571,8 +1668,8 @@ function listLegacyRunnerStartupShortcuts(startupDir) {
 // wrapper that blocks for the lifetime of the listener with cwd = runnerDir;
 // a long-lived cmd.exe holding cwd inside RUNNER_HOME blocks every later
 // uninstall with EPERM. Bypassing run.cmd loses its self-update relaunch
-// path, but `mgr runner install` refreshing the runner binary is the
-// preferred update mechanism in @omega.js/desktop anyway.
+// path, but `npx omega runner start` refreshing the runner binary in place
+// is the update mechanism in @omega.js/desktop anyway.
 //
 // Detached + windowsHide + ignored stdio = no console window flashes during
 // install and the listener survives the install command's exit. UAC-
@@ -1733,7 +1830,7 @@ async function monitor(options) {
   // exactly which orgs the monitor will pick up signing events from.
   const report = orgRunnerReport({ home });
   if (report.length === 0) {
-    logger.log('(no orgs registered yet — run `npx omega runner install` first)');
+    logger.log('(no orgs registered yet: run `npx omega runner start` first)');
   } else {
     logger.log(`Monitoring signing requests across ${report.length} org(s):`);
     for (const { state, lines } of report) {

package/dist/commands/sign-windows.js

@@ -21,8 +21,8 @@ const os      = require('os');
 const jetpack = require('fs-jetpack');
 const { execute } = require('node-powertools');
 
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('sign-windows');
+const build = require('../build.js');
+const logger = build.logger('sign-windows');
 
 // The box's own signing configuration (`<runner home>\.env`: the cert, the PIN,
 // signtool) is read before anything below looks at process.env, so a manual
@@ -90,9 +90,9 @@ async function runSignCommand(options) {
     return smokeTest();
   }
 
-  const strategy = Manager.getWindowsSignStrategy();
+  const strategy = build.getWindowsSignStrategy();
 
-  const config   = Manager.getConfig();
+  const config   = build.getConfig();
   const projectRoot = process.cwd();
 
   // Resolve --in and --out (CLI flags) → directories of unsigned / signed artifacts.
@@ -441,7 +441,7 @@ async function signWithSigntool(targets, inDir, outDir, deps) {
   // (mac/linux equivalents are produced by electron-builder during their publish step,
   // but Windows is split into a post-build sign job so we have to write the yml here).
   if (signedExes.length > 0) {
-    const pkg = Manager.getPackage('project') || {};
+    const pkg = build.getPackage('project') || {};
     const version = pkg.version;
     if (!version) {
       log.warn('Could not determine version from package.json; skipping latest.yml generation.');

package/dist/commands/test.js

@@ -1,8 +1,8 @@
 // Libraries
 const path = require('path');
 const fs = require('fs');
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('test');
+const build = require('../build.js');
+const logger = build.logger('test');
 const { run } = require('../test/runner.js');
 const attachLogFile = require('../utils/attach-log-file.js');
 const { EXTENDED_MODE_WARNING } = require('../test/utils/extended-mode-warning.js');
@@ -43,7 +43,7 @@ module.exports = async function (options) {
   // Extended mode — opt into tests that hit REAL external services (Firebase, analytics,
   // update feeds) instead of skipping them. Off by default so `npx omega test` stays fast and
   // offline-safe. The canonical signal is the unprefixed `TEST_EXTENDED_MODE` env var — the
-  // SAME name across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop (cross-framework parity); `--extended` is the CLI
+  // SAME name on every framework (cross-framework parity); `--extended` is the CLI
   // shorthand. Once set on process.env it propagates to every spawned child (electron
   // main/renderer/boot, the gulp boot build) automatically via `{ ...process.env }`.
   const extended    = options.extended === true
@@ -58,7 +58,7 @@ module.exports = async function (options) {
   // When @omega.js/desktop itself runs its own boot-layer tests (the cwd's package.json is @omega.js/desktop's), there's
   // no real consumer app to boot. Point the boot runner at the fixture under
   // dist/test/fixtures/consumer-app unless the caller has already set OMEGA_TEST_BOOT_PROJECT
-  // explicitly. Mirrors BXM's OMEGA_TEST_BOOT_PROJECT / UJM's UJ_TEST_BOOT_PROJECT.
+  // explicitly.
   if (!process.env.OMEGA_TEST_BOOT_PROJECT) {
     try {
       const cwdPkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));

package/dist/commands/update.js

@@ -5,8 +5,8 @@
  * non-quarantined, non-breaking set (`--major` opts into breaking) through
  * npu when present. The whole verb is the shared devkit implementation.
  */
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('update');
+const build = require('../build.js');
+const logger = build.logger('update');
 const { runUpdate } = require('../vendor/devkit/update.js');
 
 module.exports = async function (options) {

package/dist/commands/validate-certs.js

@@ -38,8 +38,8 @@ const { certificateExpiry, EXPIRY_WARN_DAYS } = require('../vendor/devkit/certs.
 const { signingPathCandidates } = require('../vendor/devkit/signing-env.js');
 const { requiredWhenHolds } = require('../vendor/config/env-rules.js');
 
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('validate-certs');
+const build = require('../build.js');
+const logger = build.logger('validate-certs');
 
 module.exports = async function (options) {
   options = options || {};
@@ -48,8 +48,8 @@ module.exports = async function (options) {
   logger.log('Validating signing prerequisites...');
 
   const platform = process.platform;
-  const config = Manager.getConfig();
-  const winStrategy = Manager.getWindowsSignStrategy();
+  const config = build.getConfig();
+  const winStrategy = build.getWindowsSignStrategy();
 
   const issues = [];
 

package/dist/commands/version.js

@@ -1,8 +1,8 @@
 // Libraries
-const Manager = new (require('../build.js'));
-const logger = Manager.logger('version');
+const build = require('../build.js');
+const logger = build.logger('version');
 
-const package = Manager.getPackage('main');
+const package = build.getPackage('main');
 
 module.exports = async function (options) {
   logger.log(package.version);

package/dist/defaults/.github/workflows/build.yml

@@ -239,6 +239,8 @@ jobs:
         uses: actions/upload-artifact@v7
         with:
           name: windows-unsigned
+          # An intermediate windows-sign consumes in this same run; the releases repo is the durable home.
+          retention-days: 1
           # Capture installer + auto-updater feed + blockmap so windows-sign can re-upload them all.
           path: |
             release/*.exe

package/dist/defaults/AGENTS.md

@@ -19,8 +19,9 @@ This project consumes **OMEGA Desktop** (@omega.js/desktop), a comprehensive fra
 
 ## 🚨 READ @omega.js/client TOO
 
-**@omega.js/desktop ships `@omega.js/client` as a runtime singleton inside the renderer process.**
+**@omega.js/desktop's renderer instance extends `@omega.js/client`'s base class.**
 - It powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.).
+- `omega.auth.user` is always a `User`: `authenticated`, `plan`, `active`, `profile.displayName`; `omega.auth.listen()` delivers `{ user, denied }`.
 - Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with @omega.js/client as much as with @omega.js/desktop.
 
 **Required reading:**
@@ -71,28 +72,36 @@ npx omega install live # restore the published @omega.js/desktop from npm
 
 ## Per-context imports
 
+Each entry exports ONE ready-made instance, `omega`; a consumer never writes `new`.
+
 ```js
 // src/main.js
-new (require('@omega.js/desktop/main'))().initialize();   // auto-loads JSON5 config
+const omega = require('@omega.js/desktop/main');
+omega.initialize().then(() => { const { logger, windows } = omega; });   // auto-loads JSON5 config
 
 // src/preload.js
-new (require('@omega.js/desktop/preload'))().initialize();
+const omega = require('@omega.js/desktop/preload');
+omega.initialize();
 
 // src/assets/js/components/main/index.js
-new (require('@omega.js/desktop/renderer'))().initialize();
+import omega from '@omega.js/desktop/renderer';
+omega.initialize().then(() => { const { logger, desktop } = omega; });
 ```
 
 ## Available APIs at runtime
 
-In main: `manager.storage`, `manager.ipc`, `manager.windows`, `manager.tray`, `manager.menu`, `manager.contextMenu`, `manager.startup`, `manager.appState`, `manager.deepLink`, `manager.autoUpdater`, `manager.sentry`, `manager.omega`, `manager.context`, `manager.usage`, `manager.remoteConfig`, `manager.analytics`, `manager.restartManager`.
+In main, each a property of `omega`: `windows`, `tray`, `menu`, `contextMenu`, `ipc`, `storage`, `deepLink`, `autoUpdater`, `appState`, `startup`, `protocol`, `authFlow`, `theme`, `fontawesome`, `context`, `usage`, `remoteConfig`, `remoteScripts`, `restartManager`, `analytics`, `sentry`, `logger`.
+- `omega.auth` is the signed-in account in main: `.user` (a `User`), `.listen()`, `.signOut()`, `.getIdToken()`, `.handleToken()`.
 
-In renderer: `window.desktop.storage`, `window.desktop.ipc`, `window.desktop.logger`, `window.OMEGA_BUILD_JSON.config` (the one `build.js` the view's shell loads).
+In renderer: the @omega.js/client base (`omega.auth`, `omega.firestore`, `omega.bindings`, and `omega.storage`, the page store) plus `omega.desktop`, the preload's bridge to main.
+- `omega.desktop.{ipc,storage,theme,fontawesome,autoUpdater,analytics,context,usage,remoteConfig}`; `omega.desktop.storage` is the app store, async over IPC.
+- Config: `window.OMEGA_BUILD_JSON.config` (the one `build.js` the view's shell loads).
 
 ## Dependency resolution
 
 - **Do NOT install framework dependencies directly** (`firebase`, `fs-jetpack`, `@omega.js/client`, etc.). @omega.js/desktop's bundler resolves them through the framework's own `node_modules/`. If something doesn't resolve, the issue is in @omega.js/desktop's bundle task, not your `package.json`.
-- **@omega.js/client owns Firebase.** Never `require('firebase')` or `import('firebase/app')`. Use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()` in renderers. In main process, use `manager.omega` (the @omega.js/desktop bridge).
-- **`Manager.require(name)`** resolves from @omega.js/desktop's module context at runtime for unbundled code (gulp tasks, test fixtures).
+- **@omega.js/client owns Firebase.** Never `require('firebase')` or `import('firebase/app')`. In renderers use `omega.auth` and `omega.firestore` on the renderer instance. In the main process, use `omega.auth` (the @omega.js/desktop bridge).
+- **`omega.require(name)`** resolves from @omega.js/desktop's module context at runtime for unbundled code (gulp tasks, test fixtures).
 
 ## Testing
 

package/dist/defaults/config/omega.json5

@@ -71,7 +71,7 @@
   // App/cloud platform role (provider-discriminated). `config` is the Firebase web
   // SDK config — copy directly from Firebase Console → Project Settings → SDK setup
   // (Config option). Same shape every OMEGA target reads.
-  // Empty config {} disables Firebase Auth in the renderer (client-bridge logs a warn).
+  // Empty config {} disables Firebase Auth in the renderer (the auth lib logs a warn).
   cloud: {
     provider: 'firebase',
     config: {
@@ -87,7 +87,7 @@
   },
 
   // Appearance — the app's DEFAULT theme. 'system' follows the OS preference live;
-  // 'light'/'dark' are explicit overrides. A user's runtime choice (manager.theme.set
+  // 'light'/'dark' are explicit overrides. A user's runtime choice (omega.theme.set
   // or the [data-omega-theme-set] controls) persists in storage and wins over this on
   // every boot. See docs/themes.md.
   theme: {
@@ -234,8 +234,8 @@
       //   src/integrations/tray/index.js
       //   src/integrations/menu/index.js
       //   src/integrations/context-menu/index.js
-      // To disable at runtime: call `manager.tray.disable()` / `manager.menu.disable()` /
-      // `manager.contextMenu.disable()` from your main entry. Idempotent.
+      // To disable at runtime: call `omega.tray.disable()` / `omega.menu.disable()` /
+      // `omega.contextMenu.disable()` from your main entry. Idempotent.
 
       // Startup behavior — two independent knobs.
       //
@@ -263,7 +263,7 @@
         },
       },
       // No `windows` block needed — @omega.js/desktop no longer auto-creates windows. Your main.js
-      // calls `manager.windows.create('main', { width: 1280, height: 800, ... })` when
+      // calls `omega.windows.create('main', { width: 1280, height: 800, ... })` when
       // you want UI to surface. Defaults baked in:
       //   main      → { width: 1024, height: 720, hideOnClose: true,  view: 'main' }
       //   any other → { width: 800,  height: 600, hideOnClose: false, view: name   }
@@ -282,9 +282,9 @@
       },
       // Deep links: scheme is automatically `<brand.id>://...`. Built-in routes:
       //   auth/token  → @omega.js/client auth token handoff
-      //   app/show    → manager.windows.show(query.window || 'main')
+      //   app/show    → omega.windows.show(query.window || 'main')
       //   app/quit    → app.quit()
-      // Add custom routes at runtime: manager.deepLink.on('my-route', (ctx) => {...}) in main.
+      // Add custom routes at runtime: omega.deepLink.on('my-route', (ctx) => {...}) in main.
 
       // "Hot config" — JSON document fetched from the brand site so app behavior
       // can be flipped without shipping a new build (e.g. force-update gate, ads

package/dist/defaults/hooks/build/post.js

@@ -5,5 +5,5 @@
 // auxiliary files (changelog, license bundling, etc.).
 
 module.exports = async (ctx) => {
-  // ctx = { manager, mode, projectRoot, distDir }
+  // ctx = { build, mode, projectRoot, distDir }
 };

package/dist/defaults/hooks/build/pre.js

@@ -5,5 +5,5 @@
 // the bundle / build-config tasks see it.
 
 module.exports = async (ctx) => {
-  // ctx = { manager, mode, projectRoot }
+  // ctx = { build, mode, projectRoot }
 };

package/dist/defaults/hooks/deploy/pre.js

@@ -6,5 +6,5 @@
 // that must happen before the publish reaches the release repo.
 
 module.exports = async (ctx) => {
-  // ctx = { manager, projectRoot, mode }
+  // ctx = { build, projectRoot, mode }
 };

package/dist/defaults/hooks/release/post.js

@@ -5,5 +5,5 @@
 // changelog page on your marketing site, sending notification emails.
 
 module.exports = async (ctx) => {
-  // ctx = { manager, projectRoot, artifacts }   // artifacts: array of release/ paths
+  // ctx = { build, projectRoot, artifacts }   // artifacts: array of release/ paths
 };

package/dist/defaults/hooks/release/pre.js

@@ -5,5 +5,5 @@
 // previous release before overwriting.
 
 module.exports = async (ctx) => {
-  // ctx = { manager, projectRoot }
+  // ctx = { build, projectRoot }
 };