usecix 1.0.6__tar.gz

usecix-1.0.6/LICENSE

@@ -0,0 +1,37 @@
+cix — Proprietary Software License
+Copyright (c) 2026 cix. All rights reserved.
+
+This software, including the cix client, command-line tools, MCP server,
+and all associated files (collectively, the "Software"), is the proprietary
+and confidential property of cix. The Software is licensed, not sold.
+
+This is NOT open-source software. It is NOT licensed under the MIT license,
+and it is NOT dual-licensed.
+
+1. Grant. Subject to a valid subscription and the cix Terms of Service, you
+   are granted a limited, non-exclusive, non-transferable, revocable license
+   to install and use the Software solely to interact with the cix cloud
+   service for your own internal development purposes.
+
+2. Restrictions. You may not, in whole or in part: (a) copy, redistribute,
+   sublicense, sell, rent, or lease the Software; (b) reverse engineer,
+   decompile, or disassemble the Software, or attempt to derive its source
+   code, parsing logic, or indexing heuristics; (c) create derivative works;
+   (d) remove or alter any proprietary notices; or (e) use the Software to
+   build a competing product.
+
+3. Ownership. All right, title, and interest in and to the Software,
+   including all intellectual property rights, remain exclusively with cix.
+
+4. Termination. This license terminates automatically if you breach any of
+   its terms. Upon termination you must cease all use and destroy all copies.
+
+5. No Warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+6. Limitation of Liability. IN NO EVENT SHALL cix BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY ARISING FROM OR IN CONNECTION WITH THE
+   SOFTWARE OR ITS USE.
+
+For licensing inquiries: legal@usecix.com

usecix-1.0.6/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: usecix
+Version: 1.0.6
+Summary: Git-anchored cloud-first code index + MCP for Claude, Codex, and Gemini
+License-Expression: LicenseRef-cix-Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: tqdm>=4.65
+Requires-Dist: watchfiles>=0.24
+Provides-Extra: remote
+Requires-Dist: uvicorn>=0.31; extra == "remote"
+Requires-Dist: starlette>=0.41; extra == "remote"
+Provides-Extra: db-pull
+Requires-Dist: psycopg[binary]>=3.1; extra == "db-pull"
+Requires-Dist: pymysql>=1.1; extra == "db-pull"
+Requires-Dist: pymongo>=4.6; extra == "db-pull"
+Requires-Dist: PyYAML>=6.0; extra == "db-pull"
+Provides-Extra: test
+Requires-Dist: testcontainers>=4.0; extra == "test"
+Requires-Dist: psycopg[binary]>=3.1; extra == "test"
+Requires-Dist: pymysql>=1.1; extra == "test"
+Requires-Dist: pymongo>=4.6; extra == "test"
+Requires-Dist: PyYAML>=6.0; extra == "test"
+Provides-Extra: build
+Requires-Dist: build>=1.0; extra == "build"
+Requires-Dist: nuitka>=2.0; extra == "build"
+Dynamic: license-file
+
+# cix
+
+**Git moves code. cix understands code. AI coding tools use cix to make safer changes.**
+
+cix is a code-intelligence layer that sits between Git and AI coding tools
+(Claude Code, Codex, Gemini). It indexes your committed source by Git commit
+and exposes it to your AI client as a set of structured tools — symbol search,
+navigation, schema lookup, impact analysis, and structured edits — so the
+assistant works from what your repository *actually* contains instead of
+guessing.
+
+## Why
+
+AI coding tools are strong at writing code in isolation and weak at
+understanding *your* repository. They re-read files they have already seen,
+reinvent helpers that already exist, import modules that were deprecated, or
+rename a function and miss half of its callers. cix gives the assistant a
+precise, current answer to "what does this repository mean right now?" — so it
+writes code that fits.
+
+## Install
+
+```bash
+pip install usecix
+```
+
+The heavy indexing runs in the cix cloud, not on your machine; the local
+package is a thin client that connects over HTTPS.
+
+## Quick start
+
+```bash
+# 1. Connect this machine to your cix account (opens a browser)
+cix login
+
+# 2. Register cix with your AI clients (Claude Code, Codex, Gemini)
+cix install --client all
+
+# 3. Restart your client so it picks up the cix tools
+
+# 4. In a project you want indexed
+cd ~/path/to/your/project
+cix index
+```
+
+Then open your AI client in that project and start working — it will use the
+cix tools to search, read by symbol, check schemas, and assess impact before
+editing.
+
+## Commands
+
+cix installs a single `cix` dispatcher; each subcommand is also available as
+`cix-<command>` (for example, `cix-index`).
+
+| Command | What it does |
+| --- | --- |
+| `cix login` | Authenticate and fetch credentials |
+| `cix install` | Install cix integrations (Claude, Codex, Gemini) |
+| `cix uninstall` | Remove cix integrations |
+| `cix index` | Build / update the index for the current project |
+| `cix mcp` | Run the cix MCP server (stdio) |
+| `cix serve` | Run the cix MCP server (remote SSE) |
+| `cix doctor` | Diagnose your cix install and project setup |
+| `cix config` | View / update per-project settings |
+
+Run `cix <command> --help` for details on any command.
+
+## Requirements
+
+- **Python 3.11+**
+- **Git** — cix indexes committed source and tracks freshness by commit.
+- **A GitHub-hosted repository** for the project you want indexed.
+- **A supported AI client** — Claude Code, Codex CLI, and/or Gemini CLI.
+- **A cix account** — `cix login` walks you through it.
+
+## License
+
+cix is proprietary software. See the bundled `LICENSE` file. It is not open
+source, and is not MIT- or dual-licensed.

usecix-1.0.6/README.md

@@ -0,0 +1,167 @@
+# cix — Code Index for Claude and Codex
+
+> **Git moves code. cix understands code. AI clients use cix to make safer changes.**
+
+cix is a semantic intelligence layer that sits between Git and AI coding tools (Claude Code, Codex, Gemini, ChatGPT, GitHub PR bots). It indexes committed source by Git SHA, exposes structured queries (symbols, routes, schemas, callers, impact), and validates AI-proposed edits before they hit the repo.
+
+> **Status:** cix is in **v0 (cloud-first preview)**. The cloud index, MCP tool surface, convention hooks, and per-edit validation are used daily on the dev project.
+
+> **Docs:** [Goals](docs/goals.md) · [Components](docs/components.md) · [Problem](docs/problem.md) · [Roadmap](docs/roadmap.md) · [Tools](docs/tools.md) · [Where content lives](docs/where_content_lives.md)
+
+---
+
+## How it works
+
+cix is split across four repos, but you only install one:
+
+- **`cix`** (this repo) — the thin client. CLI, MCP server, edit application, freshness gate. Ships to your machine via `pipx`.
+- **`cix-api`** — the cloud backend. Owns the parser, the indexer, and the symbol DB. Clones repos via Git provider OAuth, parses with the proprietary parser, stores the symbol graph in cloud Neon. Never ships to clients.
+- **`cix-cloud`** — auth, billing, telemetry, dashboard data feeds.
+- **`cix-web`** — the dashboard at usecix.com.
+
+When an AI tool calls a cix MCP tool (e.g. `search_code`), the local client routes it to cix-api. When you edit a file, the local client POSTs the new bytes to cix-api `/v1/validate`, which parses, returns ok/err, and populates an overlay index so the next read sees the fresh shape. The local process never holds the parser or the index — it's a thin client over the cloud.
+
+See [Components](docs/components.md) for the full architecture and [Goals](docs/goals.md) for the contract.
+
+---
+
+## What cix gives an AI agent
+
+Coding agents waste tokens rediscovering the same project on every prompt. They `Read` files they've read before, `Glob` directories that haven't moved, `Grep` strings whose home they already know. Each rediscovery costs latency, tokens, and — critically — context window.
+
+cix replaces those blind loops with indexed navigation against the cloud index:
+
+- **Search before write.** `search_code`, `get_symbol`, `find_usages` answer "does this exist? who calls it?" in milliseconds against a parser-built symbol graph that lives in cloud Neon.
+- **Read by symbol, not by file.** `get_symbol`, `get_file_outline` return only the slice the agent needs. A 500-line file becomes a 30-line symbol.
+- **Impact before edit.** `impact_analysis` answers "what would break if X changed?" — direct + transitive callers, affected HTTP routes, GraphQL handlers, tests, and data models, with a risk tier and reasons.
+- **Schema before query.** `get_schema` returns parsed table definitions for Laravel, Django, Alembic / SQLAlchemy, Prisma, EF Core (and surfaces ORM evidence when no concrete schema is indexed), raw SQL — so the agent stops inventing column names.
+- **Validation at edit time.** When the agent writes a file, the local cix client POSTs the new bytes to cix-api `/v1/validate`. Cloud parses, returns ok/err, and refreshes the overlay so the next read is current — no separate reindex step.
+- **Convention enforcement at write time.** A PreToolUse hook blocks writes that violate `conventions.json` folder/naming rules and blocks new files whose stem collides with an existing indexed symbol.
+- **Honest freshness.** Every read carries `canonical_sha` and `pending_edits`. cix never claims more certainty than it has.
+
+---
+
+## Quick start
+
+From zero to cix working inside Claude / Codex in about three minutes:
+
+```bash
+# 1. Install the package (pipx keeps it out of your project venvs)
+pipx install git+https://github.com/usecix/cix
+
+# 2. Register with your clients
+#    --client accepts: claude, codex, gemini, a comma-separated subset, or all
+cix-install --client all
+
+# 3. Connect this client to cix-api (one-time, opens a browser)
+cix-login
+
+# 4. Restart Claude Code, Codex, and/or Gemini CLI so they pick up the new MCP servers.
+
+# 5. Inside each project you want indexed
+cd ~/sites/myproject
+cix-init --client all
+#   ▸ kicks off a cloud index of the repo via cix-api (~30-60s)
+#   ▸ MCP picks up the canonical index automatically when ready
+
+# 6. Open your client in the project and start asking it to do things.
+```
+
+cix-init also installs a Git push-side hook so subsequent pushes to your default branch trigger an incremental reindex via the GitHub App webhook. Out-of-band edits (manual edits in another editor) trigger an overlay revalidation through the same path Claude / Codex go through.
+
+---
+
+## What to try first
+
+After install + `cix-init`, restart your client and give it a real task. You should see it call cix tools before reaching for `Read` / `Glob` / `Grep`. Good first prompts on a freshly indexed project:
+
+- *"Where is the user authentication handler?"* — should call `search_code` or `find_backend_handler`, not `Glob`.
+- *"Add a new component called X"* — should call `check_convention` and `search_code` before writing.
+- *"What columns are on the invoices table?"* — should call `get_schema` before answering.
+
+If the client jumps straight to file reads without calling cix, restart it (MCP servers load at client boot, not at `/clear`) and re-run `cix-doctor` to confirm registration + cix-api connectivity.
+
+After a `git pull`: run `cix catchup` for a backward-looking briefing — new routes / removed services / schema changes since your last visit. Pair with `--mine` to filter to deltas your current branch touches. Team-tier; see [`docs/feature_cix_catchup.md`](docs/feature_cix_catchup.md).
+
+---
+
+## What works today
+
+- **Cloud index via cix-api.** GitHub App OAuth → clone → parse → write to cloud Neon. Push webhook reindexes incrementally.
+- **MCP tool surface** for symbol search, navigation, schema lookup, file outlines, impact analysis, structured edits, and refactor-rename. All routed through cix-api. Full list in [Tools](docs/tools.md).
+- **Per-edit validation.** When the agent writes a file, the local client POSTs to cix-api `/v1/validate` and surfaces ok/err. No separate reindex step.
+- **Pre-commit impact summary.** Every `git commit` prints a one-line headline plus a per-symbol caller tree before the commit lands — `Impact: 3 symbols changed, 14 callers affected across 2 files` and the routes / schema columns touched. Always exits 0 so it informs but never blocks. Configurable via `.cix/config.json` (`precommit.enabled`, `precommit.warn_threshold`, `precommit.max_callers_per_symbol`).
+- **Silent Diff pre-commit guard.** Same hook, narrower job: interrupts only when your staged change deletes / renames / breaks the signature of a symbol that still has callers in files you haven't touched in the same commit. `[y]` continues, `[n]` aborts, `[show me]` expands. Fail-open on stale index / unreachable service / no TTY. Toggle with `cix config --no-guard`. See [feature_silent_diff.md](docs/feature_silent_diff.md).
+- **Convention enforcement.** A PreToolUse hook blocks writes that violate `conventions.json` folder / naming rules, and blocks new files whose filename stem collides with an existing indexed symbol.
+- **DB schema indexing** for Laravel, Django, Alembic / SQLAlchemy, Prisma, EF Core, and raw SQL. `get_schema` returns parsed table definitions; the instruction docs tell the client to call it before any model / migration / query.
+- **Freshness metadata on every response** — `canonical_sha`, `pending_edits`, `trust_level`, `stale` — so the agent knows when to trust cix and when to re-check.
+- **Multi-client support.** Claude Code, Codex CLI, Gemini CLI all get the MCP tools. Hooks (PreToolUse convention block, PostToolUse validate, SessionStart guide) are currently Claude-only.
+
+See [Tools](docs/tools.md) for the full surface and [Components](docs/components.md) for the architecture.
+
+---
+
+## Known beta limitations
+
+- **First-time index requires a Git remote.** cix-api clones the repo via the GitHub App. Repos without a remote — or repos behind a Git host we don't yet support — won't index. GitLab and Bitbucket OAuth are on the v1 path but not landed; today, GitHub-hosted repos only.
+- **Hooks are Claude-only.** Codex and Gemini get the MCP tools but not the PreToolUse convention block, the PostToolUse validate, or the SessionStart tool-order guide. Parity is on the roadmap; it is not done.
+- **No PyPI release yet.** Install is `pipx install git+https://...`. Tag-and-publish to PyPI lands with the v0.1 ship.
+
+---
+
+## How to report useful failures
+
+A good failure report is reproducible by someone who has never seen your project. Please include:
+
+1. **The literal prompt** you gave the agent — not a paraphrase.
+2. **The cix tool call and its raw response** — including the `canonical_sha`, `pending_edits`, `trust_level`, `stale`, and `error_code` fields. If the agent skipped cix entirely, say so explicitly.
+3. **What the file or symbol actually looks like on disk** at the moment of the call — paste the relevant span or attach the file.
+4. **`cix-doctor` output** — captures install mode, cix-api connectivity, and client registration.
+5. **The cix version** — `pipx list | grep cix` or `pip show cix`.
+
+What we don't need: long IDE transcripts, screenshots, or "it felt slow." A five-line repro is worth more than a 500-line trace.
+
+---
+
+## Requirements
+
+- **Python 3.11+** — cix uses 3.11 stdlib features (`tomllib` and friends). `python3 --version` to check.
+- **Git** — cix's freshness model and the canonical reindex both rely on a Git remote.
+- **A GitHub-hosted repo** for the project you want indexed. GitLab and Bitbucket are on the v1 path; not yet supported.
+- **A coding-agent client** — Claude Code, Codex CLI, and / or Gemini CLI. `cix-install` configures whichever you have.
+- **A cix account** — `cix-login` walks you through it (free tier covers one public repo).
+- **pipx** (recommended for install) — see [Why pipx](#why-pipx) below. Plain `pip` works too — see [Don't want pipx? Use pip](#dont-want-pipx-use-pip).
+
+### Why pipx
+
+cix is a CLI tool, not a Python library you `import` from your code. `pipx` installs it into an isolated virtualenv and links the entry points (`cix`, `cix-init`, `cix-doctor`, `cix-mcp`) onto your `PATH`. Three concrete benefits:
+
+- **No dependency collisions.** cix pins `tree-sitter`, `httpx`, and a handful of other libraries. With pipx those pins live in cix's own venv — they can't fight whatever your project venv pins.
+- **Runnable from any cwd.** MCP clients spawn `cix-mcp` directly. No `cd ~/sites/cix && source venv/bin/activate` step before each run.
+- **Clean upgrades and uninstalls.** `pipx upgrade cix` or `pipx uninstall cix` touches only cix's own venv — nothing else on the system.
+
+It's the same install model as `ruff`, `black`, `poetry`, and most other CLI-first Python tools. To install pipx itself: `brew install pipx` on macOS, or `python3 -m pip install --user pipx && python3 -m pipx ensurepath` elsewhere.
+
+### Don't want pipx? Use pip
+
+Plain `pip` in a virtualenv works too:
+
+```bash
+python3 -m venv ~/.local/cix-venv
+~/.local/cix-venv/bin/pip install git+https://github.com/usecix/cix
+
+# Then either put the venv's bin dir on PATH:
+echo 'export PATH="$HOME/.local/cix-venv/bin:$PATH"' >> ~/.zshrc
+# ...or symlink the entry points individually into ~/.local/bin.
+```
+
+Installing into a project's existing venv or your global Python also works — but you take on the responsibility of keeping cix's dependencies from clashing with whatever else you have installed there. We don't recommend `sudo pip install` into the system Python on any platform.
+
+---
+
+## Start here
+
+- **New to cix?** Read [The Problem](docs/problem.md) — why this exists.
+- **Want the architecture?** [Components](docs/components.md) covers the four-repo split and the IP boundary.
+- **Want the contract?** [Goals](docs/goals.md) lists the five invariants and the v1 done criteria.
+- **Where are we headed?** [Roadmap](docs/roadmap.md) is the phased migration plan.

usecix-1.0.6/README.pypi.md

@@ -0,0 +1,79 @@
+# cix
+
+**Git moves code. cix understands code. AI coding tools use cix to make safer changes.**
+
+cix is a code-intelligence layer that sits between Git and AI coding tools
+(Claude Code, Codex, Gemini). It indexes your committed source by Git commit
+and exposes it to your AI client as a set of structured tools — symbol search,
+navigation, schema lookup, impact analysis, and structured edits — so the
+assistant works from what your repository *actually* contains instead of
+guessing.
+
+## Why
+
+AI coding tools are strong at writing code in isolation and weak at
+understanding *your* repository. They re-read files they have already seen,
+reinvent helpers that already exist, import modules that were deprecated, or
+rename a function and miss half of its callers. cix gives the assistant a
+precise, current answer to "what does this repository mean right now?" — so it
+writes code that fits.
+
+## Install
+
+```bash
+pip install usecix
+```
+
+The heavy indexing runs in the cix cloud, not on your machine; the local
+package is a thin client that connects over HTTPS.
+
+## Quick start
+
+```bash
+# 1. Connect this machine to your cix account (opens a browser)
+cix login
+
+# 2. Register cix with your AI clients (Claude Code, Codex, Gemini)
+cix install --client all
+
+# 3. Restart your client so it picks up the cix tools
+
+# 4. In a project you want indexed
+cd ~/path/to/your/project
+cix index
+```
+
+Then open your AI client in that project and start working — it will use the
+cix tools to search, read by symbol, check schemas, and assess impact before
+editing.
+
+## Commands
+
+cix installs a single `cix` dispatcher; each subcommand is also available as
+`cix-<command>` (for example, `cix-index`).
+
+| Command | What it does |
+| --- | --- |
+| `cix login` | Authenticate and fetch credentials |
+| `cix install` | Install cix integrations (Claude, Codex, Gemini) |
+| `cix uninstall` | Remove cix integrations |
+| `cix index` | Build / update the index for the current project |
+| `cix mcp` | Run the cix MCP server (stdio) |
+| `cix serve` | Run the cix MCP server (remote SSE) |
+| `cix doctor` | Diagnose your cix install and project setup |
+| `cix config` | View / update per-project settings |
+
+Run `cix <command> --help` for details on any command.
+
+## Requirements
+
+- **Python 3.11+**
+- **Git** — cix indexes committed source and tracks freshness by commit.
+- **A GitHub-hosted repository** for the project you want indexed.
+- **A supported AI client** — Claude Code, Codex CLI, and/or Gemini CLI.
+- **A cix account** — `cix login` walks you through it.
+
+## License
+
+cix is proprietary software. See the bundled `LICENSE` file. It is not open
+source, and is not MIT- or dual-licensed.

usecix-1.0.6/apps/cli/cix/scripts/_cloud_wait.py

@@ -0,0 +1,271 @@
+"""Poll a cix-api reindex job to completion, emitting one line per phase.
+
+Shared by cix-init's _kick_cloud_index and cix-index's full-reindex
+trigger so customers get the same UX (and the same Ctrl-C escape
+hatch) regardless of which entry point started the job.
+
+Cloud reindex jobs are async: the kickoff endpoint returns a job_id
+immediately, the orchestrator runs in a Vercel sandbox for ~30-60s,
+then writes status back. We print a line each time the backend reports
+a new heartbeat stage — no fake percentage, no spinner pinned at 100%.
+"""
+
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from cix.cloud.config import CloudConfig
+from cix.cloud.transport import TransportError, TransportNotConfigured, repos_index_job
+
+
+POLL_INTERVAL_S = 2
+TIMEOUT_S = 300
+
+
+def wait_for_index_job(
+    config: CloudConfig,
+    job_id: str,
+    *,
+    label: str = "Indexing",
+    bar_indent: str = "  ",
+    out=None,
+) -> dict[str, Any] | None:
+    """Poll ``/v1/repos/index/{job_id}`` until the job finishes.
+
+    Returns the final job row on success/failed, or ``None`` if the
+    user interrupted (Ctrl-C) or the wait timed out. In every
+    non-success case we print a one-line note so the customer knows
+    where things stand.
+
+    Emits one line per backend phase transition (sourced from the
+    indexer's heartbeat ``last_heartbeat_stage``) so the user sees real
+    motion through the run rather than a fake percentage:
+
+        {indent}→ preparing sandbox
+        {indent}→ cloning repo
+        {indent}→ refreshing files (3/17)
+        {indent}→ finalizing
+
+    Before the indexer posts its first heartbeat the job row carries
+    no stage (the sandbox is still booting/cloning), so we emit
+    "preparing sandbox" up-front — otherwise the first seconds of every
+    run read as a silent freeze. When the backend exposes no stage
+    detail at all we degrade to that single line.
+
+    On timeout we print the last observed phase and how long the
+    heartbeat has been frozen — a stuck sandbox (heartbeat age ≈ the
+    whole wait) reads very differently from a genuinely slow one
+    (heartbeat still advancing), and that distinction is the first
+    thing an operator needs.
+    """
+    out = out or sys.stdout
+    t0 = time.time()
+    current_stage: str | None = None
+    last_resp: dict[str, Any] | None = None
+    print(f"{bar_indent}→ preparing sandbox", file=out, flush=True)
+    try:
+        while True:
+            elapsed = int(time.time() - t0)
+            if elapsed > TIMEOUT_S:
+                print(_timeout_note(bar_indent, elapsed, last_resp), file=out)
+                return None
+
+            try:
+                resp = repos_index_job(config, job_id=job_id)
+            except (TransportError, TransportNotConfigured):
+                # Treat transient network errors as a missed poll, not a fatal
+                # condition. The job is still running cloud-side.
+                resp = None
+
+            if resp:
+                last_resp = resp
+                status = resp.get("status")
+                if status in ("success", "failed"):
+                    return resp
+                stage = resp.get("last_heartbeat_stage")
+                if stage and stage != current_stage:
+                    current_stage = stage
+                    print(
+                        f"{bar_indent}→ {_stage_label(stage)}",
+                        file=out,
+                        flush=True,
+                    )
+            time.sleep(POLL_INTERVAL_S)
+    except KeyboardInterrupt:
+        print(
+            f"\n{bar_indent}→ {label} continues cloud-side (job={job_id[:12]}); "
+            f"check with `cix-index`.",
+            file=out,
+        )
+        return None
+
+
+
+def print_job_result(
+    final: dict[str, Any] | None,
+    *,
+    started_at: float,
+    label: str = "Index",
+    indent: str = "  ",
+    out=None,
+) -> None:
+    """Pretty-print the outcome of a wait_for_index_job call.
+
+    Separated from ``wait_for_index_job`` so callers that want to
+    customise the success/failure messaging can omit it. ``started_at``
+    is the wall-clock time the wait began; used to render duration.
+    """
+    if final is None:
+        # Already printed a note inside wait_for_index_job.
+        return
+    out = out or sys.stdout
+    elapsed = max(0, int(time.time() - started_at))
+    status = final.get("status")
+    mode = final.get("mode")  # may be None on older cix-api responses
+    if status == "skip":
+        # Server short-circuited because nothing changed since the last
+        # cloud index. No sandbox provisioned, no work done.
+        print(f"{indent}✓ No changes to index — skipped ({elapsed}s).", file=out)
+        return
+    if status == "success":
+        symbols = final.get("symbol_count")
+        symbols_str = f"{symbols:,}" if isinstance(symbols, int) else "?"
+        if mode == "incremental":
+            files_touched = final.get("files_touched")
+            if isinstance(files_touched, int):
+                plural = "" if files_touched == 1 else "s"
+                # "5,446 total symbols" makes clear the count is the
+                # repo-wide total, not what this run processed.
+                print(
+                    f"{indent}✓ Indexed {files_touched} file{plural}; "
+                    f"{symbols_str} total symbols ({elapsed}s).",
+                    file=out,
+                )
+            else:
+                # Old job rows pre-files_touched column. Fall back gracefully.
+                print(
+                    f"{indent}✓ Indexed (incremental); {symbols_str} total symbols "
+                    f"({elapsed}s).",
+                    file=out,
+                )
+        elif mode == "full_rebuild":
+            print(
+                f"{indent}✓ Indexed {symbols_str} symbols (full rebuild, {elapsed}s).",
+                file=out,
+            )
+        else:
+            # Old cix-api response without mode field — keep prior phrasing.
+            suffix = f"{symbols_str} symbols" if symbols_str != "?" else "indexed"
+            print(f"{indent}✓ {label} ready ({suffix}, {elapsed}s).", file=out)
+        return
+    # Failure path. Surface the stage the job died at (strip the
+    # 'stopped-by:' marker prefix so the user sees a clean label) and
+    # the error message tail.
+    err = (final.get("error_message") or "").strip()
+    if err:
+        err = err.splitlines()[-1][:200]
+    stage = (final.get("last_heartbeat_stage") or "").strip()
+    if stage.startswith("stopped-by:"):
+        stage = stage[len("stopped-by:"):]
+    if stage:
+        print(
+            f"{indent}✗ {label} failed at {stage} (+{elapsed}s): "
+            f"{err or status}",
+            file=out,
+        )
+    else:
+        print(f"{indent}✗ {label} failed after {elapsed}s: {err or status}", file=out)
+
+def _stage_label(stage: str) -> str:
+    """Map sandbox/indexer.py heartbeat stages to short human labels.
+
+    The indexer emits granular incremental stages (per-file refresh) and
+    coarser full-rebuild stages. We translate both into the honest, stable
+    vocabulary the user sees: preparing sandbox -> cloning repo -> detecting
+    changes -> refreshing files -> shipping batches -> finalizing -> wrapping
+    up. Unknown stages fall through as-is so a new heartbeat added cloud-side
+    still shows something useful before the CLI knows the new name.
+
+    The per-file incremental stage is "incremental-file-{idx}/{total}" — we
+    surface the "{idx}/{total}" counter as "refreshing files (3/17)" so the
+    user sees real, honest motion through the changed set rather than a raw
+    slug. No fake precision: the counter is the indexer's own file index.
+    """
+    if stage.startswith("incremental-file-"):
+        progress = stage[len("incremental-file-"):]
+        return f"refreshing files ({progress})"
+    return {
+        "starting": "starting",
+        "initializing": "starting",
+        "cloning": "cloning repo",
+        "clone-done": "preparing",
+        "incremental-starting": "detecting changes",
+        "incremental-done": "refreshing files",
+        "shipping-batches": "shipping batches",
+        "schema-extracting": "reading schema",
+        "history-walking": "recording history",
+        "index-status-posting": "finalizing",
+        "index-status-unconfirmed": "finalizing (retrying)",
+        "finalize-posting": "finalizing",
+        "commits-posting": "wrapping up",
+        "shutdown-signaling": "wrapping up",
+    }.get(stage, stage)
+
+def _heartbeat_age_s(last_heartbeat_at: Any) -> int | None:
+    """Seconds since the indexer last emitted a heartbeat.
+
+    ``last_heartbeat_at`` is the ISO-8601 string from the job row
+    (``_serialise`` in cix-api). Returns None if absent or unparseable
+    so callers can fall back to a stage-only message. A large value is
+    the signal that the sandbox wedged rather than merely running slow.
+    """
+    if not isinstance(last_heartbeat_at, str) or not last_heartbeat_at.strip():
+        return None
+    try:
+        hb = datetime.fromisoformat(last_heartbeat_at)
+    except ValueError:
+        return None
+    if hb.tzinfo is None:
+        hb = hb.replace(tzinfo=timezone.utc)
+    return max(0, int((datetime.now(timezone.utc) - hb).total_seconds()))
+
+def _timeout_note(
+    bar_indent: str,
+    elapsed: int,
+    last_resp: dict[str, Any] | None,
+) -> str:
+    """Build the message printed when the CLI poll wait exceeds TIMEOUT_S.
+
+    Replaces the old "still running after Ns" line, which discarded the
+    stage/heartbeat data the poll already had in hand. We now surface:
+
+      * the last phase the indexer reported (``last_heartbeat_stage``),
+      * how long that heartbeat has been frozen.
+
+    A heartbeat age close to ``elapsed`` means the sandbox wedged at
+    that phase (stuck); an age that keeps tracking the poll interval
+    means the job is merely slow. That one number is what tells an
+    operator which of the two they're looking at.
+    """
+    lines = [f"{bar_indent}⚠ Indexing still running after {elapsed}s."]
+    if last_resp:
+        stage = (last_resp.get("last_heartbeat_stage") or "").strip()
+        age = _heartbeat_age_s(last_resp.get("last_heartbeat_at"))
+        if stage:
+            phase = _stage_label(stage)
+            if age is not None:
+                frozen = " — heartbeat frozen" if age >= 30 else ""
+                lines.append(
+                    f"{bar_indent}  Last phase: {phase} "
+                    f"(no heartbeat for {age}s{frozen})."
+                )
+            else:
+                lines.append(f"{bar_indent}  Last phase: {phase}.")
+        elif age is not None:
+            lines.append(f"{bar_indent}  No heartbeat for {age}s.")
+    lines.append(
+        f"{bar_indent}  Job will keep running cloud-side; "
+        f"check later with `cix-index`."
+    )
+    return "\n".join(lines)