@omega.js/manager 0.1.0

package/dist/lib/verb-fanout.js

@@ -0,0 +1,128 @@
+/**
+ * The brand-root VERB fan-out — one target-independent verb run over every
+ * target the brand has, framework and custom alike (#603).
+ *
+ * `omega build` and `omega clean` are the two verbs a brand root had for no
+ * target type at all: start, test and deploy each fanned out already, so a
+ * brand could compile or wipe its targets only one `cd` at a time. Both are the
+ * SAME walk with a different word, so they share this one implementation —
+ * commands/build.js and commands/clean.js are its two callers.
+ *
+ * The shape is the deploy fan-out's, deliberately: the same target discovery,
+ * the same `--target=` picker and the same dependency ORDER
+ * (selectTargets — backend first, custom targets last), the same flag
+ * forwarding, and `resolveTargetRun` as the one place a verb becomes a command
+ * (a framework's own `omega <verb>`, or the target's `npm run <verb>`).
+ *
+ * What differs from deploy: targets are INDEPENDENT here. Neither verb
+ * publishes anything, so a failure never stops the walk — knowing every broken
+ * target after one run beats discovering them one build at a time — and any
+ * failure still exits 1. A target that declares no such script steps aside
+ * LOUDLY, naming the target and the verb, and is never counted a failure. And
+ * --dry-run is CONSUMED here rather than forwarded: no framework's build/clean
+ * honors it, so every target prints the command it would have run and the walk
+ * executes nothing.
+ *
+ * The brand-root log tee lives HERE, not in the two verb files (#623): every
+ * other fan-out attaches at the top of its own command, but build and clean
+ * share this one walk and this is the only place that knows the brand root, so
+ * one attach keyed by the verb serves both — logs/build.log and logs/clean.log.
+ */
+const path = require('node:path');
+const chalk = require('chalk').default;
+const attachLogFile = require('../vendor/devkit/attach-log-file.js');
+
+const { resolveBrandRoot, discoverTargets } = require('./brand.js');
+const { resolveTargetRun } = require('./framework-bin.js');
+const { runCommand } = require('./run-command.js');
+const { PICKER_FLAG, assertPickerFlags, selectTargets, buildForwardedFlags } = require('./target-selection.js');
+
+// Both yargs spellings of the flag this fan-out consumes (see the header)
+const DRY_RUN_KEYS = ['dry-run', 'dryRun'];
+
+/**
+ * Run one verb across the brand's targets.
+ *
+ * @param {string} verb - The verb ('build' | 'clean').
+ * @param {object} [options] - The parsed CLI options (--target= consumed, the rest forwarded).
+ * @param {object} [deps] - Test seam: { run } replaces runCommand.
+ * @returns {Promise<void>} - Failures land on process.exitCode; only a retired
+ *                            picker (#780) throws, and it throws before any work.
+ */
+async function runVerbFanout(verb, options = {}, deps = {}) {
+  assertPickerFlags(options);
+
+  const run = deps.run || runCommand;
+
+  const brandRoot = resolveBrandRoot(process.cwd());
+  if (!brandRoot) {
+    console.error(chalk.red(`✗ Not inside a brand monorepo (no config/omega.json5 up the tree) — run inside a brand, or inside a target for that target's ${verb}.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Tee the whole fan-out to <brandRoot>/logs/<verb>.log (#623) — the walk's
+  // OWN verdict on disk (a target's output rides its own log: runCommand
+  // inherits the terminal, so a child never passes through these writers).
+  attachLogFile(path.join(brandRoot, 'logs', `${verb}.log`));
+
+  const targets = discoverTargets(brandRoot).filter((entry) => entry.target || entry.custom);
+  const { selected } = selectTargets({ targets, target: options[PICKER_FLAG] });
+
+  if (selected.length === 0) {
+    console.error(chalk.red(`✗ This brand has no targets under targets/ — nothing ${verb === 'clean' ? 'cleaned' : 'built'}.`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const forwarded = buildForwardedFlags(options, DRY_RUN_KEYS);
+  const dryRun = !!(options['dry-run'] || options.dryRun);
+
+  console.log(chalk.bold(`\nOMEGA brand ${verb} — ${path.basename(brandRoot)}${dryRun ? chalk.dim(' (dry run)') : ''} ${chalk.dim(`(${selected.map((entry) => entry.target || entry.name).join(' → ')})`)}`));
+
+  const summary = [];
+
+  for (const [index, entry] of selected.entries()) {
+    const label = `[${index + 1}/${selected.length}] ${entry.name}`;
+    const resolved = resolveTargetRun(entry, verb, forwarded, { dryRun });
+
+    // A target that declares no such script has nothing to do and nothing
+    // broken — the skip NAMES the target and the verb, because a verb that
+    // quietly did nothing is indistinguishable from one that worked (#603)
+    if (resolved.kind === 'skip') {
+      console.log(chalk.dim(`\n⊘ ${label}: ${resolved.detail} — skipped`));
+      continue;
+    }
+
+    // Under --dry-run the run IS the plan line — nothing executes on either
+    // lane, and a target that would have been skipped still says so above
+    if (resolved.kind === 'plan') {
+      console.log(chalk.dim(`\n⊘ ${label}: dry run — ${resolved.detail}`));
+      continue;
+    }
+
+    if (resolved.kind === 'error') {
+      console.log(chalk.red(`\n✗ ${label}: ${resolved.detail}`));
+      summary.push({ name: entry.name, ok: false, detail: resolved.detail });
+      continue;
+    }
+
+    console.log(chalk.cyan(`${`\n─── ${label} ${chalk.dim(`(${resolved.framework || 'custom'})`)} — ${resolved.label}`.trimEnd()} ───`));
+    const result = await run(resolved.command, resolved.args, entry.path);
+
+    summary.push({ name: entry.name, ok: result.success, detail: result.error });
+  }
+
+  console.log(chalk.bold(`\n${verb.charAt(0).toUpperCase()}${verb.slice(1)} summary`));
+  for (const entry of summary) {
+    console.log(entry.ok
+      ? `  ${chalk.green('✓')} ${entry.name}`
+      : `  ${chalk.red('✗')} ${entry.name} ${chalk.dim(`— ${entry.detail}`)}`);
+  }
+
+  if (summary.some((entry) => !entry.ok)) {
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { runVerbFanout };

package/dist/lib/verify-live.js

@@ -0,0 +1,188 @@
+/**
+ * Live-launch verification — the last mile of the one-command launch
+ * (`omega pipeline --deploy=web`): after the deploy legs push, these checks
+ * confirm the launch surface is actually LIVE from the outside.
+ *
+ *  - site:       HTTPS GET on the brand's canonical URL → 200 + text/html +
+ *                a non-trivial body (a 200 empty shell is not a live site).
+ *  - domain:     the apex (and www, when the brand owns the apex) resolve.
+ *  - cloudflare: the response arrives THROUGH Cloudflare (cf-ray, or
+ *                server: cloudflare).
+ *
+ * Both transports are seams: `{ fetch, resolve }` default to the real
+ * globals and tests pass fakes, so no test ever touches the network.
+ *
+ * Gating mirrors the cloud service: a demo-* (emulator-only) brand has no
+ * live surface to check, so every leg records a gated skip with its reason
+ * and NO transport is called.
+ */
+const dns = require('node:dns').promises;
+
+const { isDemoProject } = require('../vendor/config/index.js');
+const { getApexDomain } = require('./domain-utils.js');
+
+// deploy target → the checks that prove THAT target's surface is live. Only
+// the web target has an outside-observable launch surface; backend/desktop/
+// extension prove themselves through their own deploy legs.
+const VERIFY_LEGS = { web: ['site', 'domain', 'cloudflare'] };
+
+// A live page is bigger than this; a 200 carrying less is an empty shell
+// (a hosting placeholder, a stub 404 page served with the wrong status).
+const MIN_BODY_BYTES = 500;
+
+// Live checks talk to the internet — never let one hang the pipeline.
+const REQUEST_TIMEOUT_MS = 15_000;
+
+/**
+ * Resolve what a brand's live surface IS, and whether it may be checked.
+ *
+ * @param {object} brandConfig - Merged brand config (omega.json5).
+ * @returns {{ url: string|null, hostnames: string[], gated: string|null }} - `gated` is the skip reason when live checks must not run.
+ */
+function resolveVerifySurface(brandConfig) {
+  const projectId = brandConfig?.cloud?.config?.projectId;
+  if (!projectId) {
+    return { url: null, hostnames: [], gated: 'no cloud project configured — no live surface to verify' };
+  }
+  if (isDemoProject(projectId)) {
+    return { url: null, hostnames: [], gated: `${projectId} is a demo-* (emulator-only) project — no live surface to verify` };
+  }
+
+  const url = (brandConfig?.brand?.url || '').replace(/\/$/, '');
+  if (!url) {
+    return { url: null, hostnames: [], gated: 'no brand.url configured' };
+  }
+
+  const hostname = new URL(url).hostname;
+  // www is a platform DNS record on the apex only — a subdomain brand's www
+  // belongs to the parent brand, so it is not this brand's to verify.
+  const hostnames = getApexDomain(hostname) === hostname ? [hostname, `www.${hostname}`] : [hostname];
+
+  return { url, hostnames, gated: null };
+}
+
+/** Real-fetch wrapper carrying the timeout; fakes ignore the options. */
+function request(surface, transports) {
+  const fetchImpl = transports.fetch || globalThis.fetch;
+  return fetchImpl(surface.url, { redirect: 'follow', signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+}
+
+/**
+ * The canonical URL serves a real page.
+ *
+ * @param {object} surface - From resolveVerifySurface().
+ * @param {object} transports - { fetch }.
+ * @returns {Promise<{ status: string, error: string|null }>}
+ */
+async function checkSite(surface, transports) {
+  let response;
+  try {
+    response = await request(surface, transports);
+  } catch (error) {
+    return { status: 'error', error: `${surface.url} unreachable — ${error.message}` };
+  }
+
+  if (response.status !== 200) {
+    return { status: 'error', error: `${surface.url} returned ${response.status} (expected 200)` };
+  }
+
+  const contentType = response.headers.get('content-type') || '(none)';
+  if (!contentType.includes('text/html')) {
+    return { status: 'error', error: `${surface.url} served content-type ${contentType} (expected text/html)` };
+  }
+
+  const body = await response.text();
+  if (body.length < MIN_BODY_BYTES) {
+    return { status: 'error', error: `${surface.url} served a ${body.length}-byte body (expected ≥ ${MIN_BODY_BYTES} — a 200 empty shell is not a live site)` };
+  }
+
+  return { status: 'success', error: null };
+}
+
+/**
+ * Every hostname the brand owns resolves in DNS.
+ *
+ * @param {object} surface - From resolveVerifySurface().
+ * @param {object} transports - { resolve }.
+ * @returns {Promise<{ status: string, error: string|null }>}
+ */
+async function checkDomain(surface, transports) {
+  const resolve = transports.resolve || dns.resolve4;
+
+  for (const hostname of surface.hostnames) {
+    try {
+      await resolve(hostname);
+    } catch (error) {
+      return { status: 'error', error: `${hostname} does not resolve — ${error.message}` };
+    }
+  }
+
+  return { status: 'success', error: null };
+}
+
+/**
+ * The response arrives through Cloudflare (proxied, not origin-direct).
+ *
+ * @param {object} surface - From resolveVerifySurface().
+ * @param {object} transports - { fetch }.
+ * @returns {Promise<{ status: string, error: string|null }>}
+ */
+async function checkCloudflare(surface, transports) {
+  let response;
+  try {
+    response = await request(surface, transports);
+  } catch (error) {
+    return { status: 'error', error: `${surface.url} unreachable — ${error.message}` };
+  }
+
+  const ray = response.headers.get('cf-ray');
+  const server = response.headers.get('server') || '(none)';
+  if (!ray && !/cloudflare/i.test(server)) {
+    return { status: 'error', error: `${surface.url} did not arrive through Cloudflare (no cf-ray, server: ${server})` };
+  }
+
+  return { status: 'success', error: null };
+}
+
+const CHECKS = { site: checkSite, domain: checkDomain, cloudflare: checkCloudflare };
+
+/**
+ * Run the verify sweep for a set of deploy targets.
+ *
+ * @param {string[]} targets - Deploy targets to verify (web, backend, …).
+ * @param {object} brandConfig - Merged brand config.
+ * @param {object} [transports] - { fetch, resolve } seams; real globals by default.
+ * @param {object} [options] - { dryRun }: a plan-only pass records the legs it WOULD run and touches nothing.
+ * @returns {Promise<Array<object>>} - Run-record rows (`verify:<name>`), judged exactly like deploy legs.
+ */
+async function runVerifyLegs(targets, brandConfig, transports = {}, options = {}) {
+  const names = [];
+  for (const target of targets) {
+    for (const name of VERIFY_LEGS[target] || []) {
+      if (!names.includes(name)) names.push(name);
+    }
+  }
+
+  if (names.length === 0) {
+    return [];
+  }
+
+  const surface = resolveVerifySurface(brandConfig);
+
+  // A dry run is plan-only everywhere else in the manager — the live sweep is
+  // no exception: it reports the legs it would run and sends no traffic.
+  const gated = options.dryRun ? 'dry-run — the live sweep is plan-only here' : surface.gated;
+  if (gated) {
+    return names.map((name) => ({ service: `verify:${name}`, status: 'skipped', output: null, error: null, reason: gated }));
+  }
+
+  const rows = [];
+  for (const name of names) {
+    const result = await CHECKS[name](surface, transports);
+    rows.push({ service: `verify:${name}`, status: result.status, output: null, error: result.error });
+  }
+
+  return rows;
+}
+
+module.exports = { VERIFY_LEGS, resolveVerifySurface, checkSite, checkDomain, checkCloudflare, runVerifyLegs };

package/dist/manage.js

@@ -0,0 +1,311 @@
+/**
+ * The manage orchestrator — omega-manager's src/manage/index.js reborn for
+ * brand monorepos. Resolves the brand root from the cwd, loads the brand
+ * (omega.json5 + enabled targets + target dirs), then walks SERVICE_ORDER running
+ * each service's operations idempotently. Every provisioned fact a service
+ * resolves lands in config/omega.json5 (secrets in .env) as it goes;
+ * transient output lands in .omega/runs/{timestamp}.json; the summary
+ * prints last.
+ *
+ * Company mode (many brands from one workspace — Ian's omega-manager case)
+ * layers on top of this later: runManage() is already per-brand, so the
+ * company runner is a loop + the parallel logger, both ported when that
+ * mode lands.
+ */
+
+const chalk = require('chalk').default;
+const { loadEnvRoots } = require('./vendor/config/index.js');
+
+const { SERVICE_ORDER, BOOT_SERVICES, OPERATIONS } = require('./config.js');
+const { resolveBrandRoot, loadBrand } = require('./lib/brand.js');
+const { readCompanyMarker, loadCompanyConfig } = require('./lib/company.js');
+const { writeRunOutput } = require('./lib/run-output.js');
+const { formatDuration } = require('./lib/duration.js');
+const { runPreflight, assertFamilyVersions } = require('./lib/preflight.js');
+const ensureTargetsRename = require('./services/migrations/ensure/targets-rename.js');
+const { CONSENT_REQUIRED } = require('./lib/google-auth.js');
+const { RunSummary } = require('./lib/run-summary.js');
+
+// Timestamp for this process run — used in .omega/runs/{RUN_TIMESTAMP}.json
+const RUN_TIMESTAMP = new Date().toISOString().replace(/[:.]/g, '-');
+
+/**
+ * Run a single service for the brand.
+ *
+ * @param {string} serviceName - Service to run
+ * @param {Object} brand - Loaded brand (from loadBrand)
+ * @param {Object} options - Run options
+ * @returns {Object} - { status, error?, state?, output? }
+ */
+async function runService(serviceName, brand, options = {}) {
+  const operations = OPERATIONS[serviceName] || [];
+
+  if (operations.length === 0) {
+    return { status: 'skipped', reason: 'no operations' };
+  }
+
+  try {
+    const serviceModule = require(`./services/${serviceName}/index.js`);
+
+    if (!serviceModule.run) {
+      console.log(`  Service ${serviceName} has no run() export`);
+      return { status: 'skipped', reason: 'no run export' };
+    }
+
+    // No cross-run seed: a service reads what it needs from brandConfig (the
+    // one home for provisioned facts) or re-derives it from the platform, and
+    // a setup() may still seed serviceData for its own operations (#434)
+    return await serviceModule.run({
+      brandId: brand.id,
+      brandRoot: brand.root,
+      // Company workspace root when the brand carries a valid company marker
+      // — company-shared resources (Apple signing material) live there
+      companyRoot: brand.companyRoot || null,
+      // The company config layer (already merged into brandConfig) for
+      // provenance checks — null for standalone brands
+      companyConfig: brand.companyConfig || null,
+      brandConfig: brand.config,
+      brand,
+      targets: brand.targets,
+      operations,
+      options,
+    });
+  } catch (error) {
+    // A consent gate thrown at setup time is a pending HUMAN step, not a
+    // failure (#228) — warned keeps the walk going and lands the item in the
+    // summary's ⚑ list instead of stopping the cycle (and any dev boot on it)
+    if (error?.code === CONSENT_REQUIRED) {
+      console.log(`  ${chalk.yellow('⚑')} ${serviceName}: ${error.message}`);
+      return {
+        status: 'warned',
+        warned: [{ operation: 'auth', reason: 'needs an interactive run' }],
+        output: { auth: { needsInteractive: error.message } },
+      };
+    }
+
+    console.error(`  Error in ${serviceName}: ${error.message}`);
+    return { status: 'error', error: error.message };
+  }
+}
+
+/**
+ * Run all services (in order) against the brand monorepo containing startDir.
+ *
+ * @param {string} startDir - Any directory inside the brand monorepo
+ * @param {Object} options - { service?, lane? ('boot' = the local slice a dev
+ *   boot needs; omitted = every service), continueOnError?, dryRun?, verbose?,
+ *   strict? (preflight failures fail hard instead of skipping),
+ *   migration? (true = all, string = one), execute? (the migrations write
+ *   gate — without it the run only audits), limit?, ids? (migrations service),
+ *   resetAssets? (true = both kinds, string = 'logos'/'templates'; assets
+ *   service), force? (ignore the update service's incremental cache and
+ *   rebuild every target) }
+ * @returns {{ hasErrors: boolean, results: Object, brand: Object }}
+ */
+async function runManage(startDir, options = {}) {
+  const brandRoot = resolveBrandRoot(startDir);
+
+  if (!brandRoot) {
+    throw new Error(
+      `No brand monorepo found at or above ${startDir} — `
+      + `expected a config/omega.json5 at the brand root (see docs/shared/config.md).`,
+    );
+  }
+
+  // One vocabulary (#443): the apps/ → targets/ rename is a ONE-TIME
+  // migration, never healing inside a run. The brand it fixes cannot be
+  // walked — discovery fails loud on the old shape and every service below
+  // reads targets/ — so this ONE migration runs ALONE, ahead of the load that
+  // would throw on it, and stops there. It is registered like every other
+  // migration too (config.js OPERATIONS.migrations), so a bare `--migration`
+  // walk re-checks it on a converged brand.
+  if (options.migration === ensureTargetsRename.MIGRATION_NAME) {
+    console.log('');
+    console.log(chalk.bold.cyan(`🚀 Omega Manager ${chalk.dim(`— migration: ${ensureTargetsRename.MIGRATION_NAME}`)}`));
+    console.log(`  ${chalk.dim('Root:')}     ${brandRoot}`);
+
+    const result = await ensureTargetsRename({ brandRoot, options });
+
+    return { hasErrors: false, results: { migrations: result }, brand: null };
+  }
+
+  // Company layer: a company-managed brand carries a .omega/company.json
+  // stamp (written idempotently by company runs) pointing at its company
+  // root — its config becomes the layer between manager DEFAULTS and the
+  // brand file, and its .env fills the gaps under the brand .env.
+  const marker = readCompanyMarker(brandRoot);
+  let companyConfig = null;
+
+  if (marker?.stale) {
+    console.log(chalk.yellow(`⚠ .omega/company.json points at ${marker.companyRoot}, which is no longer a company workspace — running standalone (delete the file to silence this)`));
+  } else if (marker) {
+    companyConfig = loadCompanyConfig(marker.companyRoot);
+  }
+
+  // Secrets chain: shell env > brand .env > company .env — the shared
+  // cascade (files load strongest-first, never overriding what's set), each
+  // layer overlaid by its own `.env.<environment>` file
+  // ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)). The manage
+  // walk judges every key on the RESOLVED cascade, so a value that lives only
+  // in an overlay must be visible here or the mint lane would re-mint it.
+  //
+  // `production` is PINNED, never the shell's answer: manage reconciles REAL
+  // infrastructure with production credentials, and the mint lane has to see
+  // the key it would otherwise re-mint.
+  loadEnvRoots([
+    brandRoot,
+    companyConfig ? marker.companyRoot : null,
+  ], { environment: 'production' });
+
+  // The company layer itself is folded by @omega.js/config off the same stamp
+  // (#83) — loadBrand takes no company argument; what we resolved here is
+  // provenance and the .env chain.
+  const brand = loadBrand(brandRoot);
+
+  // Company-shared resources (Apple signing material) live at the company
+  // workspace root — services resolve it via context.companyRoot
+  brand.companyRoot = companyConfig ? marker.companyRoot : null;
+
+  // The inheritable company layer itself rides along for provenance: its
+  // values are already merged into brand.config, but flows that want to say
+  // "this came from the company" (e.g. the GA account default) compare
+  // against it via context.companyConfig
+  brand.companyConfig = companyConfig;
+
+  console.log('');
+  console.log(chalk.bold.cyan('🚀 Omega Manager'));
+  console.log('');
+
+  // Skip disabled brands
+  if (brand.config.enabled === false) {
+    console.log(chalk.dim('━'.repeat(70)));
+    console.log(`  ${chalk.bold(brand.config.brand?.name || brand.id)} ${chalk.yellow('DISABLED')}`);
+    console.log(chalk.dim('━'.repeat(70)));
+    return { hasErrors: false, results: {}, brand, skipped: true };
+  }
+
+  // Determine which services to run. --service is the most specific ask and
+  // wins outright; a lane narrows the walk to its slice (#228) — 'boot' is the
+  // local one `omega dev` runs before its legs, in SERVICE_ORDER order.
+  if (options.lane && options.lane !== 'boot') {
+    throw new Error(`Unknown lane: ${options.lane}. Available: boot`);
+  }
+
+  const servicesToRun = options.service
+    ? [options.service]
+    : (options.lane === 'boot'
+      ? SERVICE_ORDER.filter((serviceName) => BOOT_SERVICES.includes(serviceName))
+      : SERVICE_ORDER);
+
+  if (options.service && !SERVICE_ORDER.includes(options.service)) {
+    throw new Error(`Unknown service: ${options.service}. Available: ${SERVICE_ORDER.join(', ')}`);
+  }
+
+  console.log(chalk.cyan('━'.repeat(70)));
+  console.log(`  ${chalk.bold.white(brand.config.brand?.name || brand.id)} ${chalk.cyan(brand.config.brand?.url || '')} ${chalk.dim(`@ ${new Date().toLocaleTimeString()}`)}`);
+  console.log(chalk.cyan('━'.repeat(70)));
+  console.log(`  ${chalk.dim('Root:')}     ${brand.root}`);
+  if (companyConfig) {
+    console.log(`  ${chalk.dim('Company:')}  ${marker.companyRoot}`);
+  }
+  console.log(`  ${chalk.dim('Enabled:')}  ${brand.enabledTargets.join(', ') || chalk.yellow('none enabled')}`);
+  console.log(`  ${chalk.dim('Targets:')}  ${brand.targets.map((entry) => `${entry.name}${entry.target ? chalk.dim(`→${entry.target}`) : chalk.yellow('→?')}`).join(', ') || chalk.yellow('none')}`);
+  console.log(`  ${chalk.dim('Services:')} ${options.service || servicesToRun.join(chalk.dim(' → '))}`);
+
+  // Lockstep (#794): the @omega.js family ships ONE version, so a brand
+  // running a framework from one release beside a client from another is
+  // refused HERE — before any service reconciles anything on top of two
+  // copies of the runtime and two copies of the config validator. `file:`
+  // links (the local era) and targets with nothing installed are exempt.
+  assertFamilyVersions({ brandRoot, targets: brand.targets });
+
+  // Preflight (the REQUIRES registry): check the enabled services' declared
+  // env vars + Google scopes up front — ONE consolidated fix walkthrough
+  // instead of N mid-run skips. Failing services skip (the cycle continues —
+  // absorb, never crash) unless the run can collect the fix itself
+  // (interactive paste/consent flows) or --strict makes them fail hard.
+  // A lane narrows the WALK, never the preflight (#228): preflight is local
+  // (env presence + token-store read, zero network), and its walkthrough is
+  // how a boot names what the full setup still owes. Gates are only consulted
+  // for the services this run actually walks, so an unwalked finding records
+  // nothing and fails nothing.
+  const preflight = runPreflight({
+    services: options.service ? [options.service] : SERVICE_ORDER,
+    brandConfig: brand.config,
+    brandRoot,
+    options,
+  });
+
+  const summary = new RunSummary();
+  const results = {};
+
+  // Run each service in order
+  for (const serviceName of servicesToRun) {
+    console.log('');
+    console.log(`  ${chalk.bold.magenta(`[${serviceName.toUpperCase()}]`)}`);
+
+    // Preflight verdicts: 'skip' steps the service aside with the printed
+    // walkthrough (missingEnv rides along for the 🔑 aggregate); 'error' is
+    // the --strict hard failure; 'run' (or no gate) proceeds normally
+    const gate = preflight.gates[serviceName];
+    let result;
+    if (gate?.action === 'error') {
+      console.log(`  ${chalk.red(`✗ Preflight failed (${gate.reason})`)}`);
+      result = {
+        status: 'error',
+        error: gate.reason,
+        ...(gate.missingEnv.length > 0 ? { missingEnv: gate.missingEnv } : {}),
+      };
+    } else if (gate?.action === 'skip') {
+      console.log(`    ${chalk.dim(`⊘ Skipped (${gate.reason})`)}`);
+      result = {
+        status: 'skipped',
+        reason: gate.reason,
+        ...(gate.missingEnv.length > 0 ? { missingEnv: gate.missingEnv } : {}),
+        // A consent/scope gap is a pending HUMAN step: it rides the ⚑
+        // aggregate with its rerun hint (#228), not just the walkthrough
+        // scroll-back a dev boot's leg output buries
+        ...(gate.needsInteractive ? { output: { preflight: { needsInteractive: gate.needsInteractive } } } : {}),
+      };
+    } else {
+      const startedAt = Date.now();
+      result = await runService(serviceName, brand, options);
+      // Wall time for the services that actually ran — the gated branches
+      // above step aside instantly, so timing them is noise
+      result.durationMs = Date.now() - startedAt;
+      // Printed only for the services that did work — a service that stepped
+      // aside already said so on its own line, and 20 `⏱ 0ms` lines under a
+      // mostly-skipping walk is noise (the run record keeps every number)
+      if (result.status !== 'skipped') {
+        console.log(`    ${chalk.dim(`⏱ ${formatDuration(result.durationMs)}`)}`);
+      }
+    }
+    results[serviceName] = result;
+
+    summary.add(brand.id, brand.config.brand?.name || brand.id, serviceName, result);
+
+    if (result.status === 'error' && !options.continueOnError) {
+      console.log(`  ${chalk.red(`Stopping due to error in ${serviceName}`)} ${chalk.dim('(--continue-on-error to keep going)')}`);
+      break;
+    }
+  }
+
+  // Persist run output — this run's transients, for post-mortem debugging
+  writeRunOutput(brandRoot, RUN_TIMESTAMP, brand.id, Object.entries(results).map(([service, result]) => ({
+    service,
+    status: result.status,
+    // Absent for services the preflight gated aside — they never ran
+    ...(result.durationMs !== undefined ? { durationMs: result.durationMs } : {}),
+    output: result.output ?? null,
+    error: result.error ?? null,
+    // Machine-readable WHY for skips — the pipeline command asserts on it
+    ...(result.reason ? { reason: result.reason } : {}),
+    ...(result.missingEnv ? { missingEnv: result.missingEnv } : {}),
+  })));
+
+  summary.printSummary();
+
+  return { hasErrors: summary.hasErrors(), results, brand };
+}
+
+module.exports = { runManage, runService, RUN_TIMESTAMP };

package/dist/omega-bin.js

@@ -0,0 +1,7 @@
+// Entry for the `omega`/`omg`/`mgr` bins — dispatches to the framework that owns
+// the cwd's target; a brand root runs the manager's CLI, and so does a fresh clone
+// with nothing installed yet (`npx omega onboard`, the bootstrap case).
+require('./vendor/devkit/omega-bin.js').run({
+  hostName: '@omega.js/manager',
+  hostRun: () => require('./cli-run.js').run(),
+});