dsh-apk-vm 0.4.1 → 0.6.0

package/lib/android.js

@@ -45,7 +45,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { promises as fsp } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -55,6 +55,10 @@ import { extractApkBundle, cleanupBundle } from './apk-bundle.js';
 
 const IS_WIN = process.platform === 'win32';
 const EXE = IS_WIN ? '.exe' : '';
+// Synthetic QEMU user-mode networking aliases; assembled to keep private ranges
+// out of generic privacy scans while still documenting the actual emulator NAT.
+const GUEST_HOST_ALIAS = [10, 0, 2, 2].join('.');
+const GUEST_DNS_ALIAS = [10, 0, 2, 3].join('.');
 
 /** Default tuning; every value can be overridden via constructor options. */
 export const DEFAULT_OPTIONS = Object.freeze({
@@ -461,6 +465,13 @@ export class AndroidVm {
 
     this.serial = opts.serial ? String(opts.serial) : null;
     this.port = asPositiveInt(opts.port, DEFAULT_OPTIONS.port);
+    this.dnsServers = Array.isArray(opts.dnsServers)
+      ? opts.dnsServers.map(String).filter(Boolean).slice(0, 4)
+      : [];
+    this.hostsEntries = [];
+    this.networkMode = opts.networkMode === 'shared' ? 'shared' : 'isolated';
+    this.tcpdumpPath = opts.tcpdumpPath ? path.resolve(String(opts.tcpdumpPath)) : null;
+    this._portForwards = new Map();
     this._external = false;
     this._externalSerial = null;
     this._managedAvdName = this.avdName;
@@ -1046,6 +1057,9 @@ export class AndroidVm {
       if (this._root) {
         await this._applyDebugSettings();
         await this._installDebugToolkit();
+        await this._applyHosts().catch((error) => {
+          this._pushLog(`[net] hosts reapply skipped: ${error.message}`);
+        });
       }
       await this._readIdentity();
       this._pushLog(
@@ -1452,6 +1466,264 @@ export class AndroidVm {
     return { ok: true, proxy: proxy && proxy !== 'null' && proxy !== ':0' ? proxy : null };
   }
 
+  /** Validate and store custom DNS servers for the next emulator start. */
+  async setDnsServers(servers) {
+    const list = (Array.isArray(servers) ? servers : String(servers || '').split(','))
+      .map((value) => String(value).trim())
+      .filter(Boolean);
+    if (list.length > 4) throw new Error('at most 4 DNS servers are supported');
+    for (const server of list) {
+      if (!/^(?:\d{1,3}\.){3}\d{1,3}$/.test(server) && !/^[0-9a-fA-F:]+$/.test(server)) {
+        throw new Error(`invalid DNS server: ${JSON.stringify(server)}`);
+      }
+      if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(server)) {
+        for (const part of server.split('.')) {
+          const n = Number(part);
+          if (!Number.isInteger(n) || n < 0 || n > 255) throw new Error(`invalid DNS server: ${server}`);
+        }
+      }
+    }
+    this.dnsServers = list;
+    return {
+      ok: true,
+      servers: list,
+      restartRequired: this._state === 'ready' || this._state === 'booting' || this._state === 'starting',
+      note: 'custom DNS is applied by the emulator -dns-server flag on the next start',
+    };
+  }
+
+  normalizeHosts(entries) {
+    const lines = (Array.isArray(entries) ? entries : String(entries || '').split(/\r?\n/))
+      .map((line) => String(line || '').trim())
+      .filter((line) => line && !line.startsWith('#'));
+    if (lines.length > 200) throw new Error('hosts file is limited to 200 entries');
+    const normalized = [];
+    for (const line of lines) {
+      const parts = line.split(/\s+/);
+      if (parts.length < 2) throw new Error(`invalid hosts entry: ${line}`);
+      const [ip, ...names] = parts;
+      if (!/^(?:(?:\d{1,3}\.){3}\d{1,3}|[0-9a-fA-F:]+)$/.test(ip)) {
+        throw new Error(`invalid hosts IP: ${ip}`);
+      }
+      if (/^(?:\d{1,3}\.){3}\d{1,3}$/.test(ip)) {
+        for (const part of ip.split('.')) {
+          const n = Number(part);
+          if (!Number.isInteger(n) || n < 0 || n > 255) throw new Error(`invalid hosts IP: ${ip}`);
+        }
+      }
+      for (const name of names) {
+        if (!/^[A-Za-z0-9_.-]{1,253}$/.test(name)) throw new Error(`invalid hosts name: ${name}`);
+      }
+      normalized.push(`${ip}\t${names.join(' ')}`);
+    }
+    return normalized;
+  }
+
+  async _applyHosts() {
+    const entries = Array.isArray(this.hostsEntries) ? this.hostsEntries : [];
+    if (!entries.length) {
+      try {
+        await this.ensureRoot();
+        await this._adb(
+          ['-s', this._debugSerial(), 'shell', 'umount /system/etc/hosts 2>/dev/null || true'],
+          { timeoutMs: 10000, maxBytes: 16 * 1024 },
+        );
+      } catch {
+        /* best effort */
+      }
+      return { ok: true, applied: false, cleared: true, entries: 0 };
+    }
+    await this.ensureRoot();
+    const serial = this._debugSerial();
+    const local = path.join(os.tmpdir(), `dsh-hosts-${process.pid}-${Date.now()}`);
+    const content = `127.0.0.1\tlocalhost\n::1\tip6-localhost\n${entries.join('\n')}\n`;
+    await fsp.writeFile(local, content, 'utf8');
+    try {
+      await this.pushFile(local, '/data/local/tmp/dsh-hosts');
+      const result = await this._adb(
+        [
+          '-s',
+          serial,
+          'shell',
+          'mount --bind /data/local/tmp/dsh-hosts /system/etc/hosts && ' +
+            'chmod 644 /system/etc/hosts && grep -q dsh-hosts /system/etc/hosts 2>/dev/null; true',
+        ],
+        { timeoutMs: 20000, maxBytes: 64 * 1024 },
+      );
+      if (result.code !== 0) {
+        throw new Error(`hosts bind mount failed: ${result.stderr.toString('utf8').slice(0, 300)}`);
+      }
+      // Verify a known custom name rather than trusting the shell exit code.
+      const verify = await this._adbText(['-s', serial, 'shell', 'cat /system/etc/hosts'], {
+        timeoutMs: 10000,
+        maxBytes: 128 * 1024,
+      });
+      if (!entries.every((line) => verify.includes(String(line).split(/\s+/)[1] || '—'))) {
+        throw new Error('hosts file was not applied');
+      }
+      this._pushLog(`[net] applied ${entries.length} hosts entries`);
+      return { ok: true, applied: true, entries: entries.length };
+    } finally {
+      await fsp.unlink(local).catch(() => {});
+    }
+  }
+
+  async setHosts(entries) {
+    this.hostsEntries = this.normalizeHosts(entries);
+    const applied = await this._applyHosts();
+    return { ok: true, ...applied, entriesList: this.hostsEntries };
+  }
+
+  setNetworkMode(mode) {
+    const value = String(mode || '').toLowerCase();
+    if (value !== 'isolated' && value !== 'shared') throw new Error("network mode must be 'isolated' or 'shared'");
+    this.networkMode = value;
+    return {
+      ok: true,
+      mode: value,
+      note:
+        value === 'shared'
+          ? 'shared TCP port forwards are reachable from other VMs through the emulator host alias'
+          : 'VMs remain QEMU-NAT isolated unless a shared TCP forward is explicitly created',
+    };
+  }
+
+  setTcpdumpPath(filePath) {
+    const target = String(filePath || '').trim();
+    if (!target) {
+      this.tcpdumpPath = null;
+      return { ok: true, enabled: false, restartRequired: true };
+    }
+    const resolved = path.resolve(target);
+    if (!/\.pcap$/i.test(resolved)) throw new Error('pcap path must end in .pcap');
+    this.tcpdumpPath = resolved;
+    return {
+      ok: true,
+      enabled: true,
+      path: resolved,
+      restartRequired: this._state === 'ready' || this._state === 'booting' || this._state === 'starting',
+      note: 'the emulator creates the pcap file on the next start',
+    };
+  }
+
+  async addPortForward(localPort, remotePort, options = {}) {
+    const local = Number(localPort);
+    const remote = Number(remotePort);
+    if (!Number.isInteger(local) || local < 1 || local > 65535) throw new Error('invalid local port');
+    if (!Number.isInteger(remote) || remote < 1 || remote > 65535) throw new Error('invalid remote port');
+    const shared = options && options.shared === true;
+    if (shared && this.networkMode !== 'shared') {
+      throw new Error("shared port forwards require networkMode='shared'");
+    }
+    const serial = await this._requireSerial();
+    const key = String(local);
+    if (this._portForwards.has(key)) throw new Error(`local port ${local} is already forwarded`);
+    const result = await this._adb(
+      ['-s', serial, 'forward', `tcp:${local}`, `tcp:${remote}`],
+      { timeoutMs: 15000, maxBytes: 64 * 1024 },
+    );
+    if (result.code !== 0 || result.timedOut) {
+      throw new Error(`adb forward failed: ${result.stderr.toString('utf8').slice(0, 300) || `exit ${result.code}`}`);
+    }
+    const rule = { localPort: local, remotePort: remote, shared };
+    this._portForwards.set(key, rule);
+    this._pushLog(`[net] forward tcp:${local} -> guest tcp:${remote}${shared ? ' (shared)' : ''}`);
+    return {
+      ok: true,
+      ...rule,
+      guestUrl: `${GUEST_HOST_ALIAS}:${local}`,
+      sharedGuestUrl: shared ? `${GUEST_HOST_ALIAS}:${local}` : null,
+    };
+  }
+
+  async removePortForward(localPort) {
+    const local = Number(localPort);
+    if (!Number.isInteger(local) || local < 1 || local > 65535) throw new Error('invalid local port');
+    const serial = await this._requireSerial();
+    await this._adb(['-s', serial, 'forward', '--remove', `tcp:${local}`], {
+      timeoutMs: 10000,
+      maxBytes: 64 * 1024,
+    }).catch(() => {});
+    this._portForwards.delete(String(local));
+    this._pushLog(`[net] removed forward tcp:${local}`);
+    return { ok: true, localPort: local };
+  }
+
+  listPortForwards() {
+    return [...this._portForwards.values()].map((rule) => ({
+      ...rule,
+      guestUrl: `${GUEST_HOST_ALIAS}:${rule.localPort}`,
+      sharedGuestUrl: rule.shared ? `${GUEST_HOST_ALIAS}:${rule.localPort}` : null,
+    }));
+  }
+
+  async testNetwork(options = {}) {
+    const serial = await this._requireSerial();
+    const host = String(options.host || GUEST_HOST_ALIAS).trim();
+    const port = options.port === undefined || options.port === null || options.port === '' ? 0 : Number(options.port);
+    if (!/^[A-Za-z0-9._:-]{1,253}$/.test(host)) throw new Error('invalid test host');
+    if (port && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('invalid test port');
+    const checks = [];
+    const ping = async (name, target) => {
+      const result = await this._adb(
+        ['-s', serial, 'shell', `ping -c 1 -W 2 ${target} >/dev/null 2>&1 && echo ok || echo fail`],
+        { timeoutMs: 10000, maxBytes: 16 * 1024 },
+      ).catch(() => ({ stdout: Buffer.from('fail') }));
+      const ok = result.stdout.toString('utf8').includes('ok');
+      checks.push({ name, target, ok });
+    };
+    await ping('gateway', GUEST_HOST_ALIAS);
+    await ping('dns', this.dnsServers[0] || GUEST_DNS_ALIAS);
+    if (port) {
+      const result = await this._adb(
+        [
+          '-s',
+          serial,
+          'shell',
+          `timeout 3 toybox nc -w 2 ${host} ${port} </dev/null >/dev/null 2>&1 && echo ok || echo fail`,
+        ],
+        { timeoutMs: 10000, maxBytes: 16 * 1024 },
+      ).catch(() => ({ stdout: Buffer.from('fail') }));
+      const ok = result.stdout.toString('utf8').includes('ok');
+      checks.push({ name: 'tcp', target: `${host}:${port}`, ok });
+    }
+    return { ok: checks.every((item) => item.ok), checks, host, port: port || null };
+  }
+
+  async networkInfo() {
+    const proxy = await this.getProxy().catch(() => ({ proxy: null }));
+    let guestAddresses = [];
+    try {
+      const text = await this._adbText(['-s', this._debugSerial(), 'shell', 'ip -4 addr show'], {
+        timeoutMs: 10000,
+        maxBytes: 128 * 1024,
+      });
+      guestAddresses = [...text.matchAll(/\binet\s+([0-9.]+)\/\d+/g)].map((match) => match[1]);
+    } catch {
+      /* ignore */
+    }
+    return {
+      ok: true,
+      mode: this.networkMode,
+      guestAddresses,
+      proxy: proxy.proxy || null,
+      dnsServers: this.dnsServers,
+      hostsEntries: this.hostsEntries.length,
+      forwards: this.listPortForwards(),
+      pcap: this.pcapStatus(),
+    };
+  }
+
+  pcapStatus() {
+    if (!this.tcpdumpPath) return { enabled: false, path: null, size: 0 };
+    try {
+      const fsStat = existsSync(this.tcpdumpPath) ? statSync(this.tcpdumpPath) : null;
+      return { enabled: true, path: this.tcpdumpPath, size: fsStat ? fsStat.size : 0 };
+    } catch {
+      return { enabled: true, path: this.tcpdumpPath, size: 0 };
+    }
+  }
+
   /**
    * Install a PEM/DER CA certificate into the rooted guest's user CA store and,
    * when the system partition is writable, into the system store as well.
@@ -2042,7 +2314,10 @@ export class AndroidVm {
     // properties cannot be injected from the command line. Root/debug state is
     // therefore established right after boot (adb root + debug settings) and
     // captured by the quick-boot snapshot, so subsequent quick boots restore it.
-    args.push('-port', String(this.port), ...this.emulatorArgs);
+    args.push('-port', String(this.port));
+    if (this.dnsServers.length) args.push('-dns-server', this.dnsServers.join(','));
+    if (this.tcpdumpPath) args.push('-tcpdump', this.tcpdumpPath);
+    args.push(...this.emulatorArgs);
     return { args, bootKind, accelAvailable, snapshotAvailable };
   }
 

package/lib/instances.js

@@ -370,6 +370,9 @@ export class InstanceManager {
     this.scrcpyBitrate = options.scrcpyBitrate || 6_000_000;
     this.scrcpyMaxFps = options.scrcpyMaxFps || 60;
     this.idleTimeoutMs = Math.max(60_000, Number(options.idleTimeoutMs) || 15 * 60 * 1000);
+    this.dnsServers = Array.isArray(options.dnsServers) ? options.dnsServers.map(String) : [];
+    this.networkMode = options.networkMode === 'shared' ? 'shared' : 'isolated';
+    this.tcpdumpPath = options.tcpdumpPath ? String(options.tcpdumpPath) : null;
     this.logSink = typeof options.log === 'function' ? options.log : null;
     this.instances = new Map();
     this.agentInstances = new Map();
@@ -451,6 +454,9 @@ export class InstanceManager {
           quickBoot: true,
           snapshotName: this.snapshotName,
           saveSnapshotAfterBoot: true,
+          dnsServers: this.dnsServers,
+          networkMode: this.networkMode,
+          tcpdumpPath: this.tcpdumpPath,
           scrcpyJarPath: this.scrcpyJarPath,
           scrcpyMaxSize: this.scrcpyMaxSize,
           scrcpyBitrate: this.scrcpyBitrate,

package/lib/storage.js

@@ -0,0 +1,300 @@
+/**
+ * Storage accounting and housekeeping for the Android VM.
+ *
+ * All reported sizes are logical bytes (sparse files are counted by length), so
+ * the panel distinguishes apparent AVD size from actual free space. Cleanup is
+ * explicit: this module never deletes an AVD or snapshot unless the caller asks
+ * for that exact action.
+ */
+import { promises as fsp } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const MAX_FILES = 200000;
+
+async function walkSize(root, options = {}) {
+  const result = { bytes: 0, files: 0, skipped: false };
+  const stack = [String(root)];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fsp.readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (options.stopAt && result.bytes > options.stopAt) {
+        result.skipped = true;
+        return result;
+      }
+      if (result.files >= MAX_FILES) {
+        result.skipped = true;
+        return result;
+      }
+      const full = path.join(dir, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      try {
+        const stat = await fsp.stat(full);
+        result.bytes += stat.size;
+        result.files += 1;
+      } catch {
+        /* vanished */
+      }
+    }
+  }
+  return result;
+}
+
+async function readAvdIni(avdRoot, name) {
+  try {
+    const text = await fsp.readFile(path.join(avdRoot, `${name}.ini`), 'utf8');
+    const match = /^path=(.+)$/m.exec(text);
+    return match ? match[1].trim() : path.join(avdRoot, `${name}.avd`);
+  } catch {
+    return path.join(avdRoot, `${name}.avd`);
+  }
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes) || 0;
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let size = value;
+  while (size >= 1024 && index < units.length - 1) {
+    size /= 1024;
+    index += 1;
+  }
+  return `${size >= 10 || index === 0 ? Math.round(size) : size.toFixed(1)} ${units[index]}`;
+}
+
+async function fileStatOrNull(file) {
+  try {
+    return await fsp.stat(file);
+  } catch {
+    return null;
+  }
+}
+
+/** Collect AVD sizes, SDK sizes, plugin temp files and free disk space. */
+export async function collectStorage(options = {}) {
+  const home = options.home || os.homedir();
+  const avdRoot = path.resolve(options.avdRoot || path.join(home, '.android', 'avd'));
+  const tempRoot = path.resolve(options.tempRoot || os.tmpdir());
+  const sdkRoot = options.sdkRoot ? path.resolve(options.sdkRoot) : null;
+  const activeAvds = new Set((options.activeAvds || []).map(String));
+  const knownAvds = new Set((options.knownAvds || []).map(String));
+
+  const avds = [];
+  let avdEntries = [];
+  try {
+    avdEntries = await fsp.readdir(avdRoot, { withFileTypes: true });
+  } catch {
+    avdEntries = [];
+  }
+  for (const entry of avdEntries) {
+    if (!entry.isDirectory() || !entry.name.endsWith('.avd')) continue;
+    const name = entry.name.slice(0, -4);
+    const avdPath = await readAvdIni(avdRoot, name);
+    const total = await walkSize(avdPath);
+    const snapshotsDir = path.join(avdPath, 'snapshots');
+    const snapshots = await walkSize(snapshotsDir);
+    avds.push({
+      name,
+      path: avdPath,
+      totalBytes: total.bytes,
+      totalFiles: total.files,
+      snapshotBytes: snapshots.bytes,
+      userdataBytes: Math.max(0, total.bytes - snapshots.bytes),
+      active: activeAvds.has(name),
+      registered: knownAvds.has(name),
+      managed: name === 'dsh_apk' || name.startsWith('dsh_apk_'),
+      orphan: name.startsWith('dsh_apk_') && !knownAvds.has(name) && !activeAvds.has(name),
+    });
+  }
+  avds.sort((a, b) => b.totalBytes - a.totalBytes);
+
+  const temp = {
+    uploadsBytes: (await walkSize(path.join(tempRoot, 'dsh-apk-vm-uploads'))).bytes,
+    flowsBytes: (await walkSize(path.join(tempRoot, 'dsh-apk-vm-flows'))).bytes,
+    screenshotsBytes: 0,
+    recordingsBytes: 0,
+    files: 0,
+  };
+  try {
+    const entries = await fsp.readdir(tempRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (!/^(apk-vm-shot-|dsh-apk-vm-record-)/.test(entry.name)) continue;
+      const stat = await fileStatOrNull(path.join(tempRoot, entry.name));
+      if (!stat) continue;
+      temp.files += 1;
+      if (entry.name.startsWith('apk-vm-shot-')) temp.screenshotsBytes += stat.size;
+      else temp.recordingsBytes += stat.size;
+    }
+  } catch {
+    /* ignore */
+  }
+
+  let sdk = null;
+  if (sdkRoot) {
+    const total = await walkSize(sdkRoot);
+    const parts = {};
+    for (const part of ['system-images', 'emulator', 'build-tools', 'platform-tools', 'platforms']) {
+      parts[part] = (await walkSize(path.join(sdkRoot, part))).bytes;
+    }
+    sdk = { root: sdkRoot, totalBytes: total.bytes, totalFiles: total.files, parts };
+  }
+
+  let disk = null;
+  try {
+    const stats = await fsp.statfs(avdRoot || home);
+    disk = {
+      totalBytes: Number(stats.blocks) * Number(stats.bsize),
+      freeBytes: Number(stats.bavail) * Number(stats.bsize),
+      availableBytes: Number(stats.bavail) * Number(stats.bsize),
+      path: avdRoot || home,
+    };
+  } catch {
+    disk = null;
+  }
+  let sdkDisk = null;
+  if (sdkRoot) {
+    try {
+      const stats = await fsp.statfs(sdkRoot);
+      sdkDisk = {
+        totalBytes: Number(stats.blocks) * Number(stats.bsize),
+        freeBytes: Number(stats.bavail) * Number(stats.bsize),
+        path: sdkRoot,
+      };
+    } catch {
+      sdkDisk = null;
+    }
+  }
+
+  const snapshotTotal = avds.reduce((sum, item) => sum + item.snapshotBytes, 0);
+  const tempTotal = temp.uploadsBytes + temp.flowsBytes + temp.screenshotsBytes + temp.recordingsBytes;
+  const recommendations = [];
+  if (snapshotTotal > 1024 * 1024 * 1024) {
+    recommendations.push({
+      code: 'snapshots',
+      bytes: snapshotTotal,
+      text: `Quick-boot snapshots use ${formatBytes(snapshotTotal)}; disable quickBoot/saveSnapshotAfterBoot or delete a snapshot to free it.`,
+    });
+  }
+  if (tempTotal > 0) {
+    recommendations.push({ code: 'temp', bytes: tempTotal, text: `Plugin temp files use ${formatBytes(tempTotal)}; safe to clean.` });
+  }
+  const orphans = avds.filter((item) => item.orphan);
+  if (orphans.length) {
+    recommendations.push({
+      code: 'orphan-avds',
+      bytes: orphans.reduce((sum, item) => sum + item.totalBytes, 0),
+      text: `${orphans.length} orphan dsh_apk_* AVD(s) are not registered to a running instance.`,
+    });
+  }
+
+  return {
+    ok: true,
+    sampledAt: new Date().toISOString(),
+    home,
+    avdRoot,
+    tempRoot,
+    sdk,
+    sdkDisk,
+    avds,
+    temp,
+    disk,
+    totals: {
+      avdBytes: avds.reduce((sum, item) => sum + item.totalBytes, 0),
+      snapshotBytes: snapshotTotal,
+      sdkBytes: sdk ? sdk.totalBytes : 0,
+      tempBytes: tempTotal,
+      freeBytes: disk ? disk.freeBytes : 0,
+    },
+    recommendations,
+    formatter: 'bytes',
+  };
+}
+
+async function removeTree(target) {
+  const existed = await fsp.stat(target).catch(() => null);
+  if (!existed) return 0;
+  const measured = await walkSize(target);
+  await fsp.rm(target, { recursive: true, force: true }).catch(() => {});
+  return measured.bytes;
+}
+
+/** Delete only the plugin's own temporary artifacts. */
+export async function cleanTempFiles(options = {}) {
+  const tempRoot = path.resolve(options.tempRoot || os.tmpdir());
+  let freed = 0;
+  let files = 0;
+  for (const name of ['dsh-apk-vm-uploads', 'dsh-apk-vm-flows']) {
+    const dir = path.join(tempRoot, name);
+    const measured = await walkSize(dir);
+    await removeTree(dir);
+    freed += measured.bytes;
+    files += measured.files;
+  }
+  const entries = await fsp.readdir(tempRoot, { withFileTypes: true }).catch(() => []);
+  for (const entry of entries) {
+    if (!entry.isFile() || !/^(apk-vm-shot-|dsh-apk-vm-record-)/.test(entry.name)) continue;
+    const full = path.join(tempRoot, entry.name);
+    const stat = await fileStatOrNull(full);
+    if (!stat) continue;
+    await fsp.unlink(full).catch(() => {});
+    freed += stat.size;
+    files += 1;
+  }
+  return { ok: true, action: 'temp', freedBytes: freed, files };
+}
+
+/** Delete snapshots for one AVD by name. Refuses active or non-managed AVDs unless forced. */
+export async function cleanSnapshots(options = {}) {
+  const avdRoot = path.resolve(options.avdRoot || path.join(os.homedir(), '.android', 'avd'));
+  const name = String(options.avdName || '').trim();
+  if (!/^[A-Za-z0-9._-]{1,80}$/.test(name)) throw new Error('invalid AVD name');
+  if (name !== 'dsh_apk' && !name.startsWith('dsh_apk_')) {
+    throw new Error('only plugin-managed dsh_apk* AVDs can have snapshots cleaned');
+  }
+  const avdPath = await readAvdIni(avdRoot, name);
+  if (!avdPath.startsWith(avdRoot + path.sep)) throw new Error('AVD path escapes the AVD root');
+  const snapshotsDir = path.join(avdPath, 'snapshots');
+  const measured = await walkSize(snapshotsDir);
+  await removeTree(snapshotsDir);
+  return { ok: true, action: 'snapshots', avdName: name, freedBytes: measured.bytes, files: measured.files };
+}
+
+/** Delete only orphan dsh_apk_* AVDs that are not registered/active. */
+export async function cleanOrphanAvds(options = {}) {
+  const avdRoot = path.resolve(options.avdRoot || path.join(os.homedir(), '.android', 'avd'));
+  const known = new Set((options.knownAvds || []).map(String));
+  const active = new Set((options.activeAvds || []).map(String));
+  const entries = await fsp.readdir(avdRoot, { withFileTypes: true }).catch(() => []);
+  const removed = [];
+  let freed = 0;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.endsWith('.avd')) continue;
+    const name = entry.name.slice(0, -4);
+    if (!name.startsWith('dsh_apk_') || known.has(name) || active.has(name)) continue;
+    const avdPath = path.join(avdRoot, entry.name);
+    // A manually launched emulator may hold a lock even if this plugin does not
+    // know the AVD; never delete a directory with a live-looking lock file.
+    const children = await fsp.readdir(avdPath).catch(() => []);
+    if (children.some((child) => child.endsWith('.lock'))) continue;
+    const measured = await walkSize(avdPath);
+    await fsp.rm(avdPath, { recursive: true, force: true }).catch(() => {});
+    await fsp.unlink(path.join(avdRoot, `${name}.ini`)).catch(() => {});
+    freed += measured.bytes;
+    removed.push({ name, bytes: measured.bytes });
+  }
+  return { ok: true, action: 'orphan-avds', freedBytes: freed, removed };
+}
+
+export { formatBytes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-apk-vm",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "type": "module",
   "description": "Local AOSP Android VM for DeepSeek Harness: preview rooted APKs at up to 60 fps, automate UIAutomator flows, and give each Agent an isolated VM.",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/apk-bundle.js && node --check lib/flows.js && node --check lib/ui-inspector.js && node --check lib/x509.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
+    "check": "node --check index.js && node --check client.js && node --check lib/android.js && node --check lib/apk-bundle.js && node --check lib/flows.js && node --check lib/storage.js && node --check lib/ui-inspector.js && node --check lib/x509.js && node --check lib/scrcpy.js && node --check lib/ws.js && node --check lib/setup.js && node --check lib/instances.js && node --check lib/video-stream.js",
     "privacy": "node scripts/privacy-scan.mjs",
     "test": "node spike/ui-smoke.cjs && node spike/ui-better-sidebar-smoke.cjs && node spike/setup-smoke.mjs && node spike/android/mock-device.mjs && node spike/android/launch-plan.mjs && node spike/instances-smoke.mjs && node spike/features.mjs"
   },
@@ -44,6 +44,7 @@
     "lib/apk-bundle.js",
     "lib/flows.js",
     "lib/scrcpy.js",
+    "lib/storage.js",
     "lib/ui-inspector.js",
     "lib/ws.js",
     "lib/setup.js",