agentic-workflow-manager 6.5.2 → 8.0.0

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

@@ -7,6 +7,8 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const status_1 = require("../../../src/commands/sensors/status");
+const checks_1 = require("../../../src/commands/preflight/checks");
+const run_1 = require("../../../src/commands/sensors/run");
 // `resolveOnPath` resuelve PATH en proceso (ya no invoca un shell — ver
 // core/paths.ts). Por eso estos tests controlan un PATH aislado en vez de
 // mockear `execSync`: ademas de reflejar el mecanismo real, los vuelve
@@ -36,8 +38,8 @@ describe('computeSensorStatus', () => {
         fs_1.default.writeFileSync(p, '#!/bin/sh\nexit 0\n');
         fs_1.default.chmodSync(p, 0o755);
     }
-    it('returns NOT_CONFIGURED when .awm/sensors.json missing', () => {
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+    it('returns NOT_CONFIGURED when .awm/sensors.json missing', async () => {
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.overall).toBe('NOT_CONFIGURED');
         expect(result.pack).toBeNull();
     });
@@ -47,42 +49,42 @@ describe('computeSensorStatus', () => {
         fs_1.default.mkdirSync(binDir, { recursive: true });
         fs_1.default.writeFileSync(path_1.default.join(binDir, tool), '');
     }
-    it('returns HEALTHY when an npx tool is installed locally', () => {
+    it('keeps an operational legacy manifest DEGRADED even when its npx tool is installed locally', async () => {
         installLocalBin('tsc');
         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: { typecheck: { cmd: 'npx tsc --noEmit', fast: true } }
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
-        expect(result.overall).toBe('HEALTHY');
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
+        expect(result.overall).toBe('DEGRADED');
         expect(result.pack).toBe('js-ts');
         expect(result.checks.typecheck.ok).toBe(true);
     });
-    it('marks an npx sensor DEGRADED when the tool is NOT installed locally (npx would fetch a remote package)', () => {
+    it('marks an npx sensor DEGRADED when the tool is NOT installed locally (npx would fetch a remote package)', async () => {
         // No node_modules/.bin/depcruise → status must NOT report ✔ just because npx exists.
         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: { depcheck: { cmd: 'npx depcruise --config .dep-cruiser.awm.js app', fast: false } }
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.overall).toBe('DEGRADED');
         expect(result.checks.depcheck.ok).toBe(false);
         expect(result.checks.depcheck.detail).toMatch(/not installed locally/i);
     });
-    it('marks a sensor DEGRADED when its --config file is missing', () => {
+    it('marks a sensor DEGRADED when its --config file is missing', async () => {
         installLocalBin('eslint');
         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: { lint: { cmd: 'npx eslint . --config eslint.config.awm.mjs --format json', fast: true } }
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.checks.lint.ok).toBe(false);
         expect(result.checks.lint.detail).toMatch(/missing config/i);
     });
-    it('is HEALTHY when the npx tool is installed and the --config file exists', () => {
+    it('is HEALTHY when the npx tool is installed and the --config file exists', async () => {
         installLocalBin('eslint');
         fs_1.default.writeFileSync(path_1.default.join(tmpDir, 'eslint.config.awm.mjs'), 'export default []');
         fs_1.default.mkdirSync(path_1.default.join(tmpDir, '.awm'), { recursive: true });
@@ -90,17 +92,17 @@ describe('computeSensorStatus', () => {
             pack: 'js-ts',
             sensors: { lint: { cmd: 'npx eslint . --config eslint.config.awm.mjs --format json', fast: true } }
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.checks.lint.ok).toBe(true);
     });
-    it('returns DEGRADED when a binary is missing', () => {
+    it('returns DEGRADED when a binary is missing', async () => {
         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 } }
         }));
         // PATH aislado y vacio => semgrep no resuelve.
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.overall).toBe('DEGRADED');
         expect(result.checks.security.ok).toBe(false);
     });
@@ -112,19 +114,19 @@ describe('computeSensorStatus', () => {
         afterEach(() => {
             Object.defineProperty(process, 'platform', { value: originalPlatform });
         });
-        it('resuelve un binario instalado recorriendo PATH, sin invocar un shell', () => {
+        it('resuelve un binario instalado recorriendo PATH, sin invocar un shell', async () => {
             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 } }
             }));
             installOnPath('semgrep');
-            const result = (0, status_1.computeSensorStatus)(tmpDir);
-            expect(result.overall).toBe('HEALTHY');
+            const result = await (0, status_1.computeSensorStatus)(tmpDir);
+            expect(result.overall).toBe('DEGRADED');
             expect(result.checks.security.ok).toBe(true);
         });
     });
-    it('is DEGRADED (never HEALTHY) when the manifest has zero sensor entries', () => {
+    it('is DEGRADED (never HEALTHY) when the manifest has zero sensor entries', async () => {
         // `Object.values({}).every(...)` is vacuously true — guard against reading an
         // empty manifest (the honest floor when the registry had no pack.json for the
         // detected stack) as a clean run that found nothing wrong.
@@ -133,11 +135,11 @@ describe('computeSensorStatus', () => {
             pack: 'python',
             sensors: {},
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.overall).toBe('DEGRADED');
         expect(result.pack).toBe('python');
     });
-    it('degrades gracefully (never throws) when sensors is null in a hand-edited manifest', () => {
+    it('degrades gracefully (never throws) when sensors is null in a hand-edited manifest', async () => {
         // Regression for Finding 3: `checkManifest` (preflight) already guards
         // `manifest.sensors ?? {}` — computeSensorStatus needs the same guard, or a
         // corrupted/hand-edited manifest with `"sensors": null` crashes
@@ -147,20 +149,69 @@ describe('computeSensorStatus', () => {
             pack: 'python',
             sensors: null,
         }));
-        expect(() => (0, status_1.computeSensorStatus)(tmpDir)).not.toThrow();
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.overall).toBe('DEGRADED');
         expect(result.pack).toBe('python');
         expect(result.checks).toEqual({});
     });
-    it('marks disabled sensors as ok', () => {
+    it('marks disabled sensors as ok', async () => {
         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: { mutation: { enabled: false } }
         }));
-        const result = (0, status_1.computeSensorStatus)(tmpDir);
+        const result = await (0, status_1.computeSensorStatus)(tmpDir);
         expect(result.checks.mutation.ok).toBe(true);
         expect(result.checks.mutation.detail).toBe('disabled');
     });
+    it('does not trust the initialized v2 variant after local tool drift', async () => {
+        // The manifest records ESLint 9 at init time, but local evidence is now ESLint
+        // 10. Status must resolve the installed pack again, not certify the stale
+        // initializedCompatibility record.
+        const previousHome = process.env.AWM_HOME;
+        const home = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-status-home-'));
+        try {
+            process.env.AWM_HOME = home;
+            const registry = path_1.default.join(home, 'registries', 'baseline');
+            fs_1.default.mkdirSync(path_1.default.join(registry, 'sensor-packs', 'js-ts'), { recursive: true });
+            fs_1.default.writeFileSync(path_1.default.join(home, 'registries.json'), JSON.stringify([{ name: 'baseline', remote: 'https://example.test/baseline.git' }]));
+            const variant = (id, range) => ({
+                id, priority: 10, certifiedRange: range,
+                requirements: { tool: 'eslint', toolRange: range, runtime: 'node', runtimeRange: '>=0.0.0' },
+                assets: ['eslint.config.awm.mjs'], formatter: 'eslint-llm', probe: { kind: 'config-present' },
+                command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['.'] },
+            });
+            fs_1.default.writeFileSync(path_1.default.join(registry, 'sensor-packs', 'js-ts', 'pack.json'), JSON.stringify({
+                schemaVersion: 2, name: 'js-ts', description: 'test', detects: ['package.json'], coverage: { schemaVersion: 1, classes: { lint: { description: 'lint', detectors: [{ sensor: 'lint' }], remedy: { summary: 'fix lint', command: 'awm sensors init --pack js-ts' } } } },
+                sensors: { lint: { applicability: { allFiles: ['package.json'] }, variants: [variant('eslint-9', '>=9.0.0 <10.0.0'), variant('eslint-10', '>=10.0.0 <11.0.0')] } },
+            }));
+            fs_1.default.writeFileSync(path_1.default.join(tmpDir, 'package.json'), JSON.stringify({ devDependencies: { eslint: '^10.0.0' } }));
+            fs_1.default.mkdirSync(path_1.default.join(tmpDir, 'node_modules', 'eslint'), { recursive: true });
+            fs_1.default.writeFileSync(path_1.default.join(tmpDir, 'node_modules', 'eslint', 'package.json'), JSON.stringify({ version: '10.0.0' }));
+            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({
+                schemaVersion: 2, pack: 'js-ts', sensors: { lint: {
+                        enabled: true, variantId: 'eslint-9', command: { executable: 'eslint', resolution: 'node-modules-bin', args: ['.'] },
+                        initializedCompatibility: { state: 'certified', reason: 'range-and-probe', variantId: 'eslint-9', toolVersion: '9.0.0', runtimeVersion: process.versions.node, certifiedRange: '>=9.0.0 <10.0.0', evidence: [] },
+                    } },
+            }));
+            const result = await (0, status_1.computeSensorStatus)(tmpDir);
+            expect(result.overall).toBe('DEGRADED');
+            expect(result.checks.lint).toMatchObject({ ok: false, detail: expect.stringContaining('variant-drift') });
+            fs_1.default.writeFileSync(path_1.default.join(tmpDir, 'AGENTS.md'), '# test\n');
+            const gate = await (0, checks_1.preflight)(tmpDir);
+            expect(gate.status).toBe('degraded');
+            expect(gate.checks.find(check => check.id === 'tools')).toMatchObject({ ok: false, detail: expect.stringContaining('variant-drift') });
+            const run = await (0, run_1.runSensors)({ cwd: tmpDir, all: true });
+            expect(run.overall).toBe('not_certified');
+            expect(run.sensors).toEqual([expect.objectContaining({ name: 'lint', status: 'inconclusive', skipReason: expect.stringContaining('variant-drift') })]);
+        }
+        finally {
+            if (previousHome === undefined)
+                delete process.env.AWM_HOME;
+            else
+                process.env.AWM_HOME = previousHome;
+            fs_1.default.rmSync(home, { recursive: true, force: true });
+        }
+    });
 });

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

@@ -137,7 +137,7 @@ describe('awm update — honest outcome', () => {
         // `unusableSyncedRegistries` mira contenido EN DISCO: se siembra el content root
         // y el registries.json para que `docs` cuente como stale, no como roto.
         const registriesDir = path_1.default.join(process.env.AWM_HOME, 'registries');
-        fs_1.default.mkdirSync(path_1.default.join(registriesDir, 'docs'), { recursive: true });
+        fs_1.default.mkdirSync(path_1.default.join(registriesDir, 'docs', 'skills'), { recursive: true });
         fs_1.default.writeFileSync(path_1.default.join(process.env.AWM_HOME, 'registries.json'), JSON.stringify([{ name: 'docs', remote: 'https://example.test/docs.git' }]));
         const { runUpdateCore, updateOutro } = require('../../src/commands/update');
         const result = await runUpdateCore({}, deps({

package/dist/tests/core/bundles.test.js

@@ -37,6 +37,14 @@ describe('readCatalog', () => {
         expect(entries.map((e) => e.name).sort()).toEqual(['dev', 'frontend']);
         expect(entries.find((e) => e.name === 'dev').scope).toBe('baseline');
     });
+    it('rejects a catalog symlink instead of reading outside the registry', () => {
+        const content = makeFixture();
+        const outside = path_1.default.join(path_1.default.dirname(content), 'outside-catalog.json');
+        fs_1.default.writeFileSync(outside, JSON.stringify({ bundles: [] }));
+        fs_1.default.rmSync(path_1.default.join(content, 'catalog.json'));
+        fs_1.default.symlinkSync(outside, path_1.default.join(content, 'catalog.json'));
+        expect(() => (0, bundles_1.readCatalog)(content)).toThrow(/symbolic link/);
+    });
 });
 describe('discoverBundles', () => {
     it('loads each bundle and normalizes skill refs (string | object)', () => {
@@ -54,6 +62,35 @@ describe('discoverBundles', () => {
         const empty = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-empty-'));
         expect((0, bundles_1.discoverBundles)(empty)).toEqual([]);
     });
+    it('rejects catalog sources that escape the registry content root', () => {
+        const content = makeFixture();
+        const outside = path_1.default.join(path_1.default.dirname(content), 'outside');
+        fs_1.default.mkdirSync(outside, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(outside, 'bundle.json'), JSON.stringify({ name: 'outside' }));
+        fs_1.default.writeFileSync(path_1.default.join(content, 'catalog.json'), JSON.stringify({
+            bundles: [{ name: 'outside', source: '../outside', version: '1.0.0', scope: 'project' }],
+        }));
+        expect(() => (0, bundles_1.discoverBundles)(content)).toThrow(/invalid bundle source/i);
+    });
+    it('rejects a bundle manifest symlink instead of reading outside the registry', () => {
+        const content = makeFixture();
+        const outside = path_1.default.join(path_1.default.dirname(content), 'outside-bundle.json');
+        fs_1.default.writeFileSync(outside, JSON.stringify({ name: 'outside' }));
+        fs_1.default.rmSync(path_1.default.join(content, 'bundles', 'dev', 'bundle.json'));
+        fs_1.default.symlinkSync(outside, path_1.default.join(content, 'bundles', 'dev', 'bundle.json'));
+        expect(() => (0, bundles_1.discoverBundles)(content)).toThrow(/symbolic link/);
+    });
+    it('rejects a catalog source that reaches a bundle through an intermediate symlink', () => {
+        const content = makeFixture();
+        const outside = path_1.default.join(path_1.default.dirname(content), 'outside-bundle');
+        fs_1.default.mkdirSync(outside, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(outside, 'bundle.json'), JSON.stringify({ name: 'outside' }));
+        fs_1.default.symlinkSync(outside, path_1.default.join(content, 'outside'));
+        fs_1.default.writeFileSync(path_1.default.join(content, 'catalog.json'), JSON.stringify({
+            bundles: [{ name: 'outside', source: 'outside', version: '1.0.0', scope: 'project' }],
+        }));
+        expect(() => (0, bundles_1.discoverBundles)(content)).toThrow(/symbolic link/);
+    });
 });
 describe('resolveBundleSkills', () => {
     it('follows dependsOn transitively and dedupes', () => {

package/dist/tests/core/discovery.test.js

@@ -18,6 +18,10 @@ const WORKFLOWS_DIR = path_1.default.join(CONTENT_ROOT, 'workflows');
 describe('Artifact Discovery', () => {
     beforeEach(() => {
         jest.clearAllMocks();
+        fs_1.default.lstatSync.mockImplementation(() => {
+            const error = Object.assign(new Error('missing'), { code: 'ENOENT' });
+            throw error;
+        });
     });
     describe('discoverSkills', () => {
         it('should return a list of skill directories that contain a SKILL.md', () => {

package/dist/tests/core/init/orchestrator.test.js

@@ -19,7 +19,11 @@ function seedRegistry(contentRoot) {
     fs_1.default.writeFileSync(path_1.default.join(contentRoot, 'hooks', 'run-hook.cmd'), '#!/bin/sh\n');
     fs_1.default.chmodSync(path_1.default.join(contentRoot, 'hooks', 'run-hook.cmd'), 0o755);
     fs_1.default.mkdirSync(path_1.default.join(contentRoot, 'sensor-packs', 'js-ts'), { recursive: true });
-    fs_1.default.writeFileSync(path_1.default.join(contentRoot, 'sensor-packs', 'js-ts', 'pack.json'), JSON.stringify({ sensors: { lint: { defaultCmd: 'eslint {{SOURCE_DIRS}}', fast: true } } }));
+    fs_1.default.writeFileSync(path_1.default.join(contentRoot, 'sensor-packs', 'js-ts', 'pack.json'), 
+    // R3 validates even a legacy pack at the registry boundary.  This fixture
+    // intentionally stays legacy (no schemaVersion) but must still carry its
+    // required stable identity, just like a real legacy registry pack.
+    JSON.stringify({ name: 'js-ts', sensors: { lint: { defaultCmd: 'eslint {{SOURCE_DIRS}}', fast: true } } }));
     // catalog + bundle dev (baseline)
     fs_1.default.writeFileSync(path_1.default.join(contentRoot, 'catalog.json'), JSON.stringify({
         version: 1, bundles: [{ name: 'dev', source: './bundles/dev', version: '1.0.0', scope: 'baseline' }],

package/dist/tests/core/init/steps.test.js

@@ -143,6 +143,22 @@ describe('stepHook / stepDevCore / stepAmbient', () => {
         expect((0, steps_1.stepDevCore)(deps({ machine: m, project: null }, a)).action).toBe('applied');
         expect(a.installBundle).toHaveBeenCalled();
     });
+    it('defers local-only baseline bundles during --machine-only (R7)', () => {
+        const a = spies();
+        const m = machine();
+        m.devCore = { present: false, brokenLinks: [] };
+        const r = (0, steps_1.stepDevCore)(deps({ machine: m, project: null }, a, {
+            agent: 'copilot',
+            enabledAgents: ['copilot'],
+            machineOnly: true,
+        }));
+        expect(r).toMatchObject({
+            action: 'skipped',
+            level: 'machine',
+        });
+        expect(r.detail).toMatch(/project scope.*deferred/i);
+        expect(a.installBundle).not.toHaveBeenCalled();
+    });
     // Regression for the confirmed production bug: `awm init -a copilot` crashed
     // 100% of the time with "machine.devCore: skill global scope is not
     // supported by Copilot...", rolling back the ENTIRE init transaction (even
@@ -386,13 +402,13 @@ describe('stepActivation', () => {
     });
 });
 describe('stepSensors', () => {
-    it('skips when sensors present', () => {
+    it('skips when sensors present', async () => {
         const a = spies();
-        expect((0, steps_1.stepSensors)(deps({ machine: machine(), project: project() }, a)).action).toBe('skipped');
+        expect((await (0, steps_1.stepSensors)(deps({ machine: machine(), project: project() }, a))).action).toBe('skipped');
     });
-    it('inits sensors when absent', () => {
+    it('inits sensors when absent', async () => {
         const a = spies();
-        const r = (0, steps_1.stepSensors)(deps({ machine: machine(), project: project({ sensors: { present: false } }) }, a));
+        const r = await (0, steps_1.stepSensors)(deps({ machine: machine(), project: project({ sensors: { present: false } }) }, a));
         expect(r.action).toBe('applied');
         expect(a.initSensors).toHaveBeenCalledWith({ cwd: '/repo', registryRoot: '/cache/registry', configure: true }); // sensorPacksRoot='/cache/registry' from deps()
     });

package/dist/tests/core/ledger/scan.test.js

@@ -0,0 +1,217 @@
+"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 scan_1 = require("../../../src/core/ledger/scan");
+function mkTmp() {
+    return fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-ledger-scan-'));
+}
+function entry(over = {}) {
+    return {
+        ts: '2026-08-14T00:00:00.000Z', branch: 'feat-x', phase: 'qa', source_skill: 'post-implementation-qa',
+        polarity: 'finding', class: 'logica', signature: 'lint-error', severity: 'important', desc: 'private detail',
+        defectClass: 'lint-errors', ...over,
+    };
+}
+function write(root, relative, lines) {
+    const target = path_1.default.join(root, relative);
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    fs_1.default.writeFileSync(target, lines.map(line => typeof line === 'string' ? line : JSON.stringify(line)).join('\n') + '\n');
+}
+describe('scanProjectLedgers', () => {
+    let root;
+    beforeEach(() => { root = mkTmp(); });
+    afterEach(() => { fs_1.default.rmSync(root, { recursive: true, force: true }); });
+    test('reads only direct active and archive files in deterministic path and line order', () => {
+        write(root, '.awm/ledger/z.jsonl', [entry({ signature: 'z' })]);
+        write(root, '.awm/ledger/a.jsonl', [entry({ signature: 'a' })]);
+        write(root, '.awm/ledger/archive/b.jsonl', [entry({ signature: 'b' })]);
+        write(root, '.awm/ledger/archive/nested/ignored.jsonl', [entry({ signature: 'ignored' })]);
+        const scan = (0, scan_1.scanProjectLedgers)(root);
+        expect(scan.entries.map(item => item.source)).toEqual([
+            '.awm/ledger/a.jsonl:1', '.awm/ledger/archive/b.jsonl:1', '.awm/ledger/z.jsonl:1',
+        ]);
+        expect(scan.sources).toMatchObject({ activeFiles: 2, archivedFiles: 1, validFindings: 3, skippedFindings: 0 });
+    });
+    test('orders direct active and archive sources together by their relative path', () => {
+        write(root, '.awm/ledger/b.jsonl', [entry({ signature: 'active-b' })]);
+        write(root, '.awm/ledger/archive/a.jsonl', [entry({ signature: 'archive-a' })]);
+        const scan = (0, scan_1.scanProjectLedgers)(root);
+        expect(scan.entries.map(item => item.source)).toEqual([
+            '.awm/ledger/archive/a.jsonl:1', '.awm/ledger/b.jsonl:1',
+        ]);
+    });
+    test('counts wins as valid but excludes them from findings', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry({ polarity: 'win' }), entry({ signature: 'finding' })]);
+        const scan = (0, scan_1.scanProjectLedgers)(root);
+        expect(scan.entries.map(item => item.entry.signature)).toEqual(['finding']);
+        expect(scan.sources).toMatchObject({ validEntries: 2, validFindings: 1 });
+    });
+    test.each([
+        ['invalid JSON', 'invalid-json', ['{not-json'], {}],
+        ['invalid persisted class', 'invalid-defect-class', [{ ...entry(), defectClass: 'Bad_ID' }], {}],
+        ['oversized line', 'line-too-large', [JSON.stringify(entry()) + 'x'.repeat(100)], { maxLineBytes: 64 }],
+    ])('reports %s as a typed skipped finding', (_name, reason, lines, limits) => {
+        write(root, '.awm/ledger/a.jsonl', lines);
+        const scan = (0, scan_1.scanProjectLedgers)(root, limits);
+        expect(scan.sources.skippedFindings).toBe(1);
+        expect(scan.sources.skippedByReason).toMatchObject({ [reason]: 1 });
+    });
+    test('rejects a symlink without reading its target', () => {
+        const outside = path_1.default.join(root, 'outside.jsonl');
+        fs_1.default.writeFileSync(outside, JSON.stringify(entry()));
+        const ledger = path_1.default.join(root, '.awm', 'ledger');
+        fs_1.default.mkdirSync(ledger, { recursive: true });
+        fs_1.default.symlinkSync(outside, path_1.default.join(ledger, 'linked.jsonl'));
+        const scan = (0, scan_1.scanProjectLedgers)(root);
+        expect(scan.entries).toEqual([]);
+        expect(scan.sources.skippedByReason).toMatchObject({ 'symlink-entry': 1 });
+    });
+    test('records direct non-regular entries and never descends into them', () => {
+        fs_1.default.mkdirSync(path_1.default.join(root, '.awm', 'ledger', 'directory.jsonl'), { recursive: true });
+        write(root, '.awm/ledger/directory.jsonl/hidden.jsonl', [entry({ signature: 'hidden' })]);
+        const scan = (0, scan_1.scanProjectLedgers)(root);
+        expect(scan.entries).toEqual([]);
+        expect(scan.sources.skippedByReason).toMatchObject({ 'nonregular-entry': 1 });
+    });
+    test('reports file and entry limits once without reading candidates beyond the bound', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry({ signature: 'a' })]);
+        write(root, '.awm/ledger/b.jsonl', [entry({ signature: 'b' })]);
+        const files = (0, scan_1.scanProjectLedgers)(root, { maxFiles: 1 });
+        expect(files.entries.map(item => item.entry.signature)).toEqual(['a']);
+        expect(files.sources.skippedByReason).toMatchObject({ 'file-limit': 1 });
+        write(root, '.awm/ledger/entries.jsonl', [entry({ signature: 'first' }), entry({ signature: 'second' })]);
+        const entries = (0, scan_1.scanProjectLedgers)(root, { maxEntries: 1, maxFiles: 10 });
+        expect(entries.entries).toHaveLength(1);
+        expect(entries.sources.skippedByReason).toMatchObject({ 'entry-limit': 1 });
+    });
+    test('enumerates file candidates with bounded memory and never opens a source after maxFiles', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry({ signature: 'first' })]);
+        write(root, '.awm/ledger/b.jsonl', [entry({ signature: 'must-not-open' })]);
+        write(root, '.awm/ledger/archive/c.jsonl', [entry({ signature: 'also-must-not-open' })]);
+        const readSpy = jest.spyOn(fs_1.default, 'readFileSync');
+        const readdirSpy = jest.spyOn(fs_1.default, 'readdirSync').mockImplementation(() => {
+            throw new Error('unbounded readdir must not be used for ledger candidates');
+        });
+        try {
+            const scan = (0, scan_1.scanProjectLedgers)(root, { maxFiles: 1 });
+            expect(scan.entries.map(item => item.entry.signature)).toEqual(['first']);
+            expect(scan.sources.skippedByReason).toMatchObject({ 'file-limit': 1 });
+            expect(readSpy.mock.calls.map(([candidate]) => String(candidate))).not.toContain(path_1.default.join(root, '.awm', 'ledger', 'b.jsonl'));
+            expect(readSpy.mock.calls.map(([candidate]) => String(candidate))).not.toContain(path_1.default.join(root, '.awm', 'ledger', 'archive', 'c.jsonl'));
+        }
+        finally {
+            readdirSpy.mockRestore();
+            readSpy.mockRestore();
+        }
+    });
+    test('sorts the retained candidate window instead of assuming host directory order', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry({ signature: 'first' })]);
+        write(root, '.awm/ledger/b.jsonl', [entry({ signature: 'witness' })]);
+        write(root, '.awm/ledger/c.jsonl', [entry({ signature: 'must-not-enumerate' })]);
+        const ledgerDirectory = path_1.default.join(root, '.awm', 'ledger');
+        const originalOpen = fs_1.default.opendirSync;
+        let readCalls = 0;
+        const openSpy = jest.spyOn(fs_1.default, 'opendirSync').mockImplementation((directory, options) => {
+            if (String(directory) === ledgerDirectory) {
+                const names = ['b.jsonl', 'a.jsonl', 'c.jsonl'];
+                let index = 0;
+                return {
+                    closeSync: jest.fn(),
+                    readSync: jest.fn(() => {
+                        readCalls += 1;
+                        if (readCalls > 2)
+                            throw new Error('candidate enumeration exceeded bounded window');
+                        const name = names[index++];
+                        return name === undefined ? null : { name };
+                    }),
+                };
+            }
+            const handle = originalOpen(directory, options);
+            const originalRead = handle.readSync.bind(handle);
+            jest.spyOn(handle, 'readSync').mockImplementation(() => {
+                readCalls += 1;
+                if (readCalls > 2)
+                    throw new Error('candidate enumeration exceeded bounded window');
+                return originalRead();
+            });
+            return handle;
+        });
+        try {
+            const scan = (0, scan_1.scanProjectLedgers)(root, { maxFiles: 1 });
+            expect(scan.entries.map(item => item.entry.signature)).toEqual(['first']);
+            expect(scan.sources.skippedByReason).toMatchObject({ 'file-limit': 1 });
+            expect(readCalls).toBe(2);
+        }
+        finally {
+            openSpy.mockRestore();
+        }
+    });
+    test('shares the candidate window across active and archive directories', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry({ signature: 'active-first' })]);
+        write(root, '.awm/ledger/b.jsonl', [entry({ signature: 'active-witness' })]);
+        write(root, '.awm/ledger/archive/c.jsonl', [entry({ signature: 'archive-must-not-enumerate' })]);
+        const originalOpen = fs_1.default.opendirSync;
+        let candidateReads = 0;
+        const openSpy = jest.spyOn(fs_1.default, 'opendirSync').mockImplementation((directory, options) => {
+            const handle = originalOpen(directory, options);
+            const originalRead = handle.readSync.bind(handle);
+            jest.spyOn(handle, 'readSync').mockImplementation(() => {
+                const item = originalRead();
+                if (item?.name.endsWith('.jsonl')) {
+                    candidateReads += 1;
+                    if (candidateReads > 2)
+                        throw new Error('candidate enumeration exceeded the global bounded window');
+                }
+                return item;
+            });
+            return handle;
+        });
+        try {
+            const scan = (0, scan_1.scanProjectLedgers)(root, { maxFiles: 1 });
+            expect(scan.entries.map(item => item.entry.signature)).toEqual(['active-first']);
+            expect(scan.sources.skippedByReason).toMatchObject({ 'file-limit': 1 });
+            expect(candidateReads).toBe(2);
+        }
+        finally {
+            openSpy.mockRestore();
+        }
+    });
+    test('reports a too-large file without parsing it', () => {
+        write(root, '.awm/ledger/a.jsonl', [entry()]);
+        const scan = (0, scan_1.scanProjectLedgers)(root, { maxFileBytes: 1 });
+        expect(scan.entries).toEqual([]);
+        expect(scan.sources.skippedByReason).toMatchObject({ 'file-too-large': 1 });
+    });
+    test('reports over-deep JSON before parsing it', () => {
+        write(root, '.awm/ledger/a.jsonl', ['{"x":{"x":{"x":{"x":{"x":1}}}}}']);
+        const scan = (0, scan_1.scanProjectLedgers)(root, { maxJsonDepth: 3 });
+        expect(scan.entries).toEqual([]);
+        expect(scan.sources.skippedByReason).toMatchObject({ 'json-too-deep': 1 });
+    });
+    test('keeps every finding for analysis while bounding renderable references per defect class', () => {
+        write(root, '.awm/ledger/a.jsonl', [
+            entry({ signature: 'first', defectClass: 'lint-errors' }),
+            entry({ signature: 'second', defectClass: 'lint-errors' }),
+            entry({ signature: 'other', defectClass: 'static-type-errors' }),
+        ]);
+        const scan = (0, scan_1.scanProjectLedgers)(root, { maxRefsPerClass: 1 });
+        expect(scan.entries.map(item => item.entry.signature)).toEqual(['first', 'second', 'other']);
+        expect(scan.entries.map(item => item.evidenceRef)).toEqual([
+            '.awm/ledger/a.jsonl:1', null, '.awm/ledger/a.jsonl:3',
+        ]);
+        expect(scan.omittedEvidenceRefs).toBe(1);
+        expect(scan.sources).toMatchObject({
+            validFindings: 3,
+            skippedFindings: 1,
+            skippedByReason: { 'evidence-ref-limit': 1 },
+        });
+    });
+    test('rejects non-object limit overrides instead of accepting an impossible public input', () => {
+        expect(() => (0, scan_1.scanProjectLedgers)(root, null)).toThrow(/limits.*object/i);
+    });
+});