@starci/hfs 4.11.21 → 4.12.0

package/release/gate.mjs

@@ -14,10 +14,8 @@ import { failure, refusal } from '../stack/errors.mjs';
 import { produceLintReports } from './lint-report.mjs';
 import { URGENT_RULING, l4Path, readUrgent, recordRow, writeUrgent } from './records.mjs';
 import { sonarQualityGate } from './sonar-quality-gate.mjs';
-
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
 const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
-
 const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'requireCi']);
 /** Release-block keys that no longer exist, each with what replaced it. */
 const REMOVED_FIELDS = new Map([['tagMatchesVersion', 'the release tag is always <tagPrefix><package.json version>; delete the key']]);
@@ -40,433 +38,463 @@ const SCRIPT_GATES = ['format:check', 'typecheck', 'build:be', 'lint', 'db:lint'
 const WORLD_SCRIPTS = ['test:integration', 'test:e2e', 'test:contract'];
 // An app with an entity list (db/entity-list.mjs) checks its entities against the migrated schema: a row of every gate, declared or default.
 const DB_DRIFT = { name: 'db-drift', command: ['npx', 'starci', 'app', 'db', 'drift'], summary: null, env: {} };
-
 /** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
 export const refName = (value) => typeof value === 'string' && REF_NAME.test(value);
-
 const scriptGate = (script) => ({
-  name: script.replaceAll(':', '-'),
-  command: ['npm', 'run', script],
-  summary: script === 'test' ? 'jest' : null,
-  env: {},
+    name: script.replaceAll(':', '-'),
+    command: ['npm', 'run', script],
+    summary: script === 'test' ? 'jest' : null,
+    env: {},
 });
-
 /** Default gates run app-check, the enabled audit, then every managed script present in the app and the entity drift row, Sonar following when it is declared. */
 function defaultGates(scripts, audit, entities) {
-  const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
-  const world = typeof scripts?.['test:e2e'] === 'string' ? WORLD_SCRIPTS.filter((script) => typeof scripts?.[script] === 'string') : [];
-  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate), ...world.map(scriptGate), ...(entities ? [DB_DRIFT] : [])];
+    const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
+    const world = typeof scripts?.['test:e2e'] === 'string' ? WORLD_SCRIPTS.filter((script) => typeof scripts?.[script] === 'string') : [];
+    return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate), ...world.map(scriptGate), ...(entities ? [DB_DRIFT] : [])];
 }
-
 /** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
 function releaseServices(services, options) {
-  const audit = services?.audit ?? {};
-  if (!plain(audit) || (audit.in !== undefined && (!Array.isArray(audit.in) || !audit.in.every((scope) => typeof scope === 'string'))) || (audit.omitDev !== undefined && typeof audit.omitDev !== 'boolean')) throw refusal(RELEASE_CODE, 'services.audit must be a mapping with a string-list in and boolean omitDev');
-  const sonar = services?.sonar;
-  const compatible = typeof sonar?.host === 'string' ? { ...sonar, host: { public: sonar.host } } : sonar;
-  const quality = qualityServices({ services: { ...services, sonar: compatible } }, options);
-  if (audit.mode === 'disabled') quality.audit = null;
-  return quality;
-}
-
+    const audit = services?.audit ?? {};
+    if (!plain(audit) || (audit.in !== undefined && (!Array.isArray(audit.in) || !audit.in.every((scope) => typeof scope === 'string'))) || (audit.omitDev !== undefined && typeof audit.omitDev !== 'boolean'))
+        throw refusal(RELEASE_CODE, 'services.audit must be a mapping with a string-list in and boolean omitDev');
+    const sonar = services?.sonar;
+    const compatible = typeof sonar?.host === 'string' ? { ...sonar, host: { public: sonar.host } } : sonar;
+    const quality = qualityServices({ services: { ...services, sonar: compatible } }, options);
+    if (audit.mode === 'disabled')
+        quality.audit = null;
+    return quality;
+}
 /** The shared audit settings preserve release scope, level and development-dependency selection. */
 function auditGate(audit) {
-  if (!audit || !audit.in.includes('release-gate')) return null;
-  if (!['info', 'low', 'moderate', 'high', 'critical'].includes(audit.level)) throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
-  return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
+    if (!audit || !audit.in.includes('release-gate'))
+        return null;
+    if (!['info', 'low', 'moderate', 'high', 'critical'].includes(audit.level))
+        throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
+    return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
 }
-
 /** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
 function sonarGate(services, env) {
-  const configured = services?.sonar;
-  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
-  const tokenName = sonar?.token;
-  if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
-  const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
-  const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
-  if (organization) command.push(`-Dsonar.organization=${organization}`);
-  if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
-  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar,
-    credentialNames: [...new Set(['SONAR_TOKEN', tokenName])] };
-}
-
+    const configured = services?.sonar;
+    const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
+    const tokenName = sonar?.token;
+    if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName])
+        throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
+    const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
+    const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
+    if (organization)
+        command.push(`-Dsonar.organization=${organization}`);
+    if (!command.every((word) => TOKEN.test(word)))
+        throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
+    return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar,
+        credentialNames: [...new Set(['SONAR_TOKEN', tokenName])] };
+}
 function gateProblems(entry, at, seen) {
-  const found = [];
-  for (const key of Object.keys(entry)) if (!GATE_FIELDS.has(key)) found.push(`${at}.${key}: is not a field of a gate`);
-  if (typeof entry.name !== 'string' || !GATE_NAME.test(entry.name)) found.push(`${at}.name: must match ${GATE_NAME}`);
-  else if (seen.has(entry.name)) found.push(`${at}.name: ${entry.name} is declared twice`);
-  const command = entry.command;
-  if (!Array.isArray(command) || command.length === 0 || !command.every((word) => typeof word === 'string' && TOKEN.test(word))) found.push(`${at}.command: must be a non-empty list of plain words (no shell strings)`);
-  if (entry.summary !== undefined && entry.summary !== 'jest') found.push(`${at}.summary: must be jest`);
-  const env = entry.env ?? {};
-  if (!plain(env) || !Object.entries(env).every(([key, value]) => ENV_KEY.test(key) && typeof value === 'string')) found.push(`${at}.env: must map UPPER_CASE names to string values`);
-  return found;
-}
-
+    const found = [];
+    for (const key of Object.keys(entry))
+        if (!GATE_FIELDS.has(key))
+            found.push(`${at}.${key}: is not a field of a gate`);
+    if (typeof entry.name !== 'string' || !GATE_NAME.test(entry.name))
+        found.push(`${at}.name: must match ${GATE_NAME}`);
+    else if (seen.has(entry.name))
+        found.push(`${at}.name: ${entry.name} is declared twice`);
+    const command = entry.command;
+    if (!Array.isArray(command) || command.length === 0 || !command.every((word) => typeof word === 'string' && TOKEN.test(word)))
+        found.push(`${at}.command: must be a non-empty list of plain words (no shell strings)`);
+    if (entry.summary !== undefined && entry.summary !== 'jest')
+        found.push(`${at}.summary: must be jest`);
+    const env = entry.env ?? {};
+    if (!plain(env) || !Object.entries(env).every(([key, value]) => ENV_KEY.test(key) && typeof value === 'string'))
+        found.push(`${at}.env: must map UPPER_CASE names to string values`);
+    return found;
+}
 function gatesOf(list, problems) {
-  if (!Array.isArray(list) || list.length === 0) {
-    problems.push('release.gates: must be a non-empty list');
-    return [];
-  }
-  const seen = new Set();
-  const gates = [];
-  list.forEach((entry, index) => {
-    const at = `release.gates[${index}]`;
-    const found = plain(entry) ? gateProblems(entry, at, seen) : [`${at}: must be a mapping`];
-    problems.push(...found);
-    if (found.length === 0) {
-      seen.add(entry.name);
-      gates.push({ name: entry.name, command: entry.command, summary: entry.summary ?? null, env: entry.env ?? {} });
+    if (!Array.isArray(list) || list.length === 0) {
+        problems.push('release.gates: must be a non-empty list');
+        return [];
     }
-  });
-  return gates;
+    const seen = new Set();
+    const gates = [];
+    list.forEach((entry, index) => {
+        const at = `release.gates[${index}]`;
+        const found = plain(entry) ? gateProblems(entry, at, seen) : [`${at}: must be a mapping`];
+        problems.push(...found);
+        if (found.length === 0) {
+            seen.add(entry.name);
+            gates.push({ name: entry.name, command: entry.command, summary: entry.summary ?? null, env: entry.env ?? {} });
+        }
+    });
+    return gates;
 }
-
 /** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
 export function normalizeRelease(block, scripts = {}, services = {}, options = {}) {
-  const raw = block ?? {};
-  if (!plain(raw)) return { problems: ['release: must be a mapping'] };
-  const problems = [];
-  for (const key of Object.keys(raw)) {
-    if (REMOVED_FIELDS.has(key)) problems.push(`release.${key}: is removed (${REMOVED_FIELDS.get(key)})`);
-    else if (!FIELDS.has(key)) problems.push(`release.${key}: is not a field of the release block`);
-  }
-  const tagPrefix = raw.tagPrefix ?? 'v';
-  const defaultBranch = raw.defaultBranch ?? 'main';
-  // The candidate CI of `release push` is an app's choice and off by default (owner ruling release-require-ci-per-project); the local gate never is.
-  const requireCi = raw.requireCi ?? false;
-  if (typeof tagPrefix !== 'string' || !PREFIX.test(tagPrefix)) problems.push(`release.tagPrefix: must match ${PREFIX}`);
-  if (!refName(defaultBranch)) problems.push(`release.defaultBranch: must match ${REF_NAME}`);
-  if (typeof requireCi !== 'boolean') problems.push('release.requireCi: must be true or false');
-  const quality = releaseServices(services, options);
-  const audit = auditGate(quality.audit);
-  const gates = raw.gates === undefined ? defaultGates(scripts, audit, options.entities === true) : gatesOf(raw.gates, problems);
-  if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit')) gates.push(audit);
-  if (raw.gates !== undefined && options.entities === true && !gates.some((gate) => gate.name === DB_DRIFT.name)) gates.push(DB_DRIFT);
-  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, requireCi, services: quality } } : { problems };
-}
-
+    const given = block ?? {};
+    if (!plain(given))
+        return { problems: ['release: must be a mapping'] };
+    const raw = given; // reason: the release block is YAML parsed from disk; every field is judged below
+    const problems = [];
+    for (const key of Object.keys(raw)) {
+        if (REMOVED_FIELDS.has(key))
+            problems.push(`release.${key}: is removed (${REMOVED_FIELDS.get(key)})`);
+        else if (!FIELDS.has(key))
+            problems.push(`release.${key}: is not a field of the release block`);
+    }
+    const tagPrefix = raw.tagPrefix ?? 'v';
+    const defaultBranch = raw.defaultBranch ?? 'main';
+    // The candidate CI of `release push` is an app's choice and off by default (owner ruling release-require-ci-per-project); the local gate never is.
+    const requireCi = raw.requireCi ?? false;
+    if (typeof tagPrefix !== 'string' || !PREFIX.test(tagPrefix))
+        problems.push(`release.tagPrefix: must match ${PREFIX}`);
+    if (!refName(defaultBranch))
+        problems.push(`release.defaultBranch: must match ${REF_NAME}`);
+    if (typeof requireCi !== 'boolean')
+        problems.push('release.requireCi: must be true or false');
+    const quality = releaseServices(services, options);
+    const audit = auditGate(quality.audit);
+    const gates = raw.gates === undefined ? defaultGates(scripts, audit, options.entities === true) : gatesOf(raw.gates, problems);
+    if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit'))
+        gates.push(audit);
+    if (raw.gates !== undefined && options.entities === true && !gates.some((gate) => gate.name === DB_DRIFT.name))
+        gates.push(DB_DRIFT);
+    return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, requireCi, services: quality } } : { problems };
+}
 /* ---- git through the seam */
-
 /** Runs git in the app root; a missing git or (unless allowFail) a non-zero exit is a failure whose message names the first stderr line. */
 export function git(ctx, args, { allowFail = false } = {}) {
-  const run = tool(ctx, 'git', args, { cwd: ctx.cwd, env: ctx.env });
-  if (run.error) throw failure('RELEASE_GIT_MISSING', `cannot run git (${run.error.message})`);
-  if (run.status !== 0 && !allowFail) throw failure('RELEASE_GIT_FAILED', `git ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
-  return { code: run.status, stdout: String(run.stdout ?? '').trim(), stderr: String(run.stderr ?? '') };
+    const run = tool(ctx, 'git', args, { cwd: ctx.cwd, env: ctx.env });
+    if (run.error)
+        throw failure('RELEASE_GIT_MISSING', `cannot run git (${run.error.message})`);
+    if (run.status !== 0 && !allowFail)
+        throw failure('RELEASE_GIT_FAILED', `git ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
+    return { code: run.status, stdout: String(run.stdout ?? '').trim(), stderr: String(run.stderr ?? '') };
 }
-
 /** The directory that holds the L4 records: <git common dir>/starci-release. */
 export const releaseDir = (ctx) => path.join(path.resolve(ctx.cwd, git(ctx, ['rev-parse', '--git-common-dir']).stdout), 'starci-release');
-
 /** Annotated tags `<prefix><digit>*` that point at HEAD (lightweight tags do not count: the hook ignores them). */
 export function annotatedOnHead(ctx, prefix) {
-  const names = lines(git(ctx, ['tag', '--points-at', 'HEAD', '--list', `${prefix}[0-9]*`]).stdout);
-  return names.filter((name) => git(ctx, ['cat-file', '-t', `refs/tags/${name}`], { allowFail: true }).stdout === 'tag');
+    const names = lines(git(ctx, ['tag', '--points-at', 'HEAD', '--list', `${prefix}[0-9]*`]).stdout);
+    return names.filter((name) => git(ctx, ['cat-file', '-t', `refs/tags/${name}`], { allowFail: true }).stdout === 'tag');
 }
-
 /** Every tag on HEAD whose name ends in a version, annotated or not, under any prefix: a release commit carries exactly one. */
 const versionTagsOnHead = (ctx) => lines(git(ctx, ['tag', '--points-at', 'HEAD']).stdout).filter((name) => /[0-9]+[.][0-9]+[.][0-9]+$/u.test(name));
-
 /** The rewrittenBy predicate of the app's slots: true for a path a dev server writes (hfs slots `rewrittenBy`); without a readable hfs.json, for none. */
 function rewrittenByDevServer(root) {
-  let hfs;
-  try { hfs = openHfs({ repoRoot: root }); } catch { return () => false; }
-  return (file) => typeof hfs.slotOf(file)?.rewrittenBy === 'string';
+    let hfs; // reason: openHfs is the slot machine of the app's hfs.json (runtime/scripts/hfs/slots.mjs)
+    try {
+        hfs = openHfs({ repoRoot: root });
+    }
+    catch {
+        return () => false;
+    }
+    return (file) => typeof hfs.slotOf(file)?.rewrittenBy === 'string';
 }
-
 /**
  * The paths that make the tree dirty: every changed tracked path and every untracked one, except an untracked file the app's slots declare a dev
  * server rewrites (`rewrittenBy`, e.g. the AGENTS.md `next dev` writes): that one is known generated output, never a change of the release.
  */
 export function dirtyPaths(ctx) {
-  const rewritten = rewrittenByDevServer(ctx.cwd);
-  return lines(git(ctx, ['status', '--porcelain', '--untracked-files=all']).stdout)
-    .filter((line) => !(line.startsWith('?? ') && rewritten(line.slice(3).replace(/^"|"$/gu, ''))));
+    const rewritten = rewrittenByDevServer(ctx.cwd);
+    return lines(git(ctx, ['status', '--porcelain', '--untracked-files=all']).stdout)
+        .filter((line) => !(line.startsWith('?? ') && rewritten(line.slice(3).replace(/^"|"$/gu, ''))));
 }
-
 /** Tag names that exist locally or on the remote. */
 function takenTags(ctx, prefix, remote) {
-  const local = lines(git(ctx, ['tag', '--list', `${prefix}*`]).stdout);
-  const listed = lines(git(ctx, ['ls-remote', '--tags', remote], { allowFail: true }).stdout);
-  const remoteNames = listed.map((line) => line.split('refs/tags/')[1]?.replace(/\^\{\}$/u, '')).filter(Boolean);
-  return new Set([...local, ...remoteNames]);
+    const local = lines(git(ctx, ['tag', '--list', `${prefix}*`]).stdout);
+    const listed = lines(git(ctx, ['ls-remote', '--tags', remote], { allowFail: true }).stdout);
+    const remoteNames = listed.map((line) => line.split('refs/tags/')[1]?.replace(/\^\{\}$/u, '')).filter((name) => Boolean(name));
+    return new Set([...local, ...remoteNames]);
 }
-
 /** The tag this release uses is `<prefix><package version>`; its state is on-head (reused), free (will be created) or taken (exists on another commit). */
 function chooseTag(ctx, config, { prefix, remote }) {
-  const tag = `${prefix}${config.version}`;
-  if (annotatedOnHead(ctx, prefix).includes(tag)) return { tag, state: 'on-head' };
-  return { tag, state: takenTags(ctx, prefix, remote).has(tag) ? 'taken' : 'free' };
+    const tag = `${prefix}${config.version}`;
+    if (annotatedOnHead(ctx, prefix).includes(tag))
+        return { tag, state: 'on-head' };
+    return { tag, state: takenTags(ctx, prefix, remote).has(tag) ? 'taken' : 'free' };
 }
-
 /* ---- gate results */
-
 const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-
 const lineAfter = (text, label) => {
-  const found = text.split('\n').find((line) => line.startsWith(label));
-  return found === undefined ? null : found.slice(label.length).trim();
+    const found = text.split('\n').find((line) => line.startsWith(label));
+    return found === undefined ? null : found.slice(label.length).trim();
 };
-
 /** The jest summary lines of a log: { suites, failedSuites, tests, failed, passed } or null when jest printed none. */
 function jestSummary(text) {
-  const suites = lineAfter(text, 'Test Suites:');
-  const tests = lineAfter(text, 'Tests:');
-  if (suites === null || tests === null) return null;
-  const count = (line, word) => Number(new RegExp(String.raw`(\d+) ${word}`, 'u').exec(line)?.[1] ?? 0);
-  return {
-    suites: count(suites, 'total'), failedSuites: count(suites, 'failed'),
-    tests: count(tests, 'total'), failed: count(tests, 'failed'), passed: count(tests, 'passed'),
-  };
-}
-
+    const suites = lineAfter(text, 'Test Suites:');
+    const tests = lineAfter(text, 'Tests:');
+    if (suites === null || tests === null)
+        return null;
+    const count = (line, word) => Number(new RegExp(String.raw `(\d+) ${word}`, 'u').exec(line)?.[1] ?? 0);
+    return {
+        suites: count(suites, 'total'), failedSuites: count(suites, 'failed'),
+        tests: count(tests, 'total'), failed: count(tests, 'failed'), passed: count(tests, 'passed'),
+    };
+}
 /** Judges a jest-style gate from its log: green needs suites that all passed, every test passed and no coverage threshold miss. */
 function judgeJest(text) {
-  const summary = jestSummary(text);
-  const misses = (text.match(THRESHOLD_MISS) ?? []).length;
-  if (!summary) return { pass: false, detail: 'no jest summary in the log', summary: null, misses };
-  const pass = summary.suites > 0 && summary.failedSuites === 0 && summary.failed === 0 && summary.passed === summary.tests && misses === 0;
-  const detail = `suites ${summary.suites - summary.failedSuites}/${summary.suites}, tests ${summary.passed}/${summary.tests}, coverage-threshold misses ${misses}`;
-  return { pass, detail, summary, misses };
-}
-
+    const summary = jestSummary(text);
+    const misses = (text.match(THRESHOLD_MISS) ?? []).length;
+    if (!summary)
+        return { pass: false, detail: 'no jest summary in the log', summary: null, misses };
+    const pass = summary.suites > 0 && summary.failedSuites === 0 && summary.failed === 0 && summary.passed === summary.tests && misses === 0;
+    const detail = `suites ${summary.suites - summary.failedSuites}/${summary.suites}, tests ${summary.passed}/${summary.tests}, coverage-threshold misses ${misses}`;
+    return { pass, detail, summary, misses };
+}
 /** [command, args] to start an argv; on Windows npm and npx are .cmd files, so they start through cmd.exe (words are validated, never a shell string). */
 export function launch(argv, platform) {
-  if (platform === 'win32' && WRAPPED.has(argv[0])) return ['cmd.exe', ['/d', '/s', '/c', ...argv]];
-  return [argv[0], argv.slice(1)];
+    if (platform === 'win32' && WRAPPED.has(argv[0]))
+        return ['cmd.exe', ['/d', '/s', '/c', ...argv]];
+    return [argv[0], argv.slice(1)];
 }
-
 /** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. An unreachable host is a red row: Sonar is required. */
 async function sonarAvailability(ctx, gate) {
-  const sonar = gate.provider;
-  if (!sonar) return null;
-  let up = false;
-  try {
-    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
-    up = response.ok && (await response.json()).status === 'UP';
-  } catch { up = false; }
-  if (up) return null;
-  return { pass: false, detail: `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds` };
-}
-
+    const sonar = gate.provider;
+    if (!sonar)
+        return null;
+    let up = false;
+    try {
+        const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
+        up = response.ok && (await response.json()).status === 'UP';
+    }
+    catch {
+        up = false;
+    }
+    if (up)
+        return null;
+    return { pass: false, detail: `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds` };
+}
 /** An unreachable Sonar host stays a red row with a real log and no scan invocation. */
 export async function runAvailableGate(ctx, gate, options) {
-  const availability = await sonarAvailability(ctx, gate);
-  const log = path.join(options.dir, `${gate.name}.log`);
-  if (!availability) {
-    if (!gate.provider) return runGate(ctx, gate, options);
-    // The scanner imports the app's declared external issues report: produce it first with the app's own lint, as the managed CI does.
-    const started = ctx.now();
-    const lint = produceLintReports(ctx, { launch, platform: options.platform, env: withoutCredentials(ctx.env, options.credentialNames) });
-    if (lint.pass) return judgeQualityGate(ctx, gate, runGate(ctx, gate, { ...options, preface: lint.text }));
-    fs.writeFileSync(log, lint.text);
-    return { name: gate.name, command: gate.command.join(' '), pass: false, detail: 'lint report failed (see log)', seconds: Math.round((ctx.now() - started) / 1000),
-      summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
-  }
-  fs.writeFileSync(log, availability.detail + '\n');
-  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
-    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
-}
-
+    const availability = await sonarAvailability(ctx, gate);
+    const log = path.join(options.dir, `${gate.name}.log`);
+    if (!availability) {
+        if (!gate.provider)
+            return runGate(ctx, gate, options);
+        // The scanner imports the app's declared external issues report: produce it first with the app's own lint, as the managed CI does.
+        const started = ctx.now();
+        const lint = produceLintReports(ctx, { launch, platform: options.platform, env: withoutCredentials(ctx.env, options.credentialNames) });
+        if (lint.pass)
+            return judgeQualityGate(ctx, gate, runGate(ctx, gate, { ...options, preface: lint.text }));
+        fs.writeFileSync(log, lint.text);
+        return { name: gate.name, command: gate.command.join(' '), pass: false, detail: 'lint report failed (see log)', seconds: Math.round((ctx.now() - started) / 1000),
+            summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+    }
+    fs.writeFileSync(log, availability.detail + '\n');
+    return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
+        summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+}
 /**
  * A scanner that exited 0 only uploaded its report: the row passes when the server's quality gate of that analysis is OK
  * (sonar-quality-gate.mjs). The verdict replaces the row's detail and is appended to its log; the row's time includes the wait.
  */
 async function judgeQualityGate(ctx, gate, row) {
-  if (!row.pass) return row;
-  const started = ctx.now();
-  const verdict = await sonarQualityGate(ctx, { cwd: ctx.cwd, host: gate.provider.host, token: gate.env.SONAR_TOKEN });
-  const failed = (verdict.conditions ?? []).map((line) => `  failed: ${line}\n`).join('');
-  fs.appendFileSync(row.log, `\nquality gate: ${verdict.detail}\n${failed}`);
-  return { ...row, pass: verdict.pass, detail: verdict.detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
-}
-
+    if (!row.pass)
+        return row;
+    const started = ctx.now();
+    const verdict = await sonarQualityGate(ctx, { cwd: ctx.cwd, host: gate.provider.host, token: gate.env.SONAR_TOKEN });
+    const failed = (verdict.conditions ?? []).map((line) => `  failed: ${line}\n`).join('');
+    fs.appendFileSync(row.log, `\nquality gate: ${verdict.detail}\n${failed}`);
+    return { ...row, pass: verdict.pass, detail: verdict.detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
+}
 export const withoutCredentials = (values, credentialNames) => {
-  const selected = new Set(credentialNames);
-  return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
+    const selected = new Set(credentialNames);
+    return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
 };
-
 export function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
-  const log = path.join(dir, `${gate.name}.log`);
-  const started = ctx.now();
-  const [command, args] = launch(gate.command, platform);
-  // The native scanner alone consumes Sonar credentials; ordinary gates cannot inherit or reintroduce them.
-  const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)) };
-  const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
-  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
-  const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
-  fs.writeFileSync(log, preface + text);
-  const verdict = judgeVerdict(run, gate, text);
-  if (gate.name === 'sonar' && gate.env.SONAR_TOKEN) verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
-  const seconds = Math.round((ctx.now() - started) / 1000);
-  return {
-    name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
-    summary: verdict.summary ?? null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env),
-  };
-}
-
+    const log = path.join(dir, `${gate.name}.log`);
+    const started = ctx.now();
+    const [command, args] = launch(gate.command, platform);
+    // The native scanner alone consumes Sonar credentials; ordinary gates cannot inherit or reintroduce them.
+    const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)) };
+    const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
+    const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+    const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
+    fs.writeFileSync(log, preface + text);
+    const verdict = judgeVerdict(run, gate, text);
+    if (gate.name === 'sonar' && gate.env.SONAR_TOKEN)
+        verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
+    const seconds = Math.round((ctx.now() - started) / 1000);
+    return {
+        name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
+        summary: verdict.summary ?? null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env),
+    };
+}
 function judgeVerdict(run, gate, text) {
-  if (run.error) return { pass: false, detail: `cannot run (${run.error.message})` };
-  if (run.status !== 0) return { pass: false, detail: `exit ${run.status}` };
-  if (gate.summary === 'jest') return judgeJest(text);
-  return { pass: true, detail: 'exit 0' };
+    if (run.error)
+        return { pass: false, detail: `cannot run (${run.error.message})` };
+    if (run.status !== 0)
+        return { pass: false, detail: `exit ${run.status}` };
+    if (gate.summary === 'jest')
+        return judgeJest(text);
+    return { pass: true, detail: 'exit 0' };
 }
-
 /* ---- the gate */
-
 function sourceProblem(ctx, source, head) {
-  if (source === 'HEAD') return null;
-  if (!refName(source)) return `--source ${source} is not a ref name`;
-  const resolved = git(ctx, ['rev-parse', '--verify', `${source}^{commit}`], { allowFail: true });
-  if (resolved.code !== 0) return `cannot resolve --source ${source}`;
-  if (resolved.stdout !== head) return `--source ${source} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: the hook and the L4 record are about HEAD; check the candidate out first`;
-  return null;
-}
-
+    if (source === 'HEAD')
+        return null;
+    if (!refName(source))
+        return `--sha ${source} is not a ref name`;
+    const resolved = git(ctx, ['rev-parse', '--verify', `${source}^{commit}`], { allowFail: true });
+    if (resolved.code !== 0)
+        return `cannot resolve --sha ${source}`;
+    if (resolved.stdout !== head)
+        return `--sha ${source} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: the hook and the L4 record are about HEAD; check the candidate out first`;
+    return null;
+}
 function tagLine({ tag, state }) {
-  if (state === 'on-head') return `tag            ${tag} (annotated, already on HEAD)`;
-  if (state === 'taken') return `tag            ${tag} (TAKEN by another commit)`;
-  return `tag            ${tag} (free: will be created, annotated)`;
+    if (state === 'on-head')
+        return `tag            ${tag} (annotated, already on HEAD)`;
+    if (state === 'taken')
+        return `tag            ${tag} (TAKEN by another commit)`;
+    return `tag            ${tag} (free: will be created, annotated)`;
 }
-
 /** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
 export function inspect(ctx, config, options) {
-  const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
-  const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
-  const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
-  const red = [];
-  const problem = sourceProblem(ctx, options.source ?? 'HEAD', head);
-  if (problem) red.push(problem);
-  const dirty = dirtyPaths(ctx);
-  if (dirty.length > 0) red.push(`working tree is not clean (${dirty.length} path(s), first: ${dirty[0].slice(0, 100)}): the record would vouch for files that are not in HEAD`);
-  else out.push('worktree       clean');
-  const prefix = options.tagPrefix ?? config.tagPrefix;
-  if (!PREFIX.test(prefix)) throw refusal('RELEASE_USAGE', `--tag-prefix must match ${PREFIX}`);
-  const chosen = chooseTag(ctx, config, { prefix, remote: 'origin' });
-  if (chosen.state === 'taken') red.push(`tag ${chosen.tag} already exists on another commit (local or remote)`);
-  const stray = versionTagsOnHead(ctx).filter((name) => name !== chosen.tag);
-  if (stray.length > 0) red.push(`HEAD already carries the release tag ${stray[0]} but package.json version ${config.version} gives ${chosen.tag}: a release commit carries exactly one tag, so set the version to match the tag or release a new commit`);
-  out.push(tagLine(chosen));
-  return { head, chosen, red, out };
-}
-
+    const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
+    const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
+    const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
+    const red = [];
+    const problem = sourceProblem(ctx, (options.source ?? 'HEAD'), head);
+    if (problem)
+        red.push(problem);
+    const dirty = dirtyPaths(ctx);
+    if (dirty.length > 0)
+        red.push(`working tree is not clean (${dirty.length} path(s), first: ${dirty[0].slice(0, 100)}): the record would vouch for files that are not in HEAD`);
+    else
+        out.push('worktree       clean');
+    const prefix = (options.tagPrefix ?? config.tagPrefix);
+    if (!PREFIX.test(prefix))
+        throw refusal('RELEASE_USAGE', `--tag-prefix must match ${PREFIX}`);
+    const chosen = chooseTag(ctx, config, { prefix, remote: 'origin' });
+    if (chosen.state === 'taken')
+        red.push(`tag ${chosen.tag} already exists on another commit (local or remote)`);
+    const stray = versionTagsOnHead(ctx).filter((name) => name !== chosen.tag);
+    if (stray.length > 0)
+        red.push(`HEAD already carries the release tag ${stray[0]} but package.json version ${config.version} gives ${chosen.tag}: a release commit carries exactly one tag, so set the version to match the tag or release a new commit`);
+    out.push(tagLine(chosen));
+    return { head, chosen, red, out };
+}
 function planLines(config, facts, dir, recordPath) {
-  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (every gate must pass, in this order):'];
-  for (const gate of config.gates) {
-    const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
-    const teardown = gate.teardownOf ? ` (teardown of ${gate.teardownOf}: runs whenever it ran)` : '';
-    out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}${teardown}`);
-  }
-  out.push(`then: write ${path.basename(recordPath)} and \`git tag -a ${facts.chosen.tag}\` on ${facts.head.slice(0, 10)}; push it with \`starci app release push\`.`);
-  return out;
-}
-
+    const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (every gate must pass, in this order):'];
+    for (const gate of config.gates) {
+        const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
+        const teardown = gate.teardownOf ? ` (teardown of ${gate.teardownOf}: runs whenever it ran)` : '';
+        out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}${teardown}`);
+    }
+    out.push(`then: write ${path.basename(recordPath)} and \`git tag -a ${facts.chosen.tag}\` on ${facts.head.slice(0, 10)}; push it with \`starci app release push\`.`);
+    return out;
+}
 export function assertUnmoved(ctx, head) {
-  const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
-  if (now !== head) throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
-  const dirty = dirtyPaths(ctx);
-  if (dirty.length > 0) throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
+    const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
+    if (now !== head)
+        throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
+    const dirty = dirtyPaths(ctx);
+    if (dirty.length > 0)
+        throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
 }
-
 function writeRecord(ctx, { head, tag, results, recordPath, requireCi, promotedFrom = null }) {
-  const record = {
-    schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
-    note: 'Every gate passed on a clean HEAD; every entry links its log and sha256.',
-    ci: requireCi === true ? { required: true, note: 'starci app release push waits for the candidate CI of this sha (release.requireCi=true)' } : { required: false, note: CI_NOT_REQUIRED },
-    ...(promotedFrom ? { promotedFrom } : {}),
-    gates: results,
-  };
-  fs.mkdirSync(path.dirname(recordPath), { recursive: true });
-  fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
-}
-
+    const record = {
+        schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
+        note: 'Every gate passed on a clean HEAD; every entry links its log and sha256.',
+        ci: requireCi === true ? { required: true, note: 'starci app release push waits for the candidate CI of this sha (release.requireCi=true)' } : { required: false, note: CI_NOT_REQUIRED },
+        ...(promotedFrom ? { promotedFrom } : {}),
+        gates: results,
+    };
+    fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+    fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+}
 /**
  * Gates run sequentially because each failure prevents subsequent commands and record creation. A teardown row (`teardownOf`) is the exception: it runs
  * whenever the row it tears down ran, red or green, so a red row never leaves a started service behind; its own verdict counts like any row's.
  */
 async function runAll(ctx, config, options) {
-  fs.mkdirSync(options.dir, { recursive: true });
-  return config.gates.reduce(async (pending, gate) => {
-    const results = await pending;
-    if (results.some((result) => !result.pass) && !(gate.teardownOf && results.some((result) => result.name === gate.teardownOf))) return results;
-    const result = await runAvailableGate(ctx, gate, options);
-    recordRow(options.common, options.head, result);
-    return [...results, result];
-  }, Promise.resolve([]));
-}
-
+    fs.mkdirSync(options.dir, { recursive: true });
+    return config.gates.reduce(async (pending, gate) => {
+        const results = await pending;
+        if (results.some((result) => !result.pass) && !(gate.teardownOf && results.some((result) => result.name === gate.teardownOf)))
+            return results;
+        const result = await runAvailableGate(ctx, gate, options);
+        recordRow(options.common, options.head, result);
+        return [...results, result];
+    }, Promise.resolve([]));
+}
 export function summaryOf(result) {
-  return `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+    return `${result.pass ? 'PASS' : 'FAIL'} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
 }
-
 /**
  * The urgent release a back-fill judges: `tag` must name HEAD (the back-fill runs on the very commit that shipped, never a re-release) and HEAD must
  * carry an urgent record of that tag. Returns the record; refuses otherwise.
  */
 function backfillTarget(ctx, common, tag, head) {
-  if (!refName(tag)) throw refusal('RELEASE_USAGE', `--backfill ${tag} is not a tag name`);
-  const resolved = git(ctx, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}^{commit}`], { allowFail: true });
-  if (resolved.code !== 0 || resolved.stdout === '') throw refusal('RELEASE_BACKFILL_TAG_UNKNOWN', `no tag ${tag} in this repository`);
-  if (resolved.stdout !== head) throw refusal('RELEASE_BACKFILL_NOT_ON_TAG', `${tag} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: run the back-fill in a clean checkout of the tag (git worktree add --detach <dir> ${tag}), so the full gate judges exactly what shipped`);
-  const urgent = readUrgent(common, head);
-  if (!urgent || urgent.tag !== tag) throw refusal('RELEASE_BACKFILL_NOT_URGENT', `${tag} has no urgent record on ${head.slice(0, 10)}: only a release pushed with release push --urgent is back-filled`);
-  return urgent;
-}
-
+    if (!refName(tag))
+        throw refusal('RELEASE_USAGE', `--backfill ${tag} is not a tag name`);
+    const resolved = git(ctx, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}^{commit}`], { allowFail: true });
+    if (resolved.code !== 0 || resolved.stdout === '')
+        throw refusal('RELEASE_BACKFILL_TAG_UNKNOWN', `no tag ${tag} in this repository`);
+    if (resolved.stdout !== head)
+        throw refusal('RELEASE_BACKFILL_NOT_ON_TAG', `${tag} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: run the back-fill in a clean checkout of the tag (git worktree add --detach <dir> ${tag}), so the full gate judges exactly what shipped`);
+    const urgent = readUrgent(common, head);
+    if (!urgent || urgent.tag !== tag)
+        throw refusal('RELEASE_BACKFILL_NOT_URGENT', `${tag} has no urgent record on ${head.slice(0, 10)}: only a release pushed with release push --urgent is back-filled`);
+    return urgent;
+}
 /** A red back-fill: the urgent record keeps the verdict and the fix ticket (kind verify) the harness opened; nothing on the remote or on prod changes. */
 function backfillRed(ctx, { common, urgent, failed, openTicket }) {
-  const names = failed.map((item) => item.name);
-  const title = `RELEASE_BACKFILL_RED: the back-fill of urgent release ${urgent.tag} (${urgent.head.slice(0, 12)}) is red at ${names.join(', ')}`;
-  const tail = failed.map((item) => `${item.name}: ${item.detail} (log ${item.log})`).join('\n');
-  const ticket = typeof openTicket === 'function' ? openTicket({ title, tail, code: 'RELEASE_BACKFILL_RED', tag: urgent.tag, head: urgent.head }) : null;
-  writeUrgent(common, { ...urgent, backfill: { state: 'red', at: new Date(ctx.now()).toISOString(), failed: names, ticket: ticket ?? null } });
-  const said = ticket
-    ? `back-fill red: fix ticket ${ticket} opened (kind verify); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`
-    : `back-fill red: no ticket queue in this run (run it through the starci CLI to open one); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`;
-  return { said, ticket: ticket ?? null };
-}
-
+    const names = failed.map((item) => item.name);
+    const title = `RELEASE_BACKFILL_RED: the back-fill of urgent release ${urgent.tag} (${urgent.head.slice(0, 12)}) is red at ${names.join(', ')}`;
+    const tail = failed.map((item) => `${item.name}: ${item.detail} (log ${item.log})`).join('\n');
+    const ticket = typeof openTicket === 'function' ? openTicket({ title, tail, code: 'RELEASE_BACKFILL_RED', tag: urgent.tag, head: urgent.head }) : null;
+    writeUrgent(common, { ...urgent, backfill: { state: 'red', at: new Date(ctx.now()).toISOString(), failed: names, ticket: ticket ?? null } });
+    const said = ticket
+        ? `back-fill red: fix ticket ${ticket} opened (kind verify); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`
+        : `back-fill red: no ticket queue in this run (run it through the starci CLI to open one); ${urgent.tag} stays an urgent release and nothing on the remote or on prod changed`;
+    return { said, ticket: ticket ?? null };
+}
 /**
  * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
- * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform, backfill, openTicket }.
+ * writes the L4 record and creates the annotated tag. options: { execute, source (the --sha ref), tagPrefix, platform, backfill, openTicket }.
  * With `backfill` (a tag pushed by `release push --urgent`, checked out at HEAD) the same full gate judges that commit: green writes its L4 record
  * (promotedFrom the urgent record) and marks the urgent record promoted, with no new tag and no push; red opens a fix ticket through `openTicket`.
  */
 export async function releaseGate(ctx, config, options = {}) {
-  // Sonar is a row of the managed CI, so it is a row of the local gate whenever the app declares it (and when --sonar asks for it); a missing token is a refusal, never a skip.
-  if (options.sonar || config.services?.sonar) config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
-  const credentialNames = config.gates.find(gate => gate.provider)?.credentialNames ?? ['SONAR_TOKEN', config.services?.sonar?.token].filter(Boolean);
-  ctx = Object.create(ctx, {env: {value: withoutCredentials(ctx.env, credentialNames)}});
-  // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):
-  // the gate no longer refuses over the latest default-branch run.
-  const facts = inspect(ctx, config, options);
-  const common = releaseDir(ctx);
-  const urgent = options.backfill === undefined ? null : backfillTarget(ctx, common, options.backfill, facts.head);
-  const recordPath = l4Path(common, facts.head);
-  const dir = path.join(common, facts.head.slice(0, 12));
-  const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
-  if (urgent) plan.push(`back-fill      urgent release ${urgent.tag} (${URGENT_RULING}): green promotes it to this L4 record with no new tag and no push; red opens a fix ticket and changes nothing on prod`);
-  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ...(urgent ? { backfill: urgent.tag } : {}) };
-  if (urgent?.backfill?.state === 'promoted') return { ok: true, lines: [...plan, `back-fill already promoted ${urgent.tag} to ${urgent.backfill.l4}. Nothing to do.`], data: { ...base, red: [], executed: false, promoted: true } };
-  if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
-  if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
-  const results = await runAll(ctx, config, { dir, common, head: facts.head, platform: options.platform ?? process.platform, credentialNames });
-  const report = results.map(summaryOf);
-  const failed = results.filter((result) => !result.pass);
-  if (failed.length > 0 && urgent) {
-    const { said, ticket } = backfillRed(ctx, { common, urgent, failed, openTicket: options.openTicket });
-    return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record.`, said], data: { ...base, executed: true, results, promoted: false, ticket } };
-  }
-  if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
-  assertUnmoved(ctx, facts.head);
-  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi, promotedFrom: urgent ? { record: `${facts.head}.urgent.json`, reason: urgent.reason, role: urgent.role, at: urgent.createdAt } : null });
-  if (urgent) {
-    writeUrgent(common, { ...urgent, backfill: { state: 'promoted', at: new Date(ctx.now()).toISOString(), l4: recordPath } });
-    return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, `back-fill green: urgent release ${urgent.tag} is promoted to a normal L4 release (no re-release, no push)`], data: { ...base, executed: true, results, promoted: true } };
-  }
-  const created = facts.chosen.state !== 'on-head';
-  if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
-  const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;
-  return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
+    // Sonar is a row of the managed CI, so it is a row of the local gate whenever the app declares services.sonar; a missing token is a refusal, never a skip.
+    if (config.services?.sonar)
+        config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
+    const credentialNames = config.gates.find(gate => gate.provider)?.credentialNames ?? ['SONAR_TOKEN', config.services?.sonar?.token].filter(Boolean);
+    ctx = Object.create(ctx, { env: { value: withoutCredentials(ctx.env, credentialNames) } });
+    // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):
+    // the gate no longer refuses over the latest default-branch run.
+    const facts = inspect(ctx, config, options);
+    const common = releaseDir(ctx);
+    const urgent = options.backfill === undefined ? null : backfillTarget(ctx, common, options.backfill, facts.head);
+    const recordPath = l4Path(common, facts.head);
+    const dir = path.join(common, facts.head.slice(0, 12));
+    const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
+    if (urgent)
+        plan.push(`back-fill      urgent release ${urgent.tag} (${URGENT_RULING}): green promotes it to this L4 record with no new tag and no push; red opens a fix ticket and changes nothing on prod`);
+    const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name), ...(urgent ? { backfill: urgent.tag } : {}) };
+    if (urgent?.backfill?.state === 'promoted')
+        return { ok: true, lines: [...plan, `back-fill already promoted ${urgent.tag} to ${urgent.backfill.l4}. Nothing to do.`], data: { ...base, red: [], executed: false, promoted: true } };
+    if (facts.red.length > 0)
+        return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
+    if (options.execute !== true)
+        return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
+    const results = await runAll(ctx, config, { dir, common, head: facts.head, platform: options.platform ?? process.platform, credentialNames });
+    const report = results.map(summaryOf);
+    const failed = results.filter((result) => !result.pass);
+    if (failed.length > 0 && urgent) {
+        const { said, ticket } = backfillRed(ctx, { common, urgent, failed, openTicket: options.openTicket });
+        return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record.`, said], data: { ...base, executed: true, results, promoted: false, ticket } };
+    }
+    if (failed.length > 0)
+        return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
+    assertUnmoved(ctx, facts.head);
+    writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi, promotedFrom: urgent ? { record: `${facts.head}.urgent.json`, reason: urgent.reason, role: urgent.role, at: urgent.createdAt } : null });
+    if (urgent) {
+        writeUrgent(common, { ...urgent, backfill: { state: 'promoted', at: new Date(ctx.now()).toISOString(), l4: recordPath } });
+        return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, `back-fill green: urgent release ${urgent.tag} is promoted to a normal L4 release (no re-release, no push)`], data: { ...base, executed: true, results, promoted: true } };
+    }
+    const created = facts.chosen.state !== 'on-head';
+    if (created)
+        git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
+    const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;
+    return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
 }