claws-code 0.8.0

package/scripts/verify-wrapped.sh

@@ -0,0 +1,194 @@
+#!/usr/bin/env bash
+# Claws — verify a wrapped terminal runs in real pty mode
+#
+# End-to-end test that exercises the full path:
+#   1. Socket is live
+#   2. Create a wrapped terminal via the protocol
+#   3. Send a marker command, read it back via readLog
+#   4. Scan VS Code's Claws output log for pipe-mode warning
+#   5. Close the test terminal
+#
+# Run AFTER reloading VS Code. A successful run proves node-pty loaded
+# inside the extension host and wrapped terminals capture output correctly.
+#
+# Usage:
+#   bash ~/.claws-src/scripts/verify-wrapped.sh [project-root]
+#
+#   # Or via curl URL:
+#   bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/verify-wrapped.sh)
+
+set -eo pipefail
+
+PROJECT_ROOT="${1:-$(pwd)}"
+SOCK="$PROJECT_ROOT/.claws/claws.sock"
+
+C_RESET=$'\033[0m'; C_BOLD=$'\033[1m'
+C_GREEN=$'\033[0;32m'; C_RED=$'\033[0;31m'; C_YELLOW=$'\033[0;33m'; C_BLUE=$'\033[0;34m'; C_DIM=$'\033[2m'
+
+ok()   { printf "  ${C_GREEN}✓${C_RESET} %s\n" "$*"; }
+bad()  { printf "  ${C_RED}✗${C_RESET} %s\n" "$*"; }
+info() { printf "  ${C_DIM}%s${C_RESET}\n" "$*"; }
+h()    { printf "\n${C_BOLD}${C_BLUE}═══ %s ═══${C_RESET}\n" "$*"; }
+
+# A pure-Node client so we can parse JSON properly and handle async replies.
+# Writes commands to the socket, waits for the matching response, returns it.
+SOCK_CLIENT=$(cat <<'CLIENT_JS'
+const net = require('net');
+const sock = net.createConnection(process.argv[2]);
+const requests = JSON.parse(process.argv[3]);
+let buf = '';
+const results = [];
+let idx = 0;
+
+sock.on('connect', () => {
+  sock.write(JSON.stringify(requests[idx]) + '\n');
+});
+
+sock.on('data', (d) => {
+  buf += d.toString('utf8');
+  while (true) {
+    const nl = buf.indexOf('\n');
+    if (nl === -1) break;
+    const line = buf.slice(0, nl);
+    buf = buf.slice(nl + 1);
+    if (!line.trim()) continue;
+    let resp;
+    try { resp = JSON.parse(line); }
+    catch { results.push({ parseError: line }); break; }
+    results.push(resp);
+    idx++;
+    if (idx < requests.length) {
+      sock.write(JSON.stringify(requests[idx]) + '\n');
+    } else {
+      sock.end();
+    }
+  }
+});
+
+sock.on('error', (e) => { console.error('SOCKET ERROR:', e.message); process.exit(1); });
+sock.on('close', () => { console.log(JSON.stringify(results)); process.exit(0); });
+setTimeout(() => { console.error('TIMEOUT'); process.exit(1); }, 10000);
+CLIENT_JS
+)
+
+run_protocol() {
+  # Args: a JSON array of requests. Prints a JSON array of responses.
+  echo "$1" | xargs -0 -I{} echo "" >/dev/null  # dummy to absorb stdin
+  node -e "$SOCK_CLIENT" "$SOCK" "$1"
+}
+
+# ─── 1. Socket live? ───────────────────────────────────────────────────────
+h "1. Socket check"
+if [ ! -S "$SOCK" ]; then
+  bad "no socket at $SOCK"
+  info "the Claws extension isn't running in this project. Open the project in VS Code and reload."
+  exit 1
+fi
+list_resp=$(node -e "$SOCK_CLIENT" "$SOCK" '[{"cmd":"list"}]' 2>&1)
+if ! echo "$list_resp" | grep -q '"ok":true'; then
+  bad "socket exists but didn't respond to 'list': $list_resp"
+  exit 1
+fi
+ok "socket LIVE — extension is listening"
+term_count=$(echo "$list_resp" | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(r[0].terminals.length)")
+info "existing terminals: $term_count"
+
+# ─── 2. Create a wrapped terminal ──────────────────────────────────────────
+h "2. Create wrapped terminal"
+create_resp=$(node -e "$SOCK_CLIENT" "$SOCK" '[{"cmd":"create","name":"verify-pty","wrapped":true,"show":false}]' 2>&1)
+if ! echo "$create_resp" | grep -q '"ok":true'; then
+  bad "create failed: $create_resp"
+  exit 1
+fi
+TERM_ID=$(echo "$create_resp" | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(r[0].id)")
+WRAPPED=$(echo "$create_resp" | node -e "const r=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(r[0].wrapped)")
+ok "created terminal id=$TERM_ID wrapped=$WRAPPED"
+if [ "$WRAPPED" != "true" ]; then
+  bad "created terminal is NOT wrapped — verification cannot continue"
+  exit 1
+fi
+
+# ─── 3. Wait for shell prompt, send marker, read back ──────────────────────
+h "3. Send → readLog round trip"
+info "waiting 2s for shell to initialize..."
+sleep 2
+
+MARKER="CLAWS_VERIFY_$(date +%s)_$$"
+send_req=$(node -e "console.log(JSON.stringify([{cmd:'send',id:'$TERM_ID',text:'echo $MARKER',newline:true}]))")
+send_resp=$(node -e "$SOCK_CLIENT" "$SOCK" "$send_req" 2>&1)
+if ! echo "$send_resp" | grep -q '"ok":true'; then
+  bad "send failed: $send_resp"
+  exit 1
+fi
+ok "sent: echo $MARKER"
+
+info "waiting 2s for command to run..."
+sleep 2
+
+read_req=$(node -e "console.log(JSON.stringify([{cmd:'readLog',id:'$TERM_ID',strip:true,limit:16384}]))")
+read_resp=$(node -e "$SOCK_CLIENT" "$SOCK" "$read_req" 2>&1)
+BYTES=$(echo "$read_resp" | node -e "try{const r=JSON.parse(require('fs').readFileSync(0,'utf8'));console.log(r[0].bytes||'')}catch{console.log('')}")
+
+if echo "$BYTES" | grep -q "$MARKER"; then
+  ok "marker '$MARKER' found in readLog output — pty capture is working"
+  info "readLog last 3 lines:"
+  echo "$BYTES" | tail -3 | sed 's/^/      /'
+else
+  bad "marker NOT found in readLog output"
+  info "this usually means:"
+  info "  - the wrapped terminal is in pipe-mode (node-pty not loaded)"
+  info "  - OR the shell didn't have time to run echo (rare — unlikely after 2s)"
+  info "  - OR readLog is pulling from a different source (file vs ring buffer)"
+  info "received bytes (first 300 chars):"
+  echo "${BYTES:0:300}" | sed 's/^/      /'
+fi
+
+# ─── 4. Scan VS Code's Claws log for pipe-mode warning ─────────────────────
+h "4. Pipe-mode warning scan"
+LOGROOT="$HOME/Library/Application Support/Code/logs"
+if [ ! -d "$LOGROOT" ]; then
+  info "no VS Code logs dir at $LOGROOT — skipping"
+else
+  # Find the most recent Claws output log across all VS Code session dirs
+  latest_log=$(find "$LOGROOT" -name "1-Claws.log" -type f 2>/dev/null | xargs ls -t 2>/dev/null | head -1)
+  if [ -n "$latest_log" ] && [ -f "$latest_log" ]; then
+    info "log: $latest_log"
+    # Check ONLY entries from the current hour — older pipe-mode mentions
+    # may be stale from pre-fix sessions and don't indicate current breakage
+    recent_pipemode=$(grep "pipe-mode" "$latest_log" 2>/dev/null | tail -5)
+    if [ -n "$recent_pipemode" ]; then
+      bad "pipe-mode mentions found in Claws log:"
+      echo "$recent_pipemode" | sed 's/^/      /'
+      info "if these are from BEFORE your last reload, they're stale. Check timestamps."
+      info "if they're recent, node-pty still isn't loading in the extension host:"
+      info "    bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/rebuild-node-pty.sh)"
+    else
+      ok "no pipe-mode mentions in this session's log"
+      # Also check for the positive signal
+      if grep -q "activating (typescript)" "$latest_log" 2>/dev/null; then
+        ok "extension activated with v0.4 TypeScript bundle"
+      fi
+    fi
+  else
+    info "no Claws log found — extension may not have logged yet"
+  fi
+fi
+
+# ─── 5. Clean up the test terminal ─────────────────────────────────────────
+h "5. Cleanup"
+close_req=$(node -e "console.log(JSON.stringify([{cmd:'close',id:'$TERM_ID'}]))")
+node -e "$SOCK_CLIENT" "$SOCK" "$close_req" >/dev/null 2>&1 || true
+ok "closed test terminal id=$TERM_ID"
+
+# ─── Summary ──────────────────────────────────────────────────────────────
+echo ""
+if echo "$BYTES" | grep -q "$MARKER"; then
+  printf "${C_GREEN}${C_BOLD}VERIFICATION PASSED${C_RESET}\n"
+  echo "  Wrapped terminals are capturing output — node-pty is working."
+  echo "  TUI apps (claude, vim, htop) will render cleanly."
+else
+  printf "${C_RED}${C_BOLD}VERIFICATION FAILED${C_RESET}\n"
+  echo "  Wrapped terminal did not echo the marker back through readLog."
+  echo "  Next step: bash <(curl -fsSL https://raw.githubusercontent.com/neunaha/claws/main/scripts/rebuild-node-pty.sh)"
+  exit 1
+fi

package/templates/CLAUDE.global.md

@@ -0,0 +1,135 @@
+<!-- CLAWS-GLOBAL:BEGIN -->
+## Claws — Machine-Wide Terminal Policy (v{VERSION}) · npm: claws-code
+
+Claws may be installed in the current project. The trigger is the file `.claws/claws.sock` in the project root — if it exists, the rest of this section applies. If it does not, this section is inert.
+
+### What is already running for you
+
+When you start a session in a Claws project, several things happen automatically before your first message. You do not need to spawn or arm any of them yourself:
+
+- **MCP server** (`mcp__claws__*` tools) is registered via `.mcp.json` and exposes the full Claws API.
+- **Sidecar** (`stream-events.js --auto-sidecar`) is spawned by the SessionStart hook, streaming every bus event into `.claws/events.log`.
+- **Hooks** in `~/.claude/settings.json` watch your tool calls: a Monitor gate on spawn-class MCP calls, an orphan-cleanup PostToolUse hook, a `--no-verify` block on Bash, and a Stop hook that kills the sidecar at session end.
+
+You should treat these as part of the runtime — do not respawn them, do not kill them.
+
+### The simple path: `/claws-do`
+
+For most work, run `/claws-do "<task>"`. It classifies the task into one of four buckets and runs the right tool:
+
+1. **One-shot shell** — `claws_exec(command, …)` for quick captures.
+2. **Single Claude task** — `claws_worker(name, mission)` for anything that needs a TUI Claude session.
+3. **Parallel fleet** — `claws_fleet(workers=[…])` for independent jobs that can run in parallel.
+4. **Wave with LEAD** — multi-role wave army for coordinated multi-worker missions.
+
+`/claws-status` shows live terminal + lifecycle state. `/claws-help` lists every command and tool.
+
+Each entry-point command (`/claws-do`, `/claws`, `/claws-fix`) includes a MANDATORY
+cold-start sequence at its top — read it before deliberating.
+
+### Terminal hygiene (non-negotiable)
+
+- **NEVER use Bash for long-lived processes** — servers, watchers, REPLs, builds. Use `claws_create` + `claws_send`, or let `claws_worker` / `claws_fleet` do it for you.
+- **ALWAYS create wrapped terminals** (`wrapped: true` is the default — leave it on). Wrapped terminals capture every pty byte to a log; unwrapped terminals are invisible to `claws_read_log`.
+- **ALWAYS close terminals you create.** Either via `claws_done()` from inside the worker (preferred), or `claws_close(id)` from the orchestrator at cleanup.
+- **NEVER touch terminals you did not create.**
+- **NEVER run Claude headless** (`claude -p "…"`). Workers must be visible TUI sessions launched via `claws_worker` or by sending `claude --dangerously-skip-permissions` into a wrapped terminal.
+
+### Workers boot themselves — do not run the send sequence manually
+
+`claws_worker(mission=…)` and `claws_fleet(workers=[…])` run the full boot sequence internally: create wrapped terminal → launch `claude --model … --dangerously-skip-permissions` → wait for the prompt to settle (detected by `❯` + `cost:$` stable for 3 polls) → bracketed-paste the mission → submit. Boot waits default to 25 s.
+
+You do **not** call `claws_create` + `claws_send` to boot workers manually. That sequence is automated.
+
+`claws_worker` and `claws_fleet` use a **mode-aware** detach default:
+- Mission-mode (you pass `mission=…`) → `detach: true` by default. The call returns immediately with `terminal_id` + `correlation_id` and a copy-pasteable `monitor_arm_command`. Poll completion with `claws_workers_wait(terminal_ids=[…])`.
+- Command-mode (you pass `command=…` instead) → `detach: false` by default. The call blocks until the command exits.
+- Override with `detach: true|false` if needed.
+
+`claws_fleet` always defaults to detach unless you pass `detach: false` explicitly.
+
+### Worker completion — five layers, `claws_done()` is primary
+
+Every worker mission must end with these final actions, in order:
+
+```
+F1 (Bash):    git status --short                       — verify state
+F2 (Bash):    git log --oneline -5                     — verify commits
+F3 (MCP):     claws_done()                             — PRIMARY, REQUIRED
+F4 (Bash):    printf '%s\n' '__CLAWS_DONE__'           — pty-byte backup
+F5 (chat):    end final message with __CLAWS_DONE__    — last-resort backup
+```
+
+`claws_done()` reads `CLAWS_TERMINAL_ID` from the worker's environment (set by the extension at spawn), publishes `system.worker.completed` with `marker:'__CLAWS_DONE__'`, and closes the terminal. Zero arguments. That is the entire signal — you do not need `claws_publish` for completion.
+
+The marker the server recognizes is **`__CLAWS_DONE__`** and only that string. No other marker variant is recognized.
+
+If a worker exits without firing F3 or F4, VS Code's `onDidCloseTerminal` triggers the Wave D fallback: the extension publishes `system.worker.terminated`, which the MCP server upgrades to `system.worker.completed` with `completion_signal:'terminated'`. So a worker that just dies still gets accounted for — but `claws_done()` is the canonical path and what `/claws-do` and the prompt templates teach.
+
+### Monitor — sidecar streams, per-worker filters
+
+The sidecar is already running and writing every bus event to `.claws/events.log`. The PreToolUse hook gates spawn-class MCP calls (`claws_create`, `claws_worker`, `claws_fleet`, `claws_dispatch_subworker`) and refuses if no Monitor process is detected — there is a 5 s grace from the first call.
+
+The hook accepts either of these patterns:
+- `pgrep -f 'stream-events\.js'` — the canonical bus subscription (preferred)
+- `pgrep -f 'tail.*\.claws/events\.log'` — legacy `tail -F` fallback (still works)
+
+Per-worker observation: every spawn response includes a `monitor_arm_command` string. Copy-paste it into a `Monitor(...)` call:
+
+```
+Monitor(command="node <claws-bin>/stream-events.js --wait <correlation_id>",
+        description="claws monitor | term=<id>", timeout_ms=600000, persistent=false)
+```
+
+`stream-events.js --wait <correlation_id>` filters the bus stream to one worker and self-exits on `system.worker.completed`. SIGPIPE-safe, no SIGURG kill — unlike `tail -F | grep`, which the supervisor will kill within ~30 s of inactivity.
+
+### Lifecycle (full session phase machine)
+
+```
+{LIFECYCLE_PHASES}
+```
+
+`SESSION-BOOT` and `SESSION-END` are session-boundary phases (server-internal). Workers report a 9-phase subset: `PLAN → SPAWN → DEPLOY → OBSERVE → RECOVER → HARVEST → CLEANUP → REFLECT`, plus `FAILED` as an off-path terminal state. `FAILED` exits to `CLEANUP` or `SESSION-END`; `failure_cause` (with optional `recovery_hint`) is preserved across recovery.
+
+### Wave Discipline (Wave Army sub-workers only)
+
+If you receive a Wave Army mission, you are a sub-worker. You MUST:
+
+1. **Register** — call `claws_hello` with `waveId` and `subWorkerRole` within 60 s of boot. (`capabilities: ['push']` is auto-granted as of v0.7.13 — passing it is now optional but harmless.)
+2. **Boot event** — publish `wave.<waveId>.<role>.boot` immediately after hello.
+3. **Heartbeat every 20 s** — publish `worker.<peerId>.heartbeat` (use the `peerId` returned by `claws_hello`, NOT the role name — only `worker.<peerId>.*` topics reset the server's 25 s violation timer).
+4. **Phase events** — publish `worker.<peerId>.phase` on every transition.
+5. **Error events** — publish `worker.<peerId>.event` with `kind=ERROR` for any blocking failure; never silently swallow.
+6. **No `--no-verify`** — every commit must pass pre-commit hooks. The Bash hook hard-blocks `--no-verify` and `--no-gpg-sign`.
+7. **Full suite before commit** — `npm test` (or equivalent) must be green.
+8. **Type-check after `.ts` edits** — `npx tsc --noEmit` must report zero errors.
+9. **Complete event** — publish `wave.<waveId>.<role>.complete` as the absolute final act before printing the role sentinel (the LEAD waits on this).
+
+### Worker binary
+
+By default, workers spawn `claude`. If the user wants a different binary
+(common for teams using multiple Claude accounts via shell aliases like
+`claude-neu`, `claude-anish`), recognize the natural-language pattern:
+
+- "use claude-neu for workers" / "switch to claude-neu" → call `claws_set_bin(name: "claude-neu")`
+- "reset the worker binary" / "go back to claude" → call `claws_set_bin()` (no args)
+- "what binary are workers using?" → call `claws_get_bin()`
+
+The setting is per-project, persisted in `.claws/claude-bin` (gitignored), and
+takes effect immediately — next worker spawn uses the new binary. No MCP
+restart, no terminal reopen.
+
+### What's automatic now (don't do these manually)
+
+- ❌ Manual sidecar spawn — the SessionStart hook does it.
+- ❌ Manual peer registration before publishing — `claws_done` and other helpers do it for you when needed.
+- ❌ Passing `capabilities: ['push']` to `claws_hello` — auto-granted.
+- ❌ Running `claws_create` + `claws_send` to boot Claude in a worker — `claws_worker` / `claws_fleet` do the full sequence.
+- ❌ Choosing a marker string per worker — always `__CLAWS_DONE__`.
+- ❌ Polling `tail -F` for completion — use the per-worker `monitor_arm_command` from the spawn response.
+- ❌ Closing your own terminal at the end — `claws_done()` does it.
+
+### If `.claws/claws.sock` does not exist
+
+No Claws server is running for this project. Use standard tools (Bash, Edit, Write). Nothing in this section applies.
+<!-- CLAWS-GLOBAL:END -->

package/templates/CLAUDE.project.md

@@ -0,0 +1,37 @@
+<!-- CLAWS:BEGIN -->
+## Claws — {PROJECT_NAME} (v{VERSION}) · npm: claws-code
+
+The Claws MCP server is running at `{SOCKET_PATH}`. Machine-wide invariants (boot sequence, completion convention, Monitor pattern, lifecycle phases, Wave Discipline) live in `~/.claude/CLAUDE.md` — do not duplicate them here.
+
+### Where to start
+
+- **`/claws-do "<task>"`** — daily driver. Auto-classifies into shell / worker / fleet / wave.
+- **`/claws-status`** — live terminal table + lifecycle state.
+- **`/claws-help`** — full command + tool reference.
+
+### MCP tools available ({TOOLS_COUNT})
+
+{TOOLS_LIST}
+
+### Slash commands ({CMDS_COUNT})
+
+{CMDS_LIST}
+
+### Lifecycle phases
+
+```
+{LIFECYCLE_PHASES}
+```
+
+(Workers report a 9-phase subset — see `~/.claude/CLAUDE.md` for details.)
+
+### Reminders
+
+- Workers boot themselves via `claws_worker` / `claws_fleet` — do not run the send sequence manually.
+- Completion is `claws_done()` (zero-arg, F3 of the five-layer convention).
+- Marker recognized by the server: `__CLAWS_DONE__` only.
+- `claws_fleet` and `claws_worker` are non-blocking by default in mission mode (LH-14.1) — poll via `claws_workers_wait`.
+- Worker binary: defaults to `claude`. Override with `/claws-bin <name>` or write to `.claws/claude-bin`.
+
+See `~/.claude/CLAUDE.md` for the complete invariant policy.
+<!-- CLAWS:END -->