@1e0zj/dsh-plugin-mall 0.1.18 → 0.2.1

package/src/index.js

@@ -15,12 +15,17 @@
 
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, realpathSync, mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
 import { resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
-import { repoInfo, searchPlugins, verifyPlugins, preferNpmSpec, npmPackageInfo, compareVersions, assertSafeToInstall, mapLimit, NETWORK_CONCURRENCY } from "./github.js";
-import { ensureProfile, listInstalled, normalizeSpec, runInstall, runRemove, createJobTracker, assertSafeSpec, resolveRegistry } from "./installer.js";
+import { repoInfo, searchPlugins, verifyPlugins, cachedRepoManifest, fetchRawFile, preferNpmSpec, npmPackageInfo, compareVersions, assertSafeToInstall, mapLimit, NETWORK_CONCURRENCY } from "./github.js";
+import { ensureProfile, listInstalled, normalizeSpec, runInstall, runRemove, assertSafeSpec, resolveRegistry, serializeCanonicalProof } from "./installer.js";
+import { preflightInstall, inspectRemoteCandidate, recoverProfile } from "./guard.js";
 
 export const name = "@1e0zj/dsh-plugin-mall";
 export const inject = ["tools", "jobs", "systemPrompt"];
@@ -45,6 +50,952 @@ async function registryFor(profile, npmRegistry) {
   return explicit.length > 0 ? explicit.replace(/\/+$/, "") : await resolveRegistry(profile);
 }
 
+// ── profile-state fingerprinting & preflight cache (guard.js) ───────────────
+//
+// Every install path — the /market RPC channel AND the market_install agent
+// tool — runs the same preflight before a job starts: the candidate is
+// installed into a disposable directory with scripts disabled and compared
+// against the profile (manifest + patch conflict scan). A blocker refuses the
+// install; a warning requires explicit user confirmation.
+//
+// Preflight cache/pin reuse is strictly bound to a fingerprint of protected
+// profile files and installed direct dependency state. Before reuse, the
+// fingerprint is recomputed; any profile change invalidates and reruns.
+
+const PREFLIGHT_TTL = 30000; // 30s — short TTL for preflight-then-install round trip
+const PIN_TTL = 600000; // 10 min — the approval-retry window
+const NPM_PACKAGE_NAME_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+
+function directPackageJsonPath(packageName, profileDir) {
+  if (typeof packageName !== "string" || !NPM_PACKAGE_NAME_RE.test(packageName)) return undefined;
+  const modulesRoot = resolve(profileDir, "node_modules");
+  const direct = resolve(modulesRoot, ...packageName.split("/"), "package.json");
+  const rel = relative(modulesRoot, direct);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  if (existsSync(direct)) return direct;
+  return undefined;
+}
+
+/**
+ * Deterministic fingerprint of protected profile files and installed direct
+ * dependency state. Inspects ONLY <profile>/node_modules/<dep>/package.json,
+ * requires exact manifest.name, and never falls back to ancestor Node resolution.
+ */
+export function computeProfileFingerprint(profileDir) {
+  const hash = createHash("sha256");
+  const protectedFiles = ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "cordis.patch.yml"];
+  for (const filename of protectedFiles) {
+    const fullPath = join(profileDir, filename);
+    if (existsSync(fullPath)) {
+      try {
+        const content = readFileSync(fullPath);
+        hash.update(`${filename}:present:${content.length}\0`);
+        hash.update(content);
+      } catch (err) {
+        hash.update(`${filename}:error:${err?.message ?? String(err)}\0`);
+      }
+    } else {
+      hash.update(`${filename}:missing\0`);
+    }
+  }
+
+  const manifestPath = join(profileDir, "package.json");
+  if (existsSync(manifestPath)) {
+    try {
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      const deps = Object.keys(manifest.dependencies ?? {}).sort();
+      for (const dep of deps) {
+        const declaredVersion = manifest.dependencies[dep];
+        hash.update(`dep:${dep}=${declaredVersion}\0`);
+        const depPkgPath = directPackageJsonPath(dep, profileDir);
+        if (depPkgPath && existsSync(depPkgPath)) {
+          try {
+            const depManifest = JSON.parse(readFileSync(depPkgPath, "utf8"));
+            if (depManifest && typeof depManifest === "object" && depManifest.name === dep) {
+              hash.update(`installed:${dep}@${depManifest.version ?? "unknown"}\0`);
+            } else {
+              hash.update(`installed:${dep}:corrupt\0`);
+            }
+          } catch {
+            hash.update(`installed:${dep}:corrupt\0`);
+          }
+        } else {
+          hash.update(`installed:${dep}:missing\0`);
+        }
+      }
+    } catch {
+      hash.update("manifest:corrupt\0");
+    }
+  }
+
+  return hash.digest("hex");
+}
+
+// `${profileDir}\u0000${spec}` -> { report, fingerprint, at, pinnedAt }
+// ── browsing-time compat badge cache ────────────────────────────────────────
+// `${fingerprint}::${repo}` -> { entry, at }. Keyed by the profile fingerprint
+// so any install/uninstall/profile edit invalidates every badge at once; the
+// TTL only bounds how long a badge survives the plugin repo itself changing.
+const compatCache = new Map();
+const COMPAT_TTL = 600000;
+
+function compatCacheGet(key) {
+  const cached = compatCache.get(key);
+  if (cached === undefined) return undefined;
+  if (Date.now() - cached.at > COMPAT_TTL) {
+    compatCache.delete(key);
+    return undefined;
+  }
+  return cached.entry;
+}
+
+function compatCacheSet(key, entry) {
+  if (compatCache.size > 500) compatCache.clear();
+  compatCache.set(key, { entry, at: Date.now() });
+}
+
+const preflightCache = new Map();
+
+function preflightCacheKey(profileDir, spec) {
+  return `${profileDir}\u0000${spec}`;
+}
+
+/** Whether a cache entry is pinned and still inside the approval-retry window. */
+function isPinned(cached) {
+  return cached?.pinnedAt !== undefined && Date.now() - cached.pinnedAt < PIN_TTL;
+}
+
+/** Drop cached preflights for one profile. */
+function invalidatePreflightFor(profileDir) {
+  const prefix = `${profileDir}\u0000`;
+  for (const key of [...preflightCache.keys()]) {
+    if (key.startsWith(prefix)) preflightCache.delete(key);
+  }
+}
+
+/**
+ * Keep a spec's preflight report alive past the TTL for the approval-retry
+ * window. Re-checks the profile fingerprint before pinning; report-only,
+ * never caches warning consent.
+ */
+function pinPreflight(profileDir, spec) {
+  const key = preflightCacheKey(profileDir, spec);
+  const cached = preflightCache.get(key);
+  if (cached === undefined) return;
+  const currentFingerprint = computeProfileFingerprint(profileDir);
+  if (cached.fingerprint !== currentFingerprint) {
+    preflightCache.delete(key);
+    return;
+  }
+  cached.pinnedAt = Date.now();
+}
+
+/**
+ * Run the isolated preflight for a resolved install spec, reusing a fresh
+ * cache entry ONLY if the profile fingerprint matches.
+ */
+async function runPreflight({ profile, spec, force = false, onOutput }) {
+  let profileDir;
+  try {
+    profileDir = resolveProfileDir(profile);
+  } catch (error) {
+    throw new Error(`invalid profile: ${error.message}`);
+  }
+  if (!existsSync(join(profileDir, "package.json"))) ensureProfile(profile);
+
+  const currentFingerprint = computeProfileFingerprint(profileDir);
+  const key = preflightCacheKey(profileDir, spec);
+  const cached = preflightCache.get(key);
+
+  if (cached !== undefined && cached.fingerprint !== currentFingerprint) {
+    preflightCache.delete(key);
+  }
+
+  const validCached = preflightCache.get(key);
+  const fresh = validCached !== undefined
+    && validCached.fingerprint === currentFingerprint
+    && (isPinned(validCached) || Date.now() - validCached.at < PREFLIGHT_TTL);
+
+  if (!force && fresh) {
+    return { report: validCached.report, profileDir, fingerprint: currentFingerprint };
+  }
+
+  const report = await preflightInstall({ profileDir, spec, onOutput });
+  preflightCache.set(key, {
+    report,
+    fingerprint: currentFingerprint,
+    at: Date.now(),
+    pinnedAt: undefined,
+  });
+  return { report, profileDir, fingerprint: currentFingerprint };
+}
+
+// ── opaque one-shot approval tokens ─────────────────────────────────────────
+//
+// Warning consent must NOT be cached before a real needsApproval result.
+// When an install started with explicit warning consent pauses for install-script
+// approval, backend issues an opaque one-shot approval token bound to:
+//   - profile (and resolved profileDir)
+//   - canonical spec & preflight report digest
+//   - exact requested build package set
+//   - current profile-state fingerprint
+//   - surface/session (browser vs agent/owner)
+//
+// The build-approval retry atomically consumes this token. Any failure, cancel,
+// or profile mutation invalidates consent. No cross-surface/agent reuse.
+
+function canonicalizeForDigest(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeForDigest);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalizeForDigest(value[key])]));
+  }
+  return value;
+}
+
+function sha256Canonical(value) {
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(canonicalizeForDigest(value ?? null)));
+  return hash.digest("hex");
+}
+
+export function digestPreflightReport(report) {
+  return sha256Canonical(report);
+}
+
+const approvalTokens = new Map();
+
+export function issueApprovalToken({
+  profile,
+  profileDir,
+  spec,
+  preflightReport,
+  needsApproval,
+  proof,
+  surface,
+  owner,
+  warningConsentActive = false,
+  acceptWarningsActive = false,
+}) {
+  if (!profileDir || !existsSync(profileDir)) throw new Error("cannot issue approval token without an existing profile directory");
+  const token = `mkt-appr-${randomBytes(24).toString("hex")}`;
+  const reportDigest = digestPreflightReport(preflightReport);
+  const packageNames = new Set();
+  for (const item of Array.isArray(needsApproval) ? needsApproval : []) {
+    const name = typeof item === "string" ? item.trim() : (typeof item?.name === "string" ? item.name.trim() : "");
+    if (name.length > 0 && NPM_PACKAGE_NAME_RE.test(name)) {
+      packageNames.add(name);
+    }
+  }
+  const requestedPackages = [...packageNames].sort();
+  if (requestedPackages.length === 0) {
+    throw new Error("cannot issue approval token without a valid install-script package name");
+  }
+  const proofSerialized = serializeCanonicalProof(proof);
+  let canonicalProof;
+  try {
+    canonicalProof = JSON.parse(proofSerialized);
+  } catch {
+    throw new Error("cannot issue approval token without a canonical materialized artifact proof");
+  }
+  const validHash = (value) => typeof value === "string" && /^[0-9a-f]{64}$/i.test(value);
+  if (
+    !NPM_PACKAGE_NAME_RE.test(canonicalProof?.candidate?.name ?? "")
+    || !validHash(canonicalProof?.candidate?.contentHash)
+    || !Array.isArray(canonicalProof?.blockedPackages)
+    || canonicalProof.blockedPackages.length === 0
+    || canonicalProof.blockedPackages.some((entry) => (
+      !NPM_PACKAGE_NAME_RE.test(entry?.name ?? "")
+      || typeof entry?.selector !== "string"
+      || entry.selector.length === 0
+      || !validHash(entry?.contentHash)
+    ))
+  ) {
+    throw new Error("cannot issue approval token with an invalid or empty materialized artifact proof");
+  }
+  const proofNames = [...new Set(canonicalProof.blockedPackages.map((entry) => entry.name))].sort();
+  if (JSON.stringify(proofNames) !== JSON.stringify(requestedPackages)) {
+    throw new Error("approval disclosure package names do not match the materialized artifact proof");
+  }
+  const normalizeSecurityDisclosure = (entry) => ({
+    name: String(entry?.name ?? ""),
+    version: String(entry?.version ?? ""),
+    selector: String(entry?.selector ?? ""),
+    direct: Boolean(entry?.direct),
+    scripts: Object.fromEntries(["preinstall", "install", "postinstall"]
+      .filter((key) => typeof entry?.scripts?.[key] === "string")
+      .map((key) => [key, entry.scripts[key]])),
+    contentHash: String(entry?.contentHash ?? ""),
+  });
+  const disclosedSecurity = (Array.isArray(needsApproval) ? needsApproval : [])
+    .map(normalizeSecurityDisclosure)
+    .sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version) || a.selector.localeCompare(b.selector));
+  const provedSecurity = canonicalProof.blockedPackages
+    .map(normalizeSecurityDisclosure)
+    .sort((a, b) => a.name.localeCompare(b.name) || a.version.localeCompare(b.version) || a.selector.localeCompare(b.selector));
+  if (JSON.stringify(disclosedSecurity) !== JSON.stringify(provedSecurity)) {
+    throw new Error("approval disclosure identity, scripts, or content hash does not match the materialized artifact proof");
+  }
+  const disclosureSerialized = JSON.stringify(canonicalizeForDigest(needsApproval));
+  const profileFingerprint = computeProfileFingerprint(profileDir);
+  const warningConsent = Boolean(warningConsentActive || acceptWarningsActive);
+
+  const realProfileDir = realpathSync(profileDir);
+
+  const record = {
+    token,
+    profile,
+    profileDir,
+    realProfileDir,
+    spec,
+    reportDigest,
+    requestedPackages,
+    disclosureSerialized,
+    disclosureDigest: createHash("sha256").update(disclosureSerialized).digest("hex"),
+    proofSerialized,
+    proofDigest: createHash("sha256").update(proofSerialized).digest("hex"),
+    profileFingerprint,
+    surface, // "browser" | "agent"
+    owner: owner ?? "",
+    warningConsent,
+    issuedAt: Date.now(),
+    expiresAt: Date.now() + PIN_TTL,
+  };
+
+  approvalTokens.set(token, record);
+  return token;
+}
+
+export function assertValidApprovalInvocation(allowBuildScripts, approvalToken) {
+  const hasAllow = Array.isArray(allowBuildScripts) && allowBuildScripts.length > 0;
+  const hasToken = typeof approvalToken === "string" && approvalToken.trim().length > 0;
+  if (hasAllow && !hasToken) {
+    throw new Error("allowBuildScripts cannot be specified on initial install — it can only be used on retry with a valid approval token issued after install-script approval is required");
+  }
+}
+
+export function consumeApprovalToken({
+  token,
+  profile,
+  profileDir,
+  spec,
+  preflightReport,
+  allowBuildScripts,
+  surface,
+  owner,
+}) {
+  if (typeof token !== "string" || token.trim().length === 0) {
+    return { valid: false, reason: "missing approval token" };
+  }
+  const cleanToken = token.trim();
+  const record = approvalTokens.get(cleanToken);
+  if (record === undefined) {
+    return { valid: false, reason: "invalid or already consumed approval token" };
+  }
+
+  // Atomically delete token on validation to guarantee one-shot
+  approvalTokens.delete(cleanToken);
+
+  if (Date.now() > record.expiresAt) {
+    return { valid: false, reason: "approval token expired" };
+  }
+  if (record.profile !== profile) {
+    return { valid: false, reason: "approval token profile mismatch" };
+  }
+  if (record.spec !== spec) {
+    return { valid: false, reason: "approval token spec mismatch" };
+  }
+  if (record.realProfileDir && profileDir && existsSync(profileDir)) {
+    try {
+      const currentReal = realpathSync(profileDir);
+      if (record.realProfileDir !== currentReal) {
+        return { valid: false, reason: "approval token profile directory mismatch" };
+      }
+    } catch {
+      return { valid: false, reason: "approval token profile directory mismatch" };
+    }
+  }
+  if (record.surface !== surface) {
+    return { valid: false, reason: "approval token surface mismatch (cannot reuse between browser and agent)" };
+  }
+  if (record.owner !== (owner ?? "")) {
+    return { valid: false, reason: `approval token ${surface === "browser" ? "session" : "owner"} mismatch` };
+  }
+  if (
+    createHash("sha256").update(record.disclosureSerialized).digest("hex") !== record.disclosureDigest
+    || createHash("sha256").update(record.proofSerialized).digest("hex") !== record.proofDigest
+  ) {
+    return { valid: false, reason: "approval token disclosure or artifact proof integrity mismatch" };
+  }
+
+  const currentFingerprint = computeProfileFingerprint(profileDir);
+  if (record.profileFingerprint !== currentFingerprint) {
+    return { valid: false, reason: "profile state changed since approval token was issued" };
+  }
+
+  const currentReportDigest = digestPreflightReport(preflightReport);
+  if (record.reportDigest !== currentReportDigest) {
+    return { valid: false, reason: "preflight report changed since approval token was issued" };
+  }
+
+  // Exact package-set equality check:
+  // Require exact equality between sorted unique allowBuildScripts and the exact needsApproval package set (reject missing, extra, duplicate/invalid names).
+  if (!Array.isArray(allowBuildScripts)) {
+    return { valid: false, reason: "allowBuildScripts must be an array of package names" };
+  }
+  if (allowBuildScripts.length === 0) {
+    return { valid: false, reason: "allowBuildScripts cannot be empty when consuming approval token" };
+  }
+
+  const seen = new Set();
+  const normalizedAllow = [];
+  for (const raw of allowBuildScripts) {
+    if (typeof raw !== "string") {
+      return { valid: false, reason: `invalid package name in allowBuildScripts: ${JSON.stringify(raw)}` };
+    }
+    const name = raw.trim();
+    if (name.length === 0 || !NPM_PACKAGE_NAME_RE.test(name)) {
+      return { valid: false, reason: `invalid package name in allowBuildScripts: ${JSON.stringify(raw)}` };
+    }
+    if (seen.has(name)) {
+      return { valid: false, reason: `duplicate package name in allowBuildScripts: ${JSON.stringify(name)}` };
+    }
+    seen.add(name);
+    normalizedAllow.push(name);
+  }
+
+  normalizedAllow.sort();
+
+  if (normalizedAllow.length !== record.requestedPackages.length) {
+    return {
+      valid: false,
+      reason: `allowBuildScripts package count (${normalizedAllow.length}) does not match required package count (${record.requestedPackages.length})`,
+    };
+  }
+
+  for (let i = 0; i < record.requestedPackages.length; i++) {
+    if (normalizedAllow[i] !== record.requestedPackages[i]) {
+      return {
+        valid: false,
+        reason: `allowBuildScripts mismatch: expected "${record.requestedPackages[i]}", got "${normalizedAllow[i]}"`,
+      };
+    }
+  }
+
+  return { valid: true, warningConsent: record.warningConsent, proof: JSON.parse(record.proofSerialized) };
+}
+
+export function invalidateApprovalToken(token, owner, surface) {
+  if (typeof token !== "string") return false;
+  const clean = token.trim();
+  const record = approvalTokens.get(clean);
+  if (!record) return false;
+  if (owner !== undefined && record.owner !== owner) return false;
+  if (surface !== undefined && record.surface !== surface) return false;
+  approvalTokens.delete(clean);
+  return true;
+}
+
+export function clearApprovalTokensFor(profile, spec, { surface, owner } = {}) {
+  for (const [token, record] of approvalTokens) {
+    if (
+      record.profile === profile
+      && (spec === undefined || record.spec === spec)
+      && (surface === undefined || record.surface === surface)
+      && (owner === undefined || record.owner === owner)
+    ) {
+      approvalTokens.delete(token);
+    }
+  }
+}
+
+const BROWSER_SESSION_RE = /^sess_(?:[0-9a-f]{32}|[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/i;
+
+function requireBrowserSession(value) {
+  const session = typeof value === "string" ? value.trim() : "";
+  if (!BROWSER_SESSION_RE.test(session)) {
+    throw new Error("a valid browser session nonce is required");
+  }
+  return session;
+}
+
+/** Approval ownership on the agent surface must be a stable scalar identity,
+ * never the transient exec.agent object reference (a fresh facade may be
+ * supplied on every tool call). DSH's Agent.id is the live session identity;
+ * older hosts may expose the same value as session.id. */
+function requireAgentApprovalOwner(exec) {
+  const raw = exec?.agent?.id ?? exec?.agent?.session?.id;
+  const owner = raw === undefined || raw === null ? "" : String(raw).trim();
+  if (owner.length === 0 || owner.length > 256 || /[\u0000-\u001f\u007f]/.test(owner)) {
+    throw new Error("market_install approval requires a stable calling agent identity");
+  }
+  return owner;
+}
+
+// ── safe restart launch resolution (cli.js guard launch) ────────────────────
+//
+// Marketplace restart routes through this package's absolute src/cli.js:
+//   node cli.js guard launch --profile <profile> -- node <absolute official DSH entry> <original args>
+// using shell:false and ordinary argv. Fails closed if safe entry cannot be determined.
+
+export const SAFE_PROFILE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export const WINDOWS_DEVICE_BASENAME_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+
+export function assertSafeProfileName(profile, isWindows = process.platform === "win32") {
+  const value = String(profile ?? "");
+  if (!SAFE_PROFILE_NAME_RE.test(value)) {
+    throw new Error(`invalid profile name ${JSON.stringify(value)} — only letters, digits, '.', '_' and '-' are allowed, starting with a letter or digit`);
+  }
+  if (isWindows) {
+    if (/[. ]$/.test(value)) {
+      throw new Error(`invalid profile name ${JSON.stringify(value)} — Windows profile names must not end in a dot or space (on disk it would alias ${JSON.stringify(value.replace(/[. ]+$/, ""))} while using a different pending filename)`);
+    }
+    const deviceBase = value.replace(/\..*$/, "");
+    if (WINDOWS_DEVICE_BASENAME_RE.test(deviceBase)) {
+      throw new Error(`invalid profile name ${JSON.stringify(value)} — ${JSON.stringify(deviceBase.toUpperCase())} is a reserved Windows device name (even with an extension)`);
+    }
+  }
+}
+
+export function isSafeProfileName(profile, isWindows = process.platform === "win32") {
+  const value = String(profile ?? "");
+  if (!SAFE_PROFILE_NAME_RE.test(value)) return false;
+  if (isWindows) {
+    if (/[. ]$/.test(value)) return false;
+    const deviceBase = value.replace(/\..*$/, "");
+    if (WINDOWS_DEVICE_BASENAME_RE.test(deviceBase)) return false;
+  }
+  return true;
+}
+
+function packageRootFromEntry(entryPath) {
+  const parts = String(entryPath).split(/[\\/]+/);
+  for (let index = parts.length - 3; index >= 0; index--) {
+    if (
+      parts[index].toLowerCase() === "node_modules" &&
+      parts[index + 1].toLowerCase() === "@deepseek-ai" &&
+      parts[index + 2].toLowerCase() === "dsh"
+    ) {
+      return parts.slice(0, index + 3).join(sep);
+    }
+  }
+  return undefined;
+}
+
+function officialDshEntryFromRoot(pkgRoot) {
+  const manifestPath = join(pkgRoot, "package.json");
+  if (!existsSync(manifestPath)) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (manifest?.name !== "@deepseek-ai/dsh") return undefined;
+  const binRel = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.dsh;
+  if (typeof binRel !== "string" || binRel.length === 0) return undefined;
+  const root = resolve(pkgRoot);
+  const entry = resolve(root, binRel);
+  const rel = relative(root, entry);
+  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
+  if (!/\.js$/i.test(entry)) return undefined;
+  if (!existsSync(entry)) return undefined;
+  return entry;
+}
+
+function entryIsSelf(entry) {
+  try {
+    const a = realpathSync(entry);
+    const b = realpathSync(fileURLToPath(import.meta.url));
+    const cliB = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), "cli.js"));
+    const same = (x, y) => (process.platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y);
+    return same(a, b) || same(a, cliB);
+  } catch {
+    return false;
+  }
+}
+
+function entryFromShimText(shim, binDir) {
+  let text;
+  try {
+    text = readFileSync(shim, "utf8").slice(0, 65536);
+  } catch {
+    return undefined;
+  }
+  const match = /["']([^"'\r\n]*@deepseek-ai[\\/]dsh[\\/][^"'\r\n]*?\.js)["']/.exec(text);
+  if (match === null) return undefined;
+  let entry = match[1];
+  if (entry.startsWith("%dp0%")) entry = binDir + entry.slice("%dp0%".length);
+  else if (entry.startsWith("$basedir")) entry = binDir + entry.slice("$basedir".length);
+  return entry;
+}
+
+function resolveDshShim() {
+  if (process.platform === "win32") {
+    const pathEnv = process.env.PATH ?? "";
+    const pathext = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD;.PS1").split(";");
+    for (const dir of pathEnv.split(";")) {
+      if (dir.length === 0) continue;
+      for (const ext of pathext) {
+        const full = join(dir, `dsh${ext}`);
+        if (existsSync(full)) return full;
+      }
+    }
+    return undefined;
+  }
+  for (const dir of (process.env.PATH ?? "").split(":")) {
+    if (dir.length === 0) continue;
+    const full = join(dir, "dsh");
+    if (existsSync(full)) return full;
+  }
+  return undefined;
+}
+
+export function resolveCurrentDshEntry() {
+  const invoked = process.argv[1];
+  if (typeof invoked === "string" && invoked.length > 0 && existsSync(invoked)) {
+    try {
+      const real = realpathSync(invoked);
+      if (/\.js$/i.test(real) && !entryIsSelf(real)) {
+        const root = packageRootFromEntry(real);
+        if (root !== undefined) {
+          const entry = officialDshEntryFromRoot(root);
+          if (entry !== undefined && !entryIsSelf(entry)) return entry;
+        }
+      }
+      const fromText = entryFromShimText(invoked, dirname(invoked));
+      if (fromText !== undefined) {
+        const root = packageRootFromEntry(fromText);
+        if (root !== undefined) {
+          const entry = officialDshEntryFromRoot(root);
+          if (entry !== undefined && !entryIsSelf(entry)) return entry;
+        }
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
+  const shim = resolveDshShim();
+  if (shim !== undefined) {
+    const binDir = dirname(shim);
+    const roots = [];
+    try {
+      const real = realpathSync(shim);
+      if (/\.js$/i.test(real) && !entryIsSelf(real)) {
+        const root = packageRootFromEntry(real);
+        if (root !== undefined) roots.push(root);
+      }
+    } catch {
+      /* ignore */
+    }
+    const fromText = entryFromShimText(shim, binDir);
+    if (fromText !== undefined) {
+      const root = packageRootFromEntry(fromText);
+      if (root !== undefined) roots.push(root);
+    }
+    roots.push(join(binDir, "node_modules", "@deepseek-ai", "dsh"));
+    roots.push(resolve(binDir, "..", "lib", "node_modules", "@deepseek-ai", "dsh"));
+    for (const root of roots) {
+      const entry = officialDshEntryFromRoot(root);
+      if (entry !== undefined && !entryIsSelf(entry)) return entry;
+    }
+  }
+
+  return undefined;
+}
+
+export function resolveRestartLaunchPlan({ profile, config = {}, isWindows }) {
+  if (config.allowRestart === false) {
+    return { ok: false, error: "restart disabled by config (allowRestart: false)" };
+  }
+
+  const name = String(profile ?? "").trim();
+  if (name.length === 0) {
+    return { ok: false, error: "restart requires a target profile name" };
+  }
+  try {
+    // isWindows 显式传入时覆盖平台默认（离线 fixture 用它跨平台钉死 Windows 语义）。
+    assertSafeProfileName(name, isWindows === undefined ? undefined : isWindows === true);
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+
+  const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), "cli.js");
+  if (!existsSync(cliPath)) {
+    return { ok: false, error: `cannot locate guard CLI at ${cliPath}` };
+  }
+
+  const dshEntry = resolveCurrentDshEntry();
+  if (dshEntry === undefined) {
+    return { ok: false, error: "cannot resolve verified official @deepseek-ai/dsh CLI entry for automatic restart under guard probation — please restart manually" };
+  }
+
+  const nodePath = process.execPath;
+  const originalDshArgs = process.argv.slice(2);
+  const args = [cliPath, "guard", "launch", "--profile", name, "--", nodePath, dshEntry, ...originalDshArgs];
+
+  return {
+    ok: true,
+    nodePath,
+    args,
+    cliPath,
+    dshEntry,
+    profile: name,
+  };
+}
+
+// ── in-process job tracker for browser RPC ───────────────────────────────────
+
+let trackerCounter = 0;
+
+export function createJobTracker({ producerFactory } = {}) {
+  const records = new Map();
+  const prune = () => {
+    const now = Date.now();
+    for (const [id, record] of records) {
+      const terminal = record.status !== "running";
+      if (terminal && record.finishedAt !== undefined && now - record.finishedAt > 3600000) records.delete(id);
+    }
+    if (records.size > 20) {
+      const ordered = [...records.entries()].sort((a, b) => a[1].startedAt - b[1].startedAt);
+      for (const [id, record] of ordered) {
+        if (records.size <= 20) break;
+        if (record.status !== "running") records.delete(id);
+      }
+    }
+  };
+
+  return {
+    start({
+      profile,
+      spec,
+      verb = "add",
+      allowBuildScripts,
+      approvedProof,
+      preflight,
+      profileDir,
+      acceptWarningsActive = false,
+      surface = "browser",
+      session,
+      onSettled,
+      producerFactory: startProducerFactory,
+    }) {
+      const id = `market-${++trackerCounter}`;
+      const kind = verb === "remove" ? "dsh-plugin-uninstall" : "dsh-plugin-install";
+      const factory = startProducerFactory ?? producerFactory;
+      const producer = typeof factory === "function"
+        ? factory({ profile, spec, verb, allowBuildScripts, approvedProof, preflight, profileDir })
+        : verb === "remove"
+          ? runRemove({ profile, packageName: spec })
+          : runInstall({ profile, spec, allowBuildScripts, approvedProof, preflight });
+
+      const record = {
+        id,
+        kind,
+        label: `dsh plugin --profile ${profile} ${verb} ${spec}`,
+        profile,
+        spec,
+        surface,
+        session: session ?? "",
+        status: "running",
+        detail: undefined,
+        needsApproval: undefined,
+        approvalToken: undefined,
+        startedAt: Date.now(),
+        finishedAt: undefined,
+        producer,
+      };
+
+      // Ensure producer.done rejection is caught and always ends in terminal failed state
+      Promise.resolve(producer.done)
+        .catch((error) => ({
+          status: "failed",
+          detail: `${verb === "remove" ? "remove" : "install"} of ${spec} hit an unexpected error: ${error?.message ?? String(error)}`,
+        }))
+        .then((outcome) => {
+          const status = outcome?.status ?? "failed";
+          record.status = status;
+          record.detail = outcome?.detail;
+          record.needsApproval = outcome?.needsApproval;
+          record.finishedAt = Date.now();
+
+          if (status === "completed") {
+            if (profileDir) invalidatePreflightFor(profileDir);
+            clearApprovalTokensFor(profile, spec);
+          } else if (outcome?.needsApproval && outcome.needsApproval.length > 0) {
+            clearApprovalTokensFor(profile, spec, { surface: record.surface, owner: record.session });
+            const token = issueApprovalToken({
+              profile,
+              profileDir,
+              spec,
+              preflightReport: preflight,
+              needsApproval: outcome.needsApproval,
+              proof: outcome.proof,
+              surface: record.surface,
+              owner: record.session,
+              acceptWarningsActive,
+            });
+            record.approvalToken = token;
+          } else {
+            clearApprovalTokensFor(profile, spec, { surface: record.surface, owner: record.session });
+          }
+
+          try {
+            onSettled?.(outcome);
+          } catch (e) {
+            console.error("[dsh-plugin-mall] onSettled error:", e);
+          }
+        })
+        .catch((fatalError) => {
+          record.status = "failed";
+          record.detail = `internal error: ${fatalError?.message ?? String(fatalError)}`;
+          record.finishedAt = Date.now();
+          clearApprovalTokensFor(profile, spec, { surface: record.surface, owner: record.session });
+        });
+
+      records.set(id, record);
+      prune();
+      return id;
+    },
+
+    /**
+     * A visible, log-streaming job for a phase that is not install/remove.
+     * Preflight above all: it used to run inside the RPC call before any job
+     * existed, so the panel sat empty for the seconds the probe took. Now the
+     * job appears the instant the user clicks and the probe's pnpm output
+     * streams into it. The verdict rides `extras` on the snapshot so the
+     * polling client can continue into the install (or raise a risk card).
+     * Cancel is advisory — the probe has no kill handle — so it just marks the
+     * record killed and discards the outcome; the throwaway probe directory
+     * lives in the system tmpdir and is reclaimed by the OS.
+     */
+    startCustom({ kind, label, profile, spec, surface = "browser", session, run }) {
+      const id = `market-${++trackerCounter}`;
+      const queue = [];
+      const push = (text) => { queue.push(String(text ?? "")); };
+      const record = {
+        id,
+        kind,
+        label,
+        profile,
+        spec,
+        surface,
+        session: session ?? "",
+        status: "running",
+        detail: undefined,
+        extras: undefined,
+        startedAt: Date.now(),
+        finishedAt: undefined,
+        cancelled: false,
+        readOutput: () => (queue.length === 0 ? "" : queue.splice(0).join("")),
+      };
+      (async () => {
+        try {
+          const outcome = await run(push);
+          if (record.cancelled) return; // 用户已放弃，结果作废
+          record.status = outcome?.status ?? "failed";
+          record.detail = outcome?.detail;
+          record.extras = outcome?.extras;
+        } catch (error) {
+          if (record.cancelled) return;
+          record.status = "failed";
+          record.detail = error?.message ?? String(error);
+        } finally {
+          if (!record.cancelled) record.finishedAt = Date.now();
+        }
+      })();
+      records.set(id, record);
+      prune();
+      return id;
+    },
+
+    get(jobId, session) {
+      const record = records.get(String(jobId));
+      if (record === undefined) throw new Error(`unknown install job ${JSON.stringify(String(jobId))}`);
+      const isSameSession = record.surface !== "browser" || (record.session !== "" && record.session === session);
+      return {
+        snapshot: {
+          id: record.id,
+          kind: record.kind,
+          label: record.label,
+          status: record.status,
+          detail: record.detail,
+          needsApproval: record.needsApproval,
+          approvalToken: isSameSession ? record.approvalToken : undefined,
+          // extras（如预检结论）同样只对同一 session 可见，与 approvalToken 同规格。
+          extras: isSameSession ? record.extras : undefined,
+          spec: record.spec,
+          startedAt: record.startedAt,
+          finishedAt: record.finishedAt,
+        },
+        output: typeof record.readOutput === "function"
+          ? record.readOutput()
+          : typeof record.producer?.readOutput === "function" ? record.producer.readOutput() : "",
+      };
+    },
+
+    cancel(jobId, session) {
+      const record = records.get(String(jobId));
+      if (record === undefined) throw new Error(`unknown install job ${JSON.stringify(String(jobId))}`);
+      if (record.surface === "browser" && (record.session === "" || record.session !== session)) {
+        throw new Error("unauthorized to cancel job from another session");
+      }
+      if (record.cancelled !== undefined) { // startCustom：无句柄可杀，立即标 killed 并作废结果
+        record.cancelled = true;
+        if (record.status === "running") {
+          record.status = "killed";
+          record.finishedAt = Date.now();
+        }
+      }
+      if (typeof record.producer?.cancel === "function") {
+        record.producer.cancel();
+      }
+      if (record.approvalToken) {
+        invalidateApprovalToken(record.approvalToken, record.session || undefined, record.surface);
+        record.approvalToken = undefined;
+      }
+      clearApprovalTokensFor(record.profile, record.spec, { surface: record.surface, owner: record.session });
+      return "requested";
+    },
+
+    dismiss(jobId, session) {
+      const record = records.get(String(jobId));
+      if (record === undefined) return false;
+      if (record.surface === "browser" && (record.session === "" || record.session !== session)) {
+        return false;
+      }
+      if (record.approvalToken) {
+        invalidateApprovalToken(record.approvalToken, record.session || undefined, record.surface);
+        record.approvalToken = undefined;
+      }
+      return true;
+    },
+  };
+}
+
+/** Render one preflight issue as a compact line for model/error output. */
+function renderPreflightIssue(entry) {
+  const badge = entry.severity === "block" ? "BLOCK" : "WARN";
+  return `  [${badge}] ${entry.title}: ${entry.detail}`;
+}
+
+/**
+ * Enforce a preflight verdict for an install. Throws when a blocker exists, or
+ * when there are only warnings and acceptWarnings is not true.
+ */
+function enforcePreflight(report, acceptWarnings, label) {
+  if (report.verdict === "blocked") {
+    const error = new Error(`${label}: ${report.summary}\n${report.issues.filter((entry) => entry.severity === "block").map(renderPreflightIssue).join("\n")}`);
+    error.preflight = report;
+    throw error;
+  }
+  if (report.verdict === "warning" && acceptWarnings !== true) {
+    const error = new Error(`${label}: ${report.summary}\n${report.issues.filter((entry) => entry.severity === "warn").map(renderPreflightIssue).join("\n")}\n\nTo continue, show these warnings to the user and, after their explicit confirmation, call again with acceptWarnings: true.`);
+    error.preflight = report;
+    throw error;
+  }
+}
+
 /** Clip long strings for compact model-facing output. */
 function clip(text, max) {
   const trimmed = String(text ?? "").replace(/\s+/g, " ").trim();
@@ -131,39 +1082,20 @@ const BACKGROUND_OUTPUT_PROPERTIES = {
 };
 
 // ── browser RPC channel (/market) ───────────────────────────────────────────
-//
-// The web UI half (src/client.js) talks to this node half through the
-// Connection service's generic RPC channels (`connection.rpc.handle`). The
-// shared /api channel belongs to the api-gateway, so the marketplace owns its
-// own loopback-only channel. Every endpoint answers `{ok:true,value}` or
-// `{ok:false,error}` — the client unwraps this envelope itself.
 
 function rpcOk(value) {
   return { ok: true, value };
 }
 
 function rpcFail(error) {
-  // dsh connection RPC 的响应信封校验（dsh-client-connection rpcResultSchema）
-  // 要求 error 为 discriminated object：{code, message, details}。code 取
-  // 通用 "internal"，否则整条错误会被 zod 以 invalid_union 吞掉。
   return { ok: false, error: { code: "internal", message: error?.message ?? String(error), details: {} } };
 }
 
 /**
- * Dispatch one /market RPC endpoint. Runs inside the plugin fiber, so it
- * shares the tools' GitHub helpers and the install tracker. The agent-plane
- * tools keep using ctx.jobs; the browser surface uses `tracker` because the
- * web host plane has no job controller for ctx.jobs to serve.
- * @param ctx - plugin context.
- * @param endpoint - "search" | "info" | "installed" | "install" | "uninstall" | "job" | "jobCancel".
- * @param payload - endpoint arguments from the browser.
- * @param config - the row config (defaultProfile, apiBase, perPageMax).
- * @param token - GitHub token from the environment.
- * @param tracker - the in-process install tracker.
- * @returns the {ok, value|error} envelope.
+ * Dispatch one /market RPC endpoint.
  */
 async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
-  const { defaultProfile = "web", apiBase = "https://api.github.com", perPageMax = 30, allowRestart = true, npmRegistry = "", rawSources = [] } = config;
+  const { defaultProfile = "web", apiBase = "https://api.github.com", perPageMax = 30, npmRegistry = "", rawSources = [] } = config;
   switch (endpoint) {
     case "search": {
       const perPage = Math.min(Math.max(Math.trunc(payload?.perPage ?? 10) || 10, 1), Math.trunc(perPageMax) || 30);
@@ -182,6 +1114,54 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       const result = await verifyPlugins({ repos: payload?.repos, sources: rawSources });
       return rpcOk(result);
     }
+    case "compat": {
+      // Browsing-time conflict badge: statically scan each repo's manifest
+      // (and declared bundle patch, fetched as text) against the profile —
+      // the same checks the install preflight runs, minus the probe install.
+      const profile = String(payload?.profile ?? defaultProfile).trim();
+      let profileDir;
+      try {
+        profileDir = resolveProfileDir(profile);
+      } catch (error) {
+        return rpcFail(new Error(`invalid profile: ${error.message}`));
+      }
+      const repos = [...new Set((Array.isArray(payload?.repos) ? payload.repos : []).map(String)
+        .filter((repo) => /^[^@/\s][^/\s]*\/[^/\s]+$/.test(repo) && !repo.includes("..")))].slice(0, 30);
+      if (repos.length === 0) return rpcOk({ results: {} });
+      await verifyPlugins({ repos, sources: rawSources }); // populates the manifest cache
+      let fingerprint;
+      const results = {};
+      await mapLimit(repos, NETWORK_CONCURRENCY, async (repo) => {
+        const manifest = cachedRepoManifest(repo);
+        if (manifest === undefined || typeof manifest !== "object") {
+          results[repo] = { state: "unknown", summary: "无法获取插件清单，兼容性未知" };
+          return;
+        }
+        try {
+          let patchText;
+          if (typeof manifest.dsh?.bundle?.patch === "string") {
+            patchText = await fetchRawFile(repo, manifest.dsh.bundle.patch, { sources: rawSources });
+          }
+          fingerprint ??= computeProfileFingerprint(profileDir);
+          const cacheKey = `${fingerprint}::${repo}`;
+          const hit = compatCacheGet(cacheKey);
+          if (hit !== undefined) { results[repo] = hit; return; }
+          const report = inspectRemoteCandidate({ profileDir, manifest, patchText, spec: `github:${repo}` });
+          const entry = {
+            state: report.verdict === "blocked" ? "conflict" : report.verdict === "warning" ? "warning" : "compatible",
+            name: report.candidate.name,
+            summary: report.summary,
+            issues: report.issues.slice(0, 3).map(({ severity, title }) => ({ severity, title })),
+            patchChecked: typeof manifest.dsh?.bundle?.patch === "string" ? report.issues.every((item) => item.code !== "patch-unverified") : true,
+          };
+          compatCacheSet(cacheKey, entry);
+          results[repo] = entry;
+        } catch {
+          results[repo] = { state: "unknown", summary: "兼容性检查失败" };
+        }
+      });
+      return rpcOk({ results });
+    }
     case "updates": {
       const profile = String(payload?.profile ?? defaultProfile).trim();
       let deps;
@@ -193,7 +1173,6 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       }
       const registry = await registryFor(profile, npmRegistry);
       const results = {};
-      // 同 verifyPlugins 的 worker 池，而不是对所有依赖一次性扇出。
       await mapLimit(deps, NETWORK_CONCURRENCY, async (dep) => {
         if (dep.kind === "missing") { results[dep.name] = { latest: null }; return; }
         const info = await npmPackageInfo(dep.name, { registry });
@@ -216,8 +1195,56 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       }
       return rpcOk(listInstalled(profile));
     }
+    case "preflight": {
+      // 预检本身做成 job：点击安装的瞬间任务就出现在面板里，探针的 pnpm
+      // 输出实时流入——此前预检阻塞在 RPC 里，面板数秒空白只有按钮干等。
+      // 结论经 snapshot.extras 返回，轮询端据此后接安装或出风险卡片；
+      // 缓存同时被填热，随后的 install 调用不再重复探装。
+      const profile = String(payload?.profile ?? defaultProfile).trim();
+      let session;
+      try {
+        // 与 install 同规格：job 归属浏览器 session，extras 才只对本人可见。
+        session = requireBrowserSession(payload?.session);
+      } catch (error) {
+        return rpcFail(error);
+      }
+      let spec;
+      try {
+        spec = normalizeSpec(payload?.spec);
+        assertSafeSpec(spec);
+      } catch (error) {
+        return rpcFail(error);
+      }
+      try {
+        const registry = await registryFor(profile, npmRegistry);
+        const resolved = await preferNpmSpec({ spec, registry, sources: rawSources });
+        const jobId = tracker.startCustom({
+          kind: "dsh-plugin-preflight",
+          label: `preflight ${resolved}`,
+          profile,
+          spec: resolved,
+          surface: "browser",
+          session,
+          run: async (push) => {
+            push(`[dsh-plugin-mall] 预检 ${resolved}：隔离目录探装（脚本禁用）\n`);
+            const { report } = await runPreflight({ profile, spec: resolved, onOutput: (text) => push(text) });
+            push(`[dsh-plugin-mall] 预检结论：${report.verdict}\n`);
+            return { status: "completed", detail: `预检完成：${report.verdict}`, extras: report };
+          },
+        });
+        return rpcOk({ jobId, profile, spec: resolved });
+      } catch (error) {
+        return rpcFail(error);
+      }
+    }
     case "install": {
       const profile = String(payload?.profile ?? defaultProfile).trim();
+      let session;
+      try {
+        session = requireBrowserSession(payload?.session);
+      } catch (error) {
+        return rpcFail(error);
+      }
       let spec;
       try {
         spec = normalizeSpec(payload?.spec);
@@ -225,38 +1252,87 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       } catch (error) {
         return rpcFail(error);
       }
-      // npm tarball 优先（小而快、带 integrity）；registry 条目不同源的包名
-      // 视为抢注，回退 github: 全仓库 spec。查的 registry 必须是 pnpm 实际
-      // 安装用的那个，否则镜像用户这里永远比对不上、次次退化成全仓库克隆。
       const registry = await registryFor(profile, npmRegistry);
       spec = await preferNpmSpec({ spec, registry, sources: rawSources });
-      // 宿主依赖硬拦：dependencies 里拖着 @deepseek-ai/* 的包装进 profile
-      // 就是双模块实例 + 全工具调度崩溃（宿主无任何护栏，市场是最后防线）。
       try {
         await assertSafeToInstall({ spec, registry, sources: rawSources });
       } catch (error) {
         return rpcFail(error);
       }
+      const allowBuildScripts = Array.isArray(payload?.allowBuildScripts)
+        ? payload.allowBuildScripts.map((name) => String(name))
+        : undefined;
+      const approvalToken = typeof payload?.approvalToken === "string" && payload.approvalToken.trim().length > 0
+        ? payload.approvalToken.trim()
+        : undefined;
+
       try {
-        const profileDir = resolveProfileDir(profile);
-        if (!existsSync(join(profileDir, "package.json"))) ensureProfile(profile);
+        assertValidApprovalInvocation(allowBuildScripts, approvalToken);
       } catch (error) {
-        return rpcFail(new Error(`invalid profile: ${error.message}`));
+        return rpcFail(error);
       }
+
+      let preflight;
+      let acceptWarnings = false;
+      let acceptWarningsActive = false;
+      let approvedProof = undefined;
       try {
-        // 构建脚本的同意是「点名」的：只放行清单里这几个包。重试时被拦的集合
-        // 变了（依赖更新、换了版本），旧的同意不会顺延到新出现的包上。
-        const allowBuildScripts = Array.isArray(payload?.allowBuildScripts)
-          ? payload.allowBuildScripts.map((name) => String(name))
-          : undefined;
-        const jobId = tracker.start({ profile, spec, allowBuildScripts });
-        return rpcOk({ jobId, profile, spec });
+        preflight = await runPreflight({ profile, spec });
+        if (approvalToken !== undefined) {
+          const consumeResult = consumeApprovalToken({
+            token: approvalToken,
+            profile,
+            profileDir: preflight.profileDir,
+            spec,
+            preflightReport: preflight.report,
+            allowBuildScripts,
+            surface: "browser",
+            owner: session,
+          });
+          if (!consumeResult.valid) {
+            return rpcFail(new Error(`invalid approval token: ${consumeResult.reason}`));
+          }
+          acceptWarnings = consumeResult.warningConsent;
+          acceptWarningsActive = consumeResult.warningConsent;
+          approvedProof = consumeResult.proof;
+        } else {
+          acceptWarnings = payload?.acceptWarnings === true;
+          acceptWarningsActive = acceptWarnings;
+        }
+        enforcePreflight(preflight.report, acceptWarnings, `install ${spec}`);
+      } catch (error) {
+        return rpcFail(error);
+      }
+
+      pinPreflight(preflight.profileDir, spec);
+      try {
+        const jobId = tracker.start({
+          profile,
+          spec,
+          allowBuildScripts,
+          approvedProof,
+          preflight: preflight.report,
+          profileDir: preflight.profileDir,
+          acceptWarningsActive,
+          surface: "browser",
+          session,
+          onSettled: (outcome) => {
+            if (outcome?.status === "completed") invalidatePreflightFor(preflight.profileDir);
+          },
+        });
+        return rpcOk({ jobId, profile, spec, preflight: { verdict: preflight.report.verdict, summary: preflight.report.summary } });
       } catch (error) {
         return rpcFail(error);
       }
     }
     case "uninstall": {
       const profile = String(payload?.profile ?? defaultProfile).trim();
+      let session;
+      try {
+        session = requireBrowserSession(payload?.session);
+      } catch (error) {
+        return rpcFail(error);
+      }
       const packageName = String(payload?.package ?? "").trim();
       if (packageName.length === 0) return rpcFail(new Error("uninstall: package name is required"));
       try {
@@ -264,8 +1340,9 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
       } catch (error) {
         return rpcFail(error);
       }
+      let profileDir;
       try {
-        const profileDir = resolveProfileDir(profile);
+        profileDir = resolveProfileDir(profile);
         if (!existsSync(join(profileDir, "package.json"))) {
           return rpcFail(new Error(`profile "${profile}" has no package.json — nothing installed to remove`));
         }
@@ -273,7 +1350,20 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
         return rpcFail(new Error(`invalid profile: ${error.message}`));
       }
       try {
-        const jobId = tracker.start({ profile, spec: packageName, verb: "remove" });
+        const jobId = tracker.start({
+          profile,
+          spec: packageName,
+          verb: "remove",
+          profileDir,
+          surface: "browser",
+          session,
+          onSettled: (outcome) => {
+            if (outcome?.status === "completed") {
+              invalidatePreflightFor(profileDir);
+              clearApprovalTokensFor(profile);
+            }
+          },
+        });
         return rpcOk({ jobId, profile, package: packageName });
       } catch (error) {
         return rpcFail(error);
@@ -281,33 +1371,54 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
     }
     case "job": {
       try {
-        return rpcOk(tracker.get(payload?.jobId));
+        const session = requireBrowserSession(payload?.session);
+        return rpcOk(tracker.get(payload?.jobId, session));
       } catch (error) {
         return rpcFail(error);
       }
     }
     case "restart": {
-      // 一键重启：detached 拉起新 dsh 进程（用当前进程的 argv 重建启动命令）
-      // 后退出自己。仅 loopback 直连可调（channel 级 authority 已限制）；
-      // allowRestart:false 时禁用（进程由 systemd/pm2 等托管时接管重启）。
-      if (allowRestart !== true) return rpcFail(new Error("restart disabled by config (allowRestart: false)"));
-      const script = process.argv[1];
-      const scriptArgs = process.argv.slice(2);
-      if (typeof script !== "string" || script.length === 0 || !existsSync(script)) {
-        return rpcFail(new Error("cannot determine the dsh launch command for an automatic restart — please restart manually"));
-      }
-      const relaunch = `"${process.execPath}" "${script}"${scriptArgs.length > 0 ? ` ${scriptArgs.map((arg) => `"${arg}"`).join(" ")}` : ""}`;
-      const launcher = process.platform === "win32"
-        ? `timeout /t 2 /nobreak >nul & ${relaunch}`
-        : `sleep 2 && ${relaunch}`;
-      const child = spawn(launcher, { shell: true, detached: true, stdio: "ignore", cwd: process.cwd(), windowsHide: true });
+      const profile = String(payload?.profile ?? defaultProfile).trim();
+      try {
+        requireBrowserSession(payload?.session);
+      } catch (error) {
+        return rpcFail(error);
+      }
+      const plan = resolveRestartLaunchPlan({ profile, config });
+      if (!plan.ok) {
+        return rpcFail(new Error(plan.error));
+      }
+      const child = spawn(plan.nodePath, plan.args, {
+        shell: false,
+        detached: true,
+        stdio: "ignore",
+        cwd: process.cwd(),
+        windowsHide: true,
+      });
       child.unref();
-      setTimeout(() => process.exit(0), 1500);
+      setTimeout(() => process.exit(0), 1000);
       return rpcOk({ restarting: true });
     }
     case "jobCancel": {
       try {
-        return rpcOk({ result: tracker.cancel(payload?.jobId) });
+        const session = requireBrowserSession(payload?.session);
+        return rpcOk({ result: tracker.cancel(payload?.jobId, session) });
+      } catch (error) {
+        return rpcFail(error);
+      }
+    }
+    case "jobDismiss": {
+      try {
+        const session = requireBrowserSession(payload?.session);
+        const token = typeof payload?.token === "string" && payload.token.trim().length > 0 ? payload.token.trim() : undefined;
+        let dismissed = false;
+        if (payload?.jobId) {
+          dismissed = tracker.dismiss(payload.jobId, session) || dismissed;
+        }
+        if (token) {
+          dismissed = invalidateApprovalToken(token, session, "browser") || dismissed;
+        }
+        return rpcOk({ dismissed });
       } catch (error) {
         return rpcFail(error);
       }
@@ -318,13 +1429,7 @@ async function rpcDispatch(ctx, endpoint, payload, config, token, tracker) {
 }
 
 /**
- * Register the /market RPC channel once the Connection service exists (web
- * profiles). `ctx.inject` defers the callback until the service is provided —
- * activation order never races — and in headless/test profiles the callback
- * simply never runs, so the agent tools remain the only surface there.
- * @param ctx - plugin context.
- * @param config - the row config.
- * @param token - GitHub token from the environment.
+ * Register the /market RPC channel once the Connection service exists.
  */
 function registerRpcChannel(ctx, config, token) {
   const tracker = createJobTracker();
@@ -333,9 +1438,6 @@ function registerRpcChannel(ctx, config, token) {
       try {
         return await rpcDispatch(ctx, endpoint, payload ?? {}, config, token, tracker);
       } catch (error) {
-        // 没有这层兜底时连接层只会回一个 HTTP 500 "transport failure"，
-        // 真实异常既到不了浏览器也不留痕。透传错误文本，同时把堆栈
-        // 打进 dsh 进程的 stderr（前台运行时可见）。
         console.error(`[dsh-plugin-mall] /market/${String(endpoint)} failed:`, error);
         return rpcFail(error);
       }
@@ -347,10 +1449,35 @@ export function apply(ctx, config = {}) {
   const { defaultProfile = "web", apiBase = "https://api.github.com", perPageMax = 30, npmRegistry = "", rawSources = [] } = config;
   const token = process.env.GITHUB_TOKEN ?? process.env.DSH_MARKET_GITHUB_TOKEN;
 
+  // Startup recovery. A pending install marker blocks every later install and
+  // uninstall in that profile until something resolves it — and until now the
+  // only thing that did was `guard launch`, a wrapper nobody uses: people type
+  // `dsh web`. One install then wedged the profile permanently, with an error
+  // telling users to run a CLI they have never heard of.
+  //
+  // Reaching `apply` IS the proof the pending install did not break the host:
+  // this code only runs because dsh booted far enough to compose the profile
+  // and load this plugin. So resolve the marker right here — recoverProfile
+  // commits when the profile validates and rolls back when it does not. The
+  // grace-window probation of `guard launch` stays strictly better (it also
+  // catches a crash seconds later); this is the floor for a plain start.
+  try {
+    const result = recoverProfile(resolveProfileDir(defaultProfile));
+    if (result.action === "committed") {
+      console.log(`[dsh-plugin-mall] startup recovery: committed the pending install for profile "${defaultProfile}"`);
+    } else if (result.action === "rolled-back") {
+      console.warn(`[dsh-plugin-mall] startup recovery: rolled back the pending install for profile "${defaultProfile}" — ${result.reason ?? "profile failed validation"}`);
+    }
+  } catch (error) {
+    // 恢复失败绝不能拖垮插件加载：报出来，让市场照常可用（用户还能手动
+    // `dsh-plugin-guard guard recover`），而不是连界面都进不去。
+    console.error("[dsh-plugin-mall] startup recovery failed:", error);
+  }
+
   ctx.systemPrompt.section({
     name: "tool:market",
     order: 120,
-    text: "The dsh plugin marketplace tools are available: market_search discovers plugins on the GitHub dsh-plugin topic, market_info inspects one repository, market_install installs a plugin into a dsh profile as a background job (poll with job_output), market_uninstall removes an installed plugin from a dsh profile as a background job, and market_installed lists a profile's plugins. A successful market_install or market_uninstall only takes effect after the dsh process restarts — remind the user to restart. Prefer plugins with meaningful stars and a dsh.bundle declaration (market_info shows both). If market_install stops for install-script approval, that decision is the user's: show them the reported package names and commands and wait for an answer — never approve on their behalf.",
+    text: "The dsh plugin marketplace tools are available: market_search discovers plugins on the GitHub dsh-plugin topic, market_info inspects one repository, market_install installs a plugin into a dsh profile as a background job (poll with job_output), market_uninstall removes an installed plugin from a dsh profile as a background job, and market_installed lists a profile's plugins. A successful market_install or market_uninstall only takes effect after the dsh process restarts — remind the user to restart. Prefer plugins with meaningful stars and a dsh.bundle declaration (market_info shows both). market_install runs an isolated preflight before installing (the candidate is probed with install scripts disabled and scanned for conflicts); a blocker refuses the install and warnings require acceptWarnings: true after the user confirms them — never set it on the user's behalf. If market_install stops for install-script approval, that decision is also the user's: show them the reported package names and commands and wait for an answer — never approve on their behalf.",
   });
 
   ctx.tools.register(defineTool({
@@ -428,7 +1555,7 @@ export function apply(ctx, config = {}) {
 
   ctx.tools.register(defineTool({
     name: "market_install",
-    description: "Install a plugin into a local dsh profile by running `pnpm add` in that profile's directory, reconciling the profile's bundle layer list, and — for browser-side UI plugins (`dsh.client`) — registering a loader row in the profile's cordis.patch.yml. Same flow as `dsh plugin --profile <name> add <spec>`. ALWAYS runs as a background job: the call returns a job id immediately; poll with job_output and cancel with job_kill. If pnpm blocks a dependency's install scripts, the job STOPS and reports which packages want to run install-time code, what those commands are, and whether each is the plugin itself or a transitive dependency the user never chose — nothing is executed and the profile is left untouched. Relay that list to the user verbatim, and only call again with `allowBuildScripts` naming the packages they approved. A successful install only takes effect after the dsh process restarts.",
+    description: "Install a plugin into a local dsh profile by running `pnpm add` in that profile's directory, reconciling the profile's bundle layer list, and — for browser-side UI plugins (`dsh.client`) — registering a loader row in the profile's cordis.patch.yml. Same flow as `dsh plugin --profile <name> add <spec>`. ALWAYS runs as a background job: the call returns a job id immediately; poll with job_output and cancel with job_kill. The install is gated by an isolated preflight (the candidate is installed with scripts disabled into a throwaway directory and scanned for manifest/patch conflicts, host-module shadowing, and version/OS incompatibilities). A blocker refuses the install outright; a warning requires the USER's explicit consent via `acceptWarnings: true` — show the reported warnings verbatim and get their answer first, never consent on their behalf. If pnpm blocks a dependency's install scripts, the job STOPS and reports which packages want to run install-time code, what those commands are, whether each is the plugin itself or a transitive dependency, and issues a one-shot approval token. Relay that list to the user verbatim, and only call again with `allowBuildScripts` naming the packages they approved along with `approvalToken`. A successful install only takes effect after the dsh process restarts.",
     parameters: {
       spec: {
         type: "string",
@@ -439,6 +1566,14 @@ export function apply(ctx, config = {}) {
         type: "string",
         description: `Target profile under $DSH_HOME/profiles. Defaults to "${defaultProfile}".`,
       },
+      acceptWarnings: {
+        type: "boolean",
+        description: "Set true only after the USER has explicitly confirmed they accept the preflight warnings the previous call reported. Without it, an install whose preflight found only warnings is refused. Never set this on your own initiative.",
+      },
+      approvalToken: {
+        type: "string",
+        description: "Opaque one-shot approval token issued when a previous install paused for install script approval. Required on retry if the install had accepted preflight warnings.",
+      },
       allowBuildScripts: {
         type: "array",
         items: { type: "string" },
@@ -463,23 +1598,84 @@ export function apply(ctx, config = {}) {
       const registry = await registryFor(profile, npmRegistry);
       const spec = await preferNpmSpec({ spec: normalized, registry, sources: rawSources });
       await assertSafeToInstall({ spec, registry, sources: rawSources });
-      let profileDir;
-      try {
-        profileDir = resolveProfileDir(profile);
-      } catch (error) {
-        throw new Error(`market_install: invalid profile: ${error.message}`);
-      }
-      if (!existsSync(join(profileDir, "package.json"))) {
-        ensureProfile(profile);
-      }
       const allowBuildScripts = Array.isArray(args.allowBuildScripts)
         ? args.allowBuildScripts.map((name) => String(name))
         : undefined;
+      const approvalToken = typeof args.approvalToken === "string" && args.approvalToken.trim().length > 0
+        ? args.approvalToken.trim()
+        : undefined;
+      assertValidApprovalInvocation(allowBuildScripts, approvalToken);
+
+      const preflight = await runPreflight({ profile, spec });
+      let acceptWarnings = false;
+      let acceptWarningsActive = false;
+      let approvedProof = undefined;
+      const agentOwner = requireAgentApprovalOwner(exec);
+      if (approvalToken !== undefined) {
+        const consumeResult = consumeApprovalToken({
+          token: approvalToken,
+          profile,
+          profileDir: preflight.profileDir,
+          spec,
+          preflightReport: preflight.report,
+          allowBuildScripts,
+          surface: "agent",
+          owner: agentOwner,
+        });
+        if (!consumeResult.valid) {
+          throw new Error(`market_install: invalid approval token: ${consumeResult.reason}`);
+        }
+        acceptWarnings = consumeResult.warningConsent;
+        acceptWarningsActive = consumeResult.warningConsent;
+        approvedProof = consumeResult.proof;
+      } else {
+        acceptWarnings = args.acceptWarnings === true;
+        acceptWarningsActive = acceptWarnings;
+      }
+
+      enforcePreflight(preflight.report, acceptWarnings, `market_install ${spec}`);
+      pinPreflight(preflight.profileDir, spec);
+
+      const runProducer = () => {
+        const producer = runInstall({ profile, spec, allowBuildScripts, approvedProof, preflight: preflight.report });
+        const done = Promise.resolve(producer.done)
+          .catch((error) => ({
+            status: "failed",
+            detail: `install of ${spec} hit an internal error: ${error?.message ?? String(error)}`,
+          }))
+          .then((outcome) => {
+            const status = outcome?.status ?? "failed";
+            if (status === "completed") {
+              invalidatePreflightFor(preflight.profileDir);
+              clearApprovalTokensFor(profile, spec);
+            } else if (outcome?.needsApproval && outcome.needsApproval.length > 0) {
+              clearApprovalTokensFor(profile, spec, { surface: "agent", owner: agentOwner });
+              const token = issueApprovalToken({
+                profile,
+                profileDir: preflight.profileDir,
+                spec,
+                preflightReport: preflight.report,
+                needsApproval: outcome.needsApproval,
+                proof: outcome.proof,
+                surface: "agent",
+                owner: agentOwner,
+                acceptWarningsActive,
+              });
+              outcome.approvalToken = token;
+              outcome.detail = `${outcome.detail ?? ""}\n\nApproval token (pass to approvalToken on retry): ${token}`;
+            } else {
+              clearApprovalTokensFor(profile, spec, { surface: "agent", owner: agentOwner });
+            }
+            return outcome;
+          });
+        return { cancel: producer.cancel, done, readOutput: producer.readOutput };
+      };
+
       const jobId = ctx.jobs.start({
         kind: "dsh-plugin-install",
         label: `dsh plugin --profile ${profile} add ${spec}`,
         ...exec.agent ? { owner: exec.agent } : {},
-        run: () => runInstall({ profile, spec, allowBuildScripts }),
+        run: runProducer,
       });
       return { kind: "background", jobId };
     },
@@ -521,16 +1717,33 @@ export function apply(ctx, config = {}) {
       const packageName = String(args.package ?? "").trim();
       if (packageName.length === 0) throw new Error("market_uninstall: package name is required");
       assertSafeSpec(packageName);
+      let profileDir;
       try {
-        resolveProfileDir(profile);
+        profileDir = resolveProfileDir(profile);
       } catch (error) {
         throw new Error(`market_uninstall: invalid profile: ${error.message}`);
       }
+      const runProducer = () => {
+        const producer = runRemove({ profile, packageName });
+        const done = Promise.resolve(producer.done)
+          .catch((error) => ({
+            status: "failed",
+            detail: `remove of ${packageName} hit an internal error: ${error?.message ?? String(error)}`,
+          }))
+          .then((outcome) => {
+            if (outcome?.status === "completed") {
+              invalidatePreflightFor(profileDir);
+              clearApprovalTokensFor(profile);
+            }
+            return outcome;
+          });
+        return { cancel: producer.cancel, done, readOutput: producer.readOutput };
+      };
       const jobId = ctx.jobs.start({
         kind: "dsh-plugin-uninstall",
         label: `dsh plugin --profile ${profile} remove ${packageName}`,
         ...exec.agent ? { owner: exec.agent } : {},
-        run: () => runRemove({ profile, packageName }),
+        run: runProducer,
       });
       return { kind: "background", jobId };
     },
@@ -572,10 +1785,470 @@ export function apply(ctx, config = {}) {
     }),
   }));
 
-  // Browser surface: the /market RPC channel backs the Settings → Plugins →
-  // 插件市场 tab shipped in src/client.js.
   registerRpcChannel(ctx, config, token);
 }
 
-// NOTE: no `export default` — the cordis loader unwraps `exports.default ?? exports`,
-// so a default export would drop `inject`/`Config`/`name` and leave a bare apply function.
+// ── offline fixtures / self-test ────────────────────────────────────────────
+
+export async function runSelfTests() {
+  let failed = 0;
+  const check = (label, ok, extra = "") => {
+    if (ok) {
+      console.log(`  PASS ${label}`);
+    } else {
+      failed++;
+      console.error(`  FAIL ${label}${extra ? ` (${extra})` : ""}`);
+    }
+  };
+
+  const root = mkdtempSync(join(tmpdir(), "dsh-mall-index-selftest-"));
+  try {
+    const profileDir = join(root, "profiles", "web");
+    mkdirSync(profileDir, { recursive: true });
+    writeFileSync(join(profileDir, "package.json"), JSON.stringify({ name: "profile-web", dependencies: { "dep-a": "1.0.0" } }));
+    writeFileSync(join(profileDir, "pnpm-workspace.yaml"), "packages:\n  - .\n");
+    writeFileSync(join(profileDir, "cordis.patch.yml"), "[]\n");
+    mkdirSync(join(profileDir, "node_modules", "dep-a"), { recursive: true });
+    writeFileSync(join(profileDir, "node_modules", "dep-a", "package.json"), JSON.stringify({ name: "dep-a", version: "1.0.0" }));
+
+    // ── 1. computeProfileFingerprint & direct-only inspection ────────────────
+    const fp1 = computeProfileFingerprint(profileDir);
+    check("fingerprint 是非空 64 位 SHA-256 字符串", typeof fp1 === "string" && fp1.length === 64);
+    const fp1Repeat = computeProfileFingerprint(profileDir);
+    check("fingerprint 计算幂等", fp1 === fp1Repeat);
+
+    // 修改 cordis.patch.yml 改变 fingerprint
+    writeFileSync(join(profileDir, "cordis.patch.yml"), "- name: test\n");
+    const fp2 = computeProfileFingerprint(profileDir);
+    check("受保护文件修改 (cordis.patch.yml) → fingerprint 变化", fp1 !== fp2);
+
+    // 修改依赖版本改变 fingerprint
+    writeFileSync(join(profileDir, "node_modules", "dep-a", "package.json"), JSON.stringify({ name: "dep-a", version: "1.0.1" }));
+    const fp3 = computeProfileFingerprint(profileDir);
+    check("已装直系依赖版本变化 → fingerprint 变化", fp2 !== fp3);
+
+    // 依赖清单 name 不匹配 (corrupt)
+    writeFileSync(join(profileDir, "node_modules", "dep-a", "package.json"), JSON.stringify({ name: "wrong-name", version: "1.0.1" }));
+    const fpCorrupt = computeProfileFingerprint(profileDir);
+    check("依赖 package.json 名称不匹配被判定为 corrupt 且改变 fingerprint", fpCorrupt !== fp3);
+
+    // 祖先目录隔离：在 root 下建立 node_modules/dep-ancestor，但 profileDir/node_modules 下没有
+    mkdirSync(join(root, "node_modules", "dep-ancestor"), { recursive: true });
+    writeFileSync(join(root, "node_modules", "dep-ancestor", "package.json"), JSON.stringify({ name: "dep-ancestor", version: "2.0.0" }));
+    writeFileSync(join(profileDir, "package.json"), JSON.stringify({ name: "profile-web", dependencies: { "dep-a": "1.0.0", "dep-ancestor": "2.0.0" } }));
+    writeFileSync(join(profileDir, "node_modules", "dep-a", "package.json"), JSON.stringify({ name: "dep-a", version: "1.0.0" }));
+    const fpNoAncestor = computeProfileFingerprint(profileDir);
+
+    // 在 profileDir/node_modules/dep-ancestor 下真正创建
+    mkdirSync(join(profileDir, "node_modules", "dep-ancestor"), { recursive: true });
+    writeFileSync(join(profileDir, "node_modules", "dep-ancestor", "package.json"), JSON.stringify({ name: "dep-ancestor", version: "2.0.0" }));
+    const fpWithDirect = computeProfileFingerprint(profileDir);
+    check("fingerprint 绝不向上回溯祖先 node_modules (仅认 profile direct node_modules)", fpNoAncestor !== fpWithDirect);
+
+    // ── 2. First-call allowBuildScripts rejection helper ─────────────────────
+    let firstCallRejected = false;
+    try {
+      assertValidApprovalInvocation(["some-pkg"], undefined);
+    } catch (err) {
+      firstCallRejected = /cannot be specified on initial install/.test(err.message);
+    }
+    check("首次调用携带 allowBuildScripts 无审批 token 被拒绝", firstCallRejected);
+
+    let emptyTokenRejected = false;
+    try {
+      assertValidApprovalInvocation(["some-pkg"], "");
+    } catch (err) {
+      emptyTokenRejected = /cannot be specified on initial install/.test(err.message);
+    }
+    check("携带空字符串 token 调用 allowBuildScripts 被拒绝", emptyTokenRejected);
+
+    let validCallAllowed = true;
+    try {
+      assertValidApprovalInvocation(undefined, undefined);
+      assertValidApprovalInvocation([], undefined);
+      assertValidApprovalInvocation(["some-pkg"], "mkt-appr-abc123");
+    } catch {
+      validCallAllowed = false;
+    }
+    check("无 allowBuildScripts 或携带合法 token 允许通过", validCallAllowed);
+
+    const ownerA = requireAgentApprovalOwner({ agent: { id: "agent-session-123" } });
+    const ownerB = requireAgentApprovalOwner({ agent: { id: "agent-session-123" } });
+    let missingAgentRejected = false;
+    try { requireAgentApprovalOwner({}); } catch { missingAgentRejected = true; }
+    check("agent 审批 owner 使用稳定标量 ID（不绑定瞬态对象引用）且缺失时 fail closed", ownerA === ownerB && ownerA === "agent-session-123" && missingAgentRejected);
+
+    // ── 3. Safe-preflight token issuance & warning consent carrying ──────────
+    const cleanPreflightReport = {
+      verdict: "clean",
+      summary: "clean install",
+      issues: [],
+    };
+    const proofFor = (candidateName, packageNames = [candidateName]) => ({
+      candidate: { name: candidateName, version: "1.0.0", scripts: { install: "node install.js" }, contentHash: "a".repeat(64) },
+      blockedPackages: packageNames.map((packageName, index) => ({ name: packageName, version: "1.0.0", selector: `${packageName}@1.0.0`, direct: packageName === candidateName, scripts: { install: "node install.js" }, contentHash: String(index + 1).repeat(64) })),
+    });
+    const disclosureFor = (proof) => proof.blockedPackages.map((entry) => ({ ...entry }));
+    const sampleProof = {
+      candidate: { name: "safe-pkg", version: "1.0.0", scripts: { install: "node install.js" }, contentHash: "a".repeat(64) },
+      blockedPackages: [{ name: "safe-pkg", version: "1.0.0", selector: "safe-pkg@1.0.0", direct: true, scripts: { install: "node install.js" }, contentHash: "a".repeat(64) }],
+    };
+    const safeNeedsApproval = disclosureFor(sampleProof);
+    const safeToken = issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "safe-pkg@1.0.0",
+      preflightReport: cleanPreflightReport,
+      needsApproval: safeNeedsApproval,
+      proof: sampleProof,
+      surface: "agent",
+      owner: "agent-safe",
+      acceptWarningsActive: false,
+    });
+    check("安全 preflight 下依然签发审批 token", typeof safeToken === "string" && safeToken.startsWith("mkt-appr-"));
+
+    let staleDisclosureRejected = false;
+    try {
+      issueApprovalToken({
+        profile: "web",
+        profileDir,
+        spec: "safe-pkg@1.0.0",
+        preflightReport: cleanPreflightReport,
+        needsApproval: safeNeedsApproval.map((entry) => ({ ...entry, scripts: { install: "different command" } })),
+        proof: sampleProof,
+        surface: "agent",
+        owner: "agent-safe",
+      });
+    } catch (error) {
+      staleDisclosureRejected = /disclosure identity, scripts, or content hash/.test(error.message);
+    }
+    check("审批展示与物化 proof 的脚本/哈希不一致时拒绝签发 token", staleDisclosureRejected);
+
+    // 尝试用不匹配的 profileDir 消费 token（验证 realProfileDir 绑定）
+    const fakeOtherProfileDir = join(root, "profiles", "other-profile");
+    mkdirSync(fakeOtherProfileDir, { recursive: true });
+    writeFileSync(join(fakeOtherProfileDir, "package.json"), "{}");
+    const mismatchProfileDirRes = consumeApprovalToken({
+      token: safeToken,
+      profile: "web",
+      profileDir: fakeOtherProfileDir,
+      spec: "safe-pkg@1.0.0",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["safe-pkg"],
+      surface: "agent",
+      owner: "agent-safe",
+    });
+    check("profileDir realpath 不匹配时 token 消费被拒绝", !mismatchProfileDirRes.valid && /profile directory mismatch/.test(mismatchProfileDirRes.reason));
+
+    // 重新签发用于正常消费验证
+    const safeToken2 = issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "safe-pkg@1.0.0",
+      preflightReport: cleanPreflightReport,
+      needsApproval: safeNeedsApproval,
+      proof: sampleProof,
+      surface: "agent",
+      owner: "agent-safe",
+      acceptWarningsActive: false,
+    });
+
+    const safeConsume = consumeApprovalToken({
+      token: safeToken2,
+      profile: "web",
+      profileDir,
+      spec: "safe-pkg@1.0.0",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["safe-pkg"],
+      surface: "agent",
+      owner: "agent-safe",
+    });
+    check("安全 preflight token 消费成功且返回 proof 与 warningConsent", safeConsume.valid && safeConsume.warningConsent === false && serializeCanonicalProof(safeConsume.proof) === serializeCanonicalProof(sampleProof));
+
+    const warnPreflightReport = {
+      verdict: "warning",
+      summary: "warning found",
+      issues: [{ severity: "warn", code: "MANIFEST_PATCH_OVERWRITE", title: "warn", detail: "detail" }],
+    };
+    const warnProof = proofFor("warn-pkg");
+    const warnToken = issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "warn-pkg@1.0.0",
+      preflightReport: warnPreflightReport,
+      needsApproval: disclosureFor(warnProof),
+      proof: warnProof,
+      surface: "browser",
+      owner: "sess-warn",
+      acceptWarningsActive: true,
+    });
+    const warnConsume = consumeApprovalToken({
+      token: warnToken,
+      profile: "web",
+      profileDir,
+      spec: "warn-pkg@1.0.0",
+      preflightReport: warnPreflightReport,
+      allowBuildScripts: ["warn-pkg"],
+      surface: "browser",
+      owner: "sess-warn",
+    });
+    check("含警告 preflight 经确认后 token 消费携带 warningConsent 为 true", warnConsume.valid && warnConsume.warningConsent === true);
+
+    // ── 4. Exact package-set equality in consumeApprovalToken ────────────────
+    const multiProof = proofFor("multi-pkg", ["pkg-a", "pkg-b"]);
+    const multiPkgs = disclosureFor(multiProof).reverse();
+    const testIssue = () => issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      needsApproval: multiPkgs,
+      proof: multiProof,
+      surface: "agent",
+      owner: "agent-test",
+    });
+
+    // 4a. Exact match (sorted automatically)
+    const exactTok = testIssue();
+    const exactRes = consumeApprovalToken({
+      token: exactTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["pkg-b", "pkg-a"],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("完整包名集合（乱序输入）匹配成功", exactRes.valid);
+
+    // 4b. Subset rejected
+    const subTok = testIssue();
+    const subRes = consumeApprovalToken({
+      token: subTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["pkg-a"],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("子集包名消费被拒绝", !subRes.valid && /package count/.test(subRes.reason));
+
+    // 4c. Extra package rejected
+    const extraTok = testIssue();
+    const extraRes = consumeApprovalToken({
+      token: extraTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["pkg-a", "pkg-b", "pkg-c"],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("超集/额外包名消费被拒绝", !extraRes.valid && /package count/.test(extraRes.reason));
+
+    // 4d. Duplicate package rejected
+    const dupTok = testIssue();
+    const dupRes = consumeApprovalToken({
+      token: dupTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["pkg-a", "pkg-a"],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("重复包名消费被拒绝", !dupRes.valid && /duplicate package name/.test(dupRes.reason));
+
+    // 4e. Invalid package name rejected
+    const invTok = testIssue();
+    const invRes = consumeApprovalToken({
+      token: invTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["pkg-a", "../invalid"],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("非法/含路径穿越包名消费被拒绝", !invRes.valid && /invalid package name/.test(invRes.reason));
+
+    // 4f. Empty array rejected
+    const emptyTok = testIssue();
+    const emptyRes = consumeApprovalToken({
+      token: emptyTok,
+      profile: "web",
+      profileDir,
+      spec: "multi-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: [],
+      surface: "agent",
+      owner: "agent-test",
+    });
+    check("空包名数组消费被拒绝", !emptyRes.valid && /cannot be empty/.test(emptyRes.reason));
+
+    // ── 5. Cross-browser session rejection & token isolation ─────────────────
+    const browserProof = proofFor("browser-pkg");
+    const browserTok = issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "browser-pkg",
+      preflightReport: cleanPreflightReport,
+      needsApproval: disclosureFor(browserProof),
+      proof: browserProof,
+      surface: "browser",
+      owner: "session-alpha",
+    });
+    const crossSessionRes = consumeApprovalToken({
+      token: browserTok,
+      profile: "web",
+      profileDir,
+      spec: "browser-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["browser-pkg"],
+      surface: "browser",
+      owner: "session-beta",
+    });
+    check("跨浏览器 session 消费审批 token 被拒绝且销毁", !crossSessionRes.valid && /session mismatch/.test(crossSessionRes.reason));
+
+    // 跨 surface (browser vs agent)
+    const agentProof = proofFor("agent-pkg");
+    const agentTok = issueApprovalToken({
+      profile: "web",
+      profileDir,
+      spec: "agent-pkg",
+      preflightReport: cleanPreflightReport,
+      needsApproval: disclosureFor(agentProof),
+      proof: agentProof,
+      surface: "agent",
+      owner: "agent-1",
+    });
+    const crossSurfaceRes = consumeApprovalToken({
+      token: agentTok,
+      profile: "web",
+      profileDir,
+      spec: "agent-pkg",
+      preflightReport: cleanPreflightReport,
+      allowBuildScripts: ["agent-pkg"],
+      surface: "browser",
+      owner: "browser-sess",
+    });
+    check("跨 surface (agent vs browser) 消费审批 token 失败且被销毁", !crossSurfaceRes.valid && /surface mismatch/.test(crossSurfaceRes.reason));
+
+    // Tracker 隔离与 session 校验
+    const trackerProof = proofFor("foo-script");
+    let needsApprovalOutcome = {
+      status: "needsApproval",
+      needsApproval: disclosureFor(trackerProof),
+      proof: trackerProof,
+    };
+    const approvalProducer = {
+      cancel: () => {},
+      done: Promise.resolve(needsApprovalOutcome),
+      readOutput: () => "build scripts needed",
+    };
+    const sessionTracker = createJobTracker({
+      producerFactory: () => approvalProducer,
+    });
+    const sessionJobId = sessionTracker.start({
+      profile: "web",
+      spec: "foo-script",
+      profileDir,
+      surface: "browser",
+      session: "session-alpha",
+    });
+    await new Promise((resolvePromise) => setImmediate(resolvePromise));
+
+    const snapDiffSession = sessionTracker.get(sessionJobId, "session-beta").snapshot;
+    check("不同 session 查询 job 时不会暴露 approvalToken", snapDiffSession.approvalToken === undefined);
+
+    const snapSameSession = sessionTracker.get(sessionJobId, "session-alpha").snapshot;
+    check("相同 session 查询 job 时可获取 approvalToken", typeof snapSameSession.approvalToken === "string");
+
+    let cancelRefused = false;
+    try {
+      sessionTracker.cancel(sessionJobId, "session-beta");
+    } catch (err) {
+      cancelRefused = /unauthorized/.test(err.message);
+    }
+    check("不同 session 取消 job 被拒绝", cancelRefused);
+
+    const dismissDiff = sessionTracker.dismiss(sessionJobId, "session-beta");
+    check("不同 session dismiss job 返回 false", dismissDiff === false);
+
+    const dismissSame = sessionTracker.dismiss(sessionJobId, "session-alpha");
+    check("相同 session dismiss job 成功且 token 被注销", dismissSame === true);
+    const snapAfterDismiss = sessionTracker.get(sessionJobId, "session-alpha").snapshot;
+    check("dismiss 后 job snapshot 中 approvalToken 为 undefined", snapAfterDismiss.approvalToken === undefined);
+
+    // ── 6. Windows profile names & restart plan ──────────────────────────────
+    check("合法 profile 名称识别", isSafeProfileName("web", true) && isSafeProfileName("profile_1", true) && isSafeProfileName("dev-test", true));
+    check("Windows 尾随点拒绝", !isSafeProfileName("web.", true) && !isSafeProfileName("test..", true));
+    check("Windows 尾随空格拒绝", !isSafeProfileName("web ", true) && !isSafeProfileName("test ", true));
+
+    const reservedDevices = ["CON", "prn", "aux", "nul", "COM1", "com9", "lpt1", "LPT9", "con.txt", "PRN.json", "aux.yaml", "NUL.js", "COM1.d", "lpt9.log"];
+    let allDevicesRejected = true;
+    for (const dev of reservedDevices) {
+      if (isSafeProfileName(dev, true)) {
+        allDevicesRejected = false;
+        break;
+      }
+    }
+    check("Windows 保留设备名 (含扩展名及大小写) 全部拒绝", allDevicesRejected);
+
+    // isWindows: true —— 这两条断言的是 Windows 路径语义，与运行平台无关地钉死；
+    // 否则 Linux CI 上 "CON"/"web." 是合法名，plan 会因下游原因失败、错误对不上。
+    const restartBadPlan = resolveRestartLaunchPlan({ profile: "CON", config: { allowRestart: true }, isWindows: true });
+    check("保留设备名 profile 重启 plan fail-closed", !restartBadPlan.ok && /reserved Windows device name/.test(restartBadPlan.error));
+
+    const restartDotPlan = resolveRestartLaunchPlan({ profile: "web.", config: { allowRestart: true }, isWindows: true });
+    check("尾随点 profile 重启 plan fail-closed", !restartDotPlan.ok && /dot or space/.test(restartDotPlan.error));
+
+    // ── 7. Tracker isolation: producer.done rejection handling ───────────────
+    let settledOutcome = null;
+    const rejectingProducer = {
+      cancel: () => {},
+      done: Promise.reject(new Error("simulated spawn failure")),
+      readOutput: () => "",
+    };
+    let producerCalls = 0;
+    const tracker = createJobTracker({
+      producerFactory: () => {
+        producerCalls++;
+        return rejectingProducer;
+      },
+    });
+    const jobId = tracker.start({
+      profile: "fixture-profile",
+      spec: "fail-pkg",
+      profileDir,
+      onSettled: (outcome) => { settledOutcome = outcome; },
+    });
+    await new Promise((resolvePromise) => setImmediate(resolvePromise));
+    const trackerSnapshot = tracker.get(jobId, "").snapshot;
+    check(
+      "tracker rejection fixture 使用注入 producer，不触碰真实 profile",
+      producerCalls === 1 && trackerSnapshot.status === "failed" && settledOutcome?.status === "failed",
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+
+  return failed;
+}
+
+if (process.argv.includes("--self-test")) {
+  console.log("index.js self-test:");
+  runSelfTests().then((failed) => {
+    console.log(`index.js tests finished with ${failed} failures.`);
+    process.exit(failed === 0 ? 0 : 1);
+  }).catch((err) => {
+    console.error("Self-test threw:", err);
+    process.exit(1);
+  });
+}