agent-nuvira 3.5.7 → 3.5.9

package/dist/learning/perf-probe.d.ts

@@ -0,0 +1,140 @@
+/**
+ * PERF PROBE — name the three measurements an assessment is allowed to be silent
+ * about, and the exact bounded command for each.
+ *
+ * WHY THIS EXISTS (R12, the head-to-head audit, 2026-10-16). Startup time, memory
+ * and throughput were the ONE class of claim NOBODY measured: the report that
+ * compared the two agents lists them as UNMEASURED on both sides, and on the
+ * repository under review every finding about them was an inference. A gap that
+ * both sides share is not a fair comparison — it is a blind spot in the rubric,
+ * and it is the cheapest one to close because the measurements are mechanical.
+ *
+ * THE THREE MEASUREMENTS, and why these three:
+ *
+ *   1. IMPORT / COLD-START COST — the import profiler, which names the individual
+ *      expensive imports rather than one aggregate number. For a desktop app this
+ *      is the user-visible "it takes N seconds to open".
+ *   2. PEAK ALLOCATION — `tracemalloc`. Stated honestly: it traces PYTHON
+ *      allocations and does NOT see a native/CUDA/driver allocation, so a probe
+ *      reporting 40 MB for a model loader is not a bug in the probe — it is the
+ *      boundary of what this measurement can see, and the block says so.
+ *   3. WALL CLOCK OF THE HEAVIEST REALISTIC OPERATION — the one number a user
+ *      actually feels. Deliberately NOT templated with a guessed input: the
+ *      command is the project's own entry point or e2e script, because a
+ *      synthetic input measures the synthetic input.
+ *
+ * EVERY TEMPLATE HERE WAS MEASURED AGAINST A REAL MACHINE, and two of the first
+ * drafts were wrong because of it:
+ *
+ *   - `timeout` is ABSENT on macOS and `gtimeout` is not installed by default, so
+ *     a template that assumed GNU `timeout` emitted commands that fail on the
+ *     machine this was written on. The bound is therefore chosen from what the
+ *     host HAS: the coreutils wrapper when present, else the interpreter's own
+ *     `signal.alarm` — which is a real bound, not a comment (measured: the process
+ *     is killed, and nothing after the alarm prints).
+ *   - `python` is ABSENT on macOS too (only `python3` exists), so the interpreter
+ *     name is detected rather than assumed. A probe block whose commands do not
+ *     run is worse than no probe block, because it reads as one that ran.
+ *
+ * THE IMPORT PROFILER IS REACHED TWO WAYS for the same reason: `-X importtime`
+ * when the wrapper can bound the whole command, and `PYTHONPROFILEIMPORTTIME=1`
+ * when the bound has to come from inside the interpreter (so the `-X` flag has to
+ * give way to the env var). Measured: the env var produces the same profile.
+ *
+ * HARD TIMEOUTS, OR AN HONEST REFUSAL. When neither mechanism exists (Windows, in
+ * practice) the command is emitted UNBOUNDED and the block states plainly that the
+ * bound must come from the operator and that an unbound number is tagged
+ * UNMEASURED — the discipline rules 3 and 9 already apply to hang claims, moved
+ * one step earlier, to the place the numbers come from.
+ *
+ * WHY IT ONLY NAMES COMMANDS AND NEVER RUNS THEM — same reason as
+ * `self-check-discovery.ts`: these run the project's own code, which is exactly
+ * the thing that must pass the normal tool gate. Naming the command keeps the run
+ * as one consented tool call with a stated timeout; executing it here would hand
+ * any cloned repository arbitrary code execution at prompt-assembly time. This
+ * module is READ-ONLY over the filesystem, by design.
+ *
+ * DETERMINISTIC AND LLM-FREE, like everything else in `learning/`: no model
+ * decides what a project's startup cost is. Detection that finds nothing to probe
+ * yields an EMPTY string, so that turn's prompt is byte-identical to a build
+ * without this module.
+ */
+import { type MachineFacts } from './machine-facts.js';
+/** Which runtime to probe. `none` means nothing detectable — emit nothing. */
+export type PerfRuntime = 'python' | 'node' | 'none';
+/** Everything the renderer needs, so it can be tested with no filesystem at all. */
+export interface PerfProbeInput {
+    runtime: PerfRuntime;
+    /** Importable module/package name to time, e.g. `ai_voice_studio`. */
+    pythonModule?: string;
+    /** The python executable THIS machine has (`python3` on macOS, `python` on Windows). */
+    pythonCommand?: string;
+    /** Entry file to require/run for a cold-start number, repo-relative. */
+    nodeEntry?: string;
+    /** Timeout wrapper present on this machine (`timeout`, `gtimeout`), or ''. */
+    timeoutCommand?: string;
+    /** Host platform — decides whether the runtime's own alarm is available. */
+    platform?: string;
+    /** Which `/usr/bin/time` flavour exists, for the RSS probe. */
+    nativePerfTool?: 'bsd' | 'gnu' | 'none';
+}
+/** Seconds every emitted probe is bounded to. Long enough for a real import. */
+export declare const PROBE_TIMEOUT_SECONDS = 60;
+/** Hard cap on rendered probe lines — the block shares the context budget. */
+export declare const MAX_PROBE_LINES = 26;
+/**
+ * A module name that is safe to place inside a shell template. The name is
+ * derived from the REPOSITORY (a `pyproject.toml` field or a directory name), and
+ * a template that interpolates repo-controlled text into a shell command is an
+ * injection the harness would be performing on the user's behalf. Anything outside
+ * the identifier charset is dropped; an empty result means "no probe".
+ */
+export declare function safeIdentifier(name: string): string;
+/**
+ * A repo-relative path safe inside a shell template — same reasoning as
+ * {@link safeIdentifier}, with `/` allowed. Quotes, backticks, `$` and newlines
+ * are refused outright rather than escaped, because a legitimate entry path never
+ * contains them.
+ */
+export declare function safeRelativePath(p: string): string;
+/** Does this executable exist anywhere on PATH? (Never spawns a process.) */
+export declare function executableOnPath(name: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * A python one-liner, bounded by the best mechanism this host has.
+ *
+ * Returns `bounded: false` only when there is genuinely no way to bound it, and
+ * the caller then refuses to present the probe as if it were safe.
+ */
+export declare function pythonProbe(input: PerfProbeInput, program: string): {
+    command: string;
+    bounded: boolean;
+};
+/**
+ * The import-cost probe: `-X importtime` under the coreutils wrapper, or the
+ * equivalent env var when the bound has to come from inside the interpreter.
+ * Measured: both produce the same `import time: ... imported package` profile.
+ */
+export declare function pythonImportProbe(input: PerfProbeInput, moduleName: string): {
+    command: string;
+    bounded: boolean;
+};
+/**
+ * Render the probe section for the prompt. Returns '' when there is nothing to
+ * probe, which is what keeps such a turn byte-identical to a build without this.
+ *
+ * Deliberately SHORT and imperative: three measurements, the boundary of each, and
+ * the rule for a platform that forbids one. It is not a methodology essay — the
+ * model already has rules 1, 3 and 9 for how to report.
+ */
+export declare function buildPerfProbeBlock(input: PerfProbeInput): string;
+/**
+ * Detect what this project can be probed for.
+ *
+ * Deliberately shallow and cheap: two files read, one directory listing. The
+ * Python module name comes from `pyproject.toml`, else from a top-level package
+ * directory that has an `__init__.py` (the importable shape). The Node entry comes
+ * from `package.json`'s `main`, else its first `bin`. Best-effort by contract: any
+ * failure yields `runtime: 'none'`.
+ */
+export declare function detectPerfProbeInput(dir: string, facts?: MachineFacts): PerfProbeInput;
+//# sourceMappingURL=perf-probe.d.ts.map

package/dist/learning/perf-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-probe.d.ts","sourceRoot":"","sources":["../../src/learning/perf-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAKH,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAErD,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;CACzC;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC,8EAA8E;AAC9E,eAAO,MAAM,eAAe,KAAK,CAAC;AAMlC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAW5F;AASD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAWzG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAgBvC;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CA+DjE;AAaD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,cAAc,CA4FtF"}

package/dist/learning/perf-probe.js

@@ -0,0 +1,316 @@
+/**
+ * PERF PROBE — name the three measurements an assessment is allowed to be silent
+ * about, and the exact bounded command for each.
+ *
+ * WHY THIS EXISTS (R12, the head-to-head audit, 2026-10-16). Startup time, memory
+ * and throughput were the ONE class of claim NOBODY measured: the report that
+ * compared the two agents lists them as UNMEASURED on both sides, and on the
+ * repository under review every finding about them was an inference. A gap that
+ * both sides share is not a fair comparison — it is a blind spot in the rubric,
+ * and it is the cheapest one to close because the measurements are mechanical.
+ *
+ * THE THREE MEASUREMENTS, and why these three:
+ *
+ *   1. IMPORT / COLD-START COST — the import profiler, which names the individual
+ *      expensive imports rather than one aggregate number. For a desktop app this
+ *      is the user-visible "it takes N seconds to open".
+ *   2. PEAK ALLOCATION — `tracemalloc`. Stated honestly: it traces PYTHON
+ *      allocations and does NOT see a native/CUDA/driver allocation, so a probe
+ *      reporting 40 MB for a model loader is not a bug in the probe — it is the
+ *      boundary of what this measurement can see, and the block says so.
+ *   3. WALL CLOCK OF THE HEAVIEST REALISTIC OPERATION — the one number a user
+ *      actually feels. Deliberately NOT templated with a guessed input: the
+ *      command is the project's own entry point or e2e script, because a
+ *      synthetic input measures the synthetic input.
+ *
+ * EVERY TEMPLATE HERE WAS MEASURED AGAINST A REAL MACHINE, and two of the first
+ * drafts were wrong because of it:
+ *
+ *   - `timeout` is ABSENT on macOS and `gtimeout` is not installed by default, so
+ *     a template that assumed GNU `timeout` emitted commands that fail on the
+ *     machine this was written on. The bound is therefore chosen from what the
+ *     host HAS: the coreutils wrapper when present, else the interpreter's own
+ *     `signal.alarm` — which is a real bound, not a comment (measured: the process
+ *     is killed, and nothing after the alarm prints).
+ *   - `python` is ABSENT on macOS too (only `python3` exists), so the interpreter
+ *     name is detected rather than assumed. A probe block whose commands do not
+ *     run is worse than no probe block, because it reads as one that ran.
+ *
+ * THE IMPORT PROFILER IS REACHED TWO WAYS for the same reason: `-X importtime`
+ * when the wrapper can bound the whole command, and `PYTHONPROFILEIMPORTTIME=1`
+ * when the bound has to come from inside the interpreter (so the `-X` flag has to
+ * give way to the env var). Measured: the env var produces the same profile.
+ *
+ * HARD TIMEOUTS, OR AN HONEST REFUSAL. When neither mechanism exists (Windows, in
+ * practice) the command is emitted UNBOUNDED and the block states plainly that the
+ * bound must come from the operator and that an unbound number is tagged
+ * UNMEASURED — the discipline rules 3 and 9 already apply to hang claims, moved
+ * one step earlier, to the place the numbers come from.
+ *
+ * WHY IT ONLY NAMES COMMANDS AND NEVER RUNS THEM — same reason as
+ * `self-check-discovery.ts`: these run the project's own code, which is exactly
+ * the thing that must pass the normal tool gate. Naming the command keeps the run
+ * as one consented tool call with a stated timeout; executing it here would hand
+ * any cloned repository arbitrary code execution at prompt-assembly time. This
+ * module is READ-ONLY over the filesystem, by design.
+ *
+ * DETERMINISTIC AND LLM-FREE, like everything else in `learning/`: no model
+ * decides what a project's startup cost is. Detection that finds nothing to probe
+ * yields an EMPTY string, so that turn's prompt is byte-identical to a build
+ * without this module.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { detectMachineFacts } from './machine-facts.js';
+/** Seconds every emitted probe is bounded to. Long enough for a real import. */
+export const PROBE_TIMEOUT_SECONDS = 60;
+/** Hard cap on rendered probe lines — the block shares the context budget. */
+export const MAX_PROBE_LINES = 26;
+/** The one-line honesty rule, repeated in the block: no bound, no number. */
+const UNMEASURED_RULE = 'If a number cannot be produced on this machine, tag it `UNMEASURED` and name the platform constraint — never estimate it.';
+/**
+ * A module name that is safe to place inside a shell template. The name is
+ * derived from the REPOSITORY (a `pyproject.toml` field or a directory name), and
+ * a template that interpolates repo-controlled text into a shell command is an
+ * injection the harness would be performing on the user's behalf. Anything outside
+ * the identifier charset is dropped; an empty result means "no probe".
+ */
+export function safeIdentifier(name) {
+    return String(name ?? '').replace(/[^A-Za-z0-9_.-]/g, '');
+}
+/**
+ * A repo-relative path safe inside a shell template — same reasoning as
+ * {@link safeIdentifier}, with `/` allowed. Quotes, backticks, `$` and newlines
+ * are refused outright rather than escaped, because a legitimate entry path never
+ * contains them.
+ */
+export function safeRelativePath(p) {
+    const value = String(p ?? '').trim().replace(/^\.\//, '');
+    return /^[A-Za-z0-9_./@\- ]+$/.test(value) ? value : '';
+}
+/** Does this executable exist anywhere on PATH? (Never spawns a process.) */
+export function executableOnPath(name, env = process.env) {
+    if (!name)
+        return false;
+    const dirs = (env.PATH || '').split(delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        try {
+            if (existsSync(join(dir, name)))
+                return true;
+        }
+        catch {
+            // An unreadable PATH entry tells us nothing — keep looking.
+        }
+    }
+    return false;
+}
+/** `[project] name` from a pyproject.toml, without a TOML parser. */
+function pythonNameFromToml(text) {
+    const section = /\[project\]([\s\S]*?)(?:\n\[|$)/.exec(text)?.[1] ?? '';
+    const name = /^\s*name\s*=\s*["']([^"']+)["']/m.exec(section)?.[1] ?? '';
+    return name.trim();
+}
+/**
+ * A python one-liner, bounded by the best mechanism this host has.
+ *
+ * Returns `bounded: false` only when there is genuinely no way to bound it, and
+ * the caller then refuses to present the probe as if it were safe.
+ */
+export function pythonProbe(input, program) {
+    const py = safeIdentifier(input.pythonCommand || 'python');
+    if (input.timeoutCommand) {
+        return { command: `${input.timeoutCommand} ${PROBE_TIMEOUT_SECONDS} ${py} -c "${program}"`, bounded: true };
+    }
+    if (input.platform !== 'win32') {
+        // The interpreter's own alarm — a real bound, and the reason the probe works
+        // at all on a machine without coreutils (measured on macOS: it kills the run).
+        return { command: `${py} -c "import signal; signal.alarm(${PROBE_TIMEOUT_SECONDS}); ${program}"`, bounded: true };
+    }
+    return { command: `${py} -c "${program}"`, bounded: false };
+}
+/**
+ * The import-cost probe: `-X importtime` under the coreutils wrapper, or the
+ * equivalent env var when the bound has to come from inside the interpreter.
+ * Measured: both produce the same `import time: ... imported package` profile.
+ */
+export function pythonImportProbe(input, moduleName) {
+    const py = safeIdentifier(input.pythonCommand || 'python');
+    const mod = safeIdentifier(moduleName);
+    if (input.timeoutCommand) {
+        return {
+            command: `${input.timeoutCommand} ${PROBE_TIMEOUT_SECONDS} ${py} -X importtime -c "import ${mod}" 2>&1 | tail -15`,
+            bounded: true,
+        };
+    }
+    if (input.platform !== 'win32') {
+        return {
+            command: `PYTHONPROFILEIMPORTTIME=1 ${py} -c "import signal; signal.alarm(${PROBE_TIMEOUT_SECONDS}); import ${mod}" 2>&1 | tail -15`,
+            bounded: true,
+        };
+    }
+    return { command: `${py} -X importtime -c "import ${mod}" 2>&1 | tail -15`, bounded: false };
+}
+/**
+ * Render the probe section for the prompt. Returns '' when there is nothing to
+ * probe, which is what keeps such a turn byte-identical to a build without this.
+ *
+ * Deliberately SHORT and imperative: three measurements, the boundary of each, and
+ * the rule for a platform that forbids one. It is not a methodology essay — the
+ * model already has rules 1, 3 and 9 for how to report.
+ */
+export function buildPerfProbeBlock(input) {
+    if (input.runtime === 'none')
+        return '';
+    const lines = [
+        '',
+        '## Performance probes — this class of claim went UNMEASURED last time',
+        'Every performance claim ("slow to start", "eats memory", "takes forever")',
+        'needs one of these numbers, produced by the command beside it:',
+        '',
+    ];
+    let unbounded = false;
+    if (input.runtime === 'python') {
+        const mod = safeIdentifier(input.pythonModule || '');
+        const named = mod ? `\`${mod}\`` : 'the project\'s top-level package';
+        const importProbe = pythonImportProbe(input, mod || 'PACKAGE');
+        const memProbe = pythonProbe(input, `import tracemalloc; tracemalloc.start(); import ${mod || 'PACKAGE'}; cur, peak = tracemalloc.get_traced_memory(); print(f'peak {peak/1e6:.1f} MB python-alloc')`);
+        unbounded = !importProbe.bounded || !memProbe.bounded;
+        lines.push(`- Cold import cost of ${named}:  \`${importProbe.command}\``, `- Peak PYTHON allocation:  \`${memProbe.command}\``, '  (tracemalloc sees Python allocations only — a native/CUDA allocation is', '  outside it. Report that boundary rather than calling the number total.)', input.timeoutCommand
+            ? `- Wall clock of the heaviest realistic operation: the project's own entry point or e2e script, run as \`${input.timeoutCommand} ${PROBE_TIMEOUT_SECONDS} python <its-own-entry>\`.`
+            : `- Wall clock of the heaviest realistic operation: the project's own entry point or e2e script, and bound it yourself.`);
+    }
+    else {
+        const entry = safeRelativePath(input.nodeEntry || '');
+        const named = entry ? `\`${entry}\`` : 'the project\'s own main entry';
+        const startProbe = entry
+            ? pythonProbeStyleNode(input, entry)
+            : { command: 'node <the project\'s entry>', bounded: false };
+        unbounded = !startProbe.bounded;
+        const wrap = input.timeoutCommand ? `${input.timeoutCommand} ${PROBE_TIMEOUT_SECONDS} ` : '';
+        const rss = input.nativePerfTool === 'bsd'
+            ? `\`${wrap}/usr/bin/time -l node ${entry || '<entry>'} 2>&1 | grep -i "maximum resident" | tail -2\``
+            : input.nativePerfTool === 'gnu'
+                ? `\`${wrap}/usr/bin/time -v node ${entry || '<entry>'} 2>&1 | grep -i "maximum resident" | tail -2\``
+                : 'no `/usr/bin/time` on this platform — tag it `UNMEASURED`.';
+        lines.push(`- Cold require / startup of ${named}:  \`${startProbe.command}\``, `- Peak RSS:  ${rss}`, '- Wall clock of the heaviest realistic operation: the project\'s own largest', '  command or test, bounded the same way.');
+    }
+    if (unbounded) {
+        lines.push('', `No \`timeout\`/\`gtimeout\` on this machine and no interpreter-side bound`, `available, so the commands above are bounded only by you: if one has not`, `finished in ~${PROBE_TIMEOUT_SECONDS} s, interrupt it and tag the measurement UNMEASURED.`, `Do not report a number you had to kill to get.`);
+    }
+    lines.push('', UNMEASURED_RULE, 'Report each number next to the command that produced it.');
+    return lines.slice(0, MAX_PROBE_LINES).join('\n');
+}
+/** The node cold-require one-liner, bounded where the host allows (no Windows path). */
+function pythonProbeStyleNode(input, entry) {
+    const program = `const t = Date.now(); require('./${entry}'); console.log((Date.now() - t) + ' ms cold require')`;
+    if (input.timeoutCommand) {
+        return { command: `${input.timeoutCommand} ${PROBE_TIMEOUT_SECONDS} node -e "${program}"`, bounded: true };
+    }
+    // No coreutils and no interpreter alarm for node: node's own `--eval` has no
+    // watchdog flag, so the bound is the caller's. Stated, not hidden.
+    return { command: `node -e "${program}"`, bounded: false };
+}
+/**
+ * Detect what this project can be probed for.
+ *
+ * Deliberately shallow and cheap: two files read, one directory listing. The
+ * Python module name comes from `pyproject.toml`, else from a top-level package
+ * directory that has an `__init__.py` (the importable shape). The Node entry comes
+ * from `package.json`'s `main`, else its first `bin`. Best-effort by contract: any
+ * failure yields `runtime: 'none'`.
+ */
+export function detectPerfProbeInput(dir, facts) {
+    const machine = facts ?? detectMachineFacts();
+    const platform = machine.platform;
+    const timeoutCommand = executableOnPath('timeout') ? 'timeout' : executableOnPath('gtimeout') ? 'gtimeout' : '';
+    const pythonCommand = executableOnPath('python') ? 'python' : executableOnPath('python3') ? 'python3' : 'python';
+    const nativePerfTool = platform === 'darwin' ? 'bsd' : platform === 'linux' && existsSync('/usr/bin/time') ? 'gnu' : 'none';
+    const base = { timeoutCommand, platform, pythonCommand, nativePerfTool };
+    if (!dir)
+        return { runtime: 'none', ...base };
+    try {
+        if (!existsSync(dir) || !statSync(dir).isDirectory())
+            return { runtime: 'none', ...base };
+        // ── Python ────────────────────────────────────────────────────────────────
+        let pythonModule = '';
+        const pyproject = join(dir, 'pyproject.toml');
+        if (existsSync(pyproject)) {
+            try {
+                pythonModule = pythonNameFromToml(readFileSync(pyproject, 'utf8'));
+            }
+            catch {
+                // Unreadable pyproject — fall through to the directory heuristic.
+            }
+        }
+        if (!pythonModule) {
+            try {
+                const packages = readdirSync(dir, { withFileTypes: true })
+                    .filter((e) => e.isDirectory() &&
+                    !e.name.startsWith('.') &&
+                    !/^(tests?|docs?|build|dist|node_modules|venv|\.venv)$/i.test(e.name))
+                    .map((e) => e.name)
+                    .filter((name) => existsSync(join(dir, name, '__init__.py')))
+                    .sort((a, b) => a.localeCompare(b));
+                if (packages.length > 0)
+                    pythonModule = packages[0];
+            }
+            catch {
+                // Unreadable directory — no python module.
+            }
+        }
+        // ── Node ─────────────────────────────────────────────────────────────────
+        let nodeEntry = '';
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (typeof pkg.main === 'string' && pkg.main.trim())
+                    nodeEntry = pkg.main.trim();
+                else if (typeof pkg.bin === 'string' && pkg.bin.trim())
+                    nodeEntry = pkg.bin.trim();
+                else if (pkg.bin && typeof pkg.bin === 'object') {
+                    const first = Object.keys(pkg.bin).sort((a, b) => a.localeCompare(b))[0];
+                    if (first)
+                        nodeEntry = String(pkg.bin[first]);
+                }
+            }
+            catch {
+                // Malformed package.json — not a probe candidate.
+            }
+        }
+        // WHICH RUNTIME IS THIS PROJECT'S. A top-level directory holding an
+        // `__init__.py` is NOT enough on its own: measured on this very repository,
+        // a stray fixture directory (`addon/__init__.py`) made a TypeScript project
+        // probe as Python, and the block would have told the model to time the import
+        // of a directory that is not the shipped program. Python therefore needs a
+        // PROJECT MARKER behind it — the same discipline `self-check-discovery.ts`
+        // applies before it calls something a check. A Python project that also has
+        // Node tooling is probed as Python: the runtime whose startup a user waits on
+        // is what matters, and a desktop app's is Python.
+        let hasPythonMarker = false;
+        for (const marker of ['pyproject.toml', 'setup.py', 'setup.cfg', 'Pipfile']) {
+            if (existsSync(join(dir, marker)))
+                hasPythonMarker = true;
+        }
+        if (!hasPythonMarker) {
+            try {
+                hasPythonMarker = readdirSync(dir).some((n) => /^requirements.*\.txt$/i.test(n));
+            }
+            catch {
+                // Unreadable directory — no marker.
+            }
+        }
+        const safeModule = safeIdentifier(pythonModule);
+        const safeEntry = safeRelativePath(nodeEntry);
+        if (safeModule && (hasPythonMarker || !safeEntry)) {
+            return { runtime: 'python', pythonModule: safeModule, ...base };
+        }
+        if (safeEntry)
+            return { runtime: 'node', nodeEntry: safeEntry, ...base };
+        return { runtime: 'none', ...base };
+    }
+    catch {
+        return { runtime: 'none', ...base };
+    }
+}
+//# sourceMappingURL=perf-probe.js.map

package/dist/learning/perf-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"perf-probe.js","sourceRoot":"","sources":["../../src/learning/perf-probe.ts"],"names":[],"mappings":"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"}

package/dist/learning/self-check-discovery.d.ts

@@ -0,0 +1,117 @@
+/**
+ * SELF-CHECK DISCOVERY — name the project's OWN checks on an assessment turn.
+ *
+ * WHY THIS EXISTS (the side-by-side audit, 2026-10-16). On an audit of a Python
+ * desktop app (`/Users/dheeraj/Documents/anuj_voice`, 60 modules) this CLI read
+ * the right modules, measured two real bugs, and still missed three findings
+ * that the other agent found — because it never RAN the repository's own
+ * tooling. The tree contained `tools/dead_code_audit.py` (an unreachable-code
+ * auditor, clean) and `tools/winget_validate.py` (a packaging-compliance
+ * checker, which is what reported the shipped manifest defect its test suite
+ * had been failing on). This CLI's plan mentioned `tools/` in its notes and
+ * never executed either one.
+ *
+ * That is a pure capability gap, and it is the cheapest kind to close: the
+ * project has already declared its own checks in files the agent can read, and
+ * running a check the repository itself ships produces evidence whose
+ * PROVENANCE the agent cannot fabricate. A finding that says "the project's own
+ * auditor reports X" costs one tool call and cannot be a hallucination.
+ *
+ * WHY THIS ONLY NAMES COMMANDS AND NEVER RUNS THEM. A repository's declared
+ * scripts are arbitrary code. Executing them because a prompt block suggested
+ * it would hand a cloned repository's `package.json` the ability to run
+ * anything of its choosing at audit time, with no gate and no consent — the
+ * exact class of surprise the write/shell gates exist to prevent. Naming the
+ * command keeps the decision where it belongs: the model proposes the run
+ * through the normal terminal tool, which keeps its own confirmation and
+ * sandbox rules. This module is READ-ONLY over the filesystem, by design.
+ *
+ * WHY IT IS BOUNDED, AND WHY THE CAP IS RANKED RATHER THAN ALPHABETICAL. The
+ * output is prompt text that competes with the actual file tree for the context
+ * budget, so it is capped (MAX_CHECKS) and the walk is depth-1 over known
+ * directories rather than a recursive scan. But a purely alphabetical cap is
+ * WRONG, and the audited project proves it: its `tools/` directory holds ~30
+ * scripts whose names start `a11y_`, so an alphabetical list of ten filled up
+ * before it ever reached `tools/winget_validate.py` — the checker whose output
+ * WAS the release defect the assessment missed. Ordering is therefore by
+ * RELEVANCE first (a name that says check/audit/validate/verify/lint/test…, and
+ * the project's own test suite) and alphabetical only as the tie-break inside
+ * each tier. Deterministic still, and stable across turns; just not arbitrary.
+ *
+ * WHY THE SUITE OUTRANKS LOOSE SCRIPTS. `pytest` / `npm test` is the check the
+ * project itself runs before shipping, and a directory of helper scripts is not.
+ * A cap that lets thirty utility scripts displace the test suite would give the
+ * agent the weakest evidence first.
+ *
+ * WHY IT IS DETERMINISTICALLY ORDERED. Same reason the tree walk is: a block
+ * whose contents reorder between turns breaks the prompt cache, and the whole
+ * point of an ambient block is that it is stable across the turns of one task.
+ *
+ * DETERMINISTIC AND LLM-FREE, like everything else in `learning/`: it decides
+ * from the filesystem, not from a model's idea of what a project "usually"
+ * has. A project with no discoverable checks yields an EMPTY string, so its
+ * turn is byte-identical to one from a build without this module.
+ */
+/** One command the project itself declares, and where it was declared. */
+export interface SelfCheck {
+    /** The command to run, exactly as the project declares or ships it. */
+    command: string;
+    /** Where it came from (`package.json scripts`, `tools/`, CI…). */
+    source: string;
+}
+/**
+ * Everything the discovery needs, so the matching rules can be unit-tested
+ * with no filesystem at all. {@link readProjectSelfChecks} is the thin I/O
+ * wrapper that fills this in from a real directory.
+ */
+export interface SelfCheckInput {
+    /** `package.json` `scripts`, as declared. */
+    packageScripts?: Record<string, string>;
+    /** The package manager the repo uses — decides `npm run` vs `pnpm run` … */
+    packageManager?: string;
+    /** Repo-relative paths of the project's own tooling files (`tools/audit.py`). */
+    toolFiles?: string[];
+    /** Repo-relative paths of CI workflow files. */
+    ciWorkflows?: string[];
+    /** Repo-relative paths of top-level runner files (`Makefile`, `justfile`). */
+    markerFiles?: string[];
+    /** Makefile target names, already parsed (see {@link parseMakeTargets}). */
+    makeTargets?: string[];
+    /** Does a `tests/` tree with `test_*.py` files exist? */
+    hasPythonTests?: boolean;
+}
+/** Hard cap on the rendered list — the block shares the context budget. */
+export declare const MAX_CHECKS = 10;
+/**
+ * Makefile target names — the `name:` lines at the start of a line, excluding
+ * the special targets (`%`, `.PHONY`) and any name carrying a `=`/`$` (a
+ * variable assignment, not a target).
+ */
+export declare function parseMakeTargets(text: string): string[];
+/**
+ * Turn a project's declared facts into an ordered, capped list of checks.
+ *
+ * Order is by SOURCE (scripts, then Make targets, then the shipped tools, then
+ * CI) and then alphabetically inside each source — stable across turns, and
+ * "the things the project officially declares" ahead of "the loose scripts in
+ * a folder", because the declared ones are the ones its own CI actually runs.
+ */
+export declare function discoverSelfChecks(input: SelfCheckInput): SelfCheck[];
+/**
+ * Read a directory and discover its checks. Best-effort by contract: any
+ * failure (unreadable directory, malformed `package.json`, a race with a
+ * concurrent write) yields an empty list, never a throw — an ambient context
+ * must not be able to break a turn.
+ */
+export declare function readProjectSelfChecks(dir: string): SelfCheck[];
+/**
+ * Render the checks as the prompt section the assessment protocol appends.
+ * Returns '' for an empty list, which is what keeps a project with no
+ * discoverable checks byte-identical to a build without this module.
+ *
+ * The wording carries the two rules the audit proved were missing: run these
+ * BEFORE concluding, and treat their output as the strongest evidence in the
+ * report — with the provenance named, so a reader can re-run it.
+ */
+export declare function buildSelfCheckBlock(checks: SelfCheck[]): string;
+//# sourceMappingURL=self-check-discovery.d.ts.map

package/dist/learning/self-check-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-check-discovery.d.ts","sourceRoot":"","sources":["../../src/learning/self-check-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAKH,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,yDAAyD;IACzD,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAwCD,2EAA2E;AAC3E,eAAO,MAAM,UAAU,KAAK,CAAC;AAuB7B;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,EAAE,CA0DrE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,CAqG9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAkB/D"}