cortex-loop 0.1.0a1__py3-none-any.whl

cortex_ops_cli/main.py

@@ -0,0 +1,911 @@
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import shutil
+import sqlite3
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cortex import __version__
+from cortex.core import CortexKernel
+from cortex.executive import consolidate_event, effective_weight
+from cortex.genome import load_genome
+from cortex.store import SQLiteStore
+from cortex_ops_cli._check_report import (
+    collect_check_report,
+    pack_temporal_protocol_summary,
+)
+from cortex_ops_cli._check_report_output import (
+    build_kernel_metrics_payload,
+    print_check_report,
+    print_fleet_report,
+    write_status_artifact,
+)
+from cortex_ops_cli._runtime_profiles import (
+    CLAUDE_PINNED_HOOK_SCHEMA,
+    OPENAI_BRIDGE_COMMAND_PATTERN,
+    OPENAI_BRIDGE_SCHEMA_VERSION,
+    runtime_profile_install_spec,
+    set_runtime_adapter,
+)
+
+__all__ = [
+    "CLAUDE_PINNED_HOOK_SCHEMA",
+    "OPENAI_BRIDGE_COMMAND_PATTERN",
+    "OPENAI_BRIDGE_SCHEMA_VERSION",
+    "main",
+]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    handlers = {
+        "init": _run_init,
+        "check": _run_check,
+        "fleet": _run_fleet,
+        "graveyard": _run_graveyard,
+        "memory": _run_memory,
+        "repomap": _run_repomap,
+        "runtime": _run_runtime,
+        "init-db": _run_init_db,
+        "session-events": _run_session_events,
+        "show-genome": _run_show_genome,
+        "hook": _run_hook,
+    }
+    handler = handlers.get(args.command)
+    if handler is None:
+        parser.print_help()
+        return 0
+    return handler(args)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="cortex", description="Cortex hook kernel CLI")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+    init = subparsers.add_parser("init", help="Bootstrap a new project with cortex.toml and storage")
+    init.add_argument("--root", default=".", help="Target project root (default: current directory)")
+    init.add_argument(
+        "--force",
+        action="store_true",
+        help="Overwrite an existing cortex.toml in the target root",
+    )
+
+    check = subparsers.add_parser("check", help="Validate Cortex setup in the current project")
+    check.add_argument("--root", default=".", help="Project root to validate (default: current directory)")
+    check.add_argument("--json", action="store_true", help="Emit machine-readable JSON report")
+    check.add_argument(
+        "--kernel-metrics",
+        action="store_true",
+        help="Include non-gating stop-path kernel metrics in check output",
+    )
+    check.add_argument(
+        "--kernel-metrics-baseline",
+        help="Optional path to a prior kernel metrics baseline JSON for non-gating diff output",
+    )
+    check.add_argument(
+        "--write-kernel-metrics-baseline",
+        help="Optional path to write the current kernel metrics baseline JSON (must stay under --root)",
+    )
+    check.add_argument(
+        "--write-status",
+        action="store_true",
+        help="Write latest check report to .cortex/status.json",
+    )
+
+    fleet = subparsers.add_parser("fleet", help="Fleet-level Cortex operations")
+    fleet_subparsers = fleet.add_subparsers(dest="fleet_command")
+    fleet_status = fleet_subparsers.add_parser(
+        "status", help="Check multiple project roots and summarize Cortex readiness"
+    )
+    fleet_status.add_argument(
+        "--roots",
+        nargs="+",
+        required=True,
+        help="One or more project roots to inspect",
+    )
+    fleet_status.add_argument("--json", action="store_true", help="Emit machine-readable JSON output")
+
+    graveyard = subparsers.add_parser("graveyard", help="List graveyard entries from .cortex/cortex.db")
+    graveyard.add_argument("--root", default=".", help="Project root (default: current directory)")
+    graveyard.add_argument("--limit", type=int, default=20, help="Max entries to show (default: 20)")
+
+    memory = subparsers.add_parser("memory", help="Manage executive memory entries")
+    memory_subparsers = memory.add_subparsers(dest="memory_command")
+    memory_export = memory_subparsers.add_parser("export", help="Export executive memory to JSON")
+    memory_export.add_argument("--root", default=".", help="Project root (default: current directory)")
+    memory_export.add_argument("--output", required=True, help="Output JSON file path")
+    memory_export.add_argument("--min-strength", type=int, default=1, help="Minimum strength filter")
+
+    memory_import = memory_subparsers.add_parser("import", help="Import executive memory from JSON")
+    memory_import.add_argument("input", help="Path to export JSON")
+    memory_import.add_argument("--root", default=".", help="Project root (default: current directory)")
+
+    memory_list = memory_subparsers.add_parser("list", help="List executive memory entries")
+    memory_list.add_argument("--root", default=".", help="Project root (default: current directory)")
+    memory_list.add_argument(
+        "--include-decayed",
+        action="store_true",
+        help="Include entries below decay threshold",
+    )
+
+    memory_delete = memory_subparsers.add_parser("delete", help="Delete executive memory entry by id")
+    memory_delete.add_argument("entry_id", help="Entry id")
+    memory_delete.add_argument("--root", default=".", help="Project root (default: current directory)")
+
+    repomap = subparsers.add_parser("repomap", help="Generate or inspect a repo-map artifact")
+    repomap.add_argument("--root", default=".", help="Project root (default: current directory)")
+    repomap.add_argument("--config-path", help="Override cortex.toml path")
+    repomap_output = repomap.add_mutually_exclusive_group()
+    repomap_output.add_argument(
+        "--json", action="store_true", help="Print pure repo-map artifact JSON (repomap_artifact_v1)"
+    )
+    repomap_output.add_argument(
+        "--debug-json", action="store_true", help="Print CLI/debug JSON envelope (artifact + metadata)"
+    )
+    repomap.add_argument("--output", help="Override artifact output path")
+    repomap.add_argument("--stdout-text", action="store_true", help="Print text summary to stdout (when implemented)")
+    repomap.add_argument("--scope", action="append", default=[], help="Limit scan scope path (repeatable)")
+    repomap.add_argument("--focus-file", action="append", default=[], help="Prioritize a file path (repeatable)")
+    repomap.add_argument("--max-files", type=int, help="Override max ranked files for this run")
+    repomap.add_argument("--max-text-bytes", type=int, help="Override text render byte cap for this run")
+    repomap.add_argument(
+        "--parity-profile",
+        action="store_true",
+        help="Enforce parity profile: require tree-sitter parser deps and tree-sitter-backed parsing.",
+    )
+    repomap.add_argument(
+        "--timeout-ms",
+        type=int,
+        help="Optional timeout for this CLI run (milliseconds). Omit for no CLI timeout.",
+    )
+
+    init_db = subparsers.add_parser("init-db", help="Initialize .cortex/cortex.db")
+    init_db.add_argument("--root", default=".", help="Repository root (default: current directory)")
+
+    session_events = subparsers.add_parser("session-events", help="Read session event stream as JSON")
+    session_events.add_argument("--root", default=".", help="Repository root (default: current directory)")
+    session_events.add_argument("--session-id", required=True, help="Session id to read")
+    session_events.add_argument("--hooks", nargs="+", help="Optional hook filter list")
+    session_events.add_argument("--json", action="store_true", help="Emit JSON output (default)")
+
+    show_genome = subparsers.add_parser("show-genome", help="Load and print cortex.toml")
+    show_genome.add_argument("--root", default=".", help="Repository root (default: current directory)")
+
+    runtime = subparsers.add_parser("runtime", help="Install or inspect runtime integration profiles")
+    runtime_subparsers = runtime.add_subparsers(dest="runtime_command")
+    runtime_install = runtime_subparsers.add_parser("install", help="Install runtime wiring profile")
+    runtime_install.add_argument("--root", default=".", help="Project root (default: current directory)")
+    runtime_install.add_argument(
+        "--profile",
+        choices=["claude", "gemini", "openai"],
+        required=True,
+        help="Runtime profile name",
+    )
+    runtime_install.add_argument("--force", action="store_true", help="Overwrite existing runtime wiring files")
+
+    hook = subparsers.add_parser("hook", help="Invoke a Cortex hook entrypoint")
+    hook.add_argument("event", choices=["session-start", "pre-tool-use", "post-tool-use", "stop"])
+    hook.add_argument("--root", default=".", help="Repository root (default: current directory)")
+    hook.add_argument("--config-path", help="Override cortex.toml path")
+    hook.add_argument("--db-path", help="Override SQLite database path")
+    hook.add_argument("--adapter", help="Deprecated. Configure [runtime].adapter in cortex.toml.")
+    hook.add_argument(
+        "--payload-file",
+        help="Read hook payload JSON from a file; otherwise reads JSON from stdin (or {} if empty).",
+    )
+    return parser
+
+
+def _run_init(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    managed_files = {
+        root / "cortex.toml": _starter_config_toml(),
+        root / "tests" / "invariants" / "example_invariant_test.py": _starter_invariant_test(),
+    }
+    created: list[str] = []
+    overwritten: list[str] = []
+    skipped: list[str] = []
+    root.mkdir(parents=True, exist_ok=True)
+
+    invariants_dir = root / "tests" / "invariants"
+    if not invariants_dir.exists():
+        created.append(str(invariants_dir))
+    invariants_dir.mkdir(parents=True, exist_ok=True)
+
+    cortex_dir = root / ".cortex"
+    if not cortex_dir.exists():
+        created.append(str(cortex_dir))
+    cortex_dir.mkdir(parents=True, exist_ok=True)
+
+    for path, content in managed_files.items():
+        if path.exists():
+            if args.force:
+                overwritten.append(str(path))
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(content, encoding="utf-8")
+            else:
+                skipped.append(str(path))
+            continue
+        created.append(str(path))
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+
+    db_path = cortex_dir / "cortex.db"
+    if not db_path.exists():
+        created.append(str(db_path))
+    store = SQLiteStore(db_path)
+    store.initialize()
+
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "root": str(root),
+                "created": created,
+                "overwritten": overwritten,
+                "skipped": skipped,
+                "runtime_profile": None,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def _run_check(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    report = _collect_project_report(root)
+    kernel_metrics = build_kernel_metrics_payload(
+        include=any((args.kernel_metrics, args.kernel_metrics_baseline, args.write_kernel_metrics_baseline)),
+        root=root,
+        baseline_path=args.kernel_metrics_baseline,
+        write_baseline_path=args.write_kernel_metrics_baseline,
+        warnings=report["warnings"],
+    )
+    if kernel_metrics is not None: report["kernel_metrics"] = kernel_metrics  # noqa: E701
+    if args.write_status:
+        report["status_artifact"] = write_status_artifact(root, report)
+    if args.json:
+        print(json.dumps(report, indent=2, sort_keys=True))
+    else:
+        print_check_report(report)
+    return 1 if report["summary"]["errors"] else 0
+
+
+def _run_fleet(args: argparse.Namespace) -> int:
+    if args.fleet_command != "status":
+        print("Usage: cortex fleet status --roots <path...> [--json]", file=sys.stderr)
+        return 1
+    return _run_fleet_status(args)
+
+
+def _run_fleet_status(args: argparse.Namespace) -> int:
+    roots = [Path(p).resolve() for p in args.roots]
+    reports = [_collect_project_report(root) for root in roots]
+    payload = {
+        "ok": all(r["summary"]["errors"] == 0 for r in reports),
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "cortex_version": __version__,
+        "projects": reports,
+        "summary": {
+            "projects": len(reports),
+            "ok_projects": sum(1 for r in reports if r["summary"]["errors"] == 0),
+            "warning_projects": sum(1 for r in reports if r["summary"]["warnings"] > 0),
+            "error_projects": sum(1 for r in reports if r["summary"]["errors"] > 0),
+        },
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print_fleet_report(payload)
+    return 0 if payload["ok"] else 1
+
+
+def _run_runtime(args: argparse.Namespace) -> int:
+    if args.runtime_command != "install":
+        print("Usage: cortex runtime install --profile <name> --root <path>", file=sys.stderr)
+        return 1
+    return _run_runtime_install(args)
+
+
+def _run_runtime_install(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    profile = str(args.profile).strip().lower()
+    if profile not in {"claude", "gemini", "openai"}:
+        print(f"Unsupported runtime profile: {profile}", file=sys.stderr)
+        return 1
+
+    runtime_dir, managed_files, adapter_path = runtime_profile_install_spec(
+        root=root,
+        profile=profile,
+        python_executable=sys.executable,
+    )
+
+    created: list[str] = []
+    overwritten: list[str] = []
+    skipped: list[str] = []
+    root.mkdir(parents=True, exist_ok=True)
+    if not runtime_dir.exists():
+        created.append(str(runtime_dir))
+    runtime_dir.mkdir(parents=True, exist_ok=True)
+    for path, content in managed_files.items():
+        if path.exists():
+            if args.force:
+                overwritten.append(str(path))
+                path.write_text(content, encoding="utf-8")
+            else:
+                skipped.append(str(path))
+            continue
+        created.append(str(path))
+        path.write_text(content, encoding="utf-8")
+
+    config_path = root / "cortex.toml"
+    config_status = set_runtime_adapter(config_path, adapter_path)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "root": str(root),
+                "profile": profile,
+                "adapter": adapter_path,
+                "config_status": config_status,
+                "created": created,
+                "overwritten": overwritten,
+                "skipped": skipped,
+            },
+            indent=2,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def _collect_project_report(root: Path) -> dict[str, Any]:
+    return collect_check_report(
+        root,
+        repomap_dependency_status=_repomap_dependency_status,
+        repomap_parser_dependency_status=_repomap_parser_dependency_status,
+        which=shutil.which,
+        find_spec=importlib.util.find_spec,
+        run_exec=subprocess.run,
+    )
+
+
+def _run_graveyard(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    db_path = root / ".cortex" / "cortex.db"
+    if not db_path.exists():
+        print(f"Cortex graveyard: missing database at {db_path}", file=sys.stderr)
+        return 1
+
+    store = SQLiteStore(db_path)
+    entries = store.list_graveyard(limit=max(1, args.limit))
+    print(f"Cortex Graveyard ({root})")
+    if not entries:
+        print("No graveyard entries found.")
+        return 0
+
+    for entry in entries:
+        print(f"[{entry['id']}] {entry['created_at']}")
+        print(f"Summary: {entry['summary']}")
+        print(f"Reason: {entry['reason']}")
+        files = ", ".join(entry["files"]) if entry["files"] else "(none)"
+        print(f"Files: {files}")
+        print()
+    return 0
+
+
+def _run_repomap(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    config_path = Path(args.config_path).resolve() if args.config_path else root / "cortex.toml"
+    genome = load_genome(config_path)
+    if genome.parse_error:
+        print(
+            json.dumps(
+                {
+                    "ok": False,
+                    "status": "config_error",
+                    "message": f"Failed to parse Cortex config: {genome.parse_error}",
+                    "config_path": str(config_path),
+                }
+            ),
+            file=sys.stderr,
+        )
+        return 1
+
+    from cortex.repomap import run_repomap
+
+    result = run_repomap(
+        root=root,
+        repomap_config=genome.repomap,
+        scope=[str(v) for v in args.scope] or None,
+        focus_files=[str(v) for v in args.focus_file] or None,
+        output_path=args.output,
+        max_files=args.max_files,
+        max_text_bytes=args.max_text_bytes,
+        timeout_ms=args.timeout_ms,
+        parity_profile=(True if args.parity_profile else None),
+    )
+    payload = result.to_dict()
+    payload["status"] = "ok" if result.ok else "error"
+    payload["repomap"] = {
+        "enabled": genome.repomap.enabled,
+        "run_on_session_start": genome.repomap.run_on_session_start,
+        "prefer_ast_graph": genome.repomap.prefer_ast_graph,
+        "parity_profile": genome.repomap.parity_profile,
+        "non_blocking": genome.repomap.non_blocking,
+        "artifact_path": genome.repomap.artifact_path,
+        "session_start_timeout_ms": genome.repomap.session_start_timeout_ms,
+    }
+    payload["requested"] = {
+        "root": str(root),
+        "config_path": str(config_path),
+        "output": args.output or genome.repomap.artifact_path,
+        "stdout_text": bool(args.stdout_text),
+        "json": bool(args.json),
+        "scope": [str(v) for v in args.scope],
+        "focus_files": [str(v) for v in args.focus_file],
+        "max_files": args.max_files if args.max_files is not None else genome.repomap.max_ranked_files,
+        "max_text_bytes": (
+            args.max_text_bytes if args.max_text_bytes is not None else genome.repomap.max_text_bytes
+        ),
+        "timeout_ms": args.timeout_ms,
+        "parity_profile": bool(args.parity_profile or genome.repomap.parity_profile),
+    }
+
+    if args.json:
+        print(json.dumps(result.artifact.to_dict(), indent=2, sort_keys=True))
+    elif args.debug_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+    else:
+        print(f"Cortex Repo-Map: {root}")
+        print(f"Config: {config_path}")
+        if args.parity_profile or genome.repomap.parity_profile:
+            print("Profile: parity")
+        if result.ok:
+            method = str(result.artifact.provenance.get("method", "heuristic_fallback"))
+            if method == "ast_pagerank":
+                print("Repo-map artifact generated (ast_pagerank mode).")
+            else:
+                print("Repo-map artifact generated (heuristic fallback mode).")
+            if result.artifact_path:
+                print(f"Artifact: {result.artifact_path}")
+            stats = result.artifact.stats
+            print(
+                "Stats: "
+                f"files_parsed={stats.get('files_parsed', 0)} "
+                f"symbols_found={stats.get('symbols_found', 0)} "
+                f"graph_edges={stats.get('graph_edges', 0)} "
+                f"byte_count={stats.get('byte_count', 0)}"
+            )
+            if result.artifact.ranking:
+                top_paths = ", ".join(entry.path for entry in result.artifact.ranking[:5])
+                print(f"Top files: {top_paths}")
+            else:
+                print("Top files: (none)")
+            if args.stdout_text and result.artifact.text:
+                print()
+                print(result.artifact.text, end="" if result.artifact.text.endswith("\n") else "\n")
+        else:
+            error = result.artifact.error or {}
+            print(f"Repo-map generation failed: {error.get('code', 'unknown_error')}")
+            print(error.get("message", "Unknown repo-map error"))
+    return 0 if result.ok else 1
+
+
+def _run_init_db(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    db_path = root / ".cortex" / "cortex.db"
+    store = SQLiteStore(db_path)
+    store.initialize()
+    print(json.dumps({"ok": True, "db_path": str(db_path)}))
+    return 0
+
+
+def _run_memory(args: argparse.Namespace) -> int:
+    command = str(getattr(args, "memory_command", "") or "").strip().lower()
+    handlers = {
+        "export": _run_memory_export,
+        "import": _run_memory_import,
+        "list": _run_memory_list,
+        "delete": _run_memory_delete,
+    }
+    handler = handlers.get(command)
+    if handler is None:
+        print("Usage: cortex memory <export|import|list|delete> ...", file=sys.stderr)
+        return 2
+    return handler(args)
+
+
+def _run_memory_export(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    output_path = Path(args.output).expanduser()
+    if not output_path.is_absolute():
+        output_path = (root / output_path).resolve()
+    genome = load_genome(root / "cortex.toml")
+    store = SQLiteStore(root / ".cortex" / "cortex.db")
+    store.initialize()
+
+    entries = store.get_executive_memory()
+    min_strength = max(1, int(args.min_strength))
+    current = store.get_session_count()
+    exported: list[dict[str, Any]] = []
+    for entry in entries:
+        strength = int(entry.get("strength", 1))
+        if strength < min_strength:
+            continue
+        sessions_since = max(0, current - int(entry.get("last_accessed_at_session", 0)))
+        exported.append(
+            {
+                "id": str(entry.get("id") or ""),
+                "type": str(entry.get("type") or ""),
+                "trigger": str(entry.get("trigger_pattern") or ""),
+                "error": str(entry.get("error_pattern") or ""),
+                "resolution": str(entry.get("resolution") or ""),
+                "strength": strength,
+                "effective_weight": effective_weight(
+                    entry,
+                    current_session_count=current,
+                    halflife_sessions=genome.executive.halflife_sessions,
+                ),
+                "created_at_session": int(entry.get("created_at_session", 0)),
+                "last_accessed_at_session": int(entry.get("last_accessed_at_session", 0)),
+                "sessions_since_relevant": sessions_since,
+            }
+        )
+    exported.sort(key=lambda item: float(item["effective_weight"]), reverse=True)
+
+    payload = {
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "project_root": str(root),
+        "total_sessions": current,
+        "halflife_sessions": genome.executive.halflife_sessions,
+        "entries": exported,
+    }
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    print(json.dumps({"ok": True, "path": str(output_path), "entries": len(exported)}))
+    return 0
+
+
+def _run_memory_import(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    input_path = Path(args.input).expanduser()
+    if not input_path.is_absolute():
+        input_path = (root / input_path).resolve()
+    if not input_path.exists():
+        print(f"Memory import file not found: {input_path}", file=sys.stderr)
+        return 1
+    try:
+        payload = json.loads(input_path.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        print(f"Invalid memory import JSON: {exc}", file=sys.stderr)
+        return 1
+    if not isinstance(payload, dict) or not isinstance(payload.get("entries"), list):
+        print("Invalid memory import payload: expected object with entries list.", file=sys.stderr)
+        return 1
+
+    store = SQLiteStore(root / ".cortex" / "cortex.db")
+    store.initialize()
+    import_session = store.get_session_count()
+    imported = 0
+    source_session_id = f"import-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}"
+    for raw in payload["entries"]:
+        if not isinstance(raw, dict):
+            continue
+        event_type = str(raw.get("type") or "technical").strip() or "technical"
+        trigger = str(raw.get("trigger") or raw.get("trigger_pattern") or "").strip()
+        error = str(raw.get("error") or raw.get("error_pattern") or "").strip()
+        resolution = str(raw.get("resolution") or "").strip()
+        strength = max(1, int(raw.get("strength") or 1))
+        if not trigger or not error or not resolution:
+            continue
+        for _ in range(strength):
+            created = consolidate_event(
+                store,
+                event_type=event_type,
+                trigger_pattern=trigger,
+                error_pattern=error,
+                resolution=resolution,
+                session_id=source_session_id,
+            )
+        store.update_executive_entry(str(created["id"]), last_accessed_at_session=import_session)
+        imported += 1
+    print(json.dumps({"ok": True, "imported_entries": imported, "source": str(input_path)}))
+    return 0
+
+
+def _run_memory_list(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    genome = load_genome(root / "cortex.toml")
+    store = SQLiteStore(root / ".cortex" / "cortex.db")
+    store.initialize()
+    current = store.get_session_count()
+    include_decayed = bool(args.include_decayed)
+    rows: list[dict[str, Any]] = []
+    for entry in store.get_executive_memory():
+        weight = effective_weight(
+            entry,
+            current_session_count=current,
+            halflife_sessions=genome.executive.halflife_sessions,
+        )
+        sessions_since = max(0, current - int(entry.get("last_accessed_at_session", 0)))
+        if weight < genome.executive.decay_threshold:
+            injection_state = "decayed"
+        elif weight >= genome.executive.inject_threshold:
+            injection_state = "active"
+        elif sessions_since <= genome.executive.min_hold_sessions:
+            injection_state = "active_recent_hold"
+        else:
+            injection_state = "fading_not_injected"
+        if not include_decayed and weight < genome.executive.decay_threshold:
+            continue
+        rows.append(
+            {
+                "id": str(entry.get("id") or ""),
+                "type": str(entry.get("type") or ""),
+                "strength": int(entry.get("strength", 1)),
+                "effective_weight": weight,
+                "sessions_since_relevant": sessions_since,
+                "injection_state": injection_state,
+                "trigger": str(entry.get("trigger_pattern") or ""),
+                "error": str(entry.get("error_pattern") or ""),
+                "resolution": str(entry.get("resolution") or ""),
+            }
+        )
+    rows.sort(key=lambda item: float(item["effective_weight"]), reverse=True)
+    print(json.dumps({"ok": True, "total_sessions": current, "entries": rows}, indent=2))
+    return 0
+
+
+def _run_memory_delete(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    entry_id = str(args.entry_id or "").strip()
+    if not entry_id:
+        print("entry_id is required", file=sys.stderr)
+        return 2
+    store = SQLiteStore(root / ".cortex" / "cortex.db")
+    store.initialize()
+    store.delete_executive_entries([entry_id])
+    print(json.dumps({"ok": True, "deleted": entry_id}))
+    return 0
+
+
+def _run_session_events(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    db_path = root / ".cortex" / "cortex.db"
+    if not db_path.exists():
+        print(json.dumps({"ok": False, "error": f"Missing database file: {db_path}"}), file=sys.stderr)
+        return 1
+    try:
+        events = _query_session_events(
+            db_path=db_path,
+            session_id=str(args.session_id),
+            hooks=[str(item) for item in (args.hooks or [])],
+        )
+    except sqlite3.Error as exc:
+        print(json.dumps({"ok": False, "error": f"Failed to read session events: {exc}"}), file=sys.stderr)
+        return 1
+    payload = {"ok": True, "session_id": str(args.session_id), "events": events}
+    print(json.dumps(payload, indent=2 if args.json else None, sort_keys=True))
+    return 0
+
+
+def _run_show_genome(args: argparse.Namespace) -> int:
+    root = Path(args.root).resolve()
+    genome = load_genome(root / "cortex.toml")
+    payload = genome.to_dict()
+    payload["pack_temporal_protocol"] = pack_temporal_protocol_summary(
+        root=root,
+        pack_paths=list(genome.packs.paths),
+    )
+    print(json.dumps(payload, indent=2, sort_keys=True))
+    return 0
+
+
+def _run_hook(args: argparse.Namespace) -> int:
+    if args.adapter:
+        print(
+            "--adapter is no longer supported. Configure [runtime].adapter in cortex.toml.",
+            file=sys.stderr,
+        )
+        return 1
+    payload = _read_payload(args.payload_file)
+    kernel = CortexKernel(
+        root=args.root,
+        config_path=args.config_path,
+        db_path=args.db_path,
+    )
+    result = kernel.dispatch(args.event, payload)
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0
+
+
+def _starter_config_toml() -> str:
+    return """# Cortex project configuration (starter)
+
+[project]
+name = "your-project"
+type = "generic"
+root = "."
+trust_profile = "untrusted"
+
+[invariants]
+suite_paths = ["tests/invariants"]
+pytest_bin = "pytest"
+run_on_stop = true
+execution_mode = "container"
+container_engine = "docker"
+container_image = "python:3.11-slim"
+container_workdir = "/workspace"
+
+[invariants.graduation]
+enabled = true
+target_dir = "tests/invariants/graduated"
+
+[challenges]
+active_categories = [
+  "null_inputs",
+  "boundary_values",
+  "error_handling",
+  "graveyard_regression",
+]
+custom_paths = []
+require_coverage = true
+
+[graveyard]
+enabled = true
+max_matches = 5
+similarity_threshold = 0.35
+min_keyword_overlap = 1
+context_max_matches = 2
+context_summary_chars = 140
+context_reason_chars = 200
+context_max_tokens = 300
+
+[foundation]
+enabled = true
+watch_paths = ["src"]
+ignored_dirs = ["node_modules", "dist", "build", ".git", "__pycache__"]
+churn_window_commits = 200
+git_timeout_ms = 1500
+
+[foundation.stability_thresholds]
+warn_churn_count = 8
+high_churn_count = 15
+
+[repomap]
+enabled = false
+run_on_session_start = false
+prefer_ast_graph = true
+parity_profile = false
+extended_language_profile = false
+watch_paths = ["src"]
+ignored_dirs = ["node_modules", "dist", "build", ".git", ".cortex", "__pycache__"]
+max_ranked_files = 20
+max_text_bytes = 8192
+artifact_path = ".cortex/artifacts/repomap/latest.json"
+non_blocking = true
+session_start_timeout_ms = 2500
+
+[runtime]
+adapter = ""
+
+[executive]
+enabled = true
+inject_identity_preamble = true
+part_a_mode = "once_per_project"
+halflife_sessions = 30
+decay_threshold = 0.3
+inject_threshold = 0.45
+max_entries = 20
+max_tokens = 1200
+min_hold_sessions = 3
+
+[hooks]
+mode = "advisory"
+fail_on_missing_challenge_coverage = false
+recommend_revert_on_invariant_failure = true
+require_requirement_audit = false
+fail_on_requirement_audit_gap = false
+require_evidence_for_passed_requirement = true
+require_structured_stop_payload = true
+allow_message_stop_fallback = false
+
+[metrics]
+enabled = true
+track = [
+  "human_oversight_minutes",
+  "interrupt_count",
+  "escaped_defects",
+  "completion_minutes",
+  "foundation_quality",
+]
+"""
+
+
+def _starter_invariant_test() -> str:
+    return """from __future__ import annotations
+
+from pathlib import Path
+
+
+# Invariant tests are external constraints the current agent did not author.
+# They encode project rules that should keep passing across sessions and tasks.
+def test_cortex_config_exists() -> None:
+    project_root = Path(__file__).resolve().parents[2]
+    assert (project_root / "cortex.toml").exists()
+
+
+# Example of a real invariant (commented out):
+# def test_no_banned_imports() -> None:
+#     project_root = Path(__file__).resolve().parents[2]
+#     banned = "legacy_unsafe_module"
+#     for path in project_root.rglob("*.py"):
+#         if ".venv" in path.parts or ".cortex" in path.parts:
+#             continue
+#         assert banned not in path.read_text(encoding="utf-8")
+"""
+def _query_session_events(*, db_path: Path, session_id: str, hooks: list[str]) -> list[dict[str, Any]]:
+    session_token = str(session_id).strip()
+    if not session_token:
+        return []
+    hook_tokens = [str(item).strip() for item in hooks if str(item).strip()]
+    where = "WHERE session_id = ?"
+    params: list[Any] = [session_token]
+    if hook_tokens:
+        where += f" AND hook IN ({','.join(['?'] * len(hook_tokens))})"
+        params.extend(hook_tokens)
+    with sqlite3.connect(db_path) as conn:
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            f"""
+            SELECT id, hook, tool_name, status, payload_json, created_at
+            FROM events
+            {where}
+            ORDER BY created_at ASC, id ASC
+            """,
+            tuple(params),
+        ).fetchall()
+    return [
+        {
+            "id": int(row["id"]),
+            "hook": str(row["hook"]),
+            "created_at": str(row["created_at"]),
+            "tool_name": row["tool_name"],
+            "status": row["status"],
+            "payload": json.loads(row["payload_json"] or "{}"),
+        }
+        for row in rows
+    ]
+
+
+def _repomap_dependency_status() -> list[str]:
+    from cortex.repomap import repomap_missing_dependencies
+    return repomap_missing_dependencies()
+
+
+def _repomap_parser_dependency_status() -> list[str]:
+    from cortex.repomap import repomap_missing_parser_dependencies
+    return repomap_missing_parser_dependencies()
+
+
+def _read_payload(payload_file: str | None) -> dict[str, Any]:
+    raw = Path(payload_file).read_text(encoding="utf-8") if payload_file else sys.stdin.read()
+    raw = raw.strip()
+    if not raw: return {}  # noqa: E701
+    decoded = json.loads(raw)
+    if not isinstance(decoded, dict):
+        raise ValueError("Hook payload must decode to a JSON object")
+    return decoded
+
+
+if __name__ == "__main__": raise SystemExit(main())  # noqa: E701