From f9556489d8f3a1d4231ba7453a74f1bf094662ac Mon Sep 17 00:00:00 2001 From: project7 Date: Sat, 18 Jul 2026 08:50:22 +0900 Subject: [PATCH 1/2] [#1008] docs(troubleshooting): Refresh current runtime recovery guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tie the stale entries to current behavior; no runtime changes. - Trust prompt: drop the manual `claude -p "echo ok"` pre-trust and the "QuadWork v1.14.5+ pre-trusts during project creation" wording (both removed by #975). Describe the current behavior — an onData listener auto-confirms the Claude trust prompt within ~10s of agent-terminal start (server/index.js:1182); recovery is to restart the agent so the listener re-arms. - Agent-not-receiving-messages: the chat MCP shim (server/mcp-chat-shim.js, chat_read/chat_send) is wired into each agent automatically at launch (server/index.js:502-610), not configured by hand — reword the diagnostic accordingly. Verified and preserved unchanged: the session-token / cross-origin section (#968) with the correct `quadwork_session_token` localStorage key (src/lib/sessionToken.ts:14) and WS endpoints /ws/terminal,/ws/butler (server/index.js:1735), and the reverse-proxy `trusted_dashboard_hosts` (#988) section with its remote-exposure security warnings. temp_cleanup, pm2, and non-root guidance re-confirmed accurate. No AgentChattr-restore guidance present or added. Docs-only; no runtime code, tests, package versions, legacy migration implementation, or other documents touched. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/troubleshooting.md | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index ba15d5f..e39e6a9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -6,20 +6,11 @@ Common issues and fixes, structured as **Symptom > Cause > Fix**. Searchable by ## Claude Code trust prompt blocking agents -**Symptom:** Claude Code agents hang on startup. Terminal shows "Do you trust the files in this folder?" and waits for input indefinitely. +**Symptom:** A Claude Code agent hangs on startup. Its terminal shows "Do you trust the files in this folder?" and waits for input. -**Cause:** Claude Code requires explicit directory trust before running. The `--dangerously-skip-permissions` flag skips permission prompts but does NOT skip the trust gate. +**Cause:** Claude Code requires explicit directory trust before running, and `--dangerously-skip-permissions` skips permission prompts but NOT the trust gate. QuadWork normally handles this for you: when an agent's terminal starts, a listener watches its output and auto-confirms the trust prompt within the first ~10 seconds. A hang means the prompt wasn't caught in that window (e.g. the agent was slow to render it, or was started outside the normal launch flow). -**Fix:** Pre-trust each worktree directory: - -```bash -cd /path/to/project-dev && claude -p "echo ok" -cd /path/to/project-head && claude -p "echo ok" -cd /path/to/project-re1 && claude -p "echo ok" -cd /path/to/project-re2 && claude -p "echo ok" -``` - -QuadWork v1.14.5+ automatically pre-trusts worktree directories for Claude-configured agents during project creation. If upgrading from an older version, run the commands above once. +**Fix:** Restart the agent from the QuadWork dashboard. The trust listener re-arms on the fresh terminal and answers the prompt automatically — no manual pre-trust step is required, and QuadWork no longer runs a separate `claude` pre-trust command. --- @@ -66,16 +57,15 @@ QuadWork v1.14.5+ automatically pre-trusts worktree directories for Claude-confi **Symptom:** An agent doesn't respond to chat messages. Other agents can send and receive normally. -**Cause:** PTY injection isn't delivering messages to the agent process. The agent's MCP shim may not be configured, or the agent process may not be running. +**Cause:** Messages reach agents two ways — the chat MCP shim (`server/mcp-chat-shim.js`, exposing `chat_read` / `chat_send`) and PTY injection into the agent's terminal. If the agent process isn't running, or its shim failed to start, delivery stalls. The shim is wired into each agent **automatically at launch** — it isn't configured by hand. **Fix:** 1. Check that the agent process is running: ```bash ps aux | grep -E "claude|codex|gemini" ``` -2. Verify the agent's MCP shim is configured in the project's agent settings -3. Check the agent's terminal in the QuadWork dashboard for errors -4. Restart the agent from the dashboard if needed +2. Open the agent's terminal in the QuadWork dashboard and look for MCP errors (e.g. the `chat` server failing to connect) or a stuck prompt. +3. Restart the agent from the dashboard — this relaunches its terminal and re-provisions the chat MCP shim. --- From 761e06ac5f4642e0c2aa07323073003c9510dd89 Mon Sep 17 00:00:00 2001 From: project7 Date: Sat, 18 Jul 2026 08:54:24 +0900 Subject: [PATCH 2/2] [#1008] docs(troubleshooting): Correct trust-prompt recovery for regular agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address @re1: the onData trust listener at server/index.js:1182 is Butler-only (butlerSession.term). The four agents (head/dev/re1/re2) are pre-trusted at project creation by running `claude -p` in each Claude-backed worktree (server/routes.js:3924-3940, #599; #975 made it async, did not remove it). Reword the section to cite that mechanism and document the supported manual recovery — re-run `claude -p "echo ok"` in the affected worktree(s) (the same command QuadWork runs at creation), then restart the agent — instead of the incorrect "a per-agent listener auto-answers on restart" claim. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/troubleshooting.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e39e6a9..f3a69d9 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -8,9 +8,19 @@ Common issues and fixes, structured as **Symptom > Cause > Fix**. Searchable by **Symptom:** A Claude Code agent hangs on startup. Its terminal shows "Do you trust the files in this folder?" and waits for input. -**Cause:** Claude Code requires explicit directory trust before running, and `--dangerously-skip-permissions` skips permission prompts but NOT the trust gate. QuadWork normally handles this for you: when an agent's terminal starts, a listener watches its output and auto-confirms the trust prompt within the first ~10 seconds. A hang means the prompt wasn't caught in that window (e.g. the agent was slow to render it, or was started outside the normal launch flow). +**Cause:** Claude Code requires explicit directory trust before running, and `--dangerously-skip-permissions` skips permission prompts but NOT the trust gate. QuadWork pre-trusts each Claude-backed agent's worktree automatically during project creation, by running `claude -p` in it once, so the prompt normally never appears. A hang means that pre-trust didn't complete for this worktree — e.g. `claude` wasn't on `PATH` when the project was created, the worktree was recreated afterward, or the pre-trust timed out. -**Fix:** Restart the agent from the QuadWork dashboard. The trust listener re-arms on the fresh terminal and answers the prompt automatically — no manual pre-trust step is required, and QuadWork no longer runs a separate `claude` pre-trust command. +**Fix:** Re-trust the affected worktree(s) manually, then restart the agent from the dashboard: + +```bash +# Run once in each affected worktree +cd /path/to/-head && claude -p "echo ok" +cd /path/to/-dev && claude -p "echo ok" +cd /path/to/-re1 && claude -p "echo ok" +cd /path/to/-re2 && claude -p "echo ok" +``` + +This is the same command QuadWork runs at project creation; it writes the trust record so the agent's next launch skips the prompt. Re-running project setup also re-applies the pre-trust. ---