msnav 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ea0f1f4fee68dd182f4e86da45adb998043e96a62d79effa4a05094ab8fdbed
+  data.tar.gz: 75cd16332b3edc2b185adcbd155dcc4fc88e3904a5887065d3d910edaaccea64
+SHA512:
+  metadata.gz: 87694f9c0587ea8bea74c54027101d26f90c7c42e06790e853388a8608562a1dfadee1736d15fb272aa0f8f86fead6e45afc6684825d47fca1912b3f5c255c9d
+  data.tar.gz: 9f1c22c8076ccf207e700b9378ebeb97ee2f4d6c1e6fccde3c6d2f37b23f670edf8aa3164a8c48d038a8f7f5c0629e7d37f0c5cea097956712416cbfb1ad13dd

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaroslav Zahoruiko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# msnav — microservice navigation server (Ruby)
+
+A pure-Ruby daemon, run the way ruby-lsp is run, that serves
+[coderag](../graph-rag-v3)'s cross-service navigation API **inside a Ruby
+devcontainer with no Python**. The host builds the index with coderag; the
+container mounts the shared data dir and runs `msnav` — same endpoints, same
+DB, same editor extension UX.
+
+```
+HOST                                      CONTAINER (ruby image, no Python)
+─────────────────────────────            ──────────────────────────────────
+coderag index <hub>            ──DB──▶   msnav daemon  ◀── editor extension
+  ~/.local/share/coderag/hubs/<hub>/       reads coderag.db through the
+  (coderag.db stays here)                  ~/.local/share/coderag bind mount
+```
+
+msnav is a **navigation face over the shared index**: it never indexes. When
+anything (a host `coderag index`, a coderag daemon elsewhere) bumps the DB's
+`index_generation`, every msnav on the hub hot-reloads within a second.
+
+## What it serves
+
+The exact endpoints the editor extension calls, wire-compatible with the
+Python daemon (verified response-for-response against it — see Tests):
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/health` | identity probe: root, services, service_roots, pid |
+| `GET /api/nav/definition` | cross-service go-to-definition (HTTP call → route, publish → consumer, route → handler) |
+| `GET /api/nav/references` | cross-service callers of the endpoint under the cursor |
+| `GET /api/nav/hover` | target endpoint's YARD doc for the call on this line |
+| `GET /api/nav/file-targets` | every cross-service jump point in a file (CodeLens) |
+| `POST /api/register-window` `GET /api/window-commands` `GET /api/windows` `POST /api/open` | bridge-mode window registry + open routing, shared with coderag daemons through the DB |
+| `GET /api/services` `GET /api/routes` | diagnostics |
+
+Not included (by design — they need the indexer/LLM stack): reindex, watch,
+search, ask/chat, MCP, the composite LSP. Indexing freshness comes from the
+host.
+
+## Quickstart
+
+On the **host** (once per hub, with coderag installed):
+
+```sh
+cd /path/to/workspace   # the folder containing all services, with coderag.yml
+coderag index . --no-embed
+```
+
+In the **devcontainer** (Ruby image):
+
+```sh
+gem install msnav       # or from this repo: gem build msnav.gemspec && gem install msnav-*.gem
+msnav up                # idempotent; the editor extension runs this itself
+msnav status
+```
+
+The only container config needed is the data-dir mount — one line, identical
+for every service of every hub:
+
+```json
+"mounts": [
+  "source=${localEnv:HOME}/.local/share/coderag,target=/root/.local/share/coderag,type=bind"
+]
+```
+
+`msnav up` finds the hub the same way `coderag up` does: nearest ancestor
+`coderag.yml` → the conventional hub mount (`$CODERAG_HUB`, default
+`/coderag-hub`) → the data dir, matching the folder against each hub's index
+by directory name and then **by file contents** — so compose-style anonymous
+mounts (`workspaceFolder: /app`) resolve without any settings. The resolved
+service travels to the daemon, whose `/api/health` reports the `scope`
+(container path ↔ canonical host root) that the extension uses as its exact
+path mapping. Same exit codes too: 0 healthy, 1 failure, 2 no hub, 3 the
+port serves a different hub. `$CODERAG_DATA_DIR` / `$CODERAG_CONFIG` are
+honored. `msnav doctor` explains resolution from any folder.
+
+Because service locations come straight from the shared DB, an in-container
+msnav serves **host paths** for cross-service targets — jumps land in the
+window that owns the service (routed via the DB-backed window registry, so
+it works across per-container daemons, Ruby and Python alike) or open a new
+host window.
+
+## Editor extension
+
+[editor/msnav/](editor/msnav/) is the coderag extension adapted for msnav
+(`msnav.*` settings, default daemon command `msnav up`, provider + bridge
+modes). Package with `npx @vscode/vsce package --no-dependencies`. The
+original coderag extension also works against msnav — the protocol is
+identical — if you point its `coderag.daemonCommand` at `["msnav", "up"]`.
+
+## Devcontainer example
+
+[examples/devcontainer/](examples/devcontainer/) has the complete per-service
+pattern: Ruby-only Dockerfile (`libsqlite3-dev` for the sqlite3 gem, no
+Python), the single data-dir mount, and a postCreate that installs msnav and
+the extension.
+
+## CLI
+
+```
+msnav daemon [--config PATH] [--host H] [--port P]   # run in the foreground
+msnav up     [ROOT] [--port P] [--timeout S]         # ensure one is running (idempotent)
+msnav status [--port P]                              # health + registered windows
+msnav down   [--port P]                              # SIGTERM by health-reported pid
+```
+
+`daemon`/`up` also accept `--service-root/--service/--no-embed/--no-watch`
+for drop-in compatibility with `coderag up` command lines; they change
+nothing (msnav never indexes).
+
+## Compatibility
+
+- Reads coderag **schema v4** DBs (errors on older; warns-and-continues on
+  newer). Writes only the two v4 message-bus tables (`windows`,
+  `window_commands`) every daemon on the hub shares.
+- Ruby ≥ 2.6; gems: `sqlite3`, `webrick`.
+- The Docker-Desktop caveat from coderag applies here too: SQLite (WAL) over
+  bind mounts with several concurrent writers is the sensitive spot; msnav
+  keeps its writes tiny (window registry only).
+
+## Troubleshooting
+
+**`msnav up` exits 2 / "no hub found" in a devcontainer** — hub resolution
+failed. Run `msnav doctor` in the container terminal (from the workspace
+folder): it walks the same ladder `up` uses and shows what each step found.
+The folder is matched against each hub's index first by directory name, then
+**by content** (which service's indexed file paths are actually on disk —
+≥3 files and ≥60% present), so anonymous mounts like `/app` resolve too.
+Common causes when it still fails:
+
+1. *Hub not indexed / stale* — run `coderag index` on the HOST at the hub
+   (the folder containing all services); content matching compares against
+   that index.
+2. *Data dir not visible* — the mount targets `/root/...` but the container
+   runs as a non-root `remoteUser`, so msnav looks in `/home/<user>/...`.
+   Mount into the remote user's home, or mount anywhere and set
+   `$CODERAG_DATA_DIR` to the target.
+3. Escape hatches: `$CODERAG_HUB=<hub dir>` or
+   `--config <hub-dir>/coderag.yml` in `msnav.daemonCommand`.
+
+**`can't find executable msnav for gem msnav. msnav is not currently
+included in the bundle`** — msnav was invoked inside a Bundler context
+(`bundle exec`, or an environment exporting `RUBYOPT=-rbundler/setup` /
+`BUNDLE_GEMFILE`): rubygems binstubs then refuse any gem the active Gemfile
+doesn't list. msnav never needs Bundler. Fixes, best first:
+
+1. Invoke it with the Bundler context stripped —
+   `env -u RUBYOPT -u RUBYLIB -u BUNDLE_GEMFILE -u BUNDLE_BIN_PATH msnav up`
+   (the editor extension and `examples/devcontainer/postCreate.sh` already
+   do this, and `msnav up` scrubs the same variables when spawning the
+   daemon).
+2. Or add `gem "msnav", group: :development` to the service's Gemfile so the
+   bundle knows it — the ruby-lsp way; only needed if you insist on running
+   it through Bundler.
+
+**`can't find gem msnav (>= 0.a) with executable msnav
+(Gem::GemNotFoundException)`** — msnav was installed as a **git gem** in a
+Gemfile (`gem "msnav", github: …`). Git gems are visible only inside
+`bundle exec` for that Gemfile; the binstub Bundler leaves on PATH cannot
+activate them, so the extension's `msnav up` fails. msnav never loads your
+app's code (unlike ruby-lsp), so don't put it in a Gemfile at all — install
+it as a plain gem in the image (`gem install msnav`, or build+install from a
+git checkout). Quick fix inside a running container:
+`cd /usr/local/bundle/bundler/gems/msnav-*/ && gem build msnav.gemspec -o
+/tmp/m.gem && gem install /tmp/m.gem`.
+
+**`WARN: Unresolved or ambiguous specs during Gem::Specification.reset:
+stringio (…)` during install** — benign RubyGems noise, not an msnav error.
+It appears when the image carries two versions of a default gem (the one
+bundled with its Ruby plus a newer one some earlier `gem install` pulled in);
+any `gem` command then prints it. Install and runtime are unaffected —
+verified with the exact duplicate pair on Ruby 3.1. Silence it by upgrading
+RubyGems in the image (`gem update --system`) or just ignore it.
+
+## Tests
+
+```sh
+rake test        # or: ruby -Ilib -Itest test/test_*.rb
+```
+
+Unit tests run against a generated schema-v4 fixture DB; the HTTP layer is
+tested through a real WEBrick boot. Parity was verified against the Python
+daemon on coderag's `examples/shop`: **776/776** identical responses across
+every line of every file for definition / references / hover / file-targets
+(+ services and routes), plus cross-daemon window routing (register with the
+Python daemon, open via msnav, and vice versa) and generation hot-reload
+after a Python-side reindex.

data/exe/msnav

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# run-from-checkout support: prefer the sibling lib when it's there (a gem
+# install resolves msnav through RubyGems instead)
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require "msnav"
+
+exit Msnav::CLI.run(ARGV)

data/lib/msnav/cli.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "pathname"
+
+module Msnav
+  # `msnav` command line: daemon / up / status / down — the same lifecycle
+  # surface (flags, hub resolution, exit codes) as `coderag daemon/up/...`,
+  # so the editor extension's daemonCommand can point at either.
+  module CLI
+    USAGE = <<~TEXT
+      msnav — cross-service Ruby navigation server over a coderag index
+
+      Usage: msnav COMMAND [options]
+
+      Commands:
+        daemon    Run the navigation daemon (HTTP API on --host/--port)
+        up        Ensure a daemon for this hub is running (idempotent)
+        status    Health and registered windows of the daemon
+        down      Stop the daemon on --host/--port
+        doctor    Explain hub resolution from the current directory
+        version   Print the msnav version
+
+      The index is built on the host by coderag (`coderag index`); msnav
+      reads the shared coderag.db (typically via the devcontainer's
+      ~/.local/share/coderag bind mount) and serves the navigation API.
+    TEXT
+
+    class Exit < StandardError
+      attr_reader :code
+
+      def initialize(code, message = nil)
+        @code = code
+        super(message || "")
+      end
+    end
+
+    module_function
+
+    def run(argv)
+      command = argv.first
+      rest = argv[1..-1] || []
+      case command
+      when "daemon" then cmd_daemon(rest)
+      when "up" then cmd_up(rest)
+      when "status" then cmd_status(rest)
+      when "down" then cmd_down(rest)
+      when "doctor" then cmd_doctor(rest)
+      when "version", "--version", "-v"
+        puts "msnav #{VERSION}"
+        0
+      when nil, "help", "--help", "-h"
+        puts USAGE
+        command.nil? ? 1 : 0
+      else
+        warn "unknown command: #{command}\n\n#{USAGE}"
+        1
+      end
+    rescue Exit => e
+      warn e.message unless e.message.empty?
+      e.code
+    rescue Error => e
+      warn "msnav: #{e.message}"
+      1
+    end
+
+    # -------------------------------------------------------------- commands
+
+    def cmd_daemon(argv)
+      opts = { host: "127.0.0.1", port: 8787 }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: msnav daemon [options]"
+        o.on("--config PATH", "coderag.yml to load") { |v| opts[:config] = v }
+        o.on("--host HOST") { |v| opts[:host] = v }
+        o.on("--port PORT", Integer) { |v| opts[:port] = v }
+        # service scope: names which indexed service this container's window
+        # holds (msnav never extracts — this feeds health's `scope`, the
+        # extension's exact container<->host path mapping)
+        o.on("--service-root DIR") { |v| opts[:service_root] = v }
+        o.on("--service NAME") { |v| opts[:service] = v }
+        # accepted for coderag CLI compatibility (msnav never indexes)
+        o.on("--no-embed") {}
+        o.on("--no-watch") {}
+      end
+      parser.parse!(argv)
+      cfg = Config.load(opts[:config])
+      puts "msnav #{VERSION} — index #{cfg.db_path}"
+      Server.new(cfg, host: opts[:host], port: opts[:port],
+                      service_root: opts[:service_root],
+                      service_name: opts[:service]).start
+      0
+    end
+
+    def cmd_up(argv)
+      opts = { host: "127.0.0.1", port: 8787, timeout: 15.0 }
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: msnav up [ROOT] [options]"
+        o.on("--config PATH") { |v| opts[:config] = v }
+        o.on("--host HOST") { |v| opts[:host] = v }
+        o.on("--port PORT", Integer) { |v| opts[:port] = v }
+        o.on("--timeout SECONDS", Float,
+             "Seconds to wait for the daemon to become healthy") { |v| opts[:timeout] = v }
+        # passthrough flags kept for coderag compatibility
+        o.on("--service-root DIR") { |v| opts[:service_root] = v }
+        o.on("--service NAME") { |v| opts[:service] = v }
+        o.on("--no-embed") {}
+        o.on("--no-watch") {}
+      end
+      parser.parse!(argv)
+      root = argv.shift
+
+      hub, config, implicit_root, implicit_name = resolve_hub(opts[:config], root)
+      service_root = opts[:service_root] || implicit_root
+      service_name = opts[:service] || implicit_name
+      expected = Ctl.expected_workspace_root(hub)
+      url = "http://#{opts[:host]}:#{opts[:port]}"
+
+      probe = Ctl.probe_health(url)
+      if probe.state == "foreign"
+        raise Exit.new(Ctl::EXIT_FAIL,
+                       "#{url} is answering but is not a coderag daemon " \
+                       "(#{probe.detail}) — is the port taken by something else?")
+      end
+      if probe.state == "healthy"
+        if Ctl.same_root(probe.root, expected)
+          puts "already running: #{url} root=#{probe.root} pid=#{probe.pid}"
+          return 0
+        end
+        raise Exit.new(Ctl::EXIT_WRONG_ROOT,
+                       "a coderag daemon on #{url} serves a different hub:\n" \
+                       "  running: #{probe.root}\n  requested: #{expected}\n" \
+                       "leave it alone or use --port for a second daemon.")
+      end
+
+      log_path = Ctl.daemon_log_path(hub)
+      _pid, waiter = Ctl.spawn_daemon(hub, config, opts[:host], opts[:port],
+                                      service_root: service_root,
+                                      service_name: service_name,
+                                      log_path: log_path)
+      probe = Ctl.wait_healthy(url, waiter, opts[:timeout])
+      if probe.state == "healthy"
+        if Ctl.same_root(probe.root, expected)
+          puts "started: #{url} root=#{probe.root} pid=#{probe.pid}"
+          return 0
+        end
+        raise Exit.new(Ctl::EXIT_WRONG_ROOT,
+                       "a daemon appeared on #{url} but for a different hub " \
+                       "(#{probe.root})")
+      end
+      tail = Ctl.tail_log(log_path)
+      raise Exit.new(Ctl::EXIT_FAIL,
+                     "daemon did not become healthy within " \
+                     "#{opts[:timeout].round}s" +
+                     (tail.empty? ? " and wrote nothing to daemon.log" :
+                        " — last daemon.log lines:\n#{tail}"))
+    end
+
+    def cmd_status(argv)
+      opts = parse_host_port(argv, "status")
+      url = "http://#{opts[:host]}:#{opts[:port]}"
+      probe = Ctl.probe_health(url)
+      if probe.state == "down"
+        raise Exit.new(1, "no daemon at #{url} (#{probe.detail})")
+      end
+      if probe.state == "foreign"
+        raise Exit.new(1, "#{url} is answering but is not a coderag daemon " \
+                          "(#{probe.detail})")
+      end
+      h = probe.health
+      puts "coderag-compatible daemon at #{url}"
+      puts "  root:       #{h['root']}"
+      puts "  version:    #{h['version']}   pid: #{h['pid']}   " \
+           "generation: #{h['generation']}"
+      puts "  services:   #{(h['services'] || []).join(', ')}"
+      windows = fetch_windows(url)
+      live = windows.count { |w| w["alive"] }
+      puts "  windows:    #{live} live / #{windows.length} registered"
+      windows.each do |w|
+        mark = w["alive"] ? "live" : "stale (#{w['last_poll_ago']}s)"
+        puts "    [#{mark}] #{w['window_id']} roots=#{w['roots']}"
+      end
+      0
+    end
+
+    def cmd_down(argv)
+      opts = parse_host_port(argv, "down")
+      url = "http://#{opts[:host]}:#{opts[:port]}"
+      probe = Ctl.probe_health(url)
+      if probe.state == "down"
+        puts "no daemon at #{url}"
+        return 0
+      end
+      if probe.state == "foreign"
+        raise Exit.new(1, "#{url} is not a coderag daemon (#{probe.detail}) " \
+                          "— not touching it")
+      end
+      pid = probe.pid
+      raise Exit.new(1, "daemon health reports no pid — stop it manually") if pid.nil?
+      begin
+        Process.kill("TERM", pid)
+      rescue Errno::ESRCH
+        raise Exit.new(1, "daemon reports pid #{pid} but it is not visible " \
+                          "here — stop it from its own environment " \
+                          "(host vs container)")
+      rescue Errno::EPERM
+        raise Exit.new(1, "no permission to signal pid #{pid}")
+      end
+      20.times do
+        if Ctl.probe_health(url).state == "down"
+          puts "stopped: pid #{pid}"
+          return 0
+        end
+        sleep 0.25
+      end
+      raise Exit.new(1, "sent SIGTERM to pid #{pid} but #{url} still answers")
+    end
+
+    # Walks the same resolution ladder `msnav up` uses and shows what each
+    # rung sees from THIS directory — run it where `up` failed with exit 2.
+    def cmd_doctor(argv)
+      opts = parse_host_port(argv, "doctor")
+      url = "http://#{opts[:host]}:#{opts[:port]}"
+      start = Pathname.new(Dir.pwd)
+      puts "msnav #{VERSION} — hub resolution from #{start}"
+
+      row = ->(k, v) { puts format("  %-17s %s", k, v) }
+      row.call("folder name:", "'#{start.basename}' (matched against service " \
+                               "dir names at each hub, then by file contents)")
+      env_cfg = ENV["CODERAG_CONFIG"].to_s
+      row.call("CODERAG_CONFIG:", env_cfg.empty? ? "(unset)" : env_cfg)
+      walk = Ctl.find_hub_root(start)
+      row.call("coderag.yml:", walk ? "found at #{walk}" : "none from here up to /")
+      conv = Pathname.new(ENV["CODERAG_HUB"] || "/coderag-hub")
+      row.call("CODERAG_HUB:", "#{conv} " +
+               ((conv + "coderag.yml").file? ? "(usable)" : "(no coderag.yml there)"))
+      dd = Datadir.data_dir
+      src = ENV["CODERAG_DATA_DIR"].to_s.empty? ? "derived from home #{Dir.home}" : "$CODERAG_DATA_DIR"
+      row.call("data dir:", "#{dd} (#{src})")
+
+      hubs = dd + "hubs"
+      if hubs.directory?
+        entries = hubs.children.sort.select(&:directory?)
+        puts "    no hubs inside — index on the HOST first (`coderag index` at the hub)" if entries.empty?
+        entries.each do |h|
+          db = h + "coderag.db"
+          next puts "    #{h.basename}: (no coderag.db)" unless db.file?
+          names = begin
+            con = SQLite3::Database.new(db.to_s, readonly: true)
+            begin
+              con.execute("SELECT dirname FROM services").map { |r| r[0] }
+            ensure
+              con.close
+            end
+          rescue SQLite3::Exception => e
+            next puts "    #{h.basename}: unreadable (#{e.message})"
+          end
+          identified = Datadir.identify_service(db, start)
+          mark = if identified.nil?
+                   ""
+                 elsif identified == start.basename.to_s
+                   "   <-- matches this folder by name"
+                 else
+                   "   <-- matches this folder by content (as #{identified})"
+                 end
+          puts "    #{h.basename}: #{names.join(', ')}#{mark}"
+        end
+      else
+        puts "    MISSING — the host's ~/.local/share/coderag is not visible here."
+        puts "    Mount it into the REMOTE USER's home, or mount anywhere and set $CODERAG_DATA_DIR."
+      end
+
+      probe = Ctl.probe_health(url)
+      row.call("daemon #{url}:",
+               case probe.state
+               when "healthy" then "healthy (root #{probe.root}, pid #{probe.pid})"
+               when "foreign" then "something else answers (#{probe.detail})"
+               else "down"
+               end)
+
+      begin
+        hub, config, service_root, service_name = resolve_hub(nil, nil)
+        puts "\nresolution: OK — hub #{hub}, config #{config}" \
+             "#{service_root ? ", service root #{service_root}" : ''}" \
+             "#{service_name ? " (service #{service_name})" : ''}"
+        0
+      rescue Exit
+        puts "\nresolution: FAILED — `msnav up` from here exits 2. Fixes, best first:"
+        puts "  * index the hub on the HOST (`coderag index` in the folder containing"
+        puts "    all services) so this service's files match an index by content"
+        puts "  * run from the folder that actually holds the service's source"
+        puts "    (content matching needs its .rb files on disk)"
+        puts "  * or set $CODERAG_HUB to the hub dir shown above (it holds a coderag.yml),"
+        puts "    or pass --config <hub-dir>/coderag.yml in msnav.daemonCommand"
+        puts "  * non-root container? mount the data dir into the remote user's home," \
+             " or set $CODERAG_DATA_DIR to the mount target"
+        1
+      end
+    end
+
+    # --------------------------------------------------------------- helpers
+
+    def parse_host_port(argv, name)
+      opts = { host: "127.0.0.1", port: 8787 }
+      OptionParser.new do |o|
+        o.banner = "Usage: msnav #{name} [options]"
+        o.on("--host HOST") { |v| opts[:host] = v }
+        o.on("--port PORT", Integer) { |v| opts[:port] = v }
+      end.parse!(argv)
+      opts
+    end
+
+    def fetch_windows(url)
+      require "net/http"
+      uri = URI.parse("#{url}/api/windows")
+      res = Net::HTTP.start(uri.host, uri.port,
+                            open_timeout: 2, read_timeout: 2) do |http|
+        http.get(uri.request_uri)
+      end
+      res.is_a?(Net::HTTPSuccess) ? JSON.parse(res.body) : []
+    rescue StandardError
+      []
+    end
+
+    # Hub root + config for the lifecycle commands: explicit --config wins,
+    # then $CODERAG_CONFIG, then a coderag.yml walk-up from ROOT or the cwd,
+    # then the conventional container mount ($CODERAG_HUB, default
+    # /coderag-hub), then the package data dir (which hub's index matches the
+    # service this folder holds — by directory name or file contents, so
+    # `/app` style mounts work). In the last two cases the start directory is
+    # implicitly the service root (a service-only container). Returns
+    # [hub, config_path, implicit_service_root, implicit_service_name] or
+    # exits 2 — a daemon must never be rooted inside a single service
+    # directory.
+    def resolve_hub(config_path, root)
+      explicit = config_path
+      env = ENV["CODERAG_CONFIG"]
+      explicit ||= env if env && !env.empty?
+      if explicit
+        config = Pathname.new(File.expand_path(explicit))
+        unless config.file?
+          raise Exit.new(Ctl::EXIT_NO_HUB, "config not found: #{config}")
+        end
+        return [config.parent, config, nil, nil]
+      end
+
+      start = Pathname.new(File.expand_path(root || Dir.pwd))
+      start = start.realpath if start.exist?
+      hub = Ctl.find_hub_root(start)
+      return [hub, hub + "coderag.yml", nil, nil] unless hub.nil?
+
+      conv = Pathname.new(ENV["CODERAG_HUB"] || "/coderag-hub")
+      if (conv + "coderag.yml").file?
+        # service-only container: the hub arrives as a .coderag-only mount
+        # and this directory holds exactly one service's source
+        db = Ctl.resolved_storage(conv) + "coderag.db"
+        name = db.file? ? Datadir.identify_service(db, start) : nil
+        return [conv, conv + "coderag.yml", start.to_s, name]
+      end
+
+      # package data dir: a container with only the data-dir mount finds its
+      # hub by which index matches the service this folder holds
+      matches = Datadir.find_hubs_for_service_root(start)
+      if matches.length == 1
+        hub, name = matches[0]
+        config = hub + "coderag.yml"
+        # older index without a snapshot
+        config.write("storage_dir: .\n") unless config.file?
+        return [hub, config, start.to_s, name]
+      end
+      if matches.length > 1
+        raise Exit.new(Ctl::EXIT_NO_HUB,
+                       "the service in #{start} is indexed in multiple hubs:\n  " +
+                       matches.map { |h, n| "#{h} (as #{n})" }.join("\n  ") +
+                       "\npass --config <hub-dir>/coderag.yml to pick one.")
+      end
+      raise Exit.new(Ctl::EXIT_NO_HUB,
+                     "no coderag.yml found here, in any parent directory, or " \
+                     "at the conventional hub mount (#{conv}); and no indexed " \
+                     "hub in #{Datadir.data_dir} matches the service in " \
+                     "#{start}.\nIndex the hub first — on the HOST, in the " \
+                     "folder containing all services, run `coderag index` — " \
+                     "and make sure the data dir (~/.local/share/coderag) is " \
+                     "mounted into this container." \
+                     "\nRun `msnav doctor` here to see what each resolution " \
+                     "step found.")
+    end
+  end
+end