agentic-workflow-manager 9.5.0 → 9.6.0

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

@@ -3,18 +3,22 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.materializePortableSensors = materializePortableSensors;
 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");
+const safe_file_1 = require("./safe-file");
+const native_bridge_1 = require("../../../core/secure-fs/native-bridge");
+const MAX_ASSET_BYTES = 1024 * 1024;
 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`);
     return value;
 }
 function containedAsset(value, label) {
-    if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || path_1.default.isAbsolute(value) || value.split('/').some(part => !part || part === '.' || part === '..'))
+    if (typeof value !== 'string' || value.length === 0 || value.includes('\\') || path_1.default.isAbsolute(value) || /^(?:[A-Za-z]:|[\\/])/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..'))
         throw new Error(`${label} must be a contained relative asset path`);
     return value;
 }
@@ -31,45 +35,266 @@ function root(value, label) {
     }
     return resolved;
 }
-function atomicWrite(destination, content) {
-    const directory = path_1.default.dirname(destination);
-    fs_1.default.mkdirSync(directory, { recursive: true });
-    const temporary = path_1.default.join(directory, `.${path_1.default.basename(destination)}.${process.pid}.${Date.now()}.tmp`);
+/** Resolve a monorepo package only when it is a real directory below the project.
+ * A lexical `foo/bar` is not enough: a symlink must never turn an asset write
+ * into an authority outside the project transaction. */
+function containedPackageRoot(projectRoot, packageRoot) {
+    const candidate = path_1.default.join(projectRoot, packageRoot);
+    let stat;
     try {
-        fs_1.default.writeFileSync(temporary, content, { encoding: 'utf8', flag: 'wx' });
-        fs_1.default.renameSync(temporary, destination);
+        stat = fs_1.default.lstatSync(candidate);
     }
-    finally {
+    catch {
+        throw new Error('packageRoot must be an existing contained directory');
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('packageRoot must be a non-symbolic contained directory');
+    const realProject = fs_1.default.realpathSync(projectRoot);
+    const realPackage = fs_1.default.realpathSync(candidate);
+    const relative = path_1.default.relative(realProject, realPackage);
+    if (relative === '' || relative === '..' || relative.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(relative)) {
+        throw new Error('packageRoot must be a contained directory');
+    }
+    return realPackage;
+}
+function registryPackRoot(value) {
+    const resolved = root(value, 'packRoot');
+    const parsed = path_1.default.parse(resolved);
+    let current = parsed.root;
+    for (const component of path_1.default.relative(parsed.root, resolved).split(path_1.default.sep).filter(Boolean)) {
+        let stat;
         try {
-            if (fs_1.default.existsSync(temporary))
-                fs_1.default.unlinkSync(temporary);
+            stat = fs_1.default.lstatSync(current);
+        }
+        catch {
+            throw new Error('packRoot must be an existing directory');
         }
-        catch { /* best effort cleanup */ }
+        if (stat.isSymbolicLink())
+            throw new Error('packRoot contains a symlink');
+        current = path_1.default.join(current, component);
+    }
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(current);
+    }
+    catch {
+        throw new Error('packRoot must be an existing directory');
+    }
+    if (stat.isSymbolicLink())
+        throw new Error('packRoot contains a symlink');
+    return resolved;
+}
+function atomicWrite(configRoot, asset, content, noClobber = false) {
+    const destination = path_1.default.join(configRoot, ...asset.split('/'));
+    if (noClobber) {
+        (0, safe_file_1.writeProjectFile)(configRoot, asset, Buffer.from(content, 'utf8'), { mode: 'create', createParents: true });
+        return;
+    }
+    let expected;
+    try {
+        expected = (0, safe_file_1.readInspectedBoundedFileWithIdentity)(destination, fs_1.default.lstatSync(destination, { bigint: true }), MAX_ASSET_BYTES, () => new Error(`project destination cannot be safely read: ${asset}`));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    (0, safe_file_1.writeProjectFile)(configRoot, asset, Buffer.from(content, 'utf8'), expected
+        ? { mode: 'replace', expected: expected.content, expectedIdentity: expected.identity, createParents: false }
+        : { mode: 'create', createParents: true });
+}
+/** Publish a new asset without ever replacing an owner-created destination. */
+function atomicCreateAsset(configRoot, asset, content) {
+    try {
+        (0, safe_file_1.writeProjectFile)(configRoot, asset, Buffer.from(content, 'utf8'), { mode: 'create', createParents: true });
+    }
+    catch (error) {
+        if (error.message === `project destination rejected by secure-fs: ${native_bridge_1.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE}`)
+            return false;
+        throw error;
+    }
+    return true;
+}
+function selectedRegistryAsset(packRoot, asset) {
+    let current = packRoot;
+    for (const [index, component] of asset.split('/').entries()) {
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(current, { bigint: true });
+        }
+        catch {
+            throw new Error(`selected asset is missing from pack: ${asset}`);
+        }
+        if (stat.isSymbolicLink())
+            throw new Error(`selected asset contains a symlink: ${asset}`);
+        if (index < asset.split('/').length - 1 && !stat.isDirectory())
+            throw new Error(`selected asset is missing from pack: ${asset}`);
+        current = path_1.default.join(current, component);
+    }
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(current, { bigint: true });
+    }
+    catch {
+        throw new Error(`selected asset is missing from pack: ${asset}`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`selected asset must be a regular file: ${asset}`);
+    if (stat.size > BigInt(MAX_ASSET_BYTES))
+        throw new Error(`selected asset exceeds the 1 MiB limit: ${asset}`);
+    return { file: current, stat };
+}
+function readSelectedRegistryAsset(packRoot, selected, asset) {
+    // Re-walk the bounded parent chain immediately before the leaf-safe-open.
+    // A replaced ancestor can otherwise redirect the same pathname outside the
+    // inspected registry between selection and the O_NOFOLLOW leaf open.
+    const current = selectedRegistryAsset(packRoot, asset);
+    if (current.stat.dev !== selected.stat.dev || current.stat.ino !== selected.stat.ino) {
+        throw new Error(`selected asset changed identity during safe open: ${asset}`);
+    }
+    const failure = (reason) => {
+        if (reason === 'open')
+            return new Error(`selected asset cannot be safely opened: ${asset}`);
+        if (reason === 'regular')
+            return new Error(`selected asset must be a regular file: ${asset}`);
+        if (reason === 'identity')
+            return new Error(`selected asset changed identity during safe open: ${asset}`);
+        if (reason === 'size')
+            return new Error(`selected asset changed size during safe open: ${asset}`);
+        return new Error(`selected asset exceeds the 1 MiB limit: ${asset}`);
+    };
+    return (0, safe_file_1.readInspectedBoundedFile)(selected.file, selected.stat, MAX_ASSET_BYTES, failure).toString('utf8');
+}
+function portableSource(source, pack) {
+    if (!source || typeof source !== 'object')
+        throw new Error('portable source is required');
+    const candidate = source;
+    if (!candidate.registry || typeof candidate.registry !== 'object' || typeof candidate.registry.name !== 'string' || typeof candidate.registry.contentRoot !== 'string' || typeof candidate.path !== 'string') {
+        throw new Error('portable source must be a validated pack source');
+    }
+    const registry = stableId(candidate.registry.name, 'source.registry.name');
+    const configuredRoot = root(candidate.registry.contentRoot, 'source.registry.contentRoot');
+    let contentRoot;
+    try {
+        contentRoot = fs_1.default.realpathSync(configuredRoot);
     }
+    catch {
+        throw new Error('source.registry.contentRoot must be canonicalizable');
+    }
+    const packRoot = registryPackRoot(path_1.default.join(contentRoot, 'sensor-packs', pack));
+    const expectedPack = path_1.default.join(packRoot, 'pack.json');
+    if (path_1.default.resolve(candidate.path) !== expectedPack)
+        throw new Error('portable source selected pack path does not match its registry');
+    const inspectedPack = selectedRegistryAsset(packRoot, 'pack.json');
+    if (readSelectedRegistryAsset(packRoot, inspectedPack, 'pack.json') !== candidate.content) {
+        throw new Error('portable source changed after bootstrap planning');
+    }
+    return { registry, packRoot };
 }
 function priorAssets(projectRoot) {
     const manifest = path_1.default.join(projectRoot, '.awm', 'sensors.json');
-    if (!fs_1.default.existsSync(manifest))
-        return [];
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(manifest, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new Error(`cannot materialize over invalid sensor manifest ${manifest}`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`cannot materialize over invalid sensor manifest ${manifest}`);
     let parsed;
     try {
-        parsed = JSON.parse(fs_1.default.readFileSync(manifest, 'utf8'));
+        parsed = JSON.parse((0, safe_file_1.readInspectedBoundedFile)(manifest, stat, MAX_ASSET_BYTES, () => new Error(`cannot materialize over invalid sensor manifest ${manifest}`)).toString('utf8'));
     }
     catch {
         throw new Error(`cannot materialize over invalid sensor manifest ${manifest}`);
     }
     const parsedManifest = (0, manifest_1.parseSensorManifest)(parsed, manifest);
-    if (parsedManifest.kind !== 'v2')
-        return [];
-    return Object.values(parsedManifest.pack.sensors).flatMap(sensor => sensor.assets ?? []);
+    if (parsedManifest.kind === 'v2')
+        return Object.values(parsedManifest.pack.sensors).flatMap(sensor => sensor.assets ?? []);
+    if (parsedManifest.kind === 'v3' && parsedManifest.pack.mode === 'project-sensors')
+        return Object.values(parsedManifest.pack.sensors).flatMap(sensor => sensor.assets ?? []);
+    return [];
+}
+/** Materialize a previously selected logical registry source into a portable v3 manifest. */
+function materializePortableSensors(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('materialization input is required');
+    const projectRoot = root(input.projectRoot, 'projectRoot');
+    const pack = stableId(input.pack, 'pack');
+    const source = portableSource(input.source, pack);
+    const packRoot = source.packRoot;
+    if (!input.sensors || typeof input.sensors !== 'object' || Array.isArray(input.sensors))
+        throw new Error('sensors must be an object');
+    const candidate = {
+        schemaVersion: 3, mode: 'project-sensors', pack,
+        ...(input.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}),
+        source: { registry: source.registry },
+        ...(input.packageRoot ? { packageRoot: containedAsset(input.packageRoot, 'packageRoot') } : {}),
+        sensors: input.sensors,
+    };
+    const parsed = (0, manifest_1.parseSensorManifest)(candidate, 'portable materialized manifest');
+    if (parsed.kind !== 'v3' || parsed.pack.mode !== 'project-sensors')
+        throw new Error('portable materialized manifest must be v3 project-sensors');
+    const manifest = parsed.pack;
+    for (const [name, sensor] of Object.entries(manifest.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(manifest.sensors).flatMap(sensor => sensor.assets ?? []))].map((asset, index) => containedAsset(asset, `assets[${index}]`)).sort();
+    // Establish every registry authority and read every selected byte before the
+    // first project mutation. A bad later asset must not strand an earlier one.
+    const publications = input.configure === false ? [] : selected.map(asset => {
+        const selectedSource = selectedRegistryAsset(packRoot, asset);
+        return { asset, content: readSelectedRegistryAsset(packRoot, selectedSource, asset) };
+    });
+    return (0, safe_file_1.withProjectLease)(projectRoot, () => {
+        const configRoot = manifest.packageRoot ? containedPackageRoot(projectRoot, manifest.packageRoot) : projectRoot;
+        const prior = priorAssets(projectRoot);
+        const configured = [];
+        const preserved = [];
+        const created = [];
+        try {
+            if (input.configure !== false) {
+                for (const publication of publications) {
+                    if (atomicCreateAsset(configRoot, publication.asset, publication.content)) {
+                        const destination = manifest.packageRoot ? `${manifest.packageRoot}/${publication.asset}` : publication.asset;
+                        const absolute = path_1.default.join(projectRoot, ...destination.split('/'));
+                        const stat = fs_1.default.lstatSync(absolute, { bigint: true });
+                        const observed = (0, safe_file_1.readInspectedBoundedFileWithIdentity)(absolute, stat, MAX_ASSET_BYTES, () => new Error(`created asset cannot be safely observed: ${publication.asset}`));
+                        if (!observed.content.equals(Buffer.from(publication.content, 'utf8'))) {
+                            throw new Error(`created asset changed before manifest publication: ${publication.asset}`);
+                        }
+                        created.push({ destination, identity: observed.identity });
+                        configured.push(publication.asset);
+                    }
+                    else
+                        preserved.push(publication.asset);
+                }
+            }
+            atomicWrite(projectRoot, '.awm/sensors.json', (0, manifest_1.serializeManifestV3)(manifest), true);
+        }
+        catch (error) {
+            for (const entry of created.reverse()) {
+                try {
+                    (0, safe_file_1.removeObservedProjectFile)(projectRoot, entry.destination, entry.identity);
+                }
+                catch { /* Preserve a competing replacement; report the original publication failure. */ }
+            }
+            throw error;
+        }
+        return { manifest, configured, preserved, orphaned: prior.filter(asset => !selected.includes(asset)).sort() };
+    });
 }
 /** Write a selected, v2-only sensor configuration without overwriting user files.
- * The manifest is the commit point: created assets are removed best-effort if writing it fails. */
+ * Assets published before a manifest failure are deliberately left in place: a
+ * pathname rollback cannot be made safe after a concurrent project-parent swap. */
 function materializeResolvedSensors(input) {
     if (!input || typeof input !== 'object')
         throw new Error('materialization input is required');
     const projectRoot = root(input.projectRoot, 'projectRoot');
-    const packRoot = root(input.packRoot, 'packRoot');
+    const packRoot = registryPackRoot(input.packRoot);
     const pack = stableId(input.pack, 'pack');
     if (!input.sensors || typeof input.sensors !== 'object' || Array.isArray(input.sensors))
         throw new Error('sensors must be an object');
@@ -86,7 +311,6 @@ function materializeResolvedSensors(input) {
     // Assets land where sensors will actually run — projectRoot by default, or
     // packageRoot underneath it for a monorepo. The manifest write below stays
     // pinned to projectRoot either way (see atomicWrite call at the end).
-    const configRoot = manifest.packageRoot ? root(path_1.default.join(projectRoot, manifest.packageRoot), 'packageRoot') : projectRoot;
     // 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.
@@ -95,44 +319,22 @@ function materializeResolvedSensors(input) {
             (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 = [];
-    const preserved = [];
-    const created = [];
-    try {
+    return (0, safe_file_1.withProjectLease)(projectRoot, () => {
+        const configRoot = manifest.packageRoot ? root(path_1.default.join(projectRoot, manifest.packageRoot), 'packageRoot') : projectRoot;
+        const prior = priorAssets(projectRoot);
+        const configured = [];
+        const preserved = [];
         if (input.configure !== false) {
             for (const asset of selected) {
-                const source = path_1.default.join(packRoot, ...asset.split('/'));
-                const destination = path_1.default.join(configRoot, ...asset.split('/'));
-                let stat;
-                try {
-                    stat = fs_1.default.lstatSync(source);
-                }
-                catch {
-                    throw new Error(`selected asset is missing from pack: ${asset}`);
+                const selectedSource = selectedRegistryAsset(packRoot, asset);
+                if (atomicCreateAsset(configRoot, asset, readSelectedRegistryAsset(packRoot, selectedSource, asset))) {
+                    configured.push(asset);
                 }
-                if (!stat.isFile() || stat.isSymbolicLink())
-                    throw new Error(`selected asset must be a regular file: ${asset}`);
-                if (fs_1.default.existsSync(destination)) {
+                else
                     preserved.push(asset);
-                    continue;
-                }
-                fs_1.default.mkdirSync(path_1.default.dirname(destination), { recursive: true });
-                atomicWrite(destination, fs_1.default.readFileSync(source, 'utf8'));
-                created.push(destination);
-                configured.push(asset);
             }
         }
-        atomicWrite(path_1.default.join(projectRoot, '.awm', 'sensors.json'), (0, manifest_1.serializeManifestV2)(manifest));
-    }
-    catch (error) {
-        for (const file of created.reverse()) {
-            try {
-                fs_1.default.unlinkSync(file);
-            }
-            catch { /* best effort transaction rollback */ }
-        }
-        throw error;
-    }
-    return { manifest, configured, preserved, orphaned: prior.filter(asset => !selected.includes(asset)).sort() };
+        atomicWrite(projectRoot, '.awm/sensors.json', (0, manifest_1.serializeManifestV2)(manifest));
+        return { manifest, configured, preserved, orphaned: prior.filter(asset => !selected.includes(asset)).sort() };
+    });
 }

package/dist/src/commands/sensors/compatibility/safe-file.js

@@ -3,16 +3,226 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSecureFsForTests = setSecureFsForTests;
+exports.setPortableReadForTests = setPortableReadForTests;
+exports.withProjectLease = withProjectLease;
+exports.writeProjectFile = writeProjectFile;
+exports.removeObservedProjectFile = removeObservedProjectFile;
+exports.withNoFollowDirectory = withNoFollowDirectory;
+exports.withDescriptorBoundWriteDirectory = withDescriptorBoundWriteDirectory;
+exports.withNoFollowChildDirectory = withNoFollowChildDirectory;
 exports.readInspectedBoundedFile = readInspectedBoundedFile;
+exports.readInspectedBoundedFileWithIdentity = readInspectedBoundedFileWithIdentity;
 const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const native_bridge_1 = require("../../../core/secure-fs/native-bridge");
+let secureFsForTest;
+let portableReadForTests = false;
+/** Test-only seam for filesystem race fixtures. Production always uses the packaged bridge. */
+function setSecureFsForTests(boundary) {
+    secureFsForTest = boundary;
+}
+/** Test-only opt-in for Node-level filesystem race fixtures. */
+function setPortableReadForTests(enabled) {
+    portableReadForTests = enabled;
+}
+function activeSecureFs() {
+    return secureFsForTest ?? native_bridge_1.secureFs;
+}
+/** Hold the native project lease for one complete sensor mutation callback. */
+function withProjectLease(projectRoot, operation) {
+    return activeSecureFs().withProjectLease(projectRoot, operation);
+}
+/** Native-only project publication. Production never falls back to pathname writes. */
+function writeProjectFile(projectRoot, destination, content, options) {
+    try {
+        activeSecureFs().writeProjectTransaction(projectRoot, destination, content, options);
+    }
+    catch (error) {
+        throw new Error(`project destination rejected by secure-fs: ${error.message}`);
+    }
+}
+/** Compensate only a file that this transaction read and identity-fenced. */
+function removeObservedProjectFile(projectRoot, destination, identity) {
+    try {
+        const remove = activeSecureFs().removeObservedProjectFile;
+        if (typeof remove !== 'function')
+            throw new Error('secure-fs native bridge does not support identity-fenced removal');
+        remove(projectRoot, destination, identity);
+    }
+    catch (error) {
+        throw new Error(`project destination rejected by secure-fs: ${error.message}`);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function snapshotDirectoryChain(directory, failure) {
+    if (!path_1.default.isAbsolute(directory))
+        throw failure();
+    const resolved = path_1.default.resolve(directory);
+    const parsed = path_1.default.parse(resolved);
+    const snapshots = [];
+    let current = parsed.root;
+    for (const component of ['', ...path_1.default.relative(parsed.root, resolved).split(path_1.default.sep).filter(Boolean)]) {
+        if (component)
+            current = path_1.default.join(current, component);
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(current, { bigint: true });
+        }
+        catch {
+            throw failure();
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw failure();
+        snapshots.push({ name: current, stat });
+    }
+    return snapshots;
+}
+function assertDirectoryChainUnchanged(snapshots, failure) {
+    for (const snapshot of snapshots) {
+        let current;
+        try {
+            current = fs_1.default.lstatSync(snapshot.name, { bigint: true });
+        }
+        catch {
+            throw failure();
+        }
+        if (!current.isDirectory() || current.isSymbolicLink() || !sameIdentity(current, snapshot.stat))
+            throw failure();
+    }
+}
+function withPortableValidatedDirectory(directory, failure, operation) {
+    const snapshots = snapshotDirectoryChain(directory, failure);
+    let result;
+    let operationError;
+    try {
+        result = operation(directory);
+    }
+    catch (error) {
+        operationError = error;
+    }
+    assertDirectoryChainUnchanged(snapshots, failure);
+    if (operationError !== undefined)
+        throw operationError;
+    return result;
+}
+function procfsDescriptorBridgeAvailable() {
+    try {
+        return process.platform === 'linux' && fs_1.default.statSync('/proc/self/fd').isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function withOpenedNoFollowDirectory(open, failure, operation) {
+    let descriptor;
+    try {
+        descriptor = open();
+        const opened = fs_1.default.fstatSync(descriptor, { bigint: true });
+        if (!opened.isDirectory())
+            throw failure();
+        return operation(`/proc/self/fd/${descriptor}`);
+    }
+    catch {
+        throw failure();
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs_1.default.closeSync(descriptor);
+            }
+            catch { /* best effort descriptor cleanup */ }
+        }
+    }
+}
+/**
+ * Bind a directory without following an observable symlink. Linux uses a
+ * descriptor path so ancestor renames cannot redirect work. Other platforms
+ * validate every component and its identity before and after the operation;
+ * Node exposes no portable openat equivalent, so any observable change fails
+ * closed rather than being accepted as a pathname race.
+ */
+function withNoFollowDirectory(directory, failure, operation) {
+    const noFollow = fs_1.default.constants.O_NOFOLLOW;
+    const directoryFlag = fs_1.default.constants.O_DIRECTORY;
+    if (!path_1.default.isAbsolute(directory))
+        throw failure();
+    if (typeof noFollow !== 'number' || typeof directoryFlag !== 'number' || !procfsDescriptorBridgeAvailable()) {
+        return withPortableValidatedDirectory(directory, failure, operation);
+    }
+    let descriptor;
+    try {
+        const parsed = path_1.default.parse(directory);
+        descriptor = fs_1.default.openSync(parsed.root, fs_1.default.constants.O_RDONLY | noFollow | directoryFlag);
+        const relative = path_1.default.relative(parsed.root, path_1.default.resolve(directory));
+        for (const component of relative.split(path_1.default.sep).filter(Boolean)) {
+            const next = fs_1.default.openSync(`/proc/self/fd/${descriptor}/${component}`, fs_1.default.constants.O_RDONLY | noFollow | directoryFlag);
+            fs_1.default.closeSync(descriptor);
+            descriptor = next;
+        }
+        const finalDescriptor = descriptor;
+        descriptor = undefined;
+        return withOpenedNoFollowDirectory(() => finalDescriptor, failure, operation);
+    }
+    catch {
+        throw failure();
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                fs_1.default.closeSync(descriptor);
+            }
+            catch { /* already closed during a failed handoff */ }
+        }
+    }
+}
 /**
- * Read the exact regular file that was previously inspected. POSIX gets
- * O_NOFOLLOW; platforms that do not expose it (notably Windows) compare the
- * bigint device/inode identity and size across open. Bigints avoid losing the
- * high bits of Windows file IDs.
+ * Run a filesystem mutation only through a descriptor-bound directory path.
+ * Identity snapshots are sufficient for bounded reads, but cannot make a
+ * pathname write safe: a parent can be replaced after the snapshot and before
+ * `mkdtemp`, staging, or publication. Platforms without the Linux descriptor
+ * bridge therefore reject before the mutation callback begins.
  */
+function withDescriptorBoundWriteDirectory(directory, failure, operation) {
+    const noFollow = fs_1.default.constants.O_NOFOLLOW;
+    const directoryFlag = fs_1.default.constants.O_DIRECTORY;
+    if (typeof noFollow !== 'number' || typeof directoryFlag !== 'number' || !procfsDescriptorBridgeAvailable())
+        throw failure();
+    return withNoFollowDirectory(directory, failure, operation);
+}
+/** Open one direct child from a previously bound directory without path re-resolution. */
+function withNoFollowChildDirectory(parentDirectory, component, failure, operation) {
+    const noFollow = fs_1.default.constants.O_NOFOLLOW;
+    const directoryFlag = fs_1.default.constants.O_DIRECTORY;
+    if (!component || component === '.' || component === '..' || /[\\/]/.test(component))
+        throw failure();
+    if (typeof noFollow !== 'number' || typeof directoryFlag !== 'number' || !procfsDescriptorBridgeAvailable()) {
+        return withPortableValidatedDirectory(path_1.default.join(parentDirectory, component), failure, operation);
+    }
+    return withOpenedNoFollowDirectory(() => fs_1.default.openSync(path_1.default.join(parentDirectory, component), fs_1.default.constants.O_RDONLY | noFollow | directoryFlag), failure, operation);
+}
+/** Read the exact regular file that was previously inspected. */
 function readInspectedBoundedFile(file, inspected, maxBytes, failure) {
+    // The JS descriptor bridge passes /proc/self/fd paths internally on Linux.
+    // They are already descriptor-bound; the native loader correctly rejects the
+    // procfs symlink representation, so retain this narrow internal path only.
+    const descriptorBoundInternalPath = process.platform === 'linux' && file.startsWith('/proc/self/fd/');
+    // The native boundary is mandatory in every shipped runtime. The
+    // filesystem race corpus opts into the portable path through a test-only
+    // seam; environment variables can never weaken production reads.
+    if (!secureFsForTest && !descriptorBoundInternalPath && !portableReadForTests) {
+        return readInspectedBoundedFileWithIdentity(file, inspected, maxBytes, failure).content;
+    }
+    // Test adapters observe the same boundary, then deliberately exercise the
+    // legacy race fixtures below. They are never selected by production code.
+    if (secureFsForTest)
+        secureFsForTest.readRegularFile(file, maxBytes);
     const noFollow = fs_1.default.constants.O_NOFOLLOW;
+    const directorySnapshots = typeof noFollow === 'number' && procfsDescriptorBridgeAvailable()
+        ? undefined
+        : snapshotDirectoryChain(path_1.default.dirname(file), () => failure('identity'));
     let descriptor;
     try {
         descriptor = fs_1.default.openSync(file, fs_1.default.constants.O_RDONLY | (typeof noFollow === 'number' ? noFollow : 0));
@@ -30,7 +240,7 @@ function readInspectedBoundedFile(file, inspected, maxBytes, failure) {
         }
         if (!opened.isFile())
             throw failure('regular');
-        if (opened.dev !== inspected.dev || opened.ino !== inspected.ino)
+        if (!sameIdentity(opened, inspected))
             throw failure('identity');
         if (opened.size !== inspected.size)
             throw failure('size');
@@ -43,9 +253,34 @@ function readInspectedBoundedFile(file, inspected, maxBytes, failure) {
             throw failure('limit');
         if (BigInt(count) !== opened.size)
             throw failure('size');
+        const after = fs_1.default.fstatSync(descriptor, { bigint: true });
+        if (!after.isFile() || !sameIdentity(after, opened))
+            throw failure('identity');
+        if (after.size !== opened.size)
+            throw failure('size');
+        if (directorySnapshots)
+            assertDirectoryChainUnchanged(directorySnapshots, () => failure('identity'));
         return buffer.subarray(0, count);
     }
     finally {
         fs_1.default.closeSync(descriptor);
     }
 }
+/**
+ * Preserve the opaque identity minted by the same native handle that supplied
+ * the bytes. Replacement callers must pass this observation back unchanged.
+ */
+function readInspectedBoundedFileWithIdentity(file, inspected, maxBytes, failure) {
+    if (process.platform === 'linux' && file.startsWith('/proc/self/fd/'))
+        throw failure('identity');
+    let observed;
+    try {
+        observed = activeSecureFs().readRegularFile(file, maxBytes);
+    }
+    catch {
+        throw failure('open');
+    }
+    if (BigInt(observed.bytes.length) !== inspected.size)
+        throw failure('size');
+    return Object.freeze({ content: observed.bytes, identity: observed.identity });
+}

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

@@ -39,8 +39,8 @@ async function runCoverage(cwd, dependencies = {}, options = {}) {
             empirical: empirical(deps, input.projectRoot, {}, min, 'unavailable') };
     }
     let live;
-    if (input.manifest.kind === 'v2') {
-        live = (await deps.resolveLive(input.projectRoot, input.pack, input.manifest.pack.registryRoot)).sensors;
+    if (input.manifest.kind !== 'legacy') {
+        live = (await deps.resolveLive(input.projectRoot, input.pack, input.registryRoot)).sensors;
     }
     else {
         live = Object.fromEntries(Object.keys(input.manifest.pack.sensors).map((name) => [name, (0, manifest_1.legacyCompatibility)('legacy manifest without schemaVersion')]));