loki-mode 6.71.1 → 6.72.0

package/docs/bug-fixes/agent-10-e2e-fullstack-fixes.md

@@ -0,0 +1,102 @@
+# Agent 10: Full-Stack Project E2E Testing - Bug Fixes
+
+## Summary
+
+Audited all 21 PRD templates, the CLI `loki init` scaffolding system, the web-app file browser, and the file watcher subsystem. Found and fixed 12 bugs across templates, CLI, server, and tests.
+
+## Known Bugs Fixed
+
+### BUG-TPL-001: SaaS template references inconsistent NextAuth.js patterns
+- **File:** `templates/saas-starter.md`
+- **Issue:** Template specifies NextAuth.js v5 in tech stack but uses v4-style route pattern in API docs (`/api/auth/[...nextauth]` without mentioning the v5 `auth.ts` config approach).
+- **Fix:** Updated the OAuth route description to reference both the Auth.js v5 config file (`src/lib/auth.ts`) and the catch-all route, making the pattern consistent.
+
+### BUG-TPL-002: CLI template missing shebang and bin configuration
+- **File:** `templates/cli-tool.md`
+- **Issue:** The CLI tool template had no mention of `#!/usr/bin/env node` shebang, no `bin` field in package.json, and no tsup banner configuration. A CLI tool built from this template would fail on `npm install -g` because the entry point wouldn't be executable.
+- **Fix:** Added a "Package Configuration" section with the required `bin` field in package.json, the shebang requirement, and tsup `banner` configuration to auto-inject the shebang into compiled output.
+
+### BUG-TPL-003: Discord bot template missing environment variable handling
+- **File:** `templates/discord-bot.md`
+- **Issue:** Template referenced `dotenv` in tech stack and `.env.example` in project structure but never specified what environment variables are needed. The AI agent would have to guess `DISCORD_TOKEN`, `DISCORD_CLIENT_ID`, etc.
+- **Fix:** Added a comprehensive "Environment Variables" section with required vars (`DISCORD_TOKEN`, `DISCORD_CLIENT_ID`), optional vars (`DISCORD_GUILD_ID`, `LOG_CHANNEL_ID`, etc.), a complete `.env.example` template, and startup validation code.
+
+### BUG-PROJ-001: File tree too shallow for monorepo structures
+- **File:** `web-app/server.py` (line 2366)
+- **Issue:** `_build_file_tree()` had `max_depth=4`, which is insufficient for monorepo structures like `packages/frontend/src/components/ui/Button.tsx` (6 levels). Files beyond 4 levels were silently omitted from the file browser.
+- **Fix:** Increased `max_depth` from 4 to 8. Added a `MAX_CHILDREN=500` per-directory cap with a "... (N more items)" indicator to prevent memory issues on very large projects. Also added more noise directories to the ignore list: `vendor`, `.turbo`, `.nx`, `coverage`, `.parcel-cache`.
+
+### BUG-PROJ-002: File tree doesn't update after directory moves/renames
+- **File:** `web-app/server.py` (line 429)
+- **Issue:** The `FileChangeHandler.on_any_event()` method filtered directory events to only `("created", "deleted")`, dropping `"moved"` events. When the AI renamed or moved directories during development, the file tree in the browser would not update until a manual refresh.
+- **Fix:** Added `"moved"` to the allowed directory event types: `("created", "deleted", "moved")`.
+
+## Additional Bugs Discovered and Fixed
+
+### BUG-TPL-004: Phantom `saas-app` template entry (CRITICAL)
+- **Files:** `autonomy/loki` (line 7387), `tests/test-init-command.sh`
+- **Issue:** The `TEMPLATE_NAMES` array in `cmd_init()` contained `saas-app` which has no corresponding template file. Only `saas-starter.md` exists. This caused `loki init --template saas-app` to pass validation (the name is in the array) but then fail at file lookup with a confusing "Unknown template" error. The init tests were also broken, asserting `saas-app` in config.
+- **Fix:** Removed `saas-app` from the `TEMPLATE_NAMES` array, removed its label from `_get_template_label()`, updated the help text examples to reference `saas-starter`, updated the test file to use `saas-starter` in all 4 affected test cases.
+
+### BUG-TPL-005: REST API Auth template uses .js extensions with "TypeScript throughout"
+- **File:** `templates/rest-api-auth.md`
+- **Issue:** The template says "TypeScript throughout" in requirements but lists all files with `.js` extensions in the project structure. Also referenced `Jest + supertest` instead of `Vitest + supertest` (inconsistent with other templates).
+- **Fix:** Changed all file extensions from `.js` to `.ts` in the project structure, added `tsconfig.json` to the file tree, updated testing framework from "Jest + supertest" to "Vitest + supertest".
+
+### BUG-TPL-006: Templates missing environment variable specifications
+- **Files:** `templates/slack-bot.md`, `templates/rest-api.md`, `templates/rest-api-auth.md`
+- **Issue:** Templates referenced `.env.example` in their project structures but never specified what environment variables are needed. The autonomous agent would have to invent variable names and defaults.
+- **Fix:** Added "Environment Variables" sections with complete `.env.example` content and startup validation requirements to all three templates.
+
+### BUG-TPL-007: api-only README entry says Jest, template uses Vitest
+- **File:** `templates/README.md`
+- **Issue:** The README template gallery listed "Express, in-memory, Jest" for api-only.md but the actual template specifies Vitest.
+- **Fix:** Updated README to say "Vitest" instead of "Jest".
+
+### BUG-TPL-008: Template count mismatch across documentation
+- **Files:** `CLAUDE.md`, `autonomy/loki`
+- **Issue:** CLAUDE.md said "13 PRD templates" but there are 21. The loki CLI said "22 built-in template names" but there are 21 (after removing the phantom `saas-app`).
+- **Fix:** Updated CLAUDE.md to "21 PRD templates". Updated loki CLI comment to "21 built-in template names" and help text to "21 PRD templates".
+
+### BUG-TPL-009: 7 templates missing purpose footer
+- **Files:** `dashboard.md`, `data-pipeline.md`, `game.md`, `microservice.md`, `npm-library.md`, `slack-bot.md`, `web-scraper.md`
+- **Issue:** The README says every template should have a "Purpose Footer" explaining what it tests. 7 templates were missing this section entirely. Also missing: estimated execution time.
+- **Fix:** Added purpose footer with description and time estimate to all 7 templates.
+
+### BUG-TPL-010: static-landing-page missing Success Criteria
+- **File:** `templates/static-landing-page.md`
+- **Issue:** This template had no "Success Criteria" section and no "Testing" section, unlike all other templates. The autonomous agent would not know when to stop.
+- **Fix:** Added a "Success Criteria" section with 6 measurable criteria. Also added estimated time to the purpose footer.
+
+## Validation Results
+
+- `bash -n autonomy/loki` -- PASS
+- `python3 -c "ast.parse(open('web-app/server.py').read())"` -- PASS
+- `bash -n tests/test-init-command.sh` -- PASS
+- All 21 template markdown files have properly closed code blocks -- PASS
+- All 21 templates now have purpose footers with time estimates -- PASS
+- No remaining references to phantom `saas-app` template in source code -- PASS
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `web-app/server.py` | Fixed file watcher to handle directory moves; increased file tree depth to 8; added monorepo-friendly ignore list and child cap |
+| `autonomy/loki` | Removed phantom `saas-app` template; fixed template count (22->21); updated help text examples |
+| `tests/test-init-command.sh` | Updated 4 test cases from `saas-app` to `saas-starter` |
+| `templates/saas-starter.md` | Fixed NextAuth.js v5 route pattern reference |
+| `templates/cli-tool.md` | Added shebang, bin field, and tsup banner configuration |
+| `templates/discord-bot.md` | Added environment variables section with required/optional vars |
+| `templates/slack-bot.md` | Added environment variables section |
+| `templates/rest-api-auth.md` | Fixed .js to .ts extensions; added env vars section; fixed Jest to Vitest |
+| `templates/rest-api.md` | Added environment variables section |
+| `templates/README.md` | Fixed "Jest" to "Vitest" for api-only entry |
+| `templates/static-landing-page.md` | Added Success Criteria section and time estimate |
+| `templates/dashboard.md` | Added purpose footer |
+| `templates/data-pipeline.md` | Added purpose footer |
+| `templates/game.md` | Added purpose footer |
+| `templates/microservice.md` | Added purpose footer |
+| `templates/npm-library.md` | Added purpose footer |
+| `templates/slack-bot.md` | Added purpose footer |
+| `templates/web-scraper.md` | Added purpose footer |
+| `CLAUDE.md` | Fixed template count from 13 to 21 |

package/docs/bug-fixes/agent-11-e2e-session-fixes.md

@@ -0,0 +1,70 @@
+# Agent 11: Session Lifecycle E2E Testing - Bug Fixes
+
+## Summary
+
+Investigated and fixed 5 bugs in the session lifecycle (start, pause, resume, stop, restart, monitor). Also discovered and fixed 1 new bug. All 3 files modified pass syntax validation.
+
+## Bugs Fixed
+
+### BUG-ST-002: Pause signal not checked between quality gates
+- **File**: `autonomy/run.sh` (lines ~9811, ~9833)
+- **Problem**: Three quality gates (static analysis, test coverage, code review) run sequentially with no pause/stop check between them. If a user sends PAUSE during static analysis, execution continues through all remaining gates before the pause is processed on the next loop iteration. Code review alone can take 30+ seconds.
+- **Fix**: Added pause/stop file checks between each quality gate. If a signal is detected, partial gate failures are saved and `continue` exits to the main loop, which will handle the pause on the next iteration.
+
+### BUG-ST-004: Stop endpoint returns before processes are actually killed
+- **File**: `dashboard/server.py` (line ~2863, `stop_session()`)
+- **Problem**: The `/api/control/stop` endpoint sent SIGTERM via `os.kill(pid, 15)` and immediately returned `{"success": True, "message": "Stop signal sent"}`. The caller (dashboard UI) would show "stopped" while the process was still running and cleaning up. This could lead to users starting a new session while the old one was still shutting down.
+- **Fix**: Added `await asyncio.sleep(0.5)` polling loop (up to 5s) that waits for the process to actually exit. If the process doesn't exit gracefully within 5s, escalates to SIGKILL. Response now includes `process_stopped` boolean and accurate message ("Session stopped" vs "Stop signal sent").
+
+### BUG-ST-006: Resume doesn't validate checkpoint integrity
+- **File**: `autonomy/run.sh` (`load_state()` at line ~7956)
+- **Problem**: `load_state()` loaded `retryCount` and `iterationCount` from `autonomy-state.json` without validating that the file contained valid JSON or that the values were sane (non-negative integers). A corrupted or truncated state file (from a crash during save, disk full, etc.) could cause the shell to use non-numeric values, leading to arithmetic errors or infinite loops.
+- **Fix**: Added pre-validation step using Python that checks: (1) file is valid JSON, (2) `retryCount` and `iterationCount` are numeric, (3) values are non-negative. If validation fails, backs up the corrupted file with a `.corrupt.<timestamp>` suffix and starts fresh with count=0.
+
+### BUG-ST-007: Multiple concurrent pause signals cause state corruption
+- **File**: `autonomy/run.sh` (`handle_pause()` at line ~10111)
+- **Problem**: `handle_pause()` had no re-entrancy guard. If a signal handler triggered a second pause while one was already being handled (e.g., signal handler calling cleanup which checks pause state), two concurrent pause handlers could run, both trying to read/write PAUSE files and state. The function also did not save state on pause entry, so a crash during pause would lose the "paused" status.
+- **Fix**: Added `_PAUSE_IN_PROGRESS` guard flag (checked at entry, cleared at all exit paths). Added `save_state` call at pause entry so the "paused" status persists across crashes.
+
+### BUG-ST-008: Non-atomic session.json update in loki CLI
+- **File**: `autonomy/loki` (`cmd_stop()` at line ~1354)
+- **Problem**: While `run.sh` was already fixed to use atomic temp-file + `os.replace()` for session.json updates, the `loki` CLI `cmd_stop()` still used the old pattern: `f.seek(0); f.truncate(); json.dump(d, f)`. This is non-atomic -- if the process is killed between `truncate()` and the `json.dump()` completing, session.json is left empty or partially written. The next `loki status` would fail to parse it.
+- **Fix**: Replaced with the same atomic pattern used in `run.sh`: `tempfile.mkstemp()` + `json.dump()` + `os.replace()`.
+
+### BUG-ST-010 (NEW): ITERATION_COUNT spuriously incremented on pause resume
+- **File**: `autonomy/run.sh` (`run_autonomous()` main loop at line ~9313)
+- **Problem**: The main while loop incremented `ITERATION_COUNT` at the top of each iteration, BEFORE checking for pause/stop signals. When `check_human_intervention` returned 1 (pause handled, then resumed), the `continue` statement jumped back to the top of the loop, incrementing `ITERATION_COUNT` again without actually running an AI provider iteration. Same issue occurred with `check_budget_limit` returning true. Over a session with multiple pauses, this inflated the iteration count, causing premature `max_iterations_reached` exits and incorrect RARV tier selection.
+- **Fix**: Moved pause/stop and budget checks BEFORE the `ITERATION_COUNT++` increment. Now the count only increments when an actual iteration will execute.
+
+## Bugs Verified Already Fixed
+
+### BUG-ST-001: save_state not atomic
+- **Status**: Already fixed (line 7938). Uses temp file with PID suffix + `mv -f`.
+
+### BUG-ST-003: ITERATION_COUNT not restored on resume
+- **Status**: Already fixed (line 7964). Duplicate of BUG-RUN-003.
+
+### BUG-ST-005: Gate escalation PAUSE writes to wrong path
+- **Status**: Already fixed (line 9804). Writes to `${TARGET_DIR:-.}/.loki/PAUSE`.
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `autonomy/run.sh` | BUG-ST-002, BUG-ST-006, BUG-ST-007, BUG-ST-010 |
+| `autonomy/loki` | BUG-ST-008 |
+| `dashboard/server.py` | BUG-ST-004 |
+
+## Validation
+
+- `bash -n autonomy/run.sh` -- PASS
+- `bash -n autonomy/loki` -- PASS
+- `python3 -c "import ast; ast.parse(open('dashboard/server.py').read())"` -- PASS
+
+## Edge Cases Considered
+
+1. **Crash during save_state**: Atomic write via temp+mv means the file is either fully written or not written at all. No partial state.
+2. **Concurrent stop+pause**: The pause handler checks for STOP file in its wait loop. If both arrive simultaneously, STOP takes precedence (handle_pause returns 1, which maps to return 2/stop in check_human_intervention).
+3. **Disk full during session.json write**: `tempfile.mkstemp` will fail, caught by the `except (json.JSONDecodeError, OSError): pass` handler. The original file is untouched.
+4. **OOM kill during pause**: State is saved to "paused" status at pause entry. On restart, `load_state()` will restore the paused state and the session will resume from the correct iteration.
+5. **Rapid pause/resume cycling**: The `_PAUSE_IN_PROGRESS` guard prevents re-entrant pause handling. The iteration count fix prevents count inflation during rapid pause/resume cycles.

package/docs/bug-fixes/agent-12-scenario-fixes.md

@@ -0,0 +1,120 @@
+# Agent 12 Bug Fixes - Discovered During Scenario Writing
+
+Date: 2026-03-24 | Version: v6.71.1
+
+---
+
+## Bugs Fixed (5 fixes across 3 files)
+
+### 1. BUG-EP-012: Corrupted memory index/timeline not auto-recovered
+
+**File:** `memory/storage.py` (lines 170-192)
+**Severity:** Medium
+**Symptom:** If `.loki/memory/index.json` or `timeline.json` becomes corrupted (invalid JSON from a crash or disk error), all memory operations silently fail permanently. The `_ensure_index()` method only recreates the file when it does not exist, not when it exists but contains invalid JSON.
+
+**Fix:** Added JSON validity checks in `_ensure_index()` and `_ensure_timeline()`. When the file exists but is corrupted (JSONDecodeError), it is now logged and recreated from scratch. This restores memory system functionality without requiring manual file deletion.
+
+**Before:**
+```python
+def _ensure_index(self) -> None:
+    index_path = self.base_path / "index.json"
+    if not index_path.exists():
+        # ... create initial index
+```
+
+**After:**
+```python
+def _ensure_index(self) -> None:
+    index_path = self.base_path / "index.json"
+    needs_init = not index_path.exists()
+    if not needs_init:
+        try:
+            text = index_path.read_text(encoding="utf-8", errors="replace")
+            json.loads(text)
+        except (json.JSONDecodeError, OSError):
+            logging.getLogger(__name__).warning(
+                "Corrupted index.json detected, recreating from scratch"
+            )
+            needs_init = True
+    if needs_init:
+        # ... create initial index
+```
+
+---
+
+### 2. BUG-EP-015: Orphaned temp files accumulate after kill -9
+
+**Files:** `memory/storage.py`, `autonomy/run.sh`
+**Severity:** Low
+**Symptom:** When a process is killed with SIGKILL during an atomic write (temp file + rename), the temp file is left behind because the rename never completes. These `.tmp_*.json` files in the memory directory and `.tmp.*` files in `.loki/` accumulate indefinitely.
+
+**Fix (memory/storage.py):** Added `_cleanup_stale_tmp_files()` method that runs on MemoryStorage initialization. Removes `.tmp_*.json` files older than 5 minutes.
+
+**Fix (autonomy/run.sh):** Added cleanup in `load_state()` that runs `find .loki/ -name "*.tmp.*" -mmin +5 -delete` on session startup. This catches orphaned temp files from previous kill -9 events.
+
+---
+
+### 3. BUG-EC-013: Empty provider output silently treated as success
+
+**File:** `autonomy/run.sh` (after provider invocation, ~line 9691)
+**Severity:** Medium
+**Symptom:** When a provider returns exit code 0 but produces zero output (0 bytes in iter_output), the system treats it as a successful iteration. This wastes iterations -- the system continues to the next iteration without detecting that nothing happened. If the provider consistently returns empty output (broken prompt, API issue), the stagnation detector does not kick in for 5+ iterations.
+
+**Fix:** Added a post-invocation check: if `$iter_output` exists, is empty (0 bytes), and exit_code is 0, the exit_code is overridden to 1 with a warning log message. This ensures the iteration is treated as a failure, triggering appropriate retry/backoff logic.
+
+```bash
+# BUG-EC-013: Detect empty provider output (0 bytes = no work done)
+if [ -f "$iter_output" ] && [ ! -s "$iter_output" ] && [ $exit_code -eq 0 ]; then
+    log_warn "Provider returned empty output (0 bytes) despite exit code 0 -- treating as error"
+    exit_code=1
+fi
+```
+
+---
+
+### 4. BUG-EC-014: Quality gate subprocesses have no timeout
+
+**File:** `autonomy/run.sh` (enforce_test_coverage, ~line 5529)
+**Severity:** High
+**Symptom:** Test runner invocations (vitest, jest, mocha) inside quality gates have no timeout. A hanging test runner (e.g., waiting for user input, network timeout, infinite loop in tests) blocks the entire autonomous iteration indefinitely. The system becomes unresponsive.
+
+**Fix:** Wrapped all test runner invocations with the `timeout` command, defaulting to 300 seconds (5 minutes), configurable via `LOKI_GATE_TIMEOUT` environment variable. When the timeout fires, the test runner is killed and the gate reports failure, allowing the system to continue.
+
+```bash
+local gate_timeout="${LOKI_GATE_TIMEOUT:-300}"  # 5 minutes default
+output=$(cd "${TARGET_DIR:-.}" && timeout "$gate_timeout" npx vitest run --reporter=json 2>&1) || test_passed=false
+```
+
+---
+
+## Bugs Identified But Not Fixed (4 bugs, require design decisions)
+
+### BUG-EP-004: check_provider_health() validates key exists, not validity
+- **Location:** run.sh:6864
+- **Reason not fixed:** Validating key validity requires an API call to each provider, which has cost/rate-limit implications. Requires design decision on whether to add a lightweight health check endpoint call.
+
+### BUG-CU-002: No automatic dashboard port increment
+- **Location:** run.sh dashboard startup
+- **Reason not fixed:** Changing port allocation logic requires coordination between the dashboard server, the CLI status display, and the web frontend (which connects to a hardcoded port). Needs design discussion on port discovery mechanism.
+
+### BUG-CU-005: Export reads state files without cross-file consistency
+- **Location:** loki:5034
+- **Reason not fixed:** True cross-file consistency requires either a snapshot mechanism or a single monolithic state file. The current multi-file approach is by design for performance. Low impact since export is typically used after pausing.
+
+### BUG-EC-002: No PRD size limit or truncation before context injection
+- **Location:** run.sh build_prompt
+- **Reason not fixed:** The PRD is passed as a file path reference, not inline content. Truncation would lose requirements. The AI provider handles context window overflow. However, a warning for very large PRDs (> 50KB) would be useful.
+
+---
+
+## Test Impact
+
+The fixes touch three files:
+1. `memory/storage.py` - Memory system initialization (covered by `tests/test-memory-engine.sh`, `tests/test-unified-memory.sh`)
+2. `autonomy/run.sh` - Core orchestration loop (covered by `tests/test-state-recovery.sh`, `tests/test-v6-features.sh`)
+
+All fixes are backward-compatible:
+- Memory corruption recovery only triggers on actual corruption (no behavioral change for healthy systems)
+- Temp file cleanup only removes files older than 5 minutes (safe with concurrent processes)
+- Empty output detection is a strict subset (only overrides exit_code when output is literally 0 bytes AND exit was 0)
+- Quality gate timeout defaults to 5 minutes (longer than any reasonable test suite; configurable via env var)

package/docs/bug-fixes/agent-13-enterprise-fixes.md

@@ -0,0 +1,143 @@
+# Agent 13 - Enterprise Bug Fixes
+
+Bugs discovered during enterprise scenario writing. Each includes root cause
+analysis, affected files, and applied fix (where applicable).
+
+---
+
+## BUG-E01: Helm Chart appVersion Severely Out of Date
+
+**Severity:** Medium
+**Status:** Fixed
+
+**Description:**
+The Helm chart `Chart.yaml` has `appVersion: "5.52.0"` while the actual product
+version is `6.71.1`. This means `helm install` without an explicit `--set image.tag`
+will pull the Docker image tagged `5.52.0`, which is 119+ minor versions behind.
+The `_helpers.tpl` `autonomi.image` template defaults to `Chart.appVersion` when
+`image.tag` is empty, so this directly affects production deployments.
+
+**Root Cause:**
+The Helm chart `appVersion` is not included in the 14-location version bump
+checklist in CLAUDE.md. It has drifted since the chart was first created.
+
+**Affected Files:**
+- `deploy/helm/autonomi/Chart.yaml` (line 6)
+
+**Fix Applied:**
+Updated `appVersion` from `"5.52.0"` to `"6.71.1"`.
+
+---
+
+## BUG-E02: automountServiceAccountToken Conflict
+
+**Severity:** Low
+**Status:** Documented (intentional override but inconsistent intent)
+
+**Description:**
+The ServiceAccount template (`serviceaccount.yaml:12`) sets
+`automountServiceAccountToken: false` (security best practice -- do not mount
+the SA token unless needed). However, the controlplane deployment template
+(`deployment-controlplane.yaml:29`) explicitly sets
+`automountServiceAccountToken: true` at the pod spec level. The pod-level
+setting overrides the SA-level setting, so the token IS mounted in controlplane
+pods.
+
+The worker deployment does NOT set `automountServiceAccountToken` at the pod
+level, so it inherits the SA-level `false` setting. This means:
+- Controlplane pods: SA token IS mounted (explicit true)
+- Worker pods: SA token is NOT mounted (inherits SA false)
+
+This is likely intentional (controlplane needs K8s API access for the RBAC role
+to query pods/logs/configmaps/events), but the inconsistency should be
+documented. If the controlplane needs the token, the SA-level `false` is
+misleading.
+
+**Affected Files:**
+- `deploy/helm/autonomi/templates/serviceaccount.yaml` (line 12)
+- `deploy/helm/autonomi/templates/deployment-controlplane.yaml` (line 29)
+
+**Recommendation:**
+Add a comment in `serviceaccount.yaml` explaining that the controlplane
+overrides this at the pod level. Alternatively, make the SA-level setting
+configurable via values.yaml.
+
+---
+
+## BUG-E03: Agent Card Reports "sso": false Despite OIDC Implementation
+
+**Severity:** Low
+**Status:** Fixed
+
+**Description:**
+The A2A Agent Card endpoint (`GET /.well-known/agent.json`) in
+`dashboard/server.py:516` hardcodes `"sso": False` in the enterprise
+capabilities section. However, OIDC/SSO support is fully implemented in
+`dashboard/auth.py` with:
+- OIDC issuer discovery
+- JWKS key fetching and caching
+- JWT validation (with PyJWT when available)
+- Support for Okta, Azure AD, Google Workspace
+
+The `sso` field should dynamically reflect whether OIDC is configured.
+
+**Affected Files:**
+- `dashboard/server.py` (line 516)
+
+**Fix Applied:**
+Changed `"sso": False` to `"sso": auth.is_oidc_mode()` so the agent card
+accurately reflects the current OIDC configuration state.
+
+---
+
+## BUG-E04: Worker Deployment Missing Audit Logs Volume Mount
+
+**Severity:** Low
+**Status:** Documented
+
+**Description:**
+The controlplane deployment mounts both `checkpoints` and `audit-logs` volumes
+(lines 79-86 in deployment-controlplane.yaml). The worker deployment only
+mounts `checkpoints` (lines 73-77 in deployment-worker.yaml). If workers
+perform any audit-worthy actions that write to the audit log path
+(`/data/audit/audit.log`), those writes will fail silently or go to the
+ephemeral container filesystem.
+
+This may be intentional (only the controlplane/dashboard writes audit logs),
+but if RARV iteration actions should be audited at the worker level, the
+volume mount is needed.
+
+**Affected Files:**
+- `deploy/helm/autonomi/templates/deployment-worker.yaml` (missing audit volume mount)
+
+**Recommendation:**
+If workers should write audit logs, add the audit-logs volume mount. If only
+the controlplane audits, add a comment in the worker template explaining the
+intentional omission.
+
+---
+
+## BUG-E05: Helm Test test-health.yaml Expects python3 in curl Image
+
+**Severity:** Medium
+**Status:** Fixed
+
+**Description:**
+The Helm test `test-health.yaml` uses the `curlimages/curl:8.5.0` image and
+attempts to pipe the API response through `python3 -c "import sys, json;
+json.load(sys.stdin)"`. The `curlimages/curl` image is Alpine-based and does
+NOT include Python. The test will always fail at the JSON validation step.
+
+The fallback `grep -q '{'` check partially compensates, but the logic flow is
+incorrect: the `||` chain means it tries python3 first, and if python3 is not
+found (exit code 127), it falls through to grep. This works accidentally but
+is fragile and misleading.
+
+**Affected Files:**
+- `deploy/helm/autonomi/tests/test-health.yaml` (line 22-23)
+
+**Fix Applied:**
+Replaced the python3 JSON validation with a pure-shell approach that only uses
+tools available in the curl image (grep for JSON structure verification).
+
+---

package/docs/bug-fixes/agent-14-uat-newuser-fixes.md

@@ -0,0 +1,88 @@
+# Agent 14: First-Time User Acceptance Testing -- Bug Fixes
+
+**Date:** 2026-03-24
+**Scope:** Full first-time user journey audit (install through first build)
+**Files Modified:** `autonomy/loki`, `docs/INSTALLATION.md`, `README.md`
+
+---
+
+## Bugs Fixed
+
+### BUG-FTU-001: `loki init` does not tell user to set up AI provider
+**Severity:** High -- first-time users scaffold a project but have no idea they need a provider CLI
+**Location:** `autonomy/loki`, `cmd_init()` (line ~7793)
+**Fix:** Added post-scaffold check that detects whether any AI provider CLI (claude, codex, gemini, cline, aider) is installed. If none found, prints clear installation instructions and suggests running `loki doctor`.
+
+### BUG-FTU-002: `loki web` opens browser before server is ready
+**Severity:** Medium -- user sees a blank page or connection refused on first launch
+**Location:** `autonomy/loki`, `cmd_web_start()` (line ~3336)
+**Root Cause:** The readiness loop (`curl` against `/api/session/status`) ran up to 15 retries, but its result was never checked. The browser opened regardless of whether the server actually responded.
+**Fix:** Track readiness in a `server_ready` boolean. Only open browser when `server_ready=true`. If the server is still starting, print a message telling the user to open the URL manually or refresh.
+
+### BUG-FTU-003: `loki quick` with no provider CLI gives unhelpful error
+**Severity:** High -- user sees a cryptic `run.sh` error instead of actionable guidance
+**Location:** `autonomy/loki`, `cmd_quick()` (line ~7050)
+**Fix:** Added pre-flight provider CLI check before `exec "$RUN_SH"`. If the provider CLI is missing, prints the specific install command for that provider (e.g., `npm install -g @anthropic-ai/claude-code` for claude).
+
+### BUG-FTU-005: `loki start` with no provider CLI gives unhelpful error
+**Severity:** High -- same root cause as BUG-FTU-003 but for the main `start` command
+**Location:** `autonomy/loki`, `cmd_start()` (line ~1095)
+**Fix:** Added pre-flight provider CLI check before `exec "$RUN_SH"`. Clear error message with install command.
+
+### BUG-FTU-006: `loki doctor` does not check API keys or "no provider at all"
+**Severity:** Medium -- doctor gives green output even when no provider is usable
+**Location:** `autonomy/loki`, `cmd_doctor()` (line ~5902)
+**Fix:** Added two new sections to doctor output:
+1. After listing all provider CLIs, check if zero providers are installed and show a FAIL with install instructions.
+2. New "API Keys" section showing status of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`. For provider CLIs that use their own login sessions, a note is shown instead of a failure.
+
+### BUG-FTU-004/BUG-FTU-007: INSTALLATION.md contains inaccurate references
+**Severity:** Medium -- confuses new users with nonexistent paths
+**Location:** `docs/INSTALLATION.md`
+**Fixes:**
+- **Wrong license**: File structure section claimed "MIT License" but actual license is "Business Source License 1.1". Fixed.
+- **Wrong directory**: Referenced `examples/` directory (which does not exist) instead of `templates/`. Fixed to show `templates/` with accurate description.
+- **Broken next steps**: "Next Steps" section referenced `./autonomy/run.sh examples/simple-todo-app.md` which is a path that does not exist. Replaced with the standard workflow: `loki doctor` -> `loki init` -> `loki start`.
+- **Stale note**: "Some files/directories (autonomy, tests, examples)" changed to "templates".
+- **Broken relative link**: `[README.md](README.md)` from `docs/` should be `[README.md](../README.md)`. Fixed.
+
+---
+
+## README.md Improvements
+
+### Improved "Get Started in 30 Seconds" section
+**Problem:** The quick start jumped directly from `npm install` to `loki start ./prd.md` without explaining where a first-time user gets a PRD file. This was a dead end for anyone who does not already have a PRD.
+**Fix:** Added `loki init my-app --template simple-todo-app` and `cd my-app` steps to bridge the gap. Also added a `loki quick` alternative for users who want to skip PRD creation entirely.
+
+---
+
+## Bugs Verified as Already Fixed
+
+### BUG-CLI-001: `--port` flag crashes (unbound variable)
+**Status:** Already fixed in current codebase.
+**Evidence:** Both `cmd_web_start()` and `cmd_dashboard_start()` properly guard the `--port` flag with `[[ -z "${2:-}" ]]` checks and have default port variables (`PURPLE_LAB_DEFAULT_PORT=57375`, `DASHBOARD_DEFAULT_PORT=57374`). All port references use `${LOKI_DASHBOARD_PORT:-57374}` pattern. No unbound variable risk.
+
+---
+
+## New Bugs Discovered (Not Fixed -- Documenting Only)
+
+### BUG-FTU-008: `INSTALLATION.md` "What's New" section is stale
+The section header says "What's New in v6.7.0" but the current version is v6.71.1. The content describes features from v5.15.0 through v6.1.0 -- all many versions old. This misleads first-time users about the product's current state. Recommendation: either update to show recent highlights or remove version-specific "what's new" content from the installation guide entirely (it belongs in the CHANGELOG).
+
+### BUG-FTU-009: `loki doctor` providers all marked "optional"
+All five AI providers show as "optional" in doctor output. For a first-time user, this implies none of them are needed, when in fact at least one is required for any functionality. The fix added above (checking for zero providers) mitigates this, but the individual items could be marked "at least one required" for clarity.
+
+---
+
+## Test Matrix
+
+| Journey Step | Before | After |
+|---|---|---|
+| `loki init my-app` with no provider CLI | No guidance | Prints install instructions |
+| `loki start prd.md` with no provider CLI | Cryptic run.sh error | Clear error with install command |
+| `loki quick "task"` with no provider CLI | Cryptic run.sh error | Clear error with install command |
+| `loki web` on slow server start | Browser opens to blank page | Browser deferred; user told to refresh |
+| `loki doctor` with no providers | All green (misleading) | Explicit FAIL + API key section |
+| INSTALLATION.md file structure | References nonexistent `examples/` | References correct `templates/` |
+| INSTALLATION.md license | Claims MIT | Correctly says BSL 1.1 |
+| README.md quick start | Assumes user has a PRD | Guides through `loki init` |