Merge pull request #1361 from Hellblazer/release/v6.3.1

release: conexus 6.3.1

Author: Hellblazer

.claude-plugin/marketplace.json

@@ -11,21 +11,21 @@
         "source": "git-subdir",
         "url": "https://github.com/Hellblazer/nexus.git",
         "path": "conexus",
-        "ref": "v6.3.0"
+        "ref": "v6.3.1"
       },
       "description": "Self-hosted three-tier knowledge management with 13 specialized agents, plan-centric retrieval via nx_answer, semantic search, and RDR decision tracking for Claude Code.",
-      "version": "6.3.0"
+      "version": "6.3.1"
     },
     {
       "name": "sn",
       "source": {
         "source": "git-subdir",
         "url": "https://github.com/Hellblazer/nexus.git",
         "path": "sn",
-        "ref": "v6.3.0"
+        "ref": "v6.3.1"
       },
       "description": "Injects Serena and Context7 MCP tool usage guidance into subagents via SubagentStart hook.",
-      "version": "6.3.0"
+      "version": "6.3.1"
     }
   ]
 }

.github/workflows/engine-service-release.yml

@@ -423,13 +423,36 @@ jobs:
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
 
-      - name: Build PG + pgvector bundle and package .txz
+      # nexus-m8au7: PG_VERSION + PGVECTOR_VERSION are pinned constants that
+      # rarely change across tags, yet every tag recompiled both from source
+      # (~10-20 min/arch). Cache the COMPILED PREFIX keyed on everything that
+      # determines its content: versions, arch, builder image, and the build
+      # script itself (the script does the macOS relocatability fixup — a
+      # script change MUST invalidate the cache, or a stale bundle would ship
+      # the exact 2026-07-01 dyld-abort class again). On a hit the compile is
+      # skipped; packaging, the relocation gate, signing, and upload still run
+      # per release, so the one-cosign-identity contract and per-release
+      # acquisition URLs are unchanged, and the relocation gate stays the
+      # safety net against a stale/poisoned cache entry.
+      # restore-ONLY (review finding): tag-scoped cache saves can never be
+      # restored (tags only read default-branch caches), so a save here is
+      # pure quota waste against the repo's 10GB budget and can evict the
+      # legit main-scoped entries. Only pg-bundle-cache-seed.yml saves.
+      - name: Restore compiled PG bundle cache
+        id: pg-bundle-cache
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5
+        with:
+          path: bundle
+          key: pg-bundle-${{ matrix.target.arch }}-${{ matrix.target.runner }}-pg${{ env.PG_VERSION }}-pgvector${{ env.PGVECTOR_VERSION }}-img-${{ matrix.target.image || 'native' }}-${{ hashFiles('scripts/build_pg_bundle.sh') }}
+
+      - name: Build PG + pgvector bundle (cache miss only)
+        if: steps.pg-bundle-cache.outputs.cache-hit != 'true'
         env:
           MANYLINUX_IMAGE: ${{ matrix.target.image }}
         run: |
           set -euo pipefail
           bundle="$GITHUB_WORKSPACE/bundle"
-          mkdir -p "$bundle" dist
+          mkdir -p "$bundle"
           if [ -n "$MANYLINUX_IMAGE" ]; then
             # linux: build inside manylinux_2_28 so the binaries' glibc floor is
             # 2.28 (broad compatibility), exactly as ci.yml's CA-3 gate builds them.
@@ -445,6 +468,32 @@ jobs:
             # applies MACOSX_DEPLOYMENT_TARGET). GH macOS runners have no Docker.
             BUNDLE_PREFIX="$bundle" bash scripts/build_pg_bundle.sh
           fi
+
+      - name: Package .txz
+        run: |
+          set -euo pipefail
+          bundle="$GITHUB_WORKSPACE/bundle"
+          mkdir -p dist
+          # Cache-hit sanity: a restored prefix must actually contain the PG
+          # toolchain; an empty/partial restore fails loud here rather than
+          # shipping a hollow .txz (the relocation gate below would also catch
+          # it, but this points at the cache instead of at relocation).
+          if [ ! -x "$bundle/bin/initdb" ]; then
+            echo "::error::bundle/bin/initdb missing — cache restored a hollow prefix or the build did not run"
+            exit 1
+          fi
+          # nexus-u30zm (critique Critical): a cache hit skips the build
+          # script's verify_and_mark(), which is the only place contrib
+          # completeness was asserted — a partial restore that kept initdb
+          # and vector but lost pg_trgm would otherwise sign + ship broken
+          # (RDR-155 needs pg_trgm). Mirror verify_and_mark here.
+          sharedir="$("$bundle/bin/pg_config" --sharedir)"
+          for ctl in vector pg_trgm; do
+            if [ ! -f "$sharedir/extension/$ctl.control" ]; then
+              echo "::error::$ctl.control missing from bundle — contrib set incomplete (cache corruption or build regression)"
+              exit 1
+            fi
+          done
           # -C parent + basename preserves the relative bin/ lib/ share/ layout
           # relocation depends on (identical to ci.yml packaging).
           tar -cJf "dist/$ASSET.txz" -C "$(dirname "$bundle")" "$(basename "$bundle")"
@@ -494,6 +543,10 @@ jobs:
           # bare "vector" this assertion originally (incorrectly) expected.
           "$root/bin/psql" -h "$sock" -p 59987 -U "$(id -un)" -d postgres -c \
             "CREATE EXTENSION IF NOT EXISTS vector" >/dev/null
+          # nexus-u30zm: pg_trgm must LOAD, not merely exist on disk — the
+          # cache-hit path has no other executable proof of the contrib set.
+          "$root/bin/psql" -h "$sock" -p 59987 -U "$(id -un)" -d postgres -c \
+            "CREATE EXTENSION IF NOT EXISTS pg_trgm" >/dev/null
           out="$("$root/bin/psql" -h "$sock" -p 59987 -U "$(id -un)" -d postgres -tAc \
             "SELECT extname FROM pg_extension WHERE extname='vector'")"
           if [ "$out" != "vector" ]; then

.github/workflows/pg-bundle-cache-seed.yml

@@ -0,0 +1,101 @@
+# nexus-m8au7: seed + keep-warm the compiled PG-bundle cache on MAIN.
+#
+# WHY THIS WORKFLOW EXISTS — GitHub Actions cache isolation: a run triggered
+# by a tag can only RESTORE caches created on the same ref or on the DEFAULT
+# branch (main). Caches saved by one engine-service tag run are invisible to
+# the next tag, so engine-service-release.yml's cache step can only ever hit
+# entries seeded here. Eviction is 7-days-unused; engine tags are often
+# further apart, hence the weekly cron keep-warm.
+#
+# The cache key MUST stay byte-identical to the one in
+# engine-service-release.yml (build-publish-pg-bundle job):
+#   pg-bundle-<arch>-pg<PG_VERSION>-pgvector<PGVECTOR_VERSION>-img-<image|native>-<sha256 of scripts/build_pg_bundle.sh>
+# PG_VERSION / PGVECTOR_VERSION are duplicated across ci.yml, the release
+# workflow, and here (the pre-existing duplication pattern; the build script
+# holds the defaults). Bumping a version in the release workflow WITHOUT
+# bumping it here just means a cache miss at the next tag (graceful — it
+# compiles as before); the versions live in the key precisely so a stale
+# bundle of the WRONG version can never be restored silently.
+name: pg-bundle-cache-seed
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/build_pg_bundle.sh'
+      - '.github/workflows/pg-bundle-cache-seed.yml'
+  schedule:
+    # Weekly keep-warm (Mondays 07:23 UTC — off the hour to dodge cron rush).
+    - cron: '23 7 * * 1'
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+
+jobs:
+  seed:
+    name: Seed PG bundle cache (${{ matrix.target.arch }})
+    runs-on: ${{ matrix.target.runner }}
+    timeout-minutes: 40
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - { arch: linux-amd64, runner: ubuntu-latest,    image: "quay.io/pypa/manylinux_2_28_x86_64" }
+          - { arch: linux-arm64, runner: ubuntu-24.04-arm, image: "quay.io/pypa/manylinux_2_28_aarch64" }
+          - { arch: mac-arm64,   runner: macos-14,         image: "" }
+    env:
+      # Pinned identically to engine-service-release.yml + ci.yml (see header).
+      PG_VERSION: "17.5"
+      PGVECTOR_VERSION: "v0.8.2"
+    steps:
+      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd  # v5
+
+      - name: Restore/claim cache slot
+        id: pg-bundle-cache
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5
+        with:
+          path: bundle
+          key: pg-bundle-${{ matrix.target.arch }}-${{ matrix.target.runner }}-pg${{ env.PG_VERSION }}-pgvector${{ env.PGVECTOR_VERSION }}-img-${{ matrix.target.image || 'native' }}-${{ hashFiles('scripts/build_pg_bundle.sh') }}
+
+      - name: Compile PG + pgvector (cache miss only)
+        if: steps.pg-bundle-cache.outputs.cache-hit != 'true'
+        env:
+          MANYLINUX_IMAGE: ${{ matrix.target.image }}
+        run: |
+          set -euo pipefail
+          bundle="$GITHUB_WORKSPACE/bundle"
+          mkdir -p "$bundle"
+          if [ -n "$MANYLINUX_IMAGE" ]; then
+            # Identical build environment to engine-service-release.yml:
+            # manylinux_2_28 for the glibc-2.28 floor.
+            docker run --rm \
+              -e PG_VERSION -e PGVECTOR_VERSION -e BUNDLE_PREFIX="$bundle" \
+              -v "$GITHUB_WORKSPACE:$GITHUB_WORKSPACE" \
+              "$MANYLINUX_IMAGE" /bin/bash -c '
+                set -eux
+                bash "'"$GITHUB_WORKSPACE"'/scripts/build_pg_bundle.sh"
+              '
+          else
+            BUNDLE_PREFIX="$bundle" bash scripts/build_pg_bundle.sh
+          fi
+
+      - name: Sanity-check the prefix before it becomes the cached artifact
+        if: steps.pg-bundle-cache.outputs.cache-hit != 'true'
+        run: |
+          set -euo pipefail
+          if [ ! -x "bundle/bin/initdb" ] || [ ! -x "bundle/bin/pg_ctl" ]; then
+            echo "::error::compiled prefix is missing the PG toolchain — refusing to seed a hollow cache"
+            exit 1
+          fi
+          # nexus-u30zm: contrib completeness (mirrors verify_and_mark). The
+          # actions/cache post-save runs with post-if: success() (verified
+          # upstream), so an exit 1 here genuinely prevents the seed.
+          sharedir="$(bundle/bin/pg_config --sharedir)"
+          for ctl in vector pg_trgm; do
+            if [ ! -f "$sharedir/extension/$ctl.control" ]; then
+              echo "::error::$ctl.control missing — refusing to seed an incomplete contrib set"
+              exit 1
+            fi
+          done
+          echo "prefix ok — cache will be saved on job success"

CHANGELOG.md

@@ -6,6 +6,59 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [6.3.1] - 2026-07-04
+
+The shakeout-follow-ups release (epic nexus-c0twp). Everything the 6.3.0 live
+shakeout deferred, plus everything the new safety nets caught while building
+them. Pins engine-service-v0.1.22 (cloud-gated 2026-07-04).
+
+### Fixed
+- `nx t3 gc` no longer crashes in service mode — local event-log emission is
+  skipped when the catalog is service-backed (live-shakeout finding #4).
+- `nx store put` no longer loses aspect extraction on fresh notes: the document
+  hook chain carries the catalog doc_id, not the T3 chunk id, so the engine's
+  FK accepts the enqueue (nexus-w8lg1); the enqueue-failure warning is one line
+  (traceback at debug).
+- `nx collection re-embed` and the chash backfill no longer crash on
+  `db._client` (absent from every production handle post-RDR-155); service-mode
+  re-embed is same-model-only via the verbatim vector passthrough, and a
+  cross-model `--to` fails loud with correct guidance instead of silently
+  re-embedding with the wrong model (nexus-c9xr2, nexus-u37lw, nexus-tcvpn).
+- `nx collection rename` rejects same-prefix renames whose embedding-model
+  segment differs — rename never re-embeds, so the vectors would silently stay
+  in the old model space (nexus-tcvpn).
+- HttpCatalogClient shape drifts vs the local catalog fixed across 9 methods:
+  `graph`/`graph_many` return typed entries/links (the service-mode links CLI
+  was silently broken), `collection_health_meta` no longer drops
+  `stale_source_ratio`, `validate_link` returns error lists,
+  `legacy_grandfathered` is a bool, `descendants` rows are normalized, and
+  chunk-address `resolve_chunk` works against the new engine route
+  (nexus-u26b4, nexus-gc2ze).
+
+### Added
+- Bounded per-file indexing concurrency: 2 workers by default when both the
+  vectors and catalog backends are the HTTP service; `NX_INDEX_CONCURRENCY`
+  overrides; hook chains and progress callbacks are serialized;
+  `--debug-timing` gains a `hooks_s` bucket (nexus-cfc72).
+- Mechanized runtime return-shape tripwire across the shared
+  Catalog/HttpCatalogClient surface (72 registered parity entries + audited
+  exclusions + a completeness gate), with a T3-backed leg for span/chash
+  resolution (nexus-8y1tm, nexus-oq0tk).
+
+### Changed
+- Warm `nx index repo` no longer pays ~1,400–2,800 serial catalog round-trips
+  per run: one owner-scoped list + local join in both the registration hook
+  and the frecency map, and unchanged files skip their per-file catalog
+  update entirely (nexus-dst5h).
+- Pinned engine advances to engine-service-v0.1.22: aspect-queue linkage
+  preserved across doc_id-less re-enqueues, `/resolve_chunk`, metadata
+  updates MERGE like the local catalog (previously a silent-replace data-loss
+  class in service mode), and full raw-SQL elimination in the engine
+  (nexus-nyout, nexus-gc2ze, nexus-ke45f, nexus-xtmtf, nexus-mzuj9).
+- Engine release workflow caches the compiled PG bundle across tags
+  (nexus-m8au7).
+
+
 ## [6.3.0] - 2026-07-03
 
 The service-mode seam-closure release (epic nexus-h8rf6). The first systematic

conexus/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "conexus",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "description": "Self-hosted three-tier knowledge management with plan-centric retrieval (nx_answer), specialized agents, semantic search, and RDR decision tracking for Claude Code.",
   "author": {
     "name": "Hal Hildebrand",

conexus/CHANGELOG.md

@@ -6,10 +6,16 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [6.3.1] - 2026-07-04
+
+Plugin version aligned with conexus 6.3.1. No plugin-side changes.
+
 ## [6.3.0] - 2026-07-03
 
 Plugin version aligned with conexus 6.3.0. No plugin-side changes.
 
+
+
 ## [6.2.0] - 2026-07-02
 
 Plugin version aligned with conexus 6.2.0. No conexus-plugin-side changes —

docs/cli-reference.md

@@ -82,6 +82,8 @@ nx index repo ./my-project
 | `--frecency-only` | Update frecency scores only; skip re-embedding (faster, for re-ranking refresh). Mutually exclusive with `--force` |
 | `--force-stale` | Re-index only if collection pipeline version is outdated (smart force — skips current collections) |
 | `--on-locked {skip,wait}` | Behavior under contention (default: `wait`). Per-repo advisory lock (two `nx index repo` on the same repo): `skip` exits immediately, `wait` blocks. Catalog-write fairness (RDR-146): when a foreground interactive catalog write is pending, `skip` defers this run's catalog writes to the next idempotent pass, `wait` proceeds after a bounded yield. `NX_WRITE_PRIORITY=interactive|batch` overrides the tty-based priority of a run's catalog writes. |
+
+Per-file indexing runs with bounded concurrency (6.3.1, nexus-cfc72): 2 workers by default when both the vectors and catalog backends are the HTTP service, 1 otherwise. `NX_INDEX_CONCURRENCY=N` overrides (a warning is logged when it forces concurrency past the backend gate). Progress callbacks and post-store hook chains are serialized; `--debug-timing` gains a `hooks_s` bucket so hook-serialization wait is visible separately from upload time.
 | `--no-taxonomy` | Skip automatic topic discovery after indexing |
 | `--debug-timing` | Emit an end-of-run per-stage breakdown to stderr (chunking / embed / upload / retry seconds per file, aggregated with percentages). Instruments code, prose, and PDF per-file paths — silent without the flag. Use when investigating "why did indexing take N minutes?" (introduced 4.9.0, nexus-7niu) |
 
@@ -1094,7 +1096,8 @@ nx collection list
 | `verify NAME` | Existence check + document count |
 | `reindex NAME` | Delete and re-index a collection from its source documents |
 | `backfill-hash [NAME]` | Add `chunk_text_hash` metadata to chunks missing it (no re-embedding) |
-| `rename OLD NEW` | In-place metadata-only rename in the T3 vector store + T2 + catalog cascade (4.8.0, nexus-1ccq) |
+| `rename OLD NEW` | In-place metadata-only rename in the T3 vector store + T2 + catalog cascade (4.8.0, nexus-1ccq). Never re-embeds; same-prefix renames whose embedding-model segment differs are rejected (6.3.1, nexus-tcvpn) |
+| `re-embed NAME --to MODEL` | In-place re-embed for non-CCE Voyage models (nexus-bw65). Service mode: same-model only — the computed vectors ride the verbatim passthrough; a cross-model `--to` fails loud (server-side embedding routes by the collection NAME's model segment; cross-model moves are the migration pipeline's job). `--no-dry-run --yes` to apply (6.3.1, nexus-c9xr2/u37lw) |
 | `audit NAME` | Deep-dive per-collection report: distance histogram, top-5 cross-projections, orphan chunks, hub topics, chash coverage (RDR-087 Phase 4) |
 | `health` | Composite per-collection health table — chunk counts (T3-sourced), staleness, hub score, chash coverage (RDR-087 Phase 3.4) |
 | `delete NAME` | Delete collection (irreversible) |
@@ -1136,7 +1139,7 @@ takes ~25–70 minutes on ChromaDB Cloud. Maintenance-window operation.
 
 | Flag | Description |
 |------|-------------|
-| `--force-prefix-change` | Allow a cross-prefix rename (e.g. `code__foo` → `docs__foo`). Embedding-model spaces differ across prefixes, so the renamed collection is query-incompatible with its old clients — use only when you've deleted every downstream reader |
+| `--force-prefix-change` | Allow a cross-prefix rename (e.g. `code__foo` → `docs__foo`) OR a same-prefix rename whose embedding-model segment differs (6.3.1, nexus-tcvpn). Rename never re-embeds, so either change leaves the vectors in the OLD model space under a name claiming the new one — use only when you know the vectors already match the target name (cross-model moves belong to `nx migrate` / guided-upgrade, the RDR-162 vector ETL) |
 
 Renames the collection in the T3 vector store via `t3.rename_collection` (a metadata-only update on the pgvector service path — no embedding re-upload, no Voyage cost, no vector egress), and cascades the new name through T2 taxonomy, `chash_index`, and catalog (JSONL + SQLite). Ordering (SIG-8 / nexus-nhyh): the T2 cascade runs FIRST, then the T3 rename, so a partial failure is recoverable: if the T3 rename fails the T2/catalog rows can be re-pointed or the rename re-run; if T2 fails no T3 rename was attempted.
 

mcpb/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.4",
   "name": "conexus",
   "display_name": "Conexus",
-  "version": "6.3.0",
+  "version": "6.3.1",
   "description": "Three-tier semantic memory + knowledge management for Claude Desktop chat. Persistent code/docs/RDR indexing, plan-centric retrieval via nx_answer, and a daemon-mediated storage substrate that interoperates with the Claude Code plugin and the nx CLI on the same host.",
   "long_description": "Conexus is the Claude Desktop Extension form of Nexus. Same MCP tools and storage tiers as the Claude Code plugin and the nx CLI, packaged as a .mcpb bundle that uv resolves on first install. On first launch, the host's T2 daemon is auto-installed (LaunchAgent on macOS, systemd user unit on Linux) so the MCP server has a daemon to talk to. State is shared with any other consumer on the same host (Claude Code plugin, nx CLI, Cowork via SDK bridge).",
   "author": {

mcpb/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conexus-mcpb"
-version = "6.3.0"
+version = "6.3.1"
 description = "Conexus packaged as Claude Desktop .mcpb (Desktop Extension)"
 requires-python = ">=3.12"
 dependencies = [
@@ -10,7 +10,7 @@ dependencies = [
     # while collections are indexed at 768/1024-dim, so every T3 search hits a
     # dimension mismatch and returns zero results. The .mcpb cannot run the
     # interactive `nx init` embedder choice, so it must pin [local] explicitly.
-    "conexus[local]>=6.3.0",
+    "conexus[local]>=6.3.1",
 ]
 
 [tool.uv]