Skip to content

The agent that grows with you

38.0 KB
Raw Blame
/**
 * Runtime plugin loader — plugins as CODE, not registry edits, loaded after
 * build time. The pipeline every non-bundled plugin takes:
 *
 *   source (plain ESM js) -> import allowlist (`@hermes/plugin-sdk` / `react*`
 *   only) -> bare-specifier rewrite to live shim blobs (see sdk/runtime.ts)
 *   -> blob `import()` -> validate default HermesPlugin -> register(ctx)
 *
 * Loading the same plugin id again disposes the previous registrations first
 * (agent rewrites a plugin file -> clean reload) — everything taken out
 * through `ctx` (contributions, events, sockets, `ctx.setInterval`/
 * `ctx.addEventListener`); bare globals and module-scope state are the
 * plugin's own. Failures toast + log; a broken plugin can never take the app
 * down, and a module whose evaluation never settles times out on its own row.
 *
 * Sources today: the in-repo runtime example (`?raw`, proves the pipeline)
 * and the two on-disk doors — `<hermes home>/desktop-plugins/<name>/plugin.js`
 * and the unified agent-plugin half `<hermes home>/plugins/<name>/desktop/
 * plugin.js` — the doors the agent writes through.
 *
 * SECURITY — this is NOT a capability boundary. A loaded plugin is evaluated
 * as ESM in the renderer realm with FULL app authority: the React singleton,
 * the whole SDK (`host.request` gateway RPC, `ctx.rest`, storage, `navigate`).
 * The isolation here is *error* isolation only (ContribBoundary, isolated
 * listeners) — a plugin can't crash the app, but it can do anything the app
 * can. That's acceptable for local sources (disk files can already run code),
 * and for catalog installs the trust comes from admission (human review of
 * an exact pinned SHA + the static lint in hermes_cli/plugin_validate_desktop.py),
 * not from this loader. The import allowlist below is the one runtime tripwire:
 * a plugin cannot pull a second stage from a URL. The Webapp's HTTP door
 * (`/api/desktop-plugins/*`, browser-desktop-plugins.ts) counts as local: it is
 * same-origin, reads the serving host's own disk, and runs in a tab that holds no
 * more authority than that host already grants it. A remote source (https +
 * allowlist) must NOT reuse this pipeline as-is: it needs a real boundary
 * (iframe/worker + CSP + capability gating) before it can land.
 */

import { atom } from 'nanostores'

import { isReadFileErrorResult } from '@/lib/desktop-fs'
import { installPluginSdk, sdkImportMap } from '@/sdk/runtime'
import { notifyError } from '@/store/notifications'
import { forgetPluginPreviewAccess } from '@/store/plugin-preview-grants'

import { trackGatewayEventDisposers } from './events'
import { createPluginContext, declaredCapabilities, type HermesPlugin } from './plugin'
import { $pluginRecords, dropPlugin, pluginActive, type PluginKind, publishPlugin } from './plugins-store'

interface LoadOptions {
  /** Root-level default-enable CAP: `false` ships the plugin opt-in (inventory
   *  row, off until the user toggles) even if the plugin says otherwise. The
   *  unified agent-plugin root sets this so `~/.hermes/plugins` keeps its
   *  installed-but-inert posture (GHSA-mcfc-hp25-cjv7) on the desktop side too. */
  defaultEnabled?: boolean
  /** Absolute plugin.js path (disk plugins) — recorded for reveal/inventory. */
  file?: string
  /** Inventory bucket; the disk door is the default runtime source. */
  kind?: PluginKind
  /** Agent package whose desktop half this is (unified packages). */
  packageName?: string
  packageOrigin?: PackageMarker['origin']
}

/** Live runtime plugins: id -> disposers (unload/reload support). */
const loaded = new Map<string, (() => void)[]>()

/** Module evaluation deadline. A top-level `await` that never settles (a dead
 *  host, a gateway that is not up) would otherwise hang `import()` forever —
 *  and, through the disk scan's sequential loop, every plugin listed after it. */
const IMPORT_TIMEOUT_MS = 10_000

// Matches the specifier of a static `from '…'`, a side-effect `import '…'`, or
// a dynamic `import('…')`. Deliberately loose — a sentence ending in `from`, a
// quoted example, a commented-out import all match it — so a match is honoured
// only when it sits in CODE (see `codeRanges`), never in a string or comment.
const importSpecifierRe = () => /(from\s*|import\s*\(\s*|import\s+)(['"])([^'"]+)\2/g

/** Character ranges of *source* that are code — string, template-literal and
 *  comment text excluded (template `${…}` interpolations ARE code). The
 *  specifier regex is not syntax-aware, so this is what keeps a plugin's own
 *  copy and comments — `const label = 'Copy keys from'`, `// import 'x'` —
 *  from being read as import syntax (rejected as "unsupported import") or
 *  rewritten in place (a mapped specifier inside a string must stay verbatim).
 *  Regex literals are excluded too: a quote or backtick inside a pattern
 *  (#120208) must not open a string/template state. */

/** Keywords after which a `/` opens a regex literal, never a division. */
const regexKeywordRe = /^(?:await|case|delete|do|else|in|instanceof|new|of|return|throw|typeof|void|yield)$/

/** True when the `/` at `slash` (already known not to start `//` or `/*`)
 *  opens a regex literal: the previous significant char cannot end a value.
 *  Standard division-vs-regex heuristic. */
function isRegexStart(source: string, slash: number): boolean {
  let j = slash - 1

  while (j >= 0 && /\s/.test(source[j])) {
    j -= 1
  }

  if (j < 0) {
    return true
  }

  const prev = source[j]

  // Postfix `++`/`--` ends a value (division); a lone `+`/`-` cannot.
  if (prev === '+' || prev === '-') {
    return source[j - 1] !== prev
  }

  // Identifier, number, string/template end, `)` or `]` end a value.
  if (prev === ')' || prev === ']' || prev === "'" || prev === '"' || prev === '`') {
    return false
  }

  // Block-end `}` resolves toward regex — `} /re/` (statement-start
  // pattern) is real code, `} / 2` (dividing a block) is not. Revisit if a
  // plugin ever divides a block result.
  if (prev === '}') {
    return true
  }

  if (/[A-Za-z0-9_$]/.test(prev)) {
    let k = j

    while (k >= 0 && /[A-Za-z0-9_$]/.test(source[k])) {
      k -= 1
    }

    // `x.return / 2` divides a property, it is not `return /re/`.
    if (source[k] === '.') {
      return false
    }

    return regexKeywordRe.test(source.slice(k + 1, j + 1))
  }

  return true
}

/** End offset (exclusive) of the regex literal opened at `slash`, or -1 when
 *  the pattern never closes on this line (so the `/` was a division).
 *  Escapes and `[...]` classes are honored so a quote or backtick inside the
 *  pattern (#120208) cannot leak into the surrounding lex. */
function regexEnd(source: string, slash: number): number {
  let j = slash + 1
  let inClass = false

  while (j < source.length) {
    const c = source[j]

    if (c === '\\') {
      j += 2
    } else if (c === '\n') {
      return -1
    } else if (c === '[') {
      inClass = true
      j += 1
    } else if (c === ']') {
      inClass = false
      j += 1
    } else if (c === '/' && !inClass) {
      j += 1

      while (j < source.length && /[A-Za-z]/.test(source[j])) {
        j += 1
      }

      return j
    } else {
      j += 1
    }
  }

  return -1
}

function codeRanges(source: string): Array<[number, number]> {
  const ranges: Array<[number, number]> = []
  const stack: Array<'expr' | 'template'> = []
  let state: 'block-comment' | 'code' | 'double' | 'line-comment' | 'single' | 'template' = 'code'
  let codeStart = 0
  let i = 0

  const closeCode = (end: number) => {
    if (end > codeStart) {
      ranges.push([codeStart, end])
    }
  }

  while (i < source.length) {
    const ch = source[i]
    const next = i + 1 < source.length ? source[i + 1] : ''

    if (state === 'code') {
      if (ch === '/' && next === '/') {
        closeCode(i)
        state = 'line-comment'
        i += 2
      } else if (ch === '/' && next === '*') {
        closeCode(i)
        state = 'block-comment'
        i += 2
      } else if (ch === "'") {
        closeCode(i)
        state = 'single'
        i += 1
      } else if (ch === '"') {
        closeCode(i)
        state = 'double'
        i += 1
      } else if (ch === '`') {
        closeCode(i)
        stack.push('template')
        state = 'template'
        i += 1
      } else if (ch === '/') {
        // A lone `/` (not `//` or `/*`, handled above) opens a regex literal
        // when the previous significant token cannot end a value (#120208).
        // Otherwise it is a division and stays plain code.
        const end = isRegexStart(source, i) ? regexEnd(source, i) : -1

        if (end > 0) {
          // The pattern is not code: import-looking text inside it must
          // neither match nor be rewritten in place.
          closeCode(i)
          i = end
          codeStart = i
        } else {
          i += 1
        }
      } else if (ch === '}' && stack[stack.length - 1] === 'expr') {
        closeCode(i)
        stack.pop()
        state = 'template'
        i += 1
      } else {
        i += 1
      }

      continue
    }

    if (state === 'line-comment') {
      if (ch === '\n') {
        state = 'code'
        codeStart = i
      }

      i += 1

      continue
    }

    if (state === 'block-comment') {
      if (ch === '*' && next === '/') {
        i += 2
        state = 'code'
        codeStart = i
      } else {
        i += 1
      }

      continue
    }

    if (state === 'single' || state === 'double') {
      if (ch === '\\') {
        i += 2
      } else if (ch === (state === 'single' ? "'" : '"')) {
        i += 1
        state = 'code'
        codeStart = i
      } else if (ch === '\n') {
        // Unterminated literal — recover as code so one stray quote cannot
        // swallow the rest of the file.
        i += 1
        state = 'code'
        codeStart = i
      } else {
        i += 1
      }

      continue
    }

    // Template-literal text.
    if (ch === '\\') {
      i += 2
    } else if (ch === '$' && next === '{') {
      stack.push('expr')
      state = 'code'
      i += 2
      codeStart = i
    } else if (ch === '`') {
      stack.pop()
      state = 'code'
      i += 1
      codeStart = i
    } else {
      i += 1
    }
  }

  closeCode(source.length)

  return ranges
}

/** True when *at* sits inside a code range (ordered, non-overlapping). */
function inCode(ranges: Array<[number, number]>, at: number): boolean {
  for (const [start, end] of ranges) {
    if (at < start) {
      return false
    }

    if (at < end) {
      return true
    }
  }

  return false
}

/** Rewrite ONLY mapped import specifiers (@hermes/plugin-sdk, react*) to their
 *  live shim blob URLs — never occurrences inside strings/comments. */
function rewriteSpecifiers(source: string): string {
  const map = sdkImportMap()
  const ranges = codeRanges(source)

  return source.replace(importSpecifierRe(), (whole, pre, quote, spec, offset) =>
    map[spec] && inCode(ranges, Number(offset)) ? `${pre}${quote}${map[spec]}${quote}` : whole
  )
}

/** Import specifiers outside the SDK map. Everything that is not
 *  `@hermes/plugin-sdk` / `react*` is refused up-front: a bare package would
 *  only fail later as a cryptic native "Failed to resolve module specifier",
 *  a relative path cannot resolve against the blob: base the module is
 *  evaluated from, and a URL scheme (`import 'https://…'`) is a second stage
 *  the admission lint must never be able to wave through — the loader is the
 *  last tripwire for catalog installs. */
function unsupportedImports(source: string): string[] {
  const map = sdkImportMap()
  const unsupported = new Set<string>()
  const ranges = codeRanges(source)

  for (const m of source.matchAll(importSpecifierRe())) {
    const spec = m[3]

    // Strings and comments can quote any text; only real code counts.
    if (!spec || !inCode(ranges, m.index ?? 0)) {
      continue
    }

    if (!map[spec]) {
      unsupported.add(spec)
    }
  }

  return [...unsupported]
}

export function unloadRuntimePlugin(id: string): void {
  const disposers = loaded.get(id)

  // Released BEFORE the disposers run, and each disposer in its own
  // try/catch: a disposer with its own bug must not wedge the registry
  // (#126338). With a bare forEach the throw aborted the loop and stranded
  // the delete, so every later reload re-ran the same broken disposers and
  // died before the fresh register() — file edits looked inert until an
  // app restart.
  loaded.delete(id)

  disposers?.forEach(dispose => {
    try {
      dispose()
    } catch (error) {
      console.error(`[plugins] ${id}: disposer failed during unload`, error)
    }
  })
}

/** Evaluate + register one runtime plugin. Returns its id, or null on failure. */
export async function loadRuntimePlugin(
  source: string,
  origin: string,
  options: LoadOptions = {}
): Promise<null | string> {
  installPluginSdk()

  try {
    const unsupported = unsupportedImports(source)

    if (unsupported.length > 0) {
      throw new Error(
        `unsupported import${unsupported.length > 1 ? 's' : ''}: ${unsupported.join(', ')} — ` +
          `runtime plugins may only import @hermes/plugin-sdk and react`
      )
    }

    const url = URL.createObjectURL(new Blob([rewriteSpecifiers(source)], { type: 'text/javascript' }))

    let mod: { default?: HermesPlugin }
    let deadline: ReturnType<typeof setTimeout> | undefined

    try {
      mod = await Promise.race([
        import(/* @vite-ignore */ url) as Promise<{ default?: HermesPlugin }>,
        new Promise<never>((_, reject) => {
          deadline = setTimeout(
            () =>
              reject(
                new Error(`import timed out after ${IMPORT_TIMEOUT_MS / 1000}s — module evaluation never settled`)
              ),
            IMPORT_TIMEOUT_MS
          )
        })
      ])
    } finally {
      clearTimeout(deadline)
      URL.revokeObjectURL(url)
    }

    const plugin = mod.default

    if (!plugin?.id || typeof plugin.register !== 'function') {
      throw new Error(`${origin} has no valid default HermesPlugin export`)
    }

    // A disk/runtime copy of a plugin that now ships BUNDLED (e.g. a
    // standalone install of hermes-bots predating its adoption in-tree) must
    // not register a second time: contributions would double up and the two
    // copies would fight over storage. The bundled copy wins; the disk copy
    // is skipped — but VISIBLY: a silent skip left the stale folder
    // undiscoverable while (on shells without the bundled twin) the same
    // folder actively breaks the feature it shadows. The inventory row
    // carries the file path so Capabilities → Plugins can reveal it for deletion.
    if ($pluginRecords.get()[plugin.id]?.kind === 'bundled') {
      console.info(`[plugins] ${origin} skipped — "${plugin.id}" already ships bundled with the app`)
      publishPlugin({
        id: `${plugin.id}:disk-shadowed`,
        name: `${plugin.name ?? plugin.id} (stale disk copy)`,
        description: `Shadowed by the bundled "${plugin.id}" plugin — this folder is no longer used and can be deleted.`,
        kind: options.kind ?? 'disk',
        file: options.file,
        status: 'disabled'
      })

      return null
    }

    // Two files claiming one id (a standalone install beside a unified-package
    // copy): the FIRST loaded owns the id. Silently letting the second win
    // disposed the first's registrations and made each file's hot-reload flip
    // ownership; instead the later file errors on its own folder row.
    const owner = $pluginRecords.get()[plugin.id]

    if (owner && owner.file !== options.file) {
      throw new Error(`duplicate id "${plugin.id}", already loaded from ${owner.file ?? owner.kind}`)
    }

    const capabilities = declaredCapabilities(plugin)

    const record = {
      id: plugin.id,
      name: plugin.name ?? plugin.id,
      description: plugin.description,
      capabilities,
      kind: options.kind ?? 'disk',
      file: options.file,
      packageName: options.packageName,
      packageOrigin: options.packageOrigin
    }

    const failRegistration = (error: unknown) => {
      // Roll back everything register() managed before it failed — a
      // half-registered plugin must not leave live contributions/listeners
      // nobody can ever dispose — and land the failure on the plugin's OWN
      // row so Capabilities → Plugins shows it (the toggle stays usable).
      // unloadRuntimePlugin() tolerates a throwing disposer, so a cleanup
      // bug in the rollback can neither strand the remaining disposers nor
      // hold the registration — the #126338 wedge where every later reload
      // re-ran the same broken disposers instead of the fixed file.
      unloadRuntimePlugin(plugin.id)
      console.error(`[plugins] ${plugin.id} failed to register (${origin})`, error)
      notifyError(error, `Plugin "${record.name}" failed to register`)
      publishPlugin({ ...record, status: 'error', error: error instanceof Error ? error.message : String(error) })
    }

    const activate = () => {
      // Reload = dispose the previous incarnation, then register fresh.
      unloadRuntimePlugin(plugin.id)
      const disposers: (() => void)[] = []
      // Registered BEFORE register() runs so a throw mid-way is disposable.
      loaded.set(plugin.id, disposers)

      let result: unknown

      try {
        result = trackGatewayEventDisposers(
          dispose => disposers.push(dispose),
          () => plugin.register(createPluginContext(plugin.id, dispose => disposers.push(dispose), capabilities))
        )
      } catch (error) {
        failRegistration(error)

        return
      }

      publishPlugin({ ...record, status: 'loaded' })

      // An `async register()` that rejects would otherwise be an unhandled
      // rejection beside a row that says "loaded".
      if (result && typeof (result as PromiseLike<unknown>).then === 'function') {
        void Promise.resolve(result).catch((error: unknown) => {
          if (loaded.get(plugin.id) === disposers) {
            failRegistration(error)
          }
        })
      }
    }

    publishPlugin({ ...record, status: 'disabled' }, { activate, deactivate: () => unloadRuntimePlugin(plugin.id) })

    // A disabled plugin still inventories (settings shows it, toggle
    // reactivates via the handle above) — it just never registers. A root-level
    // `defaultEnabled: false` caps the plugin's own default: the user's explicit
    // enable still wins, a plugin can't self-enable past its root's posture.
    if (pluginActive(plugin.id, (plugin.defaultEnabled ?? true) && (options.defaultEnabled ?? true))) {
      activate()
    }

    return plugin.id
  } catch (error) {
    console.error(`[plugins] runtime load failed (${origin})`, error)
    notifyError(error, `Plugin "${origin}" failed to load`)
    publishPlugin({
      id: origin,
      name: origin,
      kind: options.kind ?? 'disk',
      file: options.file,
      packageName: options.packageName,
      packageOrigin: options.packageOrigin,
      status: 'error',
      error: error instanceof Error ? error.message : String(error)
    })

    return null
  }
}

// ---------------------------------------------------------------------------
// The on-disk plugin door — ONE app-level root, `<hermes home>/desktop-plugins/`:
//  - `<id>/plugin.js` — a standalone desktop plugin (agent- or user-written);
//  - `<package>/plugin.js` + `.hermes-package.json` — the desktop HALF of a
//    unified agent+desktop package, COPIED here by Electron from the package's
//    `plugins/<package>/desktop/` folder (electron/desktop-plugins-root.ts).
//    The agent half stays in its profile; the desktop half lives with the app,
//    so it neither appears nor disappears when the active profile changes.
// SELF-MAINTAINING — no reload ceremony:
//  - each plugin.js is fs-watched (the preview watcher IPC, debounced in
//    main): saving the file hot-reloads the plugin in place;
//  - each root is fs-watched too (watchDirectory IPC), so new folders load +
//    removed ones unload on the change tick; older Electron shells without
//    watchDirectory fall back to the slow visible-tab poll.
// Panes land via placement adoption and STAY where the user drags them —
// the tree treats not-yet-loaded pane ids as hidden, so boot and reload are
// collapse -> appear, never a placeholder flash.
// ---------------------------------------------------------------------------

const DISK_POLL_MS = 5_000

interface DiskRoot {
  dir: string
  /** Path segments below each scanned folder to the entry file. */
  entrySegments: readonly string[]
}

/** The app-level root, resolved fresh each pass (Electron-local, never the
 *  backend's hermes_home — #66899). Resolving it also runs Electron's
 *  reconcile, so unified packages' desktop halves are current before we scan. */
async function diskRoots(): Promise<DiskRoot[]> {
  const root = await window.hermesDesktop?.desktopPluginsRoot?.()

  return root ? [{ dir: root, entrySegments: ['plugin.js'] }] : []
}

/** Marker Electron writes beside a materialized unified-package half. Its
 *  presence means: opt-in posture (the Python half is installed-but-inert
 *  until allowlisted — GHSA-mcfc-hp25-cjv7 — so the desktop half matches), and
 *  the record carries the package name so the Plugins page pairs it with the
 *  agent row. */
const PACKAGE_MARKER = '.hermes-package.json'

interface PackageMarker {
  /** The package is a symlinked dev checkout; `source` is its `desktop/` dir. */
  linkedSource?: string
  origin?: { catalogName?: string; repo?: string; sha?: string }
  package: string
}

async function readPackageMarker(desktop: Window['hermesDesktop'], folder: string): Promise<null | PackageMarker> {
  try {
    const { entries } = await desktop.readDir(folder)
    const marker = entries.find(entry => entry.name === PACKAGE_MARKER && !entry.isDirectory)

    if (!marker) {
      return null
    }

    const read = await desktop.readFileText(marker.path)

    if (isReadFileErrorResult(read)) {
      return null
    }

    const parsed = JSON.parse(read.text) as {
      catalogName?: string
      linked?: boolean
      package?: string
      repo?: string
      sha?: string
      source?: string
    }

    if (!parsed.package) {
      return null
    }

    return {
      linkedSource: parsed.linked && parsed.source ? parsed.source : undefined,
      origin: parsed.repo ? { catalogName: parsed.catalogName, repo: parsed.repo, sha: parsed.sha } : undefined,
      package: parsed.package
    }
  } catch {
    return null
  }
}

interface DiskPlugin {
  /** Root posture, forwarded on every (re)load of this entry. */
  defaultEnabled?: boolean
  file: string
  /** Agent package this folder is the desktop half of (unified packages). */
  packageName?: string
  packageOrigin?: PackageMarker['origin']
  /** Loaded plugin id (null while broken — kept so a fixing save reloads). */
  id: null | string
  /** Origin label (folder name) — the toast/inventory name for load errors. */
  origin: string
  /** Linked dev package only: the SOURCE `desktop/plugin.js` this copy came from. */
  sourceFile?: string
  /** Watch on `sourceFile` — a save re-syncs the copy, then reloads it. */
  sourceWatchId?: null | string
  watchId: null | string
}

/** Live disk plugins keyed by ENTRY FILE path — unique across both roots
 *  (folder names alone can collide between them). */
const disk = new Map<string, DiskPlugin>()
let watching = false
let scanning = false

/** Drop a folder-named error record — unless that name is the live plugin id
 *  of ANOTHER disk entry (two roots can carry same-named folders; a broken one
 *  must not clobber its healthy namesake's inventory row). */
function dropOriginRecord(origin: string, except: DiskPlugin): void {
  for (const other of disk.values()) {
    if (other !== except && other.id === origin) {
      return
    }
  }

  dropPlugin(origin)
}

/** A plugin source that could not be read in FULL. Evaluating a truncated
 *  file is never acceptable — half a module can still parse. */
class PluginSourceOversizeError extends Error {}

/** Read a plugin entry file in full. Prefers the dedicated readPluginSource
 *  IPC (16 MiB cap, no truncation). Older shells predate it and only offer
 *  the preview read, which silently truncates at 512 KiB — there the read
 *  fails loudly instead of handing a partial file to the evaluator. */
async function readPluginSourceText(file: string): Promise<string> {
  const desktop = window.hermesDesktop!

  if (desktop.readPluginSource) {
    return (await desktop.readPluginSource(file)).text
  }

  const result = await desktop.readFileText(file)

  if (isReadFileErrorResult(result)) {
    throw new Error(result.message || `Plugin read failed: ${result.error}`)
  }

  if (result.truncated) {
    throw new PluginSourceOversizeError(
      "plugin.js exceeds this shell's 512 KiB read limit — update Hermes Desktop to load larger plugins"
    )
  }

  return result.text
}

/** Returns false when the entry file could not be read (vanished mid-read) so
 *  the caller can reconcile/unload the registration instead of retaining a
 *  live ghost for a missing entry. */
async function loadDiskPlugin(entry: DiskPlugin): Promise<boolean> {
  const prevId = entry.id

  try {
    const text = await readPluginSourceText(entry.file)

    const id = await loadRuntimePlugin(text, entry.origin, {
      defaultEnabled: entry.defaultEnabled,
      file: entry.file,
      packageName: entry.packageName,
      packageOrigin: entry.packageOrigin
    })

    // loadRuntimePlugin only disposes the NEW id, so the previous incarnation
    // is unloaded here when the file no longer yields it: a hot-edit that
    // changes `plugin.id`, or a save that no longer loads at all (syntax
    // error, timeout, duplicate). Otherwise the old module's contributions and
    // its activate handle stay live beside the error row — the Plugins tab
    // would show a broken file as "loaded" and re-enable stale code.
    if (prevId && prevId !== id) {
      unloadRuntimePlugin(prevId)
      dropPlugin(prevId)
    }

    entry.id = id

    // A fixing save under a different plugin id — drop the folder-named
    // error record so the inventory shows one row, not a ghost.
    if (id && id !== entry.origin) {
      dropOriginRecord(entry.origin, entry)
    }

    return true
  } catch (error) {
    // An oversize source is a REAL failure the user must see (the silent
    // shape was the bug: a truncated file evaluated as a syntax error, or
    // worse, as half a plugin). It is a completed read of an existing file,
    // so report it and keep the registration (true) — everything else is a
    // file vanishing mid-read, where false lets the caller reconcile/unload.
    if (error instanceof PluginSourceOversizeError) {
      console.error(`[plugins] ${entry.origin}: ${error.message}`)
      notifyError(error, `Plugin "${entry.origin}" failed to load`)
      publishPlugin({
        id: entry.origin,
        name: entry.origin,
        kind: 'disk',
        file: entry.file,
        status: 'error',
        error: error.message
      })

      return true
    }

    return false
  }
}

async function resolveDiskPluginEntry(
  desktop: Window['hermesDesktop'],
  folderPath: string,
  segments: readonly string[]
): Promise<string | null> {
  let currentDir = folderPath

  for (let index = 0; index < segments.length; index += 1) {
    const { entries } = await desktop.readDir(currentDir)
    const entry = entries.find(candidate => candidate.name === segments[index])

    if (!entry) {
      return null
    }

    const last = index === segments.length - 1

    if (last) {
      return entry.isDirectory ? null : entry.path
    }

    if (!entry.isDirectory) {
      return null
    }

    currentDir = entry.path
  }

  return null
}

/** Bind (or, on a manual reload, re-bind) the hot-reload watch for one entry.
 *  An atomic directory replacement leaves the old watch attached to the
 *  unlinked inode, so a forced reload must drop it and watch the current file. */
async function watchDiskPluginFile(desktop: NonNullable<Window['hermesDesktop']>, record: DiskPlugin): Promise<void> {
  if (record.watchId) {
    void desktop.stopPreviewFileWatch(record.watchId)
    record.watchId = null
  }

  try {
    const watch = await desktop.watchPreviewFile(record.file)

    // Structured "folder gone" answer — nothing to watch; the poll still
    // reconciles new folders and edits need a manual reload.
    record.watchId = isReadFileErrorResult(watch) ? null : watch.id
  } catch {
    // Unwatchable — the poll still reconciles new folders; edits need a
    // manual "Reload desktop plugins".
  }
}

/** Watch a linked dev package's SOURCE `plugin.js`. Without it the developer
 *  edits their checkout while the app keeps running the copy in
 *  `desktop-plugins/` — the copy is only refreshed on Rescan or restart. */
async function watchDiskPluginSource(desktop: NonNullable<Window['hermesDesktop']>, record: DiskPlugin): Promise<void> {
  if (!record.sourceFile || record.sourceWatchId) {
    return
  }

  try {
    const watch = await desktop.watchPreviewFile(record.sourceFile)

    record.sourceWatchId = isReadFileErrorResult(watch) ? null : watch.id
  } catch {
    record.sourceWatchId = null
  }
}

/** A linked source changed: copy it over the app-root half (Electron's
 *  reconcile — the one writer of that folder), then reload every copy that
 *  pass replaced and re-bind its watch, which the folder swap orphaned. */
async function resyncLinkedDiskPlugins(): Promise<void> {
  const desktop = window.hermesDesktop

  if (!desktop?.reconcileDesktopPlugins) {
    return
  }

  const touched = new Set((await desktop.reconcileDesktopPlugins().catch(() => [])) ?? [])

  for (const record of disk.values()) {
    // The folder of `<root>/<name>/plugin.js`, either separator (Windows paths).
    if (!touched.has(record.file.replace(/[\\/][^\\/]*$/, ''))) {
      continue
    }

    if (await loadDiskPlugin(record)) {
      await watchDiskPluginFile(desktop, record)
    } else {
      void scanDiskPlugins()
    }
  }
}

/** Reconcile the disk root with the inventory. `reloadKnown` (the manual
 *  "Reload desktop plugins" command) also re-reads every already-known entry
 *  file: an installer that atomically replaces a plugin folder keeps the
 *  same path, so the fs watch on the old inode never fires and the stale
 *  module would otherwise stay live until restart (#91503). */
async function scanDiskPlugins(reloadKnown = false): Promise<void> {
  const desktop = window.hermesDesktop

  // Re-entrancy guard: the 5s poll must not overlap a slow in-flight scan
  // (reads/loads can exceed the interval).
  if (!desktop || scanning) {
    return
  }

  scanning = true

  try {
    const roots = await diskRoots()

    if (roots.length === 0) {
      return
    }

    const seen = new Set<string>()

    for (const root of roots) {
      let entries

      try {
        ;({ entries } = await desktop.readDir(root.dir))
      } catch {
        continue // Root missing (no plugins yet) — the poll/watch reconciles.
      }

      // Listing order is filesystem order; sorted so duplicate-id ownership
      // (first loaded wins) is the same on every launch.
      const folders = entries.filter(e => e.isDirectory).sort((a, b) => a.name.localeCompare(b.name))

      for (const dir of folders) {
        let file: string | null

        try {
          file = await resolveDiskPluginEntry(desktop, dir.path, root.entrySegments)
        } catch {
          continue // Folder changed during the metadata walk; the next tick reconciles.
        }

        if (!file) {
          continue // Ordinary agent package with no Desktop half — not an error.
        }

        seen.add(file)

        const known = disk.get(file)

        if (known) {
          if (reloadKnown && (await loadDiskPlugin(known))) {
            await watchDiskPluginFile(desktop, known)
          }

          continue
        }

        const marker = await readPackageMarker(desktop, dir.path)

        const record: DiskPlugin = {
          // A unified package's desktop half ships opt-in, like its agent half.
          defaultEnabled: marker ? false : undefined,
          file,
          id: null,
          origin: dir.name,
          packageName: marker?.package,
          packageOrigin: marker?.origin,
          sourceFile: marker?.linkedSource ? `${marker.linkedSource}/plugin.js` : undefined,
          sourceWatchId: null,
          watchId: null
        }

        disk.set(file, record)

        if (!(await loadDiskPlugin(record))) {
          disk.delete(file)

          continue
        }

        await watchDiskPluginFile(desktop, record)
        await watchDiskPluginSource(desktop, record)
      }
    }

    // Folder deleted -> plugin gone, cleanly (inventory row included).
    for (const [file, record] of disk) {
      if (seen.has(file)) {
        continue
      }

      retireDiskPlugin(file, record)
    }
  } catch {
    // No plugin roots (or no gateway yet) — nothing to reconcile.
  } finally {
    scanning = false
  }
}

/** Forget a disk entry whose folder is gone: unload its registration, drop
 *  its inventory rows and its preview-script grants, stop its file watch. */
function retireDiskPlugin(file: string, record: DiskPlugin): void {
  if (record.id) {
    unloadRuntimePlugin(record.id)
    dropPlugin(record.id)
    // A later plugin reusing this id must ask the user again, never inherit.
    forgetPluginPreviewAccess(record.id)
  }

  dropOriginRecord(record.origin, record)

  if (record.watchId) {
    void window.hermesDesktop?.stopPreviewFileWatch(record.watchId)
  }

  if (record.sourceWatchId) {
    void window.hermesDesktop?.stopPreviewFileWatch(record.sourceWatchId)
  }

  disk.delete(file)
}

/** Uninstall a STANDALONE disk plugin (Capabilities → Plugins trash button):
 *  Electron deletes `<root>/<folder>` (containment enforced there), then the
 *  entry is retired here so the pane/commands vanish without waiting for the
 *  next scan. Unified-package halves are not addressable this way — the agent
 *  uninstall prunes them. Resolves with the failure reason instead of throwing. */
export async function uninstallDiskPlugin(
  pluginId: string,
  /** How the folder goes away. Native Desktop deletes it in Electron; a browser-hosted tab has no disk
   *  of its own and passes the backend that serves it (`plugins.manage remove_desktop`). */
  removeDesktop?: (payload: { name: string }) => Promise<{ ok: boolean; error?: string }>
): Promise<{ ok: boolean; error?: string }> {
  const found = [...disk.entries()].find(([, record]) => record.id === pluginId || record.origin === pluginId)

  if (!found) {
    return { ok: false, error: 'not an installed desktop plugin' }
  }

  const [file, record] = found
  const remove = removeDesktop ?? window.hermesDesktop?.removeDesktopPlugin

  if (!remove) {
    return { ok: false, error: 'this Hermes Desktop build cannot remove desktop plugins — delete the folder by hand' }
  }

  const result = await remove({ name: record.origin })

  if (!result?.ok) {
    return { ok: false, error: result?.error ?? 'unknown error' }
  }

  retireDiskPlugin(file, record)

  // A reinstall under the same id must ask for its folders again (ctx.files).
  // A revoke that fails is reported: the plugin's row is gone, so the user
  // could not revoke it there any more.
  if (record.id) {
    try {
      await window.hermesDesktop?.pluginFiles?.revoke(record.id)
    } catch (error) {
      return {
        ok: false,
        error: `removed, but its folder access could not be revoked: ${error instanceof Error ? error.message : String(error)}`
      }
    }
  }

  return { ok: true }
}

/** Manual rescan (the ⌘K "Reload desktop plugins" fallback) — re-reads
 *  known entries too, unlike the fs-watch/poll reconcile. */
export const discoverRuntimePlugins = (): Promise<void> => scanDiskPlugins(true)

/** True while the disk door's FIRST scan is in flight. Boot code that must
 *  not mistake a not-yet-registered plugin route for a stale one
 *  (remembered-route restore) waits on this instead of on timing. */
export const $diskPluginsScanPending = atom(false)

/** Start the self-maintaining disk door: initial scan, per-file hot reload,
 *  fs-watched folder reconciliation (poll fallback on older shells). Idempotent. */
export function watchRuntimePlugins(): void {
  const desktop = window.hermesDesktop

  if (watching || !desktop) {
    return
  }

  watching = true
  $diskPluginsScanPending.set(true)

  const dirWatchIds = new Set<string>()
  const watchedDirs = new Set<string>()

  desktop.onPreviewFileChanged(({ id }) => {
    // Directory tick: a plugin folder appeared or vanished — reconcile.
    if (dirWatchIds.has(id)) {
      void scanDiskPlugins()

      return
    }

    for (const record of disk.values()) {
      if (record.sourceWatchId === id) {
        void resyncLinkedDiskPlugins()

        return
      }

      if (record.watchId === id) {
        void loadDiskPlugin(record).then(readable => {
          if (!readable) {
            void scanDiskPlugins()
          }
        })

        return
      }
    }
  })

  // True only when EVERY root is fs-watched — a partially watched set keeps
  // the poll alive so unwatched roots still reconcile new/removed folders.
  const startDirWatches = async (): Promise<boolean> => {
    if (!desktop.watchDirectory) {
      return false
    }

    const roots = await diskRoots()

    if (roots.length === 0) {
      return false
    }

    let all = true

    for (const root of roots) {
      if (watchedDirs.has(root.dir)) {
        continue
      }

      try {
        dirWatchIds.add((await desktop.watchDirectory(root.dir)).id)
        watchedDirs.add(root.dir)
      } catch {
        // Dir missing or unwatchable — the poll covers it and retries here.
        all = false
      }
    }

    return all
  }

  void scanDiskPlugins().then(() => $diskPluginsScanPending.set(false))
  void startDirWatches().then(watched => {
    if (watched) {
      return
    }

    const timer = window.setInterval(() => {
      if (document.visibilityState !== 'visible') {
        return
      }

      void scanDiskPlugins()

      // A root may have appeared since — upgrade to the watches and retire
      // this poll once every root is covered.
      void startDirWatches().then(upgraded => {
        if (upgraded) {
          window.clearInterval(timer)
        }
      })
    }, DISK_POLL_MS)
  })
}