marvisx-cli 0.1.0__tar.gz

marvisx_cli-0.1.0/LICENSE

@@ -0,0 +1,98 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Emilio Martucci
+Licensed Work:        MarvisX
+                      The Licensed Work is (c) 2026 Emilio Martucci.
+Additional Use Grant: You may make production use of the Licensed Work only
+                      for personal, non-commercial purposes (for example,
+                      self-hosting it for your own individual use). Any other
+                      production use is not granted here and requires a separate
+                      commercial license from the Licensor. Uses that are NOT
+                      granted include, without limitation: any commercial use;
+                      any use by, within, or for the benefit of a business,
+                      company, or other organization; offering the Licensed
+                      Work (or a modified or adapted version of it) to third
+                      parties as a hosted or managed service; and using a
+                      modified or adapted version of the Licensed Work as, or
+                      as part of, a product or service that competes with the
+                      Licensor.
+Change Date:          2030-01-01
+Change License:       Apache License, Version 2.0
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants You the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under the
+terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently
+in effect as described in this License, you must purchase a commercial license
+from the Licensor, its affiliated entities, or authorized resellers, or you must
+refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license your
+works, and to refer to it using the trademark"Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version, or
+   a license that is compatible with GPL Version 2.0 or a later version, where
+   "compatible" means that software provided under the Change License can be
+   included in a program with software provided under GPL Version 2.0 or a later
+   version. Licensor may specify additional Change Licenses without limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

marvisx_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+# Source-distribution manifest.
+#
+# `python -m build --sdist --wheel` builds the wheel FROM the sdist, so any
+# runtime data-file missing from the sdist is also missing from that wheel —
+# even though a DIRECT wheel build (uv build / pip wheel) would include it via
+# [tool.setuptools.package-data]. uv infers sdist contents from the git file
+# list; plain setuptools needs them spelled out here. Keep these globs in sync
+# with [tool.setuptools.package-data] in pyproject.toml (learning 9e527cfa).
+recursive-include migrations *.sql
+recursive-include core/scripts/install_hooks *.sh *.json *.py
+recursive-include core/api/templates *.md *.j2
+recursive-include projects/_template *

marvisx_cli-0.1.0/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: marvisx-cli
+Version: 0.1.0
+Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
+Author: MarvisX maintainers
+License: BSL-1.1
+Project-URL: Homepage, https://justaskmarvis.com
+Project-URL: Documentation, https://justaskmarvis.com/docs/getting-started
+Project-URL: Source, https://github.com/marvisx/marvisx-oss
+Project-URL: Issues, https://github.com/marvisx/marvisx-oss/issues
+Project-URL: Changelog, https://github.com/marvisx/marvisx-oss/blob/main/CHANGELOG.md
+Keywords: marvisx,cli,bootstrap,wizard,oss,agent,company-brain
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Utilities
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: click>=8
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: PyYAML>=6
+Requires-Dist: cryptography>=42
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Requires-Dist: uvloop>=0.21.0
+Requires-Dist: aiosqlite>=0.20.0
+Requires-Dist: PyJWT>=2.10.0
+Requires-Dist: bcrypt>=4.2.0
+Requires-Dist: email-validator>=2.2.0
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: python-magic>=0.4.27
+Requires-Dist: python-multipart>=0.0.18
+Requires-Dist: filelock>=3.16.0
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: itsdangerous>=2.1.0
+Requires-Dist: pywebpush>=2.0.0
+Requires-Dist: py-vapid>=1.9.0
+Requires-Dist: anthropic<1.0.0,>=0.96.0
+Requires-Dist: openai<2.0.0,>=1.50.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: tenacity<10,>=9.1
+Requires-Dist: tree-sitter<0.26,>=0.23.0
+Requires-Dist: tree-sitter-python<0.25,>=0.23.0
+Requires-Dist: tree-sitter-typescript~=0.23.2
+Requires-Dist: pygit2>=1.15.0
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: watchfiles>=1.1.0
+Requires-Dist: Pillow>=10.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: mcp>=1.12
+Requires-Dist: onnxruntime>=1.18
+Requires-Dist: tokenizers>=0.20
+Requires-Dist: huggingface-hub>=0.24
+Requires-Dist: numpy>=1.26
+Requires-Dist: psutil>=5.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Dynamic: license-file
+
+# marvis init
+
+Interactive bootstrap wizard for MarvisX OSS. Five prompts (license,
+storage, BYOK, first project, recap) reusing the shared `core/wizard/`
+state machine so the CLI and the Console `/welcome` route produce
+byte-identical settings when given the same answers.
+
+## Install
+
+```bash
+pip install marvisx-cli
+marvis init
+```
+
+Pre-install (clone and run) works too:
+
+```bash
+python -m core.cli.marvis_init init
+```
+
+## Quick start (interactive)
+
+```bash
+marvis init
+```
+
+You will be asked:
+
+1. **License** — accept BSL 1.1 (`y`/`n`).
+2. **Storage** — projects root path, database backend (`sqlite` or
+   `postgres`), and either the SQLite file path or the Postgres DSN.
+3. **LLM provider (BYOK)** — `anthropic`, `openai`, `mac_gateway`,
+   `bedrock`, or `skip`. API key prompt is hidden input. Mac gateway
+   asks for the base URL.
+4. **First project** — name, slug, and type (`code`, `work`, `system`).
+5. **Recap** — review choices, confirm.
+
+On confirmation the wizard writes:
+
+- `~/.marvis/settings.yaml` — workspace + storage + llm choice (no
+  secrets), chmod 600.
+- `~/.marvis/master.key` + `~/.marvis/byok.vault` — Fernet-encrypted
+  API key store (only if a provider was chosen).
+- `<projects_root>/<slug>/project.yaml` — first project seed.
+
+## Non-interactive / CI
+
+```bash
+marvis init \
+  --accept-bsl \
+  --no-interactive \
+  --projects-root /var/lib/marvis/projects \
+  --db-backend sqlite \
+  --db-path /var/lib/marvis/console.db \
+  --llm-provider anthropic \
+  --llm-api-key "$ANTHROPIC_API_KEY" \
+  --project-name "Local Workspace" \
+  --project-slug local-workspace \
+  --project-type code
+```
+
+YAML preset (preferred for repeatable provisioning):
+
+```bash
+marvis init --no-interactive --config init.yaml
+```
+
+`init.yaml`:
+
+```yaml
+welcome:
+  bsl_accepted: true
+storage:
+  projects_root: /var/lib/marvis/projects
+  db_backend: sqlite
+  db_path: /var/lib/marvis/console.db
+llm_provider:
+  provider: anthropic
+  api_key: sk-ant-...
+first_project:
+  name: Local Workspace
+  slug: local-workspace
+  type: code
+```
+
+## Dry run
+
+```bash
+marvis init --dry-run --accept-bsl --no-interactive ...
+```
+
+Prints the planned filesystem writes and the rendered `settings.yaml`
+without touching the disk. Exit 0.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success (or dry-run) |
+| 1 | Generic runtime error |
+| 2 | User abort at recap confirmation |
+| 3 | Validation failure (field-level errors printed) |
+
+## Tests
+
+```bash
+python -m pytest tests/test_cli_marvis_init.py
+```
+
+Ten cases cover dry-run, non-interactive flags, YAML preset, BYOK vault
+write, invalid slug rejection, Postgres backend, interactive prompts via
+`CliRunner(input=...)`, BSL gate, and `show-state` JSON dump.
+
+## Relation to `core/scripts/marvis-init.sh`
+
+`marvis-init.sh` (bash) is a deploy bootstrap: copies
+`deploy/_template/`, renders `.env` with secrets, runs
+`setup-server.sh`, and brings up Docker Compose. It targets server
+administrators provisioning a host.
+
+`marvis init` (this Python CLI) is an onboarding wizard: writes
+`settings.yaml` + BYOK vault + first project seed in the user's home.
+It targets OSS users running MarvisX locally.
+
+The two flows are complementary and will converge in a later phase. Until
+then both ship side-by-side.

marvisx_cli-0.1.0/README.md

@@ -0,0 +1,95 @@
+# MarvisX
+
+Self-hosted, EU-resident **company brain** for agent-native operations: a cross-project Knowledge Graph, audit-immutable provenance, reflective Brain pipeline, and an agent-native Model Context Protocol surface.
+
+Released as a defensive-publication architectural pattern. See the Zenodo preprint: [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860).
+
+## What MarvisX gives you
+
+- **Cross-project Knowledge Graph** with 17 deterministic edge types covering code, work-chain artifacts, knowledge-chain documents, cross-project references, and bridge edges. Canonical IDs follow `{prefix}:{kind}:{slug}`.
+- **Foreign-key-immutable audit log** with provenance pinned at the SQLite level. Designed to satisfy the logging surface required by EU Regulation 2024/1689 (AI Act) Article 12.
+- **Brain reflection pipeline** in five layers — substrate, digest and journal, drift checker, memory operations, findings — closed by a Direction-Aware loop.
+- **Constitution-enforced safety rules** enforced by deterministic hook gates and an MCP mirror for providers without native hooks.
+- **Agent-native MCP surface** exposing 91 tools, callable identically from Claude Code, Codex, Gemini, OpenCode, and a web console.
+
+## Search and embedding quality
+
+MarvisX-OSS Phase 1 defaults to **IBM Granite-Embedding-97m-Multilingual-R2** self-hosted via ONNX, blended with SQLite BM25 keyword search through Reciprocal Rank Fusion. Backend is selectable through `EMBEDDING_MODE`.
+
+This is a deliberate tradeoff: EU compliance, self-hosting, and zero external embedding cost come at the cost of retrieval quality that is below commercial managed embedding providers. See [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) for the benchmark numbers, affected workflows, mitigations available today, and the Phase 2 fine-tune roadmap.
+
+## License posture
+
+- Code: **Business Source License 1.1**, with an automatic change date converting to **Apache License 2.0** four years after release.
+- Documentation and architectural patterns: **CC-BY 4.0**.
+
+The combination is intended to make the architecture freely citable while preserving the ability to ship a self-hosted reference deployment.
+
+## Architecture map
+
+The system groups capabilities into eight functional domains (`M1 Capture`, `M2 Index`, `M3 Retrieve`, `M4 Reflect`, `M5 Act`, `M6 Agent-native I/O`, `M7 Compliance`, `M8 Productization`). The Knowledge Graph stitches them together with canonical IDs and an audit chain.
+
+For the full architectural description, see the Zenodo preprint linked above.
+
+## Repository layout
+
+```
+core/
+├── api/        # FastAPI service: KG, ingest, brain, MCP transport
+├── console/    # Next.js web console
+├── kb/         # Project-local knowledge base templates
+├── mcp-pir/    # MCP server (stdio) exposing the 91-tool surface
+└── scripts/    # Deployment, migration, and operational scripts
+
+deploy/
+└── _template/  # Reference deployment template
+                # (Docker Compose + environment scaffolding)
+```
+
+## Quick start
+
+The reference deployment uses Docker Compose. Clone the repository, copy `deploy/_template/.env.example` to `.env`, populate the required secrets, and bring the stack up:
+
+```bash
+cp deploy/_template/.env.example deploy/_template/.env
+cd deploy/_template/
+docker compose up -d
+```
+
+The Console becomes available on the configured `CONSOLE_PORT` and the API on the configured `API_PORT`. Detailed first-run instructions are inside the deployment template.
+
+## Embedding migration from a managed provider
+
+If you currently run MarvisX with a managed embedding provider such as Voyage AI, [`docs/MIGRATION-FROM-VOYAGE.md`](docs/MIGRATION-FROM-VOYAGE.md) covers the step-by-step path to the self-hosted Granite backend, including the re-index, KG threshold recalibration, and rollback procedure.
+
+## MCP surface
+
+MarvisX ships an MCP server exposing 91 tools across 11 categories: project and session context, tasks, handoffs, semantic search, learnings, costs, pull requests, knowledge graph queries, ingest triage, brain reflection layer, and audit-and-monitoring controls.
+
+The same surface is used by autonomous agents and by humans through the web console. The intent is parity: any action a user can take through the console, an agent can also take through MCP, and the reverse.
+
+## Single-user local runtime (`MARVIS_OSS_LOCAL`)
+
+The MCP server runs in-process: it calls the same use_cases the HTTP API calls, against the local SQLite database, with no uvicorn and no Node bridge. In this single-user mode there is no HTTP API in front of the database, so the HTTP audit chokepoint (which in the managed deployment forces every mutation through the API) does not exist.
+
+Audit is still recorded: the extracted use_cases write the audit log themselves (`core/api/use_cases/{tasks,pull_requests,audit}.py`), so a mutation issued through MCP still produces an audit row at the use_case level. What is lost is only the additional HTTP-surface chokepoint.
+
+Setting `MARVIS_OSS_LOCAL=1` (truthy: `1`/`true`/`yes`/`on`) makes the `block-db-direct-write` safety rule **advisory** — direct writes to a PiR SQLite database are allowed with a warning instead of being blocked. When the variable is unset or falsey the rule is unchanged: direct DB writes are blocked fail-closed, exactly as in the managed deployment. This trade-off is intentional for single-user self-hosting and never weakens the default.
+
+**No-fork guarantee.** The HTTP API and the MCP server are not two implementations: both are thin adapters over the same `core/api/use_cases`, differing only in how they fill the per-call `CallerContext`. The proof is the API test suite staying green after the extraction — the same behaviour, exercised through the HTTP surface, over the identical use_cases the MCP server calls.
+
+## Documentation
+
+- [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) — search quality expectations, affected workflows, and mitigations
+- [`docs/MIGRATION-FROM-VOYAGE.md`](docs/MIGRATION-FROM-VOYAGE.md) — migration from managed embeddings to Granite
+- [`docs/solutions/architecture-patterns/`](docs/solutions/architecture-patterns/) — architectural decision records
+
+## Contributing
+
+This is a defensive-publication release. The repository accepts issues for bug reports and clarifications. The architecture itself is documented in the Zenodo preprint; the codebase is intended as the reference implementation of that architecture.
+
+## References
+
+- Preprint (Zenodo): [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860)
+- License (code): Business Source License 1.1, change date converts to Apache License 2.0 four years after release
+- License (documentation): CC-BY 4.0

marvisx_cli-0.1.0/core/api/agents/session_health.py

@@ -0,0 +1,59 @@
+# v1.0.0 - 2026-03-02 - DevX session health checker (v1: dimension C only)
+"""Session health check — DevX Layer Sprint 3.
+
+v1 implementa solo Dimensione C (Continuita): sessione idle senza input richiesto.
+Le dimensioni A (task hygiene), B (context%), D (output quality) sono deferred Sprint 4.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from core.api.models import SessionInfo
+
+logger = logging.getLogger(__name__)
+
+IDLE_THRESHOLD_MINUTES = 15
+SESSION_MANAGER_COOLDOWN_MINUTES = 30  # Rate limit: max 1 msg per sessione per 30 min
+
+
+@dataclass
+class HealthCheckResult:
+    session_name: str
+    action: str              # "send_message" | "escalate" | "ok"
+    message: str | None
+    escalation_reason: str | None
+
+
+async def check_session_health(
+    session: SessionInfo,
+    last_action_at: datetime | None,
+) -> HealthCheckResult:
+    """v1: Solo dimensione C — sessione idle senza input richiesto.
+
+    Le dimensioni A, B, D sono deferred alla prossima sprint
+    dopo validazione di C in produzione.
+    """
+    # Rate limit: non mandare piu di 1 messaggio per cooldown period
+    if last_action_at is not None:
+        elapsed = (datetime.now(timezone.utc) - last_action_at).total_seconds() / 60
+        if elapsed < SESSION_MANAGER_COOLDOWN_MINUTES:
+            return HealthCheckResult(session.name, "ok", None, None)
+
+    # C — Continuita: sessione idle senza input richiesto
+    if session.activity_state == "idle" and not _session_waiting_for_input(session):
+        return HealthCheckResult(
+            session.name,
+            "send_message",
+            "La sessione sembra ferma. Continua con il task corrente. "
+            "Ricorda di aggiornare i task e fare handoff a fine sessione.",
+            None,
+        )
+
+    return HealthCheckResult(session.name, "ok", None, None)
+
+
+def _session_waiting_for_input(session: SessionInfo) -> bool:
+    """True se la sessione CC sta aspettando input (needs_input activity state)."""
+    return session.activity_state == "needs_input"

marvisx_cli-0.1.0/core/api/agents/session_manager.py

@@ -0,0 +1,206 @@
+# v1.0.0 - 2026-03-02 - DevX Session Manager Agent
+"""Session Manager Agent — DevX Layer Sprint 3.
+
+Runs every 10 minutes via host cron or manual trigger.
+Monitors sessions with agent_managed=True, runs health checks, acts on results.
+
+Usage:
+    cd /data/pir && python -m api.agents.session_manager
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiosqlite
+
+from core.api.config import settings
+from core.api.agents.session_health import check_session_health
+from core.api.models import SessionInfo
+from core.api.services import tmux
+
+logger = logging.getLogger(__name__)
+
+ERRORS_DIR = Path("/data/pir/logs/errors")
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+async def list_agent_managed_sessions() -> list[SessionInfo]:
+    """Return all sessions with agent_managed=True via the sessions API.
+
+    Uses the internal API endpoint to get live activity_state (computed from tmux,
+    not stored in DB). Falls back to empty list on error.
+    """
+    import urllib.request
+    from core.api.config import settings as cfg
+    token = cfg.tasks_api_token if hasattr(cfg, "tasks_api_token") else os.environ.get("TASKS_API_TOKEN", "")
+    api_base = os.environ.get("PIR_INTERNAL_BASE", "http://localhost:8100")
+    try:
+        req = urllib.request.Request(
+            f"{api_base}/api/v1/sessions?agent_managed=true",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "X-Agent-Name": "marvisx",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read())
+        return [SessionInfo(**s) for s in data]
+    except Exception as exc:
+        logger.error("Failed to list agent_managed sessions: %s", exc)
+        return []
+
+
+async def get_last_agent_action(db: aiosqlite.Connection, session_name: str) -> datetime | None:
+    """Return the last time an automated action was taken on this session."""
+    try:
+        cursor = await db.execute(
+            "SELECT MAX(created_at) FROM agent_actions WHERE session_name = ?",
+            (session_name,),
+        )
+        row = await cursor.fetchone()
+        if row and row[0]:
+            # Parse ISO string from SQLite — may be naive (no tz offset)
+            ts_str: str = row[0]
+            ts_str = ts_str.replace("Z", "+00:00")
+            dt = datetime.fromisoformat(ts_str)
+            # SQLite stores UTC without offset — assume UTC if naive
+            if dt.tzinfo is None:
+                dt = dt.replace(tzinfo=timezone.utc)
+            return dt
+    except Exception as exc:
+        logger.warning("Failed to get last agent action for %s: %s", session_name, exc)
+    return None
+
+
+async def log_agent_action(
+    db: aiosqlite.Connection,
+    session_name: str,
+    action: str,
+    detail: str | None,
+) -> None:
+    """Log an automated action taken on a session."""
+    try:
+        await db.execute(
+            """
+            INSERT INTO agent_actions (agent_name, session_name, action, detail, created_at)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            ("session-manager", session_name, action, detail, datetime.now(timezone.utc).isoformat()),
+        )
+        await db.commit()
+    except Exception as exc:
+        logger.error("Failed to log agent action: %s", exc)
+
+
+async def send_session_message(session_name: str, text: str) -> bool:
+    """Send a message to a tmux session."""
+    try:
+        return await tmux.send_keys(session_name, text)
+    except Exception as exc:
+        logger.error("Failed to send message to session %s: %s", session_name, exc)
+        return False
+
+
+async def send_telegram_alert(text: str) -> None:
+    """Send a Telegram alert (best-effort)."""
+    import urllib.request
+    if not settings.telegram_bot_token or not settings.telegram_owner_chat_id:
+        logger.info("Telegram not configured, skipping alert")
+        return
+    try:
+        url = f"https://api.telegram.org/bot{settings.telegram_bot_token}/sendMessage"
+        data = json.dumps({
+            "chat_id": settings.telegram_owner_chat_id,
+            "text": text,
+            "parse_mode": "HTML",
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            resp.read()
+    except Exception as exc:
+        logger.warning("Telegram alert failed: %s", exc)
+
+
+async def log_error_to_knowledge(session_name: str, error_text: str) -> None:
+    """Log an error to the knowledge errors store for downstream analysis."""
+    ERRORS_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    error_file = ERRORS_DIR / f"{ts}-session-manager-{session_name}.txt"
+    try:
+        error_file.write_text(
+            f"session: {session_name}\nerror: {error_text}\nts: {ts}\n"
+        )
+    except Exception as exc:
+        logger.error("Failed to write error file: %s", exc)
+
+
+# ── core loop ────────────────────────────────────────────────────────────────
+
+async def _process_session(
+    db: aiosqlite.Connection,
+    session: SessionInfo,
+) -> None:
+    """Process a single session — isolated to not block others."""
+    last_action_at = await get_last_agent_action(db, session.name)
+    result = await check_session_health(session, last_action_at)
+
+    if result.action == "send_message" and result.message:
+        success = await send_session_message(session.name, result.message)
+        if success:
+            await log_agent_action(db, session.name, "health_check:C", result.message)
+            logger.info("Sent health check message to session %s", session.name)
+        else:
+            logger.warning("Failed to send message to session %s", session.name)
+
+    elif result.action == "escalate" and result.escalation_reason:
+        await send_telegram_alert(
+            f"<b>DevX Escalation</b> — <code>{session.name}</code>\n\n{result.escalation_reason}"
+        )
+        await log_agent_action(db, session.name, "escalate", result.escalation_reason)
+        logger.warning("Escalated session %s: %s", session.name, result.escalation_reason)
+
+
+async def run_session_manager() -> None:
+    """Main loop: monitor agent_managed sessions, run health checks."""
+    logger.info("Session Manager starting...")
+    from core.api.db import write_db
+    async with write_db() as db:
+        sessions = await list_agent_managed_sessions()
+        if not sessions:
+            logger.info("No agent_managed sessions to monitor")
+            return
+
+        logger.info("Checking %d agent_managed session(s)...", len(sessions))
+
+        results = await asyncio.gather(
+            *[_process_session(db, s) for s in sessions],
+            return_exceptions=True,
+        )
+
+        for session, result in zip(sessions, results):
+            if isinstance(result, Exception):
+                logger.error(
+                    "Health check failed for session %s: %s", session.name, result
+                )
+                await log_error_to_knowledge(session.name, str(result))
+
+    logger.info("Session Manager complete")
+
+
+# ── CLI entrypoint ────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s — %(message)s",
+    )
+    asyncio.run(run_session_manager())