Skip to content

A full-featured download manager.

27.8 KB
Raw Blame
// Orchestrates the install / upgrade / uninstall lifecycle for a plugin.
//
// The install flow is two-phase:
//   1. `stage(moextPath, sourceInput)` — extracts to a staging dir, parses
//      the manifest, computes the consent payload (and any diff against an
//      existing install), and returns `{stagingId, consent}`. The renderer
//      then shows a dialog.
//   2. `commit(stagingId, grants)` — finalizes the install. On upgrade we
//      run onDeactivate, rename the old dir to a backup, swap in the new
//      one, write `_install.json`, refresh the registry, and remove the
//      backup. On failure mid-swap, the backup is restored.
//
// `uninstall(pluginId)` is the I14 cascade: deactivate → drop plugin state
// row → purge plugin_storage + plugin_task_metadata + plugin_cookie_jar →
// remove the install directory → refresh registry.

import { createHash, randomUUID } from 'node:crypto'
import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
import path from 'node:path'
import { FALLBACK_LOCALE } from '@shared/constants/locales'
import { AppError, ErrorCode } from '@shared/errors'
import { REGISTRY_PLUGIN_ID_RE } from '@shared/schemas/registry'
import type { PluginManifest } from '@shared/types/plugin'
import type {
  ConsentPayload,
  ConsentSnapshot,
  GrantsMap,
  InstallRecord,
  InstallRecordSource,
  OfficialPackageProof,
} from '@shared/types/plugin-install'
import type { FfmpegDetection } from '../capabilities/ffmpeg-detect'
import type { CapabilityHost } from '../capabilities/interface'
import {
  type ManifestLocaleDict,
  resolveManifestI18n,
} from '../manifest/i18n-resolve'
import { parseManifest } from '../manifest/parse'
import { resolveInsidePluginDir } from '../manifest/path-safety'
import type { PluginRegistry } from '../plugin-registry'
import type { PluginExecutableIdentity } from '../post/delivery-types'
import type { PluginSecurityService } from '../security/security-service'
import type { PluginStateStore } from '../state/plugin-state-store'
import { buildConsentPayload } from './consent-payload'
import {
  diffTrustSurface,
  readInstallRecord,
  requiresConsent,
  writeInstallRecord,
} from './install-record'
import { extractLoadedMoext, loadMoext } from './moext-reader'
import {
  OFFICIAL_ARCHIVE_FILENAME,
  verifyOfficialPackage,
} from './official-package'
import { computePublicCommandHashes } from './public-command-hash'
import {
  assertMatchesRegistryExpectation,
  type RegistryExpectation,
} from './registry-expectation'
import {
  normalizeSource,
  type SourceInput,
  sourceUrlEquals,
} from './source-resolver'

// Plan D will provide a real `SchemaCache`. Until then, the installer accepts
// any object exposing this minimal shape. When Plan D lands, swap the import.
export interface CommandSchemaCacheLike {
  installCommandSchemas(
    pluginId: string,
    commands: ReadonlyArray<{
      id: string
      argsSchema?: unknown
      resultSchema?: unknown
      public?: boolean
    }>
  ): void
  uninstall(pluginId: string): void
}

/**
 * Runtime teardown seam shared by the Electron and server plugin hosts.
 * `deactivate()` does not resolve until the worker bridge has been disposed.
 */
export interface PluginRuntimeHostLike {
  isQuiescent(pluginId: string): boolean
  deactivate(pluginId: string): Promise<void>
  applyPolicyMutation?<T>(
    pluginId: string,
    publish: () => Promise<T> | T
  ): Promise<T>
}

/**
 * Durable post-delivery lifecycle participant. Production binds the shared
 * PluginHookRuntime after both the installer and Hook runtime exist.
 */
export interface PluginInstallerRetentionSink {
  supersede(executable: PluginExecutableIdentity, at: number): Promise<number>
  pluginUnavailable(
    pluginId: string,
    reason: 'uninstalled',
    at: number
  ): Promise<number>
}

export interface PluginInstallerOptions {
  security?: PluginSecurityService
  pluginsDir: string
  registry: PluginRegistry
  stateStore: PluginStateStore
  capabilityHost: CapabilityHost
  hostVersion: string
  /** Test seam; production always uses the pinned official signing keys. */
  signingPubkeys?: readonly string[]
  /**
   * Optional Plan D dependency. Until Plan D lands, the installer falls
   * back to local hash computation only.
   */
  schemaCache?: CommandSchemaCacheLike
  /**
   * Server-only hook. Returns `{ok:false, reason}` to reject installation
   * before the consent payload is built. Inject `isServerAckSatisfied` here
   * on the server runtime; leave undefined on Electron.
   */
  serverAck?: (
    source: InstallRecordSource,
    prevRecord: InstallRecord | null
  ) => { ok: boolean; reason?: string }
  /**
   * Advisory availability snapshot for consent. Runtime dependencies are
   * enforced when enabling/activating the plugin, never while installing it.
   */
  ffmpegDetect?: () => Promise<FfmpegDetection>
}

interface StagedInstall {
  pluginId: string
  newManifest: PluginManifest
  source: InstallRecordSource
  stagingDir: string
  consent: ConsentPayload
  archivePath: string
  archiveSha256: string
  previousRecord: InstallRecord | null
  official?: OfficialPackageProof
  runtimeHost?: PluginRuntimeHostLike
}

export interface StageResult {
  stagingId: string
  consent: ConsentPayload
  /** True when a trust-equivalent upgrade committed without another prompt. */
  committed: boolean
  /** Present when `committed` is true. */
  pluginId?: string
}

export interface StageOptions {
  /** §6.3 registry↔manifest consistency gate; checked before any commit. */
  expect?: RegistryExpectation
  /** Digest pinned by a non-registry source such as server bootstrap. */
  expectedSha256?: string
  /** Runtime teardown seam supplied by the shell command boundary. */
  runtimeHost?: PluginRuntimeHostLike
}

async function loadManifestLocale(
  rootDir: string,
  l10n: string | undefined,
  lang: string
): Promise<ManifestLocaleDict> {
  if (!l10n) return {}
  const localeDir = resolveInsidePluginDir(rootDir, l10n)
  if (!localeDir) return {}
  try {
    const raw = await readFile(path.join(localeDir, `${lang}.json`), 'utf8')
    const parsed = JSON.parse(raw)
    const out: ManifestLocaleDict = {}
    for (const [key, value] of Object.entries(parsed)) {
      if (typeof value === 'string') out[key] = value
    }
    return out
  } catch {
    return {}
  }
}

async function resolveManifestForInstall(
  manifest: PluginManifest,
  rootDir: string
): Promise<PluginManifest> {
  const l10n = (manifest as { l10n?: string }).l10n
  const fallback = await loadManifestLocale(rootDir, l10n, FALLBACK_LOCALE)
  return resolveManifestI18n(manifest, {
    currentDict: fallback,
    fallbackDict: fallback,
  })
}

function resolvePluginInstallDir(pluginsDir: string, pluginId: string): string {
  if (!REGISTRY_PLUGIN_ID_RE.test(pluginId)) {
    throw new AppError(
      ErrorCode.PluginManifestInvalid,
      'plugin.install.invalid_plugin_id'
    )
  }

  const root = path.resolve(pluginsDir)
  const candidate = path.resolve(root, pluginId)
  const relative = path.relative(root, candidate)
  if (
    relative === '' ||
    relative === '..' ||
    relative.startsWith(`..${path.sep}`) ||
    path.isAbsolute(relative)
  ) {
    throw new AppError(
      ErrorCode.PluginManifestInvalid,
      'plugin.install.invalid_plugin_id'
    )
  }
  return candidate
}

function sameInstallRecord(
  left: InstallRecord | null,
  right: InstallRecord | null
): boolean {
  if (left === null || right === null) return left === right
  return JSON.stringify(left) === JSON.stringify(right)
}

export class PluginInstaller {
  private readonly pending = new Map<string, StagedInstall>()
  private readonly mutationTails = new Map<string, Promise<void>>()
  private retentionSink?: PluginInstallerRetentionSink

  constructor(private readonly opts: PluginInstallerOptions) {}

  bindRetentionSink(sink: PluginInstallerRetentionSink): void {
    if (this.retentionSink && this.retentionSink !== sink) {
      throw new Error('plugin installer retention sink is already bound')
    }
    this.retentionSink = sink
  }

  async stage(
    moextPath: string,
    sourceInput: SourceInput,
    options?: StageOptions
  ): Promise<StageResult> {
    const stagingDir = path.join(
      this.opts.pluginsDir,
      '_staging',
      `s_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`
    )
    const extractedDir = path.join(stagingDir, 'tree')
    const archivePath = path.join(stagingDir, 'archive.moext')
    const loadedMoext = await loadMoext(moextPath)
    const official =
      options?.expect?.requiresOfficialSignature ||
      options?.expect?.officialSignature
        ? verifyOfficialPackage(
            loadedMoext,
            options.expect.officialSignature,
            this.opts.signingPubkeys
          )
        : undefined
    const pinnedSha256 =
      sourceInput.type === 'local'
        ? sourceInput.fileHash
        : (options?.expectedSha256 ?? options?.expect?.packageSha256)
    if (pinnedSha256 && loadedMoext.archiveSha256 !== pinnedSha256) {
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        sourceInput.type === 'local'
          ? 'plugin.install.local_file_hash_mismatch'
          : 'plugin.install.sha256_mismatch'
      )
    }

    let manifestRaw: string
    let bundleSha256: string
    try {
      const extracted = await extractLoadedMoext(loadedMoext, extractedDir)
      manifestRaw = extracted.manifestRaw
      bundleSha256 = extracted.bundleSha256
      // Consent can remain open indefinitely. Keep the exact package on disk
      // instead of retaining up to 5 MiB in the installer's pending Map.
      await writeFile(archivePath, loadedMoext.bytes, {
        flag: 'wx',
        mode: 0o600,
      })
    } catch (error) {
      await rm(stagingDir, { recursive: true, force: true })
      throw error
    }

    let parsedManifest: PluginManifest
    try {
      const result = parseManifest(manifestRaw, {
        hostVersion: this.opts.hostVersion,
        official: official !== undefined,
      })
      parsedManifest = await resolveManifestForInstall(
        result.manifest as PluginManifest,
        extractedDir
      )
    } catch (e) {
      await rm(stagingDir, { recursive: true, force: true })
      throw e
    }

    if (options?.expect) {
      try {
        assertMatchesRegistryExpectation(parsedManifest, options.expect)
      } catch (e) {
        await rm(stagingDir, { recursive: true, force: true })
        throw e
      }
    }

    const normalized = normalizeSource(sourceInput)
    const source: InstallRecordSource = {
      type: normalized.type,
      url: normalized.url,
      bundleSha256,
      archiveSha256: loadedMoext.archiveSha256,
      recordedAt: Date.now(),
    }
    try {
      await this.opts.security?.refreshIfStale()
      this.opts.security?.assertAllowed({
        pluginId: parsedManifest.id,
        version: parsedManifest.version,
        archiveSha256: loadedMoext.archiveSha256,
      })
    } catch (error) {
      await rm(stagingDir, { recursive: true, force: true })
      throw error
    }
    const finalDir = resolvePluginInstallDir(
      this.opts.pluginsDir,
      parsedManifest.id
    )
    const prev = await readInstallRecord(finalDir)

    if (this.opts.registry.get(parsedManifest.id)?.origin === 'builtin') {
      await rm(stagingDir, { recursive: true, force: true })
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        'plugin.install.builtin_already_installed'
      )
    }
    if (prev?.official && !official) {
      await rm(stagingDir, { recursive: true, force: true })
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        'plugin.install.official_signature_invalid'
      )
    }

    if (this.opts.serverAck) {
      const r = this.opts.serverAck(source, prev)
      if (!r.ok) {
        await rm(stagingDir, { recursive: true, force: true })
        throw new AppError(
          ErrorCode.PluginManifestInvalid,
          r.reason ?? 'plugin.lifecycle.unsigned_not_allowed'
        )
      }
    }

    // I6 — plugin id is immutable across upgrades.
    if (prev && prev.pluginId !== parsedManifest.id) {
      await rm(stagingDir, { recursive: true, force: true })
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        'plugin.manifest.id_collision_with_builtin'
      )
    }

    const nextSnapshot: ConsentSnapshot = {
      permissions: parsedManifest.permissions,
      optionalPermissions: parsedManifest.optionalPermissions ?? [],
      invokesCommands: parsedManifest.invokesCommands ?? [],
      publicCommands: computePublicCommandHashes(parsedManifest),
      requestedHeapMB: parsedManifest.requestedHeapMB ?? 32,
      enginesMotrix: parsedManifest.engines.motrix,
      hostPermissions: parsedManifest.hostPermissions ?? [],
    }

    let diff = prev ? diffTrustSurface(prev, nextSnapshot) : null
    if (prev && diff) {
      if (!sourceUrlEquals(prev.source, source)) {
        diff = {
          ...diff,
          sourceUrlChanged: { from: prev.source.url, to: source.url },
        }
      }
    }
    const needConsent = !prev || (diff !== null && requiresConsent(diff))

    const needsFfmpeg =
      parsedManifest.permissions.includes('ffmpeg') ||
      (parsedManifest.optionalPermissions ?? []).includes('ffmpeg')

    let ffmpegDetection: FfmpegDetection = { available: false }
    if (needsFfmpeg && this.opts.ffmpegDetect) {
      try {
        ffmpegDetection = await this.opts.ffmpegDetect()
      } catch {
        // A failed probe must not prevent storing a valid, consented package.
      }
    }

    const installedCalleeTitles = this.collectCalleeTitles(
      parsedManifest.invokesCommands ?? []
    )
    const consent = buildConsentPayload(
      parsedManifest,
      source,
      prev,
      diff,
      installedCalleeTitles,
      { ffmpegDetection }
    )
    consent.trustSurface.notVerified = official === undefined

    // Locale/manifest resolution is complete. A pending consent transaction
    // only needs the protected archive, so do not retain a second extracted
    // copy indefinitely alongside it.
    await rm(extractedDir, { recursive: true, force: true })

    const stagingId = path.basename(stagingDir)
    const staged: StagedInstall = {
      pluginId: parsedManifest.id,
      newManifest: parsedManifest,
      source,
      stagingDir,
      consent,
      archivePath,
      archiveSha256: loadedMoext.archiveSha256,
      previousRecord: prev,
      official,
      runtimeHost: options?.runtimeHost,
    }
    this.pending.set(stagingId, staged)

    if (!needConsent) {
      const committed = await this.commit(
        stagingId,
        prev?.grants ?? {},
        options?.runtimeHost
      )
      return {
        stagingId,
        consent,
        committed: true,
        pluginId: committed.pluginId,
      }
    }
    return { stagingId, consent, committed: false }
  }

  async commit(
    stagingId: string,
    grants: GrantsMap,
    runtimeHost?: PluginRuntimeHostLike
  ): Promise<{ pluginId: string }> {
    const staged = this.pending.get(stagingId)
    if (!staged) {
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        'plugin.install.staging_not_found'
      )
    }

    const liveHost = runtimeHost ?? staged.runtimeHost
    return this.withPluginMutation(staged.pluginId, () =>
      this.withRuntimePolicyMutation(staged.pluginId, liveHost, async () => {
        // A second commit may have consumed this staging entry while this call
        // waited for the per-plugin mutation lock.
        if (this.pending.get(stagingId) !== staged) {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.staging_not_found'
          )
        }

        const finalDir = resolvePluginInstallDir(
          this.opts.pluginsDir,
          staged.pluginId
        )
        const prev = await readInstallRecord(finalDir)
        if (this.opts.registry.get(staged.pluginId)?.origin === 'builtin') {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.builtin_already_installed'
          )
        }
        if (!sameInstallRecord(prev, staged.previousRecord)) {
          throw new AppError(
            ErrorCode.PluginManifestInvalid,
            'plugin.install.changed_since_staging'
          )
        }

        const record: InstallRecord = {
          version: 1,
          pluginId: staged.pluginId,
          source: staged.source,
          securityReviewed: !this.opts.security?.configured,
          grants,
          consentSnapshot: {
            permissions: staged.newManifest.permissions,
            optionalPermissions: staged.newManifest.optionalPermissions ?? [],
            invokesCommands: staged.newManifest.invokesCommands ?? [],
            publicCommands: computePublicCommandHashes(staged.newManifest),
            requestedHeapMB: staged.newManifest.requestedHeapMB ?? 32,
            enginesMotrix: staged.newManifest.engines.motrix,
            hostPermissions: staged.newManifest.hostPermissions ?? [],
          },
          ...(staged.official ? { official: staged.official } : {}),
        }
        const commitDir = path.join(
          this.opts.pluginsDir,
          '_staging',
          `c_${randomUUID()}`
        )
        let backupDir: string | null = null
        let swapped = false
        let supersededExecutable: PluginExecutableIdentity | undefined

        try {
          this.opts.security?.assertAllowed({
            pluginId: staged.pluginId,
            version: staged.newManifest.version,
            archiveSha256: staged.archiveSha256,
          })
          // Never commit the long-lived staging tree: it was visible while the
          // consent dialog was open. Re-read through one file descriptor, verify
          // the staged archive digest, then extract those exact bytes into the
          // one-shot swap directory.
          const loadedMoext = await loadMoext(staged.archivePath)
          if (loadedMoext.archiveSha256 !== staged.archiveSha256) {
            throw new AppError(
              ErrorCode.PluginManifestInvalid,
              staged.official
                ? 'plugin.install.official_signature_invalid'
                : 'plugin.install.sha256_mismatch'
            )
          }
          await extractLoadedMoext(loadedMoext, commitDir)
          if (staged.official) {
            verifyOfficialPackage(
              loadedMoext,
              staged.official.signature,
              this.opts.signingPubkeys
            )
            await writeFile(
              path.join(commitDir, OFFICIAL_ARCHIVE_FILENAME),
              loadedMoext.bytes,
              { flag: 'wx', mode: 0o600 }
            )
          }
          await writeInstallRecord(commitDir, record)
          await mkdir(this.opts.pluginsDir, { recursive: true })

          if (prev) {
            // PluginHost.deactivate waits for the worker-side handler, tears
            // down the bridge, and terminates the worker before disk changes.
            await this.stopRuntime(staged.pluginId, liveHost)
            supersededExecutable = await this.executableSupersededBy(
              staged,
              commitDir
            )
            backupDir = `${finalDir}.bak-${randomUUID()}`
            await rename(finalDir, backupDir)
          }
          await rename(commitDir, finalDir)
          swapped = true

          this.installCommandSchemas(staged.pluginId, staged.newManifest)
          await this.opts.registry.discover()
          this.opts.security?.assertAllowed({
            pluginId: staged.pluginId,
            version: staged.newManifest.version,
            archiveSha256: staged.archiveSha256,
          })
          if (
            staged.official &&
            !this.opts.registry.get(staged.pluginId)?.official
          ) {
            throw new AppError(
              ErrorCode.PluginManifestInvalid,
              'plugin.install.official_signature_invalid'
            )
          }
          if (supersededExecutable) {
            // Admission remains closed until this succeeds. If durable
            // terminalization fails, the catch below restores the old bundle
            // and registry identity, so no delivery is lost for an upgrade
            // that did not commit.
            await this.retentionSink?.supersede(
              supersededExecutable,
              Date.now()
            )
          }

          this.pending.delete(stagingId)
          await rm(staged.stagingDir, { recursive: true, force: true }).catch(
            () => undefined
          )
          if (backupDir) {
            await rm(backupDir, { recursive: true, force: true }).catch(
              () => undefined
            )
          }
          return { pluginId: staged.pluginId }
        } catch (error) {
          if (backupDir) {
            if (swapped) {
              await rm(finalDir, { recursive: true, force: true }).catch(
                () => undefined
              )
            }
            await rename(backupDir, finalDir).catch(() => undefined)
          } else if (swapped) {
            await rm(finalDir, { recursive: true, force: true }).catch(
              () => undefined
            )
          }
          if (backupDir || swapped) {
            await this.opts.registry
              .discover()
              .then(() => {
                const restored = this.opts.registry.get(staged.pluginId)
                if (restored) {
                  this.installCommandSchemas(staged.pluginId, restored.manifest)
                } else if (this.opts.schemaCache) {
                  this.opts.schemaCache.uninstall(staged.pluginId)
                }
              })
              .catch(() => undefined)
          }
          throw error
        } finally {
          await rm(commitDir, { recursive: true, force: true }).catch(
            () => undefined
          )
        }
      })
    )
  }

  async cancel(stagingId: string): Promise<void> {
    const staged = this.pending.get(stagingId)
    if (!staged) return
    await this.withPluginMutation(staged.pluginId, async () => {
      if (this.pending.get(stagingId) !== staged) return
      this.pending.delete(stagingId)
      await rm(staged.stagingDir, { recursive: true, force: true })
    })
  }

  async uninstall(
    pluginId: string,
    runtimeHost?: PluginRuntimeHostLike
  ): Promise<void> {
    const finalDir = resolvePluginInstallDir(this.opts.pluginsDir, pluginId)
    await this.withPluginMutation(pluginId, () =>
      this.withRuntimePolicyMutation(pluginId, runtimeHost, async () => {
        // A worker retaining old code must not survive removal of its durable
        // files. Unlike handler failures (which PluginHost handles internally),
        // a bridge-disposal failure aborts the uninstall.
        if (runtimeHost) {
          await this.stopRuntime(pluginId, runtimeHost)
        } else {
          // Preserve the legacy direct-installer behavior for embedders that do
          // not yet supply a PluginHost. Production IPC always passes it.
          await this.opts.capabilityHost.lifecycle
            .runDeactivate(pluginId)
            .catch(() => undefined)
        }
        // Diagnostics remain on disk, but no writer may outlive its plugin.
        // A flush/close failure aborts before any durable plugin state is removed.
        await this.opts.capabilityHost.releaseLog?.(pluginId)
        const removedDir = path.join(
          this.opts.pluginsDir,
          '_staging',
          `u_${randomUUID()}`
        )
        await mkdir(path.dirname(removedDir), { recursive: true })
        let bundleMoved = false
        try {
          await rename(finalDir, removedDir)
          bundleMoved = true
        } catch (error) {
          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
        }
        try {
          await this.opts.registry.discover()
          await this.retentionSink?.pluginUnavailable(
            pluginId,
            'uninstalled',
            Date.now()
          )
        } catch (error) {
          if (bundleMoved) {
            await rename(removedDir, finalDir)
            await this.opts.registry.discover()
          }
          throw error
        }
        this.opts.stateStore.remove(pluginId)
        await this.opts.capabilityHost.storage.deleteAll(pluginId)
        await this.opts.capabilityHost.metadata.deleteAllForPlugin(pluginId)
        this.opts.capabilityHost.cookieJarFor(pluginId).clear()
        if (bundleMoved) {
          await rm(removedDir, { recursive: true, force: true })
        }
        if (this.opts.schemaCache) this.opts.schemaCache.uninstall(pluginId)
      })
    )
  }

  private installCommandSchemas(
    pluginId: string,
    manifest: PluginManifest
  ): void {
    if (!this.opts.schemaCache) return
    this.opts.schemaCache.installCommandSchemas(
      pluginId,
      (manifest.contributes.commands ?? []) as ReadonlyArray<{
        id: string
        argsSchema?: unknown
        resultSchema?: unknown
        public?: boolean
      }>
    )
  }

  private async executableSupersededBy(
    staged: StagedInstall,
    commitDir: string
  ): Promise<PluginExecutableIdentity | undefined> {
    const sink = this.retentionSink
    if (!sink) return undefined
    const previous = this.opts.registry.policySnapshot(staged.pluginId)
    if (!previous?.executableDigest) {
      throw new AppError(
        ErrorCode.PluginRuntimeFault,
        'plugin.install.previous_executable_identity_missing'
      )
    }
    const nextEntry = resolveInsidePluginDir(commitDir, staged.newManifest.main)
    if (!nextEntry) {
      throw new AppError(
        ErrorCode.PluginManifestInvalid,
        'plugin.install.main_outside_plugin_root'
      )
    }
    const nextDigest = createHash('sha256')
      .update(await readFile(nextEntry))
      .digest('hex')
    if (
      previous.version === staged.newManifest.version &&
      previous.executableDigest === nextDigest
    ) {
      return undefined
    }
    return {
      pluginId: staged.pluginId,
      version: previous.version,
      digest: previous.executableDigest,
    }
  }

  private async stopRuntime(
    pluginId: string,
    runtimeHost?: PluginRuntimeHostLike
  ): Promise<void> {
    if (!runtimeHost) {
      await this.opts.capabilityHost.lifecycle.runDeactivate(pluginId)
      return
    }
    await runtimeHost.deactivate(pluginId)
    if (!runtimeHost.isQuiescent(pluginId)) {
      throw new AppError(
        ErrorCode.PluginRuntimeFault,
        'plugin.install.runtime_still_active'
      )
    }
  }

  private withRuntimePolicyMutation<T>(
    pluginId: string,
    runtimeHost: PluginRuntimeHostLike | undefined,
    operation: () => Promise<T>
  ): Promise<T> {
    return runtimeHost?.applyPolicyMutation
      ? runtimeHost.applyPolicyMutation(pluginId, operation)
      : operation()
  }

  private async withPluginMutation<T>(
    pluginId: string,
    operation: () => Promise<T>
  ): Promise<T> {
    const previous = this.mutationTails.get(pluginId) ?? Promise.resolve()
    let release!: () => void
    const current = new Promise<void>((resolve) => {
      release = resolve
    })
    const tail = previous.then(
      () => current,
      () => current
    )
    this.mutationTails.set(pluginId, tail)
    await previous.catch(() => undefined)
    try {
      return await operation()
    } finally {
      release()
      if (this.mutationTails.get(pluginId) === tail) {
        this.mutationTails.delete(pluginId)
      }
    }
  }

  private collectCalleeTitles(
    invokes: ReadonlyArray<string>
  ): Record<string, string> {
    const titles: Record<string, string> = {}
    for (const cmd of invokes) {
      // Convention: `<pluginId>.<commandShortName>` — first two dot segments
      // identify the callee plugin. This matches Plan D's command-id format.
      const segments = cmd.split('.')
      if (segments.length < 3) continue
      const calleePluginId = segments.slice(0, 2).join('.')
      const callee = this.opts.registry.get(calleePluginId)
      const declared = callee?.manifest.contributes.commands
      const found = declared?.find((d) => d.id === cmd)
      if (found) titles[cmd] = found.title
    }
    return titles
  }
}