agentic-workflow-manager 9.4.1 → 9.6.0

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

@@ -9,7 +9,7 @@ const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const status_1 = require("../sensors/status");
-const init_1 = require("../sensors/init");
+const detection_1 = require("../sensors/detection");
 const baseline_1 = require("../sensors/baseline");
 const run_1 = require("../sensors/run");
 const paths_1 = require("../../core/paths");
@@ -83,13 +83,13 @@ function checkContextKernel(cwd) {
         remedy: inspection.remedy,
     };
 }
-function readManifest(cwd) {
-    try {
-        return JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, MANIFEST), 'utf-8'));
-    }
-    catch {
+function manifestView(status) {
+    if (!status.pack)
         return null;
-    }
+    const sensors = Object.fromEntries(Object.entries(status.checks).map(([name, check]) => [name, {
+            enabled: check.detail !== 'disabled',
+        }]));
+    return { pack: status.pack, sensors };
 }
 /**
  * Total sensor entries and how many are enabled (`enabled !== false`, so a missing
@@ -111,8 +111,8 @@ function countEnabledSensors(manifest) {
  * `awm sensors init`" look identical from the outside, and on a team the second one is
  * the common case. Requiring the manifest turns the decision into a reviewable diff.
  */
-function checkManifest(cwd, manifest) {
-    if (!fs_1.default.existsSync(path_1.default.join(cwd, MANIFEST))) {
+function checkManifest(status) {
+    if (status.mode === 'missing') {
         return {
             id: 'manifest',
             ok: false,
@@ -121,14 +121,26 @@ function checkManifest(cwd, manifest) {
                 + '`"enabled": false` — an unconfigured repo and a deliberate opt-out must not look alike)',
         };
     }
-    if (!manifest) {
+    if (status.mode === 'invalid') {
         return {
             id: 'manifest',
             ok: false,
-            detail: '.awm/sensors.json is not valid JSON',
+            detail: status.reason === 'schema-unsupported'
+                ? '.awm/sensors.json uses an unsupported schema'
+                : '.awm/sensors.json is not valid JSON',
             remedy: 'fix or regenerate it with `awm sensors init`',
         };
     }
+    if (status.mode === 'native-gate')
+        return { id: 'manifest', ok: true, detail: 'native CI quality authority declared', remedy: 'verify the native CI gate before accepting this run' };
+    if (status.mode === 'opt-out')
+        return { id: 'manifest', ok: true, detail: 'local quality gate deliberately disabled', remedy: 'remove the opt-out declaration or provide a quality gate' };
+    if (status.mode === 'source-unavailable' || status.mode === 'source-ambiguous') {
+        return { id: 'manifest', ok: false, detail: `sensor source ${status.mode}: ${status.reason}`, remedy: status.remedy };
+    }
+    const manifest = manifestView(status);
+    if (!manifest)
+        return { id: 'manifest', ok: false, detail: 'sensor authority is unavailable', remedy: 'repair or regenerate the sensor manifest' };
     const { total, enabled } = countEnabledSensors(manifest);
     // total === 0 is NOT an opt-out: a deliberate opt-out lists every known sensor NAME
     // explicitly with `enabled: false` (total > 0, enabled === 0). Zero entries means
@@ -151,8 +163,7 @@ function checkManifest(cwd, manifest) {
     };
 }
 /** Every enabled sensor's command must resolve. This is the check nothing was calling. */
-async function checkTools(cwd) {
-    const status = await (0, status_1.computeSensorStatus)(cwd);
+async function checkTools(cwd, status) {
     if (status.overall === 'NOT_CONFIGURED') {
         return { id: 'tools', ok: false, detail: 'no manifest to check', remedy: 'run `awm sensors init`' };
     }
@@ -188,10 +199,11 @@ async function checkTools(cwd) {
  * same drift (`packDrift`) but never rewrites the manifest, so this is the blocking
  * surface, and `awm sensors init` is the only thing that adopts the real pack.
  */
-function checkPack(cwd, manifest) {
+function checkPack(cwd, status) {
+    const manifest = manifestView(status);
     if (!manifest)
         return { id: 'pack', ok: true, detail: 'skipped (no manifest)' };
-    const detection = (0, init_1.detectStack)(cwd);
+    const detection = (0, detection_1.detectStack)(cwd);
     if (manifest.pack === 'generic' && detection.pack !== 'generic') {
         return {
             id: 'pack',
@@ -231,7 +243,8 @@ function checkPack(cwd, manifest) {
  * "baseline present" for that same case, reassuring the operator that debt is being
  * suppressed when it silently is not.
  */
-function checkSensorsBaseline(cwd, manifest) {
+function checkSensorsBaseline(cwd, status) {
+    const manifest = manifestView(status);
     const enabled = manifest ? countEnabledSensors(manifest).enabled : 0;
     if (enabled === 0) {
         return { id: 'sensors-baseline', ok: true, detail: 'no enabled sensors — nothing to baseline' };
@@ -432,17 +445,21 @@ async function preflight(cwd = process.cwd(), opts = {}) {
         || (opts.requireCurrent !== undefined && typeof opts.requireCurrent !== 'boolean')) {
         throw new Error('preflight options must contain optional boolean verifySensors and requireCurrent');
     }
-    const manifest = readManifest(cwd);
-    const manifestExists = fs_1.default.existsSync(path_1.default.join(cwd, MANIFEST));
+    const sensorStatus = await (0, status_1.computeSensorStatus)(cwd);
+    const manifestExists = sensorStatus.mode !== 'missing';
     const contextKernel = checkContextKernel(cwd);
     const checks = [
         checkContext(cwd),
         ...(contextKernel ? [contextKernel] : []),
-        checkManifest(cwd, manifest),
+        checkManifest(sensorStatus),
         // Skipped when there is no manifest: reporting "tools broken" (or nudging toward
         // a baseline that has nothing to snapshot) on a repo that was never set up
         // buries the one thing the operator needs to read.
-        ...(manifestExists ? [await checkTools(cwd), checkPack(cwd, manifest), checkSensorsBaseline(cwd, manifest)] : []),
+        ...(manifestExists && !['native-gate', 'opt-out', 'source-unavailable', 'source-ambiguous'].includes(sensorStatus.mode ?? '')
+            ? [
+                ...(sensorStatus.mode !== 'invalid' ? [await checkTools(cwd, sensorStatus), checkPack(cwd, sensorStatus)] : []),
+                checkSensorsBaseline(cwd, sensorStatus),
+            ] : []),
         // The empirical mode is intentionally opt-in: ordinary preflight remains a
         // quick static inspection and must not dispatch project software.
         ...(opts.verifySensors === true ? [await checkSensorExecution(cwd)] : []),
@@ -455,17 +472,31 @@ async function preflight(cwd = process.cwd(), opts = {}) {
     const blockingFailure = (check) => !check.ok && check.advisory !== true;
     const invalidContextKernel = contextKernel !== null && blockingFailure(contextKernel);
     const status = invalidContextKernel ? 'degraded'
-        : !manifestExists ? 'not_configured'
-            : checks.some(blockingFailure) ? 'degraded'
-                : 'ready';
+        : sensorStatus.mode === 'native-gate' ? 'native_gate'
+            : sensorStatus.mode === 'opt-out' ? 'ungated'
+                : !manifestExists ? 'not_configured'
+                    : checks.some(blockingFailure) ? 'degraded'
+                        : 'ready';
     const currentness = opts.requireCurrent === true ? await (0, check_1.checkCurrentness)(cwd) : undefined;
     if (currentness) {
         checks.splice(checks.length - 1, 0, checkAuthoritativeCurrentness(currentness));
     }
     const strictFailure = checks.some(blockingFailure);
     const strictStatus = invalidContextKernel ? 'degraded'
-        : !manifestExists ? 'not_configured'
-            : strictFailure ? 'degraded'
-                : 'ready';
-    return currentness ? { status: strictStatus, checks, currentness } : { status, checks };
+        : sensorStatus.mode === 'native-gate' ? 'native_gate'
+            : sensorStatus.mode === 'opt-out' ? 'ungated'
+                : !manifestExists ? 'not_configured'
+                    : strictFailure ? 'degraded'
+                        : 'ready';
+    const authorityRemedy = sensorStatus.remedy
+        ?? (sensorStatus.mode === 'native-gate' ? 'verify the declared native CI quality gate before accepting this run'
+            : sensorStatus.mode === 'opt-out' ? 'remove the opt-out declaration or provide a quality gate' : undefined);
+    const authority = {
+        mode: sensorStatus.mode ?? 'invalid',
+        reason: sensorStatus.reason ?? 'sensor-authority-unavailable',
+        projectRoot: sensorStatus.projectRoot ?? path_1.default.resolve(cwd),
+        manifestPath: sensorStatus.manifestPath ?? path_1.default.join(path_1.default.resolve(cwd), MANIFEST),
+        ...(authorityRemedy ? { remedy: authorityRemedy } : {}),
+    };
+    return currentness ? { status: strictStatus, checks, currentness, ...authority } : { status, checks, ...authority };
 }

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

@@ -0,0 +1,171 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planSensorBootstrap = planSensorBootstrap;
+exports.applySensorBootstrap = applySensorBootstrap;
+const registries_1 = require("../../core/registries");
+const contract_1 = require("./compatibility/contract");
+const manifest_1 = require("./compatibility/manifest");
+const pack_source_1 = require("./compatibility/pack-source");
+const live_1 = require("./compatibility/live");
+const source_1 = require("./compatibility/source");
+const detection_1 = require("./detection");
+const migrate_1 = require("./migrate");
+const project_1 = require("./project");
+const materialize_1 = require("./compatibility/materialize");
+const migrate_2 = require("./migrate");
+const safe_file_1 = require("./compatibility/safe-file");
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
+function blocked(projectRoot, manifestPath, dryRun, reason, remedy, candidates) {
+    return { kind: 'blocked', projectRoot, manifestPath, changes: [], dryRun, reason, remedy, ...(candidates ? { candidates } : {}) };
+}
+function options(input) {
+    if (input === undefined)
+        return { dryRun: false };
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('bootstrap options must be an object');
+    const value = input;
+    if (Object.keys(value).some(key => !['mode', 'reason', 'dryRun', 'registryRoot', 'configure', 'pack', 'packageRoot'].includes(key)))
+        throw new Error('bootstrap options contain an unknown field');
+    if (value.mode !== undefined && value.mode !== 'project-sensors' && value.mode !== 'native-gate' && value.mode !== 'opt-out')
+        throw new Error('bootstrap mode must be project-sensors, native-gate, or opt-out');
+    if (value.reason !== undefined && (typeof value.reason !== 'string' || value.reason.trim() === '' || value.reason.length > 512 || /[\0\r\n]/.test(value.reason)))
+        throw new Error('bootstrap reason must be a nonempty bounded single-line string');
+    if (value.dryRun !== undefined && typeof value.dryRun !== 'boolean')
+        throw new Error('bootstrap dryRun must be a boolean');
+    if (value.configure !== undefined && typeof value.configure !== 'boolean')
+        throw new Error('bootstrap configure must be a boolean');
+    if (value.registryRoot !== undefined && (typeof value.registryRoot !== 'string' || (!path_1.default.isAbsolute(value.registryRoot) && !path_1.default.win32.isAbsolute(value.registryRoot)) || /[\0\r\n]/.test(value.registryRoot)))
+        throw new Error('bootstrap registryRoot must be an absolute single-line path');
+    if (value.pack !== undefined && (typeof value.pack !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value.pack)))
+        throw new Error('bootstrap pack must be a stable lowercase id');
+    if (value.packageRoot !== undefined && (typeof value.packageRoot !== 'string' || value.packageRoot.length === 0 || value.packageRoot.includes('\\') || value.packageRoot.split('/').some(part => part === '' || part === '.' || part === '..')))
+        throw new Error('bootstrap packageRoot must be a contained relative path');
+    return { mode: value.mode, reason: value.reason, dryRun: value.dryRun === true, registryRoot: value.registryRoot, configure: value.configure !== false, pack: value.pack, packageRoot: value.packageRoot };
+}
+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) {
+    const detectionRoot = packageRoot ? path_1.default.resolve(projectRoot, packageRoot) : projectRoot;
+    const detected = (0, detection_1.detectStack)(detectionRoot);
+    const pack = requestedPack ?? detected.pack;
+    const registries = (0, registries_1.listRegistries)();
+    const selected = registryRoot === undefined ? registries : registries.filter(registry => registry.contentRoot === registryRoot);
+    if (registryRoot !== undefined && selected.length !== 1)
+        return { reason: 'registry-root-not-configured', remedy: 'configure-the-registry-before-bootstrap' };
+    const sources = (0, pack_source_1.listPackSources)(pack, { registries: selected });
+    if (sources.length === 0)
+        return { reason: 'source-unavailable', remedy: 'install-registry-or-run-awm-update' };
+    if (sources.length !== 1)
+        return { reason: 'source-ambiguous', remedy: 'configure-one-logical-registry', candidates: sources.map(item => item.registry.name).sort().slice(0, 32) };
+    const source = sources[0];
+    let parsed;
+    try {
+        parsed = (0, contract_1.parseSensorPack)(JSON.parse(source.content), source.path);
+    }
+    catch {
+        return { reason: 'source-invalid', remedy: 'repair-or-run-awm-update' };
+    }
+    if (parsed.kind !== 'v2')
+        return { reason: 'source-unsupported', remedy: 'install-a-v2-sensor-pack' };
+    let live;
+    try {
+        live = await (0, live_1.resolveParsedPackCompatibility)(detectionRoot, parsed.pack);
+    }
+    catch {
+        return { reason: 'compatibility-unresolvable', remedy: 'repair-project-tools-or-select-another-mode' };
+    }
+    const sensors = {};
+    for (const [name, packSensor] of Object.entries(live.pack.sensors)) {
+        const evidence = live.sensors[name];
+        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' };
+        sensors[name] = { enabled: true, ...(packSensor.fast === undefined ? {} : { fast: packSensor.fast }), ...(packSensor.timeout === undefined ? {} : { timeout: packSensor.timeout }), variantId: variant.id, command: variant.command, ...(variant.assets.length === 0 ? {} : { assets: variant.assets }), ...(variant.policyRef ? { policyRef: variant.policyRef } : {}), initializedCompatibility: evidence };
+    }
+    const manifest = (0, manifest_1.parseSensorManifest)({ schemaVersion: 3, mode: 'project-sensors', pack, source: { registry: source.registry.name }, ...(packageRoot ? { packageRoot } : {}), sensors }, 'bootstrap candidate');
+    if (manifest.kind !== 'v3' || manifest.pack.mode !== 'project-sensors')
+        throw new Error('bootstrap project-sensors candidate is invalid');
+    (0, manifest_1.serializeManifestV3)(manifest.pack);
+    const assets = [...new Set(Object.values(sensors).flatMap(sensor => sensor.assets ?? []))].sort();
+    return { manifest: manifest.pack, source, changes: [{ path: '.awm/sensors.json', action: 'create' }, ...assets.map(asset => ({ path: packageRoot ? `${packageRoot}/${asset}` : asset, action: 'create' }))] };
+}
+/** Plan a one-time portable bootstrap. This function never writes project or machine state. */
+async function planSensorBootstrap(cwd = process.cwd(), input = {}) {
+    const opts = options(input);
+    const project = (0, project_1.resolveSensorProject)(cwd);
+    if (project.state === 'invalid')
+        return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'manifest-invalid', 'repair-sensor-manifest');
+    if (project.state === 'configured') {
+        if (project.manifest.kind === 'v3') {
+            if (opts.mode !== undefined && opts.mode !== project.manifest.pack.mode) {
+                return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'mode-conflicts-with-existing-declaration', 'run-bootstrap-without-mode');
+            }
+            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');
+        let source;
+        try {
+            source = (0, source_1.resolveSensorSource)(project.manifest, { registries: (0, registries_1.listRegistries)() });
+        }
+        catch {
+            return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'source-invalid', 'repair-or-run-awm-update');
+        }
+        if (!('source' in source))
+            return blocked(project.projectRoot, project.manifestPath, opts.dryRun, source.reason, source.remedy);
+        try {
+            const original = fs_1.default.readFileSync(project.manifestPath);
+            return { kind: 'migrate', projectRoot: project.projectRoot, manifestPath: project.manifestPath, changes: [{ path: '.awm/sensors.json', action: 'replace' }], dryRun: opts.dryRun, migration: (0, migrate_1.planV2Migration)({ manifest: project.manifest.pack, source }), source, originalDigest: digest(original) };
+        }
+        catch {
+            return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'migration-not-equivalent', 'repair-or-select-one-compatible-registry');
+        }
+    }
+    if (!opts.mode)
+        return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'mode-required', 'choose-project-sensors-native-gate-or-opt-out');
+    if (opts.mode !== 'project-sensors') {
+        if (!opts.reason)
+            return blocked(project.projectRoot, project.manifestPath, opts.dryRun, 'reason-required', 'provide-a-versioned-reason');
+        return { kind: 'create', projectRoot: project.projectRoot, manifestPath: project.manifestPath, changes: [{ path: '.awm/sensors.json', action: 'create' }], dryRun: opts.dryRun, manifest: declaration(opts.mode, opts.reason), configure: opts.configure };
+    }
+    const planned = await projectSensors(project.projectRoot, opts.registryRoot, opts.pack, opts.packageRoot);
+    if ('reason' in planned)
+        return blocked(project.projectRoot, project.manifestPath, opts.dryRun, planned.reason, planned.remedy, 'candidates' in planned ? planned.candidates : undefined);
+    return { kind: 'create', projectRoot: project.projectRoot, manifestPath: project.manifestPath, changes: planned.changes, dryRun: opts.dryRun, manifest: planned.manifest, source: planned.source, configure: opts.configure };
+}
+/** Apply only a validated, non-dry-run create or migration plan. */
+function applySensorBootstrap(plan) {
+    if (!plan || typeof plan !== 'object')
+        throw new Error('bootstrap plan is required');
+    if (plan.kind !== 'create' && plan.kind !== 'migrate')
+        throw new Error('only a create or migrate bootstrap plan can be applied');
+    if (plan.dryRun)
+        throw new Error('a dry-run bootstrap plan cannot be applied');
+    if (plan.kind === 'migrate') {
+        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);
+        return 'migrated';
+    }
+    if (plan.manifest.mode === 'project-sensors') {
+        if (!plan.source)
+            throw new Error('project-sensors bootstrap plan requires its resolved source');
+        (0, materialize_1.materializePortableSensors)({ projectRoot: plan.projectRoot, pack: plan.manifest.pack, source: plan.source, ...(plan.manifest.packageRoot ? { packageRoot: plan.manifest.packageRoot } : {}), sensors: plan.manifest.sensors, configure: plan.configure !== false });
+        return 'created';
+    }
+    const parsed = (0, manifest_1.parseSensorManifest)(plan.manifest, 'bootstrap declaration');
+    if (parsed.kind !== 'v3' || parsed.pack.mode === 'project-sensors')
+        throw new Error('bootstrap declaration plan is invalid');
+    (0, safe_file_1.withProjectLease)(plan.projectRoot, () => {
+        (0, safe_file_1.writeProjectFile)(plan.projectRoot, '.awm/sensors.json', Buffer.from((0, manifest_1.serializeManifestV3)(parsed.pack), 'utf8'), { mode: 'create', createParents: true });
+    });
+    return 'created';
+}

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

@@ -12,6 +12,7 @@ const semver_1 = __importDefault(require("semver"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const contract_1 = require("../coverage/contract");
+const safe_file_1 = require("./safe-file");
 const timeout_1 = require("./timeout");
 const PACK_SCHEMA_VERSION = 2;
 const SHELL_EXECUTABLES = new Set(['sh', 'bash', 'cmd', 'powershell']);
@@ -107,32 +108,34 @@ function resolveSemgrepPolicy(policyRef, source, location = 'policy') {
         invalid(source, `${location}.policyRef escapes sensor-packs root`);
     let stat;
     try {
-        stat = fs_1.default.lstatSync(candidate);
+        stat = fs_1.default.lstatSync(candidate, { bigint: true });
     }
     catch {
         invalid(source, `${location}.policyRef does not resolve to a regular policy file`);
     }
     if (!stat.isFile() || stat.isSymbolicLink() || stat.size > MAX_POLICY_BYTES)
         invalid(source, `${location}.policyRef must resolve to a bounded regular policy file`);
-    let realRoot;
-    let realPolicy;
-    try {
-        realRoot = fs_1.default.realpathSync(sensorPacksRoot);
-        realPolicy = fs_1.default.realpathSync(candidate);
-    }
-    catch {
-        invalid(source, `${location}.policyRef cannot be canonicalized`);
-    }
-    if (!contained(realRoot, realPolicy))
-        invalid(source, `${location}.policyRef escapes sensor-packs root`);
+    const failure = (reason) => {
+        if (reason === 'open')
+            return new Error(`Invalid sensor pack${sourceSuffix(source)}: ${location}.policyRef cannot be safely opened`);
+        if (reason === 'regular')
+            return new Error(`Invalid sensor pack${sourceSuffix(source)}: ${location}.policyRef must resolve to a bounded regular policy file`);
+        if (reason === 'identity')
+            return new Error(`Invalid sensor pack${sourceSuffix(source)}: ${location}.policyRef changed identity during safe open`);
+        if (reason === 'size')
+            return new Error(`Invalid sensor pack${sourceSuffix(source)}: ${location}.policyRef changed size during safe open`);
+        return new Error(`Invalid sensor pack${sourceSuffix(source)}: ${location}.policyRef must resolve to a bounded regular policy file`);
+    };
     let parsed;
     try {
-        parsed = JSON.parse(fs_1.default.readFileSync(realPolicy, 'utf8'));
+        parsed = JSON.parse((0, safe_file_1.readInspectedBoundedFile)(candidate, stat, MAX_POLICY_BYTES, failure).toString('utf8'));
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('Invalid sensor pack'))
+            throw error;
         invalid(source, `${location}.policyRef must contain valid JSON`);
     }
-    return parseSemgrepPolicy(parsed, realPolicy);
+    return parseSemgrepPolicy(parsed, candidate);
 }
 function parseStructuredCommand(input, source) {
     const value = record(input, source, 'command');

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.legacyCompatibility = legacyCompatibility;
 exports.parseSensorManifest = parseSensorManifest;
 exports.serializeManifestV2 = serializeManifestV2;
+exports.serializeManifestV3 = serializeManifestV3;
 const contract_1 = require("./contract");
 const timeout_1 = require("./timeout");
 const semver_1 = __importDefault(require("semver"));
@@ -183,6 +184,22 @@ function provenanceRoot(value, source) {
         invalid(source, 'registryRoot must be an absolute normalized path');
     return parsed;
 }
+/**
+ * A v3 declaration is copied between machines, so no nested string may retain
+ * a host path. Structured command arguments are intentionally free-form and
+ * are therefore the only remaining place an otherwise validated declaration
+ * could hide one.
+ */
+function containsPhysicalPath(value) {
+    if (typeof value === 'string') {
+        // Web URLs are portable command values, not host filesystem paths.
+        const withoutWebUrls = value.replace(/https?:\/\/[^\s"']+/gi, '');
+        return /(?:^|[^A-Za-z0-9_.~\/\\-])["']?(?:\/|\\|[A-Za-z]:|\/\/)/.test(withoutWebUrls);
+    }
+    return Array.isArray(value)
+        ? value.some(containsPhysicalPath)
+        : isRecord(value) && Object.values(value).some(containsPhysicalPath);
+}
 function parseV2Manifest(value, source) {
     fields(value, ['schemaVersion', 'pack', 'packSelection', 'registryRoot', 'packageRoot', 'sensors', 'concurrency'], source, 'root');
     if (value.schemaVersion !== 2)
@@ -209,13 +226,69 @@ function parseV2Manifest(value, source) {
     }
     return manifest;
 }
+function parseV3ProjectManifest(value, source) {
+    fields(value, ['schemaVersion', 'mode', 'pack', 'packSelection', 'source', 'packageRoot', 'sensors', 'concurrency'], source, 'root');
+    const sourceValue = record(value.source, source, 'source');
+    fields(sourceValue, ['registry'], source, 'source');
+    const sensorsInput = record(value.sensors, source, 'sensors');
+    const sensors = {};
+    for (const name of Object.keys(sensorsInput))
+        sensors[id(name, source, 'sensor id')] = parseV2Sensor(sensorsInput[name], source, `sensors.${name}`);
+    const manifest = {
+        schemaVersion: 3,
+        mode: 'project-sensors',
+        pack: id(value.pack, source, 'pack'),
+        source: { registry: id(sourceValue.registry, source, 'source.registry') },
+        sensors,
+    };
+    if ('packSelection' in value) {
+        if (value.packSelection !== 'explicit')
+            invalid(source, 'packSelection must be "explicit" when present');
+        manifest.packSelection = 'explicit';
+    }
+    if ('packageRoot' in value)
+        manifest.packageRoot = asset(value.packageRoot, source, 'packageRoot');
+    if ('concurrency' in value) {
+        if (typeof value.concurrency !== 'number' || !Number.isSafeInteger(value.concurrency) || value.concurrency <= 0)
+            invalid(source, 'concurrency must be a positive safe integer');
+        manifest.concurrency = value.concurrency;
+    }
+    return manifest;
+}
+function parseV3Manifest(value, source) {
+    if (value.schemaVersion !== 3)
+        invalid(source, `unsupported manifest schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2, 3; upgrade or migrate the manifest`);
+    if (value.mode === 'project-sensors')
+        return parseV3ProjectManifest(value, source);
+    if (value.mode !== 'native-gate' && value.mode !== 'opt-out')
+        invalid(source, 'schemaVersion 3 mode must be "project-sensors", "native-gate", or "opt-out"');
+    fields(value, ['schemaVersion', 'mode', 'reason'], source, 'root');
+    return { schemaVersion: 3, mode: value.mode, reason: text(value.reason, source, 'reason') };
+}
 function parseSensorManifest(input, source) {
     const value = record(input, source, 'root');
-    return 'schemaVersion' in value ? { kind: 'v2', pack: parseV2Manifest(value, source) } : { kind: 'legacy', pack: parseLegacyManifest(value, source) };
+    if (!('schemaVersion' in value))
+        return { kind: 'legacy', pack: parseLegacyManifest(value, source) };
+    if (value.schemaVersion === 2)
+        return { kind: 'v2', pack: parseV2Manifest(value, source) };
+    if (value.schemaVersion === 3)
+        return { kind: 'v3', pack: parseV3Manifest(value, source) };
+    invalid(source, `unsupported manifest schemaVersion ${String(value.schemaVersion)}; supported: legacy, 2, 3; upgrade or migrate the manifest`);
 }
 function serializeManifestV2(input) {
     const parsed = parseSensorManifest(input, 'manifest serialization');
     if (parsed.kind !== 'v2')
         throw new Error('Cannot serialize a legacy sensor manifest as v2');
-    return JSON.stringify(parsed.pack, null, 2);
+    return JSON.stringify(parsed.pack, null, 2) + '\n';
+}
+/** Serialize a validated portable v3 declaration deterministically. */
+function serializeManifestV3(input) {
+    const parsed = parseSensorManifest(input, 'manifest serialization');
+    if (parsed.kind !== 'v3') {
+        throw new Error('Cannot serialize a non-v3 sensor manifest as v3');
+    }
+    if (parsed.pack.mode === 'project-sensors' && containsPhysicalPath(parsed.pack)) {
+        throw new Error('Cannot serialize a v3 declaration containing a physical path');
+    }
+    return JSON.stringify(parsed.pack, null, 2) + '\n';
 }