@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/onboarding/setup_environment.js

@@ -0,0 +1,219 @@
+import { spawn } from 'node:child_process';
+import { basename, win32 } from 'node:path';
+import { sanitizeTerminalText } from '../ui/core/text_width.js';
+const PROBE_TIMEOUT_MS = 2000;
+const INSTALL_TIMEOUT_MS = 120_000;
+const TERMINATION_GRACE_MS = 150;
+const OUTPUT_LIMIT_BYTES = 8192;
+const CONCURRENT_PROBES = 4;
+const SHELL_SENTINEL = 'ZTC_SETUP_SHELL_READY';
+const PROBES = [
+    { id: 'git', label: 'Git', command: 'git', args: ['--version'], version: /\bgit version (\d[^\s]*)/, required: true },
+    { id: 'rg', label: 'ripgrep', command: 'rg', args: ['--version'], version: /\bripgrep (\d[^\s]*)/, required: false },
+    { id: 'gh', label: 'GitHub CLI', command: 'gh', args: ['--version'], version: /\bgh version (\d[^\s]*)/, required: false },
+    { id: 'python', label: 'Python', command: 'python3', args: ['--version'], version: /\bPython (\d[^\s]*)/, required: false },
+    { id: 'bun', label: 'Bun', command: 'bun', args: ['--version'], version: /^(\d+\.\d+[^\s]*)/m, required: false },
+    { id: 'deno', label: 'Deno', command: 'deno', args: ['--version'], version: /\bdeno (\d[^\s]*)/, required: false },
+    { id: 'make', label: 'Make', command: 'make', args: ['--version'], version: /\b(?:GNU )?Make (\d[^\s]*)/i, required: false },
+    { id: 'curl', label: 'curl', command: 'curl', args: ['--version'], version: /\bcurl (\d[^\s]*)/, required: false },
+    { id: 'ssh', label: 'SSH', command: 'ssh', args: ['-V'], version: /\bOpenSSH[_ ](\d[^\s,]*)/, required: false },
+    { id: 'tar', label: 'tar', command: 'tar', args: ['--version'], version: /\b(?:bsdtar|tar(?: \(GNU tar\))?) (\d[^\s]*)/, required: false },
+    { id: 'unzip', label: 'unzip', command: 'unzip', args: ['-v'], version: /\bUnZip (\d[^\s]*)/, required: false },
+];
+function text(value) {
+    return sanitizeTerminalText(value).replace(/\s+/g, ' ').trim().slice(0, 256);
+}
+function environment(options) {
+    return { ...(options.env ?? process.env) };
+}
+/** A fixed executable/argv process, never a caller-provided shell command. */
+async function run(command, args, options, timeoutMs) {
+    if (options.signal?.aborted)
+        return { status: 'cancelled', output: '' };
+    return new Promise(resolve => {
+        const child = spawn(command, [...args], {
+            cwd: options.cwd, env: environment(options), shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32',
+        });
+        let reason;
+        let bytes = 0;
+        let output = '';
+        let escalation;
+        let errorCode;
+        const terminate = (signal) => {
+            if (!child.pid)
+                return;
+            try {
+                if (process.platform !== 'win32')
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    child.kill(signal);
+            }
+        };
+        const stop = (status) => {
+            if (reason)
+                return;
+            reason = status;
+            terminate('SIGTERM');
+            escalation = setTimeout(() => terminate('SIGKILL'), TERMINATION_GRACE_MS);
+        };
+        const deadline = setTimeout(() => stop('timeout'), timeoutMs);
+        const abort = () => stop('cancelled');
+        options.signal?.addEventListener('abort', abort, { once: true });
+        const receive = (chunk) => {
+            bytes += chunk.length;
+            if (bytes > OUTPUT_LIMIT_BYTES) {
+                stop('output_limit');
+                return;
+            }
+            if (!reason)
+                output += chunk.toString('utf8');
+        };
+        child.stdout.on('data', receive);
+        child.stderr.on('data', receive);
+        child.on('error', error => {
+            errorCode = error.code;
+            reason ??= errorCode === 'ENOENT' ? 'missing' : 'failed';
+        });
+        child.on('close', (exitCode, signal) => {
+            clearTimeout(deadline);
+            if (escalation)
+                clearTimeout(escalation);
+            options.signal?.removeEventListener('abort', abort);
+            resolve({ status: reason ?? (exitCode === 0 && signal === null ? 'ready' : 'failed'),
+                output: reason ? '' : output, ...(exitCode !== null ? { exitCode } : {}), ...(errorCode ? { errorCode } : {}) });
+        });
+    });
+}
+function failureDetail(label, result) {
+    switch (result.status) {
+        case 'missing': return `${label} is missing from PATH. Install it or use /setup to select a supported installation.`;
+        case 'timeout': return `${label} probe timed out. Check the executable and retry /setup.`;
+        case 'cancelled': return `${label} check was cancelled. Retry /setup when ready.`;
+        case 'output_limit': return `${label} exceeded the bounded output limit. Check the executable and retry /setup.`;
+        default: return `${label} failed${result.exitCode !== undefined ? ` with exit ${result.exitCode}` : result.errorCode ? ` (${text(result.errorCode)})` : ''}. Repair the tool or PATH and retry /setup.`;
+    }
+}
+async function inspectTool(probe, options) {
+    const result = await run(probe.command, probe.args, options, PROBE_TIMEOUT_MS);
+    const version = result.status === 'ready' ? probe.version.exec(result.output)?.[1] : undefined;
+    return { id: probe.id, label: probe.label, required: probe.required,
+        status: result.status === 'ready' && !version ? 'failed' : result.status,
+        detail: result.status === 'ready' ? version ? `${probe.label} is available.` : `${probe.label} did not return a recognized version. Repair the executable and retry /setup.` : failureDetail(probe.label, result),
+        ...(version ? { version: text(version) } : {}) };
+}
+async function inspectGitHubAuth(options) {
+    // Do not request --show-token/JSON or retain any auth stdout/stderr in the report.
+    const result = await run('gh', ['auth', 'status', '--active', '--hostname', 'github.com'], options, PROBE_TIMEOUT_MS);
+    return { id: 'gh_auth', label: 'GitHub authentication', required: false, status: result.status,
+        detail: result.status === 'ready' ? 'The active GitHub account is authenticated for github.com.'
+            : result.status === 'failed' ? 'GitHub authentication is unavailable. Run gh auth login manually, then retry /setup.'
+                : failureDetail('GitHub authentication', result) };
+}
+/** Health uses only an allowlisted shell name and a fixed, literal sentinel. */
+export async function runSetupShellHealth(options = {}) {
+    const env = environment(options);
+    const path = (process.platform === 'win32' ? env.COMSPEC ?? env.ComSpec ?? 'cmd.exe' : env.SHELL ?? '/bin/sh');
+    const name = (process.platform === 'win32' ? win32.basename(path) : basename(path)).toLowerCase().replace(/\.exe$/, '');
+    let args;
+    if (['sh', 'bash', 'zsh', 'dash', 'ksh', 'fish'].includes(name))
+        args = ['-c', `printf %s ${SHELL_SENTINEL}`];
+    else if (name === 'cmd' && process.platform === 'win32')
+        args = ['/d', '/s', '/c', `echo ${SHELL_SENTINEL}`];
+    else if (['powershell', 'pwsh'].includes(name))
+        args = ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', `[Console]::Write('${SHELL_SENTINEL}')`];
+    else
+        return { name: text(name), path: text(path), status: 'unsupported', detail: 'Selected shell is unsupported. Select sh, bash, zsh, fish, PowerShell or cmd outside ZTC and retry /setup.' };
+    if (!path || path.length > 1024 || /[\0\r\n]/.test(path)) {
+        return { name: text(name), path: text(path), status: 'unsupported', detail: 'Selected shell path is invalid. Correct the shell environment and retry /setup.' };
+    }
+    const result = await run(path, args, options, PROBE_TIMEOUT_MS);
+    const healthReady = result.status === 'ready' && result.output.trim() === SHELL_SENTINEL;
+    return { name: text(name), path: text(path), status: result.status === 'ready' && !healthReady ? 'failed' : result.status,
+        detail: healthReady ? 'Selected shell executed the setup health sentinel.'
+            : result.status === 'ready' ? 'Selected shell did not return the expected health sentinel. Repair its startup configuration and retry /setup.' : failureDetail('Selected shell', result) };
+}
+async function bounded(work) {
+    const result = new Array(work.length);
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(CONCURRENT_PROBES, work.length) }, async () => {
+        while (next < work.length) {
+            const index = next++;
+            result[index] = await work[index]();
+        }
+    }));
+    return result;
+}
+export async function inspectSetupEnvironment(options = {}) {
+    const managers = process.platform === 'darwin' ? ['brew']
+        : process.platform === 'linux' ? ['apt', 'dnf', 'brew'] : [];
+    const work = [
+        () => runSetupShellHealth(options), ...PROBES.map(probe => () => inspectTool(probe, options)),
+        () => inspectGitHubAuth(options), ...managers.map(manager => () => run(manager === 'apt' ? 'apt-get' : manager, ['--version'], options, PROBE_TIMEOUT_MS)),
+    ];
+    const results = await bounded(work);
+    const shell = results[0];
+    const checks = results.slice(1, PROBES.length + 2);
+    const managerResults = results.slice(PROBES.length + 2);
+    const managerIndex = managerResults.findIndex((result, index) => result.status === 'ready'
+        && (managers[index] === 'brew' ? /\bHomebrew \d/.test(result.output) : managers[index] === 'apt' ? /\bapt \d/.test(result.output) : /^(?:dnf5? version )?\d+\./m.test(result.output)));
+    const problemManager = managerResults.find(result => result.status !== 'missing');
+    const packageManager = managerIndex >= 0
+        ? { id: managers[managerIndex], status: 'ready', detail: `${managers[managerIndex]} is available for explicitly selected Git/ripgrep installations.` }
+        : managers.length === 0 ? { id: null, status: 'unsupported', detail: 'Automatic tool installation supports Homebrew, apt and dnf. Install missing tools manually on this platform.' }
+            : problemManager ? { id: null, status: problemManager.status === 'ready' ? 'failed' : problemManager.status, detail: failureDetail('Supported package manager', { ...problemManager, status: problemManager.status === 'ready' ? 'failed' : problemManager.status }) }
+                : { id: null, status: 'missing', detail: 'No supported package manager is available. Install missing tools manually or configure Homebrew, apt or dnf outside ZTC.' };
+    const runtimeKind = options.runtimeKind ?? 'host';
+    const nodeReady = /^v\d+\./.test(process.version) && Number(process.versions.node.split('.')[0]) >= 20;
+    const node = {
+        version: process.version, executable: process.execPath, runtimeKind,
+        status: nodeReady ? 'ready' : 'unsupported',
+        detail: nodeReady ? `The running ${runtimeKind === 'bundled' ? 'bundled' : 'host'} Node runtime meets ZTC's Node 20 requirement.`
+            : runtimeKind === 'bundled' ? 'The bundled runtime requires Node 20 or later. Update or reinstall the desktop app.' : 'ZTC requires Node 20 or later. Update the Node runtime used to launch ZTC.',
+    };
+    return { platform: process.platform, shell, node, packageManager, checks,
+        ready: nodeReady && shell.status === 'ready' && checks.filter(check => check.required).every(check => check.status === 'ready') };
+}
+/** Only fixed package names/argv are supported; no sudo or arbitrary command input. */
+export async function installMissingSetupTools(options) {
+    if (!Array.isArray(options.tools) || options.tools.length > 16 || options.tools.some(tool => tool !== 'git' && tool !== 'rg')) {
+        throw new RangeError('Unsupported setup install tool: choose Git and/or ripgrep.');
+    }
+    const tools = [...new Set(options.tools)];
+    const before = await inspectSetupEnvironment(options);
+    const attempts = [];
+    for (const tool of tools) {
+        const check = before.checks.find(entry => entry.id === tool);
+        if (options.signal?.aborted || check.status === 'cancelled') {
+            attempts.push({ tool, status: 'cancelled', action: 'not_installed', detail: 'Installation was cancelled. Retry /setup when ready.' });
+            continue;
+        }
+        if (check.status !== 'missing') {
+            attempts.push({ tool, status: check.status, action: 'skipped', detail: check.status === 'ready' ? `${check.label} is already available; no installation is needed.` : `${check.label} is present but unhealthy. Repair the executable before retrying installation.` });
+            continue;
+        }
+        const manager = before.packageManager.id;
+        if (!manager) {
+            attempts.push({ tool, status: 'unsupported', action: 'not_installed', detail: 'No supported package manager is available. Install this tool manually, then retry /setup.' });
+            continue;
+        }
+        // Official fixed install syntax: docs.brew.sh/Manpage; Debian apt-get(8); dnf command_ref.
+        const command = manager === 'apt' ? 'apt-get' : manager;
+        const packageName = tool === 'rg' ? 'ripgrep' : 'git';
+        const args = manager === 'brew' ? ['install', packageName] : ['install', '-y', packageName];
+        const env = { ...environment(options), ...(manager === 'brew' ? { HOMEBREW_NO_AUTO_UPDATE: '1', HOMEBREW_NO_INSTALL_CLEANUP: '1' } : manager === 'apt' ? { DEBIAN_FRONTEND: 'noninteractive' } : {}) };
+        const result = await run(command, args, { ...options, env }, INSTALL_TIMEOUT_MS);
+        const verification = result.status === 'ready' ? await inspectTool(PROBES.find(probe => probe.id === tool), options) : undefined;
+        const installed = result.status === 'ready' && verification?.status === 'ready';
+        attempts.push({ tool, status: installed ? 'ready' : result.status === 'ready' ? 'failed' : result.status,
+            action: installed ? 'installed' : 'not_installed', command, args,
+            detail: installed ? `${check.label} installation was verified.`
+                : result.status === 'ready' ? `${check.label} installation could not be verified; the tool is still missing or unhealthy. Check PATH and retry /setup.`
+                    : `${failureDetail(`${check.label} installation`, result)} No privilege escalation was attempted; use your system administrator's normal installation process if permissions are required.` });
+    }
+    return { before, attempts, after: tools.length ? await inspectSetupEnvironment(options) : before };
+}

package/dist/onboarding/setup_workspace.d.ts

@@ -0,0 +1,17 @@
+export declare class SetupWorkspaceError extends Error {
+    readonly code: 'unowned' | 'invalid_marker' | 'unsupported_path' | 'invalid_configuration' | 'cancelled' | 'persistence';
+    constructor(message: string, code: 'unowned' | 'invalid_marker' | 'unsupported_path' | 'invalid_configuration' | 'cancelled' | 'persistence');
+}
+export interface SetupWorkspaceOptions {
+    workspaceRoot?: string;
+    provider: string;
+    model: string;
+    signal?: AbortSignal;
+}
+export interface SetupWorkspaceResult {
+    path: string;
+    sessionId: string;
+    created: boolean;
+}
+/** Create only our sample files; reruns preserve the marker, session and edits. */
+export declare function ensureSetupWorkspace(options: SetupWorkspaceOptions): Promise<SetupWorkspaceResult>;

package/dist/onboarding/setup_workspace.js

@@ -0,0 +1,129 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { profileConfigDir } from '../config/profiles.js';
+import { generateSessionId, loadSessionById, saveSession, setSessionName } from '../session.js';
+const MARKER = '.ztc-setup.json';
+const SAMPLE_FILES = {
+    'hello.js': "console.log('Hello from ZTC');\n",
+    'README.md': '# Getting started with ZTC\n\nAsk ZTC to explain hello.js, then make a small change and review the diff.\nYour current project and conversation remain separate from this sample.\n',
+};
+export class SetupWorkspaceError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'SetupWorkspaceError';
+    }
+}
+function requireActive(signal) {
+    if (signal?.aborted)
+        throw new SetupWorkspaceError('Setup was cancelled. Run /setup to try again.', 'cancelled');
+}
+function parseMarker(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new SetupWorkspaceError('The sample workspace marker is unreadable. Preserve this directory and choose a different sample location.', 'invalid_marker');
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new SetupWorkspaceError('The sample workspace marker is invalid. Preserve this directory and choose a different sample location.', 'invalid_marker');
+    }
+    const marker = value;
+    if (marker._schema_version !== 1 || marker.product !== 'ZTC'
+        || typeof marker.sessionId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_-]{1,127}$/.test(marker.sessionId)
+        || typeof marker.provider !== 'string' || !marker.provider.trim()
+        || typeof marker.model !== 'string' || !marker.model.trim()) {
+        throw new SetupWorkspaceError('The sample workspace marker is invalid. Preserve this directory and choose a different sample location.', 'invalid_marker');
+    }
+    return { _schema_version: 1, product: 'ZTC', sessionId: marker.sessionId, provider: marker.provider, model: marker.model };
+}
+async function readMarker(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new SetupWorkspaceError('Setup will not overwrite an existing directory that it does not own. Preserve it and choose another sample location.', 'unowned');
+        }
+        throw new SetupWorkspaceError('The sample workspace marker cannot be opened as a regular file.', 'invalid_marker');
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > 4096)
+            throw new SetupWorkspaceError('The sample workspace marker is invalid or too large.', 'invalid_marker');
+        return parseMarker(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Create only our sample files; reruns preserve the marker, session and edits. */
+export async function ensureSetupWorkspace(options) {
+    requireActive(options.signal);
+    if (!options.provider.trim() || !options.model.trim()) {
+        throw new SetupWorkspaceError('Choose an account and model before creating the sample workspace.', 'invalid_configuration');
+    }
+    const path = resolve(options.workspaceRoot ?? join(profileConfigDir(), 'workspaces', 'getting-started'));
+    const markerPath = join(path, MARKER);
+    let created = false;
+    let marker;
+    try {
+        const parent = dirname(path);
+        await mkdir(parent, { recursive: true });
+        requireActive(options.signal);
+        await mkdir(path);
+        created = true;
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const stat = await lstat(path);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new SetupWorkspaceError('The sample path must be an ordinary directory. Choose another sample location.', 'unsupported_path');
+        }
+    }
+    if (created) {
+        marker = { _schema_version: 1, product: 'ZTC', sessionId: generateSessionId(), provider: options.provider, model: options.model };
+        requireActive(options.signal);
+        // Exclusive publication prevents a rerun from replacing another workspace's identity.
+        const handle = await open(markerPath, 'wx', 0o600);
+        try {
+            await handle.writeFile(JSON.stringify(marker, null, 2) + '\n', 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    else {
+        marker = await readMarker(markerPath);
+    }
+    for (const [name, content] of Object.entries(SAMPLE_FILES)) {
+        requireActive(options.signal);
+        try {
+            await writeFile(join(path, name), content, { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    requireActive(options.signal);
+    const existing = await loadSessionById(marker.sessionId, path);
+    if (!existing) {
+        await saveSession(marker.sessionId, path, [], marker.model, marker.provider);
+        const named = await setSessionName(marker.sessionId, path, 'Getting started with ZTC');
+        if (!named || named.metadata.id !== marker.sessionId) {
+            throw new SetupWorkspaceError('The sample session could not be saved. Check storage permissions and rerun /setup.', 'persistence');
+        }
+    }
+    const saved = await loadSessionById(marker.sessionId, path);
+    if (!saved || saved.metadata.id !== marker.sessionId || saved.metadata.cwd !== path) {
+        throw new SetupWorkspaceError('The sample session could not be verified. Check storage permissions and rerun /setup.', 'persistence');
+    }
+    return { path, sessionId: marker.sessionId, created };
+}

package/dist/optimize/adapters/index.d.ts

@@ -1,7 +1,10 @@
 import type { OptimizationSpec } from '../types.js';
-import type { OptimizationAdapter } from './types.js';
+import type { OptimizationAdapter, OptimizationExecutionResult, OptimizationExecutorDeps } from './types.js';
+import type { OptimizationPlanArtifacts } from '../types.js';
 export declare function list_optimization_adapters(): OptimizationAdapter[];
 export declare function resolve_optimization_adapter(spec: OptimizationSpec): OptimizationAdapter | null;
+/** Canonical result projection for built-in and plugin producers, including legacy or failed output. */
+export declare function evaluate_optimization_adapter(adapter: OptimizationAdapter, spec: OptimizationSpec, deps: OptimizationExecutorDeps, artifacts: OptimizationPlanArtifacts): Promise<OptimizationExecutionResult>;
 export { kernelbenchCandidateOptimizationAdapter, kernelbenchOptimizationAdapter, } from './kernelbench.js';
 export { popcornOptimizationAdapter } from './popcorn.js';
 export { profileBenchmarkOptimizationAdapter } from './profile_benchmark.js';

package/dist/optimize/adapters/index.js

@@ -1,3 +1,4 @@
+import { describeOptimizationResult } from '../measurements.js';
 import { runtimePluginRegistry } from '../../plugin/runtime_registry.js';
 import { kernelbenchCandidateOptimizationAdapter, kernelbenchOptimizationAdapter, } from './kernelbench.js';
 import { popcornOptimizationAdapter } from './popcorn.js';
@@ -26,6 +27,12 @@ export function resolve_optimization_adapter(spec) {
     }
     return null;
 }
+/** Canonical result projection for built-in and plugin producers, including legacy or failed output. */
+export async function evaluate_optimization_adapter(adapter, spec, deps, artifacts) {
+    return describeOptimizationResult(adapter.evaluate
+        ? await adapter.evaluate(spec, deps, artifacts)
+        : await adapter.execute(spec, deps, artifacts));
+}
 export { kernelbenchCandidateOptimizationAdapter, kernelbenchOptimizationAdapter, } from './kernelbench.js';
 export { popcornOptimizationAdapter } from './popcorn.js';
 export { profileBenchmarkOptimizationAdapter } from './profile_benchmark.js';

package/dist/optimize/adapters/kernelbench.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join, resolve } from 'path';
+import { captureAdapterOptimizationMeasurement } from '../measurements.js';
 import { resolve_benchmark_repo_root, run_shell_with_timeout, shell_join, sh_quote } from './runtime.js';
 import { resolve_path_reference, resolve_path_within_cwd } from '../paths.js';
 function request_includes(spec, needle) {
@@ -141,7 +142,8 @@ function load_kernelbench_metrics(spec, stdout) {
         return null;
     }
     try {
-        const payload = JSON.parse(readFileSync(stackReportPath, 'utf-8'));
+        const rawOutput = readFileSync(stackReportPath, 'utf-8');
+        const payload = JSON.parse(rawOutput);
         const rows = payload.layers || [];
         if (rows.length === 0) {
             return null;
@@ -162,6 +164,7 @@ function load_kernelbench_metrics(spec, stdout) {
                 && candidateSpeedup > baselineSpeedup);
         const layerName = typeof finalLayer.layer === 'string' ? finalLayer.layer : 'final';
         return {
+            sourcePath: stackReportPath, rawOutput,
             summary: `KernelBench execution completed. Final layer ${layerName} scored ${candidateScore.toFixed(3)}.`,
             notes: [
                 `KernelBench selected layer: ${layerName}.`,
@@ -370,7 +373,7 @@ async function evaluate_candidate_spec(spec, deps, artifacts) {
     const name = typeof payload.name === 'string' ? payload.name : 'unknown';
     const mode = typeof payload.mode === 'string' ? payload.mode : 'structural';
     const correctness = Boolean(payload.correctness);
-    return {
+    return captureAdapterOptimizationMeasurement({
         ok: shellResult.exitCode === 0 && candidateScore !== undefined,
         status: shellResult.exitCode === 0 && candidateScore !== undefined ? 'completed' : 'failed',
         adapterId: 'kernelbench',
@@ -400,7 +403,10 @@ async function evaluate_candidate_spec(spec, deps, artifacts) {
                 improved: undefined,
             }
             : undefined,
-    };
+    }, stdoutPath, shellResult.stdout || '', !shellResult.truncated, { runId: artifacts.runId, unit: 'score', selection: {
+            repositoryRoot: resolve_benchmark_repo_root(spec.cwd), selector: JSON.stringify(parse_kernelbench_task_selector(spec)),
+            profile: spec.profile, gpuRequested: build_kernelbench_flags(spec).gpu, mode, reportedLevel: level, reportedProblem: problemId,
+        } });
 }
 function build_command(spec, model) {
     const { supportedStages, deferredStages } = executable_stages(spec);
@@ -541,7 +547,7 @@ export const kernelbenchOptimizationAdapter = {
         const loadedMetrics = shellResult.exitCode === 0
             ? load_kernelbench_metrics(spec, shellResult.stdout || '')
             : null;
-        return {
+        return captureAdapterOptimizationMeasurement({
             ok: shellResult.exitCode === 0,
             status: shellResult.exitCode === 0 ? 'completed' : 'failed',
             adapterId: 'kernelbench',
@@ -558,6 +564,9 @@ export const kernelbenchOptimizationAdapter = {
             deferredStages: plan.deferredStages,
             notes: [...plan.notes, ...(loadedMetrics?.notes || [])],
             metrics: loadedMetrics?.metrics,
-        };
+        }, loadedMetrics?.sourcePath || stdoutPath, loadedMetrics?.rawOutput || shellResult.stdout || '', !shellResult.truncated && loadedMetrics !== null && !build_kernelbench_flags(spec).random, { runId: artifacts.runId, unit: 'score', selection: { repositoryRoot: resolve_benchmark_repo_root(spec.cwd),
+                evaluator: spec.evaluator?.ref ?? null, profile: spec.profile, model: deps.model ?? null,
+                flags: JSON.stringify(build_kernelbench_flags(spec)),
+            } });
     },
 };

package/dist/optimize/adapters/popcorn.js

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { captureAdapterOptimizationMeasurement } from '../measurements.js';
 import { resolve_benchmark_repo_root, run_shell_with_timeout, shell_join, sh_quote } from './runtime.js';
 import { resolve_path_reference, resolve_path_within_cwd } from '../paths.js';
 function parse_gpu(spec) {
@@ -252,7 +253,7 @@ async function evaluate_candidate(spec, deps, artifacts) {
     const breakdown = payload.score_breakdown && typeof payload.score_breakdown === 'object'
         ? JSON.stringify(payload.score_breakdown)
         : null;
-    return {
+    return captureAdapterOptimizationMeasurement({
         ok: benchmarkResult.exitCode === 0 && candidateValue !== undefined,
         status: benchmarkResult.exitCode === 0 && candidateValue !== undefined ? 'completed' : 'failed',
         adapterId: 'popcorn',
@@ -280,7 +281,7 @@ async function evaluate_candidate(spec, deps, artifacts) {
                 improved: undefined,
             }
             : undefined,
-    };
+    }, stdoutPath, benchmarkResult.stdout || '', !benchmarkResult.truncated && !testResult.truncated, { runId: artifacts.runId, unit: 'microseconds', selection: { repositoryRoot: repoRoot, leaderboard, gpu, profile: spec.profile } });
 }
 export const popcornOptimizationAdapter = {
     id: 'popcorn',

package/dist/optimize/adapters/profile_benchmark.js

@@ -1,5 +1,6 @@
 import { writeFileSync } from 'fs';
 import { join } from 'path';
+import { captureAdapterOptimizationMeasurement, describeOptimizationResult } from '../measurements.js';
 import { resolve_benchmark_repo_root, run_shell_with_timeout, shell_join, sh_quote } from './runtime.js';
 const SUPPORTED_PROFILE_BENCHMARKS = new Set([
     'ifbench',
@@ -218,13 +219,12 @@ async function evaluate(spec, deps, artifacts) {
     writeFileSync(stdoutPath, result.stdout || '', 'utf-8');
     writeFileSync(stderrPath, result.stderr || '', 'utf-8');
     const parsed = parse_summary(result.stdout || '');
-    const ok = result.exitCode === 0 && parsed !== null;
-    return {
-        ok,
-        status: ok ? 'completed' : 'failed',
+    const execution = captureAdapterOptimizationMeasurement({
+        ok: result.exitCode === 0,
+        status: result.exitCode === 0 ? 'completed' : 'failed',
         adapterId: profileBenchmarkOptimizationAdapter.id,
-        summary: ok
-            ? `${benchmark_name(spec)} completed with ${parsed.passed}/${parsed.total} passing.`
+        summary: parsed
+            ? `${benchmark_name(spec)} completed with ${parsed.passed}/${parsed.total} reported passing.`
             : `${benchmark_name(spec)} benchmark did not produce a parseable successful summary.`,
         command: adapterPlan.command,
         planPath: artifacts.planPath,
@@ -240,7 +240,13 @@ async function evaluate(spec, deps, artifacts) {
             direction: 'maximize',
             candidateValue: parsed.score,
         } : undefined,
-    };
+    }, stdoutPath, result.stdout || '', !result.truncated, { runId: artifacts.runId, unit: 'fraction', selection: {
+            repositoryRoot: repoRoot, benchmark: benchmark_name(spec), selector: benchmark_selector(spec),
+            profile: spec.profile, limit: parse_limit(spec), reportedTotal: parsed?.total ?? null, model: benchmark_model_arg(deps.model) ?? null,
+        } });
+    const ok = result.exitCode === 0 && (parsed !== null || execution.measurementReport?.value !== null && execution.measurementReport?.value !== undefined);
+    return describeOptimizationResult({ ...execution, ok, status: ok ? 'completed' : 'failed',
+        summary: parsed ? execution.summary : ok ? `${benchmark_name(spec)} completed with an explicitly declared reported objective.` : execution.summary });
 }
 export const profileBenchmarkOptimizationAdapter = {
     id: 'profile-benchmark',

package/dist/optimize/adapters/rfbench.js

@@ -1,5 +1,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { basename, dirname, join, resolve } from 'path';
+import { captureAdapterOptimizationMeasurement, assessOptimizationResult } from '../measurements.js';
+import { is_better_result, result_score } from '../results.js';
 import { build_rf_report, } from '../../bench/rf_shared.js';
 import { resolve_path_reference, resolve_path_within_cwd } from '../paths.js';
 function failed_openems_backend_result(candidate, targetSpec, payload) {
@@ -391,6 +393,8 @@ function read_candidate_evaluation_pair(resultRunDir) {
 function load_combine_donors(branchRecords) {
     const donors = [];
     for (const record of branchRecords) {
+        if (record.survivedFamilyPolicy !== true)
+            continue;
         const candidatePath = record.selectedTarget || record.materializedTarget;
         if (!candidatePath || !existsSync(candidatePath)) {
             continue;
@@ -1429,26 +1433,30 @@ async function try_openems_evaluation(projectDir, candidatePath, targetSpecPath,
     };
 }
 function write_backend_status(projectDir, payload) {
+    ensure_bench_artifact_dirs(projectDir);
     const paths = bench_paths(projectDir);
     writeFileSync(paths.backendStatus, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
 }
-function sync_bench_state(projectDir, targetSpec, baselineCandidate, baselineEval, candidate, evaluation, score, note, backend, backendNote, pipeline, baselineScore, runId) {
+function sync_bench_state(projectDir, targetSpec, baselineCandidate, baselineEval, candidate, evaluation, score, note, backend, backendNote, pipeline, baselineScore, runId, execution) {
     ensure_bench_artifact_dirs(projectDir);
     const paths = bench_paths(projectDir);
     const timestamp = new Date().toISOString();
-    let bestScore = -Infinity;
-    if (existsSync(paths.bestCandidate)) {
-        const best = read_json(paths.bestCandidate);
-        bestScore = Number(best.score);
-    }
+    const bestResultPath = join(projectDir, 'artifacts', 'best_optimization_result.json');
+    const bestExists = existsSync(paths.bestCandidate);
+    const previousResult = bestExists && existsSync(bestResultPath) ? read_json(bestResultPath) : null;
+    // Historical best files remain readable; no scalar-only incumbent or new output confers comparison authority.
+    const promoted = result_score(execution) !== null && (bestExists
+        ? previousResult !== null && is_better_result(previousResult, execution)
+        : is_better_result(null, execution));
+    const measurementReport = assessOptimizationResult(execution);
     writeFileSync(paths.currentCandidate, `${JSON.stringify(candidate, null, 2)}\n`, 'utf-8');
     writeFileSync(paths.currentEval, `${JSON.stringify(evaluation, null, 2)}\n`, 'utf-8');
     writeFileSync(paths.baselineCandidate, `${JSON.stringify(baselineCandidate, null, 2)}\n`, 'utf-8');
     writeFileSync(paths.baselineEval, `${JSON.stringify(baselineEval, null, 2)}\n`, 'utf-8');
-    const promoted = score >= bestScore;
     if (promoted) {
         writeFileSync(paths.bestCandidate, `${JSON.stringify(candidate, null, 2)}\n`, 'utf-8');
         writeFileSync(paths.bestEval, `${JSON.stringify(evaluation, null, 2)}\n`, 'utf-8');
+        writeFileSync(bestResultPath, `${JSON.stringify(execution, null, 2)}\n`, 'utf-8');
     }
     const previousState = existsSync(paths.sessionState)
         ? read_json(paths.sessionState)
@@ -1460,9 +1468,10 @@ function sync_bench_state(projectDir, targetSpec, baselineCandidate, baselineEva
         generation: nextGeneration,
         evaluations: previousEvaluations + 1,
         population_size: Number(previousState.population_size) || 24,
-        elite_id: promoted ? candidate.id : String(previousState.elite_id || candidate.id),
-        best_score: promoted ? score : Number(previousState.best_score) || score,
-        phase: promoted ? 'elite_update' : 'candidate_evaluation',
+        elite_id: promoted ? candidate.id : String(previousState.elite_id || ''),
+        best_score: promoted ? measurementReport.value : Number(previousState.best_score) || 0,
+        measurementReport,
+        phase: promoted ? 'reported_elite_update' : 'candidate_evaluation',
         strategy: note,
         checkpoint_path: `artifacts/checkpoints/g${String(nextGeneration).padStart(3, '0')}_checkpoint.json`,
         current_job: `evaluate:${candidate.id}`,
@@ -1475,7 +1484,7 @@ function sync_bench_state(projectDir, targetSpec, baselineCandidate, baselineEva
         generation: nextGeneration,
         candidate: candidate.id,
         score,
-        outcome: promoted ? 'promoted' : 'accepted',
+        outcome: promoted ? 'reported_comparable_selection' : 'recorded_unqualified',
         note,
         timestamp,
     })}\n`, 'utf-8');
@@ -1710,7 +1719,6 @@ async function evaluate_candidate_spec(spec, deps, artifacts) {
     });
     const pipeline = spec.pipeline.map((stage) => stage.engine).join(' -> ');
     const note = finalCandidate.mutation_summary || `evaluated ${finalCandidate.topology}`;
-    sync_bench_state(projectDir, targetSpec, finalBaselineCandidate, finalBaselineEvaluation, finalCandidateWithScore, finalEvaluation, finalScored.score, [note, strategyAdjusted.note, diversityAdjusted.note].filter(Boolean).join('; '), finalBackend, backendAttempt.note, pipeline, finalBaselineScore, artifacts.runId);
     writeFileSync(join(artifacts.runDir, 'candidate_normalized.json'), `${JSON.stringify(finalCandidateWithScore, null, 2)}\n`, 'utf-8');
     writeFileSync(join(artifacts.runDir, 'evaluation.json'), `${JSON.stringify(finalEvaluation, null, 2)}\n`, 'utf-8');
     writeFileSync(join(artifacts.runDir, 'baseline_evaluation.json'), `${JSON.stringify(finalBaselineEvaluation, null, 2)}\n`, 'utf-8');
@@ -1747,9 +1755,12 @@ async function evaluate_candidate_spec(spec, deps, artifacts) {
             improved: finalScored.score > finalBaselineScore,
         },
     };
-    writeFileSync(join(artifacts.runDir, 'execution_result.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf-8');
+    const capturedResult = captureAdapterOptimizationMeasurement(result, join(artifacts.runDir, 'evaluation.json'), `${JSON.stringify(finalEvaluation, null, 2)}\n`, true, { runId: artifacts.runId, unit: 'score', selection: { projectDir, benchName, backend: finalBackend,
+            targetSpec: JSON.stringify(targetSpec), baselineScore: finalBaselineScore, profile: spec.profile } });
+    sync_bench_state(projectDir, targetSpec, finalBaselineCandidate, finalBaselineEvaluation, finalCandidateWithScore, finalEvaluation, finalScored.score, [note, strategyAdjusted.note, diversityAdjusted.note].filter(Boolean).join('; '), finalBackend, backendAttempt.note, pipeline, finalBaselineScore, artifacts.runId, capturedResult);
+    writeFileSync(join(artifacts.runDir, 'execution_result.json'), `${JSON.stringify(capturedResult, null, 2)}\n`, 'utf-8');
     deps.onProgress?.(`RF bench: ${finalCandidateWithScore.id} completed with candidate_value=${finalScored.score.toFixed(4)} baseline_value=${finalBaselineScore.toFixed(4)} improved=${finalScored.score > finalBaselineScore}.`);
-    return result;
+    return capturedResult;
 }
 export const rfbenchOptimizationAdapter = {
     id: 'rfbench',