agentic-workflow-manager 8.0.0 → 8.1.1

package/dist/scripts/sensor-support-matrix.js

@@ -3,7 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.R3_PREPUBLICATION_FIXTURE_PURPOSE = exports.R3_PREPUBLICATION_FIXTURE_RELATIVE_PATH = exports.SENSOR_DOC_PATH = exports.SENSOR_PACKS = exports.SENSOR_END_MARKER = exports.SENSOR_BEGIN_MARKER = void 0;
+exports.R3_PUBLISHED_REGISTRY_COMMIT = exports.R3_PUBLISHED_REGISTRY_TAG = exports.R3_PREPUBLICATION_FIXTURE_PURPOSE = exports.R3_PREPUBLICATION_FIXTURE_RELATIVE_PATH = exports.SENSOR_DOC_PATH = exports.SENSOR_PACKS = exports.SENSOR_END_MARKER = exports.SENSOR_BEGIN_MARKER = void 0;
+exports.extractPublishedSupportMetadata = extractPublishedSupportMetadata;
+exports.verifyPublishedRegistryIdentity = verifyPublishedRegistryIdentity;
 exports.parseRegistrySensorPacks = parseRegistrySensorPacks;
 exports.renderSensorSupportMatrix = renderSensorSupportMatrix;
 exports.spliceSensorSupportMatrix = spliceSensorSupportMatrix;
@@ -15,6 +17,7 @@ exports.registryRootFromArgs = registryRootFromArgs;
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 const contract_1 = require("../src/commands/sensors/compatibility/contract");
 exports.SENSOR_BEGIN_MARKER = '<!-- BEGIN GENERATED: sensor-pack-support -->';
 exports.SENSOR_END_MARKER = '<!-- END GENERATED: sensor-pack-support -->';
@@ -27,6 +30,66 @@ exports.R3_PREPUBLICATION_FIXTURE_RELATIVE_PATH = 'tests/fixtures/sensor-support
  * never an invented description of an unpublished registry release.
  */
 exports.R3_PREPUBLICATION_FIXTURE_PURPOSE = 'R3 pre-publication contract fixture';
+exports.R3_PUBLISHED_REGISTRY_TAG = 'v2.0.0';
+exports.R3_PUBLISHED_REGISTRY_COMMIT = 'c35c087a0801c0b4e69e0a4ac3eafef9ecdf37cd';
+/**
+ * Extract the registry-owned certification matrix without copying or rewording it.
+ * `SUPPORT.md` is generated by the registry from its manifests and frozen tool pins;
+ * this consumer must preserve that published evidence rather than infer certification
+ * from a compatibility range.
+ */
+function extractPublishedSupportMetadata(source) {
+    if (typeof source !== 'string' || source.length === 0) {
+        throw new Error('published sensor support metadata must be non-empty text');
+    }
+    const begin = '<!-- BEGIN GENERATED: sensor-pack-support -->';
+    const end = '<!-- END GENERATED: sensor-pack-support -->';
+    const starts = source.split(begin).length - 1;
+    const ends = source.split(end).length - 1;
+    if (starts !== 1 || ends !== 1) {
+        throw new Error('published sensor support metadata requires exactly one generated marker pair');
+    }
+    const start = source.indexOf(begin) + begin.length;
+    const finish = source.indexOf(end);
+    if (finish <= start)
+        throw new Error('published sensor support metadata has invalid marker order');
+    const metadata = source.slice(start, finish).trim();
+    if (!metadata.includes('| Pack | Sensor | Variant | Tool | Certified range | Supported OS | OS certification evidence | Status | Evidence |')) {
+        throw new Error('published sensor support metadata lacks the certification table');
+    }
+    if (!metadata.includes('Status: `certified` has a matching frozen tool pin;')) {
+        throw new Error('published sensor support metadata lacks certification status semantics');
+    }
+    return metadata;
+}
+function exactArgument(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1 || argv[index + 1] === undefined || argv[index + 1].startsWith('--') || index !== argv.lastIndexOf(flag)) {
+        throw new Error(`sensor support matrix requires exactly one ${flag} <value>`);
+    }
+    return argv[index + 1];
+}
+/** Refuse a mutable sibling checkout: published evidence is valid only for this immutable release. */
+function verifyPublishedRegistryIdentity(registryRoot, tag, commit) {
+    const root = registryPath(registryRoot);
+    if (tag !== exports.R3_PUBLISHED_REGISTRY_TAG || commit !== exports.R3_PUBLISHED_REGISTRY_COMMIT) {
+        throw new Error(`sensor support matrix requires published registry ${exports.R3_PUBLISHED_REGISTRY_TAG}@${exports.R3_PUBLISHED_REGISTRY_COMMIT}`);
+    }
+    const resolve = (revision) => {
+        try {
+            return (0, child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', revision], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+        }
+        catch {
+            throw new Error(`published registry root must be a git checkout at ${exports.R3_PUBLISHED_REGISTRY_TAG}`);
+        }
+    };
+    const head = resolve('HEAD');
+    const taggedCommit = resolve(`${tag}^{commit}`);
+    if (head !== commit)
+        throw new Error(`published registry HEAD ${head} does not match expected commit ${commit}`);
+    if (taggedCommit !== commit)
+        throw new Error(`published registry tag ${tag} resolves to ${taggedCommit}, expected commit ${commit}`);
+}
 function registryPath(value) {
     if (typeof value !== 'string' || value.trim().length === 0 || value.includes('\0')) {
         throw new Error('sensor support matrix requires a non-empty --registry-root');
@@ -58,24 +121,47 @@ function parseRegistrySensorPacks(registryRoot) {
 function variants(pack) {
     return Object.entries(pack.sensors).flatMap(([sensor, definition]) => definition.variants.map((variant) => `\`${sensor}/${variant.id}\`: ${variant.requirements.tool} ${variant.requirements.toolRange}; ${variant.requirements.runtime} ${variant.requirements.runtimeRange}; certified ${variant.certifiedRange}`)).join('<br>');
 }
+function publishedSupportMetadata(registryRoot) {
+    const file = path_1.default.join(registryRoot, 'sensor-packs', 'SUPPORT.md');
+    if (!fs_1.default.existsSync(file))
+        return null;
+    const stat = fs_1.default.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`published sensor support metadata must be a regular file: ${file}`);
+    return extractPublishedSupportMetadata(fs_1.default.readFileSync(file, 'utf8'));
+}
 /** Pure renderer used by freshness tests and the documentation command. */
 function renderSensorSupportMatrix(registryRoot) {
+    const root = registryPath(registryRoot);
+    const publishedMetadata = publishedSupportMetadata(root);
     const lines = [
-        `### Sensor-pack compatibility contract (${exports.R3_PREPUBLICATION_FIXTURE_PURPOSE})`,
+        publishedMetadata === null
+            ? `### Sensor-pack compatibility contract (${exports.R3_PREPUBLICATION_FIXTURE_PURPOSE})`
+            : '### Sensor-pack compatibility contract (published registry evidence)',
         '',
         '| Pack | Contract | Version-aware variants and certified ranges | Evidence status |',
         '|---|---|---|---|',
     ];
-    for (const { name, parsed } of parseRegistrySensorPacks(registryRoot)) {
+    for (const { name, parsed } of parseRegistrySensorPacks(root)) {
         if (parsed.kind === 'legacy') {
             lines.push(`| \`${name}\` | legacy pack | No v2 variants declared | compatible-unverified — migrate the pack before claiming version certification |`);
         }
         else {
-            lines.push(`| \`${name}\` | pack schema v2 | ${variants(parsed.pack)} | Fixture-declared ranges only; real-tool and OS certification awaits published registry release evidence |`);
+            lines.push(`| \`${name}\` | pack schema v2 | ${variants(parsed.pack)} | ${publishedMetadata === null ? 'Fixture-declared ranges only; real-tool and OS certification awaits published registry release evidence' : 'Published compatibility contract; certification evidence is reproduced below from the registry'} |`);
         }
     }
     lines.push('');
-    lines.push('> Generated from the pinned R3 pre-publication contract fixture, not the published `awm-baseline-registry` manifests. **Do not edit by hand** — `npm run docs:matrix` regenerates this block. T13 verifies the actual registry tag and release evidence.');
+    if (publishedMetadata === null) {
+        lines.push('> Generated from the pinned R3 pre-publication contract fixture, not the published `awm-baseline-registry` manifests. **Do not edit by hand** — `npm run docs:matrix:prepublication` regenerates this fixture-only block. T13 verifies the actual registry tag and release evidence.');
+    }
+    else {
+        lines.push('');
+        lines.push('#### Published certification evidence');
+        lines.push('');
+        lines.push(publishedMetadata);
+        lines.push('');
+        lines.push('> Generated from the supplied published `awm-baseline-registry` root. Certification states, frozen pins, and OS evidence are registry-owned metadata reproduced verbatim; **do not edit by hand**.');
+    }
     return lines.join('\n');
 }
 function spliceSensorSupportMatrix(markdown, generated) {
@@ -83,20 +169,32 @@ function spliceSensorSupportMatrix(markdown, generated) {
     const end = markdown.indexOf(exports.SENSOR_END_MARKER);
     if (begin === -1 || end === -1 || end < begin)
         throw new Error(`support-matrix.md lacks ${exports.SENSOR_BEGIN_MARKER} / ${exports.SENSOR_END_MARKER}`);
-    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    // Preserve the line ending of the block this renderer owns. Another generated
+    // block may legitimately have a different EOL during a Windows checkout.
+    const eol = markdown.slice(begin, end).includes('\r\n') ? '\r\n' : '\n';
     const block = generated.split('\n').join(eol);
     return markdown.slice(0, begin + exports.SENSOR_BEGIN_MARKER.length) + eol + eol + block + eol + eol + markdown.slice(end);
 }
 function registryRootFromArgs(argv) {
-    const index = argv.indexOf('--registry-root');
-    if (index === -1 || argv[index + 1] === undefined || argv[index + 1].startsWith('--') || index !== argv.lastIndexOf('--registry-root')) {
-        throw new Error('sensor support matrix requires exactly one --registry-root <path>');
-    }
-    return registryPath(argv[index + 1]);
+    return registryPath(exactArgument(argv, '--registry-root'));
 }
 /* istanbul ignore next: command shell is covered through exported functions. */
 if (require.main === module) {
-    const root = registryRootFromArgs(process.argv.slice(2));
+    const argv = process.argv.slice(2);
+    const root = registryRootFromArgs(argv);
+    const stdout = argv.includes('--stdout');
+    if (argv.includes('--prepublication-fixture')) {
+        if (argv.filter((value) => value === '--prepublication-fixture').length !== 1 || argv.filter((value) => value === '--stdout').length > 1 || (argv.length !== 3 && argv.length !== 4)) {
+            throw new Error('sensor support matrix fixture mode accepts only --registry-root <path> --prepublication-fixture [--stdout]');
+        }
+    }
+    else {
+        verifyPublishedRegistryIdentity(root, exactArgument(argv, '--registry-tag'), exactArgument(argv, '--registry-commit'));
+    }
+    if (stdout) {
+        process.stdout.write(`${renderSensorSupportMatrix(root)}\n`);
+        process.exit(0);
+    }
     const current = fs_1.default.readFileSync(exports.SENSOR_DOC_PATH, 'utf8');
     fs_1.default.writeFileSync(exports.SENSOR_DOC_PATH, spliceSensorSupportMatrix(current, renderSensorSupportMatrix(root)), 'utf8');
     process.stdout.write('support-matrix.md sensor-pack evidence regenerated from registry manifests\n');

package/dist/scripts/support-matrix.js

@@ -144,7 +144,10 @@ function spliceGenerated(markdown, generated) {
     if (begin === -1 || end === -1 || end < begin) {
         throw new Error(`support-matrix.md no tiene los marcadores ${exports.BEGIN_MARKER} / ${exports.END_MARKER}`);
     }
-    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    // Each renderer owns only its marked block. A document can temporarily contain
+    // another generated block with different line endings, so using the first CRLF
+    // anywhere in the file would rewrite this block and create CI-only drift.
+    const eol = markdown.slice(begin, end).includes('\r\n') ? '\r\n' : '\n';
     const block = generated.split('\n').join(eol);
     return markdown.slice(0, begin + exports.BEGIN_MARKER.length)
         + eol + eol + block + eol + eol

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

@@ -49,7 +49,10 @@ function registerPreflightCommand(program) {
         const report = await (0, checks_1.preflight)(opts.cwd ?? process.cwd());
         process.stdout.write(opts.json ? JSON.stringify(report, null, 2) + '\n' : formatReport(report));
         const code = exitCodeFor(report);
+        // `process.exit()` may truncate the JSON written immediately above when
+        // stdout is a pipe (CI, an API consumer, or a shell capture). Preserve
+        // the semantic exit code while allowing Node to flush the report.
         if (code !== 0)
-            process.exit(code);
+            process.exitCode = code;
     });
 }

package/dist/src/commands/sensors/compatibility/contract.js

@@ -3,13 +3,18 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSemgrepPolicy = parseSemgrepPolicy;
+exports.resolveSemgrepPolicy = resolveSemgrepPolicy;
 exports.parseStructuredCommand = parseStructuredCommand;
 exports.assertNoEqualPriorityOverlap = assertNoEqualPriorityOverlap;
 exports.parseSensorPack = parseSensorPack;
 const semver_1 = __importDefault(require("semver"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const contract_1 = require("../coverage/contract");
 const PACK_SCHEMA_VERSION = 2;
 const SHELL_EXECUTABLES = new Set(['sh', 'bash', 'cmd', 'powershell']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn', 'bun']);
 const ALLOWED_PROBES = new Set([
     'version',
     'eslint-print-config',
@@ -18,6 +23,9 @@ const ALLOWED_PROBES = new Set([
     'package-script-present',
     'config-present',
 ]);
+function normalizedPackageManager(value) {
+    return value.toLowerCase().replace(/\.exe$/, '');
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -62,9 +70,72 @@ function stringArray(value, source, location) {
         invalid(source, `${location} must be a nonempty array`);
     return value.map((item, index) => text(item, source, `${location}[${index}]`));
 }
+function assetArray(value, source, location, allowEmpty = false) {
+    if (!Array.isArray(value) || (!allowEmpty && value.length === 0))
+        invalid(source, `${location} must be a ${allowEmpty ? '' : 'nonempty '}array`);
+    return value.map((item, index) => asset(item, source, `${location}[${index}]`));
+}
+const SEMGREP_POLICY_REF = 'shared/semgrep-policy.json';
+const MAX_POLICY_BYTES = 64 * 1024;
+function contained(root, candidate) {
+    const prefix = root.endsWith(path_1.default.sep) ? root : root + path_1.default.sep;
+    return candidate.startsWith(prefix);
+}
+function parseSemgrepPolicy(input, source) {
+    const value = record(input, source, 'Semgrep policy');
+    fields(value, ['tool', 'toolRange', 'runtime', 'runtimeRange', 'probe'], source, 'Semgrep policy');
+    if (value.tool !== 'semgrep' || value.runtime !== 'python' || value.probe !== 'semgrep-validate') {
+        invalid(source, 'Semgrep policy must declare semgrep, python, and semgrep-validate');
+    }
+    const toolRange = text(value.toolRange, source, 'Semgrep policy.toolRange');
+    const runtimeRange = text(value.runtimeRange, source, 'Semgrep policy.runtimeRange');
+    if (semver_1.default.validRange(toolRange) === null || semver_1.default.validRange(runtimeRange) === null)
+        invalid(source, 'Semgrep policy ranges must be valid semver ranges');
+    return { tool: 'semgrep', toolRange, runtime: 'python', runtimeRange, probe: 'semgrep-validate' };
+}
+function resolveSemgrepPolicy(policyRef, source, location = 'policy') {
+    if (policyRef !== SEMGREP_POLICY_REF)
+        invalid(source, `${location}.policyRef must be the contained AWM-owned ${SEMGREP_POLICY_REF}`);
+    if (typeof source !== 'string' || !path_1.default.isAbsolute(source) || path_1.default.normalize(source) !== source || path_1.default.basename(source) !== 'pack.json') {
+        invalid(source, `${location}.policyRef requires an absolute pack.json source`);
+    }
+    const packRoot = path_1.default.dirname(source);
+    const sensorPacksRoot = path_1.default.dirname(packRoot);
+    const candidate = path_1.default.join(sensorPacksRoot, ...SEMGREP_POLICY_REF.split('/'));
+    if (!contained(sensorPacksRoot, candidate))
+        invalid(source, `${location}.policyRef escapes sensor-packs root`);
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(candidate);
+    }
+    catch {
+        invalid(source, `${location}.policyRef does not resolve to a regular policy file`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_POLICY_BYTES)
+        invalid(source, `${location}.policyRef must resolve to a bounded regular policy file`);
+    let realRoot;
+    let realPolicy;
+    try {
+        realRoot = fs_1.default.realpathSync(sensorPacksRoot);
+        realPolicy = fs_1.default.realpathSync(candidate);
+    }
+    catch {
+        invalid(source, `${location}.policyRef cannot be canonicalized`);
+    }
+    if (!contained(realRoot, realPolicy))
+        invalid(source, `${location}.policyRef escapes sensor-packs root`);
+    let parsed;
+    try {
+        parsed = JSON.parse(fs_1.default.readFileSync(realPolicy, 'utf8'));
+    }
+    catch {
+        invalid(source, `${location}.policyRef must contain valid JSON`);
+    }
+    return parseSemgrepPolicy(parsed, realPolicy);
+}
 function parseStructuredCommand(input, source) {
     const value = record(input, source, 'command');
-    fields(value, ['executable', 'resolution', 'args', 'fileInput'], source, 'command');
+    fields(value, ['executable', 'resolution', 'args', 'packageManager', 'environment', 'fileInput', 'pythonEnvironmentRoot'], source, 'command');
     const executable = text(value.executable, source, 'command.executable');
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(executable) || SHELL_EXECUTABLES.has(executable.toLowerCase().replace(/\.exe$/, ''))) {
         invalid(source, 'command.executable must not be a shell or path');
@@ -78,6 +149,29 @@ function parseStructuredCommand(input, source) {
             invalid(source, `command.args[${index}] must not embed {files}`);
     }
     const command = { executable, resolution: value.resolution, args };
+    if ('pythonEnvironmentRoot' in value) {
+        if (value.resolution !== 'python-environment' || (value.pythonEnvironmentRoot !== '.venv' && value.pythonEnvironmentRoot !== 'venv'))
+            invalid(source, 'command.pythonEnvironmentRoot must name the selected .venv or venv Python environment');
+        command.pythonEnvironmentRoot = value.pythonEnvironmentRoot;
+    }
+    const executablePackageManager = normalizedPackageManager(executable);
+    if (PACKAGE_MANAGERS.has(executablePackageManager) && !('packageManager' in value))
+        invalid(source, 'command.packageManager is required for a package-manager executable');
+    if ('packageManager' in value) {
+        if (typeof value.packageManager !== 'string' || !PACKAGE_MANAGERS.has(normalizedPackageManager(value.packageManager)))
+            invalid(source, 'command.packageManager must be npm, pnpm, yarn, or bun');
+        const packageManager = normalizedPackageManager(value.packageManager);
+        if (packageManager !== executablePackageManager)
+            invalid(source, 'command.packageManager must match executable');
+        command.packageManager = packageManager;
+    }
+    if ('environment' in value) {
+        const environment = record(value.environment, source, 'command.environment');
+        fields(environment, ['ESLINT_USE_FLAT_CONFIG'], source, 'command.environment');
+        if ((environment.ESLINT_USE_FLAT_CONFIG !== 'true' && environment.ESLINT_USE_FLAT_CONFIG !== 'false') || Object.keys(environment).length !== 1)
+            invalid(source, 'command.environment must be the exact allowlisted ESLINT_USE_FLAT_CONFIG=true or false mapping');
+        command.environment = { ESLINT_USE_FLAT_CONFIG: environment.ESLINT_USE_FLAT_CONFIG };
+    }
     if ('fileInput' in value) {
         const fileInput = record(value.fileInput, source, 'command.fileInput');
         fields(fileInput, ['placeholder', 'extensions'], source, 'command.fileInput');
@@ -99,40 +193,61 @@ function parseStructuredCommand(input, source) {
 }
 function parseVariant(input, source, location) {
     const value = record(input, source, location);
-    fields(value, ['id', 'priority', 'requirements', 'certifiedRange', 'command', 'assets', 'formatter', 'probe'], source, location);
+    fields(value, ['id', 'priority', 'requirements', 'certifiedRange', 'command', 'assets', 'formatter', 'probe', 'policyRef'], source, location);
     const certifiedRange = text(value.certifiedRange, source, `${location}.certifiedRange`);
     if (semver_1.default.validRange(certifiedRange) === null)
         invalid(source, `${location}.certifiedRange must be a valid semver range`);
     if (typeof value.priority !== 'number' || !Number.isSafeInteger(value.priority))
         invalid(source, `${location}.priority must be a safe integer`);
-    const requirements = record(value.requirements, source, `${location}.requirements`);
-    fields(requirements, ['tool', 'toolRange', 'runtime', 'runtimeRange', 'configFiles'], source, `${location}.requirements`);
-    const toolRange = text(requirements.toolRange, source, `${location}.requirements.toolRange`);
-    const runtimeRange = text(requirements.runtimeRange, source, `${location}.requirements.runtimeRange`);
+    const policy = 'policyRef' in value ? resolveSemgrepPolicy(value.policyRef, source, location) : undefined;
+    if (policy && ('requirements' in value || 'probe' in value))
+        invalid(source, `${location}.policyRef is authoritative; requirements and probe must not duplicate it`);
+    if (!policy && (!('requirements' in value) || !('probe' in value)))
+        invalid(source, `${location} requires requirements and probe when policyRef is absent`);
+    const requirements = policy ? undefined : record(value.requirements, source, `${location}.requirements`);
+    if (requirements)
+        fields(requirements, ['tool', 'toolRange', 'runtime', 'runtimeRange', 'configFiles'], source, `${location}.requirements`);
+    const toolRange = policy?.toolRange ?? text(requirements.toolRange, source, `${location}.requirements.toolRange`);
+    const runtimeRange = policy?.runtimeRange ?? text(requirements.runtimeRange, source, `${location}.requirements.runtimeRange`);
     if (semver_1.default.validRange(toolRange) === null || semver_1.default.validRange(runtimeRange) === null)
         invalid(source, `${location}.requirements ranges must be valid semver ranges`);
-    const probe = record(value.probe, source, `${location}.probe`);
-    fields(probe, ['kind'], source, `${location}.probe`);
-    if (typeof probe.kind !== 'string' || !ALLOWED_PROBES.has(probe.kind))
-        invalid(source, `${location}.probe.kind must be an allowed probe`);
+    const probe = policy ? undefined : record(value.probe, source, `${location}.probe`);
+    if (probe) {
+        fields(probe, ['kind'], source, `${location}.probe`);
+        if (typeof probe.kind !== 'string' || !ALLOWED_PROBES.has(probe.kind))
+            invalid(source, `${location}.probe.kind must be an allowed probe`);
+    }
     return {
         id: id(value.id, source, `${location}.id`),
         priority: value.priority,
         certifiedRange,
-        requirements: { tool: text(requirements.tool, source, `${location}.requirements.tool`), toolRange, runtime: text(requirements.runtime, source, `${location}.requirements.runtime`), runtimeRange, ...('configFiles' in requirements ? { configFiles: stringArray(requirements.configFiles, source, `${location}.requirements.configFiles`).map((file, index) => asset(file, source, `${location}.requirements.configFiles[${index}]`)) } : {}) },
-        assets: stringArray(value.assets, source, `${location}.assets`).map((entry, index) => asset(entry, source, `${location}.assets[${index}]`)),
+        requirements: policy
+            ? { tool: policy.tool, toolRange, runtime: policy.runtime, runtimeRange }
+            : { tool: text(requirements.tool, source, `${location}.requirements.tool`), toolRange, runtime: text(requirements.runtime, source, `${location}.requirements.runtime`), runtimeRange, ...('configFiles' in requirements ? { configFiles: stringArray(requirements.configFiles, source, `${location}.requirements.configFiles`).map((file, index) => asset(file, source, `${location}.requirements.configFiles[${index}]`)) } : {}) },
+        assets: assetArray(value.assets, source, `${location}.assets`, true),
         formatter: text(value.formatter, source, `${location}.formatter`),
-        probe: { kind: probe.kind },
+        probe: { kind: policy?.probe ?? probe.kind },
+        ...(policy ? { policyRef: SEMGREP_POLICY_REF } : {}),
         command: parseStructuredCommand(value.command, source),
     };
 }
-function assertNoEqualPriorityOverlap(variants) {
-    if (!Array.isArray(variants) || variants.length === 0)
-        throw new Error('variants must be a nonempty array');
-    const parsed = variants.map((variant, index) => parseVariant(variant, 'public overlap validator', `variants[${index}]`));
+function parseHardening(input, source) {
+    const value = record(input, source, 'hardening');
+    const names = Object.keys(value);
+    if (names.length === 0)
+        invalid(source, 'hardening must be nonempty when declared');
+    const hardening = {};
+    for (const name of names) {
+        const entry = record(value[name], source, `hardening.${name}`);
+        fields(entry, ['assets'], source, `hardening.${name}`);
+        hardening[id(name, source, 'hardening id')] = { assets: assetArray(entry.assets, source, `hardening.${name}.assets`) };
+    }
+    return hardening;
+}
+function assertNoEqualPriorityOverlapParsed(parsed) {
     for (let left = 0; left < parsed.length; left++) {
         const first = parsed[left];
-        for (let right = left + 1; right < variants.length; right++) {
+        for (let right = left + 1; right < parsed.length; right++) {
             const second = parsed[right];
             const toolRangesIntersect = semver_1.default.intersects(first.requirements.toolRange, second.requirements.toolRange);
             const runtimeRangesIntersect = semver_1.default.intersects(first.requirements.runtimeRange, second.requirements.runtimeRange);
@@ -142,6 +257,11 @@ function assertNoEqualPriorityOverlap(variants) {
         }
     }
 }
+function assertNoEqualPriorityOverlap(variants) {
+    if (!Array.isArray(variants) || variants.length === 0)
+        throw new Error('variants must be a nonempty array');
+    assertNoEqualPriorityOverlapParsed(variants.map((variant, index) => parseVariant(variant, 'public overlap validator', `variants[${index}]`)));
+}
 function parseSensor(input, source, location, variantIds) {
     const value = record(input, source, location);
     fields(value, ['applicability', 'variants', 'fast'], source, location);
@@ -154,7 +274,7 @@ function parseSensor(input, source, location, variantIds) {
         variantIds.add(variant.id);
     }
     try {
-        assertNoEqualPriorityOverlap(variants);
+        assertNoEqualPriorityOverlapParsed(variants);
     }
     catch (error) {
         invalid(source, `${location}.variants ${error instanceof Error ? error.message : 'overlap validation failed'}`);
@@ -234,7 +354,7 @@ function parseSensorPack(input, source) {
     const value = record(input, source, 'root');
     if (!('schemaVersion' in value))
         return { kind: 'legacy', pack: parseLegacyPack(value, source) };
-    fields(value, ['schemaVersion', 'name', 'description', 'detects', 'sensors', 'coverage'], source, 'root');
+    fields(value, ['schemaVersion', 'name', 'description', 'detects', 'sensors', 'coverage', 'hardening'], source, 'root');
     if (value.schemaVersion !== PACK_SCHEMA_VERSION)
         invalid(source, `unsupported pack schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2; upgrade or migrate the pack`);
     const sensorsInput = record(value.sensors, source, 'sensors');
@@ -252,10 +372,11 @@ function parseSensorPack(input, source) {
     catch (error) {
         invalid(source, `coverage.${error instanceof Error ? error.message.replace(/^.*?: /, '') : 'is invalid'}`);
     }
+    const hardening = 'hardening' in value ? parseHardening(value.hardening, source) : undefined;
     return { kind: 'v2', pack: {
             schemaVersion: PACK_SCHEMA_VERSION,
             name: id(value.name, source, 'name'), description: text(value.description, source, 'description'), detects: stringArray(value.detects, source, 'detects'),
-            sensors,
+            sensors, ...(hardening ? { hardening } : {}),
             coverage,
         } };
 }

package/dist/src/commands/sensors/compatibility/discovery.js

@@ -200,7 +200,7 @@ function discoverProjectEvidence(cwd, pack, dependencies = {}) {
     const sitePackages = environment ? pythonSitePackages(root, environment.rootParts, targetPlatform) : [];
     const toolVersions = Object.fromEntries([...tools].sort().map(tool => [tool, pythonToolVersion(root, sitePackages, tool) ?? installedPackageVersion(root, tool)]));
     return {
-        cwd: root, os: targetPlatform, runtimeVersions: { node: process.versions.node ?? null, ...(environment ? { python: environment.runtimeVersion } : {}) }, declaredToolRanges, toolVersions,
+        cwd: root, os: targetPlatform, runtimeVersions: { node: process.versions.node ?? null, ...(environment ? { python: environment.runtimeVersion } : {}) }, pythonEnvironmentRoot: environment?.rootParts[0] ?? null, declaredToolRanges, toolVersions,
         packageManager: declaredManager ?? (lockManagers.size === 1 ? [...lockManagers][0] : null), packageManagerConflict: lockManagers.size > 1,
         scripts, configFiles, paths: [...new Set([...(safeFile(root, 'package.json') ? ['package.json'] : []), ...locks, ...configFiles])].sort(),
     };

package/dist/src/commands/sensors/compatibility/live.js

@@ -11,13 +11,42 @@ const discovery_1 = require("./discovery");
 const resolve_1 = require("./resolve");
 const probe_1 = require("./probe");
 const path_1 = __importDefault(require("path"));
+/**
+ * Python package metadata is evidence only for a contained virtual environment.
+ * A v2 command that names a Python-runtime tool must therefore resolve through
+ * that same environment — never a same-named executable inherited from PATH.
+ *
+ * Keep this at the live pack boundary so the command used by probing, init's
+ * materialized manifest, and `sensors run` is one identical structured command.
+ */
+function containedRuntimeCommand(variant, pythonEnvironmentRoot) {
+    if (variant.requirements.runtime !== 'python')
+        return variant;
+    return {
+        ...variant,
+        command: {
+            ...variant.command,
+            resolution: 'python-environment',
+            ...(pythonEnvironmentRoot ? { pythonEnvironmentRoot } : {}),
+        },
+    };
+}
+function bindContainedRuntimeCommands(pack, pythonEnvironmentRoot) {
+    return {
+        ...pack,
+        sensors: Object.fromEntries(Object.entries(pack.sensors).map(([name, sensor]) => [
+            name,
+            { ...sensor, variants: sensor.variants.map(variant => containedRuntimeCommand(variant, pythonEnvironmentRoot)) },
+        ])),
+    };
+}
 /**
  * Re-resolve a v2 pack from the configured registry and current project evidence.
  * Manifest evidence is intentionally not an input: it is an init-time trace, not a
  * live certification source. Probes are bounded and structured through the shared
  * compatibility probe runner.
  */
-async function resolveLiveCompatibility(cwd, packName, registryRoot) {
+async function resolveLiveCompatibility(cwd, packName, registryRoot, options = {}) {
     if (typeof cwd !== 'string' || cwd.trim() === '')
         throw new Error('cwd must be a non-empty path');
     if (typeof packName !== 'string' || !/^[a-z][a-z0-9-]*$/.test(packName))
@@ -31,29 +60,33 @@ async function resolveLiveCompatibility(cwd, packName, registryRoot) {
     const parsed = (0, contract_1.parseSensorPack)(JSON.parse(source.content), source.path);
     if (parsed.kind !== 'v2')
         throw new Error(`sensor pack "${packName}" does not provide a v2 compatibility contract`);
-    return resolveParsedPackCompatibility(cwd, parsed.pack);
+    return resolveParsedPackCompatibility(cwd, parsed.pack, options);
 }
 /** Resolve a pre-parsed v2 pack. Init uses this when given an explicit registry root. */
-async function resolveParsedPackCompatibility(cwd, pack) {
+async function resolveParsedPackCompatibility(cwd, pack, options = {}) {
     if (typeof cwd !== 'string' || cwd.trim() === '')
         throw new Error('cwd must be a non-empty path');
     if (!pack || typeof pack !== 'object' || pack.schemaVersion !== 2)
         throw new Error('pack must be a parsed v2 sensor pack');
     const evidence = (0, discovery_1.discoverProjectEvidence)(cwd, pack);
-    const initial = (0, resolve_1.resolveProjectCompatibility)(pack, evidence).sensors;
+    const executionPack = bindContainedRuntimeCommands(pack, evidence.pythonEnvironmentRoot);
+    const resolutionEvidence = { ...evidence, ...(options.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}) };
+    const initial = (0, resolve_1.resolveProjectCompatibility)(executionPack, resolutionEvidence).sensors;
     const sensors = {};
-    for (const [name, sensor] of Object.entries(pack.sensors)) {
+    for (const [name, sensor] of Object.entries(executionPack.sensors)) {
         const base = initial[name];
         const variant = base.variantId === null ? null : sensor.variants.find(candidate => candidate.id === base.variantId) ?? null;
         const probe = variant
             ? await (0, probe_1.runCompatibilityProbe)(variant.probe, {
                 cwd,
                 toolExecutable: variant.command.executable,
+                toolResolution: variant.command.resolution,
+                pythonEnvironmentRoot: variant.command.pythonEnvironmentRoot,
                 configFiles: evidence.configFiles,
                 scripts: evidence.scripts,
             })
             : null;
-        sensors[name] = (0, resolve_1.resolveProjectCompatibility)({ ...pack, sensors: { [name]: sensor } }, { ...evidence, probe: probe ?? undefined }).sensors[name];
+        sensors[name] = (0, resolve_1.resolveProjectCompatibility)({ ...executionPack, sensors: { [name]: sensor } }, { ...resolutionEvidence, probe: probe ?? undefined }).sensors[name];
     }
-    return { pack, sensors };
+    return { pack: executionPack, sensors };
 }

package/dist/src/commands/sensors/compatibility/manifest.js

@@ -135,7 +135,7 @@ function parseLegacyManifest(value, source) {
 }
 function parseV2Sensor(input, source, location) {
     const value = record(input, source, location);
-    fields(value, ['enabled', 'fast', 'variantId', 'command', 'assets', 'initializedCompatibility'], source, location);
+    fields(value, ['enabled', 'fast', 'variantId', 'command', 'assets', 'policyRef', 'initializedCompatibility'], source, location);
     if (typeof value.enabled !== 'boolean')
         invalid(source, `${location}.enabled must be a boolean`);
     const sensor = {
@@ -152,7 +152,12 @@ function parseV2Sensor(input, source, location) {
     if (sensor.initializedCompatibility.state === 'certified' && !semver_1.default.satisfies(sensor.initializedCompatibility.toolVersion, sensor.initializedCompatibility.certifiedRange))
         invalid(source, `${location}.initializedCompatibility.toolVersion must satisfy certifiedRange`);
     if ('assets' in value)
-        sensor.assets = stringArray(value.assets, source, `${location}.assets`, false).map((entry, index) => asset(entry, source, `${location}.assets[${index}]`));
+        sensor.assets = stringArray(value.assets, source, `${location}.assets`, true).map((entry, index) => asset(entry, source, `${location}.assets[${index}]`));
+    if ('policyRef' in value) {
+        if (value.policyRef !== 'shared/semgrep-policy.json')
+            invalid(source, `${location}.policyRef must be the contained AWM-owned shared/semgrep-policy.json`);
+        sensor.policyRef = value.policyRef;
+    }
     if ('fast' in value) {
         if (typeof value.fast !== 'boolean')
             invalid(source, `${location}.fast must be a boolean`);
@@ -167,7 +172,7 @@ function provenanceRoot(value, source) {
     return parsed;
 }
 function parseV2Manifest(value, source) {
-    fields(value, ['schemaVersion', 'pack', 'registryRoot', 'sensors', 'concurrency'], source, 'root');
+    fields(value, ['schemaVersion', 'pack', 'packSelection', 'registryRoot', 'sensors', 'concurrency'], source, 'root');
     if (value.schemaVersion !== 2)
         invalid(source, `unsupported manifest schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2; upgrade or migrate the manifest`);
     const pack = id(value.pack, source, 'pack');
@@ -176,6 +181,11 @@ function parseV2Manifest(value, source) {
     for (const name of Object.keys(sensorsInput))
         sensors[id(name, source, 'sensor id')] = parseV2Sensor(sensorsInput[name], source, `sensors.${name}`);
     const manifest = { schemaVersion: 2, pack, sensors };
+    if ('packSelection' in value) {
+        if (value.packSelection !== 'explicit')
+            invalid(source, 'packSelection must be "explicit" when present');
+        manifest.packSelection = 'explicit';
+    }
     if ('registryRoot' in value)
         manifest.registryRoot = provenanceRoot(value.registryRoot, source);
     if ('concurrency' in value) {

package/dist/src/commands/sensors/compatibility/materialize.js

@@ -7,6 +7,7 @@ exports.materializeResolvedSensors = materializeResolvedSensors;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const manifest_1 = require("./manifest");
+const contract_1 = require("./contract");
 function stableId(value, label) {
     if (typeof value !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value))
         throw new Error(`${label} must be a stable lowercase id`);
@@ -81,7 +82,14 @@ function materializeResolvedSensors(input) {
             throw new Error('materialized sensor must be v2');
         sensors[name] = parsed.pack.sensors[name];
     }
-    const manifest = { schemaVersion: 2, pack, sensors, ...(input.registryRoot ? { registryRoot: input.registryRoot } : {}) };
+    const manifest = { schemaVersion: 2, pack, sensors, ...(input.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}), ...(input.registryRoot ? { registryRoot: input.registryRoot } : {}) };
+    // A policy reference is deliberately not a materialized asset. Resolve it here
+    // from the registry-owned sibling only, so a manifest cannot turn arbitrary
+    // registry content into a project write through a cosmetic policy field.
+    for (const [name, sensor] of Object.entries(sensors)) {
+        if (sensor.policyRef)
+            (0, contract_1.resolveSemgrepPolicy)(sensor.policyRef, path_1.default.join(packRoot, 'pack.json'), `sensors.${name}`);
+    }
     const selected = [...new Set(Object.values(sensors).flatMap(sensor => sensor.assets ?? []))].map((asset, index) => containedAsset(asset, `assets[${index}]`)).sort();
     const prior = priorAssets(projectRoot);
     const configured = [];