@inetafrica/open-claudia 3.0.44 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## v3.1.1 — /logout and switch-account: re-auth is finally reachable from chat
+
+Reported live: with Claude or Codex already connected, there was **no way to sign into a different account** — `/login` showed "connected" and tapping a model just switched models, because the auth-aware picker (correctly, since v3.0.36) only starts a login flow when a provider is *not* authenticated. And `/clear_oauth_token` alone didn't help: it clears the bot-held token but the CLI credential store keeps `authStatus` reading "authenticated", so the picker still never offered a sign-in. Re-auth needs a *full* sign-out first — this release adds it.
+
+- **New `/logout [claude|codex]`** (owner-only) — a full sign-out: runs `claude auth logout` / `codex logout` against the CLI credential store **and** (for Claude) clears the bot-held OAuth token from `.env`, process env, and vault in the same step. Partial clears were exactly the trap. Reports each step honestly (including "CLI not found — store untouched"), then offers a **Sign in** button so the fresh login is one tap away. Without an argument it shows provider buttons.
+- **`/login` picker grows a 🔁 Switch account button** under each *connected* provider. Tapping it asks first — showing who is currently signed in (email where the CLI exposes it, else the auth method: OAuth token source / ChatGPT account / API key) and warning that the bot loses that provider until the new login completes — then signs out and chains straight into the fresh login flow. A stray tap can't kill a working auth: the destructive step is behind the explicit confirm.
+- **`/clear_oauth_token` is now documented as the narrow tool** (bot token only); `/logout claude` is the full story.
+- **Agent-space / OpenClaw:** new auth-flow primitives `logoutClaude`/`logoutCodex`/`providerLogout`/`canLogout`/`providerAccountSummary` (core/auth-flow.js), shared executor `performProviderLogout` + `startProviderLogin` (core/handlers.js), new callback family `sw:`/`lo:`/`losw:`/`li:` (core/actions.js, owner-gated). New test `test-logout.js` in the pretest chain.
+
+## v3.1.0 — Memory becomes required: safe-mode boot, crash-loop rescue, and /downgrade
+
+Three waves folded into one release, graduated to a minor because boot semantics change. Wave 0: the memory substrate is now **required** — a missing `node:sqlite` boots into safe mode instead of silently degrading, a boot crash loop lands there too, and a new `/downgrade` completes the rescue-from-chat story. Wave 1: the memory-substrate revival, root-caused from a live incident — a pod ran 16 days repeating corrected branding mistakes because its entire memory substrate silently never initialized. Wave 2: the first fix batch from the 2026-07-20 blind code review (18 verified findings; deeper architectural items ship in later batches).
+
+### Wave 0 — boot safety (why this is a minor)
+
+- **The memory substrate is now required, not a silent fallback.** A boot without `node:sqlite` (Node < 24) no longer quietly runs with keyword-only memory — it enters **safe mode**: adapters and diagnostic slash commands stay up, but no agent turns, crons, watches, reviewer, or memory writes run. The owner gets one loud alert explaining exactly what's missing and every way out. Running degraded is still possible, but only as an explicit choice: `MEMORY_ALLOW_DEGRADED=1` in the environment, or a one-shot `/safemode continue` from chat.
+- **A boot crash loop can no longer strand you with a dead pod.** If 3 consecutive boots die before reaching 5 minutes of stable uptime, the next boot comes up in safe mode instead of crashing a fourth time — the chat channel stays alive precisely so you can rescue it *from chat*. The alert carries the last recorded exit reason (or names it a hard kill — OOM/SIGKILL — when there is none). The counter is honest about edge cases: a clean deliberate exit (restart/upgrade) never counts as a crash, a hard kill *after* proven-stable uptime starts a fresh count, and safe mode's own stability doesn't launder the streak away — only a stable full boot, `/safemode continue`, or a deliberate version change resets it.
+- **New `/downgrade` — roll back to what ran before.** With no argument it targets the previously-running version from the new boot version history; `/downgrade <version>` picks any published release (strict semver-validated, existence-checked against the registry before anything executes). Works from safe mode, which turns a bad release into a two-command recovery: crash loop → safe mode → `/downgrade` → back online. On source-overlay pods the change is flagged as ephemeral (a pod recreate returns to the image version — roll the image for permanence). Both `/upgrade` and `/downgrade` clear the crash counter, since a deliberate version change is an operator fix attempt.
+- **`/safemode`** shows the active reasons, last exit, and ways out at any time (and reports "running normally" when not in safe mode). `/status` gains a ⛔ banner line while safe mode is active. Non-allowlisted messages in safe mode get a one-line banner pointing at `/safemode` instead of silence.
+- **`package.json` now declares `engines.node >= 24`.** npm warns at install on older runtimes; the bot itself still *boots* on them — deliberately, straight into safe mode, so an old pod becomes a diagnosable chat instead of a crash loop.
+- **Agent-space / OpenClaw (wave 0):** new module `core/safe-mode.js` (boot gate consulted at the top of `bot.js`; router gates every message/action through it); new state files under the config dir: `boot-marker.json`, `safemode-continue.json`, `version-history.json` (last 20 versions seen at boot). New commands `/downgrade`, `/safemode`; safe-mode command allowlist: help, start, version, status, doctor, requirements, restart, upgrade, downgrade, safemode, whoami, cluster. New test `test-safe-mode.js` in the pretest chain (which also now runs the previously-unwired `test-boot-health.js` and `test-lexical-floor.js`).
+
+### Wave 1 — memory-substrate revival
+
+- **Why a pod forgot everything for 16 days — and why that can never be silent again.** The pod base image ran Node 20, which has no `node:sqlite` — so pack FTS matching, the recall graph, and episodic memory all bailed out quietly at require-time. 542 turns produced zero recall seeds; three separate user corrections were reviewed and dropped; nothing anywhere said a word. `Dockerfile.base` now builds `FROM node:24-slim` (node:sqlite stable), and the CI build job tests on `node:24` to match — with the `sim-no-sqlite` shim tests keeping the degraded path covered.
+- **/doctor grew a full memory-health section.** Substrate presence (hard fail with the exact fix when node:sqlite is missing), recall-graph size, the last 24h of the recall pipeline (turns, seeded, injected, walker failures — 10+ live turns with zero seeds is a hard fail: "matching is returning NOTHING"), reviewer success rate (<50% fail, <90% warn, deferred counts, last error code), mutation-lock state (free / stale / long-held / active), deferred review batches on disk, corpus size vs the lesson cap, and disk headroom.
+- **Substrate degradation announces itself at boot.** A degraded boot sends the owner one loud alert ("⚠️ MEMORY SUBSTRATE DEGRADED … I will remember poorly until this is fixed") — deduped per capability fingerprint, re-fired every 24h while broken, cleared the moment a healthy boot is seen so a later regression alerts fresh.
+- **Every upgrade is now followed by a doctor run on the NEW process.** All three `/upgrade` paths (AgentSpace rollout, source-overlay, npm) record a marker before restarting; the next boot consumes it and sends a full doctor report back to the channel that requested the upgrade. The pre-restart report can only ever vouch for the *old* process — this closes the gap where an upgrade lands on a broken substrate and nobody notices.
+- **Recall now has a floor: no sqlite means keyword matching, never nothing.** `matchPacks`/`matchEntities` fall back to a pure-JS lexical scorer that mirrors the FTS scoring exactly (strong-field hit 2, body hit 1, same thresholds and limits, porter stemming approximated by substring + suffix-strip variants). Both recall engines get seeds through the same two matchers, so the floor fixes classic *and* discoverer with zero engine changes — proven equivalent by a parity test that runs the same assertions with and without the no-sqlite shim.
+- **The memory reviewer can no longer be starved by a stale lock.** In a container the bot is PID 1 — and after a crash, the *restarted* bot is also PID 1, so the old liveness check saw a dead incarnation's mutation lock as alive forever (one pod: 87% of reviewer runs starved with `MEMORY_MUTATION_LOCK_TIMEOUT`, feeding a 43-restart loop). Locks now carry a per-process boot id: same pid + different boot id breaks immediately, ownerless locks break after a 5s grace, and a genuinely live holder is still never broken. The reviewer also gained a seatbelt: on lock timeout it retries once after 60s, and if still starved it persists the decision batch to `pending-review-mutations.jsonl` (capped, surfaced by /doctor) and records the run as "deferred" instead of losing the memory write.
+- **LOCKED stance lines now carry rule authority.** A Stance line containing `LOCKED` (uppercase — prose "locked" stays put) is hoisted under a "BINDING CONSTRAINTS" header in every injection mode, so a frozen choice reads as a rule, not background prose. The reviewer prompt gained the matching contract: never weaken, reword, or drop a LOCKED line unless the user explicitly unlocks it, and when a reply violates one, journal the violation ("VIOLATION: …") so drift becomes visible instead of silently absorbed.
+- **Compaction stops matching memory against its own boilerplate.** The summarize meta-turn now skips recall entirely (its prompt is instructions about summarizing — matching packs against it was noise). The seed turn — which opens a fresh session and previously lost all pack context — now matches on what the work *is*: the condensed brief plus open task titles, so the packs active before compaction re-attract immediately. Lessons stay always-on, and re-attracted packs bring their LOCKED constraints back with authority.
+- **Agent-space / OpenClaw (wave 1):** base-image change `FROM node:20-slim` → `node:24-slim` (rebuild `:base` required — the CI base job triggers on the Dockerfile.base change), CI build image `node:20` → `node:24`. New modules `core/doctor-memory.js`, `core/boot-health.js`; boot wiring in `bot.js`; marker writes in the three `/upgrade` paths. New state files under the config dir: `substrate-alert.json`, `pending-doctor.json`, `pending-review-mutations.jsonl`; mutation-lock `owner.json` gains a `bootId`. New tests `test-boot-health.js`, `test-lexical-floor.js`; expanded `test-memory-mutation-queue.js`, `test-extractive-injection.js`, `test-provider-compaction.js`, `test-provider-recall.js`.
+
+### Wave 2 — blind-review fix batch
+
+- **The recall graph no longer eats its own memory.** The nightly decay pass rewrote every edge weight by reapplying the *full* age since last reinforcement — every night. That compounds: an edge on the intended 60-day half-life actually emptied in about ten nights, so long-lived Hebbian links quietly bled away and recall got worse the longer you used it. Decay is now computed **on read** (the stored weight is the value as of its `last_reinforced` stamp; every read maps through `effectiveWeight()`), reinforce/weaken settle the accrued decay before applying their delta, and the nightly rewrite path is gone entirely — the bug class can no longer exist. A one-time, idempotent migration (`recall-graph.db` PRAGMA `user_version` 0→1) treats existing weights as current and restarts the clock. The half-life is now a dream-tunable knob (`decayHalfLifeDays`, env-pinnable) read lazily, so a tuning change applies on the very next read.
+- **Keyring and tool state can no longer be destroyed by a crash mid-write.** The operational keyring, tool `state.json`/usage books, and recall tuning were bare `writeFileSync` calls — an OOM kill or power loss mid-write left a truncated, unparseable file, and for the keyring that meant every stored credential gone. All of them now go through the crash-safe writer (temp file + fsync + atomic rename, 0600). The keyring additionally snapshots the last good version to `keyring.json.bak` before each overwrite and *reads through* it transparently: a corrupt primary logs one warning per process, serves the backup, and the next successful write repairs the primary in place.
+- **When memory recall breaks, you now hear about it instead of the bot quietly getting dumber.** Recall has always been fail-open (a crashed builder must not block the turn) — but it was also fail-*silent*: the error vanished and every turn just ran memoryless. The failure now logs to the bot log, shows immediately as a "🧠 Recall FAILED this turn" banner when `/recall` is on, and after **3 consecutive** failed turns the owner gets one alert per streak ("running without pack/entity/tool context", with the last error) — quiet again until it recovers or breaks anew.
+- **"ok deploy kazee now" no longer skips memory recall.** The recall pre-gate skipped short turns that *start* with a pleasantry — an ack prefix hid a real command, so deploy/restart requests wearing an "ok"/"thanks" ran without any pack context. The gate now strips leading pleasantry tokens (stacked ones too) and tiers what remains; pure ack chains ("ok thanks sounds good") still skip at any length.
+- **A chat approval is no longer burned by a run that could never start.** `tool run --approval <id>` consumed the one-shot token *before* checking keyring credentials — a missing key meant the human's Approve was spent on nothing and they had to be asked again. The creds preflight now runs before any approval machinery (including owner escalation, which is no longer raised for unrunnable commands): the failure names the missing keys, the token survives, and the byte-identical command redeems it after `keyring set`.
+- **Tool-sequence learning now sees piped compositions.** The graph that learns "tool A is usually followed by tool B" split command lines on `&&`, `||`, `;` and newlines — but not on a single `|` or background `&`, so `tool run a … | tool run b …` credited only the first tool. It now splits on all shell composition operators, with quoted arguments masked first so a pipe inside a string doesn't split the command.
+- **Two source files no longer masquerade as binaries.** `core/recall/discoverer.js` and `core/state.js` contained raw NUL bytes inside string literals (composite-key separators), which made grep and most tooling treat the files as binary and skip them. The bytes are now written as `\u0000` escapes — byte-for-byte identical strings at runtime, plain text on disk.
+- **README caught up with reality on recall engines.** It claimed **classic** was the default and **discoverer** opt-in; the shipped default has been `discoverer` (per-chat `/engine` → `RECALL_ENGINE` env → default). The engine docs, command table, and env table now say so, and the discoverer section documents its cost profile: one small utility-model call per non-trivial turn, skipped entirely by the pre-gate on trivial turns, model pinnable via `RECALL_DISCOVERER_MODEL`.
+- **Agent-space / OpenClaw:** no new deps, no new env (all knobs pre-existed). One schema touch: the automatic, idempotent `recall-graph.db` `user_version` 0→1 restamp above; keyring writes now leave a `.bak` sibling. Changes span `core/recall/graph.js`/`tuning.js`/`discoverer.js`, `core/keyring.js`, `core/tools.js`, `core/tool-graph.js`, `core/state.js`, `core/system-prompt.js`, `core/turn-observer.js`, `core/dream.js`, `bin/tool.js`, README. Covered by new `test-turn-observer.js` (in the pretest chain) plus expanded cases in `test-recall-graph.js`, `test-recall-discoverer.js`, `test-tools.js`, `test-tool-graph.js`, `test-tool-manifest.js`, `test-provider-core-prompt.js`; full suite green. Existing pods pick it up on their next approved upgrade.
+
 ## v3.0.44 — Safety refusals explain themselves, and one refusal no longer poisons every turn after it
 
 - **A Claude safety refusal now tells you why instead of dumping a raw API error.** When the model declines a request (`stop_reason: "refusal"`), the API attaches a category and sometimes an explanation — but all you saw was "API Error … appears to violate our Usage Policy" with a request id buried inside. The refusal is now detected structurally from the stream (`stop_details` category/explanation, with a text-parse fallback when the CLI flattens it into the error string) and surfaced as a clear ⛔ diagnostic: the reason, the request ID (for support), and your options (/new, rephrase, /model or /backend).

package/README.md

@@ -15,7 +15,7 @@ Send text, voice notes, screenshots, and files from your phone. Open Claudia run
 ### Memory & long-term context
 - **Context packs** — living per-topic documents (one per project, system, or recurring task) holding Stance, Procedure, State, and Journal. Packs matching your message are auto-injected into the agent's context, and a background reviewer updates them after every substantial turn — the assistant keeps its train of thought across sessions and projects
 - **Entity memory** — short notes on the people, places, projects, orgs, and systems you mention, extracted automatically and injected when they come up again
-- **Pluggable recall** — switch per chat with `/engine`: the stable **classic** keyword engine (default) or the opt-in **discoverer**, which walks a typed-edge graph over the same packs/entities and surfaces hits with one-line why-bullets
+- **Pluggable recall** — switch per chat with `/engine`: the **discoverer** graph engine (default), which walks a typed-edge graph over your packs/entities and surfaces hits with one-line why-bullets, or the simpler **classic** keyword engine as an explicit opt-out
 - **Dream consolidation** — a nightly pass on a stronger model that merges duplicate packs, builds umbrella/parent pack trees, tightens descriptions, dedupes entities, tends the recall graph, and reports what it tidied — with everything backed up first
 - **Personality** — a persona file gives the assistant a consistent voice on top of your soul file, and the dream pass evolves it gently as you work together
 - **Transcript search** — redacted project transcripts indexed in SQLite FTS5; `open-claudia transcript-search` gives the agent ~50ms ranked recall over months of history
@@ -54,7 +54,7 @@ Send text, voice notes, screenshots, and files from your phone. Open Claudia run
 
 ## Prerequisites
 
-- [Node.js](https://nodejs.org/) 18+ (22.5+ recommended — its built-in SQLite powers transcript/pack/entity search; on older Node those features quietly disable themselves)
+- [Node.js](https://nodejs.org/) **24+** (required — its built-in SQLite powers pack/entity/transcript search and the recall graph). On older Node the bot boots into **safe mode** (diagnostic commands only) instead of running with degraded memory; set `MEMORY_ALLOW_DEGRADED=1` or send `/safemode continue` to explicitly run with keyword-only memory.
 - A Telegram bot token (from [@BotFather](https://t.me/BotFather)) and/or a Kazee Chat bot
 - At least one authenticated coding-agent provider on the host machine for model turns (setup, doctor, status, and web configuration also work with none installed)
 - (Optional) [whisper.cpp](https://github.com/ggerganov/whisper.cpp) + ffmpeg for voice notes
@@ -179,7 +179,7 @@ When you select a project, the last conversation is automatically resumed. Tap "
 |---------|-------------|
 | `/learn [<hint>]` | Capture the last piece of work into the matching context pack |
 | `/skills [show\|remove <name>]` | List, show, or remove legacy learned skills |
-| `/engine [classic\|discoverer]` | Switch the per-chat memory recall engine (default `classic`) |
+| `/engine [classic\|discoverer]` | Switch the per-chat memory recall engine (default `discoverer`) |
 | `/recall [on\|off]` | Toggle a per-turn "🧠 Recall this turn" debug line showing which packs/entities surfaced (and why, on discoverer) |
 | `/soul` | View/edit assistant identity and personality |
 | `/dreamsummary [on\|off]` | Toggle the post-dream memory summary in chat |
@@ -208,10 +208,11 @@ When you select a project, the last conversation is automatically resumed. Tap "
 | Command | Description |
 |---------|-------------|
 | `/auth_status` | Reports redacted Claude auth status and whether an OAuth token is configured |
-| `/login` | Starts a Claude login flow, sends the URL/code, accepts paste-back codes (`/auth_code <code>`, `/cancel_auth`) |
+| `/login` | Starts a Claude login flow, sends the URL/code, accepts paste-back codes (`/auth_code <code>`, `/cancel_auth`). Connected providers show a **🔁 Switch account** button that signs out and starts a fresh login |
+| `/logout [claude\|codex]` | Full sign-out: clears the CLI credential store **and** (for Claude) the bot-held OAuth token, then offers a sign-in button. Without an argument, shows provider buttons |
 | `/setup_token` | Runs `claude setup-token`; the resulting OAuth token is stored without echoing it |
 | `/use_oauth_token [<token>]` | Stores `CLAUDE_CODE_OAUTH_TOKEN` for non-interactive runs; the message is deleted when possible. Without an argument, send the token as the next message |
-| `/clear_oauth_token` | Removes the stored OAuth token |
+| `/clear_oauth_token` | Removes the stored OAuth token only (`/logout claude` for a full sign-out) |
 
 Tokens are redacted from chat output and logs.
 
@@ -230,6 +231,8 @@ Tokens are redacted from chat output and logs.
 |---------|-------------|
 | `/version` | Show current running version |
 | `/upgrade` | Upgrade to latest version and restart (includes a post-upgrade doctor summary) |
+| `/downgrade [version]` | Roll back to the previously-running version (or a specific one) |
+| `/safemode` | Show safe-mode status and ways out; `/safemode continue` boots normally despite a missing memory substrate |
 | `/restart` | Restart the bot |
 | `/dashboard` | Get a one-time login link to the web dashboard |
 | `/stop` | Cancel a running task |
@@ -256,7 +259,7 @@ Open Claudia layers three memory systems on top of provider-native sessions:
 
 **Entity memory** (`~/.open-claudia/entities/<slug>.md`) works the same way for the people, places, projects, orgs, and systems you mention — who they are, current truth, and a dated observation log. Mentioning a name injects its note.
 
-**Recall engines** — how packs and entities get matched and surfaced is pluggable per chat via `/engine` (or the `RECALL_ENGINE` env default). **classic** (the default) is keyword FTS plus a relevance judge with headline injection — stable and unchanged. **discoverer** (opt-in) adds a typed-edge graph over the same corpus (`parent`/`governed-by`/`related` edges with weights in `recall-graph.db`) and runs: a pre-gate that skips recall on trivial turns → FTS seeding → spreading activation across the graph (1–2 hops — auto-pulls cross-cutting concerns the query never named) → a walker that reads each candidate and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). Edges form structurally from pack `parent` frontmatter and `[[links]]`, and strengthen via Hebbian co-use when the agent opens packs together (📖); weights decay over time. Inspect with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`, or flip on `/recall` to watch — per turn — which packs/entities surfaced and why, right in the chat. Switch back any time with `/engine classic`.
+**Recall engines** — how packs and entities get matched and surfaced is pluggable per chat via `/engine` (or the `RECALL_ENGINE` env default). **discoverer** (the default) runs a typed-edge graph over the corpus (`parent`/`governed-by`/`related` edges with weights in `recall-graph.db`): a pre-gate that skips recall on trivial turns → FTS seeding → spreading activation across the graph (1–2 hops — auto-pulls cross-cutting concerns the query never named) → a walker that reads each candidate and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). The walker is one small utility-model call per non-trivial turn (typically fractions of a cent; pin the model with `RECALL_DISCOVERER_MODEL`, and trivial/short turns skip it entirely via the pre-gate). Edges form structurally from pack `parent` frontmatter and `[[links]]`, and strengthen via Hebbian co-use when the agent opens packs together (📖); weights decay over time. **classic** is the explicit opt-out: keyword FTS plus a relevance judge with headline injection, no graph and no walker. Inspect with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`, or flip on `/recall` to watch — per turn — which packs/entities surfaced and why, right in the chat. Switch any time with `/engine classic`.
 
 **Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, through the configured provider's high model tier): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, cross-links notes, and tends the recall graph (structural sync, weight decay, orphan prune). The pass is *evidence-grounded*: per-turn recall telemetry (what surfaced, what got kept, what the agent actually opened) feeds the prompt, so archive/merge calls rest on usage numbers rather than vibes. Most nights run as cheap *deltas* — full pack bodies only for what changed since the last dream plus graph neighbours and pre-computed merge candidates; a full-corpus sweep runs every `DREAM_FULL_SWEEP_DAYS` (30). Deterministic phases run even if the model call fails: journal backfill dedupe, weakening of graph nodes that keep arriving but never get kept, co-rescue edge reinforcement, episodic index tending, and a memory-health report (rescue rate, noise, latency, spend) in the morning chat summary. Dream may also tune one bounded recall knob per night (`recall-tuning.json`) — every change is checked against the next window's health and auto-rolled-back if rescue drops or noise rises; env pins always win. Anything merged away is backed up under `~/.open-claudia/backup/dream-<stamp>/` first, and each report and morning summary records the provider/model used. Configure with `DREAM_CRON`, `DREAM_TIER`, `DREAM_PROVIDER`, or a provider-specific `DREAM_MODEL_CLAUDE` / `DREAM_MODEL_CODEX`; disable with `DREAM=off`.
 
@@ -451,7 +454,7 @@ All stored in `~/.open-claudia/`:
 | `USAGE_ALERT_RATE_MULTIPLIER` | No | Alert when the latest context-token rate exceeds the recent baseline by this multiple (default `1.75`, `off` disables) |
 | `USAGE_ALERT_BASELINE_TURNS` / `USAGE_ALERT_MIN_BASELINE_TURNS` / `USAGE_ALERT_COOLDOWN_MS` | No | Tune token-rate baseline size, minimum sample size, and alert cooldown |
 | `MEMORY_RECALL_MAX_CHARS` | No | Hard cap for auto-injected pack/entity memory per turn (default `9000`, `off` disables auto recall injection) |
-| `RECALL_ENGINE` | No | Default recall engine when a chat hasn't set one via `/engine` (`classic` or `discoverer`, default `classic`) |
+| `RECALL_ENGINE` | No | Default recall engine when a chat hasn't set one via `/engine` (`classic` or `discoverer`, default `discoverer`) |
 | `RECALL_GRAPH_DB` / `RECALL_METRICS` | No | Override the discoverer graph DB path; `off` on metrics disables per-turn recall logging |
 | `RECALL_WALKER_MAX_CANDIDATES` | No | Cap on candidates sent to the discoverer's walker judge per turn (default `14`; dream-tunable 8–20, env pins it) |
 | `RECALL_EPISODES` / `RECALL_EPISODE_LIMIT` | No | `off` disables episodic transcript candidates in recall; limit caps transcript hits per turn (default `3`; dream-tunable 1–5) |
@@ -513,6 +516,8 @@ The bot checks npm for new versions every 5 minutes. When an update is available
 
 For direct npm installs, `/upgrade` updates Open Claudia itself and does not install optional provider CLIs such as Codex. Container deployments should roll out a new Docker image when bundled CLI tools change.
 
+If a release goes bad, `/downgrade` rolls back to the previously-running version (boot history remembers what ran before), and `/downgrade <version>` targets any published release. If the bot ever enters a boot crash loop (3 consecutive boots dying before stable uptime), it comes up in **safe mode** — adapters and diagnostic commands stay alive so you can `/doctor`, `/upgrade`, `/downgrade`, or `/safemode continue` from chat instead of being stranded with a dead process.
+
 ## Cron Jobs
 
 Schedule recurring tasks:

package/bin/tool.js

@@ -375,6 +375,21 @@ async function run(args) {
       const commandLine = approvals.formatApprovedCommand(["open-claudia", "tool", "run", t.name, ...toolArgs]);
       let approvedVia = "";
 
+      // B10: creds preflight BEFORE any approval machinery. A missing keyring
+      // key used to be discovered only after the one-shot --approval token was
+      // consumed (or an owner approval raised), burning a human decision on a
+      // run that could never start. Failing here leaves every token valid.
+      {
+        const missing = tools.missingRequires(t);
+        if (missing.length) {
+          console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
+          if (approvalId) {
+            console.error(`Approval ${approvalId} was NOT consumed — after setting the keys, re-run the exact same command with the same --approval token.`);
+          }
+          process.exitCode = 1; return;
+        }
+      }
+
       // ── Phase 3.5: per-speaker external gate ──────────────────────────────
       // When this run is FOR an external (non-owner) speaker, a write/destructive
       // tool cannot rely on the agent's own --yes flag — the external could have
@@ -486,11 +501,6 @@ async function run(args) {
         console.error(`✅ Approval ${reqId} redeemed (single use) — running.`);
       }
 
-      const missing = tools.missingRequires(t);
-      if (missing.length) {
-        console.error(`Cannot run ${t.name}: missing keyring keys ${missing.join(", ")}. Set them with 'open-claudia keyring set <name> <value>'.`);
-        process.exitCode = 1; return;
-      }
       // Fingerprint check: warn (never block) when the source changed since the
       // last verified (exit-0) run — the next green run re-verifies it.
       try {

package/bot.js

@@ -69,6 +69,18 @@ require("./core/handlers"); // side-effect: register slash commands
 
 const CURRENT_VERSION = require(path.join(__dirname, "package.json")).version;
 
+// Boot gate: decide full / degraded / safe before anything heavy initializes.
+// Consumes the exit-reason record once (reused for the Back-online greeting).
+// Safe mode (missing substrate, or a boot crash loop) keeps adapters + slash
+// commands alive so the operator can diagnose and /upgrade, /downgrade or
+// /safemode continue from chat instead of facing a dead bot.
+const safeBoot = require("./core/safe-mode");
+const lastExitInfo = require("./core/restart-reason").consumeExitReason();
+const bootMode = safeBoot.beginBoot({ exitInfo: lastExitInfo, currentVersion: CURRENT_VERSION });
+if (bootMode.mode !== "full") {
+  console.error(`Boot mode: ${bootMode.mode}${bootMode.reasons.length ? ` (${bootMode.reasons.join(", ")})` : ""}`);
+}
+
 // Register existing operational-keyring values so the redactor scrubs them
 // from any output we ship to chat. (New ones are registered on /keyring set.)
 try {
@@ -226,7 +238,33 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
 
 // ── Boot ────────────────────────────────────────────────────────────
 
+// Minimal boot: adapters + slash commands only. No scheduler/crons, no dream,
+// no connected-apps, no loopback, no web UI, no onboarding — nothing that can
+// run an agent turn or write memory. The alert tells the owner exactly why and
+// which commands still work.
+async function safeModeBoot() {
+  for (const adapter of adapters) {
+    try {
+      await adapter.start();
+      await adapter.registerCommands(publicCommands());
+      console.log(`Adapter ready (safe mode): ${adapter.id} (${adapter.type})`);
+    } catch (e) {
+      console.error(`Adapter ${adapter.id} failed to start in safe mode:`, e.message);
+    }
+  }
+  const alert = safeBoot.formatSafeModeAlert({ version: CURRENT_VERSION });
+  console.error(alert);
+  const tg = adapters.find((a) => a.type === "telegram");
+  try { if (tg && CHAT_ID) await tg.send(CHAT_ID, alert); } catch (e) {}
+  console.log(`Open Claudia v${CURRENT_VERSION} in SAFE MODE on: ${adapters.map((a) => a.id).join(", ") || "no channels"}`);
+}
+
 (async () => {
+  if (bootMode.mode === "safe") {
+    await safeModeBoot();
+    return;
+  }
+
   // Idempotent setup: ensure tools & config are in place (safe on every boot)
   try {
     const { ensureSetup, formatSetupResults } = require("./health");
@@ -311,6 +349,10 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
     }
   }
 
+  // This incarnation counts as healthy once it survives the stable window —
+  // resets the crash-loop streak the safe-mode gate counts at boot.
+  setTimeout(() => { try { safeBoot.markBootStable(); } catch (e) {} }, safeBoot.STABLE_UPTIME_MS).unref();
+
   console.log(`Open Claudia v${CURRENT_VERSION} running on: ${adapters.map((a) => a.id).join(", ")}`);
   console.log(`Runtime mode: ${runtimeMode} (single modular runtime)`);
   console.log(`Workspace: ${require("./core/config").WORKSPACE}`);
@@ -324,9 +366,9 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
   // chat_id — boot onboarding below opens the DM when outreach is needed.
   // Skipped entirely pre-onboarding: a fresh pod's first words should be
   // the onboarding greeting, not "Back online".
-  // Consume (and clear) the exit reason once, up front: a code-initiated exit
-  // recorded why; no record ⇒ an external hard restart nothing could log.
-  const exitInfo = require("./core/restart-reason").consumeExitReason();
+  // Exit reason was consumed once at the top of boot (the safe-mode gate needs
+  // it); reuse it here. No record ⇒ an external hard restart nothing could log.
+  const exitInfo = lastExitInfo;
   const reasonLine = exitInfo
     ? `\n↳ Reboot reason: ${exitInfo.reason}`
     : "\n↳ Reboot reason: external / hard restart — no code-side reason recorded (e.g. SIGKILL, OOM, host or k8s force-restart).";
@@ -338,6 +380,39 @@ setInterval(checkForUpdates, 5 * 60 * 1000);
     } catch (e) {}
   }
 
+  // Post-upgrade doctor gate + substrate degradation alert. The /upgrade
+  // pre-restart report can only see the OLD process; the marker makes the NEW
+  // one verify itself and report. Independently, a missing node:sqlite must
+  // announce itself loudly instead of silently running memory-blind.
+  try {
+    const bootHealth = require("./core/boot-health");
+    const marker = bootHealth.consumePendingDoctor();
+    let doctorReportSent = false;
+    if (marker) {
+      const { runDoctorChecks, formatDoctorReport } = require("./core/doctor");
+      const report = formatDoctorReport(runDoctorChecks());
+      const header = `Post-upgrade health check (${marker.reason || "upgrade"}), now running v${CURRENT_VERSION}:`;
+      const target = adapters.find((a) => a.type === (marker.adapterType || "telegram")) || adapters.find((a) => a.type === "telegram");
+      const channel = (target && target.type === marker.adapterType && marker.channel) || CHAT_ID;
+      try {
+        if (target && channel) {
+          const msg = `${header}\n\n${report}`;
+          await target.send(channel, msg.length > 3900 ? msg.slice(0, 3900) : msg);
+          doctorReportSent = true;
+        }
+      } catch (e) {}
+      if (!doctorReportSent) console.log(`${header}\n${report}`);
+    }
+    const alert = bootHealth.checkSubstrateAlert({ suppress: doctorReportSent });
+    if (alert) {
+      console.error(alert);
+      const tg = adapters.find((a) => a.type === "telegram");
+      try { if (tg && CHAT_ID && isOnboarded()) await tg.send(CHAT_ID, alert); } catch (e) {}
+    }
+  } catch (e) {
+    console.error("boot health check failed:", e.message);
+  }
+
   // Proactive first-boot outreach: greet an env-provisioned owner, guide them
   // through /login, then run the LLM onboarding interview once authed.
   try { await require("./core/boot-onboarding").initBootOnboarding(adapters); }

package/core/actions.js

@@ -22,6 +22,7 @@ const { finishOnboarding } = require("./onboarding");
 const {
   startSession, switchProviderState, startNewConversation,
   endCurrentSession, activeContinueOptions, applyProviderSetting,
+  performProviderLogout, startProviderLogin,
 } = require("./handlers");
 const providerRegistry = require("./providers");
 const jobs = require("./jobs");
@@ -29,6 +30,7 @@ const scheduler = require("./scheduler");
 const { sideChatCoordinator } = require("./side-chat");
 const {
   claudeProviderAuthStatus, runClaudeAuthCommand, runCodexLoginStatus, runCodexDeviceLogin,
+  canLogout, providerAccountSummary,
 } = require("./auth-flow");
 
 const REMOVED_PROVIDER_CALLBACK_MESSAGE = "This button is from an older Open Claudia release. Cursor Agent support has been removed. Open /backend to choose Claude Code or OpenAI Codex.";
@@ -350,6 +352,26 @@ async function handleAction(envelope) {
     await send(switched ? `Switched to ${beLabel}.\nModel: ${model}` : `Model: ${model}`);
     return;
   }
+  // Switch-account / sign-out / sign-in buttons (from the /login picker and
+  // /logout). sw: asks first — a stray tap must not kill a working auth.
+  if (d.startsWith("sw:") || d.startsWith("lo:") || d.startsWith("losw:") || d.startsWith("li:")) {
+    if (!isChatOwner(envelope.channelId)) return send("Owner only — provider auth is shared across users.");
+    const providerId = d.slice(d.indexOf(":") + 1);
+    if (!canLogout(providerId)) return send(`No sign-out flow for "${providerId}". Open /login again.`);
+    const label = providerId === "claude" ? "Claude" : "Codex";
+    if (d.startsWith("sw:")) {
+      const account = providerAccountSummary(providerId);
+      return send(
+        `${label} is signed in as: ${account}\n\nSign out and start a fresh sign-in? The bot loses ${label} until the new login completes.`,
+        { keyboard: { inline_keyboard: [[
+          { text: `Yes — switch ${label} account`, callback_data: `losw:${providerId}` },
+          { text: "Cancel", callback_data: "noop" },
+        ]] } },
+      );
+    }
+    if (d.startsWith("li:")) return startProviderLogin(providerId);
+    return performProviderLogout(providerId, { thenLogin: d.startsWith("losw:") });
+  }
   if (d.startsWith("m:")) {
     state.settings.model = d.slice(2) === "default" ? null : d.slice(2);
     await send(`Model: ${state.settings.model || "default"}`);

package/core/auth-flow.js

@@ -494,6 +494,69 @@ async function runCodexDeviceLogin() {
   });
 }
 
+// ── Logout / switch account ────────────────────────────────────────
+// Full sign-out clears BOTH credential sources. A partial clear is the
+// re-auth trap: authStatus stays "authenticated" via the other source, so
+// the /login picker never offers a fresh sign-in (the v3.0.36 side effect).
+
+function logoutClaude(deps = {}) {
+  const steps = [];
+  const tokenInfo = (deps.getClaudeOAuthToken || getClaudeOAuthToken)();
+  if (tokenInfo.value) {
+    (deps.clearClaudeOAuthToken || clearClaudeOAuthToken)();
+    steps.push(`Bot OAuth token cleared (${tokenInfo.source})`);
+  }
+  const binary = deps.binary !== undefined ? deps.binary : claudeExecutable();
+  if (!binary) {
+    steps.push("Claude CLI not found — CLI credential store untouched");
+    return { ok: steps.length > 1 || !!tokenInfo.value, steps };
+  }
+  const result = (deps.runCommand || runCommand)(binary, ["auth", "logout"], { env: claudeSubprocessEnv(), timeout: 15000 });
+  steps.push(result.ok ? "Claude CLI store signed out" : `Claude CLI logout: ${summarizeAuthOutput(result.output, false)}`);
+  return { ok: result.ok || !!tokenInfo.value, steps };
+}
+
+function logoutCodex(deps = {}) {
+  const binary = deps.binary !== undefined ? deps.binary : codexExecutable();
+  if (!binary) return { ok: false, steps: ["Codex CLI not found — nothing to sign out"] };
+  const result = (deps.runCommand || runCommand)(binary, ["logout"], { env: codexSubprocessEnv(), timeout: 15000 });
+  return { ok: result.ok, steps: [result.ok ? "Codex CLI store signed out" : `Codex logout: ${summarizeAuthOutput(result.output, false)}`] };
+}
+
+const PROVIDER_LOGOUTS = { claude: logoutClaude, codex: logoutCodex };
+
+function canLogout(providerId) {
+  return Object.prototype.hasOwnProperty.call(PROVIDER_LOGOUTS, providerId);
+}
+
+function providerLogout(providerId, deps = {}) {
+  const fn = PROVIDER_LOGOUTS[providerId];
+  if (!fn) return { ok: false, steps: [`No sign-out flow for provider "${providerId}"`] };
+  return fn(deps);
+}
+
+// Short "who is signed in" line for confirm prompts — best effort, only
+// what the CLI exposes.
+function providerAccountSummary(providerId) {
+  if (providerId === "claude") {
+    const tokenInfo = getClaudeOAuthToken();
+    if (tokenInfo.value) return `OAuth token (${tokenInfo.source})`;
+    const output = runClaudeAuthStatusDiagnostic();
+    const email = (String(output).match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i) || [null])[0];
+    return email || "CLI credential store";
+  }
+  if (providerId === "codex") {
+    const status = runCodexLoginStatus();
+    if (!status.ok) return "not signed in";
+    const email = (String(status.output).match(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/i) || [null])[0];
+    if (email) return email;
+    if (/chatgpt/i.test(status.output)) return "ChatGPT account";
+    if (/api key/i.test(status.output)) return "API key";
+    return "CLI credential store";
+  }
+  return "unknown";
+}
+
 module.exports = {
   CLAUDE_OAUTH_TOKEN_KEY, CLAUDE_OAUTH_VAULT_KEY,
   getClaudeOAuthToken,
@@ -527,4 +590,9 @@ module.exports = {
   sendCodexAuthStatusSummary,
   saveCodexApiKeyWithCli,
   runCodexDeviceLogin,
+  logoutClaude,
+  logoutCodex,
+  canLogout,
+  providerLogout,
+  providerAccountSummary,
 };

package/core/boot-health.js

@@ -0,0 +1,84 @@
+// Boot-time health wiring: the loud substrate-degradation alert and the
+// post-upgrade doctor gate. A node-20 pod once ran 16 days with its whole
+// memory substrate silently absent — degradation must announce itself at
+// boot, and every upgrade must be followed by a health check on the NEW
+// process (the pre-restart report in /upgrade can only see the old one).
+// bot.js does the adapter wiring; this module owns state and messages.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../config-dir");
+const { sqliteAvailable } = require("./doctor-memory");
+
+const ALERT_STATE_FILE = path.join(CONFIG_DIR, "substrate-alert.json");
+const PENDING_DOCTOR_FILE = path.join(CONFIG_DIR, "pending-doctor.json");
+const ALERT_REPEAT_MS = 24 * 60 * 60 * 1000;
+
+function capabilityFingerprint() {
+  return `node:${process.version}|sqlite:${sqliteAvailable() ? "ok" : "missing"}`;
+}
+
+// Owner-facing degradation alert, deduped: fires once per capability
+// fingerprint, re-fires if the fingerprint changes or after 24h. A healthy
+// substrate clears the state so a later regression alerts again. `suppress`
+// marks the state without returning the message (used when a full doctor
+// report was already sent this boot).
+function checkSubstrateAlert({ suppress = false, now = Date.now() } = {}) {
+  if (sqliteAvailable()) {
+    try { fs.rmSync(ALERT_STATE_FILE, { force: true }); } catch (_) {}
+    return null;
+  }
+  const fp = capabilityFingerprint();
+  try {
+    const state = JSON.parse(fs.readFileSync(ALERT_STATE_FILE, "utf-8"));
+    if (state.fingerprint === fp && now - Date.parse(state.at || 0) < ALERT_REPEAT_MS) return null;
+  } catch (_) {}
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(ALERT_STATE_FILE, JSON.stringify({ fingerprint: fp, at: new Date(now).toISOString() }), { mode: 0o600 });
+  } catch (_) {}
+  if (suppress) return null;
+  return [
+    "⚠️ MEMORY SUBSTRATE DEGRADED",
+    `This runtime (Node ${process.version}) has no node:sqlite — pack matching, the recall graph and episodic memory are OFF (lexical keyword fallback only). I will remember poorly until this is fixed.`,
+    "Fix: run on Node 24+ — for pods, roll to the node:24 base image.",
+    "/doctor has the full report.",
+  ].join("\n");
+}
+
+// Called by /upgrade (all three paths) just before the restart: the next boot
+// consumes the marker and sends a full doctor report for the NEW process.
+function recordPendingDoctor({ reason, from, to } = {}) {
+  let adapterType = null;
+  let channel = null;
+  try {
+    const context = require("./context");
+    const adapter = context.currentAdapter();
+    adapterType = adapter ? adapter.type : null;
+    channel = context.currentChannelId() || null;
+  } catch (_) {}
+  try {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(PENDING_DOCTOR_FILE, JSON.stringify({
+      reason: String(reason || "upgrade").slice(0, 160),
+      from: from || "",
+      to: to || "",
+      adapterType,
+      channel,
+      at: new Date().toISOString(),
+    }), { mode: 0o600 });
+    return true;
+  } catch (_) { return false; }
+}
+
+function consumePendingDoctor() {
+  let marker = null;
+  try { marker = JSON.parse(fs.readFileSync(PENDING_DOCTOR_FILE, "utf-8")); } catch (_) { return null; }
+  try { fs.rmSync(PENDING_DOCTOR_FILE, { force: true }); } catch (_) {}
+  return marker;
+}
+
+module.exports = {
+  ALERT_STATE_FILE, PENDING_DOCTOR_FILE,
+  capabilityFingerprint, checkSubstrateAlert, recordPendingDoctor, consumePendingDoctor,
+};