tide-watch

OpenClaw 的主动会话容量监控和管理。通过在可配置阈值（75%、85%、90%、95%）处发出警告、在重置之前自动备份会话以及管理会话恢复提示来防止上下文窗口锁定。在处理长期运行的项目、管理多个对话渠道（Discord、Telegram、网络聊天）或防止完整上下文窗口丢失工作时使用。包括用于容量检查、跨会话仪表板、存档管理和会话恢复的 CLI 工具。支持任何模型或提供商。

## 概述（中文）

OpenClaw 的主动会话容量监控和管理。通过在可配置阈值（75%、85%、90%、95%）处发出警告、在重置之前自动备份会话以及管理会话恢复提示来防止上下文窗口锁定。在处理长期运行的项目、管理多个对话渠道（Discord、Telegram、网络聊天）或防止完整上下文窗口丢失工作时使用。包括用于容量检查、跨会话仪表板、存档管理和会话恢复的 CLI 工具。支持任何模型或提供商。

## 原文

# Tide Watch 🌊

Proactive session capacity monitoring for OpenClaw.

## ⚠️ Security & Architecture Notice

**Tide Watch is a HYBRID SKILL with two operational modes:**

### Mode 1: Directives-Only (Recommended for Most Users)
**Description:** AGENTS.md and HEARTBEAT.md directives only  
**Code Execution:** **NONE** - Uses OpenClaw's built-in tools only (no CLI installation)  
**File Access:** Reads OpenClaw session files via agent's built-in tools  
**Installation:** Copy template directives to workspace config files  
**Security:** Lowest risk - no code installation or execution required

**What it does:**
- ✅ Monitors session capacity via `session_status` tool
- ✅ Warns at thresholds (75%, 85%, 90%, 95%)
- ✅ Auto-loads resumption prompts on session reset
- ✅ All operations through OpenClaw's native tools

### Mode 2: CLI Tools (Optional)
**Description:** Node.js command-line tools for manual management  
**Code Execution:** **YES** - Executable JavaScript code  
**File Access:** Direct read/write to `~/.openclaw/agents/main/sessions/`  
**Installation:** `git clone` + `npm link` (requires Node.js)  
**Security:** Moderate risk - requires code inspection before install

**What it does:**
- CLI commands: `tide-watch status`, `tide-watch dashboard`, etc.
- Manual capacity checks
- Session archive management
- Resumption prompt editing (⚠️ see CVE-2026-001 below)

### Mode Comparison

| Feature | Directives-Only | CLI Tools |
|---------|-----------------|-----------|
| **Node.js required?** | ❌ No | ✅ Yes (14+) |
| **Installation** | Copy templates | `npm link` |
| **Code execution** | ❌ None | ✅ JavaScript |
| **File access** | Via built-in tools | Direct filesystem |
| **Security risk** | Lowest | Moderate |
| **Use case** | Passive monitoring | Active management |

**Choose Directives-Only if:** You only need capacity warnings and resumption prompts.  
**Choose CLI Tools if:** You need manual session management, archiving, or dashboard views.

### 🚨 CRITICAL SECURITY NOTICE: CVE-2026-001

**Vulnerability:** Shell injection in `editResumePrompt` function  
**Affected Version:** v1.0.0 ONLY  
**Current Version:** v1.0.1 (PATCHED)  
**Severity:** HIGH (CVSS 7.8)  
**Status:** ✅ FIXED

**Summary:** v1.0.0 contained a shell injection vulnerability in the CLI's `resume-prompt edit` command. An attacker who could control the `--session` parameter could execute arbitrary commands. **This has been fixed in v1.0.1** by replacing `execSync` with `spawnSync`.

**If you installed v1.0.0:** **Update immediately** to v1.0.1.

**Full disclosure:** See [SECURITY-ADVISORY-CVE-2026-001.md](./SECURITY-ADVISORY-CVE-2026-001.md)

### Security Best Practices

**For Directives-Only Mode (Safest):**
1. ✅ Copy AGENTS.md.template and HEARTBEAT.md.template to workspace
2. ✅ No code installation required
3. ✅ No npm dependencies
4. ✅ Lowest security surface

**For CLI Tools Mode (If Needed):**
1. ⚠️ **Verify version 1.0.1 or later** (`tide-watch --version`)
2. ⚠️ **Inspect code before installing:**
   - Review `lib/capacity.js` and `lib/resumption.js`
   - Check `package.json` for install hooks (should have none)
   - Run `npm test` to verify behavior (113 tests)
3. ⚠️ **Only use UUID session IDs** with `--session` flag
4. ⚠️ **Avoid untrusted input** to CLI commands
5. ⚠️ **Review backups location** (`~/.openclaw/agents/main/sessions/archive/`)

**Operation Types:**

**Read-Only Operations** (✅ Safe, no modifications):
- `tide-watch status` - Check current session count
- `tide-watch check --session <id>` - View specific session capacity
- `tide-watch check --current` - Auto-detect and check current session (v1.3.4+)
- `tide-watch dashboard` - Visual capacity overview
- `tide-watch dashboard --watch` - Live updating dashboard
- `tide-watch dashboard --raw-size` - Show full precision token counts (v1.3.2+)
- `tide-watch report` - List sessions above threshold
- `tide-watch resume-prompt show --session <id>` - View resumption prompt

**Modifying Operations** (⚠️ Moves/creates files):
- `tide-watch archive --older-than <time>` - Moves sessions to archive/ (time-based)
- `tide-watch archive --session <id>` - Archive specific session (v1.3.3+)
- `tide-watch archive --session <id1> --session <id2>` - Archive multiple sessions (v1.3.3+)
- `tide-watch resume-prompt edit --session <id>` - Opens editor (CVE patched in v1.0.1)
- `tide-watch resume-prompt delete --session <id>` - Deletes resumption prompt file

**New Flags (v1.3.2+):**
- `--raw-size` - Show full precision token counts (e.g., `18,713/128,000` instead of `18.7k/128k`)
- `--current` - Auto-detect current session via `OPENCLAW_SESSION_ID` environment variable (v1.3.4+)
- `--session` (enhanced) - Supports partial IDs, multiple sessions for archive, labels/channels (v1.3.3+)

**File System Access:**
- Reads: `~/.openclaw/agents/main/sessions/*.jsonl` (session data)
- Writes: `~/.openclaw/agents/main/sessions/resume-prompts/*.md` (resumption prompts)
- Moves: `~/.openclaw/agents/main/sessions/archive/` (archived sessions)

**Network Activity:** **NONE** - All operations are local filesystem only.

### CLI Reference

**Complete flag and option documentation:**

**Display Options:**
- `--raw-size` - Show full precision token counts with commas (v1.3.2+)
  - Default: Human-readable (e.g., `18.7k/128k`, `20.6k/1M`)
  - With flag: Full precision (e.g., `18,713/128,000`, `20,631/1,000,000`)
  - Use case: When exact token counts needed
  - Example: `tide-watch dashboard --raw-size`

- `--json` - Output as JSON instead of formatted table
  - Example: `tide-watch check --session abc123 --json`
  - Useful for scripting and parsing

- `--pretty` - Pretty-print JSON output (requires `--json`)
  - Example: `tide-watch report --json --pretty`

**Session Selection:**
- `--session <key>` - Target specific session (enhanced in v1.3.3+)
  - Full UUID: `--session 17290631-42fe-40c0-bd23-c5da511c6f7b`
  - Partial UUID: `--session 17290631-4` (v1.3.3+)
  - Label: `--session "#navi-code-yatta"` (v1.3.3+)
  - Channel: `--session discord` (v1.3.3+)
  - Channel + label: `--session "discord/#navi-code"` (v1.3.3+)
  - Multiple (archive only): `--session abc123 --session def456` (v1.3.3+)

- `--current` - Auto-detect current session (v1.3.4+)
  - Requires: `OPENCLAW_SESSION_ID` environment variable
  - Example: `tide-watch check --current`
  - Use case: Heartbeat monitoring (check THIS session)
  - Fallback: Graceful error with helpful message if env var not set

**Filtering:**
- `--all` - Show all sessions regardless of capacity
- `--threshold <num>` - Filter sessions above percentage (default: 75)
- `--active <hours>` - Only show sessions active within N hours
- `--agent <id>` - Filter to specific agent (multi-agent setups)
- `--exclude-agent <id>` - Exclude specific agent (can use multiple times)

**Archive Options:**
- `--older-than <time>` - Archive sessions older than time
  - Examples: `4d`, `2w`, `1mo`, `3months`
  - Mutually exclusive with `--session`
  
- `--dry-run` - Preview archive without making changes
  - Example: `tide-watch archive --older-than 7d --dry-run`

- `--exclude-channel <name>` - Exclude channel from archiving
  - Example: `tide-watch archive --older-than 30d --exclude-channel discord`

- `--min-capacity <num>` - Only archive sessions below capacity threshold
  - Example: `tide-watch archive --older-than 7d --min-capacity 50`

**Live Monitoring:**
- `--watch` - Live updating dashboard (refreshes every 10s)
  - Example: `tide-watch dashboard --watch`
  - Press Ctrl+C to exit

**Multi-Agent:**
- `--all-agents` - Multi-agent discovery mode (default, auto-discovers agents)
- `--single-agent-only` - Single-agent mode (main agent only)

**Configuration Override:**
- `--refresh-interval <seconds>` - Dashboard refresh interval