Files
headroom/tests/test_cli/test_wrap_serena_boost.py
df8ebdf97d fix(wrap): stop blocking the launch on the Serena pre-index (#3557)
## Description

`headroom wrap` ran `serena project index` synchronously, so the agent
did not start until the index finished or hit the stall budget (300s by
default, configurable since #3183). As reported in #3436, that is a wait
the user always pays and often gets nothing for: in a directory holding
several repositories the index cannot finish inside any sensible budget,
so every launch waited the whole budget out and then threw the partial
work away. Even a small, already-warm project paid about 15s per launch
for a cache Serena fills lazily anyway.

This moves the index off the launch path. It is now spawned and left to
run alongside the agent, so the launch is immediate and the cache still
warms. Serena's MCP server answers symbol queries from whatever is
already cached and indexes the rest on demand, so nothing is lost by not
waiting.

Closes #3436

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [x] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `_index_serena_project` now spawns `serena project index` and returns
immediately instead of calling `communicate(timeout=...)`. It prints one
line saying the index is warming in the background.
- The child's `stdout`/`stderr` are now `DEVNULL` rather than pipes.
This is load-bearing, not tidying: nothing drains those pipes once the
wrap stops waiting, and the indexer writes a progress line per file, so
a full 64 KiB pipe buffer would block the child permanently. Serena
already records its own failures in `.serena/logs/indexing.txt`.
- New `_stop_background_serena_index`, registered with `atexit`, stops
the child when the wrap exits so a long index does not outlive the
session that started it. It reuses the existing
`_kill_serena_index_tree`, which already handles the `uvx` → `serena`
grandchild on both platforms (#2938).
- `HEADROOM_SERENA_INDEX_TIMEOUT` keeps its name and its meaning — how
long the launch may wait — with a new default of 0. A positive integer
opts back into the previous blocking behaviour with that budget; an
unusable value warns and falls back to the background, as it did before.
`_resolve_serena_index_timeout_seconds` is renamed
`_resolve_serena_index_wait_seconds` and the `_SERENA_INDEX_TIMEOUT =
300` constant is gone, since nothing defaults to it any more.
- Tests in `tests/test_cli/test_wrap_serena_boost.py` are updated for
the new default and extended: the launch never waits, output is
redirected rather than piped, the exit hook kills a running index and
leaves a finished one alone, and the blocking path still works when the
env var asks for it.

### Two things a reviewer may want to check

**Killing a half-finished index is cheap.** Upstream
`ProjectCommands._index_project` calls `ls_mgr.save_all_caches()` every
30 seconds during the loop, and `request_document_symbols` skips files
whose content hash it has already cached. So a killed index loses at
most the last 30 seconds of work, and the next wrap resumes roughly
where this one stopped rather than starting over. A hard kill of the
wrap process itself (SIGKILL, an ungraceful terminal close) skips
`atexit` and does leave the indexer running — that is the one gap.

**The indexer and Serena's MCP server now write `.serena/cache/**`
concurrently**, where previously the pre-index always finished first.
Upstream `solidlsp.util.cache.save_cache` writes the pickle in place
with no atomic rename, so a torn write is possible. Serena tolerates
this by design: `_load_document_symbols_cache` wraps the load in
`try/except` with the comment *"cache can become corrupt, so just skip
loading it"*, and `_save_document_symbols_cache` catches and logs rather
than raising. The worst case is a cache rebuild, not a failure.

Issue #3436 offered a second option — skip the pre-index whenever a
`.serena/cache` directory already exists. I did not take it: it leaves
the first and most expensive launch blocking, and a cache that exists
but is stale or partial would then never be refreshed. Backgrounding
removes the wait in both cases.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -m pytest tests/test_cli/test_wrap_serena_boost.py -q -p no:randomly
======================== 49 passed, 1 skipped in 0.55s ========================

$ python -m pytest tests/test_cli/ -q -p no:randomly --ignore=tests/test_cli/test_mcp.py
============ 5 failed, 723 passed, 2 skipped, 2 warnings in 39.52s ============
# The 5 failures and the test_mcp.py collection error reproduce identically on
# an unmodified upstream/main checkout on this machine: Windows has no
# signal.SIGHUP, the symlink tests need privileges, and the local pydantic-core
# is newer than pydantic expects. None involve the changed code.

$ python -m ruff check . && python -m ruff format --check .
All checks passed!
1577 files already formatted

$ python -m mypy headroom --ignore-missing-imports --python-version 3.13
Found 12 errors in 3 files (checked 532 source files)
# All 12 pre-exist in headroom/ccr/mcp_server.py, headroom/memory/mcp_server.py
# and headroom/release_version.py (local MCP SDK version drift). Zero in
# headroom/cli/wrap.py. Local mypy here is 2.3.1, not CI's 1.20.2.
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.13.11, uvx 0.11.28, serena-agent
from PyPI, real `serena project index` child processes (no mocks). A
scratch project holding 533 real `.py` files with a
`.serena/project.yml` and a cold cache.
- Exact command / steps: imported the patched `headroom.cli.wrap` from
this branch, `chdir` into the scratch project, then (1) called
`_index_serena_project(verbose=True)` and timed the return, checked the
child with `tasklist`, slept, and inspected `.serena/cache`; (2)
repeated it and called `_stop_background_serena_index()` while the child
was still running; (3) repeated with `HEADROOM_SERENA_INDEX_TIMEOUT=5`
and with `HEADROOM_SERENA_INDEX_TIMEOUT=60s`.
- Observed result: (1) `_index_serena_project() returned in 0.01s`,
printing `Serena: indexing project in the background (symbol tools work
meanwhile)`; the child kept running afterwards and produced
`document_symbols.pkl` (31,492,659 bytes) and `raw_document_symbols.pkl`
(6,048,168 bytes) on its own. (2) `2s later: child pid 29672 alive=True
(poll=None)` then `after the exit hook: child pid 29672 alive=False
(poll=1)`, handle cleared; the cache was empty at that point, which
matches Serena's 30-second flush cadence — a kill inside the first
window loses that window. (3) with `=5` the call blocked and printed
`Serena: pre-indexing project (waiting up to 5s)…` then `Serena: project
pre-indexed (symbol cache warmed)`, returning in 2.46s with nothing left
for the exit hook; with `=60s` it printed `Serena: ignoring
HEADROOM_SERENA_INDEX_TIMEOUT='60s' (want a positive integer number of
seconds) — indexing in the background instead` and returned in 0.01s.
- Not tested: a full `headroom wrap claude` end-to-end launch (the proof
exercises the changed function directly against real Serena rather than
starting an agent); POSIX behaviour — `start_new_session` and the
`os.killpg` branch of `_kill_serena_index_tree` are covered only by unit
tests on this Windows machine; the reporter's own multi-repository Go
tree; and the concurrent cache-write case is reasoned from upstream
Serena source, not reproduced.

## Runtime Rollout Safety

- Rollout-managed feature(s): none — this is not behind a rollout
channel. It is the Serena pre-index step of `headroom wrap`, which runs
whenever `--code-memory serena` (the default) is active and the project
already has `.serena/project.yml`.
- Minimum rollout channel: n/a (stable; ships with the next release).
- Stable/default behavior changed: yes. The default pre-index goes from
blocking the launch for up to 300s to running in the background. No
config or flag changes name or meaning; `HEADROOM_SERENA_INDEX_TIMEOUT`
changes only its default.
- Kill switch / disable path: set `HEADROOM_SERENA_INDEX_TIMEOUT` to a
positive integer to restore the previous blocking pre-index with that
budget (`HEADROOM_SERENA_INDEX_TIMEOUT=300` reproduces today's default
exactly). `--code-memory none` still disables Serena entirely.
- Unsafe override required: no.
- Qualification impact: none beyond the updated unit tests. The
pre-index has always been best-effort and non-fatal, and it still is;
nothing downstream reads its result.
- Rollback path: revert this commit. It touches one function, one new
helper and one env-var resolver in `headroom/cli/wrap.py`, with no
persisted state, no config migration and no on-disk format change — a
revert restores the old behaviour immediately.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

"I have made corresponding changes to the documentation" means the
in-file documentation: `HEADROOM_SERENA_INDEX_TIMEOUT` is documented
only in `headroom/cli/wrap.py` and its test module, both updated here,
so there is no user-facing doc page to change. No screenshots — this is
CLI timing behaviour.

@wallrj offered to test a PR in #3436; this is ready for that if you
would like to try it against the cert-manager tree.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-09-24 11:32:55 -05:00

678 lines
24 KiB
Python

"""Serena "boost" wrap-time helpers: prefer-Serena instruction injection,
repo-language scoping of ``.serena/project.yml``, and background symbol-cache
pre-indexing.
All Serena subprocess calls are mocked — these tests never invoke real ``uvx``.
"""
from __future__ import annotations
import subprocess
from collections.abc import Iterator
from pathlib import Path
from unittest.mock import Mock
import pytest
from headroom.cli import wrap as wrap_cli
# ---------------------------------------------------------------------------
# _inject_serena_instructions
# ---------------------------------------------------------------------------
def _opt_in(monkeypatch: pytest.MonkeyPatch) -> None:
"""Enable the opt-in gate so injection actually writes.
Instruction injection rewrites the user's CLAUDE.md/AGENTS.md, so it is
off by default. Tests that exercise the write path must opt in via
``HEADROOM_SERENA_INSTRUCTIONS``.
"""
monkeypatch.setenv("HEADROOM_SERENA_INSTRUCTIONS", "1")
def test_inject_creates_file_and_mentions_tools(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
_opt_in(monkeypatch)
target = tmp_path / "AGENTS.md"
assert wrap_cli._inject_serena_instructions(target) is True
content = target.read_text()
assert wrap_cli._SERENA_MARKER in content
# The whole point is steering the agent toward Serena's symbol tools.
for tool in ("get_symbols_overview", "find_symbol", "find_referencing_symbols"):
assert tool in content, f"{tool} missing from injected guidance"
def test_inject_is_idempotent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
_opt_in(monkeypatch)
target = tmp_path / "AGENTS.md"
wrap_cli._inject_serena_instructions(target)
wrap_cli._inject_serena_instructions(target) # second call is a no-op
content = target.read_text()
assert content.count(wrap_cli._SERENA_MARKER) == 1
def test_inject_appends_to_existing_file(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
_opt_in(monkeypatch)
target = tmp_path / "CLAUDE.md"
target.write_text("# Project notes\n\nkeep me\n")
wrap_cli._inject_serena_instructions(target)
content = target.read_text()
assert "keep me" in content # existing content preserved
assert wrap_cli._SERENA_MARKER in content
def test_inject_off_by_default_writes_nothing(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
# Without opting in, injection is a no-op: returns False and never touches
# the user's hint file (the default, so the two OpenCode AGENTS.md tests pass).
monkeypatch.delenv("HEADROOM_SERENA_INSTRUCTIONS", raising=False)
missing = tmp_path / "AGENTS.md"
assert wrap_cli._inject_serena_instructions(missing) is False
assert not missing.exists() # nothing created
existing = tmp_path / "CLAUDE.md"
existing.write_text("# Project notes\n\nkeep me\n")
assert wrap_cli._inject_serena_instructions(existing) is False
assert existing.read_text() == "# Project notes\n\nkeep me\n" # untouched
assert wrap_cli._SERENA_MARKER not in existing.read_text()
def test_instruction_file_target_per_agent(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.chdir(tmp_path)
class _Reg:
def __init__(self, name: str) -> None:
self.name = name
assert wrap_cli._serena_instruction_file(_Reg("claude")).name == "CLAUDE.md"
assert wrap_cli._serena_instruction_file(_Reg("codex")).name == "AGENTS.md"
assert wrap_cli._serena_instruction_file(_Reg("grok")).name == "AGENTS.md"
# ---------------------------------------------------------------------------
# _index_serena_project — spawned in the background, never on the launch path
# ---------------------------------------------------------------------------
def _stub_uvx(monkeypatch: pytest.MonkeyPatch, present: bool = True) -> None:
monkeypatch.setattr(
wrap_cli.shutil,
"which",
lambda name, *a, **k: "/usr/bin/uvx" if (present and name == "uvx") else None,
)
class _FakeProc:
"""Minimal stand-in for the ``serena project index`` child process."""
def __init__(
self,
*,
returncode: int = 0,
poll_result: int | None = None,
wait_error: BaseException | None = None,
) -> None:
self.pid = 4242
self.returncode = returncode
self.stdin = None
self.stdout = None
self.stderr = None
self._poll_result = poll_result
self._wait_error = wait_error
self.waits: list[float | None] = []
self.killed = False
self.waited = False
def poll(self) -> int | None:
return self._poll_result
def wait(self, timeout: float | None = None) -> int:
self.waits.append(timeout)
self.waited = True
if self._wait_error is not None:
raise self._wait_error
return self.returncode
def kill(self) -> None:
self.killed = True
def _stub_popen(monkeypatch: pytest.MonkeyPatch, proc: _FakeProc) -> Mock:
mock_popen = Mock(return_value=proc)
monkeypatch.setattr(wrap_cli.subprocess, "Popen", mock_popen)
return mock_popen
@pytest.fixture(autouse=True)
def _no_leaked_index_child() -> Iterator[None]:
"""Never let a fake child stay parked in the module global.
``_index_serena_project`` stashes the background child so the atexit hook
can stop it. Leaving a mock there would make an unrelated test's hook act
on it — and would fire at interpreter shutdown.
"""
yield
wrap_cli._SERENA_INDEX_PROC = None
def _stub_atexit(monkeypatch: pytest.MonkeyPatch) -> list[object]:
"""Collect atexit registrations instead of really queueing them."""
registered: list[object] = []
monkeypatch.setattr(wrap_cli.atexit, "register", registered.append)
return registered
def test_preindex_runs_serena_in_cwd(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
mock_popen = _stub_popen(monkeypatch, _FakeProc())
wrap_cli._index_serena_project()
mock_popen.assert_called_once()
args, kwargs = mock_popen.call_args
cmd = args[0]
assert cmd[0] == "uvx"
assert cmd[-3:] == ["serena", "project", "index"]
# PyPI package with prebuilt wheels, not the git source (#2871).
assert "serena-agent" in cmd
assert "git+https://github.com/oraios/serena" not in cmd
assert kwargs["cwd"] == str(tmp_path) # invoked in the project cwd
def test_preindex_does_not_block_the_launch(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""The whole point of #3436: spawn, say so, and let the agent start."""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
registered = _stub_atexit(monkeypatch)
proc = _FakeProc()
_stub_popen(monkeypatch, proc)
wrap_cli._index_serena_project()
assert proc.waits == [] # never waited on
assert wrap_cli._SERENA_INDEX_PROC is proc # kept, so exit can stop it
assert registered == [wrap_cli._stop_background_serena_index]
assert "background" in capsys.readouterr().out
def test_preindex_discards_child_output(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""Pipes would wedge the child: nothing drains them once we stop waiting.
``serena project index`` writes a progress line per file, so a full pipe
buffer would block it forever instead of letting the cache warm.
"""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
mock_popen = _stub_popen(monkeypatch, _FakeProc())
wrap_cli._index_serena_project()
kwargs = mock_popen.call_args.kwargs
assert kwargs["stdout"] == subprocess.DEVNULL
assert kwargs["stderr"] == subprocess.DEVNULL
def test_preindex_never_inherits_stdin(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""Serena prompts ``[y/N]`` behind redirected output; stdin must be EOF (#2938)."""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
mock_popen = _stub_popen(monkeypatch, _FakeProc())
wrap_cli._index_serena_project()
assert mock_popen.call_args.kwargs["stdin"] == subprocess.DEVNULL
def test_preindex_child_gets_its_own_process_group(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Keeps Ctrl-C off the indexer, and lets the exit hook take out the ``uvx``
grandchild rather than orphaning it (#2938)."""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
mock_popen = _stub_popen(monkeypatch, _FakeProc())
wrap_cli._index_serena_project()
kwargs = mock_popen.call_args.kwargs
if wrap_cli.sys.platform == "win32":
assert kwargs["creationflags"] & subprocess.CREATE_NEW_PROCESS_GROUP
else:
assert kwargs["start_new_session"] is True
def test_preindex_skips_without_uvx(monkeypatch: pytest.MonkeyPatch) -> None:
_stub_uvx(monkeypatch, present=False)
mock_popen = Mock(side_effect=AssertionError("Popen must not be called without uvx"))
monkeypatch.setattr(wrap_cli.subprocess, "Popen", mock_popen)
wrap_cli._index_serena_project() # no exception
mock_popen.assert_not_called()
def test_preindex_spawn_failure_is_non_fatal(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
registered = _stub_atexit(monkeypatch)
monkeypatch.setattr(wrap_cli.subprocess, "Popen", Mock(side_effect=OSError("no exec")))
wrap_cli._index_serena_project(verbose=True) # must not propagate
assert registered == [] # nothing to stop later
assert wrap_cli._SERENA_INDEX_PROC is None
# ---------------------------------------------------------------------------
# _stop_background_serena_index — the indexer does not outlive the session
# ---------------------------------------------------------------------------
def test_exit_stops_a_still_running_index(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""Otherwise a 13-minute index grinds on with nobody left to want it."""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc(poll_result=None) # still running
_stub_popen(monkeypatch, proc)
killed: list[object] = []
monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
wrap_cli._index_serena_project()
wrap_cli._stop_background_serena_index()
assert killed == [proc]
def test_exit_leaves_a_finished_index_alone(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
_stub_popen(monkeypatch, _FakeProc(poll_result=0)) # already exited
killed: list[object] = []
monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
wrap_cli._index_serena_project()
wrap_cli._stop_background_serena_index()
assert killed == []
def test_exit_hook_kills_once_and_is_safe_to_repeat(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""``atexit`` can hold several registrations from one process."""
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc(poll_result=None)
_stub_popen(monkeypatch, proc)
killed: list[object] = []
monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
wrap_cli._index_serena_project()
wrap_cli._stop_background_serena_index()
wrap_cli._stop_background_serena_index()
assert killed == [proc]
def test_exit_hook_without_a_child_is_a_noop(monkeypatch: pytest.MonkeyPatch) -> None:
"""The hook also runs for wraps that never reached the pre-index."""
monkeypatch.setattr(
wrap_cli,
"_kill_serena_index_tree",
Mock(side_effect=AssertionError("nothing to kill")),
)
wrap_cli._stop_background_serena_index() # no exception
def test_exit_hook_survives_an_unpollable_child(monkeypatch: pytest.MonkeyPatch) -> None:
"""Shutdown is no place to raise: a broken handle just means no kill."""
proc = Mock()
proc.poll.side_effect = OSError("handle gone")
wrap_cli._SERENA_INDEX_PROC = proc
monkeypatch.setattr(
wrap_cli,
"_kill_serena_index_tree",
Mock(side_effect=AssertionError("must not kill an unpollable child")),
)
wrap_cli._stop_background_serena_index() # no exception
# ---------------------------------------------------------------------------
# HEADROOM_SERENA_INDEX_TIMEOUT — opting back into a blocking pre-index (#3436)
# ---------------------------------------------------------------------------
def _clear_index_timeout(monkeypatch: pytest.MonkeyPatch) -> None:
"""Resolve from a known-empty environment, not the developer's shell."""
monkeypatch.delenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, raising=False)
def test_index_wait_defaults_to_not_waiting(monkeypatch: pytest.MonkeyPatch) -> None:
"""Unset means background, which is what #3436 asked for."""
_clear_index_timeout(monkeypatch)
assert wrap_cli._resolve_serena_index_wait_seconds() == 0
def test_index_wait_reads_the_env(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "45")
assert wrap_cli._resolve_serena_index_wait_seconds() == 45
@pytest.mark.parametrize("raw", [" 30 ", "\t30\n"])
def test_index_wait_tolerates_surrounding_whitespace(
raw: str, monkeypatch: pytest.MonkeyPatch
) -> None:
"""An env var exported from a shell heredoc keeps its padding."""
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, raw)
assert wrap_cli._resolve_serena_index_wait_seconds() == 30
@pytest.mark.parametrize("raw", ["", " "])
def test_index_wait_treats_a_blank_value_as_unset(
raw: str, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""``export HEADROOM_SERENA_INDEX_TIMEOUT=`` is not a misconfiguration."""
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, raw)
assert wrap_cli._resolve_serena_index_wait_seconds() == 0
assert capsys.readouterr().out == "" # no warning noise on the default path
def test_index_wait_accepts_the_smallest_useful_budget(
monkeypatch: pytest.MonkeyPatch,
) -> None:
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "1")
assert wrap_cli._resolve_serena_index_wait_seconds() == 1
def test_index_wait_accepts_a_long_budget(monkeypatch: pytest.MonkeyPatch) -> None:
"""A deliberately huge monorepo may want to block for a long time."""
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "86400")
assert wrap_cli._resolve_serena_index_wait_seconds() == 86400
@pytest.mark.parametrize("raw", ["0", "-1", "abc", "30s", "1.5", "1e3", "0x10", "None"])
def test_index_wait_falls_back_to_the_background_on_an_unusable_value(
raw: str, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""Best-effort means degrade to the default, never abort the launch."""
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, raw)
assert wrap_cli._resolve_serena_index_wait_seconds() == 0
# A silently-ignored knob is the bug #3093 was about, so say so — and quote
# the value back, since the usual cause is a unit suffix the parser rejects.
out = capsys.readouterr().out
assert wrap_cli._SERENA_INDEX_TIMEOUT_ENV in out
assert repr(raw) in out
def test_index_wait_survives_a_float_unrepresentable_budget(
monkeypatch: pytest.MonkeyPatch,
) -> None:
"""``int()`` accepts integers ``float()`` cannot hold; resolving must not raise.
``wait`` would go on to raise ``OverflowError`` adding that to a monotonic
clock, which the caller's generic handler already absorbs as a non-fatal
skip — so the budget is honoured as given rather than clamped.
"""
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "1" + "0" * 400)
assert wrap_cli._resolve_serena_index_wait_seconds() == 10**400
def test_preindex_blocks_for_the_env_budget(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Setting the knob restores the pre-#3436 blocking wait."""
monkeypatch.chdir(tmp_path)
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "5")
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc()
_stub_popen(monkeypatch, proc)
wrap_cli._index_serena_project()
assert proc.waits == [5]
assert wrap_cli._SERENA_INDEX_PROC is None # waited for, nothing to stop later
def test_preindex_timeout_kills_the_tree_and_is_non_fatal(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.chdir(tmp_path)
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "5")
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc(wait_error=subprocess.TimeoutExpired(cmd="serena", timeout=5))
_stub_popen(monkeypatch, proc)
killed: list[object] = []
monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
wrap_cli._index_serena_project(verbose=True) # must not propagate
assert killed == [proc]
def test_preindex_generic_error_kills_the_tree_and_is_non_fatal(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.chdir(tmp_path)
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "5")
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc(wait_error=RuntimeError("boom"))
_stub_popen(monkeypatch, proc)
killed: list[object] = []
monkeypatch.setattr(wrap_cli, "_kill_serena_index_tree", killed.append)
wrap_cli._index_serena_project(verbose=True) # must not propagate
assert killed == [proc]
def test_preindex_backgrounds_on_an_unusable_budget(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""A bad value must not skip the pre-index or start blocking on it."""
monkeypatch.chdir(tmp_path)
monkeypatch.setenv(wrap_cli._SERENA_INDEX_TIMEOUT_ENV, "not-a-number")
_stub_uvx(monkeypatch)
_stub_atexit(monkeypatch)
proc = _FakeProc()
mock_popen = _stub_popen(monkeypatch, proc)
wrap_cli._index_serena_project() # must not propagate
mock_popen.assert_called_once()
assert proc.waits == []
# ---------------------------------------------------------------------------
# _kill_serena_index_tree — no orphaned `serena project index` on timeout
# ---------------------------------------------------------------------------
def test_kill_tree_signals_the_group_on_posix(monkeypatch: pytest.MonkeyPatch) -> None:
if wrap_cli.sys.platform == "win32":
pytest.skip("POSIX process groups")
proc = _FakeProc()
signalled: list[tuple[int, int]] = []
monkeypatch.setattr(wrap_cli.os, "getpgid", lambda pid: pid)
monkeypatch.setattr(wrap_cli.os, "killpg", lambda pgid, sig: signalled.append((pgid, sig)))
wrap_cli._kill_serena_index_tree(proc) # type: ignore[arg-type]
assert signalled == [(proc.pid, wrap_cli.signal.SIGKILL)]
assert proc.killed and proc.waited # backstop still runs
def test_kill_tree_walks_the_tree_on_windows(monkeypatch: pytest.MonkeyPatch) -> None:
if wrap_cli.sys.platform != "win32":
pytest.skip("Windows taskkill")
proc = _FakeProc()
calls: list[list[str]] = []
monkeypatch.setattr(
wrap_cli.subprocess,
"run",
lambda cmd, **kw: calls.append(cmd),
)
wrap_cli._kill_serena_index_tree(proc) # type: ignore[arg-type]
assert calls == [["taskkill", "/F", "/T", "/PID", str(proc.pid)]]
assert proc.killed and proc.waited
def test_kill_tree_survives_a_dead_child(monkeypatch: pytest.MonkeyPatch) -> None:
"""Cleanup is best-effort: a child that already exited must not raise."""
proc = _FakeProc()
monkeypatch.setattr(proc, "kill", Mock(side_effect=ProcessLookupError()))
if wrap_cli.sys.platform == "win32":
monkeypatch.setattr(wrap_cli.subprocess, "run", Mock(side_effect=OSError("gone")))
else:
monkeypatch.setattr(wrap_cli.os, "getpgid", Mock(side_effect=ProcessLookupError()))
wrap_cli._kill_serena_index_tree(proc) # type: ignore[arg-type]
# ---------------------------------------------------------------------------
# _serena_project_skip_reason — keep per-project setup off non-project roots
# ---------------------------------------------------------------------------
_NO_PROJECT_YML = "no .serena/project.yml yet — Serena will create it and index on demand"
def _with_project_yml(root: Path) -> Path:
"""Give *root* the ``.serena/project.yml`` Serena writes on first MCP start."""
(root / ".serena").mkdir(parents=True, exist_ok=True)
(root / ".serena" / "project.yml").write_text("project_name: demo\n")
return root
def test_skip_reason_none_for_ordinary_project(tmp_path: Path) -> None:
_with_project_yml(tmp_path)
assert wrap_cli._serena_project_skip_reason(tmp_path) is None
def test_skip_reason_none_for_normal_checkout(tmp_path: Path) -> None:
(tmp_path / ".git").mkdir() # real checkout: .git is a directory
_with_project_yml(tmp_path)
assert wrap_cli._serena_project_skip_reason(tmp_path) is None
def test_skip_reason_flags_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setattr(Path, "home", classmethod(lambda cls: tmp_path))
_with_project_yml(tmp_path)
assert wrap_cli._serena_project_skip_reason(tmp_path) == "$HOME is not a project"
def test_skip_reason_flags_linked_worktree(tmp_path: Path) -> None:
(tmp_path / ".git").write_text("gitdir: /repo/.git/worktrees/wt\n")
_with_project_yml(tmp_path)
assert wrap_cli._serena_project_skip_reason(tmp_path) == "linked git worktree"
def test_skip_reason_flags_missing_project_yml(tmp_path: Path) -> None:
"""The pre-index cannot succeed here — Serena would stop on a hidden prompt (#2938)."""
assert wrap_cli._serena_project_skip_reason(tmp_path) == _NO_PROJECT_YML
def test_skip_reason_flags_serena_dir_without_project_yml(tmp_path: Path) -> None:
(tmp_path / ".serena").mkdir() # cache dir exists, config does not
assert wrap_cli._serena_project_skip_reason(tmp_path) == _NO_PROJECT_YML
def test_skip_reason_survives_unresolvable_root(tmp_path: Path) -> None:
# Missing directory: resolves fine (non-strict), no config, no exception.
assert wrap_cli._serena_project_skip_reason(tmp_path / "gone") == _NO_PROJECT_YML
# ---------------------------------------------------------------------------
# _setup_serena_mcp wiring — the launch path must not wait on a doomed index
# ---------------------------------------------------------------------------
class _FakeRegistrar:
"""Just enough registrar for the post-registration branch of the setup."""
name = "claude"
display_name = "Claude"
def detect(self) -> bool:
return True
def get_server(self, server_name: str) -> None:
return None
def register_server(self, spec: object, *, force: bool = False) -> object:
from headroom.mcp_registry.base import RegisterResult, RegisterStatus
return RegisterResult(RegisterStatus.REGISTERED, "registered")
def _drive_setup(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> list[str]:
"""Run ``_setup_serena_mcp`` in *tmp_path*, returning pre-index call markers."""
monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(tmp_path / ".headroom"))
monkeypatch.chdir(tmp_path)
_stub_uvx(monkeypatch)
monkeypatch.setattr(wrap_cli, "_inject_serena_instructions", lambda *a, **k: True)
calls: list[str] = []
monkeypatch.setattr(wrap_cli, "_index_serena_project", lambda **k: calls.append("indexed"))
wrap_cli._setup_serena_mcp(_FakeRegistrar(), context="claude-code", verbose=True)
return calls
def test_setup_does_not_preindex_a_project_without_serena_config(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
"""First wrap of a fresh project: launch immediately, do not wait out the timeout."""
calls = _drive_setup(tmp_path, monkeypatch)
assert calls == []
assert "skipping pre-index" in capsys.readouterr().out
def test_setup_preindexes_once_serena_config_exists(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
"""Second wrap: Serena's MCP server has written project.yml, so the index can run."""
_with_project_yml(tmp_path)
assert _drive_setup(tmp_path, monkeypatch) == ["indexed"]