chore(release): 1.18.4 [skip ci]

## [1.18.4](https://github.com/asepharyana/zesdex/compare/v1.18.3...v1.18.4) (2026-08-27)

### Performance Improvements

* **tui:** render streaming token secara inkremental + kurangi redraw sia-sia ([2717216](https://github.com/asepharyana/zesdex/commit/271721694beb62e9fa5ff932312b293aa1d56823))

.claude/skills/commit-convention/SKILL.md

@@ -1,47 +0,0 @@
----
-name: commit-convention
-description: Conventional Commits format and version-bump rules for this repo (Bahasa Indonesia commit style). Use when creating a git commit in zesdex.
----
-
-# Commit Convention
-
-Gunakan **Conventional Commits** untuk semua commit. Format:
-
-```
-<type>(<scope>): <description>
-```
-
-**Type & efek ke versi:**
-
-| Type        | Bump  | Kapan pakai                              |
-|-------------|-------|------------------------------------------|
-| `feat`      | minor | Fitur baru                               |
-| `fix`       | patch | Perbaikan bug                            |
-| `chore`     | patch | Maintenance, update deps, dll            |
-| `docs`      | patch | Perubahan dokumentasi/comment            |
-| `refactor`  | patch | Refactor kode tanpa perubahan fungsional |
-| `test`      | patch | Nambah/ubah test                         |
-| `style`     | patch | Formatting, whitespace, lint             |
-| `perf`      | patch | Optimasi performa                        |
-| `ci`        | patch | Perubahan CI/CD                          |
-
-**Catatan:**
-- **Semua type menghasilkan release** (patch minimal). Tidak ada commit yang "skip release".
-- Tambahkan `BREAKING CHANGE:` di body commit untuk bump **major**.
-- **Scope** opsional, tapi direkomendasikan (misal `feat(agent):`, `fix(ipc):`).
-
-### Contoh
-
-```
-feat(tool): add batch file delete
-
-chore: bump reqwest to 0.12
-
-refactor(harness): flatten guard pipeline
-
-fix(ipc): reconnect loop on socket timeout
-
-docs: add architecture diagram to README
-
-BREAKING CHANGE: IPC frame header changed from 4-byte to 8-byte length
-```

.dockerignore

@@ -0,0 +1,26 @@
+# Rust build artifacts
+target/
+
+# VCS
+.git/
+.gitignore
+
+# Local/secret files
+.env
+.env.*
+!.env.example
+
+# Editor
+.idea/
+.vscode/
+*.swp
+
+# Nix
+result
+result-*
+
+# Kilo metadata
+.kilo/
+
+# Docs lessons
+docs/lesson/

.github/workflows/ci.yml

@@ -21,11 +21,11 @@ jobs:
         with:
           components: clippy
 
-      - name: Build
-        run: cargo build --release
+      - name: Format check
+        run: cargo fmt --all -- --check
 
-      - name: Test
-        run: cargo test
+      - name: Clippy workspace
+        run: cargo clippy --workspace --all-targets -- -D warnings
 
-      - name: Clippy
-        run: cargo clippy -- -D warnings
+      - name: Test workspace
+        run: cargo test --workspace

.github/workflows/deploy.yml

@@ -0,0 +1,61 @@
+name: Build & Deploy (Nix)
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: deploy
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  VPS_HOST: ${{ secrets.VPS_HOST }}
+  VPS_USER: ${{ secrets.VPS_USER }}
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v22
+        with:
+          determinate: false
+          extra-conf: |
+            sandbox = false
+            accept-flake-config = true
+
+      - name: Cache Nix
+        uses: DeterminateSystems/magic-nix-cache-action@v14
+
+      - name: Build zesdex
+        id: build
+        run: |
+          nix build .#default --impure --option sandbox false --print-build-logs
+          STORE_PATH=$(readlink result)
+          echo "store-path=$STORE_PATH" >> "$GITHUB_OUTPUT"
+          echo "Build OK: $STORE_PATH"
+
+      - name: Setup SSH key
+        env:
+          SSH_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          echo "$SSH_KEY" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          sed -i 's/\r$//' ~/.ssh/id_ed25519
+          ssh-keygen -y -f ~/.ssh/id_ed25519 >/dev/null 2>&1 || { echo "SSH key invalid"; exit 1; }
+          ssh-keyscan -H "$VPS_HOST" >> ~/.ssh/known_hosts 2>/dev/null
+
+      - name: Deploy zesdex to VPS
+        run: |
+          STORE_PATH="${{ steps.build.outputs.store-path }}"
+          ssh "$VPS_USER@$VPS_HOST" "nix copy --to file:///nix/store $STORE_PATH && nix-env --install --force $STORE_PATH --profile /nix/var/nix/profiles/zesdex && systemctl restart zesdex"

.github/workflows/flakehub-publish-rolling.yaml

@@ -0,0 +1,20 @@
+name: Publish to FlakeHub
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  flakehub-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+      - uses: DeterminateSystems/determinate-nix-action@main
+      - uses: DeterminateSystems/flakehub-push@main
+        with:
+          visibility: public
+          rolling: true

.github/workflows/release.yml

@@ -20,10 +20,10 @@ jobs:
         uses: actions-rust-lang/setup-rust-toolchain@v1
 
       - name: Build
-        run: cargo build --release
+        run: cargo build --release --workspace
 
       - name: Test
-        run: cargo test
+        run: cargo test --workspace
 
   release:
     name: Semantic Release

.gitignore

@@ -6,3 +6,4 @@ package.json
 package-lock.json
 .superpowers/
 docs/lesson/
+.kilo/

.releaserc.json

@@ -0,0 +1,18 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    ["@semantic-release/exec", {
+      "prepareCmd": "sed -i 's/^version = \"[^\"]*\"/version = \"${nextRelease.version}\"/' Cargo.toml && cargo check"
+    }],
+    ["@semantic-release/git", {
+      "assets": ["Cargo.toml", "CHANGELOG.md"],
+      "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+    }],
+    ["@semantic-release/github", {
+      "assets": []
+    }]
+  ]
+}

.reports/codemap-diff.txt

@@ -1,20 +0,0 @@
-Codemap Update Report — 2026-07-12
-====================================
-
-Status: FIRST GENERATION (no previous codemaps to compare)
-
-Files created:
-  - docs/CODEMAPS/architecture.md (new)
-  - docs/CODEMAPS/backend.md (new)
-  - docs/CODEMAPS/frontend.md (new)
-  - docs/CODEMAPS/data.md (new)
-  - docs/CODEMAPS/dependencies.md (new)
-
-Source scanned:
-  - 124 Rust source files
-  - 30 directories
-  - 103 modules
-  - 10,402 lines total
-
-No previous codemaps found — diff calculation skipped.
-Freshness: all documents generated 2026-07-12.

AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md
+
+This file provides guidance to Kilo when working with code in the zesdex repository.
+
+## Best Practice Conventions
+
+Zesdex follows Kana Engineering Best Practices:
+
+1. **Clean Architecture** — Strict domain/application/infrastructure/presentation layering.
+   - Domain has ZERO framework dependencies.
+   - Application depends only on domain.
+   - Infrastructure implements domain traits.
+   - DTOs cross layer boundaries, NOT entities.
+
+2. **Clean Code** — Functions under ~40 lines, one level of abstraction per function, descriptive names, no flag arguments, no commented-out code.
+
+3. **Documentation** — Every pub fn, struct, enum, and trait needs a doc comment (///) explaining what, flow, why, and return value.
+
+4. **Commit Convention** — Conventional Commits in Bahasa Indonesia: `feat(scope):`, `fix(scope):`, `chore:`, `docs:`.
+
+5. **Error Handling** — `anyhow::Result` and `anyhow::bail!` throughout. Log with `tracing` (never stderr).
+
+6. **Testing** — `#[cfg(test)] mod tests` blocks inline in production files. Tests are F.I.R.S.T. (Fast, Independent, Repeatable, Self-validating, Timely).
+
+7. **No Compiler Bypasses** — Never use `#[allow(...)]`, `#[expect(...)]`, or `#[allow(dead_code)]`. Fix the underlying code.
+
+8. **Boy Scout Rule** — Leave every module cleaner than you found it.
+
+## Available Agents
+
+- `@rust-engineer` — Rust clean architecture specialist (subagent).
+- `@code-reviewer` — Code review specialist (subagent).
+
+## Available Commands
+
+- `/check` — Run cargo check, clippy, and tests.
+- `/audit` — Code quality audit against clean-architecture best practices.
+- `/doc` — Generate or update doc comments.

CHANGELOG.md

@@ -1,3 +1,123 @@
+## [1.18.4](https://github.com/asepharyana/zesdex/compare/v1.18.3...v1.18.4) (2026-08-27)
+
+
+### Performance Improvements
+
+* **tui:** render streaming token secara inkremental + kurangi redraw sia-sia ([2717216](https://github.com/asepharyana/zesdex/commit/271721694beb62e9fa5ff932312b293aa1d56823))
+
+## [1.18.3](https://github.com/asepharyana/zesdex/compare/v1.18.2...v1.18.3) (2026-08-27)
+
+
+### Bug Fixes
+
+* **api:** cegah race condition pada register users.json (TOCTOU) ([884b19c](https://github.com/asepharyana/zesdex/commit/884b19ccb5fbcaa6b29cb41dc978386cf7b1b3f9))
+* **api:** perbaiki keamanan auth & WebSocket, tambah rate limiting ([6db00b2](https://github.com/asepharyana/zesdex/commit/6db00b22663839a6a975ae978058b894900c71de))
+* **build:** perbaiki referensi paket zesdex-gateway dan sinkronisasi versi nix ([6d3f491](https://github.com/asepharyana/zesdex/commit/6d3f4918bfea06b106d4fe75adf58e6a29aca2a5))
+* **build:** perbaiki referensi paket zesdex-gateway di Dockerfile & default.nix ([7f64423](https://github.com/asepharyana/zesdex/commit/7f644236158f66fcc106ec55e437ebf28ee1cca1))
+
+## [1.18.2](https://github.com/asepharyana/zesdex/compare/v1.18.1...v1.18.2) (2026-08-20)
+
+
+### Bug Fixes
+
+* **nix:** add perl to nativeBuildInputs for openssl-sys Configure ([033f964](https://github.com/asepharyana/zesdex/commit/033f964be0c695106eef74329524ad7b4b8dba14))
+* **nix:** correct cargoBuildFlags package name zesdex-backend -> zesdex-gateway ([2de5b57](https://github.com/asepharyana/zesdex/commit/2de5b57133f6c7295d8a85e63cb86504ea2a7d3e))
+
+## [1.18.1](https://github.com/asepharyana/zesdex/compare/v1.18.0...v1.18.1) (2026-08-01)
+
+
+### Bug Fixes
+
+* **nix:** restrict flake to x86_64-linux (nixpkgs 26.11 dropped darwin) ([0e0fd5d](https://github.com/asepharyana/zesdex/commit/0e0fd5df05e53a6fa17d481825f1a8c567214d0e))
+
+# [1.18.0](https://github.com/asepharyana/zesdex/compare/v1.17.0...v1.18.0) (2026-07-22)
+
+
+### Bug Fixes
+
+* add .releaserc.json for semantic-release configuration ([047d718](https://github.com/asepharyana/zesdex/commit/047d7183d72adaa0dd1a18a7f92b22d67d5aa85f))
+* **clippy:** replace type annotation with type alias + .insert() to avoid trivial_cast ([ffefa8c](https://github.com/asepharyana/zesdex/commit/ffefa8c07facbba83778f426ca4715569556b08a))
+* **rust:** remove unused imports, variables, and dead code causing CI build failures ([eb8cc17](https://github.com/asepharyana/zesdex/commit/eb8cc1799359a5ef5b4a4ee3a4202b87e80bfe6c))
+* **rust:** resolve all clippy warnings treated as errors in CI ([6b90c7e](https://github.com/asepharyana/zesdex/commit/6b90c7eb0d17d9281a377454e76dcc88a4232bc7))
+* **tui:** resolve remaining clippy errors in workspace ([eed4025](https://github.com/asepharyana/zesdex/commit/eed4025918de65eb2f3fd98cd3350d62f3322132))
+
+
+### Features
+
+* add semantic search tool for code symbol indexing and searching ([fef3c92](https://github.com/asepharyana/zesdex/commit/fef3c925cd02e1d76e2d990cc6fa4e4cba64fab0))
+* Add SOLID principles and TDD reference documentation ([55677dd](https://github.com/asepharyana/zesdex/commit/55677dd67100813a5ed2b0bbf02257b57875ea07))
+* add test_load and test_parse binaries for configuration loading and parsing ([fe2e916](https://github.com/asepharyana/zesdex/commit/fe2e9169371bf7a3cc9391d8467d47fc2258ad1f))
+* **agent:** add AI summarization for conversation history compacting ([873f870](https://github.com/asepharyana/zesdex/commit/873f870e233dd0d2c6f0cce935f83fb8ce373505))
+* **agent:** implement agent execution engine and turn handling with background processing ([efcd191](https://github.com/asepharyana/zesdex/commit/efcd191f9698023944f9096a86c1efa47e412b6b))
+* **best_practice:** add code quality scanning and commit message validation ([8ecc588](https://github.com/asepharyana/zesdex/commit/8ecc588a3e125dc6a4b2e7eb4c12c6b344449c07))
+* centralize default constants and refactor overlay enter handling in TUI ([d615090](https://github.com/asepharyana/zesdex/commit/d615090dcd34bdb93be22c1c7ce4ba674363c258))
+* enhance context gathering in auto-review engine and agent runner ([dcc8c3e](https://github.com/asepharyana/zesdex/commit/dcc8c3ee42ef568843e04143048d799bc0882288))
+* enhance explore phase with TUI workflow event handling ([b3a4d13](https://github.com/asepharyana/zesdex/commit/b3a4d131d13d94bd307720cb50c2d02dedf92873))
+* implement Component trait for modular UI components and refactor TUI views to use it ([d59713d](https://github.com/asepharyana/zesdex/commit/d59713d3e3aa4325f9753bbddd068654e442f6ef))
+* implement mandatory explore phase with parallel subagents ([f368f3a](https://github.com/asepharyana/zesdex/commit/f368f3a1c0d2df02eb50542a81bcff96d9cdc420))
+* **llm:** improve tool call handling by dynamically resizing tool_calls and updating arguments ([9bfb95d](https://github.com/asepharyana/zesdex/commit/9bfb95d795d6c7cc10cfcb907642bba7b8bb7f19))
+* **llm:** improve UTF-8 handling in response processing to prevent infinite loops ([7ea2265](https://github.com/asepharyana/zesdex/commit/7ea226509c8e11ee1bab21d216e0413715988fb9))
+* **llm:** increase max retries for streaming requests from 3 to 10 ([6c7995f](https://github.com/asepharyana/zesdex/commit/6c7995f5f5481c48ccd449e72d9563425fdcb837))
+* **mcp:** enhance MCP server registration with error handling and improve transport process management ([148ba4e](https://github.com/asepharyana/zesdex/commit/148ba4e07b424736c6b4824c5786c0c7c9cbf0a1))
+* refactor auto-review engine to use spawn_subagent for improved thread handling ([094eb4b](https://github.com/asepharyana/zesdex/commit/094eb4b8baa5abd878dcf5b611cf615955bc79eb))
+* remove obsolete design documents for clipboard OSC52, diff view, file mention, context compaction, and add development guide ([66ac4db](https://github.com/asepharyana/zesdex/commit/66ac4dbf027820697f4303264666b5f63a0b31d4))
+* **tui:** add rich context information including active jobs, README snippet, and recent git history ([2f5f62a](https://github.com/asepharyana/zesdex/commit/2f5f62ab097614d8b0c7a3e5c7bd364cd479e0aa))
+* **tui:** add support for reasoning in chat messages and update transcript handling ([285dbb1](https://github.com/asepharyana/zesdex/commit/285dbb14cccb1c261134c1fcb6c30ef1ed02bb55))
+* **tui:** enhance agent turn handling by grouping parameters and improving message management ([07b217c](https://github.com/asepharyana/zesdex/commit/07b217cf4a81b99c63101512932935246fcbc7ae))
+* **tui:** enhance system prompt with workspace structure information ([bed9f8c](https://github.com/asepharyana/zesdex/commit/bed9f8cff60711c4db998c8f10f32f8e210ae410))
+* **tui:** implement streaming support for LLM responses and update transcript handling ([cac6626](https://github.com/asepharyana/zesdex/commit/cac662658651ae092cffddfc88f39a775afef942))
+* **tui:** integrate rich context builder into agent turn process ([919435e](https://github.com/asepharyana/zesdex/commit/919435eb84f9a41a0637052a5dc1234b410714f8))
+* **tui:** introduce comprehensive state management for TUI interface ([8c58faf](https://github.com/asepharyana/zesdex/commit/8c58faf2920b7341dd50ace15044ff113cefb576))
+* **tui:** optimize performance by caching display lines and token counts, and improve action handling ([87abe8c](https://github.com/asepharyana/zesdex/commit/87abe8c3358ac17196df93d19169901a856850d3))
+* **tui:** update system message for clarity and conciseness in tool usage instructions ([5a373d1](https://github.com/asepharyana/zesdex/commit/5a373d1031b476970bd45804a65c7455be99e78d))
+
+
+# [1.17.0](https://github.com/asepharyana/zesdex/compare/v1.16.1...v1.17.0) (2026-07-20)
+
+
+### Features
+
+* **token:** add refresh token verification to TokenService ([a046519](https://github.com/asepharyana/zesdex/commit/a04651905f4afd562b516c839449a2c813ce6627))
+
+## [1.16.1](https://github.com/asepharyana/zesdex/compare/v1.16.0...v1.16.1) (2026-07-20)
+
+# [1.16.0](https://github.com/asepharyana/zesdex/compare/v1.15.2...v1.16.0) (2026-07-20)
+
+
+### Features
+
+* **tui:** add usage overlay and sidebar for displaying usage statistics and tasks ([da2ed6d](https://github.com/asepharyana/zesdex/commit/da2ed6da25953b823354cc5deaa7b404b7b13cb0))
+* **tui:** enhance agent turn with tool descriptions and sanitize arguments ([08e2f99](https://github.com/asepharyana/zesdex/commit/08e2f9998d3693e4cd57225491359c762d03f1d9))
+* **tui:** implement agent turn engine for background processing and enhance input handling ([792695b](https://github.com/asepharyana/zesdex/commit/792695b65a393cfc54efe353480b7831e91544b5))
+
+## [1.15.2](https://github.com/asepharyana/zesdex/compare/v1.15.1...v1.15.2) (2026-07-17)
+
+
+### Bug Fixes
+
+* correct jitter range to ±25% and fix abort.rs doc — review findings ([9b6e51d](https://github.com/asepharyana/zesdex/commit/9b6e51dc677cc4b798532f1e63335785f2f7bbbf))
+
+## [1.15.1](https://github.com/asepharyana/zesdex/compare/v1.15.0...v1.15.1) (2026-07-17)
+
+# [1.15.0](https://github.com/asepharyana/zesdex/compare/v1.14.0...v1.15.0) (2026-07-17)
+
+
+### Bug Fixes
+
+* **cms:** perbaiki serde default hive_mind_node_timeout_ms & toleransi parse gagal di Settings ([6d41ffc](https://github.com/asepharyana/zesdex/commit/6d41ffc587f6f8de5bb4757c7eb8d69077831057))
+* **cms:** satukan ChatMessage/Role Conversation dengan tipe kanonik zesdex-entities ([b272858](https://github.com/asepharyana/zesdex/commit/b272858edbe36af0b2eca119ff5b132de8dadce9))
+* **iam:** redirect_uri dinamis + validasi CSRF state di OAuthServiceImpl ([be278f8](https://github.com/asepharyana/zesdex/commit/be278f8b1c2bc1295368e49c38622ef2bc3ed9ee))
+* **iam:** set permission 0600 pada file token OAuth ([f2d97fb](https://github.com/asepharyana/zesdex/commit/f2d97fb17dcf4f52123da89532d7964ed8f8124c))
+* **middleware:** jangan percaya header X-Forwarded-For/X-Real-IP secara default di rate limiter ([4dc4f80](https://github.com/asepharyana/zesdex/commit/4dc4f80fa344d894c2ce62f75d239847cd13001a))
+
+
+### Features
+
+* **cms:** implement RewindBlobRepository for managing binary blobs ([22dd6fd](https://github.com/asepharyana/zesdex/commit/22dd6fdda7d0c8eabfce296bbad53587204c69fa))
+* **iam:** implementasikan FileSystemSessionLockRepository (sebelumnya belum ada implementasi) ([ff6a749](https://github.com/asepharyana/zesdex/commit/ff6a749c1149d890173922fbff76facef50a93b0))
+* **iam:** port LoopbackServer OAuth callback listener dari zesdex-backend ([910aa5e](https://github.com/asepharyana/zesdex/commit/910aa5e071911f158609c4dd8985f776d8d9235f))
+* **iam:** tambahkan CSPRNG (OsRng) untuk token state/PKCE ([5ede65f](https://github.com/asepharyana/zesdex/commit/5ede65f454b08303f588754a208dca0c37d3ce34))
+
 # [1.14.0](https://github.com/asepharyana/zesdex/compare/v1.13.0...v1.14.0) (2026-07-16)
 
 

CLAUDE.md

@@ -1,86 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-Tests use `#[cfg(test)] mod tests` blocks inline in production files (not a separate `tests/` dir).
-
-Tracing output goes to `~/.local/share/zesdex/zesdex.log`. Set `RUST_LOG=debug` for verbose logging.
-
-## Architecture Overview
-
-Zesdex is an autonomous AI coding agent with a TUI — an OpenAI/Anthropic-compatible LLM client wrapped in a tool-use harness with 37 built-in tools.
-
-Detailed architecture documentation is in `docs/CODEMAPS/`:
-
-| File | Covers |
-|------|--------|
-| [`docs/CODEMAPS/architecture.md`](docs/CODEMAPS/architecture.md) | System layout, process modes, data flow, key files |
-| [`docs/CODEMAPS/backend.md`](docs/CODEMAPS/backend.md) | Provider, OAuth, IPC, workflow engine, MCP, review, bg bash |
-| [`docs/CODEMAPS/frontend.md`](docs/CODEMAPS/frontend.md) | TUI render pipeline, 16 overlays, toasts, input handling |
-| [`docs/CODEMAPS/data.md`](docs/CODEMAPS/data.md) | Persistence, SQLite msglog, memory files, settings/config |
-| [`docs/CODEMAPS/dependencies.md`](docs/CODEMAPS/dependencies.md) | 23 Rust crates, 5 external services |
-
-`docs/runs/` holds an auto-generated audit trail: one markdown file per hive-mind convergence (see below), written deterministically by `app::workflow::docs::write_hive_mind_convergence` — not hand-maintained like `docs/CODEMAPS/`.
-
-### Key Patterns
-
-- **State mutation** — `AppStateRest` is mutable in-place from `actions/mod.rs` and `controller/input.rs`. No generic update function.
-- **No DI** — modules call `Settings::load()`, `AppConfig::load()`, `all_tools()` directly.
-- **Logging** — `tracing::warn!` to `~/.local/share/zesdex/zesdex.log` (not stderr, avoids TUI corruption).
-- **Error handling** — `anyhow::Result` and `anyhow::bail!` throughout. No custom error types.
-- **Static strings** — MCP tool descriptions use `Box::leak` + `OnceLock` cache.
-- **Tools** — `trait Tool { fn name() -> &str, fn run() -> Result<String> }`, 28 impls, gated by `Harness`.
-- **Shell safety** — `tool/shell_filter/` blocks credential leaks and destructive git commands.
-
-### Hive-Mind Orchestration (Machine Intelligence)
-
-- **A single Core Intelligence spawning anonymous processing nodes.** The Core Intelligence (main agent) compiles a cognitive cycle plan per task: an ordered list of cycles, each cycle a set of processing nodes that run in parallel. Each node's sole identity is its directive (what to do) and an access tier. Cycle count and nodes-per-cycle are entirely Core-Intelligence output.
-- **Access tiers** in `src/app/subagent/division.rs` (`tool_scope` module): tool access is granted per node via one of three tiers (`read` / `write` / `full`, see `tool_scope::tools_for`) picked by the Core Intelligence based on what each node's directive actually needs.
-- **Orchestrator** in `src/app/workflow/hive_mind.rs`: `run_hive_mind()` executes a `CognitiveCyclePlan { cycles: Vec<Vec<NodeDirective>> }` cycle-by-cycle. Node IDs are system-assigned coordinates (e.g. `"Node-0-1"`).
-- **Continuous collective state, not phase-boundary sync**: `engine::execute_primitive`'s `ScopedAgent` arm merges each node's complete output into the shared collective-state channel the instant that node finishes — not after its whole parallel cohort completes — so sibling/later nodes see it in real time.
-- **Consensus synthesis, not a per-node summary**: after all cycles complete, `synthesize_consensus()` spawns one final read-only node whose sole directive is to reconcile the entire collective state into a single consensus assessment — a real reasoning pass, not string concatenation, since node outputs can overlap or conflict.
-- **Auto-trigger** in `run_agent_turn()` (`actions/mod.rs`): `is_complex_request()` heuristics decide only whether to ask the Core Intelligence to compile a plan at all — the plan's shape is fully dynamic.
-- **`hive_mind` tool** (`src/tool/workflow.rs`) is the manual entry point: the calling LLM supplies its own `cycles` array of `{directive, access}` directly.
-- **Guaranteed documentation**: after every convergence, `src/app/workflow/docs.rs::write_hive_mind_convergence()` deterministically (not an LLM step, not skippable) writes every node's full output plus the final consensus to `docs/runs/<timestamp>-<slug>.md`.
-- **Live node progress** in TUI panel (`view/workflow.rs`): shows node designation + current tool via `AgentStatus::progress`.
-- **Auto inline review** after each edit: `src/app/subagent/auto.rs` — `spawn_quick_review()` injects verdict back into LLM conversation.
-- **Background subagents** (test-gen, arch-review, security-review) fire asynchronously at turn end via `TurnEvent::SystemNote`, retrying once on failure and escalating to a blocking (`ESCALATED:`-prefixed, `ToastKind::Error`) notice if the retry also fails.
-
-Commit convention (Conventional Commits, Bahasa Indonesia): see the `commit-convention` skill.
-
-## Code Documentation
-
-Every function, struct, enum, trait, module, and significant code block must have a doc comment (`///` or `//!`) that explains:
-
-- **What** the function/module does (purpose, not how)
-- **Flow** — a brief ASCII or prose description of the code flow / data flow above each non-trivial function
-- **Why** — non-obvious decisions, edge cases, invariants
-- **Return** — what the caller gets back, especially for `Result` types
-
-Examples:
-
-```rust
-/// Parse an SSE data chunk into one or more StreamEvents.
-///
-/// Flow: buffer → split on '\n' → flush on blank line → JSON parse → match event type
-///       → return Token / ToolCallDelta / Usage / Done.
-///
-/// Edge case: chunk may split mid-line; remaining bytes stay in buffer
-/// for the next feed() call.
-fn feed(&mut self, chunk: &str) -> Vec<StreamEvent> { ... }
-
-/// The single source-of-truth state struct for the entire application.
-///
-/// Mutated in-place from two locations: actions/mod.rs (apply_action)
-/// and controller/input.rs (key event handlers). Read-only from
-/// every other module.
-struct AppStateRest { ... }
-```
-
-Rules:
-- Every `pub fn` needs a doc comment
-- Every `pub struct` / `pub enum` / `pub trait` needs a doc comment
-- Non-trivial private functions (≥10 lines) need a doc comment
-- Write the comment above the code it documents (not inline in the body)
-- Update comments when code behavior changes — stale docs are worse than no docs
-- NEVER use compiler/linter bypass annotations or attributes (such as `#[allow(clippy::too_many_lines, clippy::too_many_arguments, clippy::ref_option)]`, `#[allow(dead_code)]`, etc.) to silence warnings or skip linter checks. Always fix the underlying code issues instead.

Cargo.lock

@@ -32,6 +32,56 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.103"
@@ -47,6 +97,18 @@ dependencies = [
  "num-traits",
 ]
 
+[[package]]
+name = "argon2"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
+dependencies = [
+ "base64ct",
+ "blake2",
+ "cpufeatures 0.2.17",
+ "password-hash",
+]
+
 [[package]]
 name = "async-trait"
 version = "0.1.89"
@@ -114,12 +176,85 @@ dependencies = [
  "pkg-config",
 ]
 
+[[package]]
+name = "axum"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
+dependencies = [
+ "axum-core",
+ "axum-macros",
+ "base64",
+ "bytes",
+ "form_urlencoded",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde_core",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sha1",
+ "sync_wrapper",
+ "tokio",
+ "tokio-tungstenite",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-macros"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7aa268c23bfbbd2c4363b9cd302a4f504fb2a9dfe7e3451d66f35dd392e20aca"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "base64"
 version = "0.22.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
+[[package]]
+name = "base64ct"
+version = "1.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
+
 [[package]]
 name = "bincode"
 version = "1.3.3"
@@ -171,6 +306,15 @@ version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
+[[package]]
+name = "blake2"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
+dependencies = [
+ "digest 0.10.7",
+]
+
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
@@ -191,9 +335,9 @@ dependencies = [
 
 [[package]]
 name = "bstr"
-version = "1.12.3"
+version = "1.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5cee35f73844aa3014bb606320a6c1f010249dbdf43342fe54b5a4f6a8ed4b79"
+checksum = "1f7dc094d718f2e1c1559ad110e27eeaae14a5465d3d56dd6dbd793079fbd530"
 dependencies = [
  "memchr",
  "regex-automata",
@@ -310,6 +454,46 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "clap"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dd059f9da4f5c36b3787f65d38ccaab1cc315f07b01f89abc8359ee6a8205011"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f09628afdcc538b57f3c6341e9c8e9970f18e4a481690a64974d7023bd33548b"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2ce8604710f6733aa641a2b3731eaa1e8b3d9973d5e3565da11800813f997a9"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "cmake"
 version = "0.1.58"
@@ -319,6 +503,12 @@ dependencies = [
  "cc",
 ]
 
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.7"
@@ -578,6 +768,12 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "data-encoding"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4ae5f15dda3c708c0ade84bfee31ccab44a3da4f88015ed22f63732abe300c8"
+
 [[package]]
 name = "deltae"
 version = "0.3.2"
@@ -620,6 +816,7 @@ checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
  "block-buffer 0.10.4",
  "crypto-common 0.1.7",
+ "subtle",
 ]
 
 [[package]]
@@ -1096,9 +1293,9 @@ checksum = "43503cc176394dd30a6525f5f36e838339b8b5619be33ed9a7783841580a97b6"
 
 [[package]]
 name = "globset"
-version = "0.4.18"
+version = "0.4.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "52dfc19153a48bde0cbd630453615c8151bce3a5adfac7a0aebfbf0a1e1f57e3"
+checksum = "e47d37d2ae4464254884b60ab7071be2b876a9c35b696bd018ddcc76847309cd"
 dependencies = [
  "aho-corasick",
  "bstr",
@@ -1224,6 +1421,12 @@ version = "1.10.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
 [[package]]
 name = "hybrid-array"
 version = "0.4.13"
@@ -1247,6 +1450,7 @@ dependencies = [
  "http",
  "http-body",
  "httparse",
+ "httpdate",
  "itoa",
  "pin-project-lite",
  "smallvec",
@@ -1445,9 +1649,9 @@ dependencies = [
 
 [[package]]
 name = "ignore"
-version = "0.4.28"
+version = "0.4.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2adf14691c72bcfc1058740436a35bdd3ae9c07d1a941ef00b749e9ea16aefa7"
+checksum = "d4ffa3a0547a138e59ddd6fa3b7c672ed47e6ad6a3cd177984ff1116aa5ba742"
 dependencies = [
  "crossbeam-deque",
  "globset",
@@ -1525,6 +1729,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
 [[package]]
 name = "itertools"
 version = "0.14.0"
@@ -1610,6 +1820,21 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "jsonwebtoken"
+version = "9.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a87cc7a48537badeae96744432de36f4be2b4a34a05a5ef32e9dd8a1c169dde"
+dependencies = [
+ "base64",
+ "js-sys",
+ "pem",
+ "ring",
+ "serde",
+ "serde_json",
+ "simple_asn1",
+]
+
 [[package]]
 name = "kasuari"
 version = "0.4.12"
@@ -1790,6 +2015,12 @@ dependencies = [
  "regex-automata",
 ]
 
+[[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+
 [[package]]
 name = "memchr"
 version = "2.8.3"
@@ -1817,6 +2048,16 @@ version = "0.3.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6877bb514081ee2a7ff5ef9de3281f14a4dd4bceac4c09388074a6b5df8a139a"
 
+[[package]]
+name = "mime_guess"
+version = "2.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f7c44f8e672c00fe5308fa235f821cb4198414e1c77935c1ab6948d3fd78550e"
+dependencies = [
+ "mime",
+ "unicase",
+]
+
 [[package]]
 name = "minimal-lexical"
 version = "0.2.1"
@@ -1937,6 +2178,16 @@ dependencies = [
  "unicode-segmentation",
 ]
 
+[[package]]
+name = "num-bigint"
+version = "0.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367"
+dependencies = [
+ "num-integer",
+ "num-traits",
+]
+
 [[package]]
 name = "num-conv"
 version = "0.2.2"
@@ -1954,6 +2205,15 @@ dependencies = [
  "syn 2.0.118",
 ]
 
+[[package]]
+name = "num-integer"
+version = "0.1.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7969661fd2958a5cb096e56c8e1ad0444ac2bbcd0061bd28660485a44879858f"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "num-traits"
 version = "0.2.19"
@@ -2003,6 +2263,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
 [[package]]
 name = "openssl"
 version = "0.10.81"
@@ -2118,12 +2384,33 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "password-hash"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
+dependencies = [
+ "base64ct",
+ "rand_core 0.6.4",
+ "subtle",
+]
+
 [[package]]
 name = "pastey"
 version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
 
+[[package]]
+name = "pem"
+version = "3.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
+dependencies = [
+ "base64",
+ "serde_core",
+]
+
 [[package]]
 name = "percent-encoding"
 version = "2.3.2"
@@ -2323,6 +2610,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
 
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
 [[package]]
 name = "precomputed-hash"
 version = "0.1.1"
@@ -2459,6 +2755,16 @@ dependencies = [
  "rand_core 0.6.4",
 ]
 
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha",
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "rand"
 version = "0.10.2"
@@ -2470,11 +2776,33 @@ dependencies = [
  "rand_core 0.10.1",
 ]
 
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
 [[package]]
 name = "rand_core"
 version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom 0.2.17",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
 
 [[package]]
 name = "rand_core"
@@ -2614,9 +2942,9 @@ dependencies = [
 
 [[package]]
 name = "regex"
-version = "1.13.0"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -2626,9 +2954,9 @@ dependencies = [
 
 [[package]]
 name = "regex-automata"
-version = "0.4.15"
+version = "0.4.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1f388202e4b80542a0921078cc23b6333bcf1409c1e3f86404cae4766a6131db"
+checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
 dependencies = [
  "aho-corasick",
  "memchr",
@@ -3030,6 +3358,17 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "serde_path_to_error"
+version = "0.1.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457"
+dependencies = [
+ "itoa",
+ "serde",
+ "serde_core",
+]
+
 [[package]]
 name = "serde_repr"
 version = "0.1.20"
@@ -3075,6 +3414,17 @@ dependencies = [
  "stable_deref_trait",
 ]
 
+[[package]]
+name = "sha1"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+dependencies = [
+ "cfg-if",
+ "cpufeatures 0.2.17",
+ "digest 0.10.7",
+]
+
 [[package]]
 name = "sha1_smol"
 version = "1.0.1"
@@ -3151,9 +3501,9 @@ dependencies = [
 
 [[package]]
 name = "simd-adler32"
-version = "0.3.9"
+version = "0.3.10"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214"
+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
 
 [[package]]
 name = "simd_cesu8"
@@ -3180,6 +3530,18 @@ dependencies = [
  "bstr",
 ]
 
+[[package]]
+name = "simple_asn1"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d585997b0ac10be3c5ee635f1bab02d512760d14b7c468801ac8a01d9ae5f1d"
+dependencies = [
+ "num-bigint",
+ "num-traits",
+ "thiserror 2.0.18",
+ "time",
+]
+
 [[package]]
 name = "siphasher"
 version = "1.0.3"
@@ -3663,6 +4025,18 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "tokio-tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c"
+dependencies = [
+ "futures-util",
+ "log",
+ "tokio",
+ "tungstenite",
+]
+
 [[package]]
 name = "tokio-util"
 version = "0.7.18"
@@ -3689,6 +4063,7 @@ dependencies = [
  "tokio",
  "tower-layer",
  "tower-service",
+ "tracing",
 ]
 
 [[package]]
@@ -3702,6 +4077,7 @@ dependencies = [
  "futures-util",
  "http",
  "http-body",
+ "http-body-util",
  "pin-project-lite",
  "tower",
  "tower-layer",
@@ -3727,6 +4103,7 @@ version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
 dependencies = [
+ "log",
  "pin-project-lite",
  "tracing-attributes",
  "tracing-core",
@@ -3788,6 +4165,22 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "tungstenite"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
+dependencies = [
+ "bytes",
+ "data-encoding",
+ "http",
+ "httparse",
+ "log",
+ "rand 0.9.5",
+ "sha1",
+ "thiserror 2.0.18",
+]
+
 [[package]]
 name = "typenum"
 version = "1.20.1"
@@ -4420,6 +4813,26 @@ dependencies = [
  "synstructure",
 ]
 
+[[package]]
+name = "zerocopy"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7cbbc0a705a0fd05cc3676525980d2bf5a9bc4adac6d6475209a7887cf59d19"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2e817b7b52d0c7358d3246da9d69935ebb18116b2b102b4230dac079b4862f5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.118",
+]
+
 [[package]]
 name = "zerofrom"
 version = "0.1.8"
@@ -4481,14 +4894,157 @@ dependencies = [
 ]
 
 [[package]]
-name = "zesdex"
-version = "1.14.0"
+name = "zesdex-api"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "argon2",
+ "axum",
+ "chrono",
+ "futures-util",
+ "jsonwebtoken",
+ "serde",
+ "serde_json",
+ "thiserror 1.0.69",
+ "tokio",
+ "tower",
+ "tower-http",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-application"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "base64",
+ "chrono",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tracing",
+ "url",
+ "uuid",
+ "zesdex-domain",
+]
+
+[[package]]
+name = "zesdex-bootstrap"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "chrono",
+ "dirs",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-daemon"
+version = "1.18.2"
 dependencies = [
  "anyhow",
  "base64",
  "chrono",
  "crossterm",
  "dirs",
+ "hex",
+ "ignore",
+ "ratatui",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tokio",
+ "tracing",
+ "uuid",
+ "webbrowser",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-domain"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "base64",
+ "chrono",
+ "libc",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tracing",
+ "url",
+ "uuid",
+]
+
+[[package]]
+name = "zesdex-gateway"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "clap",
+ "dirs",
+ "rusqlite",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "tracing-subscriber",
+ "uuid",
+ "zesdex-api",
+ "zesdex-application",
+ "zesdex-daemon",
+ "zesdex-domain",
+ "zesdex-grpc",
+ "zesdex-infrastructure",
+ "zesdex-tui",
+ "zesdex-web",
+ "zesdex-ws",
+]
+
+[[package]]
+name = "zesdex-grpc"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-infrastructure"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "argon2",
+ "axum",
+ "base64",
+ "chrono",
+ "clap",
+ "dirs",
  "dom_smoothie",
  "fast_html2md",
  "futures-util",
@@ -4497,12 +5053,13 @@ dependencies = [
  "ignore",
  "include_dir",
  "infer",
+ "jsonwebtoken",
  "libc",
  "lsp-types",
  "nucleo-matcher",
  "percent-encoding",
  "pulldown-cmark",
- "ratatui",
+ "rand_core 0.6.4",
  "regex",
  "reqwest",
  "rmcp",
@@ -4516,11 +5073,78 @@ dependencies = [
  "syntect",
  "tiktoken-rs",
  "tokio",
+ "tower",
+ "tower-http",
  "tracing",
- "tracing-subscriber",
  "url",
  "uuid",
  "webbrowser",
+ "zesdex-application",
+ "zesdex-domain",
+]
+
+[[package]]
+name = "zesdex-tui"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "base64",
+ "chrono",
+ "crossterm",
+ "dirs",
+ "hex",
+ "nucleo-matcher",
+ "pulldown-cmark",
+ "ratatui",
+ "rusqlite",
+ "serde",
+ "serde_json",
+ "sha2 0.11.0",
+ "tiktoken-rs",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-web"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "include_dir",
+ "mime_guess",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tower",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
+]
+
+[[package]]
+name = "zesdex-ws"
+version = "1.18.2"
+dependencies = [
+ "anyhow",
+ "axum",
+ "chrono",
+ "futures-util",
+ "serde",
+ "serde_json",
+ "tokio",
+ "tracing",
+ "uuid",
+ "zesdex-application",
+ "zesdex-domain",
+ "zesdex-infrastructure",
 ]
 
 [[package]]

Cargo.toml

@@ -1,11 +1,25 @@
-[package]
-name = "zesdex"
-version = "1.14.0"
+[workspace]
+resolver = "2"
+members = [
+    "apps/domain",
+    "apps/application",
+    "apps/infrastructure",
+    "apps/interfaces/tui",
+    "apps/interfaces/api",
+    "apps/interfaces/daemon",
+    "apps/interfaces/ws",
+    "apps/interfaces/grpc",
+    "apps/interfaces/web",
+    "apps/gateway",
+    "apps/bootstrap",
+]
+
+[workspace.package]
+version = "1.18.4"
 edition = "2021"
 authors = ["asepharyana <superaseph@gmail.com>"]
 
-# Treat all warnings as errors, set strict clippy levels
-[lints.rust]
+[workspace.lints.rust]
 unused = "deny"
 dead_code = "deny"
 unreachable_code = "deny"
@@ -17,49 +31,66 @@ deprecated = "deny"
 trivial_casts = "deny"
 trivial_numeric_casts = "deny"
 
-[lints.clippy]
+[workspace.lints.clippy]
 all = { level = "warn", priority = -1 }
 pedantic = { level = "warn", priority = -2 }
 
-[dependencies]
-ratatui = "0.30.2"
-crossterm = "0.29"
-tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "net", "io-util", "signal"] }
-reqwest = { version = "0.13", features = ["json", "stream", "blocking", "native-tls-vendored", "form"] }
-dom_smoothie = "0.18.0"
-fast_html2md = "0.0.62"
-scraper = "0.27.0"
-url = "2"
-percent-encoding = "2"
+[workspace.dependencies]
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 serde_yaml_ng = "0.10"
-anyhow = "1"
-include_dir = "0.7"
+chrono = { version = "0.4", features = ["serde"] }
 uuid = { version = "1", features = ["v4", "v5"] }
-dirs = "6"
-futures-util = "0.3"
-pulldown-cmark = { version = "0.13", default-features = false }
-similar = "3"
-syntect = { version = "5", default-features = false, features = ["default-fancy"] }
+anyhow = "1"
+tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time", "net", "io-util", "signal"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+reqwest = { version = "0.13", features = ["json", "stream", "blocking", "native-tls-vendored", "form"] }
+ratatui = "0.30.2"
+crossterm = "0.29"
 rusqlite = { version = "0.40", features = ["bundled"] }
-ignore = "0.4"
-regex = "1"
-globset = "0.4"
-nucleo-matcher = "0.3"
-infer = "0.19"
+thiserror = "1"
 base64 = "0.22"
 sha2 = "0.11"
 hex = "0.4"
 libc = "0.2"
+dirs = "6"
+regex = "1"
+globset = "0.4"
+ignore = "0.4"
+nucleo-matcher = "0.3"
+futures-util = "0.3"
 rmcp = { version = "2.2", default-features = false, features = ["client", "transport-child-process", "transport-streamable-http-client-reqwest", "macros"] }
-tracing = "0.1"
-chrono = { version = "0.4", features = ["serde"] }
-tracing-subscriber = { version = "0.3", features = ["env-filter"] }
-webbrowser = "1"
 lsp-types = "0.97"
 tiktoken-rs = "0.12"
+similar = "3"
+syntect = { version = "5", default-features = false, features = ["default-fancy"] }
+pulldown-cmark = { version = "0.13", default-features = false }
+infer = "0.19"
+webbrowser = "1"
+url = "2"
+percent-encoding = "2"
+dom_smoothie = "0.18.0"
+fast_html2md = "0.0.62"
+scraper = "0.27.0"
+include_dir = "0.7"
+axum = { version = "0.8", features = ["macros"] }
+tower = "0.5"
+tower-http = { version = "0.6", features = ["cors", "limit"] }
+argon2 = "0.5"
+jsonwebtoken = "9"
+clap = { version = "4", features = ["derive"] }
+rand_core = { version = "0.6", features = ["getrandom"] }
 
-[[bin]]
-name = "zesdex"
-path = "src/main.rs"
+# Clean-architecture workspace crate references
+zesdex-domain = { path = "apps/domain" }
+zesdex-application = { path = "apps/application" }
+zesdex-infrastructure = { path = "apps/infrastructure" }
+zesdex-tui = { path = "apps/interfaces/tui" }
+zesdex-api = { path = "apps/interfaces/api" }
+zesdex-daemon = { path = "apps/interfaces/daemon" }
+zesdex-ws = { path = "apps/interfaces/ws" }
+zesdex-grpc = { path = "apps/interfaces/grpc" }
+zesdex-web = { path = "apps/interfaces/web" }
+zesdex-gateway = { path = "apps/gateway" }
+zesdex-bootstrap = { path = "apps/bootstrap" }

Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1
+# Zesdex — Multi-stage Docker build
+# ===================================
+# Stage 1: Build with Rust toolchain
+FROM rust:1.85-slim-bookworm AS builder
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    pkg-config libsqlite3-dev && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . .
+
+# Build with release profile (treats warnings as errors via lints)
+RUN cargo build --release -p zesdex-gateway --bin zesdex
+
+# Stage 2: Minimal runtime image
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates libsqlite3-0 && \
+    rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /app/target/release/zesdex /usr/local/bin/zesdex
+
+ENV ZESDEX_DATA_DIR=/data
+
+VOLUME ["/data"]
+
+ENTRYPOINT ["/usr/local/bin/zesdex"]

apps/application/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "zesdex-application"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+# Application layer — port traits (interfaces), use cases, DTOs.
+# Depends ONLY on domain. Application services orchestrate domain objects
+# through port traits without knowing concrete implementations.
+[dependencies]
+zesdex-domain = { path = "../domain" }
+serde.workspace = true
+serde_json.workspace = true
+chrono.workspace = true
+uuid.workspace = true
+anyhow.workspace = true
+tracing.workspace = true
+tokio.workspace = true
+base64.workspace = true
+sha2.workspace = true
+url.workspace = true

apps/application/src/agent/explore.rs

@@ -0,0 +1,57 @@
+//! Mandatory explore phase — spawns parallel subagents to discover context
+//! before the main agent begins its turn.
+//!
+//! # Flow
+//!
+//! Before the main agent's LLM loop, [`ExploreService::explore`] dispatches
+//! at least 3 subagents in parallel (code-structure scan, symbol-index query,
+//! semantic-context search). Their findings are consolidated into a single
+//! system message that is prepended to the conversation.
+//!
+//! # Why mandatory
+//!
+//! Without structured exploration the main agent works from an empty context
+//! window. The explore phase guarantees that every turn starts with a compact
+//! snapshot of what the codebase contains and where relevant code lives.
+
+use anyhow::Result;
+use std::collections::VecDeque;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::{Arc, Mutex};
+use zesdex_domain::agent::TurnEvent;
+
+/// The consolidated output of an explore phase — a set of system-level
+/// context messages injected before the main agent prompt.
+#[derive(Debug, Clone)]
+pub struct ExploreOutput {
+    /// One or more system messages summarising what the explore subagents
+    /// discovered. Prepended to the conversation by the turn service.
+    pub context_messages: Vec<String>,
+    /// Short human-readable summary of what was explored.
+    pub summary: String,
+}
+
+/// Service trait for the mandatory pre-turn exploration phase.
+///
+/// Implementors spawn ≥3 parallel subagents, each analysing a different
+/// aspect of the workspace, and return a consolidated summary.
+///
+/// # Object safety
+///
+/// This trait is `dyn`-safe — it returns `Pin<Box<dyn Future>>` so it can
+/// be stored as `Arc<dyn ExploreService>`.
+pub trait ExploreService: Send + Sync {
+    /// Run the explore phase.
+    ///
+    /// `query` — the user's current input phrase.
+    /// `workspace_root` — absolute path to the workspace root.
+    /// `turn_events` — shared event queue for TUI updates.
+    /// Returns structured context messages and a summary blob.
+    fn explore<'a>(
+        &'a self,
+        query: &'a str,
+        workspace_root: &'a str,
+        turn_events: &'a Arc<Mutex<VecDeque<TurnEvent>>>,
+    ) -> Pin<Box<dyn Future<Output = Result<ExploreOutput>> + Send + 'a>>;
+}

apps/application/src/agent/mod.rs

@@ -0,0 +1,26 @@
+use anyhow::Result;
+use std::future::Future;
+
+use zesdex_domain::agent::AgentTurnParams;
+
+/// Interface for dispatching tool calls to their concrete implementations.
+pub trait ToolExecutor: Send + Sync {
+    /// Execute a tool call asynchronously.
+    fn execute(
+        &self,
+        tool_name: &str,
+        args: &serde_json::Value,
+    ) -> impl Future<Output = Result<String>> + Send;
+}
+
+/// Service for running agent turns asynchronously.
+pub trait AgentTurnService: Send + Sync {
+    /// Run a full agent turn loop asynchronously.
+    fn run_turn(&self, params: AgentTurnParams) -> impl Future<Output = Result<()>> + Send;
+}
+
+pub mod explore;
+pub mod turn_service;
+
+pub use explore::{ExploreOutput, ExploreService};
+pub use turn_service::{compact_messages_with_ai, AgentTurnServiceImpl};

apps/application/src/agent/turn_service.rs

@@ -0,0 +1,372 @@
+use std::collections::VecDeque;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use tracing::{debug, info, warn};
+
+use zesdex_domain::agent::{AgentTurnParams, TurnEvent};
+use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
+use zesdex_domain::main_agent_prompt;
+
+use super::{ExploreService, ToolExecutor};
+use crate::ports::ProviderService;
+
+/// Maximum tool-call iterations per agent turn before forcing termination.
+const MAX_TURN_ITERATIONS: u32 = 50;
+
+// ---------------------------------------------------------------------------
+// Helper: push a TurnEvent onto the shared queue.
+// ---------------------------------------------------------------------------
+
+fn push_event(queue: &Arc<Mutex<VecDeque<TurnEvent>>>, event: TurnEvent) {
+    if let Ok(mut q) = queue.lock() {
+        q.push_back(event);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Helper: stream-event callback that forwards tokens to the turn-event queue
+// and checks the abort flag on each emission.
+// ---------------------------------------------------------------------------
+
+fn make_stream_callback(
+    abort: &Arc<AtomicBool>,
+    turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
+) -> Box<dyn FnMut(&StreamEvent) -> bool + Send> {
+    let abort_clone = Arc::clone(abort);
+    let events_clone = Arc::clone(turn_events);
+    Box::new(move |event: &StreamEvent| -> bool {
+        if abort_clone.load(Ordering::SeqCst) {
+            return false;
+        }
+        match event {
+            StreamEvent::Token(s) => {
+                push_event(&events_clone, TurnEvent::StreamToken(s.clone()));
+            }
+            StreamEvent::Reasoning(s) => {
+                push_event(&events_clone, TurnEvent::StreamReasoning(s.clone()));
+            }
+            _ => {}
+        }
+        true
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Helper: execute a single tool call, push events, return the result string.
+// ---------------------------------------------------------------------------
+
+async fn execute_tool_call<T: ToolExecutor>(
+    tool_executor: &T,
+    turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
+    tc: &zesdex_domain::core::ToolCall,
+) -> String {
+    let name = &tc.function.name;
+    let args = zesdex_domain::core::tool_call::sanitize_tool_arguments(&tc.function.arguments);
+
+    debug!("executing tool: {name}");
+
+    let output = match tool_executor.execute(name, &args).await {
+        Ok(o) => o,
+        Err(e) => format!("Error: {e}"),
+    };
+
+    let is_error = output.starts_with("Error:");
+
+    push_event(
+        turn_events,
+        TurnEvent::ToolResult {
+            tool_call_id: tc.id.clone(),
+            tool_name: name.clone(),
+            output: output.clone(),
+            is_error,
+            path: None,
+        },
+    );
+
+    output
+}
+
+// ---------------------------------------------------------------------------
+// Helper: emit usage event from optional LLM response metadata.
+// ---------------------------------------------------------------------------
+
+fn emit_usage(turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>, usage: Option<(u64, u64)>) {
+    if let Some((tokens_in, tokens_out)) = usage {
+        push_event(
+            turn_events,
+            TurnEvent::Usage {
+                tokens_in,
+                tokens_out,
+            },
+        );
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+/// Service implementation for executing an agent turn asynchronously.
+///
+/// # Explore phase
+///
+/// Before the main LLM loop begins, [`AgentTurnServiceImpl`] runs a mandatory
+/// explore phase that spawns ≥3 parallel subagents (code structure, symbol
+/// index, semantic context) and injects their consolidated findings as a
+/// system message. See [`ExploreService`] for the trait contract.
+pub struct AgentTurnServiceImpl<P: ProviderService, T: ToolExecutor> {
+    provider: Arc<P>,
+    tool_executor: Arc<T>,
+    tool_defs: Vec<ToolDef>,
+    /// Optional explore-phase service. When `Some`, the explore phase runs
+    /// before every turn; when `None` it is skipped (tests, daemon mode).
+    explore_service: Option<Arc<dyn ExploreService>>,
+}
+
+impl<P: ProviderService, T: ToolExecutor> AgentTurnServiceImpl<P, T> {
+    pub fn new(provider: Arc<P>, tool_executor: Arc<T>, tool_defs: Vec<ToolDef>) -> Self {
+        Self {
+            provider,
+            tool_executor,
+            tool_defs,
+            explore_service: None,
+        }
+    }
+
+    /// Attach an optional explore-phase service.
+    ///
+    /// When set, every call to `run_turn` will first run the explore phase
+    /// and inject the consolidated context as a system message.
+    pub fn with_explore(mut self, service: Arc<dyn ExploreService>) -> Self {
+        self.explore_service = Some(service);
+        self
+    }
+
+    /// Execute a single LLM call with the current message list, handling
+    /// streaming events and error reporting.
+    async fn call_llm(
+        &self,
+        messages: &[ChatMessage],
+        abort: &Arc<AtomicBool>,
+        turn_events: &Arc<Mutex<VecDeque<TurnEvent>>>,
+    ) -> Result<(ChatMessage, Option<(u64, u64)>), String> {
+        let on_event = make_stream_callback(abort, turn_events);
+
+        self.provider
+            .chat_stream(
+                messages,
+                Some(self.tool_defs.clone()),
+                Some(4096),
+                Some(0.7),
+                on_event,
+            )
+            .await
+            .map_err(|e| format!("LLM error: {e}"))
+    }
+}
+
+impl<P: ProviderService, T: ToolExecutor> super::AgentTurnService for AgentTurnServiceImpl<P, T> {
+    async fn run_turn(&self, mut params: AgentTurnParams) -> anyhow::Result<()> {
+        info!(
+            "Starting async agent turn with {} messages (model: {})",
+            params.messages.len(),
+            params.model
+        );
+
+        // ── Phase 0: Mandatory explore ──────────────────────────────────
+        // Spawn ≥3 parallel subagents to discover code structure, symbols,
+        // and semantic context. The consolidated summary is injected as a
+        // system message before the main agent prompt.
+        if let Some(ref explorer) = self.explore_service {
+            // Determine workspace root from the first message's context or
+            // the first workspace root in params.
+            let user_query = params
+                .messages
+                .last()
+                .map(|m| m.content.clone().unwrap_or_default())
+                .unwrap_or_default();
+            let workspace_root = params
+                .workspace_roots
+                .first()
+                .map(|p| p.to_string_lossy().to_string())
+                .unwrap_or_else(|| ".".to_string());
+
+            push_event(
+                &params.turn_events,
+                TurnEvent::SystemNote {
+                    kind: "info".into(),
+                    message: "🔍 Exploring codebase structure...".into(),
+                },
+            );
+
+            match explorer
+                .explore(&user_query, &workspace_root, &params.turn_events)
+                .await
+            {
+                Ok(output) => {
+                    // Insert each context message as a system message.
+                    // They go at index 0 and are removed after the turn
+                    // like the main agent prompt.
+                    for ctx_msg in &output.context_messages {
+                        params
+                            .messages
+                            .insert(0, ChatMessage::system(ctx_msg.clone()));
+                    }
+                    info!(
+                        "Explore phase complete: {} context messages, {}",
+                        output.context_messages.len(),
+                        output.summary
+                    );
+                }
+                Err(e) => {
+                    warn!("Explore phase failed (non-fatal): {e}");
+                    push_event(
+                        &params.turn_events,
+                        TurnEvent::SystemNote {
+                            kind: "warn".into(),
+                            message: format!("Explore phase failed: {e}"),
+                        },
+                    );
+                }
+            }
+        }
+
+        // Insert system prompt at position 0 once and keep it there for the
+        // entire turn, avoiding per-iteration clones of the full message list.
+        // It is removed before emitting the Compacted event so persistence
+        // does not store the prompt redundantly.
+        params
+            .messages
+            .insert(0, ChatMessage::system(main_agent_prompt()));
+        let original_count = params.messages.len();
+
+        for iteration in 0..MAX_TURN_ITERATIONS {
+            // ── Check abort flag ────────────────────────────────────────
+            if params.abort.load(Ordering::SeqCst) {
+                params.abort.store(false, Ordering::SeqCst);
+                push_event(
+                    &params.turn_events,
+                    TurnEvent::SystemNote {
+                        kind: "info".into(),
+                        message: "Turn aborted by user".into(),
+                    },
+                );
+                break;
+            }
+
+            debug!("agent turn iteration {iteration}");
+
+            // ── Stream start + call LLM ─────────────────────────────────
+            push_event(&params.turn_events, TurnEvent::StreamStart);
+
+            // Uses params.messages directly (sys_msg[0] already in place
+            // from the insert above) — no per-iteration clone needed.
+            let result = self
+                .call_llm(&params.messages, &params.abort, &params.turn_events)
+                .await;
+
+            match result {
+                Ok((assistant_msg, usage)) => {
+                    let content = assistant_msg.content.clone().unwrap_or_default();
+                    let tool_calls = assistant_msg.tool_calls.clone().unwrap_or_default();
+
+                    push_event(
+                        &params.turn_events,
+                        TurnEvent::StreamDone(assistant_msg.clone()),
+                    );
+
+                    emit_usage(&params.turn_events, usage);
+
+                    // ── No tool calls → assistant is done ──────────────
+                    if tool_calls.is_empty() {
+                        params.messages.push(ChatMessage::assistant(Some(content)));
+                        break;
+                    }
+
+                    params.messages.push(assistant_msg);
+
+                    // ── Execute each tool call ──────────────────────────
+                    for tc in &tool_calls {
+                        let output =
+                            execute_tool_call(self.tool_executor.as_ref(), &params.turn_events, tc)
+                                .await;
+                        params
+                            .messages
+                            .push(ChatMessage::tool(tc.id.clone(), output));
+                    }
+                }
+                Err(e) => {
+                    warn!("{e}");
+                    push_event(&params.turn_events, TurnEvent::Error(e));
+                    break;
+                }
+            }
+        }
+
+        // Remove the synthetic sys_msg before shipping events to the TUI
+        // so the transcript shows only the actual user/assistant/tool exchange.
+        let compacted: Vec<ChatMessage> = params.messages.drain(original_count - 1..).collect();
+        push_event(&params.turn_events, TurnEvent::Compacted(compacted));
+        push_event(&params.turn_events, TurnEvent::Done);
+        params.in_flight.store(false, Ordering::SeqCst);
+
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Conversation compaction
+// ---------------------------------------------------------------------------
+
+/// Maximum number of recent messages to preserve during compaction.
+const COMPACT_KEEP_TAIL: usize = 6;
+
+/// Compacts conversation history using AI summarisation.
+///
+/// Flow: if the message count exceeds `KEEP_TAIL + 2`, the oldest messages
+/// are drained and summarised by the LLM. The summary is inserted as a
+/// system message at the head of the remaining history.
+pub async fn compact_messages_with_ai<P: ProviderService>(
+    messages: &mut Vec<ChatMessage>,
+    provider: &P,
+) -> anyhow::Result<()> {
+    if messages.len() <= COMPACT_KEEP_TAIL + 2 {
+        return Ok(()); // Not enough messages to compact
+    }
+
+    let split_idx = messages.len() - COMPACT_KEEP_TAIL;
+    let evicted: Vec<_> = messages.drain(..split_idx).collect();
+
+    let mut summary_prompt = vec![ChatMessage::system(zesdex_domain::compaction_prompt())];
+    summary_prompt.extend(evicted);
+    summary_prompt.push(ChatMessage::user(
+        "Please summarise our previous conversation above for context continuity.".to_string(),
+    ));
+
+    match provider
+        .chat(&summary_prompt, None, Some(1024), Some(0.3))
+        .await
+    {
+        Ok((summary_msg, _)) => {
+            let summary_text = summary_msg
+                .content
+                .unwrap_or_else(|| "Previous context summarised.".to_string());
+            let summary_node = ChatMessage::system(format!(
+                "[AI Summary of Previous Conversation]\n{}",
+                summary_text.trim()
+            ));
+            messages.insert(0, summary_node);
+            Ok(())
+        }
+        Err(e) => {
+            warn!("AI summarisation failed during compact, falling back to simple notice: {e}");
+            messages.insert(
+                0,
+                ChatMessage::system(
+                    "[Earlier conversation messages compacted to save context window]".to_string(),
+                ),
+            );
+            Ok(())
+        }
+    }
+}

apps/application/src/auth/mod.rs

@@ -0,0 +1,16 @@
+//! Auth use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's
+//! authentication and session management traits by coordinating
+//! injected repository and port dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`oauth_service`] — `OAuthUseCase`: OAuth 2.0 authorization-code + PKCE flow
+//! - [`session_service`] — `SessionServiceImpl`: session CRUD lifecycle
+
+pub mod oauth_service;
+pub mod session_service;
+
+pub use oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger};
+pub use session_service::SessionServiceImpl;

apps/application/src/auth/oauth_service.rs

@@ -0,0 +1,237 @@
+//! OAuth 2.0 authorization-code + PKCE flow use-case.
+//!
+//! `OAuthUseCase` orchestrates the standard PKCE-enhanced OAuth flow:
+//!
+//! 1. **`start_flow`** — generates a cryptographic PKCE code verifier,
+//!    derives its S256 challenge, creates a CSRF state token, persists
+//!    the verifier + state via `OAuthFlowStore`, and builds an
+//!    authorization URL with all required parameters.
+//! 2. **`complete_flow`** — validates the returned `state` against the
+//!    stored value (CSRF check), reads the stored verifier, delegates
+//!    the token-code exchange to an injected `TokenExchanger`, and
+//!    persists the resulting `OAuthToken` via `OAuthRepository`.
+//! 3. **`get_token`** — loads the stored OAuth token (if any).
+//!
+//! # Portability
+//!
+//! The service is generic over three injected dependencies:
+//! - `R: OAuthRepository` — token persistence
+//! - `S: OAuthFlowStore` — ephemeral flow state (verifier + CSRF state)
+//! - `E: TokenExchanger` — the HTTP token-endpoint exchange
+//!
+//! This keeps all I/O and protocol-level concerns abstracted behind
+//! port traits; the service itself contains only orchestration logic.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::auth::{OAuthConfig, OAuthRepository, OAuthToken, ServiceError};
+
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use base64::Engine as _;
+use sha2::{Digest, Sha256};
+
+// ---------------------------------------------------------------------------
+// Port traits (defined here because they are specific to this use-case)
+// ---------------------------------------------------------------------------
+
+/// Persistence contract for ephemeral OAuth flow state.
+///
+/// Between `start_flow` and `complete_flow` the verifier and CSRF state
+/// must survive across process boundaries (the user opens a browser, the
+/// provider redirects back to a loopback listener on the next invocation).
+///
+/// Implementors store key-value pairs to disk or another durable medium
+/// and clear them after a successful (or failed) flow completion.
+pub trait OAuthFlowStore: Send + Sync {
+    /// Persist the PKCE code verifier and CSRF state token.
+    fn save_flow_state(&self, verifier: &str, state: &str) -> Result<(), ServiceError>;
+
+    /// Load the stored PKCE code verifier.
+    fn load_verifier(&self) -> Result<String, ServiceError>;
+
+    /// Load the stored CSRF state token.
+    fn load_state(&self) -> Result<String, ServiceError>;
+
+    /// Clear stored flow state (verifier + state).
+    fn clear(&self) -> Result<(), ServiceError>;
+}
+
+/// Abstraction for exchanging an authorization code for tokens.
+///
+/// Implementors handle the HTTP POST to the provider's token endpoint
+/// with the appropriate form-encoded parameters, parse the JSON
+/// response, and return the extracted `OAuthToken`.
+pub trait TokenExchanger: Send + Sync {
+    /// Exchange an authorization code for an access token.
+    ///
+    /// ## Parameters
+    /// - `token_url` — the provider's token endpoint URL
+    /// - `client_id` — OAuth client identifier
+    /// - `client_secret` — optional client secret
+    /// - `redirect_uri` — must match the URI used in `start_flow`
+    /// - `code` — the authorization code from the provider's redirect
+    /// - `code_verifier` — the PKCE verifier from `start_flow`
+    fn exchange_code(
+        &self,
+        token_url: &str,
+        client_id: &str,
+        client_secret: Option<&str>,
+        redirect_uri: &str,
+        code: &str,
+        code_verifier: &str,
+    ) -> Result<OAuthToken, ServiceError>;
+}
+
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+
+/// Generate a PKCE code-verifier and its S256 code-challenge.
+///
+/// Uses 32 cryptographically random bytes, base64url-encoded (no padding)
+/// for the verifier, then SHA-256 hashes the verifier and base64url-encodes
+/// the digest for the challenge. This satisfies the PKCE `S256` method
+/// which requires a minimum verifier length of 43 characters.
+fn generate_pkce_pair() -> (String, String) {
+    // 32 random bytes → 43 base64url chars (well above the 43-char PKCE
+    // minimum).
+    let mut bytes = [0u8; 32];
+    bytes[..16].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+    bytes[16..].copy_from_slice(uuid::Uuid::new_v4().as_bytes());
+
+    let verifier = URL_SAFE_NO_PAD.encode(bytes);
+    let challenge = {
+        let mut hasher = Sha256::new();
+        hasher.update(verifier.as_bytes());
+        URL_SAFE_NO_PAD.encode(hasher.finalize())
+    };
+    (verifier, challenge)
+}
+
+/// Generate a random CSRF state token (UUID-based, 36 chars).
+fn generate_state_token() -> String {
+    uuid::Uuid::new_v4().to_string()
+}
+
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+
+/// Concrete OAuth flow use-case.
+///
+/// Generic over three dependencies:
+/// - `R` — token persistence (`OAuthRepository`)
+/// - `S` — flow-state persistence (`OAuthFlowStore`)
+/// - `E` — token-endpoint HTTP exchange (`TokenExchanger`)
+pub struct OAuthUseCase<R, S, E> {
+    /// Repository for persisting / loading OAuth tokens.
+    pub token_repo: R,
+    /// Store for ephemeral flow state (verifier + CSRF state).
+    pub flow_store: S,
+    /// Token-endpoint HTTP exchanger.
+    pub token_exchanger: E,
+    /// File path for the token JSON file.
+    pub token_path: PathBuf,
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger> OAuthUseCase<R, S, E> {
+    /// Create a new OAuth use-case.
+    pub fn new(token_repo: R, flow_store: S, token_exchanger: E, token_path: PathBuf) -> Self {
+        OAuthUseCase {
+            token_repo,
+            flow_store,
+            token_exchanger,
+            token_path,
+        }
+    }
+}
+
+impl<R: OAuthRepository, S: OAuthFlowStore, E: TokenExchanger> zesdex_domain::auth::OAuthService
+    for OAuthUseCase<R, S, E>
+{
+    fn start_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+    ) -> Result<(String, String), ServiceError> {
+        if config.auth_url.is_empty() {
+            return Err(ServiceError::InvalidConfig(
+                "OAuth auth_url is empty".to_string(),
+            ));
+        }
+
+        let (verifier, challenge) = generate_pkce_pair();
+        let state = generate_state_token();
+
+        // Persist verifier + state so `complete_flow` can retrieve them.
+        self.flow_store.save_flow_state(&verifier, &state)?;
+
+        tracing::debug!(
+            auth_url = %config.auth_url,
+            redirect_uri = %redirect_uri,
+            state_len = state.len(),
+            "starting OAuth flow",
+        );
+
+        let mut url = url::Url::parse(&config.auth_url).map_err(|e| {
+            ServiceError::InvalidConfig(format!("invalid auth_url '{}': {e}", config.auth_url))
+        })?;
+
+        url.query_pairs_mut()
+            .append_pair("response_type", "code")
+            .append_pair("client_id", &config.client_id)
+            .append_pair("redirect_uri", redirect_uri)
+            .append_pair("scope", &config.scopes.join(" "))
+            .append_pair("state", &state)
+            .append_pair("code_challenge_method", "S256")
+            .append_pair("code_challenge", &challenge);
+
+        Ok((url.to_string(), state))
+    }
+
+    fn complete_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+        code: &str,
+        state: &str,
+    ) -> Result<OAuthToken, ServiceError> {
+        // CSRF check: validate the returned state against the stored value.
+        let expected_state = self.flow_store.load_state()?;
+        if expected_state != state {
+            return Err(ServiceError::StateMismatch);
+        }
+
+        // Read the PKCE verifier that was saved in `start_flow`.
+        let verifier = self.flow_store.load_verifier()?;
+
+        tracing::debug!(
+            token_url = %config.token_url,
+            code_len = code.len(),
+            "completing OAuth flow — exchanging code for token",
+        );
+
+        // Delegate the HTTP token exchange to the injected exchanger.
+        let token = self.token_exchanger.exchange_code(
+            &config.token_url,
+            &config.client_id,
+            config.client_secret.as_deref(),
+            redirect_uri,
+            code,
+            &verifier,
+        )?;
+
+        // Persist the token and clean up flow state.
+        self.token_repo.save_token(&self.token_path, &token)?;
+        let _ = self.flow_store.clear();
+
+        Ok(token)
+    }
+
+    fn get_token(&self) -> Result<Option<OAuthToken>, ServiceError> {
+        self.token_repo
+            .load_token(&self.token_path)
+            .map_err(ServiceError::Repository)
+    }
+}

apps/application/src/auth/session_service.rs

@@ -0,0 +1,84 @@
+//! Session management use-case.
+//!
+//! `SessionServiceImpl` implements [`SessionService`] from the domain
+//! layer by delegating CRUD operations to injected repository traits.
+//!
+//! # Flow
+//!
+//! - **`create_session`** — generates a UUID v4 id, creates a `Session`
+//!   entity with the given title, persists via `SessionRepository`.
+//! - **`list_all`** — delegates to `SessionRepository::list_sessions`.
+//! - **`archive_session`** — loads session, sets `archived = true`,
+//!   persists the updated entity.
+//!
+//! # Generics
+//!
+//! - `R: SessionRepository` — session CRUD persistence
+//! - `L: SessionLockRepository` — session lock acquire/release
+
+use std::path::PathBuf;
+use tracing;
+use uuid::Uuid;
+
+use zesdex_domain::auth::{
+    ServiceError, Session, SessionId, SessionLockRepository, SessionRepository,
+};
+
+/// Concrete session service backed by injected repository implementations.
+pub struct SessionServiceImpl<R: SessionRepository, L: SessionLockRepository> {
+    /// Repository for session CRUD operations.
+    pub session_repo: R,
+    /// Repository for session lock acquire/release.
+    pub lock_repo: L,
+    /// Base data directory passed to repository methods.
+    pub base_dir: PathBuf,
+}
+
+impl<R: SessionRepository, L: SessionLockRepository> SessionServiceImpl<R, L> {
+    /// Create a new session service with the given repositories and base
+    /// data directory.
+    pub fn new(session_repo: R, lock_repo: L, base_dir: PathBuf) -> Self {
+        SessionServiceImpl {
+            session_repo,
+            lock_repo,
+            base_dir,
+        }
+    }
+}
+
+impl<R: SessionRepository, L: SessionLockRepository> zesdex_domain::auth::SessionService
+    for SessionServiceImpl<R, L>
+{
+    fn create_session(&self, title: &str) -> Result<Session, ServiceError> {
+        let id = SessionId::new(&Uuid::new_v4().to_string()).map_err(ServiceError::Other)?;
+        let title_owned = if title.is_empty() {
+            "New Session".to_string()
+        } else {
+            title.to_string()
+        };
+        let session = Session::new(id.into_string(), title_owned);
+        tracing::debug!(session_id = %session.id, title = %session.title, "creating new session");
+        self.session_repo.save_session(&self.base_dir, &session)?;
+        Ok(session)
+    }
+
+    fn list_all(&self) -> Result<Vec<Session>, ServiceError> {
+        tracing::debug!("listing all sessions");
+        self.session_repo
+            .list_sessions(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn archive_session(&self, id: SessionId) -> Result<(), ServiceError> {
+        tracing::debug!(session_id = %id, "archiving session");
+        let mut session = self.session_repo.load_session(&self.base_dir, &id)?;
+        session.archived = true;
+        let millis = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_millis();
+        session.updated_at = i64::try_from(millis).unwrap_or(i64::MAX);
+        self.session_repo.save_session(&self.base_dir, &session)?;
+        Ok(())
+    }
+}

apps/application/src/cms/conversation_service.rs

@@ -0,0 +1,68 @@
+//! Conversation use-case implementation.
+//!
+//! `ConversationServiceImpl` implements [`ConversationService`] from the
+//! domain layer. It is generic over `R: ConversationRepository`, delegating
+//! all persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method computes the session directory from the session ID, then
+//! delegates the actual I/O to the injected `repo`. Error context is
+//! added at this layer to identify which session caused the failure.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Conversation, ConversationRepository, ServiceError};
+use zesdex_domain::core::ChatMessage;
+
+/// Service implementation for conversation CRUD operations.
+///
+/// Generic over `R: ConversationRepository` so the persistence layer
+/// can be swapped without changing business logic.
+pub struct ConversationServiceImpl<R> {
+    pub repo: R,
+    /// Base directory containing session subdirectories.
+    pub sessions_dir: PathBuf,
+}
+
+impl<R: ConversationRepository> ConversationServiceImpl<R> {
+    /// Create a new service with the given repository and sessions directory.
+    pub fn new(repo: R, sessions_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating ConversationServiceImpl");
+        Self {
+            repo,
+            sessions_dir: sessions_dir.into(),
+        }
+    }
+
+    /// Compute the session directory for a given session id.
+    fn session_dir(&self, session_id: &str) -> PathBuf {
+        self.sessions_dir.join(session_id)
+    }
+}
+
+impl<R: ConversationRepository> zesdex_domain::cms::ConversationService
+    for ConversationServiceImpl<R>
+{
+    fn load_conversation(&self, session_id: &str) -> Result<Conversation, ServiceError> {
+        tracing::debug!("loading conversation for session {session_id}");
+        let dir = self.session_dir(session_id);
+        self.repo.load(&dir).map_err(ServiceError::Repository)
+    }
+
+    fn save_conversation(&self, conv: &Conversation) -> Result<(), ServiceError> {
+        tracing::debug!("saving conversation for session {}", conv.session_id);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+
+    fn add_message(&self, conv: &mut Conversation, msg: ChatMessage) -> Result<(), ServiceError> {
+        tracing::debug!("adding message to session {}", conv.session_id);
+        conv.push(msg);
+        let dir = self.session_dir(&conv.session_id);
+        self.repo.save(&dir, conv)?;
+        Ok(())
+    }
+}

apps/application/src/cms/memory_service.rs

@@ -0,0 +1,59 @@
+//! Memory use-case implementation.
+//!
+//! `MemoryServiceImpl` implements [`MemoryService`] from the domain
+//! layer. It is generic over `R: MemoryRepository`, delegating all
+//! persistence to that adapter.
+//!
+//! # Flow
+//!
+//! Each method delegates to the injected `repo` with the configured
+//! `memory_dir`. Error context is added at this layer to identify which
+//! memory operation failed.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{Memory, MemoryRepository, ServiceError};
+
+/// Service implementation for memory CRUD operations.
+///
+/// Generic over `R: MemoryRepository` so the persistence layer can be
+/// swapped without changing business logic.
+pub struct MemoryServiceImpl<R> {
+    pub repo: R,
+    /// Base directory for memory storage files.
+    pub memory_dir: PathBuf,
+}
+
+impl<R: MemoryRepository> MemoryServiceImpl<R> {
+    /// Create a new service with the given repository and memory directory.
+    pub fn new(repo: R, memory_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating MemoryServiceImpl");
+        Self {
+            repo,
+            memory_dir: memory_dir.into(),
+        }
+    }
+}
+
+impl<R: MemoryRepository> zesdex_domain::cms::MemoryService for MemoryServiceImpl<R> {
+    fn list_memories(&self) -> Result<Vec<String>, ServiceError> {
+        tracing::debug!("listing memories from {:?}", self.memory_dir);
+        self.repo
+            .list(&self.memory_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_memory(&self, memory: &Memory) -> Result<(), ServiceError> {
+        tracing::debug!("saving memory '{}'", memory.name);
+        self.repo.save(&self.memory_dir, memory)?;
+        Ok(())
+    }
+
+    fn delete_memory(&self, name: &str) -> Result<(), ServiceError> {
+        tracing::debug!("deleting memory '{name}'");
+        self.repo
+            .delete(&self.memory_dir, name)
+            .map_err(ServiceError::Repository)
+    }
+}

apps/application/src/cms/mod.rs

@@ -0,0 +1,18 @@
+//! CMS use-case implementations.
+//!
+//! Contains concrete service types that implement the domain's CMS
+//! service traits by coordinating injected repository dependencies.
+//!
+//! # Use Cases
+//!
+//! - [`conversation_service`] — `ConversationServiceImpl`: conversation CRUD
+//! - [`memory_service`] — `MemoryServiceImpl`: long-term memory management
+//! - [`settings_service`] — `SettingsServiceImpl`: settings & app-config management
+
+pub mod conversation_service;
+pub mod memory_service;
+pub mod settings_service;
+
+pub use conversation_service::ConversationServiceImpl;
+pub use memory_service::MemoryServiceImpl;
+pub use settings_service::SettingsServiceImpl;

apps/application/src/cms/settings_service.rs

@@ -0,0 +1,67 @@
+//! Settings and app-config use-case implementation.
+//!
+//! `SettingsServiceImpl` implements [`SettingsService`] from the domain
+//! layer. It is generic over `S: SettingsRepository` and `C: AppConfigRepository`,
+//! delegating persistence to those adapters.
+//!
+//! # Flow
+//!
+//! Each method delegates to the appropriate injected repository with the
+//! configured `base_dir`. The `update_provider` method coordinates between
+//! both repositories: load app config → mutate provider map → save app config.
+
+use std::path::PathBuf;
+use tracing;
+
+use zesdex_domain::cms::{
+    AppConfig, AppConfigRepository, ProviderConfig, ServiceError, Settings, SettingsRepository,
+};
+
+/// Service implementation for settings and app-config operations.
+///
+/// Generic over `S: SettingsRepository` and `C: AppConfigRepository` so
+/// the persistence layer can be swapped without changing business logic.
+pub struct SettingsServiceImpl<S, C> {
+    pub settings_repo: S,
+    pub app_config_repo: C,
+    pub base_dir: PathBuf,
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository> SettingsServiceImpl<S, C> {
+    /// Create a new service with the given repositories and base directory.
+    pub fn new(settings_repo: S, app_config_repo: C, base_dir: impl Into<PathBuf>) -> Self {
+        tracing::debug!("creating SettingsServiceImpl");
+        Self {
+            settings_repo,
+            app_config_repo,
+            base_dir: base_dir.into(),
+        }
+    }
+}
+
+impl<S: SettingsRepository, C: AppConfigRepository> zesdex_domain::cms::SettingsService
+    for SettingsServiceImpl<S, C>
+{
+    fn load_settings(&self) -> Result<Settings, ServiceError> {
+        tracing::debug!("loading settings");
+        self.settings_repo
+            .load(&self.base_dir)
+            .map_err(ServiceError::Repository)
+    }
+
+    fn save_settings(&self, settings: &Settings) -> Result<(), ServiceError> {
+        tracing::debug!("saving settings");
+        self.settings_repo.save(&self.base_dir, settings)?;
+        Ok(())
+    }
+
+    fn update_provider(&self, name: &str, config: &ProviderConfig) -> Result<(), ServiceError> {
+        tracing::debug!("updating provider '{name}'");
+        let mut app_config: AppConfig = self.app_config_repo.load(&self.base_dir)?;
+        app_config
+            .providers
+            .insert(name.to_string(), config.clone());
+        self.app_config_repo.save(&self.base_dir, &app_config)?;
+        Ok(())
+    }
+}

apps/application/src/lib.rs

@@ -0,0 +1,56 @@
+//! # Zesdex Application Layer
+//!
+//! Defines port traits (interfaces) and use-case implementations for the
+//! Zesdex application. This crate depends **only** on the domain crate;
+//! it has no knowledge of infrastructure or interface adapters.
+//!
+//! ## Architecture
+//!
+//! ```text
+//! apps/application/src/
+//! ├── lib.rs              — crate root, re-exports
+//! ├── ports/              — Port traits (interfaces to external services)
+//! │   ├── provider.rs     -- ProviderService (LLM chat completion)
+//! │   ├── password.rs     -- PasswordService (hash / verify)
+//! │   ├── token.rs        -- TokenService (JWT create / verify)
+//! │   └── authentication.rs -- AuthService (combined auth)
+//! ├── auth/               — Auth use-cases
+//! │   ├── oauth_service.rs   -- OAuth 2.0 PKCE flow
+//! │   └── session_service.rs -- Session CRUD lifecycle
+//! └── cms/                — CMS use-cases
+//!     ├── conversation_service.rs -- Conversation CRUD
+//!     ├── memory_service.rs       -- Long-term memory management
+//!     └── settings_service.rs     -- Settings & app-config management
+//! ```
+//!
+//! ## Key Design Principle
+//!
+//! Application services are generic over their repository/port dependencies.
+//! Concrete implementations are injected at the composition root, keeping
+//! the use-case logic independent of any specific persistence or infrastructure
+//! technology.
+
+pub mod agent;
+pub mod auth;
+pub mod cms;
+pub mod ports;
+
+// Re-export port traits for ergonomic access.
+pub use ports::*;
+
+// Re-export auth use-cases.
+pub use auth::{
+    oauth_service::{OAuthFlowStore, OAuthUseCase, TokenExchanger},
+    session_service::SessionServiceImpl,
+};
+
+// Re-export CMS use-cases.
+pub use cms::{
+    conversation_service::ConversationServiceImpl, memory_service::MemoryServiceImpl,
+    settings_service::SettingsServiceImpl,
+};
+
+pub use agent::{
+    turn_service::{compact_messages_with_ai, AgentTurnServiceImpl},
+    AgentTurnService, ExploreOutput, ExploreService, ToolExecutor,
+};

apps/application/src/ports/authentication.rs

@@ -0,0 +1,32 @@
+//! AuthService port — combined authentication operations.
+//!
+//! Defines a high-level authentication trait that composes password
+//! verification and token generation into a single use-case boundary.
+//! Implementations delegate to the injected `PasswordService` and
+//! `TokenService` adapters.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// High-level authentication service combining password verification
+/// and token issuance (login flow).
+///
+/// # Flow
+///
+/// 1. **`authenticate`** — verify a subject's password against a stored hash.
+/// 2. **`issue_tokens`** — generate an access + refresh token pair for a subject.
+///
+/// Implementations are generic over `PasswordService` and `TokenService`
+/// port traits.
+pub trait AuthService: Send + Sync {
+    /// Authenticate a user by verifying a password against a stored hash.
+    ///
+    /// Returns `true` if the password matches, `false` otherwise.
+    fn authenticate(&self, password: &str, hash: &str)
+        -> impl Future<Output = Result<bool>> + Send;
+
+    /// Issue a new access + refresh token pair for the given subject.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn issue_tokens(&self, sub: &str) -> Result<(String, String)>;
+}

apps/application/src/ports/mod.rs

@@ -0,0 +1,22 @@
+//! Port traits — interfaces for external / infrastructure services.
+//!
+//! These traits define the boundaries between the application layer and
+//! the outside world. Infrastructure adapters implement these traits;
+//! the application layer depends only on the trait definitions.
+//!
+//! # Ports
+//!
+//! - [`provider`] — `ProviderService`: LLM chat completion (streaming + non-streaming)
+//! - [`password`] — `PasswordService`: password hashing and verification
+//! - [`token`] — `TokenService`: JWT access/refresh token generation and verification
+//! - [`authentication`] — `AuthService`: combined authentication operations
+
+pub mod authentication;
+pub mod password;
+pub mod provider;
+pub mod token;
+
+pub use authentication::AuthService;
+pub use password::PasswordService;
+pub use provider::ProviderService;
+pub use token::TokenService;

apps/application/src/ports/password.rs

@@ -0,0 +1,24 @@
+//! PasswordService port — password hashing and verification abstraction.
+//!
+//! Defines the trait that password-hashing adapters (argon2, bcrypt, etc.)
+//! implement. The application layer depends only on this trait, never on
+//! a concrete hashing library.
+
+use anyhow::Result;
+use std::future::Future;
+
+/// Abstraction for password hashing and verification.
+///
+/// Implementors handle the actual hashing algorithm (argon2, bcrypt, etc.)
+/// and parameter selection. The trait is `Send + Sync` for use in async
+/// service layers.
+pub trait PasswordService: Send + Sync {
+    /// Hash a plaintext password and return the encoded hash string
+    /// (suitable for storage in a credential store).
+    fn hash(&self, password: &str) -> impl Future<Output = Result<String>> + Send;
+
+    /// Verify a plaintext password against a previously-hashed string.
+    ///
+    /// Returns `true` if the password matches the hash, `false` otherwise.
+    fn verify(&self, password: &str, hash: &str) -> impl Future<Output = Result<bool>> + Send;
+}

apps/application/src/ports/provider.rs

@@ -0,0 +1,56 @@
+//! ProviderService port — LLM chat completion provider abstraction.
+//!
+//! Defines the trait that HTTP-based provider clients (OpenAI, Anthropic,
+//! etc.) implement. Supports both non-streaming and SSE-streaming chat
+//! completion requests.
+//!
+//! # Flow
+//!
+//! 1. Caller builds a message list and optional tool definitions.
+//! 2. `chat` sends a non-streaming request and returns the full response.
+//! 3. `chat_stream` sends a streaming request and invokes `on_event` for
+//!    each parsed `StreamEvent` as it arrives, then returns the assembled
+//!    message and usage.
+
+use anyhow::Result;
+use std::future::Future;
+
+use zesdex_domain::core::{ChatMessage, StreamEvent, ToolDef};
+
+/// Abstraction for an LLM provider chat-completion service.
+///
+/// Both methods accept a message list, optional tool definitions, and
+/// generation parameters. Implementors handle authentication, HTTP
+/// transport, retry logic, and response parsing internally.
+///
+/// # Send + Sync
+///
+/// This trait is `Send + Sync` so it can be shared across async tasks
+/// and injected into service structs that require thread safety.
+pub trait ProviderService: Send + Sync {
+    /// Send a non-streaming chat completion request.
+    ///
+    /// Returns the assistant's `ChatMessage` and optional token usage
+    /// `(prompt_tokens, completion_tokens)`.
+    fn chat(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+
+    /// Send a streaming chat completion request.
+    ///
+    /// `on_event` is called for every parsed SSE event and returns `false`
+    /// to signal abort (caller cancellation). Returns the fully assembled
+    /// assistant message and optional usage once the stream completes.
+    fn chat_stream(
+        &self,
+        messages: &[ChatMessage],
+        tools: Option<Vec<ToolDef>>,
+        max_tokens: Option<u32>,
+        temperature: Option<f32>,
+        on_event: Box<dyn FnMut(&StreamEvent) -> bool + Send>,
+    ) -> impl Future<Output = Result<(ChatMessage, Option<(u64, u64)>)>> + Send;
+}

apps/application/src/ports/token.rs

@@ -0,0 +1,32 @@
+//! TokenService port — JWT access and refresh token abstraction.
+//!
+//! Defines the trait that JWT adapter implementations provide. Covers
+//! token generation (pair of access + refresh tokens) and access token
+//! verification (returns the subject claim).
+
+use anyhow::Result;
+
+/// Abstraction for JWT-based token generation and verification.
+///
+/// Implementors handle signing key management, token serialisation,
+/// and expiry validation. The trait is `Send + Sync` for use across
+/// thread boundaries.
+pub trait TokenService: Send + Sync {
+    /// Generate an access + refresh token pair for the given subject
+    /// identifier.
+    ///
+    /// Returns `(access_token, refresh_token)`.
+    fn generate_tokens(&self, sub: &str) -> Result<(String, String)>;
+
+    /// Verify an access token and return the embedded subject claim.
+    ///
+    /// Returns `Err` if the token is expired, malformed, or has an
+    /// invalid signature.
+    fn verify_access_token(&self, token: &str) -> Result<String>;
+
+    /// Verify a refresh token and return the embedded subject claim.
+    ///
+    /// Returns `Err` if the token is expired, malformed, or has an
+    /// invalid signature.
+    fn verify_refresh_token(&self, token: &str) -> Result<String>;
+}

apps/bootstrap/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "zesdex-bootstrap"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+# Bootstrap binary — seeds initial system data (permissions, roles,
+# admin user) idempotently. Run once after first deployment.
+[[bin]]
+name = "bootstrap"
+path = "src/main.rs"
+
+[dependencies]
+zesdex-domain = { path = "../domain" }
+zesdex-application = { path = "../application" }
+zesdex-infrastructure = { path = "../infrastructure" }
+
+serde.workspace = true
+serde_json.workspace = true
+chrono.workspace = true
+uuid.workspace = true
+anyhow.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+dirs.workspace = true

apps/bootstrap/src/lib.rs

@@ -0,0 +1,2 @@
+//! Bootstrap library — shared utilities for the bootstrap binary.
+//! The main entry point is in `main.rs`.

apps/bootstrap/src/main.rs

@@ -0,0 +1,44 @@
+//! Bootstrap binary — seeds initial system data idempotently.
+//!
+//! Creates default permissions, roles, and admin user if they don't
+//! already exist. Run once after first deployment.
+//!
+//! Usage: cargo run --bin bootstrap
+
+fn main() -> anyhow::Result<()> {
+    println!("Zesdex Bootstrap — seeding initial data...");
+
+    let store = zesdex_domain::core::Store::new();
+    store.ensure_dirs()?;
+
+    // Seed default settings if not present
+    let settings_path = store.base_dir.join("settings.json");
+    if !settings_path.exists() {
+        let settings = zesdex_domain::cms::Settings::default();
+        let content = serde_json::to_string_pretty(&settings)?;
+        let tmp = store.base_dir.join("settings.json.tmp");
+        std::fs::write(&tmp, &content)?;
+        std::fs::File::open(&tmp)?.sync_all()?;
+        std::fs::rename(&tmp, &settings_path)?;
+        println!("  ✓ Default settings created");
+    } else {
+        println!("  · Settings already exist, skipping");
+    }
+
+    // Seed default app config if not present
+    let config_path = store.base_dir.join("app_config.json");
+    if !config_path.exists() {
+        let config = zesdex_domain::cms::AppConfig::default();
+        let content = serde_json::to_string_pretty(&config)?;
+        let tmp = store.base_dir.join("app_config.json.tmp");
+        std::fs::write(&tmp, &content)?;
+        std::fs::File::open(&tmp)?.sync_all()?;
+        std::fs::rename(&tmp, &config_path)?;
+        println!("  ✓ Default app_config created");
+    } else {
+        println!("  · App config already exists, skipping");
+    }
+
+    println!("Bootstrap complete.");
+    Ok(())
+}

apps/domain/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "zesdex-domain"
+version.workspace = true
+edition.workspace = true
+authors.workspace = true
+
+# Domain layer — PURE entities, value objects, repository/service traits.
+# Zero framework dependencies. Only serde for serialization, chrono for
+# timestamps, uuid for identity.
+[dependencies]
+serde.workspace = true
+serde_json.workspace = true
+chrono.workspace = true
+uuid.workspace = true
+base64.workspace = true
+sha2.workspace = true
+url.workspace = true
+libc.workspace = true
+anyhow.workspace = true
+tracing.workspace = true

apps/domain/src/agent/defaults.rs

@@ -0,0 +1,34 @@
+//! Shared default constants used across the application.
+//!
+//! Centralising these values eliminates the hardcoded-string duplication
+//! that existed when every call site provided its own inline fallback.
+//! Consumers should reference these constants rather than repeating
+//! the string literals.
+
+/// Default LLM provider API base URL.
+pub const DEFAULT_API_BASE: &str = "https://opencode.ai/zen/v1";
+
+/// Default LLM model identifier.
+pub const DEFAULT_MODEL: &str = "deepseek-v4-flash-free";
+
+/// Fallback JWT secret used only when `JWT_SECRET` env var is unset.
+/// In production this MUST be configured via environment variable.
+pub const FALLBACK_JWT_SECRET: &str = "dev-secret";
+
+/// Default context window size (128k tokens).
+pub const DEFAULT_CONTEXT_WINDOW: usize = 256_000;
+
+/// Maximum tool-call iterations per agent turn.
+pub const MAX_TOOL_ITERATIONS: u32 = 50;
+
+/// Maximum subagent tool-call iterations.
+pub const MAX_SUBAGENT_ITERATIONS: u32 = 25;
+
+/// Default LLM request max tokens.
+pub const DEFAULT_MAX_TOKENS: u32 = 4096;
+
+/// Default temperature for the main agent.
+pub const DEFAULT_TEMPERATURE: f64 = 0.7;
+
+/// Default temperature for compaction / summary calls.
+pub const DEFAULT_COMPACT_TEMPERATURE: f64 = 0.3;

apps/domain/src/agent/mod.rs

@@ -0,0 +1,260 @@
+//! Domain types for agent lifecycle: turn events, session runtime, progress
+//! reporting, prompts, and the agent-turn parameter bundle.
+
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+use crate::core::{ChatMessage, ToolCallResult, UsageStats};
+
+pub mod defaults;
+pub mod progress;
+pub mod prompt;
+
+/// Which kind of caller (main agent vs. subagent vs. reviewer) is
+/// invoking a tool, used to scope permissions and tag log/output paths.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Hash)]
+pub enum Origin {
+    /// The main agent turn loop.
+    Main,
+    /// A spawned subagent (test-gen, arch-review, security-review, etc.).
+    SubAgent,
+    /// The auto-inline review step after an edit.
+    Reviewer,
+}
+
+impl Origin {
+    /// Short string tag for this origin, used in filenames and logs.
+    pub fn tag(self) -> String {
+        match self {
+            Origin::Main => "main",
+            Origin::SubAgent => "subagent",
+            Origin::Reviewer => "reviewer",
+        }
+        .to_string()
+    }
+}
+
+/// Severity/category of a toast notification, used to pick its color.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ToastKind {
+    Info,
+    Success,
+    Warning,
+    Error,
+    Lesson,
+}
+
+/// A transient status message shown in the TUI, auto-dismissed after `lifetime_ms`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Toast {
+    pub kind: ToastKind,
+    pub message: String,
+    pub created_at: i64,
+    pub lifetime_ms: u64,
+}
+
+impl Toast {
+    /// Create a toast with a default 5-second lifetime, stamped with now.
+    pub fn new(kind: ToastKind, message: String) -> Self {
+        Toast {
+            kind,
+            message,
+            created_at: chrono::Utc::now().timestamp_millis(),
+            lifetime_ms: 5000,
+        }
+    }
+
+    /// Whether this toast's lifetime has elapsed as of `now_ms`.
+    pub fn expired(&self, now_ms: i64) -> bool {
+        let lifetime = self.lifetime_ms as i64;
+        now_ms - self.created_at > lifetime
+    }
+}
+
+/// Agent status for workflow engine progress tracking.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub enum AgentStatus {
+    Pending,
+    Running,
+    Completed,
+    Failed(String),
+    Cancelled,
+}
+
+impl std::fmt::Display for AgentStatus {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            AgentStatus::Pending => write!(f, "pending"),
+            AgentStatus::Running => write!(f, "running"),
+            AgentStatus::Completed => write!(f, "completed"),
+            AgentStatus::Failed(msg) => write!(f, "failed: {msg}"),
+            AgentStatus::Cancelled => write!(f, "cancelled"),
+        }
+    }
+}
+
+/// Events emitted onto the turn-event queue while an agent turn runs,
+/// consumed by the event loop to update state and drive re-renders.
+#[derive(Debug, Clone)]
+pub enum TurnEvent {
+    AssistantMessage(ChatMessage),
+    ToolResult {
+        tool_call_id: String,
+        tool_name: String,
+        output: String,
+        is_error: bool,
+        path: Option<String>,
+    },
+    SystemNote {
+        kind: String,
+        message: String,
+    },
+    StreamStart,
+    StreamToken(String),
+    StreamReasoning(String),
+    StreamDone(ChatMessage),
+    Usage {
+        tokens_in: u64,
+        tokens_out: u64,
+    },
+    ReviewUsage {
+        tokens_in: u64,
+        tokens_out: u64,
+    },
+    Compacted(Vec<ChatMessage>),
+    Error(String),
+    Done,
+    WorkflowAgentUpdate {
+        agent_id: String,
+        agent_name: String,
+        status: AgentStatus,
+    },
+    TodoUpdate(String),
+    PlanUpdate(String),
+    /// Structured progress report from a subagent or workflow node,
+    /// carrying the current tool name and optional step counters.
+    AgentProgress(crate::agent::progress::AgentProgress),
+}
+
+/// How a pending tool call should be executed when the turn resumes.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum ExecutionModel {
+    Inline,
+    Deferred,
+    AsyncTokio,
+}
+
+/// A tool call awaiting execution, along with which execution model
+/// (inline, deferred, async) it should run under.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PendingTool {
+    pub tool_name: String,
+    pub args: serde_json::Value,
+    pub execution_model: ExecutionModel,
+}
+
+/// Reference to a background bash job tracked in session state.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BashJobRef {
+    pub id: String,
+    pub command: String,
+    pub started_at: i64,
+    pub running: bool,
+}
+
+/// Tracks counts of learned patterns by outcome and lifecycle stage.
+#[derive(Debug, Clone, Default)]
+pub struct LessonStats {
+    /// Total number of lessons tracked.
+    pub total: u32,
+    /// User-initiated lessons.
+    pub user: u32,
+    /// Feedback-driven lessons.
+    pub feedback: u32,
+    /// Project-scoped lessons.
+    pub project: u32,
+    /// Reference-scoped lessons.
+    pub reference: u32,
+    /// Currently active lessons.
+    pub active: u32,
+    /// Stale (outdated) lessons.
+    pub stale: u32,
+    /// Contradicted lessons.
+    pub contradicted: u32,
+    /// Human-authored lessons.
+    pub human: u32,
+    /// Verified lessons.
+    pub verified: u32,
+    /// Unverified lessons.
+    pub unverified: u32,
+}
+
+/// Per-session runtime state: message history, pending tool queue,
+/// background bash jobs, lesson/review counters.
+#[derive(Debug, Clone)]
+pub struct SessionRuntime {
+    pub messages: Vec<ChatMessage>,
+    pub tool_call_results: Vec<ToolCallResult>,
+    pub pending_tool_queue: Vec<PendingTool>,
+    pub bash_jobs: Vec<BashJobRef>,
+    pub subagent_queue: usize,
+    pub edit_count: u32,
+    pub consecutive_empty_reviews: u32,
+    pub session_start: i64,
+    /// Aggregated lesson statistics.
+    pub lessons: LessonStats,
+    pub review_count: u32,
+    pub session_dir: PathBuf,
+    pub usage: UsageStats,
+    pub hive_mind_converged: bool,
+}
+
+impl SessionRuntime {
+    pub fn new(session_dir: PathBuf) -> Self {
+        SessionRuntime {
+            messages: Vec::new(),
+            tool_call_results: Vec::new(),
+            pending_tool_queue: Vec::new(),
+            bash_jobs: Vec::new(),
+            subagent_queue: 0,
+            edit_count: 0,
+            consecutive_empty_reviews: 0,
+            session_start: chrono::Utc::now().timestamp_millis(),
+            lessons: LessonStats::default(),
+            review_count: 0,
+            session_dir,
+            usage: UsageStats::default(),
+            hive_mind_converged: false,
+        }
+    }
+
+    pub fn push_message(&mut self, msg: ChatMessage) {
+        self.messages.push(msg);
+    }
+}
+
+/// Simple ASCII progress display for a long-running operation.
+#[derive(Debug, Clone)]
+pub struct ProgressState {
+    pub current: u64,
+    pub total: u64,
+    pub message: String,
+    pub start_time: i64,
+}
+
+use std::collections::VecDeque;
+use std::sync::atomic::AtomicBool;
+use std::sync::{Arc, Mutex};
+
+/// Owned parameters required to spawn and execute an agent turn.
+pub struct AgentTurnParams {
+    pub messages: Vec<ChatMessage>,
+    pub session_dir: PathBuf,
+    pub workspace_roots: Vec<PathBuf>,
+    pub turn_events: Arc<Mutex<VecDeque<TurnEvent>>>,
+    pub in_flight: Arc<AtomicBool>,
+    pub abort: Arc<AtomicBool>,
+    pub api_key: String,
+    pub model: String,
+    pub api_base: Option<String>,
+}

apps/domain/src/agent/progress.rs

@@ -0,0 +1,81 @@
+//! Progress reporting types for long-running agent and subagent operations.
+//!
+//! These types are emitted onto the turn-event queue to drive the TUI's
+//! spinner, progress bar, and agent-status sidebar. They are pure domain
+//! types with no I/O or framework dependency.
+
+use crate::agent::AgentStatus;
+
+/// Describes progress within a single subagent or workflow-node execution.
+///
+/// Emitted as a `TurnEvent::AgentProgress` so the UI can show which tool
+/// the subagent is currently invoking, or which step it has reached.
+#[derive(Debug, Clone)]
+pub struct AgentProgress {
+    /// Unique identifier for this agent (e.g. `"Node-0-1"`, `"auto-review"`).
+    pub agent_id: String,
+    /// Human-readable display name shown in the TUI sidebar.
+    pub agent_name: String,
+    /// Current lifecycle status.
+    pub status: AgentStatus,
+    /// Optional description of the current tool or step being executed.
+    /// Set to `None` when the agent is not actively executing a tool.
+    pub current_tool: Option<String>,
+    /// Optional progress range: (completed_steps, total_steps).
+    /// When `None`, the agent shows an indeterminate spinner.
+    pub steps: Option<(u32, u32)>,
+}
+
+impl AgentProgress {
+    /// Mark this agent as running with an optional tool name.
+    pub fn running(
+        agent_id: impl Into<String>,
+        agent_name: impl Into<String>,
+        current_tool: Option<String>,
+    ) -> Self {
+        AgentProgress {
+            agent_id: agent_id.into(),
+            agent_name: agent_name.into(),
+            status: AgentStatus::Running,
+            current_tool,
+            steps: None,
+        }
+    }
+
+    /// Mark this agent as pending (queued but not yet started).
+    pub fn pending(agent_id: impl Into<String>, agent_name: impl Into<String>) -> Self {
+        AgentProgress {
+            agent_id: agent_id.into(),
+            agent_name: agent_name.into(),
+            status: AgentStatus::Pending,
+            current_tool: None,
+            steps: None,
+        }
+    }
+
+    /// Mark this agent as completed successfully.
+    pub fn completed(agent_id: impl Into<String>, agent_name: impl Into<String>) -> Self {
+        AgentProgress {
+            agent_id: agent_id.into(),
+            agent_name: agent_name.into(),
+            status: AgentStatus::Completed,
+            current_tool: None,
+            steps: None,
+        }
+    }
+
+    /// Mark this agent as failed with an error message.
+    pub fn failed(
+        agent_id: impl Into<String>,
+        agent_name: impl Into<String>,
+        error: String,
+    ) -> Self {
+        AgentProgress {
+            agent_id: agent_id.into(),
+            agent_name: agent_name.into(),
+            status: AgentStatus::Failed(error),
+            current_tool: None,
+            steps: None,
+        }
+    }
+}

apps/domain/src/agent/prompt.rs

@@ -0,0 +1,92 @@
+//! System prompts and directive templates for agent and subagent turns.
+//!
+//! Centralising all prompt text here keeps the core turn logic free of
+//! hardcoded prose, making prompts easier to maintain, review, and localise.
+//!
+//! # Flow
+//! The application layer's `AgentTurnServiceImpl` calls `main_agent_prompt()`
+//! to construct the system message at the start of each turn. Subagent and
+//! review prompts are provided by their respective modules.
+
+/// Build the main-agent system prompt.
+///
+/// The prompt establishes the agent's identity as Zesdex, an AI coding
+/// assistant, and defines the priority hierarchy that governs tool selection:
+///
+/// 1. **Workflow first** — `workflow_run` / `hive_mind` for complex tasks
+/// 2. **Planning & TODOs** — `plan_enter` / `todowrite` for structural work
+/// 3. **Reasoning** — `seq_think` for deep analysis
+/// 4. **Tool execution** — direct tools for simple actions
+pub fn main_agent_prompt() -> String {
+    "\
+You are Zesdex, an AI coding assistant. You have access to various tools \
+via native function calling to help the user.
+
+CRITICAL DIRECTIVES & PRIORITY HIERARCHY:
+1. WORKFLOW FIRST: For any multi-step, complex, or non-trivial task, \
+you MUST prioritise using `workflow_run` (to construct and execute a \
+multi-phase YAML workflow) or `hive_mind` (to orchestrate parallel \
+autonomous agents). Workflows are your primary strategy.
+2. PLANNING & TODOS: Use `plan_enter` to establish high-level \
+architectural plans and `todowrite` to maintain granular task checklists.
+3. REASONING: Use `seq_think` for deep step-by-step analysis.
+4. TOOL EXECUTION: Execute individual tools (file edits, terminal commands) \
+within or guided by your workflows. If an error occurs, analyse and fix it.
+
+Respond conversationally, concisely, and helpfully."
+        .to_string()
+}
+
+/// Build a subagent directive prompt.
+///
+/// The directive is embedded in a system message that also communicates the
+/// current working directory and workspace root so the subagent can resolve
+/// paths correctly.
+pub fn subagent_directive(directive: &str, cwd: &str, ws_root: &str) -> String {
+    format!(
+        "\
+You are a focused subagent.
+
+Current directory (PWD): {cwd}
+Workspace root: {ws_root}
+
+Your directive:
+{directive}
+
+Complete the directive autonomously using the tools available to you. \
+Return your final answer when done."
+    )
+}
+
+/// Build a conversation-compaction prompt.
+///
+/// The LLM is asked to produce a concise bulleted summary of the key
+/// requests, decisions, tools executed, and files modified.
+pub fn compaction_prompt() -> String {
+    "\
+You are a helpful assistant summarising conversation history. \
+Provide a concise summary of the key user requests, decisions, tools \
+executed, and modified files. Format as a clear bulleted list."
+        .to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn main_prompt_is_non_empty() {
+        let prompt = main_agent_prompt();
+        assert!(!prompt.is_empty());
+        assert!(prompt.contains("Zesdex"));
+        assert!(prompt.contains("WORKFLOW FIRST"));
+    }
+
+    #[test]
+    fn subagent_directive_includes_directive_text() {
+        let prompt = subagent_directive("test directive", "/home", "/home/project");
+        assert!(prompt.contains("test directive"));
+        assert!(prompt.contains("/home"));
+        assert!(prompt.contains("/home/project"));
+    }
+}

apps/domain/src/auth/commands.rs

@@ -0,0 +1,30 @@
+//! Command types for IAM domain operations.
+//!
+//! Following the `NewXxx` / command pattern from clean architecture,
+//! these types encapsulate the input data for create/update operations
+//! on domain entities. They decouple presentation DTOs from the entity
+//! mutation surface and provide a clear boundary for validation.
+
+/// Command to create a new session.
+///
+/// Carries only the data needed to construct a session entity — the
+/// service generates the UUID and timestamp internally.
+#[derive(Debug, Clone)]
+pub struct NewSession {
+    /// Human-readable session title.
+    pub title: String,
+}
+
+impl From<String> for NewSession {
+    fn from(title: String) -> Self {
+        Self { title }
+    }
+}
+
+impl From<&str> for NewSession {
+    fn from(title: &str) -> Self {
+        Self {
+            title: title.to_string(),
+        }
+    }
+}

apps/domain/src/auth/error.rs

@@ -0,0 +1,62 @@
+//! Domain error types for the IAM (auth) module.
+//!
+//! Typed error enums replace `anyhow::Result` in domain traits and
+//! application services, enabling callers to match on specific error
+//! variants (e.g. `NotFound` vs `Conflict`) rather than string-checking.
+//!
+//! # Components
+//!
+//! - [`RepositoryError`] — persistence-layer errors (not found, conflict, I/O)
+//! - [`ServiceError`] — use-case / orchestration errors (config, state
+//!   mismatch, provider failures)
+
+use std::fmt;
+
+use crate::error::DomainError;
+
+/// Shared repository error type for IAM persistence operations.
+pub type RepositoryError = DomainError;
+
+/// Errors from service / use-case operations in the IAM domain.
+#[derive(Debug)]
+pub enum ServiceError {
+    /// A repository operation failed.
+    Repository(DomainError),
+    /// The provided configuration is invalid.
+    InvalidConfig(String),
+    /// OAuth state mismatch — possible CSRF attack.
+    StateMismatch,
+    /// The OAuth provider returned an error.
+    OAuthProvider(String),
+    /// A generic error with a message.
+    Other(String),
+}
+
+impl From<DomainError> for ServiceError {
+    fn from(err: DomainError) -> Self {
+        ServiceError::Repository(err)
+    }
+}
+
+impl fmt::Display for ServiceError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            ServiceError::Repository(err) => write!(f, "repository error: {err}"),
+            ServiceError::InvalidConfig(msg) => write!(f, "invalid configuration: {msg}"),
+            ServiceError::StateMismatch => {
+                write!(f, "OAuth state mismatch — possible CSRF attack")
+            }
+            ServiceError::OAuthProvider(msg) => write!(f, "OAuth provider error: {msg}"),
+            ServiceError::Other(msg) => write!(f, "{msg}"),
+        }
+    }
+}
+
+impl std::error::Error for ServiceError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        match self {
+            ServiceError::Repository(err) => Some(err),
+            _ => None,
+        }
+    }
+}

apps/domain/src/auth/iam_session.rs

@@ -0,0 +1,12 @@
+//! IAM Session re-export.
+//!
+//! Re-exports `Session` from the auth module for consistent IAM-boundary
+//! imports. Consumers of the IAM module import `Session` from here rather
+//! than from the core session module directly, keeping the dependency
+//! internal and allowing the IAM crate to own its domain vocabulary.
+
+pub use super::session::Session;
+
+/// Alias for `Session` used in IAM contexts to distinguish from other
+/// session types in the system.
+pub type IamSession = Session;

apps/domain/src/auth/mod.rs

@@ -0,0 +1,36 @@
+//! Authentication domain entities, commands, errors, and repository/service traits.
+//!
+//! Combines the session types from `zesdex-entities` (auth sub-module) with the
+//! IAM domain types (commands, OAuth, repository/service traits) from `zesdex-iam`.
+//!
+//! # Sub-modules
+//!
+//! - [`session`] — `Session` entity (session metadata)
+//! - [`session_id`] — `SessionId` value object (validated newtype)
+//! - [`session_lock`] — `SessionLock` RAII guard (PID-file lock)
+//! - [`oauth`] — `OAuthToken`, `OAuthConfig` entities
+//! - [`iam_session`] — Re-export of `Session` for IAM-boundary consistency
+//! - [`commands`] — `NewSession` command type
+//! - [`error`] — `RepositoryError`, `ServiceError` types
+//! - [`repository`] — `SessionRepository`, `SessionLockRepository`, `OAuthRepository`
+//! - [`service`] — `SessionService`, `OAuthService` traits
+
+pub mod commands;
+pub mod error;
+pub mod iam_session;
+pub mod oauth;
+pub mod repository;
+pub mod service;
+pub mod session;
+pub mod session_id;
+pub mod session_lock;
+
+pub use commands::NewSession;
+pub use error::{RepositoryError, ServiceError};
+pub use iam_session::IamSession;
+pub use oauth::{OAuthConfig, OAuthToken};
+pub use repository::{OAuthRepository, SessionLockRepository, SessionRepository};
+pub use service::{OAuthService, SessionService};
+pub use session::Session;
+pub use session_id::SessionId;
+pub use session_lock::SessionLock;

apps/domain/src/auth/oauth.rs

@@ -0,0 +1,53 @@
+//! Pure OAuth entities — no HTTP or persistence logic.
+//!
+//! # Components
+//!
+//! - [`OAuthToken`] — access token with optional refresh token, epoch expiry
+//! - [`OAuthConfig`] — provider configuration (auth URL, token URL, client id,
+//!   optional client secret, scopes)
+use serde::{Deserialize, Serialize};
+
+/// An OAuth 2.0 access token with optional refresh token and absolute
+/// expiry time (epoch seconds).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OAuthToken {
+    /// The OAuth 2.0 access token string.
+    pub access_token: String,
+    /// Optional refresh token for long-lived access.
+    pub refresh_token: Option<String>,
+    /// Absolute expiry timestamp (epoch seconds since UNIX_EPOCH).
+    pub expires_at: u64,
+    /// Token type, e.g. `"Bearer"`.
+    pub token_type: String,
+}
+
+/// Static configuration for an OAuth provider.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OAuthConfig {
+    /// Authorization endpoint URL.
+    pub auth_url: String,
+    /// Token exchange endpoint URL.
+    pub token_url: String,
+    /// OAuth client identifier.
+    pub client_id: String,
+    /// Optional client secret (not all flows require it).
+    pub client_secret: Option<String>,
+    /// Space-separated list of requested scopes.
+    pub scopes: Vec<String>,
+}
+
+impl Default for OAuthConfig {
+    fn default() -> Self {
+        OAuthConfig {
+            auth_url: String::new(),
+            token_url: String::new(),
+            client_id: String::new(),
+            client_secret: None,
+            scopes: vec![
+                "openid".to_string(),
+                "profile".to_string(),
+                "email".to_string(),
+            ],
+        }
+    }
+}

apps/domain/src/auth/repository.rs

@@ -0,0 +1,57 @@
+//! Repository trait definitions (pure — no impls, no concrete persistence).
+//!
+//! Defines the repository contracts that infrastructure adapters implement.
+//! Following clean architecture, domain code depends only on these traits,
+//! not on concrete persistence libraries.
+//!
+//! # Traits
+//!
+//! - [`SessionRepository`] — CRUD for session metadata
+//! - [`SessionLockRepository`] — acquire/release/liveness for session locks
+//! - [`OAuthRepository`] — persist/load OAuth tokens
+
+use std::path::Path;
+
+use crate::auth::error::RepositoryError;
+use crate::auth::oauth::OAuthToken;
+use crate::auth::session::Session;
+use crate::auth::session_id::SessionId;
+
+/// Repository for loading, saving, listing, and deleting sessions.
+pub trait SessionRepository {
+    /// List all loadable sessions under `<base_dir>/sessions/`.
+    fn list_sessions(&self, base_dir: &Path) -> Result<Vec<Session>, RepositoryError>;
+
+    /// Load a single session by id.
+    fn load_session(&self, base_dir: &Path, id: &SessionId) -> Result<Session, RepositoryError>;
+
+    /// Save a session's metadata to disk.
+    fn save_session(&self, base_dir: &Path, session: &Session) -> Result<(), RepositoryError>;
+
+    /// Delete a session directory and all its contents.
+    fn delete_session(&self, base_dir: &Path, id: &SessionId) -> Result<(), RepositoryError>;
+}
+
+/// Repository for per-session PID-file advisory locks.
+pub trait SessionLockRepository {
+    /// Try to acquire the lock for a session directory.
+    /// Returns `true` if the lock was acquired, `false` if another live
+    /// process holds it.
+    fn try_lock(&self, session_dir: &Path) -> Result<bool, RepositoryError>;
+
+    /// Release the lock by removing the lock file.
+    fn unlock(&self, session_dir: &Path) -> Result<(), RepositoryError>;
+
+    /// Check whether a process with the given PID is alive.
+    fn is_alive(&self, pid: u32) -> bool;
+}
+
+/// Repository for persisting and loading OAuth tokens.
+pub trait OAuthRepository {
+    /// Persist an OAuth token to a JSON file.
+    fn save_token(&self, path: &Path, token: &OAuthToken) -> Result<(), RepositoryError>;
+
+    /// Load an OAuth token from a JSON file, returning `None` if the file
+    /// does not exist.
+    fn load_token(&self, path: &Path) -> Result<Option<OAuthToken>, RepositoryError>;
+}

apps/domain/src/auth/service.rs

@@ -0,0 +1,56 @@
+//! Service trait definitions — use-case interfaces for session management
+//! and OAuth flows.
+//!
+//! These traits define the boundary between the application orchestration
+//! layer and the domain. Implementations live in the application layer.
+//!
+//! # Traits
+//!
+//! - [`SessionService`] — create, list, archive sessions
+//! - [`OAuthService`] — start PKCE flow, complete code exchange, retrieve token
+
+use crate::auth::error::ServiceError;
+use crate::auth::oauth::{OAuthConfig, OAuthToken};
+use crate::auth::session::Session;
+use crate::auth::session_id::SessionId;
+
+/// Session management use-case boundary.
+pub trait SessionService {
+    /// Create a new session with a generated UUID and the given title.
+    fn create_session(&self, title: &str) -> Result<Session, ServiceError>;
+
+    /// List all available sessions.
+    fn list_all(&self) -> Result<Vec<Session>, ServiceError>;
+
+    /// Archive a session by id (sets `archived = true`).
+    fn archive_session(&self, id: SessionId) -> Result<(), ServiceError>;
+}
+
+/// OAuth flow use-case boundary.
+pub trait OAuthService {
+    /// Start an OAuth authorization-code + PKCE flow for the given
+    /// `redirect_uri` (the caller is responsible for actually listening on
+    /// it — e.g. a bound `LoopbackServer`). Returns `(auth_url, state)`:
+    /// the URL to send the user to, and the CSRF state token that must be
+    /// passed back into `complete_flow` unchanged.
+    fn start_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+    ) -> Result<(String, String), ServiceError>;
+
+    /// Complete the OAuth flow: validates `state` against the value
+    /// persisted during `start_flow` (bailing on mismatch — this is the
+    /// CSRF check), then exchanges `code` for a token using the same
+    /// `redirect_uri` passed to `start_flow`.
+    fn complete_flow(
+        &self,
+        config: &OAuthConfig,
+        redirect_uri: &str,
+        code: &str,
+        state: &str,
+    ) -> Result<OAuthToken, ServiceError>;
+
+    /// Retrieve the currently stored OAuth token (if any).
+    fn get_token(&self) -> Result<Option<OAuthToken>, ServiceError>;
+}

apps/domain/src/auth/session.rs

@@ -0,0 +1,71 @@
+//! Session metadata: id, title, workspace roots, and message/token counts,
+//! persisted as `session.json` per session directory.
+//!
+//! # Flow
+//!
+//! Created via [`Session::new`] → mutated in-memory → persisted via repository.
+//!
+//! # Components
+//!
+//! - `Session` struct — fields for all session metadata
+//! - `new` — timestamped constructor
+//! - `session_dir` / `conversation_path` — pure path computation
+use chrono::Utc;
+use serde::{Deserialize, Serialize};
+use std::path::{Path, PathBuf};
+
+/// Metadata for one conversation session (distinct from the message
+/// history itself, which lives in `Conversation`/the msglog).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Session {
+    /// Unique session identifier (validated against path traversal in `load`).
+    pub id: String,
+    /// Epoch-millis timestamp of creation (`Utc::now().timestamp_millis()`).
+    pub created_at: i64,
+    /// Epoch-millis timestamp of last update.
+    pub updated_at: i64,
+    /// Human-readable title for the conversation.
+    pub title: String,
+    /// Model identifier string, e.g. `"anthropic/claude-opus-4-8"`.
+    pub model: String,
+    /// Workspace root directories associated with this session.
+    pub workspace_roots: Vec<PathBuf>,
+    /// Running count of messages in the conversation.
+    pub message_count: u32,
+    /// Running count of tokens consumed.
+    pub token_count: u32,
+    /// Soft-delete flag — archived sessions are hidden from the default list.
+    pub archived: bool,
+    /// Optional AI-generated conversation summary (used for compact context).
+    pub summary: Option<String>,
+}
+
+impl Session {
+    /// Create a new session with the given id/title, defaulting the
+    /// model, workspace root (current dir), and counters.
+    pub fn new(id: String, title: String) -> Self {
+        let now = Utc::now().timestamp_millis();
+        Session {
+            id,
+            created_at: now,
+            updated_at: now,
+            title,
+            model: "anthropic/claude-opus-4-8".to_string(),
+            workspace_roots: vec![std::env::current_dir().unwrap_or_default()],
+            message_count: 0,
+            token_count: 0,
+            archived: false,
+            summary: None,
+        }
+    }
+
+    /// Compute this session's directory under `<base_dir>/sessions/<id>`.
+    pub fn session_dir(&self, base_dir: &Path) -> PathBuf {
+        base_dir.join("sessions").join(&self.id)
+    }
+
+    /// Compute this session's `conversation.json` path.
+    pub fn conversation_path(&self, base_dir: &Path) -> PathBuf {
+        self.session_dir(base_dir).join("conversation.json")
+    }
+}

apps/domain/src/auth/session_id.rs

@@ -0,0 +1,106 @@
+//! Validated session identifier newtype.
+//!
+//! [`SessionId`] wraps a `String` that has been checked for path-traversal
+//! characters. Construction via `SessionId::new(str)` validates the input
+//! once; the guarantee is then enforced by the type system for all
+//! downstream use.
+//!
+//! # Validation rules
+//!
+//! - Must not be empty
+//! - Must only contain alphanumeric characters, hyphens, and underscores
+
+use serde::{Deserialize, Serialize};
+use std::fmt;
+use std::path::Path;
+use std::path::PathBuf;
+
+/// A validated session identifier.
+///
+/// Guarantees the inner string is non-empty and contains no path-traversal
+/// characters (`/`, `\\`, `..`) or other unsafe delimiters.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub struct SessionId(String);
+
+impl SessionId {
+    /// Validate and construct a `SessionId`.
+    ///
+    /// Returns `Err(msg)` if the input contains path separators, `..`, or
+    /// is empty.
+    pub fn new(id: &str) -> Result<Self, String> {
+        if id.is_empty() {
+            return Err("session id must not be empty".to_string());
+        }
+        if id.contains('/') || id.contains('\\') || id.contains("..") {
+            return Err(format!(
+                "session id '{id}' must not contain path separators"
+            ));
+        }
+        Ok(SessionId(id.to_string()))
+    }
+
+    /// Return the underlying string.
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+
+    /// Return the underlying owned string.
+    pub fn into_string(self) -> String {
+        self.0
+    }
+
+    /// Append this session id as a component of `base_dir`, yielding
+    /// `base_dir / self.0`.
+    ///
+    /// Safe because the id has been validated to contain no path separators.
+    pub fn join_to(&self, base_dir: &Path) -> PathBuf {
+        base_dir.join(&self.0)
+    }
+}
+
+impl AsRef<str> for SessionId {
+    fn as_ref(&self) -> &str {
+        &self.0
+    }
+}
+
+impl fmt::Display for SessionId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl From<SessionId> for String {
+    fn from(sid: SessionId) -> Self {
+        sid.0
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_valid_uuids() {
+        assert!(SessionId::new("550e8400-e29b-41d4-a716-446655440000").is_ok());
+        assert!(SessionId::new("my-session_123").is_ok());
+    }
+
+    #[test]
+    fn test_rejects_path_traversal() {
+        assert!(SessionId::new("../etc/passwd").is_err());
+        assert!(SessionId::new("foo/../../bar").is_err());
+        assert!(SessionId::new("foo\\..\\bar").is_err());
+    }
+
+    #[test]
+    fn test_rejects_empty() {
+        assert!(SessionId::new("").is_err());
+    }
+
+    #[test]
+    fn test_into_string() {
+        let sid = SessionId::new("abc-123").unwrap();
+        assert_eq!(sid.into_string(), "abc-123");
+    }
+}