agentic-workflow-manager 9.5.0 → 9.6.0

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

@@ -11,7 +11,9 @@ const contract_1 = require("./contract");
 const contract_2 = require("../compatibility/contract");
 const manifest_1 = require("../compatibility/manifest");
 const pack_source_1 = require("../compatibility/pack-source");
+const source_1 = require("../compatibility/source");
 const safe_file_1 = require("../compatibility/safe-file");
+const registries_1 = require("../../../core/registries");
 function readFailure(file, error) {
     return new Error(`Cannot read ${file}: ${error instanceof Error ? error.message : String(error)}`);
 }
@@ -82,11 +84,19 @@ function resolveCoverageInputs(cwd) {
         return { kind: 'not_configured' };
     const manifestPath = path_1.default.join(projectRoot, '.awm', 'sensors.json');
     const manifest = (0, manifest_1.parseSensorManifest)(readBoundedJson(manifestPath), manifestPath);
-    if (manifest.kind === 'v3')
-        throw new Error('schemaVersion 3 sensor manifests require the project resolver');
-    const source = manifest.kind === 'v2' && manifest.pack.registryRoot !== undefined
-        ? (0, pack_source_1.resolvePackSource)(manifest.pack.pack, { registries: [{ name: 'manifest-provenance', remote: 'local', contentRoot: manifest.pack.registryRoot }] })
-        : (0, pack_source_1.resolvePackSource)(manifest.pack.pack);
+    if (manifest.kind === 'v3' && manifest.pack.mode !== 'project-sensors')
+        return { kind: 'not_configured' };
+    const coverageManifest = manifest;
+    const source = coverageManifest.kind === 'v3'
+        ? (() => {
+            const resolution = (0, source_1.resolveSensorSource)(coverageManifest, { registries: (0, registries_1.listRegistries)() });
+            if (!('source' in resolution))
+                throw new Error(`${resolution.kind}: ${resolution.remedy}`);
+            return resolution.source;
+        })()
+        : coverageManifest.kind === 'v2' && coverageManifest.pack.registryRoot !== undefined
+            ? (0, pack_source_1.resolvePackSource)(coverageManifest.pack.pack, { registries: [{ name: 'manifest-provenance', remote: 'local', contentRoot: coverageManifest.pack.registryRoot }] })
+            : (0, pack_source_1.resolvePackSource)(coverageManifest.pack.pack);
     let sourceJson;
     try {
         sourceJson = JSON.parse(source.content);
@@ -95,14 +105,14 @@ function resolveCoverageInputs(cwd) {
         throw new Error(`Invalid JSON at ${source.path}: ${error instanceof Error ? error.message : String(error)}`);
     }
     const parsedPack = (0, contract_2.parseSensorPack)(sourceJson, source.path);
-    if (parsedPack.pack.name !== manifest.pack.pack) {
-        throw new Error(`Invalid pack at ${source.path}: name must equal '${manifest.pack.pack}'`);
+    if (parsedPack.pack.name !== coverageManifest.pack.pack) {
+        throw new Error(`Invalid pack at ${source.path}: name must equal '${coverageManifest.pack.pack}'`);
     }
     const { coverage } = parsedPack.pack;
     if (coverage === undefined)
-        return { kind: 'no_reference', projectRoot, pack: manifest.pack.pack, registry: source.registry.name, manifest };
+        return { kind: 'no_reference', projectRoot, pack: coverageManifest.pack.pack, registry: source.registry.name, registryRoot: source.registry.contentRoot, manifest: coverageManifest };
     return {
-        kind: 'ready', projectRoot, pack: manifest.pack.pack, registry: source.registry.name,
-        manifest, contract: (0, contract_1.parseCoverageContract)(coverage, source.path),
+        kind: 'ready', projectRoot, pack: coverageManifest.pack.pack, registry: source.registry.name,
+        registryRoot: source.registry.contentRoot, manifest: coverageManifest, contract: (0, contract_1.parseCoverageContract)(coverage, source.path),
     };
 }

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

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectStack = detectStack;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const DETECTORS = [
+    { pack: 'js-ts', files: ['package.json'] },
+    { pack: 'python', files: ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'] },
+];
+/** Read-only stack classification shared by run, bootstrap, and legacy init. */
+function detectStack(cwd) {
+    for (const { pack, files } of DETECTORS) {
+        const indicators = files.filter(file => fs_1.default.existsSync(path_1.default.join(cwd, file)));
+        if (indicators.length > 0)
+            return { pack, indicators };
+    }
+    for (const directory of ['.', 'scripts']) {
+        const absolute = path_1.default.join(cwd, directory);
+        if (!fs_1.default.existsSync(absolute) || !fs_1.default.statSync(absolute).isDirectory())
+            continue;
+        const indicators = fs_1.default.readdirSync(absolute, { withFileTypes: true })
+            .filter(entry => entry.isFile() && entry.name.endsWith('.sh'))
+            .map(entry => directory === '.' ? entry.name : path_1.default.join(directory, entry.name));
+        if (indicators.length > 0)
+            return { pack: 'shell', indicators };
+    }
+    return { pack: 'generic', indicators: [] };
+}

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

@@ -7,12 +7,42 @@ exports.runStructuredCommand = runStructuredCommand;
 exports.runCommand = runCommand;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const paths_1 = require("../../core/paths");
 const DEFAULT_MAX_BUFFER = 64 * 1024 * 1024;
 const DEFAULT_KILL_GRACE_MS = 2_000;
 /** After SIGKILL, resolve regardless. A sensor must never hang the gate. */
 const POST_KILL_GRACE_MS = 1_000;
+const PRLIMIT_PATHS = ['/usr/bin/prlimit', '/bin/prlimit'];
+/** Decode a byte-bounded capture without allowing replacement characters to
+ * expand it. Invalid input bytes become one-byte `?` markers. */
+function decodeBoundedOutput(buffer) {
+    const decoded = Buffer.allocUnsafe(buffer.length);
+    let read = 0;
+    let written = 0;
+    const continuation = (index) => index < buffer.length && (buffer[index] & 0b1100_0000) === 0b1000_0000;
+    while (read < buffer.length) {
+        const first = buffer[read];
+        let length = 1;
+        if (first >= 0xc2 && first <= 0xdf && continuation(read + 1))
+            length = 2;
+        else if (first >= 0xe0 && first <= 0xef && continuation(read + 1) && continuation(read + 2)
+            && !(first === 0xe0 && buffer[read + 1] < 0xa0) && !(first === 0xed && buffer[read + 1] > 0x9f))
+            length = 3;
+        else if (first >= 0xf0 && first <= 0xf4 && continuation(read + 1) && continuation(read + 2) && continuation(read + 3)
+            && !(first === 0xf0 && buffer[read + 1] < 0x90) && !(first === 0xf4 && buffer[read + 1] > 0x8f))
+            length = 4;
+        else if (first >= 0x80)
+            decoded[written++] = 0x3f;
+        if (length > 1 || first < 0x80) {
+            buffer.copy(decoded, written, read, read + length);
+            written += length;
+        }
+        read += length;
+    }
+    return decoded.subarray(0, written).toString('utf8');
+}
 /**
  * Kill an entire process tree, not just its root.
  *
@@ -76,10 +106,59 @@ function collectSpawn(input, opts) {
         const startedAt = process.hrtime.bigint();
         let stdout = '';
         let stderr = '';
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let capturedBytes = 0;
         let timedOut = false;
         let overflowed = false;
         let settled = false;
         const timers = [];
+        const prlimit = !input.shell && process.platform === 'linux'
+            ? PRLIMIT_PATHS.find(candidate => regularFile(candidate))
+            : undefined;
+        const streamMaxBuffer = maxBuffer;
+        // Some structured Node CLIs call process.exit() after writing their
+        // report. Node drops an asynchronous pipe write in that case, but a
+        // regular file descriptor is flushed before exit. Keep the report on
+        // disk only until settlement. Each channel is hard-capped at maxBuffer
+        // while a shared decode budget caps the returned combined output.
+        // Linux enforces the per-file cap before either child stream can grow
+        // unbounded; polling alone can only discover excess after it happens.
+        const captureDir = prlimit ? fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-sensor-output-')) : undefined;
+        const stdoutPath = captureDir ? path_1.default.join(captureDir, 'stdout') : undefined;
+        const stderrPath = captureDir ? path_1.default.join(captureDir, 'stderr') : undefined;
+        const stdoutFd = stdoutPath ? fs_1.default.openSync(stdoutPath, 'w') : undefined;
+        const stderrFd = stderrPath ? fs_1.default.openSync(stderrPath, 'w') : undefined;
+        const readCaptured = (file, fd, budget) => {
+            fs_1.default.closeSync(fd);
+            const size = fs_1.default.statSync(file).size;
+            if (size >= streamMaxBuffer)
+                overflowed = true;
+            if (size > budget)
+                overflowed = true;
+            const bytes = Math.min(size, budget);
+            const buffer = Buffer.allocUnsafe(bytes);
+            if (buffer.length > 0) {
+                const readFd = fs_1.default.openSync(file, 'r');
+                try {
+                    fs_1.default.readSync(readFd, buffer, 0, buffer.length, 0);
+                }
+                finally {
+                    fs_1.default.closeSync(readFd);
+                }
+            }
+            return { output: decodeBoundedOutput(buffer), bytes };
+        };
+        const captureSize = (file) => {
+            if (!file)
+                return 0;
+            try {
+                return fs_1.default.statSync(file).size;
+            }
+            catch {
+                return 0;
+            }
+        };
         const child = input.shell
             ? (0, child_process_1.spawn)(input.executable, {
                 shell: true,
@@ -87,14 +166,16 @@ function collectSpawn(input, opts) {
                 detached: !(0, paths_1.isWindowsNative)(),
                 stdio: ['ignore', 'pipe', 'pipe'],
             })
-            : (0, child_process_1.spawn)(input.executable, input.args, {
+            : (0, child_process_1.spawn)(prlimit ?? input.executable, prlimit
+                ? [`--fsize=${streamMaxBuffer}`, '--', input.executable, ...input.args]
+                : input.args, {
                 shell: false,
                 cwd: opts.cwd,
                 detached: !(0, paths_1.isWindowsNative)(),
                 ...(input.environment ? { env: { ...process.env, ...input.environment } } : {}),
                 // stdin closed: a sensor must never block waiting for input, and the
                 // EOF also tells watch-mode-capable tools (vitest, jest) to run once.
-                stdio: ['ignore', 'pipe', 'pipe'],
+                stdio: prlimit ? ['ignore', stdoutFd, stderrFd] : ['ignore', 'pipe', 'pipe'],
             });
         const later = (fn, ms) => {
             const t = setTimeout(fn, ms);
@@ -107,6 +188,20 @@ function collectSpawn(input, opts) {
                 return;
             settled = true;
             timers.forEach(clearTimeout);
+            if (stdoutPath && stderrPath && stdoutFd !== undefined && stderrFd !== undefined) {
+                try {
+                    const capturedStdout = readCaptured(stdoutPath, stdoutFd, maxBuffer);
+                    stdout = capturedStdout.output;
+                    stderr = readCaptured(stderrPath, stderrFd, maxBuffer - capturedStdout.bytes).output;
+                }
+                finally {
+                    fs_1.default.rmSync(captureDir, { recursive: true, force: true });
+                }
+            }
+            else {
+                stdout = decodeBoundedOutput(Buffer.concat(stdoutChunks));
+                stderr = decodeBoundedOutput(Buffer.concat(stderrChunks));
+            }
             const elapsedMs = Number((process.hrtime.bigint() - startedAt) / 1000000n);
             resolve({ stdout, stderr, code: null, signal: null, timedOut, overflowed, elapsedMs, ...extra });
         };
@@ -124,15 +219,13 @@ function collectSpawn(input, opts) {
         const collect = (into) => (chunk) => {
             if (settled || overflowed)
                 return;
-            const text = String(chunk);
-            const current = into === 'out' ? stdout : stderr;
-            const room = maxBuffer - current.length;
-            const next = current + (text.length > room ? text.slice(0, room) : text);
-            if (into === 'out')
-                stdout = next;
-            else
-                stderr = next;
-            if (next.length >= maxBuffer) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const room = maxBuffer - capturedBytes;
+            const kept = bytes.subarray(0, Math.max(0, room));
+            if (kept.length > 0)
+                (into === 'out' ? stdoutChunks : stderrChunks).push(kept);
+            capturedBytes += kept.length;
+            if (bytes.length > kept.length || capturedBytes >= maxBuffer) {
                 overflowed = true;
                 cutShort();
             }
@@ -143,6 +236,18 @@ function collectSpawn(input, opts) {
         child.stderr?.on('error', () => { });
         child.on('error', (err) => finish({ spawnError: err }));
         child.on('close', (code, signal) => finish({ code, signal }));
+        if (stdoutPath || stderrPath) {
+            const outputWatch = setInterval(() => {
+                const stdoutSize = captureSize(stdoutPath);
+                const stderrSize = captureSize(stderrPath);
+                if (!overflowed && (stdoutSize >= streamMaxBuffer || stderrSize >= streamMaxBuffer || stdoutSize + stderrSize >= maxBuffer)) {
+                    overflowed = true;
+                    cutShort();
+                }
+            }, 25);
+            outputWatch.unref?.();
+            timers.push(outputWatch);
+        }
         later(() => { timedOut = true; cutShort(); }, opts.timeout);
     });
 }

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

@@ -8,7 +8,6 @@ exports.registerSensorsCommand = registerSensorsCommand;
 const picocolors_1 = __importDefault(require("picocolors"));
 const prompts_1 = require("@clack/prompts");
 const run_1 = require("./run");
-const init_1 = require("./init");
 const status_1 = require("./status");
 const install_1 = require("./install");
 const baseline_1 = require("./baseline");
@@ -16,6 +15,7 @@ const coverage_1 = require("./coverage");
 const render_1 = require("./coverage/render");
 const registries_1 = require("../../core/registries");
 const verdict_1 = require("./verdict");
+const bootstrap_1 = require("./bootstrap");
 /** Commander coercion for coverage recurrence emphasis. It deliberately runs
  * before the action, so an invalid value cannot trigger ledger I/O. */
 function parsePositiveSafeInteger(value) {
@@ -71,23 +71,64 @@ function registerSensorsCommand(program) {
         .action(async (opts) => {
         const registryRoot = opts.registryRoot ?? (0, registries_1.capabilityRoot)('sensor-packs') ?? undefined;
         try {
-            const result = await (0, init_1.initSensors)({ configure: opts.configure, registryRoot, pack: opts.pack, packageRoot: opts.packageRoot });
-            prompts_1.log.success(`Detected: ${result.detection.pack} (${result.detection.indicators.join(', ') || 'fallback'})`);
+            const plan = await (0, bootstrap_1.planSensorBootstrap)(process.cwd(), { mode: 'project-sensors', registryRoot, configure: opts.configure, pack: opts.pack, packageRoot: opts.packageRoot });
+            if (plan.kind === 'blocked')
+                throw new Error(`${plan.reason}: ${plan.remedy}`);
+            if (plan.kind === 'noop') {
+                prompts_1.log.info('already-configured');
+                return;
+            }
+            if (plan.kind === 'migrate')
+                throw new Error('sensors init does not migrate an existing v2 manifest; run awm sensors bootstrap');
+            const result = (0, bootstrap_1.applySensorBootstrap)(plan);
+            const detected = plan.manifest.mode === 'project-sensors' ? plan.manifest.pack : 'none';
+            prompts_1.log.success(`Detected: ${detected}`);
             // Said BEFORE "Wrote .awm/sensors.json": the manifest about to be
             // reported as written is not the one the detection implied.
-            if (result.unavailablePack) {
-                prompts_1.log.warn(`No '${result.unavailablePack}' sensor-pack in the registry — wrote the `
-                    + `'${result.manifest.pack}' pack instead (${Object.keys(result.manifest.sensors).length} sensors). `
-                    + 'Run `awm update`, or add a registry that ships it, then re-run `awm sensors init`.');
-            }
-            prompts_1.log.success('Wrote .awm/sensors.json');
-            result.configured.forEach((f) => prompts_1.log.info(`  Installed ${f}`));
+            prompts_1.log.success(`${result} .awm/sensors.json`);
         }
         catch (e) {
             prompts_1.log.error(e instanceof Error ? e.message : String(e));
             process.exit(1);
         }
     });
+    sensors
+        .command('bootstrap')
+        .description('explicitly create or migrate portable project sensor configuration')
+        .option('--mode <mode>', 'project-sensors, native-gate, or opt-out')
+        .option('--reason <text>', 'versioned reason required by native-gate and opt-out')
+        .option('--dry-run', 'report exact project changes without writing files')
+        .action(async (opts) => {
+        try {
+            const plan = await (0, bootstrap_1.planSensorBootstrap)(process.cwd(), { mode: opts.mode, reason: opts.reason, dryRun: opts.dryRun });
+            if (plan.kind === 'blocked') {
+                prompts_1.log.error(`${plan.reason}: ${plan.remedy}`);
+                process.exitCode = 1;
+                return;
+            }
+            if (plan.kind === 'noop') {
+                prompts_1.log.info('already-configured');
+                return;
+            }
+            const summary = plan.changes.map(change => change.path).join(', ');
+            if (plan.dryRun) {
+                const pack = plan.kind === 'create' && plan.manifest.mode === 'project-sensors'
+                    ? `; pack=${plan.manifest.pack}`
+                    : '';
+                prompts_1.log.info(`dry-run: ${plan.kind}${pack}; ${summary}`);
+                return;
+            }
+            const result = (0, bootstrap_1.applySensorBootstrap)(plan);
+            const pack = plan.kind === 'create' && plan.manifest.mode === 'project-sensors'
+                ? `; pack=${plan.manifest.pack}`
+                : '';
+            prompts_1.log.success(`${result}${pack}: ${summary}`);
+        }
+        catch (error) {
+            prompts_1.log.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+    });
     sensors
         .command('baseline')
         .description('snapshot current findings as accepted — sensors then fail only on NEW ones')

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

@@ -9,11 +9,8 @@ exports.buildManifest = buildManifest;
 exports.initSensors = initSensors;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const contract_1 = require("./compatibility/contract");
-const materialize_1 = require("./compatibility/materialize");
-const live_1 = require("./compatibility/live");
-const manifest_1 = require("./compatibility/manifest");
 const pack_source_1 = require("./compatibility/pack-source");
+const bootstrap_1 = require("./bootstrap");
 /** Read a pack only through the shared source resolver.  Init is a registry
  * boundary: a pack path that is absent is harmless, but a symlink or escaping
  * claimed source is never silently downgraded to an empty manifest. */
@@ -30,20 +27,6 @@ function readResolvedPack(pack, registryRoot) {
         throw error;
     }
 }
-function readV2Pack(pack, registryRoot) {
-    const source = readResolvedPack(pack, registryRoot);
-    if (!source)
-        return null;
-    let raw;
-    try {
-        raw = JSON.parse(source.content);
-    }
-    catch {
-        throw new Error(`cannot parse sensor pack ${source.path}`);
-    }
-    const parsed = (0, contract_1.parseSensorPack)(raw, source.path);
-    return parsed.kind === 'v2' ? { pack: parsed.pack, packRoot: path_1.default.dirname(source.path) } : null;
-}
 const STACK_DETECTORS = [
     { pack: 'js-ts', files: ['package.json'] },
     { pack: 'python', files: ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'] },
@@ -165,159 +148,23 @@ function availablePacks(registryRoot) {
         .map(e => e.name)
         .sort();
 }
-/** The last-resort pack, used when the detected one is absent from the registry. */
-const FALLBACK_PACK = 'generic';
-/**
- * Resolve the detected pack against what the registry actually ships.
- *
- * `--pack <name>` has always thrown here (`assertPackExists`), but auto-detection had
- * no such check: it wrote `{"pack":"python","sensors":{}}` and said nothing, so the
- * operator learned the gate was empty from an unrelated command days later. The two
- * paths now reach the same conclusion; only the remedy differs, because an explicit
- * `--pack` is a typo to correct while a detection is a fact about the tree that the
- * registry simply cannot serve yet.
- *
- * Falling back to `generic` keeps the gate measuring *something* real rather than
- * nothing. When the registry has no `generic` either, the detected pack is kept: the
- * manifest is then honestly empty, and preflight's `manifest`/`tools` checks both fail
- * on `total === 0` with a remedy pointing at the registry.
- */
-function resolvePack(detected, registryRoot) {
-    if (!registryRoot)
-        return { pack: detected }; // nothing to validate against
-    const available = availablePacks(registryRoot);
-    if (available.length === 0 || available.includes(detected))
-        return { pack: detected };
-    return {
-        pack: available.includes(FALLBACK_PACK) ? FALLBACK_PACK : detected,
-        unavailablePack: detected,
-    };
-}
-/**
- * Validate that `pack` exists as a directory under `<registryRoot>/sensor-packs/`.
- * Throws (not a swallow-and-return) so `awm sensors init --pack bogus` actually stops
- * instead of silently writing a manifest for a pack that doesn't exist. Lists every
- * pack directory actually present, sorted, so the user immediately sees valid options.
- */
-function assertPackExists(pack, registryRoot) {
-    const packsDir = path_1.default.join(registryRoot, 'sensor-packs');
-    if (!fs_1.default.existsSync(packsDir) || !fs_1.default.statSync(packsDir).isDirectory()) {
-        throw new Error('registry has no sensor-packs directory');
-    }
-    const available = availablePacks(registryRoot);
-    if (!available.includes(pack)) {
-        throw new Error(`pack '${pack}' not found in registry (available: ${available.join(', ')})`);
-    }
-}
 async function initSensors(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    const configure = opts.configure ?? true; // configure (copy pack config files) by default
-    const manifestPath = path_1.default.join(cwd, '.awm', 'sensors.json');
-    // Monorepo support: detection and evidence both need to see the real project,
-    // not the (possibly unrelated) directory the manifest lives in. The manifest
-    // write itself stays pinned to cwd regardless — see manifestPath above.
     const detectionCwd = opts.packageRoot ? path_1.default.resolve(cwd, opts.packageRoot) : cwd;
-    // --pack skips the heuristic entirely. Only validate against the registry when a
-    // registryRoot was actually given — same tolerance pattern as readPackDefaults /
-    // buildManifest elsewhere in this file for a missing registry: nothing to validate
-    // against, so nothing is validated.
-    let detection;
-    if (opts.pack) {
-        if (opts.registryRoot)
-            assertPackExists(opts.pack, opts.registryRoot);
-        detection = { pack: opts.pack, indicators: ['--pack override'] };
-    }
-    else {
-        detection = detectStack(detectionCwd);
-    }
-    let existing;
-    let existingV2;
-    if (fs_1.default.existsSync(manifestPath)) {
-        let raw;
-        try {
-            raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
-        }
-        catch {
-            throw new Error(`cannot parse existing sensor manifest ${manifestPath}`);
-        }
-        // Never overwrite a corrupt or future-version manifest during init. Legacy
-        // manifests remain a supported migration input; v2 is validated before a new
-        // materialized selection becomes the commit point.
-        const parsed = (0, manifest_1.parseSensorManifest)(raw, manifestPath);
-        if (parsed.kind === 'legacy')
-            existing = parsed.pack;
-        else if (parsed.kind === 'v2')
-            existingV2 = parsed.pack;
-        else
-            throw new Error('schemaVersion 3 sensor manifests require the project resolver');
-    }
-    // `detection` keeps saying what the tree IS; `pack` is what the registry can serve
-    // for it. They diverge only when the registry lacks the detected pack.
-    const { pack: resolvedPack, unavailablePack } = resolvePack(detection.pack, opts.registryRoot);
-    // v2 packs own the executable contract. Legacy packs deliberately retain the
-    // old string-command path below until a registry author publishes a v2 contract.
-    if (opts.registryRoot) {
-        const resolvedV2 = readV2Pack(resolvedPack, opts.registryRoot);
-        if (resolvedV2) {
-            const packSelection = opts.pack ? 'explicit' : undefined;
-            const live = await (0, live_1.resolveParsedPackCompatibility)(detectionCwd, resolvedV2.pack, { packSelection });
-            const compatibility = live.sensors;
-            const sensors = {};
-            for (const [name, sensor] of Object.entries(live.pack.sensors)) {
-                const resolved = compatibility[name];
-                const variant = resolved.variantId === null ? null : sensor.variants.find(candidate => candidate.id === resolved.variantId) ?? null;
-                // Unresolved states do not receive an arbitrary command. They remain
-                // represented in the manifest so status/coverage can explain them,
-                // but run cannot accidentally dispatch a mismatched executable.
-                if (variant) {
-                    const prior = existing?.sensors[name] ?? existingV2?.sensors[name];
-                    // Legacy string commands cannot be translated into a shell-free
-                    // structured command without guessing. Preserve the operator's
-                    // enabled/fast intent but make that migration non-certified.
-                    const migratedOverride = existing?.sensors[name]?.cmd !== undefined;
-                    sensors[name] = {
-                        enabled: prior?.enabled ?? true,
-                        fast: prior?.fast ?? sensor.fast ?? false,
-                        ...(prior?.timeout !== undefined ? { timeout: prior.timeout } : {}),
-                        variantId: variant.id,
-                        command: variant.command,
-                        assets: variant.assets,
-                        ...(variant.policyRef ? { policyRef: variant.policyRef } : {}),
-                        initializedCompatibility: migratedOverride
-                            ? { ...resolved, state: 'compatible-unverified', reason: 'legacy custom command requires explicit v2 migration' }
-                            : resolved,
-                    };
-                }
-            }
-            const materialized = (0, materialize_1.materializeResolvedSensors)({
-                projectRoot: cwd, packRoot: resolvedV2.packRoot,
-                pack: resolvedPack, ...(packSelection ? { packSelection } : {}), registryRoot: opts.registryRoot,
-                ...(opts.packageRoot ? { packageRoot: opts.packageRoot } : {}), sensors, configure,
-            });
-            return { detection, ...materialized,
-                compatibility, ...(unavailablePack ? { unavailablePack } : {}) };
-        }
-    }
-    const manifest = buildManifest(resolvedPack, existing, opts.registryRoot, cwd);
-    fs_1.default.mkdirSync(path_1.default.join(cwd, '.awm'), { recursive: true });
-    const tmpPath = manifestPath + '.tmp';
-    fs_1.default.writeFileSync(tmpPath, JSON.stringify(manifest, null, 2), 'utf-8');
-    fs_1.default.renameSync(tmpPath, manifestPath);
-    const configured = [];
-    if (configure && opts.registryRoot) {
-        // The pack whose defaults the manifest was actually built from — copying the
-        // detected pack's config files here would drop files for sensors that are not
-        // in the manifest, and miss the ones that are.
-        const packDir = path_1.default.join(opts.registryRoot, 'sensor-packs', resolvedPack);
-        if (fs_1.default.existsSync(packDir)) {
-            for (const file of fs_1.default.readdirSync(packDir).filter(f => f !== 'pack.json')) {
-                const dst = path_1.default.join(cwd, file);
-                if (!fs_1.default.existsSync(dst)) {
-                    fs_1.default.copyFileSync(path_1.default.join(packDir, file), dst);
-                    configured.push(file);
-                }
-            }
-        }
-    }
-    return { manifest, detection, configured, ...(unavailablePack ? { unavailablePack } : {}) };
+    const plan = await (0, bootstrap_1.planSensorBootstrap)(cwd, {
+        mode: 'project-sensors', registryRoot: opts.registryRoot, configure: opts.configure,
+        pack: opts.pack, packageRoot: opts.packageRoot,
+    });
+    if (plan.kind === 'blocked')
+        throw new Error(`${plan.reason}: ${plan.remedy}`);
+    if (plan.kind === 'migrate')
+        throw new Error('initSensors does not migrate existing v2 manifests; run awm sensors bootstrap');
+    if (plan.kind === 'noop')
+        return {
+            // No manifest is written or synthesized here. The compatibility API only
+            // retains its historical result shape for callers that inspect detection.
+            manifest: {}, detection: detectStack(detectionCwd), configured: [], status: 'already-configured',
+        };
+    (0, bootstrap_1.applySensorBootstrap)(plan);
+    return { manifest: plan.manifest, detection: detectStack(detectionCwd), configured: [], status: 'created' };
 }