test(lsp): explicit push/pull ordering controls on the fake LSP server (refs #2824)

[apmantza]

Summary

Refs #2824. This fixture-only PR adds deterministic JSON-RPC controls for the
later LSP fix PR: push-before-response, push-after-response, explicit push
versions, four pull outcomes, and a completion notification. The completion
notification is awaited through the governed wait seam from the interleaving
kit. It does not change production LSP behavior or the deferred-timeout
telemetry test.

The fixture-first acceptance criteria are complete. This PR unblocks the
separate production fix PR and does not close #2824.

Type of change

• Bug fix
• New feature (net-new capability)
• Enhancement (improvement to existing capability)
• Documentation

Area

• area:lsp
• area:tests

Checklist

• I have read CONTRIBUTING.md, AGENTS.md, and the fixer contract.
• The change has tests for ordering, version, pull outcomes, and completion.
• The build ran before the test suites.
• Every new control is mutation-proof; red transcripts are below.
• The title carries the conventional prefix and issue reference.
• The single changelog fragment uses valid front matter.
• The commit subject references LSP pull/push wait hardening: both-channel servers stop pulling after a push; early pullOnly snapshot caches confirmed-empty before a late push; skipped pull ≠ unavailable (from #2781/#2819, refs #2776) #2824 without a close keyword.

Tests

The real fixture contract file tests/support/fake-lsp-server.test.ts covers:

• pushBeforePullResponse emits the push before the pull response
• pushAfterPullResponse emits the pull response before the push
• pushWithVersion carries the configured document version
• respondPullWith outcomes return the requested pull result
• the completion signal arrives only after the controlled operation is observable

The tests spawn the real fixture process and assert independently parsed
JSON-RPC frames. The existing fake-LSP consumer suite and flake-shape ratchet
also passed.

Mutation evidence, after a fresh build, is recorded in this transcript:

pushBeforePullResponse mutation: 2 failed, 6 passed; the ordering and completion assertions failed.
pushAfterPullResponse mutation: 2 failed, 6 passed; the ordering and version assertions failed.
pushWithVersion mutation: 1 failed, 7 passed; the version assertion failed.
respondPullWith mutation: 3 failed, 5 passed; the error, timeout, and empty outcomes failed their independent predicates.
completion mutation: the governed wait exhausted when the completion signal was removed.

Test assessment

The touched fixture test file uniquely pins real-wire ordering, document
version, pull outcomes, completion signaling, and the existing process-cleanup
backstop. No removal candidate is present. The fixture implementation remains
the shared spawn seam for all consumers.

Blast radius

No production module changed. The fixture controls affect only tests that opt
into their environment variables; default fixture behavior is unchanged.

spawnFakeLspServer -> real fixture process -> framed JSON-RPC assertions

Class sweep

The fixture population was searched for pull handlers, push controls,
completion controls, raw delays, and governed waits across clients, tools, MCP,
scripts, the host adapter, and tests. The sweep found one fixture
implementation and its direct contract test; all other consumers retain
default behavior. The family stays distributed because the fixture owns
wire behavior while client tests own protocol assertions.

Observability

No new failure path; no record added.

Verification

PI_LENS_HOME=$PWD/.probe-home npm run build: pass
fake-LSP consumer suite: 24 files, 337 tests, pass
flake-shape ratchet: 57 tests, pass
npm run fmt:check: pass
npx tsc --noEmit: pass
npm run changelog:check: pass
check-changelog-fragments: pass
actionlint: pass in hosted CI

Fresh hosted exact-head CI is required before merge. The prior Unit failure
was in an unrelated full-suite session-start test; the focused fixture tests
must still be confirmed on the exact head.

[github-actions]

ci-classifier: infra-kill (no failing assertion; [mem-watch] KILLED WITH HEADROOM — no failing assertion, and no sample fell below 4124 MB of 15990 MB, so the box was not short of memory at any sample point (2000ms sampling: a shorter spike, or a pressure-based kill by systemd-oomd, would not show up here). Read the kernel kill evidence step for the signal's sender. exitCode=137 totalMb=15990 lowWaterAvailableMb=4124 lowWaterAt=15:43:39 childPid=2437; heaviest files by peak RSS: tests/config/bounded-container-guard.test.ts (9238 MB), tests/config/vi-mock-export-sweep.test.ts (5642 MB), tests/index-integration.test.ts (1538 MB); kernel evidence: dmesg and cgroup both show no OOM/kill records; auto-rerun triggered)

[github-actions]

A required check is failing on the current head:

• Unit tests failed — https://github.com/apmantza/pi-lens/actions/runs/34709417137/job/103595457021

[apmantza]

Latest Plegma fixer handoff

• Worker: sub-mu0xehx3-4
• Role: fixer
• Exact head worked from: 3139edad85fdf117024263046b42d05b4cead8e3
• Source artifacts: /home/akis/.plegma/work/sub-mu0xehx3-4/PR_BODY.md, /home/akis/.plegma/work/sub-mu0xehx3-4/COMMIT_MSG.txt
• Changes remain uncommitted and unpushed in the isolated worker worktree.

Handoff body

Operating rule: Keep fake-LSP ordering controls deterministic and exercise them through the real fixture wire.

Kept: This round does not change production LSP behavior, session lifecycle code, or CHANGELOG.md.

Summary

Add explicit fake-LSP controls for push ordering, diagnostic version, pull outcomes, and pull completion. The controls support #2824 follow-up tests without changing production LSP code.

Tests

• fake-lsp-server.test.ts: verifies push-before-response ordering, push-after-response ordering, pushed document versions, four pull outcomes, and completion signaling through the real fixture process.
• index-multi-root-session-start.test.ts: existing production session-start path; reproduced cleanly in isolation and in the targeted combined run.

Red-first and mutation evidence: the exact head's isolated session-start test passed, so the reported Unit failure did not reproduce locally. The new fixture-control cases time out before receiving the initialize response in this sandbox. No guard mutation was claimed because this round did not add a production guard.

Blast radius

The change is limited to the fake-LSP fixture and its real-process test coverage. It affects only tests that opt into the new FAKE_LSP_* environment variables. Production LSP clients, dispatchers, session lifecycle state, and telemetry are unchanged.

Class sweep

The fixture population was searched for existing pull handlers and completion controls. The new controls are centralized in the fixture's textDocument/diagnostic handler; no parallel fake-LSP implementation was changed.

Observability

No new production failure path; no record added. The fixture emits the requested wire frames and the tests observe those frames directly.

Test assessment

The edited fixture test adds real child-process coverage rather than a mock. Its waits use tests/clients/interleaving-kit.ts. The session-start file was not edited in this round.

Round 1

• fixed: added the requested explicit fake-LSP push/pull controls at the existing fixture seam.
• not fixed: the local sandbox cannot complete the new direct-wire cases; they time out before an initialize response.
• not fixed: PR metadata and remote CI could not be read because gh has no authentication and network DNS is unavailable.

Verification

• npm run build: passed.
• Targeted Vitest run for index-multi-root-session-start.test.ts: 1 file, 7 tests passed.
• Combined target run: session-start 7 tests passed; fake-LSP ordering 8 tests timed out in the sandbox.
• Grammar prefetch was skipped because the environment is offline.
• npm run preflight: not run because the required fixture cases remain red in this sandbox.

Proposed commit message

test(lsp): add fake ordering controls

Add deterministic fake-LSP push and pull outcomes so #2824 follow-up tests can
exercise wire ordering, document versions, and completion through one fixture.

Refs #2824

[apmantza]

Latest Plegma review handoff

Worker: sub-mu14hblz-18
Role: reviewer
Exact head: 3139eda
Artifact: /home/akis/.plegma/work/sub-mu14hblz-18/REVIEW.md
Verdict: merge after outside-sandbox verification
Next owner: orchestrator: run exact-head fixture tests and CI outside sandbox

Review verdict: merge after verification

Exact head reviewed: 3139edad85fdf117024263046b42d05b4cead8e3.

No proven source correctness finding is present in the three-file diff. The
new direct-wire tests do not pass in this sandbox, so the PR is not mergeable
from this review. Re-run the exact head in a CI-capable environment and require
fresh checks for this SHA before merging.

Findings

CRITICAL

None.

HIGH

None.

MEDIUM

None proven. The eight new cases in tests/support/fake-lsp-server.test.ts
all time out at Vitest's 5,000 ms test limit in this sandbox. The failure is
at startOrderingFixture()/the initial child response wait, before any
ordering assertion. A standalone child-process probe shows the same sandbox
process-I/O symptom: the fixture exits with code 0 without producing the
initialize response. This is consistent with the handoff's sandbox-only
qualification, but it cannot be called green without an outside-sandbox run.

LOW

None.

NITPICK

None.

Acceptance review

The diff adds the claimed controls at module scope in
tests/fixtures/fake-lsp-server.mjs:

• FAKE_LSP_PUSH_BEFORE_PULL_RESPONSE and
  FAKE_LSP_PUSH_AFTER_PULL_RESPONSE order a real
  textDocument/publishDiagnostics frame around the pull response.
• FAKE_LSP_PUSH_VERSION adds the configured integer version.
• FAKE_LSP_RESPOND_PULL_WITH covers -32601, timeout, items, and empty
  outcomes.
• FAKE_LSP_PULL_COMPLETION emits $/test/pullCompleted after those writes.

The tests spawn through spawnFakeLspServer, which calls the production
launchLSP seam, then speak framed JSON-RPC directly to the real fixture
process. Their waits use waitFor with the default wall-clock timer, which is
the correct clock for child-process progress. Each test uses try/finally and
stopLSP; the helper also registers the onTestFinished backstop.

The existing tests/index-multi-root-session-start.test.ts and
tests/clients/session-lifecycle-multi-root.test.ts pass. The PR does not
change the index or session-start path, so no integration claim about that path
is introduced by this diff.

Verification

Check	Result
npm run build	Passed
Focused fake fixture tests	8 new cases timed out; 2 existing backstop cases passed
Focused multi-root/session-start tests	40 tests passed
npm run lint	Passed
npm run fmt:check	Passed
npm run changelog:check	Passed
npm run preflight	Blocked; grammar prefetch produced no progress offline and was interrupted
Compile-valid source mutations	Not run; the review brief forbids source edits and only permits REVIEW.md
Full CI, PR metadata, comments, merge state	Blocked; gh has no token and the API host is unreachable

Blast radius

Production runtime code is untouched. The behavioral surface is the shared
fake-LSP fixture used by real LSP-process tests. The control names are only
read by the fixture process, and the class sweep found no sibling handlers for
these new names outside the fixture and its direct-wire tests. The multi-root
session-start path is unchanged and its focused tests pass.

Class sweep verdict

Cleared: real fixture spawn path, framed wire parsing, ordering controls,
version control, pull outcome controls, completion notification, interleaving
waits, cleanup/backstop registration, changelog fragment, and multi-root
session-start regression coverage.

Not cleared: exact-head CI and an outside-sandbox reproduction of the new
direct-wire cases.

Observability

The new completion notification is a bounded test-only wire event and carries
the selected pull outcome. The fixture has no production telemetry surface.
The timeout output identifies the initial wait but does not expose child
stderr or exit status in the test failure; if the outside-sandbox run also
times out, add diagnostic process-state evidence before changing controls.

Could not verify

• Live PR test(lsp): explicit push/pull ordering controls on the fake LSP server (refs #2824) #2974 title, body, comments, check runs, and merge state.
• Fresh exact-head CI status. Absent or stale checks are not treated as green.
• Whether the direct-wire cases pass on the repository's supported CI runner.
• Compile-valid guard mutations, because the brief permits no source changes.
• Full preflight, because offline tree-sitter grammar acquisition stalled.

Named output

Strong: The new tests form a useful fixture-wire fidelity layer, but they
do not exercise the production LSP client or the index session-start path.
That separation is appropriate for fixture controls; callers still need
independent production behavior tests for each ordering/outcome matrix cell.

Previous-round disposition

No previous review findings were supplied.

Finding	Disposition
Previous findings	None supplied

Next owner

The fixer or orchestrator should run the exact head outside the sandbox,
capture the direct-wire result, then refresh all required CI and merge-state
evidence. If the timeout reproduces, the fixer owns the fixture-process probe;
if it passes, the orchestrator owns recording the sandbox limitation and
updating the verdict to merge as-is only after fresh required checks pass.

[apmantza]

Detailed review handoff: #2974 (comment)

Verdict: merge after outside-sandbox verification
Next owner: orchestrator: run exact-head fixture tests and CI outside sandbox
This is a maintainer-posted COMMENTED review, not an approval.

[apmantza]

Review handoff — exact head 3139edad85fdf117024263046b42d05b4cead8e3

Verdict: merge as-is, subject to the blocked exact-head CI and external Vitest rerun. No CRITICAL, HIGH, MEDIUM, or LOW finding was reproduced.

Evidence: the real persistent-wire probe passed ordering, version, pull outcomes, completion, clean stderr, and child exit. Build, lint, format, changelog, lockfile, and fixture governance checks pass. The eight new Vitest wire tests time out only when this runner closes child stdin early; the same fixture passes through a persistent pipe. Hosted CI and full preflight remain unverified.

Next owner: orchestrator. Rerun the serialized lsp-spawn-heavy fixture suite in a process-capable environment and verify exact-head CI. Do not infer green from the local timeout or absent hosted checks.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud