prompt-hook opens CodeGraph without sync, so the MEDIUM (segment-vocab) gate tier stays permanently empty on any repo indexed before v1.2.0

[inth3shadows]

Summary

The prompt-hook's MEDIUM gate tier (#1136) depends on name_segment_vocab, which — per this repo's
own migration comment — starts empty on any database migrated from schema <7 and is only backfilled
by sync(). The prompt-hook itself never calls sync(), so on any repo indexed before upgrading to
a version carrying #1136, the MEDIUM tier returns zero matches indefinitely, until some unrelated
trigger (a manual codegraph sync, a git-hook sync, an MCP daemon sync) happens to run first.

Root cause

// src/bin/codegraph.ts:1117 (prompt-hook action)
const cg = await CodeGraph.open(plan.exploreRoot);
// ... later:
const related = cg.getSegmentMatches(proseWords);   // line 1153

// src/index.ts:295, 318-320 (CodeGraph.open)
static async open(projectRoot: string, options: OpenOptions = {}): Promise<CodeGraph> {
  // ...
  if (options.sync) {
    await instance.sync();
  }
  return instance;
}

The hook calls CodeGraph.open(plan.exploreRoot) with no options object, so options.sync is
undefined and sync() never runs on this path.

// src/db/migrations.ts:109-110 (v7 migration comment)
// ... The table starts EMPTY on migrated databases; `sync`
// detects that over a populated graph and backfills batched+yielding

The only backfill (rebuildNameSegmentVocab(), src/index.ts:1017) has exactly one call site
(src/index.ts:634, gated on vocabWasEmpty, src/index.ts:560), inside sync() — not in open()
— and getSegmentMatches() (src/index.ts:927 onward) has no lazy-backfill logic of its own; it
purely queries the table and re-verifies hits against nodes. Confirmed the empty-result path:

// src/bin/codegraph.ts:1153-1154
const related = cg.getSegmentMatches(proseWords);
if (related.length === 0) { gate('noop-unverified'); return; }

Impact

Every repo indexed before upgrading to a version with #1136 gets zero MEDIUM-tier value from the
prompt-hook — silently, with no error, logged only as noop-unverified in the gate telemetry — until
something else happens to trigger a sync first. I'd expect this to be common immediately after an
upgrade for users without a git-hook auto-sync configured (no postinstall/preinstall script exists,
and the installer's "auto-sync" machinery is about post-init file-watching, not upgrade-triggered
sync of already-indexed projects — checked both), though I don't have telemetry to confirm how often
that setup applies in practice.

Verification / scope

• Checked all 29 currently-open PRs' changed-file lists for src/bin/codegraph.ts — 3 touch it
  (Add GDScript and Godot scene graph support #1098, feat(cli): expose circular dependency detection #1012, feat(installer): add Pi as a native-extension agent target #992), none touch the prompt-hook action's line range (~1039-1220).
• Checked issues/PRs for "vocab empty", "medium tier dormant", "segment vocab backfill",
  "rebuildNameSegmentVocab", "vocabWasEmpty" — nothing.
• All claims above traced directly by reading the cited files/lines, including the exact telemetry
  outcome string and the absence of any postinstall/upgrade auto-sync path — did not run this
  end-to-end against an actual pre-v1.2.0 database to observe the empty MEDIUM tier live.

Environment

Found on main (tip e699ee9, v1.2.0).

[colbymchenry]

Confirmed and fixed in #1150 — thanks. One mitigating detail your trace didn't reach, and then what shipped:

The MCP server runs a catch-up sync() right after open, at every session start — so for the standard install (hook + MCP server together, which is what the installer writes) the backfill was already happening within the first session after upgrade. The real exposure was the window before that sync completes, hook-without-MCP setups, and — the part I cared most about — the telemetry mislabeling: a dormant vocab logging noop-unverified corrupts exactly the recall signal the funnel exists to measure.

What shipped:

• New CodeGraph.healSegmentVocabIfEmpty() — on the populated fast path it's one SELECT; on an empty vocab over a populated graph it runs the existing batched backfill under the index mutex/file-lock, and defers (returns "not usable") if another process holds the lock, since that process's own sync heals it. The hook calls this before the MEDIUM lookup — a one-time cost on the first MEDIUM-eligible prompt after upgrade, in the common case already paid by the daemon's catch-up sync before any prompt arrives.
• A distinct noop-vocab-empty gate outcome for the can't-heal case, so a dormant vocab is visible in the funnel instead of masquerading as "no matches". Documented in the telemetry doc's outcome enum.

Deliberately did not make the hook run a full sync() — the hook is latency-bound and must never mutate the index beyond this advisory table; the vocab rebuild is bounded, lock-aware, and advisory by design.