feat(cli): add codegraph upgrade self-update + stale-index re-index hint (#710)

`codegraph upgrade [version]` detects how the CLI was installed — the standalone
install.sh/install.ps1 bundle, npm-global, npx, or a source checkout — and
updates in place: re-running the canonical install.sh on macOS/Linux, an
in-place rename-and-extract swap on Windows (a running node.exe can't be
deleted, only renamed, so the detached-helper approach is avoided), and
npm/npx/source-specific guidance otherwise. Flags: `--check` (report only),
`--force`, and a positional version to pin.

Each full index is now stamped with the engine's EXTRACTION_VERSION in
project_metadata; `codegraph status` (and `--json`) flags an index built by an
older engine and recommends re-indexing, and `upgrade` prints the same reminder.
Gated on EXTRACTION_VERSION so it never nags on extraction-neutral releases.

Validated end-to-end on macOS (real bundle upgrade), Linux (Docker, real
curl|sh) and Windows (Parallels VM, real in-place swap). 32 new unit tests.

Closes #679

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/extraction/extraction-version.ts

@@ -0,0 +1,24 @@
+/**
+ * Extraction version
+ *
+ * A monotonically-increasing integer that identifies the *shape and depth* of
+ * what the extractor writes into the graph. Unlike `CURRENT_SCHEMA_VERSION`
+ * (which tracks the SQLite table layout and is migrated in place), this tracks
+ * the EXTRACTED CONTENT — node kinds, edges, synthesizers, resolver coverage.
+ *
+ * When an index was built by an older engine whose `EXTRACTION_VERSION` is
+ * below the running engine's, the data on disk is structurally fine but
+ * *stale*: it's missing whatever a newer extractor would now produce. A schema
+ * migration can't backfill that — only a re-index can. So this is the signal
+ * `codegraph status` uses to recommend a re-index, and the reason `codegraph
+ * upgrade` reminds users to refresh their projects.
+ *
+ * BUMP THIS when a release changes extraction output enough that existing
+ * indexes should be rebuilt to benefit — e.g. a new language/framework
+ * extractor, a new dynamic-dispatch synthesizer, a new node/edge kind, or a
+ * resolver fix that materially changes which edges exist. Do NOT bump for
+ * pure bug fixes, CLI/UX changes, or schema-only migrations. Over-bumping
+ * turns the re-index hint into noise — keep it honest (see CLAUDE.md, "Honesty
+ * in the product is load-bearing").
+ */
+export const EXTRACTION_VERSION = 1;