fix(cursor): incomplete cliModelSkus during ACP lock — variant picker shows raw wire params

[swear01]

Summary

Follow-up to #799 (ACP migration + dual Model/Variant pickers). Operators still see a broken or confusing Cursor model picker in active remote sessions: the Variant column shows raw ACP wire suffixes (e.g. context=272k,reasoning=medium,fast=false, fast=true) instead of human-facing CLI SKU names (e.g. GPT-5.5 High Fast, Composer 2.5 Fast).

This is not a dual-picker UX bug. The picker logic in web/src/lib/cursorModelOptions.ts is correct when the catalog includes full cliModelSkus. The failure mode is incomplete SKU discovery/cache while an ACP session holds the Cursor CLI lock.

Root cause

Cursor model catalog uses two sources (#799 design):

Source	Example	Role
ACP wires	gpt-5.5[context=272k,reasoning=medium,fast=false]	Authoritative for set_config_option
CLI SKUs	gpt-5.5-high-fast	Human-facing variant labels in picker

While agent acp is running, HAPI must not spawn agent --list-models (it SIGTERM-kills the ACP child — see cli/src/agent/backends/acp/agentCliGuard.ts).

Observed failure chain:

1. Session start seeds wires only — syncCursorModelsFromAcp() in cli/src/cursor/cursorAcpRemoteLauncher.ts calls seedCursorModelsCache({ ...snapshot }) without cliModelSkus.
2. Enrich early-return — attachCliSkusToResponse / enrichCursorModelsWithCliSkus in cli/src/modules/common/cursorModels.ts historically returned immediately when any cliModelSkus were present, so a partial cache (e.g. 2 SKUs) could never be merged with the full list (~106 SKUs on a typical host).
3. Web prefers partial session SKUs — SessionChat used session.cliModelSkus whenever length > 0, ignoring the richer machine RPC response from the runner process (which usually has no ACP lock and can cold-probe).

When cliModelSkus are missing/incomplete, resolveCursorVariantOptions falls back to raw ACP wire rows and the picker looks "怪".

Repro (local)

1. Machine with Cursor agent on PATH; cold listCursorModels returns ~28 ACP wires + ~106 CLI SKUs.
2. Start a Cursor remote ACP session (session child holds ACP lock).
3. Open in-session Model/Variant picker before runner shared cache is fully populated, or with a stale HAPI_HOME/cache/cursor-models.json containing only a few cliModelSkus.
4. Expected: Variant rows like GPT-5.5 High Fast, Composer 2.5 Fast.
5. Actual: Variant rows like context=272k,reasoning=medium,fast=false or only 2 variants for gpt-5.5.

Empirical baseline: with full SKU merge, composer-2.5 shows Composer 2.5 | Composer 2.5 Fast; gpt-5.5 shows 10 CLI variants.

Proposed fix

CLI (cache correctness)

• attachCliSkusToResponse / enrichCursorModelsWithCliSkus: merge SKU lists; never early-return on partial cliModelSkus.
• syncCursorModelsFromAcp: when seeding wires, inherit cliModelSkus from readSharedCursorModelsCache() so session RPC under lock still returns full SKUs after a runner cold probe.
• listCursorModelsWhileAcpActive: union in-memory + shared cliModelSkus before attach.

Web (defense in depth)

• mergeCursorCliModelSkus(machine, session) — prefer richer source (machine RPC often has full list).
• Extract buildInSessionCursorCatalogSources() so merge logic is not scattered in SessionChat.tsx.

Optional

• Runner background pre-warm: listCursorModels() on runner start to populate cursor-models.json before first in-session picker open.

Scope / files

Area	Path
Session seed	cli/src/cursor/cursorAcpRemoteLauncher.ts
Catalog RPC	cli/src/modules/common/cursorModels.ts
Shared cache	cli/src/modules/common/cursorModelsSharedCache.ts
Web catalog	web/src/lib/cursorPickerState.ts, web/src/components/SessionChat.tsx

Acceptance criteria

1. In-session Cursor picker shows CLI SKU names for variants when agent --list-models lists matching SKUs (not raw ACP param strings).
2. When session RPC returns 2 cliModelSkus and machine RPC returns 106, the UI uses the union (106).
3. ACP-active code paths never spawn agent --list-models.
4. Regression tests for partial-cache merge + session seed inheriting shared SKUs.

Non-goals

• Formatting/beautifying raw ACP suffixes for models with no CLI SKU coverage (e.g. some claude-sonnet-4 wires) — feat(cursor): migrate remote sessions to ACP with model/variant pickers #799 explicitly avoids semantic guessing on ACP param strings.
• Hub-level merged endpoint (web + CLI cache fix is sufficient).

Related

• feat(cursor): migrate remote sessions to ACP with model/variant pickers #799 — ACP migration + dual pickers
• fix(web/cli): Cursor model catalog — Composer 2.5 hard to find or absent in picker #705 — earlier Composer 2.5 catalog discoverability (closed via feat(cursor): migrate remote sessions to ACP with model/variant pickers #799)
• Migrate Cursor integration from agent -p stream-json mode to Cursor ACP mode #781 — ACP migration umbrella (closed)

[github-actions]

Confirmed from the current code. This report matches the implementation paths I checked: SKU enrichment currently stops as soon as any cliModelSkus exist, ACP snapshot seeding writes the snapshot without inheriting shared-cache SKUs directly at the seed call site, and the active-session web path uses session SKUs whenever that list is non-empty instead of unioning with the machine response.

The ACP lock constraint is also reflected in code: agent --list-models is intentionally skipped while ACP is active, so the fix should preserve that behavior and merge from already available cache/RPC sources instead of probing from the locked session process.

Relevant code:

• cli/src/modules/common/cursorModels.ts:42 - attachCliSkusToResponse returns early when response.cliModelSkus has any entries.
• cli/src/modules/common/cursorModels.ts:54 - enrichCursorModelsWithCliSkus has the same early return for any existing SKUs.
• cli/src/modules/common/cursorModels.ts:68 - explicit guard: never spawn agent --list-models while ACP transport is active.
• cli/src/modules/common/cursorModels.ts:195 - ACP-active catalog path uses ACP snapshot/shared/in-memory cache only.
• cli/src/cursor/cursorAcpRemoteLauncher.ts:439 - session startup builds the ACP model snapshot.
• cli/src/cursor/cursorAcpRemoteLauncher.ts:446 - snapshot is seeded with { success: true, ...snapshot }; no direct shared cliModelSkus inheritance at this call site.
• cli/src/agent/backends/acp/agentCliGuard.ts:5 - documents that spawning agent --list-models while agent acp runs terminates the ACP child.
• web/src/components/SessionChat.tsx:228 - active-session UI picks cursorModelsState.cliModelSkus whenever non-empty.
• web/src/components/SessionChat.tsx:232 - machine cliModelSkus are only used as fallback, not unioned with session SKUs.
• web/src/lib/cursorModelOptions.ts:241 - picker intentionally hides raw ACP wire rows when CLI SKUs exist for a base.
• web/src/lib/cursorPickerState.ts:73 - catalog builder accepts a single cliModelSkus list; I did not find a session+machine SKU union helper in this path.

No more repro info needed from the issue body; it already points to the affected paths and expected behavior.

---

HAPI Bot

[JonbinC]

Adding one more real-world datapoint from a self-hosted HAPI deployment, which looks very close to this issue.

Environment:

Host: Linux arm64 (jumbo-sg-arm)
HAPI: 0.20.2
Cursor Agent CLI: 2026.06.16-20-30-07-a07d3ac
Session: remote Cursor session spawned by HAPI runner

HAPI process/session shape:

hapi runner start-sync --workspace-root /home/ubuntu
hapi cursor --hapi-starting-mode remote --started-by runner --yolo
agent ... acp

HAPI logs show repeated model catalog requests for the active Cursor session:

List Cursor models request
[RUNNER RUN] Spawning session
  "agent": "cursor",
  "sessionType": "simple"
[SPAWN HAPI CLI] Spawning: hapi cursor --hapi-starting-mode remote --started-by runner --yolo
[CONTROL SERVER] Session started: ...
  "flavor": "cursor"

Observed behavior in HAPI web UI:

• Cursor session model picker only shows a very small list (in our case, effectively two Cursor model choices).
• This makes it look like the Cursor account only has a couple of available models.

But on the same machine, outside the active HAPI picker path, Cursor Agent CLI sees the full model catalog:

$ agent status
✓ Logged in as <redacted>

$ agent --version
2026.06.16-20-30-07-a07d3ac

$ agent update
Checking for updates...
Already up to date

$ agent models
# 139 model rows parsed locally
# includes composer-2.5, composer-2.5-fast, gpt-5.5 variants,
# claude-opus-4-8 variants, etc.

So in this case:

• Cursor CLI authentication is OK.
• The installed Cursor Agent CLI is current.
• agent models / agent --list-models can return the full catalog on the runner host.
• The HAPI in-session picker/catalog is the part that appears partial or falls back to a tiny list while a Cursor ACP session is active.

This matches the suspected failure mode described here: incomplete or unavailable cliModelSkus / CLI catalog while agent acp is active, causing the web picker to fall back to a confusing partial catalog.

A user-facing improvement that would have helped us diagnose this quickly: when HAPI cannot attach the full agent --list-models catalog because an ACP session is active/locked, show an explicit warning in the picker such as:

Full Cursor model catalog unavailable while ACP session is active; showing fallback/current models only.

and ideally expose a refresh/retry path when no Cursor ACP child is active.

Workaround confirmed locally: start Cursor sessions with an explicit model id, e.g.

hapi cursor --model composer-2.5-fast
hapi cursor --model gpt-5.5-extra-high-fast

That avoids relying on the incomplete runtime picker.

[b03213135]

gpt5.5 config is still changed to 272k medium unexpectedly in "hapi cursor".

hapi version

$hapi --version
hapi version: 0.20.2

reproduce

$hapi hub --relay
$hapi cursor --yolo
Select gpt5.5 1m extra high in cursor agent manually. Then go to web and send a message. The control will be switched to remote and the config is switched to 272k medium.