verikun 0.17.0 → 0.18.1

package/README.md

@@ -122,7 +122,7 @@ vk screenshot                   # -> ./.verikun/screen.png
 |---|---|
 | `run start [name] [--force]` | Begin a named run. One auto-starts on the first action if you don't. |
 | `run status` | Show the active run and its recorded steps. |
-| `run archive [name]` | Write JUnit + HTML report to `./.verikun/runs/<id>/`; exits non-zero if any step failed. |
+| `run archive [name] [--no-logs]` | Write JUnit + HTML report to `./.verikun/runs/<id>/`; exits non-zero if any step failed. Captures `artifacts/logcat.txt` by default. |
 | `run clear` | Discard the active run without a report. |
 
 ## Test runs & reports
@@ -130,10 +130,11 @@ vk screenshot                   # -> ./.verikun/screen.png
 Actions are recorded into a **test run** — one auto-starts on the first action
 (set `VERIKUN_NO_RUN=1` to disable). Every command becomes a step with its
 timing, the selector + identifier it resolved through, and pass/fail; a failing
-step also captures a screenshot **and** the UI hierarchy of the page. When a
-step fails you can additionally run `vk log <package>` to pull the device logs —
-that step records the logs **into the same run**, so the crash trace shows up in
-the report alongside the failure.
+step also captures a screenshot **and** the UI hierarchy of the page. Device
+logs are captured automatically at archive time into `artifacts/logcat.txt`
+(session-scoped when possible). You can still run `vk log <package>` mid-run to
+pull a snapshot into a step for the report; `--no-logs` / `VERIKUN_NO_LOGS`
+skips the archive dump on green runs (failures still capture).
 
 `vk run archive` finalizes the run into `./.verikun/runs/<id>/`:
 
@@ -141,10 +142,19 @@ the report alongside the failure.
   for failed assertions, `<error>` for environment errors, and the resolved
   identifier in `<system-out>`. Drops straight into CI.
 - **`report.html`** — a self-contained report: every step, the identifiers used,
-  any screenshots taken, the screenshot + hierarchy of any failed page, and any
-  device logs captured via `vk log`.
+  any screenshots taken, the screenshot + hierarchy of any failed page, a link to
+  the full device log, an app-scoped log accordion when the run launched an app,
+  and any per-step logs from `vk log`. A run that did not pass says so in a banner
+  at the top.
+- **`artifacts/logcat.txt`** — full device log for the run window (default).
+- **`artifacts/logcat-app.txt`** — app-scoped log (when a package/bundle was launched).
 - **`run.json`** — the raw recording.
 
+A `vk ai` run can also fail where no single command did — a `repeat` that never
+sees its target, a cost/timeout abort. That verdict is recorded too (as
+`run.json`'s `failure`, plus a failed step carrying the reason and a screenshot),
+so a failed test is never reported as `failures="0"` in the JUnit that CI reads.
+
 `vk run archive` exits non-zero when the run contained failures, so the same
 command both produces the report and gates CI.
 

package/dist/agent/remote.js

@@ -112,7 +112,7 @@ function createRemoteBackend(opts, health) {
     const execRaw = async (req, record) => {
         const res = await t.postJson('/v1/exec', req, EXEC_TIMEOUT_MS);
         if (record && res.step)
-            opts.onStep?.(res.step, decodeArtifacts(res.artifacts));
+            opts.onStep?.(res.step, decodeArtifacts(res.artifacts), res.logStart);
         return { code: res.code, error: res.error ? (0, rpc_1.rebuildError)(res.error) : undefined };
     };
     return {
@@ -121,6 +121,10 @@ function createRemoteBackend(opts, health) {
             const res = await t.postJson('/v1/elements', {}, ELEMENTS_TIMEOUT_MS);
             return res.elements;
         },
+        async getLogs(logOpts = {}) {
+            const res = await t.postJson('/v1/logs', logOpts, ELEMENTS_TIMEOUT_MS);
+            return res.logs ?? '';
+        },
         async install(appPath) {
             // v1 remote installs are single-file uploads; the extension is the only thing
             // the client tells the server about the artifact (never a path).

package/dist/args.js

@@ -42,6 +42,7 @@ const BOOLEAN = new Set([
     'recompile',
     'no-cache',
     'no-restart',
+    'no-logs',
     'allow-install',
     'allow-unsafe-anonymous',
     // Selector state modifiers (STATE_ATTRS in ui/selector.ts) and their negations.

package/dist/cli.js

@@ -50,6 +50,7 @@ exports.chooseLogOpts = chooseLogOpts;
 exports.evalAssert = evalAssert;
 exports.tokenizeLine = tokenizeLine;
 exports.withBatchGlobals = withBatchGlobals;
+exports.terminalFailure = terminalFailure;
 exports.executeForServer = executeForServer;
 exports.run = run;
 const node_fs_1 = require("node:fs");
@@ -975,16 +976,47 @@ function cmdRun(positionals, flags, platform, device) {
         case 'archive':
         case 'finish':
         case 'save': {
-            const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive(positionals[1]);
+            const noLogs = (0, args_1.flagBool)(flags, 'no-logs');
+            // Best-effort: archive-time log capture needs a device. Prefer the run's
+            // bound serial/platform so a multi-device host hits the right one. A
+            // missing/broken toolchain must not prevent sealing the report.
+            let fetchLogs;
+            const active = run_1.Recorder.status();
+            const hasFailures = !!active?.steps.some((s) => s.status !== 'passed');
+            if ((0, run_1.wantsArchiveLogs)(hasFailures, noLogs)) {
+                try {
+                    const plat = active?.platform === 'ios' || active?.platform === 'android'
+                        ? active.platform
+                        : platform;
+                    const driver = (0, drivers_1.getDriver)(plat, active?.device || device);
+                    fetchLogs = (opts) => driver.getLogs(opts);
+                }
+                catch (e) {
+                    (0, output_1.err)(`[verikun] archive log capture unavailable (${e.message})`);
+                }
+            }
+            const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive(positionals[1], { noLogs, fetchLogs });
             const { passed, failed } = tally(state.steps);
             if (asJson) {
-                (0, output_1.json)({ archived: dir, report: htmlPath, junit: xmlPath, steps: state.steps.length, passed, failed });
+                (0, output_1.json)({
+                    archived: dir,
+                    report: htmlPath,
+                    junit: xmlPath,
+                    steps: state.steps.length,
+                    passed,
+                    failed,
+                    ...(state.logFile ? { logFile: state.logFile } : {}),
+                });
             }
             else {
                 (0, output_1.out)(dir); // primary result: the archived run directory
                 (0, output_1.err)(`archived '${state.name}': ${state.steps.length} step(s), ${passed} passed, ${failed} failed/error`);
                 (0, output_1.err)(`  JUnit: ${xmlPath}`);
                 (0, output_1.err)(`  HTML:  ${htmlPath}`);
+                if (state.logFile)
+                    (0, output_1.err)(`  Logs:  ${(0, node_path_1.join)(dir, state.logFile)}`);
+                if (state.appLogFile)
+                    (0, output_1.err)(`  App:   ${(0, node_path_1.join)(dir, state.appLogFile)}`);
             }
             // Exit non-zero when the run contained failures, so CI can gate on it.
             return failed > 0 ? 1 : 0;
@@ -1280,6 +1312,7 @@ async function resolveBackend(platform, device, flags) {
             backend: {
                 exec: (command, positionals, f) => executeOutcome(command, positionals, f, driver),
                 getElements: () => driver.getElements(),
+                getLogs: (opts) => driver.getLogs(opts),
                 install: (appPath) => driver.install(appPath),
                 reset: (appId) => {
                     assertSafeAppId(appId);
@@ -1290,6 +1323,24 @@ async function resolveBackend(platform, device, flags) {
                         driver.clearApp(appId);
                 },
                 preflight: () => driver.preflight(),
+                captureFailure: async () => {
+                    // Two independent tries: a screencap can succeed where a dump doesn't (and
+                    // vice versa), and neither is allowed to derail recording the failure.
+                    const out = {};
+                    try {
+                        out.png = driver.screenshot();
+                    }
+                    catch {
+                        /* device may be gone — that may be why we failed */
+                    }
+                    try {
+                        out.hierarchy = driver.getElements({ all: false });
+                    }
+                    catch {
+                        /* ditto */
+                    }
+                    return out;
+                },
             },
             platform,
             device,
@@ -1300,8 +1351,9 @@ async function resolveBackend(platform, device, flags) {
         url: server,
         authKey: (0, args_1.flagStr)(flags, 'auth-key') || process.env.VERIKUN_SERVER_AUTH_KEY || undefined,
         // Each remote step is spliced into the local active run so the archived report
-        // is identical to a local run's.
-        onStep: (step, artifacts) => run_1.Recorder.appendForeignStep(step, artifacts, runCtx),
+        // is identical to a local run's. logStart travels from the server's device clock
+        // so archive-time / vk log scoping works without a local driver.
+        onStep: (step, artifacts, logStart) => run_1.Recorder.appendForeignStep(step, artifacts, { ...runCtx, logStart }),
     };
     const health = await (0, remote_1.pingServer)(opts); // fails fast (exit 3) on a bad URL or key
     runCtx = { platform: health.platform, device: health.serial };
@@ -1319,12 +1371,91 @@ async function resolveBackend(platform, device, flags) {
                 await (0, remote_1.pingServer)(opts);
                 await remote.getElements();
             },
+            // Hierarchy only: the server exposes no screenshot route, so a remote run's
+            // engine failure archives without a picture. Honest degrade over a protocol
+            // change here — tracked in #48.
+            captureFailure: async () => {
+                try {
+                    return { hierarchy: await remote.getElements() };
+                }
+                catch {
+                    return {};
+                }
+            },
         },
         platform: health.platform,
         device: health.serial,
         remote: { url: server, version: health.version },
     };
 }
+/**
+ * The one terminal-failure record for a non-ok engine result — `null` when the run
+ * passed. Exported for the unit suite.
+ *
+ * Budget and timeout aborts come back from the engine as a bare flag with NO `failure`
+ * object, so their reason is composed here; `where` is `run` because the abort is not
+ * attributable to one node. Both the recorded failure and the `[ai] …` status line are
+ * built from this, so the archive and the console cannot disagree about why a run died.
+ */
+function terminalFailure(r, opts) {
+    if (r.ok)
+        return null;
+    if (r.abortedForEnv) {
+        return { where: r.failure?.where ?? 'run', reason: r.failure?.reason ?? 'device unavailable', kind: 'env' };
+    }
+    if (r.abortedForBudget) {
+        return { where: r.failure?.where ?? 'run', reason: `cost ceiling $${opts.maxCostUsd} reached`, kind: 'budget' };
+    }
+    if (r.abortedForTimeout) {
+        return { where: 'run', reason: `run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`, kind: 'timeout' };
+    }
+    return { where: r.failure?.where ?? 'run', reason: r.failure?.reason ?? 'failed', kind: 'fail' };
+}
+/** The `[ai] …` console verdict for a terminal failure, phrased as it always was. */
+function terminalStatusLine(t) {
+    if (t.kind === 'fail')
+        return `FAIL at ${t.where}: ${t.reason}`;
+    return `ABORTED — ${t.kind === 'env' ? `environment: ${t.reason}` : t.reason}`;
+}
+/**
+ * Best-effort archive-time device-log capture via an ExecBackend (local driver or
+ * remote `/v1/logs`). Writes `artifacts/logcat.txt` onto the active run so a later
+ * `Recorder.archive()` finds `logFile` already set. Never throws — a gone device
+ * must not prevent sealing the report.
+ */
+async function prefetchArchiveLogs(backend, noLogs = false) {
+    const state = run_1.Recorder.status();
+    if (!state)
+        return;
+    const hasFailures = state.steps.some((s) => s.status !== 'passed');
+    if (!(0, run_1.wantsArchiveLogs)(hasFailures, noLogs))
+        return;
+    if (!backend.getLogs)
+        return;
+    // Skip only when both artifacts are already attached (e.g. a prior prefetch).
+    if (state.logFile && state.appLogFile)
+        return;
+    const window = (0, run_1.archiveLogWindow)(state);
+    try {
+        const full = state.logFile ? undefined : await backend.getLogs(window);
+        const appId = (0, run_1.inferRunAppId)(state);
+        let app;
+        if (appId && !state.appLogFile) {
+            try {
+                app = await backend.getLogs({ ...window, appId, scopedOnly: true });
+            }
+            catch (e) {
+                (0, output_1.err)(`[verikun] could not capture archive app logs (${e.message})`);
+            }
+        }
+        if (full !== undefined || (app !== undefined && app !== '')) {
+            run_1.Recorder.attachArchiveLogs(full, app);
+        }
+    }
+    catch (e) {
+        (0, output_1.err)(`[verikun] could not capture archive device logs (${e.message})`);
+    }
+}
 /**
  * Run one natural-language test through a backend and return DATA — no stdout
  * writes (stdout stays the caller's one result; progress streams to stderr).
@@ -1365,10 +1496,14 @@ async function runAiTest(file, opts, backend, platform, device) {
     if (existing && existing.steps.length > 0) {
         // Seal the pre-existing run into the archive instead of letting start(force=true)
         // discard it — a manual in-progress run should never be silently lost.
+        await prefetchArchiveLogs(backend);
         const sealed = run_1.Recorder.archive();
         (0, output_1.err)(`[ai] archived the active run ('${existing.name}', ${existing.steps.length} step(s)) → ${sealed.dir}`);
     }
     const started = run_1.Recorder.start(`ai: ${(0, node_path_1.basename)(file)}`, platform, device, true);
+    // Prefer --package when the prose never launches by id (rare but possible).
+    if (opts.pkg)
+        run_1.Recorder.annotateRun({ appId: opts.pkg });
     // Suppress per-step `out()` so stdout stays the one final result; progress -> stderr.
     const prevQuiet = (0, output_1.setOutputQuiet)(true);
     let result;
@@ -1394,7 +1529,15 @@ async function runAiTest(file, opts, backend, platform, device) {
         // seal the run so it is not left dangling in .verikun/run/ for the next command
         // to roll over. Then let the error map to an exit code as usual.
         run_1.Recorder.annotateRun({ ai: { ok: false, cost: cost.summaryLine(), modelRepairs: 0, improvements: [] } });
+        // No evidence capture here: a throw at this level usually IS the device dying, so
+        // the capture would fail the same way and only add noise to the error path.
+        run_1.Recorder.recordTerminalFailure({
+            where: 'run',
+            reason: e.message,
+            kind: (0, errors_1.isEnvError)(e) ? 'env' : 'fail',
+        });
         try {
+            await prefetchArchiveLogs(backend);
             run_1.Recorder.archive();
         }
         catch (sealErr) {
@@ -1419,20 +1562,18 @@ async function runAiTest(file, opts, backend, platform, device) {
             (0, output_1.err)(`[ai] could not cache plan: ${e.message}`);
         }
     }
+    // A failure the engine produced (a control node giving up, a budget/timeout abort)
+    // never ran through a command, so nothing recorded it — without this the archive
+    // declares the failed test green. Must come BEFORE the archive that renders it.
+    const terminal = terminalFailure(result, opts);
+    if (terminal)
+        run_1.Recorder.recordTerminalFailure(terminal, await backend.captureFailure?.());
     run_1.Recorder.annotateRun({
         ai: { ok: result.ok, cost: costLine, modelRepairs: result.modelRepairs, improvements: result.improvements },
     });
+    await prefetchArchiveLogs(backend);
     const { dir, xmlPath, htmlPath, state } = run_1.Recorder.archive();
-    const status = result.ok
-        ? 'PASS'
-        : result.abortedForBudget
-            ? `ABORTED — cost ceiling $${opts.maxCostUsd} reached`
-            : result.abortedForTimeout
-                ? `ABORTED — run timeout (${Math.round(opts.timeoutMs / 1000)}s) reached`
-                : result.abortedForEnv
-                    ? `ABORTED — environment: ${result.failure?.reason}`
-                    : `FAIL at ${result.failure?.where}: ${result.failure?.reason}`;
-    (0, output_1.err)(`[ai] ${status} · ${costLine}`);
+    (0, output_1.err)(`[ai] ${terminal ? terminalStatusLine(terminal) : 'PASS'} · ${costLine}`);
     (0, output_1.err)(`[ai] report: ${htmlPath}`);
     if (result.improvements.length) {
         (0, output_1.err)(`[ai] ${result.improvements.length} suggested improvement(s) (also in the report):`);
@@ -1708,11 +1849,23 @@ async function executeForServer(command, positionals, flags, driver, platform) {
     catch {
         /* surfaced by the command handler below */
     }
+    // Sample the device clock up front so the caller's run can set logStart (the
+    // ephemeral recorder never persists RunState). Best-effort — empty/unavailable
+    // just means archive / vk log fall back to last-N.
+    let logStart;
+    try {
+        const t = driver.deviceTime();
+        if (t)
+            logStart = t;
+    }
+    catch {
+        /* device clock unavailable */
+    }
     const recorder = run_1.Recorder.beginEphemeralStep(command, positionals, flags, platform, serial);
     const ctx = { driver, platform, device: serial, positionals, flags, record: recorder };
     const outcome = await runRecorded(command, ctx, recorder, driver);
     const { step, artifacts } = recorder.takeEphemeral();
-    return { ...outcome, step, artifacts };
+    return { ...outcome, step, artifacts, ...(logStart ? { logStart } : {}) };
 }
 /**
  * Run one already-parsed command for the CLI / `batch`: dispatch meta-commands,
@@ -1884,7 +2037,10 @@ ENVIRONMENT
 TEST RUNS (actions are recorded; a run auto-starts on first action)
   run start [name] [--force]          Begin a named run (else one starts implicitly)
   run status                          Show the active run, its device/session, and steps
-  run archive [name]                  Write JUnit + HTML report, move to ./.verikun/runs/<id>/
+  run archive [name] [--no-logs]      Write JUnit + HTML report, move to ./.verikun/runs/<id>/
+                                      Captures artifacts/logcat.txt by default (session-scoped);
+                                      --no-logs / VERIKUN_NO_LOGS skips on green runs (failures
+                                      still capture). Capture is best-effort and never blocks archive.
   run clear                           Discard the active run with no report
   An implicit run auto-closes (archives) and rolls over on a device change, a
   VERIKUN_SESSION change, or VERIKUN_RUN_IDLE_MIN minutes idle (default 30; 0 off).

package/dist/drivers/adb.js

@@ -356,15 +356,36 @@ class AdbDriver {
             args.push('-t', String(n));
         }
         if (opts.appId) {
-            // Scope to the app's process when it's alive. If pidof is empty the app
-            // isn't running (likely crashed) — fall through to a system-wide dump so
-            // the FATAL EXCEPTION, still in the crash buffer, is not missed.
-            const pid = this.shell(['pidof', opts.appId]).trim().split(/\s+/)[0];
-            if (pid)
-                args.push(`--pid=${pid}`);
+            // Prefer --uid: it survives process death/restart (crash traces stay under the
+            // package's uid). Fall back to --pid for a live process when uid isn't known.
+            // When neither works: vk log falls through to system-wide so a FATAL EXCEPTION
+            // isn't missed; archive accordion passes scopedOnly to keep the dump empty.
+            const uid = this.packageUid(opts.appId);
+            if (uid) {
+                args.push(`--uid=${uid}`);
+            }
+            else {
+                const pid = this.shell(['pidof', opts.appId]).trim().split(/\s+/)[0];
+                if (pid)
+                    args.push(`--pid=${pid}`);
+                else if (opts.scopedOnly)
+                    return '';
+            }
         }
         return this.shell(args, 15000);
     }
+    /** Android userId for an installed package, or '' if unknown. Used to scope
+     *  logcat across process restarts (unlike pidof, which only sees a live process). */
+    packageUid(appId) {
+        try {
+            const out = this.shell(['dumpsys', 'package', appId], 10000);
+            const m = /\buserId=(\d+)\b/.exec(out);
+            return m?.[1] ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
     deviceTime() {
         // logcat's default timestamp is MM-DD HH:MM:SS.mmm in the device's LOCAL time.
         // Sample it from the device clock with a space-free format (so no device-shell

package/dist/drivers/ios.js

@@ -433,6 +433,11 @@ class IdbDriver {
             const proc = opts.appId.split('.').pop() || opts.appId;
             args.push('--predicate', `process CONTAINS "${proc}"`);
         }
+        else if (opts.scopedOnly) {
+            // scopedOnly without an appId can't mean anything on iOS — empty rather than
+            // a full dump (mirrors Android's "couldn't scope" behaviour).
+            return '';
+        }
         const out = (0, exec_1.runText)(XCRUN, args, { timeout: 20000 }).stdout;
         if (opts.since)
             return out; // the whole session window

package/dist/report.js

@@ -5,6 +5,7 @@
 // recorder (run.ts) / suite runner (suite.ts) own all the I/O. The RunState data
 // model lives in run.ts; we import the types only.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFailure = runFailure;
 exports.toJUnitXml = toJUnitXml;
 exports.suiteTotals = suiteTotals;
 exports.toSuiteIndexJson = toSuiteIndexJson;
@@ -41,12 +42,40 @@ function resolvedLabel(s) {
 function fmtDuration(ms) {
     return ms < 1000 ? `${ms} ms` : `${(ms / 1000).toFixed(2)} s`;
 }
+/**
+ * The run's verdict, taken from the ENGINE rather than inferred from step statuses.
+ *
+ * A `vk ai` run can fail outside any command — a `repeat` that never sees its target,
+ * a budget/timeout abort — and those record no step, so a tally-only report declared
+ * the run green (issue #41). `Recorder.recordTerminalFailure` now writes `failure`, and
+ * `ai.ok` is the older, coarser signal we still fall back to; between them an
+ * unrecorded failure can no longer read as success.
+ */
+function runFailure(run) {
+    if (run.failure)
+        return run.failure;
+    if (run.ai && !run.ai.ok)
+        return { where: 'run', reason: 'the run did not pass (no step recorded the failure)' };
+    return null;
+}
 function counts(run) {
     const passed = run.steps.filter((s) => s.status === 'passed').length;
     const failures = run.steps.filter((s) => s.status === 'failed').length;
     const errors = run.steps.filter((s) => s.status === 'error').length;
     const timeMs = run.steps.reduce((a, s) => a + s.durationMs, 0);
-    return { tests: run.steps.length, passed, failures, errors, timeMs };
+    // Belt and braces. Normally the terminal failure IS a step by the time we render, so
+    // this stays false; it fires only if the failure never reached the recorder, and then
+    // both renderers emit one extra entry — hence `tests` grows too, so the tally never
+    // disagrees with the testcase list it is supposed to describe.
+    const unrecorded = failures + errors === 0 && runFailure(run) !== null;
+    return {
+        tests: run.steps.length + (unrecorded ? 1 : 0),
+        passed,
+        failures: failures + (unrecorded ? 1 : 0),
+        errors,
+        timeMs,
+        unrecorded,
+    };
 }
 // --- JUnit ----------------------------------------------------------------
 function toJUnitXml(run) {
@@ -93,16 +122,28 @@ function toJUnitXml(run) {
         return `  <testcase ${attrs}>${body}\n  </testcase>`;
     })
         .join('\n');
+    const f = runFailure(run);
+    const unrecordedCase = c.unrecorded && f
+        ? `  <testcase name="${xmlAttr(`run did not pass (${f.where})`)}" classname="verikun.run" time="0.000">` +
+            `\n    <failure message="${xmlAttr(f.reason)}" type="AssertionFailure">${xmlText(`${f.where}: ${f.reason}`)}</failure>\n  </testcase>`
+        : '';
+    const allCases = [cases, unrecordedCase].filter(Boolean).join('\n');
     const suiteAttrs = `name="${xmlAttr(run.name)}" tests="${c.tests}" failures="${c.failures}" ` +
         `errors="${c.errors}" time="${suiteTime}" timestamp="${xmlAttr(run.startedAt)}"`;
+    const suiteExtras = [];
+    if (run.logFile)
+        suiteExtras.push(`device log: ${run.logFile}`);
+    if (run.ai) {
+        suiteExtras.push('vk ai: ' +
+            run.ai.cost +
+            (run.ai.improvements.length ? '\nSuggested improvements:\n' + run.ai.improvements.join('\n') : ''));
+    }
     return (`<?xml version="1.0" encoding="UTF-8"?>\n` +
         `<testsuites name="verikun" tests="${c.tests}" failures="${c.failures}" errors="${c.errors}" time="${suiteTime}">\n` +
         `<testsuite ${suiteAttrs}>\n` +
-        `${cases}\n` +
-        (run.ai
-            ? `  <system-out>${xmlText('vk ai: ' +
-                run.ai.cost +
-                (run.ai.improvements.length ? '\nSuggested improvements:\n' + run.ai.improvements.join('\n') : ''))}</system-out>\n`
+        `${allCases}\n` +
+        (suiteExtras.length
+            ? `  <system-out>${xmlText(suiteExtras.join('\n'))}</system-out>\n`
             : '') +
         `</testsuite>\n</testsuites>\n`);
 }
@@ -136,11 +177,18 @@ const STYLE = `
   .msg.fail { color:var(--fail); }
   img.shot { display:block; margin-top:10px; max-width:300px; max-height:520px; border:1px solid var(--line); border-radius:6px; }
   details { margin-top:8px; }
+  details.run-log { margin-top:20px; background:#fff; border:1px solid var(--line); border-radius:8px; padding:10px 14px; }
+  details.run-log > summary { font-weight:600; color:#1f2328; }
+  details.run-log > summary a { font-weight:400; }
+  details.run-log pre { max-height:480px; }
   summary { cursor:pointer; color:var(--muted); font-size:13px; }
   pre { background:#0d1117; color:#e6edf3; padding:12px; border-radius:6px; overflow:auto; font-size:12px; line-height:1.45; max-height:360px; }
   .aibox { background:#fff; border:1px solid var(--line); border-radius:8px; padding:12px 14px; margin-bottom:20px; font-size:13px; }
   .aibox .cost { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; color:var(--muted); margin-top:4px; }
   .aibox ul { margin:8px 0 0; padding-left:18px; }
+  .failbox { background:#fff; border:1px solid var(--fail); border-left-width:4px; border-radius:8px; padding:12px 14px; margin-bottom:20px; font-size:13px; }
+  .failbox .where { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; color:var(--muted); }
+  .failbox .why { color:var(--fail); margin-top:4px; }
 `;
 function aiPanelHtml(ai) {
     const improvements = ai.improvements.length
@@ -154,6 +202,14 @@ function aiPanelHtml(ai) {
       ${improvements}
     </div>`;
 }
+/** The run-level failure, stated once at the top. This page is where a human looks
+ *  first, so the verdict has to be visible without reading 26 green rows. */
+function failBoxHtml(f) {
+    return `<div class="failbox">
+      <div><strong>This run did not pass.</strong> <span class="where">${htmlEsc(f.where)}</span></div>
+      <div class="why">${htmlEsc(f.reason)}</div>
+    </div>`;
+}
 function stepHtml(s) {
     const detail = [];
     if (selectorLabel(s))
@@ -316,8 +372,14 @@ ${suite.tests.map((x) => suiteTestRow(x, linkBase)).join('\n')}
 </html>
 `;
 }
-function toHtml(run) {
+/**
+ * @param opts.appLog  app-scoped logcat body for the bottom accordion (kept out
+ *                     of RunState / run.json — pass the file contents when writing
+ *                     report.html). The full device dump stays a meta-row file link.
+ */
+function toHtml(run, opts = {}) {
     const c = counts(run);
+    const failure = runFailure(run);
     const chips = [
         `<span class="chip pass">${c.passed} passed</span>`,
         c.failures ? `<span class="chip fail">${c.failures} failed</span>` : '',
@@ -332,7 +394,20 @@ function toHtml(run) {
         `started ${htmlEsc(run.startedAt)}`,
         run.finishedAt ? `finished ${htmlEsc(run.finishedAt)}` : '',
         run.implicit ? 'implicit run' : '',
+        run.logFile ? `<a href="${htmlEsc(run.logFile)}">device log</a>` : '',
     ].filter(Boolean);
+    // Bottom accordion: app-scoped dump only. The noisy full device log stays a
+    // download via the meta link — same shape on every framework (package/uid scope).
+    const appLabel = run.appId ? ` for ${htmlEsc(run.appId)}` : '';
+    const appFileLink = run.appLogFile
+        ? ` (<a href="${htmlEsc(run.appLogFile)}">${htmlEsc(run.appLogFile)}</a>)`
+        : '';
+    const appLogPanel = opts.appLog !== undefined && opts.appLog !== ''
+        ? `\n  <details class="run-log">
+    <summary>App log${appLabel}${appFileLink}</summary>
+    <pre>${htmlEsc(opts.appLog)}</pre>
+  </details>`
+        : '';
     return `<!doctype html>
 <html lang="en">
 <head>
@@ -348,10 +423,28 @@ function toHtml(run) {
   <div class="summary">
       ${chips}
   </div>
+  ${failure ? failBoxHtml(failure) : ''}
   ${run.ai ? aiPanelHtml(run.ai) : ''}
   <ol class="steps">
-    ${run.steps.map(stepHtml).join('\n    ')}
-  </ol>
+    ${[
+        ...run.steps.map(stepHtml),
+        // Only when the failure reached no step — otherwise it is already a red row.
+        ...(c.unrecorded && failure
+            ? [
+                stepHtml({
+                    index: run.steps.length,
+                    command: 'ai',
+                    name: `run did not pass (${failure.where})`,
+                    startedAt: run.startedAt,
+                    durationMs: 0,
+                    status: 'failed',
+                    exitCode: 1,
+                    message: failure.reason,
+                }),
+            ]
+            : []),
+    ].join('\n    ')}
+  </ol>${appLogPanel}
 </div>
 </body>
 </html>

package/dist/run.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Recorder = void 0;
+exports.Recorder = exports.RUN_APP_LOG_ARTIFACT = exports.RUN_LOG_ARTIFACT = void 0;
 exports.isRecordable = isRecordable;
+exports.wantsArchiveLogs = wantsArchiveLogs;
+exports.archiveLogWindow = archiveLogWindow;
+exports.inferRunAppId = inferRunAppId;
 exports.runId = runId;
 exports.uniqueDir = uniqueDir;
 exports.rolloverReason = rolloverReason;
+exports.rolloverLogsSameDevice = rolloverLogsSameDevice;
 exports.stepName = stepName;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -32,6 +36,58 @@ function isRecordable(command) {
 }
 const HIERARCHY_CAP = 24000; // chars of failure hierarchy kept inline in run.json
 const LOG_CAP = 50000; // chars of device logs kept inline in run.json (tail-kept)
+/** Max chars written to the archive-time `artifacts/logcat.txt` (tail-kept). Larger
+ *  than the per-step LOG_CAP because the file is not inlined into run.json. */
+const LOG_FILE_CAP = 512_000;
+/** When no session `logStart` marker exists, archive captures this many trailing lines. */
+const ARCHIVE_LOG_LINES = 5000;
+exports.RUN_LOG_ARTIFACT = 'artifacts/logcat.txt';
+exports.RUN_APP_LOG_ARTIFACT = 'artifacts/logcat-app.txt';
+const APP_LIFECYCLE = new Set(['launch', 'open', 'stop', 'clear']);
+/** Whether archive-time device-log capture should run. Default on; `--no-logs` /
+ *  `VERIKUN_NO_LOGS` opts out of *green* runs only — a failed run always captures
+ *  (best-effort), because that is when the log is load-bearing. Exported for tests. */
+function wantsArchiveLogs(hasFailures, noLogsFlag = false) {
+    if (hasFailures)
+        return true;
+    if (noLogsFlag)
+        return false;
+    if (process.env.VERIKUN_NO_LOGS)
+        return false;
+    return true;
+}
+/** Window passed to `getLogs` at archive time: session-scoped when `logStart` is
+ *  known, otherwise a bounded trailing dump. Exported for tests. */
+function archiveLogWindow(state) {
+    if (state.logStart)
+        return { since: state.logStart };
+    return { lines: ARCHIVE_LOG_LINES };
+}
+/** Package / bundle id the run exercised, if we can tell. Prefer an explicit
+ *  `state.appId` (set on launch/open/stop/clear); otherwise recover from those
+ *  steps' names. Exported for tests. */
+function inferRunAppId(state) {
+    if (state.appId && /^[A-Za-z0-9._-]+$/.test(state.appId))
+        return state.appId;
+    for (let i = state.steps.length - 1; i >= 0; i--) {
+        const s = state.steps[i];
+        if (!APP_LIFECYCLE.has(s.command))
+            continue;
+        // stepName is `launch com.foo` / `clear com.foo` (no flags in the name).
+        const m = /^(?:launch|open|stop|clear)\s+([A-Za-z0-9._-]+)\s*$/.exec(s.name);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+function truncateLogFile(text) {
+    if (text.length <= LOG_FILE_CAP)
+        return text;
+    return '…(truncated)\n' + text.slice(-LOG_FILE_CAP);
+}
+function runHasFailures(state) {
+    return state.steps.some((s) => s.status !== 'passed');
+}
 // --- paths & persistence --------------------------------------------------
 const activeDir = () => (0, node_path_1.join)((0, output_1.artifactDir)(), 'run');
 const archiveBase = () => (0, node_path_1.join)((0, output_1.artifactDir)(), 'runs');
@@ -49,6 +105,19 @@ function loadState(dir) {
         return null;
     }
 }
+/** Relative path of a step's failure screenshot. One place, because a synthetic
+ *  terminal-failure step has to land on the same convention as a recorded one. */
+const failImagePath = (index) => `artifacts/step-${index}-fail.png`;
+function writeArtifactTo(dir, rel, buf) {
+    (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, rel), buf);
+}
+/** Compact hierarchy text, HEAD-capped — a failure dump is read top-down, so the
+ *  first screenful is the useful part (unlike logs, which are kept tail-first). */
+function capHierarchy(els) {
+    const text = (0, format_1.formatCompact)(els);
+    return text.length > HIERARCHY_CAP ? text.slice(0, HIERARCHY_CAP) + '\n…(truncated)' : text;
+}
 function saveState(dir, state) {
     (0, node_fs_1.mkdirSync)(dir, { recursive: true });
     (0, node_fs_1.writeFileSync)(statePath(dir), JSON.stringify(state, null, 2));
@@ -123,6 +192,14 @@ function rolloverReason(state, serial, session) {
         return `idle for ${fmtAge(ageMs(state))} (>${idle}m)`;
     return null;
 }
+/** Whether the incoming step's driver is safe to use for archive-time logs of the
+ *  run being sealed. On a device-change rollover the driver is already pointed at
+ *  the *new* serial — pulling logcat from it would attribute the wrong device's
+ *  output to the old run. Idle/session rollover on the same device is fine.
+ *  Exported for tests. */
+function rolloverLogsSameDevice(runDevice, newSerial) {
+    return !runDevice || !newSerial || runDevice === newSerial;
+}
 function stepName(command, positionals, flags) {
     const p = positionals;
     const at = typeof flags['at'] === 'string' ? flags['at'] : undefined;
@@ -187,7 +264,13 @@ class Recorder {
             const reason = rolloverReason(state, serial, session);
             if (reason) {
                 try {
-                    const dest = Recorder.seal(state, dir);
+                    // Only reuse this step's driver when it still targets the run's device.
+                    // A device-change rollover must not write the new device's logcat into
+                    // the old run's archive (vk run archive binds a driver to state.device).
+                    const fetchLogs = driver && rolloverLogsSameDevice(state.device, serial)
+                        ? (opts) => driver.getLogs(opts)
+                        : undefined;
+                    const dest = Recorder.seal(state, dir, { fetchLogs });
                     (0, output_1.err)(`[verikun] previous run '${state.name}' (${state.steps.length} step(s)) auto-closed → ${dest} (${reason}); starting a fresh run`);
                     state = null;
                     rolledOver = true;
@@ -220,6 +303,11 @@ class Recorder {
             if (!state.session && session)
                 state.session = session;
         }
+        // Remember the app under test from lifecycle commands so archive can scope
+        // the accordion log without requiring a separate flag.
+        if (APP_LIFECYCLE.has(command) && positionals[0] && /^[A-Za-z0-9._-]+$/.test(positionals[0])) {
+            state.appId = positionals[0];
+        }
         // Anchor the log window at the session's first step (covers both implicit
         // creation and an explicit `vk run start`, which records no marker itself).
         // Best-effort — a missing marker just means `vk log` falls back to last-N.
@@ -352,8 +440,8 @@ class Recorder {
         if (!driver)
             return;
         try {
-            this.writeArtifact(`artifacts/step-${this.step.index}-fail.png`, driver.screenshot());
-            this.step.failImage = `artifacts/step-${this.step.index}-fail.png`;
+            this.writeArtifact(failImagePath(this.step.index), driver.screenshot());
+            this.step.failImage = failImagePath(this.step.index);
         }
         catch (e) {
             // Best-effort evidence: the device may be gone (often why the step failed). Surface
@@ -362,8 +450,7 @@ class Recorder {
                 (0, output_1.err)(`[verikun] could not capture failure screenshot (${e.message})`);
         }
         try {
-            const text = (0, format_1.formatCompact)(driver.getElements({ all: false }));
-            this.step.failHierarchy = text.length > HIERARCHY_CAP ? text.slice(0, HIERARCHY_CAP) + '\n…(truncated)' : text;
+            this.step.failHierarchy = capHierarchy(driver.getElements({ all: false }));
         }
         catch (e) {
             if (!quiet)
@@ -375,8 +462,7 @@ class Recorder {
             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);
+        writeArtifactTo(this.dir, rel, buf);
     }
     commit() {
         this.step.durationMs = Date.now() - this.startMs;
@@ -386,18 +472,87 @@ class Recorder {
         this.state.updatedAt = nowIso();
         saveState(this.dir, this.state);
     }
-    /** Finalize a run: write reports next to it, then move it into ./.verikun/runs/<id>/. */
-    static seal(state, dir) {
+    /** Finalize a run: optionally capture device logs, write reports next to it, then
+     *  move it into ./.verikun/runs/<id>/. Log capture is best-effort — a device that
+     *  is gone (often why the run failed) must never prevent sealing the report. */
+    static seal(state, dir, opts = {}) {
+        Recorder.maybeCaptureArchiveLogs(state, dir, opts);
         state.finishedAt = nowIso();
         state.updatedAt = nowIso();
         saveState(dir, state);
         (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'report.xml'), (0, report_1.toJUnitXml)(state));
-        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'report.html'), (0, report_1.toHtml)(state));
+        // Accordion embeds the *app*-scoped dump (readable); the full device dump stays
+        // a file link in the meta row. Missing file is fine — capture is best-effort.
+        let appLog;
+        if (state.appLogFile) {
+            try {
+                appLog = (0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, state.appLogFile), 'utf8');
+            }
+            catch {
+                /* report still writes */
+            }
+        }
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, 'report.html'), (0, report_1.toHtml)(state, { appLog }));
         (0, node_fs_1.mkdirSync)(archiveBase(), { recursive: true });
         const dest = uniqueDir((0, node_path_1.join)(archiveBase(), state.id));
         (0, node_fs_1.renameSync)(dir, dest);
         return dest;
     }
+    /** Write archive-time log artifacts on the ACTIVE run without sealing. Used by
+     *  remote (`--server`) callers that fetch asynchronously before `archive()`.
+     *  Pass `full` / `app` only for the pieces you have — omitted sides are left alone. */
+    static attachArchiveLogs(full, app) {
+        const dir = activeDir();
+        const state = loadState(dir);
+        if (!state)
+            return;
+        if (full !== undefined) {
+            Recorder.writeArchiveLog(state, dir, full, exports.RUN_LOG_ARTIFACT, 'logFile');
+        }
+        if (app !== undefined && app !== '') {
+            if (!state.appId)
+                state.appId = inferRunAppId(state);
+            Recorder.writeArchiveLog(state, dir, app, exports.RUN_APP_LOG_ARTIFACT, 'appLogFile');
+        }
+        saveState(dir, state);
+    }
+    static writeArchiveLog(state, dir, text, rel, field) {
+        const body = truncateLogFile(text);
+        (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, rel), body);
+        state[field] = rel;
+    }
+    static maybeCaptureArchiveLogs(state, dir, opts) {
+        if (!wantsArchiveLogs(runHasFailures(state), opts.noLogs))
+            return;
+        if (!opts.fetchLogs)
+            return;
+        const window = archiveLogWindow(state);
+        if (!state.logFile) {
+            try {
+                const text = opts.fetchLogs(window);
+                if (text !== undefined && text !== null) {
+                    Recorder.writeArchiveLog(state, dir, text, exports.RUN_LOG_ARTIFACT, 'logFile');
+                }
+            }
+            catch (e) {
+                (0, output_1.err)(`[verikun] could not capture archive device logs (${e.message})`);
+            }
+        }
+        const appId = inferRunAppId(state);
+        if (appId)
+            state.appId = appId;
+        if (appId && !state.appLogFile) {
+            try {
+                const text = opts.fetchLogs({ ...window, appId, scopedOnly: true });
+                if (text)
+                    Recorder.writeArchiveLog(state, dir, text, exports.RUN_APP_LOG_ARTIFACT, 'appLogFile');
+            }
+            catch (e) {
+                (0, output_1.err)(`[verikun] could not capture archive app logs (${e.message})`);
+            }
+        }
+    }
     /** One-line context summary for `vk run status`. */
     static contextLine(state) {
         const bits = [];
@@ -428,6 +583,8 @@ class Recorder {
      * 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).
+     * `ctx.logStart` (device-clock marker from the server) is recorded on the first
+     * splice so archive-time / `vk log` scoping works the same as a local run.
      */
     static appendForeignStep(step, artifacts = {}, ctx = {}) {
         if (process.env.VERIKUN_NO_RUN)
@@ -448,6 +605,17 @@ class Recorder {
             };
             (0, output_1.err)('[verikun] recording test run (implicit) — archive: `vk run archive` · discard: `vk run clear`');
         }
+        // Anchor the log window from the server's device clock (beginEphemeralStep
+        // never persists state, so the marker has to travel on the wire).
+        if (!state.logStart && ctx.logStart)
+            state.logStart = ctx.logStart;
+        // Mirror local beginStep: remember the app from lifecycle steps so archive
+        // can scope the accordion without a local launch having set state.appId.
+        if (APP_LIFECYCLE.has(step.command)) {
+            const m = /^(?:launch|open|stop|clear)\s+([A-Za-z0-9._-]+)\s*$/.exec(step.name);
+            if (m)
+                state.appId = m[1];
+        }
         const index = state.steps.length;
         const spliced = { ...step, index };
         for (const [rel, buf] of Object.entries(artifacts)) {
@@ -490,6 +658,56 @@ class Recorder {
             last.message = message;
         saveState(dir, state);
     }
+    /**
+     * Record a terminal failure the `vk ai` ENGINE produced rather than a command — a
+     * control node that gave up (`repeat` exhausted, `when` matched no branch), a
+     * budget/timeout abort, an engine-internal throw. None of those go through
+     * beginStep, so before this existed nothing marked the run red and the archived
+     * report declared a failed test fully green (issue #41).
+     *
+     * Always records the run-level verdict. Appends a synthetic failed step ONLY when
+     * no step is already red — a leaf failure carries its own step and evidence, and
+     * counting it twice would be its own kind of lie.
+     */
+    static recordTerminalFailure(failure, evidence) {
+        if (process.env.VERIKUN_NO_RUN)
+            return;
+        const dir = activeDir();
+        const state = loadState(dir);
+        if (!state)
+            return;
+        state.failure = { where: failure.where, reason: failure.reason };
+        if (state.steps.every((s) => s.status === 'passed')) {
+            const index = state.steps.length;
+            // An environment abort is exit 3 (the box is broken, not the app), matching
+            // what `vk ai` itself returns; everything else is an exit-1 assertion failure.
+            const env = failure.kind === 'env';
+            const step = {
+                index,
+                command: 'ai',
+                name: `ai ${env ? 'aborted' : 'failed'} at ${failure.where}`,
+                startedAt: nowIso(),
+                durationMs: 0,
+                status: env ? 'error' : 'failed',
+                exitCode: env ? 3 : 1,
+                message: failure.reason,
+            };
+            if (evidence?.png) {
+                try {
+                    writeArtifactTo(dir, failImagePath(index), evidence.png);
+                    step.failImage = failImagePath(index);
+                }
+                catch (e) {
+                    (0, output_1.err)(`[verikun] could not write the failure screenshot (${e.message})`);
+                }
+            }
+            if (evidence?.hierarchy)
+                step.failHierarchy = capHierarchy(evidence.hierarchy);
+            state.steps.push(step);
+        }
+        state.updatedAt = nowIso();
+        saveState(dir, state);
+    }
     static start(name, platform, device, force) {
         const dir = activeDir();
         const existing = loadState(dir);
@@ -521,8 +739,10 @@ class Recorder {
             (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
         return existing;
     }
-    /** Write JUnit + HTML reports and move the run into ./.verikun/runs/<id>/. */
-    static archive(name) {
+    /** Write JUnit + HTML reports and move the run into ./.verikun/runs/<id>/.
+     *  By default captures a bounded device-log tail into `artifacts/logcat.txt`
+     *  (see wantsArchiveLogs / ArchiveLogOpts). */
+    static archive(name, opts = {}) {
         const dir = activeDir();
         if (!(0, node_fs_1.existsSync)(statePath(dir))) {
             throw new errors_1.CliError('No active test run to archive. Run an action first, or `vk run start`.', 1);
@@ -532,7 +752,7 @@ class Recorder {
             throw new errors_1.CliError('Active run state is unreadable (.verikun/run/run.json is corrupt).', 3);
         if (name)
             state.name = name;
-        const dest = Recorder.seal(state, dir);
+        const dest = Recorder.seal(state, dir, opts);
         return { dir: dest, xmlPath: (0, node_path_1.join)(dest, 'report.xml'), htmlPath: (0, node_path_1.join)(dest, 'report.html'), state };
     }
 }

package/dist/server.js

@@ -11,6 +11,7 @@
 //    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.
+//    Archive-time log capture uses the dedicated /v1/logs endpoint instead.
 //  - /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.
@@ -154,13 +155,14 @@ function buildServer(config) {
         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);
+        const { code, error, step, artifacts, logStart } = 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) } : {}),
+            ...(logStart ? { logStart } : {}),
         };
         sendJson(res, 200, payload);
     }
@@ -169,6 +171,45 @@ function buildServer(config) {
         const elements = config.driver.getElements(); // CliError(3) on dump failure → 500 below
         sendJson(res, 200, { elements });
     }
+    async function handleLogs(req, res) {
+        const body = await readBody(req, EXEC_BODY_CAP);
+        let parsed = {};
+        if (body.length) {
+            try {
+                parsed = JSON.parse(body.toString('utf8'));
+            }
+            catch {
+                throw new HttpError(400, 'invalid JSON body');
+            }
+        }
+        // Mirror the driver's --since charset gate so a remote caller cannot inject
+        // into the device shell via a crafted marker (see AdbDriver.getLogs).
+        if (parsed.since !== undefined && parsed.since !== null) {
+            if (typeof parsed.since !== 'string' || !/^[0-9 :.\-]+$/.test(parsed.since)) {
+                throw new HttpError(400, `invalid since: only a logcat timestamp (digits, space, '-', ':', '.') is allowed`);
+            }
+        }
+        const lines = parsed.lines === undefined || parsed.lines === null
+            ? undefined
+            : typeof parsed.lines === 'number' && Number.isFinite(parsed.lines) && parsed.lines > 0
+                ? Math.floor(parsed.lines)
+                : undefined;
+        const appId = parsed.appId === undefined || parsed.appId === null
+            ? undefined
+            : typeof parsed.appId === 'string' && /^[A-Za-z0-9_.-]+$/.test(parsed.appId)
+                ? parsed.appId
+                : (() => {
+                    throw new HttpError(400, `invalid appId '${String(parsed.appId)}'`);
+                })();
+        const logs = config.driver.getLogs({
+            ...(lines !== undefined ? { lines } : {}),
+            ...(parsed.since ? { since: parsed.since } : {}),
+            ...(appId ? { appId } : {}),
+            ...(parsed.scopedOnly ? { scopedOnly: true } : {}),
+        });
+        const payload = { logs };
+        sendJson(res, 200, payload);
+    }
     async function handleInstall(req, res) {
         const ext = String(req.headers['x-verikun-ext'] ?? '').toLowerCase();
         if (ext !== 'apk' && ext !== 'ipa') {
@@ -256,6 +297,8 @@ function buildServer(config) {
             return deviceEndpoint(() => handleExec(req, res));
         if (req.method === 'POST' && path === '/v1/elements')
             return deviceEndpoint(() => handleElements(req, res));
+        if (req.method === 'POST' && path === '/v1/logs')
+            return deviceEndpoint(() => handleLogs(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);

package/dist/version.js

@@ -3,4 +3,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // GENERATED by scripts/gen-version.mjs from package.json's "version" at build time
 // (the `prebuild` script). Do NOT edit by hand; bump package.json instead.
-exports.VERSION = '0.17.0';
+exports.VERSION = '0.18.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "verikun",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Drive Android emulators/devices and iOS simulators for AI agents: tap, type, swipe, screenshot, and inspect the UI hierarchy by semantic identifiers — like Puppeteer for native apps.",
   "keywords": [
     "android",