loki-mode 11.3.0 → 11.3.2

package/docs/architecture/bmad-loki-voice-agent-council-analysis.md

@@ -1,61 +0,0 @@
-# BMAD Method x Loki Mode Voice Agent -- Council Analysis
-
-**Date:** 2026-02-25
-**Council:** 3 Opus reviewers (blind review)
-**Verdict:** Unanimous YES with phased approach
-
-## Proposal Summary
-
-Integrate the BMAD Method (https://github.com/bmad-code-org/BMAD-METHOD) with Loki Mode
-to create a structured requirements elicitation pipeline. BMAD provides a 4-phase
-workflow (Analysis, Planning, Solutioning, Implementation) with agent personas, step-file
-architecture, and adversarial review -- complementing Loki Mode's autonomous execution engine.
-
-## Council Findings
-
-### Reviewer 1: Architecture Focus
-
-**Vote:** YES (phased)
-
-- BMAD's step-file architecture aligns with Loki's progressive disclosure model
-- BMAD artifacts (product-brief, PRD, architecture, epics) map cleanly to Loki's SDLC phases
-- Context budget is manageable: BMAD step files load one-at-a-time (~3K tokens each)
-- Integration surface is well-defined: `.loki/queue/`, `build_prompt()`, event bus
-- Risk: BMAD is an external dependency that may change format without notice
-
-### Reviewer 2: Integration Feasibility
-
-**Vote:** YES (phased)
-
-- BMAD PRD output sections (Functional Requirements, Success Criteria, User Journeys)
-  match most of prd-analyzer.py's existing dimension patterns
-- Agent overlap is complementary, not conflicting: BMAD covers pre-development, Loki covers execution
-- Voice.sh needs significant extension for structured dialogue (currently only 4-section dictation)
-- MIT license is fully compatible with Loki Mode's distribution
-- Risk: Voice agent layer (Phase 3) has highest uncertainty; STT reliability for technical terms
-
-### Reviewer 3: Risk and Quality
-
-**Vote:** YES (phased, with gates)
-
-- Backward compatibility is achievable: BMAD integration is additive (new flag, new adapter)
-- Existing non-BMAD projects are untouched unless `--bmad-project` is explicitly used
-- Quality gates apply to all new code: 3-reviewer blind review, anti-sycophancy, test coverage
-- BMAD's adversarial review methodology strengthens Loki's existing quality gate system
-- Risk: Scope creep from Epic 2 (engine embedding) and Epic 3 (voice agent) -- phase gates essential
-
-## Recommended Phased Approach
-
-| Phase | Epic | Priority | Risk |
-|-------|-------|----------|------|
-| P0 | BMAD Artifact Pipeline (parse, score, load) | Must-have | Low |
-| P1 | BMAD Engine Embedding (agent YAML parser, step processor) | Should-have | Medium |
-| P2 | Voice Agent Layer (structured dialogue, BMAD-to-voice) | Nice-to-have | High |
-
-## Key Constraints
-
-1. P0 must ship independently and prove value before P1/P2 begin
-2. No runtime dependency on BMAD repo -- adapter reads BMAD output artifacts only
-3. Zero regression on existing non-BMAD workflows
-4. All code must pass existing 8-gate quality system
-5. Context budget: BMAD additions must stay under 15K tokens per iteration

package/docs/auto-claude-comparison.md

@@ -1,250 +0,0 @@
-# Auto-Claude vs Loki Mode: Honest Technical Comparison
-
-## Overview
-
-| Metric | Auto-Claude | Loki Mode |
-|--------|-------------|-----------|
-| **GitHub Stars** | 11,479 | 594 |
-| **Release Type** | Desktop app (Electron) | CLI skill |
-| **License** | AGPL-3.0 | MIT |
-| **Requires** | Claude Pro/Max subscription | Claude API (any tier) |
-| **Version** | v2.7.5 (stable) | v5.25.0 |
-| **Created** | Dec 2025 | Jan 2026 |
-| **Community** | Discord, YouTube | GitHub only |
-
-## Honest Assessment: Where Auto-Claude is Better
-
-### 1. Desktop GUI with Visual Task Management
-Auto-Claude provides a native Electron app with:
-- Kanban board for visual task tracking
-- Multiple agent terminals (up to 12)
-- Real-time progress visualization
-- Point-and-click interface
-
-**Loki Mode:** CLI + web dashboard with dark Vercel/Linear theme, sidebar navigation, overview cards, Completion Council views. Dashboard served on port 57374.
-
-**Verdict: Auto-Claude wins** - GUI significantly lowers barrier to entry.
-
-### 2. Package Distribution
-Auto-Claude provides:
-- Pre-built binaries for Windows, macOS (Intel + ARM), Linux
-- Auto-updates
-- SHA256 checksums
-- VirusTotal scans for security
-
-**Loki Mode:** npm, Homebrew, Docker, and git clone. Multiple distribution methods.
-
-**Verdict: Auto-Claude wins** - Professional distribution.
-
-### 3. Community and Adoption
-- Auto-Claude: 11,479 stars, Discord community, YouTube channel, active development
-- Loki Mode: 594 stars, GitHub-only community, CONTRIBUTING.md + issue templates added
-
-**Verdict: Auto-Claude wins** - Network effects matter.
-
-### 4. External Integrations
-Auto-Claude has built-in:
-- GitHub/GitLab integration (import issues, create MRs)
-- Linear integration (sync tasks)
-- OAuth setup flow
-
-**Loki Mode:** No built-in integrations. Manual git operations.
-
-**Verdict: Auto-Claude wins** - Better workflow integration.
-
-### 5. Interactive Controls
-Auto-Claude allows:
-- Ctrl+C to pause and add instructions
-- HUMAN_INPUT.md for file-based intervention
-- PAUSE file to pause after current session
-
-**Loki Mode:** Limited. INTERVENTION_NEEDED signal exists but less refined.
-
-**Verdict: Auto-Claude wins** - Better human-in-the-loop.
-
-### 6. AI-Powered Merge
-Auto-Claude has automatic conflict resolution when merging branches.
-
-**Loki Mode:** Has auto-merge but aborts on conflicts.
-
-**Verdict: Auto-Claude wins** - Smarter merge handling.
-
----
-
-## Honest Assessment: Where Loki Mode is Better
-
-### 1. Research Foundation
-Loki Mode is built on peer-reviewed research:
-- Anthropic: Constitutional AI, alignment detection
-- DeepMind: SIMA 2, Scalable Oversight via Debate
-- OpenAI: Agents SDK patterns
-- Academic: CONSENSAGENT (ACL 2025), GoalAct, A-Mem/MIRIX
-
-**Auto-Claude:** No documented research foundation.
-
-**Verdict: Loki Mode wins** - Academically grounded.
-
-### 3. Full SDLC Coverage
-Loki Mode covers:
-- Engineering (code, tests, deployment)
-- Business operations (marketing, sales, legal)
-- Growth (A/B testing, community, lifecycle)
-
-**Auto-Claude:** Engineering only. No business/marketing agents.
-
-**Verdict: Loki Mode wins** - Full spec-to-product lifecycle vs coding only.
-
-### 4. Anti-Sycophancy Measures
-Loki Mode implements CONSENSAGENT (ACL 2025):
-- Blind 3-reviewer system
-- Devil's advocate on unanimous approval
-- Severity-based blocking
-
-**Auto-Claude:** Single QA loop with no anti-sycophancy checks.
-
-**Verdict: Loki Mode wins** - Research-backed quality assurance.
-
-### 5. Quality Gates
-Loki Mode runs 8 deterministic quality gates plus full SDLC phase coverage.
-
-The 8 deterministic quality gates: static analysis (CodeQL, ESLint), test suite (pass/fail), blind 3-reviewer review with severity blocking, anti-sycophancy Devil's Advocate, mock-integrity, test-mutation, documentation coverage, and Magic Modules debate. (Backward-compatibility is a conditional healing-mode auditor, not a numbered gate.)
-
-Beyond the gates, the SDLC pipeline covers these phases:
-1. Static analysis (CodeQL, ESLint)
-2. Unit tests (test suite passes; coverage % not measured this release)
-3. API/Integration tests
-4. E2E tests (Playwright)
-5. Security scanning (OWASP)
-6. Parallel code review (3 reviewers)
-7. Performance/load testing
-8. Accessibility (WCAG)
-9. Regression testing
-10. UAT simulation
-11. Anti-sycophancy check
-12. Scale-aware review intensity
-13. Continuous monitoring
-
-**Auto-Claude:** Single QA validation loop (up to 50 iterations).
-
-**Verdict: Loki Mode wins** - Comprehensive quality vs single loop.
-
-### 7. Licensing
-- Loki Mode: BUSL-1.1 (source-available)
-- Auto-Claude: AGPL-3.0 (copyleft, requires open-sourcing modifications)
-
-### 8. API Access
-- Loki Mode: Works with Claude API (any tier)
-- Auto-Claude: Requires Claude Pro/Max subscription
-
-**Verdict: Loki Mode wins** - Lower barrier to entry.
-
-### 9. No External Dependencies
-- Loki Mode: Pure bash/skill, no Electron, no Python backend
-- Auto-Claude: Requires Python 3.9+, Node.js, Electron, specific npm packages
-
-**Verdict: Loki Mode wins** - Simpler, lighter footprint.
-
-### 10. Cursor Scale Patterns (v3.3.0)
-Loki Mode now incorporates proven patterns from Cursor's large-scale agent deployments:
-- Recursive sub-planners
-- Judge agents for cycle decisions
-- Optimistic concurrency control
-- Scale-aware review intensity
-
-**Auto-Claude:** Does not document scale patterns.
-
-**Verdict: Loki Mode wins** - Production-tested at scale.
-
----
-
-## Feature Comparison Matrix
-
-| Feature | Auto-Claude | Loki Mode |
-|---------|:-----------:|:---------:|
-| Desktop GUI | Yes | Web Dashboard (dark theme) |
-| CLI Support | Yes | Yes |
-| Git Worktrees | Yes | Yes |
-| Parallel Agents | 12 terminals | 3-5 sessions |
-| Memory Persistence | Yes (Graphiti) | Yes (episodic/semantic) |
-| GitHub Integration | Yes | No |
-| Linear Integration | Yes | No |
-| Auto-Updates | Yes | No |
-| Research Foundation | No | Yes |
-| Specialized Agents | 4 types | 41 types |
-| Business Automation | No | Yes |
-| Anti-Sycophancy | No | Yes |
-| Quality Gates | 1 (QA loop) | 14 + Completion Council |
-| Published Benchmarks | No | Yes |
-| AI Merge Resolution | Yes | No |
-| Complexity Tiers | Yes | No |
-| Human Intervention | Yes (Ctrl+C, files) | Limited |
-| License | AGPL-3.0 | MIT |
-| Subscription Required | Yes (Pro/Max) | No |
-
----
-
-## What Loki Mode Should Learn from Auto-Claude
-
-### High Priority
-1. **AI-Powered Merge Resolution** - Handle conflicts automatically instead of aborting
-2. **Human Intervention Mechanism** - Add Ctrl+C pause, HUMAN_INPUT.md, PAUSE file
-3. **Complexity Tiers** - Simple (3 phases), Standard (6), Complex (8)
-4. **Session Memory Persistence** - Graphiti-style cross-session memory
-
-### Medium Priority
-5. **Visual Dashboard Upgrade** - Better than current basic HTML polling
-6. **Spec Runner Pattern** - Interactive spec creation like Auto-Claude's CLI
-7. **GitHub/GitLab Integration** - Import issues, create MRs
-
-### Lower Priority
-8. **Package Distribution** - Consider Electron or at least versioned releases
-9. **Discord Community** - Build community infrastructure
-
----
-
-## What Auto-Claude Could Learn from Loki Mode
-
-1. **Research Foundation** - Document the science behind decisions
-3. **Anti-Sycophancy** - Blind review prevents false positives
-4. **Full SDLC** - Business, marketing, growth automation
-6. **Source-available (BUSL-1.1)** - Inspect and self-host the full code
-
----
-
-## Conclusion
-
-**Auto-Claude is better if you want:**
-- Visual GUI with Kanban board
-- Pre-packaged desktop app
-- GitHub/Linear integration
-- Large community
-
-**Loki Mode is better if you want:**
-- Research-backed architecture
-- Full spec-to-product lifecycle (not just coding)
-- 41 specialized agent roles
-- Anti-sycophancy measures
-- Source-available (BUSL-1.1) license
-- No subscription requirement
-- Verified benchmarks
-
-### Honest Summary
-
-Auto-Claude has better UX and community. Loki Mode has better architecture and coverage.
-
-Auto-Claude is a polished product. Loki Mode is a research-backed system.
-
-For pure coding tasks with GUI preference: **Auto-Claude wins**.
-For full autonomous spec-to-product delivery with quality guarantees: **Loki Mode wins**.
-
----
-
-## Sources
-
-- [Auto-Claude GitHub](https://github.com/AndyMik90/Auto-Claude)
-- [MemOS - Memory Operating System](https://github.com/MemTensor/MemOS)
-- [Dexter - Financial Research Agent](https://github.com/virattt/dexter)
-- [Simon Willison - Scaling Long-Running Autonomous Coding](https://simonwillison.net/2026/Jan/19/scaling-long-running-autonomous-coding/)
-- [Cursor - Scaling Agents Blog](https://cursor.com/blog/scaling-agents)
-- [CONSENSAGENT - ACL 2025](https://aclanthology.org/2025.findings-acl.1141/)
-- [Agentic AI Trends 2026](https://machinelearningmastery.com/7-agentic-ai-trends-to-watch-in-2026/)

package/docs/bug-fixes/agent-01-cli-fixes.md

@@ -1,101 +0,0 @@
-# Agent 01 - CLI Functional Testing Bug Fixes
-
-File modified: `autonomy/loki`
-Total changes: 166 insertions, 39 deletions
-
-## Known Bugs Fixed
-
-### BUG-CLI-003 | PID recycling guard for `cmd_web_stop`
-- **Location**: `cmd_web_stop()` PID file kill block
-- **Fix**: Before killing a PID from the PID file, verify the process command matches `python`, `uvicorn`, or `Purple` via `ps -p PID -o comm=`. If the PID has been recycled by the OS to a non-Purple-Lab process, skip the kill and warn the user.
-
-### BUG-CLI-012 | Shell injection via unquoted Python file paths
-- **Location**: Multiple `python3 -c` calls throughout the CLI
-- **Fix**: Replaced all `open('$variable')` patterns in `python3 -c` calls with environment-variable-based parameter passing (`_VAR="$value" python3 -c "import os; open(os.environ['_VAR'])"`). Fixed 14 instances across:
-  - `cmd_status` context window (lines ~1741-1742)
-  - Healing report (friction map, failure modes)
-  - Trigger schedule count
-  - Failover chain providers
-  - Vector index stats (numpy)
-  - Context show (5 token metrics)
-  - Budget cost display (2 metrics)
-  - OTEL config endpoint
-  - Project description JSON output
-
-### BUG-CLI-005 | `cmd_web_status` wrong port and log paths
-- **Location**: `cmd_web_status()`
-- **Fix**: Port lookup now checks `$PURPLE_LAB_STATE_DIR/port` (home-based) first before CWD-based fallback. Log path resolves against home-based state dir first, falling back to CWD-based path.
-
-### BUG-CLI-006 | `loki logs` truncates to 50 lines silently
-- **Location**: `cmd_logs()`
-- **Fix**: Added full argument parsing with `--tail/-n`, `--follow/-f`, `--all/-a`, and `--help`. The 50-line default is now documented in a hint line shown with output. Added `--follow` for live streaming.
-
-### BUG-CLI-007 | `loki init` skips directory creation on failure
-- **Location**: `cmd_init()` project directory creation
-- **Fix**: Added `if ! mkdir -p` guards for both the project directory and `.loki` directory creation. Script now exits with an error message if directory creation fails.
-
-### BUG-CLI-008 | `loki export` overwrites without confirmation
-- **Location**: `_export_json()`, `_export_markdown()`, `_export_csv()`, `_export_timeline()`
-- **Fix**: Added `_export_check_overwrite()` helper that checks if the output file exists and prompts `Overwrite? [y/N]` before writing. Called in all four export format functions.
-
-### BUG-CLI-009 | `loki share` generates non-unique IDs
-- **Location**: `cmd_share()` gist description
-- **Fix**: Changed gist description timestamp from `%Y-%m-%d` (day granularity) to `%Y-%m-%dT%H:%M:%S` (second granularity) to avoid collisions when sharing multiple times per day.
-
-### BUG-CLI-010 | `loki config set` accepts any key without validation
-- **Location**: `cmd_config_set()` wildcard case
-- **Fix**: Changed from a warning that stores the value anyway to a hard error that lists valid keys and returns 1. Unknown keys are now rejected.
-
-### BUG-CLI-011 | `config_get` error handling
-- **Location**: `cmd_config_get()`
-- **Fix**: Wrapped the Python heredoc in a subshell capture with `|| { error; return 1; }` pattern to gracefully handle python3 failures without leaking state. Removed unnecessary `unset` of inline env vars.
-
-### BUG-CLI-008 (Medium) | `LOKI_DIR` not exported for Python heredocs
-- **Location**: Line 129
-- **Fix**: Added `export LOKI_DIR` immediately after assignment. This ensures all Python heredocs using `os.environ.get("LOKI_DIR", ".loki")` receive the correct value.
-
-### BUG-PAR-002 | `worktree list` branch pattern never matches
-- **Location**: `cmd_worktree()` list subcommand
-- **Fix**: Branch matching pattern changed from `loki-parallel-*` to match both `parallel-*` and `loki-parallel-*`. The actual branches created by `run.sh` use `parallel-<stream>` prefix (line 2130 of run.sh), not `loki-parallel-`.
-
-### BUG-PAR-010 | `worktree clean` doesn't kill running sessions
-- **Location**: `cmd_worktree()` clean subcommand
-- **Fix**: Before removing a worktree via `git worktree remove`, check for `.loki/loki.pid` in the worktree directory. If a session is running, send SIGTERM, wait 1 second, then SIGKILL if needed.
-
-## New Bugs Found and Fixed
-
-### NEW-CLI-001 | Division by zero in context percentage calculation
-- **Location**: `cmd_status()` and `_context_show()`
-- **Fix**: Added `if [ "$ctx_total" -gt 0 ]` / `if [ "$total_tokens" -gt 0 ]` guards before the `$((used * 100 / total))` arithmetic. If total is zero, percentage defaults to 0.
-
-### NEW-CLI-002 | Missing `loki web logs` subcommand
-- **Location**: `cmd_web()` case dispatch
-- **Fix**: Added `logs)` case to `cmd_web()` that displays Purple Lab server logs using `tail -n`. Defaults to 100 lines. Also checks home-based state dir and CWD-based fallback for log file location. Updated `cmd_web_help()` to list the `logs` subcommand.
-
-## Bugs Investigated But Not Fixed (Already Correct)
-
-### BUG-CLI-001 / BUG-CLI-002 | `--port` / `--prd` unbound variable
-- **Status**: Already fixed in current code. `cmd_web_start()` initializes `port="${PURPLE_LAB_DEFAULT_PORT}"` and `prd_file=""` before the argument parsing loop. The `--port` and `--prd` handlers properly check `${2:-}` before accessing `$2`.
-
-### BUG-CLI-004 | `--no-open` flag ignored
-- **Status**: Already working correctly. The `open_browser` variable is set to `false` by `--no-open` and checked with `if [ "$open_browser" = true ]` before any browser-open calls.
-
-### BUG-CLI-009 (Medium) | Empty array with `set -u` in `list_running_sessions`
-- **Status**: Already fixed. Uses `${sessions[@]+"${sessions[@]}"}` pattern throughout, which is the correct `set -u`-safe array expansion.
-
-### BUG-CMD-001 | `cmd_web` wildcard duplicates arguments
-- **Status**: Analyzed and found to be working correctly. The `*)` case properly shifts the subcommand-as-flag, then passes it along with remaining args to `cmd_web_start`.
-
-## Bugs Found But Not Fixed (Out of Scope or Extensive)
-
-### Missing `$2` guards in `shift 2` patterns
-- **Location**: Multiple argument parsers (e.g., `cmd_state query`, trigger config parsing)
-- **Issue**: Under `set -u`, if a flag like `--agent` is the last argument without a value, `$2` is unset, causing a crash. The pattern `shift 2 ;;` should be guarded with `${2:-}` checks.
-- **Impact**: Low -- only triggers on malformed user input.
-- **Scope**: 20+ occurrences across the file; would require systematic refactoring.
-
-### Remaining shell-expanded heredocs with `$variable` in `open()` calls
-- **Location**: Lines 3745, 8002, 9332, 10228, 10262, 12604, 16844, etc.
-- **Issue**: Double-quoted heredocs (`<< HEREDOC`) interpolate shell variables into Python `open()` calls. While the variables are internally-constructed paths (not user input), specially-crafted directory names with quotes could theoretically cause injection.
-- **Impact**: Very low -- would require the user to be working in a directory with Python metacharacters in its path.
-- **Scope**: 15+ occurrences; fixing all requires converting to single-quoted heredocs with env var passing.

package/docs/bug-fixes/agent-02-purplelab-fixes.md

@@ -1,88 +0,0 @@
-# Agent 02: Purple Lab Functional Testing - Bug Fix Report
-
-## Summary
-
-Audited `web-app/server.py` (5,679 lines) and all frontend components in `web-app/src/` (50 files).
-Fixed 8 bugs (3 security, 2 resource leaks, 2 race conditions, 1 missing validation).
-Verified all 13 bugs from BUG-AUDIT-v6.61.0 against the current codebase.
-
-## Bugs Fixed
-
-### FIX-1: `_save_secrets()` crashes when crypto module is missing (BUG-PL-013 related)
-- **File**: `web-app/server.py:2431`
-- **Severity**: Medium
-- **Problem**: `_save_secrets()` calls `from crypto import encrypt_value, encryption_available` without try/except ImportError. When the crypto module is not installed, saving any secret (POST /api/secrets) crashes with an unhandled ImportError. The counterpart `_load_secrets()` already handles this correctly.
-- **Fix**: Wrapped the crypto import in try/except ImportError with plaintext fallback, matching the pattern in `_load_secrets()`.
-
-### FIX-2: `fix_session` orphans child processes (BUG-PL-007 related)
-- **File**: `web-app/server.py:4203`
-- **Severity**: High
-- **Problem**: `run_fix()` in the `/api/sessions/{id}/fix` endpoint spawns a subprocess but never calls `_track_child_pid()` or `_untrack_child_pid()`. When `loki web stop` runs, these fix processes are not found in the tracking list and remain as orphans, consuming resources. The chat endpoint (`run_chat()`) correctly tracks and untracks -- this was a missed pattern.
-- **Fix**: Added `_track_child_pid(proc.pid)` after process creation and `_untrack_child_pid(proc.pid)` in the finally block.
-
-### FIX-3: Session history leaks full filesystem paths (BUG-PL-003 from task description)
-- **File**: `web-app/server.py:3411`
-- **Severity**: Medium (security/information disclosure)
-- **Problem**: `get_sessions_history()` returned `"path": str(entry)` which exposes full paths like `/Users/lokesh/purple-lab-projects/project-123`. In deployed scenarios this leaks the server's filesystem structure, username, and directory layout.
-- **Fix**: Replaced with sanitized relative paths using `~/` prefix (e.g., `~/purple-lab-projects/project-123`). This is safe because the session history path is display-only on the frontend.
-
-### FIX-4: `delete_session` leaks filesystem path in response
-- **File**: `web-app/server.py:3495`
-- **Severity**: Low (security/information disclosure)
-- **Problem**: `delete_session()` returned `"path": str(target)` in its response, exposing the full filesystem path to the client.
-- **Fix**: Changed to return `"session_id": session_id` instead.
-
-### FIX-5: `start_session` accepts arbitrary projectDir without validation
-- **File**: `web-app/server.py:2510`
-- **Severity**: High (security)
-- **Problem**: The `projectDir` field from StartRequest was used directly without any path validation. A malicious client could pass `/etc`, `/root`, or any system path, and the server would create directories and write PRD files there. The `onboard_session` endpoint already validates paths correctly.
-- **Fix**: Added validation ensuring user-supplied `projectDir` resolves to within the home directory, matching the pattern in `onboard_session`.
-
-### FIX-6: `create_session_file` missing content size limit (BUG-PL-005 from task description)
-- **File**: `web-app/server.py:3691`
-- **Severity**: Medium
-- **Problem**: `create_session_file()` (POST) accepts file content without any size validation. The sibling `save_session_file()` (PUT) correctly enforces a 1MB limit. A client could create arbitrarily large files via the POST endpoint.
-- **Fix**: Added `len(req.content.encode(...)) > 1_048_576` check matching the PUT endpoint.
-
-### FIX-7: `pause_session` and `resume_session` mutate state without lock
-- **File**: `web-app/server.py:2972, 2989`
-- **Severity**: Medium (race condition)
-- **Problem**: Both `pause_session()` and `resume_session()` read `session.running`, `session.process`, and write `session.paused` without holding `session._lock`. Concurrent pause/resume and stop operations could produce torn state. The `stop_session` and `start_session` endpoints correctly use `async with session._lock`.
-- **Fix**: Wrapped both endpoints' state access in `async with session._lock`.
-
-### FIX-8: `delete_secret` endpoint missing key format validation
-- **File**: `web-app/server.py:4340`
-- **Severity**: Low (defense in depth)
-- **Problem**: The `delete_secret()` endpoint accepts arbitrary strings as the `key` parameter without validation. While not exploitable (used only as dict key lookup), the `set_secret()` endpoint validates key format -- the inconsistency could mask bugs.
-- **Fix**: Added `re.match(r'^[A-Za-z_][A-Za-z0-9_]*$', key)` validation matching `set_secret()`.
-
-## Bugs from Audit Already Fixed in Current Codebase
-
-The following bugs from BUG-AUDIT-v6.61.0 were already fixed before this audit:
-
-| Bug ID | Description | Status |
-|--------|-------------|--------|
-| BUG-PL-001 | Dead code after `stop_session` return | Fixed: no early return, full cleanup runs |
-| BUG-PL-002 | `session.reset()` never called on stop | Fixed: `session.reset()` called at line 2742 |
-| BUG-PL-003 (audit) | Reader task sets `running=False` without lock | Fixed: uses `async with session._lock` at line 2361 |
-| BUG-PL-004 | Chat/fix missing secrets injection | Fixed: both endpoints call `_load_secrets()` |
-| BUG-PL-005 (audit) | Pause state never tracked | Fixed: `session.paused` set in both pause/resume |
-| BUG-PL-006 | `delete_session` can delete active session | Fixed: explicit active session check at line 3458 |
-| BUG-PL-009 | Project dir name collision (second-granularity) | Fixed: uses milliseconds (`time.time() * 1000`) |
-| BUG-PL-010 | `get_status` mutates `running` without lock | Fixed: uses local `is_running` variable, not session state |
-| BUG-PL-011 | Session history breaks after first non-empty dir | Fixed: no early `break` in history loop |
-| BUG-PL-012 | `cancel_chat` unhandled `TimeoutExpired` | Fixed: caught at line 4133 |
-
-## New Bugs Discovered (Beyond Audit)
-
-All bugs listed in the "Bugs Fixed" section above (FIX-1 through FIX-8) are new discoveries not covered by the original BUG-AUDIT-v6.61.0 for the Purple Lab category. FIX-1, FIX-2, FIX-5, FIX-6, FIX-7, and FIX-8 are entirely new findings.
-
-## Verification
-
-- Python syntax: `ast.parse()` passes on modified server.py
-- Frontend build: `npm run build` succeeds with no new errors
-- All changes are backward-compatible (no API contract changes except delete_session response field rename from `path` to `session_id`)
-
-## Files Modified
-
-- `web-app/server.py` -- 8 bug fixes (50 insertions, 26 deletions)

package/docs/bug-fixes/agent-03-dashboard-fixes.md

@@ -1,119 +0,0 @@
-# Agent 03: Dashboard API Functional Testing - Bug Fix Report
-
-## Scope
-File: `dashboard/server.py` (~5,259 lines, FastAPI)
-Focus: All API routes, WebSocket handlers, task board features, security audit
-
-## Bug Audit Status from BUG-AUDIT-v6.61.0.md
-
-### Already Fixed (verified in current codebase)
-
-| Bug ID | Description | Status |
-|--------|-------------|--------|
-| BUG-DASH-001 | Token creation endpoint has no authentication | FIXED - `require_scope("admin")` dependency at line 1719 |
-| BUG-DASH-002 | WebSocket rate-limit calls close() on unaccepted connection | FIXED - `accept()` then `close()` at lines 1396-1397 |
-| BUG-DASH-003 | WebSocket connection limit rejection enters receive loop | FIXED - `connect()` returns False, caller returns at line 1421-1422 |
-| BUG-DASH-004 | `create_project` doesn't validate tenant_id | FIXED - Tenant existence check + `Field(..., gt=0)` validation |
-| BUG-DASH-005 | `update_task` doesn't clear completed_at on reopen | FIXED - `completed_at = None` in else branch at line 1254 |
-| BUG-DASH-006 | Task state machine missing DONE transitions | FIXED - `DONE: {IN_PROGRESS, REVIEW}` at line 1316 |
-| BUG-DASH-009 | ProjectUpdate.status allows arbitrary strings | FIXED - `Literal["active", "archived", "completed", "paused"]` at line 179 |
-| BUG-DASH-010 | Audit log offset allows negative values | FIXED - `ge=0` constraint at line 1824 |
-| BUG-DASH-011 | Learning signals offset allows negative values | FIXED - `ge=0` constraint at line 2443 |
-| BUG-DASH-012 | WebSocket idle timeout doesn't call disconnect | FIXED - `finally: manager.disconnect(websocket)` at line 1469 |
-| BUG-DASH-013 | GET /api/tasks ignores project_id parameter | FIXED - Filter applied at lines 1132-1134 |
-
-### Not Applicable (code removed)
-
-| Bug ID | Description | Status |
-|--------|-------------|--------|
-| BUG-PL-001 | Dead code after stop_session return | N/A - Purple Lab code removed from server.py |
-| BUG-PL-002 | session.reset() never called on stop | N/A - Purple Lab code removed from server.py |
-| BUG-PL-003 | Reader task sets running=False without lock | N/A - Purple Lab code removed |
-| BUG-PL-004 | Chat/fix/auto-fix missing secrets injection | N/A - Purple Lab code removed |
-| BUG-PL-005 | Pause state never tracked | N/A - Purple Lab code removed |
-| BUG-PL-006 | delete_session can delete active directory | N/A - Purple Lab code removed |
-| BUG-PL-007 | Chat PIDs tracked but never untracked | N/A - Purple Lab code removed |
-| BUG-DS-002 | Auto-fix restart double-wraps command | N/A - Dev server code removed |
-| BUG-DS-003 | Overly broad port regex | N/A - Dev server code removed |
-| BUG-DS-004 | pip install into server's own environment | N/A - Dev server code removed |
-| BUG-DS-005 | Docker Compose port parsing crash | N/A - Dev server code removed |
-| BUG-DASH-007 | pause_session polling loop is dead code | N/A - pause_session rewritten (no polling loop) |
-
-## Fixes Applied in This Session
-
-### 1. BUG-DASH-008: `_safe_read_text` not truly safe (lines 95-101)
-
-**Problem**: `_safe_read_text` used `Path.read_text()` directly without exception handling. While `Path.read_text()` properly manages file handles (no leak), the function could raise `OSError` on permission errors or missing files. The "safe" name was misleading -- callers expected it to never raise.
-
-**Fix**: Wrapped in try/except to return empty string on any I/O error, making the function truly safe as its name implies.
-
-### 2. SECURITY: `/api/focus` POST/DELETE missing authentication (lines 1637, 1672)
-
-**Problem**: The `/api/focus` POST and DELETE endpoints had no auth dependency. Any network-reachable client could redirect the dashboard to read from an arbitrary project directory, potentially exposing data from other projects or causing the dashboard to process attacker-controlled state files.
-
-**Fix**:
-- Added `dependencies=[Depends(auth.require_scope("control"))]` to both POST and DELETE
-- Added validation requiring the target directory to contain a `.loki/` subdirectory to prevent pointing the dashboard at arbitrary filesystem locations
-- Changed to resolve path before checking, preventing TOCTOU issues
-
-### 3. SECURITY: `/api/enterprise/tokens` GET missing authentication (line 1766)
-
-**Problem**: The token listing endpoint had no auth dependency. When enterprise mode was enabled, any client could enumerate all API tokens (names, scopes, creation dates, expiration). While raw token values are not returned, the metadata exposure is still a security risk for token enumeration and scope discovery.
-
-**Fix**: Added `dependencies=[Depends(auth.require_scope("admin"))]` to require admin authentication.
-
-### 4. Deprecated `asyncio.get_event_loop()` in sync_registry (line 1600)
-
-**Problem**: Used `asyncio.get_event_loop()` which is deprecated in Python 3.10+ for getting the running loop from within an async function. This could cause `DeprecationWarning` or incorrect behavior in future Python versions.
-
-**Fix**: Changed to `asyncio.get_running_loop()` which is the correct API for async contexts.
-
-### 5. Input validation: timeRange parameters on learning endpoints (lines 2361, 2430, 2450)
-
-**Problem**: The `timeRange` parameters on `/api/learning/metrics`, `/api/learning/trends`, and `/api/learning/signals` accepted arbitrary strings with no validation. While `_parse_time_range()` handles invalid input gracefully (returns None), passing malformed strings wastes processing and could be used for fuzzing.
-
-**Fix**: Added `Query(..., pattern=r"^\d{1,4}[hdm]$")` constraint to validate format (1-4 digit number followed by h/d/m).
-
-### 6. Input validation: quality report format parameter (line 4970)
-
-**Problem**: The `format` parameter on `/api/quality-report` accepted any string, passing it to `rigour.export_report()`. Arbitrary format strings could cause unexpected behavior in the export function.
-
-**Fix**: Added `pattern="^(json|markdown|html)$"` constraint to limit to known formats.
-
-### 7. Input validation: migration start target and codebase_path (line 5048)
-
-**Problem**: The `start_migration` endpoint accepted `codebase_path` and `target` without type checking. Non-string values (lists, dicts) from JSON body would cause cryptic errors downstream.
-
-**Fix**: Added type validation (`isinstance` check for str) and length limit (255 chars) for `target`.
-
-## Security Audit Summary (OWASP Top 10)
-
-| OWASP Category | Status | Notes |
-|----------------|--------|-------|
-| A01: Broken Access Control | FIXED | Added auth to /api/focus, /api/enterprise/tokens |
-| A02: Cryptographic Failures | OK | Token generation uses `secrets` module |
-| A03: Injection | OK | SQLAlchemy ORM prevents SQL injection; list-form subprocess calls prevent shell injection; realpath + regex prevent path traversal |
-| A04: Insecure Design | FIXED | Focus endpoint now requires .loki/ subdirectory |
-| A05: Security Misconfiguration | OK | CORS restricted to localhost; default bind to 127.0.0.1; TLS optional |
-| A06: Vulnerable Components | N/A | Dependency audit out of scope |
-| A07: Auth Failures | OK | Rate limiting on sensitive endpoints; token management requires admin |
-| A08: Data Integrity | OK | Atomic file writes for state mutations (tmp + rename) |
-| A09: Logging Failures | OK | Audit logging on destructive operations (delete, stop, kill) |
-| A10: SSRF | MITIGATED | Focus endpoint restricted to dirs with .loki/ subdirectory |
-
-## Route Coverage Audit
-
-Verified all 100+ routes in server.py for:
-- Authentication requirements (auth scope dependencies)
-- Input validation (Pydantic models, Query constraints, regex patterns)
-- Error handling (try/except with proper HTTP status codes)
-- Rate limiting (control and read limiters)
-- Path traversal protection (realpath checks, SAFE_ID_RE regex)
-- Resource cleanup (WebSocket disconnect in finally block)
-
-## Verification
-
-```
-python3 -c "import ast; ast.parse(open('dashboard/server.py').read()); print('Syntax OK')"
-# Output: Syntax OK
-```