@ngockhoale/ukit 3.4.27 → 3.4.28

package/template_project/.claude/ukit/index/ci-check.mjs

@@ -0,0 +1,665 @@
+#!/usr/bin/env node
+// /ukit:ci-check orchestrator. MANUAL ONLY: the single place that may dispatch the CI workflow, and
+// only when the user invoked the command (`run --explicit`). One dispatch per invocation, no retry,
+// no push, no merge, no publish. State lives in <project>/.ukit/storage/ci-check/ (never the User Layer).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULTS = Object.freeze({
+  workflow: 'cross-platform-ci.yml',
+  maxDispatchPerInvocation: 1,
+  maxJobs: 3,
+  maxBilledMinutesPerRun: 400,
+  monthlyFreeMinutes: 2000,
+  lockStaleMs: 10 * 60 * 1000,
+  staleInvocationMs: 6 * 60 * 60 * 1000,
+  discoverAttempts: 6,
+  discoverDelayMs: 5000,
+  waitIntervalMs: 30000,
+  waitTimeoutMs: 45 * 60 * 1000,
+  maxWaitPerCallMs: 9 * 60 * 1000,
+  pollErrorTolerance: 3,
+});
+
+const STANDARD_RUNNER = /^(ubuntu|windows|macos)-(latest|\d{2}(\.\d{2})?)$/;
+const MINUTE_MULTIPLIER = { ubuntu: 1, windows: 2, macos: 10 };
+const SAFE_NAME = /^[A-Za-z0-9._/-]+$/;
+const OS_LABEL = { ubuntu: 'LINUX', windows: 'WINDOWS', macos: 'MACOS' };
+const IN_FLIGHT = new Set(['queued', 'in_progress', 'waiting', 'requested', 'pending']);
+
+// ---------------------------------------------------------------- workflow parsing (no yaml dep)
+const stripComment = (l) => l.replace(/\s+#.*$/, '').replace(/^\s*#.*$/, '');
+const indentOf = (l) => l.match(/^ */)[0].length;
+const unquote = (s) => s.trim().replace(/^['"]|['"]$/g, '');
+const flowList = (s) => {
+  const m = s.trim().match(/^\[(.*)\]$/);
+  return m ? m[1].split(',').map(unquote).filter(Boolean) : null;
+};
+
+export function parseWorkflowFacts(text) {
+  const errors = [];
+  const lines = text.replace(/\r\n/g, '\n').split('\n').map(stripComment);
+  const triggers = [];
+  const onIdx = lines.findIndex((l) => /^["']?on["']?\s*:/.test(l));
+  if (onIdx < 0) errors.push('no top-level `on:` block');
+  else {
+    const rest = lines[onIdx].replace(/^["']?on["']?\s*:/, '').trim();
+    if (rest) {
+      const list = flowList(rest);
+      if (list) triggers.push(...list);
+      else if (/^\{.*\}$/.test(rest)) {
+        triggers.push(...rest.slice(1, -1).split(',').map((p) => unquote(p.split(':')[0])).filter(Boolean));
+      } else triggers.push(unquote(rest));
+    } else {
+      const block = [];
+      for (let i = onIdx + 1; i < lines.length; i += 1) {
+        if (!lines[i].trim()) continue;
+        if (indentOf(lines[i]) === 0) break;
+        block.push(lines[i]);
+      }
+      const min = Math.min(...block.map(indentOf));
+      for (const l of block) {
+        if (indentOf(l) !== min) continue;
+        const m = l.trim().match(/^(?:-\s*)?["']?([A-Za-z_]+)["']?\s*:?/);
+        if (m) triggers.push(m[1]);
+      }
+    }
+  }
+
+  const jobs = [];
+  const jobsIdx = lines.findIndex((l) => /^jobs\s*:/.test(l));
+  if (jobsIdx < 0) errors.push('no `jobs:` block');
+  else {
+    const body = [];
+    for (let i = jobsIdx + 1; i < lines.length; i += 1) {
+      if (lines[i].trim() && indentOf(lines[i]) === 0) break;
+      body.push(lines[i]);
+    }
+    const nonEmpty = body.filter((l) => l.trim());
+    const jobIndent = nonEmpty.length ? Math.min(...nonEmpty.map(indentOf)) : 0;
+    let cur = null;
+    for (const l of body) {
+      if (!l.trim()) continue;
+      if (indentOf(l) === jobIndent && /^\s*[\w-]+\s*:\s*$/.test(l)) {
+        cur = { id: l.trim().slice(0, -1), lines: [] };
+        jobs.push(cur);
+      } else if (cur) cur.lines.push(l);
+    }
+    for (const job of jobs) {
+      job.timeoutMinutes = null;
+      job.runsOn = null;
+      job.matrix = {};
+      let inMatrix = false;
+      let matrixIndent = -1;
+      for (const l of job.lines) {
+        const t = l.trim();
+        const ind = indentOf(l);
+        let m = t.match(/^timeout-minutes\s*:\s*(\d+)$/);
+        if (m && ind === jobIndent + 2) job.timeoutMinutes = Number(m[1]);
+        m = t.match(/^runs-on\s*:\s*(.+)$/);
+        if (m && ind === jobIndent + 2) job.runsOn = unquote(m[1]);
+        if (/^matrix\s*:\s*$/.test(t)) { inMatrix = true; matrixIndent = ind; continue; }
+        if (inMatrix && ind <= matrixIndent) inMatrix = false;
+        if (inMatrix) {
+          m = t.match(/^([\w-]+)\s*:\s*(.*)$/);
+          if (!m) { errors.push(`job ${job.id}: unsupported matrix line "${t}"`); continue; }
+          if (m[1] === 'include' || m[1] === 'exclude') { errors.push(`job ${job.id}: matrix ${m[1]} is not supported (fail-closed)`); continue; }
+          const list = flowList(m[2]);
+          if (!list) errors.push(`job ${job.id}: matrix.${m[1]} must be a flow list`);
+          else job.matrix[m[1]] = list;
+        }
+      }
+      delete job.lines;
+    }
+  }
+  return { ok: errors.length === 0, errors, triggers, jobs };
+}
+
+export function assertManualOnly(text) {
+  const facts = parseWorkflowFacts(text);
+  const only = facts.triggers.length === 1 && facts.triggers[0] === 'workflow_dispatch';
+  const errors = [...facts.errors];
+  if (!only) errors.push(`triggers must be exactly [workflow_dispatch], found [${facts.triggers.join(', ') || 'none'}]`);
+  return { ok: errors.length === 0, triggers: facts.triggers, errors };
+}
+
+export function workflowReferencedPaths(text) {
+  const out = new Set();
+  const code = text.split('\n').filter((l) => !/^\s*#/.test(l)).join('\n');
+  for (const m of code.matchAll(/(?:\.github\/ci\/[\w.-]+\.mjs|tests\/[\w/.-]+\.test\.js|tests\/python\/[\w.-]+\.(?:mjs|txt))/g)) out.add(m[0]);
+  return [...out].sort();
+}
+
+// ---------------------------------------------------------------- budget guard (fail-closed)
+export function loadPolicy(root) {
+  const p = path.join(root, '.ukit', 'storage', 'config.json');
+  let override = {};
+  if (fs.existsSync(p)) {
+    try { override = JSON.parse(fs.readFileSync(p, 'utf8')).ciCheck || {}; } catch { return { policy: { ...DEFAULTS }, error: `${p} is not valid JSON` }; }
+  }
+  return { policy: { ...DEFAULTS, ...override }, error: null };
+}
+
+export function budgetGuard(text, policy) {
+  const failures = [];
+  const facts = parseWorkflowFacts(text);
+  failures.push(...facts.errors);
+  let jobCount = 0;
+  let billed = 0;
+  const perOs = {};
+  for (const job of facts.jobs) {
+    if (job.timeoutMinutes == null) { failures.push(`job ${job.id}: timeout-minutes missing`); continue; }
+    const dims = Object.values(job.matrix);
+    const osList = job.runsOn && /\$\{\{\s*matrix\.os\s*\}\}/.test(job.runsOn) ? job.matrix.os : job.runsOn ? [job.runsOn] : null;
+    if (!osList) { failures.push(`job ${job.id}: runs-on not resolvable`); continue; }
+    const others = dims.filter((d) => d !== job.matrix.os).reduce((n, d) => n * d.length, 1);
+    for (const label of osList) {
+      if (!STANDARD_RUNNER.test(label)) { failures.push(`job ${job.id}: runner "${label}" is not a standard GitHub-hosted runner`); continue; }
+      const family = label.split('-')[0];
+      const n = others;
+      jobCount += n;
+      const minutes = n * job.timeoutMinutes * MINUTE_MULTIPLIER[family];
+      billed += minutes;
+      perOs[family] = (perOs[family] || 0) + minutes;
+    }
+  }
+  if (jobCount === 0) failures.push('no resolvable jobs');
+  if (jobCount > policy.maxJobs) failures.push(`${jobCount} jobs exceeds ciCheck.maxJobs=${policy.maxJobs}`);
+  if (billed > policy.maxBilledMinutesPerRun) failures.push(`worst-case ${billed} billed minutes exceeds ciCheck.maxBilledMinutesPerRun=${policy.maxBilledMinutesPerRun}`);
+  if (policy.maxDispatchPerInvocation !== 1) failures.push('ciCheck.maxDispatchPerInvocation must be 1');
+  return {
+    ok: failures.length === 0,
+    failures,
+    estimate: {
+      jobs: jobCount,
+      worstCaseBilledMinutes: billed,
+      perRunner: perOs,
+      note: 'Worst case = timeout-minutes x runner multiplier (Linux 1x, Windows 2x, macOS 10x). Actual usage is usually far lower.',
+      monthlyFreeMinutes: policy.monthlyFreeMinutes,
+      shareOfMonthlyFree: policy.monthlyFreeMinutes ? Number((billed / policy.monthlyFreeMinutes).toFixed(3)) : null,
+      billingVerified: false,
+      quotaNote: 'ESTIMATE ONLY (timeout x multiplier). Billing/quota is NOT verified: this does not guarantee the run fits in any free quota. Check Settings > Billing > Actions and set a spending budget with a hard stop yourself.',
+    },
+  };
+}
+
+// ---------------------------------------------------------------- state (write-ahead)
+const stateDir = (root) => path.join(root, '.ukit', 'storage', 'ci-check');
+const statePath = (root) => path.join(stateDir(root), 'state.json');
+
+export class StateCorruptError extends Error {}
+// Missing file = empty history. An unreadable/corrupt file must NOT read as empty: that would forget a
+// past dispatch and allow a duplicate one (fail closed instead).
+export function readState(root) {
+  let raw;
+  try { raw = fs.readFileSync(statePath(root), 'utf8'); } catch (e) {
+    if (e.code === 'ENOENT') return { version: 1, invocations: [] };
+    throw new StateCorruptError(`${statePath(root)} unreadable: ${e.message}`);
+  }
+  try {
+    const st = JSON.parse(raw);
+    if (!st || !Array.isArray(st.invocations)) throw new Error('missing invocations[]');
+    return st;
+  } catch (e) { throw new StateCorruptError(`${statePath(root)} is corrupt (${e.message}); inspect or move it aside, UKit will not guess`); }
+}
+export function writeState(root, state) {
+  fs.mkdirSync(stateDir(root), { recursive: true });
+  const tmp = `${statePath(root)}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmp, statePath(root));
+}
+function updateRecord(root, id, patch) {
+  const state = readState(root);
+  const rec = state.invocations.find((r) => r.id === id);
+  if (rec) Object.assign(rec, patch);
+  writeState(root, state);
+  return rec;
+}
+const pidAlive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+};
+// A lock is only taken over when its owner process is gone. An old lock whose owner is still alive is a
+// slow dispatcher, not a crashed one: stealing it would allow two dispatches for one invocation.
+function acquireLock(root, policy, now) {
+  fs.mkdirSync(stateDir(root), { recursive: true });
+  const lock = path.join(stateDir(root), 'dispatch.lock');
+  const mine = JSON.stringify({ pid: process.pid, at: now() });
+  const tryCreate = () => { fs.writeFileSync(lock, mine, { flag: 'wx' }); return true; };
+  try { tryCreate(); } catch (e) {
+    if (e.code !== 'EEXIST') return null;
+    let owner = null;
+    try { owner = JSON.parse(fs.readFileSync(lock, 'utf8')).pid; } catch { /* unreadable: treat as unknown owner */ }
+    const ageMs = (() => { try { return now() - fs.statSync(lock).mtimeMs; } catch { return 0; } })();
+    const dead = owner != null ? !pidAlive(owner) : ageMs > policy.lockStaleMs;
+    if (!dead) return null;
+    // Atomic takeover: only one contender can rename the stale lock away.
+    try { fs.renameSync(lock, `${lock}.stale.${process.pid}`); } catch { return null; }
+    try { fs.rmSync(`${lock}.stale.${process.pid}`, { force: true }); tryCreate(); } catch { return null; }
+  }
+  return () => {
+    try { if (JSON.parse(fs.readFileSync(lock, 'utf8')).pid === process.pid) fs.rmSync(lock); } catch { /* already gone */ }
+  };
+}
+
+// ---------------------------------------------------------------- deps
+export function defaultDeps(root) {
+  const exec = (cmd, args, opts = {}) => {
+    const r = spawnSync(cmd, args, { cwd: root, encoding: 'utf8', shell: process.platform === 'win32' && cmd !== 'git' && cmd !== 'gh', maxBuffer: 64 * 1024 * 1024, ...opts });
+    return { code: r.status ?? 1, stdout: r.stdout || '', stderr: r.stderr || (r.error ? String(r.error.message) : '') };
+  };
+  return {
+    git: (args) => exec('git', args),
+    gh: (args) => exec('gh', args),
+    run: (cmd, args) => exec(cmd, args),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now(),
+  };
+}
+
+const ghJson = (deps, args) => {
+  const r = deps.gh(args);
+  if (r.code !== 0) return { ok: false, error: (r.stderr || r.stdout).trim() };
+  try { return { ok: true, data: JSON.parse(r.stdout || 'null') }; } catch { return { ok: false, error: 'invalid JSON from gh' }; }
+};
+
+// ---------------------------------------------------------------- args
+export function parseArgs(argv) {
+  const a = { mode: 'run', ref: null, dryRun: false, explicit: false, wait: false, maxWaitMs: null, json: false, runId: null, workflow: null, allowSameSha: false, errors: [] };
+  const args = [...argv];
+  if (args[0] === 'status') { a.mode = 'status'; args.shift(); } else if (args[0] === 'run') args.shift();
+  while (args.length) {
+    const t = args.shift();
+    if (t === '--ref') a.ref = args.shift() ?? '';
+    else if (t === '--dry-run') a.dryRun = true;
+    else if (t === '--explicit') a.explicit = true;
+    else if (t === '--wait') a.wait = true;
+    else if (t === '--max-wait') { const n = Number(args.shift()); if (Number.isFinite(n) && n > 0) a.maxWaitMs = n * 1000; else a.errors.push('--max-wait needs seconds > 0'); }
+    else if (t === '--json') a.json = true;
+    else if (t === '--allow-same-sha') a.allowSameSha = true;
+    else if (t === '--workflow') a.workflow = args.shift() ?? '';
+    else if (/^\d+$/.test(t) && a.mode === 'status') a.runId = t;
+    else a.errors.push(`unknown argument: ${t}`);
+  }
+  for (const [k, v] of [['ref', a.ref], ['workflow', a.workflow]]) {
+    if (v !== null && (!SAFE_NAME.test(v) || v.startsWith('-'))) a.errors.push(`invalid --${k} value`);
+  }
+  if (a.mode === 'status' && a.dryRun) a.errors.push('--dry-run does not apply to status');
+  return a;
+}
+
+// ---------------------------------------------------------------- prechecks
+function gitShow(deps, sha, p) {
+  const r = deps.git(['show', `${sha}:${p}`]);
+  return r.code === 0 ? r.stdout : null;
+}
+
+export function precheck({ root, deps, args, policy, policyError }) {
+  const blockers = [];
+  const warnings = [];
+  const checks = [];
+  const note = (name, ok, detail) => { checks.push({ name, ok, detail }); if (!ok) blockers.push(`${name}: ${detail}`); };
+  const ctx = { workflow: args.workflow || policy.workflow };
+
+  note('git-repository', deps.git(['rev-parse', '--is-inside-work-tree']).code === 0, 'not inside a Git repository');
+  const remote = deps.git(['remote', 'get-url', 'origin']);
+  note('git-remote', remote.code === 0, 'no `origin` remote');
+  let ref = args.ref;
+  if (!ref) {
+    const b = deps.git(['rev-parse', '--abbrev-ref', 'HEAD']);
+    ref = b.code === 0 ? b.stdout.trim() : '';
+    if (b.code !== 0) { const sym = deps.git(['symbolic-ref', '--short', 'HEAD']); ref = sym.code === 0 ? sym.stdout.trim() : ''; }
+    if (!ref || ref === 'HEAD') { note('git-branch', false, 'detached HEAD; pass --ref <branch>'); ref = null; }
+    else if (b.code !== 0) { note('git-commits', false, `branch "${ref}" has no commits yet`); }
+  }
+  ctx.ref = ref;
+  if (blockers.length) return { ...ctx, blockers, warnings, checks };
+
+  note('gh-auth', deps.gh(['auth', 'status']).code === 0, 'GitHub CLI is not authenticated (run `gh auth login`)');
+
+  const local = deps.git(['rev-parse', '--verify', `refs/heads/${ref}`]);
+  const lsr = deps.git(['ls-remote', '--heads', 'origin', `refs/heads/${ref}`]);
+  const remoteSha = lsr.code === 0 ? (lsr.stdout.trim().split(/\s+/)[0] || null) : null;
+  if (lsr.code !== 0) note('remote-branch', false, `cannot query remote: ${lsr.stderr.trim()}`);
+  else if (!remoteSha) note('remote-branch', false, `branch "${ref}" does not exist on origin. UKit will NOT push; pushing needs your separate approval`);
+  else if (local.code === 0 && local.stdout.trim() !== remoteSha) {
+    note('remote-commit', false, `local ${local.stdout.trim().slice(0, 8)} differs from origin ${remoteSha.slice(0, 8)}; CI would test the remote commit. Pushing needs your separate approval`);
+  } else checks.push({ name: 'remote-commit', ok: true, detail: remoteSha.slice(0, 8) });
+  ctx.sha = remoteSha;
+
+  const wfPath = `.github/workflows/${ctx.workflow}`;
+  const dirty = deps.git(['status', '--porcelain', '--', '.github']);
+  if (dirty.stdout.trim()) warnings.push('uncommitted changes under .github/: CI runs the committed remote version');
+
+  let wfText = null;
+  let siblings = [];
+  if (remoteSha) {
+    wfText = gitShow(deps, remoteSha, wfPath);
+    if (wfText === null) note('workflow-file', false, `${wfPath} is not present at ${remoteSha.slice(0, 8)} (fetch the branch, or the workflow is missing)`);
+    const ls = deps.git(['ls-tree', '--name-only', remoteSha, '.github/workflows/']);
+    siblings = ls.code === 0 ? ls.stdout.split('\n').filter((f) => /\.ya?ml$/.test(f)) : [];
+    for (const f of siblings) {
+      const t = gitShow(deps, remoteSha, f);
+      const m = t === null ? { ok: false, errors: ['unreadable'] } : assertManualOnly(t);
+      note(`manual-only:${path.basename(f)}`, m.ok, m.errors.join('; '));
+    }
+  }
+  ctx.workflowText = wfText;
+
+  const repo = ghJson(deps, ['repo', 'view', '--json', 'nameWithOwner,isPrivate,defaultBranchRef']);
+  if (!repo.ok) note('gh-repo', false, repo.error);
+  else {
+    ctx.repo = repo.data.nameWithOwner;
+    ctx.private = repo.data.isPrivate;
+    ctx.defaultBranch = repo.data.defaultBranchRef?.name;
+  }
+  const wfs = ghJson(deps, ['workflow', 'list', '--all', '--json', 'name,path,state']);
+  if (!wfs.ok) note('workflow-registered', false, wfs.error);
+  else {
+    const reg = wfs.data.find((w) => w.path === wfPath);
+    if (!reg) note('workflow-registered', false, `${wfPath} is not registered on the default branch (${ctx.defaultBranch || '?'}). workflow_dispatch needs a bootstrap stub there; see docs/design/CI-CROSS-PLATFORM-MATRIX.md "Default-branch bootstrap". Not pushing`);
+    else if (reg.state !== 'active') note('workflow-registered', false, `workflow state is "${reg.state}"`);
+    else checks.push({ name: 'workflow-registered', ok: true, detail: reg.state });
+  }
+
+  const runs = ghJson(deps, ['run', 'list', '--workflow', ctx.workflow, '--limit', '20', '--json', 'databaseId,status,conclusion,headSha,headBranch,event,createdAt,url']);
+  if (!runs.ok) note('existing-runs', false, runs.error);
+  else {
+    ctx.knownRunIds = runs.data.map((r) => r.databaseId);
+    const flightHere = runs.data.filter((r) => IN_FLIGHT.has(r.status) && r.headBranch === ref);
+    for (const r of flightHere) note('duplicate-run', false, `run ${r.databaseId} is already ${r.status} on "${ref}" (${r.url}); use \`/ukit:ci-check status\``);
+    const sameSha = runs.data.find((r) => r.headSha === remoteSha && r.status === 'completed');
+    if (sameSha && !args.allowSameSha) note('duplicate-run', false, `run ${sameSha.databaseId} already completed (${sameSha.conclusion}) for ${remoteSha?.slice(0, 8)}; pass --allow-same-sha to run again`);
+    const elsewhere = runs.data.filter((r) => IN_FLIGHT.has(r.status) && r.headBranch !== ref);
+    if (elsewhere.length) warnings.push(`${elsewhere.length} other in-flight run(s) on other refs`);
+  }
+
+  let state = null;
+  try { state = readState(root); } catch (e) { note('state-file', false, e.message); }
+  for (const r of state?.invocations || []) {
+    if (!(r.workflow === ctx.workflow && ['dispatching', 'dispatched'].includes(r.status) && !r.concluded)) continue;
+    if (r.sha !== remoteSha && !r.runId) continue;
+    const age = deps.now() - Date.parse(r.dispatchedAt || r.startedAt);
+    const staleAfter = r.status === 'dispatching' ? policy.lockStaleMs : policy.staleInvocationMs;
+    if (!r.runId && age > staleAfter) {
+      // Interrupted record. Read-only look for a run it may have created; only if none exists is it abandoned.
+      const found = findRunForRecord(deps, r, ctx.workflow);
+      if (!found) { warnings.push(`invocation ${r.id} was ${r.status} for ${Math.round(age / 60000)} min with no run visible on GitHub: treated as abandoned`); continue; }
+    }
+    if (r.sha !== remoteSha && r.runId == null) continue;
+    note('duplicate-invocation', false, `invocation ${r.id} already ${r.status}${r.runId ? ` (run ${r.runId})` : ''}; use \`/ukit:ci-check status\``);
+  }
+
+  if (policyError) note('budget-guard', false, policyError);
+  else if (wfText) {
+    const g = budgetGuard(wfText, policy);
+    ctx.estimate = g.estimate;
+    if (!g.ok) for (const f of g.failures) note('budget-guard', false, f);
+    else {
+      checks.push({ name: 'budget-guard', ok: true, detail: `${g.estimate.jobs} jobs, worst case ${g.estimate.worstCaseBilledMinutes} billed min` });
+      const missing = ['windows', 'macos', 'ubuntu'].filter((f) => !(f in g.estimate.perRunner));
+      if (missing.length) note('real-matrix', false, `workflow at the ref does not cover ${missing.join(', ')}: it looks like the bootstrap stub or an incomplete matrix, not the real cross-platform CI. Not dispatching`);
+    }
+  }
+  return { ...ctx, blockers, warnings, checks };
+}
+
+export function localPreflight({ root, deps, ctx }) {
+  const results = [];
+  const add = (name, ok, detail = '') => results.push({ name, ok, detail });
+  for (const p of workflowReferencedPaths(ctx.workflowText || '')) {
+    const r = deps.git(['cat-file', '-e', `${ctx.sha}:${p}`]);
+    add(`tracked:${p}`, r.code === 0, r.code === 0 ? '' : 'referenced by the workflow but missing from the remote commit (clean checkout would fail)');
+  }
+  const lock = deps.git(['cat-file', '-e', `${ctx.sha}:yarn.lock`]);
+  if (fs.existsSync(path.join(root, 'package.json'))) add('tracked:yarn.lock', lock.code === 0, 'yarn.lock missing from remote commit (frozen-lockfile install fails)');
+  let scripts = {};
+  try { scripts = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
+  const hasPkg = fs.existsSync(path.join(root, 'package.json'));
+  if (!hasPkg) add('local-checks', true, 'SKIPPED: no package.json at the project root, docs/registry checks not run');
+  if (hasPkg && scripts['docs:render:check']) { const r = deps.run('yarn', ['docs:render:check']); add('docs:render:check', r.code === 0, r.code === 0 ? '' : (r.stdout + r.stderr).trim().split('\n').slice(-8).join('\n')); }
+  if (hasPkg && fs.existsSync(path.join(root, 'tests/consistency/docRegistry.test.js'))) {
+    const r = deps.run('yarn', ['vitest', 'run', 'tests/consistency/docRegistry.test.js']);
+    add('registry:docRegistry', r.code === 0, r.code === 0 ? '' : (r.stdout + r.stderr).trim().split('\n').slice(-8).join('\n'));
+  }
+  return { ok: results.every((r) => r.ok), results };
+}
+
+// ---------------------------------------------------------------- run discovery + dispatch
+const CLOCK_SKEW_MS = 5 * 60 * 1000;
+const RUN_FIELDS = 'databaseId,headSha,createdAt,status,url';
+// Run created by THIS dispatch: a dispatch-event run that was not in the pre-dispatch snapshot. Identity
+// comes from the snapshot, not the local clock (GitHub/local clock skew must not lose the run).
+async function discoverRun({ deps, workflow, ref, knownRunIds, policy }) {
+  for (let i = 0; i < policy.discoverAttempts; i += 1) {
+    const r = ghJson(deps, ['run', 'list', '--workflow', workflow, '--branch', ref, '--event', 'workflow_dispatch', '--limit', '10', '--json', RUN_FIELDS]);
+    if (r.ok) {
+      const fresh = r.data.filter((x) => !knownRunIds.includes(x.databaseId));
+      if (fresh.length) return fresh.sort((a, b) => b.databaseId - a.databaseId)[0];
+    }
+    if (i < policy.discoverAttempts - 1) await deps.sleep(policy.discoverDelayMs);
+  }
+  return null;
+}
+// Resume path (no snapshot): same ref + the SHA recorded at dispatch + created after the dispatch (skew-tolerant).
+// Ambiguous (more than one candidate) => no guess.
+function findRunForRecord(deps, rec, workflow) {
+  const r = ghJson(deps, ['run', 'list', '--workflow', workflow, '--branch', rec.ref, '--event', 'workflow_dispatch', '--limit', '20', '--json', RUN_FIELDS]);
+  if (!r.ok) return null;
+  const since = Date.parse(rec.dispatchedAt || rec.startedAt) - CLOCK_SKEW_MS;
+  const cands = r.data.filter((x) => x.headSha === rec.sha && Date.parse(x.createdAt) >= since);
+  return cands.length === 1 ? cands[0] : null;
+}
+
+export async function runCheck({ root, args, deps = defaultDeps(root) }) {
+  const { policy, error: policyError } = loadPolicy(root);
+  const pre = precheck({ root, deps, args, policy, policyError });
+  const out = { mode: args.dryRun ? 'dry-run' : 'run', ref: pre.ref, sha: pre.sha, workflow: pre.workflow, repo: pre.repo, private: pre.private, checks: pre.checks, warnings: pre.warnings, blockers: [...pre.blockers], estimate: pre.estimate || null, preflight: null, dispatched: false };
+  if (!args.dryRun && !args.explicit) out.blockers.push('dispatch requires the explicit /ukit:ci-check invocation (--explicit)');
+  if (out.blockers.length) return { ...out, ok: false, outcome: 'BLOCKED' };
+
+  out.preflight = localPreflight({ root, deps, ctx: pre });
+  if (!out.preflight.ok) {
+    out.blockers.push(...out.preflight.results.filter((r) => !r.ok).map((r) => `preflight ${r.name}: ${r.detail}`));
+    return { ...out, ok: false, outcome: 'PREFLIGHT_FAILED' };
+  }
+  if (args.dryRun) return { ...out, ok: true, outcome: 'DRY_RUN' };
+
+  const release = acquireLock(root, policy, deps.now);
+  if (!release) return { ...out, blockers: [...out.blockers, 'another /ukit:ci-check invocation holds the dispatch lock'], ok: false, outcome: 'BLOCKED' };
+  try {
+    // Re-read state under the lock so a concurrent invocation cannot slip through.
+    let fresh;
+    try { fresh = readState(root); } catch (e) { return { ...out, blockers: [...out.blockers, `state-file: ${e.message}`], ok: false, outcome: 'BLOCKED' }; }
+    const dup = fresh.invocations.find((r) => r.workflow === pre.workflow && r.sha === pre.sha && ['dispatching', 'dispatched'].includes(r.status) && !r.concluded
+      && (r.runId || deps.now() - Date.parse(r.dispatchedAt || r.startedAt) <= (r.status === 'dispatching' ? policy.lockStaleMs : policy.staleInvocationMs)));
+    if (dup) return { ...out, blockers: [...out.blockers, `invocation ${dup.id} already ${dup.status}`], ok: false, outcome: 'BLOCKED' };
+
+    const id = `ci-${deps.now()}`;
+    const dispatchedAt = deps.now();
+    const state = fresh;
+    for (const r of state.invocations) if (!r.runId && !r.concluded && ['dispatching', 'dispatched'].includes(r.status)) { r.status = 'abandoned'; r.concluded = true; }
+    state.invocations.push({ id, workflow: pre.workflow, ref: pre.ref, sha: pre.sha, repo: pre.repo, status: 'dispatching', runId: null, url: null, startedAt: new Date(dispatchedAt).toISOString() });
+    writeState(root, state); // write-ahead: survives an interruption between dispatch and run-id capture
+
+    const d = deps.gh(['workflow', 'run', pre.workflow, '--ref', pre.ref]); // the ONE dispatch; never retried
+    if (d.code !== 0) {
+      updateRecord(root, id, { status: 'dispatch-failed', error: (d.stderr || d.stdout).trim(), concluded: true });
+      return { ...out, ok: false, outcome: 'DISPATCH_FAILED', error: (d.stderr || d.stdout).trim(), invocationId: id };
+    }
+    updateRecord(root, id, { status: 'dispatched', dispatchedAt: new Date(dispatchedAt).toISOString() });
+    const run = await discoverRun({ deps, workflow: pre.workflow, ref: pre.ref, knownRunIds: pre.knownRunIds || [], policy });
+    if (run) updateRecord(root, id, { runId: run.databaseId, url: run.url, runSha: run.headSha });
+    if (run && run.headSha !== pre.sha) out.warnings.push(`run ${run.databaseId} tests ${String(run.headSha).slice(0, 8)}, not the validated ${String(pre.sha).slice(0, 8)} (branch moved during dispatch)`);
+    return { ...out, dispatched: true, ok: true, outcome: run ? 'DISPATCHED' : 'DISPATCHED_RUN_ID_PENDING', invocationId: id, runId: run?.databaseId ?? null, url: run?.url ?? null };
+  } finally { release(); }
+}
+
+// ---------------------------------------------------------------- status / report
+const STAGES = [
+  ['checkout', /checkout/i],
+  ['pythonNodeSetup', /setup-(node|python)|toolchain versions/i],
+  ['homeIsolation', /native gates/i],
+  ['documentationRegistry', /documentation registry/i],
+  ['hooks', /native gates/i],
+  ['artifactChecks', /artifact checks/i],
+  ['npmPack', /npm pack dry-run/i],
+  ['userLayerSafety', /user layer/i],
+];
+const rank = { failure: 4, timed_out: 4, cancelled: 3, skipped: 1, success: 0 };
+
+const osOf = (jobName) => {
+  const fam = (jobName.match(/^(ubuntu|windows|macos)/i) || [])[1]?.toLowerCase();
+  return fam ? { family: fam, label: OS_LABEL[fam] } : null;
+};
+const stripAnsi = (s) => s.replace(/\u001b\[[0-9;]*m/g, '');
+
+// The workflow runs vitest several times per job: sum EVERY "Tests ..." summary, never just the first.
+export function parseTestCounts(log) {
+  const all = [...stripAnsi(log).matchAll(/^\S*\s*Tests\s+([^\n(]*?)\s*\((\d+)\)/gm)];
+  if (!all.length) return null;
+  const n = (m, k) => Number((m[1].match(new RegExp(`(\\d+)\\s+${k}`)) || [0, 0])[1]);
+  return all.reduce((t, m) => ({ passed: t.passed + n(m, 'passed'), failed: t.failed + n(m, 'failed'), skipped: t.skipped + n(m, 'skipped'), total: t.total + Number(m[2]) }), { passed: 0, failed: 0, skipped: 0, total: 0 });
+}
+export function skippedTestNames(log) {
+  return [...stripAnsi(log).matchAll(/(?:↓|SKIPPED|skipped)[:\s]+(.+)/g)].map((m) => m[1].trim()).filter((s) => s.length < 200).slice(0, 20);
+}
+export function failureEvidence(log) {
+  return stripAnsi(log).split('\n').map((l) => l.replace(/^.*?\d{4}-\d\d-\d\dT[\d:.]+Z\s?/, '').trim())
+    .filter((l) => /(FAIL|AssertionError|Error:|ENOENT|✗|×|exit code|not found)/.test(l)).slice(0, 12);
+}
+
+export function buildReport(run, logs = {}) {
+  const expected = ['WINDOWS', 'MACOS', 'LINUX'];
+  const platforms = {};
+  for (const label of expected) platforms[label] = { present: false };
+  const failingStages = [];
+  for (const job of run.jobs || []) {
+    const os = osOf(job.name);
+    if (!os) continue;
+    const log = logs[job.databaseId] || '';
+    const stages = {};
+    for (const [stage, re] of STAGES) {
+      const steps = (job.steps || []).filter((s) => re.test(s.name));
+      if (!steps.length) { stages[stage] = 'N/A'; continue; }
+      const worst = steps.map((s) => (s.status !== 'completed' ? 'pending' : s.conclusion || 'unknown'))
+        .sort((a, b) => (rank[b] ?? 2) - (rank[a] ?? 2))[0];
+      stages[stage] = worst === 'success' ? 'PASS' : worst === 'skipped' ? 'SKIP' : worst === 'pending' ? 'PENDING' : 'FAIL';
+    }
+    const failed = (job.steps || []).filter((s) => ['failure', 'timed_out'].includes(s.conclusion)).map((s) => s.name);
+    const secs = job.startedAt && job.completedAt ? Math.max(0, Math.round((Date.parse(job.completedAt) - Date.parse(job.startedAt)) / 1000)) : null;
+    // PASS needs evidence of every required stage: a green job that lacks a stage (renamed/removed step, stub) is not a pass.
+    const missingStages = Object.entries(stages).filter(([, v]) => v === 'N/A').map(([k]) => k);
+    const verdict = job.status !== 'completed' ? 'INCOMPLETE'
+      : job.conclusion === 'success' ? (missingStages.length || Object.values(stages).some((v) => v !== 'PASS') ? 'INCOMPLETE' : 'PASS')
+        : ['failure', 'timed_out'].includes(job.conclusion) ? 'FAIL' : 'INCOMPLETE';
+    platforms[os.label] = {
+      present: true, job: job.name, verdict, conclusion: job.conclusion || null, url: job.url || null, durationSeconds: secs,
+      billedMinutes: secs == null ? null : Math.ceil(secs / 60) * MINUTE_MULTIPLIER[os.family],
+      stages, missingStages, failedSteps: failed, tests: parseTestCounts(log), skippedTests: skippedTestNames(log),
+      evidence: verdict === 'FAIL' ? failureEvidence(log) : [],
+    };
+    for (const s of failed) failingStages.push(`${os.label}: ${s}`);
+  }
+  const vs = expected.map((l) => (platforms[l].present ? platforms[l].verdict : 'INCOMPLETE'));
+  const verdict = run.status !== 'completed' ? 'INCOMPLETE' : vs.includes('FAIL') ? 'FAIL' : vs.every((v) => v === 'PASS') ? 'PASS' : 'INCOMPLETE';
+  const sum = (k) => expected.reduce((n, l) => n + (platforms[l].tests?.[k] || 0), 0);
+  return {
+    verdict, runId: run.databaseId, sha: run.headSha, url: run.url, status: run.status, conclusion: run.conclusion || null,
+    platforms, failingStages,
+    totals: { total: sum('total'), passed: sum('passed'), failed: sum('failed'), skipped: sum('skipped') },
+    billedMinutes: expected.reduce((n, l) => n + (platforms[l].billedMinutes || 0), 0),
+  };
+}
+
+export async function statusCheck({ root, args, deps = defaultDeps(root) }) {
+  const { policy } = loadPolicy(root);
+  let state;
+  try { state = readState(root); } catch (e) { return { mode: 'status', dispatched: false, ok: false, outcome: 'BLOCKED', blockers: [`state-file: ${e.message}`] }; }
+  let rec = args.runId ? state.invocations.find((r) => String(r.runId) === args.runId) : [...state.invocations].reverse().find((r) => r.status !== 'dispatch-failed');
+  let runId = args.runId || rec?.runId || null;
+  const workflow = args.workflow || rec?.workflow || policy.workflow;
+  if (!runId && rec && ['dispatched', 'dispatching'].includes(rec.status)) { // interrupted before run-id capture: read-only discovery
+    const found = findRunForRecord(deps, rec, workflow);
+    if (found) { runId = found.databaseId; updateRecord(root, rec.id, { runId, url: found.url, runSha: found.headSha }); }
+  }
+  if (!runId) {
+    const list = ghJson(deps, ['run', 'list', '--workflow', workflow, '--limit', '5', '--json', 'databaseId,status,conclusion,headSha,headBranch,event,url']);
+    return { mode: 'status', dispatched: false, ok: list.ok, outcome: list.ok ? 'NO_TRACKED_RUN' : 'GH_ERROR', recentRuns: list.ok ? list.data : [], error: list.ok ? null : list.error };
+  }
+  // One call must fit inside a single tool call (Bash tool caps at 10 min): bounded per-call wait, resumable by re-running status.
+  const deadline = deps.now() + Math.min(args.maxWaitMs ?? policy.maxWaitPerCallMs, policy.waitTimeoutMs);
+  let readErrors = 0;
+  for (;;) {
+    const v = ghJson(deps, ['run', 'view', String(runId), '--json', 'databaseId,status,conclusion,headSha,url,jobs']);
+    if (!v.ok) {
+      readErrors += 1; // read-only poll: transient API errors are tolerated; dispatch is never retried
+      if (readErrors > policy.pollErrorTolerance || !args.wait) return { mode: 'status', dispatched: false, ok: false, outcome: 'GH_ERROR', runId, error: v.error };
+      await deps.sleep(policy.waitIntervalMs);
+      continue;
+    }
+    readErrors = 0;
+    if (v.data.status === 'completed' || !args.wait || deps.now() >= deadline) {
+      const logs = {};
+      if (v.data.status === 'completed') {
+        for (const job of v.data.jobs || []) {
+          const l = deps.gh(['run', 'view', String(runId), '--log', '--job', String(job.databaseId)]);
+          if (l.code === 0) logs[job.databaseId] = l.stdout;
+        }
+      }
+      const report = buildReport(v.data, logs);
+      if (rec && v.data.status === 'completed') updateRecord(root, rec.id, { status: 'completed', concluded: true, conclusion: v.data.conclusion });
+      return { mode: 'status', dispatched: false, ok: true, outcome: report.verdict, runId, report, timedOutWaiting: v.data.status !== 'completed' && args.wait };
+    }
+    await deps.sleep(policy.waitIntervalMs);
+  }
+}
+
+// ---------------------------------------------------------------- rendering + CLI
+export function renderReport(result) {
+  const L = [];
+  if (result.report) {
+    const r = result.report;
+    L.push(`CROSS_PLATFORM_CI: ${r.verdict}`, '');
+    for (const label of ['WINDOWS', 'MACOS', 'LINUX']) {
+      const p = r.platforms[label];
+      if (!p.present) { L.push(`${label}: INCOMPLETE (no job reported)`); continue; }
+      const t = p.tests ? `${p.tests.passed} pass / ${p.tests.failed} fail / ${p.tests.skipped} skip` : 'tests n/a';
+      L.push(`${label}: ${p.verdict} | ${t} | ${p.durationSeconds ?? '?'}s | ${p.url || ''}`);
+      L.push(`  stages: ${Object.entries(p.stages).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+      for (const e of p.evidence) L.push(`  evidence: ${e}`);
+    }
+    L.push('', `Tests total ${r.totals.total}: ${r.totals.passed} passed, ${r.totals.failed} failed, ${r.totals.skipped} skipped`);
+    L.push(`Failing stages: ${r.failingStages.join('; ') || 'none'}`);
+    L.push(`Runner usage (billed-minute equivalent): ${r.billedMinutes} min`, `Run: ${r.runId} @ ${String(r.sha).slice(0, 8)} ${r.url}`);
+    return L.join('\n');
+  }
+  L.push(`ci-check ${result.mode}: ${result.outcome}`);
+  if (result.ref) L.push(`ref=${result.ref} sha=${String(result.sha || '').slice(0, 8)} workflow=${result.workflow}`);
+  for (const b of result.blockers || []) L.push(`BLOCKER: ${b}`);
+  for (const w of result.warnings || []) L.push(`warning: ${w}`);
+  if (result.estimate) L.push(`ESTIMATED (not verified billing; no free-quota guarantee): ${result.estimate.jobs} jobs, worst case ${result.estimate.worstCaseBilledMinutes} billed min (${JSON.stringify(result.estimate.perRunner)})`);
+  if (result.runId) L.push(`run: ${result.runId} ${result.url || ''}`);
+  if (result.outcome === 'DISPATCHED_RUN_ID_PENDING') L.push('dispatched; run id not yet visible. Use `/ukit:ci-check status` (it will NOT dispatch again).');
+  if (result.error) L.push(`error: ${result.error}`);
+  return L.join('\n');
+}
+
+export async function main(argv = process.argv.slice(2), root = process.cwd()) {
+  const args = parseArgs(argv);
+  if (args.errors.length) { process.stderr.write(`${args.errors.join('\n')}\n`); return 2; }
+  const result = args.mode === 'status' ? await statusCheck({ root, args }) : await runCheck({ root, args });
+  process.stdout.write(`${args.json ? JSON.stringify(result, null, 2) : renderReport(result)}\n`);
+  if (['BLOCKED', 'PREFLIGHT_FAILED', 'DISPATCH_FAILED', 'GH_ERROR'].includes(result.outcome)) return 2;
+  if (['FAIL', 'INCOMPLETE'].includes(result.outcome)) return 3;
+  return 0;
+}
+
+const isEntry = () => {
+  try { return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+};
+if (process.argv[1] && isEntry()) {
+  main().then((c) => { process.exitCode = c; }, (e) => { process.stderr.write(`${e.stack || e}\n`); process.exitCode = 1; });
+}