typeclaw 0.36.1 → 0.36.3

package/src/channels/adapters/line-attachment.ts

@@ -0,0 +1,97 @@
+import type { LinePushMessageEvent } from 'agent-messenger/line'
+
+import type { InboundAttachment } from '@/channels/types'
+
+// Splits an inbound LINE event into (text, attachments[]). Text is what the
+// agent sees in its prompt; attachments[] carries the in-turn id + kind the
+// router uses to resolve `channel_fetch_attachment` / `look_at` by id.
+//
+// LINE differs from KakaoTalk in one load-bearing way: the upstream SDK
+// (`agent-messenger/line`) currently forwards only `content_type` on the push
+// event, NOT `contentMetadata`. So unlike the KakaoTalk splitter, this one has
+// no sticker id / file name / media URL to surface — every attachment is
+// REF-FREE (empty `ref`, no fetchable handle). The placeholder is therefore
+// coarse on purpose (`[LINE sticker]`, `[LINE image]`). When the SDK starts
+// forwarding metadata (agent-messenger#214), enrich this file only; the
+// adapter / classifier contract does not change.
+//
+// Keeping the ref out of the prompt text is the same invariant the KakaoTalk
+// splitter documents: there is exactly ONE way to fetch an attachment — by its
+// in-turn id — so a hallucinated/malformed ref can never reach a tool.
+
+export type SplitInboundLine = {
+  text: string
+  attachments: InboundAttachment[]
+}
+
+// LINE thrift ContentType. The SDK stringifies `msg.raw.contentType`, which the
+// thrift layer usually renders as the symbolic name, but the wire enum is
+// numeric (see @evex/linejs-types ContentType). Normalize defends against both
+// forms so a numeric leak ("7") still maps to STICKER rather than falling
+// through to the unknown bucket.
+const NUMERIC_CONTENT_TYPE: Record<string, string> = {
+  '0': 'NONE',
+  '1': 'IMAGE',
+  '2': 'VIDEO',
+  '3': 'AUDIO',
+  '7': 'STICKER',
+  '13': 'CONTACT',
+  '14': 'FILE',
+  '15': 'LOCATION',
+}
+
+// Non-text content types that map cleanly onto the fixed InboundAttachment.kind
+// union. Types with no clean mapping (CONTACT, LOCATION, and anything unknown)
+// route as placeholder-only text — an attachment with an empty ref and an
+// invented kind would offer the agent an unusable handle, so we don't make one.
+const CONTENT_TYPE_TO_KIND: Record<string, InboundAttachment['kind']> = {
+  STICKER: 'sticker',
+  IMAGE: 'photo',
+  VIDEO: 'video',
+  AUDIO: 'audio',
+  FILE: 'file',
+}
+
+const PLACEHOLDER_ONLY_LABEL: Record<string, string> = {
+  CONTACT: 'contact',
+  LOCATION: 'location',
+}
+
+export function normalizeLineContentType(raw: string | null | undefined): string {
+  if (raw === null || raw === undefined) return 'NONE'
+  const trimmed = raw.trim()
+  if (trimmed === '') return 'NONE'
+  const numeric = NUMERIC_CONTENT_TYPE[trimmed]
+  if (numeric !== undefined) return numeric
+  const upper = trimmed.toUpperCase()
+  // LINE text is `NONE` on the wire; treat the `TEXT` spelling as the same so
+  // a genuine text message never falls into the placeholder path.
+  return upper === 'TEXT' ? 'NONE' : upper
+}
+
+export function splitInboundLine(event: LinePushMessageEvent, startId = 1): SplitInboundLine {
+  const contentType = normalizeLineContentType(event.content_type)
+
+  // NONE is LINE text; a blank NONE message stays an `empty_text` drop in the
+  // classifier, so synthesize nothing and pass the raw text through.
+  if (contentType === 'NONE') {
+    return { text: event.text ?? '', attachments: [] }
+  }
+
+  const kind = CONTENT_TYPE_TO_KIND[contentType]
+  const rawText = event.text ?? ''
+
+  if (kind !== undefined) {
+    const id = startId
+    const placeholder = `[LINE ${kind}]`
+    const text = rawText === '' ? placeholder : `${rawText}\n${placeholder}`
+    return { text, attachments: [{ id, kind, ref: '' }] }
+  }
+
+  // Placeholder-only types (contact, location, unknown/future). No attachment
+  // entry — there is nothing fetchable and no valid kind to assign.
+  const label = PLACEHOLDER_ONLY_LABEL[contentType] ?? `message: ${contentType}`
+  const placeholder = `[LINE ${label}]`
+  const text = rawText === '' ? placeholder : `${rawText}\n${placeholder}`
+  return { text, attachments: [] }
+}

package/src/channels/adapters/line-classify.ts

@@ -2,7 +2,7 @@ import type { LinePushMessageEvent } from 'agent-messenger/line'
 
 import { matchesAnyAlias } from '@/channels/engagement'
 import type { ChannelAdapterConfig } from '@/channels/schema'
-import type { InboundMessage } from '@/channels/types'
+import type { InboundAttachment, InboundMessage } from '@/channels/types'
 
 export type InboundDropReason = 'self_author' | 'empty_text' | 'unknown_chat' | 'pre_connect'
 
@@ -22,6 +22,13 @@ export type LineInboundContext = {
   // LINE push events lack `author_name`, so the adapter resolves it (best
   // effort) and passes it here; falls back to the raw author id.
   authorName?: string
+  // The adapter splits the raw event into prompt text + attachments (non-text
+  // content types become a placeholder string and a ref-free attachment) and
+  // passes the result here, so the classifier routes on the synthesized text
+  // rather than the raw `event.text`. Omitted for plain text inbounds, where
+  // `event.text` is authoritative.
+  text?: string
+  attachments?: readonly InboundAttachment[]
 }
 
 export function classifyInbound(
@@ -36,8 +43,11 @@ export function classifyInbound(
     return { kind: 'drop', reason: 'self_author' }
   }
 
-  const text = event.text ?? ''
-  if (text === '') return { kind: 'drop', reason: 'empty_text' }
+  const text = context.text ?? event.text ?? ''
+  const attachments = context.attachments ?? []
+  if (text === '' && attachments.length === 0) {
+    return { kind: 'drop', reason: 'empty_text' }
+  }
 
   const chatInfo = context.lookupChat(event.chat_id)
   if (chatInfo === null) {
@@ -65,6 +75,7 @@ export function classifyInbound(
       chat: event.chat_id,
       thread: null,
       text,
+      ...(attachments.length > 0 ? { attachments } : {}),
       externalMessageId: event.message_id,
       authorId: event.author_id,
       authorName,

package/src/channels/adapters/line.ts

@@ -25,6 +25,7 @@ import type {
   SendResult,
 } from '@/channels/types'
 
+import { splitInboundLine } from './line-attachment'
 import { createLineChannelResolver } from './line-channel-resolver'
 import { classifyInbound } from './line-classify'
 import { toLinePlainText } from './line-format'
@@ -217,13 +218,16 @@ export function createLineAdapter(options: LineAdapterOptions): LineAdapter {
 
       const bucket = channelResolver.lookupChat(event.chat_id)?.workspace ?? '@line-group'
       const inboundTag = await formatChannelTag(bucket, event.chat_id)
+      const { text, attachments } = splitInboundLine(event)
       logger.info(
-        `[line] inbound message_id=${event.message_id} author=${event.author_id} ${inboundTag} text_len=${(event.text ?? '').length}`,
+        `[line] inbound message_id=${event.message_id} author=${event.author_id} ${inboundTag} content_type=${event.content_type} text_len=${text.length} attachments=${attachments.length}`,
       )
 
       const verdict = classifyInbound(event, options.configRef(), {
         selfUserId,
         lookupChat: (id) => channelResolver.lookupChat(id),
+        text,
+        attachments,
         ...(options.selfAliasesRef ? { selfAliases: options.selfAliasesRef() } : {}),
       })
       if (verdict.kind === 'drop') {

package/src/channels/manager.ts

@@ -297,10 +297,22 @@ export function createChannelManager(options: ChannelManagerOptions): ChannelMan
 
     async start(): Promise<void> {
       const cfg = options.channelsConfigRef()
-      for (const name of ADAPTER_IDS) {
+      // Safe to fan out: `live` and every router registry are keyed by adapter
+      // name, so concurrent starts never collide. Serial start would otherwise pay
+      // the sum of each adapter's connect latency instead of just the slowest.
+      const starts = ADAPTER_IDS.flatMap((name) => {
         const adapterCfg = cfg[name]
-        if (adapterCfg !== undefined) await runSerially(name, () => startAdapter(name, adapterCfg))
-      }
+        return adapterCfg === undefined ? [] : [runSerially(name, () => startAdapter(name, adapterCfg))]
+      })
+      // Await every launched start to settle BEFORE surfacing a failure.
+      // `startAdapter` converts expected per-adapter failures to `false`, so a
+      // rejection is an unexpected throw (e.g. `buildAdapter`) that must still
+      // fail-fast. But bailing on the first rejection (plain `Promise.all`) would
+      // leave sibling starts in flight, letting a late `live.set` orphan an adapter
+      // that the caller's subsequent `stop()` never sees. Settle all, then rethrow.
+      const results = await Promise.allSettled(starts)
+      const failure = results.find((r): r is PromiseRejectedResult => r.status === 'rejected')
+      if (failure !== undefined) throw failure.reason
     },
 
     async stop(): Promise<void> {

package/src/channels/router.ts

@@ -138,6 +138,20 @@ export const SESSION_GC_INTERVAL_MS = 60 * 1000
 // recovery paths (`source: 'system'`) bypass.
 export const MAX_CHANNEL_SENDS_PER_TURN = 10
 export const ENGAGE_REACTION_EMOJI = 'eyes'
+// Best-effort "zipping it / going quiet" ack dropped on the triggering message
+// when the model disengages (channel_disengage); fire-and-forget like engage :eyes:.
+export const DISENGAGE_REACTION_EMOJI = 'zipper_mouth_face'
+// Per-adapter fallback for platforms that cannot render the default. GitHub's
+// Reactions API is a fixed 8-emoji set with no zipper-mouth; 'confused' is the
+// closest "stepping back" signal it can post, so a GitHub disengage still acks
+// instead of silently no-op'ing on the unsupported result.
+const DISENGAGE_REACTION_EMOJI_OVERRIDES: Partial<Record<AdapterId, string>> = {
+  github: 'confused',
+}
+
+export function disengageReactionEmojiFor(adapter: AdapterId): string {
+  return DISENGAGE_REACTION_EMOJI_OVERRIDES[adapter] ?? DISENGAGE_REACTION_EMOJI
+}
 
 // Wake nudge pushed into a resumed channel session at boot so drain() has a
 // non-empty batch and fires a turn. The substantive instruction the model acts
@@ -691,6 +705,12 @@ type LiveSession = {
 type ChannelCommandContext = {
   live: LiveSession | null
   event: InboundMessage | null
+  // The user who actually invoked the command, supplied by BOTH dispatch
+  // paths (text: event.authorId; native slash: options.invokerId, where
+  // event is null). /restart stamps the resume handoff's triggeringAuthorId
+  // from this so a restart resumes under the INVOKER's author-scoped role,
+  // not whichever speaker happened to own the live turn.
+  invokerId: string | null
 }
 
 export type ExecuteCommandResult =
@@ -999,6 +1019,7 @@ export type RestartCommandContext = {
   originatingSessionId: string
   originatingSessionFile?: string
   handoffOrigin: { kind: 'channel'; key: ChannelKey }
+  triggeringAuthorId?: string
 }
 
 export type ClaimHandlerInput = {
@@ -1125,18 +1146,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       // Resolve the live session when one exists so the restart can write a
       // resume handoff for this conversation; still bounces from a cold channel.
       wantsLiveSession: true,
-      handler: async ({ live }) => ({
-        reply: await onRestart(
-          live !== null
-            ? {
-                originatingSessionId: live.sessionId,
-                ...(live.getTranscriptPath?.() !== undefined
-                  ? { originatingSessionFile: live.getTranscriptPath!()! }
-                  : {}),
-                handoffOrigin: { kind: 'channel', key: live.key },
-              }
-            : undefined,
-        ),
+      handler: async ({ live, invokerId }) => ({
+        reply: await onRestart(live !== null ? buildRestartCommandContext(live, invokerId) : undefined),
       }),
     })
   }
@@ -1933,6 +1944,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     }
   }
 
+  const buildRestartCommandContext = (live: LiveSession, invokerId: string | null): RestartCommandContext => {
+    // Prefer the command invoker: a restart resumes under the author who ran
+    // /restart, not whichever speaker last owned the live turn. Fall back to
+    // live turn state only when the dispatch path supplied no invoker.
+    const triggeringAuthorId = invokerId ?? live.currentTurnAuthorId ?? live.lastTurnAuthorId ?? undefined
+    return {
+      originatingSessionId: live.sessionId,
+      ...(live.getTranscriptPath?.() !== undefined ? { originatingSessionFile: live.getTranscriptPath!()! } : {}),
+      handoffOrigin: { kind: 'channel', key: live.key },
+      ...(triggeringAuthorId !== undefined ? { triggeringAuthorId } : {}),
+    }
+  }
+
   const buildLiveOrigin = (live: LiveSession): SessionOrigin => {
     const membership = readMembership(live.key)
     const self = resolveSelfIdentity(live.key)
@@ -2234,7 +2258,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // Gating (channel.respond / session.control) and live-session resolution stay
   // at the call sites — this helper only runs the handler and delivers the reply.
   const runChannelCommand = async (event: InboundMessage, live: LiveSession | null): Promise<CommandResult> => {
-    const result = await commands.execute(event.text, { live, event })
+    const result = await commands.execute(event.text, { live, event, invokerId: event.authorId })
     if (result.kind === 'handled' && result.reply !== undefined) {
       await send(
         {
@@ -3686,7 +3710,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
 
         let live: LiveSession
         try {
-          live = await ensureLive(key, undefined, undefined, {
+          live = await ensureLive(key, undefined, handoff.triggeringAuthorId, {
             sessionId: handoff.originatingSessionId,
             sessionFile: handoff.originatingSessionFile,
           })
@@ -3785,7 +3809,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       const resolved = resolveLiveSessionForCommand(liveSessions, key)
       live = resolved.kind === 'found' ? resolved.session : null
     }
-    const result = await commands.execute(`/${lowered}`, { live, event: null })
+    const result = await commands.execute(`/${lowered}`, { live, event: null, invokerId: options.invokerId })
     if (result.kind === 'handled') {
       return result.reply !== undefined
         ? { kind: 'handled', name: result.name, reply: result.reply }
@@ -3911,11 +3935,38 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     // not re-grant the credit just cleared (see `disengagedTurn`). No-op when
     // the key has no live session — the ledger clear above still stands.
     const live = liveSessions.get(keyId)
-    if (live && !live.destroyed) live.disengagedTurn = live.turnSeq
+    if (live && !live.destroyed) {
+      live.disengagedTurn = live.turnSeq
+      reactOnDisengage(live)
+    }
     logger.info(`[channels] ${keyId} sticky cleared count=${cleared}`)
     return { keyId, cleared }
   }
 
+  const reactOnDisengage = (live: LiveSession): void => {
+    if (live.currentTurnReactionRef === null) return
+    void react({
+      adapter: live.key.adapter,
+      workspace: live.key.workspace,
+      chat: live.key.chat,
+      thread: live.key.thread,
+      reactionRef: live.currentTurnReactionRef,
+      emoji: disengageReactionEmojiFor(live.key.adapter),
+    })
+      .then((result) => {
+        if (!result.ok && result.code !== 'unsupported') {
+          logger.info(
+            `[channels] disengage-react failed adapter=${live.key.adapter} chat=${live.key.chat}: ${result.error}`,
+          )
+        }
+      })
+      .catch((err) => {
+        logger.info(
+          `[channels] disengage-react threw adapter=${live.key.adapter} chat=${live.key.chat}: ${describe(err)}`,
+        )
+      })
+  }
+
   return {
     route,
     send,

package/src/cli/hostd.ts

@@ -7,6 +7,7 @@ import { createKakaoRenewalManager } from '@/hostd/kakao-renewal-manager'
 import { createPortbrokerManager } from '@/hostd/portbroker-manager'
 import type { SupervisorLogEvent, SupervisorRestart } from '@/hostd/supervisor'
 import { computeSourceVersion, resolveSrcRoot, UNVERSIONED_SENTINEL } from '@/hostd/version'
+import { validateRestartDeps, type RestartDepsPreflightResult } from '@/init/restart-deps-preflight'
 
 export const hostdCommand = defineCommand({
   meta: {
@@ -43,7 +44,7 @@ export const hostdCommand = defineCommand({
       onShutdown: () => process.exit(0),
       portbroker,
       kakaoRenewal,
-      restartPreflight: buildHostdRestartPreflight(cliEntry, version),
+      restartPreflight: buildHostdRestartPreflight(cliEntry, version, defaultPreflightDeps),
       restart: hostdRestart,
     })
 
@@ -104,10 +105,42 @@ export function buildHostdRestart(
   }
 }
 
-export function buildHostdRestartPreflight(cliEntry: string, daemonVersion: string): RestartPreflight {
-  return async () => {
+export type HostdPreflightDeps = {
+  loadConfigSync: (cwd: string) => Config
+  validateRestartDeps: (opts: { cwd: string; plugins: readonly string[] }) => Promise<RestartDepsPreflightResult>
+}
+
+const defaultPreflightDeps: HostdPreflightDeps = {
+  loadConfigSync,
+  validateRestartDeps,
+}
+
+export function buildHostdRestartPreflight(
+  cliEntry: string,
+  daemonVersion: string,
+  deps: HostdPreflightDeps = defaultPreflightDeps,
+): RestartPreflight {
+  return async ({ containerName, cwd }) => {
     const drift = await detectSourceDrift(cliEntry, daemonVersion)
-    return drift ? { ok: false, reason: drift } : null
+    if (drift) return { ok: false, reason: drift }
+
+    // Read plugins through loadConfigSync, not validateConfig: a config that
+    // fails schema validation is caught later in buildHostdRestart (before
+    // stop). On read/parse failure we let the restart proceed — start() is the
+    // fail-closed gate, and a preflight that can't read config must not strand a
+    // healthy agent.
+    let plugins: readonly string[]
+    try {
+      plugins = deps.loadConfigSync(cwd).plugins
+    } catch {
+      return null
+    }
+
+    const depsCheck = await deps.validateRestartDeps({ cwd, plugins })
+    if (!depsCheck.ok) {
+      return { ok: false, reason: `restart refused for ${containerName}: ${depsCheck.reason}` }
+    }
+    return null
   }
 }
 

package/src/cli/reload.ts

@@ -2,7 +2,7 @@ import { defineCommand } from 'citty'
 
 import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir } from '@/init'
-import { requestReload, type ReloadResult } from '@/reload'
+import { requestReloadWithFallback, type ReloadResult } from '@/reload'
 
 import { c, errorLine, spinner } from './ui'
 
@@ -24,18 +24,29 @@ export const reload = defineCommand({
     },
   },
   async run({ args }) {
-    const url = args.url ?? (await defaultUrl())
+    const timeoutMs = Number(args.timeout)
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+      console.error(errorLine(`invalid --timeout value: ${args.timeout}`))
+      process.exit(1)
+    }
+
+    const target = args.url === undefined ? await defaultTarget() : { url: args.url }
 
     const s = spinner()
     s.start('Reloading...')
     let results: ReloadResult[]
+    let recoveredHostError: string | undefined
     try {
-      results = await requestReload({ url, timeoutMs: Number(args.timeout) })
+      const response = await requestReloadWithFallback({ ...target, timeoutMs })
+      results = response.results
+      if (response.transport === 'container-local') recoveredHostError = response.hostError
     } catch (err) {
       s.error(`reload failed: ${err instanceof Error ? err.message : String(err)}`)
       process.exit(1)
     }
 
+    printReloadRecoveryHint(recoveredHostError)
+
     if (results.length === 0) {
       s.stop(c.dim('Nothing to reload.'))
       return
@@ -61,7 +72,17 @@ export const reload = defineCommand({
   },
 })
 
-async function defaultUrl(): Promise<string> {
+export function printReloadRecoveryHint(recoveredHostError: string | undefined): void {
+  if (recoveredHostError === undefined) return
+  console.error(
+    c.yellow(
+      `Recovered via container-local reload because Docker's published host port is not accepting WebSockets (${recoveredHostError}).`,
+    ),
+  )
+  console.error(c.dim('Run `typeclaw restart --port 0` when safe to repair host TUI/reload connectivity.'))
+}
+
+async function defaultTarget(): Promise<{ url: string; cwd: string; token: string | null }> {
   const cwd = findAgentDir(process.cwd()) ?? process.cwd()
   const precheck = await requireContainerRunning({ cwd })
   if (!precheck.ok) {
@@ -72,5 +93,5 @@ async function defaultUrl(): Promise<string> {
   const token = await resolveTuiToken({ cwd })
   const url = new URL(`ws://127.0.0.1:${port}`)
   if (token !== null) url.searchParams.set('token', token)
-  return url.toString()
+  return { url: url.toString(), cwd, token }
 }

package/src/cli/ui.ts

@@ -152,6 +152,7 @@ export type StartLikeResult = {
   containerId: string
   hostd: { state: 'registered' } | { state: 'unavailable'; reason: string } | { state: 'disabled' }
   autoUpgrade?: AutoUpgradeOutcome
+  skippedPlugins?: string[]
 }
 
 export function renderStartSuccess(result: StartLikeResult): string {
@@ -167,6 +168,11 @@ export function renderStartSuccess(result: StartLikeResult): string {
     }
   }
 
+  if (result.skippedPlugins && result.skippedPlugins.length > 0) {
+    const list = result.skippedPlugins.join(', ')
+    lines.push(`${c.yellow('Skipped plugins not found in the registry:')} ${list}`)
+  }
+
   if (result.alreadyRunning) {
     lines.push(`${c.green('●')} ${name} is already running on host port ${port}.`)
   } else {

package/src/container/index.ts

@@ -15,6 +15,7 @@ export {
   DOCKER_NOT_FOUND_STDERR,
   imageTagFromCwd,
   inspectContainer,
+  sanitizeDockerStderr,
   type ContainerState,
   type DockerAvailability,
   type DockerExec,

package/src/container/start.ts

@@ -140,6 +140,10 @@ export type StartResult =
       // path — that one rebuilds the container from scratch.
       alreadyRunning: boolean
       autoUpgrade: AutoUpgradeOutcome
+      // npm plugins dropped this start because their package 404s in the
+      // registry. Non-fatal by design: a typo'd or unpublished plugin warns
+      // instead of blocking the launch.
+      skippedPlugins: string[]
     }
   | { ok: false; reason: string }
 
@@ -438,6 +442,7 @@ export async function start({
       hostd: stripHostDaemonControl(hostd),
       alreadyRunning: false,
       autoUpgrade: upgrade,
+      skippedPlugins: pluginReconcile.skipped,
     }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
@@ -758,6 +763,7 @@ async function reportAlreadyRunning(exec: DockerExec, cwd: string, containerName
     hostd: { state: 'disabled' },
     alreadyRunning: true,
     autoUpgrade: { kind: 'skipped-already-running' },
+    skippedPlugins: [],
   }
 }
 

package/src/init/reconcile-plugin-deps.ts

@@ -6,12 +6,23 @@ import { splitPluginEntrySpec } from '@/plugin'
 
 const PACKAGE_FILE = 'package.json'
 
+const NOOP: ReconcilePluginDepsResult = { changed: false, files: [], skipped: [] }
+
 export type ReconcilePluginDepsResult = {
   changed: boolean
   files: string[]
+  // Plugins skipped because their package could not be found in the registry
+  // (npm 404 / E404). A missing plugin must not block `start`: the entry is
+  // dropped from this reconcile pass and surfaced here so the caller can warn.
+  skipped: string[]
 }
 
-export type ResolveLatestVersion = (packageName: string) => Promise<string>
+// Resolves a bare plugin name to its latest published version. Returns null
+// when the package genuinely does not exist in the registry (404 / E404) so
+// the caller can skip it without blocking start. Throws on every other failure
+// (network outage, missing bun runtime, empty registry response) — those are
+// transient or environmental, not "plugin not found", and must still block.
+export type ResolveLatestVersion = (packageName: string) => Promise<string | null>
 
 export type ReconcilePluginDepsOptions = {
   cwd: string
@@ -31,27 +42,27 @@ export async function reconcilePluginDeps(options: ReconcilePluginDepsOptions):
   const resolveLatest = options.resolveLatest ?? resolveLatestFromRegistry
 
   const pkgPath = join(cwd, PACKAGE_FILE)
-  if (!existsSync(pkgPath)) return { changed: false, files: [] }
+  if (!existsSync(pkgPath)) return NOOP
 
   let raw: string
   try {
     raw = await readFile(pkgPath, 'utf8')
   } catch {
-    return { changed: false, files: [] }
+    return NOOP
   }
 
   let pkg: PackageJsonShape
   try {
     const parsed = JSON.parse(raw) as unknown
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return { changed: false, files: [] }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return NOOP
     pkg = parsed as PackageJsonShape
   } catch {
-    return { changed: false, files: [] }
+    return NOOP
   }
 
   const dependencies = { ...pkg.dependencies }
   const previousManaged = readManagedPlugins(pkg)
-  const desired = await resolveDesiredManaged(plugins, previousManaged, resolveLatest)
+  const { desired, skipped } = await resolveDesiredManaged(plugins, previousManaged, resolveLatest)
 
   let changed = false
 
@@ -73,11 +84,11 @@ export async function reconcilePluginDeps(options: ReconcilePluginDepsOptions):
 
   if (!managedEqual(previousManaged, desired)) changed = true
 
-  if (!changed) return { changed: false, files: [] }
+  if (!changed) return { changed: false, files: [], skipped }
 
   const next = withManagedPlugins({ ...pkg, dependencies: sortKeys(dependencies) }, desired)
   await writeFile(pkgPath, `${JSON.stringify(next, null, 2)}\n`)
-  return { changed: true, files: [PACKAGE_FILE] }
+  return { changed: true, files: [PACKAGE_FILE], skipped }
 }
 
 type PackageJsonShape = {
@@ -97,19 +108,30 @@ async function resolveDesiredManaged(
   plugins: readonly string[],
   previousManaged: Record<string, string>,
   resolveLatest: ResolveLatestVersion,
-): Promise<Record<string, string>> {
+): Promise<{ desired: Record<string, string>; skipped: string[] }> {
   const desired: Record<string, string> = {}
+  const skipped: string[] = []
   for (const entry of plugins) {
     if (isLocalEntry(entry)) continue
     const { name, versionSpec } = splitPluginEntrySpec(entry)
     if (name.length === 0) continue
     if (versionSpec !== undefined) {
       desired[name] = versionSpec
-    } else {
-      desired[name] = previousManaged[name] ?? (await resolveLatest(name))
+      continue
+    }
+    const pinned = previousManaged[name]
+    if (pinned !== undefined) {
+      desired[name] = pinned
+      continue
+    }
+    const resolved = await resolveLatest(name)
+    if (resolved === null) {
+      skipped.push(name)
+      continue
     }
+    desired[name] = resolved
   }
-  return sortKeys(desired)
+  return { desired: sortKeys(desired), skipped }
 }
 
 function isLocalEntry(entry: string): boolean {
@@ -154,7 +176,7 @@ function sortKeys(obj: Record<string, string>): Record<string, string> {
   return out
 }
 
-async function resolveLatestFromRegistry(packageName: string): Promise<string> {
+async function resolveLatestFromRegistry(packageName: string): Promise<string | null> {
   const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
   if (!bun) throw new Error(`cannot resolve latest version for ${packageName}: bun runtime not available`)
   const proc = bun.spawn({
@@ -164,10 +186,18 @@ async function resolveLatestFromRegistry(packageName: string): Promise<string> {
   })
   const code = await proc.exited
   if (code !== 0) {
-    const stderr = await new Response(proc.stderr).text()
-    throw new Error(`failed to resolve latest version for ${packageName}: ${stderr.trim() || `exit ${code}`}`)
+    const stderr = (await new Response(proc.stderr).text()).trim()
+    if (isPackageNotFound(stderr)) return null
+    throw new Error(`failed to resolve latest version for ${packageName}: ${stderr || `exit ${code}`}`)
   }
   const version = (await new Response(proc.stdout).text()).trim().replace(/^["']|["']$/g, '')
   if (version.length === 0) throw new Error(`registry returned no version for ${packageName}`)
   return version
 }
+
+// A registry 404 means the package does not exist — a user typo or an
+// unpublished plugin — which `start` must tolerate, not abort on. Network and
+// auth failures are deliberately NOT matched here so they keep throwing.
+export function isPackageNotFound(stderr: string): boolean {
+  return /\bE404\b/.test(stderr) || /\b404\b/.test(stderr) || /not found/i.test(stderr)
+}