agentic-workflow-manager 9.5.0 → 9.6.1

package/dist/src/core/secure-fs/native-bridge.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureFs = exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE = void 0;
+exports.nativeArtifactStatus = nativeArtifactStatus;
+exports.loadNativeSecureFsBridge = loadNativeSecureFsBridge;
+exports.createSecureFsBoundary = createSecureFsBoundary;
+exports.resolvePackageRoot = resolvePackageRoot;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const supportedPlatforms = new Set(['linux', 'darwin', 'win32']);
+const supportedArchitectures = new Set(['x64', 'arm64']);
+function artifactPath(root, platform, arch) {
+    if (!supportedPlatforms.has(platform) || !supportedArchitectures.has(arch)) {
+        throw new Error(`secure-fs native bridge does not support ${platform}-${arch}`);
+    }
+    return path_1.default.join(root, 'prebuilds', `${platform}-${arch}`, 'secure_fs.node');
+}
+function nativeArtifactStatus(options) {
+    const artifact = artifactPath(options.root, options.platform, options.arch);
+    return { status: fs_1.default.existsSync(artifact) ? 'available' : 'missing', platform: options.platform, arch: options.arch, path: artifact };
+}
+function loadNativeSecureFsBridge(options) {
+    const status = nativeArtifactStatus(options);
+    if (status.status !== 'available')
+        throw new Error(`secure-fs native artifact is unavailable for ${status.platform}-${status.arch}`);
+    let loaded;
+    try {
+        loaded = options.load(status.path);
+    }
+    catch {
+        throw new Error(`secure-fs native artifact is incompatible for ${status.platform}-${status.arch}`);
+    }
+    if (!loaded || typeof loaded !== 'object'
+        || typeof loaded.acquireProjectLease !== 'function'
+        || typeof loaded.releaseProjectLease !== 'function'
+        || typeof loaded.readRegularFile !== 'function'
+        || typeof loaded.writeProjectTransaction !== 'function'
+        || typeof loaded.removeObservedProjectFile !== 'function') {
+        throw new Error(`secure-fs native artifact is incompatible for ${status.platform}-${status.arch}`);
+    }
+    return loaded;
+}
+const IDENTITY_TOKEN_BYTES = 24;
+const NATIVE_DESTINATION_EXISTS_CODE = 'AWM_SECURE_FS_DESTINATION_EXISTS';
+exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE = 'project destination already exists';
+const identityObservations = new WeakMap();
+function absoluteFile(value, label) {
+    if (typeof value === 'string' && value.includes('\0'))
+        throw new Error(`${label} must not contain a NUL byte`);
+    if (typeof value !== 'string' || !path_1.default.isAbsolute(value) || path_1.default.normalize(value) !== value)
+        throw new Error(`${label} must be an absolute normalized path`);
+    return value;
+}
+function isNativeDestinationExistsError(error) {
+    return !!error && typeof error === 'object'
+        && error.code === NATIVE_DESTINATION_EXISTS_CODE;
+}
+function boundedBytes(value, label) {
+    if (!Buffer.isBuffer(value))
+        throw new Error(`${label} must be a Buffer`);
+    return value;
+}
+function projectDestination(value) {
+    if (typeof value !== 'string' || !value || value.includes('\\')
+        || path_1.default.posix.isAbsolute(value) || path_1.default.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value)) {
+        throw new Error('destination must be a canonical project-relative path');
+    }
+    const components = value.split('/');
+    if (components.some(component => !component || component === '.' || component === '..' || component.includes(':') || component.includes('\0'))) {
+        throw new Error('destination must contain only safe project-relative components');
+    }
+    return components.join(path_1.default.sep);
+}
+function positiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${label} must be a positive safe integer`);
+    return value;
+}
+function nativeIdentity(value) {
+    if (!Buffer.isBuffer(value) || value.length !== IDENTITY_TOKEN_BYTES
+        || value.toString('ascii', 0, 4) !== 'SFSI' || value[4] !== 1
+        || (value[5] !== 1 && value[5] !== 2) || value[6] !== 0 || value[7] !== 0) {
+        throw new Error('secure-fs native bridge returned invalid read identity');
+    }
+    const expectedKind = process.platform === 'win32' ? 2 : 1;
+    if (value[5] !== expectedKind)
+        throw new Error('secure-fs native bridge returned identity for the wrong platform');
+    return Buffer.from(value);
+}
+function secureReadResult(file, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('secure-fs native bridge returned invalid read result');
+    const candidate = value;
+    if (!Buffer.isBuffer(candidate.bytes))
+        throw new Error('secure-fs native bridge returned invalid read bytes');
+    const bytes = Buffer.from(candidate.bytes);
+    const token = Object.freeze({});
+    identityObservations.set(token, { file, bytes: Buffer.from(bytes), identity: nativeIdentity(candidate.identity) });
+    return Object.freeze({ bytes, identity: token });
+}
+function writeOptions(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('transaction options must be an object');
+    const candidate = value;
+    if (candidate.mode !== 'create' && candidate.mode !== 'replace')
+        throw new Error('transaction mode must be create or replace');
+    if (typeof candidate.createParents !== 'boolean')
+        throw new Error('transaction createParents must be boolean');
+    if (candidate.mode === 'create') {
+        if (candidate.expected !== undefined || candidate.expectedIdentity !== undefined)
+            throw new Error('create transaction cannot have replacement expectations');
+        return { mode: 'create', createParents: candidate.createParents };
+    }
+    if (!Buffer.isBuffer(candidate.expected))
+        throw new Error('replace transaction requires expected Buffer bytes');
+    if (!candidate.expectedIdentity || typeof candidate.expectedIdentity !== 'object')
+        throw new Error('replace transaction requires expected identity token');
+    const observation = identityObservations.get(candidate.expectedIdentity);
+    if (!observation)
+        throw new Error('replace transaction requires an opaque identity token from readRegularFile');
+    if (!candidate.expected.equals(observation.bytes))
+        throw new Error('replace expected bytes do not match the identity observation');
+    return {
+        mode: 'replace',
+        expected: Buffer.from(observation.bytes),
+        expectedIdentity: Buffer.from(observation.identity),
+        createParents: candidate.createParents,
+    };
+}
+function createSecureFsBoundary(load) {
+    return Object.freeze({
+        withProjectLease(projectRoot, operation) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            if (typeof operation !== 'function')
+                throw new Error('project lease operation must be a function');
+            const binding = load();
+            let token;
+            try {
+                token = binding.acquireProjectLease(validatedRoot);
+            }
+            catch (error) {
+                const message = String(error);
+                if (message.includes('project lease is already held'))
+                    throw new Error('project lease conflict');
+                if (message.includes('rejected path ancestor'))
+                    throw new Error('project destination is unsafe for lease');
+                throw new Error('project lease acquisition failed');
+            }
+            if (!token || typeof token !== 'object' || Array.isArray(token)) {
+                throw new Error('secure-fs native bridge returned invalid project lease token');
+            }
+            try {
+                return operation();
+            }
+            finally {
+                binding.releaseProjectLease(token);
+            }
+        },
+        readRegularFile(file, maxBytes) {
+            const validatedFile = absoluteFile(file, 'file');
+            const validatedMaxBytes = positiveSafeInteger(maxBytes, 'maxBytes');
+            const result = load().readRegularFile(validatedFile, validatedMaxBytes);
+            return secureReadResult(validatedFile, result);
+        },
+        writeProjectTransaction(projectRoot, destination, content, options) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            const validatedDestination = projectDestination(destination);
+            const validatedContent = boundedBytes(content, 'content');
+            const validatedOptions = writeOptions(options);
+            try {
+                load().writeProjectTransaction(validatedRoot, validatedDestination, validatedContent, validatedOptions);
+            }
+            catch (error) {
+                if (isNativeDestinationExistsError(error))
+                    throw new Error(exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE);
+                throw error;
+            }
+        },
+        removeObservedProjectFile(projectRoot, destination, identity) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            const validatedDestination = projectDestination(destination);
+            if (!identity || typeof identity !== 'object')
+                throw new Error('remove requires an opaque identity token from readRegularFile');
+            const observation = identityObservations.get(identity);
+            if (!observation)
+                throw new Error('remove requires an opaque identity token from readRegularFile');
+            const observedDestination = path_1.default.join(validatedRoot, validatedDestination);
+            if (observation.file !== observedDestination)
+                throw new Error('remove requires the exact observed destination');
+            load().removeObservedProjectFile(validatedRoot, validatedDestination, Buffer.from(observation.identity));
+        },
+    });
+}
+function resolvePackageRoot(moduleDirectory) {
+    const sourceLayout = path_1.default.resolve(moduleDirectory, '..', '..', '..');
+    return fs_1.default.existsSync(path_1.default.join(sourceLayout, 'package.json'))
+        ? sourceLayout
+        : path_1.default.resolve(sourceLayout, '..');
+}
+const packageRoot = resolvePackageRoot(__dirname);
+exports.secureFs = createSecureFsBoundary(() => loadNativeSecureFsBridge({
+    root: packageRoot,
+    platform: process.platform,
+    arch: process.arch,
+    load: artifact => require(artifact),
+}));

package/dist/src/core/text.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripControlChars = stripControlChars;
+exports.sanitizeDiagnosticText = sanitizeDiagnosticText;
 exports.sanitizeDeclaredField = sanitizeDeclaredField;
 // cli/src/core/text.ts
 /** Neutraliza bytes de control C0 (incluyendo ESC `\x1b`) y DEL de texto que
@@ -16,6 +17,12 @@ function stripControlChars(text) {
     // eslint-disable-next-line no-control-regex -- necesitamos matchear C0 deliberadamente
     return text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
 }
+/** Keeps an untrusted diagnostic field on one terminal line, without changing
+ * the whitespace policy for multiline public text or composed markdown. */
+function sanitizeDiagnosticText(text) {
+    // eslint-disable-next-line no-control-regex -- remove all C0/C1 controls, including terminal escape bytes
+    return text.replace(/\r\n|[\r\n\t\u2028\u2029]/g, ' ').replace(/[\x00-\x1f\x7f-\x9f]/g, '');
+}
 /**
  * Neutraliza marcado markdown (colapsa `\r?\n` a un espacio y quita
  * `` ` * _ # < > ``) de contenido no confiable antes de interpolarlo en un

package/dist/tests/commands/context.test.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const context_1 = require("../../src/commands/context");
-const collected = (declared, diagnostics = []) => ({ declared, diagnostics });
+const collected = (declared, diagnostics = []) => ({ declared, diagnostics, droppedNames: [] });
 const uno = { name: 'mi-proceso', appliesWhen: 'cuando hay una tarea', terminatesTo: 'development-process' };
 describe('awm context orchestrators', () => {
     it('lista los orquestadores compuestos', () => {
@@ -55,6 +55,14 @@ describe('awm context orchestrators', () => {
         const r = (0, context_1.runContextOrchestrators)(collected([uno]), { json: false, verify: 'de-verdad-no-existe' });
         expect(r.code).toBe(2);
     });
+    it('--verify rejects a dropped raw identity that sanitizes to a retained name', () => {
+        const input = {
+            ...collected([{ name: 'foobar', appliesWhen: 'x', terminatesTo: 'y' }]),
+            droppedNames: ['foo_bar'],
+        };
+        expect((0, context_1.runContextOrchestrators)(input, { json: false, verify: 'foo_bar' }).code).toBe(2);
+        expect((0, context_1.runContextOrchestrators)(input, { json: false, verify: 'foobar' }).code).toBe(0);
+    });
     it('sanea bytes de control antes de escribir a la terminal', () => {
         const hostil = { name: 'x\x1b[31m', appliesWhen: 'w\x07', terminatesTo: 't\x00' };
         const r = (0, context_1.runContextOrchestrators)(collected([hostil]), { json: false });

package/dist/tests/commands/hooks/install.test.js

@@ -186,6 +186,8 @@ describe('installHook (happy path + merge)', () => {
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.mkdirSync(path_1.default.join(registryRoot, 'skills', 'mi-proceso'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'skills', 'mi-proceso', 'SKILL.md'), '---\nname: mi-proceso\n---\n');
         fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'mi-proceso', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
         installHook({ agent: 'claude-code', registryRoot, installMethod: 'symlink' });
         const content = fs_1.default.readFileSync(path_1.default.join(tmpHome, '.awm', 'hooks', 'using-awm.md'), 'utf-8');
@@ -246,6 +248,8 @@ describe('installHook (happy path + merge)', () => {
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.mkdirSync(path_1.default.join(registryRoot, 'skills', 'proceso-valido'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'skills', 'proceso-valido', 'SKILL.md'), '---\nname: proceso-valido\n---\n');
         fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'proceso-valido', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
         const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
         let result;

package/dist/tests/commands/hooks/resync.test.js

@@ -101,6 +101,8 @@ describe('resyncInstalledHooks', () => {
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
         fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.mkdirSync(path_1.default.join(registryRoot, 'skills', 'mi-proceso'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'skills', 'mi-proceso', 'SKILL.md'), '---\nname: mi-proceso\n---\n');
         fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'mi-proceso', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
         const { installHook } = require('../../../src/commands/hooks/install');
         installHook({ agent: 'claude-code', registryRoot, installMethod: 'symlink' });

package/dist/tests/commands/sensors/bootstrap-observational.test.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const bootstrap_1 = require("../../../src/commands/sensors/bootstrap");
+describe('planSensorBootstrap observational boundary', () => {
+    it('does not create project files while reporting a missing explicit mode', async () => {
+        const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-bootstrap-observe-'));
+        try {
+            fs_1.default.writeFileSync(path_1.default.join(project, 'package.json'), '{"name":"fixture"}\n');
+            const before = fs_1.default.readdirSync(project).sort();
+            await expect((0, bootstrap_1.planSensorBootstrap)(project)).resolves.toMatchObject({ kind: 'blocked', reason: 'mode-required', changes: [] });
+            expect(fs_1.default.readdirSync(project).sort()).toEqual(before);
+            expect(fs_1.default.existsSync(path_1.default.join(project, '.awm'))).toBe(false);
+        }
+        finally {
+            fs_1.default.rmSync(project, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/commands/sensors/bootstrap.test.js

@@ -0,0 +1,175 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock('../../../src/commands/sensors/project', () => ({ resolveSensorProject: jest.fn() }));
+jest.mock('../../../src/commands/sensors/detection', () => ({ detectStack: jest.fn() }));
+jest.mock('../../../src/core/registries', () => ({ listRegistries: jest.fn(() => []) }));
+jest.mock('../../../src/commands/sensors/compatibility/pack-source', () => ({ listPackSources: jest.fn() }));
+jest.mock('../../../src/commands/sensors/compatibility/contract', () => ({ ...jest.requireActual('../../../src/commands/sensors/compatibility/contract'), parseSensorPack: jest.fn() }));
+jest.mock('../../../src/commands/sensors/compatibility/live', () => ({ resolveParsedPackCompatibility: jest.fn() }));
+jest.mock('../../../src/commands/sensors/compatibility/source', () => ({ resolveSensorSource: jest.fn() }));
+jest.mock('../../../src/commands/sensors/migrate', () => ({ planV2Migration: jest.fn(), replaceV2ManifestWithV3: jest.fn() }));
+jest.mock('../../../src/commands/sensors/compatibility/materialize', () => ({ materializePortableSensors: jest.fn() }));
+jest.mock('../../../src/commands/sensors/compatibility/safe-file', () => ({ writeProjectFile: jest.fn(), withProjectLease: jest.fn((_root, operation) => operation()) }));
+const bootstrap_1 = require("../../../src/commands/sensors/bootstrap");
+const project_1 = require("../../../src/commands/sensors/project");
+const detection_1 = require("../../../src/commands/sensors/detection");
+const pack_source_1 = require("../../../src/commands/sensors/compatibility/pack-source");
+const contract_1 = require("../../../src/commands/sensors/compatibility/contract");
+const live_1 = require("../../../src/commands/sensors/compatibility/live");
+const source_1 = require("../../../src/commands/sensors/compatibility/source");
+const migrate_1 = require("../../../src/commands/sensors/migrate");
+const migrate_2 = require("../../../src/commands/sensors/migrate");
+const materialize_1 = require("../../../src/commands/sensors/compatibility/materialize");
+const safe_file_1 = require("../../../src/commands/sensors/compatibility/safe-file");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const root = '/project';
+const missing = { state: 'missing', projectRoot: root, manifestPath: `${root}/.awm/sensors.json` };
+const source = { path: '/registry/sensor-packs/js-ts/pack.json', content: '{}', registry: { name: 'baseline', remote: 'local', contentRoot: '/registry' } };
+describe('planSensorBootstrap', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        project_1.resolveSensorProject.mockReturnValue(missing);
+        detection_1.detectStack.mockReturnValue({ pack: 'js-ts', indicators: ['package.json'] });
+    });
+    it('requires an explicit mode for a missing declaration and never calls a writer', async () => {
+        await expect((0, bootstrap_1.planSensorBootstrap)(root)).resolves.toMatchObject({ kind: 'blocked', reason: 'mode-required', changes: [] });
+        expect(pack_source_1.listPackSources).not.toHaveBeenCalled();
+    });
+    it.each(['native-gate', 'opt-out'])('requires a reason for missing %s', async (mode) => {
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode })).resolves.toMatchObject({ kind: 'blocked', reason: 'reason-required', changes: [] });
+    });
+    it('plans a versioned native declaration without writing it', async () => {
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode: 'native-gate', reason: 'remote CI', dryRun: true })).resolves.toEqual({
+            kind: 'create', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, dryRun: true, configure: true,
+            changes: [{ path: '.awm/sensors.json', action: 'create' }],
+            manifest: { schemaVersion: 3, mode: 'native-gate', reason: 'remote CI' },
+        });
+    });
+    it('returns an idempotent no-op for an existing v3 declaration', async () => {
+        project_1.resolveSensorProject.mockReturnValue({ state: 'configured', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, packageRoot: root, manifest: { kind: 'v3', pack: { schemaVersion: 3, mode: 'opt-out', reason: 'declared' } } });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root)).resolves.toMatchObject({ kind: 'noop', changes: [] });
+    });
+    it('rejects a mode that conflicts with an existing v3 declaration', async () => {
+        project_1.resolveSensorProject.mockReturnValue({ state: 'configured', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, packageRoot: root, manifest: { kind: 'v3', pack: { schemaVersion: 3, mode: 'opt-out', reason: 'declared' } } });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode: 'native-gate', reason: 'other' })).resolves.toMatchObject({ kind: 'blocked', reason: 'mode-conflicts-with-existing-declaration', changes: [] });
+    });
+    it('blocks source-unavailable v2 migration without attempting a candidate', async () => {
+        const v2 = { schemaVersion: 2, pack: 'js-ts', sensors: {} };
+        project_1.resolveSensorProject.mockReturnValue({ state: 'configured', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, packageRoot: root, manifest: { kind: 'v2', pack: v2 } });
+        source_1.resolveSensorSource.mockReturnValue({ kind: 'source-unavailable', reason: 'no-compatible-registry', remedy: 'install-registry-or-run-awm-update' });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root)).resolves.toMatchObject({ kind: 'blocked', reason: 'no-compatible-registry', changes: [] });
+        expect(migrate_1.planV2Migration).not.toHaveBeenCalled();
+    });
+    it('preserves a legacy v1 manifest and blocks an ambiguous v2 source without writes', async () => {
+        project_1.resolveSensorProject.mockReturnValueOnce({ state: 'configured', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, packageRoot: root, manifest: { kind: 'legacy', pack: { pack: 'js-ts', sensors: {}, compatibility: {} } } });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root)).resolves.toMatchObject({ kind: 'blocked', reason: 'legacy-v1-preserved', changes: [] });
+        project_1.resolveSensorProject.mockReturnValueOnce({ state: 'configured', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, packageRoot: root, manifest: { kind: 'v2', pack: { schemaVersion: 2, pack: 'js-ts', sensors: {} } } });
+        source_1.resolveSensorSource.mockReturnValue({ kind: 'source-ambiguous', reason: 'multiple-compatible-registries', remedy: 'configure-one-logical-registry', candidates: ['a', 'b'] });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root)).resolves.toMatchObject({ kind: 'blocked', reason: 'multiple-compatible-registries', changes: [] });
+        expect(migrate_1.planV2Migration).not.toHaveBeenCalled();
+    });
+    it('plans a v2 replacement only after semantic migration proves equivalence', async () => {
+        const v2 = { schemaVersion: 2, pack: 'js-ts', sensors: {} };
+        const resolution = { kind: 'logical', source };
+        const migration = { candidate: { schemaVersion: 3, mode: 'project-sensors', pack: 'js-ts', source: { registry: 'baseline' }, sensors: {} }, equivalent: true, equivalence: {} };
+        const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-bootstrap-plan-'));
+        const manifestPath = path_1.default.join(project, 'sensors.json');
+        try {
+            fs_1.default.writeFileSync(manifestPath, JSON.stringify(v2));
+            project_1.resolveSensorProject.mockReturnValue({ state: 'configured', projectRoot: project, manifestPath, packageRoot: project, manifest: { kind: 'v2', pack: v2 } });
+            source_1.resolveSensorSource.mockReturnValue(resolution);
+            migrate_1.planV2Migration.mockReturnValue(migration);
+            await expect((0, bootstrap_1.planSensorBootstrap)(project)).resolves.toMatchObject({ kind: 'migrate', changes: [{ path: '.awm/sensors.json', action: 'replace' }], migration });
+        }
+        finally {
+            fs_1.default.rmSync(project, { recursive: true, force: true });
+        }
+    });
+    it('plans a concrete portable project-sensors declaration from one logical source', async () => {
+        const variant = { id: 'eslint-9', command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['.'] }, assets: ['eslint.config.mjs'] };
+        pack_source_1.listPackSources.mockReturnValue([source]);
+        contract_1.parseSensorPack.mockReturnValue({ kind: 'v2', pack: { schemaVersion: 2, name: 'js-ts', sensors: { lint: { fast: true, variants: [variant] } } } });
+        live_1.resolveParsedPackCompatibility.mockResolvedValue({ pack: { schemaVersion: 2, name: 'js-ts', sensors: { lint: { fast: true, variants: [variant] } } }, sensors: { lint: { state: 'certified', reason: 'ok', variantId: 'eslint-9', toolVersion: '9.0.0', runtimeVersion: '24.0.0', certifiedRange: '>=9 <10', evidence: [] } } });
+        const plan = await (0, bootstrap_1.planSensorBootstrap)(root, { mode: 'project-sensors' });
+        expect(plan).toMatchObject({ kind: 'create', changes: [{ path: '.awm/sensors.json', action: 'create' }, { path: 'eslint.config.mjs', action: 'create' }], manifest: { schemaVersion: 3, mode: 'project-sensors', pack: 'js-ts', source: { registry: 'baseline' } } });
+        expect(JSON.stringify(plan.manifest)).not.toContain('/registry');
+    });
+    it('resolves compatibility from the selected package root', async () => {
+        const variant = { id: 'eslint-9', command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['.'] }, assets: [] };
+        const pack = { schemaVersion: 2, name: 'js-ts', sensors: { lint: { variants: [variant] } } };
+        pack_source_1.listPackSources.mockReturnValue([source]);
+        contract_1.parseSensorPack.mockReturnValue({ kind: 'v2', pack });
+        live_1.resolveParsedPackCompatibility.mockResolvedValue({ pack, sensors: { lint: { state: 'certified', reason: 'ok', variantId: 'eslint-9', toolVersion: '9.0.0', runtimeVersion: '24.0.0', certifiedRange: '>=9 <10', evidence: [] } } });
+        await (0, bootstrap_1.planSensorBootstrap)(root, { mode: 'project-sensors', packageRoot: 'packages/web' });
+        expect(live_1.resolveParsedPackCompatibility).toHaveBeenCalledWith(path_1.default.resolve(root, 'packages/web'), pack);
+    });
+    it('blocks project-sensors when compatibility cannot select every declared sensor variant', async () => {
+        const variant = { id: 'eslint-9', command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['.'] }, assets: [] };
+        pack_source_1.listPackSources.mockReturnValue([source]);
+        contract_1.parseSensorPack.mockReturnValue({ kind: 'v2', pack: { schemaVersion: 2, name: 'js-ts', sensors: { lint: { variants: [variant] } } } });
+        live_1.resolveParsedPackCompatibility.mockResolvedValue({ pack: { schemaVersion: 2, name: 'js-ts', sensors: { lint: { variants: [variant] } } }, sensors: { lint: { variantId: null } } });
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode: 'project-sensors' })).resolves.toMatchObject({ kind: 'blocked', reason: 'sensor-variant-unresolvable', changes: [] });
+    });
+    it('converts a compatibility probe failure into a stable blocked plan', async () => {
+        pack_source_1.listPackSources.mockReturnValue([source]);
+        contract_1.parseSensorPack.mockReturnValue({ kind: 'v2', pack: { schemaVersion: 2, name: 'js-ts', sensors: {} } });
+        live_1.resolveParsedPackCompatibility.mockRejectedValue(new Error('tool probe failed'));
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode: 'project-sensors' })).resolves.toMatchObject({ kind: 'blocked', reason: 'compatibility-unresolvable', changes: [] });
+    });
+    it.each([{ mode: 'invalid' }, { reason: 'line\nbreak' }, { dryRun: 'yes' }, { unknown: true }])('rejects invalid bootstrap options %j before planning', async (input) => {
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, input)).rejects.toThrow(/bootstrap (mode|reason|dryRun|options)/);
+        expect(pack_source_1.listPackSources).not.toHaveBeenCalled();
+    });
+    it('accepts a Windows absolute registry path without treating it as project state', async () => {
+        await expect((0, bootstrap_1.planSensorBootstrap)(root, { mode: 'project-sensors', registryRoot: 'C:\\awm\\registries\\baseline' })).resolves.toMatchObject({
+            kind: 'blocked', reason: 'registry-root-not-configured', changes: [],
+        });
+    });
+    it('rejects applying a dry-run plan before any publisher runs', () => {
+        expect(() => (0, bootstrap_1.applySensorBootstrap)({ kind: 'create', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, dryRun: true, changes: [], manifest: { schemaVersion: 3, mode: 'native-gate', reason: 'CI' } })).toThrow('dry-run');
+        expect(safe_file_1.writeProjectFile).not.toHaveBeenCalled();
+    });
+    it('publishes native declarations and project sensors through distinct native boundaries', () => {
+        expect((0, bootstrap_1.applySensorBootstrap)({ kind: 'create', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, dryRun: false, changes: [{ path: '.awm/sensors.json', action: 'create' }], manifest: { schemaVersion: 3, mode: 'native-gate', reason: 'CI' } })).toBe('created');
+        expect(safe_file_1.writeProjectFile).toHaveBeenCalledWith(root, '.awm/sensors.json', expect.any(Buffer), { mode: 'create', createParents: true });
+        expect(safe_file_1.withProjectLease).toHaveBeenCalledWith(root, expect.any(Function));
+        const manifest = { schemaVersion: 3, mode: 'project-sensors', pack: 'js-ts', source: { registry: 'baseline' }, sensors: {} };
+        expect((0, bootstrap_1.applySensorBootstrap)({ kind: 'create', projectRoot: root, manifestPath: `${root}/.awm/sensors.json`, dryRun: false, changes: [{ path: '.awm/sensors.json', action: 'create' }], manifest, source })).toBe('created');
+        expect(materialize_1.materializePortableSensors).toHaveBeenCalledWith(expect.objectContaining({ projectRoot: root, pack: 'js-ts', source, sensors: {} }));
+    });
+    it('delegates a validated migration to the fenced replacement', () => {
+        const candidate = { schemaVersion: 3, mode: 'project-sensors', pack: 'js-ts', source: { registry: 'baseline' }, sensors: {} };
+        const migration = { candidate, equivalent: true, equivalence: {} };
+        const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-bootstrap-plan-'));
+        const manifestPath = path_1.default.join(project, 'sensors.json');
+        try {
+            const bytes = Buffer.from('{"schemaVersion":2}\n');
+            fs_1.default.writeFileSync(manifestPath, bytes);
+            const plan = { kind: 'migrate', projectRoot: project, manifestPath, dryRun: false, changes: [{ path: '.awm/sensors.json', action: 'replace' }], migration, source, originalDigest: (0, crypto_1.createHash)('sha256').update(bytes).digest('hex') };
+            expect((0, bootstrap_1.applySensorBootstrap)(plan)).toBe('migrated');
+            expect(migrate_2.replaceV2ManifestWithV3).toHaveBeenCalledWith(plan.manifestPath, candidate, source);
+        }
+        finally {
+            fs_1.default.rmSync(project, { recursive: true, force: true });
+        }
+    });
+    it('rejects a migration plan whose manifest changed after planning', () => {
+        const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-bootstrap-stale-'));
+        const manifestPath = path_1.default.join(project, 'sensors.json');
+        try {
+            fs_1.default.writeFileSync(manifestPath, 'replacement');
+            const plan = { kind: 'migrate', projectRoot: project, manifestPath, dryRun: false, changes: [{ path: '.awm/sensors.json', action: 'replace' }], migration: { candidate: {}, equivalent: true, equivalence: {} }, source, originalDigest: (0, crypto_1.createHash)('sha256').update('original').digest('hex') };
+            expect(() => (0, bootstrap_1.applySensorBootstrap)(plan)).toThrow('stale');
+            expect(migrate_2.replaceV2ManifestWithV3).not.toHaveBeenCalled();
+        }
+        finally {
+            fs_1.default.rmSync(project, { recursive: true, force: true });
+        }
+    });
+});

package/dist/tests/commands/sensors/compatibility/contract.test.js

@@ -8,6 +8,7 @@ const timeout_1 = require("../../../../src/commands/sensors/compatibility/timeou
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const safe_file_1 = require("../../../../src/commands/sensors/compatibility/safe-file");
 const coverage = {
     schemaVersion: 1,
     classes: {
@@ -44,6 +45,8 @@ function validPack() {
     };
 }
 describe('sensor pack v2 contract', () => {
+    beforeEach(() => (0, safe_file_1.setPortableReadForTests)(true));
+    afterEach(() => (0, safe_file_1.setPortableReadForTests)(false));
     it('exports bounded timeout validation and resolution (R3.1, R3.4)', () => {
         expect((0, timeout_1.positiveTimeout)(1, 'sensor timeout')).toBe(1);
         expect((0, timeout_1.resolveTimeout)({ project: 90_000, pack: 30_000, fast: true })).toEqual({ timeoutMs: 90_000, source: 'project' });
@@ -84,6 +87,41 @@ describe('sensor pack v2 contract', () => {
             fs_1.default.rmSync(sensorPacks, { recursive: true, force: true });
         }
     });
+    it('rejects a Semgrep policy that changes between inspection and safe open', () => {
+        const sensorPacks = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-semgrep-policy-'));
+        const packDir = path_1.default.join(sensorPacks, 'python');
+        const policyPath = path_1.default.join(sensorPacks, 'shared', 'semgrep-policy.json');
+        const originalOpen = fs_1.default.openSync.bind(fs_1.default);
+        const open = jest.spyOn(fs_1.default, 'openSync');
+        let replaced = false;
+        try {
+            fs_1.default.mkdirSync(path_1.default.dirname(policyPath), { recursive: true });
+            fs_1.default.mkdirSync(packDir);
+            fs_1.default.writeFileSync(policyPath, JSON.stringify({
+                tool: 'semgrep', toolRange: '>=1.0.0', runtime: 'python', runtimeRange: '>=3.9.0', probe: 'semgrep-validate',
+            }));
+            const pack = validPack();
+            pack.sensors.lint.variants[0] = {
+                id: 'semgrep-python', priority: 10, certifiedRange: '>=1.0.0', policyRef: 'shared/semgrep-policy.json',
+                command: { executable: 'semgrep', resolution: 'path', args: ['--config', '.semgrep.awm.yml', '--json', '.'] },
+                assets: ['.semgrep.awm.yml'], formatter: 'semgrep',
+            };
+            open.mockImplementation(((file, flags, mode) => {
+                if (file === policyPath && !replaced) {
+                    replaced = true;
+                    fs_1.default.writeFileSync(policyPath, JSON.stringify({
+                        tool: 'semgrep', toolRange: '>=2.0.0', runtime: 'python', runtimeRange: '>=3.10.0', probe: 'semgrep-validate',
+                    }));
+                }
+                return originalOpen(file, flags, mode);
+            }));
+            expect(() => (0, contract_1.parseSensorPack)(pack, path_1.default.join(packDir, 'pack.json'))).toThrow(/changed|identity|policyRef/i);
+        }
+        finally {
+            open.mockRestore();
+            fs_1.default.rmSync(sensorPacks, { recursive: true, force: true });
+        }
+    });
     it('fails closed when a policy reference is not the AWM-owned shared Semgrep policy', () => {
         const pack = validPack();
         pack.sensors.lint.variants[0] = {

package/dist/tests/commands/sensors/compatibility/manifest.test.js

@@ -61,6 +61,73 @@ describe('sensor manifest contract', () => {
         expect(() => (0, manifest_1.parseSensorManifest)({ schemaVersion: 3, mode: 'native-gate' }, 'sensors.json')).toThrow('reason');
         expect(() => (0, manifest_1.parseSensorManifest)({ ...project, registryRoot: '/machine/root' }, 'sensors.json')).toThrow('unknown field');
     });
+    it('serializes v3 deterministically with a newline and round-trips portable semantics', () => {
+        const manifest = {
+            schemaVersion: 3,
+            mode: 'project-sensors',
+            pack: 'js-ts',
+            packSelection: 'explicit',
+            source: { registry: 'baseline' },
+            packageRoot: 'cli',
+            sensors: { lint: { ...validV2Manifest().sensors.lint, enabled: false, fast: true, timeout: 45_000, assets: ['eslint.config.awm.mjs'], policyRef: 'shared/semgrep-policy.json' } },
+            concurrency: 2,
+        };
+        const serialized = (0, manifest_1.serializeManifestV3)(manifest);
+        expect(serialized).toBe((0, manifest_1.serializeManifestV3)(manifest));
+        expect(serialized.endsWith('\n')).toBe(true);
+        expect(serialized).not.toContain('registryRoot');
+        expect(serialized).not.toContain('/home/');
+        expect((0, manifest_1.parseSensorManifest)(JSON.parse(serialized), 'sensors.json')).toEqual({ kind: 'v3', pack: manifest });
+    });
+    it.each(['native-gate', 'opt-out'])('serializes a versioned %s declaration canonically', mode => {
+        const manifest = { schemaVersion: 3, mode, reason: 'declared by project policy' };
+        expect((0, manifest_1.serializeManifestV3)(manifest)).toBe(JSON.stringify(manifest, null, 2) + '\n');
+    });
+    it('refuses to serialize a v3 declaration containing a nested physical path', () => {
+        const manifest = {
+            schemaVersion: 3,
+            mode: 'project-sensors',
+            pack: 'js-ts',
+            source: { registry: 'baseline' },
+            sensors: {
+                lint: {
+                    ...validV2Manifest().sensors.lint,
+                    command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['--config=/home/operator/.config/eslint.config.mjs'] },
+                },
+            },
+        };
+        expect(() => (0, manifest_1.serializeManifestV3)(manifest)).toThrow('physical path');
+    });
+    it('serializes a portable URL in a structured command argument', () => {
+        const manifest = {
+            schemaVersion: 3,
+            mode: 'project-sensors',
+            pack: 'js-ts',
+            source: { registry: 'baseline' },
+            sensors: {
+                lint: {
+                    ...validV2Manifest().sensors.lint,
+                    command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['--rules=https://example.invalid/rules.json'] },
+                },
+            },
+        };
+        expect(JSON.parse((0, manifest_1.serializeManifestV3)(manifest)).sensors.lint.command.args).toEqual(['--rules=https://example.invalid/rules.json']);
+    });
+    it('retains a portable URL in a structured command argument', () => {
+        const manifest = {
+            schemaVersion: 3,
+            mode: 'project-sensors',
+            pack: 'js-ts',
+            source: { registry: 'baseline' },
+            sensors: {
+                lint: {
+                    ...validV2Manifest().sensors.lint,
+                    command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['--rules-url=https://example.test/eslint/rules.json'] },
+                },
+            },
+        };
+        expect(() => (0, manifest_1.serializeManifestV3)(manifest)).not.toThrow();
+    });
     it('accepts and serializes a positive v2 project timeout (R3)', () => {
         const manifest = validV2Manifest();
         manifest.sensors.lint.timeout = 45_000;