@omega.js/desktop 0.50.0 → 0.51.0

package/dist/test/suites/renderer/cross-context-helpers.test.js

@@ -23,19 +23,20 @@ module.exports = defineCases({
       },
     },
     {
-      name: 'isTesting() returns true (we are running under OMEGA_TEST_MODE=true)',
+      name: 'isTesting() returns true (this lane named OMEGA_ENVIRONMENT=testing)',
       run: (ctx) => {
         ctx.expect(window.__emTestManager.isTesting()).toBe(true);
       },
     },
     {
-      name: 'isDevelopment() works (renderer has no app.isPackaged so it falls through)',
+      name: 'isDevelopment() answers the one input, with no renderer-specific sniff',
       run: (ctx) => {
-        // In renderer process, `electron.app` is undefined, so the helper falls back
-        // to NODE_ENV / config.em.environment. The test harness seeds config with
-        // environment='production' so this should report false.
+        // Nothing here reads app.isPackaged or NODE_ENV any more (#817): the
+        // preload has a process, so the lane's OMEGA_ENVIRONMENT answers, and a
+        // real renderer bundle answers from the baked config.environment.
         const v = window.__emTestManager.isDevelopment();
         ctx.expect(typeof v).toBe('boolean');
+        ctx.expect(v).toBe(false);
       },
     },
     {
@@ -44,7 +45,7 @@ module.exports = defineCases({
         const dev  = window.__emTestManager.isDevelopment();
         const test = window.__emTestManager.isTesting();
         const prod = window.__emTestManager.isProduction();
-        // We run under OMEGA_TEST_MODE=true → testing wins; dev and prod are both false.
+        // This lane named testing; dev and prod are both false.
         ctx.expect(test).toBe(true);
         ctx.expect(dev).toBe(false);
         ctx.expect(prod).toBe(false);
@@ -62,16 +63,18 @@ module.exports = defineCases({
       },
     },
     {
-      name: 'getEnvironment(): testing (OMEGA_TEST_MODE) takes precedence over config.em.environment',
+      name: 'getEnvironment(): the lane variable wins over the baked config.environment',
       run: (ctx) => {
-        // The test runner sets OMEGA_TEST_MODE=true, which wins over any config override —
-        // getEnvironment() always reports 'testing' here regardless of em.environment.
-        window.__emTestManager.setConfig('em.environment', 'production');
+        // The test runner names OMEGA_ENVIRONMENT=testing, and this preload has a
+        // process to read it from, so it wins over whatever the artifact was
+        // baked as (#817). A real renderer bundle has no process and takes the
+        // baked word, which is the other half of the same one-input rule.
+        window.__emTestManager.setConfig('environment', 'production');
         ctx.expect(window.__emTestManager.getEnvironment()).toBe('testing');
-        window.__emTestManager.setConfig('em.environment', 'development');
+        window.__emTestManager.setConfig('environment', 'development');
         ctx.expect(window.__emTestManager.getEnvironment()).toBe('testing');
         // Reset.
-        window.__emTestManager.setConfig('em.environment', 'production');
+        window.__emTestManager.setConfig('environment', 'production');
       },
     },
     {
@@ -104,7 +107,7 @@ module.exports = defineCases({
       },
     },
     {
-      name: 'getWebsiteUrl: dev → the classic dev origin https://localhost:4000',
+      name: 'getWebsiteUrl: dev → https://localhost:4000, from the baked classic map',
       run: (ctx) => {
         ctx.expect(window.__emTestManager.getWebsiteUrl('development')).toBe('https://localhost:4000');
       },
@@ -118,9 +121,9 @@ module.exports = defineCases({
     {
       name: 'getWebsiteUrl: no-arg resolves local under testing; explicit arg overrides',
       run: (ctx) => {
-        // The renderer always runs under OMEGA_TEST_MODE (testing wins), so the no-arg form
-        // correctly resolves LOCAL regardless of config — that's the safety guarantee.
-        window.__emTestManager.setConfig('em.environment', 'production');
+        // This lane is testing, so the no-arg form resolves LOCAL regardless of
+        // what the artifact was baked as: that's the safety guarantee.
+        window.__emTestManager.setConfig('environment', 'production');
         ctx.expect(window.__emTestManager.getWebsiteUrl()).toBe('https://localhost:4000');
         // An explicit env arg bypasses the current environment and pins the mapping.
         ctx.expect(window.__emTestManager.getWebsiteUrl('production')).toBe('https://example.com');

package/dist/utils/build-pipeline.js

@@ -18,18 +18,18 @@ function gulpCommand(task) {
 // loads the whole command surface.
 //
 // There is no `setup` step any more (#675): the local half runs inside the gulp
-// `defaults` task, which is the first step of every gulp build. What the plans
-// still need before signing is the Apple artifacts (#678) — `certs`.
+// `defaults` task, which is the first step of every gulp build. There is no
+// `certs` copy step either ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)):
+// signing material is READ IN PLACE from the signing tree, and the env load
+// derives the paths to it once (utils/load-env.js).
 const RUNNERS = {
   clean: (options) => require('../commands/clean.js')(options),
-  certs: () => {
-    const Manager = new (require('../build.js'));
-    require('./deliver-certs.js').deliverTargetCerts({
-      projectDir: Manager.getRootPath('project'),
-      logger: Manager.logger('certs'),
-    });
-  },
-  'validate-certs': (options) => require('../commands/validate-certs.js')(options),
+  // The credentials the brand's DECLARED formats cannot ship without (#867),
+  // refused before a minute of build time. Publish declares this step; a bare
+  // build does not, because a build puts nothing in front of users.
+  'ship-keys': () => require('./ship-keys.js').assertShipKeys(),
+  // `strict` rides the STEP: publish declares it (#891), a bare verb does not.
+  'validate-certs': (options, step) => require('../commands/validate-certs.js')({ ...options, strict: step.strict === true || options.strict === true }),
   gulp: (options, step) => execute(gulpCommand(step.task), { log: true }),
 };
 

package/dist/utils/github.js

@@ -1,16 +1,19 @@
-// Shared GitHub helpers used by push-secrets and the release pipeline.
+// The Octokit factory for the release pipeline (uploads, the draft flip).
 //
-// WHICH repo a verb addresses is not decided here: the app repo is
-// @omega.js/config's `brandRepo` and the releases repo its `releasesRepo`, from
-// config/omega.json5 alone (#799). The old package.json/git-remote discovery is
-// gone: a brand nested in another repo (a target inside a brand monorepo, the
-// playground inside the framework monorepo) resolved to the ENCLOSING repo.
+// WHICH repo a verb addresses is not decided here: the source repo is
+// @omega.js/config's `sourceRepo` and the releases repo its `releasesRepo`,
+// from config/omega.json5 alone (#799). The old package.json/git-remote
+// discovery is gone: a brand nested in another repo (a target inside a brand
+// monorepo, the playground inside the framework monorepo) resolved to the
+// ENCLOSING repo.
+//
+// CREATING a repo is not decided here either (#883): every repo a brand owns
+// is created and reconciled by `@omega.js/devkit/github-repo`'s ensureRepo, the
+// one home the manage walk and the web deploy use too. This file's own copy is
+// gone with it.
 //
 // Octokit factory: returns an authenticated client when GH_TOKEN is set. Returns null otherwise so
 // callers can choose to no-op or bail with a friendly message.
-//
-// Repo ensure: idempotently create a repo under <owner> if it doesn't exist. Used by the
-// deploy precheck to auto-provision the brand's public releases repo.
 
 // silent: true — pass a no-op logger so transient 404s during polling (e.g. fetching
 // in-progress job logs) don't spam the console. Errors still surface via thrown rejections.
@@ -26,48 +29,6 @@ function getOctokit(opts = {}) {
   return new Octokit(config);
 }
 
-// Idempotent: returns true if the repo exists (created or already there), false on failure.
-// Honors the `owner` distinction between user vs. org — the API endpoints differ.
-async function ensureRepo(octokit, owner, repo, opts = {}) {
-  const description = opts.description || '';
-  const isPrivate = opts.private === true;
-
-  try {
-    await octokit.rest.repos.get({ owner, repo });
-    return { created: false, exists: true };
-  } catch (err) {
-    if (err.status !== 404) throw err;
-  }
-
-  // Need to create. Check if owner is the authenticated user or an org.
-  let isOrg = false;
-  try {
-    const { data: me } = await octokit.rest.users.getAuthenticated();
-    isOrg = me.login.toLowerCase() !== owner.toLowerCase();
-  } catch (e) {
-    isOrg = true;
-  }
-
-  const params = {
-    name: repo,
-    description,
-    private: isPrivate,
-    has_issues: true,
-    has_projects: false,
-    has_wiki: false,
-    auto_init: true,
-  };
-
-  if (isOrg) {
-    await octokit.rest.repos.createInOrg({ org: owner, ...params });
-  } else {
-    await octokit.rest.repos.createForAuthenticatedUser(params);
-  }
-
-  return { created: true, exists: true };
-}
-
 module.exports = {
   getOctokit,
-  ensureRepo,
 };

package/dist/utils/load-env.js

@@ -0,0 +1,66 @@
+/**
+ * The desktop target's ONE env load
+ * ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
+ *
+ * Two boots populate `process.env` for a desktop target: the CLI (`src/cli.js`)
+ * and gulp (`src/gulp/main.js`, which runs as its own process and is invoked
+ * directly by `npm start`). Both call HERE, so a signing path is derived once,
+ * by one rule, and every reader after it (the build, `validate-certs`, the
+ * deploy precheck's secrets publish) reads the answer instead of deriving its
+ * own. The derivation itself is `@omega.js/devkit/signing-env`: the signing
+ * tree, company tier first.
+ *
+ * The lines it prints name PATHS, never contents: `CSC_LINK derived from
+ * <path>` is exactly what a signing failure is diagnosed from. WHEN they print
+ * is the caller's (gulp holds them until its log tee is attached, so build.log
+ * carries them); the SHAPE of them is here, once.
+ */
+const { loadEnv } = require('../vendor/config/index.js');
+const { deriveSigningEnv } = require('../vendor/devkit/signing-env.js');
+
+/**
+ * Load the `.env` cascade for a desktop target and derive its signing paths.
+ *
+ * @param {string} projectRoot - The target root.
+ * @param {object} [options]
+ * @param {object} [options.logger] - `{ log, warn }`; the result is reported at
+ *   once when given, and handed back for the caller to report otherwise.
+ * @param {object} [options.env] - The env map to populate (default process.env).
+ * @returns {{ derived: Array<{ key: string, value: string }>, problems: Array<{ key: string, reason: string }> }}
+ */
+function loadDesktopEnv(projectRoot, options = {}) {
+  const env = options.env || process.env;
+
+  // The cascade first (shell > target .env > brand .env > company .env). The
+  // target name delivers the schema's `deliverAs` renames (#678).
+  loadEnv(projectRoot, { target: 'desktop' });
+
+  const result = deriveSigningEnv({ env, targetDir: projectRoot });
+
+  if (options.logger) {
+    reportSigningEnv(result, options.logger);
+  }
+
+  return result;
+}
+
+/**
+ * Say what the derivation answered: one line per key, paths only.
+ *
+ * @param {{ derived: Array, problems: Array }} result - What loadDesktopEnv returned.
+ * @param {object} logger - `{ log, warn }`.
+ */
+function reportSigningEnv({ derived, problems }, logger) {
+  for (const { key, value } of derived) {
+    logger.log(`${key} derived from ${value}`);
+  }
+
+  // A file that is THERE and cannot be used is never silent: the key stays
+  // unset (Keychain discovery stays the default), and the reason is said out
+  // loud so the next rung's error is not the first anyone hears of it.
+  for (const { key, reason } of problems) {
+    logger.warn(`${key} not derived: ${reason}`);
+  }
+}
+
+module.exports = { loadDesktopEnv, reportSigningEnv };

package/dist/utils/mode-helpers.js

@@ -1,106 +1,43 @@
-// Runtime mode helpers (@omega.js/backend-pattern), shared across all three context Managers
-// (main / renderer / preload) and the build-time Manager.
+// Runtime mode helpers, shared across all three context Managers (main /
+// renderer / preload) and the build-time Manager.
 //
-// Three MUTUALLY EXCLUSIVE environments — exactly one is true:
-//   isDevelopment() — app run from source / being developed (unpackaged, e.g. `electron .`,
-//                     gulp dev), and NOT testing. Authoritative signal: `app.isPackaged ===
-//                     false`. Falls back to NODE_ENV when `app` isn't available (preload,
-//                     build-time scripts, renderer).
-//   isTesting()     — app being tested (@omega.js/desktop's test framework running this process). Single
-//                     canonical env var: `OMEGA_TEST_MODE=true`. TAKES PRECEDENCE over dev:
-//                     a test run is unpackaged, but it's a TEST, not development.
-//   isProduction()  — app packaged & distributed to users (`app.isPackaged === true`),
-//                     and NOT testing. A real positive check — NOT `!isDevelopment()`.
+// The environment half is NOT implemented here any more
+// ([#817](https://github.com/Omega-JS-Stack/omega/issues/817)). It is
+// @omega.js/config's `environment.js`, the ONE module every OMEGA target
+// answers from, and this file only re-exports it beside desktop's own
+// getVersion(). The four copies this replaced each carried their own signal
+// list and their own default, and they disagreed: desktop's answered
+// `production` with no signal while the extension's answered `development`, so
+// a desktop dev boot bundled itself as a production artifact.
 //
-// To gate "anything non-production" (skip OS side effects, isolate data) use
-// `!isProduction()` or `isDevelopment() || isTesting()` intentionally — never assume two
-// values.
+// The contract, in full, is the shared module's:
+//   getEnvironment() reads ONE input, the `OMEGA_ENVIRONMENT` variable in Node
+//   and the baked `OMEGA_BUILD_JSON.config.environment` in a renderer (which
+//   has no process.env), and a context with neither throws by name. Nothing
+//   sniffs `app.isPackaged` or NODE_ENV any more: the lane that boots or builds
+//   this app names the environment, once, where it resolves its config
+//   (src/build.js's getConfig for the build lane, main.js's initialize for the
+//   packaged runtime).
 //
-// Use these whenever behavior should differ by *what kind of process* you're in —
-// shorter timeouts in tests, DevTools menu items only in dev, prompts suppressed in
-// tests. Don't use them for "should we hit dev or prod backends" — that's a config
-// concern; use `getEnvironment()` for that (in build.js).
+//   isDevelopment() / isProduction() / isTesting() DERIVE from it, so they can
+//   never disagree with it and exactly one is true. isProduction() is a real
+//   positive check, never `!isDevelopment()`. Gate "anything non-production"
+//   with `!isProduction()` or `isDevelopment() || isTesting()` intentionally.
 //
-// Renderer caveat: Electron's `app` API isn't available in renderer processes
-// (the renderer's `electron` import surface has `ipcRenderer`, `contextBridge`,
-// etc. — no `app`). Same in preload. So those contexts fall back to NODE_ENV /
-// config.em.environment. To get a renderer-truthful signal, the consumer can have
-// main inject the value into `OMEGA_BUILD_JSON.runtime` at build time (future
-// enhancement); for now, NODE_ENV being inherited from the parent process is the
-// pragmatic answer.
-//
-// In plain Node (gulp tasks, CLI commands), `require('electron')` returns the
-// binary path as a string — no `app` object — so the same `app && typeof
-// app.isPackaged === 'boolean'` check naturally falls through to NODE_ENV.
-
-// The three environment checks are MUTUALLY EXCLUSIVE — exactly one is true:
-//   isDevelopment() — app run from source / being developed (unpackaged, NOT testing).
-//   isTesting()     — app being tested (OMEGA_TEST_MODE=true). Takes precedence over dev.
-//   isProduction()  — app packaged & distributed to users (real positive check, NOT testing).
-// Testing wins first: a test run is unpackaged, but it's a TEST, not development.
-
-// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
-// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
-// Precedence: testing → explicit config override → Electron app.isPackaged → build-time signal.
-function getEnvironment() {
-  // 1. Testing wins — set by @omega.js/desktop's test runners (OMEGA_TEST_MODE=true), regardless of packaged state.
-  if (process.env.OMEGA_TEST_MODE === 'true') return 'testing';
-
-  // 2. An explicit config.em.environment override — the consumer's deliberate decision. It beats
-  //    the auto-detected app.isPackaged (e.g. a packaged app the consumer wants to treat as dev).
-  const cfgEnv = this?.config?.em?.environment;
-  if (cfgEnv === 'development' || cfgEnv === 'testing' || cfgEnv === 'production') return cfgEnv;
-
-  // 3. In Electron main, `app.isPackaged` is the authoritative runtime signal (more accurate
-  //    than env vars). In renderer/preload, `electron` has no `app`; from plain Node (gulp/CLI),
-  //    `require('electron')` returns the binary path string — `.app` is undefined in both, so we
-  //    fall through to the build signals below.
-  //    In renderer bundles (target: 'web'), require is not available — skip entirely.
-  if (typeof require !== 'undefined') {
-    try {
-      const { app } = require('electron');
-      if (app && typeof app.isPackaged === 'boolean') return app.isPackaged ? 'production' : 'development';
-    } catch (_) {}
-  }
-
-  // 4. Build-time / Node signals. OMEGA_BUILD_MODE=true is set during a production build
-  //    (npm run build / npm run release); NODE_ENV=development is the dev fallback.
-  if (process.env.OMEGA_BUILD_MODE === 'true') return 'production';
-  if (process.env.NODE_ENV === 'development') return 'development';
-
-  // 5. Default: production. @omega.js/desktop's deployed RUNTIME can reach here without a dev signal — a
-  //    packaged app whose `app.isPackaged` somehow didn't resolve is still a shipped binary,
-  //    so production is the safe assumption for a distributed artifact. (Contrast UJM/BXM,
-  //    whose deployed artifacts always carry their signal, so they default to development —
-  //    a bare context there is just build tooling.)
-  return 'production';
-}
-
-// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
-// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
-// positive check (never `!isDevelopment()`).
-function isDevelopment() {
-  return getEnvironment.call(this) === 'development';
-}
-
-function isProduction() {
-  return getEnvironment.call(this) === 'production';
-}
-
-function isTesting() {
-  return getEnvironment.call(this) === 'testing';
-}
+// The shared module requires nothing, so it rides the renderer bundle (a
+// browser context with no Node built-ins) exactly as this file always has.
+const environment = require('../vendor/config/environment.js');
 
-// `getVersion()` — returns the app's version string. Sources, in priority order:
-//   1. `electron.app.getVersion()` when running inside Electron (main process —
+// `getVersion()` returns the app's version string. Sources, in priority order:
+//   1. `electron.app.getVersion()` when running inside Electron (main process,
 //      authoritative; reads from the packaged app's package.json baked into asar).
 //   2. `<cwd>/package.json#version` for build-time scripts / non-Electron contexts.
 //   3. null when neither resolves.
 //
-// Renderer caveat: same as isDevelopment — `electron.app` isn't available in renderer,
-// so the fallback to `process.cwd()/package.json` won't find anything useful in a
-// packaged app. Renderers that need the version should ask main via IPC, or read
-// `OMEGA_BUILD_JSON.package.version` (baked in by the bundle task's `define`).
+// Renderer caveat: `electron.app` isn't available in renderer, so the fallback to
+// `process.cwd()/package.json` won't find anything useful in a packaged app.
+// Renderers that need the version should ask main via IPC, or read
+// `OMEGA_BUILD_JSON.package.version` (baked in by the bundle task).
 function getVersion() {
   if (typeof require !== 'undefined') {
     try {
@@ -121,27 +58,22 @@ function getVersion() {
 }
 
 // Mix the helpers into a Manager constructor's prototype + the constructor itself
-// (so `Manager.isTesting()` works statically too, matching @omega.js/backend's pattern). getEnvironment()
-// is attached here too so all four entry points share one resolver — the URL helpers in
-// url-helpers.js depend on this.getEnvironment() existing.
+// (so `Manager.isTesting()` works statically too). The environment four come from
+// the shared module's own attachTo(), so every desktop entry point and every
+// sibling framework hangs the identical functions; getVersion() is desktop's and
+// is attached beside them. The URL helpers in url-helpers.js depend on
+// this.getEnvironment() existing, so this attachTo() runs first.
 function attachTo(Manager) {
-  Manager.prototype.isDevelopment  = isDevelopment;
-  Manager.prototype.isProduction   = isProduction;
-  Manager.prototype.isTesting      = isTesting;
-  Manager.prototype.getEnvironment = getEnvironment;
-  Manager.prototype.getVersion     = getVersion;
-  Manager.isDevelopment  = isDevelopment;
-  Manager.isProduction   = isProduction;
-  Manager.isTesting      = isTesting;
-  Manager.getEnvironment = getEnvironment;
-  Manager.getVersion     = getVersion;
+  environment.attachTo(Manager);
+  Manager.prototype.getVersion = getVersion;
+  Manager.getVersion = getVersion;
 }
 
 module.exports = {
   attachTo,
-  isDevelopment,
-  isProduction,
-  isTesting,
-  getEnvironment,
+  isDevelopment: environment.isDevelopment,
+  isProduction: environment.isProduction,
+  isTesting: environment.isTesting,
+  getEnvironment: environment.getEnvironment,
   getVersion,
 };

package/dist/utils/platform.js

@@ -0,0 +1,37 @@
+// The ONE translation of Node's platform word into OMEGA's platform
+// vocabulary ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)).
+//
+// OMEGA says `mac`, `windows`, `linux` everywhere it speaks for itself: the
+// config declaration (`platforms.windows.formats.nsis`), the icon dirs
+// (`config/icons/mac/`), the workflow's `platforms` input, the site's
+// `/download/<platform>/<format>` links, and a stored login record. Node says
+// `darwin`/`win32`/`linux`, and electron-builder says `mac`/`win`/`linux`.
+// Those are FOREIGN vocabularies: each is translated at exactly one point, and
+// for Node's that point is here.
+//
+// A bare OS branch (`if (process.platform === 'darwin')`) needs no translation
+// and stays as it is: it reads Node's word to decide Node's behavior and never
+// produces a name anything else consumes. This function is for the places that
+// turn the OS into a NAME: an icon directory, a release directory, the platform
+// a deploy reports building.
+
+// Node's process.platform → OMEGA's word. Electron runs on exactly these three.
+const NODE_PLATFORMS = {
+  darwin: 'mac',
+  win32: 'windows',
+  linux: 'linux',
+};
+
+/**
+ * This machine's platform in OMEGA's vocabulary.
+ *
+ * @param {string} [nodePlatform] - A `process.platform` value (defaults to this
+ *   process's own).
+ * @returns {string|null} 'mac' | 'windows' | 'linux', or null for an OS OMEGA
+ *   has no word for (the caller decides whether that is fatal).
+ */
+function desktopPlatform(nodePlatform = process.platform) {
+  return NODE_PLATFORMS[nodePlatform] || null;
+}
+
+module.exports = { desktopPlatform, NODE_PLATFORMS };

package/dist/utils/runner-env.js

@@ -226,7 +226,8 @@ function runnerLogFile(home) {
 
 // Is this process a TEST run? `OMEGA_TEST_RUNNER` is set by `omega test` for the
 // whole run (and inherited by the electron/boot children); `OMEGA_TEST_MODE` is
-// the canonical signal those children already carried. Either one means: no
+// the marker a sibling framework's runner or a consumer's own test script sets
+// (desktop's runners name the environment instead, #925). Either one means: no
 // command here may touch the machine's real runner home.
 //
 // It reads process.env, ALWAYS, and takes no environment argument. An injected

package/dist/utils/runner-job-guard.js

@@ -0,0 +1,149 @@
+// The box's half of "a self-hosted signer refuses any job that is not a trusted
+// dispatch" ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): the
+// three files `omega runner install` writes beside the runner, so the guard the
+// listener runs before every job is CONFIGURATION on the box rather than a list
+// baked into the shared desktop template.
+//
+// A runner is registered to ONE owner and serves only that owner's repos, so
+// the guard is per box, configured by the box owner (Ian 2026-09-10). The files:
+//
+//   <runner home>\job-started.js        the hook itself, a copy of src/runner/job-started.js
+//   <runner home>\allowed-repos.txt     one `owner/name` (or `owner/*`) per line
+//   <runner home>\allowed-actors.txt    one GitHub login per line
+//
+// and the path of the first one is delivered to each registered runner through
+// its own `<runner dir>\.env` as `ACTIONS_RUNNER_HOOK_JOB_STARTED`, the same
+// file the private HOME travels in
+// ([#807](https://github.com/Omega-JS-Stack/omega/issues/807)).
+//
+// Where the lists COME from at setup: the orgs this box registered against
+// (`<org>/*`, which is exactly the scope a registration already has) and the
+// `GH_TOKEN` user's own login. Narrowing `<org>/*` to individual repos, or
+// adding a second account, is an edit of the file, which is why an org already
+// answered for, by a wildcard or by any repo line, is never appended again.
+const path    = require('path');
+const jetpack = require('fs-jetpack');
+
+// The hook owns the names of its own list files and the way it READS them, so
+// the writer imports both rather than restating either: what this appends is
+// what the hook sees, by construction. Requiring the hook here runs nothing
+// (its work sits behind `require.main === module`), and the hook file itself
+// stays builtins-only for the runner home it is copied into.
+const { readList, REPOS_FILE, ACTORS_FILE } = require('../runner/job-started.js');
+
+const HOOK_FILE = 'job-started.js';
+
+const REPOS_HEADER = [
+  '# The repositories this box will sign for (#875).',
+  '# One `owner/name` per line; `owner/*` is every repo of one owner.',
+  '# `npx omega runner install` appends a line for an org it registered and has',
+  '# no line for yet, so narrowing one to single repos by hand sticks.',
+  '',
+].join('\n');
+
+const ACTORS_HEADER = [
+  '# The GitHub logins this box will sign for (#875): GITHUB_ACTOR must be one.',
+  '# One login per line. A `workflow_dispatch` carries the deploy token\'s user,',
+  '# which is the same account, so one line normally answers for every deploy.',
+  '',
+].join('\n');
+
+/**
+ * The three files, by absolute path.
+ *
+ * @param {string} home - The runner home.
+ * @returns {{hook: string, repos: string, actors: string}} The paths.
+ */
+function jobGuardPaths(home) {
+  return {
+    hook:   path.join(home, HOOK_FILE),
+    repos:  path.join(home, REPOS_FILE),
+    actors: path.join(home, ACTORS_FILE),
+  };
+}
+
+/**
+ * The two allow lists, which are the box's CONFIGURATION: an uninstall keeps
+ * them the way it keeps the box's `.env`, so a re-install never asks again and
+ * a hand-narrowed list is never destroyed. The hook script is install state and
+ * goes with the rest.
+ *
+ * @param {string} home - The runner home.
+ * @returns {string[]} The two list paths.
+ */
+function jobGuardListFiles(home) {
+  const { repos, actors } = jobGuardPaths(home);
+  return [repos, actors];
+}
+
+// Append the lines the file does not answer for yet, and nothing else: a file
+// that already answers for every line is not rewritten at all, so running the
+// setup twice writes the same bytes once.
+function appendMissing(file, header, wanted, answered) {
+  const existing = readList(file);
+  const missing  = wanted.filter((line) => !existing.some((entry) => answered(entry, line)));
+  if (missing.length === 0 && jetpack.exists(file) === 'file') return [];
+
+  const body = existing.length === 0 && jetpack.exists(file) !== 'file'
+    ? `${header}${missing.join('\n')}\n`
+    : `${(jetpack.read(file) || '').replace(/\n*$/, '\n')}${missing.join('\n')}\n`;
+  jetpack.write(file, body);
+  return missing;
+}
+
+/**
+ * Lay the guard down beside the runner, idempotently.
+ *
+ * The hook script is COPIED from this package on every run, so a box picks up a
+ * framework update the next time it installs or starts; the allow lists are the
+ * operator's and are only ever appended to.
+ *
+ * @param {string} home - The runner home.
+ * @param {object} [options]
+ * @param {string[]} [options.orgs] - The orgs this box is registered against.
+ * @param {string} [options.actor] - The GH_TOKEN user's login (absent = leave the actors file alone).
+ * @param {object} [options.logger] - Logger for the one line each write prints.
+ * @returns {{hook: string, repos: string, actors: string, added: {repos: string[], actors: string[]}}} The paths, and what was appended.
+ */
+function ensureRunnerJobGuard(home, options) {
+  const { orgs = [], actor, logger } = options || {};
+  const paths = jobGuardPaths(home);
+
+  jetpack.copy(path.join(__dirname, '..', 'runner', HOOK_FILE), paths.hook, { overwrite: true });
+
+  // An org is answered for by a `<org>/*` line OR by any single repo of it: a
+  // person who narrowed `Omega-JS-Stack/*` to one repo does not get the
+  // wildcard back on the next install.
+  const addedRepos = appendMissing(
+    paths.repos,
+    REPOS_HEADER,
+    orgs.map((org) => `${org}/*`),
+    (entry, line) => entry.split('/')[0].toLowerCase() === line.split('/')[0].toLowerCase(),
+  );
+
+  // No actor (an offline heal, or a `GET /user` that did not answer) writes the
+  // file's header and nothing else: the operator sees the file the hook names,
+  // and an empty list refuses every job rather than passing one.
+  const addedActors = appendMissing(
+    paths.actors,
+    ACTORS_HEADER,
+    actor ? [actor] : [],
+    (entry, line) => entry.toLowerCase() === line.toLowerCase(),
+  );
+
+  if (logger) {
+    if (addedRepos.length > 0)  logger.log(`  Job guard: added ${addedRepos.join(', ')} to ${paths.repos}`);
+    if (addedActors.length > 0) logger.log(`  Job guard: added ${addedActors.join(', ')} to ${paths.actors}`);
+  }
+
+  return { ...paths, added: { repos: addedRepos, actors: addedActors } };
+}
+
+module.exports = {
+  HOOK_FILE,
+  REPOS_FILE,
+  ACTORS_FILE,
+  jobGuardPaths,
+  jobGuardListFiles,
+  ensureRunnerJobGuard,
+};