agentic-workflow-manager 3.8.0 → 3.9.1

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

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflight = preflight;
+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 MANIFEST = path_1.default.join('.awm', 'sensors.json');
+/**
+ * The agent needs project context delivered every session. A repo with neither file
+ * hands every agent — and every teammate's agent — a blank slate.
+ */
+function checkContext(cwd) {
+    const present = ['AGENTS.md', 'CLAUDE.md', 'CONSTITUTION.md']
+        .filter(f => fs_1.default.existsSync(path_1.default.join(cwd, f)));
+    if (present.length === 0) {
+        return {
+            id: 'context',
+            ok: false,
+            detail: 'no AGENTS.md, CLAUDE.md or CONSTITUTION.md',
+            remedy: 'run the project-context-init skill (AGENTS.md) or project-constitution (CONSTITUTION.md)',
+        };
+    }
+    return { id: 'context', ok: true, detail: present.join(', ') };
+}
+function readManifest(cwd) {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(path_1.default.join(cwd, MANIFEST), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A repo may legitimately have no sensors — but it has to SAY so, in a committed file.
+ *
+ * That is why opting out requires a manifest with its sensors disabled rather than
+ * simply having no manifest. "We decided not to gate this repo" and "nobody ever ran
+ * `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))) {
+        return {
+            id: 'manifest',
+            ok: false,
+            detail: 'no .awm/sensors.json',
+            remedy: 'run `awm sensors init` (to opt out deliberately, init and set every sensor '
+                + '`"enabled": false` — an unconfigured repo and a deliberate opt-out must not look alike)',
+        };
+    }
+    if (!manifest) {
+        return {
+            id: 'manifest',
+            ok: false,
+            detail: '.awm/sensors.json is not valid JSON',
+            remedy: 'fix or regenerate it with `awm sensors init`',
+        };
+    }
+    const total = Object.keys(manifest.sensors ?? {}).length;
+    const enabled = Object.values(manifest.sensors ?? {}).filter(s => s.enabled !== false).length;
+    return {
+        id: 'manifest',
+        ok: true,
+        detail: enabled === 0 ? `pack ${manifest.pack}, all ${total} sensors disabled (deliberate opt-out)`
+            : `pack ${manifest.pack}, ${enabled}/${total} sensors enabled`,
+    };
+}
+/** Every enabled sensor's command must resolve. This is the check nothing was calling. */
+function checkTools(cwd) {
+    const status = (0, status_1.computeSensorStatus)(cwd);
+    if (status.overall === 'NOT_CONFIGURED') {
+        return { id: 'tools', ok: false, detail: 'no manifest to check', remedy: 'run `awm sensors init`' };
+    }
+    const broken = Object.entries(status.checks).filter(([, c]) => !c.ok);
+    if (broken.length > 0) {
+        return {
+            id: 'tools',
+            ok: false,
+            detail: broken.map(([name, c]) => `${name}: ${c.detail}`).join('; '),
+            remedy: 'install the missing tools/configs, or disable those sensors deliberately',
+        };
+    }
+    return { id: 'tools', ok: true, detail: `${Object.keys(status.checks).length} sensor(s) runnable` };
+}
+/**
+ * A manifest pinned to `generic` on a tree that clearly has a stack means the real
+ * sensors for that stack are simply absent — the gate runs, reports green, and has
+ * checked almost nothing. `runSensors` self-heals this at run time via `reconcilePack`,
+ * but only when a registry is reachable; saying it out loud here costs nothing.
+ */
+function checkPack(cwd, manifest) {
+    if (!manifest)
+        return { id: 'pack', ok: true, detail: 'skipped (no manifest)' };
+    const detection = (0, init_1.detectStack)(cwd);
+    if (manifest.pack === 'generic' && detection.pack !== 'generic') {
+        return {
+            id: 'pack',
+            ok: false,
+            detail: `manifest on 'generic' but the tree looks like '${detection.pack}' (${detection.indicators.join(', ')})`,
+            remedy: 'run `awm sensors init` to pick up the real pack for this stack',
+        };
+    }
+    return { id: 'pack', ok: true, detail: `${manifest.pack} matches the detected stack` };
+}
+function preflight(cwd = process.cwd()) {
+    const manifest = readManifest(cwd);
+    const manifestExists = fs_1.default.existsSync(path_1.default.join(cwd, MANIFEST));
+    const checks = [
+        checkContext(cwd),
+        checkManifest(cwd, manifest),
+        // Skipped when there is no manifest: reporting "tools broken" on a repo that was
+        // never set up buries the one thing the operator needs to read.
+        ...(manifestExists ? [checkTools(cwd), checkPack(cwd, manifest)] : []),
+    ];
+    const status = !manifestExists ? 'not_configured'
+        : checks.every(c => c.ok) ? 'ready'
+            : 'degraded';
+    return { status, checks };
+}

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

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitCodeFor = exitCodeFor;
+exports.formatReport = formatReport;
+exports.registerPreflightCommand = registerPreflightCommand;
+const picocolors_1 = __importDefault(require("picocolors"));
+const checks_1 = require("./checks");
+/**
+ * Exit code. Anything but `ready` exits 1.
+ *
+ * Unlike `awm sensors run` — which exits 0 on `not_certified` because exit 2 is a
+ * blocking error in Claude Code hooks — preflight is never a hook. It is invoked
+ * explicitly by a phase gate, so the exit code can carry the verdict and the caller
+ * does not have to remember to read a field out of JSON.
+ */
+function exitCodeFor(report) {
+    return report.status === 'ready' ? 0 : 1;
+}
+function formatReport(report) {
+    const lines = report.checks.map(c => `  ${c.ok ? picocolors_1.default.green('✔') : picocolors_1.default.red('✘')}  ${c.id.padEnd(9)} ${c.detail}`
+        + (c.remedy ? `\n       ${picocolors_1.default.dim('→ ' + c.remedy)}` : ''));
+    if (report.status === 'ready') {
+        return `${picocolors_1.default.green('✔')}  Harness ready — this project can be gated.\n${lines.join('\n')}\n`;
+    }
+    const headline = report.status === 'not_configured'
+        ? `${picocolors_1.default.red('✘')}  AWM is not configured in this project.`
+        : `${picocolors_1.default.red('✘')}  Harness degraded — it declares sensors it cannot run.`;
+    return `${headline}\n${lines.join('\n')}\n\n`
+        + `   ${picocolors_1.default.bold('Do not hand this off to an unattended run.')} Every quality phase downstream\n`
+        + `   (implementer, reviewers, post-qa) consumes \`awm sensors run\`. With the harness in\n`
+        + `   this state the gate reports on checks that never ran, and nobody finds out until a\n`
+        + `   bad change is already merged.\n`;
+}
+function registerPreflightCommand(program) {
+    program
+        .command('preflight')
+        .description('verify the project harness can actually gate before development starts')
+        .option('--json', 'emit the report as JSON')
+        .option('--cwd <path>', 'project directory to check (default: current)')
+        .action((opts) => {
+        const report = (0, checks_1.preflight)(opts.cwd ?? process.cwd());
+        process.stdout.write(opts.json ? JSON.stringify(report, null, 2) + '\n' : formatReport(report));
+        const code = exitCodeFor(report);
+        if (code !== 0)
+            process.exit(code);
+    });
+}

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

@@ -4,10 +4,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.changedFiles = changedFiles;
+exports.hasUnsafeWin32Chars = hasUnsafeWin32Chars;
 exports.applyChangedCmd = applyChangedCmd;
 exports.filterByExtension = filterByExtension;
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
+const paths_1 = require("../../core/paths");
 function git(args, cwd) {
     return (0, child_process_1.execFileSync)('git', args, {
         cwd,
@@ -56,14 +58,82 @@ function changedFiles(cwd, base = 'HEAD') {
     const files = Array.from(new Set(out.map(s => s.trim()).filter(Boolean))).sort();
     return { files };
 }
+/**
+ * cmd.exe metacharacters that quoting does NOT reliably neutralize.
+ *
+ * Per the BatBadBut / CVE-2024-27980 research (flatt.tech/research/posts/batbadbut-
+ * you-cant-securely-execute-commands-on-windows/ — the paper Node's own CVE fix was
+ * based on), `%` still triggers environment-variable expansion *inside* a
+ * double-quoted string, and `&` can break a command out of quoting under certain
+ * conditions. cmd.exe parses these BEFORE the target program ever sees argv, so no
+ * amount of `"..."`/`\"` escaping at the argv layer (which is all `shellQuote` can
+ * touch) is a complete guarantee against them. Newline/CR are included because the
+ * same research flags them, and they are nonsensical in a real path regardless.
+ *
+ * This is a denylist, not an escaping table, on purpose: the responsible fix for
+ * this vulnerability class is to REFUSE (fall back to the full, unscoped command —
+ * see `run.ts`), not to hand-roll a smarter cmd.exe escaper. Node's own security
+ * team reached the same conclusion for the identical problem.
+ */
+const WIN32_UNSAFE_CHARS = /[&|<>^%\r\n]/;
+/** True when `file` contains a character cmd.exe would parse as its own syntax. */
+function hasUnsafeWin32Chars(file) {
+    return WIN32_UNSAFE_CHARS.test(file);
+}
+/**
+ * CommandLineToArgvW-safe quoting (the algorithm behind Python's
+ * `subprocess.list2cmdline`, Rust's `std::process::Command` on Windows, and .NET's
+ * argument escaper). Per the documented rule
+ * (learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments):
+ * an EVEN run of backslashes before a `"` collapses to half as many literal
+ * backslashes and the `"` is a real delimiter; an ODD run collapses the same way
+ * but the leftover backslash escapes the `"` into a literal character instead of a
+ * delimiter. Backslashes not followed by a `"` are always literal and untouched.
+ *
+ * This alone does not make interpolation safe on win32 — see `hasUnsafeWin32Chars`
+ * and its callers in `run.ts` for the metacharacter layer this cannot address.
+ */
+function win32ArgvQuote(arg) {
+    let result = '"';
+    let backslashes = 0;
+    for (const ch of arg) {
+        if (ch === '\\') {
+            backslashes++;
+        }
+        else if (ch === '"') {
+            result += '\\'.repeat(backslashes * 2 + 1) + '"';
+            backslashes = 0;
+        }
+        else {
+            result += '\\'.repeat(backslashes) + ch;
+            backslashes = 0;
+        }
+    }
+    result += '\\'.repeat(backslashes * 2); // double any trailing run before the closing quote
+    result += '"';
+    return result;
+}
 /**
  * Quote a path for a shell command line. Sensor commands are strings run through a
  * shell, so a path with a space or a quote in it would otherwise split into two
  * arguments — or, worse, end the quoting and let the rest of the name be read as
- * shell syntax. Single quotes with the `'\''` escape are the only form POSIX shells
- * treat as fully literal.
+ * shell syntax.
+ *
+ * `runCommand` (see `exec.ts`) spawns this string with `shell: true`, which on
+ * win32 is `cmd.exe`, not a POSIX shell. Single quotes are not quoting syntax to
+ * cmd.exe — it just splits on the space inside them — so a POSIX-only quote here
+ * would silently hand eslint/semgrep two garbage arguments instead of one real
+ * path. `'\''` (single quotes with the escape) is what POSIX shells treat as fully
+ * literal — no exceptions, per POSIX shell grammar, so no metacharacter denylist is
+ * needed on that branch. On win32, `win32ArgvQuote` is the argv-layer half of
+ * safety; the metacharacter denylist above (enforced by the caller in `run.ts`,
+ * before this function is ever reached) is the other half this function cannot
+ * provide on its own.
  */
 function shellQuote(file) {
+    if ((0, paths_1.isWindowsNative)()) {
+        return win32ArgvQuote(file);
+    }
     return `'${file.replace(/'/g, `'\\''`)}'`;
 }
 /**

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCommand = runCommand;
 const child_process_1 = require("child_process");
+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. */
@@ -22,7 +23,7 @@ const POST_KILL_GRACE_MS = 1_000;
  * negative-pid kill reaches every descendant at once.
  */
 function killTree(pid, signal) {
-    if (process.platform === 'win32') {
+    if ((0, paths_1.isWindowsNative)()) {
         // Windows has no process groups in the POSIX sense; taskkill /T walks the tree.
         try {
             (0, child_process_1.execFile)('taskkill', ['/pid', String(pid), '/T', '/F'], () => { });
@@ -65,7 +66,7 @@ function runCommand(cmd, opts) {
         const child = (0, child_process_1.spawn)(cmd, {
             shell: true,
             cwd: opts.cwd,
-            detached: process.platform !== 'win32',
+            detached: !(0, paths_1.isWindowsNative)(),
             // 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'],

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

@@ -21,6 +21,7 @@ const baseline_1 = require("./baseline");
 const changed_1 = require("./changed");
 const init_1 = require("./init");
 const registries_1 = require("../../core/registries");
+const paths_1 = require("../../core/paths");
 const MANIFEST_FILE = '.awm/sensors.json';
 const DEFAULT_FAST_TIMEOUT = 10_000;
 const DEFAULT_SLOW_TIMEOUT = 120_000;
@@ -268,6 +269,21 @@ async function runSensors(opts = {}) {
     // Resolved once for the whole run, not per sensor: `git` is cheap but the answer
     // must be identical across sensors, or two of them scope to different file sets.
     const changed = opts.changed ? (0, changed_1.changedFiles)(cwd, opts.base ?? 'HEAD') : null;
+    // Security (BatBadBut / CVE-2024-27980): on native Windows, `runCommand` spawns
+    // the sensor command through cmd.exe (`shell: true`), which parses `& | < > ^ %`
+    // as ITS OWN syntax before the target program ever sees argv — quoting does not
+    // reliably neutralize this layer (the primary research this fix is based on
+    // concludes escaping it is not safely possible). A changed filename carrying one
+    // of these is refused, not escaped: routed through the exact same fallback the
+    // module already has for "scope could not be resolved" (`changed.error`), so
+    // every sensor degrades to its full unscoped command rather than interpolating
+    // an unsafe path. POSIX is unaffected — single-quote quoting there is fully
+    // literal per POSIX shell grammar, no metacharacter exception exists.
+    if (changed && !changed.error && (0, paths_1.isWindowsNative)() && changed.files.some(changed_1.hasUnsafeWin32Chars)) {
+        changed.error = 'a changed filename contains a cmd.exe metacharacter (& | < > ^ % or newline/CR) '
+            + 'that quoting cannot reliably neutralize on native Windows — refusing to interpolate it, '
+            + 'falling back to the full unscoped command';
+    }
     // Sensors are independent processes over the same tree, so they run
     // concurrently rather than one-after-another: wall clock becomes the slowest
     // sensor instead of the sum of all of them. Tasks are built — and dispatched —

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

@@ -7,6 +7,7 @@ exports.computeSensorStatus = computeSensorStatus;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const paths_1 = require("../../core/paths");
 /** First non-flag token after `npx` — the tool the command actually runs. */
 function npxTool(parts) {
     for (let i = 1; i < parts.length; i++) {
@@ -15,6 +16,17 @@ function npxTool(parts) {
     }
     return undefined;
 }
+/** Resolve a binary on PATH portably: `where` on win32, POSIX `command -v` elsewhere. */
+function resolveOnPath(bin) {
+    const cmd = (0, paths_1.isWindowsNative)() ? `where ${bin}` : `command -v ${bin}`;
+    try {
+        (0, child_process_1.execSync)(cmd, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** If the command references `--config <file>`, that file must exist in the repo. */
 function configCheck(parts, cwd) {
     const i = parts.indexOf('--config');
@@ -29,7 +41,7 @@ function configCheck(parts, cwd) {
  * - `npx <tool>`: the tool MUST be installed locally (node_modules/.bin). Otherwise
  *   `npx` would fetch a remote package at run time (dependency-confusion risk) and
  *   the sensor would fail. A green status here would be a lie.
- * - other binaries: must resolve on PATH (`which`).
+ * - other binaries: must resolve on PATH (`where` on win32, `command -v` elsewhere).
  * - any `--config <file>` referenced must exist.
  */
 function checkCmd(cmd, cwd) {
@@ -48,10 +60,7 @@ function checkCmd(cmd, cwd) {
         }
         return configCheck(parts, cwd) ?? { ok: true, detail: `${tool} (node_modules/.bin)` };
     }
-    try {
-        (0, child_process_1.execSync)(`which ${bin}`, { stdio: 'pipe' });
-    }
-    catch {
+    if (!resolveOnPath(bin)) {
         return { ok: false, detail: `${bin} not found in PATH` };
     }
     return configCheck(parts, cwd) ?? { ok: true, detail: bin };

package/dist/src/index.js

@@ -27,6 +27,7 @@ const hooks_1 = require("./commands/hooks");
 const sensors_1 = require("./commands/sensors");
 const ledger_1 = require("./commands/ledger");
 const context_budget_1 = require("./commands/context-budget");
+const preflight_1 = require("./commands/preflight");
 const doctor_1 = require("./commands/doctor");
 const backup_1 = require("./commands/backup");
 const init_1 = require("./commands/init");
@@ -608,6 +609,7 @@ miroCmd.command('sync <storyMapPath>')
 (0, sensors_1.registerSensorsCommand)(program);
 (0, ledger_1.registerLedgerCommand)(program);
 (0, context_budget_1.registerContextBudgetCommand)(program);
+(0, preflight_1.registerPreflightCommand)(program);
 (0, doctor_1.registerDoctorCommand)(program);
 (0, backup_1.registerBackupCommand)(program);
 (0, init_1.registerInitCommand)(program);

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

@@ -0,0 +1,123 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const checks_1 = require("../../../src/commands/preflight/checks");
+const preflight_1 = require("../../../src/commands/preflight");
+/** CLAUDE.md: no test may reach the real ~/.awm. Everything here is a tmpdir. */
+function project(opts = {}) {
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-preflight-'));
+    for (const f of opts.context ?? ['AGENTS.md'])
+        fs_1.default.writeFileSync(path_1.default.join(dir, f), '# ctx\n');
+    for (const f of opts.files ?? []) {
+        fs_1.default.mkdirSync(path_1.default.dirname(path_1.default.join(dir, f)), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, f), '');
+    }
+    for (const b of opts.bins ?? []) {
+        fs_1.default.mkdirSync(path_1.default.join(dir, 'node_modules', '.bin'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, 'node_modules', '.bin', b), '');
+    }
+    if (opts.manifest !== undefined) {
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, '.awm', 'sensors.json'), typeof opts.manifest === 'string' ? opts.manifest : JSON.stringify(opts.manifest));
+    }
+    return dir;
+}
+const dirs = [];
+const make = (o) => { const d = project(o); dirs.push(d); return d; };
+afterAll(() => dirs.forEach(d => fs_1.default.rmSync(d, { recursive: true, force: true })));
+const check = (r, id) => r.checks.find(c => c.id === id);
+describe('preflight', () => {
+    it('reports not_configured when no sensor manifest exists', () => {
+        // The team-rollout case: a developer clones the repo and never runs
+        // `awm sensors init`. Today nothing notices until an unattended run is already
+        // in flight and every quality phase is consuming a gate that certifies nothing.
+        const dir = make();
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('not_configured');
+        expect(check(report, 'manifest').ok).toBe(false);
+    });
+    it('keeps not_configured and degraded apart', () => {
+        // "You never set this up" and "you set it up and it broke" need different
+        // remedies. Collapsing them is how an absent check reads as a passing one.
+        const never = make();
+        const broken = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } }, // no local eslint
+        });
+        expect((0, checks_1.preflight)(never).status).toBe('not_configured');
+        expect((0, checks_1.preflight)(broken).status).toBe('degraded');
+    });
+    it('is ready when the declared sensors can actually run', () => {
+        const dir = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } },
+            bins: ['eslint'],
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('ready');
+        expect((0, preflight_1.exitCodeFor)(report)).toBe(0);
+    });
+    it('catches a sensor whose tool is not installed locally', () => {
+        // This is the check that existed and nothing in the flow was calling.
+        const dir = make({
+            manifest: { pack: 'js-ts', sensors: { lint: { cmd: 'npx eslint .' } } },
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'tools').detail).toContain('eslint');
+    });
+    it('accepts a deliberate opt-out, but only when it is written down', () => {
+        // A repo may legitimately have no sensors — it just has to SAY so in a committed
+        // file, so "we decided not to gate this" cannot be mistaken for "nobody set it up".
+        const optedOut = make({
+            manifest: { pack: 'generic', sensors: { security: { cmd: 'semgrep .', enabled: false } } },
+        });
+        const report = (0, checks_1.preflight)(optedOut);
+        expect(report.status).toBe('ready');
+        expect(check(report, 'manifest').detail).toContain('opt-out');
+    });
+    it('flags a manifest stuck on generic while the tree has a real stack', () => {
+        // The gate would run, report green, and have checked almost nothing.
+        const dir = make({
+            manifest: { pack: 'generic', sensors: {} },
+            files: ['package.json'],
+        });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'pack').ok).toBe(false);
+    });
+    it('flags a repo with no context contract at all', () => {
+        const dir = make({
+            context: [],
+            manifest: { pack: 'generic', sensors: {} },
+        });
+        expect(check((0, checks_1.preflight)(dir), 'context').ok).toBe(false);
+    });
+    it('treats an unparseable manifest as a failure, not as absent', () => {
+        const dir = make({ manifest: '{ not json' });
+        const report = (0, checks_1.preflight)(dir);
+        expect(report.status).toBe('degraded');
+        expect(check(report, 'manifest').detail).toContain('not valid JSON');
+    });
+    it('exits non-zero for anything but ready, so the caller need not parse JSON', () => {
+        // Unlike `awm sensors run` — which exits 0 on not_certified because exit 2 blocks
+        // Claude Code hooks — preflight is never a hook, so the verdict rides the exit code
+        // instead of depending on every agent remembering to read a field.
+        expect((0, preflight_1.exitCodeFor)({ status: 'not_configured', checks: [] })).toBe(1);
+        expect((0, preflight_1.exitCodeFor)({ status: 'degraded', checks: [] })).toBe(1);
+        expect((0, preflight_1.exitCodeFor)({ status: 'ready', checks: [] })).toBe(0);
+    });
+    it('tells the operator not to hand a broken harness to an unattended run', () => {
+        const out = (0, preflight_1.formatReport)({
+            status: 'not_configured',
+            checks: [{ id: 'manifest', ok: false, detail: 'no .awm/sensors.json', remedy: 'run `awm sensors init`' }],
+        });
+        expect(out).toContain('unattended');
+        expect(out).toContain('awm sensors init');
+    });
+});

package/dist/tests/commands/sensors/changed-windows.test.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const changed_1 = require("../../../src/commands/sensors/changed");
+describe('applyChangedCmd — Windows quoting', () => {
+    const originalPlatform = process.platform;
+    beforeEach(() => {
+        Object.defineProperty(process, 'platform', { value: 'win32' });
+    });
+    afterEach(() => {
+        Object.defineProperty(process, 'platform', { value: originalPlatform });
+    });
+    it('double-quotes paths on win32 instead of POSIX single-quoting', () => {
+        // `runCommand` spawns this string with `shell: true`, which is cmd.exe on
+        // win32. cmd.exe does not treat single quotes as quoting syntax — it would
+        // split `'my dir/a.ts'` into two garbage arguments on the space. Double
+        // quotes are the form cmd.exe actually honors.
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ['my dir/a.ts']))
+            .toBe(`eslint "my dir/a.ts"`);
+    });
+    it('escapes an embedded double quote with a preceding backslash', () => {
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ['weird"name.ts']))
+            .toBe(`eslint "weird\\"name.ts"`);
+    });
+    it('handles a filename with both a space and an embedded quote together', () => {
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ['my dir/it"s.ts']))
+            .toBe(`eslint "my dir/it\\"s.ts"`);
+    });
+    it('doubles a lone trailing backslash so the closing quote is not escaped away', () => {
+        // Bug 1 (correctness): a filename ending in a single `\` (e.g. a scoped path
+        // like `report\`), naively closed with `..."report\""`, puts an ODD number of
+        // backslashes (1) directly before the closing `"`. Per the documented
+        // CommandLineToArgvW rule (learn.microsoft.com/en-us/cpp/c-language/parsing-c-command-line-arguments),
+        // an odd backslash run before a `"` consumes the backslashes in pairs (0
+        // literal here) and the last one escapes the quote into a literal character —
+        // so the wrapper never closes and the argument is corrupted/unterminated.
+        //
+        // The correct output doubles the trailing run to an EVEN count (2) before the
+        // closing quote: even backslashes before a `"` collapse to half as many
+        // literal backslashes (1) and the `"` is read as a real delimiter, closing the
+        // wrapper cleanly and recovering exactly the original single trailing `\`.
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ['report\\']))
+            .toBe(`eslint "report\\\\"`);
+    });
+});

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

@@ -93,6 +93,10 @@ describe('applyChangedCmd', () => {
         expect((0, changed_1.applyChangedCmd)('eslint {files}', ["it's.ts"]))
             .toBe(`eslint 'it'\\''s.ts'`);
     });
+    it('handles a filename with both a space and an embedded quote together', () => {
+        expect((0, changed_1.applyChangedCmd)('eslint {files}', ["my dir/it's.ts"]))
+            .toBe(`eslint 'my dir/it'\\''s.ts'`);
+    });
 });
 describe('filterByExtension', () => {
     it('drops files the sensor cannot be handed', () => {

package/dist/tests/commands/sensors/exec-windows.test.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const events_1 = require("events");
+const child_process_1 = require("child_process");
+const exec_1 = require("../../../src/commands/sensors/exec");
+jest.mock('child_process', () => ({
+    spawn: jest.fn(),
+    execFile: jest.fn(),
+}));
+const mockSpawn = child_process_1.spawn;
+const mockExecFile = child_process_1.execFile;
+/** Minimal stand-in for a ChildProcess: enough surface for exec.ts to drive. */
+function fakeChild(pid = 4242) {
+    const child = new events_1.EventEmitter();
+    child.pid = pid;
+    child.stdout = new events_1.EventEmitter();
+    child.stderr = new events_1.EventEmitter();
+    child.unref = jest.fn();
+    return child;
+}
+describe('runCommand — win32', () => {
+    const originalPlatform = process.platform;
+    beforeEach(() => {
+        Object.defineProperty(process, 'platform', { value: 'win32' });
+        mockSpawn.mockReset();
+        mockExecFile.mockReset();
+    });
+    afterEach(() => {
+        Object.defineProperty(process, 'platform', { value: originalPlatform });
+        jest.useRealTimers();
+    });
+    it('spawns with detached: false — win32 has no POSIX process groups to detach into', async () => {
+        const child = fakeChild();
+        mockSpawn.mockReturnValue(child);
+        const pending = (0, exec_1.runCommand)('echo hi', { timeout: 5000, cwd: process.cwd() });
+        expect(mockSpawn).toHaveBeenCalledWith('echo hi', expect.objectContaining({ detached: false }));
+        child.emit('close', 0, null);
+        const r = await pending;
+        expect(r.code).toBe(0);
+    });
+    it('kills via `taskkill /pid <pid> /T /F` on timeout, never the POSIX process.kill(-pid) path', async () => {
+        jest.useFakeTimers();
+        const child = fakeChild(4242);
+        mockSpawn.mockReturnValue(child);
+        mockExecFile.mockImplementation(((...args) => {
+            const cb = args[args.length - 1];
+            if (typeof cb === 'function')
+                cb(null, '', '');
+            return {};
+        }));
+        const posixKillSpy = jest.spyOn(process, 'kill').mockImplementation(() => true);
+        const pending = (0, exec_1.runCommand)('slow-command', {
+            timeout: 1000,
+            cwd: process.cwd(),
+            killGraceMs: 500,
+        });
+        // Fire the deadline: cutShort() -> killTree(pid, 'SIGTERM').
+        jest.advanceTimersByTime(1000);
+        expect(mockExecFile).toHaveBeenCalledWith('taskkill', ['/pid', '4242', '/T', '/F'], expect.any(Function));
+        // The win32 branch returns before ever reaching the POSIX fallback.
+        expect(posixKillSpy).not.toHaveBeenCalled();
+        // Escalation to SIGKILL, then the post-kill grace that resolves regardless.
+        jest.advanceTimersByTime(500);
+        expect(mockExecFile).toHaveBeenCalledWith('taskkill', ['/pid', '4242', '/T', '/F'], expect.any(Function));
+        expect(mockExecFile).toHaveBeenCalledTimes(2);
+        expect(posixKillSpy).not.toHaveBeenCalled();
+        jest.advanceTimersByTime(1000);
+        const r = await pending;
+        expect(r.timedOut).toBe(true);
+        expect(r.signal).toBe('SIGKILL');
+        posixKillSpy.mockRestore();
+    });
+});

package/dist/tests/commands/sensors/run-changed.test.js

@@ -133,4 +133,39 @@ describe('runSensors --changed', () => {
         await load().runSensors({ cwd: dir, changed: true, base: 'main' });
         expect(mockChangedFiles).toHaveBeenCalledWith(dir, 'main');
     });
+    describe('on native Windows, with an unsafe changed filename', () => {
+        // Bug 2 (security): `runCommand` (exec.ts) spawns the sensor command with
+        // `shell: true`, which on win32 is cmd.exe — it parses `& | < > ^ %` as its
+        // OWN metacharacters BEFORE the target program ever sees argv, regardless of
+        // `"..."` wrapping in many cases (BatBadBut / CVE-2024-27980 research: `%`
+        // still triggers variable expansion inside double-quoted strings, and `&` can
+        // break out of a quoted string). Escaping these reliably is a known-unreliable
+        // approach, so the fix REFUSES: any changed file with one of these characters
+        // (on native Windows only) makes the whole scope unsafe to interpolate, and
+        // the run degrades to the sensor's full unscoped command instead — the exact
+        // fallback already used when `changedFiles()` cannot resolve the scope at all.
+        const originalPlatform = process.platform;
+        beforeEach(() => {
+            Object.defineProperty(process, 'platform', { value: 'win32' });
+        });
+        afterEach(() => {
+            Object.defineProperty(process, 'platform', { value: originalPlatform });
+        });
+        it('falls back to the full command instead of interpolating the unsafe filename', async () => {
+            dir = project({ lint: LINT });
+            mockChangedFiles.mockReturnValue({ files: ['src/a.ts', 'evil&name.ts'] });
+            const out = await load().runSensors({ cwd: dir, changed: true });
+            // The unsafe filename must never reach the dispatched command line, quoted
+            // or otherwise — assert on the actual command, not just "no crash".
+            expect(cmds()).toContain('eslint --format json .');
+            expect(cmds().join(' ')).not.toContain('evil&name.ts');
+            expect(out.sensors[0].scope).toBeUndefined();
+        });
+        it('reports the unsafe scope the same way an unresolved scope is reported', async () => {
+            dir = project({ lint: LINT });
+            mockChangedFiles.mockReturnValue({ files: ['evil&name.ts'] });
+            const out = await load().runSensors({ cwd: dir, changed: true });
+            expect(out.changedScope?.error).toBeDefined();
+        });
+    });
 });

package/dist/tests/commands/sensors/status-windows.test.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const child_process_1 = require("child_process");
+const status_1 = require("../../../src/commands/sensors/status");
+jest.mock('child_process', () => ({ execSync: jest.fn() }));
+const mockExecSync = child_process_1.execSync;
+describe('computeSensorStatus — Windows PATH resolution', () => {
+    let tmpDir;
+    const originalPlatform = process.platform;
+    beforeEach(() => {
+        tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-status-win-'));
+        mockExecSync.mockReset();
+        Object.defineProperty(process, 'platform', { value: 'win32' });
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmpDir, { recursive: true });
+        Object.defineProperty(process, 'platform', { value: originalPlatform });
+    });
+    it('resolves an installed binary on win32 using `where`, not `which`', () => {
+        fs_1.default.mkdirSync(path_1.default.join(tmpDir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tmpDir, '.awm', 'sensors.json'), JSON.stringify({
+            pack: 'js-ts',
+            sensors: { security: { cmd: 'semgrep --json .', fast: false } }
+        }));
+        mockExecSync.mockImplementation(((cmd) => {
+            if (cmd.startsWith('where '))
+                return Buffer.from('C:\\tools\\semgrep.exe');
+            throw new Error(`not found: ${cmd}`);
+        }));
+        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        expect(result.overall).toBe('HEALTHY');
+        expect(result.checks.security.ok).toBe(true);
+    });
+    it('reports ok:false on win32 when `where` cannot find the binary', () => {
+        fs_1.default.mkdirSync(path_1.default.join(tmpDir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(tmpDir, '.awm', 'sensors.json'), JSON.stringify({
+            pack: 'js-ts',
+            sensors: { security: { cmd: 'semgrep --json .', fast: false } }
+        }));
+        mockExecSync.mockImplementation(((cmd) => {
+            if (cmd.startsWith('where '))
+                throw new Error(`not found: ${cmd}`);
+            throw new Error(`not found: ${cmd}`);
+        }));
+        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        expect(result.overall).toBe('DEGRADED');
+        expect(result.checks.security.ok).toBe(false);
+    });
+});

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

@@ -85,6 +85,30 @@ describe('computeSensorStatus', () => {
         expect(result.overall).toBe('DEGRADED');
         expect(result.checks.security.ok).toBe(false);
     });
+    describe('on POSIX', () => {
+        const originalPlatform = process.platform;
+        beforeEach(() => {
+            Object.defineProperty(process, 'platform', { value: 'linux' });
+        });
+        afterEach(() => {
+            Object.defineProperty(process, 'platform', { value: originalPlatform });
+        });
+        it('resolves an installed binary using `command -v`, not `where`', () => {
+            fs_1.default.mkdirSync(path_1.default.join(tmpDir, '.awm'), { recursive: true });
+            fs_1.default.writeFileSync(path_1.default.join(tmpDir, '.awm', 'sensors.json'), JSON.stringify({
+                pack: 'js-ts',
+                sensors: { security: { cmd: 'semgrep --json .', fast: false } }
+            }));
+            mockExecSync.mockImplementation(((cmd) => {
+                if (cmd === 'command -v semgrep')
+                    return Buffer.from('/usr/bin/semgrep');
+                throw new Error(`not found: ${cmd}`);
+            }));
+            const result = (0, status_1.computeSensorStatus)(tmpDir);
+            expect(result.overall).toBe('HEALTHY');
+            expect(result.checks.security.ok).toBe(true);
+        });
+    });
     it('marks disabled sensors as ok', () => {
         fs_1.default.mkdirSync(path_1.default.join(tmpDir, '.awm'), { recursive: true });
         fs_1.default.writeFileSync(path_1.default.join(tmpDir, '.awm', 'sensors.json'), JSON.stringify({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.8.0",
+  "version": "3.9.1",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"