storkit: create 452_bug_claude_code_pty_crashes_with_fatal_runtime_error_on_agent_restart

The /help test expected the help overlay to appear, but /help now goes
through botCommand like other slash commands. Updated the test to match.

Also added reader thread join and child.wait() calls to
claude_code.rs to prevent PTY master fd leaks from web UI chat sessions.

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

.claude/settings.json

@@ -1,5 +1,7 @@
 {
-  "enabledMcpjsonServers": ["storkit"],
+  "enabledMcpjsonServers": [
+    "storkit"
+  ],
   "permissions": {
     "allow": [
       "Bash(./server/target/debug/storkit:*)",
@@ -67,7 +69,8 @@
       "Bash(tail *)",
       "Bash(wc *)",
       "Bash(npx vite:*)",
-      "Bash(npm run dev:*)"
+      "Bash(npm run dev:*)",
+      "Bash(stat *)"
     ]
   }
-}
+}

.storkit/README.md

@@ -9,16 +9,22 @@
 
 When you start a new session with this project:
 
-1. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
+1. **Check Setup Wizard:** Call `wizard_status` to check if project setup is complete. If the wizard is not complete, guide the user through the remaining steps. Important rules for the wizard flow:
+   - **Be conversational.** Don't show tool names, step numbers, or raw wizard output to the user.
+   - **On projects with existing code:** Read the codebase and generate each file, then show the user what you wrote and ask if it looks right.
+   - **On bare projects with no code:** Ask the user what they want to build, what language/framework they plan to use, and generate files from their answers.
+   - **You must actually generate the files.** The workflow for each step is: (1) call `wizard_generate` with no args to get a hint, (2) write the file content yourself based on the conversation, (3) call `wizard_generate` again with the `content` argument containing the full file body, (4) show the user what you wrote, (5) call `wizard_confirm` (they approve), `wizard_retry` (they want changes), or `wizard_skip` (they want to skip). Do not stop after discussing — follow through and write the files.
+   - **Keep moving.** After each step is confirmed, immediately proceed to the next wizard step without waiting for the user to ask.
+2. **Check for MCP Tools:** Read `.mcp.json` to discover the MCP server endpoint. Then list available tools by calling:
    ```bash
    curl -s "$(jq -r '.mcpServers["storkit"].url' .mcp.json)" \
      -H 'Content-Type: application/json' \
      -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
    ```
    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_backlog/` and `.story_kit/work/2_current/` to see what work is pending.
+3. **Read Context:** Check `.storkit/specs/00_CONTEXT.md` for high-level project goals.
+4. **Read Stack:** Check `.storkit/specs/tech/STACK.md` for technical constraints and patterns.
+5. **Check Work Items:** Look at `.storkit/work/1_backlog/` and `.storkit/work/2_current/` to see what work is pending.
 
 
 ---

.storkit/project.toml

@@ -63,30 +63,52 @@ system_prompt = "You are a full-stack engineer working autonomously in a git wor
 [[agent]]
 name = "qa-2"
 stage = "qa"
-role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+role = "Reviews coder work in worktrees: runs quality gates, verifies acceptance criteria, and reports findings."
 model = "sonnet"
 max_turns = 40
 max_budget_usd = 4.00
-prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
 ## Your Workflow
 
-### 1. Code Quality Scan
-- Run `git diff master...HEAD --stat` to see what files changed
-- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
-- Run `cargo clippy --all-targets --all-features` and note any warnings
+### 0. Read the Story
+- Read the story file at `.storkit/work/3_qa/{{story_id}}.md`
+- Extract every acceptance criterion (the `- [ ]` checkbox lines)
+- Keep this list in mind for Step 3
+
+### 1. Deterministic Gates (Prerequisites)
+Run these first — if any fail, reject immediately without proceeding to AC review:
+- Run `cargo clippy --all-targets --all-features` — must show 0 errors, 0 warnings
+- Run `cargo test` and verify all tests pass
 - If a `frontend/` directory exists:
   - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
+  - Run `npm test` and verify all frontend tests pass
 
-### 2. Test Verification
-- Run `cargo test` and verify all tests pass
-- If `frontend/` exists: run `npm test` and verify all frontend tests pass
-- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+### 2. Code Change Review
+- Run `git diff master...HEAD --stat` to see what files changed
+- Run `git diff master...HEAD` to review the actual changes
+- Flag any incomplete implementations:
+  - `todo!()`, `unimplemented!()`, `panic!()` used as stubs
+  - Placeholder strings like "TODO", "FIXME", "not implemented"
+  - Empty match arms or arms that just return `Default::default()`
+  - Hardcoded values where real logic is expected
+- Note any obvious coding mistakes (unused imports, dead code, unhandled errors)
 
-### 3. Manual Testing Support
+### 3. Acceptance Criteria Review
+For each AC extracted in Step 0:
+- Review the diff and test files to determine if the code addresses this AC
+- PASS: describe specifically how the code addresses it (which file/function/test)
+- FAIL: explain exactly what is missing or incorrect
+
+An AC fails if:
+- No code change or test relates to it
+- The implementation is stubbed out (todo!/unimplemented!)
+- A test exists but doesn't actually assert the behaviour described
+
+### 4. Manual Testing Support (only if all gates PASS and all ACs PASS)
 - Build the server: run `cargo build` and note success/failure
 - If build succeeds: find a free port (try 3010-3020) and attempt to start the server
 - Generate a testing plan including:
@@ -95,8 +117,8 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - curl commands to exercise relevant API endpoints
 - Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — 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:
+### 5. Produce Structured Report and Verdict
+Print your QA report to stdout. Then call `approve_qa` or `reject_qa` via the MCP tool based on the overall result. Use this format:
 
 ```
 ## QA Report for {{story_id}}
@@ -105,27 +127,38 @@ Print your QA report to stdout before your process exits. The server will automa
 - clippy: PASS/FAIL (details)
 - TypeScript build: PASS/FAIL/SKIP (details)
 - Biome lint: PASS/FAIL/SKIP (details)
-- Code review findings: (list any issues found, or "None")
-
-### Test Verification
 - cargo test: PASS/FAIL (N tests)
 - npm test: PASS/FAIL/SKIP (N tests)
-- Test quality issues: (list any trivial/weak tests, or "None")
+- Incomplete implementations: (list any todo!/unimplemented!/stubs found, or "None")
+- Other code review findings: (list any issues found, or "None")
+
+### Acceptance Criteria Review
+- AC: <criterion text>
+  Result: PASS/FAIL
+  Evidence: <how the code addresses it, or what is missing>
+
+(repeat for each AC)
 
 ### Manual Testing Plan
-- Server URL: http://localhost:PORT (or "Build failed")
-- Pages to visit: (list)
-- Things to check: (list)
-- curl commands: (list)
+- Server URL: http://localhost:PORT (or "Skipped — gate/AC failure" or "Build failed")
+- Pages to visit: (list, or "N/A")
+- Things to check: (list, or "N/A")
+- curl commands: (list, or "N/A")
 
 ### Overall: PASS/FAIL
+Reason: (summary of why it passed or the primary reason it failed)
 ```
 
+After printing the report:
+- If Overall is PASS: call `approve_qa(story_id='{{story_id}}')` via MCP
+- If Overall is FAIL: call `reject_qa(story_id='{{story_id}}', notes='<concise reason>')` via MCP so the coder knows exactly what to fix
+
 ## Rules
 - Do NOT modify any code — read-only review only
-- If the server fails to start, still provide the testing plan with curl commands
-- The server automatically runs acceptance gates when your process exits"""
-system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+- Gates must pass before AC review — a gate failure is an automatic reject
+- If any AC is not met, the overall result is FAIL
+- Always call approve_qa or reject_qa — never leave the story without a verdict"""
+system_prompt = "You are a QA agent. Your job is read-only: run quality gates, verify each acceptance criterion against the diff, and produce a structured QA report. Always call approve_qa or reject_qa via MCP to record your verdict. Do not modify code."
 
 [[agent]]
 name = "coder-opus"
@@ -140,30 +173,52 @@ system_prompt = "You are a senior full-stack engineer working autonomously in a
 [[agent]]
 name = "qa"
 stage = "qa"
-role = "Reviews coder work in worktrees: runs quality gates, generates testing plans, and reports findings."
+role = "Reviews coder work in worktrees: runs quality gates, verifies acceptance criteria, and reports findings."
 model = "sonnet"
 max_turns = 40
 max_budget_usd = 4.00
-prompt = """You are the QA agent for story {{story_id}}. Your job is to review the coder's work in the worktree and produce a structured QA report.
+prompt = """You are the QA agent for story {{story_id}}. Your job is to verify the coder's work satisfies the story's acceptance criteria and produce a structured QA report.
 
 Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
 
 ## Your Workflow
 
-### 1. Code Quality Scan
-- Run `git diff master...HEAD --stat` to see what files changed
-- Run `git diff master...HEAD` to review the actual changes for obvious coding mistakes (unused imports, dead code, unhandled errors, hardcoded values)
-- Run `cargo clippy --all-targets --all-features` and note any warnings
+### 0. Read the Story
+- Read the story file at `.storkit/work/3_qa/{{story_id}}.md`
+- Extract every acceptance criterion (the `- [ ]` checkbox lines)
+- Keep this list in mind for Step 3
+
+### 1. Deterministic Gates (Prerequisites)
+Run these first — if any fail, reject immediately without proceeding to AC review:
+- Run `cargo clippy --all-targets --all-features` — must show 0 errors, 0 warnings
+- Run `cargo test` and verify all tests pass
 - If a `frontend/` directory exists:
   - Run `npm run build` and note any TypeScript errors
   - Run `npx @biomejs/biome check src/` and note any linting issues
+  - Run `npm test` and verify all frontend tests pass
 
-### 2. Test Verification
-- Run `cargo test` and verify all tests pass
-- If `frontend/` exists: run `npm test` and verify all frontend tests pass
-- Review test quality: look for tests that are trivial or don't assert meaningful behavior
+### 2. Code Change Review
+- Run `git diff master...HEAD --stat` to see what files changed
+- Run `git diff master...HEAD` to review the actual changes
+- Flag any incomplete implementations:
+  - `todo!()`, `unimplemented!()`, `panic!()` used as stubs
+  - Placeholder strings like "TODO", "FIXME", "not implemented"
+  - Empty match arms or arms that just return `Default::default()`
+  - Hardcoded values where real logic is expected
+- Note any obvious coding mistakes (unused imports, dead code, unhandled errors)
 
-### 3. Manual Testing Support
+### 3. Acceptance Criteria Review
+For each AC extracted in Step 0:
+- Review the diff and test files to determine if the code addresses this AC
+- PASS: describe specifically how the code addresses it (which file/function/test)
+- FAIL: explain exactly what is missing or incorrect
+
+An AC fails if:
+- No code change or test relates to it
+- The implementation is stubbed out (todo!/unimplemented!)
+- A test exists but doesn't actually assert the behaviour described
+
+### 4. Manual Testing Support (only if all gates PASS and all ACs PASS)
 - Build the server: run `cargo build` and note success/failure
 - If build succeeds: find a free port (try 3010-3020) and attempt to start the server
 - Generate a testing plan including:
@@ -172,8 +227,8 @@ Read CLAUDE.md first, then .story_kit/README.md to understand the dev process.
   - curl commands to exercise relevant API endpoints
 - Kill the test server when done: `pkill -f 'target.*storkit' || true` (NEVER use `pkill -f storkit` — 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:
+### 5. Produce Structured Report and Verdict
+Print your QA report to stdout. Then call `approve_qa` or `reject_qa` via the MCP tool based on the overall result. Use this format:
 
 ```
 ## QA Report for {{story_id}}
@@ -182,27 +237,38 @@ Print your QA report to stdout before your process exits. The server will automa
 - clippy: PASS/FAIL (details)
 - TypeScript build: PASS/FAIL/SKIP (details)
 - Biome lint: PASS/FAIL/SKIP (details)
-- Code review findings: (list any issues found, or "None")
-
-### Test Verification
 - cargo test: PASS/FAIL (N tests)
 - npm test: PASS/FAIL/SKIP (N tests)
-- Test quality issues: (list any trivial/weak tests, or "None")
+- Incomplete implementations: (list any todo!/unimplemented!/stubs found, or "None")
+- Other code review findings: (list any issues found, or "None")
+
+### Acceptance Criteria Review
+- AC: <criterion text>
+  Result: PASS/FAIL
+  Evidence: <how the code addresses it, or what is missing>
+
+(repeat for each AC)
 
 ### Manual Testing Plan
-- Server URL: http://localhost:PORT (or "Build failed")
-- Pages to visit: (list)
-- Things to check: (list)
-- curl commands: (list)
+- Server URL: http://localhost:PORT (or "Skipped — gate/AC failure" or "Build failed")
+- Pages to visit: (list, or "N/A")
+- Things to check: (list, or "N/A")
+- curl commands: (list, or "N/A")
 
 ### Overall: PASS/FAIL
+Reason: (summary of why it passed or the primary reason it failed)
 ```
 
+After printing the report:
+- If Overall is PASS: call `approve_qa(story_id='{{story_id}}')` via MCP
+- If Overall is FAIL: call `reject_qa(story_id='{{story_id}}', notes='<concise reason>')` via MCP so the coder knows exactly what to fix
+
 ## Rules
 - Do NOT modify any code — read-only review only
-- If the server fails to start, still provide the testing plan with curl commands
-- The server automatically runs acceptance gates when your process exits"""
-system_prompt = "You are a QA agent. Your job is read-only: review code quality, run tests, try to start the server, and produce a structured QA report. Do not modify code. The server automatically runs acceptance gates when your process exits."
+- Gates must pass before AC review — a gate failure is an automatic reject
+- If any AC is not met, the overall result is FAIL
+- Always call approve_qa or reject_qa — never leave the story without a verdict"""
+system_prompt = "You are a QA agent. Your job is read-only: run quality gates, verify each acceptance criterion against the diff, and produce a structured QA report. Always call approve_qa or reject_qa via MCP to record your verdict. Do not modify code."
 
 [[agent]]
 name = "mergemaster"

.storkit/work/1_backlog/435_story_unblock_command_handles_all_stuck_states_not_just_blocked_flag.md

@@ -0,0 +1,21 @@
+---
+name: "Unblock command handles all stuck states not just blocked flag"
+---
+
+# Story 435: Unblock command handles all stuck states not just blocked flag
+
+## User Story
+
+As a project owner, I want the unblock command to clear any stuck state on a story — not just the blocked flag — so that I have a single command to unstick stories regardless of why they're stuck.
+
+## Acceptance Criteria
+
+- [ ] Unblock clears merge_failure field in addition to blocked flag
+- [ ] Unblock clears review_hold field
+- [ ] Unblock reports which fields were cleared in the confirmation message
+- [ ] Unblock works on stories in any pipeline stage (backlog, current, qa, merge, done)
+- [ ] If no stuck state is found (no blocked, merge_failure, or review_hold), returns a clear message saying so
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/436_refactor_unify_story_stuck_states_into_a_single_status_field.md

@@ -0,0 +1,26 @@
+---
+name: "Unify story stuck states into a single status field"
+---
+
+# Refactor 436: Unify story stuck states into a single status field
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Replace the separate blocked, merge_failure, and review_hold front matter fields with a single status field (e.g. status: blocked, status: merge_failure, status: review_hold). Simplifies the unblock command, auto-assign checks, and pipeline advance logic.
+
+## Acceptance Criteria
+
+- [ ] Replace blocked: true, merge_failure: string, and review_hold: true with a single status: field in story front matter
+- [ ] Auto-assign checks a single field instead of three separate ones
+- [ ] Pipeline advance and lifecycle code reads/writes the unified status field
+- [ ] Unblock command clears the status field regardless of which stuck state it was
+- [ ] retry_count remains a separate field (it's a counter, not a state)
+- [ ] Migration: existing stories with old fields are handled gracefully on read
+
+## Out of Scope
+
+- TBD

.storkit/work/1_backlog/452_bug_claude_code_pty_crashes_with_fatal_runtime_error_on_agent_restart.md

@@ -0,0 +1,48 @@
+---
+name: "Zombie process accumulation from unrereaped child processes"
+---
+
+# Bug 452: Zombie process accumulation from unrereaped child processes
+
+## Description
+
+Storkit accumulates zombie processes over time from unrereaped child and grandchild processes. Observed 101 zombies in Docker container, 27 on macOS host. Breakdown: 51 esbuild, 36 echo, 5 claude, 5 sh, 2 bash, 1 cargo.
+
+Root cause: storkit does not reap orphaned grandchild processes. The zombies are mostly grandchildren (`esbuild`, `echo`, `sh`, `cargo`) spawned by `npm run build`, `cargo test`, etc. during worktree setup and gate checks. This happens both natively (observed 27 zombies on macOS host) and in Docker containers. When the intermediate parent exits, these grandchildren get reparented to storkit (or PID 1 in Docker) and become zombies because nobody calls `waitpid` for them.
+
+**Already fixed:**
+- `docker-compose.yml` now has `init: true` which uses tini as PID 1 in Docker — this handles zombie reaping inside containers
+- `llm/providers/claude_code.rs` now has `child.wait()` after `child.kill()` in all code paths, and the reader thread is joined before returning
+- `agents/pty.rs` reader thread is now joined before returning
+
+**Remaining:** Storkit running natively (e.g. on macOS) still accumulates zombie grandchildren because there is no tini. The fix is to add a background reaper thread that periodically calls `waitpid(-1, WNOHANG)` in a loop to clean up any orphaned children. This should be spawned early in `main()` on Unix platforms. Example:
+
+```rust
+#[cfg(unix)]
+std::thread::spawn(|| {
+    loop {
+        unsafe { while libc::waitpid(-1, std::ptr::null_mut(), libc::WNOHANG) > 0 {} }
+        std::thread::sleep(std::time::Duration::from_secs(5));
+    }
+});
+```
+
+## How to Reproduce
+
+Run several agent sessions. Check with `ps -eo stat,comm | grep Z | awk '{print $2}' | sort | uniq -c | sort -rn`.
+
+## Actual Result
+
+Zombie processes accumulate continuously. Never reaped.
+
+## Expected Result
+
+No zombie accumulation during normal operation.
+
+## Acceptance Criteria
+
+- [x] `child.wait()` is called after `child.kill()` in all code paths in `claude_code.rs`
+- [x] Reader threads are joined in both `pty.rs` and `claude_code.rs`
+- [x] `init: true` added to docker-compose.yml for Docker deployments
+- [ ] Background reaper thread added for native (non-Docker) deployments
+- [ ] Verified with `ps aux | grep '<defunct>'` after running multiple agent sessions natively on macOS

.storkit/work/6_archived/426_bug_mergemaster_pipeline_marks_story_done_without_verifying_code_landed_on_master.md

@@ -49,6 +49,26 @@ Story moved to done with no code on master. The merge-queue commit exists on a d
 
 Pipeline should verify that the cherry-pick produced a merge commit on master before advancing to done. If cherry-pick fails or is missing, the story should remain in merge stage with a merge_failure flag.
 
+## Suggested Fix
+
+The code path is: `merge.rs::run_squash_merge` → `pipeline/merge.rs::start_merge_agent_work` → `lifecycle.rs::move_story_to_archived`.
+
+`run_squash_merge` (merge.rs:354) cherry-picks the merge-queue commit onto `project_root` and checks `cp.status.success()`. If it returns `success: true`, `start_merge_agent_work` (pipeline/merge.rs:106) immediately calls `move_story_to_archived`, which moves the story file to `5_done/`. The watcher then commits "storkit: done".
+
+The gap: between the cherry-pick returning success and the story moving to done, nobody verifies the cherry-pick actually produced a code commit on master. Possible failure modes:
+
+1. `project_root` is not on master (e.g. checked out to a merge-queue branch from a concurrent merge)
+2. Cherry-pick exits 0 but produces an empty commit (no code diff)
+3. Cherry-pick succeeds on the wrong branch
+
+**Fix:** After the cherry-pick in `run_squash_merge` succeeds (line 384), before returning `success: true`:
+
+1. Verify `project_root` is on master: `git rev-parse --abbrev-ref HEAD` must equal the base branch
+2. Verify the HEAD commit on master contains the expected merge message (e.g. matches `storkit: merge <story_id>`) or has a non-empty diff
+3. If either check fails, abort the cherry-pick and return `success: false`
+
+This keeps the fix entirely within `run_squash_merge` — no changes needed to the pipeline advance or lifecycle code.
+
 ## Acceptance Criteria
 
 - [ ] Pipeline must not move a story to done unless a merge commit containing the feature code exists on master

.storkit/work/6_archived/429_story_interactive_project_setup_wizard_for_new_storkit_projects.md

@@ -0,0 +1,27 @@
+---
+name: "Interactive project setup wizard for new storkit projects"
+agent: coder-opus
+---
+
+# Story 429: Interactive project setup wizard for new storkit projects
+
+## User Story
+
+As a developer adopting storkit on an existing project, I want a guided setup process that scaffolds the .storkit directory and has an agent generate project-specific configuration files, so that I can get up and running without manually writing specs and scripts.
+
+## Acceptance Criteria
+
+- [ ] storkit init scaffolds .storkit/ directory structure, project.toml, and .mcp.json without clobbering any existing files (especially CLAUDE.md)
+- [ ] Setup wizard tracks progress through ordered steps, resumable if interrupted
+- [ ] Step 1: scaffold .storkit/ directory structure and project.toml
+- [ ] Step 2: agent reads codebase and generates specs/00_CONTEXT.md, user confirms or requests revision
+- [ ] Step 3: agent reads tech stack and generates specs/tech/STACK.md, user confirms or requests revision
+- [ ] Step 4: agent creates script/test that runs the project's actual test suite, user runs it to verify, then confirms
+- [ ] Step 5: agent creates script/release tailored to the project's deployment, user confirms
+- [ ] Step 6: agent creates script/test_coverage if the stack supports it, user confirms
+- [ ] Each step gates on user confirmation before advancing to the next
+- [ ] Existing CLAUDE.md is preserved — storkit appends its content or leaves it untouched
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/430_bug_status_command_traffic_light_dots_not_coloured_in_matrix.md

@@ -0,0 +1,27 @@
+---
+name: "Status command traffic light dots not coloured in Matrix"
+---
+
+# Bug 430: Status command traffic light dots not coloured in Matrix
+
+## Description
+
+The traffic light dots in the status command use plain Unicode characters (○ ● ◑ ✗) which render without colour in Matrix. The HTML formatted_body should use data-mx-color to colour them green/yellow/red.
+
+## How to Reproduce
+
+Send the status command to the bot in Matrix. Observe the dots are monochrome.
+
+## Actual Result
+
+Dots render as plain monochrome Unicode characters.
+
+## Expected Result
+
+Dots render in colour: green (● running), yellow (◑ throttled), red (✗ blocked), grey (○ idle). Use font tag with data-mx-color attribute for Matrix HTML formatted_body.
+
+## Acceptance Criteria
+
+- [ ] HTML formatted_body uses <font data-mx-color="#colour">dot</font> for each traffic light state
+- [ ] Green (#00cc00) for running, yellow (#ffaa00) for throttled, red (#cc0000) for blocked, grey (#888888) for idle
+- [ ] Plain text fallback remains unchanged (Unicode dots for non-HTML transports)

.storkit/work/6_archived/431_story_qa_agent_reviews_code_changes_against_acceptance_criteria.md

@@ -0,0 +1,24 @@
+---
+name: "QA agent reviews code changes against acceptance criteria"
+---
+
+# Story 431: QA agent reviews code changes against acceptance criteria
+
+## User Story
+
+As a project owner, I want the QA agent to actually verify that the coder's implementation matches the story's acceptance criteria, so that incomplete or incorrect work is caught before merge.
+
+## Acceptance Criteria
+
+- [ ] QA agent reads the story's acceptance criteria before reviewing code
+- [ ] QA agent reads the full diff against master to understand what changed
+- [ ] For each AC, QA agent verifies the code addresses it and explains how
+- [ ] QA agent flags incomplete implementations: todo!(), unimplemented!(), missing match arms, placeholder values
+- [ ] QA agent checks that new code has corresponding test coverage
+- [ ] QA agent produces a structured report: each AC with pass/fail and explanation
+- [ ] If any AC is not met, QA rejects the story with a clear reason so the coder can fix it
+- [ ] Deterministic gates (clippy, tests) still run as a prerequisite before the AC review
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/432_story_complete_setup_wizard_with_mcp_tools_and_agent_driven_file_generation.md

@@ -0,0 +1,27 @@
+---
+name: "Complete setup wizard with MCP tools and agent-driven file generation"
+agent: "coder-opus"
+---
+
+# Story 432: Complete setup wizard with MCP tools and agent-driven file generation
+
+## User Story
+
+As a developer running storkit init on a new project, I want the setup wizard to walk me through each step interactively — generating files, letting me review them, and confirming before moving on — so that my project is correctly configured without manual file editing.
+
+## Acceptance Criteria
+
+- [ ] MCP tool wizard_status returns the current wizard state: which step is active, which are done/skipped/pending
+- [ ] MCP tool wizard_generate triggers the agent to read the codebase and generate content for the current step (CONTEXT.md, STACK.md, script/test, script/release, script/test_coverage)
+- [ ] MCP tool wizard_confirm confirms the current step and advances to the next
+- [ ] MCP tool wizard_skip skips the current step and advances to the next
+- [ ] MCP tool wizard_retry re-generates content for the current step if the user isn't happy with it
+- [ ] Bot command setup shows wizard progress and the current step with instructions
+- [ ] Bot command setup confirm / setup skip / setup retry drive the wizard from chat
+- [ ] Generated files are written to disk only after user confirmation, not during generation preview
+- [ ] The wizard works from Claude Code terminal via MCP tools without requiring the web UI or chat bot
+- [ ] Existing files (especially CLAUDE.md) are never overwritten — wizard appends or skips
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/433_story_setup_wizard_interviews_user_on_bare_projects_with_no_existing_code.md

@@ -0,0 +1,24 @@
+---
+name: "Setup wizard interviews user on bare projects with no existing code"
+agent: coder-opus
+---
+
+# Story 433: Setup wizard interviews user on bare projects with no existing code
+
+## User Story
+
+As a developer starting a brand new project from an empty directory, I want the setup wizard to ask me what I'm building and what tech stack I plan to use, so that it can generate meaningful CONTEXT.md and STACK.md without any codebase to analyze.
+
+## Acceptance Criteria
+
+- [ ] wizard_generate detects when the project directory has no source code files
+- [ ] On bare projects, the wizard asks the user what they want to build instead of trying to analyze code
+- [ ] Wizard asks about intended tech stack, frameworks, and language choices
+- [ ] Conversation continues until the user confirms the generated CONTEXT.md captures their intent
+- [ ] STACK.md is generated from the user's stated tech choices rather than from codebase detection
+- [ ] script/test and script/release are generated with appropriate stubs for the stated stack
+- [ ] The interview flow works via both MCP tools (Claude Code terminal) and bot commands (Matrix/WhatsApp/Slack)
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/434_story_wizard_auto_checks_completion_on_first_conversation.md

@@ -0,0 +1,20 @@
+---
+name: "Wizard auto-checks completion on first conversation"
+---
+
+# Story 434: Wizard auto-checks completion on first conversation
+
+## User Story
+
+As a developer opening Claude Code on a storkit project for the first time, I want the wizard to automatically check if setup is complete and prompt me through remaining steps, so I don't have to know to ask for it.
+
+## Acceptance Criteria
+
+- [ ] Scaffolded CLAUDE.md includes an IMPORTANT instruction telling Claude to call wizard_status on first conversation
+- [ ] If wizard is incomplete, Claude guides the user through remaining steps without being asked
+- [ ] If wizard is already complete, no wizard prompt appears — Claude behaves normally
+- [ ] Works on both existing projects with code and bare projects with no code
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/437_bug_strip_prefix_ci_panics_on_multi_byte_utf_8_input.md

@@ -0,0 +1,26 @@
+---
+name: "strip_prefix_ci panics on multi-byte UTF-8 input"
+---
+
+# Bug 437: strip_prefix_ci panics on multi-byte UTF-8 input
+
+## Description
+
+The `strip_prefix_ci` function in `server/src/chat/transport/matrix/assign.rs` slices the input string at `prefix.len()` bytes without checking that the offset is a valid UTF-8 char boundary. When the input message starts with multi-byte characters (e.g. `⏺` which is 3 bytes), the slice can land mid-character, causing a panic.
+
+## How to Reproduce
+
+Send a Matrix message to the bot that starts with a multi-byte UTF-8 character (e.g. `⏺ storkit - wizard_confirm`) where the bot name byte length falls inside a multi-byte character.
+
+## Actual Result
+
+Thread panics: `byte index 6 is not a char boundary; it is inside '⏺' (bytes 4..7)`
+
+## Expected Result
+
+The function should return `None` (no match) without panicking, since an ASCII bot name cannot match a slice containing multi-byte characters.
+
+## Acceptance Criteria
+
+- [ ] strip_prefix_ci checks is_char_boundary before slicing
+- [ ] No panic when input contains multi-byte UTF-8 characters at the prefix boundary

.storkit/work/6_archived/438_story_slash_command_autocomplete_in_web_ui_text_input.md

@@ -0,0 +1,23 @@
+---
+name: "Slash command autocomplete in web UI text input"
+---
+
+# Story 438: Slash command autocomplete in web UI text input
+
+## User Story
+
+As a user, I want to type `/` at the start of the text box and see a filtered list of available slash commands, so that I can discover and quickly invoke commands without memorizing them.
+
+## Acceptance Criteria
+
+- [ ] Typing `/` at position 0 in the ChatInput textarea shows a command picker overlay above the input
+- [ ] The overlay lists all slash commands with name and description
+- [ ] Typing further characters after `/` fuzzy-filters the list
+- [ ] Arrow keys navigate the list, Tab/Enter selects, Escape dismisses
+- [ ] Selecting a command inserts `/<command> ` into the input (with trailing space)
+- [ ] Command list is a single shared source of truth used by both the picker and HelpOverlay
+- [ ] The overlay follows the same visual style as the existing file picker (@-mention overlay)
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/439_refactor_unify_story_stuck_states_into_a_single_status_field.md

@@ -0,0 +1,25 @@
+---
+name: "Deduplicate strip_prefix_ci / strip_bot_mention into chat::util"
+---
+
+# Refactor 439: Deduplicate strip_prefix_ci / strip_bot_mention into chat::util
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Eight Matrix transport files (assign.rs, delete.rs, start.rs, rebuild.rs, reset.rs, rmtree.rs, htop.rs, timer.rs) each contain their own private copies of `strip_prefix_ci` and `strip_bot_mention`. The canonical versions already live in `chat::util` with the correct `is_char_boundary` guard. The duplicates should be removed and all call sites should use `util::strip_bot_mention` instead.
+
+## Acceptance Criteria
+
+- [ ] All 8 private copies of strip_prefix_ci are removed
+- [ ] All 8 private copies of strip_bot_mention are removed
+- [ ] All call sites use chat::util::strip_bot_mention instead
+- [ ] Existing tests in util.rs continue to pass
+- [ ] No new copies of strip_prefix_ci exist outside util.rs
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/440_refactor_consolidate_is_permission_approval_into_chat_util.md

@@ -0,0 +1,24 @@
+---
+name: "Consolidate is_permission_approval into chat::util"
+---
+
+# Refactor 440: Consolidate is_permission_approval into chat::util
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Three copies of `is_permission_approval` exist across Slack (`chat/transport/slack/commands.rs`), WhatsApp (`chat/transport/whatsapp/commands.rs`), and Matrix (`chat/transport/matrix/bot/messages.rs`). The Slack and WhatsApp versions are identical; the Matrix version is a superset that also strips @mentions. Consolidate into a single `pub` function in `chat::util` using the Matrix superset behavior, then delete the 3 private copies.
+
+## Acceptance Criteria
+
+- [ ] Single pub fn is_permission_approval exists in chat::util
+- [ ] All 3 private copies are removed
+- [ ] Matrix @mention-stripping behavior is preserved in the shared version
+- [ ] All call sites use the shared version
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/441_refactor_deduplicate_get_project_root_wrappers_in_io_modules.md

@@ -0,0 +1,22 @@
+---
+name: "Deduplicate get_project_root wrappers in io modules"
+---
+
+# Refactor 441: Deduplicate get_project_root wrappers in io modules
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Both `io/shell.rs` and `io/search.rs` contain identical private one-liner wrappers around `state.get_project_root()`. Either inline the call at each usage site or create a single shared helper, then delete the duplicate wrappers.
+
+## Acceptance Criteria
+
+- [ ] No duplicate private get_project_root wrappers in io/shell.rs and io/search.rs
+- [ ] All call sites use the canonical version or inline the call
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/442_refactor_deduplicate_stage_display_name_into_shared_module.md

@@ -0,0 +1,23 @@
+---
+name: "Deduplicate stage_display_name into shared module"
+---
+
+# Refactor 442: Deduplicate stage_display_name into shared module
+
+## Current State
+
+- TBD
+
+## Desired State
+
+`stage_display_name` has a `pub fn` in `chat/transport/matrix/notifications.rs` and a private copy in `chat/transport/matrix/delete.rs` with slightly different casing ("backlog" vs "Backlog", "in-progress" vs "Current"). The delete.rs copy should use the canonical version from notifications.rs, adjusting the callsite if the casing difference matters.
+
+## Acceptance Criteria
+
+- [ ] Private stage_display_name in delete.rs is removed
+- [ ] delete.rs uses the pub version from notifications.rs
+- [ ] Display casing is consistent or callsite is adjusted to handle the difference
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/443_refactor_extract_shared_find_story_name_from_commands.md

@@ -0,0 +1,23 @@
+---
+name: "Extract shared find_story_name from commands"
+---
+
+# Refactor 443: Extract shared find_story_name from commands
+
+## Current State
+
+- TBD
+
+## Desired State
+
+`find_story_name` is nearly identical in `chat/commands/overview.rs` and `chat/commands/unreleased.rs` (minor style diff: `let stages` vs `const STAGES`). Extract to a shared location (e.g. `chat::commands::util` or `io::stories`) and have both callers use it.
+
+## Acceptance Criteria
+
+- [ ] Single shared find_story_name function exists
+- [ ] Both overview.rs and unreleased.rs use the shared version
+- [ ] Private copies are removed
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/444_refactor_extract_shared_test_helpers_test_ctx_write_story_file_make_api.md

@@ -0,0 +1,26 @@
+---
+name: "Extract shared test helpers (test_ctx, write_story_file, make_api)"
+agent: "coder-opus"
+---
+
+# Refactor 444: Extract shared test helpers (test_ctx, write_story_file, make_api)
+
+## Current State
+
+- TBD
+
+## Desired State
+
+Several test helper functions are copy-pasted across many test modules: `test_ctx` (10 copies across http/ modules), `write_story_file` (5 copies across chat/commands/ and matrix/), `make_api` (5 copies across http/ modules), `setup_project` (3 copies in io/). Extract each into a shared `#[cfg(test)]` utility module so test scaffolding is maintained in one place.
+
+## Acceptance Criteria
+
+- [ ] test_ctx has a single shared definition used by all 10 http test modules
+- [ ] write_story_file has a single shared definition used by all 5 callers
+- [ ] make_api has a single shared definition used by all 5 callers
+- [ ] setup_project has a single shared definition used by all 3 callers
+- [ ] All private copies in individual test modules are removed
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/445_bug_rate_limited_mergemaster_exits_advance_stories_to_done_without_merging.md

@@ -0,0 +1,28 @@
+---
+name: "Rate-limited mergemaster exits advance stories to done without merging"
+---
+
+# Bug 445: Rate-limited mergemaster exits advance stories to done without merging
+
+## Description
+
+When the mergemaster agent is immediately rate-limited (zero turns, zero tool calls), it exits and run_server_owned_completion runs acceptance gates on the existing worktree. Since the coder already committed working code, the gates pass, and the pipeline advances the story to done — even though the mergemaster never executed run_squash_merge and the code was never cherry-picked onto master.
+
+## How to Reproduce
+
+Observed on stories 439 and 442. All mergemaster log entries show: init → rate_limit_event → error result. Zero turns, zero MCP tool calls, duration under 350ms. Yet both stories ended up in done with no merge commit on master.
+
+## Actual Result
+
+Stories advance to done with no code on master. The mergemaster never ran but the pipeline treated its exit as a successful completion.
+
+## Expected Result
+
+If the mergemaster exits without completing its work (no merge commit produced), the story should stay in the merge stage for retry, not advance to done.
+
+## Acceptance Criteria
+
+- [ ] run_server_owned_completion must not run for mergemaster agents — mergemaster has its own completion path via start_merge_agent_work
+- [ ] If the mergemaster process exits without producing a SquashMergeResult, the story stays in merge stage
+- [ ] Rate-limited mergemaster exits are treated as transient failures, not gate-passing completions
+- [ ] Story remains eligible for retry when mergemaster fails due to rate limiting

.storkit/work/6_archived/446_story_oauth_login_button_in_web_ui.md

@@ -0,0 +1,20 @@
+---
+name: "OAuth login button in web UI"
+---
+
+# Story 446: OAuth login button in web UI
+
+## User Story
+
+As a user of the storkit web UI, I want a login button that triggers the Anthropic OAuth flow, so that I can authenticate without manually navigating to /oauth/authorize.
+
+## Acceptance Criteria
+
+- [ ] Web UI shows a login/authenticate button when no OAuth token is active
+- [ ] Clicking the button navigates to /oauth/authorize which starts the Anthropic OAuth flow
+- [ ] After successful OAuth callback, the UI updates to show the authenticated state
+- [ ] If already authenticated, the button is hidden or shows the current auth status
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/447_bug_element_tab_completion_display_name_breaks_bot_command_matching.md

@@ -0,0 +1,27 @@
+---
+name: "Element tab-completion display name breaks bot command matching"
+---
+
+# Bug 447: Element tab-completion display name breaks bot command matching
+
+## Description
+
+When a user tab-completes a bot mention in Element, the Matrix client inserts the display name (e.g. `timmy ⚡️`) rather than the user ID (`@timmy`). If the display name contains emoji or special characters, the `strip_bot_mention` function in chat::util may fail to match it against the bot name, causing commands like `ambient on` to not be recognized.
+
+## How to Reproduce
+
+1. Set bot display_name to include emoji (e.g. `timmy ⚡️`) in bot.toml\n2. In Element, tab-complete the bot name to get `timmy ⚡️`\n3. Send `timmy ⚡️ ambient on`\n4. The bot does not respond — command not matched
+
+## Actual Result
+
+Bot ignores the command. The display name with emoji doesn't match during strip_bot_mention, so the command text is not correctly extracted.
+
+## Expected Result
+
+Bot should recognize commands regardless of whether the mention was tab-completed with the display name (including emoji) or typed manually as @localpart.
+
+## Acceptance Criteria
+
+- [ ] strip_bot_mention handles display names containing emoji and special characters
+- [ ] strip_bot_mention handles Element's tab-completion format (display name followed by colon or comma)
+- [ ] Commands work whether the user types @timmy, timmy, or tab-completes timmy ⚡️

.storkit/work/6_archived/448_story_send_oauth_login_link_via_chat_when_credentials_are_missing.md

@@ -0,0 +1,20 @@
+---
+name: "Send OAuth login link via chat when credentials are missing"
+---
+
+# Story 448: Send OAuth login link via chat when credentials are missing
+
+## User Story
+
+As a storkit user on Matrix or WhatsApp, I want the bot to send me a clickable OAuth authorize link when credentials are missing or expired, so that I can authenticate without terminal access or manually constructing the URL.
+
+## Acceptance Criteria
+
+- [ ] When storkit detects missing or expired credentials during a chat interaction, it sends the user a clickable /oauth/authorize link
+- [ ] Works on Matrix and WhatsApp transports
+- [ ] After successful OAuth callback, the user can immediately resume chatting without restarting storkit
+- [ ] If credentials are already valid, no login link is sent
+
+## Out of Scope
+
+- TBD

.storkit/work/6_archived/449_bug_oauth_callback_url_ignores_port_cli_flag.md

@@ -0,0 +1,27 @@
+---
+name: "OAuth callback URL ignores --port CLI flag"
+---
+
+# Bug 449: OAuth callback URL ignores --port CLI flag
+
+## Description
+
+OAuthState is initialized with `resolve_port()` (reads STORKIT_PORT env var, defaults to 3001) instead of the actual port the server is listening on. When the server is started with `--port 4000`, the OAuth callback URL is still generated as `http://localhost:3001/callback`, so the Anthropic redirect lands on the wrong server and the state parameter lookup fails with "Unknown or expired state parameter".
+
+## How to Reproduce
+
+Start storkit with `--port 4000` (without setting STORKIT_PORT env var). Click the OAuth login button in the web UI. Authenticate with Anthropic. The callback redirect goes to localhost:3001 instead of localhost:4000.
+
+## Actual Result
+
+Callback hits port 3001 (or wrong port). If a different storkit is running there, it returns "Invalid State". If nothing is running there, the page fails to load.
+
+## Expected Result
+
+Callback URL should use the actual server port (from --port CLI flag), so the redirect returns to the correct server instance.
+
+## Acceptance Criteria
+
+- [ ] build_routes receives the actual listening port and passes it to OAuthState::new
+- [ ] OAuth callback URL matches the port the server is actually listening on
+- [ ] Works with --port flag, STORKIT_PORT env var, and default port

.storkit/work/6_archived/450_bug_web_ui_silently_swallows_chat_errors_including_oauth_login_link.md

@@ -0,0 +1,27 @@
+---
+name: "Web UI silently swallows chat errors including OAuth login link"
+---
+
+# Bug 450: Web UI silently swallows chat errors including OAuth login link
+
+## Description
+
+When the WebSocket chat returns an error (e.g. OAuth authentication failed with a login URL), the `onError` handler in `Chat.tsx` only logs to `console.error` and resets loading state. The error message is never displayed to the user. This means the OAuth login link from story #448 works on Matrix/WhatsApp but is invisible in the web UI.
+
+## How to Reproduce
+
+Use the web UI with missing or expired OAuth credentials. Send any chat message. The server detects auth failure, attempts token refresh, fails, and returns an error containing a login URL over WebSocket.
+
+## Actual Result
+
+Nothing visible happens. The error is logged to browser console only. The user sees no feedback.
+
+## Expected Result
+
+The error message (including the clickable OAuth login link) should be displayed in the chat as an assistant message so the user can act on it.
+
+## Acceptance Criteria
+
+- [ ] WebSocket error messages are displayed in the chat UI as assistant messages
+- [ ] OAuth login URL in the error is rendered as a clickable link
+- [ ] Consistent with how Matrix and WhatsApp transports display the same error

.storkit/work/6_archived/451_bug_chat_test_tsx_help_test_expects_removed_overlay_behavior.md

@@ -0,0 +1,27 @@
+---
+name: "Chat.test.tsx /help test expects removed overlay behavior"
+---
+
+# Bug 451: Chat.test.tsx /help test expects removed overlay behavior
+
+## Description
+
+The test `AC: /help shows help overlay` in `Chat.test.tsx:1645` expects `/help` to show the `help-overlay` testid element. However, the `/help` intercept was removed from Chat.tsx and `help` was added to `knownCommands`, so `/help` now goes through `api.botCommand()` like other commands. The test needs to be updated to expect a `botCommand("help", ...)` call instead of the overlay. This is blocking gates on stories 449 and 450.
+
+## How to Reproduce
+
+Run `cd frontend && npm test` — the test `AC: /help shows help overlay` fails.
+
+## Actual Result
+
+Test fails: `findByTestId("help-overlay")` times out because the overlay is never rendered. `/help` is dispatched to the backend via `botCommand` instead.
+
+## Expected Result
+
+Test should pass by expecting `/help` to call `api.botCommand("help", ...)` and display the response in chat, consistent with the current code behavior.
+
+## Acceptance Criteria
+
+- [ ] The /help test in Chat.test.tsx is updated to expect botCommand dispatch
+- [ ] All frontend tests pass
+- [ ] HelpOverlay component and showHelp state can be removed from Chat.tsx if no longer used

.storkit/work/6_archived/453_bug_agent_pty_crashes_with_fatal_runtime_error_on_restart_after_gate_failure.md

@@ -0,0 +1,53 @@
+---
+name: "Agent PTY crashes with fatal runtime error on restart after gate failure"
+---
+
+# Bug 453: Agent PTY crashes with fatal runtime error on restart after gate failure
+
+## Description
+
+When an agent completes coding and the acceptance gates fail (e.g. a test failure), the pipeline restarts the agent on the same worktree. The restarted Claude Code PTY process crashes immediately with `fatal runtime error: assertion failed: output.write(&bytes).is_ok(), aborting`. The process exits in the same second it spawns (Session: None), burns through all 3 retries, and blocks the story.
+
+Key observations:
+- The crash is **deterministic, not intermittent**: the first PTY spawn in a worktree always works; the second spawn (restart) always crashes
+- Running `claude -p "hello"` manually in the same worktree works fine (no crash) — the issue is specific to spawning via portable-pty
+- The worktree is clean (all changes committed) — the agent has nothing to do but fix the gate failure
+- The crash is inside the Claude Code binary, not storkit code
+- Observed on every story that needed a restart: 329, 400, 420, 438, 446, 449, 450
+- Stories that passed gates on the first run were never affected — they never triggered a second spawn
+
+Likely cause: the reader thread spawned by `std::thread::spawn` in `pty.rs` (line 248-255) is never joined. After `run_agent_pty_streaming` returns, the pipeline immediately calls `start_agent` for the retry, but the old reader thread may still be running and holding a cloned PTY reader fd. The new PTY allocation could collide with the still-open fd from the previous session.
+
+The root cause is unknown. It is NOT caused by zombie process accumulation (that is a separate issue in #452).
+
+**Timeline:** The crash first appeared on 2026-03-21. Agent logs go back to 2026-02-23 with no instances before that date. Stories that hit it: 329 (Mar 21), 400 (Mar 26), 420 (Mar 28), 438 (Mar 28), 446 (Mar 30), 449 (Mar 31), 450 (Mar 31).
+
+**Suspect commits around 2026-03-21:**
+- `4344081b` — storkit: merge 343_refactor_abstract_agent_runtime_to_support_non_claude_code_backends (refactored agent runtime layer)
+- `c4e45b28` — The great storkit name conversion
+- Story 359 — Docker security hardening (`cap_drop: ALL`, added back only `SETUID`/`SETGID`) — could affect PTY allocation
+- Story 329 — Docker/OrbStack evaluation spike (first crash was on this story's mergemaster)
+
+**Ruled out:** Docker capability restrictions (cap_drop: ALL) — tested by temporarily removing all cap_drop/security_opt; crash still occurs.
+
+**Evidence of stale PTY fd:** After all agents stopped, storkit (PID 7) was still holding an open fd to `/dev/pts/ptmx` (fd 46). This is a leaked PTY master fd from a previous agent session. The reader thread spawned by `std::thread::spawn` in `pty.rs` is never joined, so the cloned reader fd stays open in the storkit process after the agent exits.
+
+Remaining areas to investigate: the unjoined reader thread leaking PTY fds, and whether the leaked fd from the first session interferes with the second PTY allocation.
+
+## How to Reproduce
+
+1. Have a story in current stage with committed code in its worktree. 2. Introduce a test failure that causes gates to fail. 3. The pipeline restarts the agent on the same worktree. 4. The Claude Code process crashes immediately on spawn.
+
+## Actual Result
+
+`fatal runtime error: assertion failed: output.write(&bytes).is_ok(), aborting` — process exits instantly (same second as spawn), Session: None. Burns through retries and blocks the story.
+
+## Expected Result
+
+The restarted agent should start successfully, receive the gate failure context, and be able to fix the issue.
+
+## Acceptance Criteria
+
+- [ ] Agent restart after gate failure successfully spawns a Claude Code PTY session
+- [ ] No fatal runtime error on PTY restart in a worktree with prior committed work
+- [ ] If Claude Code fails to start, the error is handled gracefully without burning retries

Cargo.lock

@@ -26,7 +26,7 @@ version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "generic-array",
 ]
 
@@ -38,7 +38,7 @@ checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
 dependencies = [
  "cfg-if",
  "cipher",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 ]
 
 [[package]]
@@ -265,16 +265,16 @@ checksum = "a1d084b0137aaa901caf9f1e8b21daa6aa24d41cd806e111335541eff9683bd6"
 
 [[package]]
 name = "blake3"
-version = "1.8.3"
+version = "1.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2468ef7d57b3fb7e16b576e8377cdbde2320c60e1491e961d11da40fc4f02a2d"
+checksum = "4d2d5991425dfd0785aed03aedcf0b321d61975c9b5b3689c774a2610ae0b51e"
 dependencies = [
  "arrayref",
  "arrayvec",
  "cc",
  "cfg-if",
  "constant_time_eq",
- "cpufeatures",
+ "cpufeatures 0.3.0",
 ]
 
 [[package]]
@@ -286,6 +286,15 @@ dependencies = [
  "generic-array",
 ]
 
+[[package]]
+name = "block-buffer"
+version = "0.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cdd35008169921d80bc60d3d0ab416eecb028c4cd653352907921d95084790be"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "block-padding"
 version = "0.3.3"
@@ -391,7 +400,7 @@ checksum = "c3613f74bd2eac03dad61bd53dbe620703d4371614fe0bc3b9f04dd36fe4e818"
 dependencies = [
  "cfg-if",
  "cipher",
- "cpufeatures",
+ "cpufeatures 0.2.17",
 ]
 
 [[package]]
@@ -427,7 +436,7 @@ version = "0.4.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "inout",
  "zeroize",
 ]
@@ -492,6 +501,12 @@ version = "0.9.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8"
 
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
 [[package]]
 name = "const_panic"
 version = "0.2.15"
@@ -551,6 +566,15 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "cpufeatures"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crc32fast"
 version = "1.5.0"
@@ -596,6 +620,15 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "crypto-common"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77727bb15fa921304124b128af125e7e3b968275d1b108b379190264f4423710"
+dependencies = [
+ "hybrid-array",
+]
+
 [[package]]
 name = "ctr"
 version = "0.9.2"
@@ -612,9 +645,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be"
 dependencies = [
  "cfg-if",
- "cpufeatures",
+ "cpufeatures 0.2.17",
  "curve25519-dalek-derive",
- "digest",
+ "digest 0.10.7",
  "fiat-crypto",
  "rustc_version",
  "serde",
@@ -740,7 +773,7 @@ version = "0.7.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb"
 dependencies = [
- "const-oid",
+ "const-oid 0.9.6",
  "zeroize",
 ]
 
@@ -813,11 +846,22 @@ version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
- "block-buffer",
- "crypto-common",
+ "block-buffer 0.10.4",
+ "crypto-common 0.1.7",
  "subtle",
 ]
 
+[[package]]
+name = "digest"
+version = "0.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4850db49bf08e663084f7fb5c87d202ef91a3907271aff24a94eb97ff039153c"
+dependencies = [
+ "block-buffer 0.12.0",
+ "const-oid 0.10.2",
+ "crypto-common 0.2.1",
+]
+
 [[package]]
 name = "displaydoc"
 version = "0.2.5"
@@ -862,7 +906,7 @@ dependencies = [
  "ed25519",
  "rand_core 0.6.4",
  "serde",
- "sha2",
+ "sha2 0.10.9",
  "subtle",
  "zeroize",
 ]
@@ -1371,7 +1415,7 @@ version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
 dependencies = [
- "digest",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -1452,10 +1496,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
-name = "hyper"
-version = "1.8.1"
+name = "hybrid-array"
+version = "0.4.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ab2d4f250c3d7b1c9fcdff1cece94ea4e2dfbec68614f7b87cb205f24ca9d11"
+checksum = "3944cf8cf766b40e2a1a333ee5e9b563f854d5fa49d6a8ca2764e97c6eddb214"
+dependencies = [
+ "typenum",
+]
+
+[[package]]
+name = "hyper"
+version = "1.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -1468,7 +1521,6 @@ dependencies = [
  "httpdate",
  "itoa",
  "pin-project-lite",
- "pin-utils",
  "smallvec",
  "tokio",
  "want",
@@ -1542,12 +1594,13 @@ dependencies = [
 
 [[package]]
 name = "icu_collections"
-version = "2.1.1"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4c6b649701667bbe825c3b7e6388cb521c23d88644678e83c0c4d0a621a34b43"
+checksum = "2984d1cd16c883d7935b9e07e44071dca8d917fd52ecc02c04d5fa0b5a3f191c"
 dependencies = [
  "displaydoc",
  "potential_utf",
+ "utf8_iter",
  "yoke",
  "zerofrom",
  "zerovec",
@@ -1555,9 +1608,9 @@ dependencies = [
 
 [[package]]
 name = "icu_locale_core"
-version = "2.1.1"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "edba7861004dd3714265b4db54a3c390e880ab658fec5f7db895fae2046b5bb6"
+checksum = "92219b62b3e2b4d88ac5119f8904c10f8f61bf7e95b640d25ba3075e6cac2c29"
 dependencies = [
  "displaydoc",
  "litemap",
@@ -1568,9 +1621,9 @@ dependencies = [
 
 [[package]]
 name = "icu_normalizer"
-version = "2.1.1"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5f6c8828b67bf8908d82127b2054ea1b4427ff0230ee9141c54251934ab1b599"
+checksum = "c56e5ee99d6e3d33bd91c5d85458b6005a22140021cc324cea84dd0e72cff3b4"
 dependencies = [
  "icu_collections",
  "icu_normalizer_data",
@@ -1582,15 +1635,15 @@ dependencies = [
 
 [[package]]
 name = "icu_normalizer_data"
-version = "2.1.1"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7aedcccd01fc5fe81e6b489c15b247b8b0690feb23304303a9e560f37efc560a"
+checksum = "da3be0ae77ea334f4da67c12f149704f19f81d1adf7c51cf482943e84a2bad38"
 
 [[package]]
 name = "icu_properties"
-version = "2.1.2"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "020bfc02fe870ec3a66d93e677ccca0562506e5872c650f893269e08615d74ec"
+checksum = "bee3b67d0ea5c2cca5003417989af8996f8604e34fb9ddf96208a033901e70de"
 dependencies = [
  "icu_collections",
  "icu_locale_core",
@@ -1602,15 +1655,15 @@ dependencies = [
 
 [[package]]
 name = "icu_properties_data"
-version = "2.1.2"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "616c294cf8d725c6afcd8f55abc17c56464ef6211f9ed59cccffe534129c77af"
+checksum = "8e2bbb201e0c04f7b4b3e14382af113e17ba4f63e2c9d2ee626b720cbce54a14"
 
 [[package]]
 name = "icu_provider"
-version = "2.1.1"
+version = "2.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85962cf0ce02e1e0a629cc34e7ca3e373ce20dda4c4d7294bbd0bf1fdb59e614"
+checksum = "139c4cf31c8b5f33d7e199446eff9c1e02decfc2f0eec2c8d71f65befa45b421"
 dependencies = [
  "displaydoc",
  "icu_locale_core",
@@ -1774,9 +1827,9 @@ checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
 [[package]]
 name = "iri-string"
-version = "0.7.11"
+version = "0.7.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d8e7418f59cc01c88316161279a7f665217ae316b388e58a0d10e29f54f1e5eb"
+checksum = "25e659a4bb38e810ebc252e53b5814ff908a8c58c2a9ce2fae1bbec24cbf4e20"
 dependencies = [
  "memchr",
  "serde",
@@ -1862,9 +1915,9 @@ dependencies = [
 
 [[package]]
 name = "js-sys"
-version = "0.3.92"
+version = "0.3.94"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cc4c90f45aa2e6eacbe8645f77fdea542ac97a494bcd117a67df9ff4d611f995"
+checksum = "2e04e2ef80ce82e13552136fabeef8a5ed1f985a96805761cbb9a2c34e7664d9"
 dependencies = [
  "cfg-if",
  "futures-util",
@@ -1950,9 +2003,9 @@ checksum = "09edd9e8b54e49e587e4f6295a7d29c3ea94d469cb40ab8ca70b288248a81db2"
 
 [[package]]
 name = "libc"
-version = "0.2.183"
+version = "0.2.184"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
+checksum = "48f5d2a454e16a5ea0f4ced81bd44e4cfc7bd3a507b61887c99fd3538b28e4af"
 
 [[package]]
 name = "libredox"
@@ -1985,9 +2038,9 @@ checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
 
 [[package]]
 name = "litemap"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6373607a59f0be73a39b6fe456b8192fcc3585f602af20751600e974dd455e77"
+checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
 
 [[package]]
 name = "lock_api"
@@ -2158,7 +2211,7 @@ dependencies = [
  "serde",
  "serde_html_form",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "tempfile",
  "thiserror 2.0.18",
  "tokio",
@@ -2251,7 +2304,7 @@ dependencies = [
  "ruma",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "subtle",
  "thiserror 2.0.18",
  "time",
@@ -2286,7 +2339,7 @@ dependencies = [
  "serde",
  "serde-wasm-bindgen",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "thiserror 2.0.18",
  "tokio",
  "tracing",
@@ -2340,7 +2393,7 @@ dependencies = [
  "rmp-serde",
  "serde",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "thiserror 2.0.18",
  "zeroize",
 ]
@@ -2599,7 +2652,7 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_path_to_error",
- "sha2",
+ "sha2 0.10.9",
  "thiserror 1.0.69",
  "url",
 ]
@@ -2657,7 +2710,7 @@ version = "0.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ed6a7761f76e3b9f92dfb0a60a6a6477c61024b775147ff0973a02653abaf2"
 dependencies = [
- "digest",
+ "digest 0.10.7",
  "hmac",
 ]
 
@@ -2711,12 +2764,6 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
-[[package]]
-name = "pin-utils"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
-
 [[package]]
 name = "pkcs8"
 version = "0.10.2"
@@ -2842,7 +2889,7 @@ version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8159bd90725d2df49889a078b54f4f79e87f1f8a8444194cdca81d38f5393abf"
 dependencies = [
- "cpufeatures",
+ "cpufeatures 0.2.17",
  "opaque-debug",
  "universal-hash",
 ]
@@ -2870,9 +2917,9 @@ dependencies = [
 
 [[package]]
 name = "potential_utf"
-version = "0.1.4"
+version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b73949432f5e2a09657003c25bca5e19a0e9c84f8058ca374f49e0ebe605af77"
+checksum = "0103b1cef7ec0cf76490e969665504990193874ea05c85ff9bab8b911d0a0564"
 dependencies = [
  "zerovec",
 ]
@@ -3504,7 +3551,7 @@ dependencies = [
  "rand 0.8.5",
  "ruma-common",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "thiserror 2.0.18",
 ]
 
@@ -3552,7 +3599,7 @@ version = "8.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5bcdef0be6fe7f6fa333b1073c949729274b05f123a0ad7efcb8efd878e5c3b1"
 dependencies = [
- "sha2",
+ "sha2 0.10.9",
  "walkdir",
 ]
 
@@ -3826,9 +3873,9 @@ dependencies = [
 
 [[package]]
 name = "serde_spanned"
-version = "1.1.0"
+version = "1.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "876ac351060d4f882bb1032b6369eb0aef79ad9df1ea8bc404874d8cc3d0cd98"
+checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
 dependencies = [
  "serde_core",
 ]
@@ -3876,8 +3923,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
 dependencies = [
  "cfg-if",
- "cpufeatures",
- "digest",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
 ]
 
 [[package]]
@@ -3887,8 +3934,19 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
 dependencies = [
  "cfg-if",
- "cpufeatures",
- "digest",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
+[[package]]
+name = "sha2"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.3.0",
+ "digest 0.11.2",
 ]
 
 [[package]]
@@ -4019,7 +4077,7 @@ checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
 
 [[package]]
 name = "storkit"
-version = "0.7.0"
+version = "0.8.5"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -4046,12 +4104,12 @@ dependencies = [
  "serde_json",
  "serde_urlencoded",
  "serde_yaml",
- "sha2",
+ "sha2 0.11.0",
  "strip-ansi-escapes",
  "tempfile",
  "tokio",
  "tokio-tungstenite 0.29.0",
- "toml 1.1.0+spec-1.1.0",
+ "toml 1.1.2+spec-1.1.0",
  "uuid",
  "wait-timeout",
  "walkdir",
@@ -4272,9 +4330,9 @@ dependencies = [
 
 [[package]]
 name = "tinystr"
-version = "0.8.2"
+version = "0.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42d3e9c45c09de15d06dd8acf5f4e0e399e85927b7f00711024eb7ae10fa4869"
+checksum = "c8323304221c2a851516f22236c5722a72eaa19749016521d6dff0824447d96d"
 dependencies = [
  "displaydoc",
  "zerovec",
@@ -4398,17 +4456,17 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "1.1.0+spec-1.1.0"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8195ca05e4eb728f4ba94f3e3291661320af739c4e43779cbdfae82ab239fcc"
+checksum = "81f3d15e84cbcd896376e6730314d59fb5a87f31e4b038454184435cd57defee"
 dependencies = [
  "indexmap",
  "serde_core",
  "serde_spanned",
- "toml_datetime 1.1.0+spec-1.1.0",
+ "toml_datetime 1.1.1+spec-1.1.0",
  "toml_parser",
  "toml_writer",
- "winnow 1.0.0",
+ "winnow 1.0.1",
 ]
 
 [[package]]
@@ -4422,39 +4480,39 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "1.1.0+spec-1.1.0"
+version = "1.1.1+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97251a7c317e03ad83774a8752a7e81fb6067740609f75ea2b585b569a59198f"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
 dependencies = [
  "serde_core",
 ]
 
 [[package]]
 name = "toml_edit"
-version = "0.25.8+spec-1.1.0"
+version = "0.25.10+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "16bff38f1d86c47f9ff0647e6838d7bb362522bdf44006c7068c2b1e606f1f3c"
+checksum = "a82418ca169e235e6c399a84e395ab6debeb3bc90edc959bf0f48647c6a32d1b"
 dependencies = [
  "indexmap",
- "toml_datetime 1.1.0+spec-1.1.0",
+ "toml_datetime 1.1.1+spec-1.1.0",
  "toml_parser",
- "winnow 1.0.0",
+ "winnow 1.0.1",
 ]
 
 [[package]]
 name = "toml_parser"
-version = "1.1.0+spec-1.1.0"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2334f11ee363607eb04df9b8fc8a13ca1715a72ba8662a26ac285c98aabb4011"
+checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
 dependencies = [
- "winnow 1.0.0",
+ "winnow 1.0.1",
 ]
 
 [[package]]
 name = "toml_writer"
-version = "1.1.0+spec-1.1.0"
+version = "1.1.1+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d282ade6016312faf3e41e57ebbba0c073e4056dab1232ab1cb624199648f8ed"
+checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
 
 [[package]]
 name = "tower"
@@ -4610,9 +4668,9 @@ checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
 
 [[package]]
 name = "typewit"
-version = "1.14.2"
+version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8c1ae7cc0fdb8b842d65d127cb981574b0d2b249b74d1c7a2986863dc134f71"
+checksum = "06fee3a8df48c50c55ad646a4e03b00a370da6fe1850ebf467a8d0165dfcafae"
 dependencies = [
  "typewit_proc_macros",
 ]
@@ -4681,7 +4739,7 @@ version = "0.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea"
 dependencies = [
- "crypto-common",
+ "crypto-common 0.1.7",
  "subtle",
 ]
 
@@ -4781,7 +4839,7 @@ dependencies = [
  "serde",
  "serde_bytes",
  "serde_json",
- "sha2",
+ "sha2 0.10.9",
  "subtle",
  "thiserror 2.0.18",
  "x25519-dalek",
@@ -4851,9 +4909,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6523d69017b7633e396a89c5efab138161ed5aafcbc8d3e5c5a42ae38f50495a"
+checksum = "0551fc1bb415591e3372d0bc4780db7e587d84e2a7e79da121051c5c4b89d0b0"
 dependencies = [
  "cfg-if",
  "once_cell",
@@ -4864,9 +4922,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-futures"
-version = "0.4.65"
+version = "0.4.67"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2d1faf851e778dfa54db7cd438b70758eba9755cb47403f3496edd7c8fc212f0"
+checksum = "03623de6905b7206edd0a75f69f747f134b7f0a2323392d664448bf2d3c5d87e"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -4874,9 +4932,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4e3a6c758eb2f701ed3d052ff5737f5bfe6614326ea7f3bbac7156192dc32e67"
+checksum = "7fbdf9a35adf44786aecd5ff89b4563a90325f9da0923236f6104e603c7e86be"
 dependencies = [
  "quote",
  "wasm-bindgen-macro-support",
@@ -4884,9 +4942,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-macro-support"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "921de2737904886b52bcbb237301552d05969a6f9c40d261eb0533c8b055fedf"
+checksum = "dca9693ef2bab6d4e6707234500350d8dad079eb508dca05530c85dc3a529ff2"
 dependencies = [
  "bumpalo",
  "proc-macro2",
@@ -4897,9 +4955,9 @@ dependencies = [
 
 [[package]]
 name = "wasm-bindgen-shared"
-version = "0.2.115"
+version = "0.2.117"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a93e946af942b58934c604527337bad9ae33ba1d5c6900bbb41c2c07c2364a93"
+checksum = "39129a682a6d2d841b6c429d0c51e5cb0ed1a03829d8b3d1e69a011e62cb3d3b"
 dependencies = [
  "unicode-ident",
 ]
@@ -4984,9 +5042,9 @@ dependencies = [
 
 [[package]]
 name = "web-sys"
-version = "0.3.92"
+version = "0.3.94"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "84cde8507f4d7cfcb1185b8cb5890c494ffea65edbe1ba82cfd63661c805ed94"
+checksum = "cd70027e39b12f0849461e08ffc50b9cd7688d942c1c8e3c7b22273236b4dd0a"
 dependencies = [
  "js-sys",
  "wasm-bindgen",
@@ -5465,9 +5523,9 @@ checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 
 [[package]]
 name = "winnow"
-version = "1.0.0"
+version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a90e88e4667264a994d34e6d1ab2d26d398dcdca8b7f52bec8668957517fc7d8"
+checksum = "09dac053f1cd375980747450bfc7250c264eaae0583872e845c0c7cd578872b5"
 dependencies = [
  "memchr",
 ]
@@ -5595,9 +5653,9 @@ checksum = "fdd20c5420375476fbd4394763288da7eb0cc0b8c11deed431a91562af7335d3"
 
 [[package]]
 name = "yoke"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "72d6e5c6afb84d73944e5cedb052c4680d5657337201555f9f2a16b7406d4954"
+checksum = "abe8c5fda708d9ca3df187cae8bfb9ceda00dd96231bed36e445a1a48e66f9ca"
 dependencies = [
  "stable_deref_trait",
  "yoke-derive",
@@ -5606,9 +5664,9 @@ dependencies = [
 
 [[package]]
 name = "yoke-derive"
-version = "0.8.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b659052874eb698efe5b9e8cf382204678a0086ebf46982b79d6ca3182927e5d"
+checksum = "de844c262c8848816172cef550288e7dc6c7b7814b4ee56b3e1553f275f1858e"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5618,18 +5676,18 @@ dependencies = [
 
 [[package]]
 name = "zerocopy"
-version = "0.8.47"
+version = "0.8.48"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "efbb2a062be311f2ba113ce66f697a4dc589f85e78a4aea276200804cea0ed87"
+checksum = "eed437bf9d6692032087e337407a86f04cd8d6a16a37199ed57949d415bd68e9"
 dependencies = [
  "zerocopy-derive",
 ]
 
 [[package]]
 name = "zerocopy-derive"
-version = "0.8.47"
+version = "0.8.48"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0e8bc7269b54418e7aeeef514aa68f8690b8c0489a06b0136e5f57c4c5ccab89"
+checksum = "70e3cd084b1788766f53af483dd21f93881ff30d7320490ec3ef7526d203bad4"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5638,18 +5696,18 @@ dependencies = [
 
 [[package]]
 name = "zerofrom"
-version = "0.1.6"
+version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "50cc42e0333e05660c3587f3bf9d0478688e15d870fab3346451ce7f8c9fbea5"
+checksum = "69faa1f2a1ea75661980b013019ed6687ed0e83d069bc1114e2cc74c6c04c4df"
 dependencies = [
  "zerofrom-derive",
 ]
 
 [[package]]
 name = "zerofrom-derive"
-version = "0.1.6"
+version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d71e5d6e06ab090c67b5e44993ec16b72dcbaabc526db883a360057678b48502"
+checksum = "11532158c46691caf0f2593ea8358fed6bbf68a0315e80aae9bd41fbade684a1"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -5679,9 +5737,9 @@ dependencies = [
 
 [[package]]
 name = "zerotrie"
-version = "0.2.3"
+version = "0.2.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a59c17a5562d507e4b54960e8569ebee33bee890c70aa3fe7b97e85a9fd7851"
+checksum = "0f9152d31db0792fa83f70fb2f83148effb5c1f5b8c7686c3459e361d9bc20bf"
 dependencies = [
  "displaydoc",
  "yoke",
@@ -5690,9 +5748,9 @@ dependencies = [
 
 [[package]]
 name = "zerovec"
-version = "0.11.5"
+version = "0.11.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6c28719294829477f525be0186d13efa9a3c602f7ec202ca9e353d310fb9a002"
+checksum = "90f911cbc359ab6af17377d242225f4d75119aec87ea711a880987b18cd7b239"
 dependencies = [
  "yoke",
  "zerofrom",
@@ -5701,9 +5759,9 @@ dependencies = [
 
 [[package]]
 name = "zerovec-derive"
-version = "0.11.2"
+version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eadce39539ca5cb3985590102671f2567e659fca9666581ad3411d59207951f3"
+checksum = "625dc425cab0dca6dc3c3319506e6593dcb08a9f387ea3b284dbd52a92c40555"
 dependencies = [
  "proc-macro2",
  "quote",

Cargo.toml

@@ -21,7 +21,7 @@ rust-embed = "8"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_urlencoded = "0.7"
-sha2 = "0.10"
+sha2 = "0.11.0"
 serde_yaml = "0.9"
 strip-ansi-escapes = "0.2"
 tempfile = "3"

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -1,6 +1,37 @@
 # Storkit
 
-A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend. Communicates via Matrix, WhatsApp, and Slack bot transports, and exposes MCP tools for programmatic access.
+A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend.
+
+## Getting started with Claude Code
+
+1. Download the storkit binary (or build from source — see below).
+
+2. From your project directory, scaffold and start the server:
+
+```bash
+storkit init --port 3000
+```
+
+This creates a `.storkit/` directory with the pipeline structure, `project.toml`, and `.mcp.json`. The `.mcp.json` file lets Claude Code discover storkit's MCP tools automatically.
+
+3. Open a Claude Code session in the same project directory. Claude will pick up the MCP tools from `.mcp.json`.
+
+4. Tell Claude: "help me set up this project with storkit." Claude will walk you through the setup wizard — generating project context, tech stack docs, and test/release scripts. Review each step and confirm or ask to retry.
+
+Once setup is complete, Claude can create stories, start agents, check status, and manage the full pipeline via MCP tools — no commands to memorize.
+
+## Web UI
+
+Storkit also ships an embedded React frontend. Once the server is running, open `http://localhost:3000` to see the pipeline board, agent status, and chat interface.
+
+## Chat transports
+
+Storkit can be controlled via bot commands in **Matrix**, **WhatsApp**, and **Slack**. Configure a transport in `.storkit/bot.toml` — see the example files:
+
+- `.storkit/bot.toml.matrix.example`
+- `.storkit/bot.toml.whatsapp-meta.example`
+- `.storkit/bot.toml.whatsapp-twilio.example`
+- `.storkit/bot.toml.slack.example`
 
 ## Prerequisites
 
@@ -49,7 +80,11 @@ Configuration lives in `.storkit/project.toml`. See `.storkit/bot.toml.*.example
 Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).
 
 ```bash
-script/release 0.6.1
+script/release 0.7.1
 ```
 
 This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.
+
+## License
+
+GPL-3.0. See [LICENSE](LICENSE).

docker/docker-compose.yml

@@ -108,6 +108,11 @@ services:
       retries: 3
       start_period: 10s
 
+    # Use tini as PID 1 to reap zombie child processes.
+    # Without this, grandchild processes (esbuild, cargo, etc.) spawned by
+    # npm/cargo during worktree setup and gate checks become zombies.
+    init: true
+
     # Restart policy – restart on crash but not on manual stop
     restart: unless-stopped
 

frontend/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "living-spec-standalone",
-	"version": "0.7.0",
+	"version": "0.8.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "living-spec-standalone",
-			"version": "0.7.0",
+			"version": "0.8.5",
 			"dependencies": {
 				"@types/react-syntax-highlighter": "^15.5.13",
 				"react": "^19.1.0",

frontend/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "living-spec-standalone",
 	"private": true,
-	"version": "0.7.0",
+	"version": "0.8.5",
 	"type": "module",
 	"scripts": {
 		"dev": "vite",

frontend/src/App.test.tsx

@@ -19,6 +19,7 @@ vi.mock("./api/client", () => {
 		setModelPreference: vi.fn(),
 		cancelChat: vi.fn(),
 		setAnthropicApiKey: vi.fn(),
+		getOAuthStatus: vi.fn(),
 	};
 	class ChatWebSocket {
 		connect() {}
@@ -65,6 +66,12 @@ describe("App", () => {
 		mockedApi.getAnthropicApiKeyExists.mockResolvedValue(false);
 		mockedApi.getAnthropicModels.mockResolvedValue([]);
 		mockedApi.getModelPreference.mockResolvedValue(null);
+		mockedApi.getOAuthStatus.mockResolvedValue({
+			authenticated: false,
+			expired: false,
+			expires_at: 0,
+			has_refresh_token: false,
+		});
 	});
 
 	async function renderApp() {

frontend/src/App.tsx

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { OAuthStatus } from "./api/client";
 import { api } from "./api/client";
 import { Chat } from "./components/Chat";
 import { SelectionScreen } from "./components/selection/SelectionScreen";
@@ -14,6 +15,27 @@ function App() {
 	const [isOpening, setIsOpening] = React.useState(false);
 	const [knownProjects, setKnownProjects] = React.useState<string[]>([]);
 	const [homeDir, setHomeDir] = React.useState<string | null>(null);
+	const [oauthStatus, setOauthStatus] = React.useState<OAuthStatus | null>(
+		null,
+	);
+
+	React.useEffect(() => {
+		let active = true;
+		function fetchOAuthStatus() {
+			api
+				.getOAuthStatus()
+				.then((s) => {
+					if (active) setOauthStatus(s);
+				})
+				.catch(() => {});
+		}
+		fetchOAuthStatus();
+		const intervalId = window.setInterval(fetchOAuthStatus, 5000);
+		return () => {
+			active = false;
+			window.clearInterval(intervalId);
+		};
+	}, []);
 
 	React.useEffect(() => {
 		api
@@ -182,10 +204,15 @@ function App() {
 					onCloseSuggestions={closeSuggestions}
 					completionError={completionError}
 					currentPartial={currentPartial}
+					oauthStatus={oauthStatus}
 				/>
 			) : (
 				<div className="workspace" style={{ height: "100%" }}>
-					<Chat projectPath={projectPath} onCloseProject={closeProject} />
+					<Chat
+						projectPath={projectPath}
+						onCloseProject={closeProject}
+						oauthStatus={oauthStatus}
+					/>
 				</div>
 			)}
 

frontend/src/api/client.ts

@@ -21,6 +21,19 @@ export type WsRequest =
 			config: ProviderConfig;
 	  };
 
+export interface WizardStepInfo {
+	step: string;
+	label: string;
+	status: string;
+	content?: string;
+}
+
+export interface WizardStateData {
+	steps: WizardStepInfo[];
+	current_step_index: number;
+	completed: boolean;
+}
+
 export interface AgentAssignment {
 	agent_name: string;
 	model: string | null;
@@ -80,6 +93,13 @@ export type WsResponse =
 	| { type: "pong" }
 	/** Sent on connect when the project still needs onboarding (specs are placeholders). */
 	| { type: "onboarding_status"; needs_onboarding: boolean }
+	/** Sent on connect when a setup wizard is active. */
+	| {
+			type: "wizard_state";
+			steps: WizardStepInfo[];
+			current_step_index: number;
+			completed: boolean;
+	  }
 	/** Streaming thinking token from an extended-thinking block, separate from regular text. */
 	| { type: "thinking_token"; content: string }
 	/** Streaming token from a /btw side question response. */
@@ -185,6 +205,13 @@ export interface CommandOutput {
 	exit_code: number;
 }
 
+export interface OAuthStatus {
+	authenticated: boolean;
+	expired: boolean;
+	expires_at: number;
+	has_refresh_token: boolean;
+}
+
 declare const __STORKIT_PORT__: string;
 
 const DEFAULT_API_BASE = "/api";
@@ -382,6 +409,10 @@ export const api = {
 	deleteStory(storyId: string) {
 		return callMcpTool("delete_story", { story_id: storyId });
 	},
+	/** Fetch OAuth status from the server. */
+	getOAuthStatus() {
+		return requestJson<OAuthStatus>("/oauth/status", {}, "");
+	},
 	/** Execute a bot slash command without LLM invocation. Returns markdown response text. */
 	botCommand(command: string, args: string, baseUrl?: string) {
 		return requestJson<{ response: string }>(
@@ -438,6 +469,7 @@ export class ChatWebSocket {
 	private onAgentConfigChanged?: () => void;
 	private onAgentStateChanged?: () => void;
 	private onOnboardingStatus?: (needsOnboarding: boolean) => void;
+	private onWizardState?: (state: WizardStateData) => void;
 	private onSideQuestionToken?: (content: string) => void;
 	private onSideQuestionDone?: (response: string) => void;
 	private onLogEntry?: (
@@ -528,6 +560,12 @@ export class ChatWebSocket {
 				if (data.type === "agent_state_changed") this.onAgentStateChanged?.();
 				if (data.type === "onboarding_status")
 					this.onOnboardingStatus?.(data.needs_onboarding);
+				if (data.type === "wizard_state")
+					this.onWizardState?.({
+						steps: data.steps,
+						current_step_index: data.current_step_index,
+						completed: data.completed,
+					});
 				if (data.type === "side_question_token")
 					this.onSideQuestionToken?.(data.content);
 				if (data.type === "side_question_done")
@@ -587,6 +625,7 @@ export class ChatWebSocket {
 			onAgentConfigChanged?: () => void;
 			onAgentStateChanged?: () => void;
 			onOnboardingStatus?: (needsOnboarding: boolean) => void;
+			onWizardState?: (state: WizardStateData) => void;
 			onSideQuestionToken?: (content: string) => void;
 			onSideQuestionDone?: (response: string) => void;
 			onLogEntry?: (timestamp: string, level: string, message: string) => void;
@@ -606,6 +645,7 @@ export class ChatWebSocket {
 		this.onAgentConfigChanged = handlers.onAgentConfigChanged;
 		this.onAgentStateChanged = handlers.onAgentStateChanged;
 		this.onOnboardingStatus = handlers.onOnboardingStatus;
+		this.onWizardState = handlers.onWizardState;
 		this.onSideQuestionToken = handlers.onSideQuestionToken;
 		this.onSideQuestionDone = handlers.onSideQuestionDone;
 		this.onLogEntry = handlers.onLogEntry;

frontend/src/components/Chat.test.tsx

@@ -1481,6 +1481,10 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/status" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
@@ -1551,6 +1555,10 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/git" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
@@ -1569,6 +1577,10 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/cost" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
@@ -1595,6 +1607,10 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/reset" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
@@ -1626,7 +1642,8 @@ describe("Slash command handling (Story 374)", () => {
 		expect(mockedApi.botCommand).not.toHaveBeenCalled();
 	});
 
-	it("AC: /help shows help overlay", async () => {
+	it("AC: /help calls botCommand and displays response", async () => {
+		mockedApi.botCommand.mockResolvedValue({ response: "Available commands: status, help, ..." });
 		render(<Chat projectPath="/tmp/project" onCloseProject={vi.fn()} />);
 		await waitFor(() => expect(capturedWsHandlers).not.toBeNull());
 
@@ -1634,13 +1651,22 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/help" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
 
-		expect(await screen.findByTestId("help-overlay")).toBeInTheDocument();
+		await waitFor(() => {
+			expect(mockedApi.botCommand).toHaveBeenCalledWith(
+				"help",
+				"",
+				undefined,
+			);
+		});
 		expect(lastSendChatArgs).toBeNull();
-		expect(mockedApi.botCommand).not.toHaveBeenCalled();
 	});
 
 	it("AC: botCommand API error shows error message in chat", async () => {
@@ -1652,6 +1678,10 @@ describe("Slash command handling (Story 374)", () => {
 		await act(async () => {
 			fireEvent.change(input, { target: { value: "/git" } });
 		});
+		// First Enter selects the command from the picker; second Enter submits it
+		await act(async () => {
+			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
+		});
 		await act(async () => {
 			fireEvent.keyDown(input, { key: "Enter", shiftKey: false });
 		});
@@ -1661,3 +1691,40 @@ describe("Slash command handling (Story 374)", () => {
 		).toBeInTheDocument();
 	});
 });
+
+describe("Bug 450: WebSocket error messages displayed in chat", () => {
+	beforeEach(() => {
+		capturedWsHandlers = null;
+		setupMocks();
+	});
+
+	it("AC1: WebSocket error message is shown in chat as an assistant message", async () => {
+		render(<Chat projectPath="/tmp/project" onCloseProject={vi.fn()} />);
+
+		await waitFor(() => expect(capturedWsHandlers).not.toBeNull());
+
+		act(() => {
+			capturedWsHandlers?.onError("Something went wrong on the server.");
+		});
+
+		expect(
+			await screen.findByText("Something went wrong on the server."),
+		).toBeInTheDocument();
+	});
+
+	it("AC2: OAuth login URL in WebSocket error is rendered as a clickable link", async () => {
+		render(<Chat projectPath="/tmp/project" onCloseProject={vi.fn()} />);
+
+		await waitFor(() => expect(capturedWsHandlers).not.toBeNull());
+
+		act(() => {
+			capturedWsHandlers?.onError(
+				"OAuth login required. Please visit: https://example.com/oauth/login",
+			);
+		});
+
+		const link = await screen.findByRole("link", { name: /https:\/\/example\.com\/oauth\/login/ });
+		expect(link).toBeInTheDocument();
+		expect(link).toHaveAttribute("href", "https://example.com/oauth/login");
+	});
+});

frontend/src/components/Chat.tsx

@@ -4,7 +4,12 @@ import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 import type { AgentConfigInfo } from "../api/agents";
 import { agentsApi } from "../api/agents";
-import type { AnthropicModelInfo, PipelineState } from "../api/client";
+import type {
+	AnthropicModelInfo,
+	OAuthStatus,
+	PipelineState,
+	WizardStateData,
+} from "../api/client";
 import { api, ChatWebSocket } from "../api/client";
 import { useChatHistory } from "../hooks/useChatHistory";
 import type { Message, ProviderConfig } from "../types";
@@ -17,6 +22,7 @@ import { LozengeFlyProvider } from "./LozengeFlyContext";
 import { MessageItem } from "./MessageItem";
 import type { LogEntry } from "./ServerLogsPanel";
 import { ServerLogsPanel } from "./ServerLogsPanel";
+import SetupWizard from "./SetupWizard";
 import { SideQuestionOverlay } from "./SideQuestionOverlay";
 import { StagePanel } from "./StagePanel";
 import { WorkItemDetailPanel } from "./WorkItemDetailPanel";
@@ -159,9 +165,14 @@ const getContextWindowSize = (
 interface ChatProps {
 	projectPath: string;
 	onCloseProject: () => void;
+	oauthStatus?: OAuthStatus | null;
 }
 
-export function Chat({ projectPath, onCloseProject }: ChatProps) {
+export function Chat({
+	projectPath,
+	onCloseProject,
+	oauthStatus = null,
+}: ChatProps) {
 	const { messages, setMessages, clearMessages } = useChatHistory(projectPath);
 	const [loading, setLoading] = useState(false);
 	const [model, setModel] = useState("claude-code-pty");
@@ -217,6 +228,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 		new Map(),
 	);
 	const [needsOnboarding, setNeedsOnboarding] = useState(false);
+	const [wizardState, setWizardState] = useState<WizardStateData | null>(null);
 	const onboardingTriggeredRef = useRef(false);
 	const [selectedWorkItemId, setSelectedWorkItemId] = useState<string | null>(
 		null,
@@ -401,6 +413,14 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 				console.error("WebSocket error:", message);
 				setLoading(false);
 				setActivityStatus(null);
+				const markdownMessage = message.replace(
+					/(https?:\/\/[^\s]+)/g,
+					"[$1]($1)",
+				);
+				setMessages((prev) => [
+					...prev,
+					{ role: "assistant", content: markdownMessage },
+				]);
 				if (queuedMessagesRef.current.length > 0) {
 					const batch = queuedMessagesRef.current.map((item) => item.text);
 					queuedMessagesRef.current = [];
@@ -466,6 +486,9 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 			onOnboardingStatus: (onboarding: boolean) => {
 				setNeedsOnboarding(onboarding);
 			},
+			onWizardState: (state: WizardStateData) => {
+				setWizardState(state);
+			},
 			onSideQuestionToken: (content) => {
 				setSideQuestion((prev) =>
 					prev ? { ...prev, response: prev.response + content } : prev,
@@ -606,12 +629,6 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 	const sendMessage = async (messageText: string) => {
 		if (!messageText.trim()) return;
 
-		// /help — show available slash commands overlay
-		if (/^\/help\s*$/i.test(messageText)) {
-			setShowHelp(true);
-			return;
-		}
-
 		// /reset — clear session and message history without LLM
 		if (/^\/reset\s*$/i.test(messageText)) {
 			setMessages([]);
@@ -648,6 +665,14 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 					"overview",
 					"rebuild",
 					"loc",
+					"help",
+					"ambient",
+					"htop",
+					"rmtree",
+					"timer",
+					"unblock",
+					"unreleased",
+					"setup",
 				]);
 
 				if (knownCommands.has(cmd)) {
@@ -931,6 +956,7 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 				enableTools={enableTools}
 				onToggleTools={setEnableTools}
 				wsConnected={wsConnected}
+				oauthStatus={oauthStatus}
 			/>
 
 			{/* Two-column content area */}
@@ -978,65 +1004,79 @@ export function Chat({ projectPath, onCloseProject }: ChatProps) {
 								gap: "24px",
 							}}
 						>
-							{needsOnboarding && messages.length === 0 && !loading && (
-								<div
-									data-testid="onboarding-welcome"
-									style={{
-										padding: "24px",
-										borderRadius: "12px",
-										background: "#1c2a1c",
-										border: "1px solid #2d4a2d",
-										marginBottom: "8px",
-									}}
-								>
-									<h3
+							{wizardState &&
+								!wizardState.completed &&
+								messages.length === 0 &&
+								!loading && (
+									<SetupWizard
+										wizardState={wizardState}
+										onWizardUpdate={setWizardState}
+										sendMessage={sendMessage}
+									/>
+								)}
+							{needsOnboarding &&
+								!wizardState &&
+								messages.length === 0 &&
+								!loading && (
+									<div
+										data-testid="onboarding-welcome"
 										style={{
-											margin: "0 0 8px 0",
-											color: "#a0d4a0",
-											fontSize: "1.1rem",
+											padding: "24px",
+											borderRadius: "12px",
+											background: "#1c2a1c",
+											border: "1px solid #2d4a2d",
+											marginBottom: "8px",
 										}}
 									>
-										Welcome to Storkit
-									</h3>
-									<p
-										style={{
-											margin: "0 0 16px 0",
-											color: "#ccc",
-											lineHeight: 1.5,
-										}}
-									>
-										This project needs to be set up before you can start writing
-										stories. The agent will guide you through configuring your
-										project goals and tech stack.
-									</p>
-									<button
-										type="button"
-										data-testid="onboarding-start-button"
-										onClick={() => {
-											if (onboardingTriggeredRef.current) return;
-											onboardingTriggeredRef.current = true;
-											setNeedsOnboarding(false);
-											sendMessage(
-												"I just created a new project. Help me set it up.",
-											);
-										}}
-										style={{
-											padding: "10px 20px",
-											borderRadius: "8px",
-											border: "none",
-											backgroundColor: "#a0d4a0",
-											color: "#1a1a1a",
-											cursor: "pointer",
-											fontSize: "0.95rem",
-											fontWeight: 600,
-										}}
-									>
-										Start Project Setup
-									</button>
-								</div>
-							)}
+										<h3
+											style={{
+												margin: "0 0 8px 0",
+												color: "#a0d4a0",
+												fontSize: "1.1rem",
+											}}
+										>
+											Welcome to Storkit
+										</h3>
+										<p
+											style={{
+												margin: "0 0 16px 0",
+												color: "#ccc",
+												lineHeight: 1.5,
+											}}
+										>
+											This project needs to be set up before you can start
+											writing stories. The agent will guide you through
+											configuring your project goals and tech stack.
+										</p>
+										<button
+											type="button"
+											data-testid="onboarding-start-button"
+											onClick={() => {
+												if (onboardingTriggeredRef.current) return;
+												onboardingTriggeredRef.current = true;
+												setNeedsOnboarding(false);
+												sendMessage(
+													"I just created a new project. Help me set it up.",
+												);
+											}}
+											style={{
+												padding: "10px 20px",
+												borderRadius: "8px",
+												border: "none",
+												backgroundColor: "#a0d4a0",
+												color: "#1a1a1a",
+												cursor: "pointer",
+												fontSize: "0.95rem",
+												fontWeight: 600,
+											}}
+										>
+											Start Project Setup
+										</button>
+									</div>
+								)}
 							{messages.map((msg: Message, idx: number) => (
 								<MessageItem
+									// biome-ignore lint/suspicious/noArrayIndexKey: Message has no stable ID
 									key={`msg-${idx}-${msg.role}-${msg.content.substring(0, 20)}`}
 									msg={msg}
 								/>

frontend/src/components/ChatHeader.tsx

@@ -1,4 +1,5 @@
 import * as React from "react";
+import type { OAuthStatus } from "../api/client";
 import { api } from "../api/client";
 
 const { useState, useEffect } = React;
@@ -32,6 +33,7 @@ interface ChatHeaderProps {
 	enableTools: boolean;
 	onToggleTools: (enabled: boolean) => void;
 	wsConnected: boolean;
+	oauthStatus?: OAuthStatus | null;
 }
 
 const getContextEmoji = (percentage: number): string => {
@@ -55,6 +57,7 @@ export function ChatHeader({
 	enableTools,
 	onToggleTools,
 	wsConnected,
+	oauthStatus = null,
 }: ChatHeaderProps) {
 	const hasModelOptions = availableModels.length > 0 || claudeModels.length > 0;
 	const [showConfirm, setShowConfirm] = useState(false);
@@ -340,6 +343,63 @@ export function ChatHeader({
 				</div>
 
 				<div style={{ display: "flex", alignItems: "center", gap: "16px" }}>
+					{oauthStatus !== null &&
+						(!oauthStatus.authenticated || oauthStatus.expired) && (
+							<button
+								type="button"
+								title="Authenticate with Claude via OAuth"
+								onClick={() => {
+									window.open(
+										"/oauth/authorize",
+										"_blank",
+										"noopener,noreferrer",
+									);
+								}}
+								style={{
+									padding: "6px 12px",
+									borderRadius: "99px",
+									border: "none",
+									fontSize: "0.85em",
+									backgroundColor: "#1a3a5c",
+									color: "#7eb8f7",
+									cursor: "pointer",
+									outline: "none",
+									transition: "all 0.2s",
+									whiteSpace: "nowrap",
+								}}
+								onMouseOver={(e) => {
+									e.currentTarget.style.backgroundColor = "#234d7a";
+									e.currentTarget.style.color = "#a8d4ff";
+								}}
+								onMouseOut={(e) => {
+									e.currentTarget.style.backgroundColor = "#1a3a5c";
+									e.currentTarget.style.color = "#7eb8f7";
+								}}
+								onFocus={(e) => {
+									e.currentTarget.style.backgroundColor = "#234d7a";
+									e.currentTarget.style.color = "#a8d4ff";
+								}}
+								onBlur={(e) => {
+									e.currentTarget.style.backgroundColor = "#1a3a5c";
+									e.currentTarget.style.color = "#7eb8f7";
+								}}
+							>
+								{oauthStatus.expired ? "Re-authenticate" : "Login with Claude"}
+							</button>
+						)}
+					{oauthStatus?.authenticated && !oauthStatus.expired && (
+						<span
+							title="Authenticated with Claude via OAuth"
+							style={{
+								fontSize: "0.8em",
+								color: "#4caf50",
+								whiteSpace: "nowrap",
+							}}
+						>
+							✓ Claude
+						</span>
+					)}
+
 					<div
 						style={{
 							fontSize: "0.75em",

frontend/src/components/ChatInput.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { api } from "../api/client";
+import { SLASH_COMMANDS, type SlashCommand } from "../slashCommands";
 
 const {
 	forwardRef,
@@ -113,6 +114,83 @@ function FilePickerOverlay({
 	);
 }
 
+interface SlashCommandPickerOverlayProps {
+	query: string;
+	selectedIndex: number;
+	onSelect: (cmd: SlashCommand) => void;
+}
+
+function SlashCommandPickerOverlay({
+	query,
+	selectedIndex,
+	onSelect,
+}: SlashCommandPickerOverlayProps) {
+	const filtered = SLASH_COMMANDS.filter((cmd) =>
+		fuzzyMatch(cmd.name, query),
+	).sort((a, b) => fuzzyScore(a.name, query) - fuzzyScore(b.name, query));
+
+	if (filtered.length === 0) return null;
+
+	return (
+		<div
+			data-testid="slash-command-picker"
+			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: "300px",
+				overflowY: "auto",
+			}}
+		>
+			{filtered.map((cmd, idx) => (
+				<button
+					key={cmd.name}
+					type="button"
+					data-testid={`slash-command-item-${idx}`}
+					onClick={() => onSelect(cmd)}
+					style={{
+						display: "flex",
+						flexDirection: "column",
+						width: "100%",
+						textAlign: "left",
+						padding: "10px 14px",
+						background: idx === selectedIndex ? "#2d4a6e" : "transparent",
+						border: "none",
+						cursor: "pointer",
+						gap: "2px",
+					}}
+				>
+					<code
+						style={{
+							fontSize: "0.88rem",
+							color: idx === selectedIndex ? "#ececec" : "#e0e0e0",
+							fontFamily: "monospace",
+						}}
+					>
+						{cmd.name}
+					</code>
+					<span
+						style={{
+							fontSize: "0.78rem",
+							color: idx === selectedIndex ? "#b0c0d0" : "#888",
+						}}
+					>
+						{cmd.description}
+					</span>
+				</button>
+			))}
+		</div>
+	);
+}
+
 export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 	function ChatInput(
 		{ loading, queuedMessages, onSubmit, onCancel, onRemoveQueuedMessage },
@@ -127,6 +205,10 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 		const [pickerSelectedIndex, setPickerSelectedIndex] = useState(0);
 		const [pickerAtStart, setPickerAtStart] = useState(0);
 
+		// Slash command picker state
+		const [slashQuery, setSlashQuery] = useState<string | null>(null);
+		const [slashSelectedIndex, setSlashSelectedIndex] = useState(0);
+
 		useImperativeHandle(ref, () => ({
 			appendToInput(text: string) {
 				setInput((prev) => (prev ? `${prev}\n${text}` : text));
@@ -153,6 +235,31 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 			setPickerSelectedIndex(0);
 		}, []);
 
+		// Compute filtered slash commands for current query
+		const filteredCommands =
+			slashQuery !== null
+				? SLASH_COMMANDS.filter((cmd) => fuzzyMatch(cmd.name, slashQuery)).sort(
+						(a, b) =>
+							fuzzyScore(a.name, slashQuery) - fuzzyScore(b.name, slashQuery),
+					)
+				: [];
+
+		const dismissSlashPicker = useCallback(() => {
+			setSlashQuery(null);
+			setSlashSelectedIndex(0);
+		}, []);
+
+		const selectCommand = useCallback(
+			(cmd: SlashCommand) => {
+				// Extract base command (first word, e.g. "/assign" from "/assign <number> <model>")
+				const baseCommand = cmd.name.split(" ")[0];
+				setInput(`${baseCommand} `);
+				dismissSlashPicker();
+				setTimeout(() => inputRef.current?.focus(), 0);
+			},
+			[dismissSlashPicker],
+		);
+
 		const selectFile = useCallback(
 			(file: string) => {
 				// Replace the @query portion with @file
@@ -173,11 +280,20 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 				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@]*)$/);
 
+				// Slash command picker: triggered when input starts with / and no space yet
+				const slashMatch = textUpToCursor.match(/^\/(\S*)$/);
+				if (slashMatch) {
+					setSlashQuery(slashMatch[1]);
+					setSlashSelectedIndex(0);
+					if (pickerQuery !== null) dismissPicker();
+					return;
+				}
+				if (slashQuery !== null) dismissSlashPicker();
+
+				// File picker: triggered by @ at start or after whitespace
+				const atMatch = textUpToCursor.match(/(^|[\s\n])@([^\s@]*)$/);
 				if (atMatch) {
 					const query = atMatch[2];
 					const atPos = textUpToCursor.lastIndexOf("@");
@@ -196,11 +312,50 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 					if (pickerQuery !== null) dismissPicker();
 				}
 			},
-			[projectFiles.length, pickerQuery, dismissPicker],
+			[
+				projectFiles.length,
+				pickerQuery,
+				dismissPicker,
+				slashQuery,
+				dismissSlashPicker,
+			],
 		);
 
 		const handleKeyDown = useCallback(
 			(e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+				// Slash command picker navigation
+				if (slashQuery !== null && filteredCommands.length > 0) {
+					if (e.key === "ArrowDown") {
+						e.preventDefault();
+						setSlashSelectedIndex((i) =>
+							Math.min(i + 1, filteredCommands.length - 1),
+						);
+						return;
+					}
+					if (e.key === "ArrowUp") {
+						e.preventDefault();
+						setSlashSelectedIndex((i) => Math.max(i - 1, 0));
+						return;
+					}
+					if (e.key === "Tab" || e.key === "Enter") {
+						e.preventDefault();
+						selectCommand(
+							filteredCommands[slashSelectedIndex] ?? filteredCommands[0],
+						);
+						return;
+					}
+					if (e.key === "Escape") {
+						e.preventDefault();
+						dismissSlashPicker();
+						return;
+					}
+				} else if (e.key === "Escape" && slashQuery !== null) {
+					e.preventDefault();
+					dismissSlashPicker();
+					return;
+				}
+
+				// File picker navigation
 				if (pickerQuery !== null && filteredFiles.length > 0) {
 					if (e.key === "ArrowDown") {
 						e.preventDefault();
@@ -236,6 +391,11 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 				}
 			},
 			[
+				slashQuery,
+				filteredCommands,
+				slashSelectedIndex,
+				selectCommand,
+				dismissSlashPicker,
 				pickerQuery,
 				filteredFiles,
 				pickerSelectedIndex,
@@ -249,6 +409,7 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 			onSubmit(input);
 			setInput("");
 			dismissPicker();
+			dismissSlashPicker();
 		};
 
 		return (
@@ -357,6 +518,13 @@ export const ChatInput = forwardRef<ChatInputHandle, ChatInputProps>(
 							position: "relative",
 						}}
 					>
+						{slashQuery !== null && (
+							<SlashCommandPickerOverlay
+								query={slashQuery}
+								selectedIndex={slashSelectedIndex}
+								onSelect={selectCommand}
+							/>
+						)}
 						{pickerQuery !== null && (
 							<FilePickerOverlay
 								query={pickerQuery}

frontend/src/components/ChatInputSlashCommand.test.tsx

@@ -0,0 +1,240 @@
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ChatInput } from "./ChatInput";
+
+vi.mock("../api/client", () => ({
+	api: {
+		listProjectFiles: vi.fn().mockResolvedValue([]),
+	},
+}));
+
+const defaultProps = {
+	loading: false,
+	queuedMessages: [],
+	onSubmit: vi.fn(),
+	onCancel: vi.fn(),
+	onRemoveQueuedMessage: vi.fn(),
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe("Slash command picker overlay (Story 438 AC1)", () => {
+	it("shows slash command picker when / is typed at position 0", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		expect(screen.getByTestId("slash-command-picker")).toBeInTheDocument();
+	});
+
+	it("does not show slash command picker for plain text", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "hello" } });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+	});
+
+	it("does not show slash command picker when / is not at position 0", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "hello /world" } });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+	});
+});
+
+describe("Slash command list (Story 438 AC2)", () => {
+	it("lists slash commands with name and description", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		expect(screen.getByTestId("slash-command-picker")).toBeInTheDocument();
+		// First command should be /help
+		expect(screen.getByTestId("slash-command-item-0")).toBeInTheDocument();
+		expect(screen.getByTestId("slash-command-item-0")).toHaveTextContent(
+			"/help",
+		);
+	});
+});
+
+describe("Slash command fuzzy filter (Story 438 AC3)", () => {
+	it("filters commands when typing after /", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/hel" } });
+		});
+
+		expect(screen.getByTestId("slash-command-picker")).toBeInTheDocument();
+		// /help should match "hel"
+		expect(screen.getByTestId("slash-command-item-0")).toHaveTextContent(
+			"/help",
+		);
+		// /rebuild should not be visible (no match for "hel")
+		const items = screen.queryAllByTestId(/^slash-command-item-/);
+		const texts = items.map((el) => el.textContent ?? "");
+		expect(texts.some((t) => t.includes("/rebuild"))).toBe(false);
+	});
+
+	it("shows no picker when query matches nothing", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/zzzzz" } });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+	});
+});
+
+describe("Slash command keyboard navigation (Story 438 AC4)", () => {
+	it("ArrowDown navigates to next item", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		const item0 = screen.getByTestId("slash-command-item-0");
+		expect(item0).toHaveStyle({ background: "#2d4a6e" });
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "ArrowDown" });
+		});
+
+		const item1 = screen.getByTestId("slash-command-item-1");
+		expect(item1).toHaveStyle({ background: "#2d4a6e" });
+	});
+
+	it("ArrowUp stays at 0 when already at top", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "ArrowUp" });
+		});
+
+		const item0 = screen.getByTestId("slash-command-item-0");
+		expect(item0).toHaveStyle({ background: "#2d4a6e" });
+	});
+
+	it("Enter selects the highlighted command and inserts it", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/hel" } });
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Enter" });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+		expect((textarea as HTMLTextAreaElement).value).toBe("/help ");
+	});
+
+	it("Tab selects the highlighted command and inserts it", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/hel" } });
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Tab" });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+		expect((textarea as HTMLTextAreaElement).value).toBe("/help ");
+	});
+
+	it("Escape dismisses the picker", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		expect(screen.getByTestId("slash-command-picker")).toBeInTheDocument();
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Escape" });
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+	});
+});
+
+describe("Slash command selection inserts with trailing space (Story 438 AC5)", () => {
+	it("clicking a command inserts /<command> with trailing space", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/" } });
+		});
+
+		await act(async () => {
+			fireEvent.click(screen.getByTestId("slash-command-item-0"));
+		});
+
+		expect(
+			screen.queryByTestId("slash-command-picker"),
+		).not.toBeInTheDocument();
+		const val = (textarea as HTMLTextAreaElement).value;
+		expect(val).toMatch(/^\/\w+ $/);
+	});
+
+	it("selection inserts only the base command (no argument placeholders)", async () => {
+		render(<ChatInput {...defaultProps} />);
+		const textarea = screen.getByPlaceholderText("Send a message...");
+
+		await act(async () => {
+			fireEvent.change(textarea, { target: { value: "/ass" } });
+		});
+
+		await act(async () => {
+			fireEvent.keyDown(textarea, { key: "Enter" });
+		});
+
+		expect((textarea as HTMLTextAreaElement).value).toBe("/assign ");
+	});
+});

frontend/src/components/HelpOverlay.tsx

@@ -1,75 +1,8 @@
 import * as React from "react";
+import { SLASH_COMMANDS } from "../slashCommands";
 
 const { useEffect, useRef } = React;
 
-interface SlashCommand {
-	name: string;
-	description: string;
-}
-
-const SLASH_COMMANDS: SlashCommand[] = [
-	{
-		name: "/help",
-		description: "Show this list of available slash commands.",
-	},
-	{
-		name: "/status",
-		description:
-			"Show pipeline status and agent availability. `/status <number>` shows a story triage dump.",
-	},
-	{
-		name: "/assign <number> <model>",
-		description: "Pre-assign a model to a story (e.g. `/assign 42 opus`).",
-	},
-	{
-		name: "/start <number>",
-		description:
-			"Start a coder on a story. Optionally specify a model: `/start <number> opus`.",
-	},
-	{
-		name: "/show <number>",
-		description: "Display the full text of a work item.",
-	},
-	{
-		name: "/move <number> <stage>",
-		description:
-			"Move a work item to a pipeline stage (backlog, current, qa, merge, done).",
-	},
-	{
-		name: "/delete <number>",
-		description:
-			"Remove a work item from the pipeline and stop any running agent.",
-	},
-	{
-		name: "/cost",
-		description:
-			"Show token spend: 24h total, top stories, breakdown by agent type, and all-time total.",
-	},
-	{
-		name: "/git",
-		description:
-			"Show git status: branch, uncommitted changes, and ahead/behind remote.",
-	},
-	{
-		name: "/overview <number>",
-		description: "Show the implementation summary for a merged story.",
-	},
-	{
-		name: "/rebuild",
-		description: "Rebuild the server binary and restart.",
-	},
-	{
-		name: "/reset",
-		description:
-			"Clear the current Claude Code session and start fresh (messages and session ID are cleared locally).",
-	},
-	{
-		name: "/btw <question>",
-		description:
-			"Ask a side question using the current conversation as context. The question and answer are not added to the conversation history.",
-	},
-];
-
 interface HelpOverlayProps {
 	onDismiss: () => void;
 }

frontend/src/components/MessageItem.tsx

@@ -136,6 +136,7 @@ function MessageItemInner({ msg }: MessageItemProps) {
 
 							return (
 								<div
+									// biome-ignore lint/suspicious/noArrayIndexKey: ToolCall has no stable ID
 									key={`tool-${i}-${tc.function.name}`}
 									style={{
 										display: "flex",

frontend/src/components/ServerLogsPanel.tsx

@@ -202,6 +202,7 @@ export function ServerLogsPanel({ logs }: ServerLogsPanelProps) {
 						) : (
 							filteredLogs.map((entry, idx) => (
 								<div
+									// biome-ignore lint/suspicious/noArrayIndexKey: log entries have no stable ID
 									key={`${entry.timestamp}-${idx}`}
 									style={{
 										display: "flex",

frontend/src/components/SetupWizard.tsx

@@ -0,0 +1,354 @@
+import { useCallback, useState } from "react";
+import type { WizardStateData, WizardStepInfo } from "../api/client";
+
+const API_BASE = "/api";
+
+interface SetupWizardProps {
+	wizardState: WizardStateData;
+	onWizardUpdate: (state: WizardStateData) => void;
+	sendMessage: (message: string) => void;
+}
+
+/** Style constants for the wizard UI. */
+const STEP_BG_PENDING = "#1a1f2e";
+const STEP_BG_ACTIVE = "#1c2a1c";
+const STEP_BG_DONE = "#1a2a1a";
+const STEP_BORDER_PENDING = "#2a2f3e";
+const STEP_BORDER_ACTIVE = "#2d4a2d";
+const STEP_BORDER_DONE = "#2d4a2d";
+const COLOR_LABEL = "#ccc";
+const COLOR_LABEL_DONE = "#a0d4a0";
+const COLOR_ACCENT = "#a0d4a0";
+
+function statusIcon(status: string): string {
+	switch (status) {
+		case "confirmed":
+			return "\u2713";
+		case "skipped":
+			return "\u2013";
+		case "generating":
+			return "\u2026";
+		case "awaiting_confirmation":
+			return "?";
+		default:
+			return "\u00B7";
+	}
+}
+
+function stepBackground(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BG_DONE;
+	if (isActive) return STEP_BG_ACTIVE;
+	return STEP_BG_PENDING;
+}
+
+function stepBorder(status: string, isActive: boolean): string {
+	if (status === "confirmed" || status === "skipped") return STEP_BORDER_DONE;
+	if (isActive) return STEP_BORDER_ACTIVE;
+	return STEP_BORDER_PENDING;
+}
+
+/** Messages sent to the chat to trigger agent generation for each step. */
+const STEP_PROMPTS: Record<string, string> = {
+	context:
+		"Read the codebase and generate .storkit/specs/00_CONTEXT.md with a project context spec. Include High-Level Goal, Core Features, Domain Definition, and Glossary sections. Then call the wizard API to store the content: PUT /api/wizard/step/context/content",
+	stack:
+		"Read the tech stack and generate .storkit/specs/tech/STACK.md with a tech stack spec. Include Core Stack, Coding Standards, Quality Gates, and Libraries sections. Then call the wizard API to store the content: PUT /api/wizard/step/stack/content",
+	test_script:
+		"Read the project structure and create script/test — a bash script that runs the project's actual test suite. Then call the wizard API: PUT /api/wizard/step/test_script/content",
+	release_script:
+		"Read the project's deployment setup and create script/release tailored to the project. Then call the wizard API: PUT /api/wizard/step/release_script/content",
+	test_coverage:
+		"If the stack supports coverage reporting, create script/test_coverage. Then call the wizard API: PUT /api/wizard/step/test_coverage/content",
+};
+
+async function apiPost(path: string): Promise<WizardStateData | null> {
+	try {
+		const resp = await fetch(`${API_BASE}${path}`, { method: "POST" });
+		if (!resp.ok) return null;
+		return (await resp.json()) as WizardStateData;
+	} catch {
+		return null;
+	}
+}
+
+function StepCard({
+	step,
+	isActive,
+	onGenerate,
+	onConfirm,
+	onSkip,
+}: {
+	step: WizardStepInfo;
+	isActive: boolean;
+	onGenerate: () => void;
+	onConfirm: () => void;
+	onSkip: () => void;
+}) {
+	const isDone = step.status === "confirmed" || step.status === "skipped";
+
+	return (
+		<div
+			data-testid={`wizard-step-${step.step}`}
+			style={{
+				padding: "16px",
+				borderRadius: "8px",
+				background: stepBackground(step.status, isActive),
+				border: `1px solid ${stepBorder(step.status, isActive)}`,
+				opacity: !isActive && !isDone ? 0.5 : 1,
+				transition: "all 0.2s ease",
+			}}
+		>
+			<div
+				style={{
+					display: "flex",
+					alignItems: "center",
+					gap: "12px",
+				}}
+			>
+				<span
+					style={{
+						width: "24px",
+						height: "24px",
+						borderRadius: "50%",
+						display: "flex",
+						alignItems: "center",
+						justifyContent: "center",
+						fontSize: "14px",
+						fontWeight: 600,
+						background: isDone ? COLOR_ACCENT : "transparent",
+						border: isDone ? "none" : `1px solid ${COLOR_LABEL}`,
+						color: isDone ? "#1a1a1a" : COLOR_LABEL,
+					}}
+				>
+					{statusIcon(step.status)}
+				</span>
+				<span
+					style={{
+						flex: 1,
+						color: isDone ? COLOR_LABEL_DONE : COLOR_LABEL,
+						fontWeight: isActive ? 600 : 400,
+					}}
+				>
+					{step.label}
+				</span>
+				{isActive && step.status === "pending" && (
+					<button
+						type="button"
+						data-testid={`wizard-generate-${step.step}`}
+						onClick={onGenerate}
+						style={{
+							padding: "6px 14px",
+							borderRadius: "6px",
+							border: "none",
+							backgroundColor: COLOR_ACCENT,
+							color: "#1a1a1a",
+							cursor: "pointer",
+							fontSize: "0.85rem",
+							fontWeight: 600,
+						}}
+					>
+						Generate
+					</button>
+				)}
+				{isActive && step.status === "generating" && (
+					<span style={{ color: "#aaa", fontSize: "0.85rem" }}>
+						Generating...
+					</span>
+				)}
+			</div>
+
+			{step.content && step.status === "awaiting_confirmation" && (
+				<div style={{ marginTop: "12px" }}>
+					<pre
+						data-testid={`wizard-preview-${step.step}`}
+						style={{
+							background: "#111",
+							padding: "12px",
+							borderRadius: "6px",
+							fontSize: "0.8rem",
+							color: "#ddd",
+							whiteSpace: "pre-wrap",
+							maxHeight: "200px",
+							overflow: "auto",
+							margin: "0 0 12px 0",
+						}}
+					>
+						{step.content}
+					</pre>
+					<div style={{ display: "flex", gap: "8px" }}>
+						<button
+							type="button"
+							data-testid={`wizard-confirm-${step.step}`}
+							onClick={onConfirm}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "none",
+								backgroundColor: COLOR_ACCENT,
+								color: "#1a1a1a",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+								fontWeight: 600,
+							}}
+						>
+							Confirm
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-revise-${step.step}`}
+							onClick={onGenerate}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#ccc",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Revise
+						</button>
+						<button
+							type="button"
+							data-testid={`wizard-skip-${step.step}`}
+							onClick={onSkip}
+							style={{
+								padding: "6px 14px",
+								borderRadius: "6px",
+								border: "1px solid #555",
+								backgroundColor: "transparent",
+								color: "#888",
+								cursor: "pointer",
+								fontSize: "0.85rem",
+							}}
+						>
+							Skip
+						</button>
+					</div>
+				</div>
+			)}
+
+			{isActive && step.status === "pending" && !step.content && (
+				<div style={{ marginTop: "8px", display: "flex", gap: "8px" }}>
+					<button
+						type="button"
+						data-testid={`wizard-skip-${step.step}`}
+						onClick={onSkip}
+						style={{
+							padding: "4px 10px",
+							borderRadius: "6px",
+							border: "1px solid #444",
+							backgroundColor: "transparent",
+							color: "#888",
+							cursor: "pointer",
+							fontSize: "0.8rem",
+						}}
+					>
+						Skip this step
+					</button>
+				</div>
+			)}
+		</div>
+	);
+}
+
+export default function SetupWizard({
+	wizardState,
+	onWizardUpdate,
+	sendMessage,
+}: SetupWizardProps) {
+	const [, setRefreshKey] = useState(0);
+
+	const handleGenerate = useCallback(
+		(step: WizardStepInfo) => {
+			const prompt = STEP_PROMPTS[step.step];
+			if (prompt) {
+				sendMessage(prompt);
+			}
+		},
+		[sendMessage],
+	);
+
+	const handleConfirm = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/confirm`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	const handleSkip = useCallback(
+		async (step: WizardStepInfo) => {
+			const result = await apiPost(`/wizard/step/${step.step}/skip`);
+			if (result) {
+				onWizardUpdate(result);
+				setRefreshKey((k) => k + 1);
+			}
+		},
+		[onWizardUpdate],
+	);
+
+	if (wizardState.completed) {
+		return (
+			<div
+				data-testid="wizard-complete"
+				style={{
+					padding: "24px",
+					borderRadius: "12px",
+					background: STEP_BG_DONE,
+					border: `1px solid ${STEP_BORDER_DONE}`,
+					textAlign: "center",
+				}}
+			>
+				<h3 style={{ margin: "0 0 8px 0", color: COLOR_ACCENT }}>
+					Setup Complete
+				</h3>
+				<p style={{ margin: 0, color: COLOR_LABEL }}>
+					Your project is configured. You can start writing stories.
+				</p>
+			</div>
+		);
+	}
+
+	return (
+		<div
+			data-testid="setup-wizard"
+			style={{
+				display: "flex",
+				flexDirection: "column",
+				gap: "12px",
+			}}
+		>
+			<div style={{ marginBottom: "8px" }}>
+				<h3
+					style={{
+						margin: "0 0 4px 0",
+						color: COLOR_ACCENT,
+						fontSize: "1.1rem",
+					}}
+				>
+					Project Setup Wizard
+				</h3>
+				<p style={{ margin: 0, color: "#999", fontSize: "0.85rem" }}>
+					Step {wizardState.current_step_index + 1} of{" "}
+					{wizardState.steps.length}
+				</p>
+			</div>
+
+			{wizardState.steps.map((step, idx) => (
+				<StepCard
+					key={step.step}
+					step={step}
+					isActive={idx === wizardState.current_step_index}
+					onGenerate={() => handleGenerate(step)}
+					onConfirm={() => handleConfirm(step)}
+					onSkip={() => handleSkip(step)}
+				/>
+			))}
+		</div>
+	);
+}

frontend/src/components/selection/SelectionScreen.tsx

@@ -1,4 +1,5 @@
 import type { KeyboardEvent } from "react";
+import type { OAuthStatus } from "../../api/client";
 import { ProjectPathInput } from "./ProjectPathInput.tsx";
 import { RecentProjectsList } from "./RecentProjectsList.tsx";
 
@@ -24,6 +25,7 @@ export interface SelectionScreenProps {
 	onCloseSuggestions: () => void;
 	completionError: string | null;
 	currentPartial: string;
+	oauthStatus?: OAuthStatus | null;
 }
 
 export function SelectionScreen({
@@ -43,6 +45,7 @@ export function SelectionScreen({
 	onCloseSuggestions,
 	completionError,
 	currentPartial,
+	oauthStatus = null,
 }: SelectionScreenProps) {
 	const resolvedHomeDir = homeDir
 		? homeDir.endsWith("/")
@@ -57,6 +60,43 @@ export function SelectionScreen({
 			<h1>Storkit</h1>
 			<p>Paste or complete a project path to start.</p>
 
+			{oauthStatus !== null && (
+				<div style={{ marginBottom: "1rem" }}>
+					{!oauthStatus.authenticated || oauthStatus.expired ? (
+						<button
+							type="button"
+							onClick={() => {
+								window.open(
+									"/oauth/authorize",
+									"_blank",
+									"noopener,noreferrer",
+								);
+							}}
+							style={{
+								padding: "8px 16px",
+								borderRadius: "6px",
+								border: "1px solid #1a3a5c",
+								backgroundColor: "#1a3a5c",
+								color: "#7eb8f7",
+								cursor: "pointer",
+								fontSize: "0.9em",
+							}}
+						>
+							{oauthStatus.expired
+								? "Re-authenticate with Claude"
+								: "Login with Claude"}
+						</button>
+					) : (
+						<span
+							title="Authenticated with Claude via OAuth"
+							style={{ color: "#4caf50", fontSize: "0.9em" }}
+						>
+							✓ Authenticated with Claude
+						</span>
+					)}
+				</div>
+			)}
+
 			{knownProjects.length > 0 && (
 				<RecentProjectsList
 					projects={knownProjects}

frontend/src/slashCommands.ts

@@ -0,0 +1,105 @@
+export interface SlashCommand {
+	name: string;
+	description: string;
+}
+
+export const SLASH_COMMANDS: SlashCommand[] = [
+	{
+		name: "/help",
+		description: "Show this list of available slash commands.",
+	},
+	{
+		name: "/status",
+		description:
+			"Show pipeline status and agent availability. `/status <number>` shows a story triage dump.",
+	},
+	{
+		name: "/assign <number> <model>",
+		description: "Pre-assign a model to a story (e.g. `/assign 42 opus`).",
+	},
+	{
+		name: "/start <number>",
+		description:
+			"Start a coder on a story. Optionally specify a model: `/start <number> opus`.",
+	},
+	{
+		name: "/show <number>",
+		description: "Display the full text of a work item.",
+	},
+	{
+		name: "/move <number> <stage>",
+		description:
+			"Move a work item to a pipeline stage (backlog, current, qa, merge, done).",
+	},
+	{
+		name: "/delete <number>",
+		description:
+			"Remove a work item from the pipeline and stop any running agent.",
+	},
+	{
+		name: "/cost",
+		description:
+			"Show token spend: 24h total, top stories, breakdown by agent type, and all-time total.",
+	},
+	{
+		name: "/git",
+		description:
+			"Show git status: branch, uncommitted changes, and ahead/behind remote.",
+	},
+	{
+		name: "/overview <number>",
+		description: "Show the implementation summary for a merged story.",
+	},
+	{
+		name: "/ambient",
+		description: "Toggle ambient mode: `/ambient on` or `/ambient off`.",
+	},
+	{
+		name: "/htop",
+		description:
+			"Show live system and agent process dashboard: `/htop`, `/htop 10m`, `/htop stop`.",
+	},
+	{
+		name: "/loc",
+		description:
+			"Show top source files by line count: `/loc` (top 10), `/loc <N>`, or `/loc <filepath>`.",
+	},
+	{
+		name: "/rmtree <number>",
+		description:
+			"Delete the worktree for a story without removing it from the pipeline.",
+	},
+	{
+		name: "/rebuild",
+		description: "Rebuild the server binary and restart.",
+	},
+	{
+		name: "/timer",
+		description:
+			"Schedule a deferred agent start: `/timer <story_id> <HH:MM>`, `/timer list`, `/timer cancel <story_id>`.",
+	},
+	{
+		name: "/unblock <number>",
+		description:
+			"Reset a blocked story: clears blocked flag and resets retry count.",
+	},
+	{
+		name: "/unreleased",
+		description: "Show stories merged to master since the last release tag.",
+	},
+	{
+		name: "/setup",
+		description:
+			"Show setup wizard progress; or `/setup confirm` / `/setup skip` / `/setup retry` to drive the wizard.",
+	},
+	{
+		name: "/reset",
+		description:
+			"Clear the current Claude Code session and start fresh (messages and session ID are cleared locally).",
+	},
+	{
+		name: "/btw <question>",
+		description:
+			"Ask a side question using the current conversation as context. The question and answer are not added to the conversation history.",
+	},
+];

frontend/vite.config.ts

@@ -30,6 +30,20 @@ export default defineConfig(() => {
 						proxy.on("error", (_err) => {});
 					},
 				},
+				"/oauth": {
+					target: `http://127.0.0.1:${String(backendPort)}`,
+					timeout: 120000,
+					configure: (proxy) => {
+						proxy.on("error", (_err) => {});
+					},
+				},
+				"/callback": {
+					target: `http://127.0.0.1:${String(backendPort)}`,
+					timeout: 120000,
+					configure: (proxy) => {
+						proxy.on("error", (_err) => {});
+					},
+				},
 			},
 			watch: {
 				ignored: [

script/release

@@ -59,7 +59,11 @@ PACKAGE_LOCK="${SCRIPT_DIR}/frontend/package-lock.json"
 echo "==> Regenerated package-lock.json"
 
 git add "$CARGO_TOML" "$CARGO_LOCK" "$PACKAGE_JSON" "$PACKAGE_LOCK"
-git commit -m "Bump version to ${VERSION}"
+if git diff --cached --quiet; then
+  echo "==> Version already at ${VERSION}, skipping commit"
+else
+  git commit -m "Bump version to ${VERSION}"
+fi
 
 if ! command -v cross >/dev/null 2>&1; then
   echo "Error: 'cross' is not installed. Run: cargo install cross"
@@ -77,9 +81,12 @@ echo "==> Releasing ${TAG}"
 echo "==> Building macOS (native)..."
 cargo build --release
 
-echo "==> Building Linux (static musl via cross)..."
+echo "==> Building Linux amd64 (static musl via cross)..."
 cross build --release --target x86_64-unknown-linux-musl
 
+echo "==> Building Linux arm64 (static musl via cross)..."
+cross build --release --target aarch64-unknown-linux-musl
+
 # ── Package ────────────────────────────────────────────────────
 DIST="target/dist"
 rm -rf "$DIST"
@@ -87,6 +94,7 @@ mkdir -p "$DIST"
 
 cp "target/release/${BINARY_NAME}" "${DIST}/${BINARY_NAME}-macos-arm64"
 cp "target/x86_64-unknown-linux-musl/release/${BINARY_NAME}" "${DIST}/${BINARY_NAME}-linux-amd64"
+cp "target/aarch64-unknown-linux-musl/release/${BINARY_NAME}" "${DIST}/${BINARY_NAME}-linux-arm64"
 chmod +x "${DIST}"/*
 
 echo "==> Binaries:"
@@ -109,10 +117,10 @@ fi
 MERGE_RE="^(storkit|story-kit): merge "
 if [ -n "$LOG_RANGE" ]; then
   MERGED_RAW=$(git log "$LOG_RANGE" --pretty=format:"%s" --no-merges \
-    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u)
+    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u || true)
 else
   MERGED_RAW=$(git log --pretty=format:"%s" --no-merges \
-    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u)
+    | grep -E "$MERGE_RE" | sed -E "s/$MERGE_RE//" | sort -u || true)
 fi
 
 # Categorise merged work items and format names.
@@ -138,13 +146,13 @@ if [ -n "$LOG_RANGE" ]; then
     | grep -Ev "^(storkit|story-kit): " \
     | grep -Ev "^Revert \"(storkit|story-kit): " \
     | grep -v "^Bump version" \
-    | sed 's/^/- /')
+    | sed 's/^/- /' || true)
 else
   MANUAL=$(git log --pretty=format:"%s" --no-merges \
     | grep -Ev "^(storkit|story-kit): " \
     | grep -Ev "^Revert \"(storkit|story-kit): " \
     | grep -v "^Bump version" \
-    | sed 's/^/- /')
+    | sed 's/^/- /' || true)
 fi
 
 # ── Generate summary overview ─────────────────────────────────

script/test

@@ -4,6 +4,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+echo "=== Running cargo clippy ==="
+cargo clippy --manifest-path "$PROJECT_ROOT/Cargo.toml" --all-targets --all-features
+
 echo "=== Running Rust tests ==="
 cargo test --manifest-path "$PROJECT_ROOT/Cargo.toml"
 

server/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "storkit"
-version = "0.7.0"
+version = "0.8.5"
 edition = "2024"
 build = "build.rs"
 

server/src/agents/gates.rs

@@ -171,39 +171,12 @@ fn run_command_with_timeout(
 /// otherwise `cargo nextest run` / `cargo test`) in the given directory.
 /// Returns `(gates_passed, combined_output)`.
 pub(crate) fn run_acceptance_gates(path: &Path) -> Result<(bool, String), String> {
-    let mut all_output = String::new();
-    let mut all_passed = true;
-
-    // ── cargo clippy ──────────────────────────────────────────────
-    let clippy = Command::new("cargo")
-        .args(["clippy", "--all-targets", "--all-features"])
-        .current_dir(path)
-        .output()
-        .map_err(|e| format!("Failed to run cargo clippy: {e}"))?;
-
-    all_output.push_str("=== cargo clippy ===\n");
-    let clippy_stdout = String::from_utf8_lossy(&clippy.stdout);
-    let clippy_stderr = String::from_utf8_lossy(&clippy.stderr);
-    if !clippy_stdout.is_empty() {
-        all_output.push_str(&clippy_stdout);
-    }
-    if !clippy_stderr.is_empty() {
-        all_output.push_str(&clippy_stderr);
-    }
-    all_output.push('\n');
-
-    if !clippy.status.success() {
-        all_passed = false;
-    }
-
-    // ── tests (script/test if available, else cargo nextest/test) ─
+    // Run script/test (or fallback to cargo test). This is the sole
+    // acceptance gate — project-specific linting and test commands belong
+    // in script/test, not hardcoded here.
     let (test_success, test_out) = run_project_tests(path)?;
-    all_output.push_str(&test_out);
-    if !test_success {
-        all_passed = false;
-    }
 
-    Ok((all_passed, all_output))
+    Ok((test_success, test_out))
 }
 
 /// Run `script/test_coverage` in the given directory if the script exists.

server/src/agents/lifecycle.rs

@@ -102,7 +102,7 @@ pub fn feature_branch_has_unmerged_changes(project_root: &Path, story_id: &str)
 /// * If the story is in `4_merge/`, it is moved to `5_done/` and committed.
 /// * If the story is already in `5_done/` or `6_archived/`, this is a no-op (idempotent).
 /// * If the story is not found in `2_current/`, `4_merge/`, `5_done/`, or `6_archived/`, an error is returned.
-pub fn move_story_to_archived(project_root: &Path, story_id: &str) -> Result<(), String> {
+pub fn move_story_to_done(project_root: &Path, story_id: &str) -> Result<(), String> {
     let sk = project_root.join(".storkit").join("work");
     let current_path = sk.join("2_current").join(format!("{story_id}.md"));
     let merge_path = sk.join("4_merge").join(format!("{story_id}.md"));
@@ -584,10 +584,10 @@ mod tests {
         assert!(result.unwrap_err().contains("not found in work/2_current/"));
     }
 
-    // ── move_story_to_archived tests ──────────────────────────────────────────
+    // ── move_story_to_done tests ──────────────────────────────────────────
 
     #[test]
-    fn move_story_to_archived_finds_in_merge_dir() {
+    fn move_story_to_done_finds_in_merge_dir() {
         use std::fs;
         let tmp = tempfile::tempdir().unwrap();
         let root = tmp.path();
@@ -595,16 +595,16 @@ mod tests {
         fs::create_dir_all(&merge_dir).unwrap();
         fs::write(merge_dir.join("22_story_test.md"), "test").unwrap();
 
-        move_story_to_archived(root, "22_story_test").unwrap();
+        move_story_to_done(root, "22_story_test").unwrap();
 
         assert!(!merge_dir.join("22_story_test.md").exists());
         assert!(root.join(".storkit/work/5_done/22_story_test.md").exists());
     }
 
     #[test]
-    fn move_story_to_archived_error_when_not_in_current_or_merge() {
+    fn move_story_to_done_error_when_not_in_current_or_merge() {
         let tmp = tempfile::tempdir().unwrap();
-        let result = move_story_to_archived(tmp.path(), "99_nonexistent");
+        let result = move_story_to_done(tmp.path(), "99_nonexistent");
         assert!(result.unwrap_err().contains("4_merge"));
     }
 

server/src/agents/merge.rs

@@ -247,7 +247,7 @@ pub(crate) fn run_squash_merge(
             .output()
             .map_err(|e| format!("Failed to check merge diff: {e}"))?;
         let changed_files = String::from_utf8_lossy(&diff_check.stdout);
-        let has_code_changes = changed_files.lines().any(|f| !f.starts_with(".storkit/"));
+        let has_code_changes = changed_files.lines().any(|f| !f.starts_with(".storkit/work/"));
         if !has_code_changes {
             all_output.push_str(
                 "=== Merge commit contains only .storkit/ file moves, no code changes ===\n",
@@ -383,6 +383,72 @@ pub(crate) fn run_squash_merge(
         });
     }
 
+    // ── Verify code landed on the correct branch ──────────────────
+    // Guard against the cherry-pick silently landing on the wrong branch
+    // (e.g. a merge-queue branch from a concurrent merge).  If the current
+    // branch is not the base branch, or the HEAD commit has no code diff,
+    // treat the merge as failed so the story stays in the merge stage.
+    let current_branch = Command::new("git")
+        .args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .current_dir(project_root)
+        .output()
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default();
+
+    let base_branch = crate::config::ProjectConfig::load(project_root)
+        .ok()
+        .and_then(|c| c.base_branch.clone())
+        .unwrap_or_else(|| "master".to_string());
+
+    if current_branch != base_branch {
+        all_output.push_str(&format!(
+            "=== VERIFICATION FAILED: expected branch '{base_branch}' but HEAD is on \
+             '{current_branch}'. Cherry-pick landed on wrong branch. ===\n"
+        ));
+        cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
+        return Ok(SquashMergeResult {
+            success: false,
+            had_conflicts,
+            conflicts_resolved,
+            conflict_details: Some(format!(
+                "Cherry-pick landed on '{current_branch}' instead of '{base_branch}'"
+            )),
+            output: all_output,
+            gates_passed: true,
+        });
+    }
+
+    // Verify HEAD commit has actual code changes (not an empty cherry-pick).
+    // Exclude .storkit/work/ (pipeline file moves) but keep .storkit/project.toml
+    // and other config files which are legitimate deliverables.
+    let diff_stat = Command::new("git")
+        .args(["diff", "--stat", "HEAD~1..HEAD", "--", ".", ":(exclude).storkit/work"])
+        .current_dir(project_root)
+        .output()
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default();
+
+    if diff_stat.is_empty() {
+        all_output.push_str(
+            "=== VERIFICATION FAILED: cherry-pick produced no code changes on master. ===\n",
+        );
+        cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
+        return Ok(SquashMergeResult {
+            success: false,
+            had_conflicts,
+            conflicts_resolved,
+            conflict_details: Some(
+                "Cherry-pick commit contains no code changes (empty diff)".to_string(),
+            ),
+            output: all_output,
+            gates_passed: true,
+        });
+    }
+
+    all_output.push_str(&format!(
+        "=== Verified: cherry-pick landed on '{base_branch}' with code changes ===\n"
+    ));
+
     // ── Clean up ──────────────────────────────────────────────────
     cleanup_merge_workspace(project_root, &merge_wt_path, &merge_branch);
     all_output.push_str("=== Merge-queue cleanup complete ===\n");

server/src/agents/mod.rs

@@ -10,7 +10,7 @@ use crate::config::AgentConfig;
 use serde::{Deserialize, Serialize};
 
 pub use lifecycle::{
-    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_archived,
+    close_bug_to_archive, feature_branch_has_unmerged_changes, move_story_to_done,
     move_story_to_merge, move_story_to_qa, move_story_to_stage, reject_story_from_qa,
 };
 pub use pool::AgentPool;

server/src/agents/pool/lifecycle.rs

@@ -498,18 +498,63 @@ impl AgentPool {
                         }
                     }
 
-                    // Server-owned completion: run acceptance gates automatically
-                    // when the agent process exits normally.
-                    super::pipeline::run_server_owned_completion(
-                        &agents_ref,
-                        port_for_task,
-                        &sid,
-                        &aname,
-                        result.session_id,
-                        watcher_tx_clone.clone(),
-                    )
-                    .await;
-                    AgentPool::notify_agent_state_changed(&watcher_tx_clone);
+                    // Mergemaster agents have their own completion path via
+                    // start_merge_agent_work / run_merge_pipeline and must NOT go
+                    // through server-owned gates.  When a mergemaster exits early
+                    // (e.g. rate-limited before calling start_merge_agent_work) the
+                    // feature-branch worktree compiles fine and post-merge tests on
+                    // master pass (nothing changed), which would wrongly advance the
+                    // story to 5_done/ without any squash merge having occurred.
+                    // Instead: just remove the agent from the pool and let
+                    // auto-assign restart a new mergemaster for the story.
+                    let stage = config_clone
+                        .find_agent(&aname)
+                        .map(agent_config_stage)
+                        .unwrap_or_else(|| pipeline_stage(&aname));
+                    if stage == PipelineStage::Mergemaster {
+                        let (tx_done, done_session_id) = {
+                            let mut lock = match agents_ref.lock() {
+                                Ok(a) => a,
+                                Err(_) => return,
+                            };
+                            if let Some(agent) = lock.remove(&key_clone) {
+                                (agent.tx, agent.session_id.or(result.session_id))
+                            } else {
+                                (tx_clone.clone(), result.session_id)
+                            }
+                        };
+                        let _ = tx_done.send(AgentEvent::Done {
+                            story_id: sid.clone(),
+                            agent_name: aname.clone(),
+                            session_id: done_session_id,
+                        });
+                        AgentPool::notify_agent_state_changed(&watcher_tx_clone);
+                        // Send a WorkItem event so the auto-assign watcher loop
+                        // re-dispatches a new mergemaster if the story still needs
+                        // merging.  This avoids an async call to start_agent inside
+                        // a tokio::spawn (which would require Send).
+                        let _ = watcher_tx_clone.send(
+                            crate::io::watcher::WatcherEvent::WorkItem {
+                                stage: "4_merge".to_string(),
+                                item_id: sid.clone(),
+                                action: "reassign".to_string(),
+                                commit_msg: String::new(),
+                            },
+                        );
+                    } else {
+                        // Server-owned completion: run acceptance gates automatically
+                        // when the agent process exits normally.
+                        super::pipeline::run_server_owned_completion(
+                            &agents_ref,
+                            port_for_task,
+                            &sid,
+                            &aname,
+                            result.session_id,
+                            watcher_tx_clone.clone(),
+                        )
+                        .await;
+                        AgentPool::notify_agent_state_changed(&watcher_tx_clone);
+                    }
                 }
                 Err(e) => {
                     slog_error!("[agents] Agent process error for {aname} on {sid}: {e}");
@@ -1729,7 +1774,7 @@ stage = "coder"
 
     #[tokio::test]
     async fn archiving_story_removes_agent_entries_from_pool() {
-        use crate::agents::lifecycle::move_story_to_archived;
+        use crate::agents::lifecycle::move_story_to_done;
         use std::fs;
 
         let tmp = tempfile::tempdir().unwrap();
@@ -1746,7 +1791,7 @@ stage = "coder"
 
         assert_eq!(pool.list_agents().unwrap().len(), 3);
 
-        move_story_to_archived(root, "60_story_cleanup").unwrap();
+        move_story_to_done(root, "60_story_cleanup").unwrap();
         pool.remove_agents_for_story("60_story_cleanup");
 
         let remaining = pool.list_agents().unwrap();

server/src/agents/pool/pipeline/advance.rs

@@ -308,7 +308,7 @@ impl AgentPool {
                             "[pipeline] Post-merge tests passed for '{story_id}'. Moving to done."
                         );
                         if let Err(e) =
-                            crate::agents::lifecycle::move_story_to_archived(&project_root, story_id)
+                            crate::agents::lifecycle::move_story_to_done(&project_root, story_id)
                         {
                             slog_error!("[pipeline] Failed to move '{story_id}' to done: {e}");
                         }

server/src/agents/pool/pipeline/completion.rs

@@ -4,7 +4,7 @@ use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
 use tokio::sync::broadcast;
 
-use super::super::super::{AgentEvent, AgentStatus, CompletionReport};
+use super::super::super::{AgentEvent, AgentStatus, CompletionReport, PipelineStage, pipeline_stage};
 use super::super::{AgentPool, StoryAgent, composite_key};
 use super::advance::spawn_pipeline_advance;
 
@@ -155,6 +155,21 @@ pub(in crate::agents::pool) async fn run_server_owned_completion(
 ) {
     let key = composite_key(story_id, agent_name);
 
+    // Guard: mergemaster agents have their own completion path via
+    // start_merge_agent_work / run_merge_pipeline.  Running server-owned gates
+    // for a mergemaster would wrongly advance the story to 5_done/ even when
+    // no squash merge has occurred (e.g. rate-limited exit before the agent
+    // called start_merge_agent_work).  The lifecycle caller is responsible for
+    // cleaning up the agent entry and triggering auto-assign.
+    if pipeline_stage(agent_name) == PipelineStage::Mergemaster {
+        slog!(
+            "[agents] run_server_owned_completion skipped for mergemaster \
+             '{story_id}:{agent_name}'; mergemaster completion is handled by \
+             start_merge_agent_work."
+        );
+        return;
+    }
+
     // Guard: skip if completion was already recorded (legacy path).
     {
         let lock = match agents.lock() {
@@ -516,4 +531,83 @@ mod tests {
         )
         .await;
     }
+
+    /// Regression test for bug 445: a rate-limited mergemaster exits before
+    /// calling start_merge_agent_work.  run_server_owned_completion must be a
+    /// no-op for mergemaster agents — it must not run acceptance gates and must
+    /// not advance the story to 5_done/ even when a passing script/test exists.
+    ///
+    /// Before the fix: run_server_owned_completion would call run_pipeline_advance
+    /// for the Mergemaster stage, which ran post-merge tests on master (they pass
+    /// because nothing changed), then called move_story_to_done — advancing the
+    /// story without any squash merge having occurred.
+    #[cfg(unix)]
+    #[tokio::test]
+    async fn server_owned_completion_is_noop_for_mergemaster() {
+        use std::fs;
+        use std::os::unix::fs::PermissionsExt;
+        use tempfile::tempdir;
+
+        let tmp = tempdir().unwrap();
+        let root = tmp.path();
+        init_git_repo(root);
+
+        // Create a passing script/test so post-merge tests would succeed if
+        // run_pipeline_advance were incorrectly called for this mergemaster.
+        let script_dir = root.join("script");
+        fs::create_dir_all(&script_dir).unwrap();
+        let script_test = script_dir.join("test");
+        fs::write(&script_test, "#!/usr/bin/env sh\nexit 0\n").unwrap();
+        let mut perms = fs::metadata(&script_test).unwrap().permissions();
+        perms.set_mode(0o755);
+        fs::set_permissions(&script_test, perms).unwrap();
+
+        // Story in 4_merge/ — must NOT be moved to 5_done/.
+        let merge_dir = root.join(".storkit/work/4_merge");
+        fs::create_dir_all(&merge_dir).unwrap();
+        let story_path = merge_dir.join("99_story_merge445.md");
+        fs::write(&story_path, "---\nname: Merge 445 Test\n---\n").unwrap();
+
+        let pool = AgentPool::new_test(3001);
+        pool.inject_test_agent_with_path(
+            "99_story_merge445",
+            "mergemaster",
+            AgentStatus::Running,
+            root.to_path_buf(),
+        );
+
+        run_server_owned_completion(
+            &pool.agents,
+            pool.port,
+            "99_story_merge445",
+            "mergemaster",
+            None,
+            pool.watcher_tx.clone(),
+        )
+        .await;
+
+        // Wait briefly in case any background task fires.
+        tokio::time::sleep(std::time::Duration::from_millis(150)).await;
+
+        // Story must remain in 4_merge/ — not moved to 5_done/.
+        let done_path = root.join(".storkit/work/5_done/99_story_merge445.md");
+        assert!(
+            !done_path.exists(),
+            "Story must NOT be moved to 5_done/ when run_server_owned_completion \
+             is (incorrectly) called for a mergemaster agent"
+        );
+        assert!(
+            story_path.exists(),
+            "Story must remain in 4_merge/ when mergemaster completion is a no-op"
+        );
+
+        // The agent entry should remain in the pool (lifecycle cleanup is the
+        // caller's responsibility, not run_server_owned_completion's).
+        let agents = pool.agents.lock().unwrap();
+        let key = composite_key("99_story_merge445", "mergemaster");
+        assert!(
+            agents.get(&key).is_some(),
+            "Agent must remain in pool — run_server_owned_completion is a no-op for mergemaster"
+        );
+    }
 }

server/src/agents/pool/pipeline/merge.rs

@@ -104,7 +104,7 @@ impl AgentPool {
         }
 
         let story_archived =
-            crate::agents::lifecycle::move_story_to_archived(project_root, story_id).is_ok();
+            crate::agents::lifecycle::move_story_to_done(project_root, story_id).is_ok();
         if story_archived {
             self.remove_agents_for_story(story_id);
         }

server/src/agents/pty.rs

@@ -245,13 +245,16 @@ fn run_agent_pty_blocking(
     // via recv_timeout: if no output arrives within the configured window
     // the process is killed and the agent is marked Failed.
     let (line_tx, line_rx) = std::sync::mpsc::channel::<std::io::Result<String>>();
-    std::thread::spawn(move || {
+    let sid_for_reader = story_id.to_string();
+    let aname_for_reader = agent_name.to_string();
+    let reader_handle = std::thread::spawn(move || {
         let buf_reader = BufReader::new(reader);
         for line in buf_reader.lines() {
             if line_tx.send(line).is_err() {
                 break;
             }
         }
+        slog!("[agent:{sid_for_reader}:{aname_for_reader}] Reader thread exiting");
     });
 
     let timeout_dur = if inactivity_timeout_secs > 0 {
@@ -424,6 +427,15 @@ fn run_agent_pty_blocking(
     let _ = child.kill();
     let _ = child.wait();
 
+    // Wait for the reader thread to finish so it releases the cloned PTY
+    // master fd before we return.  Without this, the next PTY spawn for the
+    // same story can collide with a still-open fd from this session (#453).
+    slog!("[agent:{story_id}:{agent_name}] Waiting for reader thread to exit");
+    if let Err(e) = reader_handle.join() {
+        slog!("[agent:{story_id}:{agent_name}] Reader thread panicked: {e:?}");
+    }
+    slog!("[agent:{story_id}:{agent_name}] Reader thread joined");
+
     slog!(
         "[agent:{story_id}:{agent_name}] Done. Session: {:?}",
         session_id

server/src/chat/commands/mod.rs

@@ -13,6 +13,7 @@ mod help;
 pub(crate) mod loc;
 mod move_story;
 mod overview;
+mod setup;
 mod show;
 mod status;
 mod timer;
@@ -177,9 +178,62 @@ pub fn commands() -> &'static [BotCommand] {
             description: "Show stories merged to master since the last release tag",
             handler: unreleased::handle_unreleased,
         },
+        BotCommand {
+            name: "setup",
+            description: "Show setup wizard progress; or `setup generate` / `setup confirm` / `setup skip` / `setup retry` to drive the wizard from chat",
+            handler: setup::handle_setup,
+        },
     ]
 }
 
+/// Like [`try_handle_command`] but returns `(plain_body, html_body)`.
+///
+/// The plain body is unchanged Markdown text suitable for the Matrix `body`
+/// field (non-HTML clients). The HTML body is suitable for `formatted_body`.
+///
+/// The pipeline-status command (no args) injects Matrix `<font data-mx-color>`
+/// tags on the traffic-light dots. All other commands produce HTML by running
+/// the plain body through pulldown-cmark.
+pub fn try_handle_command_with_html(
+    dispatch: &CommandDispatch<'_>,
+    message: &str,
+) -> Option<(String, String)> {
+    let command_text = strip_bot_mention(message, dispatch.bot_name, dispatch.bot_user_id);
+    let trimmed = command_text.trim();
+    if !trimmed.is_empty() {
+        let (cmd_name, args) = match trimmed.split_once(char::is_whitespace) {
+            Some((c, a)) => (c, a.trim()),
+            None => (trimmed, ""),
+        };
+        // Only the no-arg status variant shows the pipeline with traffic-light
+        // dots; `status <number>` is a triage dump that needs no colour tags.
+        if cmd_name.eq_ignore_ascii_case("status") && args.is_empty() {
+            let body = status::build_pipeline_status(dispatch.project_root, dispatch.agents);
+            let html = status::build_pipeline_status_html(dispatch.project_root, dispatch.agents);
+            return Some((body, html));
+        }
+    }
+    // Generic path: plain text body → Markdown-to-HTML.
+    let body = try_handle_command(dispatch, message)?;
+    let html = plain_to_html(&body);
+    Some((body, html))
+}
+
+/// Convert a Markdown string to HTML using the same options as the Matrix
+/// transport's `markdown_to_html` helper.
+fn plain_to_html(markdown: &str) -> String {
+    use pulldown_cmark::{Options, Parser, html};
+    let normalized = crate::chat::util::normalize_line_breaks(markdown);
+    let options = Options::ENABLE_TABLES
+        | Options::ENABLE_FOOTNOTES
+        | Options::ENABLE_STRIKETHROUGH
+        | Options::ENABLE_TASKLISTS;
+    let parser = Parser::new_ext(&normalized, options);
+    let mut out = String::new();
+    html::push_html(&mut out, parser);
+    out
+}
+
 /// Try to match a user message against a registered bot command.
 ///
 /// The message is expected to be the raw body text (e.g., `"@timmy help"`).

server/src/chat/commands/move_story.rs

@@ -142,11 +142,7 @@ mod tests {
         try_handle_command(&dispatch, &format!("@timmy move {args}"))
     }
 
-    fn write_story_file(root: &std::path::Path, stage: &str, filename: &str, content: &str) {
-        let dir = root.join(".storkit/work").join(stage);
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(dir.join(filename), content).unwrap();
-    }
+    use crate::chat::test_helpers::write_story_file;
 
     #[test]
     fn move_command_is_registered() {

server/src/chat/commands/setup.rs

@@ -0,0 +1,339 @@
+//! Handler for the `setup` bot command.
+//!
+//! Drives the setup wizard from any chat transport (Matrix, Slack, WhatsApp).
+//!
+//! Usage:
+//! - `setup`         — show wizard progress and current step instructions
+//! - `setup confirm` — confirm the current step (writes staged content to disk)
+//! - `setup skip`    — skip the current step
+//! - `setup retry`   — discard staged content and reset the current step
+
+use super::CommandContext;
+use crate::http::mcp::wizard_tools::{
+    generation_hint, is_script_step, step_output_path, write_if_missing,
+};
+use crate::io::wizard::{format_wizard_state, StepStatus, WizardState};
+
+pub(super) fn handle_setup(ctx: &CommandContext) -> Option<String> {
+    let sub = ctx.args.trim().to_ascii_lowercase();
+
+    match sub.as_str() {
+        "" => Some(wizard_status_reply(ctx)),
+        "generate" => Some(wizard_generate_reply(ctx)),
+        "confirm" => Some(wizard_confirm_reply(ctx)),
+        "skip" => Some(wizard_skip_reply(ctx)),
+        "retry" => Some(wizard_retry_reply(ctx)),
+        _ => Some(format!(
+            "Unknown sub-command `{sub}`. Usage: `setup`, `setup generate`, `setup confirm`, `setup skip`, `setup retry`."
+        )),
+    }
+}
+
+/// Mark the current step as generating and return the generation hint.
+///
+/// This mirrors `wizard_generate` (with no content) from the MCP tools, making
+/// the interview flow accessible from chat transports (Matrix, Slack, WhatsApp).
+fn wizard_generate_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+
+    state.set_step_status(step, StepStatus::Generating, None);
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    let hint = generation_hint(step, root);
+    format!(
+        "Step '{}' marked as generating.\n\n{hint}\n\nOnce you have the content, stage it via the API and then run `setup confirm` to write it to disk.",
+        step.label()
+    )
+}
+
+/// Compose a status reply for the `setup` command (no args).
+fn wizard_status_reply(ctx: &CommandContext) -> String {
+    match WizardState::load(ctx.project_root) {
+        Some(state) => format_wizard_state(&state),
+        None => {
+            "No setup wizard active. Run `storkit init` in the project root to begin.".to_string()
+        }
+    }
+}
+
+/// Confirm the current wizard step, writing any staged content to disk.
+fn wizard_confirm_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+    let content = state.steps[idx].content.clone();
+
+    // Write content to disk (only if a file path exists and the file is absent).
+    let write_msg =
+        if let (Some(c), Some(ref path)) = (&content, step_output_path(root, step)) {
+            let executable = is_script_step(step);
+            match write_if_missing(path, c, executable) {
+                Ok(true) => format!(" File written: `{}`.", path.display()),
+                Ok(false) => format!(" File `{}` already exists — skipped.", path.display()),
+                Err(e) => return format!("Error: {e}"),
+            }
+        } else {
+            String::new()
+        };
+
+    if let Err(e) = state.confirm_step(step) {
+        return format!("Cannot confirm step: {e}");
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    if state.completed {
+        format!(
+            "Step '{}' confirmed.{write_msg}\n\nSetup wizard complete!",
+            step.label()
+        )
+    } else {
+        let next = &state.steps[state.current_step_index()];
+        format!(
+            "Step '{}' confirmed.{write_msg}\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        )
+    }
+}
+
+/// Skip the current wizard step without writing any file.
+fn wizard_skip_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+
+    if let Err(e) = state.skip_step(step) {
+        return format!("Cannot skip step: {e}");
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    if state.completed {
+        format!(
+            "Step '{}' skipped. Setup wizard complete!",
+            step.label()
+        )
+    } else {
+        let next = &state.steps[state.current_step_index()];
+        format!(
+            "Step '{}' skipped.\n\nNext: {} — run `wizard_generate` to begin.",
+            step.label(),
+            next.step.label()
+        )
+    }
+}
+
+/// Discard staged content and reset the current step to pending.
+fn wizard_retry_reply(ctx: &CommandContext) -> String {
+    let root = ctx.project_root;
+    let mut state = match WizardState::load(root) {
+        Some(s) => s,
+        None => return "No wizard active.".to_string(),
+    };
+    if state.completed {
+        return "Wizard is already complete.".to_string();
+    }
+
+    let idx = state.current_step_index();
+    let step = state.steps[idx].step;
+
+    if let Some(s) = state.steps.iter_mut().find(|s| s.step == step) {
+        s.status = StepStatus::Pending;
+        s.content = None;
+    }
+    if let Err(e) = state.save(root) {
+        return format!("Failed to save wizard state: {e}");
+    }
+
+    format!(
+        "Step '{}' reset to pending. Run `wizard_generate` to regenerate content.",
+        step.label()
+    )
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::io::wizard::WizardState;
+    use std::collections::HashSet;
+    use std::sync::{Arc, Mutex};
+    use tempfile::TempDir;
+
+    fn make_ctx<'a>(
+        args: &'a str,
+        project_root: &'a std::path::Path,
+        agents: &'a Arc<crate::agents::AgentPool>,
+        ambient_rooms: &'a Arc<Mutex<HashSet<String>>>,
+    ) -> CommandContext<'a> {
+        CommandContext {
+            bot_name: "Bot",
+            args,
+            project_root,
+            agents,
+            ambient_rooms,
+            room_id: "!test:example.com",
+        }
+    }
+
+    #[test]
+    fn setup_no_wizard_returns_helpful_message() {
+        let dir = TempDir::new().unwrap();
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4000));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("storkit init"));
+    }
+
+    #[test]
+    fn setup_with_wizard_shows_status() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4001));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("Setup wizard"));
+    }
+
+    #[test]
+    fn setup_skip_advances_wizard() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4002));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("skip", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("skipped"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn setup_confirm_advances_wizard() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4003));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("confirm", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("confirmed"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(state.current_step_index(), 2);
+    }
+
+    #[test]
+    fn setup_retry_resets_step() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        // Stage some content first.
+        {
+            let mut state = WizardState::load(dir.path()).unwrap();
+            state.set_step_status(
+                crate::io::wizard::WizardStep::Context,
+                crate::io::wizard::StepStatus::AwaitingConfirmation,
+                Some("content".to_string()),
+            );
+            state.save(dir.path()).unwrap();
+        }
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4004));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("retry", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("reset"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(
+            state.steps[1].status,
+            crate::io::wizard::StepStatus::Pending
+        );
+    }
+
+    #[test]
+    fn setup_unknown_sub_command_returns_usage() {
+        let dir = TempDir::new().unwrap();
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4005));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("foobar", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("Unknown sub-command"));
+        assert!(result.contains("Usage"));
+    }
+
+    #[test]
+    fn setup_generate_marks_generating_and_returns_hint() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4006));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("generate", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("generating"));
+        let state = WizardState::load(dir.path()).unwrap();
+        assert_eq!(
+            state.steps[1].status,
+            crate::io::wizard::StepStatus::Generating
+        );
+    }
+
+    #[test]
+    fn setup_generate_bare_project_asks_user() {
+        let dir = TempDir::new().unwrap();
+        // Bare project — only scaffolding files
+        std::fs::create_dir_all(dir.path().join(".storkit")).unwrap();
+        WizardState::init_if_missing(dir.path());
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4007));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("generate", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("bare project"));
+        assert!(result.contains("Ask the user"));
+    }
+
+    #[test]
+    fn setup_generate_no_wizard_returns_error() {
+        let dir = TempDir::new().unwrap();
+        let agents = Arc::new(crate::agents::AgentPool::new_test(4008));
+        let rooms = Arc::new(Mutex::new(HashSet::new()));
+        let ctx = make_ctx("generate", dir.path(), &agents, &rooms);
+        let result = handle_setup(&ctx).unwrap();
+        assert!(result.contains("No wizard active"));
+    }
+}

server/src/chat/commands/show.rs

@@ -91,11 +91,7 @@ mod tests {
         try_handle_command(&dispatch, &format!("@timmy show {args}"))
     }
 
-    fn write_story_file(root: &std::path::Path, stage: &str, filename: &str, content: &str) {
-        let dir = root.join(".storkit/work").join(stage);
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(dir.join(filename), content).unwrap();
-    }
+    use crate::chat::test_helpers::write_story_file;
 
     #[test]
     fn show_command_is_registered() {

server/src/chat/commands/status.rs

@@ -122,6 +122,34 @@ fn read_stage_items(
     items
 }
 
+/// Build the HTML `formatted_body` for the pipeline status with Matrix colour
+/// tags on the traffic-light dots.
+///
+/// Converts the plain-text pipeline status (Markdown) to HTML via
+/// pulldown-cmark and wraps each traffic-light character in a
+/// `<font data-mx-color="#rrggbb">` tag so Matrix clients display them in
+/// colour.
+pub(super) fn build_pipeline_status_html(project_root: &std::path::Path, agents: &AgentPool) -> String {
+    use pulldown_cmark::{Options, Parser, html};
+
+    let plain = build_pipeline_status(project_root, agents);
+    let normalized = crate::chat::util::normalize_line_breaks(&plain);
+    let options = Options::ENABLE_TABLES
+        | Options::ENABLE_FOOTNOTES
+        | Options::ENABLE_STRIKETHROUGH
+        | Options::ENABLE_TASKLISTS;
+    let parser = Parser::new_ext(&normalized, options);
+    let mut html_out = String::new();
+    html::push_html(&mut html_out, parser);
+
+    // Wrap each traffic-light character with a Matrix colour tag.
+    html_out
+        .replace('\u{2717}', "<font data-mx-color=\"#cc0000\">\u{2717}</font>") // ✗ blocked
+        .replace('\u{25D1}', "<font data-mx-color=\"#ffaa00\">\u{25D1}</font>") // ◑ throttled
+        .replace('\u{25CF}', "<font data-mx-color=\"#00cc00\">\u{25CF}</font>") // ● running
+        .replace('\u{25CB}', "<font data-mx-color=\"#888888\">\u{25CB}</font>") // ○ idle
+}
+
 /// Build the full pipeline status text formatted for Matrix (markdown).
 pub(super) fn build_pipeline_status(project_root: &std::path::Path, agents: &AgentPool) -> String {
     // Build a map from story_id → active AgentInfo for quick lookup.
@@ -444,6 +472,81 @@ mod tests {
 
     // -- traffic_light_dot --------------------------------------------------
 
+    // -- build_pipeline_status_html (colored dots) --------------------------
+
+    #[test]
+    fn html_status_colors_idle_dot_grey() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_idle.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Idle Story\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let html = build_pipeline_status_html(tmp.path(), &agents);
+
+        assert!(
+            html.contains("<font data-mx-color=\"#888888\">\u{25CB}</font>"),
+            "idle dot should be grey (#888888): {html}"
+        );
+    }
+
+    #[test]
+    fn html_status_colors_blocked_dot_red() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_blocked.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Blocked Story\nblocked: true\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let html = build_pipeline_status_html(tmp.path(), &agents);
+
+        assert!(
+            html.contains("<font data-mx-color=\"#cc0000\">\u{2717}</font>"),
+            "blocked dot should be red (#cc0000): {html}"
+        );
+    }
+
+    #[test]
+    fn html_status_plain_text_body_unchanged() {
+        use std::io::Write;
+        use tempfile::TempDir;
+
+        let tmp = TempDir::new().unwrap();
+        let stage_dir = tmp.path().join(".storkit/work/2_current");
+        std::fs::create_dir_all(&stage_dir).unwrap();
+
+        let story_path = stage_dir.join("42_story_idle.md");
+        let mut f = std::fs::File::create(&story_path).unwrap();
+        writeln!(f, "---\nname: Idle Story\n---\n").unwrap();
+
+        let agents = AgentPool::new_test(3000);
+        let plain = build_pipeline_status(tmp.path(), &agents);
+
+        // Plain text must still use bare Unicode dots (no HTML tags).
+        assert!(
+            plain.contains('\u{25CB}'),
+            "plain text should have bare Unicode idle dot: {plain}"
+        );
+        assert!(
+            !plain.contains("data-mx-color"),
+            "plain text must not contain HTML colour attributes: {plain}"
+        );
+    }
+
+    // -- traffic_light_dot --------------------------------------------------
+
     #[test]
     fn dot_idle_when_no_agent() {
         assert_eq!(traffic_light_dot(false, false, false), "\u{25CB} "); // ○

server/src/chat/commands/triage.rs

@@ -296,11 +296,7 @@ mod tests {
         try_handle_command(&dispatch, &format!("@timmy status {args}"))
     }
 
-    fn write_story_file(root: &Path, stage: &str, filename: &str, content: &str) {
-        let dir = root.join(".storkit/work").join(stage);
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(dir.join(filename), content).unwrap();
-    }
+    use crate::chat::test_helpers::write_story_file;
 
     // -- registration -------------------------------------------------------
 

server/src/chat/commands/unblock.rs

@@ -98,17 +98,25 @@ pub(crate) fn unblock_by_path(path: &Path, story_id: &str) -> String {
 
     let story_name = meta.name.as_deref().unwrap_or(story_id).to_string();
 
-    if meta.blocked != Some(true) {
+    let has_blocked = meta.blocked == Some(true);
+    let has_merge_failure = meta.merge_failure.is_some();
+
+    if !has_blocked && !has_merge_failure {
         return format!(
             "**{story_name}** ({story_id}) is not blocked. Nothing to unblock."
         );
     }
 
-    // Clear the blocked flag (reads + writes the file).
-    if let Err(e) = clear_front_matter_field(path, "blocked") {
+    // Clear the blocked flag if present.
+    if has_blocked && let Err(e) = clear_front_matter_field(path, "blocked") {
         return format!("Failed to clear blocked flag on **{story_id}**: {e}");
     }
 
+    // Clear merge_failure if present.
+    if has_merge_failure && let Err(e) = clear_front_matter_field(path, "merge_failure") {
+        return format!("Failed to clear merge_failure on **{story_id}**: {e}");
+    }
+
     // Reset retry_count to 0 (re-read the updated file, modify, write).
     let updated_contents = match std::fs::read_to_string(path) {
         Ok(c) => c,
@@ -119,7 +127,10 @@ pub(crate) fn unblock_by_path(path: &Path, story_id: &str) -> String {
         return format!("Failed to reset retry_count on **{story_id}**: {e}");
     }
 
-    format!("Unblocked **{story_name}** ({story_id}). Retry count reset to 0.")
+    let mut cleared = Vec::new();
+    if has_blocked { cleared.push("blocked"); }
+    if has_merge_failure { cleared.push("merge_failure"); }
+    format!("Unblocked **{story_name}** ({story_id}). Cleared: {}. Retry count reset to 0.", cleared.join(", "))
 }
 
 // ---------------------------------------------------------------------------
@@ -149,11 +160,7 @@ mod tests {
         try_handle_command(&dispatch, &format!("@timmy unblock {args}"))
     }
 
-    fn write_story_file(root: &std::path::Path, stage: &str, filename: &str, content: &str) {
-        let dir = root.join(".storkit/work").join(stage);
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(dir.join(filename), content).unwrap();
-    }
+    use crate::chat::test_helpers::write_story_file;
 
     #[test]
     fn unblock_command_is_registered() {

server/src/chat/mod.rs

@@ -8,6 +8,8 @@ pub mod commands;
 pub mod timer;
 pub mod transport;
 pub mod util;
+#[cfg(test)]
+pub(crate) mod test_helpers;
 
 use async_trait::async_trait;
 

server/src/chat/test_helpers.rs

@@ -0,0 +1,15 @@
+//! Shared test utilities for chat handler tests.
+//!
+//! Import with `use crate::chat::test_helpers::write_story_file;`
+
+use std::path::Path;
+
+/// Write a work-item file into the standard pipeline directory structure.
+///
+/// Creates `.storkit/work/{stage}/{filename}` under `root`, creating any
+/// missing parent directories.
+pub(crate) fn write_story_file(root: &Path, stage: &str, filename: &str, content: &str) {
+    let dir = root.join(".storkit/work").join(stage);
+    std::fs::create_dir_all(&dir).unwrap();
+    std::fs::write(dir.join(filename), content).unwrap();
+}

server/src/chat/timer.rs

@@ -9,6 +9,8 @@ use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 
+use crate::chat::util::strip_bot_mention;
+
 // ── Data types ─────────────────────────────────────────────────────────────
 
 /// A single scheduled timer entry.
@@ -256,7 +258,7 @@ pub fn extract_timer_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<TimerCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -466,37 +468,6 @@ fn resolve_story_id(number_or_id: &str, project_root: &Path) -> Option<String> {
     None
 }
 
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ── Tests ──────────────────────────────────────────────────────────────────
 
 #[cfg(test)]

server/src/chat/transport/matrix/assign.rs

@@ -9,6 +9,7 @@
 //! that the next `start` invocation picks it up automatically.
 
 use crate::agents::{AgentPool, AgentStatus};
+use crate::chat::util::strip_bot_mention;
 use crate::io::story_metadata::{parse_front_matter, set_front_matter_field};
 use std::path::Path;
 
@@ -43,7 +44,7 @@ pub fn extract_assign_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<AssignCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -234,40 +235,6 @@ pub async fn handle_assign(
     }
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-///
-/// Mirrors the logic in `commands::strip_bot_mention` and `start::strip_mention`.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -354,6 +321,18 @@ mod tests {
         assert_eq!(cmd, None);
     }
 
+    #[test]
+    fn extract_assign_command_multibyte_prefix_no_panic() {
+        // "xxxx⏺ assign 42 opus" — ⏺ (U+23FA) is 3 bytes, starting at byte 4.
+        // "@timmy" has len 6 so text[..6] lands inside ⏺ — panics without the fix.
+        let cmd = extract_assign_command(
+            "xxxx\u{23FA} assign 42 opus",
+            "Timmy",
+            "@timmy:home.local",
+        );
+        assert_eq!(cmd, None);
+    }
+
     // -- resolve_agent_name --------------------------------------------------
 
     #[test]
@@ -371,11 +350,7 @@ mod tests {
 
     // -- handle_assign (no running coder) ------------------------------------
 
-    fn write_story_file(root: &Path, stage: &str, filename: &str, content: &str) {
-        let dir = root.join(".storkit/work").join(stage);
-        std::fs::create_dir_all(&dir).unwrap();
-        std::fs::write(dir.join(filename), content).unwrap();
-    }
+    use crate::chat::test_helpers::write_story_file;
 
     #[tokio::test]
     async fn handle_assign_returns_not_found_for_unknown_number() {

server/src/chat/transport/matrix/bot/messages.rs

@@ -1,4 +1,4 @@
-use crate::chat::util::drain_complete_paragraphs;
+use crate::chat::util::{drain_complete_paragraphs, is_permission_approval};
 use crate::http::context::PermissionDecision;
 use crate::llm::providers::claude_code::{ClaudeCodeProvider, ClaudeCodeResult};
 use crate::slog;
@@ -22,24 +22,6 @@ use super::history::{ConversationEntry, ConversationRole, save_history};
 use super::mentions::{is_reply_to_bot, mentions_bot};
 use super::verification::check_sender_verified;
 
-/// Returns `true` if the message body is an affirmative permission response.
-///
-/// Recognised affirmative tokens (case-insensitive): `yes`, `y`, `approve`,
-/// `allow`, `ok`. Anything else — including ambiguous text — is treated as
-/// denial (fail-closed).
-pub(super) fn is_permission_approval(body: &str) -> bool {
-    // Strip a leading @mention (e.g. "@timmy yes") so the bot name doesn't
-    // interfere with the check.
-    let trimmed = body
-        .trim()
-        .trim_start_matches('@')
-        .split_whitespace()
-        .last()
-        .unwrap_or("")
-        .to_ascii_lowercase();
-    matches!(trimmed.as_str(), "yes" | "y" | "approve" | "allow" | "ok")
-}
-
 /// Build the user-facing prompt for a single turn.  In multi-user rooms the
 /// sender is included so the LLM can distinguish participants.
 pub(super) fn format_user_prompt(sender: &str, message: &str) -> String {
@@ -186,10 +168,9 @@ pub(super) async fn on_room_message(
         ambient_rooms: &ctx.ambient_rooms,
         room_id: &room_id_str,
     };
-    if let Some(response) = super::super::commands::try_handle_command(&dispatch, &user_message) {
+    if let Some((response, response_html)) = super::super::commands::try_handle_command_with_html(&dispatch, &user_message) {
         slog!("[matrix-bot] Handled bot command from {sender}");
-        let html = markdown_to_html(&response);
-        if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &response, &html).await
+        if let Ok(msg_id) = ctx.transport.send_message(&room_id_str, &response, &response_html).await
             && let Ok(event_id) = msg_id.parse()
         {
             ctx.bot_sent_event_ids.lock().await.insert(event_id);
@@ -635,7 +616,13 @@ pub(super) async fn handle_message(
         }
         Err(e) => {
             slog!("[matrix-bot] LLM error: {e}");
-            let err_msg = format!("Error processing your request: {e}");
+            let err_msg = if let Some(url) = crate::llm::oauth::extract_login_url_from_error(&e) {
+                format!(
+                    "Authentication required. [Click here to log in to Claude]({url})"
+                )
+            } else {
+                format!("Error processing your request: {e}")
+            };
             let _ = msg_tx.send(err_msg.clone());
             (err_msg, None)
         }
@@ -705,43 +692,22 @@ mod tests {
         assert_eq!(prompt, "@bob:example.com: What's up?");
     }
 
-    // -- is_permission_approval -----------------------------------------------
+    // -- OAuth login link formatting ----------------------------------------
 
     #[test]
-    fn is_permission_approval_accepts_yes_variants() {
-        assert!(is_permission_approval("yes"));
-        assert!(is_permission_approval("Yes"));
-        assert!(is_permission_approval("YES"));
-        assert!(is_permission_approval("y"));
-        assert!(is_permission_approval("Y"));
-        assert!(is_permission_approval("approve"));
-        assert!(is_permission_approval("allow"));
-        assert!(is_permission_approval("ok"));
-        assert!(is_permission_approval("OK"));
+    fn oauth_error_produces_login_link() {
+        let err = "OAuth session expired or credentials missing. Please log in: http://localhost:3001/oauth/authorize";
+        let url = crate::llm::oauth::extract_login_url_from_error(err);
+        assert!(url.is_some(), "should extract URL from OAuth error");
+        let msg = format!("Authentication required. [Click here to log in to Claude]({})", url.unwrap());
+        assert!(msg.contains("http://localhost:3001/oauth/authorize"));
+        assert!(msg.contains("[Click here to log in to Claude]"));
     }
 
     #[test]
-    fn is_permission_approval_denies_no_and_other() {
-        assert!(!is_permission_approval("no"));
-        assert!(!is_permission_approval("No"));
-        assert!(!is_permission_approval("n"));
-        assert!(!is_permission_approval("deny"));
-        assert!(!is_permission_approval("reject"));
-        assert!(!is_permission_approval("maybe"));
-        assert!(!is_permission_approval(""));
-        assert!(!is_permission_approval("yes please do it"));
-    }
-
-    #[test]
-    fn is_permission_approval_strips_at_mention_prefix() {
-        assert!(is_permission_approval("@timmy yes"));
-        assert!(!is_permission_approval("@timmy no"));
-    }
-
-    #[test]
-    fn is_permission_approval_handles_whitespace() {
-        assert!(is_permission_approval("  yes  "));
-        assert!(is_permission_approval("\tyes\n"));
+    fn non_oauth_error_not_formatted_as_link() {
+        let err = "Some unrelated error";
+        assert!(crate::llm::oauth::extract_login_url_from_error(err).is_none());
     }
 
     // -- bot_name / system prompt -------------------------------------------

server/src/chat/transport/matrix/delete.rs

@@ -5,6 +5,7 @@
 //! commits the change to git.
 
 use crate::agents::{AgentPool, AgentStatus};
+use crate::chat::util::strip_bot_mention;
 use std::path::Path;
 
 /// A parsed delete command from a Matrix message body.
@@ -25,7 +26,7 @@ pub fn extract_delete_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<DeleteCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -185,41 +186,6 @@ fn stage_display_name(stage: &str) -> &str {
     }
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-///
-/// Mirrors the logic in `commands::strip_bot_mention` and `htop::strip_mention`
-/// so delete detection works without depending on private symbols.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/htop.rs

@@ -13,6 +13,7 @@ use std::time::Duration;
 use tokio::sync::{Mutex as TokioMutex, watch};
 
 use crate::agents::{AgentPool, AgentStatus};
+use crate::chat::util::strip_bot_mention;
 use crate::slog;
 use crate::chat::ChatTransport;
 
@@ -51,7 +52,7 @@ pub type HtopSessions = Arc<TokioMutex<HashMap<String, HtopSession>>>;
 /// - `htop 10m`      → `Start { duration_secs: 600 }`
 /// - `htop 120`      → `Start { duration_secs: 120 }` (bare seconds)
 pub fn extract_htop_command(message: &str, bot_name: &str, bot_user_id: &str) -> Option<HtopCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped.trim();
 
     // Strip leading punctuation (e.g. the comma in "@timmy, htop")
@@ -88,42 +89,6 @@ fn parse_duration(s: &str) -> Option<u64> {
     s.parse::<u64>().ok()
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-///
-/// Mirrors the logic in `commands::strip_bot_mention` so htop detection works
-/// without depending on private symbols in that module.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // System stats
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/rebuild.rs

@@ -6,6 +6,7 @@
 //! running.
 
 use crate::agents::AgentPool;
+use crate::chat::util::strip_bot_mention;
 use std::path::Path;
 use std::sync::Arc;
 
@@ -22,7 +23,7 @@ pub fn extract_rebuild_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<RebuildCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -56,38 +57,6 @@ pub async fn handle_rebuild(
     }
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/reset.rs

@@ -6,6 +6,7 @@
 //! affected — only the in-memory/persisted conversation state is cleared.
 
 use crate::chat::transport::matrix::bot::{ConversationHistory, RoomConversation};
+use crate::chat::util::strip_bot_mention;
 use matrix_sdk::ruma::OwnedRoomId;
 use std::path::Path;
 
@@ -22,7 +23,7 @@ pub fn extract_reset_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<ResetCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -58,38 +59,6 @@ pub async fn handle_reset(
     "Session reset. Starting fresh — previous context has been cleared.".to_string()
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/rmtree.rs

@@ -5,6 +5,7 @@
 //! The story file in the pipeline is left untouched.
 
 use crate::agents::{AgentPool, AgentStatus};
+use crate::chat::util::strip_bot_mention;
 use std::path::Path;
 
 /// A parsed rmtree command from a Matrix message body.
@@ -25,7 +26,7 @@ pub fn extract_rmtree_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<RmtreeCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -118,38 +119,6 @@ pub async fn handle_rmtree(
     response
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/matrix/start.rs

@@ -7,6 +7,7 @@
 //! name ends with the supplied hint, e.g. `coder-{hint}`).
 
 use crate::agents::AgentPool;
+use crate::chat::util::strip_bot_mention;
 use std::path::Path;
 
 /// A parsed start command from a Matrix message body.
@@ -31,7 +32,7 @@ pub fn extract_start_command(
     bot_name: &str,
     bot_user_id: &str,
 ) -> Option<StartCommand> {
-    let stripped = strip_mention(message, bot_name, bot_user_id);
+    let stripped = strip_bot_mention(message, bot_name, bot_user_id);
     let trimmed = stripped
         .trim()
         .trim_start_matches(|c: char| !c.is_alphanumeric());
@@ -177,40 +178,6 @@ pub async fn handle_start(
     }
 }
 
-/// Strip the bot mention prefix from a raw Matrix message body.
-///
-/// Mirrors the logic in `commands::strip_bot_mention` and `delete::strip_mention`.
-fn strip_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
-    let trimmed = message.trim();
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
-    }
-    if let Some(localpart) = bot_user_id.split(':').next()
-        && let Some(rest) = strip_prefix_ci(trimmed, localpart)
-    {
-        return rest;
-    }
-    if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
-    }
-    trimmed
-}
-
-fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
-    if text.len() < prefix.len() {
-        return None;
-    }
-    if !text[..prefix.len()].eq_ignore_ascii_case(prefix) {
-        return None;
-    }
-    let rest = &text[prefix.len()..];
-    match rest.chars().next() {
-        None => Some(rest),
-        Some(c) if c.is_alphanumeric() || c == '-' || c == '_' => None,
-        _ => Some(rest),
-    }
-}
-
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------

server/src/chat/transport/slack/commands.rs

@@ -9,6 +9,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::agents::AgentPool;
 use crate::chat::transport::matrix::{ConversationEntry, ConversationRole, RoomConversation};
+use crate::chat::util::is_permission_approval;
 use crate::slog;
 use crate::chat::ChatTransport;
 use crate::http::context::{PermissionDecision, PermissionForward};
@@ -86,17 +87,6 @@ pub struct SlackWebhookContext {
     pub permission_timeout_secs: u64,
 }
 
-// ── Permission approval detection ──────────────────────────────────────
-
-/// Returns `true` if the message body should be interpreted as permission approval.
-fn is_permission_approval(body: &str) -> bool {
-    let trimmed = body.trim().to_ascii_lowercase();
-    matches!(
-        trimmed.as_str(),
-        "yes" | "y" | "approve" | "allow" | "ok"
-    )
-}
-
 // ── Incoming message dispatch ───────────────────────────────────────────
 
 pub(super) async fn handle_incoming_message(

server/src/chat/transport/whatsapp/commands.rs

@@ -1,21 +1,13 @@
 use std::sync::Arc;
 
 use crate::chat::transport::matrix::{ConversationEntry, ConversationRole, RoomConversation};
+use crate::chat::util::is_permission_approval;
 use crate::http::context::{PermissionDecision};
 use crate::slog;
 use super::WhatsAppWebhookContext;
 use super::format::{chunk_for_whatsapp, markdown_to_whatsapp};
 use super::history::save_whatsapp_history;
 
-/// Returns `true` if the message body should be interpreted as permission approval.
-fn is_permission_approval(body: &str) -> bool {
-    let trimmed = body.trim().to_ascii_lowercase();
-    matches!(
-        trimmed.as_str(),
-        "yes" | "y" | "approve" | "allow" | "ok"
-    )
-}
-
 /// Dispatch an incoming WhatsApp message to bot commands.
 pub(super) async fn handle_incoming_message(ctx: &WhatsAppWebhookContext, sender: &str, message: &str) {
     use crate::chat::commands::{CommandDispatch, try_handle_command};
@@ -391,7 +383,13 @@ async fn handle_llm_message(ctx: &WhatsAppWebhookContext, sender: &str, user_mes
         }
         Err(e) => {
             slog!("[whatsapp] LLM error: {e}");
-            let err_msg = format!("Error processing your request: {e}");
+            let err_msg = if let Some(url) = crate::llm::oauth::extract_login_url_from_error(&e) {
+                format!(
+                    "Authentication required. Log in to Claude here: {url}"
+                )
+            } else {
+                format!("Error processing your request: {e}")
+            };
             let _ = msg_tx.send(err_msg.clone());
             (err_msg, None)
         }
@@ -499,6 +497,24 @@ mod tests {
         })
     }
 
+    // ── OAuth login link formatting ───────────────────────────────────────
+
+    #[test]
+    fn whatsapp_oauth_error_produces_plain_text_url() {
+        let err = "OAuth session expired or credentials missing. Please log in: http://localhost:3001/oauth/authorize";
+        let url = crate::llm::oauth::extract_login_url_from_error(err);
+        assert!(url.is_some(), "should extract URL from OAuth error");
+        let msg = format!("Authentication required. Log in to Claude here: {}", url.unwrap());
+        assert!(msg.contains("http://localhost:3001/oauth/authorize"));
+        assert!(!msg.contains('['), "WhatsApp message should not use Markdown link syntax");
+    }
+
+    #[test]
+    fn whatsapp_non_oauth_error_not_formatted_as_link() {
+        let err = "Some unrelated error occurred during processing";
+        assert!(crate::llm::oauth::extract_login_url_from_error(err).is_none());
+    }
+
     // ── Allowlist tests ───────────────────────────────────────────────────
 
     #[tokio::test]

server/src/chat/util.rs

@@ -3,6 +3,27 @@
 //! These functions are transport-agnostic helpers for processing chat messages:
 //! prefix stripping, bot-mention handling, and paragraph buffering.
 
+/// Returns `true` if the message body is an affirmative permission response.
+///
+/// Recognised affirmative tokens (case-insensitive): `yes`, `y`, `approve`,
+/// `allow`, `ok`. Anything else — including ambiguous text — is treated as
+/// denial (fail-closed).
+///
+/// A leading `@mention` (e.g. `"@timmy yes"`) is stripped before checking, so
+/// the bot name does not interfere with the result.
+pub fn is_permission_approval(body: &str) -> bool {
+    // Strip a leading @mention (e.g. "@timmy yes") so the bot name doesn't
+    // interfere with the check.
+    let trimmed = body
+        .trim()
+        .trim_start_matches('@')
+        .split_whitespace()
+        .last()
+        .unwrap_or("")
+        .to_ascii_lowercase();
+    matches!(trimmed.as_str(), "yes" | "y" | "approve" | "allow" | "ok")
+}
+
 /// Case-insensitive prefix strip that also requires the match to end at a
 /// word boundary (whitespace, punctuation, or end-of-string).
 pub fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
@@ -25,29 +46,44 @@ pub fn strip_prefix_ci<'a>(text: &'a str, prefix: &str) -> Option<&'a str> {
 /// - `@bot_localpart:server.com rest` → `rest`
 /// - `@bot_localpart rest` → `rest`
 /// - `DisplayName rest` → `rest`
+/// - `DisplayName: rest` → `rest`  (Element tab-completion inserts a colon)
+/// - `DisplayName, rest` → `rest`  (Element tab-completion may insert a comma)
+/// - `DisplayName ⚡️: rest` → `rest`  (display name with emoji)
 pub fn strip_bot_mention<'a>(message: &'a str, bot_name: &str, bot_user_id: &str) -> &'a str {
     let trimmed = message.trim();
 
     // Try full Matrix user ID (e.g. "@timmy:homeserver.local")
     if let Some(rest) = strip_prefix_ci(trimmed, bot_user_id) {
-        return rest;
+        return strip_mention_separator(rest);
     }
 
     // Try @localpart (e.g. "@timmy")
     if let Some(localpart) = bot_user_id.split(':').next()
         && let Some(rest) = strip_prefix_ci(trimmed, localpart)
     {
-        return rest;
+        return strip_mention_separator(rest);
     }
 
-    // Try display name (e.g. "Timmy")
+    // Try display name (e.g. "Timmy" or "timmy ⚡️")
     if let Some(rest) = strip_prefix_ci(trimmed, bot_name) {
-        return rest;
+        return strip_mention_separator(rest);
     }
 
     trimmed
 }
 
+/// Strip an optional Element tab-completion separator (`:` or `,`) and
+/// surrounding whitespace from the start of text that follows a bot mention.
+///
+/// Element's tab-completion inserts `DisplayName: ` (colon + space) after the
+/// name.  Without this strip the leading `:` would be treated as part of the
+/// command name and no command would match.
+fn strip_mention_separator(rest: &str) -> &str {
+    let rest = rest.trim_start();
+    let rest = rest.strip_prefix([',', ':']).unwrap_or(rest);
+    rest.trim_start()
+}
+
 /// Returns `true` when `text` ends while inside an open fenced code block.
 ///
 /// A fenced code block opens and closes on lines that start with ` ``` `
@@ -190,6 +226,45 @@ pub fn normalize_line_breaks(text: &str) -> String {
 mod tests {
     use super::*;
 
+    // -- is_permission_approval ---------------------------------------------
+
+    #[test]
+    fn is_permission_approval_accepts_yes_variants() {
+        assert!(is_permission_approval("yes"));
+        assert!(is_permission_approval("Yes"));
+        assert!(is_permission_approval("YES"));
+        assert!(is_permission_approval("y"));
+        assert!(is_permission_approval("Y"));
+        assert!(is_permission_approval("approve"));
+        assert!(is_permission_approval("allow"));
+        assert!(is_permission_approval("ok"));
+        assert!(is_permission_approval("OK"));
+    }
+
+    #[test]
+    fn is_permission_approval_denies_no_and_other() {
+        assert!(!is_permission_approval("no"));
+        assert!(!is_permission_approval("No"));
+        assert!(!is_permission_approval("n"));
+        assert!(!is_permission_approval("deny"));
+        assert!(!is_permission_approval("reject"));
+        assert!(!is_permission_approval("maybe"));
+        assert!(!is_permission_approval(""));
+        assert!(!is_permission_approval("yes please do it"));
+    }
+
+    #[test]
+    fn is_permission_approval_strips_at_mention_prefix() {
+        assert!(is_permission_approval("@timmy yes"));
+        assert!(!is_permission_approval("@timmy no"));
+    }
+
+    #[test]
+    fn is_permission_approval_handles_whitespace() {
+        assert!(is_permission_approval("  yes  "));
+        assert!(is_permission_approval("\tyes\n"));
+    }
+
     // -- strip_prefix_ci ----------------------------------------------------
 
     #[test]
@@ -274,7 +349,36 @@ mod tests {
     #[test]
     fn strip_mention_comma_after_name() {
         let rest = strip_bot_mention("@timmy, help", "Timmy", "@timmy:homeserver.local");
-        assert_eq!(rest.trim().trim_start_matches(',').trim(), "help");
+        assert_eq!(rest.trim(), "help");
+    }
+
+    #[test]
+    fn strip_mention_colon_separator_element_tab_completion() {
+        // Element tab-completes display names with a trailing ": "
+        let rest = strip_bot_mention(
+            "timmy ⚡️: ambient on",
+            "timmy ⚡️",
+            "@timmy:homeserver.local",
+        );
+        assert_eq!(rest, "ambient on");
+    }
+
+    #[test]
+    fn strip_mention_emoji_display_name_no_separator() {
+        // Display name with emoji, no separator
+        let rest = strip_bot_mention(
+            "timmy ⚡️ ambient on",
+            "timmy ⚡️",
+            "@timmy:homeserver.local",
+        );
+        assert_eq!(rest, "ambient on");
+    }
+
+    #[test]
+    fn strip_mention_colon_after_localpart() {
+        // Element may also produce "@timmy: help"
+        let rest = strip_bot_mention("@timmy: help", "Timmy", "@timmy:homeserver.local");
+        assert_eq!(rest, "help");
     }
 
     // -- drain_complete_paragraphs ------------------------------------------

server/src/http/anthropic.rs

@@ -64,6 +64,13 @@ impl AnthropicApi {
     }
 }
 
+#[cfg(test)]
+impl From<Arc<AppContext>> for AnthropicApi {
+    fn from(ctx: Arc<AppContext>) -> Self {
+        Self::new(ctx)
+    }
+}
+
 #[OpenApi(tag = "AnthropicTags::Anthropic")]
 impl AnthropicApi {
     /// Check whether an Anthropic API key is stored.
@@ -151,25 +158,16 @@ impl AnthropicApi {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::http::context::AppContext;
+    use crate::http::test_helpers::{make_api, test_ctx};
     use serde_json::json;
-    use std::sync::Arc;
     use tempfile::TempDir;
 
-    fn test_ctx(dir: &TempDir) -> AppContext {
-        AppContext::new_test(dir.path().to_path_buf())
-    }
-
-    fn make_api(dir: &TempDir) -> AnthropicApi {
-        AnthropicApi::new(Arc::new(test_ctx(dir)))
-    }
-
     // -- get_anthropic_api_key (private helper) --
 
     #[test]
     fn get_api_key_returns_err_when_not_set() {
         let dir = TempDir::new().unwrap();
-        let ctx = test_ctx(&dir);
+        let ctx = test_ctx(dir.path());
         let result = get_anthropic_api_key(&ctx);
         assert!(result.is_err());
         assert!(result.unwrap_err().contains("not found"));
@@ -178,7 +176,7 @@ mod tests {
     #[test]
     fn get_api_key_returns_err_when_empty() {
         let dir = TempDir::new().unwrap();
-        let ctx = test_ctx(&dir);
+        let ctx = test_ctx(dir.path());
         ctx.store.set(KEY_ANTHROPIC_API_KEY, json!(""));
         let result = get_anthropic_api_key(&ctx);
         assert!(result.is_err());
@@ -188,7 +186,7 @@ mod tests {
     #[test]
     fn get_api_key_returns_err_when_not_string() {
         let dir = TempDir::new().unwrap();
-        let ctx = test_ctx(&dir);
+        let ctx = test_ctx(dir.path());
         ctx.store.set(KEY_ANTHROPIC_API_KEY, json!(12345));
         let result = get_anthropic_api_key(&ctx);
         assert!(result.is_err());
@@ -198,7 +196,7 @@ mod tests {
     #[test]
     fn get_api_key_returns_key_when_set() {
         let dir = TempDir::new().unwrap();
-        let ctx = test_ctx(&dir);
+        let ctx = test_ctx(dir.path());
         ctx.store.set(KEY_ANTHROPIC_API_KEY, json!("sk-ant-test123"));
         let result = get_anthropic_api_key(&ctx);
         assert_eq!(result.unwrap(), "sk-ant-test123");
@@ -209,7 +207,7 @@ mod tests {
     #[tokio::test]
     async fn key_exists_returns_false_when_not_set() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<AnthropicApi>(&dir);
         let result = api.get_anthropic_api_key_exists().await.unwrap();
         assert!(!result.0);
     }
@@ -229,7 +227,7 @@ mod tests {
     #[tokio::test]
     async fn set_api_key_returns_true() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<AnthropicApi>(&dir);
         let payload = Json(ApiKeyPayload {
             api_key: "sk-ant-test123".to_string(),
         });
@@ -256,7 +254,7 @@ mod tests {
     #[tokio::test]
     async fn list_models_fails_when_no_key() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<AnthropicApi>(&dir);
         let result = api.list_anthropic_models().await;
         assert!(result.is_err());
     }
@@ -288,7 +286,7 @@ mod tests {
     #[test]
     fn new_creates_api_instance() {
         let dir = TempDir::new().unwrap();
-        let _api = make_api(&dir);
+        let _api = make_api::<AnthropicApi>(&dir);
     }
 
     #[test]

server/src/http/io.rs

@@ -138,18 +138,19 @@ impl IoApi {
     }
 }
 
+#[cfg(test)]
+impl From<std::sync::Arc<AppContext>> for IoApi {
+    fn from(ctx: std::sync::Arc<AppContext>) -> Self {
+        Self { ctx }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::http::context::AppContext;
+    use crate::http::test_helpers::make_api;
     use tempfile::TempDir;
 
-    fn make_api(dir: &TempDir) -> IoApi {
-        IoApi {
-            ctx: Arc::new(AppContext::new_test(dir.path().to_path_buf())),
-        }
-    }
-
     // --- list_directory_absolute ---
 
     #[tokio::test]
@@ -158,7 +159,7 @@ mod tests {
         std::fs::create_dir(dir.path().join("subdir")).unwrap();
         std::fs::write(dir.path().join("file.txt"), "content").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: dir.path().to_string_lossy().to_string(),
         });
@@ -176,7 +177,7 @@ mod tests {
         let empty = dir.path().join("empty");
         std::fs::create_dir(&empty).unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: empty.to_string_lossy().to_string(),
         });
@@ -187,7 +188,7 @@ mod tests {
     #[tokio::test]
     async fn list_directory_absolute_errors_on_nonexistent_path() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: dir.path().join("nonexistent").to_string_lossy().to_string(),
         });
@@ -201,7 +202,7 @@ mod tests {
         let file = dir.path().join("not_a_dir.txt");
         std::fs::write(&file, "content").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: file.to_string_lossy().to_string(),
         });
@@ -216,7 +217,7 @@ mod tests {
         let dir = TempDir::new().unwrap();
         let new_dir = dir.path().join("new_dir");
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(CreateDirectoryPayload {
             path: new_dir.to_string_lossy().to_string(),
         });
@@ -231,7 +232,7 @@ mod tests {
         let existing = dir.path().join("existing");
         std::fs::create_dir(&existing).unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(CreateDirectoryPayload {
             path: existing.to_string_lossy().to_string(),
         });
@@ -244,7 +245,7 @@ mod tests {
         let dir = TempDir::new().unwrap();
         let nested = dir.path().join("a").join("b").join("c");
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(CreateDirectoryPayload {
             path: nested.to_string_lossy().to_string(),
         });
@@ -258,7 +259,7 @@ mod tests {
     #[tokio::test]
     async fn get_home_directory_returns_a_path() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let result = api.get_home_directory().await.unwrap();
         let home = &result.0;
         assert!(!home.is_empty());
@@ -272,7 +273,7 @@ mod tests {
         let dir = TempDir::new().unwrap();
         std::fs::write(dir.path().join("hello.txt"), "hello world").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: "hello.txt".to_string(),
         });
@@ -283,7 +284,7 @@ mod tests {
     #[tokio::test]
     async fn read_file_errors_on_missing_file() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: "nonexistent.txt".to_string(),
         });
@@ -296,7 +297,7 @@ mod tests {
     #[tokio::test]
     async fn write_file_creates_file() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(WriteFilePayload {
             path: "output.txt".to_string(),
             content: "written content".to_string(),
@@ -312,7 +313,7 @@ mod tests {
     #[tokio::test]
     async fn write_file_creates_parent_dirs() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(WriteFilePayload {
             path: "sub/dir/file.txt".to_string(),
             content: "nested".to_string(),
@@ -334,7 +335,7 @@ mod tests {
         std::fs::write(dir.path().join("src/main.rs"), "fn main() {}").unwrap();
         std::fs::write(dir.path().join("README.md"), "# readme").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let result = api.list_project_files().await.unwrap();
         let files = &result.0;
 
@@ -348,7 +349,7 @@ mod tests {
         std::fs::create_dir(dir.path().join("subdir")).unwrap();
         std::fs::write(dir.path().join("file.txt"), "").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let result = api.list_project_files().await.unwrap();
         let files = &result.0;
 
@@ -363,7 +364,7 @@ mod tests {
         std::fs::write(dir.path().join("z_last.txt"), "").unwrap();
         std::fs::write(dir.path().join("a_first.txt"), "").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let result = api.list_project_files().await.unwrap();
         let files = &result.0;
 
@@ -380,7 +381,7 @@ mod tests {
         std::fs::create_dir(dir.path().join("adir")).unwrap();
         std::fs::write(dir.path().join("bfile.txt"), "").unwrap();
 
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: ".".to_string(),
         });
@@ -394,7 +395,7 @@ mod tests {
     #[tokio::test]
     async fn list_directory_errors_on_nonexistent() {
         let dir = TempDir::new().unwrap();
-        let api = make_api(&dir);
+        let api = make_api::<IoApi>(&dir);
         let payload = Json(FilePathPayload {
             path: "nonexistent_dir".to_string(),
         });

server/src/http/mcp/agent_tools.rs

@@ -370,13 +370,9 @@ pub(super) async fn get_worktree_commits(worktree_path: &str, base_branch: &str)
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::http::context::AppContext;
+    use crate::http::test_helpers::test_ctx;
     use crate::store::StoreOps;
 
-    fn test_ctx(dir: &std::path::Path) -> AppContext {
-        AppContext::new_test(dir.to_path_buf())
-    }
-
     #[test]
     fn tool_list_agents_empty() {
         let tmp = tempfile::tempdir().unwrap();

server/src/http/mcp/diagnostics.rs

@@ -279,11 +279,7 @@ pub(super) fn tool_loc_file(args: &Value, ctx: &AppContext) -> Result<String, St
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::http::context::AppContext;
-
-    fn test_ctx(dir: &std::path::Path) -> AppContext {
-        AppContext::new_test(dir.to_path_buf())
-    }
+    use crate::http::test_helpers::test_ctx;
 
     #[test]
     fn tool_get_server_logs_no_args_returns_string() {

server/src/http/mcp/git_tools.rs

@@ -304,12 +304,9 @@ pub(super) async fn tool_git_log(args: &Value, ctx: &AppContext) -> Result<Strin
 mod tests {
     use super::*;
     use crate::http::context::AppContext;
+    use crate::http::test_helpers::test_ctx;
     use serde_json::json;
 
-    fn test_ctx(dir: &std::path::Path) -> AppContext {
-        AppContext::new_test(dir.to_path_buf())
-    }
-
     /// Create a temp directory with a git worktree structure and init a repo.
     fn setup_worktree() -> (tempfile::TempDir, PathBuf, AppContext) {
         let tmp = tempfile::tempdir().unwrap();