impel-cli 0.18.15 → 0.18.16

package/README.md

@@ -98,8 +98,58 @@ Names include the tenant, such as `Impel Claude (Acme)` and
 `Impel ChatGPT (Acme)`. The selected CLI tenant does not affect which tenant an
 app opens. Tenant variants can remain installed side by side.
 
+Impel-managed apps do not run the vendors' in-app auto-updaters. The generated
+Claude policy disables its updater, and the ChatGPT launcher disables Sparkle
+before starting the pinned app. Run `impel update` to move managed apps to the
+next exact vendor builds reviewed and shipped with the CLI. This does not
+change the update settings of native personal Claude or ChatGPT installations.
+
 Linux does not have managed desktop apps. Use the isolated CLI commands there.
 
+## Experimental managed Cursor
+
+On macOS, a hidden experiment can prepare an isolated Cursor runtime for the
+selected Impel tenant:
+
+```sh
+impel experimental cursor prepare
+impel experimental cursor open [workspace]
+impel experimental cursor status
+```
+
+The experiment never modifies `/Applications/Cursor.app` or the native Cursor
+profile. It verifies the installed stable app's Developer ID signature, mirrors
+it into the selected tenant's Impel-managed directory, enables Cursor's bundled
+local-agent runtime with fail-closed fixed-width patches, verifies extension
+integrity and signing, and prepares a tenant-only home, user-data directory,
+and extension directory. Cursor's local-mode profile-import service is disabled
+so it cannot inspect or copy the native Cursor profile. The managed bundle
+recomputes Cursor's signed-source checksum table after its reviewed patches, and
+the launcher uses Cursor's process-lifetime secret store because no persistent
+Cursor account or provider secret belongs in this tenant runtime.
+
+The native Cursor installation continues to update through Cursor. Every
+`prepare` inspects it again and atomically rebuilds the managed copy
+when a compatible version or commit changes. If Cursor changes any reviewed
+local-agent, provider-priority, or model-transport source contract, Impel keeps
+the previous managed generation intact and refuses the update until the patch is
+reviewed. `experimental cursor open` performs this prepare step before every
+launch. A real packaged GUI battle test proves that Cursor 3.13.25 can run
+Agent through the selected tenant's gateway with Cursor's own non-secret smoke
+identity. The logical `default` model is resolved by the gateway to its
+registered Cursor default; explicit gateway models continue to use Responses.
+
+This is not complete hosted-Cursor parity or an offline Cursor.
+The managed local transport supports Agent chat, edits, terminal tools, MCP,
+vision, reasoning, and gateway model discovery, and projects the live tenant
+catalog into Cursor's model picker, but the current vendor build explicitly
+disables hosted-only features such as Tab completion, cloud Background Agents,
+shared chats/canvases, Bugbot, and server-side repository indexing in local
+mode. Enabling those paths would either send work to Cursor-hosted models or
+require additional unpublished Cursor protocols, so the experiment does not
+claim or silently emulate them. See
+[`docs/experimental-managed-cursor.md`](docs/experimental-managed-cursor.md).
+
 ## Use the CLI
 
 Select the tenant used by CLI launches:
@@ -179,6 +229,11 @@ impel update --no-recovery    # disable recovery for this run
 schema verified by that CLI. It does not mean cloning an untested moving vendor
 release.
 
+Stable installations follow npm's `latest` tag. Prerelease installations made
+from `impel-cli@next` remain on the `next` channel during `impel update`. If npm
+metadata is temporarily unavailable, update preserves the installed CLI build
+and continues tenant reconciliation without attempting a downgrade.
+
 ## Status and diagnosis
 
 ```sh

package/docs/experimental-managed-cursor.md

@@ -0,0 +1,205 @@
+# Experimental managed Cursor
+
+This hidden macOS experiment runs the stable Cursor desktop Agent against the
+selected Impel tenant without a real Cursor account or Cursor-routed BYOK. It is
+validated against Cursor 3.13.25 and remains separate from the public
+`impel setup` / `impel update` state machine:
+
+```sh
+impel experimental cursor prepare
+impel experimental cursor status
+impel experimental cursor open [workspace-or-Cursor-args...]
+```
+
+## Why standard BYOK is insufficient
+
+Cursor's supported BYOK mode still sends provider keys and requests through
+Cursor's backend, applies only to chat models, and keeps Tab on Cursor-hosted
+models. It cannot provide direct, tenant-scoped Impel inference.
+
+The stable desktop bundle also contains a dormant local-agent runtime with
+OpenAI Responses, Chat Completions, Anthropic Messages, `/models` discovery,
+tools, streaming, reasoning, vision, and MCP support. Impel enables only the
+exact reviewed local-mode signatures and locks provider resolution to its
+process environment.
+
+## Managed authentication
+
+Cursor's packaged Agent UI considers a user logged in only when both an access
+token and refresh token exist. The same stable bundle contains an unconditional
+test command that creates:
+
+- an unsigned JWT with issuer `cursor-smoke-test`, audience `cursor`, and
+  scope `smoke-test`;
+- the literal refresh token `fake-refresh-token-for-testing`.
+
+Impel reproduces that vendor-owned, non-secret identity in the tenant-only
+`state.vscdb` and also passes the JWT through Cursor's
+`--override-cursor-auth-token` process flag. It never asks for, reads, or
+stores a real Cursor credential. The source markers, storage keys, JWT contract,
+and command-line flags are part of the fail-closed vendor compatibility check.
+
+The fake identity unlocks the local Agent UI. Cursor-hosted account, model,
+analytics, and hosted-feature requests remain unauthenticated and cannot use
+the fake token for service access. The Impel PAT-derived tenant credential is
+given only to the bundled local provider:
+
+```text
+CURSOR_LOCAL_AGENT_BASE_URL=<gateway>/experimental/openai/v1
+CURSOR_LOCAL_AGENT_API_KEY=<tenant-scoped Impel credential>
+IMPEL_TENANT_ID=<tenant>
+```
+
+## Update and isolation contract
+
+For every prepare or open, Impel:
+
+1. Finds the installed stable `Cursor.app`.
+2. Verifies its complete Apple signature, Cursor bundle identifier, and vendor
+   Developer ID team.
+3. Reads the exact version and commit from `product.json`.
+4. Verifies every reviewed local-mode, authentication, provider-priority,
+   model-transport, and profile-import source contract.
+5. Verifies Cursor's extension-integrity table, then updates exactly the hashes
+   affected by the reviewed fixed-width patches.
+6. Recomputes Cursor's `product.json` checksum table after every reviewed
+   managed patch, so Cursor's own installation-integrity service verifies the
+   resulting managed bundle.
+7. Assigns a tenant-specific packaged application name and uses tenant-only
+   `HOME`, XDG, user-data, and extension roots. This isolates Cursor's
+   hardcoded `~/.cursor` agents, rules, plugins, worktrees, and logs in addition
+   to the normal VS Code profile state.
+8. Disables local-mode personal-data import so the managed app cannot inspect,
+   copy, or relaunch from the native Cursor profile.
+9. Clears inherited OpenAI, Anthropic, Google, AWS/Bedrock, Azure OpenAI,
+   Cursor, Node, Electron, and portable-profile overrides.
+10. Uses Cursor's built-in process-lifetime secret store. The managed runtime
+    has no real Cursor login or persistent provider key, while its gateway
+    bearer remains process-scoped in the launch environment.
+11. Re-signs every Electron process bundle with the reviewed entitlements and
+   verifies the complete managed copy.
+12. Atomically replaces the tenant generation only after every check passes.
+
+Tenant state lives below:
+
+```text
+~/.config/impel/apps/tenants/<tenant>/cursor/
+  runtime/current/Cursor.app
+  runtime/current/manifest.json
+  home/
+  user-data/
+  extensions/
+```
+
+The launcher rejects user-supplied `--user-data-dir`, `--extensions-dir`,
+and `--override-cursor-auth-token`. The native Cursor profile and the
+operator's `~/.cursor`, `~/.claude`, and `~/.codex` roots are never read or
+modified. The isolated `HOME` means shell, Git, and extension state that
+normally lives in a home directory must be configured separately for this
+tenant runtime.
+
+The managed copy disables self-updates. The signed native installation remains
+Cursor's update authority, and every `open` re-runs `prepare`, adopting a
+compatible stable vendor update immediately. If an update changes any reviewed
+contract, Impel preserves the previous generation and refuses the new build
+until its compatibility signatures and tests are reviewed.
+
+## Gateway contract
+
+The gateway must enable `IMPEL_EXPERIMENTAL_CROSS_APP_MODELS` and serve:
+
+```text
+GET  /experimental/openai/v1/models
+POST /experimental/openai/v1/chat/completions
+POST /experimental/openai/v1/responses
+```
+
+Cursor 3.12 initially submits Agent turns with its logical model `default`
+over Chat Completions, independently of the discovered catalog. The gateway
+maps that alias only on the experimental Cursor route to the exact registered
+Cursor default (`gpt-5.6-sol` today). Bifrost then performs its typed
+Chat-to-Responses conversion, including streaming response conversion, tools,
+reasoning, and multimodal messages. The converted request follows the normal
+pooled Codex path with `store:false`, tenant attribution, usage metering, and
+server-owned provider authentication.
+
+Explicit local-provider model requests can use Responses directly. The
+authenticated catalog is filtered by PAT scopes and live tenant pool readiness
+and advertises tools, streaming, reasoning, vision, context, modalities, and
+both protocol markers required by Cursor's bundled parser.
+
+Reasoning effort is a per-model, per-selection parameter rather than a global
+Cursor setting. The gateway catalog owns each model's allowed levels and
+default. Impel projects those values into Cursor's `Reasoning` selector, and the
+local Responses transport sends the selected value as `reasoning.effort`.
+Bifrost then converts that typed field for the selected Codex or Claude
+subscription provider. Models that advertise no reasoning levels receive no
+effort selector.
+
+## Battle-test result and parity boundary
+
+The gated packaged-GUI contract now proves all of the following against the
+real signed stable app and patched managed copy:
+
+- the native Cursor profile is unreadable and its sentinel remains unchanged;
+- the onboarding and hosted-login wall are absent;
+- the real `agent-exec` and local-agent runtime extensions activate;
+- authenticated `GET /models` reaches the loopback gateway;
+- the tenant catalog is reconciled into Cursor's named-model picker without
+  overwriting non-Impel model preferences;
+- a real Agent submission sends `model: "default"` to Chat Completions with
+  the tenant bearer;
+- the unique streamed gateway result is rendered in the Agent UI;
+- no personal provider credential or native profile is used.
+
+The direct runtime contract separately proves model discovery and a Responses
+stream with the intended model and bearer.
+
+The gateway conversion contract separately pins tool-call IDs across the next
+turn's tool result, fragmented parallel argument streams, reasoning deltas,
+`tool_calls` termination, vision input, and `store:false` after conversion.
+
+| Cursor surface | Managed local mode |
+| --- | --- |
+| Editor, terminal, source control, extensions | Retained with tenant-isolated state |
+| Agent chat, edits, terminal tools, MCP | Works through the Impel gateway |
+| Streaming, reasoning, vision, tool calls | Preserved by Cursor and Bifrost's typed conversion |
+| Model selection | Gateway owns `default`; concrete tenant models are projected into Cursor's named-model picker |
+| Tab completion | Unavailable; Cursor disables CPP/Tab in local mode |
+| Cloud Background Agents | Unavailable; hosted Cursor service |
+| Shared chats/canvases, Bugbot, code tour | Unavailable; hosted Cursor services |
+| Server-side repository indexing/search | Unavailable; hosted Cursor service |
+
+This provides direct Impel inference for the local Agent with normal Cursor
+editor updates. It cannot provide complete hosted-Cursor parity because Tab,
+cloud agents, collaboration, Bugbot, and hosted indexing use unpublished
+Cursor services rather than the bundled local-provider protocol. The app may
+still contact Cursor domains for updates, extensions, and unavailable hosted
+features; model inference is the gateway-owned boundary.
+
+The tenant gateway bearer is process-scoped because Cursor's current local
+provider contract resolves it from the launch environment. Treat extensions
+installed into this isolated Cursor profile as trusted: a same-user extension
+or process can inspect or reuse that gateway-only bearer. A short-lived,
+route-bound desktop capability would be a future hardening, but it is not part
+of the current PAT contract.
+
+## Validation
+
+The ordinary suite uses fake bundles and credentials. Validate the installed
+stable bundle and the direct local-provider transport with:
+
+```sh
+IMPEL_VALIDATE_INSTALLED_CURSOR_LOCAL=1 node --test --test-name-pattern='installed stable Cursor' test/cursor-local.test.js
+```
+
+The packaged GUI battle test uses only a disposable HOME, user-data directory,
+extension directory, workspace, process-lifetime secret store, loopback HTTP
+server, and loopback debugger:
+
+```sh
+IMPEL_VALIDATE_INSTALLED_CURSOR_GUI=1 node --test --test-name-pattern='managed Cursor GUI' test/cursor-local.test.js
+```
+
+Neither test reads or writes the operator's native Cursor profile or uses live
+provider credentials.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.18.15",
+  "version": "0.18.16",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {
@@ -12,6 +12,7 @@
   },
   "files": [
     "bin",
+    "docs/experimental-managed-cursor.md",
     "src",
     "README.md"
   ],