coding-os 0.3.2__py3-none-any.whl

cli/graph_commands.py

@@ -0,0 +1,1265 @@
+"""graph_os CLI subcommands.
+
+Registers the `cos graph-*` family on the root `cli` group:
+
+    cos graph-reindex [--path DIR] [--no-docs]
+    cos graph-query "<phrase>" [--limit N] [--kinds ...]
+    cos graph-context <uid>
+    cos graph-impact <uid> [--downstream|--upstream]
+    cos graph-references <uid>
+    cos graph-path <src> <dst>
+    cos graph-contracts [--kind http,mcp,...]
+    cos graph-rename-plan <uid> <new-name>
+    cos graph-export [--format json|mermaid|dot] [--out FILE]
+    cos graph-viz [--path DIR] [--out FILE] [--serve] [--port N]
+    cos graph-stats
+    cos graph-index-local <path>
+    cos graph-index-github <url> [--auth TOKEN]
+    cos graph-index-zip <archive>
+    cos graph-group create|add|remove|list|status|sync|query|contracts|viz ...
+
+Every subcommand prints JSON by default so scripts and agents can parse
+consistently. `--pretty` or the absence of `--json` picks a readable
+form.
+
+All commands go through the same envelope shape as the MCP tools
+(Rule 14) so agents running `cos` in a shell get the same signal they
+would via MCP.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+import click
+
+# ---------------------------------------------------------------------------
+# Lazy bootstrap — push core/ + src/core/thinking_os onto sys.path.
+# ---------------------------------------------------------------------------
+
+
+def _bootstrap_paths() -> None:
+    from cli._resources import core_dir as _core_dir
+
+    core_path = _core_dir()
+    tos_dir = core_path / "thinking_os"
+    for candidate in (core_path, tos_dir):
+        if candidate.exists() and str(candidate) not in sys.path:
+            sys.path.insert(0, str(candidate))
+
+
+def _json_echo(payload: Any, *, pretty: bool = False) -> None:
+    if isinstance(payload, str):
+        # Already a JSON envelope from a `cos_graph_*` tool.
+        try:
+            payload = json.loads(payload)
+        except json.JSONDecodeError:
+            click.echo(payload)
+            return
+    if pretty:
+        click.echo(json.dumps(payload, indent=2, default=str))
+    else:
+        click.echo(json.dumps(payload, default=str))
+
+
+def _open_backend():
+    _bootstrap_paths()
+    from database import init_db  # type: ignore
+
+    from graph_os.backends.sqlite_backend import SqliteBackend  # type: ignore
+    from graph_os.tools import graph as graph_tools  # type: ignore
+
+    conn = init_db()
+    backend = SqliteBackend(conn=conn)
+    graph_tools._BACKEND_SINGLETON = backend
+    return backend, graph_tools
+
+
+# ---------------------------------------------------------------------------
+# Parallel reindex worker — must be module-level so ProcessPoolExecutor
+# can pickle it. Each worker re-imports graph_os.tools.reindex_dispatch
+# inside its own process; init_db() inside dispatch() opens a fresh
+# SQLite WAL connection. The dispatcher's busy-retry loop handles
+# concurrent writers without the CLI having to coordinate.
+# ---------------------------------------------------------------------------
+
+
+def _report_failure_reason(report: dict) -> str | None:
+    graph_layer = (report.get("layers") or {}).get("graph") or {}
+    if report.get("status") == "error" or graph_layer.get("status") == "error":
+        return str(graph_layer.get("reason") or report.get("reason") or "unknown")
+    return None
+
+
+def _is_lock_shaped(reason: str) -> bool:
+    lowered = reason.lower()
+    return "locked" in lowered or "busy" in lowered
+
+
+def _parallel_dispatch(
+    file_path: str,
+    project_root: str,
+    include_docs: bool,
+    force: bool,
+) -> dict:
+    _bootstrap_paths()
+    from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+    # defer per-file stub linking — graph_reindex runs ONE global
+    # link after the whole walk, so mid-walk resolutions aren't orphaned by a
+    # later file's prune-before-reindex.
+    return dispatch(
+        file_path,
+        project_root=project_root,
+        include_docs=include_docs,
+        force=force,
+        link_stubs=False,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Query / context / impact / etc.
+# ---------------------------------------------------------------------------
+
+
+def register(cli: click.Group) -> None:
+    """Attach every `cos graph-*` subcommand onto the parent `cli` group."""
+
+    @cli.command(name="graph-query")
+    @click.argument("query", nargs=-1)
+    @click.option("--limit", default=10, show_default=True, type=int)
+    @click.option("--kinds", default="", help="Comma-separated node kinds.")
+    @click.option("--max-hops", default=2, type=int)
+    @click.option("--confidence-min", default=0.3, type=float)
+    @click.option("--pretty", is_flag=True)
+    def graph_query(query, limit, kinds, max_hops, confidence_min, pretty):
+        """Hybrid search over node labels + docstrings."""
+        q = " ".join(query).strip()
+        if not q:
+            raise click.BadParameter("query argument required")
+        _, tools = _open_backend()
+        result = tools.cos_graph_query(
+            q,
+            kinds=[k.strip() for k in kinds.split(",") if k.strip()] or None,
+            limit=limit,
+            max_hops=max_hops,
+            confidence_min=confidence_min,
+        )
+        _json_echo(result, pretty=pretty)
+
+    @cli.command(name="graph-search")
+    @click.argument("query", nargs=-1)
+    @click.option("--top-k", default=10, show_default=True, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_search(query, top_k, pretty):
+        """Hybrid semantic + lexical + centrality search over indexed code by free text."""
+        q = " ".join(query).strip()
+        if not q:
+            raise click.BadParameter("query argument required")
+        _, tools = _open_backend()
+        _json_echo(tools.cos_graph_search(q, top_k=top_k), pretty=pretty)
+
+    @cli.command(name="graph-context")
+    @click.argument("uid")
+    @click.option("--direction", default="both", type=click.Choice(["in", "out", "both"]))
+    @click.option("--depth", default=1, type=int)
+    @click.option("--include-content", is_flag=True)
+    @click.option("--include-evidence", is_flag=True)
+    @click.option("--pretty", is_flag=True)
+    def graph_context(uid, direction, depth, include_content, include_evidence, pretty):
+        """Neighbourhood around a symbol (callers + callees + refs)."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_context(
+                uid,
+                direction=direction,
+                depth=depth,
+                include_content=include_content,
+                include_evidence=include_evidence,
+            ),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-impact")
+    @click.argument("uid")
+    @click.option(
+        "--direction", default="downstream", type=click.Choice(["downstream", "upstream", "both"])
+    )
+    @click.option("--depth", default=3, type=int)
+    @click.option("--confidence-min", default=0.5, type=float)
+    @click.option("--pretty", is_flag=True)
+    def graph_impact(uid, direction, depth, confidence_min, pretty):
+        """Blast-radius of a change — risk-tiered."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_impact(
+                uid,
+                direction=direction,
+                depth=depth,
+                confidence_min=confidence_min,
+            ),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-references")
+    @click.argument("uid")
+    @click.option("--kinds", default="")
+    @click.option("--limit", default=100, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_references(uid, kinds, limit, pretty):
+        """Inbound edges — who references this."""
+        _, tools = _open_backend()
+        # Empty --kinds → None so the tool auto-picks the right default edge
+        # kinds PER node kind (class→constructs/inherits, fn→calls/imports).
+        # A hardcoded CSV default returned 0 for class nodes (MCP parity bug).
+        kset = tuple(k.strip() for k in kinds.split(",") if k.strip())
+        _json_echo(
+            tools.cos_graph_references(
+                uid,
+                kinds=kset or None,
+                limit=limit,
+            ),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-path")
+    @click.argument("source")
+    @click.argument("target")
+    @click.option("--max-hops", default=5, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_path(source, target, max_hops, pretty):
+        """Shortest path between two nodes."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_path(source, target, max_hops=max_hops),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-trace")
+    @click.argument("entry_uid")
+    @click.option("--max-steps", default=50, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_trace(entry_uid, max_steps, pretty):
+        """Forward execution walk from an entry point."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_trace(entry_uid, max_steps=max_steps),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-similar")
+    @click.argument("uid")
+    @click.option("--top-k", default=5, type=int)
+    @click.option("--confidence-min", default=0.5, type=float)
+    @click.option("--pretty", is_flag=True)
+    def graph_similar(uid, top_k, confidence_min, pretty):
+        """Semantic-similar nodes (difflib baseline; BGE-M3 later)."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_similar(uid, top_k=top_k, confidence_min=confidence_min),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-contracts")
+    @click.option("--kind", default="http,mcp,grpc,event,websocket")
+    @click.option("--scope", default="all")
+    @click.option("--pretty", is_flag=True)
+    def graph_contracts(kind, scope, pretty):
+        """API surface — routes, MCP tools, gRPC, events, WS."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_contracts(
+                scope=scope,
+                kinds=tuple(k.strip() for k in kind.split(",") if k.strip()),
+            ),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-rename-plan")
+    @click.argument("uid")
+    @click.argument("new_name")
+    @click.option("--no-strings", is_flag=True)
+    @click.option("--pretty", is_flag=True)
+    def graph_rename_plan(uid, new_name, no_strings, pretty):
+        """Produce a rename plan — call-sites, docs, tests, strings."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_rename_plan(uid, new_name, check_strings=not no_strings),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-export")
+    @click.option("--format", "fmt", default="json", type=click.Choice(["json", "mermaid", "dot"]))
+    @click.option("--root-uid", default=None)
+    @click.option("--edge-types", default="")
+    @click.option("--max-nodes", default=500, type=int)
+    @click.option("--out", default=None, help="Write to file instead of stdout.")
+    def graph_export(fmt, root_uid, edge_types, max_nodes, out):
+        """Export a subgraph as json / mermaid / dot."""
+        _, tools = _open_backend()
+        envelope = tools.cos_graph_export(
+            format=fmt,
+            root_uid=root_uid,
+            edge_types=[e.strip() for e in edge_types.split(",") if e.strip()] or None,
+            max_nodes=max_nodes,
+        )
+        parsed = json.loads(envelope) if isinstance(envelope, str) else envelope
+        if not parsed.get("ok"):
+            raise click.ClickException(json.dumps(parsed))
+        data = parsed["data"]
+        if fmt == "json":
+            payload = json.dumps(
+                {"nodes": data["nodes"], "edges": data["edges"]},
+                indent=2,
+                default=str,
+            )
+        else:
+            payload = data["diagram"]
+        if out:
+            Path(out).write_text(payload, encoding="utf-8")
+            click.echo(f"[graph-export] wrote {out}")
+        else:
+            click.echo(payload)
+
+    @cli.command(name="graph-stats")
+    @click.option("--pretty", is_flag=True)
+    def graph_stats(pretty):
+        """Quick snapshot: node count, edge count, schema version."""
+        backend, _ = _open_backend()
+        _bootstrap_paths()
+        from database import get_db_stats  # type: ignore
+
+        stats = get_db_stats(backend._conn)
+        report = {
+            "schema_version": stats["schema_version"],
+            "node_count": backend.count_nodes(),
+            "edge_count": backend.count_edges(),
+            "backend": backend.backend_id,
+            "db_size_bytes": stats.get("db_size_bytes"),
+        }
+        _json_echo(report, pretty=pretty)
+
+    @cli.command(name="graph-cycles")
+    @click.option("--scope", default="imports", type=click.Choice(["imports", "calls"]))
+    @click.option("--top", default=20, type=int)
+    @click.option("--min-size", default=2, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_cycles(scope, top, min_size, pretty):
+        """Circular dependencies — strongly-connected components."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_cycles(scope=scope, top=top, min_size=min_size),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-test-gap")
+    @click.option("--kind", default="")
+    @click.option("--top", default=50, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_test_gap(kind, top, pretty):
+        """Untested symbols — prod code with zero inbound test edge."""
+        _, tools = _open_backend()
+        _json_echo(tools.cos_graph_test_gap(kind=kind, top=top), pretty=pretty)
+
+    @cli.command(name="graph-dead-code")
+    @click.option("--kind", default="")
+    @click.option("--top", default=50, type=int)
+    @click.option("--include-tests", is_flag=True)
+    @click.option("--pretty", is_flag=True)
+    def graph_dead_code(kind, top, include_tests, pretty):
+        """Dead-code candidates — in-repo symbols with no non-test caller."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_dead_code(kind=kind, top=top, include_tests=include_tests),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-diff")
+    @click.option("--base", default="HEAD~1")
+    @click.option("--head", default="HEAD")
+    @click.option("--pretty", is_flag=True)
+    def graph_diff(base, head, pretty):
+        """Blast-radius of a git range — base..head changed symbols + downstream."""
+        _, tools = _open_backend()
+        _json_echo(tools.cos_graph_diff(base=base, head=head), pretty=pretty)
+
+    @cli.command(name="graph-resolve")
+    @click.argument("q")
+    @click.option("--kinds", default="")
+    @click.option("--top", default=10, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_resolve(q, kinds, top, pretty):
+        """Resolve a label / path / partial to canonical uids."""
+        _, tools = _open_backend()
+        kset = tuple(k.strip() for k in kinds.split(",") if k.strip())
+        _json_echo(
+            tools.cos_graph_resolve(q, kinds=kset or None, top=top),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-centrality")
+    @click.option("--metric", default="degree", type=click.Choice(["degree", "betweenness"]))
+    @click.option("--top", default=20, type=int)
+    @click.option("--kind", default="")
+    @click.option("--pretty", is_flag=True)
+    def graph_centrality(metric, top, kind, pretty):
+        """Hub / chokepoint nodes — degree or betweenness centrality."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_centrality(metric=metric, top=top, kind=kind or None),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-ranking")
+    @click.option("--query", default="")
+    @click.option("--top", default=20, type=int)
+    @click.option("--kind", default="")
+    @click.option("--pretty", is_flag=True)
+    def graph_ranking(query, top, kind, pretty):
+        """PageRank importance — optionally personalised by query."""
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_ranking(query=query or None, top=top, kind=kind or None),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-doctor")
+    @click.option("--fix", is_flag=True, help="Attempt safe repairs (delete dangling/stale).")
+    @click.option("--pretty", is_flag=True)
+    def graph_doctor(fix, pretty):
+        """Graph health — orphans, dangling edges, duplicates, backend status."""
+        _, tools = _open_backend()
+        _json_echo(tools.cos_graph_doctor(fix=fix), pretty=pretty)
+
+    @cli.command(name="graph-reindex")
+    @click.option("--path", default=None, help="Directory to reindex (default: repo root).")
+    @click.option("--no-docs", is_flag=True, help="Skip the docs RAG layer.")
+    @click.option(
+        "--max-files",
+        default=1_000_000,
+        type=int,
+        help="Cap on files walked (default 1M for monorepo-scale).",
+    )
+    @click.option(
+        "--workers",
+        "-j",
+        default=1,
+        type=int,
+        help="Parallel worker processes (default 1 = sequential). For "
+        "large monorepos, set to CPU count (e.g. -j 8). SQLite WAL + "
+        "the dispatcher's lock-retry loop handle concurrent writes.",
+    )
+    @click.option(
+        "--force",
+        "-f",
+        is_flag=True,
+        help="V1: bypass the file_index_state cache; reindex even "
+        "files whose content_hash matches the last successful run.",
+    )
+    @click.option(
+        "--status",
+        is_flag=True,
+        help="V1: print the top 50 most-recently-indexed files from "
+        "file_index_state and exit (debugging aid).",
+    )
+    @click.option(
+        "--rebuild-kinds",
+        is_flag=True,
+        help="S3: re-run the v16 kind-normalization data migration "
+        "without a full reindex. Useful after the NodeKind enum "
+        "ships to canonicalise legacy colon-prefixed kinds in place.",
+    )
+    @click.option(
+        "--extractor",
+        type=click.Choice(["auto", "legacy", "tree-sitter"], case_sensitive=False),
+        default="auto",
+        show_default=True,
+        help=(
+            "TASK-122 A/B flag: which parser ladder extractors should "
+            "use. 'legacy' forces ast/regex baselines; 'tree-sitter' "
+            "prefers tree-sitter when grammars are installed (lands "
+            "in TASK-119/120/121); 'auto' picks the current default. "
+            "Sets COS_EXTRACTOR_PREFERENCE for downstream extractors."
+        ),
+    )
+    @click.option(
+        "--prune-stale",
+        is_flag=True,
+        help=(
+            "W7.5 / R4-N7: delete nodes whose file_path no longer exists "
+            "on disk BEFORE reindexing. Reindex is idempotent-upsert so "
+            "moved/renamed/deleted files leave ghost nodes that bloat "
+            "the graph; this flag invokes cos_graph_doctor(fix=True) "
+            "to prune them first."
+        ),
+    )
+    def graph_reindex(
+        path,
+        no_docs,
+        max_files,
+        workers,
+        force,
+        status,
+        rebuild_kinds,
+        extractor,
+        prune_stale,
+    ):
+        """Walk a directory and rebuild the graph via the dispatcher."""
+        _bootstrap_paths()
+        # publish the chosen ladder via env so every spawned
+        # subprocess (incremental indexer, doc indexer, etc.) sees it.
+        # Existing call sites that bypass the CLI (e.g. PostToolUse
+        # auto-reindex) keep their default behaviour because the env
+        # var is unset when the CLI flag isn't passed.
+        os.environ["COS_EXTRACTOR_PREFERENCE"] = (extractor or "auto").lower()
+        if status:
+            _graph_reindex_print_status()
+            return
+        if rebuild_kinds:
+            # S3 data migration — idempotent; can be invoked standalone.
+            try:
+                import database  # type: ignore
+
+                from graph_os.types import normalize_kind  # type: ignore
+            except ImportError as exc:
+                click.echo(f"[graph-reindex] rebuild-kinds import failed: {exc}", err=True)
+                return
+            conn = database.get_connection()
+            try:
+                rows = conn.execute("SELECT DISTINCT kind FROM graph_nodes").fetchall()
+                renames: dict[str, str] = {}
+                for r in rows:
+                    legacy = r[0]
+                    if legacy is None:
+                        continue
+                    try:
+                        canonical = normalize_kind(legacy).value
+                    except ValueError:
+                        continue
+                    if canonical != legacy:
+                        renames[legacy] = canonical
+                total = 0
+                for legacy, canonical in renames.items():
+                    cur = conn.execute(
+                        "UPDATE graph_nodes SET kind = ? WHERE kind = ?",
+                        (canonical, legacy),
+                    )
+                    total += cur.rowcount or 0
+                conn.commit()
+                click.echo(
+                    f"[graph-reindex] rebuild-kinds: "
+                    f"{len(renames)} distinct kind(s) rewritten, "
+                    f"{total} row(s) updated"
+                )
+                return
+            finally:
+                conn.close()
+
+        import time as _time
+
+        from graph_os.ingest import walk_local  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+        # W7.5 / R4-N7: prune stale-path nodes before reindex when asked.
+        if prune_stale:
+            from graph_os.tools.graph import cos_graph_doctor  # type: ignore
+
+            doc = cos_graph_doctor(fix=True)
+            # cos_graph_doctor returns a JSON string (FastMCP wire); parse
+            # it before reading nested fields.
+            if isinstance(doc, str):
+                doc = json.loads(doc)
+            fixed = doc.get("data", {}).get("meta", {}).get("fixed_count", 0)
+            click.echo(f"[graph-reindex] prune-stale: removed {fixed} stale node(s)")
+
+        target = Path(path or Path.cwd()).resolve()
+        # --path is the WALK directory, not the project root. Resolve the
+        # enclosing repo root (nearest ancestor with .coding-os/) so a
+        # sub-dir --path can't spawn a stray <subdir>/.coding-os/ DB or
+        # emit subdir-relative file_paths.
+        project_root = next(
+            (p for p in (target, *target.parents) if (p / ".coding-os").is_dir()),
+            target,
+        )
+        plan = walk_local(target, max_files=max_files)
+        click.echo(f"[graph-reindex] walking {target}; {len(plan.files)} files (force={force})")
+        # Surface oversized files dropped by the per-file byte cap — a skipped
+        # large source file is a coverage gap, not a no-op (TASK-293).
+        _oversize = plan.metadata.get("skipped_oversize") or []
+        if _oversize:
+            click.echo(
+                f"[graph-reindex] skipped {len(_oversize)} oversized file(s) "
+                f"(> COS_GRAPH_MAX_FILE_BYTES): {', '.join(_oversize[:5])}"
+                + (" …" if len(_oversize) > 5 else ""),
+                err=True,
+            )
+        # Symlink / unreadable skips — counts only, surfaced so they aren't
+        # silent (TASK-302). A symlink target is indexed on its own pass, so
+        # a non-zero symlink count is informational, not an error.
+        _sym = int(plan.metadata.get("skipped_symlink") or 0)
+        _rerr = int(plan.metadata.get("skipped_read_error") or 0)
+        if _sym or _rerr:
+            click.echo(
+                f"[graph-reindex] skipped {_sym} symlink(s), {_rerr} unreadable file(s)",
+                err=True,
+            )
+        processed = skipped = errors = lock_streak = 0
+        failed_paths: list[str] = []
+        started = _time.monotonic()
+        # Circuit breaker: a write lock held by another process makes EVERY
+        # file fail after its bounded busy-wait (~5s × 3 retries). Without
+        # this, an 800-file walk grinds silently for an hour — the per-file
+        # failure used to land only in layers.graph.status, which this loop
+        # counted as PROCESSED (2026-06-11 stall, TASK-394/395). The streak
+        # resets on any success so a transient start-of-walk lock storm
+        # (workers warming up alongside hub/MCP writers) doesn't abort a
+        # run that is actually progressing.
+        _LOCK_STREAK_ABORT = 10
+
+        def _record(report: dict) -> None:
+            nonlocal processed, skipped, errors, lock_streak
+            cache = report.get("cache")
+            if cache == "hit":
+                skipped += 1
+                return
+            processed += 1
+            reason = _report_failure_reason(report)
+            if reason is None:
+                lock_streak = 0
+                return
+            errors += 1
+            failed_paths.append(str(report.get("path") or ""))
+            if errors <= 5:
+                click.echo(f"[graph-reindex]   ! {report.get('path')}: {reason}", err=True)
+            if _is_lock_shaped(reason):
+                lock_streak += 1
+            if lock_streak >= _LOCK_STREAK_ABORT:
+                raise click.ClickException(
+                    f"aborting: {lock_streak} consecutive lock-shaped graph write "
+                    "failures — another process is holding the DB write lock; "
+                    "close it and re-run"
+                )
+
+        # Live per-file progress bar — click.progressbar auto-hides when
+        # stdout is not a TTY (pipes / CI), so non-interactive runs keep
+        # the summary-only output. Replaces the per-file cache-hit echo.
+        bar = click.progressbar(length=len(plan.files), label="[graph-reindex] indexing")
+        if workers and workers > 1:
+            # ProcessPoolExecutor parallelism for monorepo-scale walks. Each
+            # worker opens its own SQLite connection via init_db() inside
+            # dispatch(); WAL mode + the dispatcher's busy-retry loop handle
+            # concurrent writers.
+            from concurrent.futures import ProcessPoolExecutor, as_completed
+
+            click.echo(f"[graph-reindex] parallel workers={workers}")
+            futures = {}
+            with ProcessPoolExecutor(max_workers=workers) as pool, bar:
+                for file_path in plan.files:
+                    fut = pool.submit(
+                        _parallel_dispatch,
+                        str(file_path),
+                        str(project_root),
+                        not no_docs,
+                        force,
+                    )
+                    futures[fut] = file_path
+                for fut in as_completed(futures):
+                    file_path = futures[fut]
+                    try:
+                        report = fut.result()
+                        _record(report)
+                    except click.ClickException:
+                        # Circuit breaker tripped — drop queued work NOW;
+                        # the context manager's shutdown(wait=True) would
+                        # otherwise grind through every pending future.
+                        pool.shutdown(wait=False, cancel_futures=True)
+                        raise
+                    except Exception as exc:
+                        errors += 1
+                        failed_paths.append(str(file_path))
+                        click.echo(f"[graph-reindex]   ! {file_path}: {exc}", err=True)
+                    bar.update(1)
+        else:
+            with bar:
+                for file_path in plan.files:
+                    try:
+                        report = dispatch(
+                            file_path,
+                            project_root=project_root,
+                            include_docs=not no_docs,
+                            force=force,
+                            link_stubs=False,  # global link after the walk
+                        )
+                        _record(report)
+                    except click.ClickException:
+                        raise
+                    except Exception as exc:
+                        errors += 1
+                        failed_paths.append(str(file_path))
+                        click.echo(f"[graph-reindex]   ! {file_path}: {exc}", err=True)
+                    bar.update(1)
+
+        # Writers serialize in SQLite, so parallel workers can drop a few
+        # files to lock contention (their hash is NOT advanced). Retry the
+        # casualties sequentially — no sibling contention — so a parallel
+        # walk converges to the same zero-error result as a sequential one.
+        if failed_paths:
+            recovered = 0
+            for rel in [p for p in failed_paths if p]:
+                try:
+                    report = dispatch(
+                        project_root / rel,
+                        project_root=project_root,
+                        include_docs=not no_docs,
+                        force=force,
+                        link_stubs=False,
+                    )
+                    if _report_failure_reason(report) is None:
+                        recovered += 1
+                except Exception as exc:
+                    click.echo(f"[graph-reindex]   ! retry {rel}: {exc}", err=True)
+            errors -= recovered
+            click.echo(f"[graph-reindex] retry pass: {recovered}/{len(failed_paths)} recovered")
+        duration = _time.monotonic() - started
+
+        # Reconcile the graph to the current walk BEFORE reporting: file_index_state
+        # rows (and their nodes/edges) for files no longer indexed — deleted from
+        # disk OR now excluded by .gitignore — are stale and make cos_graph_doctor
+        # over-count. GC them first so the parse-error summary below reads the
+        # reconciled (exact) state. ONLY on a full, uncapped repo walk
+        # (target == project_root); a --path sub-walk or a max_files-capped walk
+        # would wrongly flag every other file as stale (TASK-302).
+        if target == project_root and len(plan.files) < max_files:
+            try:
+                from database import init_db, resolve_db_path  # type: ignore
+
+                gc_conn = init_db(str(resolve_db_path(project_root)))
+                walked = {p.relative_to(project_root).as_posix() for p in plan.files}
+                stale = [
+                    r[0]
+                    for r in gc_conn.execute(
+                        "SELECT DISTINCT file_path FROM file_index_state"
+                    ).fetchall()
+                    if r[0] and r[0] not in walked
+                ]
+                gc_nodes = 0
+                for sp in stale:
+                    gc_conn.execute(
+                        "DELETE FROM graph_edges_v12 WHERE source_id IN "
+                        "(SELECT id FROM graph_nodes WHERE file_path=?) "
+                        "OR target_id IN (SELECT id FROM graph_nodes WHERE file_path=?)",
+                        (sp, sp),
+                    )
+                    cur = gc_conn.execute("DELETE FROM graph_nodes WHERE file_path=?", (sp,))
+                    gc_nodes += cur.rowcount or 0
+                    gc_conn.execute("DELETE FROM file_index_state WHERE file_path=?", (sp,))
+                if stale:
+                    gc_conn.commit()
+                    click.echo(
+                        f"[graph-reindex] reconcile: pruned {len(stale)} no-longer-indexed "
+                        f"file(s), {gc_nodes} node(s)"
+                    )
+            except Exception as exc:
+                click.echo(f"[graph-reindex] reconcile skipped: {exc}", err=True)
+
+        # Surface partial-extraction coverage gaps (some symbols dropped on a
+        # parse error) — "errors" only counts hard exceptions, so this was
+        # silent (TASK-293). Read the cumulative truth from file_index_state,
+        # the same source cos_graph_doctor reports, so the two always agree.
+        parse_err_total = parse_err_files = 0
+        try:
+            from database import init_db, resolve_db_path  # type: ignore
+
+            _pe_conn = init_db(str(resolve_db_path(project_root)))
+            _pe_row = _pe_conn.execute(
+                "SELECT COALESCE(SUM(parse_errors_count), 0), COUNT(DISTINCT file_path) "
+                "FROM file_index_state WHERE parse_errors_count > 0"
+            ).fetchone()
+            parse_err_total = int(_pe_row[0] or 0)
+            parse_err_files = int(_pe_row[1] or 0)
+        except Exception as exc:  # fail-open — never block the summary
+            import logging
+
+            logging.getLogger("graph_os.cli").debug("parse-error summary probe skipped: %s", exc)
+        click.echo(
+            f"[graph-reindex] processed={processed} skipped={skipped} "
+            f"errors={errors} parse_errors={parse_err_total} in {parse_err_files} files "
+            f"duration={duration:.2f}s"
+        )
+
+        # per-file linking during the walk cannot resolve a stub
+        # whose real target is indexed LATER (file-order dependency), so
+        # cross-module bare-name calls (ok()/fail()/...) leak to external
+        # stubs and references/impact under-report callers. Run the GLOBAL
+        # linker once now that every node exists — same precise module→file
+        # matching as the per-file pass, just applied across the whole graph.
+        try:
+            _bootstrap_paths()
+            from database import init_db, resolve_db_path  # type: ignore
+
+            from graph_os.backends.sqlite_backend import SqliteBackend  # type: ignore
+
+            # Link the same DB the walk indexed — the repo-root DB, NOT a
+            # <target>/.coding-os/ stray when --path points at a sub-dir.
+            conn = init_db(str(resolve_db_path(project_root)))
+            backend = SqliteBackend(conn=conn)
+            relinked = backend.link_external_stubs()
+            imports_linked = backend.link_import_bindings()
+            php_linked = backend.link_php_handlers()
+            click.echo(
+                f"[graph-reindex] cross-file link: {relinked} stub(s) resolved, "
+                f"{imports_linked} import binding(s)"
+                + (f" (+{php_linked} php handler(s))" if php_linked else "")
+            )
+        except Exception as exc:
+            click.echo(f"[graph-reindex] cross-file link skipped: {exc}", err=True)
+
+        # Residue sweep — the file reconcile above reads file_index_state,
+        # which holds file rows only, so folder-spine nodes and zero-edge
+        # phantoms (a folder is not a file row; a phantom carries a NULL /
+        # off-tree file_path) survive it. A bulk `git mv` / `rm -rf` of a
+        # directory fires no per-file deletion-prune, so only this
+        # authoritative full-walk pass clears the old-path folder/phantom
+        # residue. Runs AFTER the global link so a live external stub already
+        # holds its edges and is never swept; the doctor safe-repair deletes
+        # only absent-on-disk paths and zero-edge orphans, so an on-disk
+        # `src/`-prefixed node with `contains` edges survives. Same full-walk
+        # guard as the file reconcile — a sub-walk / capped walk is not
+        # authoritative.
+        if target == project_root and len(plan.files) < max_files:
+            try:
+                from graph_os.tools.graph import cos_graph_doctor  # type: ignore
+
+                swept = cos_graph_doctor(fix=True)
+                if isinstance(swept, str):
+                    swept = json.loads(swept)
+                swept_n = swept.get("data", {}).get("meta", {}).get("fixed_count", 0)
+                if swept_n:
+                    click.echo(
+                        f"[graph-reindex] reconcile-sweep: pruned {swept_n} "
+                        "residual folder/phantom node(s)"
+                    )
+            except Exception as exc:
+                click.echo(f"[graph-reindex] reconcile-sweep skipped: {exc}", err=True)
+
+    @cli.command(name="graph-index-local")
+    @click.argument("path")
+    @click.option("--alias", default=None)
+    @click.option("--max-files", default=50_000, type=int)
+    @click.option("--max-size-mb", default=500, type=int)
+    def graph_index_local(path, alias, max_files, max_size_mb):
+        """Index a local folder (outside the current repo)."""
+        _bootstrap_paths()
+        from graph_os.ingest import walk_local  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+        target = Path(path).expanduser().resolve()
+        plan = walk_local(
+            target,
+            alias=alias,
+            max_files=max_files,
+            max_size_bytes=max_size_mb * 1024 * 1024,
+        )
+        click.echo(f"[local] alias={plan.alias} files={len(plan.files)}")
+        indexed = 0
+        with click.progressbar(plan.files, label="[local] indexing") as bar:
+            for file_path in bar:
+                report = dispatch(file_path, project_root=target, include_docs=True)
+                if report.get("status") == "ok":
+                    indexed += 1
+        click.echo(f"[local] indexed {indexed}/{len(plan.files)}")
+
+    @cli.command(name="graph-index-github")
+    @click.argument("url")
+    @click.option("--branch", default=None)
+    @click.option("--alias", default=None)
+    @click.option("--auth", default=None, help="Token for private repos (never logged).")
+    @click.option("--max-size-mb", default=500, type=int)
+    @click.option("--timeout", default=300, type=int)
+    def graph_index_github(url, branch, alias, auth, max_size_mb, timeout):
+        """Clone a public GitHub repo + index (shallow by default)."""
+        _bootstrap_paths()
+        from graph_os.ingest import GithubSize, clone_github  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+        plan = clone_github(
+            url,
+            branch=branch,
+            alias=alias,
+            auth=auth,
+            size=GithubSize(
+                max_size_bytes=max_size_mb * 1024 * 1024,
+                timeout_seconds=timeout,
+            ),
+        )
+        click.echo(f"[github] alias={plan.alias} files={len(plan.files)}")
+        indexed = 0
+        with click.progressbar(plan.files, label="[github] indexing") as bar:
+            for file_path in bar:
+                report = dispatch(file_path, project_root=plan.root, include_docs=True)
+                if report.get("status") == "ok":
+                    indexed += 1
+        click.echo(f"[github] indexed {indexed}/{len(plan.files)}")
+
+    @cli.command(name="graph-index-zip")
+    @click.argument("archive")
+    @click.option("--alias", default=None)
+    @click.option("--out-dir", default=None, help="Extraction root (default tmp).")
+    @click.option("--max-size-mb", default=500, type=int)
+    def graph_index_zip(archive, alias, out_dir, max_size_mb):
+        """Extract a ZIP archive with bomb protection + index."""
+        _bootstrap_paths()
+        from graph_os.ingest import ZipSize, extract_zip  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+        out = Path(out_dir) if out_dir else Path(tempfile.mkdtemp(prefix="cos-zip-"))
+        plan = extract_zip(
+            archive,
+            alias=alias,
+            out_dir=out,
+            size=ZipSize(max_size_bytes=max_size_mb * 1024 * 1024),
+        )
+        click.echo(f"[zip] alias={plan.alias} files={len(plan.files)}")
+        indexed = 0
+        with click.progressbar(plan.files, label="[zip] indexing") as bar:
+            for file_path in bar:
+                report = dispatch(file_path, project_root=plan.root, include_docs=True)
+                if report.get("status") == "ok":
+                    indexed += 1
+        click.echo(f"[zip] indexed {indexed}/{len(plan.files)}")
+
+    @cli.command(name="graph-detect-changes")
+    @click.option(
+        "--staged",
+        "mode",
+        flag_value="staged",
+        help="Diff staged changes (git diff --cached --name-only).",
+    )
+    @click.option(
+        "--working",
+        "mode",
+        flag_value="working",
+        default=True,
+        help="Diff working-tree changes (git diff --name-only). [default]",
+    )
+    @click.option(
+        "--range",
+        "git_range",
+        default=None,
+        metavar="RANGE",
+        help="Diff a commit range, e.g. HEAD~1..HEAD (git diff --name-only RANGE).",
+    )
+    @click.option("--pretty", is_flag=True)
+    def graph_detect_changes(mode, git_range, pretty):
+        """Map changed files to affected graph symbols + downstream tasks."""
+        import subprocess
+
+        # Build the git command based on selected mode.
+        if git_range:
+            scope = git_range
+            git_cmd = ["git", "diff", "--name-only", git_range]
+        elif mode == "staged":
+            scope = "staged"
+            git_cmd = ["git", "diff", "--cached", "--name-only"]
+        else:
+            scope = "working"
+            git_cmd = ["git", "diff", "--name-only"]
+
+        try:
+            result = subprocess.run(
+                git_cmd,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode != 0:
+                raise click.ClickException(
+                    f"git exited {result.returncode}: {result.stderr.strip()}"
+                )
+            files = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+        except FileNotFoundError:
+            raise click.ClickException("git not found on PATH")
+        except subprocess.TimeoutExpired:
+            raise click.ClickException("git diff timed out after 30 s")
+
+        _, tools = _open_backend()
+        _json_echo(
+            tools.cos_graph_detect_changes(
+                scope=scope,
+                files=files or None,
+                analyze_downstream=True,
+            ),
+            pretty=pretty,
+        )
+
+    @cli.command(name="graph-communities")
+    @click.option("--top", default=20, show_default=True, type=int)
+    @click.option("--min-size", default=2, show_default=True, type=int)
+    @click.option("--pretty", is_flag=True)
+    def graph_communities(top, min_size, pretty):
+        """Louvain process clusters (TASK-075).
+
+        Reads the indexed graph; computes Louvain communities over
+        the call/import subgraph.  Use to seed the Search tab grouping
+        or to audit how the graph clusters into named processes.
+        """
+        _, tools = _open_backend()
+        result = tools.cos_graph_communities(top=int(top), min_size=int(min_size))
+        _json_echo(result, pretty=pretty)
+
+    @cli.command(name="graph-entrypoints")
+    @click.option("--top", default=20, show_default=True, type=int)
+    @click.option(
+        "--kind",
+        default="",
+        help="Filter on entry_kind: main / cli / http / cron / test.",
+    )
+    @click.option("--min-score", default=0.05, show_default=True, type=float)
+    @click.option("--pretty", is_flag=True)
+    def graph_entrypoints(top, kind, min_score, pretty):
+        """Top-N scored entry points (main / cli / http / cron / test) — TASK-081.
+
+        Reads the indexed graph; no file re-parsing.  Use to seed
+        cos_graph_trace, populate the Hub Graph tab "Start from entry
+        point" panel, or sanity-check after a reindex.
+        """
+        _, tools = _open_backend()
+        result = tools.cos_graph_entrypoints(
+            top=int(top),
+            kind=(kind or None),
+            min_score=float(min_score),
+        )
+        _json_echo(result, pretty=pretty)
+
+    @cli.command(name="graph-viz")
+    @click.option("--path", default=None)
+    @click.option("--out", default=None, help="Output HTML path.")
+    @click.option("--root-uid", default=None)
+    @click.option("--title", default="graph_os")
+    @click.option("--bundled", is_flag=True)
+    @click.option("--serve", is_flag=True)
+    @click.option("--port", default=0, type=int)
+    @click.option("--open/--no-open", "open_browser", default=True)
+    def graph_viz(path, out, root_uid, title, bundled, serve, port, open_browser):
+        """Generate the HTML graph viewer and optionally open / serve it."""
+        _bootstrap_paths()
+        from graph_os.ingest import walk_local  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+        from graph_os.viewer import build_view  # type: ignore
+
+        backend, _ = _open_backend()
+        if path:
+            target = Path(path).expanduser().resolve()
+            plan = walk_local(target)
+            for file_path in plan.files:
+                dispatch(file_path, project_root=target, include_docs=True)
+
+        out_path = Path(out or Path(".coding-os") / "graph-viz.html").resolve()
+        build_view(backend, out_path, title=title, root_uid=root_uid, bundled=bundled)
+        click.echo(f"[graph-viz] wrote {out_path}")
+        if serve:
+            _serve_static(out_path, port=port, open_browser=open_browser)
+        elif open_browser:
+            import webbrowser
+
+            webbrowser.open(out_path.as_uri())
+
+    # ── group family --------------------------------------------------
+    @cli.group(name="graph-group")
+    def graph_group():
+        """Cross-repo group operations."""
+
+    @graph_group.command("create")
+    @click.argument("name")
+    @click.option(
+        "--manifest-dir", default=None, help="Root for ~/.coding-os/groups/<name>/ overrides."
+    )
+    def group_create(name, manifest_dir):
+        _bootstrap_paths()
+        from graph_os.groups import GroupManifest, save_manifest  # type: ignore
+
+        target = _group_manifest_path(name, manifest_dir)
+        if target.exists():
+            raise click.ClickException(f"group already exists at {target}")
+        save_manifest(GroupManifest(name=name, members=[]), target)
+        click.echo(f"[group] created {target}")
+
+    @graph_group.command("add")
+    @click.argument("name")
+    @click.argument("path")
+    @click.option("--alias", default=None)
+    @click.option("--owns-route", multiple=True)
+    @click.option("--manifest-dir", default=None)
+    def group_add(name, path, alias, owns_route, manifest_dir):
+        _bootstrap_paths()
+        from graph_os.groups import load_manifest, register_member, save_manifest  # type: ignore
+
+        target = _group_manifest_path(name, manifest_dir)
+        if not target.exists():
+            raise click.ClickException("group missing; run `cos graph-group create` first")
+        manifest = load_manifest(target)
+        alias = alias or Path(path).expanduser().resolve().name
+        manifest = register_member(
+            manifest,
+            alias=alias,
+            path=str(Path(path).expanduser().resolve()),
+            owned_routes=list(owns_route),
+        )
+        save_manifest(manifest, target)
+        click.echo(f"[group] added {alias} to {name}")
+
+    @graph_group.command("list")
+    @click.option("--manifest-dir", default=None)
+    def group_list(manifest_dir):
+        base = _group_root(manifest_dir)
+        if not base.exists():
+            click.echo("(no groups)")
+            return
+        for entry in sorted(base.iterdir()):
+            if entry.is_dir() and (entry / "group.json").exists():
+                click.echo(entry.name)
+
+    @graph_group.command("status")
+    @click.argument("name")
+    @click.option("--manifest-dir", default=None)
+    def group_status(name, manifest_dir):
+        _bootstrap_paths()
+        from graph_os.groups import load_manifest  # type: ignore
+
+        target = _group_manifest_path(name, manifest_dir)
+        if not target.exists():
+            raise click.ClickException("group missing")
+        manifest = load_manifest(target)
+        payload = {
+            "name": manifest.name,
+            "members": [
+                {
+                    "alias": m.alias,
+                    "path": m.path,
+                    "exists": Path(m.path).exists(),
+                    "owned_routes": m.owned_routes,
+                }
+                for m in manifest.members
+            ],
+        }
+        click.echo(json.dumps(payload, indent=2))
+
+    @graph_group.command("sync")
+    @click.argument("name")
+    @click.option("--manifest-dir", default=None)
+    def group_sync(name, manifest_dir):
+        _bootstrap_paths()
+        from graph_os.groups import load_manifest  # type: ignore
+        from graph_os.ingest import walk_local  # type: ignore
+        from graph_os.tools.reindex_dispatch import dispatch  # type: ignore
+
+        target = _group_manifest_path(name, manifest_dir)
+        manifest = load_manifest(target)
+        indexed = 0
+        for member in manifest.members:
+            root = Path(member.path)
+            if not root.exists():
+                click.echo(f"[sync] skip {member.alias} (missing: {root})", err=True)
+                continue
+            plan = walk_local(root)
+            for file_path in plan.files:
+                report = dispatch(file_path, project_root=root, include_docs=True)
+                if report.get("status") == "ok":
+                    indexed += 1
+            click.echo(f"[sync] {member.alias}: {len(plan.files)} files")
+        click.echo(f"[sync] indexed {indexed} entries total")
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _group_root(manifest_dir: str | None) -> Path:
+    return (
+        Path(manifest_dir).expanduser() if manifest_dir else (Path.home() / ".coding-os" / "groups")
+    )
+
+
+def _group_manifest_path(name: str, manifest_dir: str | None) -> Path:
+    root = _group_root(manifest_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    folder = root / name
+    folder.mkdir(exist_ok=True)
+    return folder / "group.json"
+
+
+def _graph_reindex_print_status() -> None:
+    """V1 ``--status``: print top 50 most-recently-indexed file_index_state rows."""
+    from datetime import datetime
+
+    _bootstrap_paths()
+    try:
+        import database  # type: ignore
+    except ImportError as exc:
+        raise click.ClickException(f"thinking_os db import failed: {exc}") from exc
+    conn = database.init_db()
+    try:
+        if not database.has_file_index_state_table(conn):
+            click.echo(
+                "[graph-reindex] file_index_state table missing (migration v17 not applied)."
+            )
+            return
+        rows = conn.execute(
+            "SELECT file_path, content_hash, extractor_chain, "
+            "last_indexed_at, last_error FROM file_index_state "
+            "ORDER BY last_indexed_at DESC LIMIT 50"
+        ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        click.echo("[graph-reindex] file_index_state is empty.")
+        return
+
+    click.echo(f"{'file_path':<60}  {'hash':<12}  {'indexed_at':<20}  status")
+    click.echo("-" * 110)
+    for file_path, chash, chain, ts, err in rows:
+        when = datetime.fromtimestamp(int(ts)).isoformat(timespec="seconds")
+        status = "error" if err else "ok"
+        chain_hint = chain[:20] + ("…" if len(chain) > 20 else "")
+        display = f"{file_path} [{chain_hint}]"
+        if len(display) > 60:
+            display = display[:57] + "..."
+        click.echo(f"{display:<60}  {chash[:12]:<12}  {when:<20}  {status}")
+
+
+def _serve_static(path: Path, *, port: int, open_browser: bool) -> None:
+    import socket
+    import webbrowser
+    from http.server import HTTPServer, SimpleHTTPRequestHandler
+
+    os.chdir(path.parent)
+
+    class _Handler(SimpleHTTPRequestHandler):
+        def log_message(self, *_args, **_kwargs):
+            pass
+
+    if port == 0:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", 0))
+            port = s.getsockname()[1]
+    httpd = HTTPServer(("127.0.0.1", port), _Handler)
+    url = f"http://127.0.0.1:{port}/{path.name}"
+    click.echo(f"[serve] {url}")
+    if open_browser:
+        webbrowser.open(url)
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        httpd.shutdown()
+        click.echo("\n[serve] bye")
+
+
+__all__ = ["register"]