fix: suppress unused variable TS errors that block release build

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -60,7 +60,16 @@
       "Edit",
       "Write",
       "Bash(find *)",
-      "Bash(sqlite3 *)"
+      "Bash(sqlite3 *)",
+      "Bash(cat <<:*)",
+      "Bash(cat <<'ENDJSON:*)",
+      "Bash(make release:*)",
+      "Bash(npm test:*)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(wc *)",
+      "Bash(npx vite:*)",
+      "Bash(npm run dev:*)"
     ]
   }
 }

.gitignore

@@ -1,5 +1,6 @@
 # Claude Code
 .claude/settings.local.json
+.mcp.json
 
 # Local environment (secrets)
 .env
@@ -25,6 +26,7 @@ frontend/node_modules
 frontend/dist
 frontend/dist-ssr
 frontend/test-results
+frontend/serve
 frontend/*.local
 server/target
 

.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "story-kit": {
-      "type": "http",
-      "url": "http://localhost:3001/mcp"
-    }
-  }
-}

.story_kit/.gitignore

@@ -4,10 +4,19 @@ bot.toml
 # Matrix SDK state store
 matrix_store/
 matrix_device_id
+matrix_history.json
 
 # Agent worktrees and merge workspace (managed by the server, not tracked in git)
 worktrees/
 merge_workspace/
 
+# Intermediate pipeline stages (transient, not committed per spike 92)
+work/2_current/
+work/3_qa/
+work/4_merge/
+
 # Coverage reports (generated by cargo-llvm-cov, not tracked in git)
 coverage/
+
+# Token usage log (generated at runtime, contains cost data)
+token_usage.jsonl

.story_kit/README.md

@@ -18,7 +18,7 @@ When you start a new session with this project:
    This returns the full tool catalog (create stories, spawn agents, record tests, manage worktrees, etc.). Familiarize yourself with the available tools before proceeding. These tools allow you to directly manipulate the workflow and spawn subsidiary agents without manual file manipulation.
 2. **Read Context:** Check `.story_kit/specs/00_CONTEXT.md` for high-level project goals.
 3. **Read Stack:** Check `.story_kit/specs/tech/STACK.md` for technical constraints and patterns.
-4. **Check Work Items:** Look at `.story_kit/work/1_upcoming/` and `.story_kit/work/2_current/` to see what work is pending.
+4. **Check Work Items:** Look at `.story_kit/work/1_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
 
 
 ---
@@ -52,7 +52,7 @@ project_root/
   ├── README.md          # This document
   ├── project.toml       # Agent configuration (roles, models, prompts)
   ├── work/              # Unified work item pipeline (stories, bugs, spikes)
-  │   ├── 1_upcoming/    # New work items awaiting implementation
+  │   ├── 1_backlog/    # New work items awaiting implementation
   │   ├── 2_current/     # Work in progress
   │   ├── 3_qa/          # QA review
   │   ├── 4_merge/       # Ready to merge to master
@@ -78,7 +78,7 @@ All work items (stories, bugs, spikes) live in the same `work/` pipeline. Items
 
 Items move through stages by moving the file between directories:
 
-`1_upcoming` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
+`1_backlog` → `2_current` → `3_qa` → `4_merge` → `5_done` → `6_archived`
 
 Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 
@@ -87,7 +87,7 @@ Items in `5_done` are auto-swept to `6_archived` after 4 hours by the server.
 The server watches `.story_kit/work/` for changes. When a file is created, moved, or modified, the watcher auto-commits with a deterministic message and broadcasts a WebSocket notification to the frontend. This means:
 
 *   MCP tools only need to write/move files — the watcher handles git commits
-*   IDE drag-and-drop works (drag a story from `1_upcoming/` to `2_current/`)
+*   IDE drag-and-drop works (drag a story from `1_backlog/` to `2_current/`)
 *   The frontend updates automatically without manual refresh
 
 ---
@@ -156,7 +156,7 @@ Not everything needs to be a full story. Simple bugs can skip the story process:
 *   Performance issues with known fixes
 
 ### Bug Process
-1.  **Document Bug:** Create a bug file in `work/1_upcoming/` named `{id}_bug_{slug}.md` with:
+1.  **Document Bug:** Create a bug file in `work/1_backlog/` named `{id}_bug_{slug}.md` with:
     *   **Symptom:** What the user observes
     *   **Root Cause:** Technical explanation (if known)
     *   **Reproduction Steps:** How to trigger the bug
@@ -186,7 +186,7 @@ Not everything needs a story or bug fix. Spikes are time-boxed investigations to
 *   Need to validate performance constraints
 
 ### Spike Process
-1.  **Document Spike:** Create a spike file in `work/1_upcoming/` named `{id}_spike_{slug}.md` with:
+1.  **Document Spike:** Create a spike file in `work/1_backlog/` named `{id}_spike_{slug}.md` with:
     *   **Question:** What you need to answer
     *   **Hypothesis:** What you expect to be true
     *   **Timebox:** Strict limit for the research
@@ -209,7 +209,7 @@ When the LLM context window fills up (or the chat gets slow/confused):
 1.  **Stop Coding.**
 2.  **Instruction:** Tell the user to open a new chat.
 3.  **Handoff:** The only context the new LLM needs is in the `specs/` folder and `.mcp.json`.
-    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_upcoming/` and `work/2_current/` to see what is pending."
+    *   *Prompt for New Session:* "I am working on Project X. Read `.mcp.json` to discover available tools, then read `specs/00_CONTEXT.md` and `specs/tech/STACK.md`. Then look at `work/1_backlog/` and `work/2_current/` to see what is pending."
 
 
 ---
@@ -221,7 +221,7 @@ If a user hands you this document and says "Apply this process to my project":
 1.  **Check for MCP Tools:** Look for `.mcp.json` in the project root. If it exists, you have programmatic access to workflow tools and agent spawning capabilities.
 2.  **Analyze the Request:** Ask for the high-level goal ("What are we building?") and the tech preferences ("Rust or Python?").
 3.  **Git Check:** Check if the directory is a git repository (`git status`). If not, run `git init`.
-4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_upcoming/` through `work/6_archived/`).
+4.  **Scaffold:** Run commands to create the `work/` and `specs/` folders with the 6-stage pipeline (`work/1_backlog/` through `work/6_archived/`).
 5.  **Draft Context:** Write `specs/00_CONTEXT.md` based on the user's answer.
 6.  **Draft Stack:** Write `specs/tech/STACK.md` based on best practices for that language.
 7.  **Wait:** Ask the user for "Story #1".

.story_kit/bot.toml.example

@@ -13,3 +13,7 @@ enabled = false
 
 # Maximum conversation turns to remember per room (default: 20).
 # history_size = 20
+
+# Rooms where the bot responds to all messages (not just addressed ones).
+# This list is updated automatically when users toggle ambient mode at runtime.
+# ambient_rooms = ["!roomid:example.com"]

.story_kit/problems.md

@@ -0,0 +1,16 @@
+# Problems
+
+Recurring issues observed during pipeline operation. Review periodically and create stories for systemic problems.
+
+## 2026-03-18: Stories graduating to "done" with empty merges (7 of 10)
+
+Pipeline allows stories to move through coding → QA → merge → done without any actual code changes landing on master. The squash-merge produces an empty diff but the pipeline still marks the story as done. Affected stories: 247, 273, 274, 278, 279, 280, 92. Only 266, 271, 277, and 281 actually shipped code. Root cause: no check that the merge commit contains a non-empty diff. Filed bug 283 for the manual_qa gate issue specifically, but the empty-merge-to-done problem is broader and needs its own fix.
+
+## 2026-03-18: Agent committed directly to master instead of worktree
+
+Multiple agents have committed directly to master instead of their worktree/feature branch:
+
+- Commit `5f4591f` ("fix: update should_commit_stage test to match 5_done") — likely mergemaster
+- Commit `a32cfbd` ("Add bot-level command registry with help command") — story 285 coder committed code + Cargo.lock directly to master
+
+Agents should only commit to their feature branch or merge-queue branch, never to master directly. Suspect agents are running `git commit` in the project root instead of the worktree directory. This can also revert uncommitted fixes on master (e.g. project.toml pkill fix was overwritten). Frequency: at least 2 confirmed cases. This is a recurring and serious problem — needs a guard in the server or agent prompts.

.story_kit/project.toml

@@ -1,3 +1,18 @@
+# Project-wide default QA mode: "server", "agent", or "human".
+# Per-story `qa` front matter overrides this setting.
+default_qa = "server"
+
+# Default model for coder agents. Only agents with this model are auto-assigned.
+# Opus coders are reserved for explicit per-story `agent:` front matter requests.
+default_coder_model = "sonnet"
+
+# Maximum concurrent coder agents. Stories wait in 2_current/ when all slots are full.
+max_coders = 3
+
+# Maximum retries per story per pipeline stage before marking as blocked.
+# Set to 0 to disable retry limits.
+max_retries = 2
+
 [[component]]
 name = "frontend"
 path = "frontend"
@@ -34,7 +49,7 @@ You have these tools via the story-kit MCP server:
 ## Your Workflow
 1. Read CLAUDE.md and .story_kit/README.md to understand the project and dev process
 2. Read the story file from .story_kit/work/ to understand requirements
-3. Move it to work/2_current/ if it is in work/1_upcoming/
+3. Move it to work/2_current/ if it is in work/1_backlog/
 4. Start coder-1 on the story: call start_agent with story_id="{{story_id}}" and agent_name="coder-1"
 5. Wait for completion: call wait_for_agent with story_id="{{story_id}}" and agent_name="coder-1". The server automatically runs acceptance gates (cargo clippy + tests) when the coder process exits. wait_for_agent returns when the coder reaches a terminal state.
 6. Check the result: inspect the "completion" field in the wait_for_agent response — if gates_passed is true, the work is done; if false, review the gate_output and decide whether to start a fresh coder.
@@ -69,6 +84,16 @@ max_budget_usd = 5.00
 prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
 system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
 
+[[agent]]
+name = "coder-3"
+stage = "coder"
+role = "Full-stack engineer. Implements features across all components."
+model = "sonnet"
+max_turns = 50
+max_budget_usd = 5.00
+prompt = "You are working in a git worktree on story {{story_id}}. Read CLAUDE.md first, then .story_kit/README.md to understand the dev process. The story details are in your prompt above. Follow the SDTW process through implementation and verification (Steps 1-3). The worktree and feature branch already exist - do not create them. Check .mcp.json for MCP tools. Do NOT accept the story or merge - commit your work and stop. If the user asks to review your changes, tell them to run: cd \"{{worktree_path}}\" && git difftool {{base_branch}}...HEAD\n\nIMPORTANT: Commit all your work before your process exits. The server will automatically run acceptance gates (cargo clippy + tests) when your process exits and advance the pipeline based on the results.\n\n## Bug Workflow: Root Cause First\nWhen working on bugs:\n1. Investigate the root cause before writing any fix. Use `git bisect` to find the breaking commit or `git log` to trace history. Read the relevant code before touching anything.\n2. Fix the root cause with a surgical, minimal change. Do NOT add new abstractions, wrappers, or workarounds when a targeted fix to the original code is possible.\n3. Write commit messages that explain what broke and why, not just what was changed.\n4. If you cannot determine the root cause after thorough investigation, document what you tried and why it was inconclusive — do not guess and ship a speculative fix."
+system_prompt = "You are a full-stack engineer working autonomously in a git worktree. Follow the Story-Driven Test Workflow strictly. Run cargo clippy and biome checks before considering work complete. Commit all your work before finishing - use a descriptive commit message. Do not accept stories, move them to archived, or merge to master - a human will do that. Do not coordinate with other agents - focus on your assigned story. The server automatically runs acceptance gates when your process exits. For bugs, always find and fix the root cause. Use git bisect to find breaking commits. Do not layer new code on top of existing code when a surgical fix is possible. If root cause is unclear after investigation, document what you tried rather than guessing."
+
 [[agent]]
 name = "qa-2"
 stage = "qa"
@@ -102,7 +127,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- Kill the test server when done: `pkill -f 'target.*story-kit' || true` (NEVER use `pkill -f story-kit` — it kills the vite dev server)
 
 ### 4. Produce Structured Report
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
@@ -179,7 +204,7 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - URL to visit in the browser
   - Things to check in the UI
   - curl commands to exercise relevant API endpoints
-- Kill the test server when done: `pkill -f story-kit || true`
+- Kill the test server when done: `pkill -f 'target.*story-kit' || true` (NEVER use `pkill -f story-kit` — it kills the vite dev server)
 
 ### 4. Produce Structured Report
 Print your QA report to stdout before your process exits. The server will automatically run acceptance gates. Use this format:
@@ -220,7 +245,7 @@ role = "Merges completed coder work into master, runs quality gates, archives st
 model = "opus"
 max_turns = 30
 max_budget_usd = 5.00
-prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master using the merge_agent_work MCP tool.
+prompt = """You are the mergemaster agent for story {{story_id}}. Your job is to merge the completed coder work into master.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
@@ -229,20 +254,43 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 2. Review the result: check success, had_conflicts, conflicts_resolved, gates_passed, and gate_output
 3. If merge succeeded and gates passed: report success to the human
 4. If conflicts were auto-resolved (conflicts_resolved=true) and gates passed: report success, noting which conflicts were resolved
-5. If conflicts could not be auto-resolved: call report_merge_failure(story_id='{{story_id}}', reason='<conflict details>') and report to the human. Master is untouched.
+5. If conflicts could not be auto-resolved: **resolve them yourself** in the merge worktree (see below)
-6. If merge failed for any other reason: call report_merge_failure(story_id='{{story_id}}', reason='<details>') and report to the human.
+6. If merge failed for any other reason: call report_merge_failure(story_id='{{story_id}}', reason='<details>') and report to the human
-7. If gates failed after merge: attempt to fix minor issues (see below), then re-trigger merge_agent_work. After 2 fix attempts, call report_merge_failure and stop.
+7. If gates failed after merge: attempt to fix the issues yourself in the merge worktree, then re-trigger merge_agent_work. After 3 fix attempts, call report_merge_failure and stop.
 
-## How Conflict Resolution Works
+## Resolving Complex Conflicts Yourself
-The merge pipeline uses a temporary merge-queue branch and worktree to isolate merges from master. Simple additive conflicts (both branches adding code at the same location) are resolved automatically by keeping both additions. Complex conflicts (modifying the same lines differently) are reported without touching master.
 
-## Fixing Minor Gate Failures
+When the auto-resolver fails, you have access to the merge worktree at `.story_kit/merge_workspace/`. Go in there and resolve the conflicts manually:
-If quality gates fail (cargo clippy, cargo test, npm run build, npm test), attempt to fix minor issues yourself before reporting to the human.
 
-**Fix yourself (up to 2 attempts total):**
+1. Run `git diff --name-only --diff-filter=U` in the merge worktree to list conflicted files
+2. **Build context before touching code.** Run `git log --oneline master...HEAD` on the feature branch to see its commits. Then run `git log --oneline --since="$(git log -1 --format=%ci <feature-branch-base-commit>)" master` to see what landed on master since the branch was created. Read the story files in `.story_kit/work/` for any recently merged stories that touch the same files — this tells you WHY master changed and what must be preserved.
+3. Read each conflicted file and understand both sides of the conflict
+4. **Understand intent, not just syntax.** The feature branch may be behind master — master's version of shared infrastructure is almost always correct. The feature branch's contribution is the NEW functionality it adds. Your job is to integrate the new into master's structure, not pick one side.
+5. Resolve by integrating the feature's new functionality into master's code structure
+5. Stage resolved files with `git add`
+6. Run `cargo check` (and `npm run build` if frontend changed) to verify compilation
+7. If it compiles, commit and re-trigger merge_agent_work
+
+### Common conflict patterns in this project:
+
+**Story file rename/rename conflicts:** Both branches moved the story .md file to different pipeline directories. Resolution: `git rm` both sides — story files in `work/2_current/`, `work/3_qa/`, `work/4_merge/` are gitignored and don't need to be committed.
+
+**bot.rs tokio::select! conflicts:** Master has a `tokio::select!` loop in `handle_message()` that handles permission forwarding (story 275). Feature branches created before story 275 have a simpler direct `provider.chat_stream().await` call. Resolution: KEEP master's tokio::select! loop. Integrate only the feature's new logic (e.g. typing indicators, new callbacks) into the existing loop structure. Do NOT replace the loop with the old direct call.
+
+**Duplicate functions/imports:** The auto-resolver keeps both sides, producing duplicates. Resolution: keep one copy (prefer master's version), delete the duplicate.
+
+**Formatting-only conflicts:** Both sides reformatted the same code differently. Resolution: pick either side (prefer master).
+
+## Fixing Gate Failures
+
+If quality gates fail (cargo clippy, cargo test, npm run build, npm test), attempt to fix issues yourself in the merge worktree.
+
+**Fix yourself (up to 3 attempts total):**
 - Syntax errors (missing semicolons, brackets, commas)
+- Duplicate definitions from merge artifacts
 - Simple type annotation errors
 - Unused import warnings flagged by clippy
+- Mismatched braces from bad conflict resolution
 - Trivial formatting issues that block compilation or linting
 
 **Report to human without attempting a fix:**
@@ -250,17 +298,14 @@ If quality gates fail (cargo clippy, cargo test, npm run build, npm test), attem
 - Missing function implementations
 - Architectural changes required
 - Non-trivial refactoring needed
-- Anything requiring understanding of broader system context
 
-**Max retry limit:** If gates still fail after 2 fix attempts, call report_merge_failure to record the failure, then stop immediately and report the full gate output to the human. Do not retry further.
+**Max retry limit:** If gates still fail after 3 fix attempts, call report_merge_failure to record the failure, then stop immediately and report the full gate output to the human.
 
 ## CRITICAL Rules
 - NEVER manually move story files between pipeline stages (e.g. from 4_merge/ to 5_done/)
 - NEVER call accept_story — only merge_agent_work can move stories to done after a successful merge
-- When merge fails, ALWAYS call report_merge_failure to record the failure — do NOT improvise with file moves
+- When merge fails after exhausting your fix attempts, ALWAYS call report_merge_failure
-- Only use MCP tools (merge_agent_work, report_merge_failure) to drive the merge process
-- Only attempt fixes that are clearly minor and low-risk
 - Report conflict resolution outcomes clearly
 - Report gate failures with full output so the human can act if needed
 - The server automatically runs acceptance gates when your process exits"""
-system_prompt = "You are the mergemaster agent. Your primary responsibility is to trigger the merge_agent_work MCP tool and report the results. CRITICAL: Never manually move story files or call accept_story. When merge fails, call report_merge_failure to record the failure. For minor gate failures (syntax errors, unused imports, missing semicolons), attempt to fix them yourself — but stop after 2 attempts, call report_merge_failure, and report to the human. For complex failures or unresolvable conflicts, call report_merge_failure and report clearly so the human can act. The merge pipeline automatically resolves simple additive conflicts."
+system_prompt = "You are the mergemaster agent. Your primary job is to merge feature branches to master. First try the merge_agent_work MCP tool. If the auto-resolver fails on complex conflicts, resolve them yourself in the merge worktree — you are an opus-class agent capable of understanding both sides of a conflict and producing correct merged code. Common patterns: keep master's tokio::select! permission loop in bot.rs, discard story file rename conflicts (gitignored), remove duplicate definitions. After resolving, verify compilation before re-triggering merge. CRITICAL: Never manually move story files or call accept_story. After 3 failed fix attempts, call report_merge_failure and stop."

.story_kit/work/1_backlog/280_story_long_running_supervisor_agent_with_periodic_pipeline_polling.md

@@ -0,0 +1,32 @@
+---
+name: "Long-running supervisor agent with periodic pipeline polling"
+agent: coder-opus
+---
+
+# Story 280: Long-running supervisor agent with periodic pipeline polling
+
+## User Story
+
+As a project owner, I want a long-running supervisor agent (opus) that automatically monitors the pipeline, assigns agents, resolves stuck items, and handles routine operational tasks, so that I don't have to manually check status, kick agents, or babysit the pipeline in every conversation.
+
+## Acceptance Criteria
+
+- [ ] Server can start a persistent supervisor agent that stays alive across the session (not per-story)
+- [ ] Server prods the supervisor periodically (default 30s, configurable in project.toml) with a pipeline status update
+- [ ] Supervisor auto-assigns agents to unassigned items in current/qa/merge stages
+- [ ] Supervisor detects stuck agents (no progress for configurable timeout) and restarts them
+- [ ] Supervisor detects merge failures and sends stories back to current for rebase when appropriate
+- [ ] Supervisor can be chatted with via Matrix (timmy relays to supervisor) or via the web UI
+- [ ] Supervisor logs its decisions so the human can review what it did and why
+- [ ] Polling interval is configurable in project.toml (e.g. supervisor_poll_interval_secs = 30)
+- [ ] Supervisor logs persistent/recurring problems to `.story_kit/problems.md` with timestamp, description, and frequency — humans review this file periodically to create stories for systemic issues
+
+## Notes
+
+- **2026-03-18**: Moved back to current from merge. Previous attempt went through the full pipeline but the squash-merge produced an empty diff — no code was actually implemented. Needs a real implementation.
+
+## Out of Scope
+
+- Supervisor accepting or merging stories to master (human job)
+- Supervisor making architectural decisions
+- Replacing the existing per-story agent spawning — supervisor coordinates on top of it

.story_kit/work/1_backlog/312_bug_auto_assign_assigns_mergemaster_to_coding_stage_stories.md

@@ -0,0 +1,37 @@
+---
+name: "Auto-assign assigns mergemaster to coding-stage stories"
+---
+
+# Bug 312: Auto-assign assigns mergemaster to coding-stage stories
+
+## Description
+
+Auto-assign picks agents whose configured stage doesn't match the pipeline stage of the story. Observed multiple mismatch types:
+
+- **Mergemaster assigned to coding-stage stories**: Story 310 was in `2_current/` but got mergemaster instead of a coder (2026-03-19)
+- **Coders assigned to QA-stage stories**: Coders (stage=coder) have been observed running on stories in `3_qa/`
+- **QA agents assigned to merge-stage stories**: QA agents (stage=qa) have been observed running on stories in `4_merge/`
+
+The `auto_assign_available_work` function doesn't enforce that the agent's configured stage matches the pipeline stage of the story it's being assigned to. Story 279 (auto-assign respects agent stage from front matter) was supposed to fix stage matching, but the check may only apply to front-matter preferences, not the fallback assignment path.
+
+## How to Reproduce
+
+1. Move a story to any pipeline stage with no agent front matter preference
+2. Wait for auto_assign_available_work to run
+3. Observe that agents from the wrong stage get assigned (e.g. mergemaster to coding, coder to QA)
+
+## Actual Result
+
+Agents are assigned to stories in pipeline stages that don't match their configured stage. Mergemaster codes, coders do QA, QA agents attempt merges.
+
+## Expected Result
+
+Only coder-stage agents should be assigned to stories in 2_current/. Mergemaster should only be assigned to stories in 4_merge/.
+
+## Acceptance Criteria
+
+- [ ] auto_assign_available_work checks that the agent's configured stage matches the pipeline stage of the story before assigning
+- [ ] Coder agents only assigned to stories in 2_current/
+- [ ] QA agents only assigned to stories in 3_qa/
+- [ ] Mergemaster only assigned to stories in 4_merge/
+- [ ] Fallback assignment path respects stage matching (not just front-matter preference path)

.story_kit/work/1_upcoming/92_spike_stop_auto_committing_intermediate_pipeline_moves.md

@@ -1,55 +0,0 @@
----
-name: "Stop auto-committing intermediate pipeline moves"
----
-
-# Spike 92: Stop auto-committing intermediate pipeline moves
-
-## Goal
-
-Determine how to stop the filesystem watcher from auto-committing every pipeline stage move (upcoming -> current -> qa -> merge -> done -> archive) while still committing at terminal states (creation in upcoming, acceptance in done and archived). This keeps git history clean while preserving cross-machine portability for completed work.
-
-## Context
-
-The watcher in `server/src/io/watcher.rs` currently auto-commits every file change in `.story_kit/work/`. A single story run generates 5+ commits just from pipeline moves:
-- `story-kit: create 42_story_foo`
-- `story-kit: start 42_story_foo`
-- `story-kit: queue 42_story_foo for QA`
-- `story-kit: queue 42_story_foo for merge`
-- `story-kit: accept 42_story_foo`
-
-Since story runs complete relatively quickly, the intermediate state (current/qa/merge) is transient and doesn't need to be committed. Only creation and archival are meaningful checkpoints.
-
-## Questions to Answer
-
-1. Can we filter `stage_metadata()` to only commit for `1_upcoming` and `5_archived` stages while still broadcasting `WatcherEvent`s for all stages (so the frontend stays in sync)?
-2. Should we keep `git add -A .story_kit/work/` for the committed stages, or narrow it to only the specific file?
-3. What happens if the server crashes mid-pipeline? Uncommitted moves are lost — is this acceptable given the story can just be re-run?
-4. Should intermediate moves be `.gitignore`d at the directory level, or is filtering in the watcher sufficient?
-5. Do any other parts of the system (agent worktree setup, merge_agent_work, sparse checkout) depend on intermediate pipeline files being committed to master?
-
-## Approach to Investigate
-
-### Option A: Filter in `flush_pending()`
-- In `flush_pending()`, still broadcast the `WatcherEvent` for all stages
-- Only call `git_add_work_and_commit()` for stages `1_upcoming` and `5_archived`
-- Simplest change — ~5 lines modified in `watcher.rs`
-
-### Option B: Two-tier watcher
-- Split into "commit-worthy" events (create, archive) and "notify-only" events (start, qa, merge)
-- Commit-worthy events go through git
-- Notify-only events just broadcast to WebSocket clients
-- More explicit but same end result as Option A
-
-### Option C: .gitignore intermediate directories
-- Add `2_current/`, `3_qa/`, `4_merge/` to `.gitignore`
-- Watcher still sees events (gitignore doesn't affect filesystem watching)
-- Git naturally ignores them
-- Risk: harder to debug, `git status` won't show pipeline state
-
-## Acceptance Criteria
-
-- [ ] Spike document updated with findings and recommendation
-- [ ] If Option A is viable: prototype the change and verify git log is clean during a full story run
-- [ ] Confirm frontend still receives real-time pipeline updates for all stages
-- [ ] Confirm no other system depends on intermediate pipeline commits being on master
-- [ ] Identify any edge cases (server crash, manual git operations, multi-machine sync)

.story_kit/work/5_done/310_story_bot_delete_command_removes_a_story_from_the_pipeline.md

@@ -0,0 +1,24 @@
+---
+name: "Bot delete command removes a story from the pipeline"
+---
+
+# Story 310: Bot delete command removes a story from the pipeline
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} delete {story_number}" to remove a story/bug/spike from the pipeline, so that I can clean up obsolete or duplicate work items from chat.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} delete {number}' finds the story/bug/spike by number across all pipeline stages and deletes the file
+- [ ] Confirms deletion with the story name and stage it was in
+- [ ] Returns a friendly message if no story with that number exists
+- [ ] Stops any running agent on the story before deleting
+- [ ] Removes the worktree if one exists for the story
+- [ ] Registered in the command registry so it appears in help output
+- [ ] Handled at bot level without LLM invocation
+- [ ] Commits the deletion to git
+
+## Out of Scope
+
+- TBD

.story_kit/work/5_done/311_story_server_enforced_retry_limits_for_failed_merge_and_empty_diff_stories.md

@@ -0,0 +1,22 @@
+---
+name: "Server-enforced retry limits for failed merge and empty-diff stories"
+---
+
+# Story 311: Server-enforced retry limits for failed merge and empty-diff stories
+
+## User Story
+
+As a project owner, I want the server to enforce retry limits on stories that fail merge or produce empty diffs, so that agents don't loop infinitely on broken stories and waste tokens.
+
+## Acceptance Criteria
+
+- [ ] auto_assign_available_work checks the merge_failure front matter flag and skips stories in 4_merge that already have a reported failure
+- [ ] Server tracks retry count per story per stage in front matter (e.g. retry_count: 2)
+- [ ] After N retries (configurable in project.toml, default 2), story is flagged as blocked and auto-assign stops trying
+- [ ] Blocked stories show a clear indicator in pipeline status (MCP and bot status command)
+- [ ] Server detects 'coder finished with no commits on feature branch' at gate-check stage and fails the gates early instead of advancing to QA
+- [ ] Empty-diff merge failures are detected and reported without needing the mergemaster agent to discover them
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/266_story_matrix_bot_structured_conversation_history.md

@@ -0,0 +1,60 @@
+---
+name: "Matrix bot structured conversation history"
+agent: coder-opus
+---
+
+# Story 266: Matrix bot structured conversation history
+
+## User Story
+
+As a user chatting with the Matrix bot, I want it to remember and own its prior responses naturally, so that conversations feel like talking to one continuous entity rather than a new instance each message.
+
+## Acceptance Criteria
+
+- [ ] Conversation history is passed as structured API messages (user/assistant turns) rather than a flattened text prefix
+- [ ] Claude recognises its prior responses as its own, maintaining consistent personality across a conversation
+- [ ] Per-room history survives server restarts (persisted to disk or database)
+- [ ] Rolling window trimming still applies to keep context bounded
+- [ ] Multi-user rooms still attribute messages to the correct sender
+
+## Investigation Notes (2026-03-18)
+
+The current implementation attempts session resumption via `--resume <session_id>` but it's not working:
+
+### Code path: how session resumption is supposed to work
+
+1. `server/src/matrix/bot.rs:671-676` — `handle_message()` reads `conv.session_id` from the per-room `RoomConversation` to get the resume ID.
+2. `server/src/matrix/bot.rs:717` — passes `resume_session_id` to `provider.chat_stream()`.
+3. `server/src/llm/providers/claude_code.rs:57` — `chat_stream()` stores it as `resume_id`.
+4. `server/src/llm/providers/claude_code.rs:170-173` — if `resume_session_id` is `Some`, appends `--resume <id>` to the `claude -p` command.
+5. `server/src/llm/providers/claude_code.rs:348` — `process_json_event()` looks for `json["session_id"]` in each streamed NDJSON event and sends it via a oneshot channel (`sid_tx`).
+6. `server/src/llm/providers/claude_code.rs:122` — after the PTY exits, `sid_rx.await.ok()` captures the session ID (or `None` if never sent).
+7. `server/src/matrix/bot.rs:785-787` — stores `new_session_id` back into `conv.session_id` and persists via `save_history()`.
+
+### What's broken
+
+- **No session_id captured:** `.story_kit/matrix_history.json` contains conversation entries but no `session_id`. `RoomConversation.session_id` is always `None`.
+- **Root cause:** `claude -p --output-format stream-json` may not emit a `session_id` in its NDJSON events, or the parser at step 5 isn't matching the actual event shape. The oneshot channel never fires.
+- **Effect:** Every message spawns a fresh Claude Code process with no `--resume` flag. Each turn is a blank slate.
+- **History persistence works fine** — serialization round-trips correctly (test at `bot.rs:1335-1339`). The problem is purely that `--resume` is never invoked.
+
+### Debugging steps
+
+1. Run `claude -p "hello" --output-format stream-json --verbose 2>/dev/null` manually and inspect the NDJSON for a `session_id` field. Check what event type carries it and whether the key name matches what `process_json_event()` expects.
+2. If `session_id` is present but nested differently (e.g. inside an `event` wrapper), fix the JSON path at `claude_code.rs:348`.
+3. If `-p` mode doesn't emit `session_id` at all, consider an alternative: pass conversation history as a structured prompt prefix, or switch to the Claude API directly.
+
+### Previous attempt failed (2026-03-18)
+
+A sonnet coder attempted this story but did NOT fix the root cause. It rewrote the `chat_stream()` call in `bot.rs` to look identical to what was already there — it never investigated why `session_id` isn't being captured. The merge auto-resolver then jammed the duplicate call inside the `tokio::select!` permission loop, producing mismatched braces. The broken merge was reverted.
+
+**What the coder must actually do:**
+
+1. **Do NOT rewrite the `chat_stream()` call or the `tokio::select!` loop in `bot.rs`.** That code is correct and handles permission forwarding (story 275). Do not touch it.
+2. **The bug is in `claude_code.rs`, not `bot.rs`.** The `process_json_event()` function at line ~348 looks for `json["session_id"]` but it's likely never finding it. Start by running step 1 above to see what the actual NDJSON output looks like.
+3. **If `claude -p` doesn't emit `session_id` at all**, the `--resume` approach won't work. In that case, the fix is to pass conversation history as a prompt prefix (prepend prior turns to the user message) or use `--continue` instead of `--resume`, or call the Claude API directly instead of shelling out to the CLI.
+4. **Rebase onto current master before starting.** Master has changed significantly (spike 92, story 275 permission handling, gitignore changes).
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/267_story_mcp_update_story_tool_should_support_front_matter_fields.md

@@ -0,0 +1,19 @@
+---
+name: "MCP update_story tool should support front matter fields"
+---
+
+# Story 267: MCP update_story tool should support front matter fields
+
+## User Story
+
+As an operator using the MCP tools, I want update_story to accept optional front matter fields (like agent, manual_qa, etc.) so that I can update story metadata without editing files by hand.
+
+## Acceptance Criteria
+
+- [ ] update_story MCP tool accepts optional agent parameter to set/change the agent front matter field
+- [ ] update_story MCP tool accepts optional arbitrary front matter key-value pairs
+- [ ] Front matter updates are auto-committed via the filesystem watcher like other story mutations
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/268_refactor_upgrade_tokio_tungstenite_to_0_29_0.md

@@ -0,0 +1,23 @@
+---
+name: "Upgrade tokio-tungstenite to 0.29.0"
+---
+
+# Refactor 268: Upgrade tokio-tungstenite to 0.29.0
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Upgrade tokio-tungstenite from 0.28.0 to 0.29.0 in workspace Cargo.toml and fix any breaking API changes.
+
+## Acceptance Criteria
+
+- [ ] tokio-tungstenite = "0.29.0" in workspace Cargo.toml
+- [ ] All code compiles without errors
+- [ ] All tests pass
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/269_story_file_references_in_web_ui_chat_input.md

@@ -0,0 +1,22 @@
+---
+name: "@ file references in web UI chat input"
+---
+
+# Story 269: @ file references in web UI chat input
+
+## User Story
+
+As a user chatting in the web UI, I want to type @ to get an autocomplete overlay listing project files, so that I can reference specific files in my messages the same way Zed and Claude Code do.
+
+## Acceptance Criteria
+
+- [ ] Typing @ in the chat input triggers a file picker overlay
+- [ ] Overlay searches project files with fuzzy matching as the user types after @
+- [ ] Selecting a file inserts a reference into the message (e.g. @path/to/file.rs)
+- [ ] The referenced file contents are included as context when the message is sent to the LLM
+- [ ] Overlay is dismissable with Escape
+- [ ] Multiple @ references can be used in a single message
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/270_bug_qa_test_server_overwrites_root_mcp_json_with_wrong_port.md

@@ -0,0 +1,31 @@
+---
+name: "QA test server overwrites root .mcp.json with wrong port"
+---
+
+# Bug 270: QA test server overwrites root .mcp.json with wrong port
+
+## Description
+
+When the QA agent starts a test server in a worktree (e.g. on port 3012), that server auto-detects the shared project root and calls open_project, which writes .mcp.json with the test server's port. This clobbers the root .mcp.json that should always point to the main server (port 3001).
+
+Root cause: open_project in server/src/io/fs.rs:527 unconditionally calls write_mcp_json(&p, port) with its own port. Because worktrees share .story_kit/ with the real project, the test server resolves to the real project root and overwrites the root .mcp.json instead of writing to its own worktree directory.
+
+Fix: Remove the write_mcp_json call from open_project entirely. Worktree .mcp.json files are already written correctly during worktree creation (worktree.rs:81,97), and the root .mcp.json is committed in git. open_project should not touch it.
+
+## How to Reproduce
+
+1. QA agent starts on a story\n2. QA agent starts a test server in the worktree on a non-default port (e.g. 3012)\n3. Test server auto-opens the project root\n4. Root .mcp.json is overwritten with test port
+
+## Actual Result
+
+Root .mcp.json contains the QA test server's port (e.g. 3012) instead of the main server's port (3001). Interactive Claude sessions lose MCP connectivity.
+
+## Expected Result
+
+Root .mcp.json always points to the primary server's port. Test servers started by QA agents should not overwrite it.
+
+## Acceptance Criteria
+
+- [ ] QA test servers do not overwrite root .mcp.json
+- [ ] Root .mcp.json always reflects the primary server's port
+- [ ] Worktree .mcp.json files are only written during worktree creation

.story_kit/work/6_archived/271_story_show_assigned_agent_in_expanded_work_item_view.md

@@ -0,0 +1,19 @@
+---
+name: "Show assigned agent in expanded work item view"
+---
+
+# Story 271: Show assigned agent in expanded work item view
+
+## User Story
+
+As a project owner viewing an expanded work item in the web UI, I want to see which agent (e.g. coder-opus) has been assigned via front matter, so that I know which coder is working on or will pick up the story.
+
+## Acceptance Criteria
+
+- [ ] Expanded work item view displays the agent front matter field if set
+- [ ] Shows the specific agent name (e.g. 'coder-opus') not just 'assigned'
+- [ ] If no agent is set in front matter, the field is omitted or shows unassigned
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/272_story_clear_merge_error_front_matter_when_story_leaves_merge_stage.md

@@ -0,0 +1,19 @@
+---
+name: "Clear merge error front matter when story leaves merge stage"
+---
+
+# Story 272: Clear merge error front matter when story leaves merge stage
+
+## User Story
+
+As an operator, I want merge error front matter to be automatically removed when a story is moved out of the merge stage via MCP, so that stale error metadata doesn't persist when the story is retried.
+
+## Acceptance Criteria
+
+- [ ] When a story with merge_error front matter is moved out of 4_merge via MCP, the merge_error field is automatically stripped
+- [ ] Works for all destinations: back to 2_current, back to 1_upcoming, or forward to 5_done
+- [ ] Stories without merge_error front matter are unaffected
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/273_story_matrix_bot_sends_typing_indicator_while_waiting_for_claude_response.md

@@ -0,0 +1,24 @@
+---
+name: "Matrix bot sends typing indicator while waiting for Claude response"
+---
+
+# Story 273: Matrix bot sends typing indicator while waiting for Claude response
+
+## User Story
+
+As a user chatting with the Matrix bot, I want to see a typing indicator in Element while the bot is processing my message, so that I know it received my request and is working on a response.
+
+## Acceptance Criteria
+
+- [ ] Bot sets m.typing on the room as soon as it starts the Claude API call
+- [ ] Typing indicator is cleared when the first response chunk is sent to the room
+- [ ] Typing indicator is cleared on error so it doesn't get stuck
+- [ ] No visible delay between sending a message and seeing the typing indicator
+
+## Notes
+
+- **2026-03-18**: Moved back to current from done. Previous attempt went through the full pipeline but merged with an empty diff — no typing indicator code was actually implemented. Needs a real implementation this time.
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/274_story_mcp_pipeline_status_tool_with_agent_assignments.md

@@ -0,0 +1,20 @@
+---
+name: "MCP pipeline status tool with agent assignments"
+---
+
+# Story 274: MCP pipeline status tool with agent assignments
+
+## User Story
+
+As a user checking pipeline status, I want an MCP tool that returns a structured status report including which agent is assigned to each work item, so that I can quickly see what's active and spot stuck items.
+
+## Acceptance Criteria
+
+- [ ] New MCP tool (e.g. `get_pipeline_status`) returns all work items across all active pipeline stages (current, qa, merge, done) with their stage, name, and assigned agent
+- [ ] Upcoming backlog items are included with count or listing
+- [ ] Agent assignment info comes from story front matter (`agent` field) and/or the running agent list
+- [ ] Response is structured/deterministic (not free-form prose)
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/275_story_matrix_bot_surfaces_claude_code_permission_prompts_to_chat.md

@@ -0,0 +1,22 @@
+---
+name: "Matrix bot surfaces Claude Code permission prompts to chat"
+agent: coder-opus
+---
+
+# Story 275: Matrix bot surfaces Claude Code permission prompts to chat
+
+## User Story
+
+As a user chatting with the Matrix bot, I want to see permission prompts from Claude Code in the chat and be able to approve or deny them, so that headless Claude Code sessions don't silently hang when they need authorization to proceed.
+
+## Acceptance Criteria
+
+- [ ] When Claude Code hits a permission prompt during a bot-initiated session, the bot sends the prompt text to the Matrix room as a message
+- [ ] The user can approve or deny the permission by replying in chat (e.g. yes/no or a reaction)
+- [ ] The bot relays the user decision back to the Claude Code subprocess so execution continues
+- [ ] If the user does not respond within a configurable timeout, the permission is denied (fail-closed)
+- [ ] The bot does not hang or timeout silently when a permission prompt is pending - the user always sees what is happening
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/276_story_detect_and_log_when_root_mcp_json_port_is_modified.md

@@ -0,0 +1,17 @@
+---
+name: "Detect and log when root .mcp.json port is modified"
+---
+
+# Story 276: Detect and log when root .mcp.json port is modified
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] TODO
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/277_story_matrix_bot_uses_its_configured_name_instead_of_claude.md

@@ -0,0 +1,19 @@
+---
+name: "Matrix bot uses its configured name instead of \"Claude\""
+---
+
+# Story 277: Matrix bot uses its configured name instead of "Claude"
+
+## User Story
+
+As a Matrix user, I want the bot to identify itself by its configured name (e.g., "Timmy") rather than "Claude", so that the bot feels like a distinct personality in the chat.
+
+## Acceptance Criteria
+
+- [ ] The Matrix bot refers to itself by its configured display name (e.g., 'Timmy') in conversations, not 'Claude'
+- [ ] The bot's self-referencing name is derived from configuration, not hardcoded
+- [ ] If no custom name is configured, the bot falls back to a sensible default
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/278_story_auto_assign_agents_to_pipeline_items_on_server_startup.md

@@ -0,0 +1,17 @@
+---
+name: "Auto-assign agents to pipeline items on server startup"
+---
+
+# Story 278: Auto-assign agents to pipeline items on server startup
+
+## User Story
+
+As a ..., I want ..., so that ...
+
+## Acceptance Criteria
+
+- [ ] TODO
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/279_story_auto_assign_should_respect_agent_stage_when_front_matter_specifies_agent.md

@@ -0,0 +1,20 @@
+---
+name: "Auto-assign should respect agent stage when front matter specifies agent"
+---
+
+# Story 279: Auto-assign should respect agent stage when front matter specifies agent
+
+## User Story
+
+As a project operator, I want auto-assign to respect the pipeline stage when a story's front matter specifies a preferred agent, so that a coder agent isn't assigned to do QA work just because the story originally requested that coder.
+
+## Acceptance Criteria
+
+- [ ] When a story in `3_qa/` has `agent: coder-opus` in front matter, auto-assign skips the preferred agent (stage mismatch) and assigns a free QA-stage agent instead
+- [ ] When a story in `2_current/` has `agent: coder-opus` in front matter, auto-assign still respects the preference (stage matches)
+- [ ] When the preferred agent's stage mismatches, auto-assign logs a message indicating the stage mismatch and fallback
+
+## Out of Scope
+
+- Changing the front matter `agent` field automatically when a story advances stages
+- Adding per-stage agent preferences to front matter

.story_kit/work/6_archived/281_story_matrix_bot_announces_itself_when_it_comes_online.md

@@ -0,0 +1,20 @@
+---
+name: "Matrix bot announces itself when it comes online"
+---
+
+# Story 281: Matrix bot announces itself when it comes online
+
+## User Story
+
+As a user in the Matrix room, I want Timmy to post a message when he starts up, so that I know the bot is online and ready to accept commands.
+
+## Acceptance Criteria
+
+- [ ] Bot sends a brief greeting message to each configured room on startup (e.g. 'Timmy is online.')
+- [ ] Message uses the configured display_name, not a hardcoded name
+- [ ] Message is only sent once per startup, not on reconnects or sync resumptions
+- [ ] Bot does not announce if it was already running (e.g. after a brief network blip)
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/282_story_matrix_bot_ambient_mode_toggle_via_chat_command.md

@@ -0,0 +1,24 @@
+---
+name: "Matrix bot ambient mode toggle via chat command"
+---
+
+# Story 282: Matrix bot ambient mode toggle via chat command
+
+## User Story
+
+As a user chatting with Timmy in a Matrix room, I want to toggle between "addressed mode" (bot only responds when mentioned by name) and "ambient mode" (bot responds to all messages) via a chat command, so that I don't have to @-mention the bot on every message when I'm the only one around.
+
+## Acceptance Criteria
+
+- [ ] Matrix bot defaults to addressed mode — only forwards messages containing the bot's name to Claude
+- [ ] Chat command "{bot_name} ambient on" switches to ambient mode — bot forwards all room messages to Claude (bot name comes from display_name in bot.toml)
+- [ ] Chat command "{bot_name} ambient off" switches back to addressed mode
+- [ ] Mode is persisted per-room in bot.toml so it survives bot restarts
+- [ ] bot.toml.example includes the ambient_mode setting with a comment explaining it
+- [ ] Bot confirms the mode switch with a short response in chat
+- [ ] When other users join or are active, user can flip back to addressed mode to avoid noise
+- [ ] Ambient mode applies per-room (not globally across all rooms)
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/283_bug_pipeline_does_not_check_manual_qa_flag_before_advancing_from_qa_to_merge.md

@@ -0,0 +1,30 @@
+---
+name: "Pipeline does not check manual_qa flag before advancing from QA to merge"
+---
+
+# Bug 283: Pipeline does not check manual_qa flag before advancing from QA to merge
+
+## Description
+
+Story 247 added the manual_qa front matter field and the MCP tooling to set it, but the pipeline in pool.rs never actually checks the flag. After QA passes gates and coverage, stories move straight to merge regardless of manual_qa setting.
+
+## How to Reproduce
+
+1. Create a story with manual_qa: true in front matter
+2. Let it go through the coder and QA stages
+3. Observe that it moves directly to merge without waiting for human approval
+
+## Actual Result
+
+Stories always advance from QA to merge automatically, ignoring the manual_qa flag.
+
+## Expected Result
+
+Stories with manual_qa: true should pause after QA passes and wait for human approval before moving to merge. Stories with manual_qa: false (the default) should advance automatically as they do now.
+
+## Acceptance Criteria
+
+- [ ] Pipeline checks manual_qa front matter field after QA gates pass
+- [ ] manual_qa defaults to false — stories advance automatically unless explicitly opted in
+- [ ] Stories with manual_qa: true wait in 3_qa for human approval via accept_story or the UI
+- [ ] Stories with manual_qa: false proceed directly from QA to merge as before

.story_kit/work/6_archived/284_story_matrix_bot_status_command_shows_pipeline_and_agent_availability.md

@@ -0,0 +1,22 @@
+---
+name: "Matrix bot status command shows pipeline and agent availability"
+---
+
+# Story 284: Matrix bot status command shows pipeline and agent availability
+
+## User Story
+
+As a user in a Matrix room, I want to type "{bot_name} status" and get a formatted summary of the full pipeline (upcoming through done) with agent assignments, plus which agents are currently free, so that I can check project status without leaving chat.
+
+## Acceptance Criteria
+
+- [ ] Chat command "{bot_name} status" triggers a pipeline status display (bot name comes from display_name in bot.toml)
+- [ ] Output shows all stages: upcoming, current, qa, merge, done — with story names and IDs
+- [ ] Each active story shows its assigned agent name and model
+- [ ] Output includes a section showing which agents are free (not currently assigned to any story)
+- [ ] Response is formatted for readability in Matrix (monospace or markdown as appropriate)
+- [ ] Command is handled at the bot level — does not require a full Claude invocation
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/285_story_matrix_bot_help_command_lists_available_bot_commands.md

@@ -0,0 +1,25 @@
+---
+name: "Matrix bot help command lists available bot commands"
+---
+
+# Story 285: Matrix bot help command lists available bot commands
+
+## User Story
+
+As a user in a Matrix room, I want to type "{bot_name} help" and get a list of all available bot commands with brief descriptions, so that I can discover what the bot can do without having to ask or remember.
+
+## Acceptance Criteria
+
+- [ ] Chat command "{bot_name} help" displays a list of all available bot-level commands (bot name comes from display_name in bot.toml)
+- [ ] Each command is shown with a short description of what it does
+- [ ] Help output is formatted for readability in Matrix
+- [ ] Help command is handled at the bot level — does not require a full Claude invocation
+- [ ] Help list automatically includes new commands as they are added (driven by a registry or similar, not a hardcoded string)
+
+## Notes
+
+- **2026-03-18**: Moved back to current from done. Previous attempt committed code directly to master (commit a32cfbd) instead of the worktree, and the help command is not functional in the running server. Needs a clean implementation this time.
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/286_story_server_self_rebuild_and_restart_via_mcp_tool.md

@@ -0,0 +1,22 @@
+---
+name: "Server self-rebuild and restart via MCP tool"
+---
+
+# Story 286: Server self-rebuild and restart via MCP tool
+
+## User Story
+
+As a project owner away from my terminal, I want to tell the bot to restart the server so that it picks up new code changes, without needing physical access to the machine.
+
+## Acceptance Criteria
+
+- [ ] MCP tool `rebuild_and_restart` triggers a cargo build of the server
+- [ ] If the build fails, server stays up and returns the build error
+- [ ] If the build succeeds, server re-execs itself with the new binary using std::os::unix::process::CommandExt::exec()
+- [ ] Server logs the restart so it's traceable
+- [ ] Matrix bot reconnects automatically after the server comes back up
+- [ ] Running agents are gracefully stopped before re-exec
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/287_story_rename_upcoming_pipeline_stage_to_backlog.md

@@ -0,0 +1,22 @@
+---
+name: "Rename upcoming pipeline stage to backlog"
+---
+
+# Story 287: Rename upcoming pipeline stage to backlog
+
+## User Story
+
+As a project owner, I want the "upcoming" pipeline stage renamed to "backlog" throughout the codebase, UI, and directory structure, so that the terminology better reflects that these items are not necessarily coming up next.
+
+## Acceptance Criteria
+
+- [ ] Directory renamed from 1_upcoming to 1_backlog
+- [ ] All server code references updated (watcher, lifecycle, MCP tools, workflow, etc.)
+- [ ] Frontend UI labels updated
+- [ ] MCP tool descriptions and outputs use "backlog" instead of "upcoming"
+- [ ] Existing story/bug files moved to the new directory
+- [ ] Git commit messages use "backlog" for new items going forward
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/288_bug_ambient_mode_state_lost_on_server_restart.md

@@ -0,0 +1,29 @@
+---
+name: "Ambient mode state lost on server restart"
+---
+
+# Bug 288: Ambient mode state lost on server restart
+
+## Description
+
+Story 282 implemented ambient mode toggle but only in-memory. The acceptance criterion requiring persistence in bot.toml was not implemented. Every server restart (including rebuild_and_restart) clears ambient mode for all rooms.
+
+## How to Reproduce
+
+1. Type "timmy ambient on" — get confirmation
+2. Restart server (or rebuild_and_restart)
+3. Send unaddressed message — bot ignores it, ambient mode is gone
+
+## Actual Result
+
+Ambient mode state is lost on server restart.
+
+## Expected Result
+
+Ambient mode per-room state is persisted in bot.toml and restored on startup.
+
+## Acceptance Criteria
+
+- [ ] Ambient mode per-room state is saved to bot.toml when toggled
+- [ ] Ambient mode state is restored from bot.toml on server startup
+- [ ] bot.toml.example includes the ambient_rooms setting with a comment

.story_kit/work/6_archived/289_bug_rebuild_and_restart_mcp_tool_does_not_rebuild.md

@@ -0,0 +1,28 @@
+---
+name: "rebuild_and_restart MCP tool does not rebuild"
+agent: coder-opus
+---
+
+# Bug 289: rebuild_and_restart MCP tool does not rebuild
+
+## Description
+
+The rebuild_and_restart MCP tool re-execs the server binary but does not run cargo build first. It restarts with the old binary, so code changes are not picked up.
+
+## How to Reproduce
+
+1. Make a code change to the server
+2. Call rebuild_and_restart via MCP
+3. Observe the server restarts but the code change is not reflected
+
+## Actual Result
+
+Server re-execs with the old binary. Code changes are not compiled.
+
+## Expected Result
+
+Server runs cargo build --release (or cargo build) before re-execing, so the new binary includes the latest code changes.
+
+## Acceptance Criteria
+
+- [ ] Bug is fixed and verified

.story_kit/work/6_archived/290_story_show_agent_output_stream_in_expanded_work_item_detail_panel.md

@@ -0,0 +1,22 @@
+---
+name: "Remove agent thinking traces from agents sidebar"
+---
+
+# Story 290: Remove agent thinking traces from agents sidebar
+
+## User Story
+
+As a user viewing an expanded work item in the web UI, I want to see the live agent output stream (thinking traces, tool calls, progress) for the agent working on that story, so that I can monitor progress in context rather than in the agents sidebar.
+
+## Acceptance Criteria
+
+- [ ] Agent thinking traces are removed from the agents sidebar panel — they should only appear in the work item detail panel (which already has SSE streaming wired up in `WorkItemDetailPanel.tsx`)
+
+## Notes
+
+The detail panel (`WorkItemDetailPanel.tsx`) already has agent log streaming implemented — SSE subscription, real-time output, status badges, etc. The only remaining work is removing the thinking traces from the agents sidebar (`AgentPanel.tsx` or similar) so they don't appear in both places.
+
+## Out of Scope
+
+- Replacing the agents sidebar entirely — it still shows agent names, status, and assignments
+- Historical agent output (only live stream while agent is running)

.story_kit/work/6_archived/291_story_show_test_results_in_work_item_detail_panel.md

@@ -0,0 +1,21 @@
+---
+name: "Show test results in work item detail panel"
+---
+
+# Story 291: Show test results in work item detail panel
+
+## User Story
+
+As a project owner viewing a work item in the web UI, I want to see the most recent test run results in the expanded detail panel, so that I can quickly see pass/fail status without digging through agent logs.
+
+## Acceptance Criteria
+
+- [ ] Expanded work item detail panel shows the most recent test results for that story
+- [ ] Test results display pass/fail counts for unit and integration tests
+- [ ] Failed tests are listed by name so you can see what broke
+- [ ] Test results are read from the story file's ## Test Results section (already written by record_tests MCP tool)
+- [ ] Panel shows a clear empty state when no test results exist yet
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/292_story_show_server_logs_in_web_ui.md

@@ -0,0 +1,22 @@
+---
+name: "Show server logs in web UI"
+review_hold: true
+---
+
+# Story 292: Show server logs in web UI
+
+## User Story
+
+As a project owner using the web UI, I want to see live server logs in the interface, so that I can debug agent behavior and pipeline issues without needing terminal access.
+
+## Acceptance Criteria
+
+- [ ] Web UI has a server logs panel accessible from the main interface
+- [ ] Logs stream in real-time via WebSocket or SSE
+- [ ] Logs can be filtered by keyword (same as get_server_logs MCP tool's filter param)
+- [ ] Log entries show timestamp and severity level
+- [ ] Panel doesn't interfere with the existing pipeline board and work item views
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/293_story_register_all_bot_commands_in_the_command_registry.md

@@ -0,0 +1,23 @@
+---
+name: "Register all bot commands in the command registry"
+review_hold: true
+---
+
+# Story 293: Register all bot commands in the command registry
+
+## User Story
+
+As a user, I want all bot commands (help, status, ambient on/off) to be registered in the command registry in commands.rs, so that the help command lists everything the bot can do and there's one consistent mechanism for handling bot-level commands.
+
+## Acceptance Criteria
+
+- [ ] Status command is moved from bot.rs into the command registry in commands.rs
+- [ ] Ambient on/off command is moved from bot.rs into the command registry in commands.rs
+- [ ] Help command output lists all registered commands including status and ambient
+- [ ] No bot-level commands are handled outside of the registry (single mechanism)
+- [ ] Existing behavior of all commands is preserved
+- [ ] Registry handler functions receive enough context to perform their work (e.g. project_root for status, ambient_rooms for ambient)
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/294_story_rename_app_title_from_story_kit_to_storkit.md

@@ -0,0 +1,19 @@
+---
+name: "Rename app title from Story Kit to Storkit"
+review_hold: true
+---
+
+# Story 294: Rename app title from Story Kit to Storkit
+
+## User Story
+
+As a user, I want the application title to say "Storkit" instead of "Story Kit", so that the branding reflects the new name.
+
+## Acceptance Criteria
+
+- [ ] The top title in the web UI header displays "Storkit" instead of "Story Kit"
+- [ ] Any other visible references to "Story Kit" in the UI are updated to "Storkit"
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/295_bug_stories_stuck_in_qa_when_qa_agent_is_busy.md

@@ -0,0 +1,64 @@
+---
+name: "Stories stuck in QA when QA agent is busy"
+review_hold: true
+---
+
+# Bug 295: Stories stuck in QA when QA agent is busy
+
+## Description
+
+When multiple stories pass coding gates simultaneously and move to QA, only the first one gets a QA agent assigned. The others fail with "Agent 'qa' is already running" and are never retried when the QA agent becomes free. Stories get stuck in QA with no agent indefinitely.
+
+The root cause is in the server-owned agent completion handler in `server/src/agents/pool.rs`. When a coder finishes and gates pass, the server calls the pipeline advance logic which tries to start a QA agent. If the QA agent is already busy on another story, the start fails with an error and the story is left in `3_qa/` with no agent. There is no retry mechanism — the `auto_assign_available_work` function is only called on startup (via `reconcile_on_startup`) and when agents are manually started, not when agents complete.
+
+## How to Reproduce
+
+1. Have 3 stories in current with coders running (e.g. coder-1, coder-2, coder-opus)
+2. All 3 coders finish within seconds of each other and pass gates
+3. Server tries to start QA agent on all 3:
+   - Story 292: `qa` agent starts successfully
+   - Story 293: fails — `"Agent 'qa' is already running on story '292'"`
+   - Story 294: fails — same error
+4. QA on 292 completes (gates pass after retry)
+5. Stories 293 and 294 remain stuck in QA with no agent — nobody retries them
+
+## Server Log Evidence (2026-03-18)
+
+```
+21:00:35 [agent:292:coder-1] Done.
+21:00:42 [agents] Server-owned completion for '292:coder-1': gates_passed=true
+21:00:47 [agent:292:qa] Spawning claude...
+
+21:01:32 [agent:293:coder-2] Done.
+21:01:34 [agent:294:coder-opus] Done.
+
+21:01:41 [agents] Server-owned completion for '293:coder-2': gates_passed=true
+21:01:41 [ERROR] Failed to start qa agent for '293': Agent 'qa' is already running on story '292'
+
+21:01:48 [agents] Server-owned completion for '294:coder-opus': gates_passed=true
+21:01:48 [ERROR] Failed to start qa agent for '294': Agent 'qa' is already running on story '292'
+
+21:08:18 [agents] Server-owned completion for '292:qa': gates_passed=true
+(293 and 294 are never picked up)
+```
+
+## Actual Result
+
+Stories 293 and 294 stuck in QA with no agent after 292's QA agent was busy. The pipeline status shows them in `3_qa` with `agent: null` indefinitely.
+
+## Expected Result
+
+When a QA agent finishes a story, `auto_assign_available_work` should be called to scan for unassigned stories in all active stages and assign free agents. Stories 293 and 294 should get QA agents as soon as the QA agent finishes with 292.
+
+## Suggested Fix
+
+In the server-owned completion handler (the code path that runs after an agent's process exits), call `auto_assign_available_work()` after processing the completed story. This ensures that when any agent becomes free, the server immediately looks for pending work to assign it to.
+
+The relevant code is in `server/src/agents/pool.rs` — the `handle_agent_completion` path (around line 804-950) and `auto_assign_available_work` (around line 1437-1559).
+
+## Acceptance Criteria
+
+- [ ] When an agent completes (any stage), `auto_assign_available_work` is called to pick up pending stories
+- [ ] Stories that failed agent assignment due to busy agents are picked up when agents become available
+- [ ] Server logs when a story is queued for retry vs permanently failed
+- [ ] Multiple stories completing QA sequentially works correctly (story A finishes QA → story B gets QA agent)

.story_kit/work/6_archived/296_story_track_per_agent_token_usage_for_cost_visibility_and_optimisation.md

@@ -0,0 +1,54 @@
+---
+name: "Track per-agent token usage for cost visibility and optimisation"
+---
+
+# Story 296: Track per-agent token usage for cost visibility and optimisation
+
+## User Story
+
+As a project owner, I want to see how many tokens each agent consumes per story, so that I can identify expensive operations and optimise token usage across the pipeline.
+
+## Acceptance Criteria
+
+- [ ] Implement per-agent token tracking that captures input tokens, output tokens, and cache tokens for each agent run
+- [ ] Token usage is recorded per story and per agent (e.g. coder-1 on story 293 used X tokens)
+- [ ] Running totals are visible — either via MCP tool, web UI, or both
+- [ ] Historical token usage is persisted so it survives server restarts (e.g. in story files or a separate log)
+- [ ] Data is structured to support later analysis (e.g. which agent types are most expensive, which stories cost the most)
+
+## Research Notes
+
+Claude Code's JSON stream already emits all the data we need. No external library required.
+
+**Data available in the `result` event at end of each agent session:**
+```json
+{
+  "type": "result",
+  "total_cost_usd": 1.57,
+  "usage": {
+    "input_tokens": 7,
+    "output_tokens": 475,
+    "cache_creation_input_tokens": 185020,
+    "cache_read_input_tokens": 810585
+  },
+  "modelUsage": {
+    "claude-opus-4-6[1m]": {
+      "inputTokens": 7,
+      "outputTokens": 475,
+      "cacheReadInputTokens": 810585,
+      "cacheCreationInputTokens": 185020,
+      "costUSD": 1.57
+    }
+  }
+}
+```
+
+**Where to hook in:**
+- `server/src/llm/providers/claude_code.rs` — `process_json_event()` already parses the JSON stream but currently ignores usage data from the `result` event
+- Parse `usage` + `total_cost_usd` from the `result` event and pipe it to the agent completion handler in `server/src/agents/pool.rs`
+
+**No external libraries needed** — Anthropic SDK, LiteLLM, Helicone, Langfuse etc. are all overkill since we have direct access to Claude Code's output stream.
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/297_story_improve_bot_status_command_formatting.md

@@ -0,0 +1,20 @@
+---
+name: "Improve bot status command formatting"
+---
+
+# Story 297: Improve bot status command formatting
+
+## User Story
+
+As a user reading the bot's status output in Matrix, I want to see clean story numbers and titles (not filenames), with agent assignments shown inline, so that the output is easy to scan at a glance.
+
+## Acceptance Criteria
+
+- [ ] Status output shows story number and title (e.g. '293 — Register all bot commands') not the full filename stem
+- [ ] Each story shows which agent is working on it if one is assigned (e.g. 'coder-1 (sonnet)')
+- [ ] Stories with no agent assigned show no agent info rather than cluttering the output
+- [ ] Output is compact and scannable in a Matrix chat window
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/298_story_bot_htop_command_with_live_updating_process_dashboard.md

@@ -0,0 +1,25 @@
+---
+name: "Bot htop command with live-updating process dashboard"
+---
+
+# Story 298: Bot htop command with live-updating process dashboard
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} htop" and see a live-updating dashboard of system load and agent processes, so that I can monitor resource usage without needing terminal access.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} htop' sends an initial status message showing load average and per-agent process info (CPU, memory, story assignment)
+- [ ] Message is edited every 5 seconds with updated stats
+- [ ] Only shows processes related to the project (agent PIDs and their child process trees)
+- [ ] '{bot_name} htop stop' stops the live updating and sends a final 'monitoring stopped' edit
+- [ ] Works regardless of what language/toolchain the agents are using (monitors by PID tree, not by process name)
+- [ ] Uses Matrix message editing (replacement events) to update in place
+- [ ] Only one htop session per room at a time — a second '{bot_name} htop' stops the existing session and starts a fresh one
+- [ ] Auto-stops after 5 minutes by default to prevent runaway editing
+- [ ] Optional timeout override: '{bot_name} htop 10m' to set a custom duration
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/299_story_bot_git_status_command_shows_working_tree_and_branch_info.md

@@ -0,0 +1,22 @@
+---
+name: "Bot git status command shows working tree and branch info"
+---
+
+# Story 299: Bot git status command shows working tree and branch info
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} git" and see the current git status (branch, uncommitted changes, how far ahead/behind remote), so that I can check the repo state without terminal access.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} git' displays current branch name
+- [ ] Shows count of uncommitted changes (staged and unstaged) with filenames
+- [ ] Shows how many commits ahead/behind the remote branch
+- [ ] Output is formatted compactly for Matrix chat
+- [ ] Registered in the command registry in commands.rs so it appears in help output
+- [ ] Handled at bot level without LLM invocation
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/300_story_show_token_cost_badge_on_pipeline_board_work_items.md

@@ -0,0 +1,21 @@
+---
+name: "Show token cost badge on pipeline board work items"
+---
+
+# Story 300: Show token cost badge on pipeline board work items
+
+## User Story
+
+As a project owner viewing the pipeline board, I want to see the total token cost for each work item displayed as a badge, so that I can quickly spot expensive stories at a glance.
+
+## Acceptance Criteria
+
+- [ ] Each work item on the pipeline board shows its total cost in USD as a small badge
+- [ ] Cost is fetched from the token_usage.jsonl data via a new API endpoint
+- [ ] Items with no recorded usage show no badge (not $0.00)
+- [ ] Cost updates when the pipeline refreshes (e.g. after an agent completes)
+- [ ] Expanded work item detail panel shows per-agent cost breakdown (coder, QA, mergemaster) with token counts
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/301_story_dedicated_token_usage_page_in_web_ui.md

@@ -0,0 +1,21 @@
+---
+name: "Dedicated token usage page in web UI"
+---
+
+# Story 301: Dedicated token usage page in web UI
+
+## User Story
+
+As a project owner, I want a dedicated token usage page in the web UI that shows per-story and per-agent cost breakdowns with totals, so that I can analyse where tokens are being spent and identify optimisation opportunities.
+
+## Acceptance Criteria
+
+- [ ] New page/panel accessible from the main navigation
+- [ ] Shows a table of all recorded agent sessions with story, agent name, model, token counts, and cost
+- [ ] Sortable by cost, story, agent, or date
+- [ ] Shows summary totals: total cost, cost by agent type (coder vs QA vs mergemaster), cost by model (opus vs sonnet)
+- [ ] Data loads from the token_usage.jsonl log via API endpoint
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/302_story_bot_cost_command_shows_total_and_per_story_token_spend.md

@@ -0,0 +1,22 @@
+---
+name: "Bot cost command shows total and per-story token spend"
+---
+
+# Story 302: Bot cost command shows total and per-story token spend
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} cost" to see total token spend and the top most expensive stories, so that I can check burn rate from my phone.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} cost' shows total spend for the last 24 hours
+- [ ] Shows top 5 most expensive stories from the last 24 hours with their costs
+- [ ] Shows cost breakdown by agent type (coder, QA, mergemaster) for the last 24 hours
+- [ ] Also shows an all-time total for context
+- [ ] Registered in the command registry so it appears in help output
+- [ ] Handled at bot level without LLM invocation
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/303_story_bot_cost_command_with_story_filter_for_detailed_breakdown.md

@@ -0,0 +1,21 @@
+---
+name: "Bot cost command with story filter for detailed breakdown"
+---
+
+# Story 303: Bot cost command with story filter for detailed breakdown
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} cost 293" to see a detailed token breakdown for a specific story, so that I can understand where the tokens went on an expensive item.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} cost {story_number}' shows all agent sessions for that story
+- [ ] Each session shows agent name, model, input/output/cache tokens, and cost in USD
+- [ ] Shows total cost for the story at the bottom
+- [ ] Registered in the command registry (can share the 'cost' command with args parsing)
+- [ ] Returns a friendly message if no usage data exists for the story
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/304_story_mcp_tool_to_move_stories_between_pipeline_stages.md

@@ -0,0 +1,23 @@
+---
+name: "MCP tool to move stories between pipeline stages"
+---
+
+# Story 304: MCP tool to move stories between pipeline stages
+
+## User Story
+
+As a bot operator (Timmy), I want an MCP tool that moves stories between pipeline stages, so that I don't need shell mv permissions to manage the pipeline.
+
+## Acceptance Criteria
+
+- [ ] New MCP tool 'move_story' accepts story_id and target_stage (e.g. 'backlog', 'current', 'qa', 'merge', 'done')
+- [ ] Validates the story exists before moving
+- [ ] Handles the file move between stage directories
+- [ ] Returns a confirmation message with the old and new stage
+- [ ] Works for stories, bugs, spikes, and refactors
+- [ ] Replaces the need for shell mv commands to move story files
+- [ ] Tool description tells bots to prefer specific tools (accept_story, move_story_to_merge, request_qa) when available, and use move_story only for arbitrary moves that lack a dedicated tool (e.g. moving to backlog, moving ghost stories back to current)
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/305_story_bot_show_command_displays_story_text_in_chat.md

@@ -0,0 +1,21 @@
+---
+name: "Bot show command displays story text in chat"
+---
+
+# Story 305: Bot show command displays story text in chat
+
+## User Story
+
+As a project owner in a Matrix room, I want to type "{bot_name} show {story_number}" and see the full story text displayed in chat, so that I can review story details without accessing the file system.
+
+## Acceptance Criteria
+
+- [ ] '{bot_name} show {number}' finds the story/bug/spike by number across all pipeline stages and displays its full markdown content
+- [ ] Output is formatted for readability in Matrix
+- [ ] Returns a friendly message if no story with that number exists
+- [ ] Registered in the command registry so it appears in help output
+- [ ] Handled at bot level without LLM invocation
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/306_story_replace_manual_qa_boolean_with_configurable_qa_mode_field.md

@@ -0,0 +1,26 @@
+---
+name: "Replace manual_qa boolean with configurable qa mode field"
+---
+
+# Story 306: Replace manual_qa boolean with configurable qa mode field
+
+## User Story
+
+As a project owner, I want to configure QA mode per-story and set a project-wide default, so that I can choose between human review, server-only gate checks, or full agent QA on a per-story basis.
+
+## Acceptance Criteria
+
+- [ ] Replace manual_qa: true/false front matter field with qa: human|server|agent
+- [ ] qa: server — skip the QA agent entirely, rely on server's automated gate checks (clippy + tests + coverage). If gates pass, advance straight to merge
+- [ ] qa: agent — current behavior, spin up a QA agent (Claude session) to review code and run gates
+- [ ] qa: human — hold in QA for human approval after server gates pass (current manual_qa: true behavior)
+- [ ] Default qa mode is configurable in project.toml (e.g. default_qa = "server")
+- [ ] Set the initial default in project.toml to "server"
+- [ ] Per-story front matter qa field overrides the project default
+- [ ] Backwards compatible: existing stories without a qa field use the project default
+- [ ] Remove the old manual_qa field handling and replace with the new qa field throughout pool.rs, story_metadata.rs, and any other references
+- [ ] Update bot.toml.example and project.toml documentation to reflect the new field
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/307_story_configurable_coder_pool_size_and_default_model_in_project_toml.md

@@ -0,0 +1,25 @@
+---
+name: "Configurable coder pool size and default model in project.toml"
+agent: coder-opus
+---
+
+# Story 307: Configurable coder pool size and default model in project.toml
+
+## User Story
+
+As a project owner, I want to configure the number of concurrent coder agents and their default model in project.toml, so that I can control resource usage and cost while still being able to override per-story when needed.
+
+## Acceptance Criteria
+
+- [ ] New project.toml setting: default_coder_model (e.g. 'sonnet') determines which model is used for coder agents by default
+- [ ] New project.toml setting: max_coders (e.g. 3) limits concurrent coder agent slots
+- [ ] Add one more sonnet coder to the agent config (coder-3) for a total of 3 sonnet coders
+- [ ] When all coder slots are full, new stories wait in current until a slot frees up
+- [ ] Per-story front matter agent field still overrides the default (e.g. agent: coder-opus assigns opus)
+- [ ] Opus coders are only used when explicitly requested via front matter
+- [ ] QA and mergemaster limits are unchanged (not configurable via this story)
+- [ ] auto_assign_available_work respects the max_coders limit
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/309_story_show_token_cost_breakdown_in_expanded_work_item_detail_panel.md

@@ -0,0 +1,20 @@
+---
+name: "Show token cost breakdown in expanded work item detail panel"
+---
+
+# Story 309: Show token cost breakdown in expanded work item detail panel
+
+## User Story
+
+As a project owner viewing a work item in the web UI, I want to see a per-agent token cost breakdown in the expanded detail panel, so that I can understand where tokens were spent on that story.
+
+## Acceptance Criteria
+
+- [ ] WorkItemDetailPanel fetches token cost data using the existing /work-items/:story_id/token-cost endpoint
+- [ ] Shows per-agent session breakdown: agent name, model, token counts (input/output/cache), cost in USD
+- [ ] Shows total cost for the story
+- [ ] Shows empty state when no token data exists for the story
+
+## Out of Scope
+
+- TBD

.story_kit/work/6_archived/92_spike_stop_auto_committing_intermediate_pipeline_moves.md

@@ -0,0 +1,119 @@
+---
+name: "Stop auto-committing intermediate pipeline moves"
+agent: "coder-opus"
+review_hold: true
+---
+
+# Spike 92: Stop auto-committing intermediate pipeline moves
+
+## Goal
+
+Determine how to stop the filesystem watcher from auto-committing every pipeline stage move (upcoming -> current -> qa -> merge -> done -> archive) while still committing at terminal states (creation in upcoming, acceptance in done and archived). This keeps git history clean while preserving cross-machine portability for completed work.
+
+## Context
+
+The watcher in `server/src/io/watcher.rs` currently auto-commits every file change in `.story_kit/work/`. A single story run generates 5+ commits just from pipeline moves:
+- `story-kit: create 42_story_foo`
+- `story-kit: start 42_story_foo`
+- `story-kit: queue 42_story_foo for QA`
+- `story-kit: queue 42_story_foo for merge`
+- `story-kit: accept 42_story_foo`
+
+Since story runs complete relatively quickly, the intermediate state (current/qa/merge) is transient and doesn't need to be committed. Only creation and archival are meaningful checkpoints.
+
+## Questions to Answer
+
+1. Can we filter `stage_metadata()` to only commit for `1_upcoming` and `6_archived` stages while still broadcasting `WatcherEvent`s for all stages (so the frontend stays in sync)?
+2. Should we keep `git add -A .story_kit/work/` for the committed stages, or narrow it to only the specific file?
+3. What happens if the server crashes mid-pipeline? Uncommitted moves are lost — is this acceptable given the story can just be re-run?
+4. Should intermediate moves be `.gitignore`d at the directory level, or is filtering in the watcher sufficient?
+5. Do any other parts of the system (agent worktree setup, merge_agent_work, sparse checkout) depend on intermediate pipeline files being committed to master?
+
+## Findings
+
+### Q1: Can we filter to only commit terminal stages?
+
+**Yes.** The fix is in `flush_pending()`, not `stage_metadata()`. We add a `should_commit_stage()` predicate that returns `true` only for `1_upcoming` and `6_archived`. The event broadcast path is decoupled from the commit path — `flush_pending()` always broadcasts a `WatcherEvent` regardless of whether it commits.
+
+Prototype implemented: added `COMMIT_WORTHY_STAGES` constant and `should_commit_stage()` function. The change is ~15 lines including the constant, predicate, and conditional in `flush_pending()`.
+
+### Q2: Keep `git add -A .story_kit/work/` or narrow to specific file?
+
+**Keep `git add -A .story_kit/work/`.** When committing a terminal stage (e.g. `6_archived`), the file has been moved from a previous stage (e.g. `5_done`). Using `-A` on the whole work directory captures both the addition in the new stage and the deletion from the old stage in a single commit. Narrowing to the specific file would miss the deletion side of the move.
+
+### Q3: Server crash mid-pipeline — acceptable?
+
+**Yes.** If the server crashes while a story is in `2_current`, `3_qa`, or `4_merge`, the file is lost from git but:
+- The story file still exists on the filesystem (it's just not committed)
+- The agent's work is in its own feature branch/worktree (independent of pipeline file state)
+- The story can be re-queued from `1_upcoming` which IS committed
+- Pipeline state is transient by nature — it reflects "what's happening right now", not permanent record
+
+### Q4: `.gitignore` vs watcher filtering?
+
+**Watcher filtering is sufficient.** `.gitignore` approach (Option C) has downsides:
+- `git status` won't show pipeline state, making debugging harder
+- If you ever need to commit an intermediate state (e.g. for a new feature), you'd have to fight `.gitignore`
+- Watcher filtering is explicit and easy to understand — a constant lists the commit-worthy stages
+- No risk of accidentally ignoring files that should be tracked
+
+### Q5: Dependencies on intermediate pipeline commits?
+
+**None found.** Thorough investigation confirmed:
+
+1. **`merge_agent_work`** (`agents/merge.rs`): Creates a temporary `merge-queue/` branch and worktree. Reads the feature branch, not pipeline files. After merge, calls `move_story_to_archived()` which is a filesystem operation.
+
+2. **Agent worktree setup** (`worktree.rs`): Creates worktrees from feature branches. Sparse checkout is a no-op (disabled). Does not read pipeline file state from git.
+
+3. **MCP tool handlers** (`agents/lifecycle.rs`): `move_story_to_current()`, `move_story_to_merge()`, `move_story_to_qa()`, `move_story_to_archived()` — all pure filesystem `fs::rename()` operations. None perform git commits.
+
+4. **Frontend** (`http/workflow.rs`): `load_pipeline_state()` reads directories from the filesystem directly via `fs::read_dir()`. Never calls git. WebSocket events keep the frontend in sync.
+
+5. **No git inspection commands** reference pipeline stage directories anywhere in the codebase.
+
+### Edge Cases
+
+- **Multi-machine sync:** Only `1_upcoming` and `6_archived` are committed. If you push/pull, you'll see story creation and archival but not intermediate pipeline state. This is correct — intermediate state is machine-local runtime state.
+- **Manual git operations:** `git status` will show uncommitted files in intermediate stages. This is actually helpful for debugging — you can see what's in the pipeline without grepping git log.
+- **Sweep (5_done → 6_archived):** The sweep moves files to `6_archived`, which triggers a watcher event that WILL commit (since `6_archived` is a terminal stage). This naturally captures the final state.
+
+## Approach to Investigate
+
+### Option A: Filter in `flush_pending()` ← **RECOMMENDED**
+- In `flush_pending()`, still broadcast the `WatcherEvent` for all stages
+- Only call `git_add_work_and_commit()` for stages `1_upcoming` and `6_archived`
+- Simplest change — ~15 lines modified in `watcher.rs`
+
+### Option B: Two-tier watcher
+- Split into "commit-worthy" events (create, archive) and "notify-only" events (start, qa, merge)
+- Commit-worthy events go through git
+- Notify-only events just broadcast to WebSocket clients
+- More explicit but same end result as Option A
+
+### Option C: .gitignore intermediate directories
+- Add `2_current/`, `3_qa/`, `4_merge/` to `.gitignore`
+- Watcher still sees events (gitignore doesn't affect filesystem watching)
+- Git naturally ignores them
+- Risk: harder to debug, `git status` won't show pipeline state
+
+## Recommendation
+
+**Option A is viable and implemented.** The prototype is in `server/src/io/watcher.rs`:
+- Added `COMMIT_WORTHY_STAGES` constant: `["1_upcoming", "6_archived"]`
+- Added `should_commit_stage()` predicate
+- Modified `flush_pending()` to conditionally commit based on stage, while always broadcasting events
+- All 872 tests pass, clippy clean
+
+A full story run will now produce only 2 pipeline commits instead of 5+:
+- `story-kit: create 42_story_foo` (creation in `1_upcoming`)
+- `story-kit: accept 42_story_foo` (archival in `6_archived`)
+
+The intermediate moves (`start`, `queue for QA`, `queue for merge`, `done`) are still broadcast to WebSocket clients for real-time frontend updates, but no longer clutter git history.
+
+## Acceptance Criteria
+
+- [x] Spike document updated with findings and recommendation
+- [x] If Option A is viable: prototype the change and verify git log is clean during a full story run
+- [x] Confirm frontend still receives real-time pipeline updates for all stages
+- [x] Confirm no other system depends on intermediate pipeline commits being on master
+- [x] Identify any edge cases (server crash, manual git operations, multi-machine sync)

Cargo.lock

@@ -3997,7 +3997,7 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "story-kit"
-version = "0.1.0"
+version = "0.3.1"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -4025,8 +4025,8 @@ dependencies = [
  "strip-ansi-escapes",
  "tempfile",
  "tokio",
- "tokio-tungstenite 0.28.0",
+ "tokio-tungstenite 0.29.0",
- "toml 1.0.6+spec-1.1.0",
+ "toml 1.0.7+spec-1.1.0",
  "uuid",
  "wait-timeout",
  "walkdir",
@@ -4333,14 +4333,14 @@ dependencies = [
 
 [[package]]
 name = "tokio-tungstenite"
-version = "0.28.0"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d25a406cddcc431a75d3d9afc6a7c0f7428d4891dd973e4d54c56b46127bf857"
+checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
 dependencies = [
  "futures-util",
  "log",
  "tokio",
- "tungstenite 0.28.0",
+ "tungstenite 0.29.0",
 ]
 
 [[package]]
@@ -4367,22 +4367,22 @@ dependencies = [
  "serde_spanned",
  "toml_datetime 0.7.5+spec-1.1.0",
  "toml_parser",
- "winnow",
+ "winnow 0.7.14",
 ]
 
 [[package]]
 name = "toml"
-version = "1.0.6+spec-1.1.0"
+version = "1.0.7+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "399b1124a3c9e16766831c6bba21e50192572cdd98706ea114f9502509686ffc"
+checksum = "dd28d57d8a6f6e458bc0b8784f8fdcc4b99a437936056fa122cb234f18656a96"
 dependencies = [
  "indexmap",
  "serde_core",
  "serde_spanned",
- "toml_datetime 1.0.0+spec-1.1.0",
+ "toml_datetime 1.0.1+spec-1.1.0",
  "toml_parser",
  "toml_writer",
- "winnow",
+ "winnow 1.0.0",
 ]
 
 [[package]]
@@ -4396,9 +4396,9 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "1.0.0+spec-1.1.0"
+version = "1.0.1+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "32c2555c699578a4f59f0cc68e5116c8d7cabbd45e1409b989d4be085b53f13e"
+checksum = "9b320e741db58cac564e26c607d3cc1fdc4a88fd36c879568c07856ed83ff3e9"
 dependencies = [
  "serde_core",
 ]
@@ -4412,23 +4412,23 @@ dependencies = [
  "indexmap",
  "toml_datetime 0.7.5+spec-1.1.0",
  "toml_parser",
- "winnow",
+ "winnow 0.7.14",
 ]
 
 [[package]]
 name = "toml_parser"
-version = "1.0.9+spec-1.1.0"
+version = "1.0.10+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "702d4415e08923e7e1ef96cd5727c0dfed80b4d2fa25db9647fe5eb6f7c5a4c4"
+checksum = "7df25b4befd31c4816df190124375d5a20c6b6921e2cad937316de3fccd63420"
 dependencies = [
- "winnow",
+ "winnow 1.0.0",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.0.6+spec-1.1.0"
+version = "1.0.7+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607"
+checksum = "f17aaa1c6e3dc22b1da4b6bba97d066e354c7945cac2f7852d4e4e7ca7a6b56d"
 
 [[package]]
 name = "tower"
@@ -4562,9 +4562,9 @@ dependencies = [
 
 [[package]]
 name = "tungstenite"
-version = "0.28.0"
+version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8628dcc84e5a09eb3d8423d6cb682965dea9133204e8fb3efee74c2a0c259442"
+checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
 dependencies = [
  "bytes 1.11.1",
  "data-encoding",
@@ -4574,7 +4574,6 @@ dependencies = [
  "rand 0.9.2",
  "sha1",
  "thiserror 2.0.18",
- "utf-8",
 ]
 
 [[package]]
@@ -5445,6 +5444,12 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "winnow"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a90e88e4667264a994d34e6d1ab2d26d398dcdca8b7f52bec8668957517fc7d8"
+
 [[package]]
 name = "winreg"
 version = "0.10.1"

Cargo.toml

@@ -24,9 +24,9 @@ serde_yaml = "0.9"
 strip-ansi-escapes = "0.2"
 tempfile = "3"
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync"] }
-toml = "1.0.6"
+toml = "1.0.7"
 uuid = { version = "1.22.0", features = ["v4", "serde"] }
-tokio-tungstenite = "0.28.0"
+tokio-tungstenite = "0.29.0"
 walkdir = "2.5.0"
 filetime = "0.2"
 matrix-sdk = { version = "0.16.0", default-features = false, features = [

frontend/index.html

@@ -4,7 +4,7 @@
         <meta charset="UTF-8" />
         <link rel="icon" type="image/svg+xml" href="/vite.svg" />
         <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>Story Kit</title>
+        <title>Storkit</title>
     </head>
 
     <body>

frontend/src/App.tsx

@@ -7,6 +7,7 @@ import "./App.css";
 
 function App() {
 	const [projectPath, setProjectPath] = React.useState<string | null>(null);
+	const [_view, setView] = React.useState<"chat" | "token-usage">("chat");
 	const [isCheckingProject, setIsCheckingProject] = React.useState(true);
 	const [errorMsg, setErrorMsg] = React.useState<string | null>(null);
 	const [pathInput, setPathInput] = React.useState("");
@@ -120,6 +121,7 @@ function App() {
 		try {
 			await api.closeProject();
 			setProjectPath(null);
+			setView("chat");
 		} catch (e) {
 			console.error(e);
 		}

frontend/src/api/agents.ts

@@ -128,8 +128,7 @@ export function subscribeAgentStream(
 	onEvent: (event: AgentEvent) => void,
 	onError?: (error: Event) => void,
 ): () => void {
-	const host = import.meta.env.DEV ? "http://127.0.0.1:3001" : "";
+	const url = `/agents/${encodeURIComponent(storyId)}/${encodeURIComponent(agentName)}/stream`;
-	const url = `${host}/agents/${encodeURIComponent(storyId)}/${encodeURIComponent(agentName)}/stream`;
 
 	const eventSource = new EventSource(url);
 

frontend/src/api/client.test.ts

@@ -262,7 +262,7 @@ describe("ChatWebSocket", () => {
 
 		// Server pushes pipeline_state on fresh connection
 		const freshState = {
-			upcoming: [{ story_id: "1_story_test", name: "Test", error: null }],
+			backlog: [{ story_id: "1_story_test", name: "Test", error: null }],
 			current: [],
 			qa: [],
 			merge: [],

frontend/src/api/client.ts

@@ -33,10 +33,12 @@ export interface PipelineStageItem {
 	error: string | null;
 	merge_failure: string | null;
 	agent: AgentAssignment | null;
+	review_hold: boolean | null;
+	qa: string | null;
 }
 
 export interface PipelineState {
-	upcoming: PipelineStageItem[];
+	backlog: PipelineStageItem[];
 	current: PipelineStageItem[];
 	qa: PipelineStageItem[];
 	merge: PipelineStageItem[];
@@ -50,7 +52,7 @@ export type WsResponse =
 	| { type: "error"; message: string }
 	| {
 			type: "pipeline_state";
-			upcoming: PipelineStageItem[];
+			backlog: PipelineStageItem[];
 			current: PipelineStageItem[];
 			qa: PipelineStageItem[];
 			merge: PipelineStageItem[];
@@ -83,7 +85,9 @@ export type WsResponse =
 	/** Streaming token from a /btw side question response. */
 	| { type: "side_question_token"; content: string }
 	/** Final signal that the /btw side question has been fully answered. */
-	| { type: "side_question_done"; response: string };
+	| { type: "side_question_done"; response: string }
+	/** A single server log entry (bulk on connect, then live). */
+	| { type: "log_entry"; timestamp: string; level: string; message: string };
 
 export interface ProviderConfig {
 	provider: string;
@@ -115,6 +119,7 @@ export interface WorkItemContent {
 	content: string;
 	stage: string;
 	name: string | null;
+	agent: string | null;
 }
 
 export interface TestCaseResult {
@@ -138,6 +143,37 @@ export interface SearchResult {
 	matches: number;
 }
 
+export interface AgentCostEntry {
+	agent_name: string;
+	model: string | null;
+	input_tokens: number;
+	output_tokens: number;
+	cache_creation_input_tokens: number;
+	cache_read_input_tokens: number;
+	total_cost_usd: number;
+}
+
+export interface TokenCostResponse {
+	total_cost_usd: number;
+	agents: AgentCostEntry[];
+}
+
+export interface TokenUsageRecord {
+	story_id: string;
+	agent_name: string;
+	model: string | null;
+	timestamp: string;
+	input_tokens: number;
+	output_tokens: number;
+	cache_creation_input_tokens: number;
+	cache_read_input_tokens: number;
+	total_cost_usd: number;
+}
+
+export interface AllTokenUsageResponse {
+	records: TokenUsageRecord[];
+}
+
 export interface CommandOutput {
 	stdout: string;
 	stderr: string;
@@ -277,6 +313,9 @@ export const api = {
 	getHomeDirectory(baseUrl?: string) {
 		return requestJson<string>("/io/fs/home", {}, baseUrl);
 	},
+	listProjectFiles(baseUrl?: string) {
+		return requestJson<string[]>("/io/fs/files", {}, baseUrl);
+	},
 	searchFiles(query: string, baseUrl?: string) {
 		return requestJson<SearchResult[]>(
 			"/fs/search",
@@ -308,8 +347,52 @@ export const api = {
 			baseUrl,
 		);
 	},
+	getTokenCost(storyId: string, baseUrl?: string) {
+		return requestJson<TokenCostResponse>(
+			`/work-items/${encodeURIComponent(storyId)}/token-cost`,
+			{},
+			baseUrl,
+		);
+	},
+	getAllTokenUsage(baseUrl?: string) {
+		return requestJson<AllTokenUsageResponse>("/token-usage", {}, baseUrl);
+	},
+	/** Approve a story in QA, moving it to merge. */
+	approveQa(storyId: string) {
+		return callMcpTool("approve_qa", { story_id: storyId });
+	},
+	/** Reject a story in QA, moving it back to current with notes. */
+	rejectQa(storyId: string, notes: string) {
+		return callMcpTool("reject_qa", { story_id: storyId, notes });
+	},
+	/** Launch the QA app for a story's worktree. */
+	launchQaApp(storyId: string) {
+		return callMcpTool("launch_qa_app", { story_id: storyId });
+	},
 };
 
+async function callMcpTool(
+	toolName: string,
+	args: Record<string, unknown>,
+): Promise<string> {
+	const res = await fetch("/mcp", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			jsonrpc: "2.0",
+			id: 1,
+			method: "tools/call",
+			params: { name: toolName, arguments: args },
+		}),
+	});
+	const json = await res.json();
+	if (json.error) {
+		throw new Error(json.error.message);
+	}
+	const text = json.result?.content?.[0]?.text ?? "";
+	return text;
+}
+
 export class ChatWebSocket {
 	private static sharedSocket: WebSocket | null = null;
 	private static refCount = 0;
@@ -336,6 +419,11 @@ export class ChatWebSocket {
 	private onOnboardingStatus?: (needsOnboarding: boolean) => void;
 	private onSideQuestionToken?: (content: string) => void;
 	private onSideQuestionDone?: (response: string) => void;
+	private onLogEntry?: (
+		timestamp: string,
+		level: string,
+		message: string,
+	) => void;
 	private connected = false;
 	private closeTimer?: number;
 	private wsPath = DEFAULT_WS_PATH;
@@ -394,7 +482,7 @@ export class ChatWebSocket {
 				if (data.type === "error") this.onError?.(data.message);
 				if (data.type === "pipeline_state")
 					this.onPipelineState?.({
-						upcoming: data.upcoming,
+						backlog: data.backlog,
 						current: data.current,
 						qa: data.qa,
 						merge: data.merge,
@@ -421,6 +509,8 @@ export class ChatWebSocket {
 					this.onSideQuestionToken?.(data.content);
 				if (data.type === "side_question_done")
 					this.onSideQuestionDone?.(data.response);
+				if (data.type === "log_entry")
+					this.onLogEntry?.(data.timestamp, data.level, data.message);
 				if (data.type === "pong") {
 					window.clearTimeout(this.heartbeatTimeout);
 					this.heartbeatTimeout = undefined;
@@ -476,6 +566,7 @@ export class ChatWebSocket {
 			onOnboardingStatus?: (needsOnboarding: boolean) => void;
 			onSideQuestionToken?: (content: string) => void;
 			onSideQuestionDone?: (response: string) => void;
+			onLogEntry?: (timestamp: string, level: string, message: string) => void;
 		},
 		wsPath = DEFAULT_WS_PATH,
 	) {
@@ -493,6 +584,7 @@ export class ChatWebSocket {
 		this.onOnboardingStatus = handlers.onOnboardingStatus;
 		this.onSideQuestionToken = handlers.onSideQuestionToken;
 		this.onSideQuestionDone = handlers.onSideQuestionDone;
+		this.onLogEntry = handlers.onLogEntry;
 		this.wsPath = wsPath;
 		this.shouldReconnect = true;
 

frontend/src/components/AgentPanel.test.tsx

@@ -213,7 +213,7 @@ describe("RosterBadge availability state", () => {
 	});
 });
 
-describe("Thinking traces hidden from agent stream UI", () => {
+describe("Agent output not shown in sidebar (story 290)", () => {
 	beforeAll(() => {
 		Element.prototype.scrollIntoView = vi.fn();
 	});
@@ -224,7 +224,51 @@ describe("Thinking traces hidden from agent stream UI", () => {
 		mockedSubscribeAgentStream.mockReturnValue(() => {});
 	});
 
-	// AC1: thinking block is never rendered even when thinking events arrive
+	// AC1: output events do not appear in the agents sidebar
+	it("does not render agent output when output event arrives", async () => {
+		let emitEvent: ((e: AgentEvent) => void) | null = null;
+		mockedSubscribeAgentStream.mockImplementation(
+			(_storyId, _agentName, onEvent) => {
+				emitEvent = onEvent;
+				return () => {};
+			},
+		);
+
+		const agentList: AgentInfo[] = [
+			{
+				story_id: "290_output",
+				agent_name: "coder-1",
+				status: "running",
+				session_id: null,
+				worktree_path: "/tmp/wt",
+				base_branch: "master",
+				log_session_id: null,
+			},
+		];
+		mockedAgents.listAgents.mockResolvedValue(agentList);
+
+		const { container } = render(<AgentPanel />);
+		await screen.findByTestId("roster-badge-coder-1");
+
+		await act(async () => {
+			emitEvent?.({
+				type: "output",
+				story_id: "290_output",
+				agent_name: "coder-1",
+				text: "doing some work...",
+			});
+		});
+
+		// No output elements in the sidebar
+		expect(
+			container.querySelector('[data-testid^="agent-output-"]'),
+		).not.toBeInTheDocument();
+		expect(
+			container.querySelector('[data-testid^="agent-stream-"]'),
+		).not.toBeInTheDocument();
+	});
+
+	// AC1: thinking events do not appear in the agents sidebar
 	it("does not render thinking block when thinking event arrives", async () => {
 		let emitEvent: ((e: AgentEvent) => void) | null = null;
 		mockedSubscribeAgentStream.mockImplementation(
@@ -236,7 +280,7 @@ describe("Thinking traces hidden from agent stream UI", () => {
 
 		const agentList: AgentInfo[] = [
 			{
-				story_id: "218_thinking",
+				story_id: "290_thinking",
 				agent_name: "coder-1",
 				status: "running",
 				session_id: null,
@@ -253,109 +297,16 @@ describe("Thinking traces hidden from agent stream UI", () => {
 		await act(async () => {
 			emitEvent?.({
 				type: "thinking",
-				story_id: "218_thinking",
+				story_id: "290_thinking",
 				agent_name: "coder-1",
 				text: "Let me consider the problem carefully...",
 			});
 		});
 
-		// AC1: thinking block must not be present
+		// No thinking block or output in sidebar
 		expect(screen.queryByTestId("thinking-block")).not.toBeInTheDocument();
-	});
+		expect(
-
+			screen.queryByText("Let me consider the problem carefully..."),
-	// AC2: after thinking events, only regular output is rendered
+		).not.toBeInTheDocument();
-	it("renders regular output but not thinking block when both arrive", async () => {
-		let emitEvent: ((e: AgentEvent) => void) | null = null;
-		mockedSubscribeAgentStream.mockImplementation(
-			(_storyId, _agentName, onEvent) => {
-				emitEvent = onEvent;
-				return () => {};
-			},
-		);
-
-		const agentList: AgentInfo[] = [
-			{
-				story_id: "218_output",
-				agent_name: "coder-1",
-				status: "running",
-				session_id: null,
-				worktree_path: "/tmp/wt",
-				base_branch: "master",
-				log_session_id: null,
-			},
-		];
-		mockedAgents.listAgents.mockResolvedValue(agentList);
-
-		render(<AgentPanel />);
-		await screen.findByTestId("roster-badge-coder-1");
-
-		// Thinking event — must be ignored visually
-		await act(async () => {
-			emitEvent?.({
-				type: "thinking",
-				story_id: "218_output",
-				agent_name: "coder-1",
-				text: "thinking deeply",
-			});
-		});
-
-		// AC3: output event still renders correctly (no regression)
-		await act(async () => {
-			emitEvent?.({
-				type: "output",
-				story_id: "218_output",
-				agent_name: "coder-1",
-				text: "Here is the result.",
-			});
-		});
-
-		// AC1: no thinking block
-		expect(screen.queryByTestId("thinking-block")).not.toBeInTheDocument();
-
-		// AC2+AC3: output area renders the text but NOT thinking text
-		const outputArea = screen.getByTestId("agent-output-coder-1");
-		expect(outputArea).toBeInTheDocument();
-		expect(outputArea.textContent).toContain("Here is the result.");
-		expect(outputArea.textContent).not.toContain("thinking deeply");
-	});
-
-	// AC3: output-only event stream (no thinking) still works
-	it("renders output event text without a thinking block", async () => {
-		let emitEvent: ((e: AgentEvent) => void) | null = null;
-		mockedSubscribeAgentStream.mockImplementation(
-			(_storyId, _agentName, onEvent) => {
-				emitEvent = onEvent;
-				return () => {};
-			},
-		);
-
-		const agentList: AgentInfo[] = [
-			{
-				story_id: "218_noThink",
-				agent_name: "coder-1",
-				status: "running",
-				session_id: null,
-				worktree_path: "/tmp/wt",
-				base_branch: "master",
-				log_session_id: null,
-			},
-		];
-		mockedAgents.listAgents.mockResolvedValue(agentList);
-
-		render(<AgentPanel />);
-		await screen.findByTestId("roster-badge-coder-1");
-
-		await act(async () => {
-			emitEvent?.({
-				type: "output",
-				story_id: "218_noThink",
-				agent_name: "coder-1",
-				text: "plain output line",
-			});
-		});
-
-		expect(screen.queryByTestId("thinking-block")).not.toBeInTheDocument();
-		const outputArea = screen.getByTestId("agent-output-coder-1");
-		expect(outputArea.textContent).toContain("plain output line");
 	});
 });

frontend/src/components/AgentPanel.tsx

@@ -13,7 +13,6 @@ const { useCallback, useEffect, useRef, useState } = React;
 interface AgentState {
 	agentName: string;
 	status: AgentStatusValue;
-	log: string[];
 	sessionId: string | null;
 	worktreePath: string | null;
 	baseBranch: string | null;
@@ -120,7 +119,6 @@ export function AgentPanel({
 					const current = prev[key] ?? {
 						agentName,
 						status: "pending" as AgentStatusValue,
-						log: [],
 						sessionId: null,
 						worktreePath: null,
 						baseBranch: null,
@@ -144,14 +142,6 @@ export function AgentPanel({
 								},
 							};
 						}
-						case "output":
-							return {
-								...prev,
-								[key]: {
-									...current,
-									log: [...current.log, event.text ?? ""],
-								},
-							};
 						case "done":
 							return {
 								...prev,
@@ -168,17 +158,12 @@ export function AgentPanel({
 								[key]: {
 									...current,
 									status: "failed",
-									log: [
-										...current.log,
-										`[ERROR] ${event.message ?? "Unknown error"}`,
-									],
 									terminalAt: current.terminalAt ?? Date.now(),
 								},
 							};
-						case "thinking":
-							// Thinking traces are internal model state — never display them.
-							return prev;
 						default:
+							// output, thinking, and other events are not displayed in the sidebar.
+							// Agent output streams appear in the work item detail panel instead.
 							return prev;
 					}
 				});
@@ -204,7 +189,6 @@ export function AgentPanel({
 					agentMap[key] = {
 						agentName: a.agent_name,
 						status: a.status,
-						log: [],
 						sessionId: a.session_id,
 						worktreePath: a.worktree_path,
 						baseBranch: a.base_branch,
@@ -261,9 +245,6 @@ export function AgentPanel({
 		}
 	};
 
-	// Agents that have streaming content to show
-	const activeAgents = Object.values(agents).filter((a) => a.log.length > 0);
-
 	return (
 		<div
 			style={{
@@ -420,35 +401,6 @@ export function AgentPanel({
 				</div>
 			)}
 
-			{/* Per-agent streaming output */}
-			{activeAgents.map((agent) => (
-				<div
-					key={`stream-${agent.agentName}`}
-					data-testid={`agent-stream-${agent.agentName}`}
-					style={{
-						display: "flex",
-						flexDirection: "column",
-						gap: "4px",
-					}}
-				>
-					{agent.log.length > 0 && (
-						<div
-							data-testid={`agent-output-${agent.agentName}`}
-							style={{
-								fontSize: "0.8em",
-								fontFamily: "monospace",
-								color: "#ccc",
-								whiteSpace: "pre-wrap",
-								wordBreak: "break-word",
-								lineHeight: "1.5",
-							}}
-						>
-							{agent.log.join("")}
-						</div>
-					)}
-				</div>
-			))}
-
 			{actionError && (
 				<div
 					style={{

frontend/src/components/Chat.test.tsx

@@ -38,6 +38,8 @@ vi.mock("../api/client", () => {
 		setModelPreference: vi.fn(),
 		cancelChat: vi.fn(),
 		setAnthropicApiKey: vi.fn(),
+		readFile: vi.fn(),
+		listProjectFiles: vi.fn(),
 	};
 	class ChatWebSocket {
 		connect(handlers: WsHandlers) {
@@ -60,6 +62,8 @@ const mockedApi = {
 	setModelPreference: vi.mocked(api.setModelPreference),
 	cancelChat: vi.mocked(api.cancelChat),
 	setAnthropicApiKey: vi.mocked(api.setAnthropicApiKey),
+	readFile: vi.mocked(api.readFile),
+	listProjectFiles: vi.mocked(api.listProjectFiles),
 };
 
 function setupMocks() {
@@ -68,6 +72,8 @@ function setupMocks() {
 	mockedApi.getAnthropicModels.mockResolvedValue([]);
 	mockedApi.getModelPreference.mockResolvedValue(null);
 	mockedApi.setModelPreference.mockResolvedValue(true);
+	mockedApi.readFile.mockResolvedValue("");
+	mockedApi.listProjectFiles.mockResolvedValue([]);
 	mockedApi.cancelChat.mockResolvedValue(true);
 	mockedApi.setAnthropicApiKey.mockResolvedValue(true);
 }
@@ -625,16 +631,20 @@ describe("Chat localStorage persistence (Story 145)", () => {
 
 		// Verify sendChat was called with ALL prior messages + the new one
 		expect(lastSendChatArgs).not.toBeNull();
-		expect(lastSendChatArgs?.messages).toHaveLength(3);
+		const args = lastSendChatArgs as unknown as {
-		expect(lastSendChatArgs?.messages[0]).toEqual({
+			messages: Message[];
+			config: unknown;
+		};
+		expect(args.messages).toHaveLength(3);
+		expect(args.messages[0]).toEqual({
 			role: "user",
 			content: "What is Rust?",
 		});
-		expect(lastSendChatArgs?.messages[1]).toEqual({
+		expect(args.messages[1]).toEqual({
 			role: "assistant",
 			content: "Rust is a systems programming language.",
 		});
-		expect(lastSendChatArgs?.messages[2]).toEqual({
+		expect(args.messages[2]).toEqual({
 			role: "user",
 			content: "Tell me more",
 		});
@@ -1343,7 +1353,14 @@ describe("Bug 264: Claude Code session ID persisted across browser refresh", ()
 
 		expect(lastSendChatArgs).not.toBeNull();
 		expect(
-			(lastSendChatArgs?.config as Record<string, unknown>).session_id,
+			(
+				(
+					lastSendChatArgs as unknown as {
+						messages: Message[];
+						config: unknown;
+					}
+				)?.config as Record<string, unknown>
+			).session_id,
 		).toBe("persisted-session-xyz");
 	});
 
@@ -1386,3 +1403,57 @@ describe("Bug 264: Claude Code session ID persisted across browser refresh", ()
 		expect(localStorage.getItem(otherKey)).toBe("other-session");
 	});
 });
+
+describe("File reference expansion (Story 269 AC4)", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		capturedWsHandlers = null;
+		lastSendChatArgs = null;
+		setupMocks();
+	});
+
+	it("includes file contents as context when message contains @file reference", async () => {
+		mockedApi.readFile.mockResolvedValue('fn main() { println!("hello"); }');
+
+		render(<Chat projectPath="/tmp/project" onCloseProject={vi.fn()} />);
+		await waitFor(() => expect(capturedWsHandlers).not.toBeNull());
+
+		const input = screen.getByPlaceholderText("Send a message...");
+		await act(async () => {
+			fireEvent.change(input, { target: { value: "explain @src/main.rs" } });
+		});
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
+
+		await waitFor(() => expect(lastSendChatArgs).not.toBeNull());
+		const sentMessages = (
+			lastSendChatArgs as NonNullable<typeof lastSendChatArgs>
+		).messages;
+		const userMsg = sentMessages[sentMessages.length - 1];
+		expect(userMsg.content).toContain("explain @src/main.rs");
+		expect(userMsg.content).toContain("[File: src/main.rs]");
+		expect(userMsg.content).toContain("fn main()");
+	});
+
+	it("sends message without modification when no @file references are present", async () => {
+		render(<Chat projectPath="/tmp/project" onCloseProject={vi.fn()} />);
+		await waitFor(() => expect(capturedWsHandlers).not.toBeNull());
+
+		const input = screen.getByPlaceholderText("Send a message...");
+		await act(async () => {
+			fireEvent.change(input, { target: { value: "hello world" } });
+		});
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
+
+		await waitFor(() => expect(lastSendChatArgs).not.toBeNull());
+		const sentMessages = (
+			lastSendChatArgs as NonNullable<typeof lastSendChatArgs>
+		).messages;
+		const userMsg = sentMessages[sentMessages.length - 1];
+		expect(userMsg.content).toBe("hello world");
+		expect(mockedApi.readFile).not.toHaveBeenCalled();
+	});
+});

frontend/src/components/Chat.tsx

@@ -13,6 +13,8 @@ import { ChatInput } from "./ChatInput";
 import { HelpOverlay } from "./HelpOverlay";
 import { LozengeFlyProvider } from "./LozengeFlyContext";
 import { MessageItem } from "./MessageItem";
+import type { LogEntry } from "./ServerLogsPanel";
+import { ServerLogsPanel } from "./ServerLogsPanel";
 import { SideQuestionOverlay } from "./SideQuestionOverlay";
 import { StagePanel } from "./StagePanel";
 import { WorkItemDetailPanel } from "./WorkItemDetailPanel";
@@ -165,7 +167,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 	const [apiKeyInput, setApiKeyInput] = useState("");
 	const [hasAnthropicKey, setHasAnthropicKey] = useState(false);
 	const [pipeline, setPipeline] = useState<PipelineState>({
-		upcoming: [],
+		backlog: [],
 		current: [],
 		qa: [],
 		merge: [],
@@ -200,6 +202,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 	const [agentConfigVersion, setAgentConfigVersion] = useState(0);
 	const [agentStateVersion, setAgentStateVersion] = useState(0);
 	const [pipelineVersion, setPipelineVersion] = useState(0);
+	const [storyTokenCosts, setStoryTokenCosts] = useState<Map<string, number>>(
+		new Map(),
+	);
 	const [needsOnboarding, setNeedsOnboarding] = useState(false);
 	const onboardingTriggeredRef = useRef(false);
 	const [selectedWorkItemId, setSelectedWorkItemId] = useState<string | null>(
@@ -214,6 +219,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 		loading: boolean;
 	} | null>(null);
 	const [showHelp, setShowHelp] = useState(false);
+	const [serverLogs, setServerLogs] = useState<LogEntry[]>([]);
 	// Ref so stale WebSocket callbacks can read the current queued messages
 	const queuedMessagesRef = useRef<{ id: string; text: string }[]>([]);
 	const queueIdCounterRef = useRef(0);
@@ -360,6 +366,29 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 			onPipelineState: (state) => {
 				setPipeline(state);
 				setPipelineVersion((v) => v + 1);
+				const allItems = [
+					...state.backlog,
+					...state.current,
+					...state.qa,
+					...state.merge,
+					...state.done,
+				];
+				for (const item of allItems) {
+					api
+						.getTokenCost(item.story_id)
+						.then((cost) => {
+							if (cost.total_cost_usd > 0) {
+								setStoryTokenCosts((prev) => {
+									const next = new Map(prev);
+									next.set(item.story_id, cost.total_cost_usd);
+									return next;
+								});
+							}
+						})
+						.catch(() => {
+							// Silently ignore — cost data may not exist yet.
+						});
+				}
 			},
 			onPermissionRequest: (requestId, toolName, toolInput) => {
 				setPermissionQueue((prev) => [
@@ -402,6 +431,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 					prev ? { ...prev, response, loading: false } : prev,
 				);
 			},
+			onLogEntry: (timestamp, level, message) => {
+				setServerLogs((prev) => [...prev, { timestamp, level, message }]);
+			},
 		});
 
 		return () => {
@@ -554,7 +586,26 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 			}
 		}
 
-		const userMsg: Message = { role: "user", content: messageText };
+		// Expand @file references: append file contents as context
+		const fileRefs = [...messageText.matchAll(/(^|[\s\n])@([^\s@]+)/g)].map(
+			(m) => m[2],
+		);
+		let expandedText = messageText;
+		if (fileRefs.length > 0) {
+			const expansions = await Promise.allSettled(
+				fileRefs.map(async (ref) => {
+					const contents = await api.readFile(ref);
+					return { ref, contents };
+				}),
+			);
+			for (const result of expansions) {
+				if (result.status === "fulfilled") {
+					expandedText += `\n\n[File: ${result.value.ref}]\n\`\`\`\n${result.value.contents}\n\`\`\``;
+				}
+			}
+		}
+
+		const userMsg: Message = { role: "user", content: expandedText };
 		const newHistory = [...messages, userMsg];
 
 		setMessages(newHistory);
@@ -794,7 +845,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 											fontSize: "1.1rem",
 										}}
 									>
-										Welcome to Story Kit
+										Welcome to Storkit
 									</h3>
 									<p
 										style={{
@@ -980,28 +1031,34 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 								<StagePanel
 									title="Done"
 									items={pipeline.done ?? []}
+									costs={storyTokenCosts}
 									onItemClick={(item) => setSelectedWorkItemId(item.story_id)}
 								/>
 								<StagePanel
 									title="To Merge"
 									items={pipeline.merge}
+									costs={storyTokenCosts}
 									onItemClick={(item) => setSelectedWorkItemId(item.story_id)}
 								/>
 								<StagePanel
 									title="QA"
 									items={pipeline.qa}
+									costs={storyTokenCosts}
 									onItemClick={(item) => setSelectedWorkItemId(item.story_id)}
 								/>
 								<StagePanel
 									title="Current"
 									items={pipeline.current}
+									costs={storyTokenCosts}
 									onItemClick={(item) => setSelectedWorkItemId(item.story_id)}
 								/>
 								<StagePanel
-									title="Upcoming"
+									title="Backlog"
-									items={pipeline.upcoming}
+									items={pipeline.backlog}
+									costs={storyTokenCosts}
 									onItemClick={(item) => setSelectedWorkItemId(item.story_id)}
 								/>
+								<ServerLogsPanel logs={serverLogs} />
 							</>
 						)}
 					</LozengeFlyProvider>

frontend/src/components/ChatHeader.test.tsx

@@ -136,9 +136,9 @@ describe("ChatHeader", () => {
 		expect(screen.getByText("Built: 2026-01-01 00:00")).toBeInTheDocument();
 	});
 
-	it("displays Story Kit branding in the header", () => {
+	it("displays Storkit branding in the header", () => {
 		render(<ChatHeader {...makeProps()} />);
-		expect(screen.getByText("Story Kit")).toBeInTheDocument();
+		expect(screen.getByText("Storkit")).toBeInTheDocument();
 	});
 
 	it("labels the claude-pty optgroup as 'Claude Code'", () => {

frontend/src/components/ChatHeader.tsx

@@ -82,7 +82,7 @@ export function ChatHeader({
 						letterSpacing: "0.02em",
 					}}
 				>
-					Story Kit
+					Storkit
 				</span>
 				<div
 					title={projectPath}

frontend/src/components/ChatInput.tsx

@@ -1,6 +1,14 @@
 import * as React from "react";
+import { api } from "../api/client";
 
-const { forwardRef, useEffect, useImperativeHandle, useRef, useState } = React;
+const {
+	forwardRef,
+	useCallback,
+	useEffect,
+	useImperativeHandle,
+	useRef,
+	useState,
+} = React;
 
 export interface ChatInputHandle {
 	appendToInput(text: string): void;
@@ -14,6 +22,97 @@ interface ChatInputProps {
 	onRemoveQueuedMessage: (id: string) => void;
 }
 
+/** Fuzzy-match: returns true if all chars of `query` appear in order in `str`. */
+function fuzzyMatch(str: string, query: string): boolean {
+	if (!query) return true;
+	const lower = str.toLowerCase();
+	const q = query.toLowerCase();
+	let qi = 0;
+	for (let i = 0; i < lower.length && qi < q.length; i++) {
+		if (lower[i] === q[qi]) qi++;
+	}
+	return qi === q.length;
+}
+
+/** Score a fuzzy match: lower is better. Exact prefix match wins, then shorter paths. */
+function fuzzyScore(str: string, query: string): number {
+	const lower = str.toLowerCase();
+	const q = query.toLowerCase();
+	// Prefer matches where query appears as a contiguous substring
+	if (lower.includes(q)) return lower.indexOf(q);
+	return str.length;
+}
+
+interface FilePickerOverlayProps {
+	query: string;
+	files: string[];
+	selectedIndex: number;
+	onSelect: (file: string) => void;
+	onDismiss: () => void;
+	anchorRef: React.RefObject<HTMLTextAreaElement | null>;
+}
+
+function FilePickerOverlay({
+	query,
+	files,
+	selectedIndex,
+	onSelect,
+}: FilePickerOverlayProps) {
+	const filtered = files
+		.filter((f) => fuzzyMatch(f, query))
+		.sort((a, b) => fuzzyScore(a, query) - fuzzyScore(b, query))
+		.slice(0, 10);
+
+	if (filtered.length === 0) return null;
+
+	return (
+		<div
+			data-testid="file-picker-overlay"
+			style={{
+				position: "absolute",
+				bottom: "100%",
+				left: 0,
+				right: 0,
+				background: "#1e1e1e",
+				border: "1px solid #444",
+				borderRadius: "8px",
+				marginBottom: "6px",
+				overflow: "hidden",
+				zIndex: 100,
+				boxShadow: "0 4px 16px rgba(0,0,0,0.4)",
+				maxHeight: "240px",
+				overflowY: "auto",
+			}}
+		>
+			{filtered.map((file, idx) => (
+				<button
+					key={file}
+					type="button"
+					data-testid={`file-picker-item-${idx}`}
+					onClick={() => onSelect(file)}
+					style={{
+						display: "block",
+						width: "100%",
+						textAlign: "left",
+						padding: "8px 14px",
+						background: idx === selectedIndex ? "#2d4a6e" : "transparent",
+						border: "none",
+						color: idx === selectedIndex ? "#ececec" : "#aaa",
+						cursor: "pointer",
+						fontFamily: "monospace",
+						fontSize: "0.85rem",
+						whiteSpace: "nowrap",
+						overflow: "hidden",
+						textOverflow: "ellipsis",
+					}}
+				>
+					{file}
+				</button>
+			))}
+		</div>
+	);
+}
+
 export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 	function ChatInput(
 		{ loading, queuedMessages, onSubmit, onCancel, onRemoveQueuedMessage },
@@ -22,6 +121,12 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 		const [input, setInput] = useState("");
 		const inputRef = useRef<HTMLTextAreaElement>(null);
 
+		// File picker state
+		const [projectFiles, setProjectFiles] = useState<string[]>([]);
+		const [pickerQuery, setPickerQuery] = useState<string | null>(null);
+		const [pickerSelectedIndex, setPickerSelectedIndex] = useState(0);
+		const [pickerAtStart, setPickerAtStart] = useState(0);
+
 		useImperativeHandle(ref, () => ({
 			appendToInput(text: string) {
 				setInput((prev) => (prev ? `${prev}\n${text}` : text));
@@ -32,10 +137,118 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 			inputRef.current?.focus();
 		}, []);
 
+		// Compute filtered files for current picker query
+		const filteredFiles =
+			pickerQuery !== null
+				? projectFiles
+						.filter((f) => fuzzyMatch(f, pickerQuery))
+						.sort(
+							(a, b) => fuzzyScore(a, pickerQuery) - fuzzyScore(b, pickerQuery),
+						)
+						.slice(0, 10)
+				: [];
+
+		const dismissPicker = useCallback(() => {
+			setPickerQuery(null);
+			setPickerSelectedIndex(0);
+		}, []);
+
+		const selectFile = useCallback(
+			(file: string) => {
+				// Replace the @query portion with @file
+				const before = input.slice(0, pickerAtStart);
+				const cursorPos = inputRef.current?.selectionStart ?? input.length;
+				const after = input.slice(cursorPos);
+				setInput(`${before}@${file}${after}`);
+				dismissPicker();
+				// Restore focus after state update
+				setTimeout(() => inputRef.current?.focus(), 0);
+			},
+			[input, pickerAtStart, dismissPicker],
+		);
+
+		const handleInputChange = useCallback(
+			(e: React.ChangeEvent<HTMLTextAreaElement>) => {
+				const val = e.target.value;
+				setInput(val);
+
+				const cursor = e.target.selectionStart ?? val.length;
+				// Find the last @ before the cursor that starts a reference token
+				const textUpToCursor = val.slice(0, cursor);
+				// Match @ not preceded by non-whitespace (i.e. @ at start or after space/newline)
+				const atMatch = textUpToCursor.match(/(^|[\s\n])@([^\s@]*)$/);
+
+				if (atMatch) {
+					const query = atMatch[2];
+					const atPos = textUpToCursor.lastIndexOf("@");
+					setPickerAtStart(atPos);
+					setPickerQuery(query);
+					setPickerSelectedIndex(0);
+
+					// Lazily load files on first trigger
+					if (projectFiles.length === 0) {
+						api
+							.listProjectFiles()
+							.then(setProjectFiles)
+							.catch(() => {});
+					}
+				} else {
+					if (pickerQuery !== null) dismissPicker();
+				}
+			},
+			[projectFiles.length, pickerQuery, dismissPicker],
+		);
+
+		const handleKeyDown = useCallback(
+			(e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+				if (pickerQuery !== null && filteredFiles.length > 0) {
+					if (e.key === "ArrowDown") {
+						e.preventDefault();
+						setPickerSelectedIndex((i) =>
+							Math.min(i + 1, filteredFiles.length - 1),
+						);
+						return;
+					}
+					if (e.key === "ArrowUp") {
+						e.preventDefault();
+						setPickerSelectedIndex((i) => Math.max(i - 1, 0));
+						return;
+					}
+					if (e.key === "Enter" || e.key === "Tab") {
+						e.preventDefault();
+						selectFile(filteredFiles[pickerSelectedIndex] ?? filteredFiles[0]);
+						return;
+					}
+					if (e.key === "Escape") {
+						e.preventDefault();
+						dismissPicker();
+						return;
+					}
+				} else if (e.key === "Escape" && pickerQuery !== null) {
+					e.preventDefault();
+					dismissPicker();
+					return;
+				}
+
+				if (e.key === "Enter" && !e.shiftKey) {
+					e.preventDefault();
+					handleSubmit();
+				}
+			},
+			[
+				pickerQuery,
+				filteredFiles,
+				pickerSelectedIndex,
+				selectFile,
+				dismissPicker,
+			],
+		);
+
 		const handleSubmit = () => {
 			if (!input.trim()) return;
 			onSubmit(input);
 			setInput("");
+			dismissPicker();
 		};
 
 		return (
@@ -135,24 +348,30 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 							</button>
 						</div>
 					))}
-					{/* Input row */}
+					{/* Input row with file picker overlay */}
 					<div
 						style={{
 							display: "flex",
 							gap: "8px",
 							alignItems: "center",
+							position: "relative",
 						}}
 					>
+						{pickerQuery !== null && (
+							<FilePickerOverlay
+								query={pickerQuery}
+								files={projectFiles}
+								selectedIndex={pickerSelectedIndex}
+								onSelect={selectFile}
+								onDismiss={dismissPicker}
+								anchorRef={inputRef}
+							/>
+						)}
 						<textarea
 							ref={inputRef}
 							value={input}
-							onChange={(e) => setInput(e.target.value)}
+							onChange={handleInputChange}
-							onKeyDown={(e) => {
+							onKeyDown={handleKeyDown}
-								if (e.key === "Enter" && !e.shiftKey) {
-									e.preventDefault();
-									handleSubmit();
-								}
-							}}
 							placeholder="Send a message..."
 							rows={1}
 							style={{

frontend/src/components/ChatInputFilePicker.test.tsx

@@ -0,0 +1,194 @@
+import {
+	act,
+	fireEvent,
+	render,
+	screen,
+	waitFor,
+} from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { api } from "../api/client";
+import { ChatInput } from "./ChatInput";
+
+vi.mock("../api/client", () => ({
+	api: {
+		listProjectFiles: vi.fn(),
+	},
+}));
+
+const mockedListProjectFiles = vi.mocked(api.listProjectFiles);
+
+const defaultProps = {
+	loading: false,
+	queuedMessages: [],
+	onSubmit: vi.fn(),
+	onCancel: vi.fn(),
+	onRemoveQueuedMessage: vi.fn(),
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	mockedListProjectFiles.mockResolvedValue([
+		"src/main.rs",
+		"src/lib.rs",
+		"frontend/index.html",
+		"README.md",
+	]);
+});
+
+describe("File picker overlay (Story 269 AC1)", () => {
+	it("shows file picker overlay when @ is typed", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+	});
+
+	it("does not show file picker overlay for text without @", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "hello world" } });
+		});
+
+		expect(screen.queryByTestId("file-picker-overlay")).not.toBeInTheDocument();
+	});
+});
+
+describe("File picker fuzzy matching (Story 269 AC2)", () => {
+	it("filters files by query typed after @", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@main" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+
+		// main.rs should be visible, README.md should not
+		expect(screen.getByText("src/main.rs")).toBeInTheDocument();
+		expect(screen.queryByText("README.md")).not.toBeInTheDocument();
+	});
+
+	it("shows all files when @ is typed with no query", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+
+		// All 4 files should be visible
+		expect(screen.getByText("src/main.rs")).toBeInTheDocument();
+		expect(screen.getByText("src/lib.rs")).toBeInTheDocument();
+		expect(screen.getByText("README.md")).toBeInTheDocument();
+	});
+});
+
+describe("File picker selection (Story 269 AC3)", () => {
+	it("clicking a file inserts @path into the message", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-item-0")).toBeInTheDocument();
+		});
+
+		await act(async () => {
+			fireEvent.click(screen.getByTestId("file-picker-item-0"));
+		});
+
+		// Picker should be dismissed and the file reference inserted
+		expect(screen.queryByTestId("file-picker-overlay")).not.toBeInTheDocument();
+		expect((textarea as HTMLTextAreaElement).value).toMatch(/^@\S+/);
+	});
+
+	it("Enter key selects highlighted file and inserts it into message", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@main" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Enter" });
+		});
+
+		expect(screen.queryByTestId("file-picker-overlay")).not.toBeInTheDocument();
+		expect((textarea as HTMLTextAreaElement).value).toContain("@src/main.rs");
+	});
+});
+
+describe("File picker dismiss (Story 269 AC5)", () => {
+	it("Escape key dismisses the file picker", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Escape" });
+		});
+
+		expect(screen.queryByTestId("file-picker-overlay")).not.toBeInTheDocument();
+	});
+});
+
+describe("Multiple @ references (Story 269 AC6)", () => {
+	it("typing @ after a completed reference triggers picker again", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		// First reference
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "@main" } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+
+		// Select file
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Enter" });
+		});
+
+		// Type a second @
+		await act(async () => {
+			const current = (textarea as HTMLTextAreaElement).value;
+			fireEvent.change(textarea, { target: { value: `${current} @` } });
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("file-picker-overlay")).toBeInTheDocument();
+		});
+	});
+});

frontend/src/components/LozengeFlyContext.test.tsx

@@ -9,7 +9,7 @@ import { StagePanel } from "./StagePanel";
 
 function makePipeline(overrides: Partial<PipelineState> = {}): PipelineState {
 	return {
-		upcoming: [],
+		backlog: [],
 		current: [],
 		qa: [],
 		merge: [],
@@ -59,6 +59,8 @@ describe("AgentLozenge fixed intrinsic width", () => {
 				error: null,
 				merge_failure: null,
 				agent: { agent_name: "coder-1", model: "sonnet", status: "running" },
+				review_hold: null,
+				qa: null,
 			},
 		];
 		const pipeline = makePipeline({ current: items });
@@ -111,6 +113,8 @@ describe("LozengeFlyProvider fly-in visibility", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -151,6 +155,8 @@ describe("LozengeFlyProvider fly-in visibility", () => {
 						model: null,
 						status: "running",
 					},
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -213,6 +219,8 @@ describe("LozengeFlyProvider fly-in clone", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: "sonnet", status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -254,6 +262,8 @@ describe("LozengeFlyProvider fly-in clone", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -301,6 +311,8 @@ describe("LozengeFlyProvider fly-in clone", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -370,6 +382,8 @@ describe("LozengeFlyProvider fly-out", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: "haiku", status: "completed" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -395,6 +409,8 @@ describe("LozengeFlyProvider fly-out", () => {
 					error: null,
 					merge_failure: null,
 					agent: null,
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -427,6 +443,8 @@ describe("AgentLozenge idle vs active appearance", () => {
 				error: null,
 				merge_failure: null,
 				agent: { agent_name: "coder-1", model: null, status: "running" },
+				review_hold: null,
+				qa: null,
 			},
 		];
 		const { container } = render(
@@ -451,6 +469,8 @@ describe("AgentLozenge idle vs active appearance", () => {
 				error: null,
 				merge_failure: null,
 				agent: { agent_name: "coder-1", model: null, status: "pending" },
+				review_hold: null,
+				qa: null,
 			},
 		];
 		const { container } = render(
@@ -475,6 +495,8 @@ describe("AgentLozenge idle vs active appearance", () => {
 				error: null,
 				merge_failure: null,
 				agent: { agent_name: "coder-1", model: null, status: "running" },
+				review_hold: null,
+				qa: null,
 			},
 		];
 		const { container } = render(
@@ -526,6 +548,8 @@ describe("hiddenRosterAgents: assigned agents are absent from roster", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -547,6 +571,8 @@ describe("hiddenRosterAgents: assigned agents are absent from roster", () => {
 					error: null,
 					merge_failure: null,
 					agent: null,
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -569,6 +595,8 @@ describe("hiddenRosterAgents: assigned agents are absent from roster", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -629,6 +657,8 @@ describe("hiddenRosterAgents: fly-out keeps agent hidden until clone lands", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "completed" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -640,6 +670,8 @@ describe("hiddenRosterAgents: fly-out keeps agent hidden until clone lands", ()
 					error: null,
 					merge_failure: null,
 					agent: null,
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -682,6 +714,8 @@ describe("hiddenRosterAgents: fly-out keeps agent hidden until clone lands", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "completed" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -693,6 +727,8 @@ describe("hiddenRosterAgents: fly-out keeps agent hidden until clone lands", ()
 					error: null,
 					merge_failure: null,
 					agent: null,
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -766,6 +802,8 @@ describe("LozengeFlyProvider agent swap (name change)", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: "sonnet", status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -777,6 +815,8 @@ describe("LozengeFlyProvider agent swap (name change)", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-2", model: "haiku", status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -861,6 +901,8 @@ describe("LozengeFlyProvider fly-out without roster element", () => {
 						model: null,
 						status: "completed",
 					},
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -872,6 +914,8 @@ describe("LozengeFlyProvider fly-out without roster element", () => {
 					error: null,
 					merge_failure: null,
 					agent: null,
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -943,6 +987,8 @@ describe("FlyingLozengeClone initial non-flying render", () => {
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -1018,6 +1064,8 @@ describe("Bug 137: no animation actions lost during rapid pipeline updates", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: "sonnet", status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -1029,6 +1077,8 @@ describe("Bug 137: no animation actions lost during rapid pipeline updates", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-2", model: "haiku", status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -1095,6 +1145,8 @@ describe("Bug 137: no animation actions lost during rapid pipeline updates", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-1", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -1106,6 +1158,8 @@ describe("Bug 137: no animation actions lost during rapid pipeline updates", ()
 					error: null,
 					merge_failure: null,
 					agent: { agent_name: "coder-2", model: null, status: "running" },
+					review_hold: null,
+					qa: null,
 				},
 			],
 		});
@@ -1191,6 +1245,8 @@ describe("Bug 137: animations remain functional through sustained agent activity
 						error: null,
 						merge_failure: null,
 						agent: { agent_name: agentName, model: null, status: "running" },
+						review_hold: null,
+						qa: null,
 					},
 				],
 			});

frontend/src/components/LozengeFlyContext.tsx

@@ -115,7 +115,7 @@ export function LozengeFlyProvider({
 	const assignedAgentNames = useMemo(() => {
 		const names = new Set<string>();
 		for (const item of [
-			...pipeline.upcoming,
+			...pipeline.backlog,
 			...pipeline.current,
 			...pipeline.qa,
 			...pipeline.merge,
@@ -165,13 +165,13 @@ export function LozengeFlyProvider({
 
 		const prev = prevPipelineRef.current;
 		const allPrev = [
-			...prev.upcoming,
+			...prev.backlog,
 			...prev.current,
 			...prev.qa,
 			...prev.merge,
 		];
 		const allCurr = [
-			...pipeline.upcoming,
+			...pipeline.backlog,
 			...pipeline.current,
 			...pipeline.qa,
 			...pipeline.merge,

frontend/src/components/ServerLogsPanel.tsx

@@ -0,0 +1,246 @@
+import * as React from "react";
+
+const { useCallback, useEffect, useRef, useState } = React;
+
+export interface LogEntry {
+	timestamp: string;
+	level: string;
+	message: string;
+}
+
+interface ServerLogsPanelProps {
+	logs: LogEntry[];
+}
+
+function levelColor(level: string): string {
+	switch (level.toUpperCase()) {
+		case "ERROR":
+			return "#e06c75";
+		case "WARN":
+			return "#e5c07b";
+		default:
+			return "#98c379";
+	}
+}
+
+export function ServerLogsPanel({ logs }: ServerLogsPanelProps) {
+	const [isOpen, setIsOpen] = useState(false);
+	const [filter, setFilter] = useState("");
+	const [severityFilter, setSeverityFilter] = useState<string>("ALL");
+	const scrollRef = useRef<HTMLDivElement>(null);
+	const userScrolledUpRef = useRef(false);
+	const lastScrollTopRef = useRef(0);
+
+	const filteredLogs = logs.filter((entry) => {
+		const matchesSeverity =
+			severityFilter === "ALL" || entry.level.toUpperCase() === severityFilter;
+		const matchesFilter =
+			filter === "" ||
+			entry.message.toLowerCase().includes(filter.toLowerCase()) ||
+			entry.timestamp.includes(filter);
+		return matchesSeverity && matchesFilter;
+	});
+
+	const scrollToBottom = useCallback(() => {
+		const el = scrollRef.current;
+		if (el) {
+			el.scrollTop = el.scrollHeight;
+			lastScrollTopRef.current = el.scrollTop;
+		}
+	}, []);
+
+	// Auto-scroll when new entries arrive (unless user scrolled up).
+	useEffect(() => {
+		if (!isOpen) return;
+		if (!userScrolledUpRef.current) {
+			scrollToBottom();
+		}
+	}, [filteredLogs.length, isOpen, scrollToBottom]);
+
+	const handleScroll = () => {
+		const el = scrollRef.current;
+		if (!el) return;
+		const isAtBottom = el.scrollHeight - el.scrollTop - el.clientHeight < 5;
+		if (el.scrollTop < lastScrollTopRef.current) {
+			userScrolledUpRef.current = true;
+		}
+		if (isAtBottom) {
+			userScrolledUpRef.current = false;
+		}
+		lastScrollTopRef.current = el.scrollTop;
+	};
+
+	const severityButtons = ["ALL", "INFO", "WARN", "ERROR"] as const;
+
+	return (
+		<div
+			data-testid="server-logs-panel"
+			style={{
+				borderRadius: "8px",
+				border: "1px solid #333",
+				overflow: "hidden",
+			}}
+		>
+			{/* Header / toggle */}
+			<button
+				type="button"
+				data-testid="server-logs-panel-toggle"
+				onClick={() => setIsOpen((v) => !v)}
+				style={{
+					width: "100%",
+					display: "flex",
+					alignItems: "center",
+					justifyContent: "space-between",
+					padding: "8px 12px",
+					background: "#1e1e1e",
+					border: "none",
+					cursor: "pointer",
+					color: "#ccc",
+					fontSize: "0.85em",
+					fontWeight: 600,
+					textAlign: "left",
+				}}
+			>
+				<span>Server Logs</span>
+				<span style={{ color: "#666", fontSize: "0.85em" }}>
+					{logs.length > 0 && (
+						<span style={{ marginRight: "8px", color: "#555" }}>
+							{logs.length}
+						</span>
+					)}
+					{isOpen ? "▲" : "▼"}
+				</span>
+			</button>
+
+			{isOpen && (
+				<div style={{ background: "#0d1117" }}>
+					{/* Filter controls */}
+					<div
+						style={{
+							display: "flex",
+							gap: "6px",
+							padding: "8px",
+							borderBottom: "1px solid #1e1e1e",
+							flexWrap: "wrap",
+							alignItems: "center",
+						}}
+					>
+						<input
+							type="text"
+							data-testid="server-logs-filter-input"
+							value={filter}
+							onChange={(e) => setFilter(e.target.value)}
+							placeholder="Filter logs..."
+							style={{
+								flex: 1,
+								minWidth: "80px",
+								padding: "4px 8px",
+								borderRadius: "4px",
+								border: "1px solid #333",
+								background: "#161b22",
+								color: "#ccc",
+								fontSize: "0.8em",
+								outline: "none",
+							}}
+						/>
+						{severityButtons.map((sev) => (
+							<button
+								key={sev}
+								type="button"
+								data-testid={`server-logs-severity-${sev.toLowerCase()}`}
+								onClick={() => setSeverityFilter(sev)}
+								style={{
+									padding: "3px 8px",
+									borderRadius: "4px",
+									border: "1px solid",
+									borderColor:
+										severityFilter === sev ? levelColor(sev) : "#333",
+									background:
+										severityFilter === sev
+											? "rgba(255,255,255,0.06)"
+											: "transparent",
+									color:
+										sev === "ALL"
+											? severityFilter === "ALL"
+												? "#ccc"
+												: "#555"
+											: levelColor(sev),
+									fontSize: "0.75em",
+									cursor: "pointer",
+									fontWeight: severityFilter === sev ? 700 : 400,
+								}}
+							>
+								{sev}
+							</button>
+						))}
+					</div>
+
+					{/* Log entries */}
+					<div
+						ref={scrollRef}
+						onScroll={handleScroll}
+						data-testid="server-logs-entries"
+						style={{
+							maxHeight: "240px",
+							overflowY: "auto",
+							padding: "4px 0",
+							fontFamily: "monospace",
+							fontSize: "0.75em",
+						}}
+					>
+						{filteredLogs.length === 0 ? (
+							<div
+								style={{
+									padding: "16px",
+									color: "#444",
+									textAlign: "center",
+									fontSize: "0.9em",
+								}}
+							>
+								No log entries
+							</div>
+						) : (
+							filteredLogs.map((entry, idx) => (
+								<div
+									key={`${entry.timestamp}-${idx}`}
+									style={{
+										display: "flex",
+										gap: "6px",
+										padding: "1px 8px",
+										lineHeight: "1.5",
+										borderBottom: "1px solid #111",
+									}}
+								>
+									<span
+										style={{ color: "#444", flexShrink: 0, minWidth: "70px" }}
+									>
+										{entry.timestamp.replace("T", " ").replace("Z", "")}
+									</span>
+									<span
+										style={{
+											color: levelColor(entry.level),
+											flexShrink: 0,
+											minWidth: "38px",
+											fontWeight: 700,
+										}}
+									>
+										{entry.level}
+									</span>
+									<span
+										style={{
+											color: "#c9d1d9",
+											wordBreak: "break-word",
+											whiteSpace: "pre-wrap",
+										}}
+									>
+										{entry.message}
+									</span>
+								</div>
+							))
+						)}
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}

frontend/src/components/StagePanel.test.tsx

@@ -17,6 +17,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -37,6 +39,8 @@ describe("StagePanel", () => {
 					model: "sonnet",
 					status: "running",
 				},
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -56,6 +60,8 @@ describe("StagePanel", () => {
 					model: null,
 					status: "running",
 				},
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -74,6 +80,8 @@ describe("StagePanel", () => {
 					model: "haiku",
 					status: "pending",
 				},
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="QA" items={items} />);
@@ -88,6 +96,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -102,6 +112,8 @@ describe("StagePanel", () => {
 				error: "Missing front matter",
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Upcoming" items={items} />);
@@ -116,6 +128,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Upcoming" items={items} />);
@@ -132,6 +146,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -148,6 +164,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="QA" items={items} />);
@@ -164,6 +182,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Done" items={items} />);
@@ -180,6 +200,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Upcoming" items={items} />);
@@ -199,6 +221,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Current" items={items} />);
@@ -215,6 +239,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="QA" items={items} />);
@@ -231,6 +257,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Done" items={items} />);
@@ -247,6 +275,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: "Squash merge failed: conflicts in Cargo.lock",
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Merge" items={items} />);
@@ -266,6 +296,8 @@ describe("StagePanel", () => {
 				error: null,
 				merge_failure: null,
 				agent: null,
+				review_hold: null,
+				qa: null,
 			},
 		];
 		render(<StagePanel title="Merge" items={items} />);

frontend/src/components/StagePanel.tsx

@@ -42,6 +42,8 @@ interface StagePanelProps {
 	items: PipelineStageItem[];
 	emptyMessage?: string;
 	onItemClick?: (item: PipelineStageItem) => void;
+	/** Map of story_id → total_cost_usd for displaying cost badges. */
+	costs?: Map<string, number>;
 }
 
 function AgentLozenge({
@@ -128,6 +130,7 @@ export function StagePanel({
 	items,
 	emptyMessage = "Empty.",
 	onItemClick,
+	costs,
 }: StagePanelProps) {
 	return (
 		<div
@@ -240,6 +243,19 @@ export function StagePanel({
 												{typeLabel}
 											</span>
 										)}
+										{costs?.has(item.story_id) && (
+											<span
+												data-testid={`cost-badge-${item.story_id}`}
+												style={{
+													fontSize: "0.65em",
+													fontWeight: 600,
+													color: "#e3b341",
+													marginRight: "8px",
+												}}
+											>
+												${costs.get(item.story_id)?.toFixed(2)}
+											</span>
+										)}
 										{item.name ?? item.story_id}
 									</div>
 									{item.error && (

frontend/src/components/TokenUsagePage.tsx

@@ -0,0 +1,440 @@
+import * as React from "react";
+import type { TokenUsageRecord } from "../api/client";
+import { api } from "../api/client";
+
+type SortKey =
+	| "timestamp"
+	| "story_id"
+	| "agent_name"
+	| "model"
+	| "total_cost_usd";
+type SortDir = "asc" | "desc";
+
+function formatCost(usd: number): string {
+	if (usd === 0) return "$0.00";
+	if (usd < 0.001) return `$${usd.toFixed(6)}`;
+	if (usd < 0.01) return `$${usd.toFixed(4)}`;
+	return `$${usd.toFixed(3)}`;
+}
+
+function formatTokens(n: number): string {
+	if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
+	return String(n);
+}
+
+function formatTimestamp(iso: string): string {
+	const d = new Date(iso);
+	const year = d.getFullYear();
+	const month = String(d.getMonth() + 1).padStart(2, "0");
+	const day = String(d.getDate()).padStart(2, "0");
+	const h = String(d.getHours()).padStart(2, "0");
+	const m = String(d.getMinutes()).padStart(2, "0");
+	return `${year}-${month}-${day} ${h}:${m}`;
+}
+
+/** Infer an agent type from the agent name. */
+function agentType(agentName: string): string {
+	const lower = agentName.toLowerCase();
+	if (lower.startsWith("coder")) return "coder";
+	if (lower.startsWith("qa")) return "qa";
+	if (lower.startsWith("mergemaster") || lower.startsWith("merge"))
+		return "mergemaster";
+	return "other";
+}
+
+interface SortHeaderProps {
+	label: string;
+	sortKey: SortKey;
+	current: SortKey;
+	dir: SortDir;
+	onSort: (key: SortKey) => void;
+	align?: "left" | "right";
+}
+
+function SortHeader({
+	label,
+	sortKey,
+	current,
+	dir,
+	onSort,
+	align = "left",
+}: SortHeaderProps) {
+	const active = current === sortKey;
+	return (
+		<th
+			style={{
+				padding: "8px 12px",
+				textAlign: align,
+				cursor: "pointer",
+				userSelect: "none",
+				borderBottom: "1px solid #333",
+				color: active ? "#ececec" : "#aaa",
+				fontWeight: active ? "700" : "500",
+				whiteSpace: "nowrap",
+				fontSize: "0.8em",
+				letterSpacing: "0.05em",
+				textTransform: "uppercase",
+			}}
+			onClick={() => onSort(sortKey)}
+		>
+			{label}
+			{active ? (dir === "asc" ? " ↑" : " ↓") : ""}
+		</th>
+	);
+}
+
+interface TokenUsagePageProps {
+	projectPath: string;
+}
+
+export function TokenUsagePage({
+	projectPath: _projectPath,
+}: TokenUsagePageProps) {
+	const [records, setRecords] = React.useState<TokenUsageRecord[]>([]);
+	const [loading, setLoading] = React.useState(true);
+	const [error, setError] = React.useState<string | null>(null);
+	const [sortKey, setSortKey] = React.useState<SortKey>("timestamp");
+	const [sortDir, setSortDir] = React.useState<SortDir>("desc");
+
+	React.useEffect(() => {
+		setLoading(true);
+		setError(null);
+		api
+			.getAllTokenUsage()
+			.then((resp) => setRecords(resp.records))
+			.catch((e) =>
+				setError(e instanceof Error ? e.message : "Failed to load token usage"),
+			)
+			.finally(() => setLoading(false));
+	}, []);
+
+	function handleSort(key: SortKey) {
+		if (key === sortKey) {
+			setSortDir((d) => (d === "asc" ? "desc" : "asc"));
+		} else {
+			setSortKey(key);
+			setSortDir(key === "timestamp" ? "desc" : "asc");
+		}
+	}
+
+	const sorted = React.useMemo(() => {
+		return [...records].sort((a, b) => {
+			let cmp = 0;
+			switch (sortKey) {
+				case "timestamp":
+					cmp = a.timestamp.localeCompare(b.timestamp);
+					break;
+				case "story_id":
+					cmp = a.story_id.localeCompare(b.story_id);
+					break;
+				case "agent_name":
+					cmp = a.agent_name.localeCompare(b.agent_name);
+					break;
+				case "model":
+					cmp = (a.model ?? "").localeCompare(b.model ?? "");
+					break;
+				case "total_cost_usd":
+					cmp = a.total_cost_usd - b.total_cost_usd;
+					break;
+			}
+			return sortDir === "asc" ? cmp : -cmp;
+		});
+	}, [records, sortKey, sortDir]);
+
+	// Compute summary totals
+	const totalCost = records.reduce((s, r) => s + r.total_cost_usd, 0);
+
+	const byAgentType = React.useMemo(() => {
+		const map: Record<string, number> = {};
+		for (const r of records) {
+			const t = agentType(r.agent_name);
+			map[t] = (map[t] ?? 0) + r.total_cost_usd;
+		}
+		return map;
+	}, [records]);
+
+	const byModel = React.useMemo(() => {
+		const map: Record<string, number> = {};
+		for (const r of records) {
+			const m = r.model ?? "unknown";
+			map[m] = (map[m] ?? 0) + r.total_cost_usd;
+		}
+		return map;
+	}, [records]);
+
+	const cellStyle: React.CSSProperties = {
+		padding: "7px 12px",
+		borderBottom: "1px solid #222",
+		fontSize: "0.85em",
+		color: "#ccc",
+		whiteSpace: "nowrap",
+	};
+
+	return (
+		<div
+			style={{
+				height: "100%",
+				overflowY: "auto",
+				background: "#111",
+				padding: "24px",
+				fontFamily: "monospace",
+			}}
+		>
+			<h2
+				style={{
+					color: "#ececec",
+					margin: "0 0 20px",
+					fontSize: "1.1em",
+					fontWeight: "700",
+					letterSpacing: "0.04em",
+				}}
+			>
+				Token Usage
+			</h2>
+
+			{/* Summary totals */}
+			<div
+				style={{
+					display: "flex",
+					gap: "16px",
+					flexWrap: "wrap",
+					marginBottom: "24px",
+				}}
+			>
+				<SummaryCard
+					label="Total Cost"
+					value={formatCost(totalCost)}
+					highlight
+				/>
+				{Object.entries(byAgentType)
+					.sort(([a], [b]) => a.localeCompare(b))
+					.map(([type, cost]) => (
+						<SummaryCard
+							key={type}
+							label={`${type.charAt(0).toUpperCase()}${type.slice(1)}`}
+							value={formatCost(cost)}
+						/>
+					))}
+				{Object.entries(byModel)
+					.sort(([, a], [, b]) => b - a)
+					.map(([model, cost]) => (
+						<SummaryCard key={model} label={model} value={formatCost(cost)} />
+					))}
+			</div>
+
+			{loading && (
+				<p style={{ color: "#555", fontSize: "0.9em" }}>Loading...</p>
+			)}
+			{error && <p style={{ color: "#e05c5c", fontSize: "0.9em" }}>{error}</p>}
+
+			{!loading && !error && records.length === 0 && (
+				<p style={{ color: "#555", fontSize: "0.9em" }}>
+					No token usage records found.
+				</p>
+			)}
+
+			{!loading && !error && records.length > 0 && (
+				<div style={{ overflowX: "auto" }}>
+					<table
+						style={{
+							width: "100%",
+							borderCollapse: "collapse",
+							fontSize: "0.9em",
+						}}
+					>
+						<thead>
+							<tr style={{ background: "#1a1a1a" }}>
+								<SortHeader
+									label="Date"
+									sortKey="timestamp"
+									current={sortKey}
+									dir={sortDir}
+									onSort={handleSort}
+								/>
+								<SortHeader
+									label="Story"
+									sortKey="story_id"
+									current={sortKey}
+									dir={sortDir}
+									onSort={handleSort}
+								/>
+								<SortHeader
+									label="Agent"
+									sortKey="agent_name"
+									current={sortKey}
+									dir={sortDir}
+									onSort={handleSort}
+								/>
+								<SortHeader
+									label="Model"
+									sortKey="model"
+									current={sortKey}
+									dir={sortDir}
+									onSort={handleSort}
+								/>
+								<th
+									style={{
+										...cellStyle,
+										borderBottom: "1px solid #333",
+										textAlign: "right",
+										color: "#aaa",
+										fontSize: "0.8em",
+										letterSpacing: "0.05em",
+										textTransform: "uppercase",
+										fontWeight: "500",
+									}}
+								>
+									Input
+								</th>
+								<th
+									style={{
+										...cellStyle,
+										borderBottom: "1px solid #333",
+										textAlign: "right",
+										color: "#aaa",
+										fontSize: "0.8em",
+										letterSpacing: "0.05em",
+										textTransform: "uppercase",
+										fontWeight: "500",
+									}}
+								>
+									Cache+
+								</th>
+								<th
+									style={{
+										...cellStyle,
+										borderBottom: "1px solid #333",
+										textAlign: "right",
+										color: "#aaa",
+										fontSize: "0.8em",
+										letterSpacing: "0.05em",
+										textTransform: "uppercase",
+										fontWeight: "500",
+									}}
+								>
+									Cache↩
+								</th>
+								<th
+									style={{
+										...cellStyle,
+										borderBottom: "1px solid #333",
+										textAlign: "right",
+										color: "#aaa",
+										fontSize: "0.8em",
+										letterSpacing: "0.05em",
+										textTransform: "uppercase",
+										fontWeight: "500",
+									}}
+								>
+									Output
+								</th>
+								<SortHeader
+									label="Cost"
+									sortKey="total_cost_usd"
+									current={sortKey}
+									dir={sortDir}
+									onSort={handleSort}
+									align="right"
+								/>
+							</tr>
+						</thead>
+						<tbody>
+							{sorted.map((r, i) => (
+								<tr
+									key={`${r.story_id}-${r.agent_name}-${r.timestamp}`}
+									style={{ background: i % 2 === 0 ? "#111" : "#161616" }}
+								>
+									<td style={cellStyle}>{formatTimestamp(r.timestamp)}</td>
+									<td
+										style={{
+											...cellStyle,
+											color: "#8b9cf7",
+											maxWidth: "220px",
+											overflow: "hidden",
+											textOverflow: "ellipsis",
+										}}
+									>
+										{r.story_id}
+									</td>
+									<td style={{ ...cellStyle, color: "#7ec8a4" }}>
+										{r.agent_name}
+									</td>
+									<td style={{ ...cellStyle, color: "#c9a96e" }}>
+										{r.model ?? "—"}
+									</td>
+									<td style={{ ...cellStyle, textAlign: "right" }}>
+										{formatTokens(r.input_tokens)}
+									</td>
+									<td style={{ ...cellStyle, textAlign: "right" }}>
+										{formatTokens(r.cache_creation_input_tokens)}
+									</td>
+									<td style={{ ...cellStyle, textAlign: "right" }}>
+										{formatTokens(r.cache_read_input_tokens)}
+									</td>
+									<td style={{ ...cellStyle, textAlign: "right" }}>
+										{formatTokens(r.output_tokens)}
+									</td>
+									<td
+										style={{
+											...cellStyle,
+											textAlign: "right",
+											color: "#e08c5c",
+											fontWeight: "600",
+										}}
+									>
+										{formatCost(r.total_cost_usd)}
+									</td>
+								</tr>
+							))}
+						</tbody>
+					</table>
+				</div>
+			)}
+		</div>
+	);
+}
+
+function SummaryCard({
+	label,
+	value,
+	highlight = false,
+}: {
+	label: string;
+	value: string;
+	highlight?: boolean;
+}) {
+	return (
+		<div
+			style={{
+				background: highlight ? "#1e1e2e" : "#1a1a1a",
+				border: `1px solid ${highlight ? "#3a3a5a" : "#2a2a2a"}`,
+				borderRadius: "8px",
+				padding: "12px 16px",
+				minWidth: "120px",
+			}}
+		>
+			<div
+				style={{
+					fontSize: "0.7em",
+					color: "#666",
+					textTransform: "uppercase",
+					letterSpacing: "0.07em",
+					marginBottom: "4px",
+				}}
+			>
+				{label}
+			</div>
+			<div
+				style={{
+					fontSize: "1.1em",
+					fontWeight: "700",
+					color: highlight ? "#c9a96e" : "#ececec",
+					fontFamily: "monospace",
+				}}
+			>
+				{value}
+			</div>
+		</div>
+	);
+}

frontend/src/components/WorkItemDetailPanel.test.tsx

@@ -1,7 +1,7 @@
 import { act, render, screen, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { AgentEvent, AgentInfo } from "../api/agents";
-import type { TestResultsResponse } from "../api/client";
+import type { TestResultsResponse, TokenCostResponse } from "../api/client";
 
 vi.mock("../api/client", async () => {
 	const actual =
@@ -12,6 +12,7 @@ vi.mock("../api/client", async () => {
 			...actual.api,
 			getWorkItemContent: vi.fn(),
 			getTestResults: vi.fn(),
+			getTokenCost: vi.fn(),
 		},
 	};
 });
@@ -30,6 +31,7 @@ const { WorkItemDetailPanel } = await import("./WorkItemDetailPanel");
 
 const mockedGetWorkItemContent = vi.mocked(api.getWorkItemContent);
 const mockedGetTestResults = vi.mocked(api.getTestResults);
+const mockedGetTokenCost = vi.mocked(api.getTokenCost);
 const mockedListAgents = vi.mocked(agentsApi.listAgents);
 const mockedSubscribeAgentStream = vi.mocked(subscribeAgentStream);
 
@@ -37,6 +39,7 @@ const DEFAULT_CONTENT = {
 	content: "# Big Title\n\nSome content here.",
 	stage: "current",
 	name: "Big Title Story",
+	agent: null,
 };
 
 const sampleTestResults: TestResultsResponse = {
@@ -51,6 +54,7 @@ beforeEach(() => {
 	vi.clearAllMocks();
 	mockedGetWorkItemContent.mockResolvedValue(DEFAULT_CONTENT);
 	mockedGetTestResults.mockResolvedValue(null);
+	mockedGetTokenCost.mockResolvedValue({ total_cost_usd: 0, agents: [] });
 	mockedListAgents.mockResolvedValue([]);
 	mockedSubscribeAgentStream.mockReturnValue(() => {});
 });
@@ -436,6 +440,60 @@ describe("WorkItemDetailPanel - Agent Logs", () => {
 	});
 });
 
+describe("WorkItemDetailPanel - Assigned Agent", () => {
+	it("shows assigned agent name when agent front matter field is set", async () => {
+		mockedGetWorkItemContent.mockResolvedValue({
+			...DEFAULT_CONTENT,
+			agent: "coder-opus",
+		});
+
+		render(
+			<WorkItemDetailPanel
+				storyId="271_story_test"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		const agentEl = await screen.findByTestId("detail-panel-assigned-agent");
+		expect(agentEl).toHaveTextContent("coder-opus");
+	});
+
+	it("omits assigned agent field when no agent is set in front matter", async () => {
+		render(
+			<WorkItemDetailPanel
+				storyId="271_story_test"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await screen.findByTestId("detail-panel-content");
+		expect(
+			screen.queryByTestId("detail-panel-assigned-agent"),
+		).not.toBeInTheDocument();
+	});
+
+	it("shows the specific agent name not just 'assigned'", async () => {
+		mockedGetWorkItemContent.mockResolvedValue({
+			...DEFAULT_CONTENT,
+			agent: "coder-haiku",
+		});
+
+		render(
+			<WorkItemDetailPanel
+				storyId="271_story_test"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		const agentEl = await screen.findByTestId("detail-panel-assigned-agent");
+		expect(agentEl).toHaveTextContent("coder-haiku");
+		expect(agentEl).not.toHaveTextContent("assigned");
+	});
+});
+
 describe("WorkItemDetailPanel - Test Results", () => {
 	it("shows empty test results message when no results exist", async () => {
 		mockedGetTestResults.mockResolvedValue(null);
@@ -553,3 +611,146 @@ describe("WorkItemDetailPanel - Test Results", () => {
 		});
 	});
 });
+
+describe("WorkItemDetailPanel - Token Cost", () => {
+	const sampleTokenCost: TokenCostResponse = {
+		total_cost_usd: 0.012345,
+		agents: [
+			{
+				agent_name: "coder-1",
+				model: "claude-sonnet-4-6",
+				input_tokens: 1000,
+				output_tokens: 500,
+				cache_creation_input_tokens: 200,
+				cache_read_input_tokens: 100,
+				total_cost_usd: 0.009,
+			},
+			{
+				agent_name: "coder-2",
+				model: null,
+				input_tokens: 800,
+				output_tokens: 300,
+				cache_creation_input_tokens: 0,
+				cache_read_input_tokens: 0,
+				total_cost_usd: 0.003345,
+			},
+		],
+	};
+
+	it("shows empty state when no token data exists", async () => {
+		mockedGetTokenCost.mockResolvedValue({ total_cost_usd: 0, agents: [] });
+
+		render(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByTestId("token-cost-empty")).toBeInTheDocument();
+		});
+		expect(screen.getByText("No token data recorded")).toBeInTheDocument();
+	});
+
+	it("shows per-agent breakdown and total cost when data exists", async () => {
+		mockedGetTokenCost.mockResolvedValue(sampleTokenCost);
+
+		render(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(screen.getByTestId("token-cost-content")).toBeInTheDocument();
+		});
+
+		expect(screen.getByTestId("token-cost-total")).toHaveTextContent(
+			"$0.012345",
+		);
+		expect(screen.getByTestId("token-cost-agent-coder-1")).toBeInTheDocument();
+		expect(screen.getByTestId("token-cost-agent-coder-2")).toBeInTheDocument();
+	});
+
+	it("shows agent name and model when model is present", async () => {
+		mockedGetTokenCost.mockResolvedValue(sampleTokenCost);
+
+		render(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(
+				screen.getByTestId("token-cost-agent-coder-1"),
+			).toBeInTheDocument();
+		});
+
+		const agentRow = screen.getByTestId("token-cost-agent-coder-1");
+		expect(agentRow).toHaveTextContent("coder-1");
+		expect(agentRow).toHaveTextContent("claude-sonnet-4-6");
+	});
+
+	it("shows agent name without model when model is null", async () => {
+		mockedGetTokenCost.mockResolvedValue(sampleTokenCost);
+
+		render(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(
+				screen.getByTestId("token-cost-agent-coder-2"),
+			).toBeInTheDocument();
+		});
+
+		const agentRow = screen.getByTestId("token-cost-agent-coder-2");
+		expect(agentRow).toHaveTextContent("coder-2");
+		expect(agentRow).not.toHaveTextContent("null");
+	});
+
+	it("re-fetches token cost when pipelineVersion changes", async () => {
+		mockedGetTokenCost.mockResolvedValue({ total_cost_usd: 0, agents: [] });
+
+		const { rerender } = render(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={0}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(mockedGetTokenCost).toHaveBeenCalledTimes(1);
+		});
+
+		mockedGetTokenCost.mockResolvedValue(sampleTokenCost);
+
+		rerender(
+			<WorkItemDetailPanel
+				storyId="42_story_foo"
+				pipelineVersion={1}
+				onClose={() => {}}
+			/>,
+		);
+
+		await waitFor(() => {
+			expect(mockedGetTokenCost).toHaveBeenCalledTimes(2);
+		});
+
+		await waitFor(() => {
+			expect(screen.getByTestId("token-cost-content")).toBeInTheDocument();
+		});
+	});
+});

frontend/src/components/WorkItemDetailPanel.tsx

@@ -2,13 +2,18 @@ import * as React from "react";
 import Markdown from "react-markdown";
 import type { AgentEvent, AgentInfo, AgentStatusValue } from "../api/agents";
 import { agentsApi, subscribeAgentStream } from "../api/agents";
-import type { TestCaseResult, TestResultsResponse } from "../api/client";
+import type {
+	AgentCostEntry,
+	TestCaseResult,
+	TestResultsResponse,
+	TokenCostResponse,
+} from "../api/client";
 import { api } from "../api/client";
 
 const { useEffect, useRef, useState } = React;
 
 const STAGE_LABELS: Record<string, string> = {
-	upcoming: "Upcoming",
+	backlog: "Backlog",
 	current: "Current",
 	qa: "QA",
 	merge: "To Merge",
@@ -27,6 +32,8 @@ interface WorkItemDetailPanelProps {
 	storyId: string;
 	pipelineVersion: number;
 	onClose: () => void;
+	/** True when the item is in QA and awaiting human review. */
+	reviewHold?: boolean;
 }
 
 function TestCaseRow({ tc }: { tc: TestCaseResult }) {
@@ -109,10 +116,12 @@ export function WorkItemDetailPanel({
 	storyId,
 	pipelineVersion,
 	onClose,
+	reviewHold: _reviewHold,
 }: WorkItemDetailPanelProps) {
 	const [content, setContent] = useState<string | null>(null);
 	const [stage, setStage] = useState<string>("");
 	const [name, setName] = useState<string | null>(null);
+	const [assignedAgent, setAssignedAgent] = useState<string | null>(null);
 	const [loading, setLoading] = useState(true);
 	const [error, setError] = useState<string | null>(null);
 	const [agentInfo, setAgentInfo] = useState<AgentInfo | null>(null);
@@ -121,6 +130,7 @@ export function WorkItemDetailPanel({
 	const [testResults, setTestResults] = useState<TestResultsResponse | null>(
 		null,
 	);
+	const [tokenCost, setTokenCost] = useState<TokenCostResponse | null>(null);
 	const panelRef = useRef<HTMLDivElement>(null);
 	const cleanupRef = useRef<(() => void) | null>(null);
 
@@ -133,6 +143,7 @@ export function WorkItemDetailPanel({
 				setContent(data.content);
 				setStage(data.stage);
 				setName(data.name);
+				setAssignedAgent(data.agent);
 			})
 			.catch((err: unknown) => {
 				setError(err instanceof Error ? err.message : "Failed to load content");
@@ -154,6 +165,18 @@ export function WorkItemDetailPanel({
 			});
 	}, [storyId, pipelineVersion]);
 
+	// Fetch token cost on mount and when pipeline updates arrive.
+	useEffect(() => {
+		api
+			.getTokenCost(storyId)
+			.then((data) => {
+				setTokenCost(data);
+			})
+			.catch(() => {
+				// Silently ignore — token cost may not exist yet.
+			});
+	}, [storyId, pipelineVersion]);
+
 	useEffect(() => {
 		cleanupRef.current?.();
 		cleanupRef.current = null;
@@ -278,6 +301,14 @@ export function WorkItemDetailPanel({
 							{stageLabel}
 						</div>
 					)}
+					{assignedAgent ? (
+						<div
+							data-testid="detail-panel-assigned-agent"
+							style={{ fontSize: "0.75em", color: "#888" }}
+						>
+							Agent: {assignedAgent}
+						</div>
+					) : null}
 				</div>
 				<button
 					type="button"
@@ -352,6 +383,96 @@ export function WorkItemDetailPanel({
 					</div>
 				)}
 
+				{/* Token Cost section */}
+				<div
+					data-testid="token-cost-section"
+					style={{
+						border: "1px solid #2a2a2a",
+						borderRadius: "8px",
+						padding: "10px 12px",
+						background: "#161616",
+					}}
+				>
+					<div
+						style={{
+							fontWeight: 600,
+							fontSize: "0.8em",
+							color: "#555",
+							marginBottom: "8px",
+						}}
+					>
+						Token Cost
+					</div>
+					{tokenCost && tokenCost.agents.length > 0 ? (
+						<div data-testid="token-cost-content">
+							<div
+								style={{
+									fontSize: "0.75em",
+									color: "#888",
+									marginBottom: "8px",
+								}}
+							>
+								Total:{" "}
+								<span data-testid="token-cost-total" style={{ color: "#ccc" }}>
+									${tokenCost.total_cost_usd.toFixed(6)}
+								</span>
+							</div>
+							{tokenCost.agents.map((agent: AgentCostEntry) => (
+								<div
+									key={agent.agent_name}
+									data-testid={`token-cost-agent-${agent.agent_name}`}
+									style={{
+										fontSize: "0.75em",
+										color: "#888",
+										padding: "4px 0",
+										borderTop: "1px solid #222",
+									}}
+								>
+									<div
+										style={{
+											display: "flex",
+											justifyContent: "space-between",
+											marginBottom: "2px",
+										}}
+									>
+										<span style={{ color: "#ccc", fontWeight: 600 }}>
+											{agent.agent_name}
+											{agent.model ? (
+												<span
+													style={{ color: "#666", fontWeight: 400 }}
+												>{` (${agent.model})`}</span>
+											) : null}
+										</span>
+										<span style={{ color: "#aaa" }}>
+											${agent.total_cost_usd.toFixed(6)}
+										</span>
+									</div>
+									<div style={{ color: "#555" }}>
+										in {agent.input_tokens.toLocaleString()} / out{" "}
+										{agent.output_tokens.toLocaleString()}
+										{(agent.cache_creation_input_tokens > 0 ||
+											agent.cache_read_input_tokens > 0) && (
+											<>
+												{" "}
+												/ cache +
+												{agent.cache_creation_input_tokens.toLocaleString()}{" "}
+												read {agent.cache_read_input_tokens.toLocaleString()}
+											</>
+										)}
+									</div>
+								</div>
+							))}
+						</div>
+					) : (
+						<div
+							data-testid="token-cost-empty"
+							style={{ fontSize: "0.75em", color: "#444" }}
+						>
+							No token data recorded
+						</div>
+					)}
+				</div>
+
 				{/* Test Results section */}
 				<div
 					data-testid="test-results-section"
@@ -410,75 +531,96 @@ export function WorkItemDetailPanel({
 					}}
 				>
 					{/* Agent Logs section */}
-					<div
+					{!agentInfo && (
-						data-testid={
-							agentInfo ? "agent-logs-section" : "placeholder-agent-logs"
-						}
-						style={{
-							border: "1px solid #2a2a2a",
-							borderRadius: "8px",
-							padding: "10px 12px",
-							background: "#161616",
-						}}
-					>
 						<div
+							data-testid="placeholder-agent-logs"
 							style={{
-								display: "flex",
+								border: "1px solid #2a2a2a",
-								alignItems: "center",
+								borderRadius: "8px",
-								justifyContent: "space-between",
+								padding: "10px 12px",
-								marginBottom: agentInfo ? "6px" : "4px",
+								background: "#161616",
 							}}
 						>
 							<div
 								style={{
 									fontWeight: 600,
 									fontSize: "0.8em",
-									color: agentInfo ? "#888" : "#555",
+									color: "#555",
+									marginBottom: "4px",
 								}}
 							>
 								Agent Logs
 							</div>
-							{agentInfo && agentStatus && (
-								<div
-									data-testid="agent-status-badge"
-									style={{
-										fontSize: "0.7em",
-										color: STATUS_COLORS[agentStatus],
-										fontWeight: 600,
-									}}
-								>
-									{agentInfo.agent_name} — {agentStatus}
-								</div>
-							)}
-						</div>
-						{agentInfo && agentLog.length > 0 ? (
-							<div
-								data-testid="agent-log-output"
-								style={{
-									fontSize: "0.75em",
-									fontFamily: "monospace",
-									color: "#ccc",
-									whiteSpace: "pre-wrap",
-									wordBreak: "break-word",
-									lineHeight: "1.5",
-									maxHeight: "200px",
-									overflowY: "auto",
-								}}
-							>
-								{agentLog.join("")}
-							</div>
-						) : agentInfo ? (
-							<div style={{ fontSize: "0.75em", color: "#444" }}>
-								{agentStatus === "running" || agentStatus === "pending"
-									? "Waiting for output..."
-									: "No output."}
-							</div>
-						) : (
 							<div style={{ fontSize: "0.75em", color: "#444" }}>
 								Coming soon
 							</div>
-						)}
+						</div>
-					</div>
+					)}
+					{agentInfo && (
+						<div
+							data-testid="agent-logs-section"
+							style={{
+								border: "1px solid #2a2a2a",
+								borderRadius: "8px",
+								padding: "10px 12px",
+								background: "#161616",
+							}}
+						>
+							<div
+								style={{
+									display: "flex",
+									alignItems: "center",
+									justifyContent: "space-between",
+									marginBottom: "6px",
+								}}
+							>
+								<div
+									style={{
+										fontWeight: 600,
+										fontSize: "0.8em",
+										color: "#888",
+									}}
+								>
+									Agent Logs
+								</div>
+								{agentStatus && (
+									<div
+										data-testid="agent-status-badge"
+										style={{
+											fontSize: "0.7em",
+											color: STATUS_COLORS[agentStatus],
+											fontWeight: 600,
+										}}
+									>
+										{agentInfo.agent_name} — {agentStatus}
+									</div>
+								)}
+							</div>
+							{agentLog.length > 0 ? (
+								<div
+									data-testid="agent-log-output"
+									style={{
+										fontSize: "0.75em",
+										fontFamily: "monospace",
+										color: "#ccc",
+										whiteSpace: "pre-wrap",
+										wordBreak: "break-word",
+										lineHeight: "1.5",
+										maxHeight: "200px",
+										overflowY: "auto",
+									}}
+								>
+									{agentLog.join("")}
+								</div>
+							) : (
+								<div style={{ fontSize: "0.75em", color: "#444" }}>
+									{agentStatus === "running" || agentStatus === "pending"
+										? "Waiting for output..."
+										: "No output."}
+								</div>
+							)}
+						</div>
+					)}
 
 					{/* Placeholder sections for future content */}
 					{(

frontend/src/components/selection/SelectionScreen.test.tsx

@@ -33,7 +33,7 @@ function makeProps(
 describe("SelectionScreen", () => {
 	it("renders the title and description", () => {
 		render(<SelectionScreen {...makeProps()} />);
-		expect(screen.getByText("Story Kit")).toBeInTheDocument();
+		expect(screen.getByText("Storkit")).toBeInTheDocument();
 		expect(
 			screen.getByText("Paste or complete a project path to start."),
 		).toBeInTheDocument();

frontend/src/components/selection/SelectionScreen.tsx

@@ -54,7 +54,7 @@ export function SelectionScreen({
 			className="selection-screen"
 			style={{ padding: "2rem", maxWidth: "800px", margin: "0 auto" }}
 		>
-			<h1>Story Kit</h1>
+			<h1>Storkit</h1>
 			<p>Paste or complete a project path to start.</p>
 
 			{knownProjects.length > 0 && (

frontend/src/setupTests.ts

@@ -1 +1,20 @@
 import "@testing-library/jest-dom";
+import { beforeEach, vi } from "vitest";
+
+// Provide a default fetch mock so components that call API endpoints on mount
+// don't throw URL-parse errors in the jsdom test environment.  Tests that need
+// specific responses should mock the relevant `api.*` method as usual.
+beforeEach(() => {
+	vi.stubGlobal(
+		"fetch",
+		vi.fn((input: string | URL | Request) => {
+			const url = typeof input === "string" ? input : input.toString();
+			// Endpoints that return arrays need [] not {} to avoid "not iterable" errors.
+			const arrayEndpoints = ["/agents", "/agents/config"];
+			const body = arrayEndpoints.some((ep) => url.endsWith(ep))
+				? JSON.stringify([])
+				: JSON.stringify({});
+			return Promise.resolve(new Response(body, { status: 200 }));
+		}),
+	);
+});

frontend/vite.config.ts

@@ -16,10 +16,31 @@ export default defineConfig(() => {
         "/api": {
           target: `http://127.0.0.1:${String(backendPort)}`,
           timeout: 120000,
+          configure: (proxy) => {
+            proxy.on("error", (_err) => {
+              // Swallow proxy errors (e.g. ECONNREFUSED during backend restart)
+              // so the vite dev server doesn't crash.
+            });
+          },
+        },
+        "/agents": {
+          target: `http://127.0.0.1:${String(backendPort)}`,
+          timeout: 120000,
+          configure: (proxy) => {
+            proxy.on("error", (_err) => {});
+          },
         },
       },
       watch: {
-        ignored: ["**/.story_kit/**", "**/target/**"],
+        ignored: [
+          "**/.story_kit/**",
+          "**/target/**",
+          "**/.git/**",
+          "**/server/**",
+          "**/Cargo.*",
+          "**/vendor/**",
+          "**/node_modules/**",
+        ],
       },
     },
     build: {