@principles/core 1.73.0

package/dist/runtime-v2/types/runtime-summary-types.d.ts

@@ -0,0 +1,93 @@
+import { type Static } from '@sinclair/typebox';
+/**
+ * Runtime truth represents the current state of the system.
+ * Used for control decisions, Phase 3 eligibility, and real-time operations.
+ * Sources: queue state, active session registry
+ */
+export interface RuntimeTruth {
+    queueState: {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+        lastUpdated: string;
+    };
+    activeSessions: string[];
+}
+export declare const RuntimeTruthSchema: import("@sinclair/typebox").TObject<{
+    queueState: import("@sinclair/typebox").TObject<{
+        total: import("@sinclair/typebox").TNumber;
+        pending: import("@sinclair/typebox").TNumber;
+        inProgress: import("@sinclair/typebox").TNumber;
+        completed: import("@sinclair/typebox").TNumber;
+        lastUpdated: import("@sinclair/typebox").TString;
+    }>;
+    activeSessions: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+}>;
+export type RuntimeTruthStatic = Static<typeof RuntimeTruthSchema>;
+/**
+ * Trend metrics for analytics aggregation.
+ */
+export interface TrendMetrics {
+    successRateChange: number;
+    toolCallVolumeChange: number;
+    painSignalRateChange: number;
+}
+export declare const TrendMetricsSchema: import("@sinclair/typebox").TObject<{
+    successRateChange: import("@sinclair/typebox").TNumber;
+    toolCallVolumeChange: import("@sinclair/typebox").TNumber;
+    painSignalRateChange: import("@sinclair/typebox").TNumber;
+}>;
+export type TrendMetricsStatic = Static<typeof TrendMetricsSchema>;
+/**
+ * Analytics truth represents historical data and aggregated metrics.
+ * Used for insights, trends, and supporting evidence (where explicitly allowed).
+ * NOT used for control decisions or Phase 3 eligibility.
+ * Sources: trajectory.db, daily-stats.json, control-ui DB
+ */
+export interface AnalyticsTruth {
+    trajectoryData: {
+        totalTasks: number;
+        successRate: number;
+        timeoutRate: number;
+        lastUpdated: string;
+    };
+    dailyStats: {
+        toolCalls: number;
+        painSignals: number;
+        evolutionTasks: number;
+        lastUpdated: string;
+    };
+    trends: {
+        sevenDay: TrendMetrics;
+        thirtyDay: TrendMetrics;
+    };
+}
+export declare const AnalyticsTruthSchema: import("@sinclair/typebox").TObject<{
+    trajectoryData: import("@sinclair/typebox").TObject<{
+        totalTasks: import("@sinclair/typebox").TNumber;
+        successRate: import("@sinclair/typebox").TNumber;
+        timeoutRate: import("@sinclair/typebox").TNumber;
+        lastUpdated: import("@sinclair/typebox").TString;
+    }>;
+    dailyStats: import("@sinclair/typebox").TObject<{
+        toolCalls: import("@sinclair/typebox").TNumber;
+        painSignals: import("@sinclair/typebox").TNumber;
+        evolutionTasks: import("@sinclair/typebox").TNumber;
+        lastUpdated: import("@sinclair/typebox").TString;
+    }>;
+    trends: import("@sinclair/typebox").TObject<{
+        sevenDay: import("@sinclair/typebox").TObject<{
+            successRateChange: import("@sinclair/typebox").TNumber;
+            toolCallVolumeChange: import("@sinclair/typebox").TNumber;
+            painSignalRateChange: import("@sinclair/typebox").TNumber;
+        }>;
+        thirtyDay: import("@sinclair/typebox").TObject<{
+            successRateChange: import("@sinclair/typebox").TNumber;
+            toolCallVolumeChange: import("@sinclair/typebox").TNumber;
+            painSignalRateChange: import("@sinclair/typebox").TNumber;
+        }>;
+    }>;
+}>;
+export type AnalyticsTruthStatic = Static<typeof AnalyticsTruthSchema>;
+//# sourceMappingURL=runtime-summary-types.d.ts.map

package/dist/runtime-v2/types/runtime-summary-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-summary-types.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/types/runtime-summary-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;EAS7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,kBAAkB;;;;EAI7B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,EAAE;QACN,QAAQ,EAAE,YAAY,CAAC;QACvB,SAAS,EAAE,YAAY,CAAC;KACzB,CAAC;CACH;AAED,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;EAiB/B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC"}

package/dist/runtime-v2/types/runtime-summary-types.js

@@ -0,0 +1,35 @@
+import { Type } from '@sinclair/typebox';
+export const RuntimeTruthSchema = Type.Object({
+    queueState: Type.Object({
+        total: Type.Number(),
+        pending: Type.Number(),
+        inProgress: Type.Number(),
+        completed: Type.Number(),
+        lastUpdated: Type.String(),
+    }),
+    activeSessions: Type.Array(Type.String()),
+});
+export const TrendMetricsSchema = Type.Object({
+    successRateChange: Type.Number(),
+    toolCallVolumeChange: Type.Number(),
+    painSignalRateChange: Type.Number(),
+});
+export const AnalyticsTruthSchema = Type.Object({
+    trajectoryData: Type.Object({
+        totalTasks: Type.Number(),
+        successRate: Type.Number(),
+        timeoutRate: Type.Number(),
+        lastUpdated: Type.String(),
+    }),
+    dailyStats: Type.Object({
+        toolCalls: Type.Number(),
+        painSignals: Type.Number(),
+        evolutionTasks: Type.Number(),
+        lastUpdated: Type.String(),
+    }),
+    trends: Type.Object({
+        sevenDay: TrendMetricsSchema,
+        thirtyDay: TrendMetricsSchema,
+    }),
+});
+//# sourceMappingURL=runtime-summary-types.js.map

package/dist/runtime-v2/types/runtime-summary-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-summary-types.js","sourceRoot":"","sources":["../../../src/runtime-v2/types/runtime-summary-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAkBtD,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5C,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;QACtB,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;QACpB,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE;QACtB,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE;QACzB,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;QACxB,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;KAC3B,CAAC;IACF,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;CAC1C,CAAC,CAAC;AAYH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5C,iBAAiB,EAAE,IAAI,CAAC,MAAM,EAAE;IAChC,oBAAoB,EAAE,IAAI,CAAC,MAAM,EAAE;IACnC,oBAAoB,EAAE,IAAI,CAAC,MAAM,EAAE;CACpC,CAAC,CAAC;AA4BH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,MAAM,CAAC;IAC9C,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC;QAC1B,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE;QACzB,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;QAC1B,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;QAC1B,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;KAC3B,CAAC;IACF,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;QACtB,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;QACxB,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;QAC1B,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE;QAC7B,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;KAC3B,CAAC;IACF,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC;QAClB,QAAQ,EAAE,kBAAkB;QAC5B,SAAS,EAAE,kBAAkB;KAC9B,CAAC;CACH,CAAC,CAAC"}

package/dist/runtime-v2/utils/cli-process-runner.d.ts

@@ -0,0 +1,35 @@
+export interface CliProcessRunnerOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    killGracePeriodMs?: number;
+}
+export type SpawnErrorCode = 'ENOENT' | 'EACCES' | 'EMFILE' | 'UNKNOWN';
+export interface CliOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    /**
+     * Explicit spawn error type. Set when proc.on('error') is called with
+     * ENOENT (binary not found), EACCES (permission denied), EMFILE (too many open files),
+     * or other errors. Use this instead of parsing stderr for error detection.
+     */
+    spawnError?: SpawnErrorCode;
+}
+/**
+ * Run a CLI process with timeout, graceful tree kill, and env merge.
+ *
+ * @param opts.command - Non-empty path to the binary to run (validated)
+ * @param opts.args - Array of string arguments (no shell injection, shell: false)
+ * @param opts.cwd - Working directory for the child process
+ * @param opts.env - Environment variables (merged with parent process.env)
+ * @param opts.timeoutMs - Optional timeout in ms; if exceeded the process tree is killed
+ * @param opts.killGracePeriodMs - Grace period between SIGTERM and SIGKILL (default 3000ms)
+ * @returns CliOutput with captured stdout, stderr, exitCode, timedOut flag, and durationMs
+ */
+export declare function runCliProcess(opts: CliProcessRunnerOptions): Promise<CliOutput>;
+//# sourceMappingURL=cli-process-runner.d.ts.map

package/dist/runtime-v2/utils/cli-process-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-runner.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/utils/cli-process-runner.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAgFD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,CAkLrF"}

package/dist/runtime-v2/utils/cli-process-runner.js

@@ -0,0 +1,259 @@
+/**
+ * CliProcessRunner — generic child process runner with timeout, graceful tree kill,
+ * env merge, and no shell injection.
+ *
+ * Purpose: Foundation utility consumed by OpenClawCliRuntimeAdapter (m6-02).
+ * Runs arbitrary CLI commands, captures stdout/stderr, and handles timeouts with
+ * graceful tree kill (SIGTERM → grace period → SIGKILL).
+ */
+import { spawn, execSync } from 'child_process';
+/**
+ * Resolve a command on Windows when it may be a npm shim (.cmd/.bat/.exe).
+ *
+ * On Windows, `spawn('openclaw', [], {shell:false})` fails with ENOENT because
+ * Node's spawn() with shell:false does not consult the PATHEXT associations that
+ * cmd.exe uses. `where.exe` (equivalent to `which` on Unix) resolves the actual
+ * executable path including .cmd/.bat shims created by npm.
+ *
+ * When running under Git Bash (MSYS), `where.exe` returns Unix-style paths
+ * (e.g. /c/Users/.../openclaw) which spawn() cannot use. This function converts
+ * them to Windows paths and prefers Windows-native executables (.cmd, .bat, .exe).
+ *
+ * @returns The resolved command path, or the original if not Windows or already absolute.
+ */
+function resolveCommandForWindows(command) {
+    if (process.platform !== 'win32') {
+        return command;
+    }
+    // If the command already contains a path separator, it is already resolved
+    if (command.includes('/') || command.includes('\\')) {
+        return command;
+    }
+    try {
+        // Use where.exe to resolve the command — works for .cmd, .bat, .exe shims
+        const result = execSync(`where.exe ${command}`, {
+            encoding: 'utf-8',
+            timeout: 5000,
+            windowsHide: true,
+        });
+        // where.exe returns all matches, one per line
+        const lines = result.split('\n').map((l) => l.trim()).filter(Boolean);
+        // Prefer Windows-native executables (.cmd, .bat, .exe) over Unix scripts.
+        // If a .cmd/.bat file is found, return it directly — avoids the broken
+        // anaconda MSYS cygpath bug where shell scripts get wrong path resolution.
+        const windowsNative = lines.find((l) => /\.(cmd|bat|exe)$/i.test(l));
+        if (windowsNative) {
+            // Convert MSYS Unix-style .cmd paths (e.g. /c/Users/.../openclaw.cmd)
+            // to proper Windows absolute paths before returning.
+            const normalized = windowsNative.replace(/\\/g, '/');
+            if (/^\/[a-z]\//i.test(normalized)) {
+                const msysPath = normalized;
+                const driveLetter = msysPath[1] ?? 'C';
+                const winPath = driveLetter.toUpperCase() + ':' + msysPath.slice(2).replace(/\//g, '\\');
+                return winPath;
+            }
+            return windowsNative;
+        }
+        // No Windows-native result found. The first line may be a Unix-style path
+        // (e.g. /c/Users/.../openclaw) returned by Git Bash's where.exe.
+        // Convert it to a Windows absolute path so spawn() can use it.
+        if (lines.length > 0) {
+            const firstResult = lines[0] ?? command;
+            // Convert MSYS/Git Bash Unix-style path to Windows path
+            // /c/Users/... → C:\Users\...
+            // /d/Program Files/... → D:\Program Files\...
+            if (/^[A-Z]:/i.test(firstResult)) {
+                // Already a Windows absolute path (e.g. C:\Users\...)
+                return firstResult;
+            }
+            if (/^\/[a-z]\//i.test(firstResult)) {
+                // MSYS Unix-style path: /c/Users/... → C:\Users\...
+                const msysPath = /** @type {string} */ (firstResult);
+                const driveLetter = msysPath[1] ?? 'C';
+                const winPath = driveLetter.toUpperCase() + ':' + msysPath.slice(2).replace(/\//g, '\\');
+                return winPath;
+            }
+            return firstResult;
+        }
+    }
+    catch {
+        // where.exe failed — fall through to original command
+    }
+    return command;
+}
+/**
+ * Run a CLI process with timeout, graceful tree kill, and env merge.
+ *
+ * @param opts.command - Non-empty path to the binary to run (validated)
+ * @param opts.args - Array of string arguments (no shell injection, shell: false)
+ * @param opts.cwd - Working directory for the child process
+ * @param opts.env - Environment variables (merged with parent process.env)
+ * @param opts.timeoutMs - Optional timeout in ms; if exceeded the process tree is killed
+ * @param opts.killGracePeriodMs - Grace period between SIGTERM and SIGKILL (default 3000ms)
+ * @returns CliOutput with captured stdout, stderr, exitCode, timedOut flag, and durationMs
+ */
+export async function runCliProcess(opts) {
+    // ── Input validation ──────────────────────────────────────────────────────
+    if (typeof opts.command !== 'string' || opts.command.trim() === '') {
+        throw new TypeError('opts.command must be a non-empty string');
+    }
+    const { command } = opts;
+    const rawArgs = opts.args ?? [];
+    if (!Array.isArray(rawArgs) || rawArgs.some((a) => typeof a !== 'string')) {
+        throw new TypeError('opts.args must be an array of strings');
+    }
+    const args = rawArgs;
+    const { cwd } = opts;
+    const { timeoutMs } = opts;
+    const killGracePeriodMs = opts.killGracePeriodMs ?? 3000;
+    // ── Env merge ─────────────────────────────────────────────────────────────
+    const env = Object.assign({}, process.env, opts.env ?? {});
+    // ── Output capture ────────────────────────────────────────────────────────
+    let stdout = '';
+    let stderr = '';
+    // ── Resolve command on Windows (npm shim resolution) ─────────────────────
+    const resolved = resolveCommandForWindows(command);
+    // ── Windows: detect if resolved command is a .cmd/.bat shim ─────────────
+    const isWindowsCmdShim = process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved);
+    // ── Spawn configuration ──────────────────────────────────────────────────
+    const spawnConfig = (() => {
+        if (process.platform !== 'win32') {
+            return { command: resolved, args, shell: false };
+        }
+        if (isWindowsCmdShim) {
+            // Windows batch files (.cmd/.bat): use spawn with shell:false and array args.
+            // Use forward slashes (/ instead of \) — cmd.exe accepts both but MSYS bash
+            // does NOT do path conversion on forward slashes, avoiding the anaconda
+            // cygpath bug that corrupts /c/ → D:\ProgramData\anaconda3\Library\c\.
+            const forwardPath = resolved.replace(/\\/g, '/');
+            return { command: 'cmd.exe', args: ['/c', forwardPath, ...args], shell: false };
+        }
+        // Non-batch Windows executables can be spawned directly. Keeping shell=false
+        // preserves argv boundaries and keeps ENOENT handling deterministic.
+        return { command: resolved, args, shell: false };
+    })();
+    // ── Spawn ─────────────────────────────────────────────────────────────────
+    const proc = spawn(spawnConfig.command, spawnConfig.args, {
+        cwd,
+        env,
+        shell: spawnConfig.shell,
+    });
+    // Attach data handlers BEFORE spawning so we don't miss any output
+    proc.stdout?.on('data', (chunk) => {
+        stdout += chunk.toString();
+    });
+    proc.stderr?.on('data', (chunk) => {
+        stderr += chunk.toString();
+    });
+    const startedAt = Date.now();
+    // ── Timeout handling ──────────────────────────────────────────────────────
+    let timeoutHandle = null;
+    let killGraceHandle = null;
+    // Flag set when timeout fires; consulted in close/error handlers to set timedOut correctly
+    let timedOut = false;
+    function killProcessTree() {
+        const { pid } = proc;
+        if (pid === null || pid === undefined)
+            return;
+        if (process.platform === 'win32') {
+            // Windows: use taskkill with /T (kill process tree) and /F (force)
+            // taskkill /F is SIGKILL equivalent — force kill without grace period
+            const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F']);
+            killer.on('error', () => {
+                // Process may have already exited — taskkill itself failed
+            });
+        }
+        else {
+            // Unix: send SIGTERM to the process group (negative pid = whole group)
+            try {
+                process.kill(-pid, 'SIGTERM');
+            }
+            catch {
+                // Process may have already exited
+            }
+        }
+    }
+    function cancelTimers() {
+        if (timeoutHandle !== null) {
+            clearTimeout(timeoutHandle);
+            timeoutHandle = null;
+        }
+        if (killGraceHandle !== null) {
+            clearTimeout(killGraceHandle);
+            killGraceHandle = null;
+        }
+    }
+    if (timeoutMs != null) {
+        timeoutHandle = setTimeout(() => {
+            // Mark timedOut=true FIRST so close/error handlers know the process was killed by timeout
+            timedOut = true;
+            // First, attempt graceful termination
+            killProcessTree();
+            // Then schedule SIGKILL after grace period (only on non-Windows)
+            if (process.platform !== 'win32') {
+                const { pid } = proc;
+                killGraceHandle = setTimeout(() => {
+                    if (pid != null) {
+                        try {
+                            process.kill(-pid, 'SIGKILL');
+                        }
+                        catch {
+                            // Already exited
+                        }
+                    }
+                }, killGracePeriodMs);
+            }
+        }, timeoutMs);
+    }
+    // ── Completion promise ─────────────────────────────────────────────────────
+    return new Promise((resolve) => {
+        let settled = false;
+        function resolveOnce(output) {
+            if (!settled) {
+                settled = true;
+                cancelTimers();
+                resolve(output);
+            }
+        }
+        proc.on('close', (code) => {
+            const durationMs = Date.now() - startedAt;
+            resolveOnce({
+                stdout,
+                stderr,
+                // When killed by timeout, exitCode is non-null (OS-level kill exit code).
+                // Normal exit uses the actual code; timeout kills set exitCode=null per CliOutput contract.
+                exitCode: timedOut ? null : code,
+                timedOut,
+                durationMs,
+            });
+        });
+        proc.on('error', (err) => {
+            // ENOENT, EACCES, EMFILE, etc. — resolve with null exit code and empty output
+            // so callers can handle "command not found" gracefully
+            const durationMs = Date.now() - startedAt;
+            const errWithCode = err;
+            let spawnError = undefined;
+            if (errWithCode.code === 'ENOENT') {
+                spawnError = 'ENOENT';
+            }
+            else if (errWithCode.code === 'EACCES') {
+                spawnError = 'EACCES';
+            }
+            else if (errWithCode.code === 'EMFILE') {
+                spawnError = 'EMFILE';
+            }
+            else if (errWithCode.code) {
+                spawnError = 'UNKNOWN';
+            }
+            resolveOnce({
+                stdout: '',
+                stderr: errWithCode.code ? `ENOENT: ${errWithCode.code}` : err.message,
+                exitCode: null,
+                timedOut,
+                durationMs,
+                spawnError,
+            });
+        });
+    });
+}
+//# sourceMappingURL=cli-process-runner.js.map

package/dist/runtime-v2/utils/cli-process-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-runner.js","sourceRoot":"","sources":["../../../src/runtime-v2/utils/cli-process-runner.ts"],"names":[],"mappings":"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"}

package/dist/runtime-v2/utils/cli-process-runner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-process-runner.test.d.ts.map

package/dist/runtime-v2/utils/cli-process-runner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-runner.test.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/utils/cli-process-runner.test.ts"],"names":[],"mappings":""}

package/dist/runtime-v2/utils/cli-process-runner.test.js

@@ -0,0 +1,111 @@
+/**
+ * CliProcessRunner unit tests.
+ *
+ * Covers: success (exit 0), non-zero exit, timeout, and ENOENT cases.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { runCliProcess } from './cli-process-runner.js';
+describe('runCliProcess', () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('success case (exit code 0)', () => {
+        it('resolves with stdout, exitCode 0, timedOut false, durationMs >= 0', async () => {
+            const result = await runCliProcess({
+                command: 'node',
+                args: ['-e', 'console.log("hello")'],
+            });
+            expect(result.stdout).toBe('hello\n');
+            expect(result.exitCode).toBe(0);
+            expect(result.timedOut).toBe(false);
+            expect(result.durationMs).toBeGreaterThanOrEqual(0);
+        });
+    });
+    describe('non-zero exit case', () => {
+        it('captures non-zero exit code in result', async () => {
+            const result = await runCliProcess({
+                command: 'node',
+                args: ['-e', 'process.exit(42)'],
+            });
+            expect(result.exitCode).toBe(42);
+            expect(result.timedOut).toBe(false);
+        });
+    });
+    describe('timeout case', () => {
+        it('sets timedOut=true and exitCode=null when process is killed on timeout', async () => {
+            const runPromise = runCliProcess({
+                command: 'node',
+                args: ['-e', 'setTimeout(() => {}, 10000)'],
+                timeoutMs: 100,
+                killGracePeriodMs: 50,
+            });
+            // Advance time past the timeout threshold
+            await vi.advanceTimersByTimeAsync(200);
+            const result = await runPromise;
+            expect(result.timedOut).toBe(true);
+            // exitCode is null because the process was killed, not exited normally
+            expect(result.exitCode).toBeNull();
+        });
+    });
+    describe('ENOENT case (binary not found)', () => {
+        it('resolves with exitCode null and empty stdout when command does not exist', async () => {
+            const result = await runCliProcess({
+                command: 'nonexistent-binary-xyz123',
+            });
+            expect(result.exitCode).toBeNull();
+            expect(result.stdout).toBe('');
+        });
+    });
+    describe.skip('Windows command resolution', () => {
+        it('on Windows, resolves openclaw to openclaw.cmd via where.exe', async () => {
+            if (process.platform !== 'win32') {
+                return;
+            }
+            const result = await runCliProcess({
+                command: 'openclaw',
+                args: ['--version'],
+            });
+            // Should succeed (not ENOENT) if Windows resolution works
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toContain('OpenClaw');
+        });
+        it('on Windows, spawn uses resolved command path', async () => {
+            if (process.platform !== 'win32') {
+                return;
+            }
+            const result = await runCliProcess({
+                command: 'node',
+                args: ['--version'],
+            });
+            expect(result.exitCode).toBe(0);
+        });
+        it('on non-Windows, command is passed through unchanged', async () => {
+            if (process.platform === 'win32') {
+                return;
+            }
+            // On Unix, 'node' should work directly without where.exe resolution
+            const result = await runCliProcess({
+                command: 'node',
+                args: ['--version'],
+            });
+            expect(result.exitCode).toBe(0);
+            expect(result.stdout).toContain('v');
+        });
+    });
+    describe('validation', () => {
+        it('throws TypeError when command is an empty string', async () => {
+            await expect(runCliProcess({ command: '' })).rejects.toThrow(TypeError);
+        });
+        it('throws TypeError when command is whitespace-only', async () => {
+            await expect(runCliProcess({ command: '   ' })).rejects.toThrow(TypeError);
+        });
+        it('throws TypeError when command is not a string', async () => {
+            // @ts-expect-error — intentionally passing invalid type to test runtime validation
+            await expect(runCliProcess({ command: 123 })).rejects.toThrow(TypeError);
+        });
+    });
+});
+//# sourceMappingURL=cli-process-runner.test.js.map

package/dist/runtime-v2/utils/cli-process-runner.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-process-runner.test.js","sourceRoot":"","sources":["../../../src/runtime-v2/utils/cli-process-runner.test.ts"],"names":[],"mappings":"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"}

package/dist/storage-adapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * StorageAdapter interface for the Evolution SDK.
+ *
+ * This interface decouples the evolution engine from specific persistence
+ * implementations (file system, SQLite, remote API). All higher-level
+ * modules that need to read or mutate the principle ledger should depend
+ * on this interface rather than importing principle-tree-ledger directly.
+ *
+ * The interface uses HybridLedgerStore from types.ts as the
+ * canonical store shape, but future adapters can map alternative backends
+ * to this shape.
+ */
+import type { HybridLedgerStore } from './types.js';
+/**
+ * Abstract storage adapter for the principle ledger.
+ *
+ * Implementations must guarantee:
+ * - Atomic writes (no partial/corrupted state on crash)
+ * - Thread-safe concurrent access (locking or equivalent)
+ * - Consistent read-after-write visibility
+ *
+ * The `mutateLedger` method is the preferred way to perform read-modify-write
+ * cycles. It encapsulates locking so callers never need to manage it.
+ */
+export interface StorageAdapter {
+    /**
+     * Load the current ledger state from persistence.
+     *
+     * If no persisted state exists (first run), returns an empty store.
+     */
+    loadLedger(): Promise<HybridLedgerStore>;
+    /**
+     * Persist the full ledger state.
+     *
+     * Must be atomic -- partial writes must never be visible to readers.
+     */
+    saveLedger(store: HybridLedgerStore): Promise<void>;
+    /**
+     * Perform a read-modify-write cycle with automatic locking.
+     *
+     * The `mutate` function receives the current store and may return a
+     * value synchronously or via Promise. The store is persisted after
+     * the mutate function resolves, regardless of its return value.
+     *
+     * If two concurrent `mutateLedger` calls overlap, one must wait for
+     * the other to complete (pessimistic locking) or retry on conflict
+     * (optimistic locking). The choice is left to the implementation.
+     *
+     * @example
+     * ```ts
+     * const count = await adapter.mutateLedger((store) => {
+     *   store.tree.principles['p-1'] = newPrinciple;
+     *   return Object.keys(store.tree.principles).length;
+     * });
+     * ```
+     */
+    mutateLedger<T>(mutate: (store: HybridLedgerStore) => T | Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=storage-adapter.d.ts.map

package/dist/storage-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-adapter.d.ts","sourceRoot":"","sources":["../src/storage-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAMpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACnF"}

package/dist/storage-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage-adapter.js.map

package/dist/storage-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-adapter.js","sourceRoot":"","sources":["../src/storage-adapter.ts"],"names":[],"mappings":""}