verikun 0.4.1 → 0.7.0

package/dist/run.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Recorder = void 0;
 exports.isRecordable = isRecordable;
+exports.runId = runId;
+exports.uniqueDir = uniqueDir;
 exports.rolloverReason = rolloverReason;
 exports.stepName = stepName;
 const node_fs_1 = require("node:fs");
@@ -54,11 +56,13 @@ function saveState(dir, state) {
 function nowIso() {
     return new Date().toISOString();
 }
+/** Timestamp id used for runs — exported so `vk suite` mints suite ids the same way. */
 function runId() {
     const d = new Date();
     const p = (n) => String(n).padStart(2, '0');
     return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}-${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
 }
+/** First non-existing `<base>`, `<base>-2`, `<base>-3`, … — exported for `vk suite`. */
 function uniqueDir(base) {
     if (!(0, node_fs_1.existsSync)(base))
         return base;
@@ -155,11 +159,17 @@ class Recorder {
     dir;
     step;
     startMs;
-    constructor(state, dir, step, startMs) {
+    sink;
+    constructor(state, dir, step, startMs, 
+    /** Ephemeral mode (vk server): artifacts land here instead of on disk, and
+     *  commit() never touches ./.verikun — the step is returned to the caller
+     *  via takeEphemeral() and spliced into the CALLER's run instead. */
+    sink) {
         this.state = state;
         this.dir = dir;
         this.step = step;
         this.startMs = startMs;
+        this.sink = sink;
     }
     /**
      * Open a step for a recordable command, auto-starting an implicit run if none
@@ -234,6 +244,43 @@ class Recorder {
         };
         return new Recorder(state, dir, step, Date.now());
     }
+    /**
+     * Open a single-step recorder that never touches disk — the `vk server` path.
+     * The step (and any artifacts, e.g. failure screenshots) accumulate in memory
+     * and are handed back by takeEphemeral() for the wire; the CALLING verikun
+     * splices them into its own on-disk run via appendForeignStep. Deliberately
+     * ignores VERIKUN_NO_RUN: this is how step detail reaches the remote caller,
+     * not a local test run.
+     */
+    static beginEphemeralStep(command, positionals, flags, platform, serial) {
+        const state = {
+            id: 'ephemeral',
+            name: 'ephemeral',
+            startedAt: nowIso(),
+            updatedAt: nowIso(),
+            platform,
+            device: serial,
+            implicit: true,
+            steps: [],
+        };
+        const step = {
+            index: 0,
+            command,
+            name: stepName(command, positionals, flags),
+            startedAt: nowIso(),
+            durationMs: 0,
+            status: 'passed',
+            exitCode: 0,
+        };
+        // No dir: ephemeral recording never touches disk (activeDir() would mkdir
+        // ./.verikun as a side effect), and writeArtifact/commit divert to the sink.
+        return new Recorder(state, '', step, Date.now(), {});
+    }
+    /** The finished ephemeral step + its in-memory artifacts. Only meaningful after
+     *  finish()/finishError() on a beginEphemeralStep recorder. */
+    takeEphemeral() {
+        return { step: this.step, artifacts: this.sink ?? {} };
+    }
     /** Attach selector / heal-tier / resolved-element / message detail to the current step. */
     note(info) {
         const s = this.step;
@@ -319,11 +366,17 @@ class Recorder {
         }
     }
     writeArtifact(rel, buf) {
+        if (this.sink) {
+            this.sink[rel] = buf;
+            return;
+        }
         (0, node_fs_1.mkdirSync)((0, node_path_1.join)(this.dir, 'artifacts'), { recursive: true });
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(this.dir, rel), buf);
     }
     commit() {
         this.step.durationMs = Date.now() - this.startMs;
+        if (this.sink)
+            return; // ephemeral: the step goes to the wire, not to disk
         this.state.steps.push(this.step);
         this.state.updatedAt = nowIso();
         saveState(this.dir, this.state);
@@ -364,6 +417,53 @@ class Recorder {
         Object.assign(state, patch);
         saveState(dir, state);
     }
+    /**
+     * Splice a step another verikun produced (a `vk server`'s ephemeral step) into
+     * the ACTIVE local run, so a remote `vk ai` run archives a report identical to
+     * a local one. Re-indexes the step, writes its artifact buffers under the new
+     * index, and rewrites the step's artifact references to match. Creates an
+     * implicit run first if none is active (parity with beginStep's auto-start).
+     */
+    static appendForeignStep(step, artifacts = {}, ctx = {}) {
+        if (process.env.VERIKUN_NO_RUN)
+            return;
+        const dir = activeDir();
+        let state = loadState(dir);
+        if (!state) {
+            state = {
+                id: runId(),
+                name: 'run',
+                startedAt: nowIso(),
+                updatedAt: nowIso(),
+                platform: ctx.platform ?? 'android',
+                device: ctx.device,
+                session: currentSession(),
+                implicit: true,
+                steps: [],
+            };
+            (0, output_1.err)('[verikun] recording test run (implicit) — archive: `vk run archive` · discard: `vk run clear`');
+        }
+        const index = state.steps.length;
+        const spliced = { ...step, index };
+        for (const [rel, buf] of Object.entries(artifacts)) {
+            // The rel path comes from the (authenticated) server's response; still, never
+            // let it steer the write outside the run's artifacts/ directory.
+            if (!/^artifacts\/[A-Za-z0-9._-]+$/.test(rel)) {
+                (0, output_1.err)(`[verikun] skipping remote artifact with unexpected path '${rel}'`);
+                continue;
+            }
+            const newRel = rel.replace(/\bstep-\d+-/, `step-${index}-`);
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, 'artifacts'), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, newRel), buf);
+            if (spliced.image === rel)
+                spliced.image = newRel;
+            if (spliced.failImage === rel)
+                spliced.failImage = newRel;
+        }
+        state.steps.push(spliced);
+        state.updatedAt = nowIso();
+        saveState(dir, state);
+    }
     /** Downgrade the most-recently-recorded step from a failed attempt to a healed
      *  pass — the `vk ai` engine calls this after a successful repair so a
      *  self-healed leaf does not count as a failure (and the run that the engine

package/dist/server.js

@@ -0,0 +1,349 @@
+"use strict";
+// `vk server` — expose THIS machine's connected device to remote verikun clients
+// (`vk ai/suite/install --server <url>`) over HTTP+JSON, Node's built-in http only.
+//
+// Security model (the server is the trust boundary, not the transport):
+//  - Mandatory bearer auth: a key is REQUIRED unless --allow-unsafe-anonymous is
+//    passed explicitly (for networks that are themselves the boundary, e.g. a
+//    private tailnet). If none is configured, one is generated and printed loudly.
+//    Comparison is crypto.timingSafeEqual over fixed-width sha256 digests.
+//  - /v1/exec accepts ONLY verikun's validated action grammar: every request runs
+//    through the SAME validateNode gate that guards `vk ai` model repairs, so only
+//    KNOWN_COMMANDS action verbs execute — never `ui`/`log`, never a shell. The
+//    server's driver is fixed at startup; client flags can never repoint the device.
+//  - /v1/install is a privileged management verb: auth PLUS --allow-install, body
+//    streamed to a server-generated temp path (the client supplies only an
+//    allowlisted extension — never a path), optional sha256 verification.
+//  - Binds 127.0.0.1 unless --bind opts into exposure. One run-token holds the
+//    device lock at a time (409 otherwise; an idle lock is taken over so a crashed
+//    caller can't wedge the box). Device endpoints are serialized via a mutex.
+//
+// cli.ts reaches this module via a DYNAMIC import (no static cli↔server cycle, and
+// node:http stays off the default CLI load path); this module imports cli.ts's
+// executeForServer statically — a one-way runtime edge.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildServer = buildServer;
+exports.cmdServer = cmdServer;
+const node_http_1 = require("node:http");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_stream_1 = require("node:stream");
+const promises_1 = require("node:stream/promises");
+const args_1 = require("./args");
+const errors_1 = require("./errors");
+const drivers_1 = require("./drivers");
+const output_1 = require("./output");
+const ir_1 = require("./agent/ir");
+const rpc_1 = require("./rpc");
+const cli_1 = require("./cli");
+const version_1 = require("./version");
+const DEFAULT_PORT = 8391;
+const EXEC_BODY_CAP = 1024 * 1024; // 1 MB of JSON is far beyond any leaf command
+const INSTALL_BODY_CAP = 512 * 1024 * 1024; // 512 MB app build
+// A silent run-token older than this may be taken over by a new one — long enough
+// to survive a client-side compile/repair pause, short enough that a crashed
+// caller doesn't wedge the device.
+const LOCK_IDLE_MS = 5 * 60 * 1000;
+/** An error that already knows its HTTP status + the client-side exit code. */
+class HttpError extends Error {
+    status;
+    exitCode;
+    constructor(status, message, exitCode = status === 400 || status === 404 || status === 413 ? 2 : 3) {
+        super(message);
+        this.status = status;
+        this.exitCode = exitCode;
+        this.name = 'HttpError';
+    }
+}
+function sendJson(res, status, payload) {
+    const body = JSON.stringify(payload);
+    res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+    res.end(body);
+}
+function readBody(req, cap) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > cap) {
+                reject(new HttpError(413, `request body exceeds ${cap} bytes`));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks)));
+        req.on('error', reject);
+    });
+}
+/** Wire flags → FlagSpec[] for validateNode. Primitives are coerced to strings
+ *  (a boolean flag travels as "true"); anything structured is rejected. */
+function flagsToSpecs(flags) {
+    if (flags === undefined || flags === null)
+        return [];
+    if (typeof flags !== 'object' || Array.isArray(flags))
+        throw new HttpError(400, 'flags must be an object');
+    return Object.entries(flags).map(([name, value]) => {
+        if (typeof value === 'string')
+            return { name, value };
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return { name, value: String(value) };
+        throw new HttpError(400, `flag '${name}' must be a string`);
+    });
+}
+function encodeArtifacts(artifacts) {
+    const out = {};
+    for (const [rel, buf] of Object.entries(artifacts))
+        out[rel] = buf.toString('base64');
+    return out;
+}
+function buildServer(config) {
+    const sha = (s) => (0, node_crypto_1.createHash)('sha256').update(s, 'utf8').digest();
+    const authorized = (req) => {
+        if (!config.authKey)
+            return true; // --allow-unsafe-anonymous
+        const m = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? '');
+        if (!m)
+            return false;
+        // Fixed-width digests make the comparison length-safe as well as timing-safe.
+        return (0, node_crypto_1.timingSafeEqual)(sha(m[1]), sha(config.authKey));
+    };
+    // One active run-token owns the device; see LOCK_IDLE_MS for takeover.
+    let lock = null;
+    const acquireLock = (token) => {
+        const now = Date.now();
+        if (lock && lock.token !== token) {
+            if (now - lock.lastSeenMs < LOCK_IDLE_MS)
+                return false;
+            (0, output_1.err)(`[server] device lock: idle run ${lock.token.slice(0, 8)}… taken over by ${token.slice(0, 8)}…`);
+        }
+        lock = { token, lastSeenMs: now };
+        return true;
+    };
+    // The device can serve one interaction at a time — serialize the device endpoints
+    // through a promise chain (requests queue in arrival order).
+    let queue = Promise.resolve();
+    const serialize = (fn) => {
+        const next = queue.then(fn, fn);
+        queue = next.catch(() => undefined);
+        return next;
+    };
+    async function handleExec(req, res) {
+        const body = await readBody(req, EXEC_BODY_CAP);
+        let parsed;
+        try {
+            parsed = JSON.parse(body.toString('utf8'));
+        }
+        catch {
+            throw new HttpError(400, 'invalid JSON body');
+        }
+        // The exact gate that guards model repairs: only KNOWN_COMMANDS action verbs
+        // pass — a client cannot run `ui`, `log`, or anything outside the grammar.
+        let node;
+        try {
+            node = (0, ir_1.validateNode)({ type: 'command', command: parsed?.command, positionals: parsed?.positionals, flags: flagsToSpecs(parsed?.flags) }, 'rpc');
+        }
+        catch (e) {
+            if (e instanceof ir_1.InvalidPlanError)
+                throw new HttpError(400, `rejected: ${e.message}`);
+            throw e;
+        }
+        if (node.type !== 'command')
+            throw new HttpError(400, 'rejected: not a command leaf');
+        const t0 = Date.now();
+        const { code, error, step, artifacts } = await (0, cli_1.executeForServer)(node.command, node.positionals, (0, ir_1.leafToFlags)(node), config.driver, config.platform);
+        (0, output_1.err)(`[server] exec ${node.command} ${node.positionals.join(' ')} → exit ${code} (${Date.now() - t0}ms)`);
+        const payload = {
+            code,
+            ...(error ? { error: (0, rpc_1.describeError)(error) } : {}),
+            ...(step ? { step } : {}),
+            ...(artifacts && Object.keys(artifacts).length ? { artifacts: encodeArtifacts(artifacts) } : {}),
+        };
+        sendJson(res, 200, payload);
+    }
+    async function handleElements(req, res) {
+        await readBody(req, EXEC_BODY_CAP); // drain (the body is unused; keeps keep-alive sane)
+        const elements = config.driver.getElements(); // CliError(3) on dump failure → 500 below
+        sendJson(res, 200, { elements });
+    }
+    async function handleInstall(req, res) {
+        const ext = String(req.headers['x-verikun-ext'] ?? '').toLowerCase();
+        if (ext !== 'apk' && ext !== 'ipa') {
+            throw new HttpError(400, `x-verikun-ext must be 'apk' or 'ipa' (got '${ext || '(missing)'}')`);
+        }
+        // The temp path is server-generated — the client never supplies a path, so
+        // there is no traversal surface. Streamed (backpressured), never buffered.
+        const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), 'verikun-server');
+        (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+        const tmpPath = (0, node_path_1.join)(dir, `${(0, node_crypto_1.randomUUID)()}.${ext}`);
+        const hasher = (0, node_crypto_1.createHash)('sha256');
+        let size = 0;
+        const counter = new node_stream_1.Transform({
+            transform(chunk, _enc, cb) {
+                size += chunk.length;
+                if (size > INSTALL_BODY_CAP) {
+                    cb(new HttpError(413, `install body exceeds ${INSTALL_BODY_CAP} bytes`));
+                    return;
+                }
+                hasher.update(chunk);
+                cb(null, chunk);
+            },
+        });
+        try {
+            await (0, promises_1.pipeline)(req, counter, (0, node_fs_1.createWriteStream)(tmpPath));
+            const digest = hasher.digest('hex');
+            const expected = String(req.headers['x-verikun-sha256'] ?? '').toLowerCase();
+            if (expected && expected !== digest) {
+                throw new HttpError(400, `sha256 mismatch: upload arrived corrupted (got ${digest.slice(0, 12)}…, expected ${expected.slice(0, 12)}…)`);
+            }
+            (0, output_1.err)(`[server] install: received ${size} bytes (.${ext}), installing…`);
+            config.driver.install(tmpPath);
+            (0, output_1.err)('[server] install: done');
+            sendJson(res, 200, { ok: true, bytes: size, sha256: digest });
+        }
+        finally {
+            try {
+                (0, node_fs_1.unlinkSync)(tmpPath);
+            }
+            catch {
+                /* upload may have failed before the file existed */
+            }
+        }
+    }
+    async function handle(req, res) {
+        const path = (req.url ?? '').split('?')[0];
+        if (req.method === 'GET' && path === '/v1/health') {
+            // Unauthenticated preflight — but if the caller DID send a key, verify it, so
+            // a client with a wrong key fails fast at ping instead of at its first step.
+            if (config.authKey && req.headers.authorization && !authorized(req)) {
+                throw new HttpError(401, 'invalid auth key');
+            }
+            const health = {
+                ok: true,
+                version: version_1.VERSION,
+                platform: config.platform,
+                serial: config.serial,
+                installEnabled: config.allowInstall,
+            };
+            sendJson(res, 200, health);
+            return;
+        }
+        if (!authorized(req))
+            throw new HttpError(401, 'missing or invalid auth key');
+        const token = String(req.headers['x-verikun-run'] ?? '(anonymous)');
+        const deviceEndpoint = (fn) => serialize(async () => {
+            if (!acquireLock(token)) {
+                throw new HttpError(409, 'device is locked by another active run — retry when it finishes');
+            }
+            await fn();
+        });
+        if (req.method === 'POST' && path === '/v1/release') {
+            // A finished client frees its lock so the NEXT command (a fresh run token)
+            // proceeds immediately instead of waiting out the idle takeover. Serialized
+            // so it lands after any in-flight request; only the holder can release.
+            return serialize(async () => {
+                await readBody(req, EXEC_BODY_CAP); // drain
+                const released = lock !== null && lock.token === token;
+                if (released)
+                    lock = null;
+                sendJson(res, 200, { ok: true, released });
+            });
+        }
+        if (req.method === 'POST' && path === '/v1/exec')
+            return deviceEndpoint(() => handleExec(req, res));
+        if (req.method === 'POST' && path === '/v1/elements')
+            return deviceEndpoint(() => handleElements(req, res));
+        if (req.method === 'POST' && path === '/v1/install') {
+            if (!config.allowInstall) {
+                throw new HttpError(403, 'install is disabled on this server (start it with --allow-install)', 3);
+            }
+            return deviceEndpoint(() => handleInstall(req, res));
+        }
+        throw new HttpError(404, `unknown endpoint ${req.method} ${path}`);
+    }
+    const server = (0, node_http_1.createServer)((req, res) => {
+        const started = Date.now();
+        handle(req, res)
+            .catch((e) => {
+            const mapped = e instanceof HttpError
+                ? e
+                : e instanceof errors_1.CliError
+                    ? new HttpError(e.exitCode === 2 ? 400 : 500, e.message, e.exitCode)
+                    : new HttpError(500, e.message || 'internal error', 3);
+            if (!res.headersSent) {
+                const body = { error: mapped.message, exitCode: mapped.exitCode };
+                sendJson(res, mapped.status, body);
+            }
+            else {
+                res.destroy();
+            }
+        })
+            .finally(() => {
+            (0, output_1.err)(`[server] ${req.method} ${(req.url ?? '').split('?')[0]} → ${res.statusCode} (${Date.now() - started}ms)`);
+        });
+    });
+    // A 512 MB upload over a slow link can legitimately exceed Node's 5-minute
+    // default request window.
+    server.requestTimeout = 30 * 60 * 1000;
+    return server;
+}
+async function cmdServer(positionals, flags) {
+    if (positionals.length > 0) {
+        throw new errors_1.CliError(`server: unexpected argument '${positionals[0]}'. Usage: verikun server [--bind addr] [--port n] [--auth-key k] [--allow-install] [--allow-unsafe-anonymous]`, 2);
+    }
+    const platform = (0, cli_1.platformFromFlags)(flags);
+    const device = (0, cli_1.deviceFromFlags)(flags, platform);
+    const bind = (0, args_1.flagStr)(flags, 'bind') || '127.0.0.1';
+    const port = (0, args_1.flagNum)(flags, 'port') ?? DEFAULT_PORT;
+    const allowInstall = (0, args_1.flagBool)(flags, 'allow-install');
+    const anonymous = (0, args_1.flagBool)(flags, 'allow-unsafe-anonymous');
+    // The env var is the documented channel for the key (keeps it out of argv/ps).
+    let authKey = (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined;
+    if (anonymous && authKey) {
+        throw new errors_1.CliError('--allow-unsafe-anonymous cannot be combined with an auth key (--auth-key / VERIKUN_SERVER_AUTH_KEY) — pick one.', 2);
+    }
+    let generated = false;
+    if (!anonymous && !authKey) {
+        authKey = (0, node_crypto_1.randomBytes)(32).toString('base64url');
+        generated = true;
+    }
+    // Build the ONE driver the server will ever use, and fail fast (exit 2/3) if no
+    // device resolves — before binding a port.
+    const driver = (0, drivers_1.getDriver)(platform, device);
+    const serial = driver.resolvedSerial();
+    // Handlers print "tapped …" confirmations via out(); a server's stdout is not a
+    // data channel, so silence them — request logging goes to stderr instead.
+    (0, output_1.setOutputQuiet)(true);
+    const server = buildServer({ driver, platform, serial, authKey, allowInstall });
+    return new Promise((resolve, reject) => {
+        server.on('error', (e) => reject(new errors_1.CliError(`server: could not listen on ${bind}:${port} (${e.message})`, 3)));
+        server.listen(port, bind, () => {
+            (0, output_1.err)(`[server] verikun ${version_1.VERSION} listening on http://${bind}:${port}`);
+            (0, output_1.err)(`[server] device: ${platform} · ${serial}`);
+            (0, output_1.err)(`[server] install endpoint: ${allowInstall ? 'ENABLED (--allow-install)' : 'disabled (pass --allow-install to accept builds)'}`);
+            if (generated) {
+                (0, output_1.err)('[server] auth key generated for this session — clients pass it via VERIKUN_SERVER_AUTH_KEY or --auth-key:');
+                (0, output_1.err)(`[server]     ${authKey}`);
+            }
+            else if (anonymous) {
+                (0, output_1.err)('[server] WARNING: --allow-unsafe-anonymous — NO AUTHENTICATION. Anyone who can reach this');
+                (0, output_1.err)('[server]          address fully controls the connected device. Only use when the network');
+                (0, output_1.err)('[server]          itself is the boundary (e.g. a private tailnet), never on a shared LAN.');
+            }
+            else {
+                (0, output_1.err)('[server] auth: key configured');
+            }
+            (0, output_1.err)('[server] stop with Ctrl-C');
+        });
+        const close = () => {
+            (0, output_1.err)('[server] shutting down');
+            server.close();
+            resolve(0);
+        };
+        process.once('SIGINT', close);
+        process.once('SIGTERM', close);
+    });
+}

package/dist/suite.js

@@ -0,0 +1,152 @@
+"use strict";
+// `vk suite <dir>` — run a directory of natural-language tests sequentially as one
+// suite: reset the app between tests, collect each test's result, and write a suite
+// overview (index.json manifest + index.html) that links every test's archived
+// report. Exits 1 when any test failed, so the command doubles as the CI gate.
+//
+// Dependency-injected like agent/engine.ts: this module imports NOTHING from cli.ts
+// — the actual test execution (`runTest`, which is cli.ts's runAiTest bound to a
+// local-or-remote backend) and the between-test reset come in via SuiteDeps. That
+// keeps the enumeration/tally/manifest logic pure enough to unit-test without a
+// device, and cli.ts free of a suite→cli import cycle.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortTestFiles = sortTestFiles;
+exports.listTestFiles = listTestFiles;
+exports.toSuiteResult = toSuiteResult;
+exports.cmdSuite = cmdSuite;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const args_1 = require("./args");
+const errors_1 = require("./errors");
+const output_1 = require("./output");
+const run_1 = require("./run");
+const report_1 = require("./report");
+const version_1 = require("./version");
+/** Lexicographic order, so authors sequence flows with 01-…, 02-… prefixes. */
+function sortTestFiles(files) {
+    return [...files].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** The *.md files in a suite dir (non-recursive). README.md is documentation for
+ *  the suite, not a test — skipped by convention. */
+function listTestFiles(dir) {
+    const files = (0, node_fs_1.readdirSync)(dir).filter((f) => {
+        if (!f.toLowerCase().endsWith('.md') || f.toLowerCase() === 'readme.md')
+            return false;
+        try {
+            return (0, node_fs_1.statSync)((0, node_path_1.join)(dir, f)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+    return sortTestFiles(files);
+}
+/** Fold one test's AiRunResult into the manifest row (pure; unit-tested). */
+function toSuiteResult(file, r, durationMs) {
+    const steps = r.state?.steps ?? [];
+    const passedSteps = steps.filter((s) => s.status === 'passed').length;
+    const failure = r.failure
+        ? `FAIL at ${r.failure.where}: ${r.failure.reason}`
+        : r.abortedForBudget
+            ? 'aborted: cost ceiling reached'
+            : r.abortedForTimeout
+                ? 'aborted: run timeout reached'
+                : undefined;
+    return {
+        id: r.runDir ? (0, node_path_1.basename)(r.runDir) : '',
+        file,
+        name: (0, node_path_1.basename)(file, (0, node_path_1.extname)(file)),
+        ok: r.ok,
+        durationMs,
+        costUsd: r.costUsd,
+        steps: steps.length,
+        passedSteps,
+        failedSteps: steps.length - passedSteps,
+        modelRepairs: r.modelRepairs,
+        ...(r.ok ? {} : { failure: failure ?? 'failed' }),
+    };
+}
+async function cmdSuite(dirArg, flags, deps) {
+    const dir = (0, node_path_1.resolve)(process.cwd(), dirArg);
+    if (!(0, node_fs_1.existsSync)(dir) || !(0, node_fs_1.statSync)(dir).isDirectory()) {
+        throw new errors_1.CliError(`suite: '${dirArg}' is not a directory`, 2);
+    }
+    const files = listTestFiles(dir);
+    if (files.length === 0) {
+        throw new errors_1.CliError(`suite: no test files (*.md) in '${dirArg}'`, 2);
+    }
+    const suiteId = (0, run_1.runId)();
+    const name = (0, args_1.flagStr)(flags, 'name') || (0, node_path_1.basename)(dir);
+    const startedAt = new Date().toISOString();
+    (0, output_1.err)(`[suite] '${name}': ${files.length} test(s) from ${dirArg} (${deps.platform}${deps.device ? ` · ${deps.device}` : ''})`);
+    const results = [];
+    for (let i = 0; i < files.length; i++) {
+        const file = files[i];
+        (0, output_1.err)(`[suite] ── (${i + 1}/${files.length}) ${file} ──`);
+        if (deps.reset) {
+            try {
+                await deps.reset();
+                (0, output_1.err)('[suite] app state reset');
+            }
+            catch (e) {
+                // Surface but continue: a flaky reset should not zero out the whole suite —
+                // the test itself will fail loudly if the stale state actually matters.
+                (0, output_1.err)(`[suite] reset failed (${e.message}) — continuing`);
+            }
+        }
+        const t0 = Date.now();
+        try {
+            const r = await deps.runTest((0, node_path_1.join)(dir, file));
+            results.push(toSuiteResult(file, r, Date.now() - t0));
+        }
+        catch (e) {
+            // A test that THREW (env error: device gone, server unreachable, bad file)
+            // still becomes a failed row — one broken test must not vaporize the suite
+            // report for the tests that already ran.
+            const msg = e instanceof Error ? e.message : String(e);
+            (0, output_1.err)(`[suite] ${file} errored: ${msg}`);
+            results.push({
+                id: '',
+                file,
+                name: (0, node_path_1.basename)(file, (0, node_path_1.extname)(file)),
+                ok: false,
+                durationMs: Date.now() - t0,
+                costUsd: 0,
+                steps: 0,
+                passedSteps: 0,
+                failedSteps: 0,
+                modelRepairs: 0,
+                failure: msg.split('\n')[0],
+            });
+        }
+    }
+    const suite = {
+        schemaVersion: 1,
+        id: suiteId,
+        name,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        platform: deps.platform,
+        device: deps.device,
+        verikun: version_1.VERSION,
+        totals: (0, report_1.suiteTotals)(results),
+        tests: results,
+    };
+    // .verikun/suites/<id>/ sits beside .verikun/runs/<id>/, so index.html reaches a
+    // test report at ../../runs/<id>/report.html — the linkBase below.
+    const outDir = (0, run_1.uniqueDir)((0, node_path_1.join)((0, output_1.artifactDir)(), 'suites', suiteId));
+    (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'index.json'), (0, report_1.toSuiteIndexJson)(suite));
+    (0, node_fs_1.writeFileSync)((0, node_path_1.join)(outDir, 'index.html'), (0, report_1.toSuiteHtml)(suite, { linkBase: '../../' }));
+    const t = suite.totals;
+    (0, output_1.err)(`[suite] ${t.passed}/${t.tests} passed · ${t.steps} steps · $${t.costUsd.toFixed(4)} · ${(t.durationMs / 1000).toFixed(1)}s`);
+    for (const r of results)
+        (0, output_1.err)(`  ${r.ok ? 'PASS' : 'FAIL'} ${r.file}${r.failure ? ` — ${r.failure}` : ''}`);
+    (0, output_1.err)(`[suite] overview: ${(0, node_path_1.join)(outDir, 'index.html')}`);
+    if ((0, args_1.flagBool)(flags, 'json'))
+        (0, output_1.json)(suite);
+    else
+        (0, output_1.out)(outDir); // primary machine result: the suite directory
+    // The CI gate: any failed test fails the invocation (mirrors `vk run archive`).
+    return t.failed > 0 ? 1 : 0;
+}