@ornexus/neocortex 4.60.72 → 4.60.73

package/packages/client/dist/commands/mutation-qa-run.js

@@ -1,3 +1,219 @@
-import{spawnSync as E}from"node:child_process";import{createHash as q}from"node:crypto";import{existsSync as p,lstatSync as k,mkdirSync as G,mkdtempSync as V,readFileSync as Y,realpathSync as l,rmSync as J,writeFileSync as K}from"node:fs";import{homedir as Z,tmpdir as ee}from"node:os";import{isAbsolute as M,join as u,relative as F,resolve as C,sep as B}from"node:path";import{mutationQaGit as f}from"./mutation-qa-git.js";import{planMutationQa as I}from"./mutation-qa.js";import{evaluateMutationQaReport as te}from"./mutation-qa-verdict.js";const re="reports/mutation/mutation.json",oe=8*1024*1024,ne=1800*1e3,ie=300*1e3;function x(n,t){const a=F(n,t);return a!==".."&&!a.startsWith(`..${B}`)&&!M(a)}function $(n){const t=u(n,re);if(!p(t))return null;const a=l(t);if(a!==t||!x(n,a))throw new Error("mutation-qa-report-path-unsafe");const r=k(t);if(!r.isFile()||r.size===0||r.size>oe)throw new Error("mutation-qa-report-size-invalid");return Y(t)}function se(n,t){const a=f(n,["rev-parse","--verify","HEAD"]).toString("utf8").trim(),r=t.baseRef.startsWith("sha:")?t.baseSha:t.baseRef,i=f(n,["rev-parse","--verify","--end-of-options",`${r}^{commit}`]).toString("utf8").trim();if(a!==t.headSha||i!==t.baseSha)throw new Error("mutation-qa-physical-drift");if(f(n,["status","--porcelain=v1","-z","--untracked-files=all"]).toString("utf8").split("\0").filter(Boolean).some(o=>!o.startsWith("?? ")||!(o.slice(3).startsWith("node_modules/")||o.slice(3).startsWith("reports/mutation/")||o.slice(3).startsWith(".stryker-tmp/"))))throw new Error("mutation-qa-checkout-drift");for(const o of t.eligibleFiles){const e=C(n,o.path);if(!x(n,e)||l(e)!==e||!k(e).isFile()||f(n,["hash-object","--",o.path]).toString("utf8").trim()!==o.blobSha)throw new Error("mutation-qa-source-drift")}}function N(n){for(const t of(process.env.PATH??"").split(":")){if(!M(t))continue;const a=u(t,n);if(p(a)){try{const r=l(a);if((r.startsWith("/usr/")||r.startsWith("/home/linuxbrew/.linuxbrew/"))&&k(r).isFile()&&(n!=="npm"||r.endsWith(".js")))return r}catch{}return null}}return null}function Q(n,t,a,r,i){const s=l(process.execPath),o="/home/linuxbrew/.linuxbrew";if(!s.startsWith("/usr/")&&!s.startsWith(`${o}/`))return null;const e=["--die-with-parent","--unshare-net","--unshare-pid","--new-session","--ro-bind","/usr","/usr"];for(const c of["/bin","/lib","/lib64"])p(c)&&e.push("--ro-bind",c,c);if(s.startsWith(`${o}/`)){if(!p(o))return null;e.push("--dir","/home","--dir","/home/linuxbrew","--ro-bind",o,o)}else e.push("--dir","/home");e.push("--bind",t,"/home/worker"),i&&e.push("--dir","/npm-cache","--overlay-src",i,"--tmp-overlay","/npm-cache"),e.push("--dir","/etc","--ro-bind",a,"/etc/hosts","--proc","/proc","--dev","/dev","--tmpfs","/tmp","--dir","/work","--bind",n,"/work","--chdir","/work","--clearenv");for(const[c,m]of Object.entries(r))e.push("--setenv",c,m);return e}function de(n,t,a){if(!/^[a-f0-9]{64}$/.test(a))throw new Error("mutation-qa-plan-digest-invalid");const r=C(n),i=I(r,t);if(i.planSha256!==a)throw new Error("mutation-qa-plan-drift");const s={schemaVersion:1,kind:"mutation-qa-run",planSha256:i.planSha256,headSha:i.headSha,checkpointAccepted:!1,localOnly:!0,executionEnvironment:"os-sandbox-clone"};if(i.outcome==="skipped-no-files")return Object.freeze({...s,outcome:"skipped-no-files"});if(!p(u(r,"package-lock.json")))return Object.freeze({...s,outcome:"skipped-dependencies-unavailable"});const o=V(u(ee(),"mutation-qa-run-")),e=u(o,"checkout"),c=u(o,"home");G(c,{mode:448});const m=u(o,"hosts");K(m,`127.0.0.1 localhost
-::1 localhost
-`,{mode:384});const A={PATH:process.env.PATH??"/usr/bin:/bin",HOME:"/home/worker",TMPDIR:"/tmp",CI:"true",LANG:"C.UTF-8",NO_COLOR:"1",npm_config_offline:"true",npm_config_yes:"false",npm_config_ignore_scripts:"true",npm_config_audit:"false",npm_config_fund:"false",npm_config_userconfig:"/dev/null",npm_config_globalconfig:"/tmp/npm-global.npmrc"};try{f(r,["clone","--local","--no-hardlinks","--no-checkout",r,e]),f(e,["checkout","--detach",i.headSha]),i.baseRef.startsWith("sha:")||f(e,["update-ref",i.baseRef,i.baseSha]);const O=N("npm"),d=N("bwrap"),j=u(Z(),".npm");if(!O||!d||!p(j))return Object.freeze({...s,outcome:"skipped-host-isolation-unavailable"});const v=Q(e,c,m,A),R=Q(e,c,m,{...A,npm_config_cache:"/npm-cache",npm_config_logs_dir:"/tmp/npm-logs"},l(j));if(!v||!R)return Object.freeze({...s,outcome:"skipped-host-isolation-unavailable"});const w=l(process.execPath),g=E(d,[...v,"--",w,"-e","process.exit(0)"],{cwd:e,timeout:1e4,maxBuffer:4096,stdio:["ignore","pipe","pipe"],env:{PATH:process.env.PATH??"/usr/bin:/bin"}});if(g.error||g.signal||g.status!==0)return Object.freeze({...s,outcome:"skipped-host-isolation-unavailable"});const y=E(d,[...R,"--",w,O,"ci","--offline","--ignore-scripts","--no-audit","--no-fund"],{cwd:e,timeout:ie,maxBuffer:2*1024*1024,stdio:["ignore","pipe","pipe"],env:{PATH:process.env.PATH??"/usr/bin:/bin"}});if(y.error||y.signal||y.status!==0)return Object.freeze({...s,outcome:"skipped-dependencies-unavailable"});const P=u(e,"node_modules/.bin/stryker");if(!p(P))return Object.freeze({...s,outcome:"skipped-stryker-missing"});const S=l(P);if(!x(e,S)||!k(S).isFile())throw new Error("mutation-qa-stryker-path-unsafe");const D=`/work/${F(e,S).split(B).join("/")}`,T=$(e),L=T?q("sha256").update(T).digest("hex"):null,U=process.umask(63);let h=null,z=!1,H=!1;try{const b=E(d,[...v,"--",w,D,"run","--mutate",i.eligibleFiles.map(X=>X.path).join(","),"--reporters","json","--timeoutMS","600000","--concurrency","4","--coverageAnalysis","off"],{cwd:e,timeout:ne,maxBuffer:2097152,stdio:["ignore","pipe","pipe"],env:{PATH:process.env.PATH??"/usr/bin:/bin"}});h=b.status,z=!!b.error||!!b.signal,H=b.error?.code==="ENOENT"}finally{process.umask(U)}if(se(e,i),I(r,t).planSha256!==i.planSha256)throw new Error("mutation-qa-physical-drift");if(H)return Object.freeze({...s,outcome:"skipped-host-isolation-unavailable"});if(z||h!==0&&h!==1)return Object.freeze({...s,outcome:"skipped-stryker-error"});const _=$(e);if(!_||q("sha256").update(_).digest("hex")===L){if(h===1)return Object.freeze({...s,outcome:"skipped-stryker-error"});throw new Error("mutation-qa-report-stale")}const W=te(i,_);return h===1&&!W.runnerBreakCrossed?Object.freeze({...s,outcome:"skipped-stryker-error"}):Object.freeze({...s,outcome:"verified",verdict:W})}finally{J(o,{recursive:!0,force:!0})}}export{de as runMutationQa};
+/** Root-owned Stryker execution. Runs project code only after explicit local authorization. */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { mutationQaGit } from './mutation-qa-git.js';
+import { planMutationQa } from './mutation-qa.js';
+import { evaluateMutationQaReport } from './mutation-qa-verdict.js';
+const REPORT_RELATIVE_PATH = 'reports/mutation/mutation.json';
+const MAX_REPORT_BYTES = 8 * 1024 * 1024;
+const MAX_PROCESS_MS = 30 * 60 * 1000;
+const MAX_PREPARE_MS = 5 * 60 * 1000;
+function ensureInside(root, path) {
+    const rel = relative(root, path);
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+function readSafeReport(root) {
+    const path = join(root, REPORT_RELATIVE_PATH);
+    if (!existsSync(path))
+        return null;
+    const real = realpathSync(path);
+    if (real !== path || !ensureInside(root, real))
+        throw new Error('mutation-qa-report-path-unsafe');
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size === 0 || stat.size > MAX_REPORT_BYTES) {
+        throw new Error('mutation-qa-report-size-invalid');
+    }
+    return readFileSync(path);
+}
+function assertPhysicalAfterRun(root, plan) {
+    const head = mutationQaGit(root, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim();
+    const baseRevision = plan.baseRef.startsWith('sha:') ? plan.baseSha : plan.baseRef;
+    const base = mutationQaGit(root, ['rev-parse', '--verify', '--end-of-options', `${baseRevision}^{commit}`])
+        .toString('utf8').trim();
+    if (head !== plan.headSha || base !== plan.baseSha)
+        throw new Error('mutation-qa-physical-drift');
+    const entries = mutationQaGit(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all'])
+        .toString('utf8').split('\0').filter(Boolean);
+    if (entries.some((entry) => !entry.startsWith('?? ')
+        || !(entry.slice(3).startsWith('node_modules/')
+            || entry.slice(3).startsWith('reports/mutation/')
+            || entry.slice(3).startsWith('.stryker-tmp/')))) {
+        throw new Error('mutation-qa-checkout-drift');
+    }
+    for (const file of plan.eligibleFiles) {
+        const path = resolve(root, file.path);
+        if (!ensureInside(root, path) || realpathSync(path) !== path || !lstatSync(path).isFile()
+            || mutationQaGit(root, ['hash-object', '--', file.path]).toString('utf8').trim() !== file.blobSha) {
+            throw new Error('mutation-qa-source-drift');
+        }
+    }
+}
+function trustedTool(name) {
+    for (const directory of (process.env.PATH ?? '').split(':')) {
+        if (!isAbsolute(directory))
+            continue;
+        const candidate = join(directory, name);
+        if (!existsSync(candidate))
+            continue;
+        try {
+            const tool = realpathSync(candidate);
+            if ((tool.startsWith('/usr/') || tool.startsWith('/home/linuxbrew/.linuxbrew/'))
+                && lstatSync(tool).isFile() && (name !== 'npm' || tool.endsWith('.js')))
+                return tool;
+        }
+        catch { /* The first matching tool on PATH is not trusted. */ }
+        return null;
+    }
+    return null;
+}
+function sandboxArgs(sandbox, privateHome, hostsPath, sourceEnv, cachePath) {
+    const executable = realpathSync(process.execPath);
+    const brewRoot = '/home/linuxbrew/.linuxbrew';
+    if (!executable.startsWith('/usr/') && !executable.startsWith(`${brewRoot}/`))
+        return null;
+    const args = ['--die-with-parent', '--unshare-net', '--unshare-pid', '--new-session',
+        '--ro-bind', '/usr', '/usr'];
+    for (const path of ['/bin', '/lib', '/lib64']) {
+        if (existsSync(path))
+            args.push('--ro-bind', path, path);
+    }
+    if (executable.startsWith(`${brewRoot}/`)) {
+        if (!existsSync(brewRoot))
+            return null;
+        args.push('--dir', '/home', '--dir', '/home/linuxbrew', '--ro-bind', brewRoot, brewRoot);
+    }
+    else {
+        args.push('--dir', '/home');
+    }
+    args.push('--bind', privateHome, '/home/worker');
+    if (cachePath)
+        args.push('--dir', '/npm-cache', '--overlay-src', cachePath, '--tmp-overlay', '/npm-cache');
+    args.push('--dir', '/etc', '--ro-bind', hostsPath, '/etc/hosts', '--proc', '/proc', '--dev', '/dev', '--tmpfs', '/tmp', '--dir', '/work', '--bind', sandbox, '/work', '--chdir', '/work', '--clearenv');
+    for (const [key, value] of Object.entries(sourceEnv)) {
+        args.push('--setenv', key, value);
+    }
+    return args;
+}
+/** Installs only from the local npm cache in a disposable clone; never mutates the source checkout. */
+export function runMutationQa(projectRoot, baseRef, expectedPlanSha256) {
+    if (!/^[a-f0-9]{64}$/.test(expectedPlanSha256))
+        throw new Error('mutation-qa-plan-digest-invalid');
+    const root = resolve(projectRoot);
+    const plan = planMutationQa(root, baseRef);
+    if (plan.planSha256 !== expectedPlanSha256)
+        throw new Error('mutation-qa-plan-drift');
+    const base = { schemaVersion: 1, kind: 'mutation-qa-run',
+        planSha256: plan.planSha256, headSha: plan.headSha,
+        checkpointAccepted: false, localOnly: true,
+        executionEnvironment: 'os-sandbox-clone' };
+    if (plan.outcome === 'skipped-no-files')
+        return Object.freeze({ ...base, outcome: 'skipped-no-files' });
+    if (!existsSync(join(root, 'package-lock.json'))) {
+        return Object.freeze({ ...base, outcome: 'skipped-dependencies-unavailable' });
+    }
+    const tempRoot = mkdtempSync(join(tmpdir(), 'mutation-qa-run-'));
+    const sandbox = join(tempRoot, 'checkout');
+    const privateHome = join(tempRoot, 'home');
+    mkdirSync(privateHome, { mode: 0o700 });
+    const hostsPath = join(tempRoot, 'hosts');
+    writeFileSync(hostsPath, '127.0.0.1 localhost\n::1 localhost\n', { mode: 0o600 });
+    const environment = { PATH: process.env.PATH ?? '/usr/bin:/bin', HOME: '/home/worker',
+        TMPDIR: '/tmp', CI: 'true', LANG: 'C.UTF-8', NO_COLOR: '1',
+        npm_config_offline: 'true', npm_config_yes: 'false', npm_config_ignore_scripts: 'true',
+        npm_config_audit: 'false', npm_config_fund: 'false',
+        npm_config_userconfig: '/dev/null', npm_config_globalconfig: '/tmp/npm-global.npmrc' };
+    try {
+        mutationQaGit(root, ['clone', '--local', '--no-hardlinks', '--no-checkout', root, sandbox]);
+        mutationQaGit(sandbox, ['checkout', '--detach', plan.headSha]);
+        if (!plan.baseRef.startsWith('sha:')) {
+            mutationQaGit(sandbox, ['update-ref', plan.baseRef, plan.baseSha]);
+        }
+        const npmCli = trustedTool('npm');
+        const bwrap = trustedTool('bwrap');
+        const npmCache = join(homedir(), '.npm');
+        if (!npmCli || !bwrap || !existsSync(npmCache)) {
+            return Object.freeze({ ...base, outcome: 'skipped-host-isolation-unavailable' });
+        }
+        const confined = sandboxArgs(sandbox, privateHome, hostsPath, environment);
+        const installConfined = sandboxArgs(sandbox, privateHome, hostsPath, {
+            ...environment, npm_config_cache: '/npm-cache', npm_config_logs_dir: '/tmp/npm-logs',
+        }, realpathSync(npmCache));
+        if (!confined || !installConfined) {
+            return Object.freeze({ ...base, outcome: 'skipped-host-isolation-unavailable' });
+        }
+        const executable = realpathSync(process.execPath);
+        const sandboxProbe = spawnSync(bwrap, [...confined, '--', executable, '-e', 'process.exit(0)'], {
+            cwd: sandbox, timeout: 10_000, maxBuffer: 4096,
+            stdio: ['ignore', 'pipe', 'pipe'], env: { PATH: process.env.PATH ?? '/usr/bin:/bin' },
+        });
+        if (sandboxProbe.error || sandboxProbe.signal || sandboxProbe.status !== 0) {
+            return Object.freeze({ ...base, outcome: 'skipped-host-isolation-unavailable' });
+        }
+        const install = spawnSync(bwrap, [...installConfined, '--', executable, npmCli,
+            'ci', '--offline', '--ignore-scripts', '--no-audit', '--no-fund'], {
+            cwd: sandbox, timeout: MAX_PREPARE_MS, maxBuffer: 2 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'], env: { PATH: process.env.PATH ?? '/usr/bin:/bin' },
+        });
+        if (install.error || install.signal || install.status !== 0) {
+            return Object.freeze({ ...base, outcome: 'skipped-dependencies-unavailable' });
+        }
+        const binary = join(sandbox, 'node_modules/.bin/stryker');
+        if (!existsSync(binary))
+            return Object.freeze({ ...base, outcome: 'skipped-stryker-missing' });
+        const realBinary = realpathSync(binary);
+        if (!ensureInside(sandbox, realBinary) || !lstatSync(realBinary).isFile()) {
+            throw new Error('mutation-qa-stryker-path-unsafe');
+        }
+        const binaryInside = `/work/${relative(sandbox, realBinary).split(sep).join('/')}`;
+        const priorReport = readSafeReport(sandbox);
+        const priorDigest = priorReport ? createHash('sha256').update(priorReport).digest('hex') : null;
+        const previousUmask = process.umask(0o077);
+        let exitStatus = null;
+        let processError = false;
+        let hostIsolationUnavailable = false;
+        try {
+            const result = spawnSync(bwrap, [...confined, '--', executable, binaryInside, 'run', '--mutate',
+                plan.eligibleFiles.map((file) => file.path).join(','), '--reporters', 'json',
+                '--timeoutMS', '600000', '--concurrency', '4', '--coverageAnalysis', 'off'], {
+                cwd: sandbox, timeout: MAX_PROCESS_MS, maxBuffer: 2 * 1024 * 1024,
+                stdio: ['ignore', 'pipe', 'pipe'], env: { PATH: process.env.PATH ?? '/usr/bin:/bin' },
+            });
+            exitStatus = result.status;
+            processError = !!result.error || !!result.signal;
+            hostIsolationUnavailable = result.error?.code === 'ENOENT';
+        }
+        finally {
+            process.umask(previousUmask);
+        }
+        assertPhysicalAfterRun(sandbox, plan);
+        if (planMutationQa(root, baseRef).planSha256 !== plan.planSha256) {
+            throw new Error('mutation-qa-physical-drift');
+        }
+        if (hostIsolationUnavailable) {
+            return Object.freeze({ ...base, outcome: 'skipped-host-isolation-unavailable' });
+        }
+        if (processError || (exitStatus !== 0 && exitStatus !== 1)) {
+            return Object.freeze({ ...base, outcome: 'skipped-stryker-error' });
+        }
+        const rawReport = readSafeReport(sandbox);
+        if (!rawReport || createHash('sha256').update(rawReport).digest('hex') === priorDigest) {
+            if (exitStatus === 1)
+                return Object.freeze({ ...base, outcome: 'skipped-stryker-error' });
+            throw new Error('mutation-qa-report-stale');
+        }
+        const verdict = evaluateMutationQaReport(plan, rawReport);
+        // StrykerJS may exit 1 only because its configured break threshold was
+        // crossed. Never infer that from an exit code alone: require a fresh,
+        // fully validated report whose own score proves that exact condition.
+        if (exitStatus === 1 && !verdict.runnerBreakCrossed) {
+            return Object.freeze({ ...base, outcome: 'skipped-stryker-error' });
+        }
+        return Object.freeze({ ...base, outcome: 'verified', verdict });
+    }
+    finally {
+        rmSync(tempRoot, { recursive: true, force: true });
+    }
+}

package/packages/client/dist/commands/mutation-qa-verdict.js

@@ -1 +1,149 @@
-import{createHash as F}from"node:crypto";function C(t,r,e,i){const o=t+r+e+i;return o===0?0:Math.round((t+i)/o*1e4)/100}function O(t,r){const e=Buffer.from(t,"utf8");return F(r).update(`blob ${e.byteLength}\0`).update(e).digest("hex")}function L(t,r){const e=t.match(/^src\/([^/]+)\//)?.[1];return e&&r.perAreaThreshold[e]!==void 0?r.perAreaThreshold[e]:e==="adapters"&&r.perAreaThreshold.infrastructure!==void 0?r.perAreaThreshold.infrastructure:r.defaultThreshold}function z(t,r){const e=t.policy.thresholds;if(t.outcome!=="ready"||t.eligibleFiles.length===0)throw new Error("mutation-qa-plan-not-ready");if(r.byteLength===0||r.byteLength>8*1024*1024)throw new Error("mutation-qa-report-size-invalid");if([e.defaultThreshold,e.blockThreshold,...Object.values(e.perAreaThreshold)].some(a=>!Number.isFinite(a)||a<0||a>100)||e.blockThreshold>e.defaultThreshold)throw new Error("mutation-qa-thresholds-invalid");let i;try{i=JSON.parse(r.toString("utf8"))}catch{throw new Error("mutation-qa-report-invalid")}if(!i||typeof i!="object"||Array.isArray(i))throw new Error("mutation-qa-report-invalid");const o=i;if(typeof o.schemaVersion!="string"||!/^[12](?:\.\d+){0,2}$/.test(o.schemaVersion)||!o.thresholds||typeof o.thresholds!="object"||Array.isArray(o.thresholds)||!o.files||typeof o.files!="object"||Array.isArray(o.files))throw new Error("mutation-qa-report-invalid");const u=o.thresholds,c=u.high,d=u.low,s=u.break===void 0||u.break===null?null:u.break;if(typeof c!="number"||!Number.isFinite(c)||c<0||c>100||typeof d!="number"||!Number.isFinite(d)||d<0||d>c||s!==null&&(typeof s!="number"||!Number.isFinite(s)||s<0||s>d))throw new Error("mutation-qa-report-invalid");const j=o.files,y=t.eligibleFiles.map(a=>a.path).sort(),N=Object.keys(j).sort();if(y.length!==N.length||y.some((a,n)=>a!==N[n]))throw new Error("mutation-qa-report-scope-mismatch");let f=0,p=0,b=0,m=0,w=0,g=0;for(const a of y){const n=j[a];if(!n||typeof n!="object"||Array.isArray(n)||typeof n.language!="string"||typeof n.source!="string"||!Array.isArray(n.mutants))throw new Error("mutation-qa-report-invalid");const A=t.eligibleFiles.find(l=>l.path===a)?.blobSha;if(!A||O(n.source,A.length===64?"sha256":"sha1")!==A)throw new Error("mutation-qa-report-source-mismatch");const T=n.mutants;if(T.length===0||T.length>1e5)throw new Error("mutation-qa-report-invalid");let k=0,E=0,q=0,S=0;for(const l of T){if(!l||typeof l!="object"||Array.isArray(l))throw new Error("mutation-qa-report-invalid");const h=l;if(typeof h.id!="string"||!h.id||typeof h.mutatorName!="string"||!h.mutatorName||!h.location||typeof h.location!="object"||Array.isArray(h.location))throw new Error("mutation-qa-report-invalid");switch(l.status){case"Killed":f++,k++;break;case"Survived":p++,E++;break;case"NoCoverage":b++,q++;break;case"Timeout":m++,S++;break;case"RuntimeError":case"CompileError":w++;break;case"Ignored":break;default:throw new Error("mutation-qa-report-status-unsupported")}}if(k+E+q+S===0)throw new Error("mutation-qa-report-no-scored-mutants");C(k,E,q,S)<L(a,e)&&g++}const v=C(f,p,b,m),x=s!==null&&(f+m)*100<s*(f+p+b+m),B=v<e.blockThreshold?"failed":v<e.defaultThreshold||g>0||w>0?"warned":"passed";return Object.freeze({schemaVersion:1,kind:"mutation-qa-verdict",planSha256:t.planSha256,reportSha256:F("sha256").update(r).digest("hex"),runnerBreakThreshold:s,runnerBreakCrossed:x,outcome:B,mutationScore:v,killed:f,survived:p,noCoverage:b,timeout:m,invalid:w,belowAreaThresholdCount:g,checkpointAccepted:!1,localOnly:!0})}export{z as evaluateMutationQaReport};
+/** Strict local-only Stryker report validation against one immutable source plan. */
+import { createHash } from 'node:crypto';
+function score(killed, survived, noCoverage, timeout) {
+    const valid = killed + survived + noCoverage + timeout;
+    return valid === 0 ? 0 : Math.round(((killed + timeout) / valid) * 10_000) / 100;
+}
+function gitBlobSha(source, objectFormat) {
+    const content = Buffer.from(source, 'utf8');
+    return createHash(objectFormat).update(`blob ${content.byteLength}\0`).update(content).digest('hex');
+}
+function areaThreshold(path, thresholds) {
+    const area = path.match(/^src\/([^/]+)\//)?.[1];
+    if (area && thresholds.perAreaThreshold[area] !== undefined)
+        return thresholds.perAreaThreshold[area];
+    if (area === 'adapters' && thresholds.perAreaThreshold.infrastructure !== undefined) {
+        return thresholds.perAreaThreshold.infrastructure;
+    }
+    return thresholds.defaultThreshold;
+}
+/** Reject partial/foreign reports; never project file names, source, mutants or test details. */
+export function evaluateMutationQaReport(plan, rawReport) {
+    const thresholds = plan.policy.thresholds;
+    if (plan.outcome !== 'ready' || plan.eligibleFiles.length === 0) {
+        throw new Error('mutation-qa-plan-not-ready');
+    }
+    if (rawReport.byteLength === 0 || rawReport.byteLength > 8 * 1024 * 1024) {
+        throw new Error('mutation-qa-report-size-invalid');
+    }
+    if ([thresholds.defaultThreshold, thresholds.blockThreshold,
+        ...Object.values(thresholds.perAreaThreshold)].some((value) => !Number.isFinite(value)
+        || value < 0 || value > 100)
+        || thresholds.blockThreshold > thresholds.defaultThreshold) {
+        throw new Error('mutation-qa-thresholds-invalid');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawReport.toString('utf8'));
+    }
+    catch {
+        throw new Error('mutation-qa-report-invalid');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('mutation-qa-report-invalid');
+    }
+    const record = parsed;
+    if (typeof record.schemaVersion !== 'string' || !/^[12](?:\.\d+){0,2}$/.test(record.schemaVersion)
+        || !record.thresholds || typeof record.thresholds !== 'object' || Array.isArray(record.thresholds)
+        || !record.files || typeof record.files !== 'object'
+        || Array.isArray(record.files))
+        throw new Error('mutation-qa-report-invalid');
+    const runnerThresholds = record.thresholds;
+    const runnerHigh = runnerThresholds.high;
+    const runnerLow = runnerThresholds.low;
+    const runnerBreakThreshold = runnerThresholds.break === undefined || runnerThresholds.break === null
+        ? null : runnerThresholds.break;
+    if (typeof runnerHigh !== 'number' || !Number.isFinite(runnerHigh)
+        || runnerHigh < 0 || runnerHigh > 100
+        || typeof runnerLow !== 'number' || !Number.isFinite(runnerLow)
+        || runnerLow < 0 || runnerLow > runnerHigh
+        || runnerBreakThreshold !== null && (typeof runnerBreakThreshold !== 'number'
+            || !Number.isFinite(runnerBreakThreshold) || runnerBreakThreshold < 0
+            || runnerBreakThreshold > runnerLow))
+        throw new Error('mutation-qa-report-invalid');
+    const files = record.files;
+    const expected = plan.eligibleFiles.map((file) => file.path).sort();
+    const actual = Object.keys(files).sort();
+    if (expected.length !== actual.length || expected.some((path, index) => path !== actual[index])) {
+        throw new Error('mutation-qa-report-scope-mismatch');
+    }
+    let killed = 0;
+    let survived = 0;
+    let noCoverage = 0;
+    let timeout = 0;
+    let invalid = 0;
+    let belowAreaThresholdCount = 0;
+    for (const path of expected) {
+        const file = files[path];
+        if (!file || typeof file !== 'object' || Array.isArray(file)
+            || typeof file.language !== 'string'
+            || typeof file.source !== 'string'
+            || !Array.isArray(file.mutants)) {
+            throw new Error('mutation-qa-report-invalid');
+        }
+        const expectedBlob = plan.eligibleFiles.find((entry) => entry.path === path)?.blobSha;
+        if (!expectedBlob || gitBlobSha(file.source, expectedBlob.length === 64 ? 'sha256' : 'sha1') !== expectedBlob) {
+            throw new Error('mutation-qa-report-source-mismatch');
+        }
+        const mutants = file.mutants;
+        if (mutants.length === 0 || mutants.length > 100_000)
+            throw new Error('mutation-qa-report-invalid');
+        let fileKilled = 0;
+        let fileSurvived = 0;
+        let fileNoCoverage = 0;
+        let fileTimeout = 0;
+        for (const mutant of mutants) {
+            if (!mutant || typeof mutant !== 'object' || Array.isArray(mutant)) {
+                throw new Error('mutation-qa-report-invalid');
+            }
+            const record = mutant;
+            if (typeof record.id !== 'string' || !record.id
+                || typeof record.mutatorName !== 'string' || !record.mutatorName
+                || !record.location || typeof record.location !== 'object' || Array.isArray(record.location)) {
+                throw new Error('mutation-qa-report-invalid');
+            }
+            switch (mutant.status) {
+                case 'Killed':
+                    killed++;
+                    fileKilled++;
+                    break;
+                case 'Survived':
+                    survived++;
+                    fileSurvived++;
+                    break;
+                case 'NoCoverage':
+                    noCoverage++;
+                    fileNoCoverage++;
+                    break;
+                case 'Timeout':
+                    timeout++;
+                    fileTimeout++;
+                    break;
+                case 'RuntimeError':
+                case 'CompileError':
+                    invalid++;
+                    break;
+                case 'Ignored': break;
+                default: throw new Error('mutation-qa-report-status-unsupported');
+            }
+        }
+        if (fileKilled + fileSurvived + fileNoCoverage + fileTimeout === 0) {
+            throw new Error('mutation-qa-report-no-scored-mutants');
+        }
+        if (score(fileKilled, fileSurvived, fileNoCoverage, fileTimeout) < areaThreshold(path, thresholds)) {
+            belowAreaThresholdCount++;
+        }
+    }
+    const mutationScore = score(killed, survived, noCoverage, timeout);
+    const runnerBreakCrossed = runnerBreakThreshold !== null
+        && (killed + timeout) * 100
+            < runnerBreakThreshold * (killed + survived + noCoverage + timeout);
+    const outcome = mutationScore < thresholds.blockThreshold ? 'failed'
+        : mutationScore < thresholds.defaultThreshold || belowAreaThresholdCount > 0 || invalid > 0
+            ? 'warned' : 'passed';
+    return Object.freeze({ schemaVersion: 1, kind: 'mutation-qa-verdict', planSha256: plan.planSha256,
+        reportSha256: createHash('sha256').update(rawReport).digest('hex'),
+        runnerBreakThreshold, runnerBreakCrossed,
+        outcome, mutationScore, killed, survived, noCoverage, timeout, invalid, belowAreaThresholdCount,
+        checkpointAccepted: false, localOnly: true });
+}

package/packages/client/dist/commands/mutation-qa.js

@@ -1 +1,220 @@
-import{createHash as q}from"node:crypto";import{lstatSync as y,realpathSync as $}from"node:fs";import{resolve as v}from"node:path";import{mutationQaGit as w}from"./mutation-qa-git.js";import{loadMutationQaPolicy as E,policyExcludesPath as S}from"./mutation-qa-policy.js";function p(o,n){return w(o,n).toString("utf8").trim()}function k(o){return o.length>0&&o.length<=240&&/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(o)&&!o.split("/").some(n=>n==="."||n==="..")&&/\.(?:ts|tsx|js|jsx)$/.test(o)&&!/\.d\.ts$|\.(?:test|spec)\.[jt]sx?$|(?:^|\/)__tests__\/|(?:^|\/)migrations\//.test(o)}function b(o){return/\.(?:ts|tsx|js|jsx)$/.test(o)&&!/\.d\.ts$|\.(?:test|spec)\.[jt]sx?$|(?:^|\/)__tests__\/|(?:^|\/)migrations\//.test(o)}function x(o,n){const f=/^sha:([a-f0-9]{40}|[a-f0-9]{64})$/.exec(n)?.[1],m=/^refs\/remotes\/[A-Za-z0-9][A-Za-z0-9_-]{0,63}\/[A-Za-z0-9][A-Za-z0-9/_-]{0,127}$/.test(n)&&!n.includes("..")&&!n.includes("//")&&!n.endsWith("/");if(!f&&!m)throw new Error("mutation-qa-base-ref-invalid");const e=v(o);try{if($(e)!==e||!y(e).isDirectory()||p(e,["rev-parse","--show-toplevel"])!==e)throw new Error("mutation-qa-project-root-invalid");const a=p(e,["rev-parse","--verify","HEAD"]),h=f??n,i=p(e,["rev-parse","--verify","--end-of-options",`${h}^{commit}`]);if(f)try{w(e,["merge-base","--is-ancestor",i,a])}catch{throw new Error("mutation-qa-base-not-ancestor")}const d=p(e,["merge-base",i,a]);if(![a,i,d].every(c=>/^[a-f0-9]{40,64}$/.test(c)))throw new Error("mutation-qa-revision-invalid");if(f&&(i!==f||d!==i))throw new Error("mutation-qa-base-not-ancestor");if(w(e,["status","--porcelain=v1","-z","--untracked-files=all"]).byteLength!==0)throw new Error("mutation-qa-checkout-dirty");const s=E(e),u=w(e,["diff","--name-only","-z","--diff-filter=ACMR",d,a]).toString("utf8").split("\0").filter(Boolean);if(u.length>512)throw new Error("mutation-qa-scope-too-large");const r=u.filter(b);if(r.some(c=>!k(c)))throw new Error("mutation-qa-source-path-unsafe");if(r.length>128)throw new Error("mutation-qa-scope-too-large");const t=r.filter(c=>!S(s,c)).sort().map(c=>{const g=p(e,["ls-tree","HEAD","--",c]).match(/^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/);if(!g||g[3]!==c)throw new Error("mutation-qa-source-not-regular");return Object.freeze({path:c,blobSha:g[2]})});if(p(e,["rev-parse","--verify","HEAD"])!==a||p(e,["rev-parse","--verify","--end-of-options",`${h}^{commit}`])!==i||w(e,["status","--porcelain=v1","-z","--untracked-files=all"]).byteLength!==0)throw new Error("mutation-qa-physical-drift");const l={schemaVersion:1,kind:"mutation-qa-plan",outcome:t.length>0?"ready":"skipped-no-files",baseRef:n,baseSha:i,headSha:a,mergeBaseSha:d,policy:s,eligibleFiles:t,checkpointAccepted:!1,localOnly:!0};return Object.freeze({...l,planSha256:q("sha256").update("mutation-qa-plan-v1\0").update(JSON.stringify(l)).digest("hex")})}catch(a){throw a instanceof Error&&a.message.startsWith("mutation-qa-")?a:new Error("mutation-qa-plan-unavailable")}}async function C(o){let n=process.cwd(),f="",m="",e="",a=!1,h=!1,i="plain";const d=new Set;try{if(o[0]!=="plan"&&o[0]!=="run"&&o[0]!=="execute"&&o[0]!=="checkpoint"&&o[0]!=="gate")throw new Error("mutation-qa-action-invalid");for(let r=1;r<o.length;r++){const t=o[r];if(d.has(t))throw new Error("mutation-qa-argument-duplicate");d.add(t);const l=()=>o[++r]??"";if(t==="--project-root")n=l();else if(t==="--base-ref")f=l();else if(t==="--base-sha")m=l();else if(t==="--plan-sha")e=l();else if(t==="--authorize-run")a=!0;else if(t==="--record-checkpoint")h=!0;else if(t==="--format"){const c=l();if(c!=="plain"&&c!=="json")throw new Error("mutation-qa-format-invalid");i=c}else throw new Error("mutation-qa-argument-invalid")}if(!n||!!f==!!m)throw new Error("mutation-qa-target-required");if(m&&!/^([a-f0-9]{40}|[a-f0-9]{64})$/.test(m))throw new Error("mutation-qa-base-ref-invalid");const s=m?`sha:${m}`:f;if(o[0]==="execute"){if(!a||!e||h)throw new Error("mutation-qa-execute-authorization-required");const{executeMutationQaPlan:r}=await import("./mutation-qa-gate.js"),t=r(n,s,e);return console.log(i==="json"?JSON.stringify({ok:!0,execution:t}):`mutation-qa execute: ${t.decision.status} head=${t.headSha} debt=${t.followUpDebt?"recorded":"none"} qaPassed=${t.decision.qaPassed}`),t.decision.safeToContinueLocalQa?0:t.continuationAuthorized?2:1}if(o[0]==="gate"){if(!e||a||h)throw new Error("mutation-qa-gate-options-invalid");const{classifyMutationQaGate:r}=await import("./mutation-qa-gate.js"),t=r(n,s,e);return console.log(i==="json"?JSON.stringify({ok:!0,decision:t}):`mutation-qa gate: ${t.status} head=${t.headSha}`),t.safeToContinueLocalQa?0:1}if(o[0]==="checkpoint"){if(!e||a||h)throw new Error("mutation-qa-checkpoint-options-invalid");const{readMutationQaCheckpoint:r}=await import("./mutation-qa-checkpoint.js"),t=r(n,s,e);return console.log(i==="json"?JSON.stringify({ok:!0,checkpoint:t??null}):`mutation-qa checkpoint: ${t?t.verdict:"none"}`),0}if(o[0]==="run"){if(!a||!e)throw new Error("mutation-qa-run-authorization-required");if(h){const{runAndRecordMutationQa:r}=await import("./mutation-qa-checkpoint.js"),{result:t,checkpoint:l}=r(n,s,e);console.log(i==="json"?JSON.stringify({ok:!0,result:t,checkpoint:l??null}):`mutation-qa run: ${t.outcome} head=${t.headSha} checkpoint=${l?"accepted":"none"}`)}else{const{runMutationQa:r}=await import("./mutation-qa-run.js"),t=r(n,s,e);console.log(i==="json"?JSON.stringify({ok:!0,result:t}):`mutation-qa run: ${t.outcome} head=${t.headSha}`)}return 0}if(a||e||h)throw new Error("mutation-qa-plan-options-invalid");const u=x(n,s);return console.log(i==="json"?JSON.stringify({ok:!0,plan:u}):`mutation-qa plan: ${u.outcome} files=${u.eligibleFiles.length} head=${u.headSha}`),0}catch(s){const u=s instanceof Error&&/^mutation-qa-[a-z0-9-]+$/.test(s.message)?s.message:"mutation-qa-unavailable";return i==="json"?console.log(JSON.stringify({ok:!1,reasonCode:u})):console.error(`mutation-qa: ${u}`),1}}export{C as mutationQaCliHandler,x as planMutationQa};
+/** Root-owned, read-only source scope for the protected mutation-test workflow. */
+import { createHash } from 'node:crypto';
+import { lstatSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { mutationQaGit } from './mutation-qa-git.js';
+import { loadMutationQaPolicy, policyExcludesPath } from './mutation-qa-policy.js';
+function value(root, args) {
+    return mutationQaGit(root, args).toString('utf8').trim();
+}
+function eligiblePath(path) {
+    return path.length > 0 && path.length <= 240
+        && /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(path)
+        && !path.split('/').some((part) => part === '.' || part === '..')
+        && /\.(?:ts|tsx|js|jsx)$/.test(path)
+        && !/\.d\.ts$|\.(?:test|spec)\.[jt]sx?$|(?:^|\/)__tests__\/|(?:^|\/)migrations\//.test(path);
+}
+function isSourceCandidate(path) {
+    return /\.(?:ts|tsx|js|jsx)$/.test(path)
+        && !/\.d\.ts$|\.(?:test|spec)\.[jt]sx?$|(?:^|\/)__tests__\/|(?:^|\/)migrations\//.test(path);
+}
+/** No test execution, package installation, network, project write or QA verdict. */
+export function planMutationQa(projectRoot, baseRef) {
+    const exactBaseSha = /^sha:([a-f0-9]{40}|[a-f0-9]{64})$/.exec(baseRef)?.[1];
+    const remoteRef = /^refs\/remotes\/[A-Za-z0-9][A-Za-z0-9_-]{0,63}\/[A-Za-z0-9][A-Za-z0-9/_-]{0,127}$/.test(baseRef)
+        && !baseRef.includes('..') && !baseRef.includes('//') && !baseRef.endsWith('/');
+    if (!exactBaseSha && !remoteRef) {
+        throw new Error('mutation-qa-base-ref-invalid');
+    }
+    const root = resolve(projectRoot);
+    try {
+        if (realpathSync(root) !== root || !lstatSync(root).isDirectory()
+            || value(root, ['rev-parse', '--show-toplevel']) !== root) {
+            throw new Error('mutation-qa-project-root-invalid');
+        }
+        const headSha = value(root, ['rev-parse', '--verify', 'HEAD']);
+        const baseRevision = exactBaseSha ?? baseRef;
+        const baseSha = value(root, ['rev-parse', '--verify', '--end-of-options', `${baseRevision}^{commit}`]);
+        if (exactBaseSha) {
+            try {
+                mutationQaGit(root, ['merge-base', '--is-ancestor', baseSha, headSha]);
+            }
+            catch {
+                throw new Error('mutation-qa-base-not-ancestor');
+            }
+        }
+        const mergeBaseSha = value(root, ['merge-base', baseSha, headSha]);
+        if (![headSha, baseSha, mergeBaseSha].every((sha) => /^[a-f0-9]{40,64}$/.test(sha))) {
+            throw new Error('mutation-qa-revision-invalid');
+        }
+        if (exactBaseSha && (baseSha !== exactBaseSha || mergeBaseSha !== baseSha)) {
+            throw new Error('mutation-qa-base-not-ancestor');
+        }
+        if (mutationQaGit(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']).byteLength !== 0) {
+            throw new Error('mutation-qa-checkout-dirty');
+        }
+        const policy = loadMutationQaPolicy(root);
+        const changedPaths = mutationQaGit(root, ['diff', '--name-only', '-z', '--diff-filter=ACMR', mergeBaseSha, headSha])
+            .toString('utf8').split('\0').filter(Boolean);
+        if (changedPaths.length > 512)
+            throw new Error('mutation-qa-scope-too-large');
+        const sourcePaths = changedPaths.filter(isSourceCandidate);
+        if (sourcePaths.some((path) => !eligiblePath(path)))
+            throw new Error('mutation-qa-source-path-unsafe');
+        if (sourcePaths.length > 128)
+            throw new Error('mutation-qa-scope-too-large');
+        const eligibleFiles = sourcePaths.filter((path) => !policyExcludesPath(policy, path)).sort().map((path) => {
+            const entry = value(root, ['ls-tree', 'HEAD', '--', path]);
+            const match = entry.match(/^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/);
+            if (!match || match[3] !== path)
+                throw new Error('mutation-qa-source-not-regular');
+            return Object.freeze({ path, blobSha: match[2] });
+        });
+        if (value(root, ['rev-parse', '--verify', 'HEAD']) !== headSha
+            || value(root, ['rev-parse', '--verify', '--end-of-options', `${baseRevision}^{commit}`]) !== baseSha
+            || mutationQaGit(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']).byteLength !== 0) {
+            throw new Error('mutation-qa-physical-drift');
+        }
+        const fields = { schemaVersion: 1, kind: 'mutation-qa-plan',
+            outcome: eligibleFiles.length > 0 ? 'ready' : 'skipped-no-files',
+            baseRef, baseSha, headSha, mergeBaseSha, policy, eligibleFiles,
+            checkpointAccepted: false, localOnly: true };
+        return Object.freeze({ ...fields,
+            planSha256: createHash('sha256').update('mutation-qa-plan-v1\0')
+                .update(JSON.stringify(fields)).digest('hex'),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('mutation-qa-'))
+            throw error;
+        throw new Error('mutation-qa-plan-unavailable');
+    }
+}
+export async function mutationQaCliHandler(args) {
+    let projectRoot = process.cwd();
+    let baseRef = '';
+    let baseSha = '';
+    let planSha = '';
+    let authorizeRun = false;
+    let recordCheckpoint = false;
+    let format = 'plain';
+    const seen = new Set();
+    try {
+        if (args[0] !== 'plan' && args[0] !== 'run' && args[0] !== 'execute' && args[0] !== 'checkpoint'
+            && args[0] !== 'gate') {
+            throw new Error('mutation-qa-action-invalid');
+        }
+        for (let index = 1; index < args.length; index++) {
+            const arg = args[index];
+            if (seen.has(arg))
+                throw new Error('mutation-qa-argument-duplicate');
+            seen.add(arg);
+            const next = () => args[++index] ?? '';
+            if (arg === '--project-root')
+                projectRoot = next();
+            else if (arg === '--base-ref')
+                baseRef = next();
+            else if (arg === '--base-sha')
+                baseSha = next();
+            else if (arg === '--plan-sha')
+                planSha = next();
+            else if (arg === '--authorize-run')
+                authorizeRun = true;
+            else if (arg === '--record-checkpoint')
+                recordCheckpoint = true;
+            else if (arg === '--format') {
+                const selected = next();
+                if (selected !== 'plain' && selected !== 'json')
+                    throw new Error('mutation-qa-format-invalid');
+                format = selected;
+            }
+            else
+                throw new Error('mutation-qa-argument-invalid');
+        }
+        if (!projectRoot || Boolean(baseRef) === Boolean(baseSha)) {
+            throw new Error('mutation-qa-target-required');
+        }
+        if (baseSha && !/^([a-f0-9]{40}|[a-f0-9]{64})$/.test(baseSha)) {
+            throw new Error('mutation-qa-base-ref-invalid');
+        }
+        const baseSelector = baseSha ? `sha:${baseSha}` : baseRef;
+        if (args[0] === 'execute') {
+            if (!authorizeRun || !planSha || recordCheckpoint) {
+                throw new Error('mutation-qa-execute-authorization-required');
+            }
+            const { executeMutationQaPlan } = await import('./mutation-qa-gate.js');
+            const execution = executeMutationQaPlan(projectRoot, baseSelector, planSha);
+            if (format === 'json')
+                console.log(JSON.stringify({ ok: true, execution }));
+            else
+                console.log(`mutation-qa execute: ${execution.decision.status} head=${execution.headSha} debt=${execution.followUpDebt ? 'recorded' : 'none'} qaPassed=${execution.decision.qaPassed}`);
+            // Exit 2 is a recorded-debt continuation signal, never a shell-level QA pass.
+            return execution.decision.safeToContinueLocalQa ? 0
+                : execution.continuationAuthorized ? 2 : 1;
+        }
+        if (args[0] === 'gate') {
+            if (!planSha || authorizeRun || recordCheckpoint) {
+                throw new Error('mutation-qa-gate-options-invalid');
+            }
+            const { classifyMutationQaGate } = await import('./mutation-qa-gate.js');
+            const decision = classifyMutationQaGate(projectRoot, baseSelector, planSha);
+            if (format === 'json')
+                console.log(JSON.stringify({ ok: true, decision }));
+            else
+                console.log(`mutation-qa gate: ${decision.status} head=${decision.headSha}`);
+            // This action is also a shell/CI gate. A typed decision is not a pass:
+            // warned and unobserved still need a separate durable debt checkpoint.
+            return decision.safeToContinueLocalQa ? 0 : 1;
+        }
+        if (args[0] === 'checkpoint') {
+            if (!planSha || authorizeRun || recordCheckpoint) {
+                throw new Error('mutation-qa-checkpoint-options-invalid');
+            }
+            const { readMutationQaCheckpoint } = await import('./mutation-qa-checkpoint.js');
+            const checkpoint = readMutationQaCheckpoint(projectRoot, baseSelector, planSha);
+            if (format === 'json')
+                console.log(JSON.stringify({ ok: true, checkpoint: checkpoint ?? null }));
+            else
+                console.log(`mutation-qa checkpoint: ${checkpoint ? checkpoint.verdict : 'none'}`);
+            return 0;
+        }
+        if (args[0] === 'run') {
+            if (!authorizeRun || !planSha)
+                throw new Error('mutation-qa-run-authorization-required');
+            if (recordCheckpoint) {
+                const { runAndRecordMutationQa } = await import('./mutation-qa-checkpoint.js');
+                const { result, checkpoint } = runAndRecordMutationQa(projectRoot, baseSelector, planSha);
+                if (format === 'json')
+                    console.log(JSON.stringify({ ok: true, result, checkpoint: checkpoint ?? null }));
+                else
+                    console.log(`mutation-qa run: ${result.outcome} head=${result.headSha} checkpoint=${checkpoint ? 'accepted' : 'none'}`);
+            }
+            else {
+                const { runMutationQa } = await import('./mutation-qa-run.js');
+                const result = runMutationQa(projectRoot, baseSelector, planSha);
+                if (format === 'json')
+                    console.log(JSON.stringify({ ok: true, result }));
+                else
+                    console.log(`mutation-qa run: ${result.outcome} head=${result.headSha}`);
+            }
+            return 0;
+        }
+        if (authorizeRun || planSha || recordCheckpoint)
+            throw new Error('mutation-qa-plan-options-invalid');
+        const plan = planMutationQa(projectRoot, baseSelector);
+        if (format === 'json')
+            console.log(JSON.stringify({ ok: true, plan }));
+        else
+            console.log(`mutation-qa plan: ${plan.outcome} files=${plan.eligibleFiles.length} head=${plan.headSha}`);
+        return 0;
+    }
+    catch (error) {
+        const reason = error instanceof Error && /^mutation-qa-[a-z0-9-]+$/.test(error.message)
+            ? error.message : 'mutation-qa-unavailable';
+        if (format === 'json')
+            console.log(JSON.stringify({ ok: false, reasonCode: reason }));
+        else
+            console.error(`mutation-qa: ${reason}`);
+        return 1;
+    }
+}