tokenjam 0.2.0__py3-none-any.whl

tokenjam/cli/cmd_onboard.py

@@ -0,0 +1,779 @@
+from __future__ import annotations
+
+import json as json_mod
+import platform
+import secrets
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from tokenjam.core.config import find_config_file
+from tokenjam.utils.formatting import console
+
+
+@click.command("onboard")
+@click.option("--claude-code", "claude_code", is_flag=True, default=False,
+              help="Configure Claude Code telemetry to flow into tj")
+@click.option("--codex", "codex", is_flag=True, default=False,
+              help="Configure Codex CLI telemetry to flow into tj")
+@click.option("--budget", type=float, default=None,
+              help="Daily budget in USD per agent (0 = no limit)")
+@click.option("--install-daemon", "install_daemon", is_flag=True, default=False,
+              help="(no-op: daemon is installed by default; use --no-daemon to skip)")
+@click.option("--no-daemon", is_flag=True, default=False,
+              help="Skip background daemon installation")
+@click.option("--force", is_flag=True, help="Overwrite existing config")
+@click.pass_context
+def cmd_onboard(ctx: click.Context, claude_code: bool, codex: bool, budget: float | None,
+                install_daemon: bool, no_daemon: bool, force: bool) -> None:
+    """Interactive setup wizard for tj."""
+    if claude_code:
+        _onboard_claude_code(ctx, budget, no_daemon, force)
+        return
+    if codex:
+        _onboard_codex(ctx, budget, no_daemon, force)
+        return
+    existing = find_config_file()
+    if existing and not force:
+        console.print(f"[bold]Config already exists:[/bold] {existing}")
+        console.print("Use [bold]--force[/bold] to overwrite.")
+        return
+
+    console.print()
+    console.print("[bold]Setting up TokenJam...[/bold]")
+    console.print()
+
+    if budget is None:
+        budget = click.prompt(
+            "Daily budget in USD per agent (0 = no limit, default 0)",
+            type=float, default=0.0, show_default=False,
+        )
+
+    ingest_secret = secrets.token_hex(32)
+
+    want_daemon = not no_daemon
+
+    config_path = Path(".tj/config.toml")
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    budget_line = ""
+    if budget and budget > 0:
+        budget_line = f"daily_usd = {budget}"
+
+    config_text = f"""\
+# TokenJam configuration
+# Docs: https://github.com/Metabuilder-Labs/openclawwatch#configuration
+
+[defaults.budget]
+{budget_line}
+
+[security]
+ingest_secret = "{ingest_secret}"
+
+[capture]
+prompts = false
+completions = false
+tool_outputs = false
+
+[storage]
+path = "~/.tj/telemetry.duckdb"
+retention_days = 90
+
+# Per-agent overrides (optional):
+# [agents.my-agent]
+# description = "My email agent"
+#   [agents.my-agent.budget]
+#   daily_usd = 5.00
+#   session_usd = 1.00
+#   [[agents.my-agent.sensitive_actions]]
+#   name = "send_email"
+#   severity = "critical"
+"""
+    config_path.write_text(config_text)
+
+    daemon_msg = None
+    if want_daemon:
+        daemon_msg = _install_daemon(str(config_path.resolve()))
+
+    # Output
+    console.print()
+    console.print("[green]\u2713[/green] Config written to [bold].tj/config.toml[/bold]")
+    console.print(f"[green]\u2713[/green] Ingest secret generated: "
+                  f"[dim]{ingest_secret[:8]}...[/dim]")
+    if budget and budget > 0:
+        console.print(f"[green]\u2713[/green] Default daily budget: "
+                      f"[bold]${budget:.2f}[/bold] per agent")
+    if daemon_msg:
+        console.print(f"[green]\u2713[/green] {daemon_msg}")
+
+    console.print()
+    console.print("[bold]Next steps:[/bold]")
+    console.print()
+    console.print("  1. Instrument your agent:")
+    console.print()
+    console.print("[dim]     from tokenjam.sdk import watch[/dim]")
+    console.print("[dim]     from tokenjam.sdk.integrations.anthropic import patch_anthropic[/dim]")
+    console.print()
+    console.print("[dim]     patch_anthropic()[/dim]")
+    console.print()
+    console.print('[dim]     @watch(agent_id="my-agent")[/dim]')
+    console.print("[dim]     def run(task):[/dim]")
+    console.print("[dim]         ...[/dim]")
+    console.print()
+    console.print("  2. Run your agent \u2014 spans are recorded automatically")
+    console.print()
+    console.print("  3. View telemetry:")
+    console.print("[dim]     tj status          [/dim]# agent overview")
+    console.print("[dim]     tj traces          [/dim]# span history")
+    console.print("[dim]     tj serve           [/dim]# web UI at http://127.0.0.1:7391/")
+    console.print()
+
+    if not want_daemon:
+        console.print("  Run [bold]tj serve[/bold] to start the web UI "
+                      "and enable real-time alerts.")
+        console.print()
+
+    console.print(
+        "  To configure per-agent budgets, sensitive actions, or drift detection:"
+    )
+    console.print(
+        "  Edit [bold].tj/config.toml[/bold] \u2014 see "
+        "[dim]https://github.com/Metabuilder-Labs/openclawwatch#configuration[/dim]"
+    )
+    console.print()
+
+
+def _onboard_claude_code(
+    ctx: click.Context,
+    budget: float | None,
+    no_daemon: bool,
+    force: bool,
+) -> None:
+    """Configure Claude Code to send telemetry to tj."""
+    from tokenjam.core.config import (
+        AgentConfig, BudgetConfig, TjConfig, SecurityConfig, load_config, write_config,
+    )
+
+    # --claude-code always uses the global config so that all projects share one
+    # ingest secret and one running daemon. Per-project configs cause the secret in
+    # ~/.claude/settings.json to rotate on every project onboard, breaking auth for
+    # every other project.
+    global_config_path = Path.home() / ".config" / "tj" / "config.toml"
+
+    project_name = _derive_project_name()
+    agent_id = f"claude-code-{project_name}"
+
+    if budget is None:
+        budget = click.prompt(
+            "Daily budget in USD (0 = no limit, default 0)",
+            type=float, default=0.0, show_default=False,
+        )
+
+    if global_config_path.exists() and not force:
+        config = load_config(str(global_config_path))
+        if agent_id not in config.agents:
+            config.agents[agent_id] = AgentConfig()
+        if budget and budget > 0:
+            config.agents[agent_id].budget.daily_usd = budget
+        config_path = global_config_path
+        write_config(config, config_path)
+        console.print(f"  tj config updated: {config_path}")
+    else:
+        ingest_secret = secrets.token_hex(32)
+        daily_usd = budget if budget and budget > 0 else None
+        agents = {agent_id: AgentConfig(budget=BudgetConfig(daily_usd=daily_usd))}
+        config = TjConfig(
+            version="1",
+            agents=agents,
+            security=SecurityConfig(ingest_secret=ingest_secret),
+        )
+        config_path = global_config_path
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        write_config(config, config_path)
+        console.print(f"  tj config written to: {config_path}")
+        if _sync_secret_to_codex(ingest_secret):
+            console.print("  Codex config updated to match new ingest secret.")
+
+    # --- Register MCP server with Claude Code ---
+    if shutil.which("claude"):
+        subprocess.run(
+            ["claude", "mcp", "add", "tj", "--scope", "user", "--", "tj", "mcp"],
+            capture_output=True,
+        )
+
+    # --- Global settings (~/.claude/settings.json) ---
+    claude_dir = Path.home() / ".claude"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+    global_settings_path = claude_dir / "settings.json"
+
+    global_settings: dict = {}
+    if global_settings_path.exists():
+        try:
+            global_settings = json_mod.loads(global_settings_path.read_text())
+        except (json_mod.JSONDecodeError, OSError):
+            global_settings = {}
+
+    # Write global OTLP config — always overwrite endpoint vars so reinstall stays in sync.
+    # Custom headers (non-OCW) are preserved; only OCW-generated "Authorization=Bearer"
+    # headers are replaced when the secret rotates.
+    port = config.api.port
+    secret = config.security.ingest_secret
+    global_env: dict = global_settings.get("env", {})
+    global_env["CLAUDE_CODE_ENABLE_TELEMETRY"] = "1"
+    global_env["OTEL_LOGS_EXPORTER"] = "otlp"
+    global_env["OTEL_EXPORTER_OTLP_PROTOCOL"] = "http/json"
+    global_env["OTEL_EXPORTER_OTLP_ENDPOINT"] = f"http://127.0.0.1:{port}"
+    existing_header = global_env.get("OTEL_EXPORTER_OTLP_HEADERS", "")
+    if secret and (not existing_header or "Authorization=Bearer" in existing_header):
+        global_env["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {secret}"
+    global_settings["env"] = global_env
+    global_settings_path.write_text(json_mod.dumps(global_settings, indent=2) + "\n")
+
+    # --- Project settings (<cwd>/.claude/settings.json) ---
+    project_claude_dir = Path.cwd() / ".claude"
+    project_claude_dir.mkdir(parents=True, exist_ok=True)
+    project_settings_path = project_claude_dir / "settings.json"
+
+    project_settings: dict = {}
+    if project_settings_path.exists():
+        try:
+            project_settings = json_mod.loads(project_settings_path.read_text())
+        except (json_mod.JSONDecodeError, OSError):
+            project_settings = {}
+
+    project_env: dict = project_settings.get("env", {})
+    project_env["OTEL_RESOURCE_ATTRIBUTES"] = f"service.name={agent_id}"
+    project_settings["env"] = project_env
+    project_settings_path.write_text(json_mod.dumps(project_settings, indent=2) + "\n")
+
+    # --- Track onboarded project paths for clean uninstall ---
+    projects_index = config_path.parent / "projects.json"
+    try:
+        known: list[str] = json_mod.loads(projects_index.read_text()) if projects_index.exists() else []
+    except (json_mod.JSONDecodeError, OSError):
+        known = []
+    cwd_str = str(Path.cwd())
+    if cwd_str not in known:
+        known.append(cwd_str)
+        projects_index.write_text(json_mod.dumps(known, indent=2) + "\n")
+
+    # --- Shell env (~/.zshrc) ---
+    # Writes host.docker.internal endpoint so harness sessions (Docker) pick up
+    # the vars automatically via compose.yml passthrough — no manual setup needed.
+    # Native Claude Code uses settings.json (127.0.0.1) written above instead.
+    zshrc = Path.home() / ".zshrc"
+    zshrc.touch(exist_ok=True)
+    marker = "# tj harness observability"
+    zshrc_text = zshrc.read_text()
+    new_block = (
+        f"\n{marker}\n"
+        f"export CLAUDE_CODE_ENABLE_TELEMETRY=1\n"
+        f"export OTEL_LOGS_EXPORTER=otlp\n"
+        f"export OTEL_EXPORTER_OTLP_PROTOCOL=http/json\n"
+        f"export OTEL_EXPORTER_OTLP_ENDPOINT=http://host.docker.internal:{port}\n"
+        f'export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer {secret}"\n'
+    )
+    if marker not in zshrc_text:
+        with zshrc.open("a") as f:
+            f.write(new_block)
+    else:
+        # Marker already present — replace the entire block to keep the secret in sync.
+        import re as _re
+        updated = _re.sub(
+            r"# tj harness observability\n(?:export [^\n]+\n)*",
+            new_block.lstrip("\n"),
+            zshrc_text,
+        )
+        zshrc.write_text(updated)
+
+    want_daemon = not no_daemon
+    if want_daemon:
+        if not force and _daemon_already_running():
+            console.print("  Daemon:              already running (skipped reinstall)")
+        else:
+            console.print("  Daemon:              installing...")
+            _install_daemon(str(config_path.resolve()))
+
+    console.print()
+    console.print("[bold green]Claude Code observability configured.[/bold green]")
+    console.print(f"  Global settings:     {global_settings_path}")
+    console.print(f"  Project settings:    {project_settings_path}")
+    console.print("  Shell env:           ~/.zshrc (harness-compatible endpoint)")
+    console.print(f"  Agent ID:            {agent_id}")
+    if budget and budget > 0:
+        console.print(f"  Daily budget:        ${budget:.2f}")
+    console.print(f"  OTLP endpoint:       http://127.0.0.1:{port} (native)")
+    console.print(f"                       http://host.docker.internal:{port} (harness)")
+    if secret:
+        console.print(f"  Ingest secret:       {secret[:8]}...")
+    console.print()
+    if not want_daemon:
+        console.print("[dim]Start the server:[/dim]  tj serve")
+    console.print("[dim]Restart Claude Code for settings to take effect.[/dim]")
+    console.print(f"[dim]Then run:[/dim]  tj status --agent {agent_id}")
+
+
+def _onboard_codex(
+    ctx: click.Context,
+    budget: float | None,
+    no_daemon: bool,
+    force: bool,
+) -> None:
+    """Configure Codex CLI to send telemetry to tj."""
+    try:
+        import tomllib  # type: ignore[import]
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    from tokenjam.core.config import (
+        AgentConfig, BudgetConfig, TjConfig, SecurityConfig,
+        load_config, write_config,
+    )
+
+    # Codex hardcodes service.name="codex_exec" in its binary regardless of
+    # what [otel.resource] says, so all Codex traces land under "codex_exec".
+    agent_id = "codex_exec"
+
+    if budget is None:
+        budget = click.prompt(
+            "Daily budget in USD (0 = no limit, default 0)",
+            type=float, default=0.0, show_default=False,
+        )
+
+    # `--codex` always writes to the global config, mirroring `--claude-code`.
+    # Codex's own config (~/.codex/config.toml) is global and the agent_id
+    # `codex_exec` is project-agnostic by design (Codex hardcodes service.name
+    # in its binary). Per-project OCW configs would rotate the secret on every
+    # onboard, breaking the running server.
+    config_path = Path.home() / ".config" / "tj" / "config.toml"
+
+    previous_secret: str | None = None
+    if config_path.exists():
+        try:
+            prev_cfg = load_config(str(config_path))
+            previous_secret = prev_cfg.security.ingest_secret
+        except Exception:
+            previous_secret = None
+
+    if config_path.exists():
+        config = load_config(str(config_path))
+        if agent_id not in config.agents:
+            config.agents[agent_id] = AgentConfig()
+        if budget and budget > 0:
+            config.agents[agent_id].budget.daily_usd = budget
+        write_config(config, config_path)
+        console.print(f"  tj config updated: {config_path}")
+    else:
+        ingest_secret = secrets.token_hex(32)
+        daily_usd = budget if budget and budget > 0 else None
+        agents = {agent_id: AgentConfig(budget=BudgetConfig(daily_usd=daily_usd))}
+        config = TjConfig(
+            version="1",
+            agents=agents,
+            security=SecurityConfig(ingest_secret=ingest_secret),
+        )
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        write_config(config, config_path)
+        console.print(f"  tj config written to: {config_path}")
+        if _sync_secret_to_claude_code(ingest_secret):
+            console.print("  Claude Code config updated to match new ingest secret.")
+
+    port = config.api.port
+    secret = config.security.ingest_secret
+    secret_rotated = bool(previous_secret) and previous_secret != secret
+
+    # --- Write Codex CLI OTel config (~/.codex/config.toml) ---
+    codex_config_path = Path.home() / ".codex" / "config.toml"
+    codex_config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing_content = codex_config_path.read_text() if codex_config_path.exists() else ""
+
+    # Check whether an [otel] section already exists
+    existing_codex: dict = {}
+    if existing_content:
+        try:
+            existing_codex = tomllib.loads(existing_content)
+        except Exception:
+            pass
+
+    already_has_otel = "otel" in existing_codex
+    already_has_mcp = bool(existing_codex.get("mcp_servers", {}).get("tj"))
+    if already_has_otel and already_has_mcp and not force:
+        # Use plain print() for messages containing TOML section headers like
+        # [otel] — Rich treats square brackets as markup tags and would strip
+        # them, leaving the message unintelligible ("already has  and ").
+        click.echo(
+            "~/.codex/config.toml already has [otel] and [mcp_servers.tj] sections."
+        )
+        click.echo("Use --force to overwrite, or add manually:")
+        click.echo("")
+        _print_codex_otel_block(port, secret, agent_id)
+        return
+
+    otel_block = _codex_otel_toml_block(port, secret, agent_id)
+    mcp_block = _codex_mcp_toml_block()
+
+    # Build the new file content by replacing/appending each managed section.
+    base_content = existing_content
+    if force:
+        # Fully wipe previous OTEL sections so nested tables don't duplicate.
+        base_content = _codex_strip_otel_sections(base_content)
+    new_content = _codex_apply_block(
+        base_content, r"\[otel\]", already_has_otel, otel_block, force,
+    )
+    # Re-parse after the otel update so section detection is accurate.
+    try:
+        existing_after_otel = tomllib.loads(new_content)
+    except Exception:
+        existing_after_otel = existing_codex
+    existing_mcp = existing_after_otel.get("mcp_servers", {}).get("tj")
+    new_content = _codex_apply_block(
+        new_content,
+        r"\[mcp_servers\.tj\]",
+        bool(existing_mcp),
+        mcp_block,
+        force,
+    )
+    codex_config_path.write_text(new_content)
+
+    # --- Try registering via the Codex CLI as well (best-effort) ---
+    if shutil.which("codex"):
+        subprocess.run(
+            ["codex", "mcp", "add", "tj", "--", "tj", "mcp"],
+            capture_output=True,
+        )
+
+    # --- If ingest secret rotated, restart running server first ---
+    restart_msg: str | None = None
+    if secret_rotated:
+        restart_msg = _restart_tj_server_for_secret_rotation(
+            str(config_path.resolve()), no_daemon=no_daemon
+        )
+
+    # --- Install daemon if requested ---
+    want_daemon = not no_daemon
+    if want_daemon and not secret_rotated:
+        console.print("  Daemon:              auto-installing (use --no-daemon to skip)")
+        _install_daemon(str(config_path.resolve()))
+
+    console.print()
+    console.print("[bold green]Codex CLI observability configured.[/bold green]")
+    console.print(f"  Codex config:        {codex_config_path}")
+    console.print(f"  OCW config:          {config_path}")
+    if budget and budget > 0:
+        console.print(f"  Daily budget:        ${budget:.2f}")
+    console.print(f"  OTLP endpoint:       http://127.0.0.1:{port}/v1/logs")
+    if secret:
+        console.print(f"  Ingest secret:       {secret[:8]}...")
+    console.print("  MCP server:          tj mcp (registered in Codex config)")
+    if restart_msg:
+        console.print(f"  Server restart:      {restart_msg}")
+    console.print()
+    if not want_daemon:
+        console.print("[dim]Start the server:[/dim]  tj serve")
+    console.print(
+        "[dim]Codex can now call OCW tools (open_dashboard, get_status, etc.) directly.[/dim]"
+    )
+    console.print("[dim]Then run:[/dim]  tj traces")
+
+
+def _restart_tj_server_for_secret_rotation(config_path: str, no_daemon: bool) -> str:
+    """Restart running tj serve to pick up a rotated ingest secret.
+
+    We stop first to ensure any manually-started server process with stale config
+    is terminated, then (when daemon mode is enabled) start it again.
+    """
+    stopped = False
+    try:
+        # Best-effort: stop launchd/systemd daemon or background serve process.
+        stop_result = subprocess.run(
+            ["tj", "stop"], capture_output=True, text=True, timeout=10
+        )
+        stopped = stop_result.returncode == 0
+    except Exception:
+        stopped = False
+
+    if no_daemon:
+        if stopped:
+            return "stopped stale server; run `tj serve` to start with new secret"
+        return "could not auto-restart in --no-daemon mode; run `tj serve` manually"
+
+    daemon_msg = _install_daemon(config_path)
+    if daemon_msg:
+        return "restarted to pick up new ingest secret"
+    if stopped:
+        return "stopped stale server; please run `tj serve` manually"
+    return "restart attempted; verify with `tj status`"
+
+
+def _codex_mcp_toml_block() -> str:
+    """Return the [mcp_servers.tj] TOML block for ~/.codex/config.toml."""
+    return (
+        "[mcp_servers.tj]\n"
+        "# Managed by tj — gives Codex access to OCW observability tools\n"
+        'command = "tj"\n'
+        'args = ["mcp"]\n'
+    )
+
+
+def _codex_apply_block(
+    content: str,
+    section_pattern: str,
+    section_exists: bool,
+    block: str,
+    force: bool,
+) -> str:
+    """Replace or append a TOML section identified by *section_pattern* (regex).
+
+    If the section is absent, the block is appended.
+    If the section exists and *force* is True, it is replaced.
+    If the section exists and *force* is False, the content is unchanged.
+    """
+    import re as _re
+
+    if section_exists:
+        if not force:
+            return content
+        # Replace from the section header to the next section header or EOF.
+        stripped = _re.sub(
+            section_pattern + r".*?(?=\n\[|\Z)",
+            "",
+            content,
+            flags=_re.DOTALL,
+        ).rstrip()
+        return (stripped + "\n\n" + block) if stripped else block
+    # Section absent — append.
+    return (content.rstrip() + "\n\n" + block) if content.strip() else block
+
+
+def _codex_strip_otel_sections(content: str) -> str:
+    """Remove all [otel] sections (including nested exporter/resource tables)."""
+    import re as _re
+
+    patterns = (
+        r"\[otel\].*?(?=\n\[|\Z)",
+        r"\[otel\.resource\].*?(?=\n\[|\Z)",
+        r"\[otel\.exporter\.\"otlp-http\"\].*?(?=\n\[|\Z)",
+        r"\[otel\.exporter\.\"otlp-http\"\.headers\].*?(?=\n\[|\Z)",
+        r"\[otel\.exporter\.\"otlp-grpc\"\].*?(?=\n\[|\Z)",
+        r"\[otel\.exporter\.\"otlp-grpc\"\.headers\].*?(?=\n\[|\Z)",
+    )
+    stripped = content
+    for pat in patterns:
+        stripped = _re.sub(pat, "", stripped, flags=_re.DOTALL)
+    return stripped.strip()
+
+
+def _codex_otel_toml_block(port: int, secret: str, agent_id: str) -> str:
+    """Return the [otel] TOML block to append to ~/.codex/config.toml."""
+    endpoint = f"http://127.0.0.1:{port}/v1/logs"
+    # Note: Codex CLI hardcodes service.name="codex_exec" in the binary and
+    # ignores [otel.resource] entirely, so we don't write a resource block.
+    return (
+        f'[otel]\n'
+        f'# Managed by tj — do not edit this block manually\n'
+        f'log_user_prompt = false\n'
+        f'\n'
+        f'[otel.exporter."otlp-http"]\n'
+        f'endpoint = "{endpoint}"\n'
+        f'protocol = "json"\n'
+        f'\n'
+        f'[otel.exporter."otlp-http".headers]\n'
+        f'Authorization = "Bearer {secret}"\n'
+    )
+
+
+def _print_codex_otel_block(port: int, secret: str, agent_id: str = "codex_exec") -> None:
+    # Plain print — the TOML block contains [otel] and other section headers
+    # that Rich would interpret as markup tags and strip from the output.
+    click.echo("Add this to ~/.codex/config.toml:")
+    click.echo("")
+    block = _codex_otel_toml_block(port, secret, agent_id)
+    for line in block.splitlines():
+        click.echo(f"  {line}")
+    click.echo("")
+
+
+def _sync_secret_to_codex(secret: str) -> bool:
+    """Update Authorization header in ~/.codex/config.toml if an [otel] section exists."""
+    import re as _re
+    codex_path = Path.home() / ".codex" / "config.toml"
+    if not codex_path.exists():
+        return False
+    content = codex_path.read_text()
+    if "Authorization" not in content:
+        return False
+    updated = _re.sub(
+        r'(Authorization\s*=\s*"Bearer\s+)[^"]+(")',
+        rf'\g<1>{secret}\g<2>',
+        content,
+    )
+    if updated == content:
+        return False
+    codex_path.write_text(updated)
+    return True
+
+
+def _sync_secret_to_claude_code(secret: str) -> bool:
+    """Update OTLP Authorization header in ~/.claude/settings.json if present."""
+    settings_path = Path.home() / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return False
+    try:
+        settings = json_mod.loads(settings_path.read_text())
+    except (json_mod.JSONDecodeError, OSError):
+        return False
+    env = settings.get("env", {})
+    if "Authorization=Bearer" not in env.get("OTEL_EXPORTER_OTLP_HEADERS", ""):
+        return False
+    env["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Bearer {secret}"
+    settings["env"] = env
+    settings_path.write_text(json_mod.dumps(settings, indent=2) + "\n")
+    return True
+
+
+def _derive_project_name() -> str:
+    """
+    Derive a meaningful project name for the agent ID.
+    Priority: git remote origin repo name > current folder name.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, timeout=3,
+        )
+        if result.returncode == 0:
+            url = result.stdout.strip()
+            # Extract repo name from URL — handles both https and ssh forms
+            # e.g. https://github.com/org/my-repo.git  -> my-repo
+            #      git@github.com:org/my-repo.git       -> my-repo
+            name = url.rstrip("/").split("/")[-1].split(":")[-1]
+            name = name.removesuffix(".git").lower()
+            if name:
+                return name
+    except Exception:
+        pass
+    return Path.cwd().name.lower()
+
+
+def _daemon_already_running() -> bool:
+    """Check if the OCW daemon is already installed and loaded."""
+    system = platform.system()
+    if system == "Darwin":
+        plist = Path.home() / "Library/LaunchAgents/com.tokenjam.serve.plist"
+        if not plist.exists():
+            return False
+        result = subprocess.run(
+            ["launchctl", "list", "com.tokenjam.serve"],
+            capture_output=True, text=True,
+        )
+        return result.returncode == 0
+    elif system == "Linux":
+        result = subprocess.run(
+            ["systemctl", "--user", "is-active", "tokenjam"],
+            capture_output=True, text=True,
+        )
+        return result.stdout.strip() == "active"
+    return False
+
+
+def _install_daemon(config_path: str) -> str | None:
+    """Install background daemon. Returns success message or None."""
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            return _install_launchd(config_path)
+        elif system == "Linux":
+            return _install_systemd(config_path)
+        else:
+            console.print(f"[yellow]Background daemon not supported on {system}. "
+                          "Run `tj serve` manually.[/yellow]")
+            return None
+    except Exception as e:
+        console.print(f"[yellow]Daemon installation failed: {e}[/yellow]")
+        console.print("[dim]You can run `tj serve` manually instead.[/dim]")
+        return None
+
+
+def _install_launchd(config_path: str) -> str | None:
+    tj_path = shutil.which("tj") or sys.executable.replace("/python", "/tj").replace("/python3", "/tj")
+    plist_path = Path.home() / "Library/LaunchAgents/com.tokenjam.serve.plist"
+    plist_path.parent.mkdir(parents=True, exist_ok=True)
+    plist_content = f"""\
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.tokenjam.serve</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{tj_path}</string>
+        <string>--config</string>
+        <string>{config_path}</string>
+        <string>serve</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardErrorPath</key>
+    <string>/tmp/tj-serve.err</string>
+    <key>StandardOutPath</key>
+    <string>/tmp/tj-serve.out</string>
+</dict>
+</plist>"""
+    plist_path.write_text(plist_content)
+    # Unload any existing registration before loading the updated plist.
+    # Ignore errors — the service may not be registered yet on first install.
+    subprocess.run(
+        ["launchctl", "unload", "-w", str(plist_path)],
+        capture_output=True, text=True,
+    )
+    # `-w` clears the Disabled=true flag that `tj stop` writes via
+    # `launchctl unload -w`. Without `-w` here, the daemon stays disabled
+    # in launchd's database and load is a no-op even though it returns 0.
+    result = subprocess.run(
+        ["launchctl", "load", "-w", str(plist_path)],
+        capture_output=True, text=True,
+    )
+    if result.returncode != 0:
+        console.print(f"[yellow]Daemon plist written to {plist_path} but "
+                      f"launchctl load failed.[/yellow]")
+        console.print("[dim]Try loading manually:[/dim]")
+        console.print(f"  launchctl load {plist_path}")
+        console.print("[dim]Or run the server directly:[/dim]")
+        console.print("  tj serve &")
+        return None
+    console.print(
+        "  [dim]macOS will show a 'Background Items Added' notification "
+        "-- this is normal.[/dim]"
+    )
+    return f"Daemon installed at {plist_path}"
+
+
+def _install_systemd(config_path: str) -> str | None:
+    tj_path = shutil.which("tj") or sys.executable.replace("/python", "/tj").replace("/python3", "/tj")
+    service_path = Path.home() / ".config/systemd/user/tokenjam.service"
+    service_path.parent.mkdir(parents=True, exist_ok=True)
+    service_content = f"""\
+[Unit]
+Description=TokenJam observability server
+After=network.target
+
+[Service]
+ExecStart={tj_path} --config {config_path} serve
+Restart=on-failure
+
+[Install]
+WantedBy=default.target"""
+    service_path.write_text(service_content)
+    subprocess.run(
+        ["systemctl", "--user", "enable", "--now", "tokenjam"],
+        check=True,
+    )
+    return f"Daemon installed at {service_path}"