@blxzer/cursor-trellis 0.2.6 → 0.2.8

package/dist/templates/trellis/local/README.md

@@ -1,59 +1,83 @@
-# Cursor++ BYOK — Trellis subagent model routing
+# Cursor++ Local Bundle
 
-**Who needs this:** Cursor IDE with [Cursor++](https://ccursor.cometix.dev) (BYOK proxy). **Native Cursor API users can ignore this directory.**
+> **Native Cursor users:** safe to ignore or delete this directory unless using **Cursor++ BYOK**.
 
-## Agent-led setup (recommended)
+**Who needs this:** Cursor IDE with [Cursor++](https://ccursor.cometix.dev) (BYOK proxy). Method 2.5 patches the `WPeLc8` resolver so Trellis Task subagents get per-role BYOK slugs instead of inheriting the parent model.
 
-In **Cursor Agent**, run skill **`trellis-cursor2plus-setup`** (after `trellis init` with Cursor, or anytime `providers.json` changes). The agent lists models, writes commented **`~/.ccursor/trellis-task-models.json5`** with **primary** and **fallback** per role, runs `patch_wpelc8.py`, and reports WARN/ERROR from the resolver.
+## Bundle files
 
-Copy `../trellis-task-models.json5.example` only if you prefer a manual starting point.
+| File | Purpose |
+|------|---------|
+| `patch_wpelc8.py` | Operator CLI: dry-run map, compat check, apply (with `--approve`), revert |
+| `smoke.py` | Health smoke: env, patch status, configured roles (no secret reads) |
+| `trellis_task_models_config.py` | JSON5 + providers catalog resolver (used by patch) |
+| `config.local.json.example` | Optional paths (`extensionJs`, `ccursorHome`, …) |
+| `config.local.json` | Your local paths (gitignored; never commit secrets) |
 
-## What to put in `trellis-task-models.json5`
+User-wide model doc: `~/.ccursor/trellis-task-models.json5` (see `../trellis-task-models.json5.example`). Project override: `../subagent-models.json` (optional).
 
-| JSON key (under `models`) | Meaning |
-|-----------------|--------|
-| `trellis-research` | Trellis research Task subagent |
-| `trellis-implement` | Trellis implement (+ Parent/Child default Task) |
-| `trellis-check` | Trellis check Task subagent |
-| `generalPurpose` / `shell` / `best-of-n-runner` | Cursor built-in Task types |
+## Compatibility window
 
-Each role: `{ "primary": "<name>", "fallback": "<name>" }`. **Names:** use **apiModel** or **displayName** from Cursor++ (not `model-xxxxx` unless you want to). Patch time resolves against `providers.json`; missing primary → WARN + fallback; ERROR only if both fail.
+- **Verified:** Cursor **3.7.27** / Cursor++ **v0.0.11** (see `.trellis/spec/guides/cursor-subagent-policy.md`, 2026-06-18)
+- **Re-verify** after any Cursor or Cursor++ upgrade: `python patch_wpelc8.py --check-compat`
+- If `--check-compat` reports `fail` or `unknown`, treat the patch as stale until you re-apply or revert
 
-```bash
-python patch_wpelc8.py --explain      # key meanings
-python patch_wpelc8.py --list-models  # current catalog from providers.json
-```
-
-**Explore** is not in this file — use the Cursor++ panel.
+## Method 2.5 workflow
 
-## When Cursor++ models change
+1. **Dry-run map** — `python patch_wpelc8.py --print-map` (no file writes)
+2. **Operator approval** — review map and compat output; decide to proceed
+3. **Apply** — `python patch_wpelc8.py --apply --approve` (writes `extension.js`)
+4. **Reload Cursor** — Developer: Reload Window (once per apply/revert)
+5. **A ≠ B probe** — parent chat model must differ from a patched subagent map target; dispatch a `trellis-*` Task and confirm the subagent self-reports the **map target** slug/model, not the parent
+6. **Revert if needed** — `python patch_wpelc8.py --revert` then Reload Window
 
-`providers.json` is the live catalog. Slugs (`model-xxxxx`) can change when you add/remove models in Cursor++.
+Agent-led setup: run skill **`trellis-cursor2plus-setup`** in Cursor Agent (lists models, writes JSON5, runs patch steps).
 
-1. Re-run skill **`trellis-cursor2plus-setup`**, or `python patch_wpelc8.py --list-models` and fix JSON5
-2. `python patch_wpelc8.py` → Reload Window only if you had not patched yet or reverted
+## Revert recipe
 
-You may **omit** keys for Task types you never use.
+```bash
+cd .trellis/local/cursor2plus
+python patch_wpelc8.py --revert
+```
 
-## Two-layer JSON (project overrides user)
+Then **Developer: Reload Window**. Subagents return to **inherit parent** BYOK model. Re-apply only after `--check-compat` is `ok` and you have explicit `--approve`.
 
-| File | Scope |
-|------|--------|
-| `~/.ccursor/trellis-task-models.json5` (or `.json`) | User — all repos |
-| `{repo}/.trellis/local/subagent-models.json` | Project overrides (optional) |
+## A ≠ B verification recipe
 
-## Paths
+Goal: prove the patch routes **subagent** model independently of the **parent** session model.
 
-`providers.json` default: `~/.ccursor/providers.json`. Override: `config.local.json` → `providersJson`, or env `TRELLIS_CCURSOR_PROVIDERS`.
+1. Set parent chat to model **A** (any BYOK model in Cursor++).
+2. Ensure `trellis-task-models.json5` maps e.g. `trellis-implement` to model **B** (`primary`/`fallback` resolving to a different slug than A).
+3. `python patch_wpelc8.py --print-map` — note the slug for `trellis-implement` (= map target **B**).
+4. `python patch_wpelc8.py --apply --approve` → Reload Window.
+5. Dispatch a `trellis-implement` Task from a parent on model **A**.
+6. **Pass:** subagent self-report / trace shows **B** (map target), not **A**.
+7. **Fail:** subagent shows **A** → patch stale or not applied; run `--check-compat`, re-patch, or `--revert`.
 
-## Apply / revert
+## CLI reference
 
 ```bash
-cd .trellis/local/cursor2plus
-python patch_wpelc8.py --print-map
-python patch_wpelc8.py
+python patch_wpelc8.py --print-map          # dry-run slug map
+python patch_wpelc8.py --check-compat       # WPeLc8 locatability (no writes)
+python patch_wpelc8.py --apply --approve    # write patch (requires --approve)
+python patch_wpelc8.py --apply --dry-run    # validate without write
+python patch_wpelc8.py --revert             # remove patch
+python patch_wpelc8.py --explain            # JSON5 key meanings
+python patch_wpelc8.py --list-models        # catalog from providers.json
+python smoke.py                             # env + patch_status smoke
 ```
 
-**Developer: Reload Window** after patch.
+`--apply` without `--approve` **refuses** and exits non-zero.
+
+## What to put in `trellis-task-models.json5`
+
+| JSON key (under `models`) | Meaning |
+|---------------------------|---------|
+| `trellis-research` | Trellis research Task subagent |
+| `trellis-implement` | Trellis implement (+ Parent/Child default Task) |
+| `trellis-check` | Trellis check Task subagent |
+| `generalPurpose` / `shell` / `best-of-n-runner` | Cursor built-in Task types |
+
+Each role: `{ "primary": "<name>", "fallback": "<name>" }`. Names: **apiModel** or **displayName** from Cursor++ (`--list-models`). **Explore** is not in this file — use the Cursor++ panel.
 
-Policy: `.trellis/spec/guides/cursor-subagent-policy.md` (Method 2.5 / 2.6).
+Policy: `.trellis/spec/guides/cursor-subagent-policy.md` (Method 2.5 / 2.6).

package/dist/templates/trellis/local/index.d.ts

@@ -1,5 +1,6 @@
 export declare const cursor2plusPatchScript: string;
 export declare const cursor2plusReadme: string;
+export declare const cursor2plusSmokeScript: string;
 export declare const cursor2plusConfigExample: string;
 export declare const subagentModelsExample: string;
 export declare const trellisTaskModelsJson5Example: string;

package/dist/templates/trellis/local/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AACxD,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAC/E,eAAO,MAAM,qBAAqB,QAA4C,CAAC;AAC/E,eAAO,MAAM,6BAA6B,QAEzC,CAAC;AACF,eAAO,MAAM,yBAAyB,QAA6C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,sBAAsB,QAA+B,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAyB,CAAC;AACxD,eAAO,MAAM,sBAAsB,QAAwB,CAAC;AAC5D,eAAO,MAAM,wBAAwB,QAAyC,CAAC;AAC/E,eAAO,MAAM,qBAAqB,QAA4C,CAAC;AAC/E,eAAO,MAAM,6BAA6B,QAEzC,CAAC;AACF,eAAO,MAAM,yBAAyB,QAA6C,CAAC"}

package/dist/templates/trellis/local/index.js

@@ -7,6 +7,7 @@ function readLocal(name) {
 }
 export const cursor2plusPatchScript = readLocal("patch_wpelc8.py");
 export const cursor2plusReadme = readLocal("README.md");
+export const cursor2plusSmokeScript = readLocal("smoke.py");
 export const cursor2plusConfigExample = readLocal("config.local.json.example");
 export const subagentModelsExample = readLocal("subagent-models.json.example");
 export const trellisTaskModelsJson5Example = readLocal("trellis-task-models.json5.example");

package/dist/templates/trellis/local/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,iBAAiB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC,2BAA2B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CACpD,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC,+BAA+B,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/templates/trellis/local/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,iBAAiB,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;AACxD,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAC5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,SAAS,CAAC,2BAA2B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,8BAA8B,CAAC,CAAC;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,SAAS,CACpD,mCAAmC,CACpC,CAAC;AACF,MAAM,CAAC,MAAM,yBAAyB,GAAG,SAAS,CAAC,+BAA+B,CAAC,CAAC"}

package/dist/templates/trellis/local/patch_wpelc8.py

@@ -17,6 +17,7 @@ from trellis_task_models_config import (
 )
 
 MARKER = "/*TRELLIS_B2_WPeLc8*/"
+INJECT_NEEDLE = "});return!UbAQWn||"
 
 
 def _repo_root(start: Path) -> Path:
@@ -111,28 +112,43 @@ def resolve_model_layers(bundle_dir: Path, config: dict, providers_path: Path) -
     return resolve_slots_to_slugs(merged, providers_path)
 
 
-def resolve_extension_js(bundle_dir: Path, config: dict) -> Path:
+def configured_slot_map(bundle_dir: Path, config: dict) -> dict[str, list[str]]:
+    """Non-secret role → [primary, fallback, …] from JSON5 only (no providers.json read)."""
+    user_path = resolve_user_models_path(config)
+    project_path = resolve_project_models_path(bundle_dir, config)
+    user_slots = extract_raw_slots(load_task_models_document(user_path))
+    project_slots = (
+        extract_raw_slots(load_task_models_document(project_path))
+        if project_path
+        else {}
+    )
+    return _merge_slot_maps(user_slots, project_slots)
+
+
+def _extension_candidates(config: dict) -> list[Path]:
     for key in ("extensionJs", "extension_js"):
         if isinstance(config.get(key), str) and config[key].strip():
-            return Path(config[key].strip()).expanduser()
+            return [Path(config[key].strip()).expanduser()]
     env = os.environ.get("TRELLIS_CURSOR2PLUS_EXTENSION", "").strip()
     if env:
-        return Path(env).expanduser()
+        return [Path(env).expanduser()]
     if sys.platform == "win32":
         local = os.environ.get("LOCALAPPDATA", "")
-        candidates = [
+        return [
             Path(local) / "Programs" / "cursor" / "resources" / "app" / "extensions" / "cursor2plus" / "dist" / "extension.js",
             Path(r"D:\cursor\resources\app\extensions\cursor2plus\dist\extension.js"),
         ]
-    elif sys.platform == "darwin":
-        candidates = [
+    if sys.platform == "darwin":
+        return [
             Path("/Applications/Cursor.app/Contents/Resources/app/extensions/cursor2plus/dist/extension.js"),
         ]
-    else:
-        candidates = [
-            Path.home() / ".local" / "share" / "cursor" / "resources" / "app" / "extensions" / "cursor2plus" / "dist" / "extension.js",
-        ]
-    for c in candidates:
+    return [
+        Path.home() / ".local" / "share" / "cursor" / "resources" / "app" / "extensions" / "cursor2plus" / "dist" / "extension.js",
+    ]
+
+
+def resolve_extension_js(bundle_dir: Path, config: dict) -> Path:
+    for c in _extension_candidates(config):
         if c.is_file():
             return c
     raise SystemExit(
@@ -140,6 +156,13 @@ def resolve_extension_js(bundle_dir: Path, config: dict) -> Path:
     )
 
 
+def try_resolve_extension_js(bundle_dir: Path, config: dict) -> Path | None:
+    for c in _extension_candidates(config):
+        if c.is_file():
+            return c
+    return None
+
+
 def build_inject_block(model_map: dict[str, str]) -> str:
     if not model_map:
         raise SystemExit(
@@ -164,15 +187,27 @@ def find_wpelc8_body(source: str) -> tuple[int, int]:
     return start, end
 
 
+def probe_wpelc8_compat(source: str) -> dict[str, str]:
+    """Non-exiting WPeLc8 / inject-anchor probe for --check-compat and smoke."""
+    start = source.find("function WPeLc8(")
+    if start < 0:
+        return {"wpelc8": "not_locatable", "inject_anchor": "unknown", "end_anchor": "unknown"}
+    end = source.find("async function*o4ZNpa", start)
+    if end < 0:
+        return {"wpelc8": "locatable", "inject_anchor": "unknown", "end_anchor": "missing"}
+    fn = source[start:end]
+    anchor = "present" if INJECT_NEEDLE in fn else "missing"
+    return {"wpelc8": "locatable", "inject_anchor": anchor, "end_anchor": "present"}
+
+
 def apply_patch(source: str, inject: str) -> str:
     start, end = find_wpelc8_body(source)
     fn = source[start:end]
     if MARKER in fn:
         fn = remove_patch_from_fn(fn)
-    needle = "});return!UbAQWn||"
-    if needle not in fn:
-        raise SystemExit(f"inject anchor missing: {needle!r}")
-    fn_new = fn.replace(needle, f"}});{inject}return!UbAQWn||", 1)
+    if INJECT_NEEDLE not in fn:
+        raise SystemExit(f"inject anchor missing: {INJECT_NEEDLE!r}")
+    fn_new = fn.replace(INJECT_NEEDLE, f"}});{inject}return!UbAQWn||", 1)
     return source[:start] + fn_new + source[end:]
 
 
@@ -240,14 +275,80 @@ def cmd_bootstrap(bundle_dir: Path) -> None:
     print("Next: in Cursor Agent, run skill trellis-cursor2plus-setup", file=sys.stderr)
 
 
+def cmd_check_compat(bundle_dir: Path, config: dict) -> int:
+    extension = try_resolve_extension_js(bundle_dir, config)
+    result: dict[str, object] = {
+        "extension": str(extension) if extension else None,
+        "patch_marker_present": False,
+        "wpelc8": "unknown",
+        "inject_anchor": "unknown",
+        "end_anchor": "unknown",
+    }
+    if extension is None:
+        result["status"] = "unknown"
+        result["hint"] = (
+            "extension.js not found — set extensionJs in config.local.json or run --bootstrap; "
+            "manual verification required"
+        )
+        print(json.dumps(result, indent=2, sort_keys=True))
+        return 2
+
+    source = extension.read_text(encoding="utf-8", errors="ignore")
+    result["patch_marker_present"] = MARKER in source
+    probe = probe_wpelc8_compat(source)
+    result.update(probe)
+
+    wpelc8 = probe["wpelc8"]
+    anchor = probe["inject_anchor"]
+    end_anchor = probe.get("end_anchor", "unknown")
+
+    if wpelc8 == "not_locatable" or anchor == "missing":
+        result["status"] = "fail"
+        result["hint"] = (
+            "WPeLc8 or inject anchor not found after Cursor/Cursor++ upgrade — "
+            "re-run patch with --apply --approve or revert to inherit-parent"
+        )
+    elif wpelc8 == "unknown" or anchor == "unknown" or end_anchor == "unknown":
+        result["status"] = "unknown"
+        result["hint"] = "Locator uncertain — manually verify extension.js after any upgrade"
+    else:
+        result["status"] = "ok"
+        result["hint"] = "WPeLc8 and inject anchor locatable"
+
+    print(json.dumps(result, indent=2, sort_keys=True))
+    return 0 if result["status"] == "ok" else (1 if result["status"] == "fail" else 2)
+
+
 def main() -> None:
-    ap = argparse.ArgumentParser(description="Trellis Cursor++ WPeLc8 model map")
-    ap.add_argument("--revert", action="store_true")
-    ap.add_argument("--dry-run", action="store_true")
-    ap.add_argument("--bootstrap", action="store_true")
-    ap.add_argument("--explain", action="store_true")
-    ap.add_argument("--list-models", action="store_true")
-    ap.add_argument("--print-map", action="store_true")
+    ap = argparse.ArgumentParser(
+        description="Trellis Cursor++ WPeLc8 model map (Method 2.5)",
+        epilog=(
+            "Read-only: --print-map, --check-compat. "
+            "Write: --apply --approve (or --revert). "
+            "Never runs in CI by default."
+        ),
+    )
+    ap.add_argument("--revert", action="store_true", help="Remove Trellis patch from extension.js")
+    ap.add_argument("--apply", action="store_true", help="Apply patch to extension.js")
+    ap.add_argument(
+        "--approve",
+        action="store_true",
+        help="Explicit operator approval (required for --apply writes)",
+    )
+    ap.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="With --apply: validate patch without writing extension.js",
+    )
+    ap.add_argument("--bootstrap", action="store_true", help="Create config.local.json with extension path")
+    ap.add_argument("--explain", action="store_true", help="Explain trellis-task-models.json5 keys")
+    ap.add_argument("--list-models", action="store_true", help="List models from providers.json catalog")
+    ap.add_argument("--print-map", action="store_true", help="Dry-run: print resolved slug map (no file writes)")
+    ap.add_argument(
+        "--check-compat",
+        action="store_true",
+        help="Check WPeLc8 locatability in current extension.js (no file writes)",
+    )
     args = ap.parse_args()
 
     bundle_dir = Path(__file__).resolve().parent
@@ -259,39 +360,62 @@ def main() -> None:
         return
 
     config = _load_config(bundle_dir)
+
+    if args.check_compat:
+        raise SystemExit(cmd_check_compat(bundle_dir, config))
+
     providers_path = resolve_providers_json(config)
 
     if args.list_models:
         cmd_list_models(providers_path)
         return
 
-    model_map, notes = resolve_model_layers(bundle_dir, config, providers_path)
-    if notes:
-        print("resolve:", file=sys.stderr)
-        for line in notes:
-            print(line, file=sys.stderr)
-    if any("ERROR" in line for line in notes):
-        raise SystemExit(1)
+    needs_map = args.print_map or args.apply or args.revert
+    model_map: dict[str, str] = {}
+    notes: list[str] = []
+    if needs_map and not args.revert:
+        model_map, notes = resolve_model_layers(bundle_dir, config, providers_path)
+        if notes:
+            print("resolve:", file=sys.stderr)
+            for line in notes:
+                print(line, file=sys.stderr)
+        if any("ERROR" in line for line in notes):
+            raise SystemExit(1)
 
     if args.print_map:
         print(json.dumps(model_map, indent=2, sort_keys=True))
         return
 
-    extension = resolve_extension_js(bundle_dir, config)
-    source = extension.read_text(encoding="utf-8", errors="ignore")
     if args.revert:
+        extension = resolve_extension_js(bundle_dir, config)
+        source = extension.read_text(encoding="utf-8", errors="ignore")
         new = remove_patch(source)
-    else:
+        extension.write_text(new, encoding="utf-8", newline="\n")
+        print("wrote", extension)
+        return
+
+    if args.apply:
+        if not args.approve and not args.dry_run:
+            print(
+                "refused: --apply writes extension.js and requires explicit --approve "
+                "(use --dry-run to validate without writing)",
+                file=sys.stderr,
+            )
+            raise SystemExit(1)
+        extension = resolve_extension_js(bundle_dir, config)
+        source = extension.read_text(encoding="utf-8", errors="ignore")
         inject = build_inject_block(model_map)
         new = apply_patch(source, inject)
-
-    if args.dry_run:
-        print("ok", "revert" if args.revert else "patch", "delta", len(new) - len(source))
+        if args.dry_run:
+            print("ok patch delta", len(new) - len(source))
+            return
+        extension.write_text(new, encoding="utf-8", newline="\n")
+        print("wrote", extension)
         return
 
-    extension.write_text(new, encoding="utf-8", newline="\n")
-    print("wrote", extension)
+    ap.print_help()
+    raise SystemExit(2)
 
 
 if __name__ == "__main__":
-    main()
+    main()

package/dist/templates/trellis/local/smoke.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Cursor++ local bundle smoke check — whitelist metadata only, no secret reads."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from patch_wpelc8 import (
+    MARKER,
+    _load_config,
+    configured_slot_map,
+    probe_wpelc8_compat,
+    try_resolve_extension_js,
+)
+
+CAVEATS = [
+    "Cursor++ is third-party; reverse-engineering is version-bound",
+    "Never reads BYOK provider catalog file contents",
+    "Patch is operator-only; not part of CI or default Trellis workflow",
+    "Re-verify after any Cursor or Cursor++ upgrade",
+]
+
+
+def detect_env() -> tuple[str, str | None]:
+    env_flag = os.environ.get("TRELLIS_CURSOR_BYOK", "").strip()
+    if env_flag == "1":
+        return "byok", "TRELLIS_CURSOR_BYOK=1"
+    if env_flag == "0":
+        return "native", "TRELLIS_CURSOR_BYOK=0"
+
+    routes = Path.home() / ".ccursor" / "routes.json"
+    if routes.is_file():
+        try:
+            data = json.loads(routes.read_text(encoding="utf-8"))
+            byok = data.get("byokMode")
+            if byok in (1, "1", True):
+                return "byok", "routes.json:byokMode"
+            if byok in (0, "0", False):
+                return "native", "routes.json:byokMode"
+        except (OSError, json.JSONDecodeError, TypeError):
+            pass
+    return "unknown", None
+
+
+def detect_patch_status(bundle_dir: Path, config: dict) -> tuple[str, dict[str, object]]:
+    extension = try_resolve_extension_js(bundle_dir, config)
+    meta: dict[str, object] = {"extension": str(extension) if extension else None}
+    if extension is None:
+        return "not-applied", meta
+
+    source = extension.read_text(encoding="utf-8", errors="ignore")
+    marker_present = MARKER in source
+    meta["patch_marker_present"] = marker_present
+    probe = probe_wpelc8_compat(source)
+    meta.update(probe)
+
+    if not marker_present:
+        return "not-applied", meta
+
+    if probe["wpelc8"] == "not_locatable" or probe["inject_anchor"] == "missing":
+        return "stale", meta
+    if probe["wpelc8"] == "unknown" or probe["inject_anchor"] == "unknown":
+        return "stale", meta
+    return "applied", meta
+
+
+def main() -> int:
+    bundle_dir = Path(__file__).resolve().parent
+    config = _load_config(bundle_dir)
+    env, env_source = detect_env()
+    patch_status, patch_meta = detect_patch_status(bundle_dir, config)
+    slots = configured_slot_map(bundle_dir, config)
+
+    report = {
+        "env": env,
+        "env_source": env_source,
+        "patch_status": patch_status,
+        "patch_meta": patch_meta,
+        "current_map": {
+            "configured_roles": {
+                role: {"candidates": names} for role, names in sorted(slots.items())
+            },
+            "note": "Role names from user JSON5 config only; slugs not resolved (no provider catalog read)",
+        },
+        "caveats": CAVEATS,
+    }
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/templates/trellis/scripts/common/codebase_retrieval_router.py

@@ -14,8 +14,8 @@ from pathlib import Path
 from typing import Any
 
 from .cursor_retrieval_env import (
-    ENV_BYOK,
     detect_cursor_retrieval_env,
+    is_byok_conservative,
     semantic_route_spec,
 )
 
@@ -716,7 +716,7 @@ def _fallback_hints(
             "replacesRole": "semantic",
         })
     cenv = cursor_env or detect_cursor_retrieval_env()
-    if cenv == ENV_BYOK:
+    if is_byok_conservative(cenv):
         hints.append({
             "when": "built-in @codebase / SemanticSearch not in agent tool list",
             "action": (

package/dist/templates/trellis/scripts/common/cursor_retrieval_env.py

@@ -75,12 +75,26 @@ def is_byok(env: CursorRetrievalEnv | None = None) -> bool:
     return (env or detect_cursor_retrieval_env()) == ENV_BYOK
 
 
+def is_byok_conservative(env: CursorRetrievalEnv | None = None) -> bool:
+    """Conservative semantic routing: BYOK plus unknown (no routes.json / ambiguous byokMode)."""
+    resolved = env or detect_cursor_retrieval_env()
+    return resolved == ENV_BYOK or resolved == ENV_UNKNOWN
+
+
 def semantic_route_spec(cursor_env: CursorRetrievalEnv) -> dict[str, object]:
     """platform-semantic route fields for conceptual / optional semantic slots."""
-    if cursor_env == ENV_BYOK:
+    if is_byok_conservative(cursor_env):
+        unknown_caveat = (
+            " Unknown cursorEnv: conservative fast-context primary (same as BYOK)."
+            if cursor_env == ENV_UNKNOWN
+            else ""
+        )
         return {
             "commands": ["fast_context_search (fast-context MCP)"],
-            "rationale_suffix": " Cursor++ BYOK: built-in semantic unavailable; fast-context MCP primary.",
+            "rationale_suffix": (
+                " Cursor++ BYOK: built-in semantic unavailable; fast-context MCP primary."
+                + unknown_caveat
+            ),
             "platformNative": False,
             "semanticBackend": "fast-context-mcp",
         }