Merge remote-tracking branch 'upstream/main'

# Conflicts:
#	CHANGELOG.md

Author: NOVA

.agents/maintainer-notes/telegram.md

@@ -0,0 +1,37 @@
+# Telegram Maintainer Decisions
+
+Use this page during Telegram PR review. These are intentional maintainer decisions, not incidental implementation details.
+
+Verified against Telegram Bot API 10.0, May 8 2026.
+
+## Streaming
+
+- Do not reintroduce `sendMessageDraft` for answer streaming. Telegram drafts are ephemeral 30-second previews in private chats; final delivery still requires a separate `sendMessage`. OpenClaw uses `sendMessage` plus `editMessageText`, then finalizes in place so the user sees one persistent answer.
+- Streaming owns one visible preview message. Edit it forward. Do not send an extra final bubble unless the final edit genuinely failed.
+- Keep the first-preview debounce. If a provider sends token-sized deltas, coalesce them into cumulative preview text instead of removing the debounce.
+- Respect Telegram limits in the Telegram layer. Text over 4096 chars chains into continuation messages. Polls keep the current Bot API 12-option cap.
+
+## Telegram API Ownership
+
+- Prefer grammY primitives and Telegram-native helpers when they model the behavior directly. Avoid custom Bot API wrappers for behavior grammY already owns.
+- Throttling is bot-token scoped. All Telegram API clients for the same token share one grammY `apiThrottler()` instance.
+- Do not silently retry failed topic sends without topic metadata. A wrong-surface success is worse than a loud Telegram error.
+- DM topics and forum topics are distinct. `direct_messages_topic_id` and `message_thread_id` are not interchangeable.
+
+## Context And Authorization
+
+- Reply context comes from OpenClaw-observed messages. Bot API updates expose `reply_to_message`, but there is no arbitrary `getMessage(chat, id)` hydration path later.
+- Current local chat context must outrank stale reply ancestry in the prompt. Old replied-to messages should not look like the active conversation.
+- Pairing is DM-only. Group and topic authorization need explicit config allowlists.
+- Telegram allowlists use numeric sender IDs. Usernames are optional, mutable, and not a reliable arbitrary-user lookup key in the Bot API.
+- Group and channel visible replies are policy-controlled. Normal room replies stay private unless `messages.groupChat.visibleReplies: "automatic"` is set or the agent explicitly calls `message.send`.
+
+## Interactive Surfaces
+
+- Native callbacks stay structured. Approval, native command, plugin, select, and multiselect callbacks must not fall through as raw callback text.
+- Preserve callback values exactly, including delimiters such as `env|prod`.
+- Native slash commands should remain fast-pathable before full workspace and agent-turn setup.
+
+## Review Standard
+
+Telegram behavior PRs need real Telegram proof when they touch transport, streaming, topics, callbacks, authorization, or reply context. Prefer the bot-to-bot QA lane or an equivalent live Telegram probe over synthetic-only validation.

.agents/skills/crabbox/SKILL.md

@@ -127,6 +127,7 @@ Read the JSON summary. Useful fields:
 - `provider`: should be `blacksmith-testbox`
 - `leaseId`: `tbx_...`
 - `syncDelegated`: should be `true`
+- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`
 - `commandMs` / `totalMs`
 - `exitCode`
 
@@ -138,6 +139,62 @@ unclear:
 blacksmith testbox list
 ```
 
+## Observability Flags
+
+Use these on debugging runs before inventing ad hoc logging:
+
+- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,
+  sudo/apt, Node, pnpm, Docker, and bubblewrap. On `blacksmith-testbox`, this
+  prints a delegated-unsupported note because the workflow owns setup.
+- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct
+  providers and prints `set len=N secret=true` style summaries. On
+  `blacksmith-testbox`, env forwarding is unsupported; put secrets in the
+  Testbox workflow instead.
+- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple
+  `export NAME=value` / `NAME=value` lines from a local profile without
+  executing it, then forwards only allowlisted names. `--allow-env` is
+  repeatable and comma-separated. Profile values override ambient allowlisted
+  env values for that run.
+- `--script <file>` / `--script-stdin`: upload a local script into
+  `.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute
+  directly; scripts without a shebang run through `bash`. Arguments after `--`
+  become script args.
+- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a
+  fresh remote checkout of the GitHub PR. Bare numbers use the current repo's
+  GitHub origin. Add `--apply-local-patch` only when the current local
+  `git diff --binary HEAD` should be applied on top of that PR checkout.
+- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to
+  local files and keep binary/noisy output out of retained logs. Parent
+  directories must already exist. These are direct-provider only.
+- `--capture-on-fail`: on non-zero direct-provider exits, downloads
+  `.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,
+  `coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.
+- `--timing-json`: final machine-readable timing. Add
+  `echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell
+  commands; direct providers and Blacksmith Testbox both report them as
+  `commandPhases`.
+
+Live-provider debug template for direct AWS/Hetzner leases:
+
+```sh
+mkdir -p .crabbox/logs
+pnpm crabbox:run -- --provider aws \
+  --preflight \
+  --env-from-profile ~/.profile \
+  --allow-env OPENAI_API_KEY,OPENAI_BASE_URL \
+  --timing-json \
+  --capture-stdout .crabbox/logs/live-provider.stdout.log \
+  --capture-stderr .crabbox/logs/live-provider.stderr.log \
+  --capture-on-fail \
+  --shell -- \
+  "echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live"
+```
+
+Do not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or
+`--sync-only` to delegated providers. Also do not pass `--script*` or
+`--fresh-pr` there. Crabbox rejects these because the provider owns sync or
+command transport.
+
 ## Efficient Bug E2E Verification
 
 Use the smallest Crabbox lane that proves the reported user path, not just the
@@ -179,6 +236,11 @@ Efficient flow:
 Keep it efficient:
 
 - Reuse existing E2E scripts and helper assertions before writing ad hoc shell.
+- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead
+  of quote-heavy `--shell` strings on direct SSH providers.
+- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the
+  local dirty tree. Add `--apply-local-patch` only when testing a local fixup on
+  top of that PR.
 - Use one-shot Crabbox for a single proof; use a reusable Testbox only when
   several commands must share built images, installed packages, or live state.
 - Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a
@@ -285,7 +347,9 @@ Common Crabbox-only failures:
 - Slug/claim confusion: use the raw `tbx_...` id, or run one-shot without
   `--id`.
 - Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the
-  printed Actions URL.
+  printed Actions URL. Large sync warnings now include top source directories
+  by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect
+  those before reaching for `--force-sync-large`.
 - Cleanup uncertainty: run `blacksmith testbox list` and stop only boxes you
   created.
 - Testbox queued/capacity pressure: do not convert a broad changed gate or full
@@ -294,18 +358,19 @@ Common Crabbox-only failures:
   report the capacity blocker.
 
 If Crabbox cannot dispatch, sync, attach, or stop but Blacksmith itself works,
-use direct Blacksmith from the repo root:
+first try the same command through the repo wrapper with `--debug` and
+`--timing-json`:
 
 ```sh
-blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
-blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed"
-blacksmith testbox stop --id <tbx_id>
+pnpm crabbox:run -- --provider blacksmith-testbox --debug --timing-json -- \
+  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed
 ```
 
-Direct full suite:
+Full suite:
 
 ```sh
-blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test"
+pnpm crabbox:run -- --provider blacksmith-testbox --debug --timing-json -- \
+  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test
 ```
 
 Auth fallback, only when `blacksmith` says auth is missing:
@@ -340,16 +405,15 @@ The hydration workflow owns checkout, Node/pnpm setup, dependency install,
 secrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command
 execution, timing, logs/results, and cleanup.
 
-Minimal direct Blacksmith fallback, from repo root:
+Minimal Blacksmith-backed Crabbox run, from repo root:
 
 ```sh
-blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
-blacksmith testbox run --id <tbx_id> "env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed"
-blacksmith testbox stop --id <tbx_id>
+pnpm crabbox:run -- --provider blacksmith-testbox --timing-json -- \
+  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed
 ```
 
-Use direct Blacksmith only when Crabbox is the broken layer and Blacksmith
-itself still works. Prefer direct `blacksmith testbox list` for cleanup
+Use direct Blacksmith only when Crabbox is the broken layer and you are
+isolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup
 diagnostics, not as a reusable work queue.
 
 Important Blacksmith footguns:

.agents/skills/openclaw-debugging/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: openclaw-debugging
+description: Debug OpenClaw model, provider, tool-surface, code-mode, streaming, and live/Crabbox behavior by choosing the right logs, probes, and proof path before changing code.
+---
+
+# OpenClaw Debugging
+
+Use this skill when OpenClaw behavior differs between local tests, live models,
+providers, code mode, Tool Search, Crabbox, or CI, and the next move should be a
+debug signal rather than a guess.
+
+## Read First
+
+- `docs/logging.md` for log files, `openclaw logs`, and targeted debug flags.
+- `docs/reference/test.md` for local test commands.
+- `docs/reference/code-mode.md` for code-mode exec/wait and tool catalog rules.
+- Use `$openclaw-testing` for choosing test lanes.
+- Use `$crabbox` for broad, Docker, package, Linux, live-key, or CI-parity proof.
+
+## Default Loop
+
+1. State the suspected boundary: config, tool construction, provider payload,
+   fetch, stream/SSE, transcript replay, worker/runtime, package/dist, or CI.
+2. Add or enable the narrowest signal that proves that boundary.
+3. Reproduce with the same provider/model/config. Do not randomly switch models
+   unless the model itself is the variable being tested.
+4. Compare configured state with actual run activation.
+5. Patch the root cause.
+6. Rerun the exact failing probe, then broaden only if the contract requires it.
+
+## Model Transport Logs
+
+Use targeted env flags instead of global debug when the model request shape or
+stream timing matters:
+
+```bash
+OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
+OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway
+OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted OPENCLAW_DEBUG_SSE=peek openclaw gateway
+```
+
+Useful flags:
+
+- `OPENCLAW_DEBUG_MODEL_TRANSPORT=1`: request start, fetch response, SDK
+  headers, first SSE event, stream done, and transport errors at `info`.
+- `OPENCLAW_DEBUG_MODEL_PAYLOAD=summary`: bounded payload summary.
+- `OPENCLAW_DEBUG_MODEL_PAYLOAD=tools`: all model-facing tool names.
+- `OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted`: capped, redacted JSON payload.
+  Use only while debugging; prompts/message text may still appear.
+- `OPENCLAW_DEBUG_SSE=events`: first-event and stream-completion timing.
+- `OPENCLAW_DEBUG_SSE=peek`: first five redacted SSE events.
+- `OPENCLAW_DEBUG_CODE_MODE=1`: code-mode tool-surface diagnostics.
+
+Watch logs with:
+
+```bash
+openclaw logs --follow
+```
+
+## Common Boundaries
+
+- **Config vs activation:** config can be enabled while the run disables tools,
+  is raw, has an empty allowlist, or lacks model tool support. Check the actual
+  visible tools before enforcing provider payload invariants.
+- **Tool surface:** inspect final model-visible tool names, not only the tool
+  registry or config. Code mode means exactly `exec` and `wait` only after it
+  actually activates.
+- **Provider payload:** log fields, model id, service tier, reasoning, input
+  size, metadata keys, prompt-cache key presence, and tool names before SDK
+  call.
+- **Fetch vs SSE:** fetch response proves HTTP headers arrived; first SSE event
+  proves provider body progress. A gap here is a stream/body/provider issue, not
+  tool execution.
+- **Worker/dist:** run `pnpm build` when touching workers, dynamic imports,
+  package exports, lazy runtime boundaries, or published paths.
+- **Live keys:** check local `~/.profile` for key presence/length before saying
+  live proof is blocked. Never print secrets.
+
+## Code Pointers
+
+- Model payload + Responses stream:
+  `src/agents/openai-transport-stream.ts`
+- Guarded fetch/timing:
+  `src/agents/provider-transport-fetch.ts`
+- OpenAI/Codex provider wrappers:
+  `src/agents/pi-embedded-runner/openai-stream-wrappers.ts`
+- Tool construction, Tool Search, code-mode activation:
+  `src/agents/pi-embedded-runner/run/attempt.ts`
+- Code-mode runtime and worker:
+  `src/agents/code-mode.ts`
+  `src/agents/code-mode.worker.ts`
+- Tool Search catalog:
+  `src/agents/tool-search.ts`
+
+## Proof Choice
+
+- Single helper/payload bug: local targeted Vitest.
+- Docs/logging-only: `pnpm check:docs` and `git diff --check`.
+- Worker/dist/lazy import/package surface: targeted tests plus `pnpm build`.
+- Live provider/model behavior: same provider/model with debug flags and a real
+  key if available.
+- Docker/package/Linux/CI-parity: `$crabbox`.
+- CI failure: exact SHA, relevant job only, logs only after failure/completion.
+
+## Output Habit
+
+Report:
+
+- boundary tested
+- exact command/env shape, redacted
+- observed signal, such as tool names or first SSE event timing
+- fix location
+- narrow proof and any remaining risk

.agents/skills/openclaw-debugging/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OpenClaw Debugging"
+  short_description: "Debug model, tool, stream, and live behavior"
+  default_prompt: "Use $openclaw-debugging to identify the right OpenClaw debug boundary, turn on targeted logs, and choose the narrowest local or Crabbox proof."