Initial public upload from Projekte/Sidecar-Workspace (part 17)

codex-sidecarV1/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+.pytest_cache/
+.coverage

codex-sidecarV1/.pytest_cache/.gitignore

@@ -0,0 +1,2 @@
+# Created by pytest automatically.
+*

codex-sidecarV1/.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

codex-sidecarV1/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

codex-sidecarV1/.pytest_cache/v/cache/lastfailed

@@ -0,0 +1,5 @@
+{
+  "tests/test_governor.py::GovernorTests": true,
+  "tests/test_state.py::StateTests": true,
+  "tests/test_watcher.py::WatcherTests": true
+}

codex-sidecarV1/.pytest_cache/v/cache/nodeids

@@ -0,0 +1,15 @@
+[
+  "tests/test_cli.py::CliTests::test_exec_dry_run_allows_safe_prompt",
+  "tests/test_cli.py::CliTests::test_exec_dry_run_refuses_risky_prompt",
+  "tests/test_cli.py::CliTests::test_replay_json_returns_subagent_summary",
+  "tests/test_cli.py::CliTests::test_status_json_reports_capabilities_truth",
+  "tests/test_governor.py::GovernorTests::test_build_gate_without_repo_falls_back_to_plan",
+  "tests/test_governor.py::GovernorTests::test_build_ready_requires_repo_and_check",
+  "tests/test_governor.py::GovernorTests::test_contract_has_stable_labels",
+  "tests/test_governor.py::GovernorTests::test_empty_prompt_fail_open",
+  "tests/test_governor.py::GovernorTests::test_wrapper_refuses_risky_prompt",
+  "tests/test_state.py::StateTests::test_build_without_check_produces_plan_contract_and_advisory",
+  "tests/test_state.py::StateTests::test_replay_builds_subagent_aware_snapshot",
+  "tests/test_state.py::StateTests::test_risky_shell_is_advisory_not_fake_block",
+  "tests/test_watcher.py::WatcherTests::test_normalize_realistic_subagent_session"
+]

codex-sidecarV1/README.md

@@ -0,0 +1,53 @@
+# codex-sidecarV1
+
+Standalone Codex sidecar V1 workspace.
+
+This repo now implements the practical V1 shape for the real Codex runtime:
+
+- replay-first watcher over `~/.codex/sessions/*.jsonl`
+- explicit mode contracts for prompts
+- advisory findings from observed sessions
+- no hidden context injection and no fake tool blocking
+- optional wrapper boundary through `codex-sidecar exec`
+
+## Usage
+
+Run it directly without installation:
+
+```bash
+PYTHONPATH=src python3 -m codex_sidecar contract "build only parser module and run tests"
+PYTHONPATH=src python3 -m codex_sidecar status --json
+PYTHONPATH=src python3 -m codex_sidecar replay ~/.codex/sessions/.../rollout-....jsonl --json
+PYTHONPATH=src python3 -m codex_sidecar exec --prompt "review current diff" --dry-run -- codex
+```
+
+The public Codex V1 capability contract is:
+
+- `supports_context_injection = false`
+- `supports_tool_blocking = false`
+- `supports_session_replay = true`
+- `supports_post_tool_observation = true`
+- advisory outputs only unless launched through the wrapper boundary
+
+Split baseline:
+
+- Source repo: `../Sidecar-V8`
+- Baseline commit: `1950d86`
+- Split date: `2026-04-24`
+- Intent: leave `Sidecar-V8` in place and continue new work here
+
+`Sidecar-V8` worktree was intentionally left dirty at split time. Status snapshot:
+
+- `M adapters/claude_code/adapter.py`
+- `M adapters/codex/adapter.py`
+- `M core/sidecar_core/__init__.py`
+- `M core/sidecar_core/adapter.py`
+- `M core/sidecar_core/core.py`
+- `M core/tests/test_adapter.py`
+- `M core/tests/test_sidecar_core.py`
+- `?? core/sidecar_core/capabilities.py`
+- `?? core/sidecar_core/evaluation_bridge.py`
+- `?? core/sidecar_core/proof_registry.py`
+- `?? core/sidecar_core/runtime.py`
+- `?? core/tests/test_proof_registry.py`
+- `?? core/tests/test_runtime.py`

codex-sidecarV1/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codex-sidecar"
+version = "0.1.0"
+description = "Standalone Codex sidecar V1 for replay, contracts, and advisory governance."
+requires-python = ">=3.11"
+readme = "README.md"
+authors = [{ name = "Codex" }]
+dependencies = []
+
+[project.scripts]
+codex-sidecar = "codex_sidecar.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

codex-sidecarV1/src/codex_sidecar/__init__.py

@@ -0,0 +1,21 @@
+"""Standalone Codex sidecar V1."""
+
+from .capabilities import CapabilityProfile, CODEX_V1_CAPABILITIES
+from .governor import ModeContract, WrapperDecision, advise_on_snapshot, contract_for_prompt
+from .state import SessionSnapshot, build_snapshot
+from .watcher import NormalizedEvent, find_latest_session, normalize_session_file, resolve_session_path
+
+__all__ = [
+    "CODEX_V1_CAPABILITIES",
+    "CapabilityProfile",
+    "ModeContract",
+    "NormalizedEvent",
+    "SessionSnapshot",
+    "WrapperDecision",
+    "advise_on_snapshot",
+    "build_snapshot",
+    "contract_for_prompt",
+    "find_latest_session",
+    "normalize_session_file",
+    "resolve_session_path",
+]

codex-sidecarV1/src/codex_sidecar/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for `python -m codex_sidecar`."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

codex-sidecarV1/src/codex_sidecar/capabilities.py

@@ -0,0 +1,43 @@
+"""Capability profile for the current Codex runtime."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilityProfile:
+    """Public capability contract for Codex sidecar V1."""
+
+    adapter_name: str
+    event_source: str
+    supports_context_injection: bool
+    supports_tool_blocking: bool
+    supports_session_replay: bool
+    supports_post_tool_observation: bool
+    advisory_only: bool
+    wrapper_boundary_available: bool
+
+    def to_dict(self) -> dict[str, bool | str]:
+        return {
+            "adapter_name": self.adapter_name,
+            "event_source": self.event_source,
+            "supports_context_injection": self.supports_context_injection,
+            "supports_tool_blocking": self.supports_tool_blocking,
+            "supports_session_replay": self.supports_session_replay,
+            "supports_post_tool_observation": self.supports_post_tool_observation,
+            "advisory_only": self.advisory_only,
+            "wrapper_boundary_available": self.wrapper_boundary_available,
+        }
+
+
+CODEX_V1_CAPABILITIES = CapabilityProfile(
+    adapter_name="codex",
+    event_source="pull",
+    supports_context_injection=False,
+    supports_tool_blocking=False,
+    supports_session_replay=True,
+    supports_post_tool_observation=True,
+    advisory_only=True,
+    wrapper_boundary_available=True,
+)

codex-sidecarV1/src/codex_sidecar/cli.py

@@ -0,0 +1,190 @@
+"""CLI surfaces for Codex sidecar V1."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+from .capabilities import CODEX_V1_CAPABILITIES
+from .governor import render_contract, wrapper_decision
+from .state import build_snapshot
+from .watcher import find_latest_session, resolve_session_path
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="codex-sidecar")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    contract = subparsers.add_parser("contract", help="Render a bounded visible contract.")
+    contract.add_argument("prompt")
+    contract.add_argument("--cwd", default=".")
+    contract.add_argument("--json", action="store_true")
+    contract.set_defaults(func=_cmd_contract)
+
+    status = subparsers.add_parser("status", help="Show current or latest session status.")
+    status.add_argument("--session", default="")
+    status.add_argument("--root", default="")
+    status.add_argument("--json", action="store_true")
+    status.set_defaults(func=_cmd_status)
+
+    replay = subparsers.add_parser("replay", help="Replay a Codex rollout file.")
+    replay.add_argument("session")
+    replay.add_argument("--root", default="")
+    replay.add_argument("--json", action="store_true")
+    replay.set_defaults(func=_cmd_replay)
+
+    exec_parser = subparsers.add_parser("exec", help="Wrapper-style launch boundary.")
+    exec_parser.add_argument("--prompt", required=True)
+    exec_parser.add_argument("--cwd", default=".")
+    exec_parser.add_argument("--json", action="store_true")
+    exec_parser.add_argument("--dry-run", action="store_true")
+    exec_parser.add_argument("--force", action="store_true")
+    exec_parser.add_argument("cmd", nargs=argparse.REMAINDER)
+    exec_parser.set_defaults(func=_cmd_exec)
+
+    return parser
+
+
+def _cmd_contract(args: argparse.Namespace) -> int:
+    decision = wrapper_decision(args.prompt, cwd=args.cwd)
+    payload = {
+        "contract": decision.contract.to_dict(),
+        "findings": [finding.to_dict() for finding in decision.findings],
+        "capabilities": CODEX_V1_CAPABILITIES.to_dict(),
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+    print(render_contract(decision.contract))
+    if decision.findings:
+        print("")
+        print("Findings:")
+        for finding in decision.findings:
+            print(f"- [{finding.severity}] {finding.message} -> {finding.recommendation}")
+    print("")
+    print("Capabilities:")
+    for key, value in CODEX_V1_CAPABILITIES.to_dict().items():
+        print(f"- {key}: {value}")
+    return 0
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    root = args.root or None
+    if args.session:
+        session_path = resolve_session_path(args.session, root=root)
+    else:
+        latest = find_latest_session(root=root)
+        if latest is None:
+            return _emit({"status": "empty", "reason": "no session files found"}, args.json)
+        session_path = latest
+    snapshot = build_snapshot(session_path)
+    payload = {"status": "ok", "session": snapshot.to_dict()}
+    return _emit(payload, args.json)
+
+
+def _cmd_replay(args: argparse.Namespace) -> int:
+    session_path = resolve_session_path(args.session, root=args.root or None)
+    snapshot = build_snapshot(session_path)
+    payload = {
+        "status": "ok",
+        "mode": "replay",
+        "session": snapshot.to_dict(),
+    }
+    return _emit(payload, args.json)
+
+
+def _cmd_exec(args: argparse.Namespace) -> int:
+    decision = wrapper_decision(args.prompt, cwd=args.cwd)
+    cmd = list(args.cmd)
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+
+    payload = {
+        "decision": decision.to_dict(),
+        "command": cmd,
+        "cwd": str(Path(args.cwd).resolve()),
+    }
+    if args.json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        if not decision.allowed and not args.force:
+            return 2
+        if args.dry_run or not cmd:
+            return 0
+    else:
+        print(render_contract(decision.contract), file=sys.stderr)
+        if decision.findings:
+            print("", file=sys.stderr)
+            print("Findings:", file=sys.stderr)
+            for finding in decision.findings:
+                print(
+                    f"- [{finding.severity}] {finding.message} -> {finding.recommendation}",
+                    file=sys.stderr,
+                )
+        print("", file=sys.stderr)
+
+    if not decision.allowed and not args.force:
+        if not args.json:
+            print(
+                f"Wrapper refused launch: {decision.reason}",
+                file=sys.stderr,
+            )
+        return 2
+
+    if args.dry_run or not cmd:
+        return 0
+
+    completed = subprocess.run(cmd, cwd=args.cwd, check=False)
+    return int(completed.returncode)
+
+
+def _emit(payload: dict[str, object], as_json: bool) -> int:
+    if as_json:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return 0
+
+    session = payload.get("session")
+    if not isinstance(session, dict):
+        print(payload.get("reason", "no session data"))
+        return 0
+
+    contract = session.get("contract")
+    print(f"Session: {session['session_id']}")
+    print(f"Path: {session['session_path']}")
+    print(f"CWD: {session['cwd']}")
+    print(f"Workflow Phase: {session['workflow_phase']}")
+    print(f"Prompt: {session['prompt'] or '(none captured)'}")
+    if isinstance(contract, dict):
+        print(f"Mode: {contract['mode']} ({contract['reason']})")
+    print(f"Verification Seen: {session['verification_seen']}")
+    print(f"Errors: {session['errors']}")
+
+    subagent = session.get("subagent", {})
+    if isinstance(subagent, dict) and subagent:
+        print(
+            "Subagent: "
+            f"{subagent.get('agent_nickname') or '?'} / {subagent.get('agent_role') or '?'} "
+            f"(depth={subagent.get('depth')}, parent={subagent.get('parent_thread_id')})"
+        )
+
+    findings = session.get("findings", [])
+    if findings:
+        print("Findings:")
+        for finding in findings:
+            print(f"- [{finding['severity']}] {finding['message']}")
+
+    capabilities = session.get("capabilities", {})
+    if isinstance(capabilities, dict):
+        print("Capabilities:")
+        for key, value in capabilities.items():
+            print(f"- {key}: {value}")
+    return 0

codex-sidecarV1/src/codex_sidecar/governor.py

@@ -0,0 +1,428 @@
+"""Bounded advisory governor for Codex sidecar V1."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+
+from .models import Finding, ModeContract, SessionSnapshot, WrapperDecision
+
+MODES = ("plan", "build", "review", "debug", "research", "eval", "meta")
+
+PLAN_TERMS = (
+    "plan",
+    "scope",
+    "decide",
+    "decide whether",
+    "design",
+    "concept",
+    "structure",
+    "think through",
+)
+BUILD_TERMS = (
+    "implement",
+    "build",
+    "fix ",
+    "create",
+    "update",
+    "edit",
+    "change",
+    "commit",
+    "push",
+    "deploy",
+)
+RISK_TERMS = (
+    "push directly",
+    "push to production",
+    "production",
+    "skip tests",
+    "delete the old tests",
+    "rm -rf",
+    "force push",
+)
+REVIEW_TERMS = (
+    "review",
+    "findings",
+    "audit",
+    "check the diff",
+    "code review",
+)
+DEBUG_TERMS = (
+    "debug",
+    "bug",
+    "traceback",
+    "error",
+    "failing",
+    "root cause",
+    "reproduce",
+)
+RESEARCH_TERMS = (
+    "research",
+    "look up",
+    "source",
+    "sources",
+    "docs",
+    "compare options",
+    "what is",
+    "how does",
+)
+EVAL_TERMS = (
+    "eval",
+    "benchmark",
+    "metric",
+    "measure",
+    "compare prompts",
+    "goldset",
+    "real sessions",
+)
+META_TERMS = (
+    "meta",
+    "harness",
+    "sidecar",
+    "governor",
+    "workflow",
+    ".codex",
+    "claude code",
+    "codex runtime",
+)
+SCOPE_TERMS = ("only", "scope", "module", "repo", "file", "folder", "path", "directory")
+CHECK_TERMS = ("test", "tests", "pytest", "smoke", "check", "verify", "done")
+
+PROMPT_RISK_MAP = {
+    "risk_direct_production": ("production", "Prompt pushes directly toward production risk."),
+    "risk_skip_tests": ("skip tests", "Prompt asks to bypass verification."),
+    "risk_force_push": ("force push", "Prompt asks for a force-push style workflow."),
+    "risk_destructive_delete": ("rm -rf", "Prompt contains destructive deletion intent."),
+}
+
+SHELL_RISK_PATTERNS = {
+    "dangerous_rm": r"\brm\s+-rf\b",
+    "git_reset_hard": r"\bgit\s+reset\s+--hard\b",
+    "force_push": r"\bgit\s+push\b.*--force",
+    "production_deploy": r"\bdeploy\b.*\bprod",
+    "sudo_write": r"\bsudo\b",
+}
+
+TEST_COMMAND_PATTERNS = (
+    "pytest",
+    "unittest",
+    "npm test",
+    "pnpm test",
+    "cargo test",
+    "go test",
+    "uv run pytest",
+)
+
+
+def contract_for_prompt(prompt: str, cwd: str | Path | None = None) -> ModeContract | None:
+    """Return a compact mode contract, or None for fail-open empty input."""
+    prompt = " ".join((prompt or "").split())
+    if not prompt:
+        return None
+    mode, reason = classify_prompt(prompt, cwd=cwd, with_reason=True)
+    target = _target_from_prompt(prompt)
+    return _contract(mode, target, reason)
+
+
+def classify_prompt(
+    prompt: str,
+    cwd: str | Path | None = None,
+    *,
+    with_reason: bool = False,
+) -> str | tuple[str, str]:
+    """Classify a prompt into the bounded sidecar modes."""
+    prompt = " ".join((prompt or "").split())
+    lower = prompt.lower()
+    cwd_path = Path(cwd or ".").resolve()
+
+    explicit = _explicit_mode(lower)
+    if explicit:
+        if explicit == "build":
+            reason = _build_blocker(prompt, cwd_path)
+            if reason:
+                return _result("plan", reason, with_reason)
+        return _result(explicit, "explicit_mode", with_reason)
+
+    if _has_any(lower, REVIEW_TERMS):
+        return _result("review", "review_terms", with_reason)
+    if _has_any(lower, DEBUG_TERMS):
+        return _result("debug", "debug_terms", with_reason)
+    if _has_any(lower, EVAL_TERMS):
+        return _result("eval", "eval_terms", with_reason)
+    if _has_any(lower, RESEARCH_TERMS):
+        return _result("research", "research_terms", with_reason)
+    if _has_any(lower, META_TERMS):
+        return _result("meta", "meta_terms", with_reason)
+    if _has_any(lower, RISK_TERMS):
+        return _result("plan", "risk_requires_plan", with_reason)
+    if _has_any(lower, BUILD_TERMS):
+        reason = _build_blocker(prompt, cwd_path)
+        if reason:
+            return _result("plan", reason, with_reason)
+        return _result("build", "build_ready", with_reason)
+    if _has_any(lower, PLAN_TERMS) or _looks_fuzzy(lower):
+        return _result("plan", "planning_or_fuzzy", with_reason)
+    return _result("plan", "default_plan", with_reason)
+
+
+def render_contract(contract: ModeContract) -> str:
+    """Render a stable, explicit user-visible contract."""
+    return "\n".join(
+        [
+            f"Mode: {contract.mode}",
+            f"Reason: {contract.reason}",
+            f"Goal: {contract.goal}",
+            f"Non-Goal: {contract.non_goal}",
+            f"Stop-Condition: {contract.stop_condition}",
+            f"Allowed Behavior: {contract.allowed_behavior}",
+            f"Failure Signal: {contract.failure_signal}",
+        ]
+    )
+
+
+def detect_prompt_risks(prompt: str) -> list[Finding]:
+    """Detect explicitly risky prompt intent."""
+    lower = prompt.lower()
+    findings: list[Finding] = []
+    for code, (needle, message) in PROMPT_RISK_MAP.items():
+        if needle in lower:
+            findings.append(
+                Finding(
+                    code=code,
+                    severity="high",
+                    message=message,
+                    recommendation="Switch to plan mode and require an explicit verification path.",
+                )
+            )
+    return findings
+
+
+def detect_shell_risks(command: str) -> list[Finding]:
+    """Detect clearly risky shell commands."""
+    findings: list[Finding] = []
+    for code, pattern in SHELL_RISK_PATTERNS.items():
+        if re.search(pattern, command):
+            findings.append(
+                Finding(
+                    code=code,
+                    severity="high",
+                    message=f"Observed risky shell command: {command}",
+                    recommendation="Stop and switch to plan unless the wrapper owner explicitly forces execution.",
+                )
+            )
+    return findings
+
+
+def advise_on_snapshot(snapshot: SessionSnapshot) -> tuple[Finding, ...]:
+    """Produce advisory findings from an observed session snapshot."""
+    findings: list[Finding] = []
+    findings.extend(detect_prompt_risks(snapshot.prompt))
+
+    if snapshot.contract and snapshot.contract.mode == "build" and not snapshot.verification_seen:
+        findings.append(
+            Finding(
+                code="verification_missing",
+                severity="medium",
+                message="Build-like activity was observed without a verification signal.",
+                recommendation="Switch to plan or add a concrete test/smoke-check before treating the task as complete.",
+            )
+        )
+
+    if snapshot.subagent:
+        findings.append(
+            Finding(
+                code="subagent_lineage_present",
+                severity="info",
+                message="Session originated from a spawned subagent thread.",
+                recommendation="Keep summaries explicit about parent thread, depth, and delegated role.",
+            )
+        )
+
+    for call in snapshot.tool_calls:
+        if call.shell_command:
+            findings.extend(detect_shell_risks(call.shell_command))
+        if call.exit_code not in (None, 0):
+            findings.append(
+                Finding(
+                    code="tool_error",
+                    severity="medium",
+                    message=f"Tool call {call.tool_name} exited with code {call.exit_code}.",
+                    recommendation="Summarize the failure and decide whether the next step is debug or plan.",
+                )
+            )
+    return tuple(_dedupe_findings(findings))
+
+
+def wrapper_decision(prompt: str, cwd: str | Path | None = None) -> WrapperDecision:
+    """Return the explicit wrapper-mode launch decision."""
+    contract = contract_for_prompt(prompt, cwd=cwd)
+    if contract is None:
+        fallback = _contract("plan", "The current task", "empty_prompt")
+        return WrapperDecision(
+            allowed=True,
+            reason="empty_prompt_fail_open",
+            contract=fallback,
+            findings=(),
+        )
+
+    findings = tuple(detect_prompt_risks(prompt))
+    blocking_codes = {
+        "risk_direct_production",
+        "risk_skip_tests",
+        "risk_force_push",
+        "risk_destructive_delete",
+    }
+    if any(finding.code in blocking_codes for finding in findings):
+        return WrapperDecision(
+            allowed=False,
+            reason="wrapper_refused_risky_prompt",
+            contract=contract,
+            findings=findings,
+        )
+    return WrapperDecision(
+        allowed=True,
+        reason="wrapper_allowed_visible_contract",
+        contract=contract,
+        findings=findings,
+    )
+
+
+def _contract(mode: str, target: str, reason: str) -> ModeContract:
+    if mode == "plan":
+        return ModeContract(
+            mode="plan",
+            reason=reason,
+            goal=f"Turn {target} into a buildable plan or a single clear open question.",
+            non_goal="No code edits, no speculative runtime, no orchestration sprawl.",
+            stop_condition="Stops with a buildable plan, or with one explicit blocking question.",
+            allowed_behavior="Read/search/replay only. Use advisory findings, not hidden injection or fake blocking.",
+            failure_signal="The task is still fuzzy, risky, or not verification-ready.",
+        )
+    if mode == "build":
+        return ModeContract(
+            mode="build",
+            reason=reason,
+            goal=f"Implement {target} as one stable, testable change.",
+            non_goal="No scope creep, no unrelated refactors, no new controller layer.",
+            stop_condition="Stops with a diff plus a concrete test, smoke-check, or explicit failure.",
+            allowed_behavior="Edit only within clear scope and keep verification visible.",
+            failure_signal="Repo, scope, or verification signal becomes unclear and must fall back to plan.",
+        )
+    if mode == "review":
+        return ModeContract(
+            mode="review",
+            reason=reason,
+            goal=f"Assess {target} for bugs, regressions, and missing checks.",
+            non_goal="No fixes, no refactors, no second build task.",
+            stop_condition='Stops with findings or an explicit "no findings" result plus remaining test gaps.',
+            allowed_behavior="Read/search/diff/tests for evidence only.",
+            failure_signal="The review scope mutates into implementation or the evidence is weak.",
+        )
+    if mode == "debug":
+        return ModeContract(
+            mode="debug",
+            reason=reason,
+            goal=f"Reproduce and narrow {target}, then fix minimally or define the next experiment.",
+            non_goal="No feature work, no guesswork, no cosmetic refactor.",
+            stop_condition="Stops with root cause, minimal fix, or the next reproducible experiment.",
+            allowed_behavior="Prefer reproduction, logs, and minimal edits after a concrete hypothesis.",
+            failure_signal="No reproduction, no hypothesis, or the fix grows beyond the bug.",
+        )
+    if mode == "research":
+        return ModeContract(
+            mode="research",
+            reason=reason,
+            goal=f"Clarify {target} with sources, options, and a recommendation.",
+            non_goal="No implementation and no unsourced claims.",
+            stop_condition="Stops with sources, options, and a decision recommendation.",
+            allowed_behavior="Use replay, docs, and repo reads. Keep tradeoffs explicit.",
+            failure_signal="No reliable sources or the question fragments into multiple decisions.",
+        )
+    if mode == "eval":
+        return ModeContract(
+            mode="eval",
+            reason=reason,
+            goal=f"Measure or compare {target} into a usable result.",
+            non_goal="No product feature work during measurement.",
+            stop_condition="Stops with a metric, comparison, or a clearly testable hypothesis.",
+            allowed_behavior="Use sessions, logs, tables, and reproducible checks only.",
+            failure_signal="The metric is not measurable or the result would be anecdotal.",
+        )
+    if mode == "meta":
+        return ModeContract(
+            mode="meta",
+            reason=reason,
+            goal=f"Simplify or clarify {target} without inventing a new control plane.",
+            non_goal="No new agent system, no hidden injector, no daemon-first architecture.",
+            stop_condition="Stops with lower complexity or a clear reason to stop.",
+            allowed_behavior="Read existing rules and keep changes bounded to explicit interfaces.",
+            failure_signal="Meta work starts creating more machinery than it removes.",
+        )
+    raise ValueError(f"unknown mode: {mode}")
+
+
+def _result(mode: str, reason: str, with_reason: bool) -> str | tuple[str, str]:
+    return (mode, reason) if with_reason else mode
+
+
+def _explicit_mode(lower: str) -> str | None:
+    match = re.match(r"^/?(plan|build|review|debug|research|eval|meta)(?:mode)?\b", lower)
+    return match.group(1) if match else None
+
+
+def _build_blocker(prompt: str, cwd: Path) -> str | None:
+    lower = prompt.lower()
+    if not _repo_is_clear(cwd):
+        return "build_gated_no_repo"
+    if len(prompt.strip()) < 16:
+        return "build_gated_unclear_goal"
+    if not (_has_any(lower, SCOPE_TERMS) or len(prompt.split()) >= 6):
+        return "build_gated_unclear_scope"
+    if not _has_any(lower, CHECK_TERMS):
+        return "build_gated_missing_check"
+    return None
+
+
+def _repo_is_clear(cwd: Path) -> bool:
+    for path in (cwd, *cwd.parents):
+        if (path / ".git").exists():
+            return True
+    return False
+
+
+def _target_from_prompt(prompt: str) -> str:
+    target = prompt.strip()
+    target = re.sub(
+        r"^/?(?:plan|build|review|debug|research|eval|meta)(?:mode)?[:\s-]*",
+        "",
+        target,
+        flags=re.I,
+    )
+    if not target:
+        return "the current task"
+    if len(target) > 140:
+        return target[:137].rstrip() + "..."
+    return target
+
+
+def _has_any(text: str, terms: tuple[str, ...]) -> bool:
+    return any(term in text for term in terms)
+
+
+def _looks_fuzzy(lower: str) -> bool:
+    return "?" in lower or any(
+        term in lower
+        for term in ("how can", "what do you think", "idea", "unclear", "everything at once")
+    )
+
+
+def _dedupe_findings(findings: list[Finding]) -> list[Finding]:
+    seen: set[tuple[str, str]] = set()
+    unique: list[Finding] = []
+    for finding in findings:
+        key = (finding.code, finding.message)
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(finding)
+    return unique

codex-sidecarV1/src/codex_sidecar/models.py

@@ -0,0 +1,126 @@
+"""Shared data models for Codex sidecar V1."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedEvent:
+    """Canonical event shape extracted from Codex JSONL traces."""
+
+    kind: str
+    session_id: str
+    timestamp: float
+    raw_type: str
+    call_id: str = ""
+    tool_name: str = ""
+    cwd: str = ""
+    message: str = ""
+    arguments: dict[str, Any] = field(default_factory=dict)
+    output: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ModeContract:
+    """Compact explicit contract for a prompt or replayed task."""
+
+    mode: str
+    reason: str
+    goal: str
+    non_goal: str
+    stop_condition: str
+    allowed_behavior: str
+    failure_signal: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """Advisory output produced by the governor."""
+
+    code: str
+    severity: str
+    message: str
+    recommendation: str
+
+    def to_dict(self) -> dict[str, str]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCall:
+    """Normalized tool-call record reconstructed from replay data."""
+
+    call_id: str
+    tool_name: str
+    arguments: dict[str, Any]
+    started_at: float
+    completed_at: float = 0.0
+    output: str = ""
+    cwd: str = ""
+    shell_command: str = ""
+    exit_code: int | None = None
+    status: str = "started"
+    touched_files: tuple[str, ...] = ()
+    risk_codes: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True, slots=True)
+class WrapperDecision:
+    """Wrapper-mode decision for pre-launch boundaries."""
+
+    allowed: bool
+    reason: str
+    contract: ModeContract
+    findings: tuple[Finding, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "allowed": self.allowed,
+            "reason": self.reason,
+            "contract": self.contract.to_dict(),
+            "findings": [finding.to_dict() for finding in self.findings],
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class SessionSnapshot:
+    """Current truth reconstructed from a Codex rollout file."""
+
+    session_id: str
+    session_path: str
+    cwd: str
+    started_at: float
+    last_timestamp: float
+    workflow_phase: str
+    workflow_transitions: tuple[dict[str, Any], ...]
+    prompt: str
+    contract: ModeContract | None
+    tool_calls: tuple[ToolCall, ...]
+    touched_files: tuple[str, ...]
+    subagent: dict[str, Any]
+    agent_messages: tuple[str, ...]
+    risky_intent_codes: tuple[str, ...]
+    findings: tuple[Finding, ...]
+    errors: int
+    verification_seen: bool
+    rate_limits: dict[str, Any]
+    capabilities: dict[str, Any]
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        payload["contract"] = self.contract.to_dict() if self.contract else None
+        payload["tool_calls"] = [call.to_dict() for call in self.tool_calls]
+        payload["findings"] = [finding.to_dict() for finding in self.findings]
+        return payload

codex-sidecarV1/src/codex_sidecar/state.py

@@ -0,0 +1,259 @@
+"""State reconstruction for Codex sidecar V1."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import shlex
+from typing import Any
+
+from .capabilities import CODEX_V1_CAPABILITIES
+from .governor import TEST_COMMAND_PATTERNS, advise_on_snapshot, contract_for_prompt, detect_prompt_risks, detect_shell_risks
+from .models import SessionSnapshot, ToolCall
+from .watcher import normalize_session_file
+
+PATH_KEYS = ("path", "file", "file_path", "workdir", "cwd", "target", "target_file")
+
+
+def build_snapshot(path: str | Path) -> SessionSnapshot:
+    """Build a replay snapshot from a rollout file."""
+    events = normalize_session_file(path)
+    raw_path = str(Path(path).expanduser())
+    session_id = ""
+    cwd = ""
+    started_at = 0.0
+    last_timestamp = 0.0
+    workflow_phase = "bootstrapping"
+    workflow_transitions: list[dict[str, Any]] = []
+    prompt = ""
+    agent_messages: list[str] = []
+    risky_codes: set[str] = set()
+    rate_limits: dict[str, Any] = {}
+    subagent: dict[str, Any] = {}
+    turn_context_cwd = ""
+    pending_calls: dict[str, dict[str, Any]] = {}
+    finalized_calls: list[ToolCall] = []
+    touched_files: list[str] = []
+
+    def transition(phase: str, reason: str, timestamp: float) -> None:
+        nonlocal workflow_phase
+        if workflow_phase == phase:
+            return
+        workflow_phase = phase
+        workflow_transitions.append(
+            {"phase": phase, "reason": reason, "timestamp": timestamp}
+        )
+
+    for event in events:
+        if not started_at and event.timestamp:
+            started_at = event.timestamp
+        last_timestamp = max(last_timestamp, event.timestamp)
+
+        if event.kind == "session_meta":
+            session_id = event.session_id or session_id
+            cwd = event.cwd or cwd
+            source = event.data.get("source", {})
+            thread_spawn = source.get("subagent", {}).get("thread_spawn", {})
+            if thread_spawn:
+                subagent = {
+                    "parent_thread_id": thread_spawn.get("parent_thread_id", ""),
+                    "depth": thread_spawn.get("depth", 0),
+                    "agent_nickname": event.data.get("agent_nickname", ""),
+                    "agent_role": event.data.get("agent_role", ""),
+                }
+            transition("bootstrapping", "session_meta", event.timestamp)
+            continue
+
+        if event.kind == "turn_context":
+            turn_context_cwd = event.cwd or turn_context_cwd
+            continue
+
+        if event.kind == "user_prompt" and event.message and not event.message.startswith("<environment_context>"):
+            prompt = event.message
+            risky_codes.update(finding.code for finding in detect_prompt_risks(prompt))
+            transition("prompted", "user_prompt", event.timestamp)
+            continue
+
+        if event.kind == "task_started":
+            transition("prompted", "task_started", event.timestamp)
+            continue
+
+        if event.kind == "tool_call":
+            call_data = {
+                "call_id": event.call_id,
+                "tool_name": event.tool_name,
+                "arguments": dict(event.arguments),
+                "started_at": event.timestamp,
+                "cwd": cwd or turn_context_cwd,
+            }
+            if event.tool_name == "exec_command":
+                shell_command = str(event.arguments.get("cmd", "")).strip()
+                call_data["shell_command"] = shell_command
+                risky_codes.update(finding.code for finding in detect_shell_risks(shell_command))
+                call_data["touched_files"] = tuple(_extract_paths_from_shell(shell_command))
+            else:
+                call_data["shell_command"] = ""
+                call_data["touched_files"] = tuple(_extract_paths_from_args(event.arguments))
+            pending_calls[event.call_id] = call_data
+            for candidate in call_data["touched_files"]:
+                if candidate not in touched_files:
+                    touched_files.append(candidate)
+            transition("tooling", f"tool_call:{event.tool_name}", event.timestamp)
+            continue
+
+        if event.kind == "tool_output":
+            call = pending_calls.get(event.call_id)
+            if call is not None:
+                call["output"] = event.output
+                exit_code = _extract_exit_code(event.output)
+                if exit_code is not None:
+                    call["exit_code"] = exit_code
+                    call["status"] = "completed" if exit_code == 0 else "failed"
+            continue
+
+        if event.kind == "command_end":
+            call = pending_calls.get(event.call_id)
+            if call is not None:
+                payload = event.data
+                command = payload.get("command", [])
+                call["cwd"] = event.cwd or call["cwd"]
+                call["completed_at"] = event.timestamp
+                call["status"] = str(payload.get("status", "completed"))
+                call["output"] = event.output or call.get("output", "")
+                exit_code = payload.get("exit_code")
+                call["exit_code"] = int(exit_code) if isinstance(exit_code, int) else call.get("exit_code")
+                if not call.get("shell_command") and isinstance(command, list):
+                    shell_command = " ".join(str(part) for part in command if part)
+                    call["shell_command"] = shell_command
+                continue
+
+        if event.kind == "agent_message" and event.message:
+            agent_messages.append(event.message)
+            transition("responded", "agent_message", event.timestamp)
+            continue
+
+        if event.kind == "task_complete":
+            if event.message:
+                agent_messages.append(event.message)
+            transition("responded", "task_complete", event.timestamp)
+            continue
+
+        if event.kind == "token_count":
+            rate_limits = dict(event.data.get("rate_limits", {}))
+
+    for call in pending_calls.values():
+        finalized_calls.append(
+            ToolCall(
+                call_id=str(call.get("call_id", "")),
+                tool_name=str(call.get("tool_name", "")),
+                arguments=dict(call.get("arguments", {})),
+                started_at=float(call.get("started_at", 0.0)),
+                completed_at=float(call.get("completed_at", 0.0)),
+                output=str(call.get("output", "")),
+                cwd=str(call.get("cwd", "")),
+                shell_command=str(call.get("shell_command", "")),
+                exit_code=call.get("exit_code"),
+                status=str(call.get("status", "started")),
+                touched_files=tuple(call.get("touched_files", ())),
+                risk_codes=tuple(sorted(risky_codes_for_call(call))),
+            )
+        )
+
+    active_cwd = cwd or turn_context_cwd or str(Path(raw_path).parent)
+    contract = contract_for_prompt(prompt, cwd=active_cwd) if prompt else None
+    verification_seen = any(_call_has_verification(call) for call in finalized_calls)
+    errors = sum(1 for call in finalized_calls if call.exit_code not in (None, 0))
+
+    provisional = SessionSnapshot(
+        session_id=session_id or Path(raw_path).stem,
+        session_path=raw_path,
+        cwd=active_cwd,
+        started_at=started_at,
+        last_timestamp=last_timestamp,
+        workflow_phase=workflow_phase,
+        workflow_transitions=tuple(workflow_transitions),
+        prompt=prompt,
+        contract=contract,
+        tool_calls=tuple(finalized_calls),
+        touched_files=tuple(touched_files),
+        subagent=subagent,
+        agent_messages=tuple(agent_messages),
+        risky_intent_codes=tuple(sorted(risky_codes)),
+        findings=(),
+        errors=errors,
+        verification_seen=verification_seen,
+        rate_limits=rate_limits,
+        capabilities=CODEX_V1_CAPABILITIES.to_dict(),
+    )
+    findings = advise_on_snapshot(provisional)
+    return SessionSnapshot(
+        session_id=provisional.session_id,
+        session_path=provisional.session_path,
+        cwd=provisional.cwd,
+        started_at=provisional.started_at,
+        last_timestamp=provisional.last_timestamp,
+        workflow_phase=provisional.workflow_phase,
+        workflow_transitions=provisional.workflow_transitions,
+        prompt=provisional.prompt,
+        contract=provisional.contract,
+        tool_calls=provisional.tool_calls,
+        touched_files=provisional.touched_files,
+        subagent=provisional.subagent,
+        agent_messages=provisional.agent_messages,
+        risky_intent_codes=provisional.risky_intent_codes,
+        findings=findings,
+        errors=provisional.errors,
+        verification_seen=provisional.verification_seen,
+        rate_limits=provisional.rate_limits,
+        capabilities=provisional.capabilities,
+    )
+
+
+def _call_has_verification(call: ToolCall) -> bool:
+    command = call.shell_command.lower()
+    return any(pattern in command for pattern in TEST_COMMAND_PATTERNS)
+
+
+def _extract_exit_code(output: str) -> int | None:
+    match = re.search(r"Process exited with code (\d+)", output)
+    if match:
+        return int(match.group(1))
+    return None
+
+
+def _extract_paths_from_args(arguments: dict[str, Any]) -> list[str]:
+    candidates: list[str] = []
+    for key, value in arguments.items():
+        if key not in PATH_KEYS:
+            continue
+        if isinstance(value, str) and _looks_like_path(value):
+            candidates.append(value)
+    return candidates
+
+
+def _extract_paths_from_shell(command: str) -> list[str]:
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return []
+
+    candidates: list[str] = []
+    for token in tokens:
+        if token.startswith("-"):
+            continue
+        if _looks_like_path(token):
+            candidates.append(token)
+    return candidates
+
+
+def _looks_like_path(value: str) -> bool:
+    if not value or value.startswith("<"):
+        return False
+    if "/" in value:
+        return True
+    return value.endswith((".py", ".md", ".toml", ".json", ".yaml", ".yml", ".txt", ".html", ".css", ".js", ".ts"))
+
+
+def risky_codes_for_call(call: dict[str, Any]) -> tuple[str, ...]:
+    shell_command = str(call.get("shell_command", ""))
+    return tuple(sorted(finding.code for finding in detect_shell_risks(shell_command)))

codex-sidecarV1/src/codex_sidecar/watcher.py

@@ -0,0 +1,249 @@
+"""Replay-oriented watcher over Codex JSONL sessions."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+import json
+from typing import Any, Iterator
+
+from .models import NormalizedEvent
+
+
+def session_root(default: str | Path | None = None) -> Path:
+    """Return the default Codex sessions root."""
+    if default is not None:
+        return Path(default).expanduser()
+    return Path.home() / ".codex" / "sessions"
+
+
+def find_latest_session(root: str | Path | None = None) -> Path | None:
+    """Return the newest JSONL rollout file under the sessions root."""
+    entries = sorted(session_root(root).rglob("*.jsonl"))
+    return entries[-1] if entries else None
+
+
+def resolve_session_path(session: str | Path, root: str | Path | None = None) -> Path:
+    """Resolve a user-supplied session id or path to a JSONL file."""
+    path = Path(session).expanduser()
+    if path.exists():
+        return path
+
+    root_path = session_root(root)
+    candidates = sorted(root_path.rglob(f"*{session}*.jsonl"))
+    if not candidates:
+        raise FileNotFoundError(f"could not resolve session: {session}")
+    return candidates[-1]
+
+
+def iter_raw_records(path: str | Path) -> Iterator[dict[str, Any]]:
+    """Yield raw JSON objects from a rollout JSONL file."""
+    with Path(path).expanduser().open(encoding="utf-8") as handle:
+        for line in handle:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            yield json.loads(stripped)
+
+
+def normalize_record(raw: dict[str, Any]) -> list[NormalizedEvent]:
+    """Normalize one raw Codex JSONL record into zero or more canonical events."""
+    raw_type = str(raw.get("type", ""))
+    payload = raw.get("payload", {})
+    timestamp = _coerce_timestamp(raw.get("timestamp"))
+
+    if raw_type == "session_meta":
+        session_id = str(payload.get("id", ""))
+        return [
+            NormalizedEvent(
+                kind="session_meta",
+                session_id=session_id,
+                timestamp=timestamp,
+                raw_type=raw_type,
+                cwd=str(payload.get("cwd", "")),
+                data=payload,
+            )
+        ]
+
+    if raw_type == "turn_context":
+        return [
+            NormalizedEvent(
+                kind="turn_context",
+                session_id="",
+                timestamp=timestamp,
+                raw_type=raw_type,
+                cwd=str(payload.get("cwd", "")),
+                data=payload,
+            )
+        ]
+
+    session_id = str(raw.get("session_id", ""))
+
+    if raw_type == "response_item":
+        payload_type = str(payload.get("type", ""))
+        if payload_type == "function_call":
+            return [
+                NormalizedEvent(
+                    kind="tool_call",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    call_id=str(payload.get("call_id", "")),
+                    tool_name=str(payload.get("name", "")),
+                    arguments=_decode_arguments(payload.get("arguments")),
+                    data=payload,
+                )
+            ]
+        if payload_type == "function_call_output":
+            return [
+                NormalizedEvent(
+                    kind="tool_output",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    call_id=str(payload.get("call_id", "")),
+                    output=_coerce_text(payload.get("output")),
+                    data=payload,
+                )
+            ]
+        if payload_type == "message":
+            role = str(payload.get("role", ""))
+            content_text = _message_text(payload.get("content", []))
+            kind = "user_prompt" if role == "user" and content_text else "agent_message"
+            return [
+                NormalizedEvent(
+                    kind=kind,
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    message=content_text,
+                    data=payload,
+                )
+            ]
+        return []
+
+    if raw_type == "event_msg":
+        payload_type = str(payload.get("type", ""))
+        if payload_type == "task_started":
+            return [
+                NormalizedEvent(
+                    kind="task_started",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    data=payload,
+                )
+            ]
+        if payload_type == "task_complete":
+            return [
+                NormalizedEvent(
+                    kind="task_complete",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    message=str(payload.get("last_agent_message", "")),
+                    data=payload,
+                )
+            ]
+        if payload_type == "agent_message":
+            return [
+                NormalizedEvent(
+                    kind="agent_message",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    message=str(payload.get("message", "")),
+                    data=payload,
+                )
+            ]
+        if payload_type == "user_message":
+            return [
+                NormalizedEvent(
+                    kind="user_prompt",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    message=str(payload.get("message", "")),
+                    data=payload,
+                )
+            ]
+        if payload_type == "token_count":
+            return [
+                NormalizedEvent(
+                    kind="token_count",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    data=payload,
+                )
+            ]
+        if payload_type == "exec_command_end":
+            return [
+                NormalizedEvent(
+                    kind="command_end",
+                    session_id=session_id,
+                    timestamp=timestamp,
+                    raw_type=raw_type,
+                    call_id=str(payload.get("call_id", "")),
+                    cwd=str(payload.get("cwd", "")),
+                    output=str(payload.get("aggregated_output", "")),
+                    data=payload,
+                )
+            ]
+    return []
+
+
+def normalize_session_file(path: str | Path) -> list[NormalizedEvent]:
+    """Normalize an entire rollout JSONL file."""
+    events: list[NormalizedEvent] = []
+    for raw in iter_raw_records(path):
+        events.extend(normalize_record(raw))
+    return events
+
+
+def _decode_arguments(arguments: Any) -> dict[str, Any]:
+    if isinstance(arguments, dict):
+        return arguments
+    if isinstance(arguments, str):
+        try:
+            decoded = json.loads(arguments)
+        except json.JSONDecodeError:
+            return {"raw_arguments": arguments}
+        if isinstance(decoded, dict):
+            return decoded
+        return {"value": decoded}
+    return {}
+
+
+def _coerce_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, ensure_ascii=True, sort_keys=True)
+
+
+def _message_text(content: Any) -> str:
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for item in content:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == "input_text":
+            text = str(item.get("text", "")).strip()
+            if text:
+                parts.append(text)
+    return "\n".join(parts).strip()
+
+
+def _coerce_timestamp(value: Any) -> float:
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str) and value:
+        normalized = value.replace("Z", "+00:00")
+        try:
+            return datetime.fromisoformat(normalized).timestamp()
+        except ValueError:
+            return 0.0
+    return 0.0

codex-sidecarV1/tests/fixtures/build_without_checks.jsonl

@@ -0,0 +1,7 @@
+{"timestamp":"2026-04-24T12:00:00.000Z","type":"session_meta","payload":{"id":"019dbf14-build-0000","timestamp":"2026-04-24T12:00:00.000Z","cwd":"/home/smlflg/Projekte/codex-sidecarV1","originator":"codex-tui","cli_version":"0.124.0","model_provider":"openai"}}
+{"timestamp":"2026-04-24T12:00:01.000Z","type":"event_msg","session_id":"019dbf14-build-0000","payload":{"type":"task_started","turn_id":"turn-build","started_at":1777027267}}
+{"timestamp":"2026-04-24T12:00:02.000Z","type":"event_msg","session_id":"019dbf14-build-0000","payload":{"type":"user_message","message":"build only parser module in src/parser.py and update status output","images":[],"local_images":[],"text_elements":[]}}
+{"timestamp":"2026-04-24T12:00:03.000Z","type":"response_item","session_id":"019dbf14-build-0000","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"sed -n '1,120p' src/parser.py\",\"workdir\":\"/home/smlflg/Projekte/codex-sidecarV1\"}","call_id":"call-build-read"}}
+{"timestamp":"2026-04-24T12:00:03.500Z","type":"response_item","session_id":"019dbf14-build-0000","payload":{"type":"function_call_output","call_id":"call-build-read","output":"Chunk ID: 2\\nProcess exited with code 0\\nOutput:\\nparser"}}
+{"timestamp":"2026-04-24T12:00:04.000Z","type":"event_msg","session_id":"019dbf14-build-0000","payload":{"type":"exec_command_end","call_id":"call-build-read","process_id":"124","turn_id":"turn-build","command":["/bin/bash","-lc","sed -n '1,120p' src/parser.py"],"cwd":"/home/smlflg/Projekte/codex-sidecarV1","parsed_cmd":[{"type":"unknown","cmd":"sed -n '1,120p' src/parser.py"}],"source":"unified_exec_startup","stdout":"","stderr":"","aggregated_output":"parser","exit_code":0,"duration":{"secs":0,"nanos":8031},"formatted_output":"","status":"completed"}}
+{"timestamp":"2026-04-24T12:00:05.000Z","type":"event_msg","session_id":"019dbf14-build-0000","payload":{"type":"agent_message","message":"I updated the parser path mentally but no tests were requested.","phase":"commentary","memory_citation":null}}

codex-sidecarV1/tests/fixtures/risky_shell.jsonl

@@ -0,0 +1,6 @@
+{"timestamp":"2026-04-24T12:10:00.000Z","type":"session_meta","payload":{"id":"019dbf14-risk-0000","timestamp":"2026-04-24T12:10:00.000Z","cwd":"/home/smlflg/Projekte/codex-sidecarV1","originator":"codex-tui","cli_version":"0.124.0","model_provider":"openai"}}
+{"timestamp":"2026-04-24T12:10:01.000Z","type":"event_msg","session_id":"019dbf14-risk-0000","payload":{"type":"task_started","turn_id":"turn-risk","started_at":1777027267}}
+{"timestamp":"2026-04-24T12:10:02.000Z","type":"event_msg","session_id":"019dbf14-risk-0000","payload":{"type":"user_message","message":"build only cleanup script and skip tests before push directly to production","images":[],"local_images":[],"text_elements":[]}}
+{"timestamp":"2026-04-24T12:10:03.000Z","type":"response_item","session_id":"019dbf14-risk-0000","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"rm -rf build && git push --force origin main\",\"workdir\":\"/home/smlflg/Projekte/codex-sidecarV1\"}","call_id":"call-risk"}}
+{"timestamp":"2026-04-24T12:10:03.500Z","type":"response_item","session_id":"019dbf14-risk-0000","payload":{"type":"function_call_output","call_id":"call-risk","output":"Chunk ID: 3\\nProcess exited with code 1\\nOutput:\\npermission denied"}}
+{"timestamp":"2026-04-24T12:10:04.000Z","type":"event_msg","session_id":"019dbf14-risk-0000","payload":{"type":"exec_command_end","call_id":"call-risk","process_id":"125","turn_id":"turn-risk","command":["/bin/bash","-lc","rm -rf build && git push --force origin main"],"cwd":"/home/smlflg/Projekte/codex-sidecarV1","parsed_cmd":[{"type":"unknown","cmd":"rm -rf build && git push --force origin main"}],"source":"unified_exec_startup","stdout":"","stderr":"","aggregated_output":"permission denied","exit_code":1,"duration":{"secs":0,"nanos":8031},"formatted_output":"","status":"failed"}}

codex-sidecarV1/tests/fixtures/subagent_session.jsonl

@@ -0,0 +1,8 @@
+{"timestamp":"2026-04-24T10:41:22.324Z","type":"session_meta","payload":{"id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","timestamp":"2026-04-24T10:40:56.880Z","cwd":"/home/smlflg/project","originator":"codex-tui","cli_version":"0.124.0","source":{"subagent":{"thread_spawn":{"parent_thread_id":"019dbf12-ad8f-7653-bdca-ca17c0fb831c","depth":1,"agent_path":null,"agent_nickname":"Darwin","agent_role":"explorer"}}},"agent_nickname":"Darwin","agent_role":"explorer","model_provider":"openai"}}
+{"timestamp":"2026-04-24T10:41:22.328Z","type":"event_msg","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"task_started","turn_id":"turn-1","started_at":1777027267}}
+{"timestamp":"2026-04-24T10:41:22.350Z","type":"event_msg","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"user_message","message":"research compare options with sources for the codex sidecar replay format","images":[],"local_images":[],"text_elements":[]}}
+{"timestamp":"2026-04-24T10:41:22.400Z","type":"response_item","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"function_call","name":"exec_command","arguments":"{\"cmd\":\"sed -n '1,120p' docs/replay.md\",\"workdir\":\"/home/smlflg/project\"}","call_id":"call-read"}}
+{"timestamp":"2026-04-24T10:41:22.450Z","type":"response_item","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"function_call_output","call_id":"call-read","output":"Chunk ID: 1\\nProcess exited with code 0\\nOutput:\\nreplay docs"}}
+{"timestamp":"2026-04-24T10:41:22.500Z","type":"event_msg","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"exec_command_end","call_id":"call-read","process_id":"123","turn_id":"turn-1","command":["/bin/bash","-lc","sed -n '1,120p' docs/replay.md"],"cwd":"/home/smlflg/project","parsed_cmd":[{"type":"unknown","cmd":"sed -n '1,120p' docs/replay.md"}],"source":"unified_exec_startup","stdout":"","stderr":"","aggregated_output":"replay docs","exit_code":0,"duration":{"secs":0,"nanos":8031},"formatted_output":"","status":"completed"}}
+{"timestamp":"2026-04-24T10:41:22.600Z","type":"event_msg","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"token_count","info":null,"rate_limits":{"primary":{"used_percent":12.0,"window_minutes":300,"resets_at":1777040182},"secondary":{"used_percent":20.0,"window_minutes":10080,"resets_at":1777400383},"plan_type":"pro"}}}
+{"timestamp":"2026-04-24T10:41:22.700Z","type":"event_msg","session_id":"019dbf14-11c2-77a3-b4a7-1c0e26456336","payload":{"type":"agent_message","message":"I compared the replay shapes and found the subagent lineage fields.","phase":"commentary","memory_citation":null}}

codex-sidecarV1/tests/test_cli.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+import json
+import subprocess
+import sys
+import unittest
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class CliTests(unittest.TestCase):
+    def _run(self, *args: str) -> subprocess.CompletedProcess[str]:
+        env = {"PYTHONPATH": str(ROOT / "src")}
+        return subprocess.run(
+            [sys.executable, "-m", "codex_sidecar", *args],
+            cwd=ROOT,
+            env=env,
+            check=False,
+            text=True,
+            capture_output=True,
+        )
+
+    def test_status_json_reports_capabilities_truth(self) -> None:
+        result = self._run("status", "--session", str(FIXTURES / "subagent_session.jsonl"), "--json")
+        self.assertEqual(result.returncode, 0)
+        payload = json.loads(result.stdout)
+        capabilities = payload["session"]["capabilities"]
+        self.assertFalse(capabilities["supports_context_injection"])
+        self.assertFalse(capabilities["supports_tool_blocking"])
+        self.assertTrue(capabilities["supports_session_replay"])
+        self.assertTrue(capabilities["supports_post_tool_observation"])
+
+    def test_replay_json_returns_subagent_summary(self) -> None:
+        result = self._run("replay", str(FIXTURES / "subagent_session.jsonl"), "--json")
+        self.assertEqual(result.returncode, 0)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["session"]["subagent"]["agent_role"], "explorer")
+
+    def test_exec_dry_run_refuses_risky_prompt(self) -> None:
+        result = self._run(
+            "exec",
+            "--prompt",
+            "build only cleanup script and skip tests before push directly to production",
+            "--dry-run",
+            "--json",
+        )
+        self.assertEqual(result.returncode, 2)
+        payload = json.loads(result.stdout)
+        self.assertFalse(payload["decision"]["allowed"])
+
+    def test_exec_dry_run_allows_safe_prompt(self) -> None:
+        result = self._run(
+            "exec",
+            "--prompt",
+            "build only parser module and run tests",
+            "--cwd",
+            str(ROOT),
+            "--dry-run",
+            "--json",
+        )
+        self.assertEqual(result.returncode, 0)
+        payload = json.loads(result.stdout)
+        self.assertTrue(payload["decision"]["allowed"])
+        self.assertEqual(payload["decision"]["contract"]["mode"], "build")
+
+
+if __name__ == "__main__":
+    unittest.main()

codex-sidecarV1/tests/test_governor.py

@@ -0,0 +1,60 @@
+from pathlib import Path
+from tempfile import TemporaryDirectory
+import unittest
+
+from codex_sidecar.governor import classify_prompt, contract_for_prompt, render_contract, wrapper_decision
+
+
+class GovernorTests(unittest.TestCase):
+    def test_empty_prompt_fail_open(self) -> None:
+        self.assertIsNone(contract_for_prompt(""))
+
+    def test_contract_has_stable_labels(self) -> None:
+        contract = contract_for_prompt("plan the smallest implementation")
+        self.assertIsNotNone(contract)
+        lines = render_contract(contract).splitlines()
+        self.assertEqual(
+            [line.split(":", 1)[0] for line in lines],
+            [
+                "Mode",
+                "Reason",
+                "Goal",
+                "Non-Goal",
+                "Stop-Condition",
+                "Allowed Behavior",
+                "Failure Signal",
+            ],
+        )
+
+    def test_build_gate_without_repo_falls_back_to_plan(self) -> None:
+        with TemporaryDirectory() as tmp:
+            mode, reason = classify_prompt(
+                "build only parser module and run tests",
+                cwd=tmp,
+                with_reason=True,
+            )
+        self.assertEqual(mode, "plan")
+        self.assertEqual(reason, "build_gated_no_repo")
+
+    def test_build_ready_requires_repo_and_check(self) -> None:
+        with TemporaryDirectory() as tmp:
+            Path(tmp, ".git").mkdir()
+            self.assertEqual(
+                classify_prompt("build only parser module and run tests", cwd=tmp),
+                "build",
+            )
+
+    def test_wrapper_refuses_risky_prompt(self) -> None:
+        with TemporaryDirectory() as tmp:
+            Path(tmp, ".git").mkdir()
+            decision = wrapper_decision(
+                "build only cleanup script and skip tests before push directly to production",
+                cwd=tmp,
+            )
+        self.assertFalse(decision.allowed)
+        self.assertEqual(decision.reason, "wrapper_refused_risky_prompt")
+        self.assertTrue(any(f.code == "risk_skip_tests" for f in decision.findings))
+
+
+if __name__ == "__main__":
+    unittest.main()

codex-sidecarV1/tests/test_state.py

@@ -0,0 +1,42 @@
+from pathlib import Path
+import unittest
+
+from codex_sidecar.state import build_snapshot
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+class StateTests(unittest.TestCase):
+    def test_replay_builds_subagent_aware_snapshot(self) -> None:
+        snapshot = build_snapshot(FIXTURES / "subagent_session.jsonl")
+
+        self.assertEqual(snapshot.session_id, "019dbf14-11c2-77a3-b4a7-1c0e26456336")
+        self.assertEqual(snapshot.workflow_phase, "responded")
+        self.assertEqual(snapshot.contract.mode, "research")
+        self.assertEqual(snapshot.subagent["parent_thread_id"], "019dbf12-ad8f-7653-bdca-ca17c0fb831c")
+        self.assertEqual(snapshot.subagent["agent_nickname"], "Darwin")
+        self.assertEqual(snapshot.touched_files, ("docs/replay.md",))
+        self.assertEqual(snapshot.rate_limits["primary"]["used_percent"], 12.0)
+        self.assertTrue(any(f.code == "subagent_lineage_present" for f in snapshot.findings))
+
+    def test_build_without_check_produces_plan_contract_and_advisory(self) -> None:
+        snapshot = build_snapshot(FIXTURES / "build_without_checks.jsonl")
+
+        self.assertEqual(snapshot.contract.mode, "plan")
+        self.assertEqual(snapshot.contract.reason, "build_gated_missing_check")
+        self.assertFalse(snapshot.verification_seen)
+        self.assertEqual(snapshot.workflow_phase, "responded")
+
+    def test_risky_shell_is_advisory_not_fake_block(self) -> None:
+        snapshot = build_snapshot(FIXTURES / "risky_shell.jsonl")
+
+        self.assertEqual(snapshot.capabilities["supports_tool_blocking"], False)
+        codes = {finding.code for finding in snapshot.findings}
+        self.assertIn("dangerous_rm", codes)
+        self.assertIn("force_push", codes)
+        self.assertIn("tool_error", codes)
+        self.assertEqual(snapshot.errors, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

codex-sidecarV1/tests/test_watcher.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+import unittest
+
+from codex_sidecar.watcher import normalize_session_file
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+class WatcherTests(unittest.TestCase):
+    def test_normalize_realistic_subagent_session(self) -> None:
+        path = FIXTURES / "subagent_session.jsonl"
+        events = normalize_session_file(path)
+
+        self.assertEqual(events[0].kind, "session_meta")
+        self.assertEqual(events[0].session_id, "019dbf14-11c2-77a3-b4a7-1c0e26456336")
+        self.assertEqual(events[0].cwd, "/home/smlflg/project")
+
+        tool_call = next(event for event in events if event.kind == "tool_call")
+        self.assertEqual(tool_call.tool_name, "exec_command")
+        self.assertEqual(tool_call.arguments["cmd"], "sed -n '1,120p' docs/replay.md")
+
+        tool_output = next(event for event in events if event.kind == "tool_output")
+        self.assertEqual(tool_output.call_id, "call-read")
+        self.assertIn("Process exited with code 0", tool_output.output)
+
+
+if __name__ == "__main__":
+    unittest.main()

sidecar-v7-demo/.codex/config.toml

@@ -0,0 +1,31 @@
+# Coding MCPs: project-local registration (2026-09-07).
+
+[mcp_servers.serena]
+command = "/home/smlflg/.local/share/coding-mcp/serena/.venv/bin/serena"
+args = ["start-mcp-server", "--context=codex", "--project", "/home/smlflg/Projekte/Sidecar-Workspace/sidecar-v7-demo", "--enable-web-dashboard", "false", "--open-web-dashboard", "false", "--enable-gui-log-window", "false"]
+cwd = "/home/smlflg/Projekte/Sidecar-Workspace/sidecar-v7-demo"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+[mcp_servers.serena.env]
+"SERENA_HOME" = "/home/smlflg/.local/share/coding-mcp/serena/state"
+
+[mcp_servers.gitnexus]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/gitnexus/node_modules/gitnexus/dist/cli/index.js", "mcp"]
+cwd = "/home/smlflg/Projekte/Sidecar-Workspace/sidecar-v7-demo"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180
+
+[mcp_servers.gitnexus.env]
+"GITNEXUS_HOME" = "/home/smlflg/.local/share/coding-mcp/gitnexus/runtime"
+
+[mcp_servers.context7]
+command = "/home/smlflg/.nvm/versions/node/v24.13.0/bin/node"
+args = ["/home/smlflg/.local/share/coding-mcp/context7/node_modules/@upstash/context7-mcp/dist/index.js"]
+cwd = "/home/smlflg/Projekte/Sidecar-Workspace/sidecar-v7-demo"
+enabled = true
+startup_timeout_sec = 120
+tool_timeout_sec = 180

sidecar-v7-demo/index.html

@@ -0,0 +1,1069 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Sidecar V7 &mdash; Wie es dir hilft</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@400;500;600;700;800&family=Fragment+Mono:wght@400&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --font-body: 'Bricolage Grotesque', system-ui, sans-serif;
+    --font-mono: 'Fragment Mono', 'SF Mono', Consolas, monospace;
+
+    /* Catppuccin Mocha — Dark First */
+    --base: #1e1e2e;
+    --mantle: #181825;
+    --crust: #11111b;
+    --surface0: #313244;
+    --surface1: #45475a;
+    --surface2: #585b70;
+    --overlay0: #6c7086;
+    --overlay1: #7f849c;
+    --text: #cdd6f4;
+    --text-dim: #a6adc8;
+    --subtext0: #a6adc8;
+    --subtext1: #bac2de;
+
+    --rosewater: #f5e0dc;
+    --flamingo: #f2cdcd;
+    --pink: #f5c2e7;
+    --mauve: #cba6f7;
+    --red: #f38ba8;
+    --maroon: #eba0ac;
+    --peach: #fab387;
+    --yellow: #f9e2af;
+    --green: #a6e3a1;
+    --teal: #94e2d5;
+    --sky: #89dceb;
+    --sapphire: #74c7ec;
+    --blue: #89b4fa;
+    --lavender: #b4befe;
+
+    --bg: var(--base);
+    --card: var(--surface0);
+    --card-hover: var(--surface1);
+    --border: var(--surface1);
+    --accent: var(--mauve);
+    --accent-dim: rgba(203, 166, 247, 0.12);
+  }
+
+  @media (prefers-color-scheme: light) {
+    :root {
+      --base: #eff1f5;
+      --mantle: #e6e9ef;
+      --crust: #dce0e8;
+      --surface0: #ccd0da;
+      --surface1: #bcc0cc;
+      --surface2: #acb0be;
+      --overlay0: #9ca0b0;
+      --overlay1: #8c8fa1;
+      --text: #4c4f69;
+      --text-dim: #6c6f85;
+      --subtext0: #6c6f85;
+      --subtext1: #5c5f77;
+
+      --rosewater: #dc8a78;
+      --flamingo: #dd7878;
+      --pink: #ea76cb;
+      --mauve: #8839ef;
+      --red: #d20f39;
+      --maroon: #e64553;
+      --peach: #fe640b;
+      --yellow: #df8e1d;
+      --green: #40a02b;
+      --teal: #179299;
+      --sky: #04a5e5;
+      --sapphire: #209fb5;
+      --blue: #1e66f5;
+      --lavender: #7287fd;
+
+      --bg: var(--base);
+      --card: var(--mantle);
+      --card-hover: var(--crust);
+      --border: var(--surface1);
+      --accent: var(--mauve);
+      --accent-dim: rgba(136, 57, 239, 0.08);
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: var(--font-body);
+    line-height: 1.6;
+    min-height: 100vh;
+  }
+
+  @keyframes fadeUp {
+    from { opacity: 0; transform: translateY(16px); }
+    to { opacity: 1; transform: translateY(0); }
+  }
+  .anim {
+    animation: fadeUp 0.45s ease-out both;
+    animation-delay: calc(var(--i, 0) * 0.04s);
+  }
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0.01ms !important;
+      transition-duration: 0.01ms !important;
+    }
+  }
+
+  .wrap {
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 48px 28px 80px;
+  }
+
+  /* ===== HEADER ===== */
+  .hero { text-align: center; margin-bottom: 64px; }
+  .hero h1 {
+    font-size: clamp(2rem, 5vw, 3.2rem);
+    font-weight: 800;
+    letter-spacing: -0.02em;
+    background: linear-gradient(135deg, var(--mauve), var(--blue), var(--teal));
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+    margin-bottom: 12px;
+  }
+  .hero .subtitle {
+    font-size: 1.15rem;
+    color: var(--text-dim);
+    max-width: 620px;
+    margin: 0 auto;
+  }
+  .hero .badge-row {
+    display: flex;
+    justify-content: center;
+    gap: 12px;
+    margin-top: 20px;
+    flex-wrap: wrap;
+  }
+  .badge {
+    font-family: var(--font-mono);
+    font-size: 0.78rem;
+    padding: 4px 14px;
+    border-radius: 20px;
+    border: 1px solid var(--border);
+    background: var(--card);
+    color: var(--text-dim);
+  }
+
+  /* ===== SECTION ===== */
+  section { margin-bottom: 72px; }
+  .section-label {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.12em;
+    color: var(--accent);
+    margin-bottom: 6px;
+  }
+  .section-title {
+    font-size: 1.7rem;
+    font-weight: 700;
+    margin-bottom: 8px;
+  }
+  .section-desc {
+    color: var(--text-dim);
+    max-width: 680px;
+    margin-bottom: 28px;
+  }
+
+  /* ===== CARDS ===== */
+  .card {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 24px;
+    transition: border-color 0.2s, background 0.2s;
+  }
+  .card:hover {
+    border-color: var(--accent);
+    background: var(--card-hover);
+  }
+  .card h3 {
+    font-size: 1.1rem;
+    font-weight: 600;
+    margin-bottom: 8px;
+  }
+  .card p, .card li {
+    color: var(--text-dim);
+    font-size: 0.92rem;
+  }
+
+  /* ===== 3-COLUMN INTRO ===== */
+  .intro-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 20px;
+  }
+  .intro-grid .card { position: relative; padding-left: 28px; }
+  .intro-grid .card::before {
+    content: '';
+    position: absolute;
+    left: 0;
+    top: 24px;
+    bottom: 24px;
+    width: 3px;
+    border-radius: 2px;
+  }
+  .intro-grid .card:nth-child(1)::before { background: var(--green); }
+  .intro-grid .card:nth-child(2)::before { background: var(--blue); }
+  .intro-grid .card:nth-child(3)::before { background: var(--yellow); }
+  .speed { font-family: var(--font-mono); font-size: 0.8rem; color: var(--green); }
+
+  /* ===== FLOW DIAGRAM ===== */
+  .flow {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0;
+    margin: 36px 0;
+    flex-wrap: wrap;
+  }
+  .flow-node {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 14px 22px;
+    font-weight: 600;
+    font-size: 0.95rem;
+    text-align: center;
+    min-width: 120px;
+    position: relative;
+  }
+  .flow-node.samuel { border-color: var(--green); color: var(--green); }
+  .flow-node.sidecar {
+    border-color: var(--mauve);
+    color: var(--mauve);
+    background: var(--accent-dim);
+  }
+  .flow-arrow {
+    font-size: 1.4rem;
+    color: var(--overlay0);
+    padding: 0 8px;
+    flex-shrink: 0;
+  }
+  .flow-outputs {
+    display: grid;
+    grid-template-columns: repeat(5, 1fr);
+    gap: 8px;
+    margin-top: 8px;
+  }
+  @media (max-width: 800px) {
+    .flow-outputs { grid-template-columns: repeat(2, 1fr); }
+  }
+  .flow-out {
+    font-family: var(--font-mono);
+    font-size: 0.72rem;
+    padding: 8px 10px;
+    border-radius: 8px;
+    text-align: center;
+    cursor: pointer;
+    border: 1px solid var(--border);
+    background: var(--card);
+    transition: all 0.2s;
+    color: var(--text-dim);
+  }
+  .flow-out:hover, .flow-out.active {
+    border-color: var(--accent);
+    color: var(--text);
+    background: var(--accent-dim);
+  }
+  .flow-out .num {
+    display: block;
+    font-family: var(--font-body);
+    font-weight: 700;
+    font-size: 1.3rem;
+    margin-bottom: 2px;
+  }
+
+  /* ===== TABS ===== */
+  .tab-content { display: none; }
+  .tab-content.active { display: block; }
+  .tab-panel {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    padding: 28px;
+    margin-top: 16px;
+  }
+  .tab-panel h3 {
+    font-size: 1.2rem;
+    font-weight: 700;
+    margin-bottom: 10px;
+  }
+  .tab-panel h3 .icon { margin-right: 8px; }
+  .tab-panel ul { list-style: none; padding: 0; }
+  .tab-panel li {
+    padding: 6px 0;
+    color: var(--text-dim);
+    font-size: 0.9rem;
+    border-bottom: 1px solid rgba(255,255,255,0.03);
+  }
+  .tab-panel li:last-child { border: none; }
+  .tab-panel li strong { color: var(--text); }
+  .tab-panel .meta {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    color: var(--overlay1);
+    margin-top: 14px;
+  }
+  .tab-panel .highlight {
+    display: inline-block;
+    padding: 2px 10px;
+    border-radius: 6px;
+    font-family: var(--font-mono);
+    font-size: 0.78rem;
+  }
+  .hl-green { background: rgba(166,227,161,0.12); color: var(--green); }
+  .hl-blue { background: rgba(137,180,250,0.12); color: var(--blue); }
+  .hl-red { background: rgba(243,139,168,0.12); color: var(--red); }
+  .hl-yellow { background: rgba(249,226,175,0.12); color: var(--yellow); }
+  .hl-mauve { background: rgba(203,166,247,0.12); color: var(--mauve); }
+  .hl-peach { background: rgba(250,179,135,0.12); color: var(--peach); }
+  .hl-teal { background: rgba(148,226,213,0.12); color: var(--teal); }
+
+  /* ===== MECHANISM GRID ===== */
+  .filter-bar {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin-bottom: 20px;
+  }
+  .filter-btn {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    padding: 5px 14px;
+    border-radius: 20px;
+    border: 1px solid var(--border);
+    background: var(--card);
+    color: var(--text-dim);
+    cursor: pointer;
+    transition: all 0.2s;
+  }
+  .filter-btn:hover, .filter-btn.active {
+    border-color: var(--accent);
+    color: var(--text);
+    background: var(--accent-dim);
+  }
+  .mech-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+    gap: 10px;
+  }
+  .mech-chip {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px 14px;
+    transition: all 0.2s;
+    cursor: default;
+  }
+  .mech-chip:hover {
+    border-color: var(--accent);
+    background: var(--card-hover);
+  }
+  .mech-chip .mech-head {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+    margin-bottom: 4px;
+  }
+  .mech-chip .mech-id {
+    font-family: var(--font-mono);
+    font-size: 0.7rem;
+    color: var(--overlay1);
+    min-width: 24px;
+  }
+  .mech-chip .mech-name {
+    font-weight: 600;
+    font-size: 0.85rem;
+    color: var(--text);
+  }
+  .mech-chip .mech-desc {
+    font-size: 0.8rem;
+    color: var(--text-dim);
+    margin-bottom: 4px;
+  }
+  .mech-chip .mech-meta {
+    font-family: var(--font-mono);
+    font-size: 0.68rem;
+    color: var(--overlay0);
+  }
+  .mech-chip .cat-dot {
+    display: inline-block;
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    margin-right: 4px;
+    vertical-align: middle;
+  }
+  .cat-focus { background: var(--blue); }
+  .cat-learning { background: var(--green); }
+  .cat-project { background: var(--peach); }
+  .cat-dopamine { background: var(--yellow); }
+  .cat-awareness { background: var(--flamingo); }
+  .cat-quality { background: var(--red); }
+  .cat-adhs { background: var(--mauve); }
+
+  .mech-count {
+    font-family: var(--font-mono);
+    font-size: 0.8rem;
+    color: var(--text-dim);
+    margin-bottom: 14px;
+  }
+
+  /* ===== PROFILE GRID ===== */
+  .profile-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 20px;
+  }
+  .profile-grid .card ul { list-style: none; padding: 0; }
+  .profile-grid .card li {
+    padding: 4px 0;
+    font-size: 0.88rem;
+    display: flex;
+    justify-content: space-between;
+    border-bottom: 1px solid rgba(255,255,255,0.03);
+  }
+  .profile-grid .card li:last-child { border: none; }
+  .skill-level {
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    padding: 1px 8px;
+    border-radius: 4px;
+  }
+  .sl-kann-bauen { background: rgba(166,227,161,0.15); color: var(--green); }
+  .sl-kann-nutzen { background: rgba(137,180,250,0.15); color: var(--blue); }
+  .sl-basics { background: rgba(249,226,175,0.15); color: var(--yellow); }
+  .sl-keine { background: rgba(108,112,134,0.15); color: var(--overlay0); }
+  .sl-angst { background: rgba(243,139,168,0.2); color: var(--red); }
+
+  .fear-card {
+    background: rgba(243,139,168,0.06);
+    border-color: rgba(243,139,168,0.2);
+  }
+  .fear-card h4 {
+    color: var(--red);
+    font-size: 0.95rem;
+    margin-bottom: 8px;
+  }
+
+  /* ===== TUNING ===== */
+  .tuning-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+    gap: 20px;
+  }
+  .tuning-grid .card h4 {
+    font-size: 0.95rem;
+    font-weight: 600;
+    margin-bottom: 8px;
+  }
+
+  /* ===== CLI ===== */
+  .cli-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+    gap: 12px;
+  }
+  .cli-cmd {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 12px 16px;
+  }
+  .cli-cmd code {
+    font-family: var(--font-mono);
+    font-size: 0.82rem;
+    color: var(--green);
+    display: block;
+    margin-bottom: 4px;
+  }
+  .cli-cmd span {
+    font-size: 0.82rem;
+    color: var(--text-dim);
+  }
+
+  /* ===== COLLAPSIBLE ===== */
+  details {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    margin-bottom: 8px;
+  }
+  details summary {
+    padding: 10px 16px;
+    cursor: pointer;
+    font-weight: 600;
+    font-size: 0.92rem;
+    user-select: none;
+  }
+  details summary:hover { color: var(--accent); }
+  details[open] summary { border-bottom: 1px solid var(--border); }
+  details .inner { padding: 14px 16px; font-size: 0.88rem; color: var(--text-dim); }
+
+  /* ===== FOOTER ===== */
+  footer {
+    text-align: center;
+    color: var(--overlay0);
+    font-size: 0.78rem;
+    font-family: var(--font-mono);
+    padding: 32px 0 24px;
+    border-top: 1px solid var(--border);
+    margin-top: 48px;
+  }
+</style>
+</head>
+<body>
+
+<div class="wrap">
+
+<!-- ============================================================ -->
+<!-- HERO -->
+<!-- ============================================================ -->
+<header class="hero anim" style="--i:0">
+  <h1>Wie Sidecar dir hilft</h1>
+  <p class="subtitle">Dein unsichtbarer Co-Pilot: ein QA-Daemon der bei jedem Claude-Prompt mitlaeuft, Muster erkennt, coacht und schuetzt.</p>
+  <div class="badge-row">
+    <span class="badge">V7 &middot; ~11K LOC</span>
+    <span class="badge">48 Mechanismen</span>
+    <span class="badge">Florian TTS+STT</span>
+    <span class="badge">MiniMax Deep Analysis</span>
+    <span class="badge">Socket: /tmp/sidecar-v7.sock</span>
+  </div>
+</header>
+
+<!-- ============================================================ -->
+<!-- SEKTION 1: Dein unsichtbarer Co-Pilot -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:2">
+  <div class="section-label">Sektion 1</div>
+  <h2 class="section-title">Dein unsichtbarer Co-Pilot</h2>
+  <p class="section-desc">Sidecar laeuft als Daemon im Hintergrund. Bei jedem Prompt, bei jedem Tool-Call schaut es mit — ohne dass du etwas tun musst.</p>
+
+  <div class="intro-grid">
+    <div class="card">
+      <h3>Was es ist</h3>
+      <p>Ein Python-Daemon der ueber einen Unix Socket mit Claude Code kommuniziert. Hooks in <code style="font-family:var(--font-mono);color:var(--accent)">~/.claude/hooks/</code> senden Events, Sidecar antwortet mit Context-Injection, Coaching-Nudges oder Safety-Blocks.</p>
+    </div>
+    <div class="card">
+      <h3>Zwei Geschwindigkeiten</h3>
+      <p><span class="speed">&lt;5ms</span> <strong>Fast Path</strong> &mdash; deterministische Regeln, Cooldowns, Pattern-Matching. Kostet $0.</p>
+      <p style="margin-top:8px"><span class="speed" style="color:var(--peach)">~2-5s</span> <strong>Slow Path</strong> &mdash; MiniMax M2.5 Deep Analysis mit Function Calling. ~$0.0003/Call.</p>
+    </div>
+    <div class="card">
+      <h3>Fail-Open Design</h3>
+      <p>Wenn Sidecar abstuerzt oder der Socket nicht erreichbar ist, laeuft Claude ganz normal weiter. Die Bridge hat ein 3-Sekunden-Timeout und liefert statischen Fallback-Kontext.</p>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================ -->
+<!-- SEKTION 2: 5 Wege wie Sidecar eingreift -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:4">
+  <div class="section-label">Sektion 2</div>
+  <h2 class="section-title">5 Wege wie Sidecar eingreift</h2>
+  <p class="section-desc">Von fluestern bis blockieren &mdash; Sidecar hat 5 Interventionspfade, jeder mit eigener Intensitaet.</p>
+
+  <!-- Flow Diagram -->
+  <div class="flow anim" style="--i:5">
+    <div class="flow-node samuel">Samuel</div>
+    <div class="flow-arrow">&rarr;</div>
+    <div class="flow-node">Prompt</div>
+    <div class="flow-arrow">&rarr;</div>
+    <div class="flow-node sidecar">Sidecar V7</div>
+    <div class="flow-arrow">&rarr;</div>
+    <div class="flow-node">Claude Code</div>
+  </div>
+
+  <div class="flow-outputs anim" style="--i:6">
+    <div class="flow-out active" onclick="showTab(0)" id="ftab-0"><span class="num">1</span>Context Injection</div>
+    <div class="flow-out" onclick="showTab(1)" id="ftab-1"><span class="num">2</span>Coaching Nudges</div>
+    <div class="flow-out" onclick="showTab(2)" id="ftab-2"><span class="num">3</span>Florian spricht</div>
+    <div class="flow-out" onclick="showTab(3)" id="ftab-3"><span class="num">4</span>Safety Gates</div>
+    <div class="flow-out" onclick="showTab(4)" id="ftab-4"><span class="num">5</span>Deep Analysis</div>
+  </div>
+
+  <!-- Tab 1: Context Injection -->
+  <div class="tab-content active" id="tab-0">
+    <div class="tab-panel">
+      <h3><span class="icon">&#128172;</span> Context Injection &mdash; Sidecar fluestert Claude Kontext zu</h3>
+      <p style="color:var(--text-dim);margin-bottom:14px">Bei <strong>jedem einzelnen Prompt</strong> injiziert Sidecar zusaetzlichen Kontext in das <code style="font-family:var(--font-mono);color:var(--accent)">additionalContext</code>-Feld. Claude sieht ihn, du nicht.</p>
+      <ul>
+        <li><strong>Phase-Erkennung</strong> &mdash; Wo bist du gerade? <span class="highlight hl-blue">exploration</span> <span class="highlight hl-green">implementation</span> <span class="highlight hl-yellow">testing</span> <span class="highlight hl-red">debugging</span></li>
+        <li><strong>Workflow-Phase</strong> &mdash; Abgeleitet aus der Activity-Phase: <span class="highlight hl-teal">planning &rarr; build &rarr; test &rarr; deploy</span></li>
+        <li><strong>Contract-Tracking</strong> &mdash; Pflichten pro Phase (must/should). Score 0-100%. Warnung wenn Obligations nicht erfuellt.</li>
+        <li><strong>Anti-Pattern-Warnungen</strong> &mdash; Erkennt Hypothesen-lose Delegation, Silent Long-Running, Vibe-Coding ohne Verstaendnis.</li>
+        <li><strong>Skill-Empfehlungen</strong> &mdash; 14 Skills, phasenbasiert. In Exploration: <code style="font-family:var(--font-mono)">/research</code>, in Testing: <code style="font-family:var(--font-mono)">/test</code>.</li>
+        <li><strong>ADHS-Patterns</strong> &mdash; Hyperfocus-Warnung, Session-Sprawl-Erkennung, Paralysis-Detection nach 20min.</li>
+        <li><strong>Personal Context</strong> &mdash; Energie-Level (Peak 13-17h), Stimmung (Keyword-Analyse), Tageszeit, Angst-Themen.</li>
+        <li><strong>Twin Memory</strong> &mdash; Relevante Beobachtungen aus der Memory-DB (Insights, Fear-Log, gelernte Konzepte).</li>
+      </ul>
+      <div class="meta">Hook: UserPromptSubmit &rarr; bridge.py &rarr; daemon.py &rarr; ContextBridge.enrich() &rarr; additionalContext</div>
+    </div>
+  </div>
+
+  <!-- Tab 2: Coaching Nudges -->
+  <div class="tab-content" id="tab-1">
+    <div class="tab-panel">
+      <h3><span class="icon">&#127919;</span> Coaching-Nudges &mdash; 48 situative Impulse</h3>
+      <p style="color:var(--text-dim);margin-bottom:14px">48 Mechanismen in 8 Kategorien. Nur <strong>eine Nudge pro Prompt</strong> (first-match nach Prioritaet).</p>
+      <ul>
+        <li><strong>Prioritaets-System</strong> &mdash; <span class="highlight hl-mauve">ADHS (Tier 0)</span> &gt; <span class="highlight hl-blue">Fokus/Qualitaet (1)</span> &gt; <span class="highlight hl-peach">Projekt (2)</span> &gt; <span class="highlight hl-green">Lernen (3)</span> &gt; <span class="highlight hl-yellow">Dopamin/Awareness (4)</span></li>
+        <li><strong>Cooldown-System</strong> &mdash; Jeder Mechanismus hat einen eigenen Cooldown (60s bis 3600s). Verhindert Spam.</li>
+        <li><strong>EWMA-Ratings</strong> &mdash; Gewichtete Bewertung (alpha=0.3). Top-Performer feuern oefter, Underperformer seltener.</li>
+        <li><strong>MechanismResult</strong> &mdash; Jede Nudge kann: Text anzeigen, Claude's Prompt anreichern (<code style="font-family:var(--font-mono)">enrich_prompt</code>), und Twin-Queries ausloesen.</li>
+        <li><strong>Du-Perspektive</strong> &mdash; 47/48 Mechanismen sprechen dich direkt an. Nur safety_gate (#29) blockiert sofort ohne Anrede.</li>
+        <li><strong>8 Kategorien</strong> &mdash; Fokus (7), Lernen (6), Projekt (5), Dopamin (5), Awareness (5), Qualitaet (4), ADHS (4+4), Workflow (6+1+1)</li>
+      </ul>
+      <div class="meta">Registry: mechanisms.py &rarr; coach.py wire_all() &rarr; fire_all() (priority-sorted)</div>
+    </div>
+  </div>
+
+  <!-- Tab 3: Florian spricht -->
+  <div class="tab-content" id="tab-2">
+    <div class="tab-panel">
+      <h3><span class="icon">&#128483;</span> Florian spricht &mdash; Hoerbares Coaching</h3>
+      <p style="color:var(--text-dim);margin-bottom:14px">Edge TTS mit <span class="highlight hl-peach">de-DE-FlorianMultilingualNeural</span>. Sidecar spricht Nudges laut aus &mdash; du hoerst Coaching, ohne auf den Bildschirm schauen zu muessen.</p>
+      <ul>
+        <li><strong>TTS-Server</strong> &mdash; Systemd Service auf Port :5050. Health-Check bei Start, Auto-Restart wenn down.</li>
+        <li><strong>Was gesprochen wird</strong> &mdash; Fokus/ADHS-Nudges (sofort), Slow-Path-Ergebnisse (zusammengefasst), Commit-Digests, Feierabend-Summary.</li>
+        <li><strong>Cooldowns pro Typ</strong> &mdash; celebration: 30s, milestone/commit: 60s, info: 120s, narration: 120s, commit_digest: 240s, goal/scope_creep: 300s, coaching: 300s, paralysis: 600s, feierabend: 1800s</li>
+        <li><strong>Dedup</strong> &mdash; Ring-Buffer der letzten 10 gesprochenen Texte. Keine Wiederholungen.</li>
+        <li><strong>STT-Antworten</strong> &mdash; Whisper STT. Samuel kann auf gesprochene Nudges antworten (max 3 Runden Dialog).</li>
+        <li><strong>TTS Voting</strong> &mdash; Multi-dimensional: Content (1-3), Timing (1-3), Form (1-3) + dismiss_ms. Legacy-kompatibel mit +1/-1.</li>
+        <li><strong>Text-Aufbereitung</strong> &mdash; Backticks entfernt, Pfade gekuerzt, Abkuerzungen expandiert (PR&rarr;Pull Request, LOC&rarr;Lines of Code), Zahlen 0-12 als Woerter.</li>
+      </ul>
+      <div class="meta">samuel/florian.py &rarr; Edge TTS :5050 &rarr; paplay/pw-play/aplay | samuel/stt.py (Whisper)</div>
+    </div>
+  </div>
+
+  <!-- Tab 4: Safety Gates -->
+  <div class="tab-content" id="tab-3">
+    <div class="tab-panel">
+      <h3><span class="icon">&#128721;</span> Safety Gates &mdash; Blockiert gefaehrliche Aktionen</h3>
+      <p style="color:var(--text-dim);margin-bottom:14px">PreToolUse Hook. Geprueft <strong>bevor</strong> ein Tool ausgefuehrt wird. Blockiert sofort &mdash; kein Cooldown, keine Bewertung.</p>
+
+      <details open>
+        <summary>Gefaehrliche Bash-Befehle</summary>
+        <div class="inner">
+          <ul>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">rm -rf ~/</code> oder <code style="font-family:var(--font-mono);color:var(--red)">rm -rf .</code> &mdash; Loeschen von Home/Root/CWD</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">git push --force</code> &mdash; Force Push</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">git reset --hard</code> &mdash; Hard Reset</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">DROP TABLE / DROP DATABASE</code> &mdash; SQL Drop</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">chmod 777</code> &mdash; Unsichere Berechtigungen</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">mkfs.*</code> &mdash; Dateisystem formatieren</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">sudo / su</code> &mdash; Kein TTY in Claude Code</li>
+            <li><code style="font-family:var(--font-mono);color:var(--red)">> /dev/sd*</code> &mdash; Direktes Schreiben auf Block Devices</li>
+          </ul>
+        </div>
+      </details>
+      <details>
+        <summary>Secret Exposure (Warnung)</summary>
+        <div class="inner">
+          <p>Bei Write/Edit: Warnt wenn API Keys, Passwörter oder Tokens im Code erscheinen. ANTHROPIC_API_KEY, MINIMAX_API_KEY, OPENAI_API_KEY, AWS_SECRET_ACCESS_KEY, password=, token=.</p>
+        </div>
+      </details>
+      <details>
+        <summary>WebSearch/WebFetch in SubAgents</summary>
+        <div class="inner">
+          <p>Blockiert WebSearch und WebFetch komplett &mdash; erzeugen Permission-Prompts die Samuel unterbrechen. Stattdessen: Gemini MCP als Background-Agent.</p>
+          <p>Prueft auch Agent-Prompts auf "websearch"/"webfetch" Keywords und blockiert diese.</p>
+        </div>
+      </details>
+      <div class="meta">Hook: PreToolUse &rarr; safety.py check_safety() + check_secret_exposure() &rarr; block/allow</div>
+    </div>
+  </div>
+
+  <!-- Tab 5: Deep Analysis -->
+  <div class="tab-content" id="tab-4">
+    <div class="tab-panel">
+      <h3><span class="icon">&#129504;</span> Deep Analysis &mdash; MiniMax Slow Path</h3>
+      <p style="color:var(--text-dim);margin-bottom:14px">Periodische LLM-Bewertung deiner Arbeit durch MiniMax M2.5 mit sandboxed Function Calling.</p>
+      <ul>
+        <li><strong>4 Tools</strong> &mdash; <code style="font-family:var(--font-mono)">read_file</code>, <code style="font-family:var(--font-mono)">list_dir</code>, <code style="font-family:var(--font-mono)">search_code</code>, <code style="font-family:var(--font-mono)">write_protocol</code> (sandboxed, read-only + Protokoll)</li>
+        <li><strong>Adaptives Intervall</strong> &mdash; 10min (clean), 5min (1+ Fehler), 3min (3+ Fehler)</li>
+        <li><strong>Event-Trigger</strong> &mdash; Error-Burst, Phase-Change, Stuck-Detection loesen sofortige Analyse aus</li>
+        <li><strong>Budget</strong> &mdash; $0.50/Tag, ~$0.0003/Analyse. BudgetTracker verhindert Ueberschreitung.</li>
+        <li><strong>Ergebnis-Pipeline</strong> &mdash; Analyse-Ergebnis wird auf den naechsten Prompt geprepended + optional von Florian vorgelesen.</li>
+        <li><strong>Coaching Rules</strong> &mdash; MiniMax kennt Samuels Regeln aus <code style="font-family:var(--font-mono)">coaching_rules.txt</code>: Research First, Delegation, CLI First, Intent First, Session-Hygiene.</li>
+      </ul>
+      <div class="meta">samuel/harness.py &rarr; MiniMax M2.5 Agent Loop &rarr; Function Calling &rarr; write_protocol &rarr; next prompt</div>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================ -->
+<!-- SEKTION 3: 48 Mechanismen -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:7">
+  <div class="section-label">Sektion 3</div>
+  <h2 class="section-title">48 Mechanismen &mdash; dein Coaching-Team</h2>
+  <p class="section-desc">Jeder Mechanismus erkennt ein Muster und reagiert darauf. Filtere nach Kategorie.</p>
+
+  <div class="filter-bar">
+    <button class="filter-btn active" onclick="filterMechs('all')">Alle (48)</button>
+    <button class="filter-btn" onclick="filterMechs('focus')"><span class="cat-dot cat-focus"></span>Fokus (7)</button>
+    <button class="filter-btn" onclick="filterMechs('learning')"><span class="cat-dot cat-learning"></span>Lernen (6)</button>
+    <button class="filter-btn" onclick="filterMechs('project')"><span class="cat-dot cat-project"></span>Projekt (5)</button>
+    <button class="filter-btn" onclick="filterMechs('dopamine')"><span class="cat-dot cat-dopamine"></span>Dopamin (5)</button>
+    <button class="filter-btn" onclick="filterMechs('awareness')"><span class="cat-dot cat-awareness"></span>Awareness (5)</button>
+    <button class="filter-btn" onclick="filterMechs('quality')"><span class="cat-dot cat-quality"></span>Qualitaet (10)</button>
+    <button class="filter-btn" onclick="filterMechs('adhs')"><span class="cat-dot cat-adhs"></span>ADHS (6)</button>
+  </div>
+  <div class="mech-count" id="mech-count">48 Mechanismen</div>
+
+  <div class="mech-grid" id="mech-grid">
+    <!-- Fokus & Session 1-7 -->
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#1</span><span class="mech-name">goal_enforcement</span></div><div class="mech-desc">Session-Ziele setzen und erinnern</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#2</span><span class="mech-name">session_timer</span></div><div class="mech-desc">90-Minuten Session-Limit</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#3</span><span class="mech-name">break_reminder</span></div><div class="mech-desc">Pausen-Erinnerung nach langer Arbeit</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#4</span><span class="mech-name">scope_creep_detection</span></div><div class="mech-desc">Scope Creep erkennen bei Projektwechsel</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#5</span><span class="mech-name">context_switch_cost</span></div><div class="mech-desc">Kosten von Kontextwechseln aufzeigen</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#6</span><span class="mech-name">deep_work_protector</span></div><div class="mech-desc">Deep Work Phasen schuetzen</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#7</span><span class="mech-name">paralysis_breaker</span></div><div class="mech-desc">Paralysis nach 20 Min erkennen</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 5min</div></div>
+
+    <!-- Lernen & Wissen 8-13 -->
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#8</span><span class="mech-name">skill_matrix_check</span></div><div class="mech-desc">Skill-Level bei neuen Konzepten pruefen (Angst-Themen!)</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#9</span><span class="mech-name">explain_check</span></div><div class="mech-desc">Erklaer-Check nach Vibe-Coding</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 30min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#10</span><span class="mech-name">learning_path</span></div><div class="mech-desc">Lernpfad-Vorschlaege via MiniMax</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#11</span><span class="mech-name">micro_lesson</span></div><div class="mech-desc">Micro-Lessons bei Wissenluecken</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#12</span><span class="mech-name">pattern_recognition</span></div><div class="mech-desc">Wiederkehrende Muster erkennen</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#13</span><span class="mech-name">documentation_nudge</span></div><div class="mech-desc">Dokumentation nach Feature anregen</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 5min</div></div>
+
+    <!-- Projekt & Accountability 14-18 -->
+    <div class="mech-chip" data-cat="project"><div class="mech-head"><span class="mech-id">#14</span><span class="mech-name">milestone_tracker</span></div><div class="mech-desc">Projekt-Fortschritt tracken</div><div class="mech-meta"><span class="cat-dot cat-project"></span>Projekt &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="project"><div class="mech-head"><span class="mech-id">#15</span><span class="mech-name">commit_frequency</span></div><div class="mech-desc">Commit-Haeufigkeit ueberwachen</div><div class="mech-meta"><span class="cat-dot cat-project"></span>Projekt &middot; CD 10min</div></div>
+    <div class="mech-chip" data-cat="project"><div class="mech-head"><span class="mech-id">#16</span><span class="mech-name">test_coverage_nudge</span></div><div class="mech-desc">Tests nach Feature-Code anregen</div><div class="mech-meta"><span class="cat-dot cat-project"></span>Projekt &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="project"><div class="mech-head"><span class="mech-id">#17</span><span class="mech-name">pr_review_reminder</span></div><div class="mech-desc">PR Review Erinnerung</div><div class="mech-meta"><span class="cat-dot cat-project"></span>Projekt &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="project"><div class="mech-head"><span class="mech-id">#18</span><span class="mech-name">project_health_check</span></div><div class="mech-desc">Projekt-Gesundheits-Check</div><div class="mech-meta"><span class="cat-dot cat-project"></span>Projekt &middot; CD 5min</div></div>
+
+    <!-- Dopamin & Motivation 19-23 -->
+    <div class="mech-chip" data-cat="dopamine"><div class="mech-head"><span class="mech-id">#19</span><span class="mech-name">xp_award</span></div><div class="mech-desc">XP vergeben bei Erfolgen</div><div class="mech-meta"><span class="cat-dot cat-dopamine"></span>Dopamin &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="dopamine"><div class="mech-head"><span class="mech-id">#20</span><span class="mech-name">streak_tracker</span></div><div class="mech-desc">Streak-Counter fuer taegliche Arbeit</div><div class="mech-meta"><span class="cat-dot cat-dopamine"></span>Dopamin &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="dopamine"><div class="mech-head"><span class="mech-id">#21</span><span class="mech-name">small_win_celebration</span></div><div class="mech-desc">Kleine Erfolge feiern</div><div class="mech-meta"><span class="cat-dot cat-dopamine"></span>Dopamin &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="dopamine"><div class="mech-head"><span class="mech-id">#22</span><span class="mech-name">progress_visualization</span></div><div class="mech-desc">Fortschritt visuell darstellen</div><div class="mech-meta"><span class="cat-dot cat-dopamine"></span>Dopamin &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="dopamine"><div class="mech-head"><span class="mech-id">#23</span><span class="mech-name">challenge_mode</span></div><div class="mech-desc">Herausforderungen vorschlagen</div><div class="mech-meta"><span class="cat-dot cat-dopamine"></span>Dopamin &middot; CD 5min</div></div>
+
+    <!-- Awareness 24-28 -->
+    <div class="mech-chip" data-cat="awareness"><div class="mech-head"><span class="mech-id">#24</span><span class="mech-name">energy_level_check</span></div><div class="mech-desc">Energie-Level abfragen</div><div class="mech-meta"><span class="cat-dot cat-awareness"></span>Awareness &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="awareness"><div class="mech-head"><span class="mech-id">#25</span><span class="mech-name">peak_time_optimizer</span></div><div class="mech-desc">Peak-Zeit optimal nutzen</div><div class="mech-meta"><span class="cat-dot cat-awareness"></span>Awareness &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="awareness"><div class="mech-head"><span class="mech-id">#26</span><span class="mech-name">mood_tracker</span></div><div class="mech-desc">Stimmung tracken</div><div class="mech-meta"><span class="cat-dot cat-awareness"></span>Awareness &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="awareness"><div class="mech-head"><span class="mech-id">#27</span><span class="mech-name">reflection_prompt</span></div><div class="mech-desc">Reflexions-Fragen stellen</div><div class="mech-meta"><span class="cat-dot cat-awareness"></span>Awareness &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="awareness"><div class="mech-head"><span class="mech-id">#28</span><span class="mech-name">burnout_detector</span></div><div class="mech-desc">Burnout-Anzeichen erkennen</div><div class="mech-meta"><span class="cat-dot cat-awareness"></span>Awareness &middot; CD 5min</div></div>
+
+    <!-- Qualitaet 29-32 -->
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#29</span><span class="mech-name">safety_gate</span></div><div class="mech-desc">Gefaehrliche Befehle blockieren (str-only, kein MechanismResult)</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#30</span><span class="mech-name">code_review_nudge</span></div><div class="mech-desc">Code Review nach grossem Feature</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#31</span><span class="mech-name">refactor_detector</span></div><div class="mech-desc">Refactoring-Bedarf erkennen</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 5min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#32</span><span class="mech-name">dependency_check</span></div><div class="mech-desc">Dependency-Updates pruefen</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 5min</div></div>
+
+    <!-- ADHS 33-36 -->
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#33</span><span class="mech-name">hyperfocus_guard</span></div><div class="mech-desc">Hyperfokus nach 4h unterbrechen</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 30min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#34</span><span class="mech-name">direction_check</span></div><div class="mech-desc">Richtungs-Check nach 15 Min ohne Fortschritt</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#35</span><span class="mech-name">decision_support</span></div><div class="mech-desc">Entscheidungs-Hilfe bei A/B-Fragen</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 10min</div></div>
+    <div class="mech-chip" data-cat="learning"><div class="mech-head"><span class="mech-id">#36</span><span class="mech-name">depth_check</span></div><div class="mech-desc">Edge-Case Check alle 20 Edits</div><div class="mech-meta"><span class="cat-dot cat-learning"></span>Lernen &middot; CD 20min</div></div>
+
+    <!-- ADHS Live-Patterns 37-40 -->
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#37</span><span class="mech-name">big_bang_guard</span></div><div class="mech-desc">Warnung bei &gt;15 Edits ohne Test-Run</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 10min</div></div>
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#38</span><span class="mech-name">review_requires_test</span></div><div class="mech-desc">Review ohne vorherigen Test erkennen</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#39</span><span class="mech-name">bug_first</span></div><div class="mech-desc">Feature-Creep bei offenen Bugs erkennen</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 10min</div></div>
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#40</span><span class="mech-name">zombie_bug_detector</span></div><div class="mech-desc">Wiederkehrende Bugs ueber Sessions erkennen</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 30min</div></div>
+
+    <!-- Planning & Drift 41 -->
+    <div class="mech-chip" data-cat="focus"><div class="mech-head"><span class="mech-id">#41</span><span class="mech-name">planning_drift_detector</span></div><div class="mech-desc">Erkennt wenn Agents ohne Richtung arbeiten</div><div class="mech-meta"><span class="cat-dot cat-focus"></span>Fokus &middot; CD 15min</div></div>
+
+    <!-- Phase Contracts 42 -->
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#42</span><span class="mech-name">contract_compliance</span></div><div class="mech-desc">Prueft ob Phase-Contract-Obligations erfuellt werden</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 10min</div></div>
+
+    <!-- Workflow 43-48 (Grosse-Fehler-Analyse) -->
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#43</span><span class="mech-name">new_repo_guard</span></div><div class="mech-desc">Warnung bei neuem Repo ohne Analyse</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 30min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#44</span><span class="mech-name">skeleton_first</span></div><div class="mech-desc">Kein Test-Skeleton bei &gt;5 Edits</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 10min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#45</span><span class="mech-name">wiring_check</span></div><div class="mech-desc">Neues Feature gewired aber nicht getestet</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="quality"><div class="mech-head"><span class="mech-id">#46</span><span class="mech-name">threshold_math</span></div><div class="mech-desc">Schwellwert-Aenderung ohne Erreichbarkeits-Check</div><div class="mech-meta"><span class="cat-dot cat-quality"></span>Qualitaet &middot; CD 15min</div></div>
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#47</span><span class="mech-name">version_squared</span></div><div class="mech-desc">V(N+1) ohne V(N) Learnings</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 60min</div></div>
+    <div class="mech-chip" data-cat="adhs"><div class="mech-head"><span class="mech-id">#48</span><span class="mech-name">usage_proof</span></div><div class="mech-desc">Grosses Feature ohne Nutzungsnachweis</div><div class="mech-meta"><span class="cat-dot cat-adhs"></span>ADHS &middot; CD 30min</div></div>
+  </div>
+</section>
+
+<!-- ============================================================ -->
+<!-- SEKTION 4: Samuel kennen lernen (Personalisierung) -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:8">
+  <div class="section-label">Sektion 4</div>
+  <h2 class="section-title">Samuel kennen lernen</h2>
+  <p class="section-desc">Sidecar kennt dich &mdash; Rhythmus, Skills, Aengste, Projekte. Alles aus <code style="font-family:var(--font-mono);color:var(--accent)">samuel.toml</code> und der Digital Twin DB.</p>
+
+  <div class="profile-grid">
+    <!-- Rhythmus -->
+    <div class="card">
+      <h3>Rhythmus &amp; ADHS</h3>
+      <ul>
+        <li><span>Aufstehen</span><span class="skill-level sl-basics">11:00</span></li>
+        <li><span>Peak-Zeit</span><span class="skill-level sl-kann-bauen">13:00 &ndash; 17:00</span></li>
+        <li><span>Second Wave</span><span class="skill-level sl-kann-nutzen">18:00 &ndash; 20:00</span></li>
+        <li><span>Max Session</span><span class="skill-level sl-basics">90 min</span></li>
+        <li><span>Hyperfocus-Limit</span><span class="skill-level sl-angst">4h</span></li>
+        <li><span>Paralysis-Timeout</span><span class="skill-level sl-angst">20 min</span></li>
+        <li><span>Max Goals/Session</span><span class="skill-level sl-basics">2</span></li>
+        <li><span>Medikation</span><span class="skill-level sl-basics">Methylphenidat 10mg</span></li>
+      </ul>
+    </div>
+
+    <!-- Skills -->
+    <div class="card">
+      <h3>Skill-Matrix</h3>
+      <ul>
+        <li><span>Sockets / asyncio / Plugin-System</span><span class="skill-level sl-kann-bauen">kann-bauen</span></li>
+        <li><span>FastAPI / Prompt Engineering</span><span class="skill-level sl-kann-bauen">kann-bauen</span></li>
+        <li><span>Agent Design / Multi-Model</span><span class="skill-level sl-kann-bauen">kann-bauen</span></li>
+        <li><span>Context Engineering</span><span class="skill-level sl-kann-bauen">kann-bauen</span></li>
+        <li><span>Token Economics / Guardrails</span><span class="skill-level sl-kann-nutzen">kann-nutzen</span></li>
+        <li><span>Git / Testing / Caching</span><span class="skill-level sl-basics">basics</span></li>
+        <li><span>Cost Optimization</span><span class="skill-level sl-basics">basics</span></li>
+        <li><span>Databases / Deployment</span><span class="skill-level sl-angst">Angst</span></li>
+        <li><span>Fine-Tuning / MLOps</span><span class="skill-level sl-angst">Angst</span></li>
+        <li><span>RAG / Embeddings / Evals</span><span class="skill-level sl-keine">keine</span></li>
+      </ul>
+    </div>
+
+    <!-- Fear Map -->
+    <div class="card fear-card">
+      <h4>Fear Map &mdash; 4 Angst-Themen</h4>
+      <p style="font-size:0.88rem;color:var(--text-dim);margin-bottom:10px">Sidecar erkennt wenn du in einem Angst-Bereich arbeitest und bietet Micro-Offers an &mdash; keine Belehrung, sondern kleine Schritte.</p>
+      <ul style="list-style:none;padding:0">
+        <li style="padding:6px 0;border-bottom:1px solid rgba(243,139,168,0.1)"><strong>databases</strong> &mdash; SQL, Schema-Design, Migrations. Micro-Offer: "Ein SELECT reicht fuer heute."</li>
+        <li style="padding:6px 0;border-bottom:1px solid rgba(243,139,168,0.1)"><strong>deployment</strong> &mdash; Server, Docker, CI/CD. Micro-Offer: "Nur ein systemd Service. Kein K8s."</li>
+        <li style="padding:6px 0;border-bottom:1px solid rgba(243,139,168,0.1)"><strong>fine-tuning</strong> &mdash; Model Training, Datasets. Micro-Offer: "Erstmal nur API-Call testen."</li>
+        <li style="padding:6px 0"><strong>mlops</strong> &mdash; Pipelines, Monitoring, A/B-Tests. Micro-Offer: "Ein pytest reicht als Anfang."</li>
+      </ul>
+    </div>
+
+    <!-- Digital Twin -->
+    <div class="card">
+      <h3>Digital Twin (memory.db)</h3>
+      <p style="font-size:0.88rem;color:var(--text-dim);margin-bottom:10px">SQLite-Datenbank unter <code style="font-family:var(--font-mono);color:var(--accent)">~/.ubw/memory.db</code>. Shared mit V6.</p>
+      <ul style="list-style:none;padding:0">
+        <li style="padding:5px 0"><strong>observations</strong> &mdash; Tool-Events, Phase-Wechsel, Session-Metriken</li>
+        <li style="padding:5px 0"><strong>insights</strong> &mdash; Synthetisierte Erkenntnisse (5 Detektoren: repeated_error, phase_mismatch, time_patterns, skill_signals, session_quality)</li>
+        <li style="padding:5px 0"><strong>fear_log</strong> &mdash; Wann welches Angst-Thema getriggert wurde</li>
+        <li style="padding:5px 0"><strong>tts_ratings</strong> &mdash; Multi-dim Bewertungen (content/timing/form/dismiss_ms)</li>
+        <li style="padding:5px 0"><strong>knowledge</strong> &mdash; Explizite Fakten, Regeln, Hypothesen, Open Loops</li>
+        <li style="padding:5px 0"><strong>dynamic_memory</strong> &mdash; Automatisch synthetisiert, in Context Bridge injiziert</li>
+      </ul>
+    </div>
+  </div>
+
+  <!-- Projekte -->
+  <div style="margin-top:24px">
+    <h3 style="font-size:1.05rem;margin-bottom:12px">Projekt-Tracking</h3>
+    <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:10px">
+      <div class="card" style="padding:14px">
+        <div style="font-weight:600;font-size:0.9rem">Sidecar V7</div>
+        <div style="display:flex;justify-content:space-between;font-size:0.82rem;color:var(--text-dim)"><span>3/10 Milestones</span><span class="highlight hl-green">active</span></div>
+        <div style="height:4px;background:var(--surface1);border-radius:2px;margin-top:6px"><div style="height:100%;width:30%;background:var(--green);border-radius:2px"></div></div>
+      </div>
+      <div class="card" style="padding:14px">
+        <div style="font-weight:600;font-size:0.9rem">Sidecar V6</div>
+        <div style="display:flex;justify-content:space-between;font-size:0.82rem;color:var(--text-dim)"><span>10/10 Milestones</span><span class="highlight hl-blue">done</span></div>
+        <div style="height:4px;background:var(--surface1);border-radius:2px;margin-top:6px"><div style="height:100%;width:100%;background:var(--blue);border-radius:2px"></div></div>
+      </div>
+      <div class="card" style="padding:14px">
+        <div style="font-weight:600;font-size:0.9rem">FireTracker</div>
+        <div style="display:flex;justify-content:space-between;font-size:0.82rem;color:var(--text-dim)"><span>1/7 Milestones</span><span class="highlight hl-yellow">paused</span></div>
+        <div style="height:4px;background:var(--surface1);border-radius:2px;margin-top:6px"><div style="height:100%;width:14%;background:var(--yellow);border-radius:2px"></div></div>
+      </div>
+      <div class="card" style="padding:14px">
+        <div style="font-weight:600;font-size:0.9rem">StudyAgent</div>
+        <div style="display:flex;justify-content:space-between;font-size:0.82rem;color:var(--text-dim)"><span>1/5 Milestones</span><span class="highlight hl-yellow">paused</span></div>
+        <div style="height:4px;background:var(--surface1);border-radius:2px;margin-top:6px"><div style="height:100%;width:20%;background:var(--yellow);border-radius:2px"></div></div>
+      </div>
+      <div class="card" style="padding:14px">
+        <div style="font-weight:600;font-size:0.9rem">TypoTuner</div>
+        <div style="display:flex;justify-content:space-between;font-size:0.82rem;color:var(--text-dim)"><span>1/5 Milestones</span><span class="highlight hl-blue">done</span></div>
+        <div style="height:4px;background:var(--surface1);border-radius:2px;margin-top:6px"><div style="height:100%;width:20%;background:var(--blue);border-radius:2px"></div></div>
+      </div>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================ -->
+<!-- SEKTION 5: Sidecar lernt mit dir (Self-Tuning) -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:9">
+  <div class="section-label">Sektion 5</div>
+  <h2 class="section-title">Sidecar lernt mit dir</h2>
+  <p class="section-desc">Das System tuned sich selbst. Gute Nudges feuern oefter, schlechte seltener, tote werden deaktiviert.</p>
+
+  <div class="tuning-grid">
+    <div class="card">
+      <h4>EWMA Ratings</h4>
+      <p>Jeder Mechanismus hat eine gewichtete Bewertung. <code style="font-family:var(--font-mono);color:var(--peach)">alpha=0.3</code> &mdash; 30% neues Signal, 70% Historie.</p>
+      <p style="margin-top:8px">Startwert: 3.0 (neutral). Erster Wert wird direkt uebernommen, danach gewichtet.</p>
+    </div>
+    <div class="card">
+      <h4>Auto-Rating Signale</h4>
+      <ul style="list-style:none;padding:0">
+        <li style="padding:4px 0"><span class="highlight hl-green">+0.5</span> Commit nach Nudge</li>
+        <li style="padding:4px 0"><span class="highlight hl-red">-0.5</span> Fehler-Burst nach Nudge</li>
+        <li style="padding:4px 0"><span class="highlight hl-blue">+1/-1</span> Manuelles TTS-Voting</li>
+        <li style="padding:4px 0"><span class="highlight hl-mauve">Multi-dim</span> Content + Timing + Form + Dismiss-Speed</li>
+      </ul>
+    </div>
+    <div class="card">
+      <h4>AdaptationEngine (alle 30min)</h4>
+      <p style="font-size:0.88rem;color:var(--text-dim)">Weighted Score = 0.4 &times; success_rate + 0.3 &times; trend + 0.3 &times; context_match</p>
+      <ul style="list-style:none;padding:0;margin-top:8px">
+        <li style="padding:4px 0"><span class="highlight hl-green">Score &gt; 0.8</span> Cooldown halbiert &mdash; "Top Performer"</li>
+        <li style="padding:4px 0"><span class="highlight hl-blue">0.3 &ndash; 0.8</span> Keine Aenderung &mdash; "Normal"</li>
+        <li style="padding:4px 0"><span class="highlight hl-yellow">Score &lt; 0.3</span> Cooldown verdoppelt &mdash; "Underperformer"</li>
+        <li style="padding:4px 0"><span class="highlight hl-red">Score &lt; 0.15</span> Deaktiviert &mdash; "Remove"</li>
+        <li style="padding:4px 0"><span class="highlight hl-peach">48h ohne Fire</span> Dormant auto-disable</li>
+      </ul>
+    </div>
+    <div class="card">
+      <h4>Spaced Repetition</h4>
+      <p style="font-size:0.88rem;color:var(--text-dim)">Ebbinghaus-Intervalle fuer gelernte Konzepte: <code style="font-family:var(--font-mono)">1d &rarr; 3d &rarr; 7d &rarr; 14d &rarr; 30d</code></p>
+      <ul style="list-style:none;padding:0;margin-top:8px">
+        <li style="padding:4px 0"><strong>Gap Detection</strong> &mdash; Gleicher Fehler 3+ mal = Knowledge Gap</li>
+        <li style="padding:4px 0"><strong>Max 2 Reviews/Session</strong> &mdash; Nicht ueberfluten</li>
+        <li style="padding:4px 0"><strong>Persist</strong> &mdash; JSON unter /tmp/sidecar-v7-learner.json</li>
+      </ul>
+    </div>
+  </div>
+</section>
+
+<!-- ============================================================ -->
+<!-- SEKTION 6: So steuerst du Sidecar -->
+<!-- ============================================================ -->
+<section class="anim" style="--i:10">
+  <div class="section-label">Sektion 6</div>
+  <h2 class="section-title">So steuerst du Sidecar</h2>
+  <p class="section-desc">CLI, Dashboard und GTK Panel &mdash; drei Wege Sidecar zu kontrollieren.</p>
+
+  <h3 style="font-size:1.05rem;margin-bottom:14px">sidecar-v7-ctl</h3>
+  <div class="cli-grid">
+    <div class="cli-cmd"><code>sidecar-v7-ctl status</code><span>Session-Info, Phase, Prompts, Errors, Extensions</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl ranking</code><span>Alle 48 Mechanismen nach EWMA-Rating sortiert</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl vote &lt;id&gt; +/-</code><span>Mechanismus bewerten (thumbs up/down)</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl sessions</code><span>Alle getrackten Sessions auflisten</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl watch &lt;sid&gt;</code><span>Aktive Session wechseln</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl dashboard</code><span>Dashboard im Browser oeffnen (:5112)</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl feierabend</code><span>Florian spricht Feierabend-Summary (2-5 min)</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl proposals</code><span>Sidecar-Vorschlaege anzeigen + Lifecycle</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl knowledge add</code><span>Manuell Wissens-Objekt hinzufuegen</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl purge --days 90</code><span>Alte Memory-Rows aufraumen (dry-run moeglich)</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl skills</code><span>Skill-Matrix aus samuel.toml</span></div>
+    <div class="cli-cmd"><code>sidecar-v7-ctl ping</code><span>Daemon Health-Check (pong?)</span></div>
+  </div>
+
+  <div style="margin-top:32px;display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:20px">
+    <div class="card">
+      <h3>Dashboard (:5112)</h3>
+      <p>FastAPI + htmx + Tailwind. Live-Ansicht von:</p>
+      <ul style="list-style:none;padding:0;margin-top:8px">
+        <li style="padding:3px 0">&bull; Mechanismus-Ranking mit EWMA-Scores</li>
+        <li style="padding:3px 0">&bull; Session-Stats (Prompts, Errors, Phase)</li>
+        <li style="padding:3px 0">&bull; TTS-Log (Florian Spoken History)</li>
+        <li style="padding:3px 0">&bull; Alignment-Digest (Bookmarks, Projects, Gaps)</li>
+        <li style="padding:3px 0">&bull; Memory Explorer (Twin DB Eintraege)</li>
+        <li style="padding:3px 0">&bull; Explainer-History (alle generierten Erklaerungen)</li>
+        <li style="padding:3px 0">&bull; XP &amp; Streak-Tracker</li>
+      </ul>
+    </div>
+    <div class="card">
+      <h3>GTK3 Panel</h3>
+      <p>Kompaktes Desktop-Widget. Zeigt:</p>
+      <ul style="list-style:none;padding:0;margin-top:8px">
+        <li style="padding:3px 0">&bull; Aktuelle Phase + Workflow</li>
+        <li style="padding:3px 0">&bull; Letzte Nudge mit Rating-Widget (Emoji-Grid)</li>
+        <li style="padding:3px 0">&bull; TTS-Stop bei Downvote</li>
+        <li style="padding:3px 0">&bull; Bubble-Dismiss fuer unerwuenschte Popups</li>
+        <li style="padding:3px 0">&bull; Singleton PID (nur eine Instanz)</li>
+      </ul>
+    </div>
+    <div class="card">
+      <h3>Systemd Service</h3>
+      <p>User-Level Service:</p>
+      <ul style="list-style:none;padding:0;margin-top:8px">
+        <li style="padding:3px 0"><code style="font-family:var(--font-mono);font-size:0.82rem;color:var(--green)">systemctl --user start sidecar-v7</code></li>
+        <li style="padding:3px 0"><code style="font-family:var(--font-mono);font-size:0.82rem;color:var(--green)">journalctl --user -u sidecar-v7 -f</code></li>
+        <li style="padding:3px 0">Auto-Restart, WatchdogSec, Socket-Cleanup</li>
+      </ul>
+    </div>
+  </div>
+</section>
+
+<footer>
+  Sidecar V7 &middot; ~11K LOC &middot; core/ (MIT) + samuel/ (privat) &middot; Socket /tmp/sidecar-v7.sock &middot; Dashboard :5112 &middot; TTS :5050
+</footer>
+
+</div><!-- /wrap -->
+
+<script>
+// Tab switching for the 5 intervention paths
+function showTab(idx) {
+  document.querySelectorAll('.tab-content').forEach(el => el.classList.remove('active'));
+  document.querySelectorAll('.flow-out').forEach(el => el.classList.remove('active'));
+  const tab = document.getElementById('tab-' + idx);
+  const btn = document.getElementById('ftab-' + idx);
+  if (tab) tab.classList.add('active');
+  if (btn) btn.classList.add('active');
+}
+
+// Mechanism filter
+function filterMechs(cat) {
+  const chips = document.querySelectorAll('.mech-chip');
+  let count = 0;
+  chips.forEach(chip => {
+    if (cat === 'all' || chip.dataset.cat === cat) {
+      chip.style.display = '';
+      count++;
+    } else {
+      chip.style.display = 'none';
+    }
+  });
+  document.getElementById('mech-count').textContent = count + ' Mechanismen';
+  document.querySelectorAll('.filter-btn').forEach(btn => {
+    btn.classList.toggle('active', btn.textContent.includes(
+      cat === 'all' ? 'Alle' :
+      cat === 'focus' ? 'Fokus' :
+      cat === 'learning' ? 'Lernen' :
+      cat === 'project' ? 'Projekt' :
+      cat === 'dopamine' ? 'Dopamin' :
+      cat === 'awareness' ? 'Awareness' :
+      cat === 'quality' ? 'Qualitaet' :
+      cat === 'adhs' ? 'ADHS' : ''
+    ));
+  });
+}
+
+// Scroll-triggered fadeUp (IntersectionObserver)
+const obs = new IntersectionObserver((entries) => {
+  entries.forEach(e => {
+    if (e.isIntersecting) {
+      e.target.style.animationPlayState = 'running';
+      obs.unobserve(e.target);
+    }
+  });
+}, { threshold: 0.1 });
+
+document.querySelectorAll('.anim').forEach(el => {
+  el.style.animationPlayState = 'paused';
+  obs.observe(el);
+});
+</script>
+
+</body>
+</html>

sidecar-v7-demo/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /