From fd2de5b3bd5d2a718ca287f2b968c2209f1805ad Mon Sep 17 00:00:00 2001
From: Ajay Krishnan <ajay@krishnan.ca>
Date: Thu, 1 Oct 2026 13:05:07 -0700
Subject: [PATCH] Warn when start leaves a running docs service on old sources

docs-mcp reads its source list once at startup, and start never restarts
a running container, so a changed list was written but silently not
loaded. The README said start loaded source changes.
---
 README.md                 |  6 ++++--
 bin/context-kit           | 22 ++++++++++++++++++++++
 scripts/test-lifecycle.sh | 28 ++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index fb23b1c..9067b01 100644
--- a/README.md
+++ b/README.md
@@ -125,8 +125,10 @@ CONTEXT_KIT_DOCS_SOURCES="config/sources.default.txt config/sources.js.txt" \
   bin/context-kit restart
 ```
 
-Source changes are loaded by `start`/`restart`; `bin/context-kit docs` is only a
-stdio bridge to the already-running docs service.
+The docs service reads its source list once, at startup. After changing
+sources, run `restart`; `start` writes the new list but leaves a running docs
+service on the old one, and says so. `bin/context-kit docs` is only a stdio
+bridge to the already-running docs service.
 
 `docs_query` searches with FTS5 plus embeddings, deduplicates exact content,
 and supports source/host filters. It returns snippets but does not retrieve full
diff --git a/bin/context-kit b/bin/context-kit
index 535802f..297b7b5 100755
--- a/bin/context-kit
+++ b/bin/context-kit
@@ -661,6 +661,21 @@ shared_services_ready() {
   wait_for_searxng && wait_for_web_search_mcp && wait_for_docs_mcp
 }
 
+# start never recreates or restarts a running container, and docs-mcp reads its
+# sources file once at startup. A changed list under an already-running
+# docs-mcp is therefore written but not loaded until `restart`.
+running_docs_kept_prior_sources() {
+  local index
+  for ((index=0; index < ${#SHARED_SERVICES[@]}; index++)); do
+    [[ "${SHARED_SERVICES[index]}" == "${DOCS_SERVICE_NAME}" ]] || continue
+    [[ "${SNAPSHOT_RUNNING[index]}" -eq 1 ]] || return 1
+    [[ "${DOCS_SOURCES_PRIOR_PRESENT}" -eq 1 ]] || return 0
+    ! cmp -s -- "${DOCS_SOURCES_BACKUP_FILE}" "${DOCS_SOURCES_FILE}"
+    return
+  done
+  return 1
+}
+
 start_locked() {
   prepare_data_dirs
   if ! docker image inspect "${WEB_SEARCH_IMAGE}" >/dev/null 2>&1 || ! docker image inspect "${DOCS_IMAGE}" >/dev/null 2>&1; then
@@ -691,9 +706,16 @@ start_locked() {
   if [[ "${result}" -eq 0 ]] && ! shared_services_ready; then
     result=1
   fi
+  local reload_needed=0
+  if [[ "${result}" -eq 0 ]] && running_docs_kept_prior_sources; then
+    reload_needed=1
+  fi
   if [[ "${result}" -eq 0 ]] && discard_docs_sources_transaction; then
     LIFECYCLE_STATE_ROLLBACK_ACTIVE=0
     disarm_lifecycle_transaction_traps
+    if [[ "${reload_needed}" -eq 1 ]]; then
+      warn "docs sources changed, but ${DOCS_SERVICE_NAME} was already running and reads them only at startup; run 'context-kit restart' to load them"
+    fi
     return 0
   fi
   [[ "${result}" -ne 0 ]] || result=1
diff --git a/scripts/test-lifecycle.sh b/scripts/test-lifecycle.sh
index 8108e7e..7b0471e 100644
--- a/scripts/test-lifecycle.sh
+++ b/scripts/test-lifecycle.sh
@@ -423,6 +423,34 @@ seed_service docs-mcp
 grep -F 'up -d --no-recreate searxng web-search-mcp docs-mcp' "${FAKE_DOCKER_LOG}" >/dev/null || fail_test "upgrade omitted --no-recreate"
 grep -E 'docker (network|volume) rm' "${FAKE_DOCKER_LOG}" >/dev/null && fail_test "upgrade removed an origin resource"
 
+new_case start-sources-under-running-docs
+seed_service searxng
+seed_service web-search-mcp
+seed_service docs-mcp
+printf 'https://example.test/llms.txt\n' > "${CASE_ROOT}/sources.txt"
+export CONTEXT_KIT_DOCS_SOURCES="${CASE_ROOT}/sources.txt"
+"${CONTEXT_KIT}" restart
+"${CONTEXT_KIT}" start >"${CASE_ROOT}/unchanged.out" 2>&1
+grep -F "context-kit restart" "${CASE_ROOT}/unchanged.out" >/dev/null \
+  && fail_test "start asked for a restart although docs sources were unchanged"
+printf 'https://example.test/llms.txt\nhttps://added.example.test/llms.txt\n' > "${CASE_ROOT}/sources.txt"
+"${CONTEXT_KIT}" start >"${CASE_ROOT}/changed.out" 2>&1
+grep -F "run 'context-kit restart' to load them" "${CASE_ROOT}/changed.out" >/dev/null \
+  || fail_test "start changed docs sources under a running docs-mcp without saying they need a restart"
+grep -F 'https://added.example.test/llms.txt' "${CONTEXT_KIT_DATA_DIR}/docs-sources.txt" >/dev/null \
+  || fail_test "start did not write the changed docs sources"
+assert_no_docs_sources_artifacts
+
+new_case start-sources-with-stopped-docs
+seed_service searxng
+seed_service web-search-mcp
+seed_service docs-mcp stopped
+printf 'https://example.test/llms.txt\n' > "${CASE_ROOT}/sources.txt"
+export CONTEXT_KIT_DOCS_SOURCES="${CASE_ROOT}/sources.txt"
+"${CONTEXT_KIT}" start >"${CASE_ROOT}/start.out" 2>&1
+grep -F "context-kit restart" "${CASE_ROOT}/start.out" >/dev/null \
+  && fail_test "start asked for a restart although it started docs-mcp with the new sources"
+
 new_case replacement-required
 seed_service searxng
 seed_service web-search-mcp