tokenjam 0.2.0__py3-none-any.whl

tokenjam/cli/cmd_serve.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import click
+from pathlib import Path
+
+from tokenjam.utils.formatting import console
+
+
+@click.command("serve")
+@click.option("--host", default=None, help="Bind host (default: from config)")
+@click.option("--port", default=None, type=int, help="Bind port (default: from config)")
+@click.option("--reload", is_flag=True, help="Enable auto-reload for development")
+@click.pass_context
+def cmd_serve(ctx: click.Context, host: str | None, port: int | None,
+              reload: bool) -> None:
+    """Start the tj API server."""
+    config = ctx.obj["config"]
+    bind_host = host or config.api.host
+    bind_port = port or config.api.port
+
+    import uvicorn
+    from tokenjam.api.app import create_app
+    from tokenjam.core.ingest import build_default_pipeline
+
+    db = ctx.obj["db"]
+    pipeline = build_default_pipeline(db, config)
+    app = create_app(config, db, pipeline)
+
+    # Schedule retention cleanup using a separate DB connection per run
+    # to avoid concurrent write conflicts with uvicorn worker threads.
+    from apscheduler.schedulers.background import BackgroundScheduler
+    from tokenjam.core.retention import run_retention_cleanup
+    from tokenjam.core.db import DuckDBBackend
+
+    def _retention_job() -> None:
+        retention_db = DuckDBBackend(config.storage)
+        try:
+            run_retention_cleanup(retention_db, config.storage)
+        finally:
+            retention_db.close()
+
+    scheduler = BackgroundScheduler()
+    scheduler.add_job(
+        _retention_job,
+        "cron",
+        hour=0,
+        minute=0,
+    )
+    scheduler.start()
+
+    @app.on_event("shutdown")
+    async def _shutdown_scheduler() -> None:
+        scheduler.shutdown(wait=False)
+
+    # Write the resolved config path so other subcommands (e.g. onboard --codex)
+    # can find the secret this server is using regardless of CWD. Defer the
+    # write to a FastAPI startup event so it only fires after uvicorn binds
+    # the port — otherwise a failed-to-bind serve clobbers the state file
+    # of the running daemon (D2).
+    import json as _json
+    _state_path = Path.home() / ".local" / "share" / "tj" / "server.state"
+
+    @app.on_event("startup")
+    async def _write_server_state() -> None:
+        _state_path.parent.mkdir(parents=True, exist_ok=True)
+        _state_path.write_text(
+            _json.dumps({
+                "config_path": str(config.config_path) if config.config_path else None,
+                "port": bind_port,
+                "pid": __import__("os").getpid(),
+            })
+        )
+
+    console.print(f"[bold]tj serve[/bold] starting on http://{bind_host}:{bind_port}")
+    console.print(f"  API docs:    http://{bind_host}:{bind_port}/docs")
+    if config.export.prometheus.enabled:
+        console.print(f"  Metrics:     http://{bind_host}:{bind_port}/metrics")
+    console.print()
+
+    if reload:
+        console.print(
+            "[yellow]Warning: --reload requires an import string, not an app instance. "
+            "Reload mode is not supported with injected db/config — ignoring --reload.[/yellow]"
+        )
+    uvicorn.run(app, host=bind_host, port=bind_port)

tokenjam/cli/cmd_status.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+from tokenjam.core.models import AlertFilters
+from tokenjam.utils.formatting import console, format_cost, format_tokens, status_icon
+from tokenjam.utils.time_parse import utcnow
+
+
+@click.command("status")
+@click.option("--agent", default=None, help="Filter to specific agent_id")
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def cmd_status(ctx: click.Context, agent: str | None, output_json: bool) -> None:
+    """Show agent status overview."""
+    db = ctx.obj["db"]
+    agent_filter = agent or ctx.obj.get("agent")
+
+    # Get all agents from recent sessions
+    if agent_filter:
+        agent_ids = [agent_filter]
+    elif hasattr(db, "conn"):
+        # Direct DB access
+        rows = db.conn.execute(
+            "SELECT DISTINCT agent_id FROM sessions WHERE agent_id IS NOT NULL ORDER BY agent_id"
+        ).fetchall()
+        agent_ids = [r[0] for r in rows]
+    else:
+        # API mode — discover agents from recent traces
+        from tokenjam.core.models import TraceFilters
+        traces = db.get_traces(TraceFilters(limit=100))
+        agent_ids = sorted({t.agent_id for t in traces if t.agent_id})
+
+    if not agent_ids:
+        if output_json:
+            click.echo(json.dumps({"agents": [], "has_active_alerts": False}))
+        else:
+            console.print("[dim]No agents found. Run an instrumented agent first.[/dim]")
+        return
+
+    has_active_alerts = False
+    agents_data = []
+
+    for aid in agent_ids:
+        session = None
+        if hasattr(db, "conn"):
+            # Direct DB access
+            sessions = db.get_completed_sessions(aid, limit=1)
+            active_rows = db.conn.execute(
+                "SELECT * FROM sessions WHERE agent_id = $1 AND status = 'active' "
+                "ORDER BY started_at DESC LIMIT 1",
+                [aid],
+            ).fetchall()
+            if active_rows:
+                cols = [d[0] for d in db.conn.description]
+                from tokenjam.core.db import _row_to_session
+                session = _row_to_session(active_rows[0], cols)
+            elif sessions:
+                session = sessions[0]
+        else:
+            # API mode — limited session info
+            sessions = db.get_completed_sessions(aid, limit=1)
+            if sessions:
+                session = sessions[0]
+
+        today_cost = db.get_daily_cost(aid, utcnow().date())
+
+        # Budget from config: per-agent overrides defaults
+        config = ctx.obj["config"]
+        agent_config = config.agents.get(aid)
+        if agent_config and agent_config.budget.daily_usd is not None:
+            daily_limit = agent_config.budget.daily_usd
+        elif hasattr(config, "defaults") and config.defaults.budget.daily_usd is not None:
+            daily_limit = config.defaults.budget.daily_usd
+        else:
+            daily_limit = None
+
+        # Active alerts
+        alerts = db.get_alerts(AlertFilters(agent_id=aid, unread=True, limit=50))
+        active_alerts = [a for a in alerts if not a.acknowledged and not a.suppressed]
+        if active_alerts:
+            has_active_alerts = True
+
+        agent_data = {
+            "agent_id": aid,
+            "status": session.status if session else "idle",
+            "session_id": session.session_id if session else None,
+            "cost_today": today_cost,
+            "daily_limit": daily_limit,
+            "input_tokens": session.input_tokens if session else 0,
+            "output_tokens": session.output_tokens if session else 0,
+            "tool_call_count": session.tool_call_count if session else 0,
+            "error_count": session.error_count if session else 0,
+            "active_alerts": len(active_alerts),
+        }
+        agents_data.append(agent_data)
+
+        if not output_json:
+            _print_agent_status(agent_data, active_alerts, session)
+
+    if output_json:
+        click.echo(json.dumps({
+            "agents": agents_data,
+            "has_active_alerts": has_active_alerts,
+        }, default=str))
+
+    ctx.exit(1 if has_active_alerts else 0)
+
+
+def _print_agent_status(data: dict, active_alerts: list, session: object | None) -> None:
+    status = data["status"]
+    icon = status_icon(status)
+    style = "green" if status == "active" else "dim"
+
+    duration_str = ""
+    if session and hasattr(session, "duration_seconds") and session.duration_seconds:
+        secs = int(session.duration_seconds)
+        mins, s = divmod(secs, 60)
+        duration_str = f"   ({mins}m {s}s)"
+
+    console.print(f"[{style}]{icon}[/] [bold]{data['agent_id']}[/bold]   "
+                  f"{status}{duration_str}")
+    console.print()
+
+    cost_str = format_cost(data["cost_today"])
+    if data["daily_limit"]:
+        cost_str += f" / {format_cost(data['daily_limit'])} limit"
+    console.print(f"  Cost today:     {cost_str}")
+
+    in_tok = format_tokens(data["input_tokens"])
+    out_tok = format_tokens(data["output_tokens"])
+    console.print(f"  Tokens:         {in_tok} in / {out_tok} out")
+
+    tool_str = str(data["tool_call_count"])
+    if data["error_count"]:
+        tool_str += f"  ({data['error_count']} failed)"
+    console.print(f"  Tool calls:     {tool_str}")
+
+    if data["session_id"]:
+        console.print(f"  Active session: {data['session_id']}")
+
+    console.print()
+    for alert in active_alerts:
+        from tokenjam.utils.formatting import severity_colour
+        colour = severity_colour(alert.severity.value)
+        console.print(f"  [{colour}]{alert.title}[/]")
+
+    if not active_alerts:
+        console.print("  [green]No active alerts[/green]")
+
+    console.print()

tokenjam/cli/cmd_stop.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+from pathlib import Path
+
+import click
+
+from tokenjam.utils.formatting import console
+
+
+@click.command("stop")
+@click.pass_context
+def cmd_stop(ctx: click.Context) -> None:
+    """Stop the tj serve daemon or background process."""
+    plist_path = Path.home() / "Library/LaunchAgents/com.tokenjam.serve.plist"
+    systemd_path = Path.home() / ".config/systemd/user/tokenjam.service"
+
+    stopped_via: list[str] = []
+
+    # Try launchd first (macOS).
+    # -w writes a Disabled entry to launchd's database so the daemon does not
+    # auto-start on the next login (the plist file stays on disk so the user
+    # can re-enable with `launchctl load <plist>` or by re-running tj serve).
+    if plist_path.exists():
+        result = subprocess.run(
+            ["launchctl", "unload", "-w", str(plist_path)],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            stopped_via.append("launchd daemon unloaded")
+
+    # Try systemd (Linux).
+    # `disable --now` stops the unit immediately AND removes it from the
+    # boot-time targets, so it does not auto-start on next login.
+    # The service file stays on disk; `systemctl --user enable --now tokenjam`
+    # re-enables it.
+    if systemd_path.exists():
+        result = subprocess.run(
+            ["systemctl", "--user", "disable", "--now", "tokenjam"],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            stopped_via.append("systemd service stopped")
+
+    # Always sweep for orphan foreground `tj serve` processes started via
+    # `tj serve &` — launchd/systemd unload doesn't affect those, and they
+    # keep holding the port. Track signaled PIDs so a slow-shutting process
+    # doesn't get re-signaled (SIGTERM is async; pgrep can return the same
+    # PID before the handler fires, which would otherwise spin forever).
+    signaled: set[int] = set()
+    for _ in range(20):  # hard cap — well above any realistic straggler count
+        pid = _find_serve_pid()
+        if not pid or pid in signaled:
+            break
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            break
+        signaled.add(pid)
+        stopped_via.append(f"PID {pid}")
+
+    if stopped_via:
+        console.print(
+            f"[green]tj serve stopped.[/green] ({', '.join(stopped_via)})"
+        )
+    else:
+        console.print("[dim]tj serve is not running.[/dim]")
+
+
+def _find_serve_pid() -> int | None:
+    """Find the PID of a running `tj serve`. process."""
+    try:
+        result = subprocess.run(
+            ["pgrep", "-f", "tokenjam.serve|tj serve"],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            for line in result.stdout.strip().splitlines():
+                pid = int(line.strip())
+                # Don't return our own PID
+                if pid != os.getpid():
+                    return pid
+    except (FileNotFoundError, ValueError):
+        pass
+    return None

tokenjam/cli/cmd_tools.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+from tokenjam.utils.formatting import console, make_table
+from tokenjam.utils.time_parse import parse_since
+
+
+@click.command("tools")
+@click.option("--agent", default=None, help="Filter to specific agent_id")
+@click.option("--since", default="24h", help="Time window (e.g. 1h, 7d)")
+@click.option("--name", "tool_name", default=None, help="Filter to specific tool")
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def cmd_tools(ctx: click.Context, agent: str | None, since: str,
+              tool_name: str | None, output_json: bool) -> None:
+    """Show tool call summary."""
+    db = ctx.obj["db"]
+    agent_filter = agent or ctx.obj.get("agent")
+    since_dt = parse_since(since)
+
+    rows = db.get_tool_calls(agent_filter, since_dt, tool_name)
+
+    if output_json:
+        click.echo(json.dumps(rows, default=str))
+        return
+
+    if not rows:
+        console.print("[dim]No tool calls found for the given filters.[/dim]")
+        return
+
+    table = make_table("TOOL", "AGENT", "CALLS", "AVG DUR")
+    for r in rows:
+        call_count = r["call_count"]
+        total_dur = r["total_duration_ms"]
+        avg_dur = f"{total_dur / call_count:.0f}ms" if call_count > 0 else "-"
+        table.add_row(
+            r["tool_name"],
+            r.get("agent_id") or "-",
+            str(call_count),
+            avg_dur,
+        )
+    console.print(table)

tokenjam/cli/cmd_traces.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+from tokenjam.core.models import NormalizedSpan, TraceFilters
+from tokenjam.utils.formatting import console, format_cost, make_table
+from tokenjam.utils.time_parse import parse_since
+
+
+@click.command("traces")
+@click.option("--agent", default=None, help="Filter to specific agent_id")
+@click.option("--since", default="24h", help="Time window (e.g. 1h, 7d)")
+@click.option("--limit", default=50, type=int)
+@click.option("--type", "span_type", default=None, help="Filter by span name/type")
+@click.option("--status", default=None, type=click.Choice(["ok", "error"]))
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def cmd_traces(ctx: click.Context, agent: str | None, since: str, limit: int,
+               span_type: str | None, status: str | None, output_json: bool) -> None:
+    """List recent traces."""
+    db = ctx.obj["db"]
+    agent_filter = agent or ctx.obj.get("agent")
+    try:
+        since_dt = parse_since(since)
+    except ValueError as exc:
+        raise click.BadParameter(str(exc), param_hint="'--since'") from exc
+    filters = TraceFilters(
+        agent_id=agent_filter,
+        since=since_dt,
+        span_name=span_type,
+        status=status,
+        limit=limit,
+    )
+    traces = db.get_traces(filters)
+
+    if output_json:
+        click.echo(json.dumps([
+            {
+                "trace_id": t.trace_id,
+                "agent_id": t.agent_id,
+                "name": t.name,
+                "start_time": t.start_time.isoformat() if t.start_time else None,
+                "duration_ms": t.duration_ms,
+                "cost_usd": t.cost_usd,
+                "status_code": t.status_code,
+                "span_count": t.span_count,
+            }
+            for t in traces
+        ], default=str))
+        return
+
+    if not traces:
+        console.print("[dim]No traces found for the given filters.[/dim]")
+        return
+
+    table = make_table("TRACE ID", "AGENT", "TYPE", "DUR", "COST", "STATUS")
+    for t in traces:
+        dur = f"{t.duration_ms:.0f}ms" if t.duration_ms else "-"
+        cost = format_cost(t.cost_usd) if t.cost_usd else "-"
+        status_style = "red" if t.status_code == "error" else ""
+        table.add_row(
+            t.trace_id[:12] + "...",
+            t.agent_id or "-",
+            t.name,
+            dur,
+            cost,
+            f"[{status_style}]{t.status_code}[/]" if status_style else t.status_code,
+        )
+    console.print(table)
+
+
+@click.command("trace")
+@click.argument("trace_id")
+@click.option("--json", "output_json", is_flag=True)
+@click.pass_context
+def cmd_trace(ctx: click.Context, trace_id: str, output_json: bool) -> None:
+    """Show span waterfall for a single trace."""
+    db = ctx.obj["db"]
+    spans = db.get_trace_spans(trace_id)
+
+    # Support prefix matching (like git short hashes)
+    if not spans and len(trace_id) < 32:
+        if hasattr(db, "conn"):
+            rows = db.conn.execute(
+                "SELECT DISTINCT trace_id FROM spans WHERE trace_id LIKE $1 LIMIT 2",
+                [trace_id + "%"],
+            ).fetchall()
+            if len(rows) == 1:
+                trace_id = rows[0][0]
+                spans = db.get_trace_spans(trace_id)
+            elif len(rows) > 1:
+                console.print(f"[red]Ambiguous prefix '{trace_id}' — matches "
+                              f"{len(rows)} traces. Use more characters.[/red]")
+                return
+
+    if not spans:
+        console.print(f"[dim]No spans found for trace {trace_id}[/dim]")
+        return
+
+    if output_json:
+        click.echo(json.dumps([
+            {
+                "span_id": s.span_id,
+                "parent_span_id": s.parent_span_id,
+                "name": s.name,
+                "kind": s.kind.value,
+                "status_code": s.status_code.value,
+                "start_time": s.start_time.isoformat() if s.start_time else None,
+                "duration_ms": s.duration_ms,
+                "provider": s.provider,
+                "model": s.model,
+                "tool_name": s.tool_name,
+                "input_tokens": s.input_tokens,
+                "output_tokens": s.output_tokens,
+                "cost_usd": s.cost_usd,
+            }
+            for s in spans
+        ], default=str))
+        return
+
+    # Build parent->children map for tree rendering
+    children: dict[str | None, list[NormalizedSpan]] = {}
+    for s in spans:
+        children.setdefault(s.parent_span_id, []).append(s)
+
+    # Find root spans (no parent or parent not in this trace)
+    span_ids = {s.span_id for s in spans}
+    roots = [s for s in spans if s.parent_span_id is None
+             or s.parent_span_id not in span_ids]
+
+    for root in roots:
+        _print_span_tree(root, children, prefix="", is_last=True)
+
+
+def _print_span_tree(span: NormalizedSpan, children: dict[str | None, list[NormalizedSpan]],
+                     prefix: str, is_last: bool) -> None:
+    connector = "\u2514\u2500 " if is_last else "\u251c\u2500 "
+    dur = f"{span.duration_ms:.0f}ms" if span.duration_ms else ""
+    cost = format_cost(span.cost_usd) if span.cost_usd else ""
+
+    parts = [f"[bold]{span.name}[/bold]"]
+    if dur:
+        parts.append(f"[dim]{dur}[/dim]")
+    if span.model:
+        parts.append(f"[cyan]{span.model}[/cyan]")
+    if span.tool_name:
+        parts.append(f"[magenta]{span.tool_name}[/magenta]")
+    if cost:
+        parts.append(cost)
+    if span.status_code.value == "error":
+        parts.append("[red]ERROR[/red]")
+
+    line = " ".join(parts)
+    console.print(f"{prefix}{connector}{line}")
+
+    child_spans = children.get(span.span_id, [])
+    for i, child in enumerate(child_spans):
+        child_prefix = prefix + ("   " if is_last else "\u2502  ")
+        _print_span_tree(child, children, child_prefix, i == len(child_spans) - 1)

tokenjam/cli/cmd_uninstall.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+
+import click
+
+from tokenjam.utils.formatting import console
+
+
+@click.command("uninstall")
+@click.option("--yes", is_flag=True, help="Skip confirmation prompt")
+@click.pass_context
+def cmd_uninstall(ctx: click.Context, yes: bool) -> None:
+    """Remove all OCW data, config, and daemon."""
+    if not yes:
+        confirmed = click.confirm(
+            "This will delete all OCW data including telemetry history. Continue?",
+            default=False,
+        )
+        if not confirmed:
+            console.print("[dim]Cancelled.[/dim]")
+            return
+
+    # 1. Stop tj serve if running
+    from tokenjam.cli.cmd_stop import cmd_stop
+    ctx.invoke(cmd_stop)
+
+    # 2. Deregister MCP server from Claude Code (Gap #13)
+    if shutil.which("claude"):
+        subprocess.run(
+            ["claude", "mcp", "remove", "tj", "--scope", "user"],
+            capture_output=True, text=True,
+        )
+        console.print("  Removed tj MCP server from Claude Code.")
+
+    # 3. Unload and delete launchd plist
+    plist_path = Path.home() / "Library/LaunchAgents/com.tokenjam.serve.plist"
+    if plist_path.exists():
+        subprocess.run(
+            ["launchctl", "unload", str(plist_path)],
+            capture_output=True, text=True,
+        )
+        plist_path.unlink()
+        console.print(f"  Removed {plist_path}")
+
+    # 4. Delete systemd service if present
+    systemd_path = Path.home() / ".config/systemd/user/tokenjam.service"
+    if systemd_path.exists():
+        subprocess.run(
+            ["systemctl", "--user", "disable", "--now", "tokenjam"],
+            capture_output=True, text=True,
+        )
+        systemd_path.unlink()
+        console.print(f"  Removed {systemd_path}")
+
+    # 5. Delete ~/.tj/ (telemetry DB)
+    ocw_dir = Path.home() / ".tj"
+    if ocw_dir.exists():
+        shutil.rmtree(ocw_dir)
+        console.print(f"  Removed {ocw_dir}")
+
+    # 6. Read projects index BEFORE deleting the global config dir.
+    global_config_dir = Path.home() / ".config" / "tj"
+    project_paths: list[Path] = []
+    projects_index = global_config_dir / "projects.json"
+    try:
+        if projects_index.exists():
+            paths = json.loads(projects_index.read_text())
+            project_paths = [Path(p) for p in paths if isinstance(p, str)]
+    except Exception:
+        pass
+
+    # 7. Delete global config ~/.config/tj/
+    if global_config_dir.exists():
+        shutil.rmtree(global_config_dir)
+        console.print(f"  Removed {global_config_dir}")
+
+    # 8. Delete local .tj/ if present
+    local_ocw = Path(".tj")
+    if local_ocw.exists():
+        shutil.rmtree(local_ocw)
+        console.print(f"  Removed {local_ocw}")
+
+    # 9. Delete temp files
+    for tmp_file in ["/tmp/tj-serve.out", "/tmp/tj-serve.err"]:
+        p = Path(tmp_file)
+        if p.exists():
+            p.unlink()
+            console.print(f"  Removed {tmp_file}")
+
+    # 10. Remove OCW env vars from ~/.claude/settings.json
+    _GLOBAL_TJ_KEYS = {
+        "CLAUDE_CODE_ENABLE_TELEMETRY",
+        "OTEL_LOGS_EXPORTER",
+        "OTEL_EXPORTER_OTLP_PROTOCOL",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_HEADERS",
+    }
+    global_settings_path = Path.home() / ".claude" / "settings.json"
+    if global_settings_path.exists():
+        try:
+            gs = json.loads(global_settings_path.read_text())
+            env = gs.get("env", {})
+            removed = [k for k in _GLOBAL_TJ_KEYS if k in env]
+            for k in removed:
+                del env[k]
+            if removed:
+                gs["env"] = env
+                global_settings_path.write_text(json.dumps(gs, indent=2) + "\n")
+                console.print(f"  Cleaned {len(removed)} OCW env vars from {global_settings_path}")
+        except Exception as exc:
+            console.print(f"  [yellow]Could not clean {global_settings_path}: {exc}[/yellow]")
+
+    # 11. Remove OTEL_RESOURCE_ATTRIBUTES from all onboarded project .claude/settings.json files.
+    # project_paths was read from projects.json before the global config dir was deleted above.
+    # Always include CWD so running uninstall from a project dir works even without the index
+    cwd = Path.cwd()
+    if cwd not in project_paths:
+        project_paths.append(cwd)
+
+    for proj in project_paths:
+        proj_settings = proj / ".claude" / "settings.json"
+        if not proj_settings.exists():
+            continue
+        try:
+            ps = json.loads(proj_settings.read_text())
+            env = ps.get("env", {})
+            if "OTEL_RESOURCE_ATTRIBUTES" in env:
+                del env["OTEL_RESOURCE_ATTRIBUTES"]
+                ps["env"] = env
+                proj_settings.write_text(json.dumps(ps, indent=2) + "\n")
+                console.print(f"  Removed OTEL_RESOURCE_ATTRIBUTES from {proj_settings}")
+        except Exception as exc:
+            console.print(f"  [yellow]Could not clean {proj_settings}: {exc}[/yellow]")
+
+    # 11. Remove # tj harness observability block from ~/.zshrc
+    zshrc = Path.home() / ".zshrc"
+    if zshrc.exists():
+        try:
+            text = zshrc.read_text()
+            # Match the marker line plus all following export lines (any count)
+            cleaned = re.sub(
+                r"# tj harness observability\n(?:export [^\n]+\n)*",
+                "",
+                text,
+            )
+            if cleaned != text:
+                zshrc.write_text(cleaned)
+                console.print(f"  Removed OCW env block from {zshrc}")
+        except Exception as exc:
+            console.print(f"  [yellow]Could not clean {zshrc}: {exc}[/yellow]")
+
+    console.print()
+    console.print("[green]TokenJam data and config removed.[/green]")
+    console.print("To remove the package itself, run: [bold]pip uninstall tokenjam[/bold]")