agentic-workflow-manager 9.7.1 → 9.8.0

package/README.md

@@ -41,9 +41,13 @@ This generates the runnable output under `dist/index.js`.
 ### 4. Running the Tests
 Before submitting a PR, ensure that the core discovery/executor functionality passes the existing test suite:
 ```bash
+npm run native:build
 npm test
 ```
-The goal is to maintain 100% passing tests for any new CLI parameter flags.
+`native:build` creates the ignored, host-specific `secure-fs` artifact required
+by the integration fixtures; it must be run again after a clean checkout or a
+change under `native/`. The goal is to maintain 100% passing tests for any new
+CLI parameter flags.
 
 ### 5. Local Execution (Testing changes locally)
 

package/dist/src/commands/job/exec-wrapper.js

@@ -17,19 +17,33 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const process_1 = require("../../core/journal/process");
+const paths_1 = require("../../core/journal/paths");
+const types_1 = require("../../core/journal/types");
+const native_bridge_1 = require("../../core/secure-fs/native-bridge");
 const fingerprint_1 = require("../../core/journal/fingerprint");
 const redact_1 = require("../../core/journal/redact");
 const atomic_file_1 = require("../../core/atomic-file");
+function validateSidecarIdentity(logsRoot, jobId, nonce) {
+    if (typeof logsRoot !== 'string' || logsRoot.length === 0 || logsRoot.length > 4096 || /[\u0000-\u001F\u007F]/.test(logsRoot)
+        || typeof jobId !== 'string' || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$/.test(jobId)
+        || typeof nonce !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(nonce)
+        || jobId.length + nonce.length > 230)
+        throw new Error('unsafe or unbounded sidecar identity');
+}
 function claimPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.claim`);
 }
 function identityPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.identity.json`);
 }
 function resultPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.result.json`);
 }
 function logPath(logsRoot, jobId, nonce) {
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     return path_1.default.join(logsRoot, `${jobId}.${nonce}.log`);
 }
 function replayVerdict(logsRoot, jobId, nonce) {
@@ -45,11 +59,46 @@ const MAX_LOG_BYTES = 1024 * 1024; // retencion acotada (R2.5)
 // dispara, tipicamente entregados en 1 tick del event loop) sin acercarse a
 // una espera perceptible si un descendiente hereda los fds y nunca cierra.
 const STDIO_GRACE_MS = 300;
+/** Only a committed generation intent may suppress controller output. A user
+ * job with the same name retains normal verifier logs. Never persist model
+ * output (which may include prompts/source bodies) in generation custody. */
+function isCommittedController(logsRoot, repoRoot, jobId, nonce, argv) {
+    if (!/^controller-gen-[1-9][0-9]*$/.test(jobId))
+        return false;
+    try {
+        const bytes = native_bridge_1.secureFs.readRegularFile(path_1.default.resolve(logsRoot, '..', 'state.json'), 1024 * 1024).bytes;
+        const state = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (!(0, types_1.isWellFormedState)(state))
+            throw new Error('controller custody journal invalid');
+        const actual = fs_1.default.lstatSync(logsRoot, { bigint: true });
+        const expected = fs_1.default.lstatSync((0, paths_1.logsDir)(repoRoot, state.branch), { bigint: true });
+        if (!actual.isDirectory() || actual.isSymbolicLink() || !expected.isDirectory() || expected.isSymbolicLink()
+            || actual.ino === 0n || actual.dev !== expected.dev || actual.ino !== expected.ino)
+            throw new Error('controller custody directory identity invalid');
+        const committed = state.generations.some(gen => gen.controllerJobId === jobId && jobId === `controller-gen-${gen.n}`
+            && gen.spawnNonce === nonce && gen.resumePrompt === undefined && (0, types_1.isControllerRecoveryAction)(gen.resumeAction)
+            && gen.launchArgvDigest === (0, process_1.argvDigest)(argv));
+        if (committed)
+            return true;
+        const ordinary = state.jobs[jobId];
+        if (ordinary?.spawnNonce === nonce && (0, process_1.argvDigest)(ordinary.argv) === (0, process_1.argvDigest)(argv))
+            return false;
+        throw new Error('controller custody launch identity unproven');
+    }
+    catch {
+        throw new Error('controller custody identity unavailable or unsafe: refusing launch before claim');
+    }
+}
 async function runExecWrapper(opts) {
     const { logsRoot, jobId, nonce, argv, cwd } = opts;
+    validateSidecarIdentity(logsRoot, jobId, nonce);
     const repoRoot = opts.repoRoot ?? process.cwd();
-    if (argv.length === 0)
-        throw new Error('argv vacio');
+    if (!Array.isArray(argv) || argv.length === 0 || argv.length > 256
+        || argv.some(argument => typeof argument !== 'string' || argument.length > 65536 || argument.includes('\0'))
+        || argv[0].length === 0 || argv.reduce((bytes, argument) => bytes + Buffer.byteLength(argument, 'utf8'), 0) > 1024 * 1024)
+        throw new Error('argv invalid or unbounded');
+    const safeCwd = (0, fingerprint_1.resolveWorkingDirectory)(repoRoot, cwd).absolute;
+    const omitControllerOutput = isCommittedController(logsRoot, repoRoot, jobId, nonce, argv);
     fs_1.default.mkdirSync(logsRoot, { recursive: true, mode: 0o700 });
     // (1) claim exclusivo DURABLE — wx + fsync de archivo y de directorio
     let fd;
@@ -77,7 +126,6 @@ async function runExecWrapper(opts) {
     // process group por job, independiente del supervisor (R4.7: shell:false,
     // argv como array, secretos solo por referencia de entorno).
     const [exe, ...args] = argv;
-    const safeCwd = (0, fingerprint_1.resolveWorkingDirectory)(repoRoot, cwd).absolute;
     const child = (0, child_process_1.spawn)(exe, args, {
         cwd: safeCwd, shell: false, detached: true,
         env: { ...process.env, [process_1.NONCE_ENV]: nonce },
@@ -105,6 +153,8 @@ async function runExecWrapper(opts) {
     const outputChunks = [];
     const logFile = logPath(logsRoot, jobId, nonce);
     const capture = (chunk) => {
+        if (omitControllerOutput)
+            return;
         if (captured >= MAX_LOG_BYTES)
             return;
         const accepted = chunk.subarray(0, MAX_LOG_BYTES - captured);

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

@@ -1,13 +1,39 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.exitCodeFor = exitCodeFor;
 exports.formatReport = formatReport;
 exports.registerPlanCommand = registerPlanCommand;
 const validate_1 = require("../../core/plan/validate");
+const admission_1 = require("../../core/admission");
+const check_1 = require("../../core/currentness/check");
+const run_1 = require("../sensors/run");
+const config_1 = require("../../utils/config");
+const providers_1 = require("../../providers");
+const registries_1 = require("../../core/registries");
+const registry_contracts_1 = require("../../core/admission/registry-contracts");
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const store_1 = require("../../core/journal/store");
+const migration_1 = require("../../core/migration");
 const SUPPORTED_SCHEMA = 'compact-slices/v1';
 const MAX_PATH_LENGTH = 4096;
 const MAX_DIAGNOSTICS = 20;
 const MAX_DIAGNOSTIC_LENGTH = 4096;
+function journalObservation(cwd) {
+    try {
+        const branch = (0, child_process_1.execFileSync)('git', ['branch', '--show-current'], { cwd, encoding: 'utf8', stdio: 'pipe' }).trim();
+        if (!branch)
+            return { journalState: null, journalCorrupt: true };
+        const journal = (0, store_1.readJournal)(cwd, branch);
+        return { journalState: journal.state, journalCorrupt: journal.corrupt };
+    }
+    catch {
+        return { journalState: null, journalCorrupt: true };
+    }
+}
 function assertText(value, name) {
     if (typeof value !== 'string' || value.length === 0 || value.length > MAX_PATH_LENGTH || value.startsWith('--') || /[\u0000-\u001F\u007F-\u009F]/.test(value)) {
         throw new Error(`${name} must be a non-empty path without control characters`);
@@ -19,6 +45,15 @@ function terminalSafe(value) {
 function assertDependencies(deps) {
     if (!deps || typeof deps.validatePlanFile !== 'function')
         throw new Error('validatePlanFile must be a function');
+    if (deps.admitPlan !== undefined && typeof deps.admitPlan !== 'function')
+        throw new Error('admitPlan must be a function');
+}
+function admissionOutput(report, json) {
+    report = (0, admission_1.sanitizeAdmissionReport)(report);
+    if (json)
+        return `${JSON.stringify(report)}\n`;
+    const diagnostic = report.diagnostics[0];
+    return `Plan admission: ${report.state}${report.provider ? ` (${terminalSafe(report.provider)})` : ''}${diagnostic ? `\n- ${terminalSafe(diagnostic.code)}: ${terminalSafe(diagnostic.message)}` : ''}\n`;
 }
 function boundedDiagnostics(diagnostics) {
     if (!Array.isArray(diagnostics))
@@ -34,16 +69,42 @@ function boundedDiagnostics(diagnostics) {
         };
     });
 }
+function assertReport(report) {
+    if (!report || typeof report !== 'object' || Array.isArray(report))
+        throw new Error('plan validator returned an invalid report');
+    switch (report.state) {
+        case 'valid':
+            (0, validate_1.assertVerifiedValidPlanReport)(report);
+            return;
+        case 'migration-required':
+            if (report.reason !== 'unmarked-plan')
+                throw new Error('plan validator returned an invalid migration reason');
+            return;
+        case 'invalid':
+            boundedDiagnostics(report.diagnostics);
+            return;
+        case 'unsupported':
+            if (typeof report.schema !== 'string' || report.schema.length === 0 || report.schema.length > MAX_PATH_LENGTH) {
+                throw new Error('plan validator returned an invalid unsupported schema');
+            }
+            boundedDiagnostics(report.diagnostics);
+            return;
+        default:
+            throw new Error('plan validator returned an unknown report state');
+    }
+}
 function reportPayload(report, planPath) {
+    assertReport(report);
     switch (report.state) {
         case 'valid':
             return {
                 state: report.state, path: planPath, schema: report.schema, planId: report.manifest.planId,
+                planDigest: report.planDigest,
                 requirements: report.manifest.requirements.length, sources: report.manifest.sources.length,
                 commands: report.manifest.commands.length, slices: report.manifest.slices.length, completeOwnership: true,
             };
-        case 'legacy':
-            return { state: report.state, path: planPath, message: 'existing full-quality path applies; compact optimization was not requested.' };
+        case 'migration-required':
+            return { state: report.state, path: planPath, reason: report.reason };
         case 'invalid':
             return { state: report.state, path: planPath, diagnostics: boundedDiagnostics(report.diagnostics) };
         case 'unsupported':
@@ -56,15 +117,16 @@ function reportPayload(report, planPath) {
     }
 }
 function exitCodeFor(report) {
-    return report.state === 'valid' || report.state === 'legacy' ? 0 : 2;
+    assertReport(report);
+    return report.state === 'valid' ? 0 : 2;
 }
 function formatReport(report, planPath) {
     const payload = reportPayload(report, planPath);
     switch (report.state) {
         case 'valid':
             return `Plan validation: valid "${terminalSafe(planPath)}" (${terminalSafe(report.schema)}; ${payload.slices} slices; ${payload.requirements} requirements; complete ownership)\n`;
-        case 'legacy':
-            return `Plan validation: legacy "${terminalSafe(planPath)}" — existing full-quality path applies; compact optimization was not requested.\n`;
+        case 'migration-required':
+            return `Plan validation: migration-required "${terminalSafe(planPath)}" (${terminalSafe(report.reason)})\nMigrate this plan to compact-slices/v1 before execution.\n`;
         case 'invalid':
             return `Plan validation: invalid "${terminalSafe(planPath)}"\n${payload.diagnostics.map(diagnostic => `- ${terminalSafe(diagnostic.code)}: ${terminalSafe(diagnostic.message)}${diagnostic.field ? ` (${terminalSafe(diagnostic.field)})` : ''}`).join('\n')}\n`;
         case 'unsupported':
@@ -73,11 +135,25 @@ function formatReport(report, planPath) {
             throw new Error('plan validator returned an unknown report state');
     }
 }
-function registerPlanCommand(program, deps = { validatePlanFile: validate_1.validatePlanFile }) {
+function registerPlanCommand(program, deps = { validatePlanFile: validate_1.validatePlanFile, admitPlan: admission_1.admitPlan }) {
     if (!program || typeof program.command !== 'function')
         throw new Error('program must be a Commander command');
     assertDependencies(deps);
     const plan = program.command('plan').description('inspect plan contracts');
+    plan.command('migration-facts <plan-path>')
+        .description('collect read-only durable migration facts')
+        .option('--cwd <path>')
+        .option('--historical-root <path>', 'admitted sibling #148 worktree')
+        .requiredOption('--issue <https-url...>', 'durable issue links, including #126')
+        .option('--json')
+        .action((planPath, options) => {
+        assertText(planPath, 'plan path');
+        const cwd = options.cwd ?? process.cwd();
+        assertText(cwd, '--cwd');
+        const report = options.historicalRoot ? (0, migration_1.collectIssue148HistoricalFacts)(options.historicalRoot, options.issue) : (deps.collectMigrationFacts ?? migration_1.collectMigrationFacts)(planPath, cwd, options.issue);
+        process.stdout.write(options.json ? `${JSON.stringify(report)}\n` : `Migration facts: ${report.state}\n`);
+        process.exitCode = report.state === 'supported-completion' ? 0 : 2;
+    });
     plan
         .command('validate <plan-path>')
         .description('validate a compact plan without modifying it')
@@ -95,4 +171,46 @@ function registerPlanCommand(program, deps = { validatePlanFile: validate_1.vali
         const code = exitCodeFor(report);
         process.exitCode = code;
     });
+    plan
+        .command('admit <plan-path>')
+        .description('read-only fail-closed compact-plan admission')
+        .requiredOption('--provider <target>', 'target provider')
+        .requiredOption('--cwd <path>', 'repository root for plan containment and source resolution')
+        .option('--execution-mode <mode>', 'explicit override: interactivo or desatendido')
+        .option('--require-current', 'require authoritative consumed-contract currentness')
+        .option('--verify-sensors', 'require an empirical sensor pass')
+        .option('--json', 'emit one stable JSON report')
+        .action(async (planPath, options) => {
+        assertText(planPath, 'plan path');
+        assertText(options.cwd, '--cwd');
+        assertText(options.provider, '--provider');
+        const admission = deps.admitPlan ?? admission_1.admitPlan;
+        const preferences = deps.readPreferences ?? config_1.readPreferences;
+        const currentnessCheck = deps.checkCurrentness ?? check_1.checkCurrentness;
+        const sensorRun = deps.runSensors ?? run_1.runSensors;
+        const registryInventory = deps.listRegistries ?? registries_1.listRegistries;
+        const planReport = deps.validatePlanFile(planPath, options.cwd);
+        // The mode comes from the same authenticated bytes/digest that produced
+        // planReport. Never reopen the path to parse a mutable header.
+        const executionMode = options.executionMode === undefined
+            ? planReport.state === 'valid' ? (planReport.executionMode ?? 'interactivo') : 'interactivo'
+            : options.executionMode === 'desatendido' ? 'desatendido' : options.executionMode === 'interactivo' ? 'interactivo' : options.executionMode;
+        const journal = executionMode === 'desatendido' ? journalObservation(options.cwd) : {};
+        const normalizedPlanPath = path_1.default.relative(options.cwd, path_1.default.resolve(options.cwd, planPath)).replace(/\\/g, '/');
+        const enabledAgents = preferences().enabledAgents;
+        // The documented order is plan, provider, currentness, sensors, journal,
+        // capabilities. Do not call the full composer early: that would resolve a
+        // capability before empirical evidence gates have had their ordered turn.
+        const earlyBoundary = planReport.state !== 'valid' || !(0, providers_1.isAgentTarget)(options.provider) || !enabledAgents.includes(options.provider);
+        if (earlyBoundary) {
+            const report = await admission({ plan: planReport, provider: options.provider, cwd: options.cwd, enabledAgents, executionMode, planPath: normalizedPlanPath, ...journal });
+            process.stdout.write(admissionOutput(report, options.json === true));
+            process.exitCode = 2;
+            return;
+        }
+        const report = await (0, registry_contracts_1.admitRegistryPlan)({ plan: planReport, provider: options.provider, cwd: options.cwd, enabledAgents, executionMode, planPath: normalizedPlanPath, ...journal, requireCurrent: options.requireCurrent === true, verifySensors: options.verifySensors === true }, { admitPlan: admission, listRegistries: registryInventory, checkCurrentness: currentnessCheck, runSensors: sensorRun });
+        process.stdout.write(admissionOutput(report, options.json === true));
+        if (report.state !== 'admitted')
+            process.exitCode = 2;
+    });
 }

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

@@ -51,7 +51,7 @@ function declaration(mode, reason) {
     return { schemaVersion: 3, mode, reason };
 }
 function digest(bytes) { return (0, crypto_1.createHash)('sha256').update(bytes).digest('hex'); }
-async function projectSensors(projectRoot, registryRoot, requestedPack, packageRoot) {
+async function projectSensors(projectRoot, registryRoot, requestedPack, packageRoot, explicitPackSelection = requestedPack !== undefined) {
     const detectionRoot = packageRoot ? path_1.default.resolve(projectRoot, packageRoot) : projectRoot;
     const detected = (0, detection_1.detectStack)(detectionRoot);
     const pack = requestedPack ?? detected.pack;
@@ -76,7 +76,9 @@ async function projectSensors(projectRoot, registryRoot, requestedPack, packageR
         return { reason: 'source-unsupported', remedy: 'install-a-v2-sensor-pack' };
     let live;
     try {
-        live = await (0, live_1.resolveParsedPackCompatibility)(detectionRoot, parsed.pack);
+        live = explicitPackSelection
+            ? await (0, live_1.resolveParsedPackCompatibility)(detectionRoot, parsed.pack, { packSelection: 'explicit' })
+            : await (0, live_1.resolveParsedPackCompatibility)(detectionRoot, parsed.pack);
     }
     catch {
         return { reason: 'compatibility-unresolvable', remedy: 'repair-project-tools-or-select-another-mode' };
@@ -84,6 +86,8 @@ async function projectSensors(projectRoot, registryRoot, requestedPack, packageR
     const sensors = {};
     for (const [name, packSensor] of Object.entries(live.pack.sensors)) {
         const evidence = live.sensors[name];
+        if (evidence.state === 'not-applicable')
+            continue;
         const variant = evidence.variantId === null ? undefined : packSensor.variants.find(item => item.id === evidence.variantId);
         if (!variant)
             return { reason: 'sensor-variant-unresolvable', remedy: 'repair-project-tools-or-select-another-mode' };
@@ -109,8 +113,32 @@ async function planSensorBootstrap(cwd = process.cwd(), input = {}) {
             }
             return { kind: 'noop', projectRoot: project.projectRoot, manifestPath: project.manifestPath, changes: [], dryRun: opts.dryRun };
         }
-        if (project.manifest.kind === 'legacy')
-            return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'legacy-v1-preserved', 'migrate-the-manifest-explicitly');
+        if (project.manifest.kind === 'legacy') {
+            // Legacy manifests can carry arbitrary commands and per-sensor
+            // semantics that a v3 pack cannot prove equivalent. Replacing
+            // them is therefore a deliberate opt-in, never an automatic
+            // side effect of inspection or an unqualified bootstrap.
+            if (opts.mode !== 'project-sensors') {
+                return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'legacy-replacement-requires-project-sensors-mode', 'rerun-bootstrap-with-mode-project-sensors');
+            }
+            // The legacy pack name identifies the source to migrate, but must not
+            // activate v2 sensors which require an explicit project opt-in.
+            const planned = await projectSensors(project.projectRoot, opts.registryRoot, project.manifest.pack.pack, undefined, false);
+            if ('reason' in planned)
+                return blocked(project.projectRoot, project.manifestPath, opts.dryRun, planned.reason, planned.remedy, 'candidates' in planned ? planned.candidates : undefined);
+            try {
+                const original = fs_1.default.readFileSync(project.manifestPath);
+                return {
+                    kind: 'migrate', projectRoot: project.projectRoot, manifestPath: project.manifestPath,
+                    changes: planned.changes.map((change, index) => index === 0 ? { ...change, action: 'replace' } : change),
+                    dryRun: opts.dryRun, migration: { kind: 'legacy-v1', manifest: planned.manifest }, source: planned.source,
+                    originalDigest: digest(original),
+                };
+            }
+            catch {
+                return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'legacy-manifest-unreadable', 'repair-the-manifest-before-bootstrap');
+            }
+        }
         let source;
         try {
             source = (0, source_1.resolveSensorSource)(project.manifest, { registries: (0, registries_1.listRegistries)() });
@@ -152,7 +180,10 @@ function applySensorBootstrap(plan) {
         const current = fs_1.default.readFileSync(plan.manifestPath);
         if (digest(current) !== plan.originalDigest)
             throw new Error('bootstrap migration plan is stale: manifest changed after planning');
-        (0, migrate_2.replaceV2ManifestWithV3)(plan.manifestPath, plan.migration.candidate, plan.source);
+        if ('kind' in plan.migration)
+            (0, migrate_1.replaceLegacyManifestWithV3)(plan.manifestPath, plan.migration.manifest, plan.source);
+        else
+            (0, migrate_2.replaceV2ManifestWithV3)(plan.manifestPath, plan.migration.candidate, plan.source);
         return 'migrated';
     }
     if (plan.manifest.mode === 'project-sensors') {

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

@@ -216,10 +216,21 @@ function parseVariant(input, source, location) {
     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 = policy ? undefined : record(value.probe, source, `${location}.probe`);
+    let probeScript;
     if (probe) {
-        fields(probe, ['kind'], source, `${location}.probe`);
+        fields(probe, ['kind', 'script'], source, `${location}.probe`);
         if (typeof probe.kind !== 'string' || !ALLOWED_PROBES.has(probe.kind))
             invalid(source, `${location}.probe.kind must be an allowed probe`);
+        // Historical schema-v2 packs remain readable. An unnamed probe cannot
+        // certify compatibility; the probe runner rejects it as unverifiable.
+        if (probe.kind === 'package-script-present' && 'script' in probe) {
+            probeScript = text(probe.script, source, `${location}.probe.script`);
+            if (!/^[A-Za-z0-9][A-Za-z0-9:_-]*$/.test(probeScript))
+                invalid(source, `${location}.probe.script must be a package script name`);
+        }
+        else if (probe.kind !== 'package-script-present' && 'script' in probe) {
+            invalid(source, `${location}.probe.script is only valid for package-script-present`);
+        }
     }
     const changedCommand = 'changedCommand' in value ? parseStructuredCommand(value.changedCommand, source) : undefined;
     if (changedCommand && !changedCommand.fileInput)
@@ -234,7 +245,7 @@ function parseVariant(input, source, location) {
                         invalid(source, `${location}.requirements.packageJsonFields[${index}] must be a stable package.json field`); return field; }) } : {}) },
         assets: assetArray(value.assets, source, `${location}.assets`, true),
         formatter: text(value.formatter, source, `${location}.formatter`),
-        probe: { kind: policy?.probe ?? probe.kind },
+        probe: { kind: policy?.probe ?? probe.kind, ...(probeScript ? { script: probeScript } : {}) },
         ...(policy ? { policyRef: SEMGREP_POLICY_REF } : {}),
         command: parseStructuredCommand(value.command, source),
         ...(changedCommand ? { changedCommand } : {}),
@@ -295,8 +306,12 @@ function parseSensor(input, source, location, variantIds) {
         applicability.allFiles = stringArray(applicabilityInput.allFiles, source, `${location}.applicability.allFiles`).map((file, index) => asset(file, source, `${location}.applicability.allFiles[${index}]`));
     if ('anyFiles' in applicabilityInput)
         applicability.anyFiles = stringArray(applicabilityInput.anyFiles, source, `${location}.applicability.anyFiles`).map((file, index) => asset(file, source, `${location}.applicability.anyFiles[${index}]`));
-    if ('kind' in applicabilityInput)
-        applicability.kind = text(applicabilityInput.kind, source, `${location}.applicability.kind`);
+    if ('kind' in applicabilityInput) {
+        const kind = text(applicabilityInput.kind, source, `${location}.applicability.kind`);
+        if (kind !== 'explicit-or-supported-language' && kind !== 'explicit-opt-in')
+            invalid(source, `${location}.applicability.kind must be a supported applicability kind`);
+        applicability.kind = kind;
+    }
     if (Object.keys(applicability).length === 0)
         invalid(source, `${location}.applicability must declare a condition`);
     if ('fast' in value && typeof value.fast !== 'boolean')

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

@@ -176,6 +176,7 @@ function discoverProjectEvidence(cwd, pack, dependencies = {}) {
     const declaredManager = typeof pkg?.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
     if (declaredManager)
         lockManagers.add(declaredManager);
+    const packageManager = declaredManager ?? (lockManagers.size === 1 ? [...lockManagers][0] : null);
     const configCandidates = new Set(COMMON_CONFIGS);
     if ('schemaVersion' in pack) {
         for (const marker of pack.detects)
@@ -193,16 +194,35 @@ function discoverProjectEvidence(cwd, pack, dependencies = {}) {
     const packageJsonFields = Object.keys(pkg ?? {}).filter(field => /^[A-Za-z][A-Za-z0-9]*$/.test(field)).sort();
     const declaredToolRanges = { ...stringMap(pkg?.dependencies), ...stringMap(pkg?.devDependencies), ...stringMap(pkg?.peerDependencies) };
     const tools = new Set();
+    const pathTools = new Set();
     if ('schemaVersion' in pack)
         for (const sensor of Object.values(pack.sensors))
-            for (const variant of sensor.variants)
+            for (const variant of sensor.variants) {
                 tools.add(variant.requirements.tool);
+                if (variant.command?.resolution === 'path' && variant.command.packageManager === variant.requirements.tool)
+                    pathTools.add(variant.requirements.tool);
+            }
     const environment = pythonEnvironment(root);
     const sitePackages = environment ? pythonSitePackages(root, environment.rootParts, targetPlatform) : [];
-    const toolVersions = Object.fromEntries([...tools].sort().map(tool => [tool, pythonToolVersion(root, sitePackages, tool) ?? installedPackageVersion(root, tool)]));
+    const toolVersions = {};
+    const toolProvenance = {};
+    for (const tool of [...tools].sort()) {
+        if (pathTools.has(tool) && packageManager === tool) {
+            // Discovery/status is read-only. A PATH executable is not inspected or
+            // executed here; callers that already possess trusted runtime evidence
+            // may inject it explicitly for an execution-time compatibility check.
+            toolVersions[tool] = exactVersion(dependencies.pathToolVersion?.(tool) ?? null);
+            toolProvenance[tool] = toolVersions[tool] === null ? null : 'path';
+        }
+        else {
+            const pythonVersion = pythonToolVersion(root, sitePackages, tool);
+            toolVersions[tool] = pythonVersion ?? installedPackageVersion(root, tool);
+            toolProvenance[tool] = pythonVersion ? 'python-environment' : toolVersions[tool] ? 'node-modules-bin' : null;
+        }
+    }
     return {
         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,
+        toolProvenance, packageManager, packageManagerConflict: lockManagers.size > 1,
         scripts, configFiles, packageJsonFields, paths: [...new Set([...(safeFile(root, 'package.json') ? ['package.json'] : []), ...locks, ...configFiles])].sort(),
     };
 }

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

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindContainedRuntimeCommands = bindContainedRuntimeCommands;
 exports.resolveLiveCompatibility = resolveLiveCompatibility;
 exports.resolveParsedPackCompatibility = resolveParsedPackCompatibility;
 const pack_source_1 = require("./pack-source");
@@ -11,6 +12,22 @@ const discovery_1 = require("./discovery");
 const resolve_1 = require("./resolve");
 const probe_1 = require("./probe");
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const semver_1 = __importDefault(require("semver"));
+/** Execution-time evidence only. Status/discovery never invokes this resolver. */
+function pathPackageManagerVersion(tool) {
+    if (!['npm', 'pnpm', 'yarn', 'bun'].includes(tool))
+        return null;
+    try {
+        const result = (0, child_process_1.spawnSync)(tool, ['--version'], { cwd: process.cwd(), shell: false, encoding: 'utf8', timeout: 5_000, maxBuffer: 1024, windowsHide: true, stdio: 'pipe' });
+        if (result.error || result.status !== 0 || result.signal || typeof result.stdout !== 'string' || result.stdout.length > 256)
+            return null;
+        return semver_1.default.valid(result.stdout.trim());
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Python package metadata is evidence only for a contained virtual environment.
  * A v2 command that names a Python-runtime tool must therefore resolve through
@@ -68,7 +85,7 @@ async function resolveParsedPackCompatibility(cwd, pack, options = {}) {
         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 evidence = (0, discovery_1.discoverProjectEvidence)(cwd, pack, { pathToolVersion: pathPackageManagerVersion });
     const executionPack = bindContainedRuntimeCommands(pack, evidence.pythonEnvironmentRoot);
     const resolutionEvidence = { ...evidence, ...(options.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}) };
     const initial = (0, resolve_1.resolveProjectCompatibility)(executionPack, resolutionEvidence).sensors;

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

@@ -48,8 +48,14 @@ async function runCompatibilityProbe(probe, evidence, executor = exec_1.runStruc
         throw new Error('compatibility probe kind must be allowed');
     if (!evidence || typeof evidence.cwd !== 'string' || evidence.cwd.trim() === '')
         throw new Error('probe evidence requires cwd');
-    if (probe.kind === 'package-script-present')
-        return { status: (evidence.scripts?.length ?? 0) > 0 ? 'matched' : 'not-matched', reason: 'package-script' };
+    if (probe.kind === 'package-script-present') {
+        const script = probe.script;
+        if (!Object.prototype.hasOwnProperty.call(probe, 'script'))
+            return { status: 'unverifiable', reason: 'package-script-name-required' };
+        if (typeof script !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9:_-]*$/.test(script))
+            throw new Error('package-script-present probe requires a named package script');
+        return { status: evidence.scripts?.includes(script) ? 'matched' : 'not-matched', reason: 'package-script' };
+    }
     if (probe.kind === 'config-present')
         return { status: (evidence.configFiles?.length ?? 0) > 0 ? 'matched' : 'not-matched', reason: 'config-file' };
     try {

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

@@ -26,7 +26,7 @@ function result(state, reason, variant, evidence) {
     return { state, reason, variantId: variant?.id ?? null, toolVersion, runtimeVersion, certifiedRange: variant?.certifiedRange ?? null, evidence: refs.slice(0, 32) };
 }
 function applies(sensor, evidence) {
-    if (sensor.applicability.kind === 'explicit-or-supported-language') {
+    if (sensor.applicability.kind === 'explicit-or-supported-language' || sensor.applicability.kind === 'explicit-opt-in') {
         return evidence.applicable === true || evidence.packSelection === 'explicit';
     }
     if (evidence.applicable === false)
@@ -40,7 +40,10 @@ function specificity(variant) {
 }
 function validVersion(value) { return typeof value === 'string' && semver_1.default.valid(value) !== null; }
 function toolFor(variant, evidence) {
-    return evidence.toolVersions === undefined ? evidence.toolVersion : evidence.toolVersions[variant.requirements.tool];
+    const tool = variant.requirements.tool;
+    const version = evidence.toolVersions === undefined ? evidence.toolVersion : evidence.toolVersions[tool];
+    const provenance = evidence.toolProvenance?.[tool];
+    return provenance !== undefined && provenance !== null && provenance !== variant.command.resolution ? null : version;
 }
 function runtimeFor(variant, evidence) {
     return evidence.runtimeVersions === undefined ? evidence.runtimeVersion : evidence.runtimeVersions[variant.requirements.runtime];

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.observeDetector = observeDetector;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const native_bridge_1 = require("../../../core/secure-fs/native-bridge");
 const contract_1 = require("./contract");
 const realIo = {
     lstatSync: fs_1.default.lstatSync,
@@ -39,23 +40,31 @@ function inspectFile(root, relative, markers, io) {
         return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
     }
     const noFollow = fs_1.default.constants.O_NOFOLLOW;
-    if (typeof noFollow !== 'number') {
+    if (typeof noFollow !== 'number' && io !== realIo) {
         return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
     }
     let fd;
     let content;
     try {
-        fd = (io.openSync ?? realIo.openSync)(absolute, fs_1.default.constants.O_RDONLY | noFollow);
-        const opened = (io.fstatSync ?? realIo.fstatSync)(fd);
-        if (!opened.isFile() || opened.size > contract_1.MAX_COVERAGE_FILE_BYTES) {
-            return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
+        if (typeof noFollow !== 'number') {
+            // Windows has no O_NOFOLLOW. Its native descriptor-anchored read
+            // rejects reparse points in every ancestor and preserves identity.
+            // Never replace an injected IO boundary with this native trust.
+            content = native_bridge_1.secureFs.readRegularFile(absolute, contract_1.MAX_COVERAGE_FILE_BYTES).bytes.toString('utf8');
         }
-        const buffer = Buffer.allocUnsafe(contract_1.MAX_COVERAGE_FILE_BYTES + 1);
-        const bytesRead = (io.readSync ?? realIo.readSync)(fd, buffer, 0, buffer.length, null);
-        if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > contract_1.MAX_COVERAGE_FILE_BYTES) {
-            return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
+        else {
+            fd = (io.openSync ?? realIo.openSync)(absolute, fs_1.default.constants.O_RDONLY | noFollow);
+            const opened = (io.fstatSync ?? realIo.fstatSync)(fd);
+            if (!opened.isFile() || opened.size > contract_1.MAX_COVERAGE_FILE_BYTES) {
+                return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
+            }
+            const buffer = Buffer.allocUnsafe(contract_1.MAX_COVERAGE_FILE_BYTES + 1);
+            const bytesRead = (io.readSync ?? realIo.readSync)(fd, buffer, 0, buffer.length, null);
+            if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > contract_1.MAX_COVERAGE_FILE_BYTES) {
+                return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };
+            }
+            content = buffer.subarray(0, bytesRead).toString('utf8');
         }
-        content = buffer.subarray(0, bytesRead).toString('utf8');
     }
     catch {
         return { status: 'unverifiable', evidence: [{ kind: 'file', path: relative, status: 'unverifiable' }] };