typeclaw 0.36.1 → 0.36.3

package/src/init/restart-deps-preflight.ts

@@ -0,0 +1,155 @@
+import { existsSync } from 'node:fs'
+import { readFile, readdir } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve } from 'node:path'
+
+import { PACKAGE_FILE } from './packagejson'
+import { PACKAGES_DIR } from './paths'
+
+// The hostd restart path is destroy-then-recreate: it `docker rm -f`s the live
+// container BEFORE `start()` runs `bun install`. A bad agent edit to
+// typeclaw.json#plugins or a packages/* manifest aborts that install AFTER the
+// old container is gone, with no rollback and no client to report to — the agent
+// self-locks out. This runs BEFORE stop() (via RestartPreflight) so a bad edit
+// becomes "restart refused, agent keeps running" instead of "agent bricked".
+//
+// Mirrors PR #770: ONLY deterministic local config errors block. No bun
+// invocation, no network — a transient registry hiccup must never strand a
+// healthy agent. start() stays the real fail-closed gate for everything else.
+
+export type RestartDepsPreflightResult = { ok: true } | { ok: false; reason: string }
+
+export type RestartDepsPreflightOptions = {
+  cwd: string
+  plugins: readonly string[]
+}
+
+const WORKSPACE_PROTOCOL = 'workspace:'
+
+const DEPENDENCY_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] as const
+
+export async function validateRestartDeps(options: RestartDepsPreflightOptions): Promise<RestartDepsPreflightResult> {
+  const { cwd, plugins } = options
+
+  const localPluginError = checkLocalPluginPaths(cwd, plugins)
+  if (localPluginError) return { ok: false, reason: localPluginError }
+
+  const workspaceError = await checkWorkspaceMembers(cwd)
+  if (workspaceError) return { ok: false, reason: workspaceError }
+
+  return { ok: true }
+}
+
+// Mirrors loadLocal() in src/plugin/loader.ts: a local plugin entry is resolved
+// against cwd and confined to it (`rel.startsWith('..') || isAbsolute(rel)`
+// throws). An escaping entry (`../x`, `/abs/x`) that happens to EXIST passes a
+// bare existsSync but the loader rejects it post-stop — so the escape check must
+// run before, and independently of, the existence check.
+function checkLocalPluginPaths(cwd: string, plugins: readonly string[]): string | null {
+  for (const entry of plugins) {
+    if (!isLocalEntry(entry)) continue
+    const resolved = resolve(cwd, entry)
+    const rel = relative(cwd, resolved)
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+      return `local plugin "${entry}" referenced in typeclaw.json#plugins escapes the agent directory; the plugin loader confines local plugins to the agent folder and would reject it after the container has stopped. Use a path inside the agent folder before restarting.`
+    }
+    if (!existsSync(resolved)) {
+      return `local plugin "${entry}" referenced in typeclaw.json#plugins does not exist on disk; restart would fail at dependency install. Remove the entry or restore the path before restarting.`
+    }
+  }
+  return null
+}
+
+function isLocalEntry(entry: string): boolean {
+  return entry.startsWith('./') || entry.startsWith('../') || isAbsolute(entry)
+}
+
+// Bun resolves the `workspace:` protocol strictly against the local workspace
+// set, so a member declaring `"<dep>": "workspace:*"` where `<dep>` is not
+// itself a workspace member aborts the WHOLE install with `<dep>@workspace:*
+// failed to resolve`. Canonical trigger: a half-migrated local plugin still
+// pinning `"typeclaw": "workspace:*"` after typeclaw became an external npm dep.
+async function checkWorkspaceMembers(cwd: string): Promise<string | null> {
+  const members = await readWorkspaceMembers(cwd)
+  if (members.length === 0) return null
+
+  const memberNames = new Set<string>()
+  for (const m of members) {
+    if (m.name !== null) memberNames.add(m.name)
+  }
+
+  for (const member of members) {
+    for (const field of DEPENDENCY_FIELDS) {
+      const deps = member.deps[field]
+      if (!deps) continue
+      for (const [depName, spec] of Object.entries(deps)) {
+        if (!spec.startsWith(WORKSPACE_PROTOCOL)) continue
+        if (!memberNames.has(depName)) {
+          return `local workspace package "${member.dirName}" depends on "${depName}": "${spec}", but "${depName}" is not a workspace package under ${PACKAGES_DIR}/. \`bun install\` would abort with "${depName}@${spec} failed to resolve", leaving the agent unable to restart. Fix ${PACKAGES_DIR}/${member.dirName}/${PACKAGE_FILE} (use a registry version range, or remove the package) before restarting.`
+        }
+      }
+    }
+  }
+
+  return null
+}
+
+type WorkspaceMember = {
+  dirName: string
+  name: string | null
+  deps: Partial<Record<(typeof DEPENDENCY_FIELDS)[number], Record<string, string>>>
+}
+
+// A member whose manifest is missing/unparseable is skipped, not failed: bun may
+// tolerate it, and we only block on the workspace-resolution class above. No
+// packages/ dir at all returns [].
+async function readWorkspaceMembers(cwd: string): Promise<WorkspaceMember[]> {
+  const packagesDir = join(cwd, PACKAGES_DIR)
+  let entries: string[]
+  try {
+    entries = await readdir(packagesDir)
+  } catch {
+    return []
+  }
+
+  const members: WorkspaceMember[] = []
+  for (const dirName of entries) {
+    const manifestPath = join(packagesDir, dirName, PACKAGE_FILE)
+    if (!existsSync(manifestPath)) continue
+    let raw: string
+    try {
+      raw = await readFile(manifestPath, 'utf8')
+    } catch {
+      continue
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(raw)
+    } catch {
+      continue
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) continue
+    const pkg = parsed as Record<string, unknown>
+    members.push({
+      dirName,
+      name: typeof pkg.name === 'string' ? pkg.name : null,
+      deps: extractDeps(pkg),
+    })
+  }
+  return members
+}
+
+function extractDeps(
+  pkg: Record<string, unknown>,
+): Partial<Record<(typeof DEPENDENCY_FIELDS)[number], Record<string, string>>> {
+  const out: Partial<Record<(typeof DEPENDENCY_FIELDS)[number], Record<string, string>>> = {}
+  for (const field of DEPENDENCY_FIELDS) {
+    const value = pkg[field]
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) continue
+    const deps: Record<string, string> = {}
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof v === 'string') deps[k] = v
+    }
+    if (Object.keys(deps).length > 0) out[field] = deps
+  }
+  return out
+}

package/src/permissions/permissions.ts

@@ -20,6 +20,17 @@ export type PermissionService = {
   // the config reloadable so role match-rule edits (typeclaw role claim,
   // hand-edits to typeclaw.json) take effect without a container restart.
   replaceRoles(roles: RolesConfig | undefined): void
+  // Rebuilds the role table with a new plugin-permission set, preserving the
+  // object identity that plugin factories captured. The plugin manager calls
+  // this AFTER the load loop to finalize the permission model from only the
+  // plugins that survived: a user plugin that failed to load must not leave
+  // its declared permissions or owner-wildcard exclusions in the live service.
+  // Optional so the many partial test stubs and the channel-respond stub need
+  // not implement it; the real service from createPermissionService always does.
+  replacePluginPermissions?(opts: {
+    pluginPermissions: readonly string[]
+    ownerWildcardExclusions: readonly string[]
+  }): void
 }
 
 export type UnknownPermissionWarning = {
@@ -34,6 +45,7 @@ export const noopPermissionService: PermissionService = {
   compareRoleSeverity: () => undefined,
   describe: () => ({ role: 'guest', permissions: [] }),
   replaceRoles: () => {},
+  replacePluginPermissions: () => {},
 }
 
 type ResolvedRole = {
@@ -109,9 +121,10 @@ function levenshtein(a: string, b: string): number {
 }
 
 export function createPermissionService(opts: CreatePermissionServiceOptions = {}): PermissionService {
-  const pluginPermissions = opts.pluginPermissions ?? []
-  const ownerWildcardExclusions = opts.ownerWildcardExclusions ?? []
-  let resolved = buildRoleTable(opts.roles ?? {}, pluginPermissions, ownerWildcardExclusions)
+  let pluginPermissions = opts.pluginPermissions ?? []
+  let ownerWildcardExclusions = opts.ownerWildcardExclusions ?? []
+  let lastRoles = opts.roles ?? {}
+  let resolved = buildRoleTable(lastRoles, pluginPermissions, ownerWildcardExclusions)
   let byName = new Map(resolved.map((r) => [r.name, r]))
 
   function resolveRole(origin: SessionOrigin | undefined): string {
@@ -186,7 +199,14 @@ export function createPermissionService(opts: CreatePermissionServiceOptions = {
       return { role: name, permissions: role?.permissions ?? [] }
     },
     replaceRoles(roles) {
-      resolved = buildRoleTable(roles ?? {}, pluginPermissions, ownerWildcardExclusions)
+      lastRoles = roles ?? {}
+      resolved = buildRoleTable(lastRoles, pluginPermissions, ownerWildcardExclusions)
+      byName = new Map(resolved.map((r) => [r.name, r]))
+    },
+    replacePluginPermissions(next) {
+      pluginPermissions = next.pluginPermissions
+      ownerWildcardExclusions = next.ownerWildcardExclusions
+      resolved = buildRoleTable(lastRoles, pluginPermissions, ownerWildcardExclusions)
       byName = new Map(resolved.map((r) => [r.name, r]))
     },
   }

package/src/plugin/loader.ts

@@ -15,9 +15,7 @@ export type LoadPluginEntryFn = (entry: string, agentDir: string) => Promise<Res
 
 // Thrown only when a plugin entry cannot be resolved at all (uninstalled
 // package, missing local file, unresolvable export subpath). The manager
-// treats this as non-fatal and skips the entry. Every other failure --
-// path-escape, import-time evaluation throws, invalid definition -- stays a
-// plain Error so it remains a hard boot error.
+// treats this as non-fatal and skips the entry.
 export class PluginNotFoundError extends Error {
   readonly entry: string
   constructor(entry: string, message: string, options?: { cause?: unknown }) {
@@ -27,6 +25,20 @@ export class PluginNotFoundError extends Error {
   }
 }
 
+// Thrown when a plugin entry violates a security boundary (e.g. a local path
+// escaping the agent directory). Stays fatal for ALL plugins — even the
+// per-plugin tolerance for user plugin bugs MUST NOT swallow this, or a
+// malicious typeclaw.json could point at arbitrary host files and have the
+// failure silently downgraded to a warning.
+export class PluginSecurityError extends Error {
+  readonly entry: string
+  constructor(entry: string, message: string) {
+    super(message)
+    this.name = 'PluginSecurityError'
+    this.entry = entry
+  }
+}
+
 export async function loadPluginEntry(entry: string, agentDir: string): Promise<ResolvedPlugin> {
   if (isLocalPath(entry)) {
     return loadLocal(entry, agentDir)
@@ -44,7 +56,7 @@ async function loadLocal(entry: string, agentDir: string): Promise<ResolvedPlugi
   // cannot point at arbitrary files on the host.
   const rel = relative(agentDir, resolved)
   if (rel.startsWith('..') || isAbsolute(rel)) {
-    throw new Error(`plugin path escapes agent directory: ${entry} (resolved to ${resolved})`)
+    throw new PluginSecurityError(entry, `plugin path escapes agent directory: ${entry} (resolved to ${resolved})`)
   }
   if (!existsSync(resolved)) {
     throw new PluginNotFoundError(entry, `plugin path does not exist: ${entry} (resolved to ${resolved})`)

package/src/plugin/manager.ts

@@ -11,10 +11,22 @@ import {
 
 import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
 import { createHookBus, type HookBus } from './hooks'
-import { loadPluginEntry, type LoadPluginEntryFn, PluginNotFoundError, type ResolvedPlugin } from './loader'
+import { loadPluginEntry, type LoadPluginEntryFn, PluginSecurityError, type ResolvedPlugin } from './loader'
 import { discardRegistrationsBy, emptyRegistry, type PluginRegistry, registerContributions } from './registry'
 import type { PluginExports } from './types'
 
+export type FailedPlugin = { entry: string; phase: 'resolve' | 'config' | 'factory' | 'register'; error: string }
+
+// A user (typeclaw.json / local / npm) plugin that fails to load must not brick
+// the agent: the agent can edit its own plugins, and a self-introduced bug would
+// otherwise leave the container unable to boot and repair itself. Such failures
+// are isolated (skip + warn, keep the rest). Bundled plugins are part of the
+// trusted runtime, so their failure stays fatal — and PluginSecurityError stays
+// fatal for everyone.
+function isToleratedUserError(err: unknown): boolean {
+  return !(err instanceof PluginSecurityError)
+}
+
 export type LoadPluginsOptions = {
   entries: string[]
   agentDir: string
@@ -36,6 +48,7 @@ export type LoadPluginsResult = {
   permissions: PermissionService
   declaredPermissions: readonly string[]
   loadedPlugins: { name: string; version: string | undefined; source: string }[]
+  failedPlugins: FailedPlugin[]
   markBooted: () => void
   setSpawnSubagent: (fn: SpawnSubagentFn) => void
 }
@@ -51,113 +64,117 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
     throw new Error('plugin: spawnSubagent is not yet wired')
   }
 
-  // Non-fatal: a single unresolvable entry (uninstalled package, typo) must
-  // not abort boot for every other plugin -- warn and skip it. Only genuine
-  // resolution failures (PluginNotFoundError) are swallowed; path-escape,
-  // import-time throws, and invalid definitions stay fatal so a broken or
-  // malicious plugin still hard-fails boot.
+  const failed: FailedPlugin[] = []
+
+  // A user entry that fails to resolve OR throws at import time (typo,
+  // uninstalled package, syntax error in a local plugin the agent just edited)
+  // is isolated: warn, record, skip — the rest still boot. PluginSecurityError
+  // (path escape) is the one exception and stays fatal.
   const resolvedEntries = await Promise.all(
     opts.entries.map(async (entry) => {
       try {
         return { entry, resolved: await loadEntry(entry, opts.agentDir) }
       } catch (err) {
-        if (!(err instanceof PluginNotFoundError)) throw err
-        console.warn(`[plugin] failed to load "${entry}", ignoring: ${err.message}`)
+        if (!isToleratedUserError(err)) throw err
+        const message = err instanceof Error ? err.message : String(err)
+        console.warn(`[plugin] failed to load "${entry}", skipping: ${message}`)
+        failed.push({ entry, phase: 'resolve', error: message })
         return null
       }
     }),
   )
-  const allPlugins: { entry: string; resolved: ResolvedPlugin }[] = [
-    ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved })) ?? []),
-    ...resolvedEntries.filter((e): e is { entry: string; resolved: ResolvedPlugin } => e !== null),
+  const allPlugins: { entry: string; resolved: ResolvedPlugin; isBundled: boolean }[] = [
+    ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved, isBundled: true })) ?? []),
+    ...resolvedEntries
+      .filter((e): e is { entry: string; resolved: ResolvedPlugin } => e !== null)
+      .map((e) => ({ ...e, isBundled: false })),
   ]
 
-  const declaredPermissions = collectDeclaredPermissions(allPlugins)
-  const ownerWildcardExclusions = collectOwnerWildcardExclusions(allPlugins)
+  // Seed the permission service from BUNDLED plugins only. A user plugin's
+  // declared permissions / owner-wildcard exclusions must not enter the live
+  // service until the plugin actually survives registration — otherwise a
+  // plugin reported as disabled could still widen the allowed set or (worse)
+  // strip an owner-wildcard bypass. Bundled plugins are always survivors:
+  // their failure is fatal, so the boot aborts before this service is used.
+  const bundledPlugins = allPlugins.filter((p) => p.isBundled)
   const permissions = createPermissionService({
     ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
-    pluginPermissions: declaredPermissions,
-    ownerWildcardExclusions,
+    pluginPermissions: collectDeclaredPermissions(bundledPlugins),
+    ownerWildcardExclusions: collectOwnerWildcardExclusions(bundledPlugins),
   })
 
-  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
-  // the known set, so a typo like `security.bypass.secretExfilBach` is
-  // visible at boot rather than silently failing to bypass the matching
-  // guard. We log instead of throw because the runtime still functions --
-  // the unknown string just never matches anything.
-  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
-    console.warn(
-      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
-    )
-  }
+  const survivors: { entry: string; resolved: ResolvedPlugin; isBundled: boolean }[] = []
 
-  for (const { entry, resolved } of allPlugins) {
+  for (const plugin of allPlugins) {
+    const { entry, resolved, isBundled } = plugin
+    // Name conflict is a global invariant (two plugins claiming one name make
+    // every later name-keyed lookup ambiguous), so it stays fatal regardless of
+    // origin — never demoted to a per-plugin skip.
     if (loaded.find((l) => l.name === resolved.name)) {
       throw new Error(`plugin name conflict: ${resolved.name} (entry ${entry}) already loaded`)
     }
 
-    let validatedConfig: unknown = undefined
-    if (resolved.defined.configSchema) {
-      const raw = opts.configsByName[resolved.name]
-      const parsed = (resolved.defined.configSchema as z.ZodType<unknown>).safeParse(raw ?? {})
-      if (!parsed.success) {
-        throw new Error(`plugin ${resolved.name}: config invalid: ${formatZodIssues(parsed.error)}`)
-      }
-      validatedConfig = parsed.data
-    } else if (opts.configsByName[resolved.name] !== undefined) {
-      throw new Error(
-        `plugin ${resolved.name}: config block "${resolved.name}" present in typeclaw.json but plugin declares no configSchema`,
-      )
-    }
-
-    const logger = createPluginLogger(resolved.name)
-    const ctx = createPluginContext({
-      name: resolved.name,
-      version: resolved.version,
-      agentDir: opts.agentDir,
-      config: validatedConfig as never,
-      logger,
-      permissions,
-      resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
-      hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
-      spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
-      isBooted: () => booted,
-    })
-
-    let exports: PluginExports
-    try {
-      exports = await resolved.defined.plugin(ctx)
-    } catch (err) {
-      discardRegistrationsBy(resolved.name, registry, hooks)
-      const message = err instanceof Error ? err.message : String(err)
-      throw new Error(`plugin ${resolved.name}: factory threw: ${message}`)
-    }
-
     try {
-      registerContributions({
-        pluginName: resolved.name,
-        logger,
-        exports,
-        ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
+      await registerOnePlugin({
+        resolved,
+        config: opts.configsByName[resolved.name],
+        agentDir: opts.agentDir,
         registry,
         hooks,
-        agentDir: opts.agentDir,
-        pluginConfig: validatedConfig,
+        permissions,
+        ctxDeps: {
+          resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
+          hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
+          spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
+          isBooted: () => booted,
+        },
       })
     } catch (err) {
+      const phase = err instanceof PluginPhaseError ? err.phase : 'factory'
+      const message = err instanceof PluginPhaseError ? err.detail : err instanceof Error ? err.message : String(err)
+      // Bundled/core plugin failures are typeclaw bugs (or a compromised
+      // runtime) — fail loud. Only user plugin failures are isolated.
+      if (isBundled || !isToleratedUserError(err instanceof PluginPhaseError ? err.original : err)) {
+        throw err instanceof PluginPhaseError ? err.original : err
+      }
       discardRegistrationsBy(resolved.name, registry, hooks)
-      throw err
+      console.warn(`[plugin] failed to load "${entry}", skipping: ${message}`)
+      failed.push({ entry, phase, error: message })
+      continue
     }
 
+    survivors.push(plugin)
     loaded.push({ name: resolved.name, version: resolved.version, source: resolved.source })
   }
 
+  // Finalize the permission model from the survivor set only. Plugin factories
+  // captured `permissions` by reference (their hooks read it at request time),
+  // so we mutate that same object in place rather than returning a new one.
+  const declaredPermissions = collectDeclaredPermissions(survivors)
+  permissions.replacePluginPermissions?.({
+    pluginPermissions: declaredPermissions,
+    ownerWildcardExclusions: collectOwnerWildcardExclusions(survivors),
+  })
+
+  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
+  // the known set, so a typo like `security.bypass.secretExfilBach` is
+  // visible at boot rather than silently failing to bypass the matching
+  // guard. We log instead of throw because the runtime still functions --
+  // the unknown string just never matches anything. Run AFTER finalization so
+  // a failed plugin's declarations don't make a role's permission look known.
+  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
+    console.warn(
+      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
+    )
+  }
+
   return {
     registry,
     hooks,
     permissions,
     declaredPermissions,
     loadedPlugins: loaded,
+    failedPlugins: failed,
     markBooted: () => {
       booted = true
     },
@@ -167,6 +184,93 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   }
 }
 
+// Tags WHICH sub-phase failed (for the failedPlugins report) while preserving
+// the ORIGINAL error so the caller can keep PluginSecurityError fatal even when
+// it surfaces deep inside registration.
+class PluginPhaseError extends Error {
+  readonly phase: FailedPlugin['phase']
+  readonly detail: string
+  readonly original: unknown
+  constructor(phase: FailedPlugin['phase'], detail: string, original: unknown) {
+    super(detail)
+    this.name = 'PluginPhaseError'
+    this.phase = phase
+    this.detail = detail
+    this.original = original
+  }
+}
+
+type RegisterOnePluginArgs = {
+  resolved: ResolvedPlugin
+  config: unknown
+  agentDir: string
+  registry: PluginRegistry
+  hooks: HookBus
+  permissions: PermissionService
+  ctxDeps: {
+    resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
+    hasGithubAppTokenResolver?: () => boolean
+    spawnSubagent: SpawnSubagentFn
+    isBooted: () => boolean
+  }
+}
+
+async function registerOnePlugin(args: RegisterOnePluginArgs): Promise<void> {
+  const { resolved, registry, hooks } = args
+
+  let validatedConfig: unknown = undefined
+  if (resolved.defined.configSchema) {
+    const parsed = (resolved.defined.configSchema as z.ZodType<unknown>).safeParse(args.config ?? {})
+    if (!parsed.success) {
+      const message = `plugin ${resolved.name}: config invalid: ${formatZodIssues(parsed.error)}`
+      throw new PluginPhaseError('config', message, new Error(message))
+    }
+    validatedConfig = parsed.data
+  } else if (args.config !== undefined) {
+    const message = `plugin ${resolved.name}: config block "${resolved.name}" present in typeclaw.json but plugin declares no configSchema`
+    throw new PluginPhaseError('config', message, new Error(message))
+  }
+
+  const logger = createPluginLogger(resolved.name)
+  const ctx = createPluginContext({
+    name: resolved.name,
+    version: resolved.version,
+    agentDir: args.agentDir,
+    config: validatedConfig as never,
+    logger,
+    permissions: args.permissions,
+    resolveGithubTokenForRepo: args.ctxDeps.resolveGithubTokenForRepo,
+    hasGithubAppTokenResolver: args.ctxDeps.hasGithubAppTokenResolver,
+    spawnSubagent: args.ctxDeps.spawnSubagent,
+    isBooted: args.ctxDeps.isBooted,
+  })
+
+  let exports: PluginExports
+  try {
+    exports = await resolved.defined.plugin(ctx)
+  } catch (err) {
+    discardRegistrationsBy(resolved.name, registry, hooks)
+    const message = `plugin ${resolved.name}: factory threw: ${err instanceof Error ? err.message : String(err)}`
+    throw new PluginPhaseError('factory', message, err)
+  }
+
+  try {
+    registerContributions({
+      pluginName: resolved.name,
+      logger,
+      exports,
+      ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
+      registry,
+      hooks,
+      agentDir: args.agentDir,
+      pluginConfig: validatedConfig,
+    })
+  } catch (err) {
+    discardRegistrationsBy(resolved.name, registry, hooks)
+    throw new PluginPhaseError('register', err instanceof Error ? err.message : String(err), err)
+  }
+}
+
 function collectDeclaredPermissions(
   plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
 ): readonly string[] {

package/src/reload/client.ts

@@ -10,6 +10,13 @@ export type RequestReloadOptions = {
 
 const DEFAULT_TIMEOUT_MS = 30_000
 
+export class ReloadConnectionError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ReloadConnectionError'
+  }
+}
+
 export async function requestReload({
   url,
   scope,
@@ -26,11 +33,15 @@ export async function requestReload({
     }
     const onError = (err: unknown) => {
       cleanup()
-      reject(new Error(`failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`))
+      reject(
+        new ReloadConnectionError(
+          `failed to connect to ${displayUrl}: ${err instanceof Error ? err.message : String(err)}`,
+        ),
+      )
     }
     const onClose = () => {
       cleanup()
-      reject(new Error(`connection to ${displayUrl} closed before opening`))
+      reject(new ReloadConnectionError(`connection to ${displayUrl} closed before opening`))
     }
     const cleanup = () => {
       if (timer !== undefined) clearTimeout(timer)
@@ -41,7 +52,7 @@ export async function requestReload({
     timer = setTimeout(() => {
       cleanup()
       ws.close()
-      reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
+      reject(new ReloadConnectionError(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
     }, timeoutMs)
     ws.addEventListener('open', onOpen, { once: true })
     ws.addEventListener('error', onError, { once: true })