fix(monorepo): harden grounding and python startup readiness

Author: maehwasoo

apps/api/src/ailss_api/agent.py

@@ -371,13 +371,27 @@ def _compose_answer(
     results: Sequence[RetrieveResult],
     note_excerpts: list[str | None],
 ) -> str:
-    segments = [f'Local baseline answer for "{user_input}":']
+    segments: list[str] = []
     for result, note_excerpt in zip(results, note_excerpts, strict=True):
+        evidence = _select_answer_evidence_text(result, note_excerpt)
+        if evidence is None:
+            continue
         label = result.title or result.path
         summary = result.summary or result.snippet
-        evidence = note_excerpt or result.evidence_text or result.evidence[0].text
         segments.append(f"{label} ({result.path}) points to {summary}. Evidence: {evidence}")
-    return " ".join(segments)
+    if not segments:
+        return ""
+    return f'Local baseline answer for "{user_input}": ' + " ".join(segments)
+
+
+def _select_answer_evidence_text(result: RetrieveResult, note_excerpt: str | None) -> str | None:
+    if note_excerpt:
+        return note_excerpt
+    if result.evidence_text:
+        return result.evidence_text
+    if result.evidence:
+        return result.evidence[0].text
+    return None
 
 
 def _read_note_excerpt(settings: Settings, note_path: str) -> str | None:

apps/api/tests/test_agent.py

@@ -195,6 +195,45 @@ def test_agent_run_cites_hit_chunk_when_neighbors_precede_match(
     assert payload["citations"][0]["chunk_id"] == "docs-03-plan-1"
 
 
+def test_agent_run_fails_when_selected_results_have_no_grounding_evidence(
+    tmp_path: Path, monkeypatch: MonkeyPatch
+) -> None:
+    settings = build_settings_with_seed_data(tmp_path)
+    monkeypatch.setattr(
+        "ailss_api.agent.retrieve_notes",
+        lambda request, settings: RetrieveResponse(
+            query=request.query,
+            mode="semantic_local",
+            results=[
+                RetrieveResult(
+                    path="missing.md",
+                    title="Ungrounded note",
+                    summary="Missing note file and no indexed evidence.",
+                    snippet="Indexed snippet without inspectable evidence.",
+                    evidence_text=None,
+                    evidence=[],
+                )
+            ],
+            usage=RetrievalUsage(latency_ms=1.0, used_chunks_k=1),
+        ),
+    )
+    client = TestClient(create_app(settings))
+
+    response = client.post(
+        "/agent/run",
+        json={
+            "input": DEFAULT_AGENT_INPUT,
+            "context": {"top_k": 1},
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["outcome"] == "failed"
+    assert payload["answer"] is None
+    assert payload["failure"]["code"] == "grounding_failure"
+
+
 def test_agent_run_rejects_write_request_without_apply(tmp_path: Path) -> None:
     settings = build_settings_with_seed_data(tmp_path)
     client = TestClient(create_app(settings))

packages/obsidian-plugin/src/pythonApi/pythonApiServiceController.ts

@@ -35,6 +35,9 @@ type PortNegotiationResult = {
 	shutdownSucceeded: boolean;
 };
 
+const PYTHON_API_READY_TIMEOUT_MS = 30_000;
+const PYTHON_API_READY_POLL_INTERVAL_MS = 150;
+
 export class PythonApiServiceController {
 	private proc: ChildProcess | null = null;
 	private stopRequested = false;
@@ -310,8 +313,8 @@ export class PythonApiServiceController {
 			await waitForPythonApiHealth({
 				host: preflight.host,
 				port: preflight.port,
-				timeoutMs: 5_000,
-				pollIntervalMs: 150,
+				timeoutMs: PYTHON_API_READY_TIMEOUT_MS,
+				pollIntervalMs: PYTHON_API_READY_POLL_INTERVAL_MS,
 			});
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);

packages/obsidian-plugin/test/pythonApi/pythonApiServiceController.startupHelpers.test.ts

@@ -4,10 +4,16 @@ vi.mock("../../src/utils/tcp.js", () => ({
 	waitForTcpPortToBeAvailable: vi.fn(),
 }));
 
+vi.mock("../../src/pythonApi/client.js", () => ({
+	requestPythonApiShutdown: vi.fn(),
+	waitForPythonApiHealth: vi.fn(),
+}));
+
 import {
 	PythonApiServiceController,
 	type PythonApiServiceControllerDeps,
 } from "../../src/pythonApi/pythonApiServiceController.js";
+import { waitForPythonApiHealth } from "../../src/pythonApi/client.js";
 import { waitForTcpPortToBeAvailable } from "../../src/utils/tcp.js";
 
 type TestSettings = ReturnType<PythonApiServiceControllerDeps["getSettings"]>;
@@ -32,6 +38,7 @@ type ControllerInternals = {
 		shutdownAttempted: boolean;
 		shutdownSucceeded: boolean;
 	}>;
+	waitUntilHealthy: (preflight: StartupPreflight) => Promise<void>;
 	composePortInUseErrorMessage: (options: {
 		host: string;
 		port: number;
@@ -104,6 +111,7 @@ function createController(
 
 describe("PythonApiServiceController startup helper branches", () => {
 	const waitForPort = vi.mocked(waitForTcpPortToBeAvailable);
+	const waitForHealth = vi.mocked(waitForPythonApiHealth);
 
 	beforeEach(() => {
 		vi.clearAllMocks();
@@ -154,6 +162,26 @@ describe("PythonApiServiceController startup helper branches", () => {
 		expect(saveSettings).not.toHaveBeenCalled();
 	});
 
+	it("waits long enough for Python uv cold starts during readiness checks", async () => {
+		const { controller } = createController();
+		const internals = asInternals(controller);
+		const preflight = await internals.prepareStartupPreflight();
+		waitForHealth.mockResolvedValue({
+			status: "ok",
+			service: "ailss-api",
+			version: "0.1.0-dev",
+			checks: {},
+		});
+
+		await expect(internals.waitUntilHealthy(preflight)).resolves.toBeUndefined();
+		expect(waitForHealth).toHaveBeenCalledWith({
+			host: "127.0.0.1",
+			port: 8787,
+			timeoutMs: 30_000,
+			pollIntervalMs: 150,
+		});
+	});
+
 	it("returns available when the Python port is already free", async () => {
 		const { controller } = createController();
 		const internals = asInternals(controller);