@mulmoclaude/core 5.5.0 → 5.5.1

package/assets/helps/error-recovery.md

@@ -152,6 +152,45 @@ checked**. Open the body with a line saying the answer came from this lookup and
 is awaiting maintainer review — it is a draft, not documentation. Never edit
 `bug-report-faq.md` yourself.
 
+## "Failed to authenticate" — the Claude CLI's own login expired
+
+### Symptoms
+
+- `[Error] Failed to authenticate: OAuth session expired and could not be refreshed`
+- `[Error] Failed to authenticate. API Error: 401 …` / `Invalid API key`
+- Older versions: that text shown as a normal reply, then a separate `[Error] claude exited with code 1`
+- Every turn fails the same way until the user acts — failures come in bursts, not at random
+
+### Cause
+
+The `claude` CLI that MulmoClaude spawns could not authenticate with Anthropic, so it
+exited before running anything. This is the CLI's own login (`claude login`, stored in
+`~/.claude` / the macOS Keychain), not a MulmoClaude or Google account link. An OAuth
+(subscription) session goes stale when its silent refresh fails; nothing on the
+MulmoClaude side can refresh it.
+
+### Fix
+
+The user runs `claude /login` (or `claude login`) in a terminal **on the host**, then
+resends the message. If they authenticate with `ANTHROPIC_API_KEY` instead, check that
+key. Switching auth mode is not the fix — a fresh `/login` is.
+
+If `/login` succeeds and the error persists (typically `401 OAuth access token is
+invalid`), what to check depends on the sandbox:
+
+- **Sandbox off** — the spawned CLI inherits the server's environment, so a
+  `CLAUDE_CODE_OAUTH_TOKEN` set where MulmoClaude was started (shell profile or `.env`)
+  overrides the stored login. The user unsets or replaces it and **restarts
+  MulmoClaude**; a new terminal does not change the running server.
+- **Sandbox on** — the container gets only the variables MulmoClaude passes explicitly,
+  and that token is not one of them; it authenticates from the host's mounted
+  `~/.claude`. Do not chase the environment variable here — the host login is the one
+  that counts.
+
+You will usually be reading this AFTER the user re-logged in (a failing turn never
+reaches you); answer "why did that happen" with the cause above rather than
+investigating MulmoClaude's settings.
+
 ## gh / git / SSH errors inside the sandbox
 
 ### Symptoms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/core",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "description": "Shared server-side core for MulmoClaude and MulmoTerminal \u2014 the always-shipped-together subsystems consolidated behind subpath exports so the two hosts can't drift. Server-only except the browser-safe ./artifacts, ./whisper/client, ./workspace-setup/slug, ./translation/client, ./remote-view, ./remote-host and ./plugin-vue entries. All host specifics are injected.",
   "repository": {
     "type": "git",
@@ -226,7 +226,7 @@
   "dependencies": {
     "@duckdb/node-api": "^1.5.5-r.5",
     "@mulmoclaude/common": "^1.3.0",
-    "@mulmoclaude/markdown-utils": "^3.0.0",
+    "@mulmoclaude/markdown-utils": "^3.0.1",
     "dompurify": "^3.4.15",
     "fast-xml-parser": "^5.11.1",
     "google-auth-library": "^11.1.0",