From 37a9584d0c14effa54a732adfb1942279fffeb34 Mon Sep 17 00:00:00 2001
From: mblanke <mblanke@gmail.com>
Date: Mon, 23 Feb 2026 14:22:17 -0500
Subject: [PATCH] docs: update changelog and add robust dev-up startup script

---
 scripts/dev-up.ps1 | 58 ++++++++++++++++++++++++++++++++++++++++++++++
 update.md          | 58 +++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 scripts/dev-up.ps1

diff --git a/scripts/dev-up.ps1 b/scripts/dev-up.ps1
new file mode 100644
index 0000000..e046a22
--- /dev/null
+++ b/scripts/dev-up.ps1
@@ -0,0 +1,58 @@
+param(
+    [switch]$Build,
+    [switch]$BackendOnly,
+    [int]$HealthTimeoutSeconds = 60
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Write-Step([string]$msg) {
+    Write-Host "`n=== $msg ===" -ForegroundColor Cyan
+}
+
+function Wait-Http200([string]$url, [int]$timeoutSeconds) {
+    $sw = [System.Diagnostics.Stopwatch]::StartNew()
+    while ($sw.Elapsed.TotalSeconds -lt $timeoutSeconds) {
+        try {
+            $resp = Invoke-WebRequest -Uri $url -UseBasicParsing -TimeoutSec 5
+            if ($resp.StatusCode -eq 200) { return $true }
+        } catch {}
+        Start-Sleep -Seconds 2
+    }
+    return $false
+}
+
+Write-Step 'Starting containers'
+$composeArgs = if ($BackendOnly) { 'up -d backend' } else { 'up -d' }
+if ($Build) { $composeArgs = $composeArgs.Replace('up -d', 'up -d --build') }
+
+# Use cmd wrapper to safely allow merged output while preserving exit code semantics.
+cmd /c "docker compose $composeArgs 2>&1"
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "docker compose failed with exit code $LASTEXITCODE"
+    exit $LASTEXITCODE
+}
+
+Write-Step 'Container status'
+docker compose ps
+
+Write-Step 'Health checks'
+$backendOk = Wait-Http200 -url 'http://localhost:8000/openapi.json' -timeoutSeconds $HealthTimeoutSeconds
+$frontendOk = if ($BackendOnly) { $true } else { Wait-Http200 -url 'http://localhost:3000/' -timeoutSeconds $HealthTimeoutSeconds }
+
+if (-not $backendOk) {
+    Write-Error 'Backend health check failed: http://localhost:8000/openapi.json did not return HTTP 200 in time.'
+    exit 1
+}
+if (-not $frontendOk) {
+    Write-Error 'Frontend health check failed: http://localhost:3000/ did not return HTTP 200 in time.'
+    exit 1
+}
+
+Write-Step 'All good'
+Write-Host 'Backend:  http://localhost:8000/openapi.json (OK)' -ForegroundColor Green
+if (-not $BackendOnly) {
+    Write-Host 'Frontend: http://localhost:3000/ (OK)' -ForegroundColor Green
+}
+exit 0
+
diff --git a/update.md b/update.md
index c278fe2..b6eaf54 100644
--- a/update.md
+++ b/update.md
@@ -38,4 +38,60 @@
 | With logged-in users | N/A | **43** (real names only) |
 | OS detected | None | **Windows 10** (inferred from hostnames) |
 | Deduplication | None (same host  20 datasets) | **Full** (by FQDN/ClientId) |
-| System account filtering | None | **DWM-*, UMFD-*, LOCAL/NETWORK SERVICE removed** |
\ No newline at end of file
+| System account filtering | None | **DWM-*, UMFD-*, LOCAL/NETWORK SERVICE removed** |
+## 2026-02-23: Agent Execution Controls, Learning Mode, and Dev Startup Hardening
+
+### Agent Assist: Explicit Execution + Learning Controls
+- **Problem**: Agent behavior was partly implicit (intent-triggered execution only), with no analyst override to force/disable execution and no explicit "learning mode" explainability toggle.
+- **Solution**:
+  - Added `execution_preference` to assist requests (`auto | force | off`).
+  - Added `learning_mode` flag for analyst-friendly explanations and rationale.
+  - Preserved deterministic execution path for policy-domain scans while allowing explicit override.
+
+#### Backend Updates
+- `backend/app/api/routes/agent_v2.py`
+  - Extended `AssistRequest` with `execution_preference` and `learning_mode`.
+  - Added `_should_execute_policy_scan(request)` helper:
+    - `off`: advisory-only (never execute scan)
+    - `force`: execute scan regardless of query phrasing
+    - `auto`: existing intent-based policy execution behavior
+  - Wired `learning_mode` into agent context calls.
+- `backend/app/agents/core_v2.py`
+  - Extended `AgentContext` with `learning_mode: bool`.
+  - Prompt construction now adds analyst-teaching/explainability guidance when enabled.
+
+#### Frontend Updates
+- `frontend/src/api/client.ts`
+  - Extended `AssistRequest` with `execution_preference` and `learning_mode`.
+  - Extended `AssistResponse` with optional `execution` payload.
+- `frontend/src/components/AgentPanel.tsx`
+  - Added Execution selector (`Auto`, `Force execute`, `Advisory only`).
+  - Added `Learning mode` switch.
+  - Added execution results accordion (scope, datasets, top domains, hit count, elapsed).
+  - Cleaned stream update logic to avoid loop-closure lint warnings.
+
+#### Tests and Validation
+- `backend/tests/test_agent_policy_execution.py`
+  - Added regression tests for:
+    - `execution_preference=off` (stays advisory)
+    - `execution_preference=force` (executes scanner)
+- Validation:
+  - Backend tests: `test_agent_policy_execution.py` passed.
+  - Frontend build: clean compile after warning cleanup.
+
+### Frontend Warning Cleanup
+- `frontend/src/components/AnalysisDashboard.tsx`
+  - Removed unused `DeleteIcon` import.
+- `frontend/src/components/MitreMatrix.tsx`
+  - Fixed `useCallback` dependency warning by including `huntList`.
+
+### Dev Reliability: Docker Compose Startup on PowerShell
+- **Problem**: Intermittent `docker compose up -d 2>&1` exit code `1` despite healthy/running containers.
+- **Root Cause**: PowerShell `2>&1` handling can surface `NativeCommandError` for compose stderr/progress output (false failure signal).
+- **Solution**:
+  - Added `scripts/dev-up.ps1` startup helper to:
+    - run compose with stable output handling,
+    - show container status,
+    - verify backend/frontend readiness,
+    - return actionable exit codes.
+  - Updated backend liveness probe to `http://localhost:8000/openapi.json` (current app does not expose `/health`).