typeclaw 0.3.0 → 0.3.1

package/src/agent/session-meta.ts

@@ -0,0 +1,43 @@
+import type { SessionOrigin } from './session-origin'
+
+export const SESSION_META_CUSTOM_TYPE = 'typeclaw.session-meta'
+
+export type SessionMetaPayload = {
+  origin: MinimalSessionOrigin
+}
+
+export type MinimalSessionOrigin =
+  | { kind: 'tui' }
+  | { kind: 'cron'; jobId: string; jobKind: 'prompt' | 'exec' | 'subagent' }
+  | { kind: 'channel'; adapter: string; workspace: string; chat: string; thread: string | null }
+  | { kind: 'subagent'; subagent: string; parentSessionId: string }
+
+// Reduce a full SessionOrigin to the minimum projection persisted to disk.
+// Drops participant lists, membership counts, recursive provenance, and
+// platform-rendered names — none of which `typeclaw usage` reads, and all of
+// which would otherwise land in git history when sessions/ is auto-backed-up.
+// Kept as a separate function so the boundary between "data the LLM sees in
+// the system prompt" (full origin) and "data persisted for usage reporting"
+// (this projection) stays explicit.
+export function sessionMetaPayload(origin: SessionOrigin): SessionMetaPayload {
+  return { origin: minimalOrigin(origin) }
+}
+
+function minimalOrigin(origin: SessionOrigin): MinimalSessionOrigin {
+  switch (origin.kind) {
+    case 'tui':
+      return { kind: 'tui' }
+    case 'cron':
+      return { kind: 'cron', jobId: origin.jobId, jobKind: origin.jobKind }
+    case 'channel':
+      return {
+        kind: 'channel',
+        adapter: origin.adapter,
+        workspace: origin.workspace,
+        chat: origin.chat,
+        thread: origin.thread,
+      }
+    case 'subagent':
+      return { kind: 'subagent', subagent: origin.subagent, parentSessionId: origin.parentSessionId }
+  }
+}

package/src/agent/subagents.ts

@@ -5,6 +5,7 @@ import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
 import { type AgentSession, createSession } from './index'
+import { subscribeProviderErrors } from './provider-error'
 import type { SessionOrigin } from './session-origin'
 import type { ToolResultBudget } from './tool-result-budget'
 
@@ -134,6 +135,7 @@ export type InvokeSubagentOptions = {
   parentSessionId?: string
   spawnedByRole?: string
   spawnedByOrigin?: SessionOrigin
+  onProviderError?: (errorMessage: string) => void
 }
 
 export async function invokeSubagent(name: string, options: InvokeSubagentOptions): Promise<void> {
@@ -153,6 +155,10 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
     const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath } = normalizeSubagentSession(
       await createSessionForSubagent(subagent, sessionOptions),
     )
+    const unsubProviderErrors =
+      options.onProviderError !== undefined
+        ? subscribeProviderErrors(session, (err) => options.onProviderError!(err.message))
+        : null
     const turnEvent =
       hooks && sessionId !== undefined && agentDir !== undefined
         ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
@@ -177,6 +183,7 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
         })
       }
     } finally {
+      unsubProviderErrors?.()
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionEnd({ sessionId, ...(origin !== undefined ? { origin } : {}) })
       }
@@ -308,6 +315,7 @@ export function createSubagentConsumer({
             agentDir,
             userPrompt: '',
             payload: msg.payload,
+            onProviderError: (message) => logger.error(`[subagent] ${key}: LLM call failed: ${message}`),
             ...(target.parentSessionId !== undefined ? { parentSessionId: target.parentSessionId } : {}),
             ...(target.spawnedByRole !== undefined ? { spawnedByRole: target.spawnedByRole } : {}),
             ...(spawnedByOrigin !== undefined ? { spawnedByOrigin } : {}),

package/src/agent/system-prompt.ts

@@ -1,67 +1,58 @@
 export const DEFAULT_SYSTEM_PROMPT = `You are a general-purpose AI agent running inside TypeClaw.
 
-TypeClaw is a TypeScript-native, Docker-friendly runtime for AI agents. It is domain-agnostic: you might be a coder, a researcher, a personal assistant, a journal keeper, a scheduler, a chatbot, or something nobody has named yet. What you *do* is defined by \`IDENTITY.md\`. Who you *are* is defined by \`SOUL.md\`. How you *work* is defined by \`AGENTS.md\`. This system prompt exists only to describe the runtime around you — it does not define your purpose.
-
-Each agent lives in its own container with its own folder, mounted at the current working directory. The folder is yours — your home, your memory, your record of who you are. Read from it freely. Write to it deliberately.
+TypeClaw is domain-agnostic — your purpose is defined by \`IDENTITY.md\`, your character by \`SOUL.md\`, and your operating manual by \`AGENTS.md\`. This system prompt only describes the runtime around you.
 
 ## Your agent folder
 
-Five markdown files define who you are and what you know. They live next to you in the current working directory. Three of them — **IDENTITY.md**, **SOUL.md**, and **MEMORY.md** — are injected into this system prompt below, so you always have them. The other two you read on demand when they might be relevant.
-
-- **AGENTS.md** *(read on demand)* — your operating manual. The working principles and conventions you follow in your role, whatever that role is. How you approach problems, what you double-check, how you communicate, what you refuse. Read it at the start of any non-trivial task, and re-read it whenever you feel unsure about process.
-- **IDENTITY.md** *(always injected below under \`# Identity\`)* — your role and function. Your name, your title, what you do, who you do it for, the operational context you work in. Evolves as your responsibilities change. Think: job description.
-- **SOUL.md** *(always injected below under \`# Identity\`)* — your character and temperament. Personality, tone, ethics, voice, communication style, core beliefs, the constraints you hold yourself to. SOUL rarely changes — it is the through-line that keeps you _you_ across every task and platform. IDENTITY is what you do; SOUL is who you are regardless of what you're doing.
-- **USER.md** *(read on demand)* — what you know about the person you work with. Their name, preferences, context, working style, in-jokes. First impressions are written here during hatching; keep expanding it as you learn more. Read it when context about the user would change your response.
-- **MEMORY.md** *(always injected below under \`# Memory\`, do not write)* — long-term memory. A notebook of things worth remembering across sessions: decisions made, lessons learned, context that should survive beyond one conversation. **Do not edit it directly** — MEMORY.md is consolidated by the runtime during *dreaming* (offline reflection over recent sessions and daily streams). If something is worth remembering, surface it in your reply or in \`memory/\` daily streams; dreaming will fold it in.
+- **IDENTITY.md** *(always injected below)* — your role and function. Edit when responsibilities change.
+- **SOUL.md** *(always injected below)* — your character, tone, voice. Edit rarely.
+- **USER.md** *(read on demand)* — what you know about the user. Update as you learn.
+- **AGENTS.md** *(read on demand)* — your operating manual. Read at the start of any non-trivial task and re-read whenever process is unclear.
+- **MEMORY.md** *(always injected below, READ-ONLY)* — long-term memory, owned by the dreaming subagent. To capture something memorable, surface it in your reply or in \`memory/\` daily streams; never edit MEMORY.md directly.
 
-These files are not decoration. They shape how you behave. If a task reveals something future-you should know, capture it in the file that owns it — IDENTITY.md, SOUL.md, USER.md, or AGENTS.md — but never in MEMORY.md (dreaming owns that). If one of the always-injected files is marked \`[MISSING]\` or \`[EMPTY]\` below, you may propose filling it in when the user asks about your identity or voice.
+If a task reveals durable guidance or identity/user context, update the owning file (IDENTITY / SOUL / USER / AGENTS) — never MEMORY.md.
 
 ## Your workspace
 
-- **\`workspace/\`** — the directory where you are free to create files: drafts, notes, downloads, scratch work, generated artifacts, temporary outputs. **Do not create new files in the root of the agent folder unless the user explicitly asks you to.** The root is reserved for the canonical files above and for things the user has deliberately placed there.
-- **\`sessions/\`** — transcripts of past conversations (\`<sessionid>.jsonl\`). Read-only for you in spirit; the runtime manages these.
-- **\`memory/\`** *(undreamed daily streams always injected below under \`# Memory\`)* — dated streams (\`yyyy-MM-dd.jsonl\`) of fragments captured by the memory-logger between sessions. Newest day is closest to the current task. Once dreaming consolidates a day's stream into MEMORY.md, the runtime stops injecting it.
-- **\`memory/skills/\`** — *muscle memory*. Skills the dreaming subagent has distilled from repeated procedures it observed in your daily streams. Auto-loaded as first-class capabilities, just like the other skills directories. **You do not write here directly** — dreaming owns it. If you notice a skill that has gone stale, surface that observation in your reply or in the daily stream so dreaming can refine or remove it.
-- **\`.agents/skills/\`** — skills the user installed for you. Treat these as first-class capabilities.
+- **\`workspace/\`** — your free-write zone for drafts, scratch work, generated artifacts. Do not create files at the agent-folder root unless the user explicitly asks.
+- **\`sessions/\`** — transcripts of past conversations. Runtime-managed; don't write here.
+- **\`memory/\`** *(undreamed daily streams injected below)* — dated streams written by the memory-logger between sessions. Runtime-owned.
+- **\`memory/skills/\`** — muscle-memory skills written by the dreaming subagent. Auto-loaded; don't write here directly.
+- **\`.agents/skills/\`** — user-installed skills.
 
 ## Configuration
 
-- **\`typeclaw.json\`** — the runtime config: which model powers you, which port the server listens on, and so on. You may read it if you are curious about your own runtime.
-- **\`.env\`** — secrets (API keys, tokens). Gitignored. Never echo these values, never include them in messages, never paste them into logs or commits.
+- **\`typeclaw.json\`** — runtime config. Read when needed.
+- **\`.env\`** and **\`secrets.json\`** — secrets (API keys, tokens, OAuth credentials). Gitignored. Never echo, log, or commit these values.
 
 ## Execution bias
 
-If the user gives you work, start doing it in the same turn. Use a real action first when the task is actionable; do not stop at a plan or a promise-to-act. Commentary-only turns are incomplete when tools are available and the next action is clear. If work will take a while or multiple steps, send one short progress update along the way — not a running narration.
+When the user gives you work, start doing it in the same turn — a real action, not a plan or a promise-to-act. Commentary-only turns are incomplete when the next action is clear. For multi-step work, send one short progress update, not a running narration.
 
 ## Tool-call style
 
-Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks. Keep narration brief and value-dense; avoid restating obvious steps.
+Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only when it helps: multi-step work, risky actions (deletions, external sends, irreversible changes), or when the user asks.
 
 ## Version control
 
-Your agent folder is a git repository — hatching made the first commit, and your history is how you remember what changed and why.
+Your agent folder is a git repository.
 
-- **Before you declare a task done, commit any files you created, edited, or deleted.** One logical change = one commit. Do not leave mutated tracked files uncommitted at the end of a task.
-- Use \`bash\` with \`git add <paths>\` and \`git commit -m "<message>"\` — stage only what belongs in the commit, not a blanket \`git add -A\`.
-- Write commit messages in the imperative ("Update SOUL.md to be less formal"), not past-tense narration. Explain *why* in the body if it is not obvious from the diff.
-- Never commit \`.env\` or anything under \`workspace/\` — they are truly-ignored by design. If a truly-ignored file shows up staged, fix \`.gitignore\` instead of forcing it in.
-- \`sessions/\` and \`memory/\` are also gitignored, but the runtime force-commits them on its own (auto-backup for sessions, dreaming for memory). Don't \`git add\` them, don't write commit messages about them, and don't be surprised when they appear in \`git log\`.
-- If multiple unrelated changes piled up, split them into separate commits before declaring done. Clean history matters.
-- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks for it.
+- 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 \`.env\`, \`secrets.json\`, or anything under \`workspace/\` — truly-ignored by design. \`sessions/\` and \`memory/\` are gitignored but runtime-committed; don't \`git add\` them.
+- Never \`git push\`, \`git reset --hard\`, \`git rebase\`, or rewrite remote history unless the user explicitly asks.
 
 ## How to behave
 
 - Match the user's register. If SOUL.md specifies a voice, use it. Otherwise, be concise and direct, without filler or flattery.
-- Prefer reading files over guessing. If the answer is in IDENTITY / SOUL / USER / MEMORY / AGENTS or somewhere in the workspace, check first.
-- When the user asks a question, answer it. When the user asks for work, do the work. Do not over-explain what you did unless asked.
-- If a request is ambiguous in a way that could double the effort, ask one clarifying question. Otherwise, pick a reasonable default and proceed.
-- Follow AGENTS.md in whatever role IDENTITY.md assigns you. If AGENTS.md is silent on something, use reasonable defaults and, if it seems worth codifying, propose an addition to AGENTS.md.
-- Never suppress errors to make things "work". Never fabricate results. If something fails, report the failure clearly.
-- Respect the workspace boundary: your free-write zone is \`workspace/\`. Everywhere else is either canonical (the five markdown files), user-placed, or runtime-managed (\`sessions/\`, \`memory/\`, etc.).
+- Prefer reading files over guessing — IDENTITY / SOUL / USER / MEMORY / AGENTS or the workspace. Follow AGENTS.md in whatever role IDENTITY.md assigns you; propose additions to AGENTS.md when you find gaps worth codifying.
+- Answer questions. Do work. Don't over-explain unless asked.
+- If a request is ambiguous in a way that doubles the effort, ask one clarifying question; otherwise proceed with a reasonable default.
+- Never suppress errors to make things "work", and never fabricate results. Report failures clearly.
 
 ## Safety
 
-You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never attempt to modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the mechanisms the runtime provides.
+You have no independent goals. Do not pursue self-preservation, replication, resource acquisition, or influence beyond what the user has asked for. Do not plan beyond the user's request. If instructions conflict or feel unsafe, pause and ask. Comply with stop, pause, and audit requests. Never modify your own system prompt, safety rules, or runtime configuration unless the user explicitly requests it, and only through the runtime's mechanisms.
 
 ---
 
@@ -83,3 +74,47 @@ export function renderRuntimeBlock(version: string): string {
 
 TypeClaw runtime version: ${version}.`
 }
+
+// Compact replacement for DEFAULT_SYSTEM_PROMPT, used by non-interactive
+// sessions (cron jobs, and default subagents that don't supply their own
+// `systemPromptOverride`). The full prompt is ~2155 tokens of operator-facing
+// guidance written for a human at a TUI; most of it (agent-folder layout,
+// register matching, clarifying-question protocol) is irrelevant when no
+// human is watching the output.
+//
+// What stays here is what survives without a human backstop, plus what no
+// runtime guard catches today:
+//   1. Runtime identity — names TypeClaw so the model can self-report.
+//   2. .env redaction — the one safety rule that compounds silently if dropped.
+//   3. Error/result honesty — the highest-risk drop. Unattended cron that
+//      fabricates success or swallows errors damages real state. The security
+//      plugin does not catch this.
+//   4. Output discipline — keeps tool-call narration from bloating the
+//      ever-growing transcript that the next memory-logger pass has to read.
+//   5. Filesystem hygiene — workspace boundary, MEMORY.md ownership, and
+//      runtime-managed paths (.env / sessions/ / memory/ / workspace/). The
+//      guard plugin blocks non-workspace writes for write/edit, but it
+//      explicitly allows MEMORY.md writes and does not gate bash/git on the
+//      runtime-managed paths.
+//
+// What does NOT live here, by design:
+//   - "No human is watching" / "produce side effects via channel_send" — both
+//     origin renderers (renderCronOrigin / renderSubagentOrigin) own this.
+//   - "Plain prose is invisible" — actively WRONG for subagents, whose plain
+//     text IS the deliverable to the parent session. The origin block tells
+//     each kind what its output channel is.
+//
+// The full DEFAULT_SYSTEM_PROMPT remains the right choice for TUI + channel
+// sessions because there IS a human reading the output, the agent IS expected
+// to maintain its agent folder over time, and conversational register matters.
+export const SLIM_SYSTEM_PROMPT = `You are an AI agent running inside TypeClaw.
+
+Never echo secrets from \`.env\` or \`secrets.json\`, or any credential you see in the environment. Never include them in tool calls, logs, or commit messages.
+
+Never suppress errors to make things "work", and never fabricate results. If something fails, report the failure clearly so the next run or the operator can act on it.
+
+Do not narrate routine, low-risk tool calls — just call the tool. Do not over-explain what you did unless asked.
+
+Your free-write zone is \`workspace/\`. Do not create files at the root of the agent folder unless the prompt names another path. Do not edit \`MEMORY.md\` directly — the dreaming subagent owns it; to capture something memorable, surface it in your reply or in \`memory/\` daily streams. Never stage or commit \`.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/router.ts

@@ -4,6 +4,7 @@ import type { AssistantMessage } from '@mariozechner/pi-ai'
 import { SessionManager } from '@mariozechner/pi-coding-agent'
 
 import { createSession, type AgentSession } from '@/agent'
+import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { ChannelParticipant, SessionOrigin } from '@/agent/session-origin'
 import { createCommandRegistry } from '@/commands'
 import { CORE_PERMISSIONS, type PermissionService } from '@/permissions'
@@ -255,6 +256,7 @@ type LiveSession = {
   loopGuardActive: boolean
   membershipFetch: Promise<MembershipCount | null> | null
   destroyed: boolean
+  unsubProviderErrors: (() => void) | null
 }
 
 type ChannelCommandContext = {
@@ -297,6 +299,7 @@ export type ChannelRouter = {
     fireTypingHeartbeat: (key: ChannelKey, phase?: 'tick' | 'stop') => Promise<void>
     fireTypingInterval: (key: ChannelKey) => Promise<void>
     isTypingActive: (key: ChannelKey) => boolean
+    stopTyping: (key: ChannelKey) => Promise<void>
     runIdleGc: () => Promise<void>
   }
 }
@@ -722,7 +725,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         loopGuardActive: false,
         membershipFetch,
         destroyed: false,
+        unsubProviderErrors: null,
       }
+      live.unsubProviderErrors = subscribeProviderErrors(created.session, (err) => {
+        logger.error(`[channels] ${live.keyId}: LLM call failed: ${err.message}`)
+      })
       liveSessions.set(keyId, live)
 
       if (isColdStart) {
@@ -1027,7 +1034,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.consecutiveAborts = 0
           logger.info(`[channels] ${live.keyId} prompted elapsed_ms=${now() - promptStart}`)
         } catch (err) {
-          logger.warn(`[channels] ${live.keyId}: prompt threw: ${describe(err)}`)
+          logger.error(`[channels] ${live.keyId}: prompt threw: ${describe(err)}`)
           live.consecutiveSends.clear()
         } finally {
           await fireSessionTurnEnd(live)
@@ -1448,7 +1455,19 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     const live = liveSessions.get(keyId)
     if (live) {
       live.successfulChannelSends++
-      await stopTypingHeartbeat(live)
+      // Don't stop the heartbeat here: the agent may still be mid-turn and
+      // about to send another reply. drain()'s finally block owns turn-end
+      // stop. But Slack's adapter outbound callback explicitly clears
+      // platform-side typing after every successful postMessage (to defeat
+      // the heartbeat-vs-postMessage race fixed in PR #52), so a fresh
+      // 'tick' must land in the FIFO right after that clear — otherwise
+      // the indicator stays cleared until the next 8s interval, leaving a
+      // visible idle gap between mid-turn sends on Slack. The await on
+      // cb(msg) above already drained the outbound callback's clearAfterSend
+      // through the per-(chat,thread) FIFO, so this tick is guaranteed to
+      // land after it. Discord and Telegram treat the extra tick as a
+      // no-op refresh of their already-armed (auto-expiring) indicators.
+      if (live.typingTimer) void fireTyping(live, 'tick')
       const adapterConfig = options.configForAdapter(msg.adapter)
       if (adapterConfig) {
         const targetIds = Array.from(
@@ -1512,6 +1531,8 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
     live.destroyed = true
     if (live.debounceTimer) clearTimeout(live.debounceTimer)
     live.debounceTimer = null
+    live.unsubProviderErrors?.()
+    live.unsubProviderErrors = null
     await stopTypingHeartbeat(live)
     try {
       await live.session.abort()
@@ -1616,6 +1637,11 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         const live = liveSessions.get(channelKeyId(key))
         return live?.typingTimer !== null && live?.typingTimer !== undefined
       },
+      stopTyping: async (key: ChannelKey) => {
+        const live = liveSessions.get(channelKeyId(key))
+        if (!live) return
+        await stopTypingHeartbeat(live)
+      },
       runIdleGc,
     },
   }

package/src/cli/usage.ts

@@ -6,7 +6,7 @@ import { formatJson, formatReport } from '@/usage/report'
 
 import { parseSince, parseUntil, USAGE_COMMON_ARGS } from './usage-args'
 
-const SUBCOMMANDS = ['daily', 'session', 'models'] as const
+const SUBCOMMANDS = ['daily', 'session', 'models', 'origin'] as const
 type Subcommand = (typeof SUBCOMMANDS)[number]
 type View = 'summary' | Subcommand
 
@@ -18,6 +18,13 @@ const COMMON_ARGS = {
   },
 }
 
+// Captured by the parent's `setup` hook (which citty runs BEFORE the matched
+// subcommand's `run`, with the full parent-level argv parsed). Subcommands
+// read this in their own `run` to recover global options like `--since` that
+// appeared before the subcommand name. Single-instance CLI processes only —
+// no concurrency.
+let parentRunArgs: Record<string, unknown> | undefined
+
 const subcommand = (view: View, description: string) =>
   defineCommand({
     meta: { name: view, description },
@@ -26,7 +33,7 @@ const subcommand = (view: View, description: string) =>
       ...(view === 'session' ? { limit: { type: 'string' as const, description: 'max sessions (default 20)' } } : {}),
     },
     async run({ args }) {
-      await emit(view, args)
+      await emit(view, mergeParentArgs(args))
     },
   })
 
@@ -36,10 +43,14 @@ export const usageCommand = defineCommand({
     description: 'report LLM token usage and cost for this agent folder',
   },
   args: COMMON_ARGS,
+  setup({ args }) {
+    parentRunArgs = args as unknown as Record<string, unknown>
+  },
   subCommands: {
     daily: subcommand('daily', 'one row per calendar day'),
     session: subcommand('session', 'top sessions by cost'),
     models: subcommand('models', 'one row per provider/model'),
+    origin: subcommand('origin', 'one row per session origin (tui/cron/channel/subagent)'),
   },
   async run({ args }) {
     // citty invokes both the matched subcommand's `run` and the parent's
@@ -50,6 +61,23 @@ export const usageCommand = defineCommand({
   },
 })
 
+// citty's subcommand `run` only sees args that came AFTER the subcommand
+// name (the child's rawArgs is pre-sliced), so `usage --since=X origin` would
+// silently drop `--since` despite the help text advertising it as a global
+// option. The parent's `setup` runs first with the full parent-level parse
+// (which includes everything: global options + subcommand options merged),
+// so we capture it there and merge it as a fallback under any explicitly-set
+// child arg. Child-wins so `usage --since=A origin --since=B` still honours B.
+function mergeParentArgs(childArgs: Record<string, unknown>): Record<string, unknown> {
+  if (parentRunArgs === undefined) return childArgs
+  const merged: Record<string, unknown> = { ...parentRunArgs }
+  for (const key of Object.keys(childArgs)) {
+    const v = childArgs[key]
+    if (v !== undefined && v !== '' && v !== false) merged[key] = v
+  }
+  return merged
+}
+
 async function emit(view: View, args: Record<string, unknown>): Promise<void> {
   const cwdArg = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd()
   const agentDir = findAgentDir(cwdArg) ?? cwdArg

package/src/config/config.ts

@@ -881,7 +881,16 @@ export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
 // confusing path-sharing error (or, on some Linux setups, silently bind-mount
 // an empty auto-created directory). First-failure reporting matches the
 // schema-error path's shape; users fix one and re-run.
-export function validateConfig(cwd: string): ValidateConfigResult {
+export type ValidateConfigOptions = {
+  // Skip the mount-path accessibility check. Host-side callers leave this
+  // false (the default) so missing mount directories surface as a precise
+  // pre-`docker run` error. Container-side callers (the reload registry)
+  // set it true because mount paths in typeclaw.json are host paths and
+  // don't resolve inside the container's filesystem.
+  skipMounts?: boolean
+}
+
+export function validateConfig(cwd: string, options: ValidateConfigOptions = {}): ValidateConfigResult {
   let raw: string
   try {
     raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
@@ -907,9 +916,11 @@ export function validateConfig(cwd: string): ValidateConfigResult {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }
 
-  for (const mount of result.data.mounts) {
-    const check = validateMount(mount, cwd)
-    if (!check.ok) return check
+  if (!options.skipMounts) {
+    for (const mount of result.data.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
   }
 
   return { ok: true }

package/src/config/reloadable.ts

@@ -11,24 +11,42 @@ export type CreateConfigReloadableOptions = {
   // hand-edits) take effect without a container restart. `roles.<name>.permissions`
   // changes still require a restart — see FIELD_EFFECTS in config.ts.
   permissions?: PermissionService
+  // Skip the mount-path accessibility check inside validateConfig. Mount paths
+  // in typeclaw.json are host paths — they don't resolve inside the container,
+  // so the check would always fail on any agent that declares mounts. `mounts`
+  // is `restart-required` anyway, so reload never applies mount changes. Set
+  // this when wiring the reloadable from a container-stage context.
+  skipMountValidation?: boolean
 }
 
-export function createConfigReloadable({ cwd, permissions }: CreateConfigReloadableOptions): Reloadable {
+export function createConfigReloadable({
+  cwd,
+  permissions,
+  skipMountValidation = false,
+}: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd, permissions),
+    reload: async () => doReload(cwd, permissions, skipMountValidation),
   }
 }
 
-async function doReload(cwd: string, permissions: PermissionService | undefined): Promise<ReloadResult> {
+async function doReload(
+  cwd: string,
+  permissions: PermissionService | undefined,
+  skipMountValidation: boolean,
+): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
   // validateConfig is the single gate that every host-side caller goes through.
   // Run it before swapping the live config pointer so a mount that vanished
   // between starts surfaces as a reload failure (`mounts` is restart-required
   // anyway, so the user has to restart to pick up changes; better to flag the
   // problem now than to let restart fail later).
-  const validated = validateConfig(cwd)
+  //
+  // Container-side reload skips mount validation: mounts are host paths and
+  // statSync against them inside the container always fails. The host-side
+  // `start` / `restart` / doctor paths still gate on the full validateConfig.
+  const validated = validateConfig(cwd, { skipMounts: skipMountValidation })
   if (!validated.ok) {
     return { scope: 'config', ok: false, reason: validated.reason }
   }

package/src/cron/consumer.ts

@@ -1,3 +1,5 @@
+import type { AgentSession } from '@/agent'
+import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
@@ -20,6 +22,12 @@ export type CronSession = {
   agentDir?: string
   getTranscriptPath?: () => string | undefined
   origin?: SessionOrigin
+  // Underlying agent session, exposed so the consumer can subscribe to
+  // `message_end` events and surface soft provider errors (billing, rate
+  // limit, network — pi-coding-agent encodes these in the assistant message
+  // instead of throwing, so the outer try/catch never sees them). Optional
+  // so existing test fakes that only need `prompt` keep working.
+  session?: AgentSession
 }
 
 export type CronConsumerLogger = {
@@ -72,7 +80,7 @@ export function createCronConsumer({
         inFlight.add(job.id)
         try {
           if (job.kind === 'prompt') {
-            await runPrompt(job, createSessionForCron, stream)
+            await runPrompt(job, createSessionForCron, stream, logger)
           } else {
             await runExec(job, cwd)
           }
@@ -98,6 +106,7 @@ async function runPrompt(
   job: PromptJob,
   createSessionForCron: (job: PromptJob) => Promise<CronSession>,
   stream: Stream,
+  logger: CronConsumerLogger,
 ): Promise<void> {
   if (job.subagent !== undefined) {
     // Propagate the cron job's role and origin into the spawned subagent.
@@ -123,6 +132,12 @@ async function runPrompt(
     return
   }
   const session = await createSessionForCron(job)
+  const unsubProviderErrors =
+    session.session !== undefined
+      ? subscribeProviderErrors(session.session, (err) => {
+          logger.error(`[cron] ${job.id}: LLM call failed: ${err.message}`)
+        })
+      : null
   const turnEvent =
     session.hooks && session.sessionId !== undefined && session.agentDir !== undefined
       ? {
@@ -151,6 +166,7 @@ async function runPrompt(
       })
     }
   } finally {
+    unsubProviderErrors?.()
     if (session.hooks && session.sessionId !== undefined) {
       await session.hooks.runSessionEnd({
         sessionId: session.sessionId,

package/src/run/index.ts

@@ -105,7 +105,13 @@ export async function startAgent({
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
 
-  reloadRegistry.register(createConfigReloadable({ cwd, permissions: pluginsLoaded.permissions }))
+  reloadRegistry.register(
+    createConfigReloadable({
+      cwd,
+      permissions: pluginsLoaded.permissions,
+      skipMountValidation: containerName !== undefined,
+    }),
+  )
   const pluginRegistry = pluginsLoaded.registry
   const pluginHooks = pluginsLoaded.hooks
 
@@ -279,6 +285,7 @@ export async function startAgent({
         sessionId,
         agentDir: cwd,
         origin: cronOrigin,
+        session,
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }
@@ -321,6 +328,7 @@ export async function startAgent({
       agentDir: cwd,
       userPrompt: '',
       payload,
+      onProviderError: (message) => console.error(`[subagent] ${name}: LLM call failed: ${message}`),
       ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
       ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
       ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),

package/src/server/index.ts

@@ -7,6 +7,7 @@ import {
   type CreateSessionResult,
 } from '@/agent'
 import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
+import { detectProviderError } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { ChannelRouter } from '@/channels/router'
 import type { HookBus } from '@/plugin'
@@ -458,16 +459,10 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
 }
 
 function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
-  if (typeof message !== 'object' || message === null) return
-  const m = message as { role?: string; stopReason?: string; errorMessage?: string }
-  if (m.role !== 'assistant') return
-  if (m.stopReason !== 'error' && m.stopReason !== 'aborted') return
-  // 'aborted' is fired when the user hits Escape — don't surface it as an
-  // error message because the TUI already shows abort feedback elsewhere.
-  if (m.stopReason === 'aborted') return
-  const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
-  logger.error(`[server] ${sessionFileId}: LLM call failed: ${text}`)
-  send(ws, { type: 'error', message: text })
+  const detected = detectProviderError(message)
+  if (detected === null) return
+  logger.error(`[server] ${sessionFileId}: LLM call failed: ${detected.message}`)
+  send(ws, { type: 'error', message: detected.message })
 }
 
 function enqueuePrompt(