Skip to content

fix(knowledge): read the context search's config off the event loop - #22222

Merged
bolichen97 merged 2 commits into
mainfrom
fix/22209-knowledge-context-config-off-loop
Oct 19, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/22209-knowledge-context-config-off-loop

Conversation

@cruisercohen

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Main's ratchet lane goes green again by moving the chat context search's config.json read off the event loop.

Main Ratchet Audit → Backend ratchet & baseline gates has failed on every main push since 28ee969f83 (#22084, 07:09 PDT 10-19; first red run 39266424032, job Backend ratchet & baseline gates), tracked by #22209. Only one step fails, Check for blocking IO inside async def, on the fs ledger:

blocking IO inside an `async def` in a file the baseline does not list.
  dashboard/handlers/knowledge_agent_context.py:83: blocking fs call on the event loop
1 baselined file(s) now have fewer on-loop blocking calls.
  dashboard/handlers/knowledge.py: 1 -> 0
sync-io-in-async gate FAILED: 1 new offender(s), 0 grown count(s), 0 file(s) with new calls on added lines, 1 entr(y/ies) to prune.

Every other gate in the lane passes. The same gate runs on pull requests, so each PR inherits this red.

Why it matters

The red hides any real drift a later push adds to that lane, and every open PR carries it. The flagged call itself is also a real stall: search_for_context stat'ed and read config.json on the loop, so a home on a mount that stopped answering would hold every endpoint until the kernel gave up.

Not a goal

What changed (motivation → approach → change)

  • Cause: a merge race between two PRs. refactor(dashboard): split updates and knowledge handlers into owners #22073 (01:14 PDT) split handlers/knowledge.py into owners and moved search_for_context into knowledge_agent_context.py. ci(sync-io): gate filesystem syscalls inside async def #22084 (07:09 PDT) added the fs gate with a baseline built on an older base, where that call still sat in handlers/knowledge.py. On the merged tree the call reads as a new offender and its old row as stale.
  • Fix at the root rather than moving the row: the stat and read go into _read_knowledge_config(), which search_for_context awaits with asyncio.to_thread, as the other dashboard handlers that read the gateway's own config do. The path is the gateway's own (data_home()), never the request's, so the default executor is the lane the gate names, not the bounded request-path probe pool. Behaviour is unchanged: a missing, unreadable, malformed or wrong-typed file or knowledge block still reads as {}.
  • The stale handlers/knowledge.py row is removed by the gate's own --update-baseline (shrink-only: one line deleted, no count raised, no row or marker added).
  • handlers/knowledge.py (the facade) lists the new helper in its TYPE_CHECKING manifest, which test_facade_mirror_guards.py requires.

Backwards compatibility

Compatible: the route, its query parameters, its response and its config fallbacks are unchanged; only the thread the config read runs on moves.

Removes nothing: the one deleted line is a baseline row for a file that no longer has the offence, and the test allowance dropped was the on-loop exception for this same call.

Tests

  • test_knowledge_onloop_fs.py::TestStaticRatchet::test_no_coroutine_touches_the_filesystem_on_the_loop: the ("search_for_context", "exists") on-loop allowance is gone, so the ratchet now refuses that call. It fails on main's code (search_for_context:83 exists) and passes here.
  • New TestSearchForContext::test_config_read_runs_off_the_loop: serves the route against a real config.json (its fetch_max_tokens reaches the response, so the read happened) and asserts the file is never touched on the loop's thread. It fails on main's code ([('exists', 'MainThread')]) and passes here.
  • Ran locally with RATCHET_SCOPE_WHOLE_TREE=1, as the lane does: check_sync_io_in_async.py --test and the gate itself (pass, 138 known calls in 57 files), plus the lane's black, file-line-cap, subprocess-encoding, acp-frame-host-data, agent-sdk-boundary, cwd-relative-reads and lockdown gates and its census + config-baseline tests (all pass).
  • pytest (660 passed): test_knowledge_onloop_fs, test_sync_io_in_async_gate, test_knowledge_handlers_facade, test_facade_mirror_guards, test_knowledge_handlers_coverage*, test_cse_2026_08_05_fixes, test_no_config_dir_in_async, test_knowledge_cross_thread, test_knowledge_search_upgrade, test_campaign_facades_base_public_names, test_config_json_bom, test_json_object_body_guard, test_knowledge_owner_gate.
  • black, isort, flake8 and mypy clean on the touched files.

Manual verification

N/A — unit coverage sufficient: the change only moves a read onto a worker thread, and the tests above prove both the thread and the read's result.

Related Issues

Refs #22209 (the audit workflow closes it on the next all-green main push). Cause: #22073 + #22084.

Pattern harvest

Rule candidate: review-prompt
Pattern: a PR that adds a path-keyed baseline must rebuild it on current main right before merge; a file split that lands first moves rows to new paths (here #22073 vs #22084).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

search_for_context stat'ed and read the gateway's config.json inside the
coroutine. #22084's fs gate flags that call; its baseline row named
handlers/knowledge.py, but #22073 had already moved search_for_context into
knowledge_agent_context.py, so main's ratchet lane reads one new offender
plus one stale row (red since 28ee969).

The read now runs in _read_knowledge_config on asyncio.to_thread (the path
is the gateway's own, not the request's). The stale knowledge.py row is
pruned with --update-baseline, and test_knowledge_onloop_fs.py drops the
on-loop allowance for that call and proves the read leaves the loop thread.

Refs #22209
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ba4c6a4857475ef6fd3dd03c088478640a55a686 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 19, 2026
@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ba4c6a4857475ef6fd3dd03c088478640a55a686 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] ba4c6a4

Description read

[DESCRIPTION-READ] 5f3f396e89ba952f262ab50ecd88247bd5861c7bbdceed04338577927208f80d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ba4c6a4857475ef6fd3dd03c088478640a55a686 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check that the ratchet lane is green on a fresh rebase. The baseline is path-keyed, and the race that caused this could happen again.

What this change ships

Inventory (5 items) — 5 justified

Intent: get main's ratchet lane green again by moving the chat context search's config.json read off the event loop. This is a FIX.

  1. The context search now reads config.json on a worker thread, so a stalled home mount no longer freezes every endpoint. — justified
  2. The stale handlers/knowledge.py row is removed from the fs baseline, as the gate's shrink-only update requires. — justified
  3. The on-loop allowance for search_for_context is removed from the knowledge ratchet test, so that call is now refused there. — justified
  4. The facade's TYPE_CHECKING manifest lists _read_knowledge_config, which test_facade_mirror_guards.py requires. — justified
  5. A new route test shows the config read never runs on the loop's thread and that its value reaches the response. — justified

[FIRST-PRINCIPLES-REVIEWED] ba4c6a4

Description read

[DESCRIPTION-READ] 6d8e6f1e2fda59242f064df224cd4bd745e029f6a0a9c42a40286e0129444d2d

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ba4c6a4857475ef6fd3dd03c088478640a55a686 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ba4c6a4

Verdict parsed from the review's SHA-scoped output markers for commit ba4c6a4857475ef6fd3dd03c088478640a55a686.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ba4c6a4857475ef6fd3dd03c088478640a55a686: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ba4c6a4857475ef6fd3dd03c088478640a55a686 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ba4c6a4

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ba4c6a4857475ef6fd3dd03c088478640a55a686: <one-sentence reason>

@cruisercohen
cruisercohen marked this pull request as ready for review October 19, 2026 16:43
@cruisercohen
cruisercohen requested review from a team and KiroCrewCaptain as code owners October 19, 2026 16:43
@cruisercohen
cruisercohen enabled auto-merge (squash) October 19, 2026 16:43
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 19, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to ship. One maintainer check remains before approval: the required checks on this head.

Head reviewed: 46d2e0d. Bots read: Design PASS, First Principles PASS, UX skipped, Opus no blocking findings, GPT no blocking findings. Readiness is action required.

What I checked:

  • The diff matches the description. _read_knowledge_config() keeps every fallback of the old inline read: a missing, unreadable, malformed or wrong-typed file or block still gives {}.
  • The path comes from data_home(), not from the request. So the default executor through asyncio.to_thread is the correct lane, not the bounded probe pool.
  • The facade manifest entry is needed. The facade mirror makes monkeypatch.setattr(kh, "data_home", ...) reach the owner module, so the new test patches the real reader.
  • The baseline edit only removes one row. No count goes up and no row is added.
  • I ran these at this head: test_knowledge_onloop_fs.py, test_facade_mirror_guards.py and test_knowledge_handlers_facade.py (84 passed). I also ran check_sync_io_in_async.py on the whole tree (pass, 138 known calls in 57 files).
  • I put the old inline read back and ran the new test again. It fails with [('exists', 'MainThread')], and the static ratchet test also fails. So both tests go red if the fix regresses.

Why I do not approve yet: the backend test shards were skipped on this head because the Fast Gate is red. The Coverage Gate fails closed for the same reason, and the Harness Parity Gate shows the known allowlist failure from main. None of these come from this diff. When main is green again and readiness shows passed on this head, this is ready to approve and merge.

No must-fix or should-fix findings.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 19, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at head ba4c6a4.

This head only merges main into the branch. The PR's own patch is byte-identical to the one I reviewed at 46d2e0d (same four files, same 172-line diff), so my earlier review still holds: 0 findings, and both new tests fail if the old on-loop config read is put back.

Gates checked on this head:

  • Readiness is passed.
  • CI is green, including all eight Linux backend shards, all eight Windows backend shards, Coverage Combine and Coverage Gate. These were the checks that were red or skipped before.
  • Harness Parity Gate, Static Ratchet Gate and the AI review lanes (Design, First Principles, Opus, GPT) all pass, with no blocking finding.
  • The branch is mergeable into main. No security denylist path is touched, and the .github/ change only removes one row from a baseline data file.

@bolichen97
bolichen97 merged commit c3f2b27 into main Oct 19, 2026
103 checks passed
@bolichen97
bolichen97 deleted the fix/22209-knowledge-context-config-off-loop branch October 19, 2026 19:15
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants