Skip to content

fix: make the fts5 install hints skip the excluded pysqlite3 wheel - #34052

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/32574-pysqlite3-hint-spec
Nov 10, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/32574-pysqlite3-hint-spec

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Every command Kiro Crew prints for installing pysqlite3-binary installs only a version setup.cfg allows, so following the advice never installs the wheel whose SQLite can freeze the process.

When this Python's SQLite lacks FTS5, kirocrew doctor prints a Fix: command and memory init raises FTS5_UNAVAILABLE_HINT. All three commands they show install pysqlite3-binary with no version. #32424 made setup.cfg exclude 0.5.4.post2, whose bundled SQLite 3.51.1 can deadlock a thread closing a WAL database against a thread opening it, but 0.5.4.post2 is the newest release on PyPI, so a bare install picks exactly that wheel.

Why it matters

These hints appear exactly when the user's interpreter has no usable pysqlite3, so they are the main manual route into the package. A Linux x86_64 user who follows one gets the build #32424 excludes and is open to the same whole-process freeze.

Not a goal

  • A doctor warning when an existing install already carries the excluded wheel (the issue's optional item).
  • Changing which pysqlite3-binary versions setup.cfg accepts.

What changed (motivation → approach → change)

Where the user sees it Before After
kirocrew doctor, sqlite fts5 row, Fix: <python> -m pip install pysqlite3-binary <python> -m pip install 'pysqlite3-binary>=0.5.4,!=0.5.4.post2'
FTS5_UNAVAILABLE_HINT, both commands pip install pysqlite3-binary pip install 'pysqlite3-binary>=0.5.4,!=0.5.4.post2'

The advice spelled the package by name while the exclusion lives only in setup.cfg, so it went stale the day #32424 landed. PYSQLITE3_REQUIREMENT in src/kiro_crew/_sqlite_compat.py now holds the setup.cfg spec without its platform marker, and both hints render it, quoted so a shell does not read > as a redirect. A test pins the constant to setup.cfg, the same transcribe-and-pin pattern extras.REQUIREMENTS uses, so the next exclusion fails a test instead of drifting. The doctor spec in docs/system-specs/modules/cli.md names the constant.

Backwards compatibility

Compatible: only printed advice changes, and the spec it installs is the range setup.cfg already requires.

Removes nothing: no code path, key or record goes away; two strings gain a version range.

Tests

  • test/test_sqlite_compat.py::test_the_pysqlite3_spec_is_the_one_setup_cfg_declares: the constant equals setup.cfg's pysqlite3-binary requirement, marker removed.
  • test/test_sqlite_compat.py::test_every_fts5_hint_command_installs_the_declared_spec: both FTS5_UNAVAILABLE_HINT commands install the quoted spec.
  • test/test_cli_doctor_install.py::TestDoctorPrintsNoBareInstallCommand::test_the_fts5_fix_installs_the_spec_setup_cfg_declares: the doctor's Fix: line installs the quoted spec.
  • test_the_fts5_fix_names_this_interpreter_and_is_gated keeps checking the gate around the doctor command, anchored on the call's new argument.

Determinism: the four tests above passed 20 of 20 runs at -n0 and 10 of 10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test/test_sqlite_compat_resolver.py and test/test_doctor_tz_data.py; all 74 tests of the two changed files passed in a shuffled order (seed 16321).

Proof: PROVEN test/test_cli_doctor_install.py::TestDoctorPrintsNoBareInstallCommand::test_the_fts5_fix_names_this_interpreter_and_is_gated (head 1c4408c)

Manual verification

Rendered both surfaces on this head with FTS5 forced missing: the doctor row prints Fix: <python> -m pip install 'pysqlite3-binary>=0.5.4,!=0.5.4.post2', and the hint prints the same quoted spec in both commands. pip install --dry-run resolves the bare pysqlite3-binary to 0.5.4.post2 and the new spec to 0.5.4.

Screenshots / video

N/A — the diff touches no frontend path; the changed text prints in a terminal and in an exception message.

Related Issues

Closes #32574

Sibling sweep

Swept: git grep -n "pysqlite3" -- src scripts website docs setup.cfg ':!*.lock'
Swept: git grep -n "pip_install_command_for(" -- src
Sibling: src/kiro_crew/doctor_checks/install.py:757 -- not affected -- the tzdata Fix line names a package whose setup.cfg spec is only a floor, which the newest release always meets
Sibling: src/kiro_crew/doctor_checks/features.py:162 -- not affected -- faiss-cpu is not declared in setup.cfg at all

Pattern harvest

Rule candidate: review-prompt
Pattern: a printed install command names a package that setup.cfg declares with an exclusion or upper bound, but not the declared spec

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

The doctor's FTS5 Fix line and FTS5_UNAVAILABLE_HINT told the user to
install pysqlite3-binary with no version. setup.cfg excludes
0.5.4.post2, whose bundled SQLite can deadlock a WAL close against an
open, and it is the newest release, so a bare install picked it.

Both hints now render _sqlite_compat.PYSQLITE3_REQUIREMENT, the
setup.cfg spec without its marker, and a test pins the constant to
setup.cfg so the next exclusion cannot drift.

Closes #32574
@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 9, 2026 18:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 9, 2026
@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 1c4408c7e94b0c0330af11b1c81f6a274db4ea16 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing to check. The change only edits the version range in CLI install-hint text (kirocrew doctor Fix: line and FTS5_UNAVAILABLE_HINT). It adds or changes no dashboard control, so no screenshot or recording is needed.

[UX-REVIEWED] 1c4408c

Description read

[DESCRIPTION-READ] aa3bf06420cff1c5e29d8e3101af4f5f062771ffd39f0ebda9f67356162eb885

That sha256 names everything this verdict read: the PR description, plus the 22 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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 1c4408c7e94b0c0330af11b1c81f6a274db4ea16 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

The fix is proportionate: one constant matches setup.cfg, a test pins it there, and both hints print it. No design-level concerns.

[DESIGN-REVIEWED] 1c4408c

Description read

[DESCRIPTION-READ] 790f742476079ae3ef59fd98b4953feeae5ecb961d3d1d9fe51c97bb7b635abd

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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 1c4408c7e94b0c0330af11b1c81f6a274db4ea16 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. Both hints now install the range setup.cfg declares, and no third bare pysqlite3-binary install command remains in src, docs, website or scripts.

What this change ships

Inventory (5 items) — 4 justified

Intent: someone following Kiro Crew's FTS5 install advice should never install the excluded pysqlite3-binary 0.5.4.post2 wheel, the one that can freeze the process. FIX.

  1. The kirocrew doctor sqlite fts5 Fix: line installs 'pysqlite3-binary>=0.5.4,!=0.5.4.post2' — justified
  2. Both commands in FTS5_UNAVAILABLE_HINT install the same quoted spec — justified
  3. New exported constant _sqlite_compat.PYSQLITE3_REQUIREMENT, pinned to setup.cfg by a test — justified
  4. The hint message now spells "KiroCrew" as "Kiro Crew" — undeclared, rides along
  5. The doctor step in cli.md names the constant — justified

[FIRST-PRINCIPLES-REVIEWED] 1c4408c

Description read

[DESCRIPTION-READ] c33efb825013170996c0f1e7a7fe14bcd8d842203f151829eb61243e6d6d67c8

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 Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 1c4408c

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1c4408c7e94b0c0330af11b1c81f6a274db4ea16 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1c4408c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1c4408c7e94b0c0330af11b1c81f6a274db4ea16 false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 enabled auto-merge (squash) November 9, 2026 18:48
@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 Nov 9, 2026

@buluoray buluoray 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.

Approved at 1c4408c. The doctor Fix line and both FTS5_UNAVAILABLE_HINT commands now install setup.cfg's quoted spec pysqlite3-binary>=0.5.4,!=0.5.4.post2 instead of the bare name, which resolves to the excluded 0.5.4.post2 wheel (src/kiro_crew/_sqlite_compat.py:235, :238; src/kiro_crew/doctor_checks/install.py:694). test/test_sqlite_compat.py:32 pins the constant to setup.cfg, and every mutation turns a test red. GPT, Opus, UX and Security Scope pass; Analyze (python) is a rate limit.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 10, 2026
@bolichen97 bolichen97 closed this Nov 10, 2026
auto-merge was automatically disabled November 10, 2026 08:33

Pull request was closed

@bolichen97 bolichen97 reopened this Nov 10, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 10, 2026
@KiroCrewCaptain
KiroCrewCaptain merged commit 67650d8 into main Nov 10, 2026
196 of 198 checks passed

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

This review checked head 1c4408c and found nothing blocking. PYSQLITE3_REQUIREMENT matches the install_requires spec in setup.cfg, and all three printed install commands use it: both lines of FTS5_UNAVAILABLE_HINT (quoted with shlex.quote) and the doctor Fix: line (quoted per platform by pip_install_command_for). No other place in src, website, docs or scripts prints a bare pysqlite3 install command. The review ran the tests at head with mutations: reverting either production hunk, or dropping !=0.5.4.post2 from the constant, turns at least one test red. The edited source-scan test still requires exactly one gated render.

Done well: one constant now holds the spec, and a test pins it to setup.cfg, so the next exclusion fails a test and the hints cannot drift out of date again.

Optional:

  • FTS5_UNAVAILABLE_HINT now spells the brand two ways. Line 242 still says "KiroCrew memory and knowledge search require it", and the edited line 243 says "Kiro Crew depends on it here". You could change line 242 to "Kiro Crew" too, or leave it.
  • #14007 rewrites the same hint lines in a different direction, so whichever PR merges second will need a rebase.

@KiroCrewCaptain
KiroCrewCaptain deleted the fix/32574-pysqlite3-hint-spec branch November 10, 2026 18:51
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 10, 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.

The FTS5 fix hint and kirocrew doctor still suggest the pysqlite3-binary wheel that #32424 excludes

3 participants