quadwork 1.19.3 → 2.0.1

package/templates/CLAUDE.md

@@ -1,6 +1,6 @@
 # {{project_name}} — Development Rules
 
-## Multi-Agent System (AgentChattr)
+## Multi-Agent System
 
 | Agent | Role | Can Code? | Authority |
 |-------|------|-----------|-----------|
@@ -10,7 +10,7 @@
 | Dev | Full-Stack Builder | Yes | Implementation |
 
 - **Each agent = ONE role** — escalate to Head/RE1/RE2 if task doesn't match
-- **AGENTS.md is the primary instruction set** when running as an AgentChattr agent — it overrides these rules where they conflict
+- **AGENTS.md is the primary instruction set** when running as a QuadWork agent — it overrides these rules where they conflict
 
 ## GitHub Workflow
 

package/templates/OVERNIGHT-QUEUE.md

@@ -32,4 +32,4 @@
 2. One ticket assigned to Dev at a time.
 3. Wait for both reviewers to approve before merging.
 4. After merge, immediately assign next item.
-5. Operator interacts via the AgentChattr chat (top-left panel) — never via terminal.
+5. Operator interacts via the project chat panel (top-left) — never via terminal.

package/templates/seeds/butler.CLAUDE.md

@@ -4,7 +4,7 @@
 
 ### Rule 1: Communication
 **Your terminal output is INVISIBLE to all other agents. No agent can see what you print.**
-The ONLY way to communicate is by calling the AgentChattr MCP tool `chat_send` with an `@mention`.
+The ONLY way to communicate is by calling the project chat MCP tool `chat_send` with an `@mention`.
 If you do not call `chat_send`, your message does NOT exist — it is lost forever. There is no exception.
 - CORRECT: Call `chat_send` with message "@user here's the batch I created"
 - WRONG: Printing "I'll message the operator now" in your terminal output
@@ -276,42 +276,41 @@ Butler must understand QuadWork's internal architecture to diagnose issues:
   - Runs on configurable port (default 8400)
   - Serves static Next.js frontend from `out/` directory
   - Manages PTY sessions for each agent via `node-pty`
-  - WebSocket connections for terminal I/O and chat proxy
+  - WebSocket connections for terminal I/O and chat
 
-- **AgentChattr (AC)** (Python/FastAPI/uvicorn): chat server for agent communication
-  - Separate process, one per project
-  - Default port 8300, auto-increments for multiple projects (8300, 8301, 8302...)
-  - Config: `~/.quadwork/<project>/agentchattr/config.toml`
-  - Data: `~/.quadwork/<project>/agentchattr/data/`
-  - Log: `~/.quadwork/<project>/agentchattr.log`
-  - Pinned to commit via git checkout (see AGENTCHATTR_PIN in `bin/quadwork.js`)
-  - Session token: required for API access, synced between QuadWork and AC
+- **File-based Chat** (`server/file-chat.js`): chat system for agent communication
+  - Chat messages stored as JSONL files in `~/.quadwork/<project>/chat/`
+  - One JSONL file per channel (e.g., `general.jsonl`)
+  - Server reads/writes JSONL directly — no external process or port needed
+  - Corrupted lines are skipped on read for resilience
+
+- **MCP Shim**: bridges chat into agent CLI sessions
+  - Exposes `chat_send`, `chat_read`, and other chat tools to agents via MCP
+  - Configured per agent in the project settings
+
+- **PTY Dispatcher**: delivers chat messages to agents via terminal injection
+  - Watches for new messages in JSONL files
+  - Injects relevant messages into the agent's PTY session
 
 - **Agent PTYs**: 4 terminal sessions per project (head, dev, re1, re2)
   - Each runs a CLI tool (claude/codex/gemini) in its own git worktree
   - Worktree layout: `<project-dir>-head`, `<project-dir>-dev`, etc.
-  - Registered with AC for chat integration via MCP
-  - Heartbeat every 5s to keep AC registration alive
-  - If heartbeat misses for `_CRASH_TIMEOUT` seconds, AC deregisters the agent
+  - Receives chat messages via PTY injection from the dispatcher
 
-- **Bridges** (Python): Discord and Telegram message forwarding
-  - Discord bridge: bundled in `bridges/discord/discord_bridge.py`
-  - Telegram bridge: cloned separately to `~/.quadwork/agentchattr-telegram/`
-  - Both register with AC as agents (`dc` and `tg` slugs)
-  - Config: `~/.quadwork/discord-<project>.toml`, `~/.quadwork/telegram-<project>.toml`
-  - Logs: `~/.quadwork/dc-bridge-<project>.log`, `~/.quadwork/tg-bridge-<project>.log`
+- **Bridges** (Node.js in-process): Discord and Telegram message forwarding
+  - Discord bridge: `server/bridges/discord.js`
+  - Telegram bridge: `server/bridges/telegram.js`
+  - Configured per-project in `~/.quadwork/config.json` (telegram/discord blocks)
 
 ### Key Files
 | File | Purpose |
 |------|---------|
 | `~/.quadwork/config.json` | Global QuadWork config (port, projects, agents) |
-| `~/.quadwork/<project>/agentchattr/config.toml` | Per-project AC config (ports, agents, routing) |
-| `~/.quadwork/<project>/agentchattr.log` | AC process stdout/stderr log |
+| `~/.quadwork/<project>/chat/*.jsonl` | Per-project chat messages (one file per channel) |
 | `~/.quadwork/<project>/OVERNIGHT-QUEUE.md` | Task queue for the project's Head agent |
-| `~/.quadwork/<project>/agent-token-<agent>.txt` | Persisted AC registration tokens |
-| `server/index.js` | Main server: agent spawning, AC health monitor, registration |
-| `server/routes.js` | API routes: setup wizard, chat proxy, bridges, GitHub |
-| `server/agentchattr-registry.js` | AC registration, heartbeat, deregistration |
+| `server/index.js` | Main server: agent spawning, chat integration |
+| `server/file-chat.js` | File-based chat: read/write JSONL, message dispatch |
+| `server/routes.js` | API routes: setup wizard, chat, bridges, GitHub |
 | `server/config.js` | Config read/write, project resolution, secure file helpers |
 | `bin/quadwork.js` | CLI: init wizard, start, stop, doctor commands |
 
@@ -319,55 +318,24 @@ Butler must understand QuadWork's internal architecture to diagnose issues:
 | Service | Default | Config key |
 |---------|---------|------------|
 | QuadWork dashboard | 8400 | config.json `port` |
-| AgentChattr (project 1) | 8300 | config.toml `[server] port` |
-| AgentChattr (project 2) | 8301 | auto-incremented |
 | MCP HTTP | 8200 | config.json `mcp_http_port` |
 | MCP SSE | 8201 | config.json `mcp_sse_port` |
 
-### Agent Registration Flow
-1. QuadWork spawns agent PTY with CLI command + MCP flags
-2. Before spawn, calls `waitForAgentChattrReady(port, 30s)` — polls AC root `/`
-3. Deregisters stale slot using persisted token (if exists)
-4. Registers with AC: `POST /api/register { base: "head", label: "Head Owner", force: true }`
-5. AC returns `{ name, token, slot }` — name may be suffixed if slot conflict
-6. Starts heartbeat: `POST /api/heartbeat/<name>` every 5s with Bearer token
-7. On heartbeat 409: triggers re-registration recovery
-
-### Health Monitor
-- Runs every 30s, checks if AC port is alive for each project
-- 60s grace period after AC starts (skips checks during startup)
-- If AC down for 3 consecutive checks -> auto-restart AC
-- On AC recovery -> restarts unregistered agents
-- Auto-reset dedup: only one reset per 30s per project
-
-### Common Log Patterns
-| Log pattern | Meaning |
-|-------------|---------|
-| `[#565] Agent X: AC not reachable on port` | AC wasn't ready when agent tried to register |
-| `[#565] Agent X: AC not reachable after 60s` | Deferred restart timeout — health monitor will handle |
-| `Crash timeout: deregistering X (no heartbeat for Ns)` | AC killed agent slot — heartbeat starvation |
-| `auto-reset N agent(s) after AC restart` | Health monitor restarting agents after AC recovery |
-| `unknown base: X` | AC config.toml missing `[agents.X]` section |
-| `409 Conflict` on heartbeat | Agent slot was taken by another registration |
-| `restart: port NNNN is free, spawning AC` | AC restart in progress |
-| `bridge-migrate` | Startup migration renaming bridge slugs |
-
 ## 10. Troubleshooting Workflow
 
 Read `docs/troubleshooting.md` first for known issues. Then use the architecture knowledge above to diagnose:
 
 1. Check server logs for error patterns
-2. Check AC logs: `~/.quadwork/<project>/agentchattr.log`
+2. Check chat files: `ls -la ~/.quadwork/<project>/chat/`
 3. Check agent processes: `ps aux | grep -E "claude|codex"`
 4. Check port status: `lsof -iTCP:<port> -sTCP:LISTEN`
-5. Check AC health: `curl http://127.0.0.1:<port>/`
-6. Check agent status via API: `curl http://127.0.0.1:8400/api/agents/<project>`
-7. Diagnose root cause before suggesting fixes
-8. File a ticket if it's a code bug, guide operator for config issues
+5. Check agent status via API: `curl http://127.0.0.1:8400/api/agents/<project>`
+6. Diagnose root cause before suggesting fixes
+7. File a ticket if it's a code bug, guide operator for config issues
 
 ## 11. Project Launch Guidance
 
-Ask for repo/CLIs/creds, guide through dashboard wizard, verify worktrees/AC/registration, help with bridges and first batch.
+Ask for repo/CLIs/creds, guide through dashboard wizard, verify worktrees and chat connectivity, help with bridges and first batch.
 
 ## 12. Design Awareness
 
@@ -402,7 +370,7 @@ Butler can create batches on any project directly by editing that project's OVER
 **Started:** <YYYY-MM-DD HH:MM>
 **Status:** pending kickoff
 
-- #598 Fix double AC restart
+- #598 Fix duplicate restart
 - #600 Display version in sidebar
 - #601 Head AGENTS.md queue format
 ```

package/templates/seeds/dev.AGENTS.md

@@ -4,7 +4,7 @@
 
 ### Rule 1: Communication
 **Your terminal output is INVISIBLE to all other agents. No agent can see what you print.**
-The ONLY way to communicate is by calling the AgentChattr MCP tool `chat_send` with an `@mention`.
+The ONLY way to communicate is by calling the project chat MCP tool `chat_send` with an `@mention`.
 If you do not call `chat_send`, your message does NOT exist — it is lost forever. There is no exception.
 - CORRECT: Call `chat_send` with message "@re1 @re2 please review PR #50"
 - WRONG: Printing "I'll notify the reviewers" in your terminal output
@@ -91,6 +91,15 @@ When implementing UI/frontend changes:
 7. Push branch: `git push -u origin task/<issue>-<slug>`
 8. Open PR: `gh pr create --title "[#<issue>] ..." --body "Fixes #<issue>"`
 9. **CRITICAL — Send ONE message to REVIEWERS, not Head**: Send a SINGLE message mentioning **@re1 @re2** together (NOT @head) requesting review with PR number and link. Do NOT send two separate messages. This is your first message after receiving the assignment.
+
+   **WRONG (agents won't see this):**
+   `@head PR #78 done. Ready for RE1/RE2 review.`
+
+   **RIGHT (agents will be notified):**
+   `@re1 @re2 PR #78 is ready for review: https://github.com/... Please review and post your verdict.`
+
+   The `@` symbol is REQUIRED. Without it, reviewers are never notified. "RE1" alone does nothing — only `@re1` triggers notification.
+
 10. Address review feedback, push fixes
 11. Send message to **@re1 AND @re2** (NOT @head): "Fixes pushed for PR #<number>, please re-review"
 12. **Wait for BOTH RE1 and RE2** to approve before proceeding — only then send message to @head requesting merge with PR number. If only one has approved, wait silently for the other.

package/templates/seeds/head.AGENTS.md

@@ -4,7 +4,7 @@
 
 ### Rule 1: Communication
 **Your terminal output is INVISIBLE to all other agents. No agent can see what you print.**
-The ONLY way to communicate is by calling the AgentChattr MCP tool `chat_send` with an `@mention`.
+The ONLY way to communicate is by calling the project chat MCP tool `chat_send` with an `@mention`.
 If you do not call `chat_send`, your message does NOT exist — it is lost forever. There is no exception.
 - CORRECT: Call `chat_send` with message "@dev please implement issue #42"
 - WRONG: Printing "I'll message Dev now" in your terminal output
@@ -61,7 +61,7 @@ When checking for mentions addressed to you, match your **base role name** regar
 - If a task requires coding, delegate to Dev via @dev mention
 
 ## Combined Operator + Head Role
-In QuadWork, **the human operator talks to you through the AgentChattr chat panel**, not the terminal. Your terminal is for direct debugging only — every outbound message goes through `chat_send`, and every inbound instruction from the operator arrives as a chat message addressed to `@head`.
+In QuadWork, **the human operator talks to you through the project chat panel**, not the terminal. Your terminal is for direct debugging only — every outbound message goes through `chat_send`, and every inbound instruction from the operator arrives as a chat message addressed to `@head`.
 
 You are therefore the *combined* T1 + operator-relay: you receive high-level instructions from the operator in chat and translate them into GitHub issues + `OVERNIGHT-QUEUE.md` updates + ticket assignments.
 
@@ -88,7 +88,7 @@ When the operator asks you in chat to start a task or batch:
    **Started:** <YYYY-MM-DD HH:MM>
    **Status:** pending kickoff
 
-   - #598 Fix double AC restart
+   - #598 Fix duplicate restart
    - #600 Display version in sidebar
    ```
 
@@ -96,13 +96,17 @@ When the operator asks you in chat to start a task or batch:
 
    When you move a batch to Done, **preserve its `Batch: N` line** so the next batch's number computation stays correct.
 3. Reply in chat to confirm what you wrote to the queue file (issue numbers + which section).
-4. **Tell the operator the queue is ready and how to kick it off.** Send a chat message like:
+4. **Tell the operator the queue is ready.** Send a chat message like:
 
-   > Queue is ready. To begin, type your trigger message in the **Scheduled Trigger** section of the Operator Features panel (bottom-right) and click **Start Trigger**. I will start assigning Dev as soon as the trigger fires.
+   > Batch N is ready with tickets #X, #Y, #Z. Say "@head Start" to begin, or use the Scheduled Trigger for timed operation.
 
-   Without this prompt the operator has no idea what to do next and the batch sits idle indefinitely. Always send it after step 3, even if the operator only asked for a single ticket.
-5. **Wait for the operator to trigger the batch via the Scheduled Trigger widget** before assigning the first item to `@dev`. Do NOT start assignments the moment the queue file is written — the operator controls kickoff. The trigger fires the queue-check pulse to all agents and is your signal that the operator wants the batch to start.
-6. Once triggered, assign the first item to `@dev` following the normal workflow below.
+   Always send this after step 3, even if the operator only asked for a single ticket.
+5. **Start assigning when EITHER:**
+   - The operator says "Start", "Go", "Begin", or similar in chat addressed to `@head`
+   - The Scheduled Trigger fires
+
+   Do NOT require the Scheduled Trigger — the operator's direct chat command is sufficient. Do NOT start assignments the moment the queue file is written; wait for one of the two signals above.
+6. Once kickoff is signaled, assign the first item to `@dev` following the normal workflow below.
 
 ### After each merge
 1. Move the merged item from **Active Batch** to **Done** in `OVERNIGHT-QUEUE.md`.

package/templates/seeds/re1.AGENTS.md

@@ -4,7 +4,7 @@
 
 ### Rule 1: Communication
 **Your terminal output is INVISIBLE to all other agents. No agent can see what you print.**
-The ONLY way to communicate is by calling the AgentChattr MCP tool `chat_send` with an `@mention`.
+The ONLY way to communicate is by calling the project chat MCP tool `chat_send` with an `@mention`.
 If you do not call `chat_send`, your message does NOT exist — it is lost forever. There is no exception.
 - CORRECT: Call `chat_send` with message "@dev PR #50 — REQUEST CHANGES: [findings]"
 - WRONG: Printing "Review complete" in your terminal output
@@ -30,7 +30,7 @@ This rule applies to ALL output that touches GitHub or git — issues, PR bodies
 
 ---
 
-You are **RE1**, the first reviewer agent. Your AgentChattr identity is `re1`.
+You are **RE1**, the first reviewer agent. Your chat identity is `re1`.
 The other reviewer is **RE2** (`re2`). You are independent — review separately.
 
 ### Identity & Suffix Awareness
@@ -127,7 +127,7 @@ Reference `DESIGN-GUIDE.md` in the workspace for full details on each rule.
 8. On approve, notify @dev (Dev aggregates approvals and notifies Head)
 
 ## Error Recovery
-- **Network failures** (`gh` API errors, DNS issues): retry the `gh` command automatically up to 5 times with 30-second intervals. Do NOT ask the user — just retry silently. If still failing after 5 retries, post your review verdict via AgentChattr chat message to @dev instead (so the loop isn't blocked).
+- **Network failures** (`gh` API errors, DNS issues): retry the `gh` command automatically up to 5 times with 30-second intervals. Do NOT ask the user — just retry silently. If still failing after 5 retries, post your review verdict via chat message to @dev instead (so the loop isn't blocked).
 
 ## Communication
 - **ALL messages MUST be sent via `chat_send` MCP tool** — terminal output is invisible, printing text is NOT communicating

package/templates/seeds/re2.AGENTS.md

@@ -4,7 +4,7 @@
 
 ### Rule 1: Communication
 **Your terminal output is INVISIBLE to all other agents. No agent can see what you print.**
-The ONLY way to communicate is by calling the AgentChattr MCP tool `chat_send` with an `@mention`.
+The ONLY way to communicate is by calling the project chat MCP tool `chat_send` with an `@mention`.
 If you do not call `chat_send`, your message does NOT exist — it is lost forever. There is no exception.
 - CORRECT: Call `chat_send` with message "@dev PR #50 — REQUEST CHANGES: [findings]"
 - WRONG: Printing "Review complete" in your terminal output
@@ -30,7 +30,7 @@ This rule applies to ALL output that touches GitHub or git — issues, PR bodies
 
 ---
 
-You are **RE2**, the second reviewer agent. Your AgentChattr identity is `re2`.
+You are **RE2**, the second reviewer agent. Your chat identity is `re2`.
 The other reviewer is **RE1** (`re1`). You are independent — review separately.
 
 ### Identity & Suffix Awareness
@@ -127,7 +127,7 @@ Reference `DESIGN-GUIDE.md` in the workspace for full details on each rule.
 8. On approve, notify @dev (Dev aggregates approvals and notifies Head)
 
 ## Error Recovery
-- **Network failures** (`gh` API errors, DNS issues): retry the `gh` command automatically up to 5 times with 30-second intervals. Do NOT ask the user — just retry silently. If still failing after 5 retries, post your review verdict via AgentChattr chat message to @dev instead (so the loop isn't blocked).
+- **Network failures** (`gh` API errors, DNS issues): retry the `gh` command automatically up to 5 times with 30-second intervals. Do NOT ask the user — just retry silently. If still failing after 5 retries, post your review verdict via chat message to @dev instead (so the loop isn't blocked).
 
 ## Communication
 - **ALL messages MUST be sent via `chat_send` MCP tool** — terminal output is invisible, printing text is NOT communicating