discoclaw 0.5.8 → 0.7.0

package/.context/README.md

@@ -21,11 +21,12 @@ Core instructions live in `CLAUDE.md` at the repo root.
 | **Voice system (STT/TTS, audio pipeline, actions)** | `voice.md` |
 | **Forge/plan standing constraints** | `project.md` *(auto-loaded by forge)* |
 | **Plan & Forge commands** | `plan-and-forge.md` *(in docs/, not .context/)* |
+| **Engineering lessons / compound learnings** | `docs/compound-lessons.md` *(single checked-in durable artifact; lives in `docs/`, not `.context/`; human/developer reference, not auto-loaded into agent context)* |
 
 ## Context Hygiene (Strict)
 - Read the minimum necessary modules for the task.
 - Do not load modules "just in case."
-- Some reference docs live in `docs/` rather than `.context/` — these are human/developer references and are **not** auto-loaded into agent context. The `.context/project.md` file remains the only `.context` module for plan/forge constraints.
+- Some reference docs live in `docs/` rather than `.context/` — these are human/developer references and are **not** auto-loaded into agent context. The `.context/project.md` file remains the only `.context` module for plan/forge constraints, and `docs/compound-lessons.md` remains the single checked-in artifact for distilled engineering lessons.
 
 ## Quick Reference
 - **pa.md** — PA behavioral rules, Discord formatting, memory, group chat etiquette, autonomy tiers
@@ -42,3 +43,4 @@ Core instructions live in `CLAUDE.md` at the repo root.
 - **voice.md** — Voice subsystem: module map, audio data flow, key patterns (barge-in, allowlist gating), wiring sequence, dependencies, config reference
 - **project.md** — Standing constraints auto-loaded by forge drafter and auditor
 - **docs/plan-and-forge.md** — Canonical reference for `!plan` and `!forge` commands (lives in `docs/`, not `.context/` — human/developer reference, not auto-loaded into agent context)
+- **docs/compound-lessons.md** — Single checked-in durable artifact for distilled engineering lessons from audits, forge runs, and repeated workflow failures

package/.context/dev.md

@@ -79,12 +79,12 @@ Two setup paths:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PRIMARY_RUNTIME` | `claude` | Runtime engine (`claude`, `openai`, `openrouter`, `gemini`, `codex`) |
-| `RUNTIME_MODEL` | `capable` | Model tier (`fast`, `capable`) or concrete model name passed to the CLI |
+| `RUNTIME_MODEL` | `capable` | **Deprecated — use `models.json` instead.** Model tier (`fast`, `capable`) or concrete model name passed to the CLI |
 | `RUNTIME_TOOLS` | `Bash,Read,Write,Edit,Glob,Grep,WebSearch,WebFetch` | Comma-separated tool list |
 | `RUNTIME_TIMEOUT_MS` | `1800000` | Per-invocation timeout in milliseconds |
 | `RUNTIME_FALLBACK_MODEL` | *(unset)* | Auto-fallback model when primary is overloaded (e.g. `sonnet`) |
 | `RUNTIME_MAX_BUDGET_USD` | *(unset)* | Max USD per CLI process; one-shot = per invocation, multi-turn = per session lifetime |
-| `DISCOCLAW_FAST_MODEL` | `fast` | Default "fast" model tier alias used for summarization, auto-tag, and cron parsing |
+| `DISCOCLAW_FAST_MODEL` | `fast` | **Deprecated — use `models.json` instead.** Default "fast" model tier alias used for summarization, auto-tag, and cron parsing |
 | `DISCOCLAW_RUNTIME_SESSIONS` | `1` | Persist Claude session IDs across messages |
 | `DISCOCLAW_SESSION_SCANNING` | `1` | Enable session ID scanning for resume detection |
 | `DISCOCLAW_ACTION_FOLLOWUP_DEPTH` | `3` | Max depth for chained action follow-ups |
@@ -165,7 +165,7 @@ Two setup paths:
 ### Health/Status
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DISCOCLAW_HEALTH_COMMANDS_ENABLED` | `1` | Enable `!health` command (uptime, memory, runtime status) |
+| `DISCOCLAW_HEALTH_COMMANDS_ENABLED` | `1` | Enable `!health` and `!doctor` commands (uptime, memory, runtime status, config doctor) |
 | `DISCOCLAW_HEALTH_VERBOSE_ALLOWLIST` | *(empty — falls back to `DISCORD_ALLOW_USER_IDS`)* | Space/comma-separated user IDs that can request verbose health output |
 
 ### Plan & Forge

package/.context/memory.md

@@ -161,8 +161,8 @@ Bot:   Sure — is this related to the auth middleware test you were debugging
 `workspace/MEMORY.md` + `workspace/memory/YYYY-MM-DD.md`
 
 Curated long-term notes and daily scratch logs. Loaded in DMs only. These hold
-things too nuanced for structured durable items — decisions, lessons, project
-context, relationship dynamics.
+things too nuanced for structured durable items — decisions, project context,
+relationship dynamics. Engineering lessons belong in `docs/compound-lessons.md`.
 
 **What the user sees:**
 - In DMs, the bot has deep context about ongoing projects and past decisions.

package/.context/pa.md

@@ -9,17 +9,20 @@ For architecture details, see `.context/architecture.md`.
 
 ## Workspace Files
 
-| File | Purpose | Loaded |
-|------|---------|--------|
-| `SOUL.md` | Core personality and values | Every prompt |
-| `IDENTITY.md` | Name and vibe | Every prompt |
-| `USER.md` | Who you're helping | Every prompt |
-| `AGENTS.md` | Your personal rules and conventions | Every prompt |
-| `TOOLS.md` | Available tools and integrations | Every prompt |
-| `MEMORY.md` | Curated long-term memory | DM prompts |
-| `BOOTSTRAP.md` | First-run onboarding (deleted after) | Once |
+| File | Purpose | Owner | Loaded |
+|------|---------|-------|--------|
+| `SOUL.md` | Core personality and values | User | Every prompt |
+| `IDENTITY.md` | Name and vibe | User | Every prompt |
+| `USER.md` | Who you're helping | User | Every prompt |
+| `templates/instructions/SYSTEM_DEFAULTS.md` | Tracked default instructions (runtime-injected) | Discoclaw repo (tracked) | Every prompt |
+| `AGENTS.md` | Personal rules and preferences | User (never overwritten) | Every prompt |
+| `TOOLS.md` | Available tools and integrations | Discoclaw | Every prompt |
+| `MEMORY.md` | Curated long-term memory | User | DM prompts |
+| `BOOTSTRAP.md` | First-run onboarding (deleted after) | User | Once |
 
 Templates live in `templates/workspace/` and are scaffolded on first run (copy-if-missing).
+Tracked defaults come from `templates/instructions/SYSTEM_DEFAULTS.md` and are injected at runtime.
+Legacy `workspace/DISCOCLAW.md` files are not authoritative.
 
 ## Operational Essentials
 
@@ -115,5 +118,11 @@ See `.context/memory.md` for full architecture, examples, and config reference.
 
 ## Customization
 
-These rules are generic defaults. Override or extend them in `workspace/AGENTS.md`,
-which is your personal space — not tracked by git, not overwritten on updates.
+Instruction precedence is deterministic:
+1. immutable security policy (`ROOT_POLICY`)
+2. tracked defaults (`templates/instructions/SYSTEM_DEFAULTS.md`)
+3. `workspace/AGENTS.md` overrides
+4. memory/context sections
+
+Customize behavior in `workspace/AGENTS.md` (user-owned, never overwritten).
+Do not rely on `workspace/DISCOCLAW.md`; defaults are sourced from the tracked template and injected at runtime.

package/.context/project.md

@@ -20,6 +20,10 @@ Standing constraints for planning and auditing. These apply to all forge/plan op
 - Keep changes minimal — don't over-engineer for hypothetical multi-user scenarios.
 - Prefer wiring existing systems together over building new abstractions.
 - Tests are required for new functionality.
+- `docs/compound-lessons.md` is the single checked-in durable artifact for reusable engineering lessons. Raw findings can stay in plans, audits, postmortems, or task context, but distilled standing guidance belongs there.
+- Forge drafter/auditor/reviser agents should consult `docs/compound-lessons.md` for known patterns and pitfalls before drafting, search for an existing matching lesson first, and update that entry instead of proposing a near-duplicate.
+- Before drafting, consult the `## Lessons` section of `docs/compound-lessons.md` to avoid rediscovering known patterns. When a plan reveals a materially distinct reusable lesson from audits, postmortems, or task/workflow context, include a `docs/compound-lessons.md` update in `## Changes`.
+- If a change closes a recurring workflow, review, or quality gap, the implementing engineer must either update `docs/compound-lessons.md` in the same change or explicitly record that no durable lesson was needed. Auditors and reviewers must verify that decision and the dedup check before approval.
 
 ## Plan Scope & Size Constraints
 
@@ -40,4 +44,4 @@ Plans that grow too large fail — they blow past token limits, cause audit/revi
 ### Auditor guidance
 - Do NOT flag "underspecified implementation details" as medium/high. The plan describes intent and scope — the implementing agent fills in the details.
 - DO flag: missing scope items, incorrect assumptions about existing code, safety/correctness issues, missing error handling for external boundaries.
-- If a plan is too large or touches too many source modules, flag that as **high severity** with recommendation to split. Co-located test files, lockfile changes from dependency additions, and doc/inventory updates do not count toward the scope cap.
+- If a plan is too large or touches too many source modules, flag that as **high severity** with recommendation to split. Co-located test files, lockfile changes from dependency additions, and doc/inventory updates do not count toward the scope cap.

package/.context/runtime.md

@@ -3,6 +3,7 @@
 ## Model Names & IDs
 
 **Always research official documentation** when referencing model names, IDs, or parameters — never guess or rely on training data alone. Model names change frequently across providers.
+For the complete maintainer docs index covering providers, SDKs, Discord, MCP, and dependency references, see `docs/official-docs.md`.
 
 Sources to check:
 - **Anthropic:** https://platform.claude.com/docs/en/about-claude/models/overview
@@ -45,7 +46,7 @@ The factory provides: subprocess tracking, process pool, stall detection, sessio
 | Strategy | File | Multi-turn | Notes |
 |----------|------|------------|-------|
 | Claude Code | `strategies/claude-strategy.ts` | process-pool | Default JSONL parsing, image support |
-| Codex CLI | `strategies/codex-strategy.ts` | session-resume | Custom JSONL (thread.started, item.completed), error sanitization; reasoning items surface in the Discord preview during streaming but are excluded from the final reply |
+| Codex CLI | `strategies/codex-strategy.ts` | session-resume | Custom JSONL (thread.started, item.completed), error sanitization; reasoning items surface in the Discord preview during streaming but are excluded from the final reply; image support via `--image` temp files; if a resumed turn includes images, the adapter resets to a fresh session because `codex exec resume` cannot accept `--image`, notifies the user, and loses prior conversation context |
 | Gemini CLI | `strategies/gemini-strategy.ts` | none (Phase 1) | Text-only output mode; no sessions; stdin fallback for large prompts |
 | Template | `strategies/template-strategy.ts` | — | Commented starting point for new models |
 
@@ -102,6 +103,39 @@ Shutdown: `killAllSubprocesses()` from `cli-adapter.ts` kills all tracked subpro
   - No tool execution, no fs tools
   - No image input/output support
 
+## Anthropic REST Runtime
+
+Direct HTTP adapter for the Anthropic Messages API — no CLI subprocess, no cold-start. Designed for latency-sensitive paths like voice where the ~2-4 s CLI bootstrap is unacceptable.
+
+- Adapter: `src/runtime/anthropic-rest.ts`
+- Factory: `createAnthropicRestRuntime(opts)`
+- Auth: `x-api-key` header (from `ANTHROPIC_API_KEY` env var)
+- Streaming: SSE (`stream: true`) — emits `text_delta`, `usage`, `text_final`, `done` engine events
+- Runtime ID: `claude_code` (same as CLI adapter so model tier resolution is compatible)
+- Default model: `claude-sonnet-4-6` (set at registration time in `src/index.ts`)
+- Capabilities: `streaming_text` only (no tools, no sessions)
+- Conditional registration: only registered as `'anthropic'` in the runtime registry when `ANTHROPIC_API_KEY` is set
+
+Env vars:
+
+| Var | Default | Purpose |
+|-----|---------|---------|
+| `ANTHROPIC_API_KEY` | *(required)* | API key; also gates adapter registration |
+
+Configurable via `AnthropicRestOpts`: `baseUrl` (default `https://api.anthropic.com`), `apiVersion` (default `2023-06-01`), `defaultMaxTokens` (default `1024`).
+
+### Voice auto-wiring
+
+When both `ANTHROPIC_API_KEY` and `DISCOCLAW_VOICE_ENABLED=1` are set, the startup path in `src/index.ts` auto-wires the Anthropic REST adapter as the voice runtime. `resolveVoiceRuntime()` checks `voiceModelRef.runtime` first, then falls back to the `'anthropic'` registry entry, then the primary CLI runtime. Model overrides are now configured in `models.json`; the voice runtime override is still in `runtime-overrides.json` (`voiceRuntime` key). The model can also be changed via the `!models` command.
+
+### Key files
+
+| File | Role |
+|------|------|
+| `src/runtime/anthropic-rest.ts` | Adapter: SSE streaming, abort/timeout, system prompt extraction |
+| `src/runtime/anthropic-rest.test.ts` | Unit tests (mocked fetch, SSE parsing, error handling, abort) |
+| `src/runtime/openai-compat.ts` | Provides `splitSystemPrompt()` used by the adapter |
+
 ## OpenRouter Adapter
 
 - Implementation: reuses `src/runtime/openai-compat.ts` with `id: 'openrouter'` — no separate adapter file needed.
@@ -279,6 +313,8 @@ When a Discord message or reaction target has image attachments (PNG, JPEG, WebP
 3. **Download** — `downloadAttachment()` fetches the image with a 10 s timeout, post-checks actual size, and returns base64.
 4. **Delivery** — The runtime adapter writes a `stream-json` stdin message containing `[{ type: 'text', text: prompt }, { type: 'image', source: { type: 'base64', ... } }, ...]`. When images are present, `--output-format` is forced to `stream-json` regardless of the configured format.
 
+**Codex delivery:** Codex CLI does not accept base64 image data via stdin — it requires file paths on disk via `--image <path>` flags. The Codex strategy writes each `ImageData` (base64) to a temp file before invocation and cleans up after. If images arrive on a resumed Codex turn, the adapter automatically falls back to a fresh session because `codex exec resume` does not support `--image`; the user sees a notification, and prior conversation context is lost. The full pipeline is: Discord attachment → base64 `ImageData` → temp file → `--image <path>` → cleanup.
+
 ### Security controls
 
 | Control | Detail |

package/.context/voice.md

@@ -51,6 +51,8 @@ User speaks in Discord voice channel
 
 - **Allowlist gating** — `AudioReceiver` only subscribes to users in `DISCORD_ALLOW_USER_IDS`. Empty allowlist = ignore everyone (fail-closed).
 - **Dual-flag voice actions** — Voice action execution requires both `VOICE_ENABLED` and `DISCORD_ACTIONS_VOICE`. The `buildVoiceActionFlags()` function intersects a voice-specific allowlist (messaging, tasks, memory) with env config; all other action categories are hard-disabled.
+- **Queued invocations** — `VoiceResponder` queues new transcriptions when a pipeline is already in-flight instead of aborting the active AI call. Only the most recent pending text is kept (coalesced). On completion the responder drains the queue, processing the next pending transcription. This eliminates the death-spiral where CLI cold-start latency caused cascading cancellations. Barge-in still stops *playback* immediately but never cancels the running AI request.
+- **Fast invoke path** — When `ANTHROPIC_API_KEY` is set, voice auto-wires to the Anthropic REST adapter (`src/runtime/anthropic-rest.ts`) instead of the CLI subprocess path. Direct HTTP eliminates the ~2-4 s CLI cold-start, bringing first-token latency under 500 ms. The wiring happens at startup in `src/index.ts`; at invoke time `resolveVoiceRuntime()` picks the `'anthropic'` adapter from the registry. Model configuration is now in `models.json`; the voice runtime override is still in `runtime-overrides.json` (`voiceRuntime` key). The model can also be changed via the `!models` command.
 - **Generation-based cancellation** — `VoiceResponder` increments a generation counter on each new transcription. If a newer transcription arrives mid-pipeline, the older one is silently abandoned.
 - **Barge-in** — Gated on a non-empty STT transcription result, not the raw VAD `speaking.start` event. Echo from the bot's own TTS leaking through the user's mic produces empty transcriptions and is ignored. Only when `VoiceResponder.handleTranscription()` receives a non-empty transcript while the player is active does it stop playback and advance the generation counter. This eliminates false positives from echo without relying on a static grace-period timeout.
 - **Conversation ring buffer** — `ConversationBuffer` maintains a per-guild 10-turn ring buffer of user/model exchanges that gets injected into the voice prompt as formatted conversation history. Turns are appended live during a session. On voice join, the buffer backfills from recent voice-log channel messages so context carries across disconnects. The buffer is cleared when the bot leaves the voice channel.
@@ -87,4 +89,5 @@ When `voiceEnabled=true`, the post-connect block in `src/index.ts` initializes t
 | `DEEPGRAM_TTS_VOICE` | `aura-2-asteria-en` | Deepgram TTS voice name |
 | `DEEPGRAM_TTS_SPEED` | `1.3` | Deepgram TTS playback speed (range 0.5–1.5) |
 | `CARTESIA_API_KEY` | — | Required for cartesia TTS |
+| `ANTHROPIC_API_KEY` | — | Enables the Anthropic REST adapter; when set and voice is enabled, voice auto-wires to the direct Messages API path (zero CLI cold-start). See `runtime.md § Anthropic REST Runtime`. |
 | *(built-in)* | — | Telegraphic style instruction hardcoded into every voice AI invocation — front-loads the answer, strips preambles/markdown/filler, keeps responses short for TTS latency. Not an env var; not overridable by `DISCOCLAW_VOICE_SYSTEM_PROMPT`. |

package/.env.example

@@ -45,6 +45,24 @@ DISCORD_ALLOW_USER_IDS=
 # Collected as a required field by `discoclaw init`.
 DISCORD_GUILD_ID=
 
+# Optional custom service name for multi-instance installs.
+# Written automatically by `discoclaw install-daemon --service-name <name>`.
+# `discoclaw dashboard`, `!restart`, and other service actions use this to target the correct unit.
+# Leave unset to use the default service name: discoclaw
+#DISCOCLAW_SERVICE_NAME=discoclaw
+# Disable the local operator dashboard HTTP server inside the main discoclaw process.
+# It is enabled by default and binds to 127.0.0.1. To allow access from a Tailscale
+# phone/browser without SSH tunneling, set DISCOCLAW_DASHBOARD_TRUSTED_HOSTS to your
+# tailnet IP or MagicDNS name.
+#DISCOCLAW_DASHBOARD_ENABLED=0
+# Dashboard port (default: 9401). Multi-instance setups on the same machine must use distinct ports.
+#DISCOCLAW_DASHBOARD_PORT=9401
+# Comma-separated Host header allowlist for non-loopback dashboard access.
+# When set, the dashboard binds to 0.0.0.0 but still rejects all Host headers except
+# loopback names plus the entries listed here.
+# Example: phone.tailnet.ts.net,100.64.0.12
+#DISCOCLAW_DASHBOARD_TRUSTED_HOSTS=
+
 # Where the Claude CLI runs (its working directory).
 # Default: ./workspace (or $DISCOCLAW_DATA_DIR/workspace if DATA_DIR is set)
 #WORKSPACE_CWD=
@@ -59,12 +77,31 @@ DISCORD_GUILD_ID=
 #CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1
 # Optional: isolate Codex state/sessions from ~/.codex (helps avoid stale rollout DB issues):
 #CODEX_HOME=/absolute/path/to/.codex-home-discoclaw
+# Runtime launcher state hardening for CLI providers.
+# When enabled, launcher state/path errors (e.g. Codex rollout-path corruption) trigger
+# one automatic retry with CODEX_HOME set to a clean stable home.
+# Set to 0 to disable this behavior.
+#DISCOCLAW_CLI_LAUNCHER_STATE_HARDENING=1
+# Optional stable home override used by the hardening retry above.
+# Default: <discoclaw cwd>/.codex-home-discoclaw
+#DISCOCLAW_CODEX_STABLE_HOME=/absolute/path/to/.codex-home-discoclaw
 # Disable Codex session persistence/resume (workaround for session DB issues):
 #CODEX_DISABLE_SESSIONS=1
-
+# Emit Codex item lifecycle debug events in stream preview (item.started/item.completed + item.type):
+#DISCOCLAW_CODEX_ITEM_TYPE_DEBUG=1
+# Log each Discord preview line decision (allowed/suppressed + rendered line) to journald:
+#DISCOCLAW_DEBUG_STREAM_PREVIEW_LINES=1
+
+# [DEPRECATED] Model configuration has moved to models.json (managed via !models commands).
+# RUNTIME_MODEL is still read as a fallback when models.json is missing, but new deployments
+# should use `!models set chat <model>` instead. See docs for migration details.
 # Model tier: fast | capable | deep (provider-agnostic).
 # Concrete model names (e.g. opus, sonnet, gpt-4o) are still accepted as passthrough.
 #RUNTIME_MODEL=capable
+# [DEPRECATED] Plan execution has its own startup default now. When models.json is missing
+# or reset, DISCOCLAW_PLAN_RUN_MODEL seeds the dedicated `plan-run` role independently.
+# New deployments should use `!models set plan-run <model>` instead.
+#DISCOCLAW_PLAN_RUN_MODEL=capable
 
 # Output format for the Claude CLI. stream-json gives smoother streaming.
 #CLAUDE_OUTPUT_FORMAT=stream-json
@@ -117,6 +154,7 @@ DISCORD_GUILD_ID=
 # Only set this to override the auto-discovered channel.
 #DISCOCLAW_VOICE_LOG_CHANNEL=
 #DEEPGRAM_API_KEY=
+#ANTHROPIC_API_KEY=
 
 # ----------------------------------------------------------
 # Secret management via Discord DM

package/.env.example.full

@@ -49,14 +49,30 @@ DISCORD_ALLOW_USER_IDS=
 #PRIMARY_RUNTIME=claude
 
 # --- Primary models ---
+# [DEPRECATED] Model configuration has moved to models.json (managed via !models commands).
+# RUNTIME_MODEL is still read as a fallback when models.json is missing, but new deployments
+# should use `!models set chat <model>` instead. See docs for migration details.
 # Model tier: fast | capable | deep (provider-agnostic).
 # Concrete model names (e.g. opus, sonnet, gpt-4o) are still accepted as passthrough.
 #RUNTIME_MODEL=capable
+# [DEPRECATED] Plan execution has its own startup default now. When models.json is missing
+# or reset, DISCOCLAW_PLAN_RUN_MODEL seeds the dedicated `plan-run` role independently.
+# New deployments should use `!models set plan-run <model>` instead.
+#DISCOCLAW_PLAN_RUN_MODEL=capable
 
 # --- Fast-tier default ---
+# [DEPRECATED] Model configuration has moved to models.json (managed via !models commands).
+# DISCOCLAW_FAST_MODEL is still read as a fallback when models.json is missing, but new
+# deployments should use `!models set fast <model>` instead.
 # Sets the default model for all "small" tasks (summary, cron, cron auto-tag, task auto-tag).
 # Valid tiers: fast | capable | deep. Individual overrides (DISCOCLAW_SUMMARY_MODEL, etc.) still win when set.
 #DISCOCLAW_FAST_MODEL=fast
+# [DEPRECATED] Fast-tier runtime selection has moved to models.json (managed via !models commands).
+# Use `!models set fast <provider>/<model>` to route fast-tier through a different runtime —
+# the provider prefix auto-selects the runtime adapter. DISCOCLAW_FAST_RUNTIME is still read
+# as a fallback when models.json has no fast-tier entry, but new deployments should migrate.
+# Valid values: claude | gemini | codex | openai | openrouter
+#DISCOCLAW_FAST_RUNTIME=
 
 # --- Tier model overrides ---
 # Override the concrete model resolved for any runtime × tier combination.
@@ -177,6 +193,10 @@ DISCORD_GUILD_ID=
 # Per-category flags (only active when master switch is 1):
 #DISCOCLAW_DISCORD_ACTIONS_CHANNELS=1
 #DISCOCLAW_DISCORD_ACTIONS_MESSAGING=1
+# Comma-separated absolute directory paths allowed for the sendFile Discord action.
+# Defaults to /tmp when unset. DISCOCLAW_DATA_DIR and WORKSPACE_CWD are always
+# auto-included when configured. Symlinks are resolved via fs.realpath() before checking.
+#DISCOCLAW_SENDFILE_ALLOWED_DIRS=/tmp
 #DISCOCLAW_DISCORD_ACTIONS_GUILD=1
 # Intentionally off — moderation actions require explicit opt-in.
 #DISCOCLAW_DISCORD_ACTIONS_MODERATION=0
@@ -207,6 +227,17 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # When depth reaches this limit, the defer action is disabled for that run (default: 4).
 #DISCOCLAW_DISCORD_ACTIONS_DEFER_MAX_DEPTH=4
 
+# Allow the AI to schedule repeating self-invocations with loopCreate/loopList/loopCancel.
+# Loops are inspectable recurring jobs and should be preferred over chaining repeated defers.
+# Default: on. Set to 0 to disable.
+#DISCOCLAW_DISCORD_ACTIONS_LOOP=1
+# Minimum interval (seconds) accepted for loopCreate (default: 60).
+#DISCOCLAW_DISCORD_ACTIONS_LOOP_MIN_INTERVAL_SECONDS=60
+# Maximum interval (seconds) accepted for loopCreate (default: 86400 / 24 h).
+#DISCOCLAW_DISCORD_ACTIONS_LOOP_MAX_INTERVAL_SECONDS=86400
+# Maximum number of active loops allowed at once (default: 5).
+#DISCOCLAW_DISCORD_ACTIONS_LOOP_MAX_CONCURRENT=5
+
 # Allow the AI to spawn parallel sub-agents in target channels.
 # Each spawned agent is a fire-and-forget invocation that posts output to the specified channel.
 # Spawned agents run at recursion depth 1 and cannot themselves spawn further agents.
@@ -255,6 +286,10 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #DISCOCLAW_SUMMARY_MODEL=fast
 #DISCOCLAW_SUMMARY_MAX_CHARS=2000
 #DISCOCLAW_SUMMARY_EVERY_N_TURNS=5
+# Estimated token threshold for one-pass summary recompression.
+#DISCOCLAW_SUMMARY_MAX_TOKENS=1500
+# Compression target ratio used when recompression runs (target = max_tokens * ratio).
+#DISCOCLAW_SUMMARY_TARGET_RATIO=0.65
 # Override storage directory for rolling summaries.
 #DISCOCLAW_SUMMARY_DATA_DIR=
 # Durable per-user facts/preferences (manual via !memory commands).
@@ -287,6 +322,34 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # Character budget for recent conversation history in prompts (0 = disabled).
 #DISCOCLAW_MESSAGE_HISTORY_BUDGET=3000
 
+# ----------------------------------------------------------
+# Cold storage — vector-indexed conversation history (off by default)
+# ----------------------------------------------------------
+# Master switch — enables SQLite + sqlite-vec backed long-term memory.
+# When enabled, messages are chunked, embedded, and stored for semantic
+# retrieval. Matching context is injected into prompts automatically.
+#DISCOCLAW_COLD_STORAGE_ENABLED=0
+# API key for the embedding provider. Falls back to OPENAI_API_KEY when unset.
+# For the default "openai" provider, this is your OpenAI API key.
+#COLD_STORAGE_API_KEY=
+# Embedding provider: openai (default) or openai-compat (any OpenAI-compatible API).
+#COLD_STORAGE_PROVIDER=openai
+# Model name for embeddings (required for openai-compat; optional for openai).
+#COLD_STORAGE_MODEL=
+# Embedding dimensions (required for openai-compat; optional for openai).
+#COLD_STORAGE_DIMENSIONS=
+# Base URL for the embedding API (required for openai-compat; optional for openai).
+#COLD_STORAGE_BASE_URL=
+# Path to the SQLite database file. Default: <data-dir>/cold-storage.db
+#COLD_STORAGE_DB_PATH=
+# Max characters for the cold-storage prompt section injected into each prompt (default: 1500).
+#DISCOCLAW_COLD_STORAGE_INJECT_MAX_CHARS=1500
+# Max search results returned per query (default: 10).
+#DISCOCLAW_COLD_STORAGE_SEARCH_LIMIT=10
+# Comma-separated channel IDs to restrict cold-storage ingestion and retrieval.
+# When set, only messages from these channels are stored/searched. Empty = all channels.
+#COLD_STORAGE_CHANNEL_FILTER=
+
 # ----------------------------------------------------------
 # Bot identity
 # ----------------------------------------------------------
@@ -359,12 +422,38 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # Sets the systemd unit / launchd label name used by !restart and !update apply.
 # Default: discoclaw. Ignored when DC_RESTART_CMD is set (that overrides the entire command).
 #DISCOCLAW_SERVICE_NAME=discoclaw
+# Disable the local operator dashboard HTTP server inside the main discoclaw process.
+# It is enabled by default and bound to 127.0.0.1; see DISCOCLAW_DASHBOARD_TRUSTED_HOSTS
+# for Tailscale/LAN access. When DISCOCLAW_DASHBOARD_TRUSTED_HOSTS is set, the server
+# binds to 0.0.0.0 and accepts only loopback Host headers plus the trusted list.
+#DISCOCLAW_DASHBOARD_ENABLED=0
+# Operator dashboard port (default: 9401).
+#DISCOCLAW_DASHBOARD_PORT=9401
+# Comma-separated Host header allowlist for dashboard access over Tailscale or another
+# trusted network path. Supports hostnames and IPv4 addresses only; IPv6 literals are
+# rejected because Host parsing is ambiguous here. Example:
+#DISCOCLAW_DASHBOARD_TRUSTED_HOSTS=phone.tailnet.ts.net,100.64.0.12
 # Global cap on parallel runtime invocations across all Discord sessions (0 = unlimited).
 #DISCOCLAW_MAX_CONCURRENT_INVOCATIONS=3
 # Max depth for chained action follow-ups (e.g. defer → action → response). 0 = disabled.
 #DISCOCLAW_ACTION_FOLLOWUP_DEPTH=3
 # Timeout for runtime invocations (ms).
 #RUNTIME_TIMEOUT_MS=1800000
+# Global runtime supervisor wrapper (off by default; preserves legacy behavior).
+# When enabled, all runtime invocations run through plan -> execute -> evaluate -> decide.
+#DISCOCLAW_GLOBAL_SUPERVISOR_ENABLED=0
+# Emit supervisor cycle audit JSON on stdout or stderr.
+#DISCOCLAW_GLOBAL_SUPERVISOR_AUDIT_STREAM=stderr
+# Max supervisor cycles before forced bail (must be >= 1).
+#DISCOCLAW_GLOBAL_SUPERVISOR_MAX_CYCLES=3
+# Max retries allowed across cycles (must be >= 0).
+#DISCOCLAW_GLOBAL_SUPERVISOR_MAX_RETRIES=2
+# Max escalation prompt level applied across retries (must be >= 0).
+#DISCOCLAW_GLOBAL_SUPERVISOR_MAX_ESCALATION_LEVEL=2
+# Hard cap on total streamed events across all cycles (must be >= 1).
+#DISCOCLAW_GLOBAL_SUPERVISOR_MAX_TOTAL_EVENTS=5000
+# Wall-time cap for the full supervisor loop (ms). 0 disables wall-time cap.
+#DISCOCLAW_GLOBAL_SUPERVISOR_MAX_WALL_TIME_MS=0
 # Multi-turn mode: persistent subprocess per session, keeping session context across messages (default: 1).
 #DISCOCLAW_MULTI_TURN=1
 # Timeout (ms) before a multi-turn process is considered hung and restarted.
@@ -377,18 +466,26 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #DISCOCLAW_SESSION_SCANNING=1
 # Parse tool-use events during streaming for better progress reporting and stall suppression.
 #DISCOCLAW_TOOL_AWARE_STREAMING=1
-# Stream stall detection: kill one-shot process if no stdout/stderr for this long (ms). 0 = disabled. (default: 600000)
-#DISCOCLAW_STREAM_STALL_TIMEOUT_MS=120000
-# Progress stall timeout: alert after this many ms with no progress event (ms). 0 = disabled.
-#DISCOCLAW_PROGRESS_STALL_TIMEOUT_MS=300000
+# Render a denser "Thinking..." streaming preview tail (more lines + wider logs + richer tool signals).
+# Helps previews update more visibly during long runs; action tags are still stripped from preview text.
+#DISCOCLAW_STREAM_PREVIEW_RAW=0
+# Stream stall detection: kill one-shot process if no stdout/stderr for this long (ms). 0 = disabled. (default: 1800000)
+#DISCOCLAW_STREAM_STALL_TIMEOUT_MS=1800000
+# Progress stall timeout: alert after this many ms with no progress event (ms). 0 = disabled. (default: 1800000)
+#DISCOCLAW_PROGRESS_STALL_TIMEOUT_MS=1800000
 # Stream stall warning: show user-visible warning in Discord after this many ms of no events. 0 = disabled. (default: 300000)
 #DISCOCLAW_STREAM_STALL_WARNING_MS=60000
-# Post a brief "Done (Xm Ys)" completion notice as a new message after long-running runs finish.
-# Discord's unread indicator fires on new messages but not edits, so users who left the channel
-# while the bot was working will see an unread badge. Set to 0 to disable.
+# Enable long-run watchdog follow-up status updates.
+# Normal path: after the threshold delay, a deferred "Still running..." check-in is posted.
+# Recovery path: lifecycle state is persisted and swept on startup so interrupted long-running
+# runs still get a final status update after restart.
+# Persistence-first lifecycle: run completion is persisted before attempting the final Discord
+# post/edit, and finalPosted is set only after a successful post/edit. Crash boundaries may
+# duplicate follow-up/final updates, but should not omit them. Set to 0 to disable watchdog
+# follow-up posting entirely.
 #DISCOCLAW_COMPLETION_NOTIFY=1
-# Minimum elapsed time (ms) before a completion notice is sent. Runs shorter than this are
-# considered "fast" and don't need a notification. Default: 30000 (30 seconds).
+# Delay (ms) before the in-process "Still running..." follow-up timer fires. Fast runs shorter
+# than this are considered non-long-running and do not post watchdog follow-ups. Default: 30000.
 #DISCOCLAW_COMPLETION_NOTIFY_THRESHOLD_MS=30000
 
 # ----------------------------------------------------------
@@ -405,6 +502,10 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #PLAN_PHASE_TIMEOUT_MS=1800000
 # Max audit-fix attempts per phase before marking failed.
 #PLAN_PHASE_AUDIT_FIX_MAX=3
+# Default heartbeat interval (ms) for command-path phase progress updates
+# in `!plan run*` and `!forge`. Set to 0 to disable periodic heartbeats;
+# phase starts/transitions and the single terminal outcome still post.
+#PLAN_FORGE_HEARTBEAT_INTERVAL_MS=45000
 # Max draft-audit-revise loops before CAP_REACHED.
 #FORGE_MAX_AUDIT_ROUNDS=5
 # Model overrides for forge roles (fall back to RUNTIME_MODEL).
@@ -434,7 +535,7 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # Optional: isolate Codex state/sessions from ~/.codex (helps avoid stale rollout DB issues).
 #CODEX_HOME=/absolute/path/to/.codex-home-discoclaw
 # Default model for the Codex CLI adapter. Used when FORGE_AUDITOR_MODEL is not set.
-#CODEX_MODEL=gpt-5.3-codex
+#CODEX_MODEL=gpt-5.4
 # WARNING: disables Codex approval prompts and sandbox protections (full-access mode).
 # Equivalent to passing --dangerously-bypass-approvals-and-sandbox to codex exec.
 #CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=0
@@ -540,13 +641,17 @@ DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN=0
 # Leave unset to disable transcript mirroring.
 #DISCOCLAW_VOICE_LOG_CHANNEL=  # e.g. "voice-log" if using the default scaffold
 # Model for voice AI responses: tier (fast | capable | deep) or concrete name (sonnet, opus, haiku).
-# Independent of RUNTIME_MODEL — allows tuning voice latency vs quality separately from chat.
-# Switchable at runtime via `modelSet voice <model>`.
-# Default: follows DISCOCLAW_FAST_MODEL (override here for voice-specific tuning).
+# Independent of the chat model — allows tuning voice latency vs quality separately from chat.
+# Switchable at runtime via `!models set voice <model>`.
+# Default: follows the startup chat model unless overridden here.
 #DISCOCLAW_VOICE_MODEL=sonnet
 # Custom system prompt prepended to voice AI invocations. Max 4000 chars.
 # Use this to set a conversational tone, brevity instructions, or persona for voice responses.
 #DISCOCLAW_VOICE_SYSTEM_PROMPT=
+# Anthropic API key for direct Messages API access (bypasses Claude CLI cold-start).
+# When set and voice is enabled, voice invocations use the Anthropic REST adapter
+# instead of the CLI subprocess, eliminating ~2-5s cold-start latency per response.
+#ANTHROPIC_API_KEY=
 # API key for Deepgram Nova-3 STT. Required when DISCOCLAW_STT_PROVIDER=deepgram.
 #DEEPGRAM_API_KEY=
 # Deepgram STT model for voice transcription (default: nova-3-conversationalai).

package/README.md

@@ -26,6 +26,7 @@ Your assistant carries context across every conversation, channel, and restart.
 
 - **Durable facts** — `!memory remember prefers dark mode` persists across sessions and channels
 - **Rolling summaries** — Compresses earlier conversation so context carries forward, even across restarts
+- **Cold storage** — Semantic search over past conversations using vector embeddings + keyword search. Relevant history is automatically retrieved and injected into the prompt (see [docs/memory.md](docs/memory.md))
 - **Per-channel context** — Each channel gets a markdown file shaping behavior (formal in #work, casual in #random)
 - **Customizable identity** — Personality, name, and values defined in workspace files (`SOUL.md`, `IDENTITY.md`, etc.)
 - **Group chat aware** — Knows when to speak up and when to stay quiet in shared channels
@@ -84,6 +85,24 @@ DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by
 4. Streams the response back, chunked to fit Discord's message limits
 5. Parses and executes any Discord actions the assistant emitted
 
+### Instruction precedence
+
+Prompt assembly has two layers, each with its own ordering contract.
+
+**Preamble precedence** — the front of every prompt, in strict priority order:
+
+1. **Immutable security policy** (hard-coded root rules)
+2. **Tracked defaults** (runtime-injected from `templates/instructions/SYSTEM_DEFAULTS.md`)
+3. **Tracked tools** (runtime-injected from `templates/instructions/TOOLS.md`)
+4. **User rules override** (`workspace/AGENTS.md`)
+5. **User tools override** (`workspace/TOOLS.md`, optional)
+6. **Memory/context layers** (workspace identity files, channel context, durable/rolling memory, etc.)
+
+**Post-preamble section ordering** — the sections between the preamble and the user message are arranged to exploit primacy bias (high-signal sections first) and recency bias (action schemas and constraints near the end, just before the user message). Low-signal data sections sit in the middle. See [`docs/prompt-ordering.md`](docs/prompt-ordering.md) for the canonical order and rationale.
+
+`workspace/DISCOCLAW.md` is no longer a managed or authoritative instruction source.
+If you still have a legacy copy, treat it as historical reference only.
+
 ### Message batching
 
 When multiple messages arrive while the bot is thinking (i.e., an AI invocation is already active for that session), they're automatically combined into a single prompt rather than queued individually. This means rapid follow-up messages are processed together, giving the bot full context in one shot. Commands (`!`-prefixed messages) bypass batching and are always processed individually.
@@ -92,11 +111,13 @@ When multiple messages arrive while the bot is thinking (i.e., an AI invocation
 
 Set `PRIMARY_RUNTIME=openrouter` to route requests through [OpenRouter](https://openrouter.ai), which provides access to models from Anthropic, OpenAI, Google, and others via a single API key — useful if you want to switch models without managing multiple provider accounts.
 
-Required: `OPENROUTER_API_KEY`. Optional overrides: `OPENROUTER_BASE_URL` (default: `https://openrouter.ai/api/v1`) and `OPENROUTER_MODEL` (default: `anthropic/claude-sonnet-4`). See `.env.example` for the full reference.
+Required: `OPENROUTER_API_KEY`. Optional overrides: `OPENROUTER_BASE_URL` (default: `https://openrouter.ai/api/v1`) and `OPENROUTER_MODEL` (default: `anthropic/claude-sonnet-4`). OpenRouter does not have a built-in `fast`/`capable`/`deep` tier map inside DiscoClaw, so if you want tier names or fast/voice auto-switching to resolve through OpenRouter, define the specific `DISCOCLAW_TIER_OPENROUTER_<TIER>` vars you need in `.env` and restart. A single unique entry such as `DISCOCLAW_TIER_OPENROUTER_FAST=openai/gpt-5-mini` is enough for that exact-string fast/voice reverse-mapping. See `.env.example` for the full reference.
 
 ## Model Overrides
 
-The `!models` command lets you view and swap AI models per role at runtime — no restart needed, and changes persist across restarts.
+The `!models` command lets you view and swap AI models per role at runtime — no restart needed. Per-role model values persist to `models.json` under the data dir, while fast/voice runtime overlays persist separately to `runtime-overrides.json`. Live runtime swaps like `!models set chat openrouter` are still live-only until the next restart, but they affect the main runtime path broadly, not just chat.
+
+For the full operator guide to install-mode detection, persistent adapter switches, OpenRouter tier overrides, fast/voice runtime behavior, and `!models reset` semantics, see [docs/runtime-switching.md](docs/runtime-switching.md).
 
 **Roles:** `chat`, `fast`, `forge-drafter`, `forge-auditor`, `summary`, `cron`, `cron-exec`, `voice`
 
@@ -104,17 +125,18 @@ The `!models` command lets you view and swap AI models per role at runtime — n
 |---------|-------------|
 | `!models` | Show current model assignments |
 | `!models set <role> <model>` | Change the model for a role |
-| `!models reset` | Revert all roles to env-var defaults |
-| `!models reset <role>` | Revert a specific role |
+| `!models reset` | Revert all roles to startup defaults and clear overrides |
+| `!models reset <role>` | Revert a specific role to its startup default |
 
 **Examples:**
 - `!models set chat claude-sonnet-4` — use Sonnet for chat
-- `!models set chat openrouter` — switch chat to the OpenRouter runtime
+- `!models set chat openrouter` — live-switch the main runtime to OpenRouter until restart
 - `!models set cron-exec haiku` — run crons on a cheaper model
+- `!models set cron-exec default` — clear the cron-exec override and use the startup default again
 - `!models set voice sonnet` — use a specific model for voice
-- `!models reset` — clear all overrides
+- `!models reset` — clear all overrides and revert to startup defaults
 
-Setting the `chat` role to a runtime name (`openrouter`, `openai`, `gemini`, `codex`, `claude`) switches the active runtime adapter for that role.
+Setting `chat` to a runtime name (`openrouter`, `openai`, `gemini`, `codex`, `claude`) live-switches the main runtime path until restart; setting `voice` to a runtime name switches only voice. Exact model-string runtime auto-switching is only implemented for `fast` and `voice`.
 
 ## Secret Management
 
@@ -165,6 +187,15 @@ When using the Claude runtime, you can connect external tool servers via MCP. Pl
 **Contributors (from source):**
 - Everything above, plus **pnpm** — enable via Corepack (`corepack enable`) or install separately
 
+### Model capability requirement
+
+DiscoClaw assumes reliable structured output for several runtime paths (for example: Discord actions, cron JSON routing, and tool-call loops).
+
+- For OpenAI-compatible and OpenRouter adapters, pick models that reliably support JSON-shaped output and function calling.
+- "OpenAI-compatible" API shape alone is not a capability guarantee.
+- If a model fails JSON/tool-call smoke tests, treat it as unsupported for DiscoClaw runtime use.
+- Use the [model validation smoke test checklist](docs/configuration.md#model-validation-smoke-test-recommended) before adopting a new model.
+
 <!-- source-of-truth: docs/discord-bot-setup.md -->
 ## Quick start
 
@@ -211,6 +242,7 @@ Full step-by-step guide: [docs/discord-bot-setup.md](docs/discord-bot-setup.md)
 ### Operations
 
 - [Configuration reference](docs/configuration.md) — all environment variables indexed by category
+- [Runtime/model switching](docs/runtime-switching.md) — operator guide for switching adapters, models, and defaults safely
 - [Webhook exposure](docs/webhook-exposure.md) — tunnel/proxy setup and webhook security
 - [Data migration](docs/data-migration.md) — migrating task data between formats
 
@@ -242,6 +274,14 @@ Full step-by-step guide: [docs/discord-bot-setup.md](docs/discord-bot-setup.md)
    discoclaw install-daemon --service-name personal
    ```
 
+4. **Open the local operator dashboard:**
+   ```bash
+   discoclaw dashboard
+   ```
+   By default this listens on `127.0.0.1`. To reach it from a phone over Tailscale,
+   set `DISCOCLAW_DASHBOARD_TRUSTED_HOSTS` to your tailnet IP or MagicDNS hostname.
+   See [docs/dashboard-tailscale.md](docs/dashboard-tailscale.md).
+
 #### From source (contributors)
 
 ```bash
@@ -282,7 +322,9 @@ pnpm install
 pnpm build
 ```
 
-Run `pnpm preflight` — it flags configuration options from `.env.example` that aren't in your `.env` yet.
+Run `pnpm preflight` — it flags configuration options from `.env.example` that aren't in your `.env` yet. You can also run `discoclaw doctor` to inspect config drift and related issues, `discoclaw doctor --fix` to apply safe remediations, or use `!doctor` / `!doctor fix` from Discord (`!health doctor` / `!health doctor fix` remain supported). Restart the service afterward for fixed config to take effect.
+
+For a local operator console, run `discoclaw dashboard` in the project directory. It shows the active service target, current model assignments, runtime overrides, config doctor status, and quick actions for status/logs/restart. It binds to `127.0.0.1` by default; configure `DISCOCLAW_DASHBOARD_TRUSTED_HOSTS` to allow Tailscale access via a tailnet IP or MagicDNS hostname while keeping Host-header checks in place for all other names. See [docs/dashboard-tailscale.md](docs/dashboard-tailscale.md).
 
 If running as a systemd service, restart it: