typeclaw 0.36.2 → 0.36.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.36.2",
+  "version": "0.36.4",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -48,7 +48,7 @@
     "@mariozechner/pi-tui": "^0.67.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.19.2",
+    "agent-messenger": "2.19.4",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",

package/src/agent/plugin-tools.ts

@@ -53,7 +53,7 @@ import {
   resolveSandboxSymlinks,
   resolveWritableZones,
   SandboxDegradedProcError,
-  type SandboxProcStrategy,
+  SandboxProcProbeUnverifiedError,
   subtractMasked,
 } from '@/sandbox'
 
@@ -644,15 +644,19 @@ async function applyBashSandbox(
   // bwrap does --clearenv, so the overlay must be re-introduced via env.set or
   // it would never reach the sandboxed process (the non-sandboxed spawnHook
   // path does not run when the command is rewritten to a bwrap invocation).
-  const proc = await resolveProcStrategy()
+  const { strategy: proc, degradeReason } = await resolveProcStrategy()
   // Fail fast with an actionable error when /proc degraded to tmpfs AND the
   // command needs a real /proc: under tmpfs Bun would otherwise abort deep in its
-  // pipeline with the opaque "NotDir", which the model retries forever. The
-  // SandboxDegradedProcError message tells it this is an environment limit, not
-  // the command's fault. Guarded on the command so non-bun bash still runs in the
-  // degraded mode (it does not touch /proc/self/{fd,maps}).
+  // pipeline with the opaque "NotDir", which the model retries forever. Which
+  // error depends on WHY it degraded: a 'definitive' degrade (a real leak / an
+  // incapable host) is permanent → SandboxDegradedProcError ("retrying won't
+  // help"); an 'unverified' degrade (the safety probe stayed inconclusive through
+  // its retry budget, e.g. a boot-time load spike) is transient and re-probes on
+  // the next call → SandboxProcProbeUnverifiedError ("retry the same command").
+  // Guarded on the command so non-bun bash still runs in the degraded mode (it
+  // does not touch /proc/self/{fd,maps}).
   if (proc === 'tmpfs' && commandNeedsRealProc(command)) {
-    throw new SandboxDegradedProcError()
+    throw degradeReason === 'unverified' ? new SandboxProcProbeUnverifiedError() : new SandboxDegradedProcError()
   }
   const { commandString } = buildSandboxedCommand(command, {
     mounts: [
@@ -698,26 +702,44 @@ function subtractMaskedProtected(
 // --mount-proc` in a container booted WITHOUT the cap (or vice versa). Both
 // probes are cached process-globally, so this resolves to one spawn per
 // container lifetime regardless of how many bash calls hit it.
-async function resolveProcStrategy(): Promise<SandboxProcStrategy> {
-  if (config.sandbox.realProc && (await canMountRealProc())) return 'real-proc'
+// A tmpfs degrade carries WHY it happened so the caller can pick a permanent vs
+// retryable error. 'definitive': the probe returned a real cross-userns leak
+// ('unsafe') — the ONLY verdict proven permanent, so it fails closed for good.
+// 'unverified': the safety probe never reached a definitive verdict within its
+// retry budget. That covers BOTH a transient load spike AND a durable
+// incapability (no usable namespaces, a bwrap that starts but cannot set up its
+// sandbox): the probe cannot prove a NEGATIVE capability — only a leak is
+// definitive — so a genuinely incapable host also lands here and simply keeps
+// re-degrading on each call. Since 'inconclusive' is never cached, that costs a
+// re-probe but is correct: the only false case is "capable but briefly
+// saturated", which recovers; an incapable host stays degraded either way.
+// Absent when the strategy is not tmpfs.
+type ProcStrategyResolution =
+  | { strategy: 'real-proc' | 'proc-bind'; degradeReason?: undefined }
+  | { strategy: 'tmpfs'; degradeReason: 'definitive' | 'unverified' }
+
+async function resolveProcStrategy(): Promise<ProcStrategyResolution> {
+  if (config.sandbox.realProc && (await canMountRealProc())) return { strategy: 'real-proc' }
   // Retry an 'inconclusive' proc-bind probe (transient under load) before
   // degrading — a single such hiccup must not break external-package runs on a
   // capable host. 'unsafe' still fails closed with no retry.
-  if (
-    await resolveProcBindSafetyWithRetry(
-      () => getProcBindSafetyVerdict(),
-      (ms) => Bun.sleep(ms),
-    )
+  const verdict = await resolveProcBindSafetyWithRetry(
+    () => getProcBindSafetyVerdict(),
+    (ms) => Bun.sleep(ms),
   )
-    return 'proc-bind'
+  if (verdict === 'safe') return { strategy: 'proc-bind' }
   // Degraded last resort: no working /proc strategy. External package runners
   // (bunx/bun add/bun run <pkg-bin>) will fail with Bun's opaque "NotDir" because
-  // /proc/self/{fd,maps} are absent. Warn once so an operator on such an exotic
-  // host (no usable user namespaces at all) gets a diagnostic instead of the bare
-  // Bun error. Not gated on parsing the command — that heuristic is fragile (see
-  // PR #696); this is a strategy-level notice, fail-closed and command-agnostic.
-  warnTmpfsProcFallbackOnce()
-  return 'tmpfs'
+  // /proc/self/{fd,maps} are absent. Only a proven 'unsafe' (a real cross-userns
+  // leak) is DEFINITIVE — warn once (a real operator-facing limit). An
+  // 'inconclusive' is reported as retryable upstream and NOT warned (it would cry
+  // wolf every boot storm); a durably-incapable host re-degrades quietly here,
+  // since the probe cannot distinguish it from transient load.
+  if (verdict === 'unsafe') {
+    warnTmpfsProcFallbackOnce()
+    return { strategy: 'tmpfs', degradeReason: 'definitive' }
+  }
+  return { strategy: 'tmpfs', degradeReason: 'unverified' }
 }
 
 let tmpfsProcFallbackWarned = false

package/src/agent/system-prompt.ts

@@ -1,5 +1,8 @@
 import { formatLocalDateTime, formatLocalWeekday, resolveLocalTimezoneName } from '@/shared'
 
+const PACKAGE_JSON_INSTALL_RULE =
+  "After editing `package.json` (adding, removing, or bumping dependencies/plugins), run the project's package manager to update the lockfile and installed dependency state — e.g. `bun install`, `npm install`, `pnpm install`, or `yarn install`, matching the existing lockfile. Commit the lockfile change alongside the `package.json` edit."
+
 // The orchestration roster (the `Briefly: ...` enumeration of public subagents)
 // is GENERATED from the registry by `renderPublicSubagentRoster` and threaded in
 // here, so a newly-registered public subagent can never be silently missing from
@@ -83,6 +86,7 @@ Your agent folder is a git repository.
 - Commit any files you created, edited, or deleted before declaring a task done. One logical change = one commit; split unrelated changes.
 - Use \`git add <paths>\` (not \`git add -A\`). Imperative commit messages ("Update SOUL.md to be less formal"); explain *why* in the body if non-obvious.
 - Never commit \`secrets.json\`, \`.env\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
+- ${PACKAGE_JSON_INSTALL_RULE}
 - Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks.
 
 ## How to behave
@@ -251,6 +255,8 @@ Never suppress errors to make things "work", and never fabricate results. If som
 
 Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
 
+${PACKAGE_JSON_INSTALL_RULE}
+
 Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. \`public/\` is the guest-visible zone — write there anything meant to be shared with an untrusted caller (a \`guest\`-role turn cannot read \`workspace/\` but can read \`public/\`). Do not edit \`memory/topics/\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or let the memory-logger append to \`memory/streams/\`. Never stage or commit \`secrets.json\`, \`.env\`, \`sessions/\`, \`memory/\`, or \`workspace/\` — those are runtime- or user-managed.
 
 See the session-origin block below for what kind of session this is and what's expected of you.`

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/adapters/slack-bot-classify.ts

@@ -14,6 +14,7 @@ export type SlackInboundAppMentionEvent = SlackSocketModeAppMentionEvent
 export type InboundDropReason =
   | 'self_author' // event.user === botUserId; we never route our own messages back to ourselves
   | 'no_user' // event has no `user` field (e.g. system messages: channel_join, message_changed)
+  | 'slack_system_message' // non-replyable Slack message subtype events (e.g. channel_topic)
   | 'empty_text' // event has neither text nor files — nothing for the agent to act on
   | 'pre_connect' // bot identity is not known yet, so mention/self/reply classification cannot be trusted
 
@@ -62,6 +63,10 @@ export function classifyInbound(
     return { kind: 'drop', reason: 'no_user' }
   }
 
+  if (!isRouteableSlackMessageSubtype(event.subtype)) {
+    return { kind: 'drop', reason: 'slack_system_message' }
+  }
+
   const rawText = event.text ?? ''
   const { text, attachments } = splitInbound(event)
   const slackAttachments = Array.isArray(event.attachments) ? event.attachments : undefined
@@ -156,6 +161,10 @@ export function classifyInbound(
   }
 }
 
+export function isRouteableSlackMessageSubtype(subtype: string | undefined): boolean {
+  return subtype === undefined || subtype === 'bot_message' || subtype === 'file_share' || subtype === 'me_message'
+}
+
 // Slack encodes user mentions inline as `<@U…>` (or `<@W…>` for some org
 // accounts, and `<@U…|fallback>` when the client supplied a label). Pull
 // every distinct id out of the text — duplicates collapse so the caller

package/src/channels/adapters/slack-bot.ts

@@ -38,6 +38,7 @@ import {
   classifyInbound,
   describeSlackFile,
   type InboundDropReason,
+  isRouteableSlackMessageSubtype,
   renderPlaceholder,
   type SlackInboundAppMentionEvent,
   type SlackInboundMessageEvent,
@@ -694,7 +695,7 @@ export function createSlackHistoryCallback(deps: {
     }
 
     const botUserId = botUserIdRef()
-    const rawMessages = raw.messages ?? []
+    const rawMessages = (raw.messages ?? []).filter((message) => isRouteableSlackMessageSubtype(message.subtype))
     const mapped = rawMessages.map((m) => mapSlackMessage(m, botUserId))
     // History payloads carry no profile, so mapSlackMessage echoes the raw
     // id into authorName; resolve it here so prompts show display names.
@@ -1316,6 +1317,7 @@ function dropHint(reason: InboundDropReason): string {
     case 'no_user':
     case 'pre_connect':
     case 'self_author':
+    case 'slack_system_message':
       return ''
   }
 }

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/container/index.ts

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

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 })

package/src/reload/docker-exec-client.ts

@@ -0,0 +1,109 @@
+import {
+  CONTAINER_PORT,
+  containerNameFromCwd,
+  defaultDockerExec,
+  sanitizeDockerStderr,
+  type DockerExec,
+  type DockerExecResult,
+} from '@/container'
+
+import type { ReloadResult } from './types'
+
+export type RequestReloadViaDockerExecOptions = {
+  cwd: string
+  token: string | null
+  scope?: string
+  timeoutMs?: number
+  exec?: DockerExec
+}
+
+type DockerExecReloadEnvelope = { ok: true; results: ReloadResult[] } | { ok: false; reason: string }
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+const RELOAD_SCRIPT = String.raw`
+const timeoutMs = Number(process.env.TYPECLAW_RELOAD_TIMEOUT_MS ?? '30000')
+const url = new URL('ws://127.0.0.1:' + (process.env.TYPECLAW_CONTAINER_PORT ?? '8973'))
+if (process.env.TYPECLAW_TUI_TOKEN) url.searchParams.set('token', process.env.TYPECLAW_TUI_TOKEN)
+const ws = new WebSocket(url.toString())
+let settled = false
+const finish = (payload, code) => {
+  if (settled) return
+  settled = true
+  console.log(JSON.stringify(payload))
+  if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN) ws.close()
+  setTimeout(() => process.exit(code), 0)
+}
+const timer = setTimeout(() => finish({ ok: false, reason: 'timed out waiting for container-local reload_result after ' + timeoutMs + 'ms' }, 1), timeoutMs)
+ws.addEventListener('open', () => {
+  const scope = process.env.TYPECLAW_RELOAD_SCOPE
+  ws.send(JSON.stringify(scope ? { type: 'reload', scope } : { type: 'reload' }))
+})
+ws.addEventListener('message', (event) => {
+  const msg = JSON.parse(String(event.data))
+  if (msg.type !== 'reload_result') return
+  clearTimeout(timer)
+  finish({ ok: true, results: msg.results }, 0)
+})
+ws.addEventListener('error', (event) => finish({ ok: false, reason: String(event.message ?? event) }, 1))
+ws.addEventListener('close', () => finish({ ok: false, reason: 'container-local websocket closed before reload_result' }, 1))
+`
+
+export async function requestReloadViaDockerExec({
+  cwd,
+  token,
+  scope,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  exec = defaultDockerExec,
+}: RequestReloadViaDockerExecOptions): Promise<ReloadResult[]> {
+  const envArgs = ['-e', `TYPECLAW_CONTAINER_PORT=${CONTAINER_PORT}`, '-e', `TYPECLAW_RELOAD_TIMEOUT_MS=${timeoutMs}`]
+  if (token !== null) envArgs.push('-e', `TYPECLAW_TUI_TOKEN=${token}`)
+  if (scope !== undefined) envArgs.push('-e', `TYPECLAW_RELOAD_SCOPE=${scope}`)
+
+  const signal = AbortSignal.timeout(timeoutMs)
+  let result: DockerExecResult
+  try {
+    result = await exec(['exec', ...envArgs, containerNameFromCwd(cwd), 'bun', '-e', RELOAD_SCRIPT], { signal })
+  } catch (err) {
+    if (signal.aborted) throw new Error(`docker exec timed out after ${timeoutMs}ms`)
+    throw err
+  }
+  if (signal.aborted) throw new Error(`docker exec timed out after ${timeoutMs}ms`)
+  if (result.exitCode !== 0) {
+    const envelope = parseEnvelope(result.stdout)
+    if (envelope !== null && !envelope.ok) throw new Error(envelope.reason)
+    const reason =
+      sanitizeDockerStderr(result.stderr) || result.stdout.trim() || `docker exec exited with code ${result.exitCode}`
+    throw new Error(reason)
+  }
+
+  const envelope = parseEnvelope(result.stdout)
+  if (envelope === null) throw new Error('container-local reload returned invalid JSON')
+  if (!envelope.ok) throw new Error(envelope.reason)
+  return envelope.results
+}
+
+function parseEnvelope(stdout: string): DockerExecReloadEnvelope | null {
+  const line = stdout
+    .split('\n')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .at(-1)
+  if (line === undefined) return null
+  try {
+    const parsed: unknown = JSON.parse(line)
+    return isEnvelope(parsed) ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+function isEnvelope(value: unknown): value is DockerExecReloadEnvelope {
+  if (!isRecord(value) || typeof value.ok !== 'boolean') return false
+  if (value.ok) return Array.isArray(value.results)
+  return typeof value.reason === 'string'
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}

package/src/reload/index.ts

@@ -1,4 +1,10 @@
-export { requestReload, type RequestReloadOptions } from './client'
+export { ReloadConnectionError, requestReload, type RequestReloadOptions } from './client'
+export { requestReloadViaDockerExec, type RequestReloadViaDockerExecOptions } from './docker-exec-client'
 export { formatChannelReloadSummary } from './format'
 export { ReloadRegistry } from './registry'
+export {
+  requestReloadWithFallback,
+  type RequestReloadWithFallbackOptions,
+  type RequestReloadWithFallbackResult,
+} from './recover'
 export type { Reloadable, ReloadAllResult, ReloadResult } from './types'

package/src/reload/recover.ts

@@ -0,0 +1,38 @@
+import { ReloadConnectionError, requestReload } from './client'
+import { requestReloadViaDockerExec } from './docker-exec-client'
+import type { ReloadResult } from './types'
+
+export type RequestReloadWithFallbackOptions = {
+  url: string
+  cwd?: string
+  token?: string | null
+  scope?: string
+  timeoutMs?: number
+  reload?: typeof requestReload
+  reloadViaDockerExec?: typeof requestReloadViaDockerExec
+}
+
+export type RequestReloadWithFallbackResult =
+  | { transport: 'host'; results: ReloadResult[] }
+  | { transport: 'container-local'; results: ReloadResult[]; hostError: string }
+
+export async function requestReloadWithFallback({
+  url,
+  cwd,
+  token,
+  scope,
+  timeoutMs,
+  reload = requestReload,
+  reloadViaDockerExec = requestReloadViaDockerExec,
+}: RequestReloadWithFallbackOptions): Promise<RequestReloadWithFallbackResult> {
+  try {
+    return { transport: 'host', results: await reload({ url, scope, timeoutMs }) }
+  } catch (err) {
+    if (!(err instanceof ReloadConnectionError) || cwd === undefined || token === undefined) throw err
+    return {
+      transport: 'container-local',
+      results: await reloadViaDockerExec({ cwd, token, scope, timeoutMs }),
+      hostError: err.message,
+    }
+  }
+}

package/src/sandbox/availability.ts

@@ -220,29 +220,46 @@ export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boo
 // leak-block guarantee — it only buys more chances to PROVE it.
 export const PROC_BIND_RETRY_BACKOFF_MS = [250, 1_000, 2_000, 4_000] as const
 
+// The retrying resolver returns the SAME three states as the probe, never a
+// boolean: 'safe' selects proc-bind; the two failure states stay DELIBERATELY
+// distinct so the caller reacts differently. 'unsafe' is a DEFINITIVE host fact
+// (a real cross-userns environ leak was observed, or the binary is genuinely
+// absent) — permanent, fail closed, retrying buys nothing. 'inconclusive' means
+// the safety probe never returned a definitive verdict within the backoff budget
+// (a boot-time CPU/IO storm tripping the probe's own timeout) — it proves NOTHING
+// about the host, so the SAME container can recover on a later call once the
+// spike passes. Folding these two into a single boolean `false` is what made a
+// transient boot-storm degrade look permanent: the caller degraded to tmpfs AND
+// told the model "retrying won't help", so a capable host stayed broken until
+// restart.
+//
 // proc-bind selection must distinguish "definitely unavailable" from "couldn't
-// verify right now". A DEFINITIVE verdict is final: 'safe'→true; a real userns
-// leak ('unsafe')→false with NO retry. Only an 'inconclusive' verdict (transient
-// probe failure that proves nothing about the host) is retried, because degrading
-// the bash call to tmpfs over a transient hiccup is what silently broke
+// verify right now". A DEFINITIVE verdict is final: 'safe'; a real userns leak
+// ('unsafe') with NO retry. Only an 'inconclusive' verdict (transient probe
+// failure that proves nothing about the host) is retried, because degrading the
+// bash call to tmpfs over a transient hiccup is what silently broke
 // external-package runs on capable hosts. 'inconclusive' is never cached
 // (see the cache type), so each retry re-probes from scratch. After the backoff
-// budget is exhausted we fail CLOSED — an unverified leak-block is never treated
-// as safe. Pure and dependency-injected (probe + sleep) so the retry policy is
-// unit-testable without spawning processes; production passes
-// getProcBindSafetyVerdict and Bun.sleep.
+// budget is exhausted we return 'inconclusive' — an unverified leak-block is
+// never treated as safe, but the RESULT (a transient unknown, not a definitive
+// 'unsafe') lets the caller offer a retryable degrade. Pure and
+// dependency-injected (probe + sleep) so the retry policy is unit-testable
+// without spawning processes; production passes getProcBindSafetyVerdict and
+// Bun.sleep.
 export async function resolveProcBindSafetyWithRetry(
   probe: () => Promise<ProcBindSafetyVerdict>,
   sleep: (ms: number) => Promise<void>,
   backoffMs: readonly number[] = PROC_BIND_RETRY_BACKOFF_MS,
-): Promise<boolean> {
+): Promise<ProcBindSafetyVerdict> {
   for (let attempt = 0; ; attempt++) {
     const verdict = await probe()
-    if (verdict === 'safe') return true
-    if (verdict === 'unsafe') return false
+    if (verdict === 'safe') return 'safe'
+    if (verdict === 'unsafe') return 'unsafe'
 
     const backoff = backoffMs[attempt]
-    if (backoff === undefined) return false
+    // Budget exhausted: still unverified. Report 'inconclusive' (NOT 'unsafe') so
+    // the caller knows this is a retryable unknown, not a definitive host fact.
+    if (backoff === undefined) return 'inconclusive'
     await sleep(backoff)
   }
 }
@@ -282,9 +299,14 @@ async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
     // marker: that proves the sentinel is dumpable, same-uid, AND that this pid is
     // OUR sentinel (not a reused pid), so the ONLY thing that can deny the read
     // from inside the sandbox is the child-userns boundary (rules out a false
-    // "blocked" from dumpable=0 / uid mismatch). If the parent can't read the
-    // marker, the sentinel setup is unsound — inconclusive, fail closed, no cache.
-    if (!(await parentReadsSentinelMarker(sentinelPid))) return INCONCLUSIVE
+    // "blocked" from dumpable=0 / uid mismatch). The marker can be absent for a
+    // moment right after Bun.spawn: the child pid exists before `/usr/bin/env -i
+    // SECRET=... /bin/sleep` has exec'd and replaced its environ. Treating that
+    // startup race as immediate INCONCLUSIVE made the retry budget collapse into
+    // pure backoff time (~7.25s) and produced the first-tool `bunx` degrade even
+    // though the same host proved safe on the next call. Wait briefly for the
+    // marker before deciding setup is unsound; a real failure still fails closed.
+    if (!(await waitForSentinelMarker(sentinelPid))) return INCONCLUSIVE
 
     const proc = Bun.spawn(
       [
@@ -387,6 +409,9 @@ async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
 // briefly-saturated box; a genuinely wedged runtime still trips it and degrades.
 const PROC_BIND_PROBE_TIMEOUT_MS = 12_000
 
+const PROC_BIND_SENTINEL_READY_TIMEOUT_MS = 1_000
+const PROC_BIND_SENTINEL_READY_POLL_MS = 25
+
 // Designated probe-script exit codes. ONLY these two are a cacheable verdict;
 // every other code (a setup failure, bwrap startup failure, a signal, 127, …) is
 // inconclusive and must NOT be cached — see the exit-code interpretation in
@@ -457,6 +482,24 @@ async function parentReadsSentinelMarker(sentinelPid: number): Promise<boolean>
   }
 }
 
+async function waitForSentinelMarker(
+  sentinelPid: number,
+  readMarker: (pid: number) => Promise<boolean> = parentReadsSentinelMarker,
+  sleep: (ms: number) => Promise<void> = (ms) => Bun.sleep(ms),
+  timeoutMs: number = PROC_BIND_SENTINEL_READY_TIMEOUT_MS,
+  pollMs: number = PROC_BIND_SENTINEL_READY_POLL_MS,
+  now: () => number = Date.now,
+): Promise<boolean> {
+  const deadline = now() + timeoutMs
+  for (;;) {
+    if (await readMarker(sentinelPid)) return true
+    if (now() >= deadline) return false
+    await sleep(pollMs)
+  }
+}
+
+export const _waitForSentinelMarkerForTests = waitForSentinelMarker
+
 export function _resetProcBindProbeCacheForTests(): void {
   procBindProbeCache.clear()
   procBindProbeInFlight.clear()

package/src/sandbox/errors.ts

@@ -41,3 +41,29 @@ export class SandboxDegradedProcError extends Error {
     )
   }
 }
+
+// Distinct from SandboxDegradedProcError: that one is the PERMANENT verdict (a
+// real userns leak, or a host with no usable namespaces — retrying is futile).
+// This one fires when the proc-bind safety probe stayed 'inconclusive' through
+// its whole retry budget — typically a boot-time CPU/IO storm tripping the
+// probe's own timeout. The host is very likely capable; the probe just couldn't
+// prove it RIGHT NOW. Because an 'inconclusive' verdict is never cached, the next
+// bash call re-probes from scratch and usually promotes to proc-bind once the
+// spike passes. So the message tells the model the OPPOSITE of the permanent
+// case: retrying IS the fix. Without this split, a single unlucky boot-storm
+// probe degraded a fully-capable container to tmpfs and told the agent it was a
+// permanent environment limit — so it gave up instead of retrying.
+export class SandboxProcProbeUnverifiedError extends Error {
+  override readonly name = 'SandboxProcProbeUnverifiedError'
+  constructor() {
+    super(
+      'sandbox /proc strategy could not be verified right now: the cap-free ' +
+        'proc-bind safety probe stayed inconclusive (usually transient load on the ' +
+        'host while the container was starting up), so this bun package command ' +
+        '(bun install / bun add / bunx / bun run) was held back rather than run ' +
+        'under a broken /proc. This is almost certainly temporary and NOT a problem ' +
+        'with the command or the package: retry the SAME command in a few seconds — ' +
+        'the next attempt re-probes and normally succeeds.',
+    )
+  }
+}

package/src/sandbox/index.ts

@@ -27,7 +27,12 @@ export { resolveSandboxSymlinks, type SandboxSymlinkSpec } from './symlinks'
 export { commandNeedsRealProc, isPackageInstallCommand } from './package-install'
 export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
 export { formatCommand, shellQuote } from './quote'
-export { SandboxDegradedProcError, SandboxPolicyError, SandboxUnavailableError } from './errors'
+export {
+  SandboxDegradedProcError,
+  SandboxPolicyError,
+  SandboxProcProbeUnverifiedError,
+  SandboxUnavailableError,
+} from './errors'
 export {
   DEFAULT_SANDBOX_ENV,
   type SandboxCommandFilter,

package/src/skills/typeclaw-config/SKILL.md

@@ -16,7 +16,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 - `port` — the TCP port the websocket server binds to inside the container. The TUI on the host stage connects to this. Default `8973`. **Restart-required.**
 - `model` — a fully-qualified `<provider>/<model-id>` string. The runtime resolves this against the built-in provider registry to decide which API to call for every turn. **Live-reloadable.**
 - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
-- `plugins` — array of plugin package names loaded at server boot. **Restart-required.**
+- `plugins` — array of plugin module specifiers loaded at server boot: npm package names for published plugins, or relative paths for local plugins you are authoring. **Restart-required.**
 - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
 - `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, KakaoTalk), plus the GitHub channel (a webhook-driven adapter that watches repos and reviews PRs — see **GitHub channel** below). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
 - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated package installs — `tmux`, `gh`, `python`, `xvfb` default on (`true`); `cjkFonts` defaults to `"auto"` (resolved from host locale at start); `ffmpeg`, `cloudflared`, `claudeCode`, `codexCli` default off (`false`) — set a toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, and `codexCli` are boolean-only). Most toggles install apt packages with BuildKit cache mounts; `cloudflared`, `claudeCode`, and `codexCli` are exceptions — `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's official `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package. (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
@@ -45,7 +45,7 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
 | `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                                                                                                                                                                           |
-| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `plugins`     | no       | array of strings | Plugin module specifiers loaded at server boot: use npm package names for published plugins (for example, `typeclaw-gws-multi-account`) and relative paths only for local plugins you are authoring (for example, `./packages/my-plugin`). Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                 |
 | `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Channels and Alias** below for schema/edit mechanics; the matching behavior lives in the `typeclaw-channels` skill. **Live-reloadable.**                                                                                                                                                                                 |
 | `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers (plus the `github` webhook channel — see **GitHub channel** below). Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill; engagement behavior lives in `typeclaw-channels`. **Live-reloadable.** See **Channels and Alias** below.                                                                                                   |
 | `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                                                                                                                                                                             |

package/src/skills/typeclaw-monorepo/SKILL.md

@@ -11,10 +11,10 @@ Your agent folder is a **bun monorepo**. The root `package.json` declares `"work
 
 You have two free-write zones at the agent root: `workspace/` and `packages/`. Both are exempt from the non-workspace-write guard so you can edit them without acknowledging anything, but their relationship to git is opposite, and picking the wrong one is the most common mistake.
 
-| Zone         | Purpose                                                            | Tracked in git?                                                                                           | Reusable?                                    |
-| ------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `workspace/` | One-off scripts, scratch work, throwaway experiments               | **No** — entire dir is gitignored                                                                         | No (the dir itself is invisible to git)      |
-| `packages/`  | Reusable packages, custom plugins, shared utilities, internal libs | **Yes** — every file is tracked and MUST be committed when edited (only `*/node_modules/` ignored inside) | Yes (committed and importable across agents) |
+| Zone         | Purpose                                                                  | Tracked in git?                                                                                           | Reusable?                                    |
+| ------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `workspace/` | One-off scripts, scratch work, throwaway experiments                     | **No** — entire dir is gitignored                                                                         | No (the dir itself is invisible to git)      |
+| `packages/`  | Reusable packages, custom local plugins, shared utilities, internal libs | **Yes** — every file is tracked and MUST be committed when edited (only `*/node_modules/` ignored inside) | Yes (committed and importable across agents) |
 
 The two columns to internalize:
 
@@ -26,7 +26,7 @@ Anything you put in `packages/` MUST land in a commit — see `typeclaw-git`. Th
 **Decision rule, top to bottom — stop at the first match:**
 
 1. **Will another script or another part of the agent folder import this?** → `packages/<name>/`. Even if "another part" is just "tomorrow's me writing a sibling script", a reusable thing belongs here.
-2. **Is this a custom typeclaw plugin** (anything you'd list in `typeclaw.json`'s `plugins`)? → `packages/<plugin-name>/`. Always. Plugins are the canonical packages.
+2. **Is this a custom local typeclaw plugin you are authoring?** → `packages/<plugin-name>/`. If you are adding an existing or published plugin, keep its npm package specifier in `typeclaw.json#plugins`; do not create or guess a `./packages/...` path.
 3. **Will the user want to track this in git, see it in PRs, depend on it from a cron job?** → `packages/<name>/`.
 4. **Is this throwaway** — a one-shot data transformation, a debug script, a scratch experiment that exists for one task and dies? → `workspace/`.
 5. **Default if unsure** → `packages/<name>/`. Better to commit something reusable than to lose something useful in the gitignored void.
@@ -97,6 +97,8 @@ To depend on a workspace package from the **agent root** (e.g. so cron `exec` jo
 
 ## Custom typeclaw plugins live under `packages/`
 
+This section is only for plugins you are **authoring locally** in the agent folder. If the user asks to add/install an existing or published plugin, use the plugin's npm package specifier in `typeclaw.json#plugins` (for example, `"typeclaw-gws-multi-account"`) and do **not** fabricate a `./packages/...` path.
+
 If you are writing a typeclaw plugin (anything that uses `definePlugin` from `typeclaw/plugin`), the canonical home is `packages/<plugin-name>/`. The workflow:
 
 1. **Author**: `packages/my-plugin/index.ts` exports `definePlugin({ ... })` as default.

package/src/skills/typeclaw-plugins/SKILL.md

@@ -115,6 +115,13 @@ Without `configSchema`, `ctx.config` is `never` and any reference is a type erro
 
 The **derived name is the key** for the per-plugin config block at the top level of `typeclaw.json`. Two plugins with the same derived name are a boot error.
 
+Use the entry format that matches the plugin's source:
+
+- **Published npm plugin** → put the npm package specifier in `plugins[]`, e.g. `"typeclaw-gws-multi-account"` or `"typeclaw-plugin-standup-log@1.2.3"`. Do **not** invent a `./packages/...` path for a published package.
+- **Local plugin you are authoring in this agent folder** → put its relative path in `plugins[]`, e.g. `"./packages/my-plugin"`. The path must exist and point at local plugin code.
+
+If the user says to add/install an existing plugin by package name, preserve that package name. Only use `./packages/<name>` when you are creating or wiring a local workspace package that exists in this repo.
+
 ### Local path safety
 
 Local plugin paths **must resolve inside `agentDir`**. Absolute paths (`/etc/...`) and parent-traversing paths (`../../foo`) are rejected with:
@@ -125,9 +132,11 @@ plugin path escapes agent directory: <entry> (resolved to <abs-path>)
 
 This is why `./plugins/x.ts` works and `/Users/me/x.ts` does not.
 
-### Recommended location: `packages/<plugin-name>/`
+### Recommended location for new local plugins: `packages/<plugin-name>/`
+
+This section is about plugins you are **authoring locally**. For a published npm plugin, keep the npm package specifier in `plugins[]`; do not create or guess a local path.
 
-The agent folder is a **bun monorepo**, and `packages/` is its workspace root. **Custom plugins go there.** A `./packages/standup-log/` plugin is a real workspace package — bun installs its dependencies, the workspace symlink machinery makes it importable, and it lands in git like any other reusable code. Concretely:
+The agent folder is a **bun monorepo**, and `packages/` is its workspace root. **Custom local plugins go there.** A `./packages/standup-log/` plugin is a real workspace package — bun installs its dependencies, the workspace symlink machinery makes it importable, and it lands in git like any other reusable code. Concretely:
 
 ```
 packages/