fix(cli): show cold-start preparation (#160)

* fix(cli): show cold-start preparation

* fix(cli): scope startup preparation accurately

* test(cli): verify cold-start timing and modes

* test(cli): cover MCP startup preparation

* lockfile

* docs(cli): avoid exact preparation message literal

Describe the preparation progress message generically so docs stay accurate across interactive and redirected/log presentations.

Author: lzehrung

codegraph-skill/codegraph/SKILL.md

@@ -36,7 +36,7 @@ Use `--root` to define the boundary for config lookup, cache scope, path confine
 - `codegraph.config.json` discovery globs are project-root-relative.
 - CLI `--include-glob` and `--ignore-glob` values are one-off filters relative to each active scan root.
 - Use `--no-gitignore` only when ignored files are intentionally in scope.
-- Index builds and updates report progress automatically on interactive stderr while reusable cache hits stay quiet. Use `--progress` for redirected progress logs or `--no-progress` to suppress feedback; JSON stdout is unchanged.
+- Every command that starts by loading the project index reports preparation on stderr when startup checks exceed a brief threshold, then reports builds or updates automatically. Fast reusable cache hits stay quiet; use `--progress` for redirected logs or `--no-progress` to suppress feedback, and JSON stdout remains unchanged.
 
 ## Choose the Smallest Follow-up
 

docs/cli.md

@@ -311,7 +311,7 @@ Short JSON shape:
 - Small orientation budgets default to `--health skip`. Medium and large default to `--health summary`, which counts cycles and unresolved imports while omitting duplicate health; use `--health full` when exhaustive duplicate counts matter.
 - Use `packet get` with file paths, symbol names, SQL object names, file/symbol/chunk/SQL/graph handles, or review handles to retrieve bounded evidence plus follow-up commands.
 - Agent commands reuse the incremental index path and default to disk cache. Use shared index flags such as `--cache`, `--cache-strict`, `--cache-verify`, `--threads`, `--native`, `--workers`, `--include-glob`, `--ignore-glob`, and `--no-gitignore` when the packet should match a specific scan mode.
-- When an index must be built or updated, interactive terminals immediately show progress on stderr; cache and snapshot hits stay quiet. Use `--progress` to force newline-delimited updates when stderr is redirected, or `--no-progress` to suppress feedback.
+- Every command that starts by loading the project index reports a preparation progress message on stderr when startup checks exceed a brief threshold, then transitions to build or update progress when work is required. Fast cache and snapshot hits stay quiet; use `--progress` for redirected progress logs or `--no-progress` to suppress feedback.
 
 #### Live file views
 

docs/coverage/js.md

@@ -4,52 +4,52 @@ Source: `coverage/js/lcov.info`
 
 ## Summary
 
-| Metric | Hit | Found | Coverage |
-| --- | ---: | ---: | ---: |
-| Lines | 21778 | 24063 | 90.50% |
-| Functions | 3682 | 3906 | 94.27% |
-| Branches | 16357 | 20980 | 77.96% |
+| Metric    |   Hit | Found | Coverage |
+| --------- | ----: | ----: | -------: |
+| Lines     | 21778 | 24063 |   90.50% |
+| Functions |  3682 |  3906 |   94.27% |
+| Branches  | 16357 | 20980 |   77.96% |
 
 ## Least-covered Files
 
-| File | Lines | Functions | Branches |
-| --- | ---: | ---: | ---: |
-| `src/languages/definitions/htmlStub.ts` | 50.00% | 50.00% | n/a |
-| `src/cli/index.ts` | 54.29% | 33.33% | 48.84% |
-| `src/cli/navigation.ts` | 55.36% | 66.67% | 56.25% |
-| `src/languages/definitions/javascript.ts` | 62.50% | 83.33% | 55.56% |
-| `src/cli/explore.ts` | 62.50% | 100.00% | 50.00% |
-| `src/languages/definitions/typescript.ts` | 62.86% | 81.82% | 41.18% |
-| `src/cli/install.ts` | 63.41% | 71.43% | 63.33% |
-| `src/util/projectFiles/parsers.ts` | 64.29% | 76.92% | 41.67% |
-| `src/indexer/parsed-cache.ts` | 64.71% | 100.00% | 58.33% |
-| `src/indexer.ts` | 66.67% | 66.67% | 100.00% |
-| `src/languages/definitions/css.ts` | 66.67% | 0.00% | n/a |
-| `src/languages/definitions/html.ts` | 66.67% | 0.00% | n/a |
-| `src/languages/definitions/less.ts` | 66.67% | 0.00% | n/a |
-| `src/languages/definitions/sql.ts` | 66.67% | 0.00% | n/a |
-| `src/languages/definitions/svelte.ts` | 66.67% | 0.00% | n/a |
-| `src/languages/definitions/vue.ts` | 66.67% | 0.00% | n/a |
-| `src/drift/report.ts` | 67.44% | 100.00% | 46.58% |
-| `src/cli/graph.ts` | 67.55% | 63.16% | 43.11% |
-| `src/agent/handles.ts` | 68.00% | 91.67% | 45.45% |
-| `src/impact/testPatterns.ts` | 69.70% | 63.64% | 61.54% |
+| File                                      |  Lines | Functions | Branches |
+| ----------------------------------------- | -----: | --------: | -------: |
+| `src/languages/definitions/htmlStub.ts`   | 50.00% |    50.00% |      n/a |
+| `src/cli/index.ts`                        | 54.29% |    33.33% |   48.84% |
+| `src/cli/navigation.ts`                   | 55.36% |    66.67% |   56.25% |
+| `src/languages/definitions/javascript.ts` | 62.50% |    83.33% |   55.56% |
+| `src/cli/explore.ts`                      | 62.50% |   100.00% |   50.00% |
+| `src/languages/definitions/typescript.ts` | 62.86% |    81.82% |   41.18% |
+| `src/cli/install.ts`                      | 63.41% |    71.43% |   63.33% |
+| `src/util/projectFiles/parsers.ts`        | 64.29% |    76.92% |   41.67% |
+| `src/indexer/parsed-cache.ts`             | 64.71% |   100.00% |   58.33% |
+| `src/indexer.ts`                          | 66.67% |    66.67% |  100.00% |
+| `src/languages/definitions/css.ts`        | 66.67% |     0.00% |      n/a |
+| `src/languages/definitions/html.ts`       | 66.67% |     0.00% |      n/a |
+| `src/languages/definitions/less.ts`       | 66.67% |     0.00% |      n/a |
+| `src/languages/definitions/sql.ts`        | 66.67% |     0.00% |      n/a |
+| `src/languages/definitions/svelte.ts`     | 66.67% |     0.00% |      n/a |
+| `src/languages/definitions/vue.ts`        | 66.67% |     0.00% |      n/a |
+| `src/drift/report.ts`                     | 67.44% |   100.00% |   46.58% |
+| `src/cli/graph.ts`                        | 67.55% |    63.16% |   43.11% |
+| `src/agent/handles.ts`                    | 68.00% |    91.67% |   45.45% |
+| `src/impact/testPatterns.ts`              | 69.70% |    63.64% |   61.54% |
 
 ## Type-Only Or Re-Export Files
 
 These files have line records but no function or branch records, so they are tracked outside the runtime ranking.
 
-| File | Lines | Functions | Branches |
-| --- | ---: | ---: | ---: |
-| `src/languages/definitions/jsFamily.ts` | 100.00% | n/a | n/a |
-| `src/duplicate-keywords.ts` | 100.00% | n/a | n/a |
-| `src/impact/types.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/adoc.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/astro.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/hbs.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/markdown.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/mdx.ts` | 100.00% | n/a | n/a |
-| `src/languages/definitions/rst.ts` | 100.00% | n/a | n/a |
-| `src/util/graphOnlyExtensions.ts` | 100.00% | n/a | n/a |
+| File                                    |   Lines | Functions | Branches |
+| --------------------------------------- | ------: | --------: | -------: |
+| `src/languages/definitions/jsFamily.ts` | 100.00% |       n/a |      n/a |
+| `src/duplicate-keywords.ts`             | 100.00% |       n/a |      n/a |
+| `src/impact/types.ts`                   | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/adoc.ts`     | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/astro.ts`    | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/hbs.ts`      | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/markdown.ts` | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/mdx.ts`      | 100.00% |       n/a |      n/a |
+| `src/languages/definitions/rst.ts`      | 100.00% |       n/a |      n/a |
+| `src/util/graphOnlyExtensions.ts`       | 100.00% |       n/a |      n/a |
 
 Generated from LCOV by `node ./scripts/coverage-markdown.mjs`.

docs/coverage/native.md

@@ -4,23 +4,23 @@ Source: `coverage/native/lcov.info`
 
 ## Summary
 
-| Metric | Hit | Found | Coverage |
-| --- | ---: | ---: | ---: |
-| Lines | 604 | 626 | 96.49% |
-| Functions | 45 | 51 | 88.24% |
-| Branches | 0 | 0 | n/a |
+| Metric    | Hit | Found | Coverage |
+| --------- | --: | ----: | -------: |
+| Lines     | 604 |   626 |   96.49% |
+| Functions |  45 |    51 |   88.24% |
+| Branches  |   0 |     0 |      n/a |
 
 ## Least-covered Files
 
-| File | Lines | Functions | Branches |
-| --- | ---: | ---: | ---: |
-| `packages/codegraph-native/src/lib.rs` | 89.47% | 70.00% | n/a |
-| `packages/codegraph-native/src/parser_pool.rs` | 92.86% | 66.67% | n/a |
-| `packages/codegraph-native/src/duplicate_tokens.rs` | 93.20% | 100.00% | n/a |
-| `packages/codegraph-native/src/projection.rs` | 97.50% | 100.00% | n/a |
-| `packages/codegraph-native/src/query.rs` | 99.31% | 92.86% | n/a |
-| `packages/codegraph-native/src/duplicate_keywords.rs` | 100.00% | 100.00% | n/a |
-| `packages/codegraph-native/src/languages.rs` | 100.00% | 100.00% | n/a |
-| `packages/codegraph-native/src/types.rs` | 100.00% | 100.00% | n/a |
+| File                                                  |   Lines | Functions | Branches |
+| ----------------------------------------------------- | ------: | --------: | -------: |
+| `packages/codegraph-native/src/lib.rs`                |  89.47% |    70.00% |      n/a |
+| `packages/codegraph-native/src/parser_pool.rs`        |  92.86% |    66.67% |      n/a |
+| `packages/codegraph-native/src/duplicate_tokens.rs`   |  93.20% |   100.00% |      n/a |
+| `packages/codegraph-native/src/projection.rs`         |  97.50% |   100.00% |      n/a |
+| `packages/codegraph-native/src/query.rs`              |  99.31% |    92.86% |      n/a |
+| `packages/codegraph-native/src/duplicate_keywords.rs` | 100.00% |   100.00% |      n/a |
+| `packages/codegraph-native/src/languages.rs`          | 100.00% |   100.00% |      n/a |
+| `packages/codegraph-native/src/types.rs`              | 100.00% |   100.00% |      n/a |
 
 Generated from LCOV by `node ./scripts/coverage-markdown.mjs`.

docs/plans/2026-07-03-08-framework-route-nodes.md

@@ -29,7 +29,7 @@ type RouteNode = {
   id: string;
   kind: "route";
   file: string;
-  name: string;        // GET /users/:id
+  name: string; // GET /users/:id
   method?: string;
   pathPattern: string;
   range: SourceRange;

docs/plans/2026-07-03-core-command-performance-cache-sync.md

@@ -47,6 +47,7 @@ Measured from the local `dist` CLI on 2026-07-03:
 ### Task 1: Add Timing Reports for `search`
 
 **Files:**
+
 - Modify: `src/cli/search.ts`
 - Modify: `src/cli.ts`
 - Test: `tests/cli-command-modules.test.ts`
@@ -182,6 +183,7 @@ git commit -m "feat: add search timing report"
 ### Task 2: Add Timing Reports for `inspect`
 
 **Files:**
+
 - Modify: `src/cli/inspect.ts`
 - Modify: `src/cli.ts`
 - Test: `tests/cli-command-modules.test.ts`
@@ -288,6 +290,7 @@ git commit -m "feat: add inspect timing report"
 ### Task 3: Make `inspect` Duplicate Detection Opt-In
 
 **Files:**
+
 - Modify: `src/cli/inspect.ts`
 - Modify: `src/cli/help.ts`
 - Modify: `docs/cli.md`
@@ -362,18 +365,18 @@ In `src/cli/inspect.ts`, change `InspectReport["duplicates"]` to a union:
 In `buildInspectReport`, add `includeDuplicates: boolean` and wrap duplicate detection:
 
 ```ts
-  const duplicates: InspectReport["duplicates"] = includeDuplicates
-    ? {
-        enabled: true,
-        total:
-          duplicateResult.groups.length +
-          duplicateResult.omittedCounts.groups +
-          duplicateResult.omittedCounts.candidatePairs,
-        omitted: duplicateResult.omittedCounts.groups + duplicateResult.omittedCounts.candidatePairs,
-        minConfidence: duplicateMinConfidence,
-        top: duplicateResult.groups.map(summarizeDuplicateGroup),
-      }
-    : { enabled: false };
+const duplicates: InspectReport["duplicates"] = includeDuplicates
+  ? {
+      enabled: true,
+      total:
+        duplicateResult.groups.length +
+        duplicateResult.omittedCounts.groups +
+        duplicateResult.omittedCounts.candidatePairs,
+      omitted: duplicateResult.omittedCounts.groups + duplicateResult.omittedCounts.candidatePairs,
+      minConfidence: duplicateMinConfidence,
+      top: duplicateResult.groups.map(summarizeDuplicateGroup),
+    }
+  : { enabled: false };
 ```
 
 Use `if` blocks instead of a nested ternary if the expression grows.
@@ -413,6 +416,7 @@ git commit -m "perf: make inspect duplicates opt-in"
 ### Task 4: Add Safe Bloom Prefilter for Text Search
 
 **Files:**
+
 - Modify: `src/agent/search.ts`
 - Test: `tests/agent-search.test.ts`
 
@@ -536,6 +540,7 @@ git commit -m "perf: prefilter identifier text search"
 ### Task 5: Add Agent Session File Fingerprints
 
 **Files:**
+
 - Modify: `src/agent/session.ts`
 - Test: `tests/agent-session.test.ts`
 
@@ -590,7 +595,7 @@ Use this helper in both `loadFiles` and `loadBase`.
 Extend the type:
 
 ```ts
-  fileFingerprint: () => Promise<string>;
+fileFingerprint: () => Promise<string>;
 ```
 
 Implement it with fresh discovery:
@@ -599,7 +604,10 @@ Implement it with fresh discovery:
 const fileFingerprint = async (): Promise<string> => {
   const discoveryOptions = await resolveAgentDiscovery(options);
   const files = await listProjectFiles(options.root, undefined, discoveryOptions);
-  return files.map((file) => normalizePath(file)).sort().join("\n");
+  return files
+    .map((file) => normalizePath(file))
+    .sort()
+    .join("\n");
 };
 ```
 
@@ -627,6 +635,7 @@ git commit -m "feat: expose agent session file fingerprint"
 ### Task 6: Add MCP Cache Sync Controller
 
 **Files:**
+
 - Create: `src/mcp/cacheSync.ts`
 - Modify: `src/mcp/server.ts`
 - Test: `tests/mcp-server.test.ts`
@@ -790,6 +799,7 @@ git commit -m "feat: add mcp cache sync controller"
 ### Task 7: Add MCP Cache Sync CLI Flags and Docs
 
 **Files:**
+
 - Modify: `src/cli/mcp.ts`
 - Modify: `src/cli/help.ts`
 - Modify: `docs/cli.md`
@@ -907,6 +917,7 @@ git commit -m "feat: expose mcp cache sync flags"
 ### Task 8: Add Lifecycle Sync for HTTP Session Initialize
 
 **Files:**
+
 - Modify: `src/mcp/server.ts`
 - Test: `tests/mcp-server.test.ts`
 
@@ -1003,6 +1014,7 @@ git commit -m "feat: sync mcp cache on lifecycle"
 ### Task 9: Final Verification and Timing Evidence
 
 **Files:**
+
 - Modify: `docs/plans/2026-06-06-performance-and-cache-opportunities.md` only if status boxes need updating.
 - No production code changes.