chore: promote staging to staging-promote/8b629851-24041939370 (2026-04-07 00:16 UTC)

.claude/rules/skills.md

@@ -31,16 +31,19 @@ activation:
   tags:
     - "devops"
   max_context_tokens: 2000
-metadata:
-  openclaw:
-    requires:
-      bins: [docker, kubectl]
-      env: [KUBECONFIG]
+requires:
+  bins: [docker, kubectl]
+  env: [KUBECONFIG]
 ---
 
 # Skill instructions here...
 ```
 
+Only the top-level `requires:` block is supported. The legacy nested shape
+`metadata.openclaw.requires` is unsupported and ignored by the current parser,
+so older external skills must be migrated instead of relying on silent
+compatibility.
+
 ## Selection Pipeline
 
 1. **Gating** -- Check binary/env/config requirements; skip skills whose prerequisites are missing

.claude/rules/testing.md

@@ -23,3 +23,44 @@ Run `bash scripts/check-boundaries.sh` to verify test tier gating.
 - Use `tempfile` crate for test directories, never hardcode `/tmp/`
 - Regression test with every bug fix (enforced by commit-msg hook)
 - Integration tests (`--test workspace_integration`) require PostgreSQL; skipped if DB is unreachable
+
+## Test Through the Caller, Not Just the Helper
+
+**When a helper gates a side-effecting flow, the test must go through the caller — not just the helper in isolation.**
+
+A whole class of bugs in this repo has the same shape: a wrapper function silently loses one of its inputs, and the unit test for the helper passes because it never crosses the layer where the input gets dropped.
+
+Real examples (do not let these recur):
+
+| Bug | Helper | What got lost | How a caller-level test would have caught it |
+|-----|--------|--------------|------------------------------------------------|
+| nearai/ironclaw#1948 | `McpServerConfig::has_custom_auth_header()` | Helper existed but `requires_auth()` never consulted it, so MCP triggered OAuth/DCR even with a user-set `Authorization` header | A test driving `mcp::factory::create_client_from_config()` with a header-bearing config and asserting zero OAuth-state side effects |
+| nearai/ironclaw#1921 | `derive_activation_status(ext, has_owner_binding)` | Wrapper hardcodes the underlying classifier's `has_paired` axis to `false`, even though `classify_wasm_channel_activation` takes both bools | A test driving `extensions_list_handler` against a DB with a real `channel_identities` row and asserting `Active`, not `Pairing` |
+| nearai/ironclaw#1502 | `window.open` mock `(url) => { window._lastOpenedUrl = url }` | Mock captured only the URL, silently swallowing `target` and `windowFeatures`; a regression to same-tab open would not fail | A mock capturing all three args plus an assert that `target === '_blank'` |
+
+### When the rule applies
+
+You must add a caller-level test (not just a helper-level unit test) when **all** of the following are true:
+
+1. The helper is a **predicate, classifier, or transform** whose return value gates a side effect (HTTP call, DB write, UI mutation, OAuth flow, secret read, tool execution, sandbox launch, etc.).
+2. There is **at least one wrapper or call site** between the helper and the side effect.
+3. The helper has **more than one input** *or* its caller computes any of the inputs from the surrounding context.
+
+If all three are true, a unit test on the helper alone is **not sufficient regression coverage**. You must additionally either:
+
+- Add a test that drives the call site (`*_handler`, `factory::create_*`, `manager::*`), **or**
+- Inline the helper into its single caller so there is no wrapper to silently drop an input.
+
+### Where the test belongs
+
+Most of these gaps are above unit-test scope and below e2e scope. Default to the **integration tier** (`cargo test --features integration`):
+
+- `tests/<module>_integration.rs` for Rust integration tests against the public handler/factory surface
+- `tests/multi_tenant_integration.rs` when the lost axis is per-user state
+- `tests/e2e/scenarios/test_*.py` when the lost axis is browser-visible
+
+Unit tests in `mod tests {}` are still fine for the helper itself, but they do not satisfy this rule.
+
+### Mock hygiene corollary
+
+When you mock a browser/runtime API in a test, the mock's signature must match the production call site's signature, and assertions should cover **every argument** the production code passes. A `(url) => {}` stub for a `window.open(url, target, features)` call site is a silent argument-loss bug waiting to happen.

.claude/rules/tools.md

@@ -2,6 +2,8 @@
 paths:
   - "src/tools/**"
   - "tools-src/**"
+  - "src/channels/**"
+  - "src/cli/**"
 ---
 # Tool Architecture
 
@@ -37,3 +39,102 @@ impl Tool for MyTool {
     fn requires_sanitization(&self) -> bool { true } // External data
 }
 ```
+
+## Everything Goes Through Tools
+
+**All actions originating from any non-agent caller — gateway handlers, CLI
+commands, routine engine, WASM channels, future channel extensions — MUST
+go through `ToolDispatcher::dispatch()`, never directly through the
+database, workspace, or domain managers.**
+
+This is the core design principle behind #2049. The reasons are concrete:
+
+1. **Audit trail.** Every dispatched call creates an `ActionRecord` linked
+   to a system job, so UI-initiated mutations are visible in job history
+   alongside agent-initiated ones. Direct DB calls bypass this entirely.
+2. **Safety pipeline parity.** The dispatcher runs the same pipeline as
+   `Worker::execute_tool`: parameter normalization, schema validation,
+   `sensitive_params()` redaction, per-tool timeout, output sanitization.
+   Direct calls skip all of it and risk leaking secrets into logs or
+   persisting unsafe content.
+3. **Channel-agnostic.** Channels are interchangeable extensions (gateway,
+   CLI, telegram, WASM, future custom channels). Routing through a single
+   dispatch function means new channels inherit the full pipeline for free.
+4. **Agent parity.** The agent can do anything channels can do (and vice
+   versa), because both call the same tools. No more "the UI can install
+   extensions but the agent can only list them" gaps.
+
+### Required pattern
+
+```rust
+// In any gateway handler, CLI command, or routine engine callback:
+use crate::tools::dispatch::{DispatchSource, ToolDispatcher};
+
+let dispatcher: &ToolDispatcher = state
+    .tool_dispatcher
+    .as_ref()
+    .ok_or((StatusCode::SERVICE_UNAVAILABLE, "dispatcher unavailable"))?;
+
+let output = dispatcher
+    .dispatch(
+        "memory_write",
+        serde_json::json!({ "target": path, "content": content }),
+        &user.user_id,
+        DispatchSource::Channel("gateway".into()),
+    )
+    .await
+    .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
+```
+
+### Forbidden pattern
+
+```rust
+// DO NOT do this in a gateway handler, CLI command, or routine callback:
+let store = state.store.as_ref().ok_or(...)?;
+store.set_setting(&user.user_id, &key, &value).await?;  // BYPASSES dispatch
+
+let workspace = resolve_workspace(&state, &user).await?;
+workspace.write(path, content).await?;  // BYPASSES dispatch + safety pipeline
+
+let ext_mgr = state.extension_manager.as_ref().ok_or(...)?;
+ext_mgr.install(name, url, kind, &user.user_id).await?;  // BYPASSES audit trail
+```
+
+### When direct access IS allowed
+
+The dispatch principle applies to **non-agent callers** acting on behalf of
+a user. These are exempt:
+
+| Layer | Why exempt |
+|---|---|
+| `Worker::execute_tool()` (agent loop) | Has its own atomic sequence-numbered audit trail; the dispatcher would conflict |
+| `EffectBridgeAdapter::execute_action()` (v2 engine) | Same — its own audit via `ThreadEvent` event sourcing |
+| The tool implementations themselves | Tools are the leaves; they need direct `Workspace`, `Database`, etc. handles to do their work |
+| Background jobs (scheduler, hygiene, mission runner) inside the engine | These ARE the engine; they emit their own events |
+| Pure read endpoints that need to JOIN/aggregate from multiple sources | A single tool call cannot express "list all jobs across users with filters X, Y, Z" — these are queries, not actions, and the audit value is low |
+
+### Annotating intentional exceptions
+
+If a handler legitimately needs direct access (rare — usually only for
+read aggregation), suppress the pre-commit check with a trailing comment
+on the offending line:
+
+```rust
+let rows = state.store.list_agent_jobs().await?; // dispatch-exempt: read-only aggregation
+```
+
+The pre-commit hook (`scripts/pre-commit-safety.sh`) flags any newly
+added line in `src/channels/web/handlers/*.rs` or `src/cli/*.rs` that
+touches `state.{store,workspace,workspace_pool,extension_manager,
+skill_registry,session_manager}.*` without a trailing
+`// dispatch-exempt: <reason>` comment on the same line. The check only
+looks at added lines (`+` lines in the diff), so existing untouched code
+doesn't trip it during incremental migration.
+
+### Migration status
+
+As of #2049, `ToolDispatcher` is wired into `GatewayState` but per-handler
+migration is incomplete. New handlers MUST use the dispatcher. Existing
+handlers should be migrated incrementally; each handler family
+(settings, memory, extensions, skills, routines, jobs, threads) is its
+own follow-up PR.