agentic-workflow-manager 6.5.2 → 8.0.0

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

@@ -9,6 +9,41 @@ exports.buildManifest = buildManifest;
 exports.initSensors = initSensors;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const contract_1 = require("./compatibility/contract");
+const materialize_1 = require("./compatibility/materialize");
+const live_1 = require("./compatibility/live");
+const manifest_1 = require("./compatibility/manifest");
+const pack_source_1 = require("./compatibility/pack-source");
+/** Read a pack only through the shared source resolver.  Init is a registry
+ * boundary: a pack path that is absent is harmless, but a symlink or escaping
+ * claimed source is never silently downgraded to an empty manifest. */
+function readResolvedPack(pack, registryRoot) {
+    try {
+        const source = (0, pack_source_1.resolvePackSource)(pack, {
+            registries: [{ name: 'init-registry', remote: 'local', contentRoot: registryRoot }],
+        });
+        return { path: source.path, content: source.content };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('was not found in configured registries'))
+            return null;
+        throw error;
+    }
+}
+function readV2Pack(pack, registryRoot) {
+    const source = readResolvedPack(pack, registryRoot);
+    if (!source)
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(source.content);
+    }
+    catch {
+        throw new Error(`cannot parse sensor pack ${source.path}`);
+    }
+    const parsed = (0, contract_1.parseSensorPack)(raw, source.path);
+    return parsed.kind === 'v2' ? { pack: parsed.pack, packRoot: path_1.default.dirname(source.path) } : null;
+}
 const STACK_DETECTORS = [
     { pack: 'js-ts', files: ['package.json'] },
     { pack: 'python', files: ['pyproject.toml', 'setup.py', 'setup.cfg', 'requirements.txt', 'Pipfile'] },
@@ -60,12 +95,12 @@ function detectSourceDirs(cwd) {
  * with the project's actual source dirs. Returns null if the pack has no pack.json.
  */
 function readPackDefaults(pack, registryRoot, cwd) {
-    const packJsonPath = path_1.default.join(registryRoot, 'sensor-packs', pack, 'pack.json');
-    if (!fs_1.default.existsSync(packJsonPath))
+    const source = readResolvedPack(pack, registryRoot);
+    if (!source)
         return null;
     let parsed;
     try {
-        parsed = JSON.parse(fs_1.default.readFileSync(packJsonPath, 'utf-8'));
+        parsed = JSON.parse(source.content);
     }
     catch {
         return null;
@@ -174,7 +209,7 @@ function assertPackExists(pack, registryRoot) {
         throw new Error(`pack '${pack}' not found in registry (available: ${available.join(', ')})`);
     }
 }
-function initSensors(opts = {}) {
+async function initSensors(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const configure = opts.configure ?? true; // configure (copy pack config files) by default
     const manifestPath = path_1.default.join(cwd, '.awm', 'sensors.json');
@@ -192,15 +227,66 @@ function initSensors(opts = {}) {
         detection = detectStack(cwd);
     }
     let existing;
+    let existingV2;
     if (fs_1.default.existsSync(manifestPath)) {
+        let raw;
         try {
-            existing = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+            raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
         }
-        catch { /* ignore corrupt manifest */ }
+        catch {
+            throw new Error(`cannot parse existing sensor manifest ${manifestPath}`);
+        }
+        // Never overwrite a corrupt or future-version manifest during init. Legacy
+        // manifests remain a supported migration input; v2 is validated before a new
+        // materialized selection becomes the commit point.
+        const parsed = (0, manifest_1.parseSensorManifest)(raw, manifestPath);
+        if (parsed.kind === 'legacy')
+            existing = parsed.pack;
+        else
+            existingV2 = parsed.pack;
     }
     // `detection` keeps saying what the tree IS; `pack` is what the registry can serve
     // for it. They diverge only when the registry lacks the detected pack.
     const { pack: resolvedPack, unavailablePack } = resolvePack(detection.pack, opts.registryRoot);
+    // v2 packs own the executable contract. Legacy packs deliberately retain the
+    // old string-command path below until a registry author publishes a v2 contract.
+    if (opts.registryRoot) {
+        const resolvedV2 = readV2Pack(resolvedPack, opts.registryRoot);
+        if (resolvedV2) {
+            const compatibility = (await (0, live_1.resolveParsedPackCompatibility)(cwd, resolvedV2.pack)).sensors;
+            const sensors = {};
+            for (const [name, sensor] of Object.entries(resolvedV2.pack.sensors)) {
+                const resolved = compatibility[name];
+                const variant = resolved.variantId === null ? null : sensor.variants.find(candidate => candidate.id === resolved.variantId) ?? null;
+                // Unresolved states do not receive an arbitrary command. They remain
+                // represented in the manifest so status/coverage can explain them,
+                // but run cannot accidentally dispatch a mismatched executable.
+                if (variant) {
+                    const prior = existing?.sensors[name] ?? existingV2?.sensors[name];
+                    // Legacy string commands cannot be translated into a shell-free
+                    // structured command without guessing. Preserve the operator's
+                    // enabled/fast intent but make that migration non-certified.
+                    const migratedOverride = existing?.sensors[name]?.cmd !== undefined;
+                    sensors[name] = {
+                        enabled: prior?.enabled ?? true,
+                        fast: prior?.fast ?? sensor.fast ?? false,
+                        variantId: variant.id,
+                        command: variant.command,
+                        assets: variant.assets,
+                        initializedCompatibility: migratedOverride
+                            ? { ...resolved, state: 'compatible-unverified', reason: 'legacy custom command requires explicit v2 migration' }
+                            : resolved,
+                    };
+                }
+            }
+            const materialized = (0, materialize_1.materializeResolvedSensors)({
+                projectRoot: cwd, packRoot: resolvedV2.packRoot,
+                pack: resolvedPack, registryRoot: opts.registryRoot, sensors, configure,
+            });
+            return { detection, ...materialized,
+                compatibility, ...(unavailablePack ? { unavailablePack } : {}) };
+        }
+    }
     const manifest = buildManifest(resolvedPack, existing, opts.registryRoot, cwd);
     fs_1.default.mkdirSync(path_1.default.join(cwd, '.awm'), { recursive: true });
     const tmpPath = manifestPath + '.tmp';

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

@@ -26,6 +26,8 @@ const changed_1 = require("./changed");
 // verbo de lectura: no debe tener a mano ninguna funcion capaz de mutar el proyecto.
 const init_1 = require("./init");
 const paths_1 = require("../../core/paths");
+const manifest_1 = require("./compatibility/manifest");
+const live_1 = require("./compatibility/live");
 const MANIFEST_FILE = '.awm/sensors.json';
 const DEFAULT_FAST_TIMEOUT = 10_000;
 const DEFAULT_SLOW_TIMEOUT = 120_000;
@@ -67,6 +69,28 @@ function readManifest(cwd) {
         return null;
     }
 }
+async function resolveLiveV2(cwd, manifest) {
+    if (manifest.kind !== 'v2')
+        return null;
+    try {
+        return await (0, live_1.resolveLiveCompatibility)(cwd, manifest.pack.pack, manifest.pack.registryRoot);
+    }
+    catch {
+        return null;
+    }
+}
+async function runV2Sensor(name, command, timeout, cwd, formatter) {
+    const res = await (0, exec_1.runStructuredCommand)(command, { timeout, cwd, maxBuffer: MAX_BUFFER });
+    const format = getFormatter(name, formatter);
+    if (res.spawnError)
+        return { name, status: 'fail', errors: [{ message: `sensor could not be started: ${res.spawnError.message}` }] };
+    if (res.timedOut || res.overflowed)
+        return { name, status: 'inconclusive', errors: [], skipReason: res.timedOut ? `timeout after ${timeout}ms` : `output exceeded ${MAX_BUFFER} bytes` };
+    const errors = format(res.stdout + res.stderr);
+    if (res.code === 0)
+        return { name, status: errors.length ? 'fail' : 'pass', errors };
+    return errors.length ? { name, status: 'fail', errors } : { name, status: 'inconclusive', errors: [], skipReason: `exit ${res.code}` };
+}
 /**
  * Detect — and only detect — that the manifest's pack no longer describes the tree:
  * it sits on the `generic` fallback while real stack indicators (package.json,
@@ -105,6 +129,10 @@ function findManifestDir(startCwd) {
     while (true) {
         if (fs_1.default.existsSync(path_1.default.join(dir, MANIFEST_FILE)))
             return dir;
+        // Temp directories are test/scratch boundaries, never project ancestors.
+        // This prevents an unrelated /tmp/.awm from being adopted by a fresh project.
+        if (dir === path_1.default.resolve(os_1.default.tmpdir()))
+            return null;
         const parent = path_1.default.dirname(dir);
         if (parent === dir)
             return null; // reached filesystem root
@@ -282,6 +310,45 @@ async function runSensors(opts = {}) {
     const manifest = readManifest(manifestDir);
     if (!manifest)
         return { sensors: [], overall: 'not_certified' };
+    let parsedManifest;
+    try {
+        parsedManifest = (0, manifest_1.parseSensorManifest)(JSON.parse(fs_1.default.readFileSync(path_1.default.join(manifestDir, MANIFEST_FILE), 'utf8')), path_1.default.join(manifestDir, MANIFEST_FILE));
+    }
+    catch {
+        return { sensors: [], overall: 'not_certified' };
+    }
+    if (parsedManifest.kind === 'v2') {
+        const live = await resolveLiveV2(manifestDir, parsedManifest);
+        const tasks = [];
+        for (const [name, sensor] of Object.entries(parsedManifest.pack.sensors)) {
+            const state = live?.sensors[name];
+            const liveSensor = live?.pack.sensors[name];
+            if (!shouldRun(sensor.fast ?? liveSensor?.fast ?? false, opts))
+                continue;
+            if (sensor.enabled === false) {
+                tasks.push(() => Promise.resolve({ name, status: 'skipped', errors: [], skipReason: 'disabled' }));
+                continue;
+            }
+            if (!state || state.state !== 'certified') {
+                tasks.push(() => Promise.resolve({ name, status: 'inconclusive', errors: [], skipReason: state ? `${state.state}: ${state.reason}` : 'compatibility could not be revalidated' }));
+                continue;
+            }
+            if (state.variantId !== sensor.variantId) {
+                tasks.push(() => Promise.resolve({ name, status: 'inconclusive', errors: [], skipReason: `variant-drift: manifest ${sensor.variantId}, live ${state.variantId ?? 'none'}; run \`awm sensors init\`` }));
+                continue;
+            }
+            const selected = liveSensor?.variants.find(candidate => candidate.id === state.variantId);
+            if (!selected) {
+                tasks.push(() => Promise.resolve({ name, status: 'inconclusive', errors: [], skipReason: 'variant-drift: selected live variant has no command; run `awm sensors init`' }));
+                continue;
+            }
+            // Variant IDs are stable selectors, not immutable command snapshots.
+            // Only the just re-resolved pack command is authorized to execute.
+            tasks.push(() => runV2Sensor(name, selected.command, (sensor.fast ?? liveSensor?.fast ?? false) ? DEFAULT_FAST_TIMEOUT : DEFAULT_SLOW_TIMEOUT, manifestDir, selected.formatter));
+        }
+        const sensors = await pooled(tasks, Math.min(MAX_CONCURRENCY, Math.max(1, tasks.length)));
+        return { sensors, overall: sensors.some(sensor => sensor.status === 'fail') ? 'fail' : sensors.some(sensor => sensor.status === 'inconclusive') ? 'not_certified' : sensors.length ? 'pass' : 'skipped' };
+    }
     const drift = detectPackDrift(manifestDir, manifest);
     const activeManifest = manifest; // el manifest COMITEADO es lo que se corre; `run` no lo reescribe
     const cwd = manifestDir; // ejecutar sensores y baseline desde donde vive el manifest
@@ -382,6 +449,10 @@ async function runSensors(opts = {}) {
             : results.length > 0 && results.every(r => r.status === 'skipped') ? 'skipped'
                 : results.length === 0 ? 'skipped'
                     : 'pass';
+    // Legacy commands retain operational compatibility but their unversioned,
+    // shell-backed contract can never certify a run.
+    if (parsedManifest.kind === 'legacy' && overall === 'pass')
+        overall = 'not_certified';
     // Honest floor: a benign-green 'skipped' over a tree that clearly HAS a stack
     // (indicators present) is a false green — the gate ran nothing real. Never green.
     if (overall === 'skipped' && drift.detection.pack !== 'generic') {

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

@@ -7,6 +7,8 @@ exports.computeSensorStatus = computeSensorStatus;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const paths_1 = require("../../core/paths");
+const manifest_1 = require("./compatibility/manifest");
+const live_1 = require("./compatibility/live");
 /** First non-flag token after `npx` — the tool the command actually runs. */
 function npxTool(parts) {
     for (let i = 1; i < parts.length; i++) {
@@ -53,16 +55,57 @@ function checkCmd(cmd, cwd) {
     }
     return configCheck(parts, cwd) ?? { ok: true, detail: bin };
 }
-function computeSensorStatus(cwd = process.cwd()) {
+async function computeSensorStatus(cwd = process.cwd()) {
     const manifestPath = path_1.default.join(cwd, '.awm', 'sensors.json');
     if (!fs_1.default.existsSync(manifestPath)) {
         return { overall: 'NOT_CONFIGURED', pack: null, checks: {} };
     }
     let manifest;
     try {
-        manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+        const raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+        const parsed = (0, manifest_1.parseSensorManifest)(raw, manifestPath);
+        if (parsed.kind === 'v2') {
+            const checks = {};
+            let live;
+            try {
+                live = await (0, live_1.resolveLiveCompatibility)(cwd, parsed.pack.pack, parsed.pack.registryRoot);
+            }
+            catch (error) {
+                const detail = `compatibility revalidation failed: ${error instanceof Error ? error.message : String(error)}`;
+                for (const [name, sensor] of Object.entries(parsed.pack.sensors)) {
+                    checks[name] = sensor.enabled === false ? { ok: true, detail: 'disabled' } : { ok: false, detail };
+                }
+                return { overall: 'DEGRADED', pack: parsed.pack.pack, checks };
+            }
+            for (const [name, sensor] of Object.entries(parsed.pack.sensors)) {
+                const state = live.sensors[name];
+                checks[name] = sensor.enabled === false
+                    ? { ok: true, detail: 'disabled' }
+                    : !state
+                        ? { ok: false, detail: 'variant-drift: sensor no longer exists in the live pack; run `awm sensors init`' }
+                        : state.variantId !== sensor.variantId
+                            ? { ok: false, detail: `variant-drift: manifest ${sensor.variantId}, live ${state.variantId ?? 'none'}; run \`awm sensors init\`` }
+                            : state.state === 'certified'
+                                ? { ok: true, detail: `certified (${state.variantId})` }
+                                : state.state === 'not-applicable'
+                                    ? { ok: true, detail: 'not applicable' }
+                                    : { ok: false, detail: `${state.state}: ${state.reason}` };
+            }
+            return { overall: Object.keys(checks).length > 0 && Object.values(checks).every(check => check.ok) ? 'HEALTHY' : 'DEGRADED', pack: parsed.pack.pack, checks };
+        }
+        manifest = parsed.pack;
     }
     catch {
+        // Preserve the historic diagnostic path for a hand-edited legacy manifest:
+        // malformed v2 is fail-closed, while a legacy `sensors:null` is surfaced as
+        // degraded rather than crashing the status command.
+        try {
+            const raw = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+            if (raw && typeof raw === 'object' && !Array.isArray(raw) && !('schemaVersion' in raw) && typeof raw.pack === 'string') {
+                return { overall: 'DEGRADED', pack: raw.pack, checks: {} };
+            }
+        }
+        catch { /* malformed JSON is not configured */ }
         return { overall: 'NOT_CONFIGURED', pack: null, checks: {} };
     }
     const checks = {};
@@ -84,6 +127,7 @@ function computeSensorStatus(cwd = process.cwd()) {
     if (Object.keys(manifest.sensors ?? {}).length === 0) {
         return { overall: 'DEGRADED', pack: manifest.pack, checks };
     }
-    const allOk = Object.values(checks).every(c => c.ok);
-    return { overall: allOk ? 'HEALTHY' : 'DEGRADED', pack: manifest.pack, checks };
+    // A legacy manifest may be operational (the checks are still useful), but it
+    // has no versioned/structured contract and must never present as certified.
+    return { overall: 'DEGRADED', pack: manifest.pack, checks };
 }

package/dist/src/commands/sync.js

@@ -77,6 +77,13 @@ async function runSyncCore(options, deps = {}) {
         if (r.action === 'error')
             console.warn(picocolors_1.default.yellow(`  ⚠  registry ${r.name}: ${r.error}`));
     }
+    try {
+        (0, registries_1.assertSyncedRegistriesUsable)(syncResults);
+    }
+    catch (e) {
+        console.error(picocolors_1.default.red(e.message));
+        return { code: 1, selectedAgents };
+    }
     // Gate minCliVersion (WS-4) before pins (contract gates first — CONSTITUTION).
     try {
         (0, registries_1.assertRegistryGates)(d.verifyMinCliVersions());

package/dist/src/core/bundles.js

@@ -16,6 +16,41 @@ const registries_1 = require("./registries");
 function catalogPath(contentDir) {
     return path_1.default.join(contentDir, 'catalog.json');
 }
+function bundleManifestPath(contentDir, source) {
+    const root = path_1.default.resolve(contentDir);
+    const manifest = path_1.default.resolve(root, source, 'bundle.json');
+    const relative = path_1.default.relative(root, manifest);
+    if (relative === '..' || relative.startsWith(`..${path_1.default.sep}`) || path_1.default.isAbsolute(relative)) {
+        throw new Error(`Invalid bundle source "${source}" in ${catalogPath(contentDir)}: it must remain inside the registry content root.`);
+    }
+    let rootStat;
+    try {
+        rootStat = fs_1.default.lstatSync(root);
+    }
+    catch (error) {
+        throw new Error(`Cannot inspect registry content root ${root}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error(`Registry content root ${root} must be a regular directory`);
+    }
+    let current = root;
+    for (const segment of relative.split(path_1.default.sep)) {
+        current = path_1.default.join(current, segment);
+        let stat;
+        try {
+            stat = fs_1.default.lstatSync(current);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                break;
+            throw new Error(`Cannot inspect registry bundle path ${current}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Registry bundle path ${current} must not be a symbolic link`);
+        }
+    }
+    return manifest;
+}
 /** Lee `catalog.json` de un registry.
  *
  *  El contenido de un registry es INPUT NO CONFIABLE (un registry de equipo,
@@ -28,7 +63,7 @@ function catalogPath(contentDir) {
  *  dos eran los que faltaban. */
 function readCatalog(contentDir) {
     const file = catalogPath(contentDir);
-    if (!fs_1.default.existsSync(file))
+    if (!(0, registries_1.assertRegularRegistryFile)(file))
         return [];
     let parsed;
     try {
@@ -74,8 +109,8 @@ function discoverBundles(contentDir) {
     const entries = readCatalog(contentDir);
     const bundles = [];
     for (const entry of entries) {
-        const manifestPath = path_1.default.join(contentDir, entry.source, 'bundle.json');
-        if (!fs_1.default.existsSync(manifestPath))
+        const manifestPath = bundleManifestPath(contentDir, entry.source);
+        if (!(0, registries_1.assertRegularRegistryFile)(manifestPath))
             continue;
         let raw;
         try {

package/dist/src/core/init/steps.js

@@ -65,8 +65,8 @@ exports.defaultActions = {
         method: o.method,
         contentDir: o.contentDir,
     }),
-    initSensors: (o) => {
-        const result = (0, init_1.initSensors)({ cwd: o.cwd, registryRoot: o.registryRoot, configure: o.configure });
+    initSensors: async (o) => {
+        const result = await (0, init_1.initSensors)({ cwd: o.cwd, registryRoot: o.registryRoot, configure: o.configure });
         // `unavailablePack`/`manifest` viajan a proposito: `stepSensors` los reporta.
         // Este wrapper proyectaba solo `detection`, asi que cualquier hallazgo nuevo de
         // initSensors moria aca en silencio antes de llegar al step que lo muestra.
@@ -216,6 +216,9 @@ function stepDevCore(d) {
     // `awm doctor` decia `healthy`. Su propio `globalUnsupportedReason` ya dice
     // que hay que instalar por proyecto, asi que eso es lo que se hace.
     const localOnly = (0, providers_1.providerFor)(d.agent).skill.global === null;
+    if (localOnly && d.machineOnly) {
+        return ok('machine.devCore', 'machine', 'skipped', `${(0, providers_1.providerFor)(d.agent).label} provides skills at project scope — deferred until project initialization`);
+    }
     for (const bundleName of toInstall) {
         d.actions.installBundle({
             bundleName,
@@ -316,13 +319,13 @@ function stepActivation(d) {
     return ok('project.activation', 'project', 'applied');
 }
 /** Step 7 – Initialize the sensor manifest if absent. */
-function stepSensors(d) {
+async function stepSensors(d) {
     const proj = d.ctx.project;
     if (!proj)
         return ok('project.sensors', 'project', 'skipped', 'no project');
     if (proj.sensors.present)
         return ok('project.sensors', 'project', 'skipped');
-    const res = d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
+    const res = await d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
     // A registry without the detected pack yields a fallback (or empty) manifest. The
     // step still succeeded — a manifest was written — but reporting a bare 'applied'
     // would let `awm init` hand back a quality gate that measures less than the

package/dist/src/core/ledger/scan.js

@@ -0,0 +1,228 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LEDGER_SCAN_LIMITS = void 0;
+exports.scanProjectLedgers = scanProjectLedgers;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const types_1 = require("./types");
+exports.DEFAULT_LEDGER_SCAN_LIMITS = {
+    maxFiles: 256,
+    maxFileBytes: 4 * 1024 * 1024,
+    maxEntries: 20_000,
+    maxLineBytes: 64 * 1024,
+    maxJsonDepth: 16,
+    maxRefsPerClass: 128,
+};
+function isWithin(root, candidate) {
+    const relative = path_1.default.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path_1.default.sep}`) && relative !== '..' && !path_1.default.isAbsolute(relative));
+}
+function assertDirectoryInside(root, directory) {
+    if (!fs_1.default.existsSync(directory))
+        return false;
+    const stat = fs_1.default.lstatSync(directory);
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        throw new Error(`ledger directory is unsafe: ${directory}`);
+    return isWithin(root, fs_1.default.realpathSync(directory));
+}
+function isJsonDepthWithinLimit(raw, maxDepth) {
+    let depth = 0;
+    let quoted = false;
+    let escaped = false;
+    for (const char of raw) {
+        if (quoted) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"')
+            quoted = true;
+        else if (char === '{' || char === '[') {
+            depth += 1;
+            if (depth > maxDepth)
+                return false;
+        }
+        else if (char === '}' || char === ']')
+            depth -= 1;
+    }
+    return true;
+}
+function boundedLimits(overrides) {
+    if (overrides === null || typeof overrides !== 'object' || Array.isArray(overrides)) {
+        throw new Error('ledger scan limits must be an object');
+    }
+    const limits = { ...exports.DEFAULT_LEDGER_SCAN_LIMITS, ...overrides };
+    for (const value of Object.values(limits)) {
+        if (!Number.isSafeInteger(value) || value < 1)
+            throw new Error('ledger scan limits must be positive safe integers');
+    }
+    return limits;
+}
+function relativeSource(root, target, line) {
+    return `${relativePath(root, target)}:${line}`;
+}
+function relativePath(root, target) {
+    return path_1.default.relative(root, target).split(path_1.default.sep).join('/');
+}
+function compareCandidates(a, b) {
+    return a.sourcePath < b.sourcePath ? -1 : a.sourcePath > b.sourcePath ? 1 : 0;
+}
+/**
+ * Reads one global bounded window across the direct ledger directories, then
+ * sorts only the retained candidates. This deliberately does not claim to
+ * find a globally lexical prefix in an unbounded directory: the extra
+ * candidate is a truncation witness, and no later candidate is opened or
+ * retained from either active or archive storage.
+ */
+function collectBoundedCandidates(root, directories, maxFiles) {
+    const candidates = [];
+    const capacity = maxFiles + 1;
+    let truncated = false;
+    for (const { directory, archive } of directories) {
+        if (candidates.length >= capacity)
+            break;
+        const handle = fs_1.default.opendirSync(directory);
+        try {
+            let item;
+            while ((item = handle.readSync()) !== null) {
+                if (!item.name.endsWith('.jsonl'))
+                    continue;
+                const target = path_1.default.join(directory, item.name);
+                candidates.push({ isArchive: archive, target, sourcePath: relativePath(root, target) });
+                if (candidates.length === capacity) {
+                    truncated = true;
+                    break;
+                }
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+    }
+    candidates.sort(compareCandidates);
+    return { candidates, truncated: truncated || candidates.length > maxFiles };
+}
+/** Reads only direct .jsonl children of active/archive ledger roots; never follows links. */
+function scanProjectLedgers(projectRoot, overrides = {}) {
+    if (typeof projectRoot !== 'string' || !path_1.default.isAbsolute(projectRoot))
+        throw new Error('projectRoot must be an absolute path');
+    const limits = boundedLimits(overrides);
+    const root = fs_1.default.realpathSync(projectRoot);
+    const ledgerRoot = path_1.default.join(root, '.awm', 'ledger');
+    const sources = {
+        activeFiles: 0, archivedFiles: 0, validEntries: 0, validFindings: 0, skippedFindings: 0, skippedByReason: {},
+    };
+    const entries = [];
+    const skip = (reason) => {
+        sources.skippedFindings += 1;
+        sources.skippedByReason[reason] = (sources.skippedByReason[reason] ?? 0) + 1;
+    };
+    if (!fs_1.default.existsSync(ledgerRoot))
+        return { entries, sources, omittedEvidenceRefs: 0 };
+    if (!assertDirectoryInside(root, path_1.default.join(root, '.awm')) || !assertDirectoryInside(root, ledgerRoot)) {
+        throw new Error('ledger directory escapes project root');
+    }
+    const directories = [{ directory: ledgerRoot, archive: false }];
+    const archive = path_1.default.join(ledgerRoot, 'archive');
+    if (fs_1.default.existsSync(archive)) {
+        if (!assertDirectoryInside(root, archive))
+            throw new Error('ledger archive directory escapes project root');
+        directories.push({ directory: archive, archive: true });
+    }
+    let filesSeen = 0;
+    let linesSeen = 0;
+    let entryLimitReached = false;
+    let omittedEvidenceRefs = 0;
+    const evidenceRefsByClass = new Map();
+    const collected = collectBoundedCandidates(root, directories, limits.maxFiles);
+    for (const { isArchive, target } of collected.candidates.slice(0, limits.maxFiles)) {
+        if (entryLimitReached)
+            break;
+        filesSeen += 1;
+        const stat = fs_1.default.lstatSync(target);
+        if (stat.isSymbolicLink()) {
+            skip('symlink-entry');
+            continue;
+        }
+        if (!stat.isFile()) {
+            skip('nonregular-entry');
+            continue;
+        }
+        const real = fs_1.default.realpathSync(target);
+        if (!isWithin(root, real)) {
+            skip('path-escape');
+            continue;
+        }
+        if (stat.size > limits.maxFileBytes) {
+            skip('file-too-large');
+            continue;
+        }
+        if (isArchive)
+            sources.archivedFiles += 1;
+        else
+            sources.activeFiles += 1;
+        const lines = fs_1.default.readFileSync(target, 'utf-8').split('\n');
+        for (let index = 0; index < lines.length; index += 1) {
+            const raw = lines[index];
+            if (!raw.trim())
+                continue;
+            if (linesSeen >= limits.maxEntries) {
+                skip('entry-limit');
+                entryLimitReached = true;
+                break;
+            }
+            linesSeen += 1;
+            if (Buffer.byteLength(raw, 'utf-8') > limits.maxLineBytes) {
+                skip('line-too-large');
+                continue;
+            }
+            if (!isJsonDepthWithinLimit(raw, limits.maxJsonDepth)) {
+                skip('json-too-deep');
+                continue;
+            }
+            let value;
+            try {
+                value = JSON.parse(raw);
+            }
+            catch {
+                skip('invalid-json');
+                continue;
+            }
+            const source = relativeSource(root, target, index + 1);
+            const parsed = (0, types_1.parseLedgerEntry)(value, source);
+            if (!parsed.ok) {
+                skip(parsed.reason);
+                continue;
+            }
+            sources.validEntries += 1;
+            if (parsed.entry.polarity === 'finding') {
+                sources.validFindings += 1;
+                const defectClass = parsed.entry.defectClass ?? 'unclassified';
+                const count = evidenceRefsByClass.get(defectClass) ?? 0;
+                const evidenceRef = count < limits.maxRefsPerClass ? source : null;
+                if (evidenceRef === null) {
+                    omittedEvidenceRefs += 1;
+                    // The finding remains available for recurrence analysis, but
+                    // its public evidence is deliberately omitted. Record the
+                    // truncation through the same typed source contract as every
+                    // other scan bound so downstream renderers cannot call it a
+                    // complete report.
+                    skip('evidence-ref-limit');
+                }
+                else
+                    evidenceRefsByClass.set(defectClass, count + 1);
+                entries.push({ entry: parsed.entry, source, evidenceRef });
+            }
+        }
+    }
+    if (!entryLimitReached && collected.truncated)
+        skip('file-limit');
+    return { entries, sources, omittedEvidenceRefs };
+}