@omega.js/desktop 0.1.0 → 0.51.0

package/dist/hooks/notarize.js

@@ -9,17 +9,32 @@
 //   APPLE_API_KEY_ID  — 10-char Key ID (matches the XXXXXXXXXX in the filename)
 //   APPLE_API_ISSUER  — issuer UUID from App Store Connect → Users and Access → Keys
 //
-// Skipped automatically when:
-//   - building for a non-darwin platform
-//   - any of the env vars above is missing (warns, doesn't fail — useful for dev builds without certs)
+// Skipped ONLY when building for a non-darwin platform. Every other state is a
+// THROW ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): a mac
+// build that reaches this hook is a mac build this framework ships, and a build
+// that cannot be signed and notarized must not become a release.
+//   - missing APPLE_API_KEY / _ID / _ISSUER: nothing can notarize it
+//   - no Developer ID signature (#872): electron-builder SKIPS signing when it
+//     finds no identity and leaves an ad-hoc signature behind, which notarytool
+//     rejects ("Failed to codesign your application"). That state used to warn
+//     and carry on, and the release published an app Gatekeeper refuses on every
+//     other Mac.
+//
+// After notarization the ticket is STAPLED and the result PROVED (stapler
+// validate + spctl --assess): the hook returns only when the .app on disk is
+// one a user's Mac will open offline. The DMG gets the same treatment in its
+// own hook (notarize-artifacts.js, artifactBuildCompleted), because the ticket
+// stapled to the app inside an image is not stapled to the image.
 
 const path = require('path');
 const fs   = require('fs');
+const { execute } = require('node-powertools');
 const Logger = require('../lib/logger');
+const { stapleAndProve, toolRunner } = require('./lib/notarize-tools.js');
 
 const logger = new Logger('notarize');
 
-module.exports = async function notarize(context) {
+module.exports = async function notarize(context, { run = toolRunner() } = {}) {
   const { electronPlatformName, appOutDir } = context;
 
   if (electronPlatformName !== 'darwin') {
@@ -31,8 +46,7 @@ module.exports = async function notarize(context) {
   const appleApiIssuer = process.env.APPLE_API_ISSUER;
 
   if (!appleApiKey || !appleApiKeyId || !appleApiIssuer) {
-    logger.warn('Skipping — set APPLE_API_KEY, APPLE_API_KEY_ID, APPLE_API_ISSUER to notarize.');
-    return;
+    throw new Error('[notarize] APPLE_API_KEY, APPLE_API_KEY_ID and APPLE_API_ISSUER are required to notarize a mac build. Run `omega deploy` (its precheck pushes them for CI) or set them in the target .env.');
   }
 
   const apiKeyPath = path.isAbsolute(appleApiKey)
@@ -43,10 +57,18 @@ module.exports = async function notarize(context) {
     throw new Error(`[notarize] APPLE_API_KEY file not found at ${apiKeyPath}`);
   }
 
-  const { notarize } = require('@electron/notarize');
   const appName = context.packager.appInfo.productFilename;
   const appPath = path.join(appOutDir, `${appName}.app`);
 
+  // Notarization verifies a Developer ID signature; an ad-hoc one (what
+  // electron-builder leaves when it finds no identity) fails the submission
+  // instead ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)).
+  if (!isDeveloperIdSigned(await readCodesign(appPath, run))) {
+    throw new Error(`[notarize] ${appName}.app is NOT Developer ID signed, so it cannot be notarized and every other Mac would refuse it. Set CSC_LINK + CSC_KEY_PASSWORD (or install a Developer ID Application identity) and build again.`);
+  }
+
+  const { notarize } = require('@electron/notarize');
+
   logger.log(`Notarizing ${appName} via App Store Connect API key (${appleApiKeyId})...`);
   const start = Date.now();
 
@@ -59,7 +81,12 @@ module.exports = async function notarize(context) {
   });
 
   const duration = Math.round((Date.now() - start) / 1000);
-  logger.log(`Done in ${duration}s.`);
+  logger.log(`Notarized in ${duration}s.`);
+
+  // The ticket, stapled and PROVED: a notarized app whose ticket never landed
+  // still fails on a Mac that is offline when the user opens it (#891).
+  await stapleAndProve({ filePath: appPath, kind: 'app', run });
+  logger.log(`Stapled and verified: stapler validate + spctl --assess both accept ${appName}.app.`);
 
   // After @omega.js/desktop's real notarization, optionally invoke the consumer's hooks/notarize/post.js as
   // an extension point. The consumer hook can do post-notarize work (custom stapling,
@@ -68,3 +95,27 @@ module.exports = async function notarize(context) {
   const runConsumerHook = require('../utils/run-consumer-hook.js');
   await runConsumerHook('notarize/post', context);
 };
+
+// Pure: does codesign's own report describe a REAL Developer ID signature? An
+// unsigned app has no report at all and an ad-hoc one ("Signature=adhoc",
+// "TeamIdentifier=not set") carries no Authority line, so the one line
+// notarization actually depends on is the one that is read.
+function isDeveloperIdSigned(codesignOutput) {
+  return /^Authority=Developer ID Application/m.test(String(codesignOutput || ''));
+}
+
+// codesign writes its report to STDERR and exits non-zero for an unsigned app,
+// so the report is folded into stdout and a failure is read as the answer it is.
+async function readCodesign(appPath, exec) {
+  const run = exec || ((cmd) => execute(cmd, { log: false }));
+
+  try {
+    return String(await run(`codesign -dv --verbose=2 "${appPath}" 2>&1`) || '');
+  } catch (e) {
+    return String(e.message || '');
+  }
+}
+
+// Exported for tests.
+module.exports.isDeveloperIdSigned = isDeveloperIdSigned;
+module.exports.readCodesign = readCodesign;

package/dist/lib/auth-persistence.js

@@ -25,6 +25,10 @@
 //        than "store it in a browser session".
 //   'none' — explicit opt-out; Firebase stays in-memory (pre-1.12 behavior).
 //
+// A TEST RUN is always 'none', whatever the config says: the test lanes never sign a
+// real user in, so the harness never touches the OS keychain. Both lanes, on the one
+// signal isTestRun() reads below ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)).
+//
 // Select via config `omega.authPersistence` ('safeStorage' | 'none' | a custom
 // registered name). Register custom strategies BEFORE manager.initialize():
 //   require('@omega.js/desktop/lib/auth-persistence').register('keytar', {...})
@@ -110,6 +114,15 @@ const noneStrategy = {
   async removeItem() {},
 };
 
+// Is this process a TEST RUN, in either lane that reaches this lib? The manager
+// answers it, in both: each lane spawns its child with `OMEGA_ENVIRONMENT=testing`
+// and the baked word never writes over it
+// ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)), so a booted
+// production artifact reports the lane it is running in too.
+function isTestRun(manager) {
+  return !!manager?.isTesting?.();
+}
+
 const authPersistence = {
   _initialized: false,
   _manager:     null,
@@ -140,6 +153,18 @@ const authPersistence = {
   // Pick + availability-check the configured strategy. Returns the active strategy
   // or null (→ caller falls back to firebase's in-memory default).
   async resolve(manager) {
+    // A TEST RUN is `none`, before any config is read: the test lanes never sign a
+    // real user in, so the OS keychain is never asked. This overrides an explicit
+    // consumer value too, because the boot layer boots the brand's REAL config through
+    // the staged test app, and an unsigned Electron binary asking macOS for a keychain
+    // item parks the whole run behind a SecurityAgent prompt
+    // ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)).
+    if (isTestRun(manager)) {
+      logger.log('auth persistence: none (test mode)');
+      authPersistence._active = null;
+      return null;
+    }
+
     const wanted = manager.config?.omega?.authPersistence || 'safeStorage';
     const strategy = authPersistence._strategies[wanted];
 

package/dist/lib/client-bridge.js

@@ -18,7 +18,7 @@
 
 const LoggerLite = require('./logger-lite.js');
 const authPersistence = require('./auth-persistence.js');
-const { localPort } = require('../utils/url-helpers.js');
+const { requiredPort } = require('../utils/url-helpers.js');
 
 const logger = new LoggerLite('client-bridge');
 
@@ -117,8 +117,8 @@ const bridge = {
 
     // A TESTING run talks to the LOCAL stack, never real auth — the same move
     // getApiUrl() makes when it maps testing to localhost, and the same one
-    // @omega.js/extension's background SW makes for its emulator runs. Only
-    // OMEGA_TEST_MODE=true reaches here; dev and production are untouched.
+    // @omega.js/extension's background SW makes for its emulator runs. Only an
+    // OMEGA_ENVIRONMENT=testing run reaches here; dev and production are untouched.
     if (bridge._manager.isTesting()) {
       const { connectAuthEmulator } = bridge._firebaseModule;
       const port = bridge._authEmulatorPort();
@@ -129,12 +129,15 @@ const bridge = {
     return bridge._firebaseAuth;
   },
 
-  // The auth emulator's port, on the same three-step chain getApiUrl() walks:
-  // the resolved-port env channel (N7), then the `dev.ports` map the bundle
-  // baked into OMEGA_BUILD_JSON, then the classic 9099
-  // ([#745](https://github.com/Omega-JS-Stack/omega/issues/745)).
+  // The auth emulator's port, on the same chain getApiUrl() walks: the
+  // resolved-port env channel (N7), then the `dev.ports` map the bundle baked
+  // into OMEGA_BUILD_JSON
+  // ([#745](https://github.com/Omega-JS-Stack/omega/issues/745)). The classic
+  // 9099 used to sit under those two as a last resort; it is gone (#834),
+  // because nothing identity-checks what answers on it and a neighbouring
+  // project's emulator reads as an auth mystery rather than a port problem.
   _authEmulatorPort() {
-    return localPort(bridge._manager, 'OMEGA_AUTH_PORT', 'auth') || 9099;
+    return requiredPort(bridge._manager, 'OMEGA_AUTH_PORT', 'auth');
   },
 
   _registerIpc() {

package/dist/lib/deep-link.js

@@ -3,8 +3,9 @@
 // Cross-platform plumbing handled internally:
 //   - macOS: the OS routes `<scheme>://...` URLs via `app.on('open-url')`. Cold-start opens may queue
 //            them before whenReady; we drain them after.
-//   - Windows/Linux: deep links arrive as the LAST entry in `process.argv` on cold-start, and as the
-//            `argv` arg of `app.on('second-instance')` on warm-start.
+//   - Windows/Linux: deep links arrive as the LAST entry in `process.argv` on cold-start, and on
+//            warm-start via `app.on('second-instance')` (read from the `additionalData` argument,
+//            which carries the duplicate's real argv; the event's own `argv` is Chromium-processed).
 //
 // Public API on manager.deepLink:
 //
@@ -23,8 +24,8 @@
 //     ctx.params   // { id: '42' }
 //     ctx.query    // { ref: 'abc' }
 //     ctx.source   // 'cold-start' | 'warm-start' | 'manual'
-//     ctx.argv     // process.argv (cold) or second-instance argv
-//     ctx.cwd      // process.cwd() or second-instance cwd
+//     ctx.argv     // process.argv (cold) or the duplicate's real argv (warm, via additionalData)
+//     ctx.cwd      // process.cwd() or the duplicate's cwd (warm)
 //     ctx.handled  // mutate: set true to suppress fall-through to '*' catch-all
 //   });
 //
@@ -117,8 +118,14 @@ const deepLink = {
     // Windows/Linux warm-start: another instance launched (e.g. user double-clicked the
     // app icon while it's already running, or a deep link arrived). The OS gave us the
     // lock, killed the duplicate, and forwarded its argv here.
-    app.on('second-instance', (_event, argv, cwd) => {
-      logger.log(`second-instance — argv=${JSON.stringify(argv)} cwd=${cwd}`);
+    app.on('second-instance', (_event, argv, cwd, additionalData) => {
+      // The event's own argv is Chromium-processed (switches first, the values detached
+      // at the end), so the duplicate's REAL command line rides along in the object it
+      // passed to requestSingleInstanceLock (#921). The fallback covers a duplicate
+      // started by a build from before that object existed.
+      const realArgv = Array.isArray(additionalData?.argv) ? additionalData.argv : argv;
+      const realCwd  = additionalData?.cwd || cwd;
+      logger.log(`second-instance argv=${JSON.stringify(realArgv)} eventArgv=${JSON.stringify(argv)} cwd=${realCwd}`);
 
       // Surface the main window. With hidden-mode apps, the consumer typically created
       // `main` with `show: false` at boot, so it's in the registry but invisible — we
@@ -134,9 +141,9 @@ const deepLink = {
         logger.log('second-instance — no main window in registry; ignoring');
       }
 
-      const url = deepLink._extractUrlFromArgv(argv);
+      const url = deepLink._extractUrlFromArgv(realArgv);
       if (url) {
-        deepLink._handle(url, 'warm-start', { argv, cwd });
+        deepLink._handle(url, 'warm-start', { argv: realArgv, cwd: realCwd });
       }
     });
   },

package/dist/lib/protocol.js

@@ -41,7 +41,13 @@ const protocol = {
     // initialize() and quits the duplicate WITHOUT running the rest of the boot
     // (two live instances would fight over storage, servers, and — for agents like
     // restart-manager — shared runtime files).
-    protocol._hasLock = app.requestSingleInstanceLock();
+    //
+    // The object rides along because the event's OWN argv is Chromium-processed
+    // (switches first, Chromium's own switches spliced in, the values detached at
+    // the end), so a brand parsing it reads its flags empty (#921). `additionalData`
+    // arrives untouched as the fourth argument of second-instance, so every brand
+    // gets the duplicate's real command line, in order, for free.
+    protocol._hasLock = app.requestSingleInstanceLock({ argv: process.argv, cwd: process.cwd() });
     if (!protocol._hasLock) {
       logger.warn('single-instance lock lost — another copy of the app is running.');
     } else {

package/dist/lib/restart-manager/install.js

@@ -94,7 +94,8 @@ function parseFeed(ymlText) {
 /**
  * Pick the install artifact for a platform from a parsed feed.
  *   darwin — zip, preferring `-<arch>-mac.zip` → `-universal-mac.zip` →
- *            `-mac-universal.zip` (the versionless form, #620) → `-mac.zip`
+ *            `-mac-universal.zip` (the #620 name) → `-mac.zip` (the name
+ *            @omega.js/desktop packages the auto-update zip under since #867)
  *   win32  — the NSIS setup .exe (run silently with /S; NSIS is what lets RM
  *            self-update via electron-updater on Windows)
  *   linux  — the .AppImage entry
@@ -111,8 +112,10 @@ function pickArtifact(feed, platform, arch) {
   if (platform === 'darwin') {
     picked = names.find((n) => n.endsWith(`-${arch}-mac.zip`))
       || names.find((n) => n.endsWith('-universal-mac.zip'))
-      // The name @omega.js/desktop packages under since #620 — a feed published
-      // before it still answers on one of the forms above.
+      // A feed published before #867 still carries the arch-shaped name; the
+      // last form is what @omega.js/desktop packages the mac auto-update zip
+      // under now. This reads the RM app's OWN feed, so every published form
+      // stays answerable.
       || names.find((n) => n.endsWith('-mac-universal.zip'))
       || names.find((n) => n.endsWith('-mac.zip'));
   } else if (platform === 'win32') {

package/dist/lib/sign-helpers/auto-unlock.js

@@ -3,8 +3,11 @@
 //
 // Strategy: in parallel with the signtool invocation, poll the Win32 window
 // list (via automately.getWindows() — a single native call, ~1-5ms) looking
-// for a "Token Logon" window. When detected, focus it and type the password
-// + Enter via automately (a maintained nutjs fork).
+// for a "Token Logon" window. When detected, type the password + Enter via
+// automately (a maintained nutjs fork), then watch the dialog for a few seconds:
+// a dialog that stays open after typing means the keystrokes did not reach it
+// (a locked console does exactly that, [#864](https://github.com/Omega-JS-Stack/omega/issues/864)),
+// and that is said out loud instead of leaving signtool's silence unexplained.
 //
 // Falls back to a no-op if:
 //   - automately isn't installed (optional dep, may have failed to compile)
@@ -20,30 +23,44 @@ try {
   automately = null;
 }
 
-const POLL_INTERVAL_MS    = 500;    // automately.getWindows() is fast — poll twice a second
-const POLL_TIMEOUT_MS     = 60000;
-const PRE_TYPE_DELAY_MS   = 2000;   // safety wait after detecting dialog before typing
-const PER_CHAR_DELAY_MS   = 60;     // small delay between keystrokes — some dialogs drop chars on fast input
+const TIMINGS = {
+  pollIntervalMs: 500,    // automately.getWindows() is fast — poll twice a second
+  pollTimeoutMs:  60000,
+  preTypeDelayMs: 2000,   // safety wait after detecting dialog before typing
+  perCharDelayMs: 60,     // small delay between keystrokes — some dialogs drop chars on fast input
+  confirmMs:      10000,  // how long a typed-into dialog gets to close before that is reported
+};
 
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
-async function findTokenLogonWindow() {
-  const windows = await automately.getWindows();
-  for (const w of windows) {
-    let title = '';
-    try { title = await w.title; } catch (e) { continue; }
-    if (title && title.startsWith('Token Logon')) return title;
-  }
-  return null;
+// The two things the helper does to the desktop, behind one seam so the loop
+// above them is provable without a desktop.
+function automatelyDriver() {
+  return {
+    findTokenLogonWindow: async () => {
+      const windows = await automately.getWindows();
+      for (const w of windows) {
+        let title = '';
+        try { title = await w.title; } catch (e) { continue; }
+        if (title && title.startsWith('Token Logon')) return title;
+      }
+      return null;
+    },
+    typeText:   (text) => automately.keyboard.type(text),
+    pressEnter: () => automately.keyboard.type(automately.Key.Enter),
+  };
 }
 
-function startAutoUnlock({ password, logger }) {
-  if (process.platform !== 'win32') return { stop: () => {} };
+function startAutoUnlock({ password, logger, driver, timings, platform }) {
+  platform = platform || process.platform;
+  if (platform !== 'win32') return { stop: () => {} };
   if (!password) return { stop: () => {} };
-  if (!automately) {
+  if (!driver && !automately) {
     if (logger) logger.warn('automately not installed — SafeNet password prompt will need manual entry. Run `npm install` in the @omega.js/desktop repo to enable auto-unlock.');
     return { stop: () => {} };
   }
+  driver  = driver || automatelyDriver();
+  timings = { ...TIMINGS, ...(timings || {}) };
 
   let stopped = false;
   let typed   = false;
@@ -51,42 +68,63 @@ function startAutoUnlock({ password, logger }) {
 
   (async function poll() {
     let attempt = 0;
-    while (!stopped && !typed && Date.now() - startedAt < POLL_TIMEOUT_MS) {
+    while (!stopped && !typed && Date.now() - startedAt < timings.pollTimeoutMs) {
       attempt += 1;
       const elapsed = Math.round((Date.now() - startedAt) / 1000);
       const pollStart = Date.now();
       let title = null;
       try {
-        title = await findTokenLogonWindow();
+        title = await driver.findTokenLogonWindow();
       } catch (e) {
         if (logger) logger.log(`auto-unlock: poll ${attempt} (${elapsed}s) — getWindows error: ${e.message}`);
       }
       const pollMs = Date.now() - pollStart;
 
       if (title) {
-        if (logger) logger.log(`auto-unlock: SafeNet Token Logon dialog detected (attempt ${attempt}, ${elapsed}s, poll took ${pollMs}ms) — title: "${title}" — waiting ${PRE_TYPE_DELAY_MS}ms before typing...`);
-        await sleep(PRE_TYPE_DELAY_MS);
+        if (logger) logger.log(`auto-unlock: SafeNet Token Logon dialog detected (attempt ${attempt}, ${elapsed}s, poll took ${pollMs}ms) — title: "${title}" — waiting ${timings.preTypeDelayMs}ms before typing...`);
+        await sleep(timings.preTypeDelayMs);
 
-        if (logger) logger.log(`auto-unlock: typing password (${password.length} chars, ~${PER_CHAR_DELAY_MS}ms each)...`);
+        if (logger) logger.log(`auto-unlock: typing password (${password.length} chars, ~${timings.perCharDelayMs}ms each)...`);
         for (const ch of password) {
           if (stopped) return;
-          await automately.keyboard.type(ch);
-          await sleep(PER_CHAR_DELAY_MS);
+          await driver.typeText(ch);
+          await sleep(timings.perCharDelayMs);
         }
-        await automately.keyboard.type(automately.Key.Enter);
+        await driver.pressEnter();
         typed = true;
         if (logger) logger.log('auto-unlock: password typed + Enter pressed.');
+        await confirmDialogClosed();
         return;
       }
 
       if (logger) logger.log(`auto-unlock: poll ${attempt} (${elapsed}s, took ${pollMs}ms) — no Token Logon window`);
-      await sleep(POLL_INTERVAL_MS);
+      await sleep(timings.pollIntervalMs);
     }
-    if (!typed && !stopped && logger) logger.warn(`auto-unlock: timed out after ${Math.round(POLL_TIMEOUT_MS / 1000)}s without seeing the Token Logon dialog`);
+    if (!typed && !stopped && logger) logger.warn(`auto-unlock: timed out after ${Math.round(timings.pollTimeoutMs / 1000)}s without seeing the Token Logon dialog`);
   })().catch((e) => {
     if (logger) logger.warn(`auto-unlock: poll error: ${e.message}`);
   });
 
+  // The dialog closing is the only proof the keystrokes landed in it.
+  async function confirmDialogClosed() {
+    const typedAt = Date.now();
+    while (!stopped && Date.now() - typedAt < timings.confirmMs) {
+      await sleep(timings.pollIntervalMs);
+      let title = null;
+      try {
+        title = await driver.findTokenLogonWindow();
+      } catch (e) {
+        if (logger) logger.log(`auto-unlock: confirm poll — getWindows error: ${e.message}`);
+        title = 'unknown';
+      }
+      if (!title) {
+        if (logger) logger.log('auto-unlock: Token Logon dialog closed.');
+        return;
+      }
+    }
+    if (!stopped && logger) logger.warn(`auto-unlock: the Token Logon dialog is still open ${Math.round(timings.confirmMs / 1000)}s after typing — the keystrokes did not reach it. Is the console session locked?`);
+  }
+
   return {
     stop: () => { stopped = true; },
   };

package/dist/lib/sign-helpers/console-lock.js

@@ -0,0 +1,34 @@
+// Is the box's console session locked? The Token Logon dialog the SafeNet
+// driver raises renders on the interactive desktop, and the auto-unlock helper
+// types the PIN into whatever holds keyboard focus there. Behind a lock screen
+// the dialog still exists (the window poll enumerates it) but every keystroke
+// lands on the lock screen, so signtool waits for a PIN that never arrives
+// ([#864](https://github.com/Omega-JS-Stack/omega/issues/864): a Windows Update
+// restart auto-signed the box in and locked it, and the sign job hung six hours).
+//
+// Windows shows the lock screen through LogonUI.exe, which exits on unlock, so
+// its presence in the process list IS the locked state.
+
+const { execute } = require('node-powertools');
+
+const TASKLIST_CMD = 'tasklist /fi "IMAGENAME eq LogonUI.exe" /fo csv /nh';
+
+// Pure: read tasklist's CSV for the lock-screen process.
+function isConsoleLocked(tasklistOutput) {
+  return /"LogonUI\.exe"/i.test(String(tasklistOutput || ''));
+}
+
+// Throw, naming the cause and the fix, when the console is locked. Off Windows
+// there is no lock screen to check.
+async function assertConsoleUnlocked(options) {
+  options = options || {};
+  const platform = options.platform || process.platform;
+  const exec     = options.exec || ((cmd) => execute(cmd, { log: false }));
+  if (platform !== 'win32') return;
+
+  if (isConsoleLocked(await exec(TASKLIST_CMD))) {
+    throw new Error('The console session is locked (LogonUI.exe is running), so the PIN cannot reach the Token Logon dialog. Unlock the box (a Windows Update restart leaves it locked) and re-run.');
+  }
+}
+
+module.exports = { isConsoleLocked, assertConsoleUnlocked };

package/dist/lib/sign-helpers/exec-with-limit.js

@@ -0,0 +1,68 @@
+// Run a shell command with a hard time limit. node-powertools' `execute` is the
+// runner every sign call already uses (shell, piped stdio, rejects with stderr),
+// and it settles only on the child's `close` event. So the limit lives on a
+// timer of its own: when it fires the attempt is rejected THEN, whatever the
+// termination below manages, instead of holding the job until GitHub's six-hour
+// default does it ([#864](https://github.com/Omega-JS-Stack/omega/issues/864)).
+//
+// `execute` spawns through a shell, so the program is the shell's child. On
+// Windows `taskkill /T` takes the tree, the same call `runner.js` makes on a
+// listener. Elsewhere the child is spawned detached, which puts the shell at
+// the head of its own process group, and the negative pid signals the group.
+
+const { spawnSync } = require('child_process');
+const { execute } = require('node-powertools');
+
+const logger = new (require('../../build.js'))().logger('exec-with-limit');
+
+// A kill that failed is exactly the state the operator needs to see, so every
+// failure is said, never swallowed.
+function terminateTree(child, platform) {
+  if (platform === 'win32') {
+    const k = spawnSync('taskkill', ['/F', '/PID', String(child.pid), '/T'], { encoding: 'utf8' });
+    if (k.status !== 0) logger.warn(`taskkill /PID ${child.pid} /T exited ${k.status}: ${String(k.stderr || k.stdout || '').trim()}`);
+    return;
+  }
+  try {
+    process.kill(-child.pid, 'SIGKILL');
+  } catch (e) {
+    logger.warn(`kill of process group ${child.pid} failed: ${e.message}`);
+  }
+}
+
+// Resolves with the command's stdout; rejects with the command's own error, or
+// with one naming the limit when the limit fired first.
+function execWithLimit(cmd, options) {
+  options = options || {};
+  const { limitMs, label = 'command' } = options;
+  if (!(limitMs > 0)) throw new Error(`execWithLimit needs a positive limitMs (got ${limitMs})`);
+
+  const platform = process.platform;
+  let child;
+  let timedOut = false;
+
+  // `detached` on Windows would open a console window for the child; on POSIX
+  // it is the process group the kill above needs. `execute` runs the setup
+  // callback synchronously, so `child` is set before this returns.
+  const run = execute(cmd, { log: false, config: { detached: platform !== 'win32' } }, (c) => { child = c; });
+
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      timedOut = true;
+      reject(new Error(`${label} produced no verdict within ${Math.round(limitMs / 1000)}s and was terminated`));
+      terminateTree(child, platform);
+    }, limitMs);
+
+    run.then(
+      (output) => { clearTimeout(timer); resolve(output); },
+      (e) => {
+        clearTimeout(timer);
+        // After the limit fired, the child's own verdict is the termination we
+        // asked for; the rejection above already said what happened.
+        if (!timedOut) reject(e);
+      },
+    );
+  });
+}
+
+module.exports = { execWithLimit };

package/dist/lib/sign-helpers/resolve-icons.js

@@ -14,7 +14,7 @@
 // Retina (@2x) variants are DERIVED. Consumers ship ONE file at the @2x (native) size.
 // @omega.js/desktop downscales it to write the @1x sibling. So `tray.png` is the 32x32 native retina
 // source (consumer-facing input name), and @omega.js/desktop emits both `trayTemplate.png` (16x16)
-// and `trayTemplate@2x.png` (32x32) into `dist/config/icons/macos/`. The output name
+// and `trayTemplate@2x.png` (32x32) into `dist/config/icons/mac/`. The output name
 // diverges from the input on macOS because the `Template` suffix is a system magic
 // marker that triggers auto-inversion in dark mode. Same retina derivation for
 // `dmg.png` (1080x760 native → emits 540x380 + 1080x760, no name change).
@@ -28,7 +28,7 @@ const jetpack = require('fs-jetpack');
 const sharp   = require('sharp');
 
 // Slot defs: per platform, a list of { slot, file, outFile, retina } entries.
-//   slot    = key under resolved[platform] (e.g. 'app' → resolved.macos.app)
+//   slot    = key under resolved[platform] (e.g. 'app' → resolved.mac.app)
 //   file    = INPUT filename — what consumers ship in config/icons/<platform>/ (or global/)
 //   outFile = OUTPUT filename written into dist/config/icons/<platform>/.
 //             Defaults to `file`. Diverges only when the on-disk runtime name
@@ -37,8 +37,10 @@ const sharp   = require('sharp');
 //             @omega.js/desktop owns that detail so consumers can just call it `tray.png`).
 //   retina  = if set, the SOURCE file is treated as @2x (native). @omega.js/desktop downscales it
 //             to produce the @1x sibling. Both files are written into dist/.
+// The platform keys are OMEGA's vocabulary (#867): `mac`, never `macos`, both
+// as the consumer's `config/icons/<platform>/` dir and as the dist output dir.
 const SLOTS = {
-  macos: [
+  mac: [
     { slot: 'app',   file: 'icon.png' },
     { slot: 'tray',  file: 'tray.png', outFile: 'trayTemplate.png', retina: true },
     { slot: 'dmg',   file: 'dmg.png',                                retina: true },
@@ -123,7 +125,7 @@ async function resolveAndCopy({ config, projectRoot, distRoot, emDefaultsRoot })
   const distIconsRoot = path.join(distRoot, 'config', 'icons');
   jetpack.dir(distIconsRoot);
 
-  const resolved = { macos: {}, windows: {}, linux: {} };
+  const resolved = { mac: {}, windows: {}, linux: {} };
 
   // First pass: resolve each platform/slot. For retina slots, source file is treated as
   // @2x; @omega.js/desktop emits both <slot>.png (downscaled) and <slot>@2x.png (the source) into dist.

package/dist/lib/tray.js

@@ -166,15 +166,16 @@ const tray = {
   //
   // Returns null if nothing is found (caller logs).
   _defaultIconPath() {
-    const platform = process.platform === 'darwin' ? 'macos'
-      : process.platform === 'win32' ? 'windows'
-      : 'linux';
+    // The icon dirs are OMEGA's vocabulary (mac/windows/linux), so the OS is
+    // read through the one translation point (#867). Electron runs nowhere else,
+    // so an unknown OS falling back to linux is the safe read.
+    const platform = require('../utils/platform.js').desktopPlatform() || 'linux';
     // INPUT name (what consumers ship in config/icons/<platform>/ or global/) is always tray.png.
-    // OUTPUT name (what gulp/build-config writes into dist/config/icons/macos/) is
-    // trayTemplate.png on mac — the `Template` suffix is a macOS magic marker that
+    // OUTPUT name (what gulp/build-config writes into dist/config/icons/mac/) is
+    // trayTemplate.png on mac: the `Template` suffix is a macOS magic marker that
     // makes the OS auto-invert the icon in dark mode.
     const inFile  = 'tray.png';
-    const outFile = platform === 'macos' ? 'trayTemplate.png' : 'tray.png';
+    const outFile = platform === 'mac' ? 'trayTemplate.png' : 'tray.png';
     const fallbackFile = 'icon.png'; // tray → app icon if absent
 
     const projectRoot = require('../utils/app-root.js')();

package/dist/main.js

@@ -3,6 +3,7 @@
 // Boot sequence below — each step delegates to a `lib/*.js` module. Stubs today, real impls land in pass 2.
 
 const LoggerLite = require('./lib/logger-lite.js');
+const { setEnvironment, ENVIRONMENT_VAR } = require('./vendor/config/environment.js');
 
 const storage      = require('./lib/storage.js');
 const theme        = require('./lib/theme.js');
@@ -146,6 +147,21 @@ Manager.prototype.initialize = async function (consumerConfig, options) {
   self.config = consumerConfig || {};
   self._options = options || {};
 
+  // The environment's ONE input is the `OMEGA_ENVIRONMENT` variable
+  // ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)), and a lane
+  // that named one is NEVER overridden here
+  // ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). The baked word
+  // is the FALLBACK, for the one case with no parent lane to inherit from: a
+  // packaged app, where this is the input every later read answers (the
+  // context-free ones, like test-stealth's, included). A dev boot inherits the
+  // word from the gulp lane that spawned this electron, and the test lanes spawn
+  // their child with `testing` while booting a PRODUCTION artifact, so writing
+  // the baked word over theirs turned every isTesting() gate in a booted app
+  // silently off.
+  if (!process.env[ENVIRONMENT_VAR] && self.config.environment) {
+    setEnvironment(self.config.environment);
+  }
+
   {
     const fs = require('fs');
     const _path = require('path');