feat(knowledge): config-driven extraction pool effort

[atomsbaza]

Re-created from #8345: its head branch had been corrupted by an orphan (parent-less) commit, and GitHub does not allow reopening a closed PR after the head branch was force-pushed. This PR carries the same single commit, rebuilt on current main (d63917efb), with targeted tests passing locally.

Problem / Motivation

Knowledge extraction effort was hardcoded to high for the Knowledge LLM pool: operators could not tune cost/latency/quality for extraction, and Knowledge config could silently resize unrelated LLM pools.

Why it matters

Extraction is the dominant cost driver of the knowledge pipeline. An operator running a cheap local model wants low; a quality-critical deployment wants max. The old constant made that impossible, and the shared pool-size key let a knowledge config change silently resize pools it did not own.

The change

• knowledge.extraction_effort config key (enum: '' inherit, low, medium, high, xhigh, max). Resolution: explicit key → agent.role_efforts.background → high (last resort).
• Effort application in AcpWorker gated on model_supports_effort for the served model (_resolved_model_id, falling back to _model), so an auto selector that resolves to a reasoning model still applies effort.
• config_pool_size_key replaces use_config_pool_size: a pool declares WHICH config key owns its width, so knowledge.extraction_pool_size can no longer resize the URL-fetch pool.
• The legacy knowledge_llm_pool alias is dropped: URL sync requires knowledge_fetch_pool explicitly and answers 503 with a machine-readable code when it is absent.
• Settings tab: extraction effort selector (Default/Low/Medium/High/Extra High/Max + inherit hint + restart badge) and pool size on the Knowledge page; i18n keys under pages.knowledge.settings.* in all catalogs; capture harness in website/scripts/capture-knowledge-effort.mjs.

Screenshots / video

Test plan

• test/test_knowledge_effort_pools.py — pool wiring + effort resolution chain
• test/test_knowledge_handlers_coverage.py — handler routes, 503 fail-loudly, background-task parking
• test/test_llm_pool.py — LLMPool semantics incl. model-support gate
• Backend targeted suites pass locally; black/isort/flake8 clean

[github-actions]

Design Review (Fable 5, fork) — 🔴 BLOCK (blocking)

Design-level review of 5c7227039db59e11453f05ee78a6237ac18fdb89 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The base tree confirms it: _hand_off_under_gate, _watch_knowledge_config, vector_leg/embed_sig, and the embed-priority plumbing all exist on current main, and this patch deletes every one of them. The rebuilt branch was reconstructed from a stale snapshot and clobbers intervening main changes. I have what I need for the verdict.

Design-Verdict: BLOCK

The rebuilt branch reverts landed main work wholesale — concurrency fixes, the live-config watcher, and the embed-signature guard vanish undocumented.

Blockers

Stale-base reconstruction silently reverts intervening main changes across knowledge.py, tests, and repo baselines.
The PR was "rebuilt on current main via a 3-way merge against the original merge-base," but the diff deletes code that exists on main today and that the description never mentions: _hand_off_under_gate/handoff_gate_context (the ingestion-gate hold protecting sync/upload rows from the orphan sweep — reintroducing the bare UPDATE sources SET sync_status = 'syncing' stamp), _watch_knowledge_config/_apply_knowledge_config (live knowledge.* appliers — embedder tuning and the artifact auto-ingest toggle stop applying without restart), vector_leg/embed_sig (the vector-space-identity guard in retrieval), the embed priority plumbing, and the off-loop KiroCrewConfig.load() in _start_artifact_ingest_async (now blocks the event loop). It also deletes the pinning test test_the_gate_is_held_from_the_lookup_through_the_ingest as if it were a gap, and regenerates black-baseline.txt and error-code-baseline.json against the stale tree — raising missing_code 1127→1134 in files this PR never touches, which that file's own header forbids. Merging ships silent regressions in a core subsystem while the description claims the PR was kept "concurrency-review-light."
Fix: rebase the single commit onto actual current main, resolving every conflict in favor of main's knowledge.py/tests/baselines, and re-apply only the effort/pool-key feature.
Clears when: the diff against main contains no deletions of _hand_off_under_gate, _watch_knowledge_config, vector_leg, or the priority parameters, and the baseline files change only for lines this PR's own code causes.

Watch

The inherit chain makes agent.role_efforts.background newly govern extraction (previously pinned high) — an intentional policy change the author explicitly asks maintainers to ratify, not just review.
Clears when: a maintainer confirms extraction should follow the background role by default, or the chain drops that middle step.

Suggestions

• Drop temp-screenshots/ from the repo; screenshots belong in the PR description, not tracked files.
• The feature itself (effort_key/config_pool_size_key bindings, explicit 503 over the alias fallback) is sound — once rebased cleanly it should be a small, reviewable diff.

[DESIGN-REVIEWED] 5c72270

[github-actions]

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

Reviewed 5c7227039db59e11453f05ee78a6237ac18fdb89 via the fork AI-review pipeline; updated in place on each push.

4 of 5 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/dashboard/handlers/knowledge.py:430 -- Available-embedder searches crash
retriever = HybridRetriever(store, embedder=embed_fn)
Available embedder -> search handlers omit required embed_sig -> constructor raises ValueError -> HTTP 500.
Anchor: residual/crash-data-loss-corruption
Fix: Resolve and pass both values with vector_leg() at both search sites.

BLOCKING -- src/kiro_crew/dashboard/handlers/knowledge.py:1477 -- URL sync permanently strands sources
"UPDATE sources SET sync_status = 'syncing' WHERE id = ?", (source_id,)
URL sync -> handler pre-marks syncing -> _background_agent_sync cannot claim it -> no fetch occurs and retries return 409.
Anchor: residual/crash-data-loss-corruption
Fix: Remove the pre-mark and let the background task atomically claim the source.

BLOCKING -- src/kiro_crew/dashboard/handlers/knowledge.py:1439 -- Removed handoff gate permits ingestion data loss
task = asyncio.create_task(_ingest_local_file_task(...)); task = asyncio.create_task(_bg_ingest(...))
Post-bind orphan reclaim overlaps a local resync or repeated upload -> source is deleted before the task claims its gate -> API reports scheduled work while the source or staged upload is lost.
Anchor: residual/guard-removal
Fix: Restore the ingestion-gate handoff from source lookup/creation until the child holds or settles its claim.

BLOCKING -- src/kiro_crew/dashboard/handlers/knowledge.py:250 -- Config loading blocks the startup event loop
cfg = KiroCrewConfig.load()
Startup with filesystem-backed config -> async startup callback performs synchronous config I/O -> gateway loop and readiness stall until I/O completes.
Anchor: no-blocking-call-on-event-loop
Fix: Restore await asyncio.to_thread(KiroCrewConfig.load).

BLOCKING -- src/kiro_crew/dashboard/handlers/knowledge.py:2757 -- Knowledge live-config handling is removed
- app.on_startup.append(_watch_knowledge_config)
Runtime Knowledge config save -> no subscriber applies embedder or artifact-ingest changes -> running behavior remains stale despite a successful save.
Anchor: residual/guard-removal
Fix: Restore the Knowledge config subscription and guarded appliers.

[BLOCK-MERGE] 5c72270
[GPT-REVIEWED] 5c72270

Adjudication (Opus 4.8) — is blocking on each finding proportionate?

Analysis complete. I opened the base code each finding names and the code it calls into.

F4 (adjudicable) — _start_artifact_ingest_async is registered as an on_startup hook (knowledge.py:2923), so it runs on the live loop; the base at knowledge.py:257 loads config via await asyncio.to_thread(...) precisely because the docstring at 252-254 states KiroCrewConfig.load() is filesystem work. The PR replaces it with a synchronous KiroCrewConfig.load(), stalling the startup loop. The remedy is restoring one line already present in base — near-zero cost, no new state, no invariant. A trivial fix cannot exceed even a LOW startup-stall harm, so blocking is proportionate.

Fenced findings — all confirmed reachable on ordinary paths, none extreme:

• F1: HybridRetriever.__init__ raises ValueError at retrieval.py:129-134 whenever embedder is passed without embed_sig; the PR passes embed_fn truthy with no sig, so any search with an available embedder 500s — the common path.
• F2: _claim_sync guards on WHERE ... sync_status <> 'syncing' (knowledge.py:1073-1076); the PR pre-marks the row 'syncing' before spawning the task, so _claim_sync returns False, _background_agent_sync returns at knowledge.py:1644 without fetching, and retries hit the 409 — the normal URL-sync path strands.
• F3: removes the ingestion-gate hand-off that closed the orphan-sweep-vs-resync/upload race; a genuine timing window, not an extreme one.
• F5: removes the live knowledge.* subscription; a runtime config save is an ordinary user action, leaving behavior stale until restart.

None reach the FLAG bar (extreme/contradictory conditions); each is reachable in normal operation.

[ADJUDICATION] 5c72270 total=1 uphold=1 downgrade=0
UPHOLD F4 src/kiro_crew/dashboard/handlers/knowledge.py:250 reason=harm-warrants-remedy
[GPT-ADJUDICATED] 5c72270
[ADJUDICATION-FENCED] 5c72270 fenced=4 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/dashboard/handlers/knowledge.py:430 -- HybridRetriever requires embed_sig alongside a truthy embedder (retrieval.py:129), so every search with an available embedder raises ValueError and 500s on the common path.
UPHOLD-FENCED F2 src/kiro_crew/dashboard/handlers/knowledge.py:1477 -- Pre-marking 'syncing' defeats _claim_sync's sync_status <> 'syncing' guard, so the background task returns without fetching and the URL source is stranded with 409 retries.
UPHOLD-FENCED F3 src/kiro_crew/dashboard/handlers/knowledge.py:1439 -- Removing the ingestion-gate hand-off reopens a real orphan-sweep-vs-resync/upload race; the window is reachable under load, not an extreme condition.
UPHOLD-FENCED F5 src/kiro_crew/dashboard/handlers/knowledge.py:2757 -- Dropping the knowledge.* live subscription leaves a runtime config save stale until restart; the triggering save is an ordinary action, so conditions are not extreme.
[GPT-ADJUDICATED-FENCED] 5c72270

[github-actions]

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of 5c7227039db59e11453f05ee78a6237ac18fdb89 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

Solid, pattern-following settings row — but the disabled-state hint's deixis lies in the auto case, the restart chip contradicts the product's own restart badge, and no screenshot could be opened.

Watch

• Disabled-state hint misleads in the common case: the row reuses effort_needs_reasoning_model ("…no effect on the model selected above"), but when Extraction model is auto the deciding model is the chat default from Settings → Chat — the select above literally reads "auto (use chat model)", so the user is told a model they never selected here is at fault (this exact case is what seedCfg({}, 'claude-haiku-4.5') pins). Frequent (auto is the default) × confusion × every visit — add a Knowledge-specific string naming the effective model.
• The hand-rolled restart required chip diverges from the product's single schema-driven pill (RestartRequiredBadge: "changes need a restart" + icon + tooltip telling the user how to restart). It is always-on while the adjacent pool-size row's SchemaRestartBadge renders nothing (knowledge.extraction_pool_size isn't marked boot-only), so two same-semantics rows read differently and the chip offers no next step. Reuse the existing badge/copy or mark the key in the schema.
• The diff deletes _watch_knowledge_config/_apply_knowledge_config (handlers/knowledge.py), so this same tab's existing "Auto-add saved artifacts" toggle and embed tuning stop applying live: the toggle saves "successfully" and silently does nothing until a gateway restart, with no restart indication on that row.

Evidence gaps

• All four screenshots (default row with hint + chip, open selector with six levels, picked state, disabled/unsupported state) are fork raw URLs / committed PNGs the workflow did not materialize — nothing rendered was viewable, and no first-time reader has seen the "Extraction effort" control. Push the branch to this repository (blind read runs) or attach the images as github user-attachments assets.

Suggestions

• Unify the two hints: effort_model_unknown_hint quotes 'Default', effort_hint doesn't — pick one form (and match the translations' typographic quotes).

[UX-REVIEWED] 5c72270

[github-actions]

First Principles Review (Fable 5, fork) — 🔴 BLOCK

Premise-level review of 5c7227039db59e11453f05ee78a6237ac18fdb89 via the fork AI-review pipeline — 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.

All verification is done. The base tree confirms: the deleted functions (_watch_knowledge_config, _hand_off_under_gate, vector_leg wiring) exist at base and would be removed by this merge; the new select_effort_level has zero consumers while its "dropped" private twin survives; both CI baselines move the wrong way. Final review follows.

First-Principles-Verdict: BLOCK

The stale "3-way merge" silently reverts four shipped mainline mechanisms and regresses two CI baselines; the declared effort feature is the minority of this diff.

Not justified as shipped

• Item 7 — undeclared: deletes the live knowledge.* config watcher; embedder tuning and the auto-ingest toggle silently become restart-only.
• Item 8 — undeclared: deletes _hand_off_under_gate/claim_settled and its pin test, reopening the orphan-sweep race its own comments document.
• Item 9 — undeclared: deletes vector_leg/embed_sig wiring whose deleted assertion names the defect it closes.
• Item 10 — undeclared: raises the error-code baseline and grows the black baseline with ~20 files this PR never touches.
• Item 6 — zero consumers: public select_effort_level added while the private duplicate it "replaced" stays and is still the one called.

What this change ships

Inventory (10 items) — 5 justified

Intent: let operators tune the Knowledge extraction pool's reasoning effort instead of a hardcoded high — a FIX-plus-ADDITION hybrid; everything outside the pool/effort/UI surface rides along.

1. New knowledge.extraction_effort key with explicit → background-role → high resolution — justified
2. Extraction now follows agent.role_efforts.background where it was always high — justified
3. /effort push gated on the served model (_resolved_model_id falling back to _model) — justified
4. Pool-size config binding is now per-workload (config_pool_size_key); unrelated pools can't be resized — justified
5. knowledge_llm_pool alias removed; URL sync without a fetch pool is a 503 knowledge_fetch_pool_unavailable — justified
6. New public kiro_crew.effort.select_effort_level — zero consumers; only test_effort.py imports it, llm_pool.py still defines and calls _select_effort_level
7. Live knowledge.* config appliers deleted (_watch_knowledge_config, _apply_knowledge_config, _stop_artifact_ingest) — undeclared, rides along
8. Ingestion-gate handoff removed from sync/upload/ingest-text paths plus its pin test — undeclared, rides along
9. Retriever loses vector_leg/embed_sig; comments reverted to the pre-in-process "Ollama" architecture — undeclared, rides along
10. error-code and black baselines regenerated against a stale tree — undeclared, rides along

Blockers

• Undeclared reverts of shipped mainline work. The description claims one commit "rebuilt on current main," but the diff deletes code present at base: the live config watcher (knowledge.py:275-346), the gate handoff (knowledge.py:1499+) with the test whose deleted comment says "without the hold the sweep could delete the row in that gap," and the vector_leg pair whose deleted assertion reads "the defect the pair closes." Deleted pins recast as nothing, with no evidence. Subtraction: rebase so handlers/knowledge.py carries only the pool/503 changes.
  Clears when: a re-pushed diff that deletes none of _watch_knowledge_config, _hand_off_under_gate, vector_leg.
• Baseline regressions. error-code-baseline.json raises missing_code 1127→1134 and dynamic_status 39→42 in six files this PR doesn't touch, against its own "Never raise a number to make CI pass"; black-baseline.txt (a shrink-only not-yet-clean list) gains ~20 unrelated entries while the description says "black baseline (shrink-only)". Subtraction: drop both baseline diffs except the knowledge entries this PR genuinely cleans.
  Clears when: baseline diffs touch only files this PR reformats, totals not raised.
• select_effort_level duplicates an existing mechanism with zero consumers. Grep: only test_effort.py imports it; llm_pool.py:360 still calls the private _select_effort_level the description says "was dropped in favor of the shared" helper. Subtraction: delete the new public helper.
  Clears when: one copy of the ladder exists with ≥1 non-test consumer.

Watch

• The claimed "latent NameError (is_claude vs via_config_option)" does not exist at base — llm_pool.py:350-351 uses via_config_option correctly and its docstring records _is_claude was already replaced. The model gate must stand on its own rationale, not this stale defect.
  Clears when: the description drops the NameError claim or points at the base line that raises it.

[FIRST-PRINCIPLES-REVIEWED] 5c72270

[github-actions]

Opus 4.8 Review (fork) — 🔴 changes requested (blocking)

Reviewed 5c7227039db59e11453f05ee78a6237ac18fdb89 via the fork AI-review pipeline; updated in place on each push.

BLOCKING — URL/web source sync self-strands: the handler pre-stamps 'syncing', then _background_agent_sync's claim can never win, so the fetch never runs and the row is stuck forever.

[BLOCK-MERGE] 5c72270

BLOCKING — src/kiro_crew/dashboard/handlers/knowledge.py (sync_source, agent/URL branch)

await asyncio.to_thread(lambda: store.db.execute(
    "UPDATE sources SET sync_status = 'syncing' WHERE id = ?", (source_id,)))
await asyncio.to_thread(lambda: store.db.commit())
task = asyncio.create_task(_background_agent_sync(source_id, url, source["name"], store, pipeline, pool))

Input POST /api/knowledge/sources/{id}/sync on any web/URL source → handler commits sync_status='syncing' → spawns _background_agent_sync, whose first act is _claim_sync (UPDATE ... WHERE id=? AND sync_status <> 'syncing'), which now matches zero rows → claimed=False → if not claimed: return before fetch_url_content/ingest_file/any terminal stamp. The URL is never fetched, nothing is ingested, and the row is left 'syncing' permanently; every later sync hits if source["sync_status"] == "syncing": return 409, so the source can never be re-synced. This is exactly the "row 'syncing' with no work behind it" strand the claim/finalize machinery exists to prevent, reintroduced on every URL sync.
Fix: delete the handler's pre-stamp UPDATE ... 'syncing' + commit() (both to_thread lines) and let _background_agent_sync's _claim_sync own the stamp, matching the local_file path.

[OPUS-REVIEWED] 5c72270