agentic-workflow-manager 6.5.2 → 8.0.0

package/dist/src/commands/sensors/coverage/render.js

@@ -6,11 +6,17 @@ const ANSI = /\x1B\[[0-?]*[ -/]*[@-~]/g;
 const OSC = /\x1B\][\s\S]*?(?:\x07|\x1B\\)/g;
 const CONTROLS = /[\u0000-\u001F\u007F-\u009F]/g;
 const OVERALL = ['covered', 'gaps', 'inconclusive'];
-const CLASS_STATUS = ['covered', 'missing', 'unverifiable'];
+const CLASS_STATUS = ['covered', 'missing', 'unverifiable', 'not-applicable'];
 const DETECTOR_STATUS = ['covered', 'missing', 'disabled', 'ineffective', 'unverifiable'];
+const COMPATIBILITY_STATE = ['certified', 'compatible-unverified', 'incompatible', 'missing-tool', 'unverifiable', 'not-applicable'];
 const REASON = ['not_configured', 'no_reference'];
 const COMMAND_EVIDENCE_STATUS = ['matched', 'custom', 'missing'];
 const FILE_EVIDENCE_STATUS = ['matched', 'missing', 'unverifiable'];
+const EMPIRICAL_STATUS = ['no-evidence', 'evidence', 'partial', 'inconclusive'];
+const EMPIRICAL_OUTCOME = ['covered-by-sensor', 'gap', 'coverage-unverifiable', 'applicability-contradiction', 'unmapped-class'];
+const SEVERITY = ['blocker', 'important', 'minor', 'info'];
+const CLUSTER_KIND = ['exact', 'convergent'];
+const SAFE_REF = /^(?:PR #[1-9][0-9]*|[a-f0-9]{7,64}|(?!\/)(?!.*(?:^|\/)\.\.?\/)[A-Za-z0-9._@+~=-]+(?:\/[A-Za-z0-9._@+~=-]+)*:[1-9][0-9]*)$/i;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -53,10 +59,149 @@ function assertEvidence(evidence, renderer) {
         }
     }
 }
+function assertCompatibility(value, renderer) {
+    if (!isRecord(value) || !hasExactFields(value, ['state', 'reason', 'variantId', 'toolVersion', 'runtimeVersion', 'certifiedRange', 'evidence'])
+        || !isOneOf(value.state, COMPATIBILITY_STATE) || !isNonBlankString(value.reason)
+        || !(value.variantId === null || isNonBlankString(value.variantId))
+        || !(value.toolVersion === null || isNonBlankString(value.toolVersion))
+        || !(value.runtimeVersion === null || isNonBlankString(value.runtimeVersion))
+        || !(value.certifiedRange === null || isNonBlankString(value.certifiedRange))
+        || !Array.isArray(value.evidence))
+        invalidReport(renderer);
+    for (const evidence of value.evidence) {
+        if (!isRecord(evidence) || !hasExactFields(evidence, 'path' in evidence ? ['kind', 'status', 'path'] : ['kind', 'status'])
+            || !isNonBlankString(evidence.kind) || !isNonBlankString(evidence.status)
+            || ('path' in evidence && !isNonBlankString(evidence.path)))
+            invalidReport(renderer);
+    }
+}
+function assertCount(value, renderer) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        invalidReport(renderer);
+}
+function assertRefs(value, renderer) {
+    if (!Array.isArray(value) || value.some((ref) => !isNonBlankString(ref) || ref.length > 256 || /[\u0000-\u001F\u007F-\u009F]/.test(ref) || !SAFE_REF.test(ref)))
+        invalidReport(renderer);
+    for (let index = 1; index < value.length; index += 1)
+        if (value[index - 1] >= value[index])
+            invalidReport(renderer);
+}
+function assertClusters(value, threshold, renderer) {
+    if (!Array.isArray(value) || value.length === 0)
+        invalidReport(renderer);
+    let occurrences = 0;
+    let recurrent = false;
+    let highestSeverity = 'info';
+    const severityRank = { blocker: 4, important: 3, minor: 2, info: 1 };
+    for (const cluster of value) {
+        if (!isRecord(cluster) || !hasExactFields(cluster, ['occurrences', 'recurrent', 'severity', 'kind', 'signatures', 'omittedSignatures', 'evidenceRefs', 'omittedEvidenceRefs'])
+            || !isOneOf(cluster.kind, CLUSTER_KIND) || !isOneOf(cluster.severity, SEVERITY) || typeof cluster.recurrent !== 'boolean')
+            invalidReport(renderer);
+        assertCount(cluster.occurrences, renderer);
+        assertRefs(cluster.signatures, renderer);
+        assertCount(cluster.omittedSignatures, renderer);
+        assertRefs(cluster.evidenceRefs, renderer);
+        assertCount(cluster.omittedEvidenceRefs, renderer);
+        if (cluster.occurrences < 1 || cluster.recurrent !== (cluster.occurrences >= threshold))
+            invalidReport(renderer);
+        occurrences += cluster.occurrences;
+        recurrent ||= cluster.recurrent;
+        if (severityRank[cluster.severity] > severityRank[highestSeverity])
+            highestSeverity = cluster.severity;
+    }
+    return { occurrences, recurrent, severity: highestSeverity };
+}
+function assertEmpirical(value, renderer) {
+    if (!isRecord(value) || !hasExactFields(value, ['recurrenceThreshold', 'status', 'classes', 'unclassified', 'sources', 'omittedEvidenceRefs'])
+        || !isOneOf(value.status, EMPIRICAL_STATUS) || !Array.isArray(value.classes) || !isRecord(value.unclassified)
+        || !isRecord(value.sources))
+        invalidReport(renderer);
+    assertCount(value.omittedEvidenceRefs, renderer);
+    if (typeof value.recurrenceThreshold !== 'number' || !Number.isSafeInteger(value.recurrenceThreshold) || value.recurrenceThreshold < 1)
+        invalidReport(renderer);
+    let previous;
+    let occurrenceCount = 0;
+    for (const item of value.classes) {
+        if (!isRecord(item) || !hasExactFields(item, ['defectClass', 'occurrences', 'recurrent', 'severity', 'outcome', 'evidenceRefs', 'omittedEvidenceRefs', 'clusters'])
+            || !isNonBlankString(item.defectClass) || !isOneOf(item.severity, SEVERITY) || !isOneOf(item.outcome, EMPIRICAL_OUTCOME)
+            || typeof item.recurrent !== 'boolean')
+            invalidReport(renderer);
+        assertCount(item.occurrences, renderer);
+        assertCount(item.omittedEvidenceRefs, renderer);
+        assertRefs(item.evidenceRefs, renderer);
+        const clusterSummary = assertClusters(item.clusters, value.recurrenceThreshold, renderer);
+        if (item.occurrences < 1 || item.occurrences !== clusterSummary.occurrences || item.recurrent !== clusterSummary.recurrent
+            || item.severity !== clusterSummary.severity)
+            invalidReport(renderer);
+        if (previous && (Number(previous.recurrent) < Number(item.recurrent)
+            || (previous.recurrent === item.recurrent && previous.occurrences < item.occurrences)
+            || (previous.recurrent === item.recurrent && previous.occurrences === item.occurrences && previous.defectClass >= item.defectClass)))
+            invalidReport(renderer);
+        previous = { recurrent: item.recurrent, occurrences: item.occurrences, defectClass: item.defectClass };
+        occurrenceCount += item.occurrences;
+    }
+    if (!hasExactFields(value.unclassified, ['occurrences', 'evidenceRefs', 'omittedEvidenceRefs']))
+        invalidReport(renderer);
+    assertCount(value.unclassified.occurrences, renderer);
+    assertCount(value.unclassified.omittedEvidenceRefs, renderer);
+    assertRefs(value.unclassified.evidenceRefs, renderer);
+    if (!hasExactFields(value.sources, ['activeFiles', 'archivedFiles', 'validEntries', 'validFindings', 'skippedFindings', 'skippedByReason']) || !isRecord(value.sources.skippedByReason))
+        invalidReport(renderer);
+    for (const key of ['activeFiles', 'archivedFiles', 'validEntries', 'validFindings', 'skippedFindings'])
+        assertCount(value.sources[key], renderer);
+    for (const count of Object.values(value.sources.skippedByReason))
+        assertCount(count, renderer);
+    const validFindings = value.sources.validFindings;
+    const validEntries = value.sources.validEntries;
+    const skippedFindings = value.sources.skippedFindings;
+    const unclassifiedOccurrences = value.unclassified.occurrences;
+    const omitted = value.omittedEvidenceRefs;
+    if (validFindings !== occurrenceCount + unclassifiedOccurrences || validEntries < validFindings)
+        invalidReport(renderer);
+    const skippedByReason = Object.values(value.sources.skippedByReason);
+    const totalSkippedByReason = skippedByReason.reduce((total, count) => total + count, 0);
+    if (skippedFindings !== totalSkippedByReason)
+        invalidReport(renderer);
+    const classOmitted = value.classes.reduce((total, item) => total + item.omittedEvidenceRefs, 0);
+    const unclassifiedOmitted = value.unclassified.omittedEvidenceRefs;
+    const scannerOmitted = (value.sources.skippedByReason['evidence-ref-limit'] ?? 0);
+    if (omitted !== scannerOmitted + classOmitted + unclassifiedOmitted)
+        invalidReport(renderer);
+    const incomplete = skippedFindings + omitted + unclassifiedOccurrences;
+    const expectedStatus = validFindings === 0
+        ? incomplete === 0 ? 'no-evidence' : 'inconclusive'
+        : incomplete === 0 ? 'evidence' : 'partial';
+    if (value.status !== expectedStatus)
+        invalidReport(renderer);
+}
+/**
+ * An empirical class is public only as an aggregate, but its outcome is still
+ * constrained by the already-public static catalog. Keeping the lookup local
+ * to the renderer avoids expanding the JSON schema with an internal state map.
+ */
+function assertEmpiricalStaticInvariant(empirical, staticStates, renderer) {
+    for (const item of empirical.classes) {
+        let expected;
+        if (staticStates === null) {
+            expected = 'coverage-unverifiable';
+        }
+        else {
+            const state = staticStates.get(item.defectClass);
+            expected = state === undefined ? 'unmapped-class'
+                : state === 'covered' ? 'covered-by-sensor'
+                    : state === 'missing' ? 'gap'
+                        : state === 'unverifiable' ? 'coverage-unverifiable'
+                            : state === 'not-applicable' ? 'applicability-contradiction'
+                                : invalidReport(renderer);
+        }
+        if (item.outcome !== expected)
+            invalidReport(renderer);
+    }
+}
 function assertCoverageEnvelope(report, renderer) {
     if (!isRecord(report) || !hasExactFields(report, 'empirical' in report
         ? ['schemaVersion', 'pack', 'registry', 'overall', 'static', 'empirical']
-        : ['schemaVersion', 'pack', 'registry', 'overall', 'static']) || report.schemaVersion !== 1
+        : ['schemaVersion', 'pack', 'registry', 'overall', 'static']) || report.schemaVersion !== 2
         || !(report.pack === null || isNonBlankString(report.pack))
         || !(report.registry === null || isNonBlankString(report.registry))
         || !isOneOf(report.overall, OVERALL) || !isRecord(report.static)) {
@@ -73,6 +218,10 @@ function assertCoverageEnvelope(report, renderer) {
         if (report.overall !== 'inconclusive' || report.pack !== null || report.registry !== null || staticReport.classes.length !== 0) {
             invalidReport(renderer);
         }
+        if (report.empirical !== undefined) {
+            assertEmpirical(report.empirical, renderer);
+            assertEmpiricalStaticInvariant(report.empirical, null, renderer);
+        }
         return;
     }
     if (staticReport.reason === 'no_reference') {
@@ -80,6 +229,10 @@ function assertCoverageEnvelope(report, renderer) {
             || staticReport.classes.length !== 0) {
             invalidReport(renderer);
         }
+        if (report.empirical !== undefined) {
+            assertEmpirical(report.empirical, renderer);
+            assertEmpiricalStaticInvariant(report.empirical, null, renderer);
+        }
         return;
     }
     if (!isNonBlankString(report.pack) || !isNonBlankString(report.registry) || staticReport.classes.length === 0) {
@@ -88,6 +241,7 @@ function assertCoverageEnvelope(report, renderer) {
     let previousId;
     let hasMissingClass = false;
     let hasUnverifiableClass = false;
+    const staticStates = new Map();
     for (const coverageClass of staticReport.classes) {
         if (!isRecord(coverageClass) || !hasExactFields(coverageClass, ['id', 'description', 'status', 'detectors', 'remedy'])
             || !isNonBlankString(coverageClass.id) || !isNonBlankString(coverageClass.description)
@@ -102,26 +256,39 @@ function assertCoverageEnvelope(report, renderer) {
             invalidReport(renderer);
         if (!isNonBlankString(coverageClass.remedy.summary) || !isNonBlankString(coverageClass.remedy.command))
             invalidReport(renderer);
-        let hasCoveredDetector = false;
-        let hasUnverifiableDetector = false;
+        let classStatus;
         for (const detector of coverageClass.detectors) {
-            if (!isRecord(detector) || !hasExactFields(detector, ['sensor', 'status', 'evidence'])
+            if (!isRecord(detector) || !hasExactFields(detector, ['sensor', 'status', 'evidence', 'compatibility'])
                 || !isNonBlankString(detector.sensor) || !isOneOf(detector.status, DETECTOR_STATUS)) {
                 invalidReport(renderer);
             }
             assertEvidence(detector.evidence, renderer);
-            hasCoveredDetector ||= detector.status === 'covered';
-            hasUnverifiableDetector ||= detector.status === 'unverifiable';
+            assertCompatibility(detector.compatibility, renderer);
+            const state = detector.compatibility.state;
+            const detectorStatus = state === 'not-applicable' ? 'not-applicable'
+                : state === 'compatible-unverified' || state === 'unverifiable' || detector.status === 'unverifiable' ? 'unverifiable'
+                    : state === 'incompatible' || state === 'missing-tool' || detector.status !== 'covered' ? 'missing'
+                        : 'covered';
+            const rank = { covered: 4, unverifiable: 3, missing: 2, 'not-applicable': 1 };
+            if (classStatus === undefined || rank[detectorStatus] > rank[classStatus])
+                classStatus = detectorStatus;
         }
-        const expectedClassStatus = hasCoveredDetector ? 'covered' : hasUnverifiableDetector ? 'unverifiable' : 'missing';
+        const expectedClassStatus = classStatus;
         if (coverageClass.status !== expectedClassStatus)
             invalidReport(renderer);
+        staticStates.set(coverageClass.id, expectedClassStatus);
         hasMissingClass ||= expectedClassStatus === 'missing';
         hasUnverifiableClass ||= expectedClassStatus === 'unverifiable';
     }
-    const expectedOverall = hasMissingClass ? 'gaps' : hasUnverifiableClass ? 'inconclusive' : 'covered';
+    const applicableClasses = staticReport.classes.filter((entry) => entry.status !== 'not-applicable');
+    const expectedOverall = hasMissingClass ? 'gaps' : hasUnverifiableClass ? 'inconclusive'
+        : applicableClasses.some((entry) => entry.status === 'covered') ? 'covered' : 'inconclusive';
     if (report.overall !== expectedOverall)
         invalidReport(renderer);
+    if (report.empirical !== undefined) {
+        assertEmpirical(report.empirical, renderer);
+        assertEmpiricalStaticInvariant(report.empirical, staticStates, renderer);
+    }
 }
 function safeHumanText(value) {
     return value.replace(OSC, '').replace(ANSI, '').replace(CONTROLS, ' ');
@@ -133,20 +300,53 @@ function renderCoverageJson(report) {
 function renderCoverageHuman(report) {
     assertCoverageEnvelope(report, 'renderCoverageHuman');
     if (report.static.reason === 'not_configured') {
-        return ['Sensor coverage', 'Overall: inconclusive', 'Reason: sensors are not configured', 'Run: awm sensors init', ''].join('\n');
+        return ['Sensor coverage', 'Overall: inconclusive', 'Reason: sensors are not configured', 'Run: awm sensors init', ...(report.empirical ? [empiricalHuman(report)] : []), ''].join('\n');
     }
     if (report.static.reason === 'no_reference') {
         return ['Sensor coverage', `Pack: ${safeHumanText(report.pack ?? 'unknown')}`, `Registry: ${safeHumanText(report.registry ?? 'unknown')}`,
-            'Overall: inconclusive', `No coverage reference for pack '${safeHumanText(report.pack ?? 'unknown')}'`, ''].join('\n');
+            'Overall: inconclusive', `No coverage reference for pack '${safeHumanText(report.pack ?? 'unknown')}'`, ...(report.empirical ? [empiricalHuman(report)] : []), ''].join('\n');
     }
     const lines = ['Sensor coverage', `Pack: ${safeHumanText(report.pack ?? 'unknown')}`, `Registry: ${safeHumanText(report.registry ?? 'unknown')}`,
         `Overall: ${report.overall}`, ''];
-    for (const item of report.static.classes.filter((entry) => entry.status !== 'covered')) {
+    for (const item of report.static.classes.filter((entry) => entry.status !== 'covered' && entry.status !== 'not-applicable')) {
         lines.push(`${item.status} ${safeHumanText(item.id)} — ${safeHumanText(item.description)}`);
-        item.detectors.forEach((detector) => lines.push(`  detector: ${safeHumanText(detector.sensor)} (${detector.status})`));
+        item.detectors.forEach((detector) => {
+            const compatibility = detector.compatibility;
+            if (!compatibility)
+                invalidReport('renderCoverageHuman');
+            lines.push(`  detector: ${safeHumanText(detector.sensor)} (${detector.status})`, `  compatibility: ${safeHumanText(compatibility.state)} — ${safeHumanText(compatibility.reason)}`);
+        });
         lines.push(`  remedy: ${safeHumanText(item.remedy.summary)}`, `  command: ${safeHumanText(item.remedy.command)}`);
     }
     const count = (status) => report.static.classes.filter((item) => item.status === status).length;
-    lines.push('', `Summary: ${count('covered')} covered, ${count('missing')} missing, ${count('unverifiable')} unverifiable`, '');
+    lines.push('', `Summary: ${count('covered')} covered, ${count('missing')} missing, ${count('unverifiable')} unverifiable, ${count('not-applicable')} not applicable`);
+    if (report.empirical)
+        lines.push(empiricalHuman(report));
+    lines.push('');
+    return lines.join('\n');
+}
+function empiricalHuman(report) {
+    const empirical = report.empirical;
+    if (!empirical)
+        return '';
+    const lines = [`Empirical coverage: ${empirical.status}`];
+    for (const item of empirical.classes) {
+        const recurrence = item.recurrent
+            ? `recurrent at threshold ${empirical.recurrenceThreshold}`
+            : `below recurrence threshold (${empirical.recurrenceThreshold})`;
+        lines.push(`${item.outcome} ${safeHumanText(item.defectClass)} — ${item.occurrences} occurrence${item.occurrences === 1 ? '' : 's'} (${item.severity}; ${recurrence})`);
+        if (item.evidenceRefs.length > 0)
+            lines.push(`  evidence: ${item.evidenceRefs.map(safeHumanText).join(', ')}`);
+        for (const cluster of item.clusters) {
+            const detail = cluster.signatures.length > 0 ? ` — ${cluster.signatures.map(safeHumanText).join(', ')}` : '';
+            lines.push(`  cluster: ${cluster.kind} (${cluster.occurrences} occurrence${cluster.occurrences === 1 ? '' : 's'}; ${cluster.severity})${detail}`);
+            if (cluster.omittedSignatures > 0)
+                lines.push(`  omitted cluster signatures: ${cluster.omittedSignatures}`);
+        }
+    }
+    if (empirical.unclassified.occurrences > 0)
+        lines.push(`unclassified findings: ${empirical.unclassified.occurrences}`);
+    if (empirical.omittedEvidenceRefs > 0)
+        lines.push(`omitted evidence refs: ${empirical.omittedEvidenceRefs}`);
     return lines.join('\n');
 }

package/dist/src/commands/sensors/coverage/resolve.js

@@ -7,8 +7,10 @@ exports.readBoundedJson = readBoundedJson;
 exports.resolveCoverageInputs = resolveCoverageInputs;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const registries_1 = require("../../../core/registries");
 const contract_1 = require("./contract");
+const contract_2 = require("../compatibility/contract");
+const manifest_1 = require("../compatibility/manifest");
+const pack_source_1 = require("../compatibility/pack-source");
 function readFailure(file, error) {
     return new Error(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
 }
@@ -59,23 +61,6 @@ function readBoundedJson(file) {
         throw new Error(`Invalid JSON at ${file}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-function readPackEnvelope(input, file, expectedName) {
-    if (typeof input !== 'object' || input === null || Array.isArray(input))
-        throw new Error(`Invalid pack at ${file}: expected object`);
-    const pack = input;
-    if (typeof pack.name !== 'string' || pack.name !== expectedName) {
-        throw new Error(`Invalid pack at ${file}: name must equal '${expectedName}'`);
-    }
-    if (typeof pack.sensors !== 'object' || pack.sensors === null || Array.isArray(pack.sensors)) {
-        throw new Error(`Invalid pack at ${file}: sensors must be an object`);
-    }
-    return 'coverage' in pack ? { coverage: pack.coverage } : {};
-}
-function safeRegistryName(name) {
-    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name) || name.includes('..')) {
-        throw new Error(`Invalid registry name '${name}': expected a safe path component`);
-    }
-}
 /** Finds the nearest manifest without following a symlink during discovery. */
 function findManifestDirNoFollow(startCwd) {
     let dir = path_1.default.resolve(startCwd);
@@ -102,25 +87,26 @@ function resolveCoverageInputs(cwd) {
     if (!projectRoot)
         return { kind: 'not_configured' };
     const manifestPath = path_1.default.join(projectRoot, '.awm', 'sensors.json');
-    const manifest = (0, contract_1.parseCoverageManifest)(readBoundedJson(manifestPath), manifestPath);
-    for (const registry of (0, registries_1.listRegistries)()) {
-        safeRegistryName(registry.name);
-        const packPath = path_1.default.join(registry.contentRoot, 'sensor-packs', manifest.pack, 'pack.json');
-        try {
-            fs_1.default.lstatSync(packPath);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT')
-                continue;
-            throw readFailure(packPath, error);
-        }
-        const { coverage } = readPackEnvelope(readBoundedJson(packPath), packPath, manifest.pack);
-        if (coverage === undefined)
-            return { kind: 'no_reference', projectRoot, pack: manifest.pack, registry: registry.name, manifest };
-        return {
-            kind: 'ready', projectRoot, pack: manifest.pack, registry: registry.name,
-            manifest, contract: (0, contract_1.parseCoverageContract)(coverage, packPath),
-        };
+    const manifest = (0, manifest_1.parseSensorManifest)(readBoundedJson(manifestPath), manifestPath);
+    const source = manifest.kind === 'v2' && manifest.pack.registryRoot !== undefined
+        ? (0, pack_source_1.resolvePackSource)(manifest.pack.pack, { registries: [{ name: 'manifest-provenance', remote: 'local', contentRoot: manifest.pack.registryRoot }] })
+        : (0, pack_source_1.resolvePackSource)(manifest.pack.pack);
+    let sourceJson;
+    try {
+        sourceJson = JSON.parse(source.content);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON at ${source.path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const parsedPack = (0, contract_2.parseSensorPack)(sourceJson, source.path);
+    if (parsedPack.pack.name !== manifest.pack.pack) {
+        throw new Error(`Invalid pack at ${source.path}: name must equal '${manifest.pack.pack}'`);
     }
-    throw new Error(`Pack '${manifest.pack}' was not found in configured registries`);
+    const { coverage } = parsedPack.pack;
+    if (coverage === undefined)
+        return { kind: 'no_reference', projectRoot, pack: manifest.pack.pack, registry: source.registry.name, manifest };
+    return {
+        kind: 'ready', projectRoot, pack: manifest.pack.pack, registry: source.registry.name,
+        manifest, contract: (0, contract_1.parseCoverageContract)(coverage, source.path),
+    };
 }

package/dist/src/commands/sensors/exec.js

@@ -1,7 +1,13 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runStructuredCommand = runStructuredCommand;
 exports.runCommand = runCommand;
 const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const paths_1 = require("../../core/paths");
 const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
 const DEFAULT_KILL_GRACE_MS = 2_000;
@@ -53,7 +59,17 @@ function killTree(pid, signal) {
  *     throws away 60s of eslint output costs double: the wall clock, and then
  *     the re-run the caller has to do to learn anything at all.
  */
-function runCommand(cmd, opts) {
+function validateOptions(opts) {
+    if (!opts || typeof opts !== 'object' || typeof opts.cwd !== 'string' || opts.cwd.trim() === '' || !Number.isSafeInteger(opts.timeout) || opts.timeout <= 0) {
+        throw new Error('exec options require a non-empty cwd and positive safe-integer timeout');
+    }
+    if (opts.maxBuffer !== undefined && (!Number.isSafeInteger(opts.maxBuffer) || opts.maxBuffer <= 0))
+        throw new Error('exec options maxBuffer must be a positive safe integer');
+    if (opts.killGraceMs !== undefined && (!Number.isSafeInteger(opts.killGraceMs) || opts.killGraceMs < 0))
+        throw new Error('exec options killGraceMs must be a non-negative safe integer');
+}
+function collectSpawn(input, opts) {
+    validateOptions(opts);
     const maxBuffer = opts.maxBuffer ?? DEFAULT_MAX_BUFFER;
     const killGraceMs = opts.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
     return new Promise((resolve) => {
@@ -63,14 +79,21 @@ function runCommand(cmd, opts) {
         let overflowed = false;
         let settled = false;
         const timers = [];
-        const child = (0, child_process_1.spawn)(cmd, {
-            shell: true,
-            cwd: opts.cwd,
-            detached: !(0, paths_1.isWindowsNative)(),
-            // stdin closed: a sensor must never block waiting for input, and the
-            // EOF also tells watch-mode-capable tools (vitest, jest) to run once.
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        const child = input.shell
+            ? (0, child_process_1.spawn)(input.executable, {
+                shell: true,
+                cwd: opts.cwd,
+                detached: !(0, paths_1.isWindowsNative)(),
+                stdio: ['ignore', 'pipe', 'pipe'],
+            })
+            : (0, child_process_1.spawn)(input.executable, input.args, {
+                shell: false,
+                cwd: opts.cwd,
+                detached: !(0, paths_1.isWindowsNative)(),
+                // stdin closed: a sensor must never block waiting for input, and the
+                // EOF also tells watch-mode-capable tools (vitest, jest) to run once.
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
         const later = (fn, ms) => {
             const t = setTimeout(fn, ms);
             t.unref?.();
@@ -120,3 +143,121 @@ function runCommand(cmd, opts) {
         later(() => { timedOut = true; cutShort(); }, opts.timeout);
     });
 }
+function validateStructuredCommand(command) {
+    if (!command || typeof command !== 'object' || typeof command.executable !== 'string' || (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(command.executable) && !path_1.default.isAbsolute(command.executable))) {
+        throw new Error('structured command executable must be a safe executable name');
+    }
+    if (!Array.isArray(command.args) || command.args.some(arg => typeof arg !== 'string' || /[\0\r\n]/.test(arg))) {
+        throw new Error('structured command args must be an array of single-line strings without NUL');
+    }
+    if (!['node-modules-bin', 'python-environment', 'path'].includes(command.resolution))
+        throw new Error('structured command resolution is unsupported');
+}
+function regularFile(candidate) {
+    try {
+        const stat = fs_1.default.lstatSync(candidate);
+        return stat.isFile() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function containedPath(root, candidate) {
+    const relative = path_1.default.relative(root, candidate);
+    return relative !== '' && !relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative);
+}
+/** Resolve a local npm shim to its real regular-file target. npm commonly uses
+ * symlinks in .bin on POSIX, so rejecting every symlink would reject valid local
+ * installs. The real target must remain inside the project's node_modules. */
+function localNodeModulesExecutable(candidate, modulesRoot) {
+    try {
+        const shim = fs_1.default.lstatSync(candidate);
+        if (!shim.isFile() && !shim.isSymbolicLink())
+            return null;
+        const real = fs_1.default.realpathSync(candidate);
+        const target = fs_1.default.statSync(real);
+        return target.isFile() && containedPath(modulesRoot, real) ? real : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Find a real executable without a shell. Windows .cmd/.bat shims are deliberately
+ * excluded: CreateProcess cannot execute them safely without cmd.exe. */
+function resolveStructuredExecutable(command, cwd) {
+    if (command.resolution === 'node-modules-bin') {
+        let modulesRoot;
+        try {
+            modulesRoot = fs_1.default.realpathSync(path_1.default.join(cwd, 'node_modules'));
+            if (!fs_1.default.statSync(modulesRoot).isDirectory())
+                throw new Error();
+        }
+        catch {
+            throw new Error('node_modules executable not found locally');
+        }
+        const bin = path_1.default.join(modulesRoot, '.bin');
+        if (!(0, paths_1.isWindowsNative)()) {
+            const local = localNodeModulesExecutable(path_1.default.join(bin, command.executable), modulesRoot);
+            if (local)
+                return local;
+            throw new Error('node_modules executable is not a contained local file');
+        }
+        const extensions = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').map(ext => ext.toLowerCase()).filter(ext => ext === '.exe' || ext === '.com');
+        const candidates = [path_1.default.join(bin, command.executable), ...extensions.map(extension => path_1.default.join(bin, command.executable + extension))];
+        for (const candidate of candidates) {
+            const lower = candidate.toLowerCase();
+            if (lower.endsWith('.cmd') || lower.endsWith('.bat'))
+                throw new Error('structured commands cannot execute Windows command wrappers');
+            const local = localNodeModulesExecutable(candidate, modulesRoot);
+            if (local && extensions.some(extension => local.toLowerCase().endsWith(extension)))
+                return local;
+        }
+        throw new Error('node_modules executable is not a contained local file');
+    }
+    const candidates = [];
+    if (command.resolution === 'python-environment') {
+        if (path_1.default.isAbsolute(command.executable))
+            throw new Error('python environment executable must be a contained local name');
+        candidates.push(path_1.default.join(cwd, '.venv', (0, paths_1.isWindowsNative)() ? 'Scripts' : 'bin', command.executable));
+        candidates.push(path_1.default.join(cwd, 'venv', (0, paths_1.isWindowsNative)() ? 'Scripts' : 'bin', command.executable));
+    }
+    else if (path_1.default.isAbsolute(command.executable))
+        candidates.push(command.executable);
+    else {
+        for (const entry of (process.env.PATH ?? '').split(path_1.default.delimiter).filter(Boolean))
+            candidates.push(path_1.default.join(entry, command.executable));
+    }
+    if (!(0, paths_1.isWindowsNative)()) {
+        const found = candidates.find(regularFile);
+        if (found)
+            return found;
+        if (command.resolution === 'python-environment')
+            throw new Error('python environment executable is not a contained local regular file');
+        return command.executable;
+    }
+    const extensions = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').map(ext => ext.toLowerCase()).filter(ext => ext === '.exe' || ext === '.com');
+    for (const candidate of candidates) {
+        const lower = candidate.toLowerCase();
+        if (lower.endsWith('.cmd') || lower.endsWith('.bat'))
+            throw new Error('structured commands cannot execute Windows command wrappers');
+        if (regularFile(candidate) && extensions.some(ext => lower.endsWith(ext)))
+            return candidate;
+        for (const extension of extensions)
+            if (regularFile(candidate + extension))
+                return candidate + extension;
+    }
+    if (command.resolution === 'python-environment')
+        throw new Error('python environment executable is not a contained local regular file');
+    return command.executable;
+}
+/** Execute a v2 command as an executable plus literal argv; it never starts a shell. */
+function runStructuredCommand(command, opts) {
+    validateStructuredCommand(command);
+    return collectSpawn({ executable: resolveStructuredExecutable(command, opts.cwd), args: command.args, shell: false }, opts);
+}
+/** Legacy sensor strings intentionally retain their documented shell semantics. */
+function runCommand(cmd, opts) {
+    if (typeof cmd !== 'string' || cmd.trim() === '' || /[\0\r\n]/.test(cmd))
+        throw new Error('runCommand: cmd must be a non-empty single-line legacy string without NUL');
+    return collectSpawn({ executable: cmd, args: [], shell: true }, opts);
+}

package/dist/src/commands/sensors/index.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exitCodeFor = exitCodeFor;
+exports.parsePositiveSafeInteger = parsePositiveSafeInteger;
 exports.registerSensorsCommand = registerSensorsCommand;
 const picocolors_1 = __importDefault(require("picocolors"));
 const prompts_1 = require("@clack/prompts");
@@ -21,15 +22,26 @@ const registries_1 = require("../../core/registries");
 function exitCodeFor(output) {
     return output.overall === 'fail' ? 1 : 0;
 }
+/** Commander coercion for coverage recurrence emphasis. It deliberately runs
+ * before the action, so an invalid value cannot trigger ledger I/O. */
+function parsePositiveSafeInteger(value) {
+    if (typeof value !== 'string' || !/^[1-9][0-9]*$/.test(value))
+        throw new Error('--min must be a positive safe integer');
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed))
+        throw new Error('--min must be a positive safe integer');
+    return parsed;
+}
 function registerSensorsCommand(program) {
     const sensors = program.command('sensors').description('manage computational sensors for the current project');
     sensors
         .command('coverage')
         .description('report static gaps between configured sensors and the pack reference')
         .option('--json', 'emit the versioned machine-readable envelope')
-        .action((opts) => {
+        .option('--min <count>', 'recurrence emphasis threshold', parsePositiveSafeInteger, 2)
+        .action(async (opts) => {
         try {
-            const report = (0, coverage_1.runCoverage)(process.cwd());
+            const report = await (0, coverage_1.runCoverage)(process.cwd(), {}, { min: opts.min });
             process.stdout.write(opts.json ? (0, render_1.renderCoverageJson)(report) : (0, render_1.renderCoverageHuman)(report));
         }
         catch (error) {
@@ -63,10 +75,10 @@ function registerSensorsCommand(program) {
         .option('--no-configure', 'skip copying sensor pack config files into the project')
         .option('--registry-root <path>', 'path to AWM registry root')
         .option('--pack <name>', 'skip auto-detection, use this pack explicitly')
-        .action((opts) => {
+        .action(async (opts) => {
         const registryRoot = opts.registryRoot ?? (0, registries_1.capabilityRoot)('sensor-packs') ?? undefined;
         try {
-            const result = (0, init_1.initSensors)({ configure: opts.configure, registryRoot, pack: opts.pack });
+            const result = await (0, init_1.initSensors)({ configure: opts.configure, registryRoot, pack: opts.pack });
             prompts_1.log.success(`Detected: ${result.detection.pack} (${result.detection.indicators.join(', ') || 'fallback'})`);
             // Said BEFORE "Wrote .awm/sensors.json": the manifest about to be
             // reported as written is not the one the detection implied.
@@ -99,8 +111,8 @@ function registerSensorsCommand(program) {
     sensors
         .command('status')
         .description('check sensor health for the current project')
-        .action(() => {
-        const status = (0, status_1.computeSensorStatus)();
+        .action(async () => {
+        const status = await (0, status_1.computeSensorStatus)();
         const icon = status.overall === 'HEALTHY' ? picocolors_1.default.green('✔') : picocolors_1.default.yellow('⚠');
         console.log(`\nPack:    ${status.pack ?? 'none'}`);
         console.log(`Overall: ${icon} ${status.overall}\n`);