fix: colab notebook - register src on kernel sys.path

Colab run 5 failed at cell 12 (import luke_scribe.config) because hatchling editable installs write a .pth pointing at src/ that the interpreter only reads at startup; a long-running Colab kernel started before pip install -e never sees it. Subprocesses (CLI) work, but kernel-side imports fail.

Fix: install cell now walks up to the repo root and inserts src/ into the kernel sys.path, verifying with import luke_scribe.config. Cell 12 has a defensive guard of the same kind. Tunnel external verification now retries up to 6x2s for DNS propagation. Troubleshooting section documents the issue.

scripts/build_colab_notebook.py

@@ -134,6 +134,17 @@ def cells() -> list[dict]:
             "print('LD_LIBRARY_PATH:', os.environ['LD_LIBRARY_PATH'])\n"
             "print('설치 완료')\n"
             "\n"
+            "# 실행 중인 Colab 커널은 새 .pth 파일을 읽지 못한다 (pip editable 설치는\n"
+            "# 인터프리터 시작 시에만 반영). → 커널 sys.path에 src/를 직접 등록해\n"
+            "# luke_scribe import를 보장한다 (서브프로세스 CLI는 .pth를 읽으므로 무관).\n"
+            "import sys, os as _os\n"
+            "_root = _os.getcwd()\n"
+            "while not _os.path.isdir(_os.path.join(_root, 'src', 'luke_scribe')) and _root != _os.path.dirname(_root):\n"
+            "    _root = _os.path.dirname(_root)\n"
+            "sys.path.insert(0, _os.path.join(_root, 'src'))\n"
+            "import luke_scribe.config as _cfg\n"
+            "print('패키지 임포트 OK →', _cfg.__file__)\n"
+            "\n"
             "# Cloudflare 터널용 cloudflared 바이너리 (실패해도 진행 — 터널 없이 로컬 사용 가능)\n"
             "!wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -O /usr/local/bin/cloudflared || echo 'cloudflared 다운로드 실패 — 터널 없이 계속합니다'\n"
             "!chmod +x /usr/local/bin/cloudflared 2>/dev/null; cloudflared --version 2>&1 | head -1 || echo 'cloudflared 미설치 — 터널 생략'\n"
@@ -272,11 +283,18 @@ def cells() -> list[dict]:
             "    print('🌐 Cloudflare 터널 (외부 접속):', TUNNEL_URL)\n"
             "    print('   대시보드 (API Docs):', TUNNEL_URL + '/docs')\n"
             "    print('   상태 (health):', TUNNEL_URL + '/health')\n"
-            "    try:\n"
-            "        ext = urllib.request.urlopen(TUNNEL_URL + '/health', timeout=15)\n"
-            "        print('   외부 접속 검증 OK (HTTP', ext.status, ')')\n"
-            "    except Exception as exc:\n"
-            "        print('   외부 접속 검증 실패 (브라우저에선 열릴 수 있음):', exc)\n"
+            "    # DNS 전파 지연 대비 재시도 (새 trycloudflare 호스트는 초반에 못 풀릴 수 있음)\n"
+            "    ext_ok = False\n"
+            "    for _ in range(6):\n"
+            "        try:\n"
+            "            ext = urllib.request.urlopen(TUNNEL_URL + '/health', timeout=15)\n"
+            "            print('   외부 접속 검증 OK (HTTP', ext.status, ')')\n"
+            "            ext_ok = True\n"
+            "            break\n"
+            "        except Exception:\n"
+            "            time.sleep(2)\n"
+            "    if not ext_ok:\n"
+            "        print('   외부 접속 검증 실패 (DNS 전파 지연이거나 Cloudflare 브라우저 체크 — 브라우저에서 직접 확인하세요)')\n"
             "    print('   ※ 임시 링크 — Colab 세션 종료 시 닫힘. API 호출에는 RAW_KEY(X-API-Key) 필요.')\n"
             "else:\n"
             "    print('터널 URL 미감지 — 서버 로그:')\n"
@@ -329,6 +347,14 @@ def cells() -> list[dict]:
             "# 12) 브로커 + 워커 포함 전체 흐름 (in-proc)\n"
             "# 서버의 in-proc 브로커에 enqueue된 job을 같은 프로세스의 워커가 소비하는 구조는\n"
             "# 프로세스 분리 필요 → 여기서는 클라이언트에서 직접 Worker.drain() 호출로 검증\n"
+            "# 커널 sys.path 보강 — editable 설치는 인터프리터 시작 시에만 반영되므로\n"
+            "# 실행 중인 커널은 src/를 직접 등록해야 한다 (셀 3에서도 처리하지만 방어적 가드)\n"
+            "import sys, os as _os\n"
+            "if not any(_os.path.isfile(_os.path.join(p, 'luke_scribe', 'config.py')) for p in sys.path):\n"
+            "    _root = _os.getcwd()\n"
+            "    while not _os.path.isdir(_os.path.join(_root, 'src', 'luke_scribe')) and _root != _os.path.dirname(_root):\n"
+            "        _root = _os.path.dirname(_root)\n"
+            "    sys.path.insert(0, _os.path.join(_root, 'src'))\n"
             "from luke_scribe.config import Settings\n"
             "from luke_scribe.jobqueue.broker import InProcBroker\n"
             "from luke_scribe.jobqueue.worker import Worker\n"
@@ -424,6 +450,10 @@ def cells() -> list[dict]:
             "- cloudflared는 셀 3에서 설치됩니다. 다운로드 실패 시 터널 없이 로컬(8000)에서 계속 사용할 수 있습니다.\n"
             "- 터널은 `http://localhost:8000`을 고정으로 바라봅니다. 다른 포트로 서버를 띄우면 터널이 연결되지 않습니다.\n"
             "- trycloudflare는 **인증 없는 Quick Tunnel**이라 URL만 알면 누구나 접근 가능합니다. 민감 데이터는 올리지 마세요.\n\n"
+            "### `No module named 'luke_scribe'` (셀 12에서 import 실패)\n\n"
+            "Colab 커널은 실행 중에는 pip editable 설치가 만든 .pth를 읽지 못합니다\n"
+            "(인터프리터 시작 시에만 반영). 설치 셀 3이 커널 sys.path에 `src/`를 직접\n"
+            "등록해 해결했습니다 — 이 셀만 다시 실행하려면 설치 셀 3(또는 전체)을 재실행하세요.\n\n"
             "### 모델 다운로드 실패\n\n"
             "- Hugging Face 연결 필요. 재시도: `LUKESCRIBE_MODEL_DOWNLOAD_RETRIES=3`\n"
             "- 특정 모델만: `--model large-v3-turbo` (기본) / `--model large-v3`\n"