@shidesheng0218/dsh-plugin-lint 0.1.0 → 0.4.0

package/src/matrix/sync.js

@@ -0,0 +1,72 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { sha256 } from '../shared/hash.js';
+import { validateManifest } from './schema.js';
+import { verifyPublicArtifact } from './export.js';
+
+const MAX_FILES = 10000;
+const MAX_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+function safeRelative(path) {
+  return typeof path === 'string' && !path.startsWith('/') && !path.includes('\\') && path !== '..' && !path.startsWith('../') && !path.includes('/../') && !path.includes('\0');
+}
+
+export async function syncMatrix({ source, outDir, fetchImpl = fetch }) {
+  if (!source) throw new ToolError('MATRIX_SOURCE_REQUIRED', 'An explicit matrix source is required.');
+  if (!outDir) throw new ToolError('MATRIX_OUTPUT_REQUIRED', 'An explicit sync output directory is required.');
+  const remote = /^https:\/\//.test(source);
+  const base = remote ? new URL(source.endsWith('/') ? source : source + '/') : realpathSync(source);
+  async function readSource(path) {
+    if (!safeRelative(path)) throw new ToolError('MANIFEST_INVALID', 'The source contains an unsafe artifact path.');
+    if (remote) {
+      const url = new URL(path, base);
+      if (url.protocol !== 'https:') throw new ToolError('MATRIX_SOURCE_UNSUPPORTED', 'Only HTTPS matrix sources are supported.');
+      const response = await fetchImpl(url, { redirect: 'error', signal: AbortSignal.timeout(10000) });
+      if (!response.ok) throw new ToolError('MATRIX_SOURCE_UNAVAILABLE', `The matrix source returned HTTP ${response.status}.`);
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.length > MAX_ARTIFACT_BYTES) throw new ToolError('ARTIFACT_TOO_LARGE', 'A matrix artifact exceeds the size limit.');
+      return bytes;
+    }
+    const pathOnDisk = realpathSync(resolve(base, path));
+    if (pathOnDisk !== base && !pathOnDisk.startsWith(base + sep)) throw new ToolError('MANIFEST_INVALID', 'A source file escapes the source directory.');
+    const bytes = readFileSync(pathOnDisk);
+    if (bytes.length > MAX_ARTIFACT_BYTES) throw new ToolError('ARTIFACT_TOO_LARGE', 'A matrix artifact exceeds the size limit.');
+    return bytes;
+  }
+
+  const manifest = JSON.parse((await readSource('manifest.json')).toString('utf8'));
+  const validation = validateManifest(manifest);
+  if (!validation.ok) throw new ToolError('MANIFEST_INVALID', validation.errors.join('; '));
+  if (manifest.artifacts.length > MAX_FILES) throw new ToolError('ARTIFACT_TOO_LARGE', 'The matrix declares too many files.');
+  const parent = dirname(outDir);
+  mkdirSync(parent, { recursive: true });
+  const staging = mkdtempSync(join(parent, '.sync-'));
+  try {
+    for (const artifact of manifest.artifacts) {
+      const bytes = await readSource(artifact.path);
+      if (bytes.length !== artifact.bytes || sha256(bytes) !== artifact.sha256) {
+        throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', `Artifact integrity mismatch: ${artifact.path}`);
+      }
+      const destination = join(staging, artifact.path);
+      mkdirSync(dirname(destination), { recursive: true });
+      writeFileSync(destination, bytes);
+    }
+    writeFileSync(join(staging, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    const verification = await verifyPublicArtifact({ dir: staging });
+    if (!verification.ok) throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', verification.errors.join('; '));
+    const backup = `${outDir}.backup-${Date.now()}`;
+    if (existsSync(outDir)) renameSync(outDir, backup);
+    try {
+      renameSync(staging, outDir);
+      rmSync(backup, { recursive: true, force: true });
+    } catch (error) {
+      if (existsSync(backup)) renameSync(backup, outDir);
+      throw error;
+    }
+    return { manifest, filesWritten: manifest.artifacts.length + 1 };
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true });
+    throw error;
+  }
+}

package/src/matrix/verify.js

@@ -0,0 +1,152 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+import { PROBE_VERSION } from '../shared/version.js';
+import { readCells, writeCell } from './cells.js';
+import { validateCell } from './schema.js';
+import { resolveArtifact } from '../probe/artifact-resolver.js';
+import { createProbeEnvironment } from '../probe/environment.js';
+import { probePackage } from '../probe/probe.js';
+
+export function sampleCells(cells, { sample = 0.2, seed = 1, all = false } = {}) {
+  if (all) return [...cells];
+  if (sample <= 0) return [];
+  let state = seed;
+  const next = () => (state = (state * 1103515245 + 12345) % 2147483648) / 2147483648;
+  return cells.filter(() => next() < Math.min(1, sample));
+}
+
+function publicError(error) {
+  return { code: error?.code || 'VERIFICATION_FAILED', message: error?.code ? error.message : 'The verification probe could not complete.' };
+}
+
+export async function verifyCells({ cells, probe, verifier = { workflow: 'local', runId: 'local', url: '', probeVersion: PROBE_VERSION }, concurrency = 2 }) {
+  const report = {
+    schemaVersion: 2,
+    at: new Date().toISOString(),
+    checked: 0,
+    confirmed: 0,
+    disputed: 0,
+    errors: 0,
+    cells: [],
+    verifier,
+  };
+  const queue = [...cells];
+  async function worker() {
+    while (queue.length > 0) {
+      const cell = queue.shift();
+      const entry = {
+        cacheKey: cell.cacheKey,
+        plugin: cell.plugin.name,
+        dsh: cell.dsh.version,
+        composition: cell.dsh.composition,
+        reported: { status: cell.result.status },
+        verification: verifier,
+      };
+      try {
+        const observation = await probe(cell);
+        if (observation.outcome === 'error') {
+          entry.verdict = 'error';
+          entry.error = observation.error;
+          report.errors += 1;
+        } else {
+          entry.observed = { status: observation.result.status };
+          entry.verdict = observation.result.status === cell.result.status ? 'confirmed' : 'disputed';
+          if (entry.verdict === 'confirmed') report.confirmed += 1;
+          else report.disputed += 1;
+        }
+      } catch (error) {
+        entry.verdict = 'error';
+        entry.error = publicError(error);
+        report.errors += 1;
+      }
+      report.cells.push(entry);
+      report.checked += 1;
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(Math.max(1, concurrency), Math.max(1, queue.length)) }, worker));
+  return report;
+}
+
+export async function verifyMatrix({ cellsDir, sample = 0.2, seed = 1, all = false, concurrency = 2, probe, verifier }) {
+  const reads = readCells(cellsDir);
+  const damaged = reads.filter((entry) => !entry.ok);
+  if (damaged.length > 0) throw new ToolError('VERIFICATION_INPUT_INVALID', `Cannot read ${damaged.length} cell file(s).`);
+  const candidates = reads.filter((entry) => entry.kind === 'v2' && entry.cell.run.trust !== 'verified').map((entry) => entry.cell);
+  const selected = sampleCells(candidates, { sample, seed, all });
+  const report = await verifyCells({ cells: selected, probe, verifier, concurrency });
+  report.seed = seed;
+  report.sample = sample;
+  return report;
+}
+
+export function createVerificationProbe({ cacheRoot, backend = 'auto' }) {
+  return async (cell) => {
+    const artifact = await resolveArtifact({
+      name: cell.plugin.name,
+      version: cell.plugin.resolvedVersion,
+      integrity: cell.plugin.integrity,
+      ...(cell.plugin.local ? { path: cell.plugin.path, local: true } : {}),
+    });
+    const environment = await createProbeEnvironment({
+      backend,
+      workDir: cacheRoot,
+      dshDir: cell.dsh.source === 'desktop' ? undefined : join(cacheRoot, 'dsh', cell.dsh.version),
+    });
+    const dsh = {
+      kind: cell.dsh.source === 'desktop' ? 'desktop' : 'npm',
+      version: cell.dsh.version,
+      source: cell.dsh.source,
+      composition: cell.dsh.composition,
+    };
+    return probePackage({ artifact, dsh, environment, tools: cell.dsh.composition !== 'web', composition: cell.dsh.composition, audit: true });
+  };
+}
+
+export function applyVerification(cell, reportEntry, { trustedVerifier = false } = {}) {
+  if (cell.schemaVersion !== 2) throw new ToolError('CELL_SCHEMA_UNSUPPORTED', 'Only v2 cells can accept verification.');
+  if (cell.cacheKey !== reportEntry.cacheKey) throw new ToolError('VERIFICATION_KEY_MISMATCH', 'The verification belongs to a different artifact or composition.');
+  if (cell.run.outcome !== 'completed' || reportEntry.reported?.status !== cell.result?.status) {
+    throw new ToolError('VERIFICATION_REPORT_MISMATCH', 'The verification does not match the reported observation.');
+  }
+  if (reportEntry.verdict === 'error') throw new ToolError('VERIFICATION_INCOMPLETE', 'Infrastructure errors are not plugin observations.');
+  const updated = structuredClone(cell);
+  const verification = reportEntry.verification;
+  if (reportEntry.verdict === 'disputed' || reportEntry.observed?.status !== cell.result.status) {
+    updated.run.trust = 'disputed';
+    updated.run.dispute = { reported: cell.result.status, observed: reportEntry.observed.status };
+    updated.run.disputedAt = new Date().toISOString();
+    if (verification) updated.run.verification = verification;
+  } else if (reportEntry.verdict === 'confirmed') {
+    if (trustedVerifier) {
+      if (!verification || typeof verification.workflow !== 'string' || !verification.workflow
+        || typeof verification.runId !== 'string' || !verification.runId
+        || typeof verification.url !== 'string' || !verification.url
+        || verification.probeVersion !== cell.probe.version) {
+        throw new ToolError('VERIFIER_IDENTITY_INVALID', 'Trusted verification needs complete workflow provenance and a matching probe version.');
+      }
+      updated.run.trust = 'verified';
+      updated.run.verification = verification;
+      updated.run.verifiedAt = new Date().toISOString();
+      delete updated.run.dispute;
+    } else {
+      updated.run.trust = cell.run.trust;
+    }
+  } else {
+    throw new ToolError('VERIFICATION_INCOMPLETE', 'The verification has no completed observed status.');
+  }
+  const validation = validateCell(updated);
+  if (!validation.ok) throw new ToolError('CELL_INVALID', validation.errors.join('; '));
+  return updated;
+}
+
+export async function runVerification({ cellsDir, cacheRoot, sample = 0.2, seed = 1, all = false, concurrency = 2, backend = 'auto', workflow = 'local', runId = 'local', runUrl = '', out }) {
+  const probe = createVerificationProbe({ cacheRoot, backend });
+  const verifier = { workflow, runId, url: runUrl, probeVersion: PROBE_VERSION };
+  const report = await verifyMatrix({ cellsDir, sample, seed, all, concurrency, probe, verifier });
+  if (out) {
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, JSON.stringify(report, null, 2) + '\n');
+  }
+  return { report, out };
+}

package/src/performance.js

@@ -0,0 +1 @@
+export * from './experimental/performance.js';

package/src/probe/artifact-resolver.js

@@ -0,0 +1,161 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { ToolError } from '../shared/errors.js';
+
+const REGISTRY = 'https://registry.npmjs.org/';
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/i;
+
+function parseSpec(value) {
+  const text = String(value);
+  const split = text.startsWith('@') ? text.lastIndexOf('@') > text.indexOf('/') : text.lastIndexOf('@') > 0;
+  if (!split) return { name: text, version: 'latest' };
+  const index = text.lastIndexOf('@');
+  return { name: text.slice(0, index), version: text.slice(index + 1) || 'latest' };
+}
+
+function validateName(name) {
+  if (typeof name !== 'string' || !PACKAGE_NAME.test(name)) {
+    throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'The artifact package name is invalid.');
+  }
+}
+
+function validateRequestedVersion(version) {
+  if (EXACT_VERSION.test(version)) return version;
+  if (/^[A-Za-z][A-Za-z0-9._-]*$/.test(version)) return version;
+  throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', `Artifact version ranges are not reproducible inputs: ${version}`);
+}
+
+function localArtifact(target) {
+  const root = resolve(target.path || target);
+  const manifestPath = join(root, 'package.json');
+  let manifest;
+  try {
+    if (!statSync(root).isDirectory()) throw new Error('not a directory');
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_SPEC_UNSUPPORTED', 'Local artifacts must be package directories with a readable package.json.', { cause });
+  }
+  const name = manifest.name || target.name;
+  validateName(name);
+  if (!EXACT_VERSION.test(manifest.version || '')) {
+    throw new ToolError('ARTIFACT_METADATA_MISMATCH', 'The local package manifest has no exact version.');
+  }
+  const hash = createHash('sha256');
+  function walk(current) {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === '.git' || entry.name === 'node_modules') continue;
+      const absolute = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolute);
+      } else if (entry.isFile()) {
+        const relative = absolute.slice(root.length + 1).replace(/\\/g, '/');
+        hash.update(relative);
+        hash.update('\0');
+        hash.update(readFileSync(absolute));
+        hash.update('\0');
+      }
+    }
+  }
+  walk(root);
+  return {
+    name,
+    requestedVersion: 'local',
+    resolvedVersion: manifest.version,
+    integrity: undefined,
+    tarballUrl: undefined,
+    installTarget: root,
+    local: true,
+    path: root,
+    sourceDigest: hash.digest('hex'),
+  };
+}
+
+export async function resolveArtifact(target, { fetchImpl = fetch } = {}) {
+  if ((typeof target === 'string' && existsSync(target)) || (target && typeof target === 'object' && (target.local || target.path))) {
+    return localArtifact(target);
+  }
+  const input = typeof target === 'string' ? parseSpec(target) : { name: target?.name, version: target?.version ?? 'latest', integrity: target?.integrity };
+  validateName(input.name);
+  const requestedVersion = validateRequestedVersion(input.version || 'latest');
+  const url = REGISTRY + encodeURIComponent(input.name);
+  let response;
+  try {
+    response = await fetchImpl(url, { headers: { accept: 'application/vnd.npm.install-v1+json' } });
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The npm registry could not be read.', { cause });
+  }
+  if (!response?.ok) throw new ToolError('ARTIFACT_REGISTRY_ERROR', `The npm registry returned HTTP ${response?.status ?? 'unknown'}.`);
+  let metadata;
+  try {
+    metadata = await response.json();
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The npm registry returned invalid JSON.', { cause });
+  }
+  const resolvedVersion = EXACT_VERSION.test(requestedVersion)
+    ? requestedVersion
+    : metadata?.['dist-tags']?.[requestedVersion];
+  if (!EXACT_VERSION.test(resolvedVersion || '')) {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', `The registry did not provide an exact version for ${input.name}@${requestedVersion}.`);
+  }
+  const versionMetadata = metadata?.versions?.[resolvedVersion];
+  if (!versionMetadata || (versionMetadata.version !== undefined && versionMetadata.version !== resolvedVersion)) {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The registry metadata does not contain the resolved version.');
+  }
+  const integrity = versionMetadata?.dist?.integrity;
+  const tarballUrl = versionMetadata?.dist?.tarball;
+  if (typeof integrity !== 'string' || typeof tarballUrl !== 'string') {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The registry artifact is missing tarball or integrity metadata.');
+  }
+  let parsedTarball;
+  try {
+    parsedTarball = new URL(tarballUrl);
+  } catch (cause) {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The registry returned an invalid tarball URL.', { cause });
+  }
+  if (parsedTarball.protocol !== 'https:' || parsedTarball.hostname !== 'registry.npmjs.org') {
+    throw new ToolError('ARTIFACT_REGISTRY_ERROR', 'The registry returned a tarball outside the explicit registry origin.');
+  }
+  if (input.integrity !== undefined && input.integrity !== integrity) {
+    throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', 'The target integrity differs from the registry metadata.');
+  }
+  return {
+    name: input.name,
+    requestedVersion,
+    resolvedVersion,
+    integrity,
+    tarballUrl,
+    installTarget: `${input.name}@${resolvedVersion}`,
+    local: false,
+    sourceDigest: integrity,
+  };
+}
+
+export function verifyIntegrity(bytes, integrity) {
+  if (typeof integrity !== 'string') return false;
+  const match = /^([A-Za-z0-9]+)-([A-Za-z0-9+/=]+)$/.exec(integrity);
+  if (!match || !['sha256', 'sha384', 'sha512'].includes(match[1])) return false;
+  try {
+    const actual = createHash(match[1]).update(bytes).digest();
+    const expected = Buffer.from(match[2], 'base64');
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+  } catch {
+    return false;
+  }
+}
+
+export async function downloadArtifact(artifact, { fetchImpl = fetch, destination } = {}) {
+  if (artifact.local) return { ...artifact, tarballPath: artifact.path };
+  const response = await fetchImpl(artifact.tarballUrl);
+  if (!response?.ok) throw new ToolError('ARTIFACT_DOWNLOAD_FAILED', `The artifact download returned HTTP ${response?.status ?? 'unknown'}.`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (!verifyIntegrity(bytes, artifact.integrity)) {
+    throw new ToolError('ARTIFACT_INTEGRITY_MISMATCH', 'The downloaded artifact does not match its pinned integrity.');
+  }
+  const target = destination || join(mkdtempSync(join(tmpdir(), 'dsh-artifact-')), basename(artifact.tarballUrl));
+  mkdirSync(join(target, '..'), { recursive: true });
+  writeFileSync(target, bytes);
+  return { ...artifact, tarballPath: target };
+}

package/src/probe/classify.js

@@ -0,0 +1,8 @@
+export function classify(bootText, entries, completionSignal) {
+  const failing = entries.filter((entry) => !/waiting for service/.test(entry.reason || ''));
+  if (failing.length > 0) return 'inactive-error';
+  if (entries.length > 0) return 'awaiting-service';
+  if (completionSignal === true) return 'active';
+  if (completionSignal === false) return 'boot-failed';
+  return /MISSING_CREDENTIAL/.test(bootText) ? 'active' : 'boot-failed';
+}

package/src/probe/dsh-adapter.js

@@ -0,0 +1,212 @@
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { ToolError } from '../shared/errors.js';
+
+const execFileAsync = promisify(execFile);
+const DESKTOP_ELECTRON = process.env.DSH_ELECTRON || '/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness';
+const DESKTOP_CLI = process.env.DSH_CLI || '/Applications/DeepSeek Harness.app/Contents/Resources/app.asar/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js';
+const DESKTOP_APP = '/Applications/DeepSeek Harness.app';
+const AMBIENT_KEYS = ['PATH', 'HOME', 'NO_COLOR', 'LANG', 'LC_ALL', 'LC_CTYPE'];
+const EXPLICIT_KEYS = new Set([...AMBIENT_KEYS, 'DSH_HOME', 'ELECTRON_RUN_AS_NODE', 'PROBE_API_KEY', 'NARB_DISABLE_NATIVE_CACHE', 'npm_config_cache']);
+
+export function safeEnv(overrides = {}) {
+  const env = {};
+  for (const key of AMBIENT_KEYS) {
+    if (typeof process.env[key] === 'string') env[key] = process.env[key];
+  }
+  for (const [key, value] of Object.entries(overrides)) {
+    if (EXPLICIT_KEYS.has(key) && value !== undefined) env[key] = String(value);
+  }
+  return env;
+}
+
+export function execFileRunner(command, args, options = {}) {
+  return execFileAsync(command, args, {
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+    ...options,
+  });
+}
+
+/**
+ * In-flight container harness installs, keyed by the shared dshDir. Matrix cells
+ * with the same DSH version reuse one install instead of racing four downloads
+ * into the same tree.
+ */
+const dockerDshInstalls = new Map();
+
+export async function resolveDsh(version, cacheRoot, { runner = execFileRunner, environment } = {}) {
+  if (!version || version === 'desktop') {
+    // The CLI lives inside app.asar, which existsSync cannot traverse; check the
+    // app bundle (or an explicit override) instead.
+    const available = Boolean(process.env.DSH_CLI) || existsSync(DESKTOP_APP) || existsSync(DESKTOP_CLI);
+    if (!available) {
+      throw new ToolError('DSH_NOT_FOUND', 'The desktop DSH was not found; pass --dsh <npm-version> to use the Docker backend.');
+    }
+    return { id: 'desktop', kind: 'desktop', version: 'desktop', node: DESKTOP_ELECTRON, cli: DESKTOP_CLI, extraArgs: ['--expose-internals'] };
+  }
+  if (environment?.isolation === 'docker') {
+    const dir = environment.dshDir;
+    const cli = join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
+    if (!existsSync(cli)) {
+      let pending = dockerDshInstalls.get(dir);
+      if (!pending) {
+        pending = (async () => {
+          await environment.boot({
+            dsh: { kind: 'npm', cli: '/usr/local/lib/node_modules/npm/bin/npm-cli.js', extraArgs: [] },
+            args: [
+              'install', '--prefix', '/dsh', '--no-audit', '--no-fund', '--silent',
+              // The shared tool volume keeps the harness tarballs across cells
+              // and across DSH versions instead of downloading them again.
+              '--cache', '/tools/npm', '--registry=https://registry.npmjs.org/',
+              '@deepseek-ai/dsh@' + version,
+            ],
+            env: { HOME: '/profile' },
+            network: 'registry',
+            writableDsh: true,
+            // Installing the harness is a one-time cold-cache download. A cold run can
+            // take 15 minutes on a slow network; the normal boot timeout is far
+            // too short for it.
+            timeoutMs: 1200000,
+          });
+        })().finally(() => dockerDshInstalls.delete(dir));
+        dockerDshInstalls.set(dir, pending);
+      }
+      await pending;
+    }
+    if (!existsSync(cli)) throw new ToolError('ARTIFACT_MISSING', 'DSH installation did not produce the expected CLI.');
+    return {
+      id: 'npm:' + version,
+      kind: 'npm',
+      version,
+      node: process.execPath,
+      cli,
+      containerNode: 'node',
+      containerCli: '/dsh/node_modules/@deepseek-ai/dsh/lib/bin.js',
+      extraArgs: [],
+    };
+  }
+  const dir = join(cacheRoot, 'dsh', version);
+  const cli = join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
+  if (!existsSync(cli)) {
+    const home = join(dir, 'home');
+    mkdirSync(home, { recursive: true });
+    await runner('npm', [
+      'install', '--prefix', dir, '--no-audit', '--no-fund', '--silent',
+      '--cache', join(dir, 'npm-cache'), '--registry=https://registry.npmjs.org/',
+      '@deepseek-ai/dsh@' + version,
+    ], { env: safeEnv({ HOME: home }), timeout: 600000, maxBuffer: 16 * 1024 * 1024 });
+  }
+  if (!existsSync(cli)) throw new ToolError('ARTIFACT_MISSING', 'DSH installation did not produce the expected CLI.');
+  return { id: 'npm:' + version, kind: 'npm', version, node: process.execPath, cli, extraArgs: [] };
+}
+
+export function startStub() {
+  const seen = [];
+  const server = createServer((req, res) => {
+    let raw = '';
+    req.on('data', (chunk) => { raw += chunk; });
+    req.on('end', () => {
+      let body = null;
+      try { body = JSON.parse(raw); } catch { /* keep null */ }
+      if (body) seen.push(body);
+      if (!body || !body.stream) {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({
+          id: 'msg_probe', type: 'message', role: 'assistant', model: body?.model || 'probe',
+          content: [{ type: 'text', text: 'ok' }], stop_reason: 'end_turn', stop_sequence: null,
+          usage: { input_tokens: 1, output_tokens: 1 },
+        }));
+        return;
+      }
+      const sse = (event, data) => res.write('event: ' + event + '\ndata: ' + JSON.stringify(data) + '\n\n');
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
+      sse('message_start', { type: 'message_start', message: { id: 'msg_probe', type: 'message', role: 'assistant', model: body.model || 'probe', content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 1, output_tokens: 1 } } });
+      sse('content_block_start', { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } });
+      sse('content_block_delta', { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'ok' } });
+      sse('content_block_stop', { type: 'content_block_stop', index: 0 });
+      sse('message_delta', { type: 'message_delta', delta: { stop_reason: 'end_turn', stop_sequence: null }, usage: { output_tokens: 1 } });
+      sse('message_stop', { type: 'message_stop' });
+      res.end();
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve({ server, seen, port: server.address().port }));
+  });
+}
+
+export async function runDsh(dsh, home, args, env = {}, { runner = execFileRunner, timeoutMs = 180000 } = {}) {
+  const { stdout, stderr } = await runner(dsh.node, [...dsh.extraArgs, dsh.cli, ...args], {
+    env: safeEnv({ DSH_HOME: home, ...(dsh.kind === 'desktop' ? { ELECTRON_RUN_AS_NODE: '1' } : {}), ...env }),
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+    timeout: timeoutMs,
+  });
+  return String(stdout || '') + String(stderr || '');
+}
+
+export function runUntilReady(dsh, home, args, env, readyRe, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 90000;
+  const graceMs = options.graceMs ?? 2500;
+  const spawnImpl = options.spawnImpl || spawn;
+  return new Promise((resolve) => {
+    const child = spawnImpl(dsh.node, [...dsh.extraArgs, dsh.cli, ...args], {
+      env: safeEnv({ DSH_HOME: home, ...(dsh.kind === 'desktop' ? { ELECTRON_RUN_AS_NODE: '1' } : {}), ...env }),
+      detached: process.platform !== 'win32',
+    });
+    let out = '';
+    let finished = false;
+    let readyScheduled = false;
+    // Keep the grace and timeout timers referenced until the promise settles.
+    // An unref'd timer does not keep the event loop alive, so on a fast or
+    // containerized scheduler the loop can be considered idle — and the test
+    // runner cancels the pending promise — before the grace timer fires. The
+    // timers are cleared in finish(), so referencing them here changes nothing
+    // about how long the process lives once the child is done.
+    const timers = new Set();
+    const later = (fn, ms) => {
+      const timer = setTimeout(() => { timers.delete(timer); fn(); }, ms);
+      timers.add(timer);
+      return timer;
+    };
+    const signal = (name) => {
+      if (child.pid && process.platform !== 'win32') {
+        try { process.kill(-child.pid, name); return; } catch { /* fall back to the direct child */ }
+      }
+      child.kill(name);
+    };
+    const finish = () => {
+      if (finished) return;
+      finished = true;
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      signal('SIGTERM');
+      // The SIGKILL backstop is best-effort cleanup after resolve: it stays
+      // unref'd so it never extends the process lifetime past settlement.
+      setTimeout(() => signal('SIGKILL'), 1500).unref();
+      resolve(out);
+    };
+    const feed = (chunk) => {
+      out += chunk;
+      if (!readyScheduled && readyRe.test(out)) {
+        readyScheduled = true;
+        later(finish, graceMs);
+      }
+    };
+    child.stdout.on('data', feed);
+    child.stderr.on('data', feed);
+    child.on('exit', () => {
+      if (finished) return;
+      finished = true;
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      resolve(out);
+    });
+    later(finish, timeoutMs);
+  });
+}
+
+export const WEB_READY = /dsh web:\s*https?:\/\//;