discoclaw 1.2.1 → 1.2.3

package/.context/discord.md

@@ -96,6 +96,8 @@ Notes:
 - `generateImage` supports two providers: **OpenAI** (models: `dall-e-3`, `gpt-image-1`) and **Gemini** (models: `imagen-4.0-generate-001`, `imagen-4.0-fast-generate-001`, `imagen-4.0-ultra-generate-001`). Provider is auto-detected from the model prefix (`dall-e-*`/`gpt-image-*` → openai, `imagen-*` → gemini) or set explicitly via the `provider` field. OpenAI provider uses `OPENAI_API_KEY` (required) and optional `OPENAI_BASE_URL`. Gemini provider uses `IMAGEGEN_GEMINI_API_KEY`. At least one key must be set when `DISCOCLAW_DISCORD_ACTIONS_IMAGEGEN=1`. Default model is auto-detected: if only `IMAGEGEN_GEMINI_API_KEY` is set, defaults to `imagen-4.0-generate-001`; otherwise defaults to `dall-e-3`. Override with `IMAGEGEN_DEFAULT_MODEL`.
 - `spawnAgent` is enabled by default (`DISCOCLAW_DISCORD_ACTIONS_SPAWN=1`; set to 0 to disable). Spawned agents run fire-and-forget: each agent runs its prompt via the configured runtime and posts its output directly to the target channel. Multiple `spawnAgent` actions in a single response run in parallel (bounded by `DISCOCLAW_DISCORD_ACTIONS_SPAWN_MAX_CONCURRENT`, default 8). Spawn is disabled for bot-originated messages and excluded from cron flows to prevent recursive agent chains. Spawned agents run at recursion depth 1 and cannot themselves spawn further agents.
 
+Action guard (false completion detection): When a reply's visible text claims Discord-managed work was performed or is being performed — in any tense (present progressive, future intent, past tense, or perfect tense) — but the turn produced zero actionable `<discord-action>` blocks and zero executed action results, the finalizer appends a visible warning. This catches fabricated completion claims ("Posted the plan", "I've sent the message") at the output boundary so the user sees the discrepancy immediately. The guard is implemented in `output-common.ts` (`claimsImmediateDiscordActionIntent` + `appendPromisedDiscordActionWithoutExecutionNotice`) and requires no prompt-layer changes — it operates purely on the finalized reply text and action execution counts.
+
 Auto-follow-up: When query actions (channelList, channelInfo, threadListArchived, forumTagList, readMessages, fetchMessage, listPins, memberInfo, roleInfo, searchMessages, eventList, taskList, taskShow, cronList, cronShow, planList, planShow, memoryShow, modelShow, forgeStatus) succeed, DiscoClaw automatically re-invokes Claude with the results. This allows Claude to reason about query results without requiring the user to send a follow-up message. Controlled by `DISCOCLAW_ACTION_FOLLOWUP_DEPTH` (default `3`, `0` disables). Mutation-only responses do not trigger follow-ups. Trivially short follow-up responses (<50 chars with no actions) are suppressed.
 
 Requirements:
@@ -236,6 +238,18 @@ grep DISCOCLAW_STATUS_CHANNEL .env
 journalctl --user -u discoclaw.service --since "5 min ago" --no-pager | grep -i "status"
 ```
 
+### Bot claims it performed a Discord action but nothing happened
+**Symptom:** Bot says "Posted the plan to #general" or "I've sent the message" but no message appears in the target channel.
+**Cause:** The model fabricated a completion claim without emitting a `<discord-action>` block. The action guard should append a visible warning to the reply.
+**Verification:**
+1. Check whether the reply ends with a warning starting with `Warning: this reply says Discord-managed work was performed`.
+2. If the warning is present, the guard is working — the model hallucinated the action. No code fix needed; the warning tells the user.
+3. If no warning is present but the action still didn't execute, check whether the action block was parsed but failed during execution (look for "Action Failed" in the status channel or bot logs).
+```bash
+# Check recent action failures
+journalctl --user -u discoclaw.service --since "5 min ago" --no-pager | grep -i "action.*fail\|warning.*discord-action"
+```
+
 ### Messages split awkwardly across Discord's 2000-char limit
 **Symptom:** Bot replies are split mid-sentence or mid-code-block, producing garbled formatting.
 **Cause:** The chunking algorithm tries to preserve code fences but can't always split cleanly if the response has deeply nested or very long code blocks.

package/.context/pa.md

@@ -40,6 +40,12 @@ Your prompt may include:
 - **Durable memory** — Persistent user facts/preferences. Treat as ground truth unless contradicted.
 - **Conversation memory** — Rolling summary, lossy. Trust recent messages over summary if they conflict.
 
+## False Completion Claims
+
+The runtime action guard (`output-common.ts`) catches both present-tense intent ("I'm posting…") and past-tense completion claims ("Posted the plan to the channel", "I've sent the message") that lack matching `<discord-action>` blocks. When the guard fires, it appends a visible warning to the reply so the user sees the discrepancy immediately.
+
+No separate prompt or instruction change is needed to address this gap — the guard operates at the output finalization boundary and catches false claims regardless of how the model phrases them. If the model fabricates a completion claim, the warning surfaces it before the user has to ask why nothing happened.
+
 ## Autonomy Tiers
 
 **Always OK:** Read files, explore, search web, run diagnostics, send Discord messages, react, share finds, work within workspace.

package/.env.example

@@ -234,6 +234,15 @@ DISCORD_GUILD_ID=
 # "anthropic-cache-telemetry" in journal output). Set LOG_LEVEL=debug for
 # full prompt section breakdowns.
 
+# ----------------------------------------------------------
+# Continuation capsule staleness
+# ----------------------------------------------------------
+# Maximum age (ms) of a continuation capsule before it is skipped at injection time.
+# Prevents stale context from prior conversations bleeding into unrelated sessions.
+# Capsules with an idle/awaiting currentFocus are always skipped regardless of age.
+# Default: 7200000 (2 hours). Set to 0 to disable TTL expiry (idle detection still applies).
+#DISCOCLAW_CAPSULE_TTL_MS=7200000
+
 # ----------------------------------------------------------
 # For all ~90 options (subsystems, actions, memory, identity,
 # observability, advanced/debug), see .env.example.full

package/.env.example.full

@@ -369,6 +369,11 @@ DISCOCLAW_DISCORD_ACTIONS_DEFER=1
 #DISCOCLAW_MEMORY_CONSOLIDATION_MODEL=fast
 # Character budget for recent conversation history in prompts (0 = disabled).
 #DISCOCLAW_MESSAGE_HISTORY_BUDGET=3000
+# Maximum age (ms) of a continuation capsule before it is skipped at injection time.
+# Prevents stale context from prior conversations bleeding into unrelated sessions.
+# Capsules with an idle/awaiting/none currentFocus are always skipped regardless of age.
+# Default: 7200000 (2 hours). Set to 0 to disable TTL expiry (idle detection still applies).
+#DISCOCLAW_CAPSULE_TTL_MS=7200000
 
 # ----------------------------------------------------------
 # Cold storage — vector-indexed conversation history (off by default)

package/README.md

@@ -6,522 +6,85 @@
 
 A personal AI orchestrator that turns Discord into a persistent workspace — built on three pillars: **Memory**, **Tasks**, and **Automations**.
 
-DiscoClaw is an orchestrator: it coordinates between a user interface (Discord), one or more AI runtimes (Claude Code, OpenAI, Codex), and local system resources — managing conversation state, task routing, scheduling, and tool access. The intelligence is rented; the coordination is owned.
+[![npm version](https://img.shields.io/npm/v/discoclaw)](https://www.npmjs.com/package/discoclaw)
+[![license](https://img.shields.io/npm/l/discoclaw)](LICENSE)
+[![node](https://img.shields.io/node/v/discoclaw)](package.json)
 
-It turns a private Discord server into a persistent AI workspace. Your assistant remembers you across sessions, tracks work in forum threads, and runs scheduled tasks autonomously — all through natural conversation.
+> Turn Discord into a persistent AI workspace — memory, tasks, automations, and voice, all through natural conversation.
 
-It's designed for a single user on a fresh, private server — your own sandbox. Not a shared bot, not a multi-user platform. Just you and your assistant in a space you control.
+DiscoClaw coordinates between Discord, AI runtimes (Claude Code, OpenAI, Codex, Gemini, OpenRouter), and local system resources. The intelligence is rented; the coordination is owned. Designed for a single user on a private server — your own sandbox.
 
-No gateways, no proxies, no web UI to deploy — Discord *is* the interface. Run DiscoClaw on a Linux or macOS machine (see [Platform support](#platform-support)) and talk to your assistant from anywhere Discord works: desktop, mobile, browser.
-
-The codebase is intentionally small — small enough to read, audit, and modify directly. Customization means changing the code, not configuring a plugin system.
-
-## Why Discord?
-
-Discord gives you channels, forum threads, DMs, mobile access, and rich formatting for free. DiscoClaw maps its three core features onto Discord primitives so there's nothing extra to learn — channels become context boundaries, forum threads become task cards and job definitions, and conversation history is the raw material for memory.
+No gateways, no proxies, no web UI. Discord *is* the interface.
 
 ## Memory — the bot knows you
 
-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
-
-**Why Discord fits:** channels = context boundaries, DMs = private deep context, conversation history is the raw material.
-
-### YouTube transcripts
-
-When you share a YouTube link in a message, DiscoClaw automatically fetches the video's transcript and injects it into the AI's context. This lets the bot answer questions about video content, summarize talks, or reference specific points — without you needing to copy-paste anything. Up to 3 videos per message are processed, with a 15-second timeout per fetch. Transcripts are sanitized before injection to prevent prompt manipulation.
+- **Durable facts** — persist across sessions, channels, and restarts
+- **Rolling summaries** — context carries forward, even across restarts
+- **Semantic search** — vector + keyword search over past conversations, auto-retrieved
+- **Per-channel personality** — markdown files shape behavior per channel
+- **YouTube transcripts** — share a link, the bot reads the video
 
 ## Tasks — the bot tracks your work
 
-A lightweight in-process task store that syncs bidirectionally with Discord forum threads.
-
-- **Create from either side** — Ask your assistant in chat or use task commands
-- **Bidirectional sync** — Status, priority, and tags stay in sync between the task store and Discord threads
-- **Status emoji and auto-tagging** — Thread names show live status at a glance
-- **Discord actions** — Your assistant manages tasks through conversation: create channels, send messages, search history, run polls, and more (see [docs/discord-actions.md](docs/discord-actions.md))
-
-**Why Discord fits:** forum threads = task cards, archive = done, thread names show live status.
+- **Bidirectional sync** — task store and Discord forum threads stay in sync
+- **Create from anywhere** — chat, commands, or the forum directly
+- **Live status** — thread names show status emoji at a glance
+- **Discord actions** — the bot manages channels, messages, polls, and more through conversation
 
 ## Automations — the bot acts on its own
 
-Recurring tasks defined as forum threads in plain language — no crontab, no separate scheduler UI.
-
-- **Plain-language schedules** — "every weekday at 7am, check the weather and post to #general"
-- **Edit to change, archive to pause, unarchive to resume**
-- **Full workspace access** — File I/O, web search, browser automation, Discord actions
-- **Multi-turn sessions** — A live process persists between runs, so context carries across executions
-
-**Why Discord fits:** forum threads = job definitions, archive/unarchive = pause/resume, no separate scheduler UI needed.
-
-For the managed Chrome/Chromium profile flow used by browser automation, see the [managed browser launcher guide](#managed-browser-launcher).
+- **Plain-language schedules** — "every weekday at 7am, check the weather"
+- **Forum-thread definitions** — edit to change, archive to pause
+- **Full workspace access** — files, web, browser automation, Discord actions
 
-<!-- source-of-truth: docs/voice.md -->
 ## Voice — the bot talks back
 
-DiscoClaw can join Discord voice channels for real-time conversation: listen via speech-to-text, think with the AI runtime, and speak the response via text-to-speech.
-
-- **STT** — Deepgram Nova-3 streaming transcription (WebSocket)
-- **TTS** — Cartesia Sonic-3 speech synthesis (WebSocket, 24 kHz PCM)
-- **Barge-in** — interrupt the bot mid-sentence by speaking; playback stops immediately
-- **Auto-join** — optionally join/leave channels automatically when you enter or leave
-- **Transcript mirror** — voice conversations are mirrored to a text channel for persistence
-- **Voice actions** — the AI can execute a restricted action subset (messaging, tasks, memory) during voice
-
-Voice is **off by default**. Enable with `DISCOCLAW_VOICE_ENABLED=1` plus API keys for your STT/TTS providers. Requires Node 22+ (for native WebSocket used by Cartesia TTS) and C++ build tools (for the `@discordjs/opus` native addon).
-
-Full setup guide: [docs/voice.md](docs/voice.md)
-
-## Self-management — the bot maintains itself
-
-- **Self-update** — `!update` checks for new npm versions; `!update apply` downloads, installs, and restarts without leaving Discord
-- **Health checks** — `!health`, `!doctor`, `!status` for diagnostics
-- **Secret management** — `!secret` manages `.env` entries from DMs
-- **Model switching** — `!models` swaps AI models per role at runtime
-- **Restart** — `!restart` restarts the service on demand
-
-## How it works
-
-DiscoClaw orchestrates the flow between Discord and AI runtimes (Claude Code by default, with `gemini-api`, OpenAI, Codex, and OpenRouter adapters available via `PRIMARY_RUNTIME`). For 1.0, `Claude CLI` on a source checkout is the explicitly supported default path, and `Codex CLI` on a source checkout is the explicitly supported secondary path. See [docs/audit/provider-auth-1.0-matrix.md](docs/audit/provider-auth-1.0-matrix.md) for the full consolidated matrix. The OpenAI-compatible and OpenRouter adapters can expose optional tool use when `OPENAI_COMPAT_TOOLS_ENABLED=1` is set, but OpenRouter support claims stop at the narrower audited boundary described below. It doesn't contain intelligence itself — it decides *when* to call the AI, *what context* to give it, and *what to do* with the output. When you send a message, the orchestrator:
-
-1. Checks the user allowlist (fail-closed — empty list means respond to nobody)
-2. Assembles context: per-channel rules, conversation history, rolling summary, and durable memory
-3. Routes to the appropriate runtime adapter, running in your workspace directory
-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.
-
-### OpenRouter
-
-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.
-
-Required: `OPENROUTER_API_KEY`. Optional overrides: `OPENROUTER_BASE_URL` (default: `https://openrouter.ai/api/v1`), `OPENROUTER_MODEL` (default: `anthropic/claude-sonnet-4.6`), and `OPENROUTER_PROVIDER_PREFERENCES` (OpenRouter-only JSON routed through the request `provider` field). Treat `.env` presence, `PRIMARY_RUNTIME=openrouter`, and `!models set chat openrouter` as config/routing intent only until the running instance proves the shipped OpenRouter path with `!status` or the startup credential report showing `openrouter-key: ok`.
-
-For source checkouts, workload evidence beyond that key-visibility proof exists only through the repo smoke path, and read-only tool coverage is the only validated tool subset today. DiscoClaw now ships built-in OpenRouter tier defaults: `fast → openai/gpt-5-mini`, `capable → anthropic/claude-sonnet-4.6`, `deep → anthropic/claude-opus-4.6`. Override them with `DISCOCLAW_TIER_OPENROUTER_<TIER>` only when you need instance-specific routing. See [docs/audit/openrouter-api-key-support-boundary.md](docs/audit/openrouter-api-key-support-boundary.md) for the support boundary that npm installs and source checkouts both ship.
-
-## Model Overrides
-
-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`
-
-| Command | Description |
-|---------|-------------|
-| `!models` | Show current model assignments |
-| `!models set <role> <model>` | Change the model for a 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` — 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 `chat` to a runtime name (`openrouter`, `openai`, `gemini-api`, `codex-cli`, `claude-cli`) live-switches the main runtime path until restart; setting `voice` to a runtime name switches only voice. Legacy aliases (`claude`, `codex`, `anthropic`) are still accepted. Exact model-string runtime auto-switching is only implemented for `fast` and `voice`.
-
-## Secret Management
-
-The `!secret` command lets you manage `.env` entries from Discord without touching the file directly. It works in DMs only — values are never echoed back.
-
-| Command | Description |
-|---------|-------------|
-| `!secret set KEY=value` | Add or update a `.env` entry |
-| `!secret unset KEY` | Remove a `.env` entry |
-| `!secret list` | List key names in `.env` (values hidden) |
-| `!secret help` | Show usage |
-
-Changes take effect after a restart (`!restart`). Writes are atomic — a partial write can't corrupt your `.env`.
-
-## Customization
-
-### Shareable integration recipes
-
-DiscoClaw supports a shareable markdown recipe format for passing integrations between users:
-
-- Spec: `docs/discoclaw-recipe-spec.md`
-- Template: `templates/recipes/integration.discoclaw-recipe.md`
-- Example files: `recipes/examples/*.discoclaw-recipe.md`
-- Skills:
-  - `skills/discoclaw-recipe-generator/SKILL.md`
-  - `skills/discoclaw-recipe-consumer/SKILL.md`
-- Install/refresh invocable skill symlinks:
-  - `pnpm claude:install-skills`
+Real-time voice with STT (Deepgram), TTS (Cartesia), barge-in, and transcript mirroring. Off by default. [Setup guide →](docs/voice.md)
 
-Author one recipe file for an integration, share it, then let another user's DiscoClaw agent consume it and produce a local implementation checklist before coding.
+## Self-management
 
-### MCP (Model Context Protocol)
+Self-update from Discord (`!update apply`), health checks (`!doctor`), secret management (`!secret`), runtime model switching (`!models`), and restart (`!restart`) — no SSH needed.
 
-When using the Claude runtime, you can connect external tool servers via MCP. Place a `.mcp.json` file in your workspace directory to configure servers — their tools become available during conversations. See [docs/mcp.md](docs/mcp.md) for the config format, examples, and troubleshooting.
-
-## Managed browser launcher
-
-Browser automation uses a Discoclaw-managed Chrome/Chromium profile directly. There is no companion service, long-lived helper daemon, or localhost control service to keep running in the background.
-
-Use the launcher flow when you need a real browser profile for login-gated sites or later headless reuse:
-
-- `discoclaw browser setup` checks storage rules, browser discovery, and current managed-profile readiness
-- `discoclaw browser launch` opens the managed profile headed for one-time login and verifies CDP against that same browser instance
-- `discoclaw browser launch --headless` reuses the same verified profile later without opening a visible window
-- `!browser help` in Discord prints the same operator-facing setup, doctor, and launch commands
-
-For source checkouts, repo-local managed browser storage is supported only at the ignored default `data/browser/` path. Custom in-repo data dirs are refused for this feature; if you need a different browser data location, move `DISCOCLAW_DATA_DIR` outside the repo.
-
-## Prerequisites
-
-**End users:**
-- **Node.js >=20** — check with `node --version`
-- One primary runtime:
-  - **Claude CLI** on your `PATH` — check with `claude --version` (see [Claude CLI docs](https://docs.anthropic.com/en/docs/claude-code) to install), or
-  - **Gemini API** via `PRIMARY_RUNTIME=gemini-api` plus `GEMINI_API_KEY`, or
-  - **Codex CLI** on your `PATH` — check with `codex --version` (binary presence only; session auth is a separate proof gate), or
-  - **OpenAI-compatible API key** via `OPENAI_API_KEY` (config presence only; live auth is a separate proof gate), or
-  - **OpenRouter API key** via `OPENROUTER_API_KEY` (config presence only until `!status` or the startup credential report shows `openrouter-key: ok`)
-- Runtime-specific access for your chosen provider (Anthropic access for Claude CLI, Google API access for `gemini-api`, OpenAI access for Codex/OpenAI models)
-
-1.0 provider/auth policy: `Claude CLI` on a source checkout is the explicitly supported default path, and `Codex CLI` on a source checkout is the explicitly supported secondary path. For every current provider/auth path, including `openai`, `openrouter`, `gemini-api`, and direct Anthropic, use the consolidated verdicts in [docs/audit/provider-auth-1.0-matrix.md](docs/audit/provider-auth-1.0-matrix.md) rather than inferring readiness from setup/config alone.
-
-`discoclaw init` scaffolds Claude CLI, Codex CLI, OpenAI, OpenRouter, and Gemini API runtime paths.
-
-For Codex and OpenAI paths, treat binary/key presence as readiness prerequisites only. The install-mode-specific support claims live in the [provider/auth 1.0 matrix](docs/audit/provider-auth-1.0-matrix.md), [Codex source-checkout audit](docs/audit/codex-blank-machine-readiness.md), and [Codex npm-managed audit](docs/audit/codex-npm-managed-path.md). For OpenRouter, the shipped support claim is narrower: [docs/audit/openrouter-api-key-support-boundary.md](docs/audit/openrouter-api-key-support-boundary.md) documents only the runtime-visible env-key proof boundary, with source-checkout workload evidence limited to the repo smoke path.
-
-**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.
-- For OpenRouter-backed source-checkout workloads, treat repo smoke-path validation as the workload proof surface, and treat read-only tool coverage as the only validated tool subset today.
-- "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
 
-### Discord setup (private server + bot)
-
-1. Create a **private Discord server** dedicated to DiscoClaw (not a shared/public server).
-2. In the [Discord Developer Portal](https://discord.com/developers/applications), create an application, then go to **Bot** -> **Add Bot**.
-3. Under **Bot** -> **Privileged Gateway Intents**, enable **Message Content Intent**.
-4. Copy the bot token and set it in `.env` as `DISCORD_TOKEN=...`.
-5. Invite the bot to your server:
-   - Go to **Installation** (left sidebar) → set **Install Link** to **Discord Provided Link**
-   - Under **Default Install Settings**, add scope `bot` under Guild Install
-   - A **Permissions** selector appears. For a private server, pick `Administrator` — it's one selection and covers everything. For tighter permissions, see the [permission profiles](docs/discord-bot-setup.md#permission-profiles-choose-intentionally) in the full guide.
-   - **Save Changes**, then open the install link, pick your server, and authorize
-6. In Discord, enable **Developer Mode** (User Settings -> Advanced), then copy IDs and set:
-   - `DISCORD_ALLOW_USER_IDS=<your user id>` (required; fail-closed if empty)
-   - `DISCORD_GUILD_ID=<server id>` (required for `pnpm release:rehearsal`; also required for auto-creating forum channels)
-
-Full step-by-step guide: [docs/discord-bot-setup.md](docs/discord-bot-setup.md)
-
-## Documentation
-
-### Getting Started
-
-- [Discord bot setup](docs/discord-bot-setup.md) — create a bot, invite it, configure permissions
-- [MCP (Model Context Protocol)](docs/mcp.md) — connect external tool servers
-
-### Features & Usage
-
-- [Memory system](docs/memory.md) — five-layer memory architecture, tuning, and troubleshooting
-- [Plan & Forge](docs/plan-and-forge.md) — autonomous planning and code generation
-- [Discord actions](docs/discord-actions.md) — channels, messaging, moderation, tasks, crons
-- [Cron / automations](docs/cron.md) — recurring task setup, advanced options, debugging
-- [Tasks](docs/tasks.md) — task lifecycle, bidirectional sync, tag maps
-- [Voice](docs/voice.md) — real-time voice chat setup (STT/TTS)
-- [Shareable recipes](docs/discoclaw-recipe-spec.md) — integration recipe format spec
-
-### Development
-
-- [Philosophy](docs/philosophy.md) — design principles and trade-offs
-- [Releasing](docs/releasing.md) — npm publish workflow and versioning
-- [Inventory](docs/INVENTORY.md) — full component inventory and MVP status
-
-### Operations
-
-- [Configuration reference](docs/configuration.md) — all environment variables indexed by category
-- [Provider/auth 1.0 matrix](docs/audit/provider-auth-1.0-matrix.md) — intended default path, supported secondary path, and the current `SUPPORTED FOR 1.0` / `PARTIAL` / `OUT OF SCOPE` verdicts for every implied provider/auth path
-- [Claude source-checkout status](CLAUDE%20SOURCE-CHECKOUT%20STATUS.md) — current closeout memo for the Claude source-checkout path, including what the latest throwaway-checkout rerun did and did not prove
-- [Claude source-checkout audit](docs/audit/claude-blank-machine-readiness.md) — current 1.0 verdict for the repo-owned `pnpm preflight*` + `pnpm claude:auth-smoke` path
-- [Claude npm-managed audit](docs/audit/claude-npm-managed-path.md) — current 1.0 verdict for `npm install -g discoclaw`, `discoclaw init`, and the daemon/runtime-path gap
-- [Codex source-checkout audit](docs/audit/codex-blank-machine-readiness.md) — current 1.0 verdict for the repo-owned `pnpm preflight*` path plus the separate Codex/OpenAI proof gates
-- [Codex npm-managed audit](docs/audit/codex-npm-managed-path.md) — current 1.0 verdict for `npm install -g discoclaw`, manual Codex login proof, optional OpenAI fast-path proof, and the daemon/runtime-path gap
-- [Managed browser launcher guide](#managed-browser-launcher) — dedicated profile flow, headed login, verified CDP handoff, and storage rules
-- [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
-
-### Install and run
-
-1. **Install globally:**
-   ```bash
-   npm install -g discoclaw
-   ```
-
-   > **Fedora 43+ / GCC 14+ — `@discordjs/opus` build failure (resolved)**
-   >
-   > This was fixed upstream in `@discordjs/opus` 0.10.0. If you are pinned to an older version, set the flag before installing:
-   > ```bash
-   > CFLAGS="-Wno-error=incompatible-pointer-types" npm install -g discoclaw
-   > ```
-
-2. **Run the interactive setup wizard** (creates `.env` and scaffolds your workspace):
-   ```bash
-   discoclaw init
-   ```
-
-3. **Register the system service:**
-   ```bash
-   discoclaw install-daemon
-   ```
-   Optional: pass `--service-name <name>` to use a custom service name (useful on macOS when running multiple instances, or to match your own naming convention):
-   ```bash
-   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).
-
-If you are validating runtime auth, keep the install mode and auth method separate:
-
-- Claude: global installs use the npm-managed path (`discoclaw init` guidance plus `discoclaw claude auth-smoke`), while source checkouts use `pnpm release:rehearsal` for the blessed full-path rehearsal or collect the same gates manually in order with `pnpm preflight:blank-machine`, `pnpm claude:auth-smoke`, `pnpm discord:smoke-test -- --guild-id <repo-local DISCORD_GUILD_ID>`, and `pnpm build`.
-- Codex from source: `pnpm preflight*` is config-only; prove the Codex session separately with `codex exec ...`, and prove any OpenAI fast/alternate path separately with `OPENAI_SMOKE_TEST_TIERS=... pnpm test`.
-- Codex from npm/global install: `discoclaw doctor` is config-only and no shipped `discoclaw codex auth-smoke` exists yet; use the same-shell `codex exec --skip-git-repo-check -- "Reply with OK"` login check, then confirm `openai-key: ok` separately if you enabled an OpenAI fast/alternate path.
-
-Current npm-managed blocker for both Claude and Codex daemon claims: `discoclaw install-daemon` still renders services with `/usr/bin/node` and a fixed service `PATH`. The interactive shell check can therefore pass while the installed daemon resolves different Node or runtime binaries.
-
-#### From source (contributors)
-
 ```bash
-git clone <repo-url> && cd discoclaw
-pnpm install --frozen-lockfile
-pnpm run setup        # guided interactive setup that writes a real clone-local .env
-# Or manually: cp .env.example .env and fill in required vars:
-#   DISCORD_TOKEN
-#   DISCORD_ALLOW_USER_IDS
-# For all ~90 options: cp .env.example.full .env
-pnpm preflight:blank-machine
-pnpm claude:auth-smoke  # if PRIMARY_RUNTIME=claude-cli, before login, from a shell/account with no active Claude session
-claude                  # if PRIMARY_RUNTIME=claude-cli, complete login in that same shell/account
-pnpm claude:auth-smoke  # if PRIMARY_RUNTIME=claude-cli, rerun after login in that same shell/account
-pnpm release:rehearsal  # blessed Claude 1.0 source-checkout rehearsal; requires repo-local .env with PRIMARY_RUNTIME=claude-cli
-codex exec -m gpt-5.4 --skip-git-repo-check --ephemeral -s read-only -- "Reply with OK"  # if PRIMARY_RUNTIME=codex-cli
-OPENAI_SMOKE_TEST_TIERS=fast pnpm test  # if any source-checkout path routes through OpenAI
-pnpm build && pnpm dev
+npm install -g discoclaw
+discoclaw init
+discoclaw install-daemon
 ```
 
-Fresh clone is not enough evidence by itself for the Claude stranger path. A source checkout still needs a real clone-local `.env`, and the first-login claim only closes when the pre-login failure, interactive `claude` login, and post-login `pnpm claude:auth-smoke` rerun all happen in the same shell/account with no active Claude session. If the host shell was already logged into Claude, the passing smoke proves only the fresh-clone post-login path. When you want stranger-run evidence from a machine with existing DiscoClaw state, isolate `DISCOCLAW_DATA_DIR`, `WORKSPACE_CWD`, `GROUPS_DIR`, and `BEADS_DIR` to throwaway paths before you claim anything about the clone.
-
-`pnpm release:rehearsal` is the blessed source-checkout entrypoint for the full Claude 1.0 operational rehearsal. Its source of truth is the checkout's own `.env`: the harness reads the repo-local file, requires `PRIMARY_RUNTIME=claude-cli`, strips repo-local persistence/config path overrides that would escape the rehearsal temp root, and then applies explicit child-process overrides for `DISCOCLAW_DATA_DIR`, `WORKSPACE_CWD`, `GROUPS_DIR`, `BEADS_DIR`, and the rehearsal task prefix. The live operator loop it holds includes the first reply, a same-conversation follow-up reply, task sync, cron execution, and restart/recovery. Fresh-clone and first-login stranger evidence are established separately by the fresh-clone QA and auth-smoke path above; the rehearsal harness accepts checkout provenance as operator context when supplied, but it does not try to prove or gate on that provenance in code.
-
-If `PRIMARY_RUNTIME=claude-cli`, run `pnpm preflight:blank-machine`, capture the separate Claude auth evidence in the order shown above, then run `pnpm discord:smoke-test -- --guild-id <repo-local DISCORD_GUILD_ID>` and `pnpm build` before `pnpm dev`, or run the full `pnpm release:rehearsal` harness once the repo-local `.env` is ready. If `PRIMARY_RUNTIME=codex-cli`, treat `pnpm preflight:blank-machine` as config/bootstrap evidence only, then capture separate Codex session-auth evidence with the `codex exec ...` prompt. If any source-checkout route uses OpenAI, capture separate `OPENAI_API_KEY` evidence with `OPENAI_SMOKE_TEST_TIERS=... pnpm test`.
-
-### Claude runtime validation
-
-Source-checkout 1.0 support status: `SUPPORTED FOR 1.0` for the repo-owned Claude path within the audited boundary: the same no-session shell or account recorded the pre-login unauthenticated result, completed interactive Claude CLI login, and then passed the post-login `pnpm claude:auth-smoke` rerun. The current closeout memo is [Claude source-checkout status](CLAUDE%20SOURCE-CHECKOUT%20STATUS.md), and the deeper audit record remains [docs/audit/claude-blank-machine-readiness.md](docs/audit/claude-blank-machine-readiness.md).
-
-Npm-managed 1.0 audit verdict: `NOT YET SUPPORT-CLAIMABLE`. The installed CLI now has a shell-level Claude check, but the daemon path still is not claimable because `discoclaw install-daemon` hardcodes `/usr/bin/node` plus a fixed service `PATH`, and `discoclaw init` does not persist `CLAUDE_BIN`. See [docs/audit/claude-npm-managed-path.md](docs/audit/claude-npm-managed-path.md).
-
-1. Create a throwaway clone, run `pnpm install --frozen-lockfile`, and supply a real clone-local `.env` (`pnpm run setup` or copy from `.env.example` / `.env.example.full`).
-2. If you are validating from a machine that already has DiscoClaw or Claude state, isolate `DISCOCLAW_DATA_DIR`, `WORKSPACE_CWD`, `GROUPS_DIR`, and `BEADS_DIR` to throwaway paths before claiming stranger-run evidence.
-3. Run the automated config/bootstrap check:
-   ```bash
-   pnpm preflight:blank-machine
-   ```
-   Optional:
-   ```bash
-   pnpm preflight:blank-machine:online
-   ```
-4. Treat the result correctly:
-   - `pnpm preflight:blank-machine` proves the local prerequisites against the current `.env` only, ignoring inherited shell env from the host machine.
-   - `pnpm preflight:blank-machine:online` adds a live Discord login/gateway-intent check on top of that same blank-machine env boundary.
-   - Plain `pnpm preflight` keeps its broader contributor-oriented behavior and can still be useful for checking the current shell environment.
-   - Neither command proves Claude login/auth state.
-5. From a shell or account with no active Claude session, run the required pre-login failure check:
-   ```bash
-   pnpm claude:auth-smoke
-   ```
-   Confirm it returns `Claude CLI appears installed but not authenticated.`
-6. Log in interactively in that same shell or account:
-   ```bash
-   claude
-   ```
-7. Rerun the happy-path check in that same shell or account:
-   ```bash
-   pnpm claude:auth-smoke
-   ```
-   Confirm it returns `Claude CLI answered the minimal prompt.`
-8. If step 7 was captured only from an already-logged-in shell or account, record that limitation and downgrade the claim to `fresh-clone post-login path only`.
-9. For the full blessed source-checkout path, run the rehearsal harness and record whether the checkout was throwaway or reused:
-   ```bash
-   pnpm release:rehearsal
-   ```
-   The harness enforces the repo-local `.env` plus explicit child-process isolation overrides, writes a closeout under `docs/release-audit/`, and treats unresolved rehearsal-owned cleanup as a blocked verdict.
-10. Start DiscoClaw after the source-checkout gates pass:
-   ```bash
-   pnpm build && pnpm dev
-   ```
-
-### Codex runtime validation
-
-Codex 1.0 support matrix:
-
-| Install mode | Config/bootstrap evidence only | Separate auth proof gates | 1.0 verdict |
-| --- | --- | --- | --- |
-| Source checkout | `pnpm preflight:blank-machine` / `pnpm preflight` prove local prerequisites only. They do not invoke Codex or OpenAI. | 1. Prove the Codex CLI session in the same shell with `codex exec -m gpt-5.4 --skip-git-repo-check --ephemeral -s read-only -- "Reply with OK"` before and after `codex` login. 2. If any source-checkout path routes through OpenAI, run `OPENAI_SMOKE_TEST_TIERS=fast pnpm test` or replace `fast` with your intended tier/model. | `PASS` for the repo-owned source path. See [docs/audit/codex-blank-machine-readiness.md](docs/audit/codex-blank-machine-readiness.md). |
-| npm / global install | `discoclaw doctor`, `!doctor`, and `discoclaw init` detection stay config-only. No shipped `discoclaw codex auth-smoke` exists yet. | 1. Run `codex exec --skip-git-repo-check -- "Reply with OK"` before and after `codex` login in the same installed shell. 2. If you enabled an OpenAI fast/alternate path, start DiscoClaw and confirm `!status` or the startup credential report shows `openai-key: ok`. | `NOT YET SUPPORT-CLAIMABLE` for the daemon path. See [docs/audit/codex-npm-managed-path.md](docs/audit/codex-npm-managed-path.md). |
-
-Do not treat `codex --version`, `OPENAI_API_KEY` presence, `pnpm preflight*`, or `discoclaw doctor` as full Codex readiness proof by themselves. Those are prerequisite/config surfaces only.
-
-## Updating
-
-DiscoClaw can check for and apply updates from inside Discord — no SSH or terminal needed.
-
-| Command | Description |
-|---------|-------------|
-| `!update` | Check if a newer version is available on npm |
-| `!update apply` | Download the update, reinstall, and restart the service |
-| `!update audit` | Show npm-managed runtime audit details |
-| `!update help` | Show usage |
-
-**Global install (from Discord):**
-
-```
-!update apply
-```
-
-**Global install (from the command line):**
-
-```bash
-npm update -g discoclaw
-discoclaw install-daemon   # re-register the service after updating
-# If you used a custom service name, pass it again:
-# discoclaw install-daemon --service-name personal
-```
-
-For Claude on npm-managed installs, keep using the installed-shell validation path after updates: rerun `discoclaw init` if you need the manual login guidance, and use `discoclaw claude auth-smoke` if you want the shipped shell-level smoke check. Do not treat `pnpm preflight*` or `pnpm claude:auth-smoke` as npm-managed evidence; those remain source-checkout-only. Re-registering the daemon also does not remove the current service-path blocker: the generated service still pins `/usr/bin/node` and a fixed `PATH`, so a passing interactive shell smoke test does not yet prove the daemon will resolve the same Node and Claude binaries.
-
-For Codex on npm-managed installs, `discoclaw doctor` remains config-only and there is still no shipped `discoclaw codex auth-smoke`. Repeat the same-shell `codex exec --skip-git-repo-check -- "Reply with OK"` login check after updates, and if you enabled an OpenAI fast/alternate path confirm the restarted instance reports `openai-key: ok`. Re-registering the daemon still does not remove the service-path blocker: the generated service pins `/usr/bin/node` and a fixed `PATH`, and init does not persist `CODEX_BIN`, so interactive shell success is not yet daemon-proof.
+You'll need a [private Discord server and bot token](docs/discord-bot-setup.md) and at least one AI runtime ([configuration reference](docs/configuration.md)).
 
 **From source:**
 
 ```bash
-git pull
-pnpm install
-pnpm build
+git clone https://github.com/DiscoClaw/discoclaw.git && cd discoclaw
+pnpm install --frozen-lockfile
+pnpm run setup
+pnpm build && pnpm dev
 ```
 
-Run `pnpm preflight` after changes to validate the automated contract again. It checks the local prerequisites Discoclaw can prove today: Node, pnpm, runtime binary presence/version, `.env` presence, env formatting, forum bootstrap eligibility, and config-doctor findings. It does not verify Codex session auth, OpenAI runtime auth, or Claude login/auth. Use `pnpm preflight:blank-machine` when you need the audit to ignore inherited shell env and inspect only the current `.env`, `pnpm preflight:blank-machine:online` if you also want a live Discord token/intents check, `pnpm claude:auth-smoke` for the Claude login/auth smoke step, and the Codex/OpenAI proof gates above for those runtime paths.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor setup including runtime validation.
 
-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.
+## Documentation
 
-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).
+**Getting started:** [Discord bot setup](docs/discord-bot-setup.md) · [Configuration](docs/configuration.md) · [MCP](docs/mcp.md)
 
-### Restart and recovery verification
+**Features:** [Memory](docs/memory.md) · [Tasks](docs/tasks.md) · [Crons](docs/cron.md) · [Voice](docs/voice.md) · [Discord actions](docs/discord-actions.md) · [Plan & Forge](docs/plan-and-forge.md) · [Browser automation](docs/browser.md) · [Recipes](docs/discoclaw-recipe-spec.md)
 
-Treat restart/recovery as a later closeout stage, not as a substitute for the source-checkout auth proof above. Record it only after the throwaway/source-checkout flow has already captured the correct Claude auth evidence and at least one normal reply. A clean restart from an already-authenticated shell does not retroactively prove the first-login stranger path.
+**Operations:** [Runtime switching](docs/runtime-switching.md) · [Dashboard](docs/dashboard-tailscale.md) · [Webhook exposure](docs/webhook-exposure.md) · [Data migration](docs/data-migration.md)
 
-If running as a systemd service, restart it:
+**Audits:** [Provider/auth matrix](docs/audit/provider-auth-1.0-matrix.md) · [Claude](docs/audit/claude-blank-machine-readiness.md) · [Codex](docs/audit/codex-blank-machine-readiness.md)
 
-```bash
-systemctl --user restart discoclaw.service
-```
-
-Then verify the recovery path in order:
-
-1. Confirm the service is back:
-   ```bash
-   systemctl --user status discoclaw.service
-   ```
-2. Inspect recent logs for a clean startup:
-   ```bash
-   journalctl --user -u discoclaw.service -n 50 --no-pager
-   ```
-3. Send a short Discord message and confirm the already-validated runtime path answers normally after restart.
-4. If a long-running reply was interrupted by the restart and `DISCOCLAW_COMPLETION_NOTIFY=1`, confirm startup recovery posts either:
-   - the persisted recovery summary text, or
-   - a generic completion notice ending with `Recovered after restart.`
-5. Keep this evidence paired with the earlier Claude validation record; restart success does not close the separate first-login stranger gate by itself.
+**Development:** [Philosophy](docs/philosophy.md) · [Releasing](docs/releasing.md) · [Inventory](docs/INVENTORY.md)
 
 ## Platform support
 
-- **All platforms** — `pnpm dev` works everywhere Node.js runs (Linux, macOS, Windows)
-- **Linux** — systemd service file provided for production deployment (see `.context/ops.md`)
-- **macOS / Windows** — use pm2, screen, or another process manager for long-running deployment; or just `pnpm dev` in a terminal
-
-> Windows is not tested for production use in v0.x. The session scanner has known path-handling issues on Windows, and the Claude CLI primarily targets Linux and macOS.
+Linux (systemd service included), macOS, Windows. Production daemon via systemd on Linux, or pm2/screen elsewhere.
 
 ## Safety
 
-DiscoClaw orchestrates powerful local tooling via AI runtimes, often with elevated permissions. Treat it like a local automation system connected to Discord.
-
-- Use a **private Discord server** — don't start in a shared or public server
-- Use **least-privilege** Discord permissions
-- Keep `DISCORD_ALLOW_USER_IDS` tight — this is the primary security boundary
-- Empty allowlist = respond to nobody (fail-closed)
-- Optionally restrict channels with `DISCORD_CHANNEL_IDS`
-- External content (Discord messages, web pages, files) is **data**, not instructions
-
-## Workspace layout
-
-The orchestrator runs AI runtimes in a separate working directory (`WORKSPACE_CWD`), keeping the repo clean while giving your assistant a persistent workspace.
-
-- Set `DISCOCLAW_DATA_DIR` to use `$DISCOCLAW_DATA_DIR/workspace` (good for Dropbox-backed setups)
-- Or leave it unset to use `./workspace` relative to the repo
-- Content (channel context, Discord config) defaults to `$DISCOCLAW_DATA_DIR/content`
-
-## Development
-
-```bash
-pnpm preflight         # automated prerequisite check; Claude auth remains manual
-pnpm preflight:blank-machine         # same check, but ignore inherited shell env and use only .env
-pnpm preflight:online  # adds live Discord login/intents validation
-pnpm preflight:blank-machine:online  # blank-machine check plus live Discord login/intents validation
-pnpm claude:auth-smoke # Claude CLI login/auth smoke check
-pnpm release:rehearsal # full Claude source-checkout release rehearsal
-pnpm dev        # start dev mode
-pnpm build      # compile TypeScript
-pnpm test       # run tests
-```
+Use a **private Discord server**, keep `DISCORD_ALLOW_USER_IDS` tight (fail-closed if empty), and use least-privilege Discord permissions. See [SECURITY.md](SECURITY.md).
 
 ## Built with
 

package/dist/config.js

@@ -704,6 +704,7 @@ export function parseConfig(env) {
             summaryTargetRatio: parseZeroToOneExclusive(env, 'DISCOCLAW_SUMMARY_TARGET_RATIO', 0.65),
             summaryDataDirOverride: parseTrimmedString(env, 'DISCOCLAW_SUMMARY_DATA_DIR'),
             summaryArchiveDirOverride: parseTrimmedString(env, 'DISCOCLAW_SUMMARY_ARCHIVE_DIR'),
+            capsuleTtlMs: parseNonNegativeInt(env, 'DISCOCLAW_CAPSULE_TTL_MS', 7_200_000),
             durableMemoryEnabled: parseBoolean(env, 'DISCOCLAW_DURABLE_MEMORY_ENABLED', true),
             durableDataDirOverride: parseTrimmedString(env, 'DISCOCLAW_DURABLE_DATA_DIR'),
             durableInjectMaxChars: parsePositiveInt(env, 'DISCOCLAW_DURABLE_INJECT_MAX_CHARS', 2000),

package/dist/discord/action-categories.js

@@ -43,12 +43,20 @@ export const QUERY_ACTION_TYPES = new Set([
     // Archive
     'archiveList',
 ]);
+// Actions that are not pure queries but still need a follow-up on success
+// because they produce data the bot needs to act on (e.g. a downloaded file).
+// Unlike QUERY_ACTION_TYPES, these also trigger follow-up on failure so the
+// bot can report the error.
+export const ALWAYS_FOLLOW_UP_TYPES = new Set([
+    'downloadAttachment',
+]);
 export function hasQueryAction(actionTypes) {
     return actionTypes.some((t) => QUERY_ACTION_TYPES.has(t));
 }
 /**
  * Returns true when a follow-up AI invocation should be triggered:
  * - any query action succeeded (to process returned data), OR
+ * - any ALWAYS_FOLLOW_UP action ran (success or failure), OR
  * - any non-query action failed (so the bot can explain the failure).
  *
  * Query action failures are excluded because there is no useful result data
@@ -58,12 +66,15 @@ export function shouldTriggerFollowUp(actions, results) {
     const anyQuerySucceeded = actions.some((a, i) => QUERY_ACTION_TYPES.has(a.type) && results[i]?.ok);
     if (anyQuerySucceeded)
         return true;
+    const anyAlwaysFollowUp = actions.some((a) => ALWAYS_FOLLOW_UP_TYPES.has(a.type));
+    if (anyAlwaysFollowUp)
+        return true;
     const anyNonQueryActionFailed = results.some((r, i) => r && !r.ok && !QUERY_ACTION_TYPES.has(actions[i]?.type ?? ''));
     return anyNonQueryActionFailed;
 }
 /**
- * Returns true when the follow-up was triggered exclusively by a non-query
- * action failure — i.e. no query action succeeded in this round.
+ * Returns true when the follow-up was triggered exclusively by a failure
+ * — i.e. no query action succeeded and no ALWAYS_FOLLOW_UP action succeeded.
  *
  * Use this to select a failure-specific placeholder message and prompt suffix
  * rather than the generic "following up..." variants.
@@ -72,6 +83,11 @@ export function isFailureFollowUp(actions, results) {
     const anyQuerySucceeded = actions.some((a, i) => QUERY_ACTION_TYPES.has(a.type) && results[i]?.ok);
     if (anyQuerySucceeded)
         return false;
+    const anyAlwaysFollowUpSucceeded = actions.some((a, i) => ALWAYS_FOLLOW_UP_TYPES.has(a.type) && results[i]?.ok);
+    if (anyAlwaysFollowUpSucceeded)
+        return false;
+    // ALWAYS_FOLLOW_UP types are not in QUERY_ACTION_TYPES, so their failures
+    // are caught here alongside regular non-query failures.
     return results.some((r, i) => r && !r.ok && !QUERY_ACTION_TYPES.has(actions[i]?.type ?? ''));
 }
 /**

package/dist/discord/capsule-invalidation.js

@@ -0,0 +1,52 @@
+/**
+ * Default TTL for continuation capsules: 2 hours.
+ * If the parent summary's updatedAt is older than this, the capsule is
+ * considered stale and should not be injected.
+ */
+export const DEFAULT_CAPSULE_TTL_MS = 2 * 60 * 60 * 1000;
+/**
+ * Patterns in `currentFocus` that indicate the capsule carries no useful
+ * state — the assistant was idle, awaiting input, or had no active task.
+ */
+const IDLE_FOCUS_PATTERNS = [
+    /^idle$/i,
+    /^none$/i,
+    /^awaiting\b/i,
+    /^waiting\b/i,
+    /^no active task/i,
+    /^n\/a$/i,
+    /^\(none\)$/i,
+    /^\(idle\)$/i,
+    /^\(awaiting\b/i,
+];
+/**
+ * Returns true when the capsule's `currentFocus` matches an idle/no-state
+ * pattern, meaning the capsule should not be injected.
+ */
+export function isCapsuleIdle(capsule) {
+    const focus = capsule.currentFocus.trim();
+    return IDLE_FOCUS_PATTERNS.some(pattern => pattern.test(focus));
+}
+/**
+ * Returns true when the parent summary's `updatedAt` exceeds the staleness
+ * threshold relative to `now`.
+ */
+export function isCapsuleExpired(updatedAt, now = Date.now(), ttlMs = DEFAULT_CAPSULE_TTL_MS) {
+    if (ttlMs <= 0)
+        return false;
+    return now - updatedAt > ttlMs;
+}
+/**
+ * Combined check: returns whether a capsule should be injected into
+ * the conversation prompt. Both idle detection and TTL expiry are
+ * evaluated; idle is checked first (cheaper).
+ */
+export function validateCapsuleForInjection(capsule, updatedAt, opts) {
+    if (isCapsuleIdle(capsule)) {
+        return { valid: false, reason: 'idle' };
+    }
+    if (isCapsuleExpired(updatedAt, opts?.now, opts?.ttlMs)) {
+        return { valid: false, reason: 'expired' };
+    }
+    return { valid: true };
+}

package/dist/discord/capsule-invalidation.test.js

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_CAPSULE_TTL_MS, isCapsuleIdle, isCapsuleExpired, validateCapsuleForInjection, } from './capsule-invalidation.js';
+function makeCapsule(currentFocus) {
+    return { currentFocus, nextStep: 'do something' };
+}
+describe('isCapsuleIdle', () => {
+    it.each([
+        'idle',
+        'Idle',
+        'IDLE',
+        'none',
+        'None',
+        'NONE',
+        'awaiting input',
+        'Awaiting user response',
+        'waiting for user',
+        'Waiting on feedback',
+        'no active task',
+        'No active task right now',
+        'n/a',
+        'N/A',
+        '(none)',
+        '(None)',
+        '(idle)',
+        '(Idle)',
+        '(awaiting input)',
+        '(Awaiting response)',
+    ])('returns true for idle focus: %s', (focus) => {
+        expect(isCapsuleIdle(makeCapsule(focus))).toBe(true);
+    });
+    it.each([
+        'Implement feature X',
+        'Debugging the parser',
+        'idling is not the same',
+        'nonetheless important',
+    ])('returns false for active focus: %s', (focus) => {
+        expect(isCapsuleIdle(makeCapsule(focus))).toBe(false);
+    });
+    it('trims whitespace before matching', () => {
+        expect(isCapsuleIdle(makeCapsule('  idle  '))).toBe(true);
+        expect(isCapsuleIdle(makeCapsule('  none  '))).toBe(true);
+    });
+});
+describe('isCapsuleExpired', () => {
+    it('returns false when within TTL', () => {
+        const now = Date.now();
+        const updatedAt = now - (DEFAULT_CAPSULE_TTL_MS - 1000);
+        expect(isCapsuleExpired(updatedAt, now)).toBe(false);
+    });
+    it('returns true when past default TTL', () => {
+        const now = Date.now();
+        const updatedAt = now - DEFAULT_CAPSULE_TTL_MS - 1;
+        expect(isCapsuleExpired(updatedAt, now)).toBe(true);
+    });
+    it('returns false at exactly the TTL boundary', () => {
+        const now = Date.now();
+        const updatedAt = now - DEFAULT_CAPSULE_TTL_MS;
+        expect(isCapsuleExpired(updatedAt, now)).toBe(false);
+    });
+    it('respects a custom ttlMs', () => {
+        const now = 100_000;
+        expect(isCapsuleExpired(90_000, now, 5_000)).toBe(true); // 10s > 5s TTL
+        expect(isCapsuleExpired(96_000, now, 5_000)).toBe(false); // 4s < 5s TTL
+    });
+    it('returns false when ttlMs is 0 (TTL disabled)', () => {
+        const now = 100_000;
+        expect(isCapsuleExpired(1, now, 0)).toBe(false);
+    });
+    it('returns false when ttlMs is negative (TTL disabled)', () => {
+        const now = 100_000;
+        expect(isCapsuleExpired(1, now, -1)).toBe(false);
+    });
+    it('DEFAULT_CAPSULE_TTL_MS is 2 hours', () => {
+        expect(DEFAULT_CAPSULE_TTL_MS).toBe(2 * 60 * 60 * 1000);
+    });
+});
+describe('validateCapsuleForInjection', () => {
+    const now = 1_000_000;
+    const freshUpdatedAt = now - 60_000; // 1 minute ago
+    it('returns valid for active, fresh capsule', () => {
+        const capsule = makeCapsule('Implementing feature X');
+        const result = validateCapsuleForInjection(capsule, freshUpdatedAt, { now });
+        expect(result).toEqual({ valid: true });
+    });
+    it('returns idle reason for idle capsule', () => {
+        const capsule = makeCapsule('idle');
+        const result = validateCapsuleForInjection(capsule, freshUpdatedAt, { now });
+        expect(result).toEqual({ valid: false, reason: 'idle' });
+    });
+    it('returns expired reason for stale capsule', () => {
+        const capsule = makeCapsule('Implementing feature X');
+        const staleUpdatedAt = now - DEFAULT_CAPSULE_TTL_MS - 1;
+        const result = validateCapsuleForInjection(capsule, staleUpdatedAt, { now });
+        expect(result).toEqual({ valid: false, reason: 'expired' });
+    });
+    it('idle takes precedence over expired', () => {
+        const capsule = makeCapsule('none');
+        const staleUpdatedAt = now - DEFAULT_CAPSULE_TTL_MS - 1;
+        const result = validateCapsuleForInjection(capsule, staleUpdatedAt, { now });
+        expect(result).toEqual({ valid: false, reason: 'idle' });
+    });
+    it('respects custom ttlMs via opts', () => {
+        const capsule = makeCapsule('Working on task');
+        const updatedAt = now - 10_000; // 10s ago
+        const result = validateCapsuleForInjection(capsule, updatedAt, { now, ttlMs: 5_000 });
+        expect(result).toEqual({ valid: false, reason: 'expired' });
+    });
+});

package/dist/discord/message-coordinator.js

@@ -19,6 +19,7 @@ import { resolveGroundedToolCapabilities } from '../runtime/tool-capabilities.js
 import { fetchMessageHistory } from './message-history.js';
 import { loadSummary, saveSummary, generateSummary, archiveSummary, recompressSummary, estimateSummaryTokens, buildConversationMemorySection, } from './summarizer.js';
 import { parseCapsuleBlock } from './capsule.js';
+import { validateCapsuleForInjection } from './capsule-invalidation.js';
 import { parseMemoryCommand, handleMemoryCommand } from './memory-commands.js';
 import { parseSecretCommand, handleSecretCommand } from './secret-commands.js';
 import { parsePlanCommand, handlePlanCommand, preparePlanRun, handlePlanSkip, closePlanIfComplete, NO_PHASES_SENTINEL, findPlanFile, looksLikePlanId, PLAN_DISABLED_NUDGE } from './plan-commands.js';
@@ -2717,6 +2718,13 @@ export function createMessageCreateHandler(params, queue, statusRef) {
                                     existingSummaryUpdatedAt = existing.updatedAt;
                                     existingSummaryRegeneratedAt = existing.regeneratedAt;
                                     existingContinuationCapsule = existing.continuationCapsule;
+                                    if (existingContinuationCapsule) {
+                                        const capsuleCheck = validateCapsuleForInjection(existingContinuationCapsule, existing.updatedAt, { ttlMs: params.capsuleTtlMs });
+                                        if (!capsuleCheck.valid) {
+                                            params.log?.info({ reason: capsuleCheck.reason, sessionKey }, 'discord:capsule skipped at injection');
+                                            existingContinuationCapsule = undefined;
+                                        }
+                                    }
                                     summarySection = buildConversationMemorySection(existingSummaryText, {
                                         turnsSinceUpdate: existing.turnsSinceUpdate,
                                         regeneratedAt: existing.regeneratedAt,

package/dist/discord/message-coordinator.test.js

@@ -450,7 +450,7 @@ describe('image input precedence — direct > reply-ref > history', () => {
     });
 });
 describe('manual message finalization guard', () => {
-    const PROMISED_ACTION_WARNING = 'Warning: this reply says Discord-managed work is starting or being handled now';
+    const PROMISED_ACTION_WARNING = 'Warning: this reply says Discord-managed work was performed or is being performed';
     beforeEach(() => {
         vi.clearAllMocks();
         resetAbortRegistry();

package/dist/discord/output-common.js

@@ -193,9 +193,11 @@ export function shouldSuppressFollowUp(processedText, actionsCount, imagesCount,
 }
 const DISCORD_ACTION_INTENT_BASE_VERBS = String.raw `create|send|edit|delete|close|open|post|react|launch|remember|forget|pin|unpin|crosspost|archive|ban|kick|timeout|set`;
 const DISCORD_ACTION_INTENT_PROGRESSIVE_VERBS = String.raw `creating|sending|editing|deleting|closing|opening|posting|reacting|launching|remembering|forgetting|pinning|unpinning|crossposting|archiving|banning|kicking|setting`;
+const DISCORD_ACTION_INTENT_PAST_VERBS = String.raw `posted|sent|edited|deleted|closed|opened|created|reacted|launched|remembered|forgot|pinned|unpinned|crossposted|archived|banned|kicked|set`;
+const DISCORD_ACTION_INTENT_PAST_PARTICIPLES = String.raw `posted|sent|edited|deleted|closed|opened|created|reacted|launched|remembered|forgotten|pinned|unpinned|crossposted|archived|banned|kicked|set`;
 const DISCORD_ACTION_INTENT_RESOURCE_NOUNS = String.raw `channel|thread|message|reply|task|plan|cron|poll|reaction|pin|user|member|nickname|status|activity|canvas|image|file|attachment|memory|preference|fact|note`;
 const DISCORD_ACTION_INTENT_NEGATION_RE = /\b(?:i have not started yet|i haven't started yet|have not started yet|haven't started yet|not started yet|i have not begun yet|i haven't begun yet|have not begun yet|haven't begun yet|i am not starting|i'm not starting|i am not doing that yet|i'm not doing that yet|not proceeding now|not handling it now)\b/i;
-const DISCORD_ACTION_INTENT_EXPLANATION_RE = /\b(?:example(?: only)?|for example|for instance|e\.g\.|i can|i could|i would|you can|you could|you would|if you want|when you're ready|would use|would emit|would send|would create|would run|do not run|don't run|not run)\b/i;
+const DISCORD_ACTION_INTENT_EXPLANATION_RE = /\b(?:example(?: only)?|for example|for instance|e\.g\.|i can|i could|i would|you can|you could|you would|if you want|if I|when you're ready|would use|would emit|would send|would create|would run|do not run|don't run|not run)\b/i;
 const DISCORD_ACTION_INTENT_PATTERNS = [
     new RegExp(String.raw `\b(?:i am|i'm)\s+(?:${DISCORD_ACTION_INTENT_PROGRESSIVE_VERBS})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b(?:[^.!?\n]{0,40}\b(?:now|already)\b)?`, 'i'),
     new RegExp(String.raw `\b(?:i am|i'm)\s+going to\s+(?:${DISCORD_ACTION_INTENT_BASE_VERBS})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b[^.!?\n]{0,40}\b(?:now|for you|in this response)\b`, 'i'),
@@ -204,6 +206,14 @@ const DISCORD_ACTION_INTENT_PATTERNS = [
     /\b(?:(?:i am|i'm)\s+)?already handling (?:it|that|this)(?: now)?\b/i,
     /\b(?:(?:i am|i'm)\s+)?taking the next pass(?: now)?\b/i,
     /\b(?:(?:i am|i'm)\s+)?cleaning(?: [^.!?\n]{0,40})? up now\b/i,
+    // Headless past — sentence-initial past verb + resource noun, no subject.
+    new RegExp(String.raw `^(?:${DISCORD_ACTION_INTENT_PAST_VERBS})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b`, 'i'),
+    // First-person past — I + past verb + resource noun.
+    new RegExp(String.raw `\bI\s+(?:${DISCORD_ACTION_INTENT_PAST_VERBS})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b`, 'i'),
+    // Perfect tense — I've / I have + past participle + resource noun.
+    new RegExp(String.raw `\b(?:I've|I have)\s+(?:${DISCORD_ACTION_INTENT_PAST_PARTICIPLES})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b`, 'i'),
+    // Done-prefix — "Done" at sentence start followed by past verb + resource noun.
+    new RegExp(String.raw `^Done\b[^a-zA-Z]{0,10}(?:${DISCORD_ACTION_INTENT_PAST_VERBS})\b[^.!?\n]{0,80}\b(?:${DISCORD_ACTION_INTENT_RESOURCE_NOUNS})s?\b`, 'i'),
 ];
 function stripCodeLikeDiscordActionText(text) {
     return text
@@ -238,7 +248,7 @@ export function buildPromisedDiscordActionWithoutExecutionNotice(visibleReplyTex
         return '';
     if (!claimsImmediateDiscordActionIntent(visibleReplyText))
         return '';
-    return 'Warning: this reply says Discord-managed work is starting or being handled now, but this turn ended with zero actionable `<discord-action>` blocks and zero executed action results. If work has not started yet, say that clearly instead.';
+    return 'Warning: this reply says Discord-managed work was performed or is being performed, but this turn ended with zero actionable `<discord-action>` blocks and zero executed action results. If work has not started yet, say that clearly instead.';
 }
 export function appendPromisedDiscordActionWithoutExecutionNotice(text, actionsCount, actionResultsCount) {
     const notice = buildPromisedDiscordActionWithoutExecutionNotice(text, actionsCount, actionResultsCount);

package/dist/discord/output-common.test.js

@@ -172,6 +172,36 @@ describe('claimsImmediateDiscordActionIntent', () => {
         expect(claimsImmediateDiscordActionIntent("I'm reading that now.")).toBe(false);
         expect(claimsImmediateDiscordActionIntent("I'm listing that now.")).toBe(false);
     });
+    it('matches headless past-tense claims (no subject)', () => {
+        expect(claimsImmediateDiscordActionIntent('Posted the plan to the channel')).toBe(true);
+    });
+    it('matches first-person past-tense claims', () => {
+        expect(claimsImmediateDiscordActionIntent('I posted the SEO plan to #website')).toBe(true);
+        expect(claimsImmediateDiscordActionIntent('I sent the message')).toBe(true);
+    });
+    it('matches perfect-tense claims', () => {
+        expect(claimsImmediateDiscordActionIntent("I've posted it to the channel")).toBe(true);
+        expect(claimsImmediateDiscordActionIntent('I have created the task')).toBe(true);
+    });
+    it('matches done-prefix past-tense claims', () => {
+        expect(claimsImmediateDiscordActionIntent('Done. Sent the message.')).toBe(true);
+        expect(claimsImmediateDiscordActionIntent('Done — posted the reply')).toBe(true);
+    });
+    it('does not match past-tense without a resource noun', () => {
+        expect(claimsImmediateDiscordActionIntent('I posted about this on my blog')).toBe(false);
+    });
+    it('does not match third-person past-tense (no "I" subject)', () => {
+        expect(claimsImmediateDiscordActionIntent('The user posted a message earlier')).toBe(false);
+    });
+    it('does not match conditional past-tense', () => {
+        expect(claimsImmediateDiscordActionIntent('If I posted the task, it would appear in the thread')).toBe(false);
+    });
+    it('does not match capability phrasing with past-tense resource nouns (regression)', () => {
+        expect(claimsImmediateDiscordActionIntent("I can post the message when you're ready")).toBe(false);
+    });
+    it('does not match example-prefixed past-tense claims', () => {
+        expect(claimsImmediateDiscordActionIntent('Example: I posted the reply')).toBe(false);
+    });
 });
 describe('buildPromisedDiscordActionWithoutExecutionNotice', () => {
     it('returns empty string when the reply does not claim immediate action intent', () => {
@@ -183,18 +213,24 @@ describe('buildPromisedDiscordActionWithoutExecutionNotice', () => {
     });
     it('returns a warning when the reply promises current work but nothing ran', () => {
         const out = buildPromisedDiscordActionWithoutExecutionNotice("I'm creating that task now.", 0, 0);
-        expect(out).toContain('Discord-managed work is starting or being handled now');
+        expect(out).toContain('Discord-managed work was performed or is being performed');
         expect(out).toContain('zero actionable `<discord-action>` blocks');
         expect(out).toContain('zero executed action results');
     });
     it('returns a warning for progress phrases the prompt guidance already forbids without actions', () => {
         const out = buildPromisedDiscordActionWithoutExecutionNotice('Taking the next pass now.', 0, 0);
-        expect(out).toContain('Discord-managed work is starting or being handled now');
+        expect(out).toContain('Discord-managed work was performed or is being performed');
     });
     it('returns empty string for generic assistant prose without Discord-action intent', () => {
         expect(buildPromisedDiscordActionWithoutExecutionNotice('Let me check that now.', 0, 0)).toBe('');
         expect(buildPromisedDiscordActionWithoutExecutionNotice("I'll show you that now.", 0, 0)).toBe('');
     });
+    it('returns a warning for a past-tense claim with zero actions/results', () => {
+        const out = buildPromisedDiscordActionWithoutExecutionNotice('I posted the plan to the channel.', 0, 0);
+        expect(out).toContain('Discord-managed work was performed or is being performed');
+        expect(out).toContain('zero actionable `<discord-action>` blocks');
+        expect(out).toContain('zero executed action results');
+    });
 });
 describe('appendPromisedDiscordActionWithoutExecutionNotice', () => {
     it('appends the warning beneath the visible reply text', () => {

package/dist/index.js

@@ -425,6 +425,7 @@ const summaryMaxChars = cfg.summaryMaxChars;
 const summaryEveryNTurns = cfg.summaryEveryNTurns;
 const summaryMaxTokens = cfg.summaryMaxTokens;
 const summaryTargetRatio = cfg.summaryTargetRatio;
+const capsuleTtlMs = cfg.capsuleTtlMs;
 const summaryDataDir = cfg.summaryDataDirOverride
     || (dataDir ? path.join(dataDir, 'memory', 'rolling') : path.join(__dirname, '..', 'data', 'memory', 'rolling'));
 const summaryArchiveDir = cfg.summaryArchiveDirOverride
@@ -1275,6 +1276,7 @@ const botParams = {
     summaryTargetRatio,
     summaryDataDir,
     summaryArchiveDir,
+    capsuleTtlMs,
     durableMemoryEnabled,
     durableDataDir,
     durableInjectMaxChars,

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "discoclaw",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Personal AI orchestrator that turns Discord into a persistent workspace",
   "license": "MIT",
+  "keywords": [
+    "discord",
+    "bot",
+    "ai",
+    "assistant",
+    "orchestrator",
+    "automation",
+    "claude",
+    "openai",
+    "memory",
+    "tasks",
+    "voice",
+    "personal-ai"
+  ],
+  "homepage": "https://discoclaw.ai",
   "repository": {
     "type": "git",
     "url": "https://github.com/DiscoClaw/discoclaw.git"