Extract WebSocket business logic into AgentSessionOrchestrator ...

- Create navi/core/orchestrator.py with AgentSessionOrchestrator and SessionRun
- Orchestrator owns _runs, _busy_sessions, Agent creation, run_agent(), run_recall()
- Transport-agnostic: accepts notify callback from WebSocket handler
- WebSocket handler (websocket.py) now only does serialization/deserialization
- _fire_recall delegates to orchestrator.run_recall() instead of inline logic
- recall_scheduler_loop now accepts orchestrator parameter
- AppContainer gains .orchestrator field, created in create_container()
- deps.py: add get_orchestrator()
- Update integration tests for scheduler_loop and websocket unit tests

All 392 tests pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Add WebSocket handler unit tests ...

Tests for reconnect/replay, concurrent-run guard, event buffering,
and session_sync behavior after both normal and recall runs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix PgSessionStore import in container.py ...

`PgSessionStore` lives in `navi.core.pg_session_store`, not `navi.core.session`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Replace global lazy singletons with explicit AppContainer + lifespan ...

- Create navi/core/container.py with AppContainer dataclass and create_container()
- Rewrite navi/api/deps.py: remove module-level singletons, add _container global
  fallback + set_container(), use _resolve_container() for all getters
- Replace @app.on_event with @asynccontextmanager lifespan in main.py
- Update routes to use Depends(get_scheduler) instead of calling get_scheduler()
- Fix FastAPI body parsing bug: remove dataclass parameters from Depends getters
  (FastAPI was treating AppContainer sub-dependencies as Body params, forcing
  embed=True on all endpoint body params and causing 422 errors)
- Update websocket.py to use _resolve_container() instead of get_registries()
- Update integration test fixtures to build AppContainer and call set_container()
- Remove obsolete tests/unit/test_startup.py (tests removed _on_startup)
- Fix test_scheduler_loop.py fixture (get_registries no longer exists)

All 387 tests pass (excluding websocket hang tests).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Add legacy redirect for session files and fix STL viewer error handling ...

- Add /sessions/{id}/files/{filename} → /api/sessions/{id}/files/{filename}
  redirect in main.py for backward compatibility with old persisted URLs
- Fix STL viewer: wrap all renderer-dependent code in `if (renderer)`
  to prevent cascading errors when WebGL is unavailable
- Rebuild dist

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix SyntaxError: Illegal return statement in STL viewer ...

The previous fix replaced `throw err` with `return` inside a module,
but top-level `return` is a SyntaxError in ES modules.
Reverted to `throw err` — the error message is already shown on screen,
so the user still gets a graceful fallback even though the error appears
in the console.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix session file URLs (add /api prefix) and WebGL error handling in STL viewer ...

Backend:
- _file_url in content_store.py now returns /api/sessions/... instead of /sessions/...
- share_file.py URL construction updated to include /api
- content_publish.py docstring updated to reflect correct endpoint

Frontend:
- contentLinks.js: avoid double /api prefix in dev mode when backend already returns it
- stl.html: replace throw err with return after showing WebGL fallback message
- Rebuild dist

Tests:
- Update expected URLs in test_content_store.py and test_share_file.py

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Step 5-7: Extract async generators from run_stream, unify run() as wrapper ...

- _compression_events_preturn / _compression_events_midturn
- _consume_stream (uses StreamState)
- _execute_tools_with_sink
- run() is now a thin wrapper around run_stream() collecting StreamEnd
- Remove dead imports (json, LLMChunk)
- Mark god-object decomposition complete in architecture_weak_spots.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Step 4: Extract SubAgentRunner from run_ephemeral() ...

- Create navi/core/subagent_runner.py with full sub-agent loop logic
- Move _iter_stream_guarded to navi/core/stream_guard.py
- Move _check_context_size to ContextCompressor.check_context_size()
- Extract build_tool_list() and load_user_enabled_tools() to tool_utils.py
- Agent.run_ephemeral() becomes a thin wrapper delegating to SubAgentRunner
- Remove ~310 lines from agent.py
- All existing run_ephemeral tests pass unchanged

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Step 3: Extract AntiStallMonitor from run_stream() ...

- Create navi/core/anti_stall.py with AntiStallMonitor class
- Encapsulates stall detection (todo progress + repeated tool calls)
- Encapsulates adaptive re-plan (failed todo step detection)
- Provides init() / pre_turn() / post_turn() two-phase interface
- Remove ~50 lines of stall/replan logic from agent.py run_stream()
- Remove _todo_status_snapshot and _todo_failed_steps helpers from agent.py
- Update AgentTurnContext: remove stall fields (now live in AntiStallMonitor)
- Add 13 unit tests for pre_turn and post_turn behavior

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Step 2: Extract AgentTurnContext dataclass from run_stream() ...

Move 10 turn-level local variables from run_stream() into AgentTurnContext:
- turn_start, tool_call_count, turn_tokens, subagent_tokens
- stall_no_todo, stall_repeat_tools, prev_tool_sigs
- known_failed, replan_msg, injected_fact_ids

This makes run_stream() readable and prepares the ground for
AntiStallMonitor (Step 3) which will consume this context.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Extract ContextCompressor, fix STL viewer, expand test suite, add architecture audit docs ...

- Extract ContextCompressor from agent.py (Step 1 of god-object refactor)
- Add retry + hard-truncate fallback logic to ContextCompressor
- Add unit tests: agent loop (14), compressor (18), KV store (8),
  auth encrypt (3), auth deps (13), todo/scratchpad/image_view/memory
- Fix WebGL STL viewer: allow-same-origin sandbox + graceful fallback
- Add CompressionStarted event and client-side compression notice
- Add docs/architecture_weak_spots.md and plan_01_god_object_agent.md
- Update test_events.py and test_agent_context_size.py for new logic

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix review issues: KV-store NULL, SVG messages, filesystem tests + docs ...

Bugs fixed:
- filesystem.py: add missing `import re` (grep was broken in production)
- image_view.py: consistent SVG rejection message for URL and file paths
- store/__init__.py: normalize user_id None→'' to prevent duplicate rows
  in unique constraint for anonymous sessions; add DDL migration for
  existing NULL values

Tests:
- Add 10 unit tests for filesystem copy, grep, diff operations

Documentation:
- agent.md: document streaming guard wrapper, system prompt caching,
  ContextVar restoration in subagents
- tools.md: document middleware hooks
- websocket.md: document image upload limits and concurrent run guard
- store.md: document user_id normalization
- mechanics.md: mark newly-documented mechanics as documented

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Add comprehensive mechanics catalog (docs/mechanics.md) ...

Master catalog of all mechanisms in the Navi project:
- 80+ mechanics catalogued across all subsystems
- Each with description, config flags, source files, documentation status
- 50 undocumented mechanics explicitly listed
- Cross-reference index for feature planning
- Updated docs/index.md to link the catalog

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix scratchpad get_section user_id and filesystem diff newline bugs ...

- get_section: use _uid() instead of None so multi-user lookups match
  the user_id-scoped writes done by the scratchpad tool execute()
- filesystem _diff: remove erroneous [l + \"\\n\"...] wrappers around
  splitlines() output; difflib.unified_diff already handles line lists

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Add inherit_system_prompt and is_subagent_only mechanisms ...

- inherit_system_prompt: subagent parameter to prepend parent's system
  prompt as a base layer before subagent specialisation
- is_subagent_only: profile flag blocking switch_profile, allowing
  spawn_agent only; shown with [subagent only] tag in list_profiles
- Document both in docs/profiles.md and docs/tools.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Fix test_rejects_empty to match current _check_path behavior ...

Empty string is explicitly rejected by _check_path since the
guard clause was added. The test comment was stale.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Enhance native toolset and add persistent KV store ...

- Add PostgreSQL-backed KvStore (navi/store/) for session-scoped data.
- Migrate todo and scratchpad from in-memory dicts to KvStore.
- Filesystem: add copy, grep, diff actions; compress description.
- CodeExec: remove language param, expose working_dir in schema.
- ImageView: resize to 1024px JPEG + Content-Type guard for URLs.
- Memory list: return distinct categories instead of all facts.
- SSH: add scp action with upload/download support.
- Update CLAUDE.md (Postgres-only), docs/tools.md, add docs/store.md.
- Fix agent/planning/context_builder async signatures for todo helpers.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

cleanup: remove deprecated tools and orphaned memory tools ...

Removed (no profile used them, no cross-dependencies):
- write_tool.py, delete_tool.py, test_tool.py
- memory_save.py, memory_search.py, memory_forget.py

Updated:
- navi/core/registry.py — removed imports and registrations
- navi/tools/__init__.py — removed imports
- docs/tools.md — removed references, updated self-extension section to MCP
- navi/tools/tool_manual.py — updated example to create_mcp_server

Profile fixes:
- developer: +tool_manual, +ssh_exec
- discuss: +list_profiles
- tool_developer: +mcp_servers navi-web

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs: document scheduled recall system ...

- Add docs/recall.md with full architecture, data model, tools, loop behavior
- Update docs/api.md with recall endpoints (GET/DELETE/POST recall) and recall_update WS event
- Update docs/websocket.md with recall_update frame and session_sync case #3
- Update docs/tools.md: add ScheduleRecallTool and ManageRecallTool
- Update docs/sessions.md: add is_recall message flag
- Update docs/index.md: link recall.md in file map

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fix(recall): stabilize scheduled callback system and improve UX ...

Backend fixes:
- stop_session now stops headless recall runs via _busy_sessions dict
- _fire_recall sets user ContextVars so tools work correctly
- MaxIterationsReached treated as success, not failure
- skip_next_recall uses GREATEST(trigger_at, now) for overdue recalls
- schedule_recall rejects past trigger times
- timezone offset double-adjustment fixed for aware datetimes
- _fire_recall registers _AgentRun for reconnect/replay support
- session_sync race with stream_start fixed

Frontend improvements:
- Recall banner moved to ChatHeader with live Cancel/Skip buttons
- Recall messages styled with is_recall flag and badge
- Real-time recall updates via WebSocket (recall_update events)
- Recall filter moved to sessions-header as toggle button
- Session list shows clock icon for sessions with pending recall
- Empty state messages for empty/filtered session lists
- Fixed missing api import in ChatHeader.vue

Tests:
- Updated scheduler_loop tests for _busy_sessions dict change

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fix(webclient): add missing updatePreview and updateName in sessions store ...

updatePreview and updateName were referenced in the store's return object
but never defined, causing ReferenceError at runtime after build.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Refactor: move tool helper modules into _internal subpackage ...

Moves non-tool infrastructure out of navi/tools/ root so that only
actual tool classes live there:

  base.py           → _internal/base.py
  loader.py         → _internal/loader.py
  middleware.py     → _internal/middleware.py
  logging_middleware.py → _internal/logging_middleware.py
  _time_parser.py   → _internal/time_parser.py

All imports updated across core/, api/, mcp/, tools/, and tests/.
No proxy files remain in navi/tools/ root.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Add self-recall (scheduled callback) system ...

Core features:
- schedule_recall tool: once/recurring/immediate callbacks
- manage_recall tool: cancel/skip/list scheduled recalls
- Natural-language time parser (ISO, relative, "tomorrow at 09:00")
- PostgreSQL-backed RecallScheduler with lazy pool init
- Background recall_scheduler_loop with asyncio.Semaphore(3)
- _busy_sessions guard prevents user messages during headless runs
- Agent.run() preserves thinking field for session history visibility
- API endpoints: GET/DELETE/POST for session recall, admin list
- Frontend: recall badge, filter, cancel/skip in sidebar and chat header
- Tests: parser, scheduler CRUD, tools, API, scheduler loop (53 tests)
- Manuals: schedule_recall.md and manage_recall.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

chore: remove test MCP servers from repo ...

project_health and time_toolkit were created for development testing
and should not be part of the committed codebase.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

feat: MCP server template, manual, and example servers ...

Add canonical scaffolding for MCP server development:

- manuals/write_mcp_server.md: full guide covering structure, validation,
  smoke-testing, registration, and troubleshooting
- mcp-servers/_template/: annotated starter with annotated mcp_server.py
  and pyproject.toml for FastMCP + pydantic
- mcp-servers/project_health/: example server with 3 tools
  (get_project_summary, find_duplicate_files, get_project_dependencies)
- mcp-servers/time_toolkit/: example server with 4 tools
  (get_current_time, convert_timezone, add_time, format_datetime)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fix: wire test_mcp_tool into MCP manager startup injection ...

The startup loop in main.py assigns _mcp_manager only to tools that
have the attribute, but test_mcp_tool never declared it and mcp_status
used _manager instead of _mcp_manager — so both received None forever.

Changes:
- test_mcp_tool: add __init__(mcp_manager) with _mcp_manager, fallback
  to module-level import if startup wiring skipped
- mcp_status: rename _manager → _mcp_manager, same fallback
- registry.py: register create_mcp_server and test_mcp_tool builtins
- main.py: include test_mcp_tool in startup wiring loop
- client.py: add 5s timeout to disconnect cleanup

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

fix: filesystem empty path validation and terminal timeout defaults ...

filesystem:
- Reject empty string paths in _check_path to prevent writing to cwd
- Clear error message when 'write' action uses 'destination' instead of 'path'

terminal:
- Reduce default timeout from 300s to 20s
- Clamp user-provided timeout between 1 and 300s
- Update parameter description to mention max and common use-cases

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

feat: add create_mcp_server and test_mcp_tool builtins ...

create_mcp_server:
- Scaffolds mcp-servers/<name>/ directory with venv, pyproject.toml,
  app/__init__.py, and annotated mcp_server.py template
- Runs pip install -e . in isolated thread to avoid event-loop issues
- Validates template with python -m py_compile

test_mcp_tool:
- Execute a single MCP tool call for isolated testing
- Detailed diagnostics: not connected, empty response, timeout, crash
- Fallback to module-level _mcp_manager if startup wiring skipped

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

refactor: rewrite tool_developer profile for MCP server development ...

Complete migration from old-style user tools (tools/*.py) to MCP servers.

Profile changes:
- Replace write_tool, delete_tool, test_tool with create_mcp_server,
  test_mcp_tool, mcp_status, reload_tools
- Update system_prompt.txt with 10-step MCP workflow
- Rewrite subagent_system_prompt.txt with canonical server format,
  absolute rules, smoke-test procedures
- Remove mcp_servers mapping from config (no longer bound to
  external servers)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>