agentic-workflow-manager 9.18.0 → 9.20.0

package/dist/tests/core/changes/receipt.test.js

@@ -0,0 +1,947 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Only the sensor execution is faked; shouldRun stays real so the selection-parity test checks the production rule.
+jest.mock('../../../src/commands/sensors/run', () => ({
+    runSensors: jest.fn(), findManifestDir: jest.fn(),
+    shouldRun: jest.requireActual('../../../src/commands/sensors/run').shouldRun,
+}));
+const fs_1 = __importDefault(require("fs"));
+const crypto_1 = __importDefault(require("crypto"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = __importStar(require("child_process"));
+const commander_1 = require("commander");
+const helpers_1 = require("./helpers");
+const receipt_1 = require("../../../src/core/changes/receipt");
+const index_1 = require("../../../src/commands/sensors/index");
+const run_1 = require("../../../src/commands/sensors/run");
+const project_1 = require("../../../src/commands/sensors/project");
+const verdict_1 = require("../../../src/commands/sensors/verdict");
+const ENV_KEYS = ['HOME', 'AWM_HOME', 'GIT_AUTHOR_NAME', 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_NAME', 'GIT_COMMITTER_EMAIL', 'GIT_CONFIG_NOSYSTEM', 'GIT_CONFIG_GLOBAL'];
+const ORIGINAL = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+// The real checkout must stay untouched. Receipts are written under the git TOPLEVEL of the cwd (not the cwd itself),
+// so both that runs directory and the cwd-relative one are watched. Outside a git repository only the latter exists.
+const checkoutToplevel = () => {
+    try {
+        return path_1.default.resolve((0, child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1' } }).trim());
+    }
+    catch {
+        return null;
+    }
+};
+const TOPLEVEL = checkoutToplevel();
+const WATCHED_RUNS = [...new Set([path_1.default.resolve('.awm', 'sensors', 'runs'), ...(TOPLEVEL === null ? [] : [path_1.default.join(TOPLEVEL, '.awm', 'sensors', 'runs')])])];
+const listRuns = () => Object.fromEntries(WATCHED_RUNS.map((d) => [d, fs_1.default.existsSync(d) ? fs_1.default.readdirSync(d).sort() : null]));
+const RUNS_BEFORE = listRuns();
+let repo;
+let root;
+let home;
+// Child git processes get an explicit identity and config isolation; the shared makeRepo already points HOME and AWM_HOME at a throwaway home.
+const gitEnv = () => ({ ...process.env, HOME: home, GIT_CONFIG_GLOBAL: path_1.default.join(home, 'gitconfig'), GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@t', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@t', GIT_CONFIG_NOSYSTEM: '1' });
+const g = (...args) => repo.git(...args);
+beforeEach(() => {
+    repo = (0, helpers_1.makeRepo)();
+    root = repo.root;
+    home = repo.home;
+    // makeRepo's own .gitignore ignores `.awm/`; these tests need a repository that does NOT (R2.2b), so the first commit is replaced.
+    repo.commit({ '.gitignore': 'node_modules\n', 'a.txt': 'a' }, 'feat: a');
+});
+afterEach(() => repo.cleanup());
+afterAll(() => {
+    for (const k of ENV_KEYS)
+        expect(process.env[k]).toBe(ORIGINAL[k]);
+    expect(listRuns()).toEqual(RUNS_BEFORE);
+});
+// `manifestPath` is the manifest the run reports (SensorAuthority): the repository root's, by default.
+const output = {
+    overall: 'pass',
+    sensors: [{ name: 'lint', status: 'pass', errors: [] }, { name: 'a-typecheck', status: 'pass', errors: [] }],
+    get manifestPath() { return path_1.default.join(root, '.awm', 'sensors.json'); },
+};
+const runsFile = (head) => path_1.default.join(root, '.awm', 'sensors', 'runs', `${head}.json`);
+const listTree = (dir) => fs_1.default.readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.name === '.git' ? [] : e.isDirectory() ? [e.name + '/', ...listTree(path_1.default.join(dir, e.name)).map((c) => `${e.name}/${c}`)] : [e.name]));
+const writeValid = () => {
+    const head = g('rev-parse', 'HEAD');
+    (0, receipt_1.writeReceipt)(root, (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '9.20.0', output: output }));
+    return head;
+};
+/** Rewrites the on-disk receipt with `mutate` applied, keeping (or not) the old digest. */
+const mutateFile = (head, mutate, redigest = false) => {
+    const parsed = JSON.parse(fs_1.default.readFileSync(runsFile(head), 'utf8'));
+    mutate(parsed);
+    if (redigest) {
+        const { digest: _d, ...body } = parsed;
+        // computeReceiptDigest refuses a body with non-object sensors; such a fixture keeps its old digest (the shape check rejects it first).
+        try {
+            parsed.digest = (0, receipt_1.computeReceiptDigest)(body);
+        }
+        catch { /* keep the old digest */ }
+    }
+    fs_1.default.writeFileSync(runsFile(head), JSON.stringify(parsed));
+};
+describe('receipt', () => {
+    test('isolation: HOME and AWM_HOME point at a throwaway directory, never the real ones', () => {
+        expect(process.env.HOME).toBe(home);
+        expect(process.env.HOME).not.toBe(ORIGINAL.HOME);
+        expect(process.env.AWM_HOME).toBe(path_1.default.join(home, '.awm'));
+        expect(process.env.AWM_HOME).not.toBe(ORIGINAL.AWM_HOME);
+        expect(process.env.GIT_CONFIG_GLOBAL).toBe(path_1.default.join(home, 'gitconfig'));
+        expect(fs_1.default.readFileSync(path_1.default.join(home, 'gitconfig'), 'utf8')).toBe('');
+    });
+    test('R2.1 full selection on a clean tree writes a 0600 receipt keyed by HEAD', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect(pre.eligible).toBe(true);
+        const note = (0, receipt_1.finalizeReceipt)(pre, output, { now: () => new Date('2026-10-17T10:00:00.000Z'), version: () => '9.20.0' });
+        expect(note).toBe('');
+        const head = g('rev-parse', 'HEAD');
+        const file = path_1.default.join(root, '.awm', 'sensors', 'runs', `${head}.json`);
+        expect(fs_1.default.existsSync(file)).toBe(true);
+        if (process.platform !== 'win32')
+            expect(fs_1.default.statSync(file).mode & 0o777).toBe(0o600);
+        const read = (0, receipt_1.readReceipt)(root, head);
+        expect(read.ok && read.receipt.sensors).toEqual({ 'a-typecheck': 'pass', lint: 'pass' });
+        expect(read.ok && Object.keys(read.receipt.sensors)).toEqual(['a-typecheck', 'lint']);
+    });
+    test('R2.3 the receipt carries schema, commit, ranAt, cliVersion and overall from the run', () => {
+        const head = g('rev-parse', 'HEAD');
+        const r = (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '9.20.0', output: { overall: 'fail', sensors: [{ name: 'lint', status: 'fail', errors: [] }] } });
+        expect(r).toMatchObject({ schema: 1, commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '9.20.0', overall: 'fail', sensors: { lint: 'fail' } });
+    });
+    (0, helpers_1.posixOnly)('R2.1 a receipt replacing an existing 0666 file ends with mode 0600', () => {
+        const head = g('rev-parse', 'HEAD');
+        fs_1.default.mkdirSync(path_1.default.dirname(runsFile(head)), { recursive: true });
+        fs_1.default.writeFileSync(runsFile(head), 'stale');
+        fs_1.default.chmodSync(runsFile(head), 0o666);
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toBe('');
+        expect(fs_1.default.statSync(runsFile(head)).mode & 0o777).toBe(0o600);
+        expect((0, receipt_1.readReceipt)(root, head).ok).toBe(true);
+    });
+    (0, helpers_1.posixOnly)('R2.1 writeReceipt forces mode 0600 on an existing file', () => {
+        const head = writeValid();
+        fs_1.default.chmodSync(runsFile(head), 0o644);
+        writeValid();
+        expect(fs_1.default.statSync(runsFile(head)).mode & 0o777).toBe(0o600);
+    });
+    (0, helpers_1.posixOnly)('R2.1 the receipt directory is 0700', () => {
+        writeValid();
+        expect(fs_1.default.statSync(path_1.default.join(root, '.awm', 'sensors', 'runs')).mode & 0o777).toBe(0o700);
+    });
+    describe('R2.2b receipt hygiene: a receipt can never be committed by git add -A', () => {
+        const ignoreFile = () => path_1.default.join(root, '.awm', 'sensors', 'runs', '.gitignore');
+        const stagedAfterAddAll = () => { g('add', '-A'); return g('diff', '--cached', '--name-only'); };
+        test('a repository that does not ignore .awm stages nothing under the runs directory', () => {
+            expect(g('ls-files', '--others', '--exclude-standard')).toBe('');
+            expect((0, receipt_1.finalizeReceipt)((0, receipt_1.captureReceiptPrecondition)(root), output)).toBe('');
+            expect(stagedAfterAddAll()).toBe('');
+            // ... and the receipt is still there, untracked and ignored.
+            const head = g('rev-parse', 'HEAD');
+            expect((0, receipt_1.readReceipt)(root, head).ok).toBe(true);
+            expect(g('check-ignore', `.awm/sensors/runs/${head}.json`)).toBe(`.awm/sensors/runs/${head}.json`);
+        });
+        test('the runs directory gets .gitignore containing exactly `*`', () => {
+            writeValid();
+            expect(fs_1.default.readFileSync(ignoreFile(), 'utf8')).toBe('*\n');
+        });
+        test('writing again is idempotent and keeps the .gitignore (same inode and content)', () => {
+            writeValid();
+            const before = fs_1.default.statSync(ignoreFile());
+            writeValid();
+            expect(fs_1.default.readFileSync(ignoreFile(), 'utf8')).toBe('*\n');
+            expect(fs_1.default.statSync(ignoreFile()).ino).toBe(before.ino);
+        });
+        test('a .gitignore with other content is replaced by `*`', () => {
+            fs_1.default.mkdirSync(path_1.default.dirname(ignoreFile()), { recursive: true });
+            fs_1.default.writeFileSync(ignoreFile(), '!*\n');
+            writeValid();
+            expect(fs_1.default.readFileSync(ignoreFile(), 'utf8')).toBe('*\n');
+        });
+        (0, helpers_1.posixOnly)('a symlinked .gitignore is refused and its target left alone, with no receipt written', () => {
+            const target = path_1.default.join(root, 'elsewhere.txt');
+            fs_1.default.writeFileSync(target, 'keep');
+            fs_1.default.mkdirSync(path_1.default.dirname(ignoreFile()), { recursive: true });
+            fs_1.default.symlinkSync(target, ignoreFile());
+            expect(() => writeValid()).toThrow(/symlink/);
+            expect(fs_1.default.readFileSync(target, 'utf8')).toBe('keep');
+            expect(fs_1.default.readdirSync(path_1.default.dirname(ignoreFile()))).toEqual(['.gitignore']);
+        });
+        test('the dirty-tree logic is unchanged: the runs directory and its .gitignore never make the tree dirty', () => {
+            writeValid();
+            expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+            g('add', '-f', '.awm/sensors/runs/.gitignore');
+            g('commit', '-q', '-m', 'chore: force-add the ignore file');
+            fs_1.default.writeFileSync(ignoreFile(), 'edited\n');
+            expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+        });
+    });
+    test('R2.1 selection rules', () => {
+        expect((0, receipt_1.isFullSelection)({})).toBe(true);
+        expect((0, receipt_1.isFullSelection)({ all: true })).toBe(true);
+        expect((0, receipt_1.isFullSelection)({ fast: true, slow: true })).toBe(true);
+        expect((0, receipt_1.isFullSelection)({ fast: true })).toBe(false);
+        expect((0, receipt_1.isFullSelection)({ slow: true })).toBe(false);
+        expect((0, receipt_1.isFullSelection)({ all: true, changed: true })).toBe(false);
+    });
+    test('R2.1 isFullSelection agrees with shouldRun for every combination of fast, slow, all and changed', () => {
+        const values = [undefined, false, true];
+        let combinations = 0;
+        for (const fast of values)
+            for (const slow of values)
+                for (const all of values)
+                    for (const changed of values) {
+                        const opts = { fast, slow, all, changed };
+                        // shouldRun does not model `changed` (it only scopes files), but a --changed run is never a full selection.
+                        const expected = (0, run_1.shouldRun)(true, opts) && (0, run_1.shouldRun)(false, opts) && !changed;
+                        expect({ opts, full: (0, receipt_1.isFullSelection)(opts) }).toEqual({ opts, full: expected });
+                        combinations++;
+                    }
+        expect(combinations).toBe(81);
+    });
+    test('R2.1 changed alone is a partial selection', () => {
+        expect((0, receipt_1.isFullSelection)({ changed: true })).toBe(false);
+    });
+    test('R2.1 all wins over fast or slow', () => {
+        expect((0, receipt_1.isFullSelection)({ all: true, fast: true })).toBe(true);
+    });
+    test('R2.2 a non-object selection is not a full selection', () => {
+        expect((0, receipt_1.isFullSelection)(undefined)).toBe(false);
+        expect((0, receipt_1.isFullSelection)(null)).toBe(false);
+    });
+    test('R2.2 an untracked file yields no receipt and a reason', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'b.txt'), 'b');
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect(pre.eligible).toBe(false);
+        const note = (0, receipt_1.finalizeReceipt)(pre, output);
+        expect(note).toMatch(/no sensor receipt written: .*uncommitted/);
+        expect(note.endsWith('\n')).toBe(true);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+    });
+    test('R2.2 a modified tracked file makes the tree dirty', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'a.txt'), 'changed');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(false);
+    });
+    test('R2.2 a staged change makes the tree dirty', () => {
+        fs_1.default.writeFileSync(path_1.default.join(root, 'a.txt'), 'staged');
+        g('add', 'a.txt');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(false);
+    });
+    test('R2.1 a modified tracked .awm/sensors.json makes the tree dirty', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'sensors.json'), '{}');
+        g('add', '.');
+        g('commit', '-q', '-m', 'chore: sensors');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'sensors.json'), '{"edited":true}');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(false);
+    });
+    test('R2.1 a modified tracked .awm/profile.json makes the tree dirty', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'profile.json'), '{}');
+        g('add', '.');
+        g('commit', '-q', '-m', 'chore: profile');
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'profile.json'), '{"edited":true}');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(false);
+    });
+    test('R2.1 an untracked file elsewhere under .awm/ makes the tree dirty', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'scratch.txt'), 'x');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(false);
+    });
+    test.each([
+        ['.awm/sensors/runs/x.json'], ['.awm/journal/entry.json'], ['.awm/ledger/l.jsonl'], ['.awm/evidence/e.txt'], ['.awm/track.json'],
+    ])('R2.1 an untracked %s does not make the tree dirty', (rel) => {
+        fs_1.default.mkdirSync(path_1.default.dirname(path_1.default.join(root, rel)), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, rel), 'x');
+        expect(g('status', '--porcelain')).not.toBe('');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+    });
+    test('R2.1 a modified tracked file under an excluded runtime path does not make the tree dirty', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'journal'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'journal', 'j.json'), '{}');
+        g('add', '.');
+        g('commit', '-q', '-m', 'chore: journal');
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'journal', 'j.json'), '{"edited":true}');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+    });
+    test('R2.1 the pre-run check sees untracked files even when status.showUntrackedFiles is no', () => {
+        g('config', 'status.showUntrackedFiles', 'no');
+        fs_1.default.writeFileSync(path_1.default.join(root, 'new.ts'), 'export {};');
+        expect(g('status', '--porcelain')).toBe('');
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect(pre.eligible).toBe(false);
+        expect(pre.eligible === false && pre.reason).toMatch(/uncommitted/);
+    });
+    test('R2.1 with status.showUntrackedFiles no, an untracked runtime-state file stays eligible', () => {
+        g('config', 'status.showUntrackedFiles', 'no');
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'journal'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'journal', 'j.json'), 'x');
+        expect((0, receipt_1.captureReceiptPrecondition)(root).eligible).toBe(true);
+    });
+    test.each([
+        ['a path traversal', '../../../x'], ['a slash', 'a/b'], ['39 hex', 'a'.repeat(39)], ['41 hex', 'a'.repeat(41)],
+        ['uppercase hex', 'A'.repeat(40)], ['a non-string', 5], ['undefined', undefined],
+    ])('R2.5 writeReceipt rejects %s as commit and writes nothing', (_n, commit) => {
+        const valid = (0, receipt_1.buildReceipt)({ commit: g('rev-parse', 'HEAD'), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        const before = listTree(root);
+        const attempt = () => (0, receipt_1.writeReceipt)(root, { ...valid, commit });
+        expect(attempt).toThrow(/invalid receipt/);
+        expect(attempt).not.toThrow(TypeError);
+        expect(listTree(root)).toEqual(before);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm'))).toBe(false);
+    });
+    test.each([['null', null], ['a string', 'x'], ['an array', []]])('R2.5 writeReceipt rejects %s as receipt without a raw TypeError', (_n, receipt) => {
+        const attempt = () => (0, receipt_1.writeReceipt)(root, receipt);
+        expect(attempt).toThrow(/invalid receipt/);
+        expect(attempt).not.toThrow(TypeError);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm'))).toBe(false);
+    });
+    test.each([['undefined', undefined], ['empty', ''], ['a number', 5]])('R2.5 writeReceipt rejects %s as root', (_n, bad) => {
+        const valid = (0, receipt_1.buildReceipt)({ commit: g('rev-parse', 'HEAD'), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        const attempt = () => (0, receipt_1.writeReceipt)(bad, valid);
+        expect(attempt).toThrow(/root must be a non-empty string/);
+        expect(attempt).not.toThrow(TypeError);
+    });
+    test('R2.5 writeReceipt rejects a receipt whose digest does not match', () => {
+        const valid = (0, receipt_1.buildReceipt)({ commit: g('rev-parse', 'HEAD'), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        expect(() => (0, receipt_1.writeReceipt)(root, { ...valid, overall: 'fail' })).toThrow(/invalid receipt: digest/);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm'))).toBe(false);
+    });
+    test('R2.3 a valid receipt round-trips write then read', () => {
+        const head = writeValid();
+        const read = (0, receipt_1.readReceipt)(root, head);
+        expect(read.ok && read.receipt.commit).toBe(head);
+        expect(read.ok && read.receipt.digest).toMatch(/^sha256:/);
+    });
+    test.each([
+        ['a multi-line sensor name', { overall: 'pass', sensors: [{ name: 'a\nb', status: 'pass', errors: [] }] }, undefined],
+        ['an empty sensor name', { overall: 'pass', sensors: [{ name: '', status: 'pass', errors: [] }] }, undefined],
+        ['a 129 code point sensor name', { overall: 'pass', sensors: [{ name: '\u{1F600}'.repeat(129), status: 'pass', errors: [] }] }, undefined],
+        ['an unknown overall', { overall: 'great', sensors: [] }, undefined],
+        ['an unknown sensor status', { overall: 'pass', sensors: [{ name: 'lint', status: 'ok', errors: [] }] }, undefined],
+        ['non-array sensors', { overall: 'pass', sensors: 'x' }, undefined],
+        ['a multi-line cliVersion', output, '1\n2'],
+    ])('R2.5 finalizeReceipt fails closed on %s: one escaped stderr line and nothing written', (_n, out, version) => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        const note = (0, receipt_1.finalizeReceipt)(pre, out, { version: () => version ?? '1.0.0' });
+        expect(note).toMatch(/^no sensor receipt written: invalid receipt: [^\n]+\n$/);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+    });
+    test('R2.5 a sensor name of exactly 128 code points is accepted and round-trips', () => {
+        const name = '\u{1F600}'.repeat(128);
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect((0, receipt_1.finalizeReceipt)(pre, { overall: 'pass', sensors: [{ name, status: 'pass', errors: [] }] })).toBe('');
+        const read = (0, receipt_1.readReceipt)(root, g('rev-parse', 'HEAD'));
+        expect(read.ok && Object.keys(read.receipt.sensors)).toEqual([name]);
+    });
+    test('R2.5 a receipt larger than readReceipt accepts is refused on write', () => {
+        const sensors = Array.from({ length: 12000 }, (_v, i) => ({ name: `${String(i).padStart(5, '0')}-${'x'.repeat(100)}`, status: 'pass', errors: [] }));
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect((0, receipt_1.finalizeReceipt)(pre, { overall: 'pass', sensors })).toMatch(/^no sensor receipt written: invalid receipt: larger than/);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+    });
+    test('R2.5 buildReceipt rejects a null input without a raw TypeError', () => {
+        expect(() => (0, receipt_1.buildReceipt)(null)).toThrow(/invalid receipt/);
+        expect(() => (0, receipt_1.buildReceipt)(null)).not.toThrow(TypeError);
+    });
+    test('R2.2 a real directory outside git still reports not a git repository', () => {
+        const plain = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plain-'));
+        try {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(plain);
+            expect(pre.eligible === false && pre.reason).toBe('not inside a git repository with a commit');
+        }
+        finally {
+            fs_1.default.rmSync(plain, { recursive: true, force: true });
+        }
+    });
+    describe('git failures', () => {
+        let spy;
+        const failStatusWith = (code) => {
+            const real = child_process_1.default.execFileSync;
+            spy = jest.spyOn(child_process_1.default, 'execFileSync').mockImplementation(((cmd, args, opts) => {
+                if (cmd === 'git' && args[0] === 'status') {
+                    throw Object.assign(new Error(`spawnSync git ${code}`), { code });
+                }
+                return real(cmd, args, opts);
+            }));
+        };
+        afterEach(() => spy?.mockRestore());
+        test.each([['ENOBUFS'], ['ETIMEDOUT']])('R2.2 a %s from git status is reported as a git failure, not a missing repository', (code) => {
+            failStatusWith(code);
+            const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+            expect(pre).toEqual({ eligible: false, reason: 'git command failed or timed out' });
+        });
+        test('R2.2 a git failure during the post-run recheck withholds the receipt with the failure reason', () => {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+            failStatusWith('ETIMEDOUT');
+            expect((0, receipt_1.finalizeReceipt)(pre, output)).toBe('no sensor receipt written: git command failed or timed out\n');
+            expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+        });
+    });
+    test('R2.1 the precondition resolves the repository root from a subdirectory', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, 'sub'));
+        const pre = (0, receipt_1.captureReceiptPrecondition)(path_1.default.join(root, 'sub'));
+        // git prints forward slashes on Windows and may resolve short names: compare both sides through the OS.
+        expect(pre.eligible).toBe(true);
+        expect(pre.eligible && fs_1.default.realpathSync.native(pre.root)).toBe(fs_1.default.realpathSync.native(root));
+        expect(pre.eligible && pre.root).toBe(path_1.default.resolve(pre.eligible ? pre.root : ''));
+        expect(pre.eligible && pre.commit).toBe(g('rev-parse', 'HEAD'));
+    });
+    test('R2.2 HEAD moving during the run yields no receipt', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.writeFileSync(path_1.default.join(root, 'c.txt'), 'c');
+        g('add', '.');
+        g('commit', '-q', '-m', 'fix: c');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/HEAD or tracked files changed/);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+    });
+    test('R2.2 a tracked file modified during the run yields no receipt and a note', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.writeFileSync(path_1.default.join(root, 'a.txt'), 'auto-fixed by a sensor');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/^no sensor receipt written: HEAD or tracked files changed during the run\n$/);
+        expect(fs_1.default.existsSync(path_1.default.join(root, '.awm', 'sensors', 'runs'))).toBe(false);
+    });
+    test('R2.2 a tracked file staged for deletion during the run yields no receipt', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        g('rm', '-q', 'a.txt');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/HEAD or tracked files changed/);
+    });
+    describe('a submodule (hidden by .gitmodules ignore=all and diff.ignoreSubmodules=all)', () => {
+        let sm = '';
+        let commitInSm = () => '';
+        beforeEach(() => {
+            const hidden = (0, helpers_1.makeHiddenSubmodule)(root, (cwd, ...args) => (0, child_process_1.execFileSync)('git', ['-c', 'commit.gpgsign=false', ...args], { cwd, encoding: 'utf8', env: gitEnv() }).trim());
+            sm = hidden.dir;
+            commitInSm = hidden.commitInSm;
+        });
+        test('R2.2 a sensor writing an untracked file inside a clean submodule still gets a receipt', () => {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+            expect(pre.eligible).toBe(true);
+            fs_1.default.writeFileSync(path_1.default.join(sm, 'coverage.out'), 'x');
+            expect((0, receipt_1.finalizeReceipt)(pre, output)).toBe('');
+            expect((0, receipt_1.readReceipt)(root, g('rev-parse', 'HEAD')).ok).toBe(true);
+        });
+        test('R2.2 a sensor that moves the submodule checkout withholds the receipt', () => {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+            commitInSm('two');
+            expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/^no sensor receipt written: HEAD or tracked files changed during the run\n$/);
+        });
+        test('R2.2 a sensor that modifies tracked content inside the submodule withholds the receipt', () => {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+            fs_1.default.writeFileSync(path_1.default.join(sm, 'one'), 'changed');
+            expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/HEAD or tracked files changed/);
+        });
+        test('R2.1 a submodule moved before the run makes the tree ineligible', () => {
+            commitInSm('two');
+            expect((0, receipt_1.captureReceiptPrecondition)(root)).toEqual({ eligible: false, reason: 'working tree has uncommitted changes (commit them first)' });
+        });
+    });
+    test('R2.2 an untracked file created by a sensor during the run does not prevent the receipt', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.mkdirSync(path_1.default.join(root, 'coverage'));
+        fs_1.default.writeFileSync(path_1.default.join(root, 'coverage', 'lcov.info'), 'x');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toBe('');
+        expect((0, receipt_1.readReceipt)(root, g('rev-parse', 'HEAD')).ok).toBe(true);
+    });
+    test('R2.2 a tracked change under an excluded runtime path during the run does not prevent the receipt', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'journal'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'journal', 'j.json'), '{}');
+        g('add', '.');
+        g('commit', '-q', '-m', 'chore: journal');
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'journal', 'j.json'), '{"edited":true}');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toBe('');
+    });
+    test('R2.2 a tracked .awm/sensors.json modified during the run yields no receipt', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'sensors.json'), '{}');
+        g('add', '.');
+        g('commit', '-q', '-m', 'chore: sensors');
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.writeFileSync(path_1.default.join(root, '.awm', 'sensors.json'), '{"edited":true}');
+        expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/HEAD or tracked files changed/);
+    });
+    test('R2.2 outside git yields no receipt', () => {
+        const plain = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plain-'));
+        try {
+            const pre = (0, receipt_1.captureReceiptPrecondition)(plain);
+            expect(pre.eligible).toBe(false);
+            expect((0, receipt_1.finalizeReceipt)(pre, output)).toMatch(/no sensor receipt written: not inside a git repository/);
+        }
+        finally {
+            fs_1.default.rmSync(plain, { recursive: true, force: true });
+        }
+    });
+    test('R2.2 a repository without a commit yields no receipt', () => {
+        const empty = fs_1.default.realpathSync.native(fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-empty-')));
+        try {
+            (0, child_process_1.execFileSync)('git', ['init', '-q', '-b', 'main'], { cwd: empty, env: gitEnv() });
+            expect((0, receipt_1.captureReceiptPrecondition)(empty).eligible).toBe(false);
+        }
+        finally {
+            fs_1.default.rmSync(empty, { recursive: true, force: true });
+        }
+    });
+    test('R2.2 a non-string cwd yields no receipt without throwing', () => {
+        expect((0, receipt_1.captureReceiptPrecondition)(undefined)).toEqual({ eligible: false, reason: 'cwd must be a non-empty string' });
+    });
+    test('R2.2 an ineligible or malformed precondition reports a reason without throwing', () => {
+        expect((0, receipt_1.finalizeReceipt)(undefined, output)).toMatch(/^no sensor receipt written: /);
+    });
+    (0, helpers_1.posixOnly)('R2.2 a write failure is reported as a single escaped line and never thrown', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'sensors'), { recursive: true });
+        const elsewhere = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-else\n-'));
+        fs_1.default.symlinkSync(elsewhere, path_1.default.join(root, '.awm', 'sensors', 'runs'));
+        try {
+            const note = (0, receipt_1.finalizeReceipt)(pre, output);
+            expect(note).toMatch(/^no sensor receipt written: .*symlink/);
+            expect(note.slice(0, -1)).not.toMatch(/[\n\r]/);
+            expect(note.endsWith('\n')).toBe(true);
+        }
+        finally {
+            fs_1.default.rmSync(elsewhere, { recursive: true, force: true });
+        }
+    });
+    test('R2.2 an error message with control characters is escaped to a single line', () => {
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        const note = (0, receipt_1.finalizeReceipt)(pre, output, { version: () => { throw new Error('bad\nline\u001b[31m'); } });
+        expect(note).toBe('no sensor receipt written: bad\\nline\\u001b[31m\n');
+    });
+    test('R2.5 an oversized receipt file is invalid', () => {
+        const head = writeValid();
+        fs_1.default.appendFileSync(runsFile(head), ' '.repeat(1024 * 1024)); // still valid JSON with a matching digest
+        expect(fs_1.default.statSync(runsFile(head)).size).toBeGreaterThan(1024 * 1024);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test('R2.5 a directory in place of the receipt file is invalid', () => {
+        const head = writeValid();
+        fs_1.default.rmSync(runsFile(head));
+        fs_1.default.mkdirSync(runsFile(head));
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test('R2.3/R2.5 digest covers every field and tampering invalidates', () => {
+        const head = g('rev-parse', 'HEAD');
+        const r = (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '9.20.0', output: output });
+        expect(r.digest).toMatch(/^sha256:[0-9a-f]{64}$/);
+        (0, receipt_1.writeReceipt)(root, r);
+        const file = path_1.default.join(root, '.awm', 'sensors', 'runs', `${head}.json`);
+        const parsed = JSON.parse(fs_1.default.readFileSync(file, 'utf8'));
+        parsed.overall = 'fail';
+        fs_1.default.writeFileSync(file, JSON.stringify(parsed));
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+        expect((0, receipt_1.readReceipt)(root, 'f'.repeat(40))).toEqual({ ok: false, code: 'receipt-missing' });
+        expect((0, receipt_1.readReceipt)(root, '../x')).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test.each([
+        ['ranAt', (r) => { r.ranAt = '2026-10-17T11:00:00.000Z'; }],
+        ['cliVersion', (r) => { r.cliVersion = '0.0.1'; }],
+        ['sensors', (r) => { r.sensors.lint = 'fail'; }],
+    ])('R2.5 changing %s without re-digesting invalidates the receipt', (_field, mutate) => {
+        const head = writeValid();
+        mutateFile(head, mutate);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test('R2.2c the digest covers the sensors as name-sorted (code unit) pairs, whatever the insertion order and integer-like names', () => {
+        const base = { schema: 1, commit: 'a'.repeat(40), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', overall: 'pass' };
+        const orders = [['9', '10', 'tsc'], ['tsc', '10', '9'], ['10', 'tsc', '9']];
+        const digests = orders.map((names) => (0, receipt_1.computeReceiptDigest)({ ...base, sensors: Object.fromEntries(names.map((n) => [n, 'pass'])) }));
+        expect(new Set(digests).size).toBe(1);
+        // Pinned: the canonical form is an array of [name, status] pairs sorted by code unit ('10' < '9' < 'tsc'), not JS object order.
+        const canonical = JSON.stringify({ schema: 1, commit: base.commit, ranAt: base.ranAt, cliVersion: base.cliVersion, overall: 'pass', sensors: [['10', 'pass'], ['9', 'pass'], ['tsc', 'pass']] });
+        expect(digests[0]).toBe('sha256:' + crypto_1.default.createHash('sha256').update(canonical).digest('hex'));
+    });
+    test('R2.2c a receipt with integer-like sensor names round-trips and its sensors read back as the same pairs', () => {
+        const names = ['9', '10', 'tsc'];
+        const pre = (0, receipt_1.captureReceiptPrecondition)(root);
+        expect((0, receipt_1.finalizeReceipt)(pre, { overall: 'pass', sensors: names.map((name) => ({ name, status: 'pass', errors: [] })) })).toBe('');
+        const read = (0, receipt_1.readReceipt)(root, g('rev-parse', 'HEAD'));
+        expect(read.ok && (0, receipt_1.sensorPairs)(read.receipt.sensors)).toEqual([['10', 'pass'], ['9', 'pass'], ['tsc', 'pass']]);
+    });
+    test('R2.3 the digest changes with each covered field', () => {
+        const base = { schema: 1, commit: 'a'.repeat(40), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', overall: 'pass', sensors: { lint: 'pass' } };
+        const d = (0, receipt_1.computeReceiptDigest)(base);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, commit: 'b'.repeat(40) })).not.toBe(d);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, ranAt: '2026-10-17T10:00:00.001Z' })).not.toBe(d);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, cliVersion: '1.0.1' })).not.toBe(d);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, overall: 'fail' })).not.toBe(d);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, sensors: { lint: 'fail' } })).not.toBe(d);
+        expect((0, receipt_1.computeReceiptDigest)({ ...base, sensors: { a: 'pass', b: 'pass' } })).toBe((0, receipt_1.computeReceiptDigest)({ ...base, sensors: { b: 'pass', a: 'pass' } }));
+    });
+    test.each([
+        ['null', null], ['undefined', undefined], ['a number', 42], ['a string', 'x'], ['an array', []],
+        ['a body whose sensors is null', { schema: 1, commit: 'a'.repeat(40), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1', overall: 'pass', sensors: null }],
+        ['a body whose sensors is a string', { schema: 1, commit: 'a'.repeat(40), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1', overall: 'pass', sensors: 'x' }],
+        ['a body whose sensors is an array', { schema: 1, commit: 'a'.repeat(40), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1', overall: 'pass', sensors: [] }],
+    ])('R2.3 computeReceiptDigest rejects %s with a typed Error, never a TypeError', (_n, body) => {
+        let caught;
+        try {
+            (0, receipt_1.computeReceiptDigest)(body);
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught).not.toBeInstanceOf(TypeError);
+        expect(caught.message).toMatch(/^invalid receipt: digest body (sensors )?must be an object$/);
+        if (!/sensors/.test(_n))
+            expect(caught.message).toBe('invalid receipt: digest body must be an object');
+    });
+    test('R2.3 buildReceipt rejects a commit that is not lowercase hex', () => {
+        const mk = (commit) => () => (0, receipt_1.buildReceipt)({ commit, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1', output: output });
+        expect(mk('../x')).toThrow(/lowercase hex/);
+        expect(mk('A'.repeat(40))).toThrow(/lowercase hex/);
+        expect(mk('a'.repeat(40))).not.toThrow();
+    });
+    test('R2.5 an extra key invalidates the receipt even with a recomputed digest', () => {
+        const head = writeValid();
+        mutateFile(head, (r) => { r.extra = 1; }, true);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test('R2.5 a receipt whose commit differs from the requested one is invalid', () => {
+        const head = writeValid();
+        mutateFile(head, (r) => { r.commit = 'e'.repeat(40); }, true);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test.each([
+        ['non-canonical ranAt', (r) => { r.ranAt = '2026-10-17'; }],
+        ['unparseable ranAt', (r) => { r.ranAt = 'not-a-date'; }],
+        ['numeric ranAt', (r) => { r.ranAt = 5; }],
+        ['unknown overall', (r) => { r.overall = 'great'; }],
+        ['unknown sensor status', (r) => { r.sensors.lint = 'ok'; }],
+        ['array sensors', (r) => { r.sensors = []; }],
+        ['null sensors', (r) => { r.sensors = null; }],
+        ['schema 2', (r) => { r.schema = 2; }],
+        ['non-string cliVersion', (r) => { r.cliVersion = 1; }],
+        ['multi-line cliVersion', (r) => { r.cliVersion = '1.0\n2.0'; }],
+        ['multi-line sensor name', (r) => { r.sensors['bad\nname'] = 'pass'; }],
+    ])('R2.5 strict shape rejects %s even with a recomputed digest', (_name, mutate) => {
+        const head = writeValid();
+        mutateFile(head, mutate, true);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test.each([['not json', 'nope{'], ['null', 'null'], ['an array', '[]'], ['a string', '"x"']])('R2.5 a file containing %s is invalid', (_n, body) => {
+        const head = writeValid();
+        fs_1.default.writeFileSync(runsFile(head), body);
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    (0, helpers_1.posixOnly)('R2.5 a symlinked receipt file is invalid', () => {
+        const head = writeValid();
+        const real = path_1.default.join(root, 'real.json');
+        fs_1.default.renameSync(runsFile(head), real);
+        fs_1.default.symlinkSync(real, runsFile(head));
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    (0, helpers_1.posixOnly)('R2.5 a receipt read through a symlinked .awm directory is invalid', () => {
+        const head = writeValid();
+        const moved = path_1.default.join(root, 'moved-awm');
+        fs_1.default.renameSync(path_1.default.join(root, '.awm'), moved);
+        fs_1.default.symlinkSync(moved, path_1.default.join(root, '.awm'));
+        expect((0, receipt_1.readReceipt)(root, head)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    test('R2.5 a missing runs directory reads as receipt-missing', () => {
+        expect((0, receipt_1.readReceipt)(root, g('rev-parse', 'HEAD'))).toEqual({ ok: false, code: 'receipt-missing' });
+    });
+    test('R2.5 readReceipt never throws on non-string input', () => {
+        expect((0, receipt_1.readReceipt)(undefined, 'a'.repeat(40))).toEqual({ ok: false, code: 'receipt-invalid' });
+        expect((0, receipt_1.readReceipt)(root, undefined)).toEqual({ ok: false, code: 'receipt-invalid' });
+    });
+    (0, helpers_1.posixOnly)('write side: a symlink already sitting at the receipt path is refused and its target is left untouched (atomic write, never a plain writeFileSync)', () => {
+        const head = g('rev-parse', 'HEAD');
+        const target = path_1.default.join(root, 'precious.txt');
+        fs_1.default.writeFileSync(target, 'keep me');
+        fs_1.default.mkdirSync(path_1.default.dirname(runsFile(head)), { recursive: true });
+        fs_1.default.symlinkSync(target, runsFile(head));
+        const receipt = (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        expect(() => (0, receipt_1.writeReceipt)(root, receipt)).toThrow(/symlink/);
+        expect(fs_1.default.readFileSync(target, 'utf8')).toBe('keep me');
+        expect(fs_1.default.lstatSync(runsFile(head)).isSymbolicLink()).toBe(true);
+    });
+    (0, helpers_1.posixOnly)('write side: a runs directory swapped for a symlink right after it was created is refused, and nothing is written through it', () => {
+        const head = g('rev-parse', 'HEAD');
+        const elsewhere = fs_1.default.mkdtempSync(path_1.default.join(home, 'elsewhere-'));
+        const real = fs_1.default.mkdirSync;
+        const spy = jest.spyOn(fs_1.default, 'mkdirSync').mockImplementation(((target, options) => {
+            const made = real(target, options);
+            if (String(target).endsWith(path_1.default.join('sensors', 'runs'))) {
+                // The race: between the mkdir and the write, the directory is replaced by a link to somewhere else.
+                fs_1.default.rmdirSync(target);
+                fs_1.default.symlinkSync(elsewhere, target);
+            }
+            return made;
+        }));
+        try {
+            const receipt = (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+            expect(() => (0, receipt_1.writeReceipt)(root, receipt)).toThrow(/symlink/);
+            expect(fs_1.default.readdirSync(elsewhere)).toEqual([]);
+        }
+        finally {
+            spy.mockRestore();
+        }
+    });
+    (0, helpers_1.posixOnly)('refuses a symlinked runs directory', () => {
+        const head = g('rev-parse', 'HEAD');
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'sensors'), { recursive: true });
+        const elsewhere = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-else-'));
+        fs_1.default.symlinkSync(elsewhere, path_1.default.join(root, '.awm', 'sensors', 'runs'));
+        const r = (0, receipt_1.buildReceipt)({ commit: head, ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        expect(() => (0, receipt_1.writeReceipt)(root, r)).toThrow(/symlink/);
+        expect(fs_1.default.readdirSync(elsewhere)).toEqual([]);
+        fs_1.default.rmSync(elsewhere, { recursive: true, force: true });
+    });
+    (0, helpers_1.posixOnly)('a symlink refusal escapes control characters in the path it names', () => {
+        const weirdRoot = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-weird\n-'));
+        const elsewhere = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-else-'));
+        try {
+            fs_1.default.symlinkSync(elsewhere, path_1.default.join(weirdRoot, '.awm'));
+            const r = (0, receipt_1.buildReceipt)({ commit: g('rev-parse', 'HEAD'), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+            let message = '';
+            try {
+                (0, receipt_1.writeReceipt)(weirdRoot, r);
+            }
+            catch (e) {
+                message = e.message;
+            }
+            expect(message).toMatch(/^refusing to use symlinked path /);
+            expect(message).not.toMatch(/[\n\r]/);
+        }
+        finally {
+            fs_1.default.rmSync(weirdRoot, { recursive: true, force: true });
+            fs_1.default.rmSync(elsewhere, { recursive: true, force: true });
+        }
+    });
+    (0, helpers_1.posixOnly)('refuses a symlinked .awm directory on write', () => {
+        const elsewhere = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-else-'));
+        fs_1.default.symlinkSync(elsewhere, path_1.default.join(root, '.awm'));
+        const r = (0, receipt_1.buildReceipt)({ commit: g('rev-parse', 'HEAD'), ranAt: '2026-10-17T10:00:00.000Z', cliVersion: '1.0.0', output: output });
+        expect(() => (0, receipt_1.writeReceipt)(root, r)).toThrow(/symlink/);
+        expect(fs_1.default.readdirSync(elsewhere)).toEqual([]);
+        fs_1.default.rmSync(elsewhere, { recursive: true, force: true });
+    });
+});
+describe('sensors run wiring (R2.2, R2.4)', () => {
+    let stdout;
+    let stderr;
+    let cwd;
+    const runCli = async (...flags) => {
+        const program = new commander_1.Command();
+        program.exitOverride();
+        (0, index_1.registerSensorsCommand)(program);
+        await program.parseAsync(['node', 'awm', 'sensors', 'run', ...flags]);
+    };
+    const written = (spy) => spy.mock.calls.map((c) => String(c[0])).join('');
+    const receiptsDir = () => path_1.default.join(root, '.awm', 'sensors', 'runs');
+    const rootManifest = () => path_1.default.join(root, '.awm', 'sensors.json');
+    // What `runSensors` reports as the manifest it ran: whatever the real resolver finds from the (mocked) cwd.
+    const resolvedManifest = () => (0, project_1.resolveSensorProject)(process.cwd()).manifestPath;
+    const commitManifest = (dir) => {
+        fs_1.default.mkdirSync(path_1.default.join(dir, '.awm'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(dir, '.awm', 'sensors.json'), '{"v":1}');
+        g('add', '-A');
+        g('commit', '-q', '-m', `chore: manifest in ${path_1.default.basename(dir)}`);
+    };
+    const receiptNames = () => fs_1.default.readdirSync(receiptsDir()).sort();
+    beforeEach(() => {
+        process.exitCode = undefined;
+        commitManifest(root);
+        run_1.findManifestDir.mockReset().mockImplementation((start) => {
+            const project = (0, project_1.resolveSensorProject)(start);
+            return project.state === 'configured' ? project.projectRoot : null;
+        });
+        run_1.runSensors.mockReset().mockImplementation(async () => ({ ...output, manifestPath: resolvedManifest() }));
+        stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        stderr = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        cwd = jest.spyOn(process, 'cwd').mockReturnValue(root);
+    });
+    afterEach(() => { stdout.mockRestore(); stderr.mockRestore(); cwd.mockRestore(); process.exitCode = undefined; });
+    test('R2.4 a full run on a clean tree writes a receipt and leaves stdout and the exit code unchanged', async () => {
+        await runCli();
+        expect(written(stdout)).toBe(JSON.stringify(output, null, 2) + '\n');
+        expect(written(stderr)).toBe('');
+        expect(process.exitCode).toBe(0);
+        expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+    });
+    test('R2.1 --all is a full selection', async () => {
+        await runCli('--all');
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(true);
+    });
+    test('R2.2 --fast writes no receipt and prints nothing on stderr', async () => {
+        await runCli('--fast');
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        expect(written(stderr)).toBe('');
+    });
+    test('R2.2 --changed writes no receipt and prints nothing on stderr', async () => {
+        await runCli('--changed');
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        expect(written(stderr)).toBe('');
+    });
+    test('R2.2 a full run on a dirty tree prints one stderr line and keeps verdict and exit code', async () => {
+        run_1.runSensors.mockResolvedValue({ overall: 'fail', sensors: [{ name: 'lint', status: 'fail', errors: [] }], manifestPath: rootManifest() });
+        fs_1.default.writeFileSync(path_1.default.join(root, 'b.txt'), 'b');
+        await runCli();
+        expect(written(stderr)).toMatch(/^no sensor receipt written: .*uncommitted.*\n$/);
+        expect(written(stdout)).toContain('"overall": "fail"');
+        expect(process.exitCode).toBe(1);
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+    });
+    test('R2.5 a sensor name the receipt cannot hold withholds the receipt but leaves stdout and the exit code unchanged', async () => {
+        const bad = { overall: 'pass', sensors: [{ name: 'a\nb', status: 'pass', errors: [] }], manifestPath: rootManifest() };
+        run_1.runSensors.mockResolvedValue(bad);
+        await runCli();
+        expect(written(stdout)).toBe(JSON.stringify(bad, null, 2) + '\n');
+        expect(process.exitCode).toBe(0);
+        expect(written(stderr)).toMatch(/^no sensor receipt written: invalid receipt: [^\n]+\n$/);
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+    });
+    test('R2.2 untracked sensor output during the run still gets a receipt with no stderr', async () => {
+        run_1.runSensors.mockImplementation(async () => { fs_1.default.writeFileSync(path_1.default.join(root, 'c.txt'), 'c'); return { ...output, manifestPath: rootManifest() }; });
+        await runCli();
+        expect(written(stderr)).toBe('');
+        expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+    });
+    test('R2.2 a tracked file changed during the run withholds the receipt with one stderr line', async () => {
+        run_1.runSensors.mockImplementation(async () => { fs_1.default.writeFileSync(path_1.default.join(root, 'a.txt'), 'fixed'); return { ...output, manifestPath: rootManifest() }; });
+        await runCli();
+        expect(written(stderr)).toMatch(/HEAD or tracked files changed/);
+        expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        expect(process.exitCode).toBe(0);
+    });
+    describe('R2.2b scope: only the repository root manifest, only when a sensor ran', () => {
+        const stdoutOf = (out) => JSON.stringify(out, null, 2) + '\n';
+        test('from a sub-directory WITHOUT its own manifest the root manifest runs (the resolver walks up) and certifies the commit', async () => {
+            const sub = path_1.default.join(root, 'packages', 'app');
+            fs_1.default.mkdirSync(sub, { recursive: true });
+            cwd.mockReturnValue(sub);
+            expect(resolvedManifest()).toBe(rootManifest());
+            await runCli();
+            expect(written(stderr)).toBe('');
+            expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+        });
+        test('a monorepo sub-manifest run writes no receipt, says so on one stderr line, and leaves stdout and the exit code alone', async () => {
+            const sub = path_1.default.join(root, 'packages', 'app');
+            fs_1.default.mkdirSync(sub, { recursive: true });
+            commitManifest(sub);
+            cwd.mockReturnValue(sub);
+            expect(fs_1.default.realpathSync.native(resolvedManifest())).toBe(fs_1.default.realpathSync.native(path_1.default.join(sub, '.awm', 'sensors.json')));
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf({ ...output, manifestPath: resolvedManifest() }));
+            expect(process.exitCode).toBe(0);
+            expect(written(stderr)).toMatch(/^no sensor receipt written: the manifest that ran is not the repository root's \.awm\/sensors\.json[^\n]*\n$/);
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('the precondition is anchored at the manifest directory, not at the cwd', async () => {
+            const plain = fs_1.default.realpathSync.native(fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-plain-')));
+            try {
+                cwd.mockReturnValue(plain); // not a git repository: only the manifest directory leads to one
+                run_1.findManifestDir.mockReturnValue(root);
+                run_1.runSensors.mockResolvedValue({ ...output, manifestPath: rootManifest() });
+                await runCli();
+                expect(written(stderr)).toBe('');
+                expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+            }
+            finally {
+                fs_1.default.rmSync(plain, { recursive: true, force: true });
+            }
+        });
+        test.each([
+            ['an empty sensors list with a pass verdict', { overall: 'pass', sensors: [] }],
+            ['not_certified with an empty list (absent or invalid manifest)', { overall: 'not_certified', sensors: [], mode: 'invalid', reason: 'manifest-malformed' }],
+        ])('%s: no receipt, one stderr line, stdout and exit code unchanged', async (_n, partial) => {
+            const out = { ...partial, manifestPath: rootManifest() };
+            run_1.runSensors.mockResolvedValue(out);
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf(out));
+            expect(process.exitCode).toBe((0, verdict_1.exitCodeForVerdict)(out.overall));
+            expect(written(stderr)).toBe('no sensor receipt written: no sensor ran, so there is nothing to certify\n');
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('R2.2c a not_certified verdict that did run sensors is reported as not certified, not as "no sensor ran"', async () => {
+            const out = { overall: 'not_certified', sensors: [{ name: 'lint', status: 'pass', errors: [] }], manifestPath: rootManifest(), reason: 'legacy-v1' };
+            run_1.runSensors.mockResolvedValue(out);
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf(out));
+            expect(process.exitCode).toBe((0, verdict_1.exitCodeForVerdict)('not_certified'));
+            expect(written(stderr)).toBe('no sensor receipt written: the verdict was not certified (not_certified)\n');
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('R2.2c schema-invalid sensor entries that were dropped withhold the receipt: it would list only the entries that ran', async () => {
+            const out = { ...output, manifestPath: rootManifest(), invalidEntries: [{ name: 'security', reason: 'command is required' }] };
+            run_1.runSensors.mockResolvedValue(out);
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf(out));
+            expect(process.exitCode).toBe(0);
+            expect(written(stderr)).toBe('no sensor receipt written: some sensor entries of the manifest were invalid and skipped, so the verdict does not cover it\n');
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('R2.2c pack drift withholds the receipt', async () => {
+            const out = { ...output, manifestPath: rootManifest(), packDrift: { manifest: 'generic', detected: 'js-ts', remedy: 'run awm sensors init' } };
+            run_1.runSensors.mockResolvedValue(out);
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf(out));
+            expect(written(stderr)).toBe('no sensor receipt written: the manifest is on the generic fallback while the tree has real stack indicators (pack drift)\n');
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('R2.2c a run in which every sensor was skipped certified nothing: no receipt, a line of its own, stdout and exit code unchanged', async () => {
+            const out = { overall: 'skipped', sensors: [{ name: 'lint', status: 'skipped', errors: [] }, { name: 'tsc', status: 'skipped', errors: [] }], manifestPath: rootManifest() };
+            run_1.runSensors.mockResolvedValue(out);
+            await runCli();
+            expect(written(stdout)).toBe(stdoutOf(out));
+            expect(process.exitCode).toBe((0, verdict_1.exitCodeForVerdict)('skipped'));
+            expect(written(stderr)).toBe('no sensor receipt written: every sensor was skipped, so the run certified nothing\n');
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+        test('R2.2c one sensor that ran among skipped ones is enough for a receipt', async () => {
+            run_1.runSensors.mockResolvedValue({ overall: 'pass', sensors: [{ name: 'lint', status: 'skipped', errors: [] }, { name: 'tsc', status: 'pass', errors: [] }], manifestPath: rootManifest() });
+            await runCli();
+            expect(written(stderr)).toBe('');
+            expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+        });
+        test('R2.2c an empty invalidEntries list does not withhold the receipt', async () => {
+            run_1.runSensors.mockResolvedValue({ ...output, manifestPath: rootManifest(), invalidEntries: [] });
+            await runCli();
+            expect(written(stderr)).toBe('');
+            expect(receiptNames()).toEqual(['.gitignore', `${g('rev-parse', 'HEAD')}.json`]);
+        });
+        test('an output that does not say which manifest ran certifies nothing (fail closed)', async () => {
+            run_1.runSensors.mockResolvedValue({ overall: 'pass', sensors: output.sensors });
+            await runCli();
+            expect(written(stderr)).toMatch(/^no sensor receipt written: the manifest that ran is not the repository root's/);
+            expect(fs_1.default.existsSync(receiptsDir())).toBe(false);
+        });
+    });
+});