discoclaw 0.6.0 → 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

@@ -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/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; image support via `--image` temp files |
+| 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 |
 
@@ -312,7 +313,7 @@ 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. The full pipeline is: Discord attachment → base64 `ImageData` → temp file → `--image <path>` → cleanup.
+**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
 

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=
@@ -80,6 +98,10 @@ DISCORD_GUILD_ID=
 # 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

package/.env.example.full

@@ -55,6 +55,10 @@ DISCORD_ALLOW_USER_IDS=
 # 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).
@@ -223,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.
@@ -407,6 +422,17 @@ 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.
@@ -443,10 +469,10 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 # 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: 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
+# 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
 # Enable long-run watchdog follow-up status updates.

package/README.md

@@ -111,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. Changes are persisted to `models.json` under the data dir and survive 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`
 
@@ -128,13 +130,13 @@ The `!models` command lets you view and swap AI models per role at runtime — n
 
 **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 and revert to startup defaults
 
-Setting the `chat` or `voice` 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
 
@@ -240,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
 
@@ -271,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
@@ -311,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:
 

package/dashboard/server.js

@@ -0,0 +1,21 @@
+const DIST_SERVER_URL = new URL('../dist/dashboard/server.js', import.meta.url);
+
+let dashboardServerModulePromise;
+
+async function loadDashboardServerModule() {
+  if (!dashboardServerModulePromise) {
+    dashboardServerModulePromise = import(DIST_SERVER_URL.href).catch((error) => {
+      if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') {
+        throw new Error('dashboard/server.js requires a built dist tree. Run `pnpm build` first.');
+      }
+      throw error;
+    });
+  }
+
+  return dashboardServerModulePromise;
+}
+
+export async function startDashboardServer(options = {}) {
+  const serverModule = await loadDashboardServerModule();
+  return serverModule.startDashboardServer(options);
+}