Release 0.2.1: shared native harness lifecycle and reliability fixes

.claude-plugin/marketplace.json

@@ -5,43 +5,43 @@
   },
   "metadata": {
     "description": "Choose the model providers to use inside Claude Code.",
-    "version": "0.2.0"
+    "version": "0.2.1"
   },
   "plugins": [
     {
       "name": "multi-core",
       "source": "./",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "Shared Multi gateway, setup, status and reversible Claude startup integration."
     },
     {
       "name": "multi-openai",
       "source": "./plugins/multi-openai",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "ChatGPT models through Codex login"
     },
     {
       "name": "multi-cursor",
       "source": "./plugins/multi-cursor",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "Official Cursor SDK coding harness"
     },
     {
       "name": "multi-zen",
       "source": "./plugins/multi-zen",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "OpenCode Zen direct API models"
     },
     {
       "name": "multi-antigravity",
       "source": "./plugins/multi-antigravity",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "Official Antigravity CLI harness"
     },
     {
       "name": "multi-grok",
       "source": "./plugins/multi-grok",
-      "version": "0.2.0",
+      "version": "0.2.1",
       "description": "Official Grok Build CLI harness"
     }
   ]

.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.2.1",
   "author": {
     "name": "greenpolo",
     "url": "https://github.com/greenpolo"

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -20,6 +20,7 @@ body:
         - Cursor SDK
         - OpenCode Zen
         - Antigravity CLI
+        - Grok Build CLI
         - Claude passthrough
         - Gateway / model picker / workers
         - Other

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -6,7 +6,7 @@ body:
     attributes:
       value: |
         Use this template for a provider integration, model/worker choice, permission mapping, or session improvement.
-        Current integrations are OpenAI, Cursor, OpenCode Zen, and Antigravity.
+        Current integrations are OpenAI, Cursor, OpenCode Zen, Antigravity, and Grok Build.
         Describe the execution route you need: Claude-executed tools or the provider's native harness.
 
   - type: textarea

AGENTS.md

@@ -7,6 +7,8 @@ and provider details live in [docs/installation.md](docs/installation.md),
 [docs/openai.md](docs/openai.md), [docs/cursor.md](docs/cursor.md),
 [docs/zen.md](docs/zen.md), [docs/antigravity.md](docs/antigravity.md), [docs/grok.md](docs/grok.md),
 [docs/permissions.md](docs/permissions.md), and [docs/platform-support.md](docs/platform-support.md).
+Claude Code function-hook UI and extensibility rules live in
+[docs/claude-mods.md](docs/claude-mods.md).
 `.agent/` is gitignored scratch space. It is never authoritative.
 
 ## Code map
@@ -21,6 +23,7 @@ and provider details live in [docs/installation.md](docs/installation.md),
 | `plugins/multi-core/src/gateway/cursor-settings.ts`, `mode-hook.ts`, `agent-definitions.ts` | Admits settings and maps prompt and worker permissions. |
 | `plugins/multi-core/src/gateway/approval.ts`, `permission-hook.ts` | Approval protocol and capability checks. |
 | `plugins/multi-core/src/gateway/mod-*.ts`, `tool-observer.ts` | Claude Mods control-plane routes, compaction, policy, and progress observation. |
+| `plugins/multi-core/src/gateway/harness-*.ts` | Session store, exchange registry, response builder, completion, and notices shared by Cursor, Antigravity, and Grok; CLI process runner and text prompt preparation shared by Antigravity and Grok. |
 | `plugins/multi-core/src/account.ts`, `setup.ts`, `install/` | Accounts, bootstrap, plugin discovery, and installation. |
 | `plugins/multi-openai/src/` | Codex authentication, models, Responses translation, instructions, and reviewer. |
 | `plugins/multi-cursor/src/` | Cursor SDK harness, permissions, progress, requests, models, and workspaces. |
@@ -34,11 +37,15 @@ and provider details live in [docs/installation.md](docs/installation.md),
 | `package.json`, `biome.json`, `knip.json` | Scripts, lint rules, and entry/project analysis. |
 
 Keep provider authentication and catalogs in provider folders. Keep shared protocol
-types and cross-provider helpers in `plugins/multi-core/src/gateway/`. Import
-concrete modules directly. Do not add barrel re-exports. Platform-dependent code
+types and cross-provider helpers in `plugins/multi-core/src/gateway/`. Prefer
+direct module imports, the existing repository convention. Platform-dependent code
 accepts an explicit `platform` option so every branch is unit-testable on Linux.
 
-## Product rules
+## Current execution contracts
+
+These describe the implemented provider boundaries to preserve during ordinary
+changes. Provider limitations are not permanent bans on requested new features;
+changes to those boundaries need corresponding implementation and verification.
 
 - Claude's permission mode controls every provider at prompt boundaries.
 - Each provider owns its login, reviewer, execution state, and credentials.
@@ -49,22 +56,33 @@ accepts an explicit `platform` option so every branch is unit-testable on Linux.
 - New bridges isolate session, worker, provider, and workspace state.
 - Do not use Cursor Fast in development or live tests; set `fast:false` explicitly.
 - Keep paid probes bounded and reuse existing usage records when possible.
-- Do not spawn fleets of Claude agents for implementation or validation.
+
+## Claude Code extensibility requirement
+
+Use Claude Mods function hooks for Claude Code harness UI or extensibility changes,
+as explicitly requested by the maintainer. Read [docs/claude-mods.md](docs/claude-mods.md)
+before changing that surface. Reuse the authenticated `/multi/mod/*` control plane
+when gateway data or actions are needed; local rendering changes need no new route.
 
 ## Verification
 
 Run `npm run check`. It checks the generated banner, Biome lint, Knip, strict
 type checking, and offline tests. `npm test` runs `tsc --noEmit` and the unit
 test suite. Use Node 24.12 or newer and avoid `DEP0190` warnings.
 
+For Claude Mods hook or surface changes, also run `npm run test:mod`. It runs
+`claude plugin test` with the installed Claude executable, without provider
+inference. It is separate from `npm run check` and the current CI matrix.
+
 | Command | Check | Login needed |
 | --- | --- | --- |
-| `npm run test:live:compaction` | Native compaction | Claude |
+| `npm run test:live:compaction` | Claude/OpenAI compaction and resume | Claude and Codex login |
 | `npm run test:live:zen` | Zen tools, cache, and resume | Zen API key |
 | `npm run test:live:cursor` | Cursor SDK tools, continuation, and disk resume | Cursor SDK login |
+| `npm run test:live:openai-instructions` | Requested planning/delegation and Plan restrictions (three-request budget) | Codex login |
 | `npm run test:live:auto-mode` | Native Auto mode | Provider login under test |
 | `npm run test:live:provider-approval` | Provider approval | Provider login under test |
-| `npm run test:live:reviewer` | Reviewer ownership | OpenAI/Cursor login as applicable |
+| `npm run test:live:reviewer` | OpenAI reviewer allow/deny and inspection | Codex login |
 | `npm run test:live:approval-worker` | Worker approval | Provider login under test |
 | `npm run test:live:permissions` | Native permissions | Claude and provider login |
 | `npm run test:live:antigravity` | Antigravity CLI harness | `agy` login |

ARCHITECTURE.md

@@ -12,7 +12,8 @@ The plugin puts external models and coding harnesses inside one Claude Code
 session. The launcher registers provider models and named workers. The Node
 gateway routes requests, preserves Claude passthrough, and coordinates sessions.
 Claude Mods provide the in-engine control plane for model rows, worker rows,
-permission state, progress, and compaction. Provider adapters own their model
+permission state, progress, and compaction. [The local Mods reference](docs/claude-mods.md)
+is required reading for changes to Claude Code UI or extensibility. Provider adapters own their model
 catalogs, authentication, execution, and review boundaries.
 
 ```text
@@ -47,7 +48,7 @@ time, streamed progress, completion, failure, and cancellation.
 
 OpenAI and Zen are direct model integrations. Their worker hooks record prompt
 identity and let Claude Code run the tool loop. Full settings translation runs
-at Cursor and Antigravity prompts, or when a direct-model conversation requests
+at Cursor, Antigravity, and Grok prompts, or when a direct-model conversation requests
 a harness worker. OpenAI
 review stays with the originating OpenAI account. Zen never borrows Codex
 review. Missing GPT review fails explicitly.
@@ -60,6 +61,18 @@ with Claude policy enforcement at the prompt boundary. Grok carries the same
 policy in its own run arguments, and each announced toolset is checked against
 it because an unknown removal is accepted and ignored by that CLI.
 
+All three harnesses share their session store, in-flight exchange registry,
+response builder, durable completion, and notices from
+`plugins/multi-core/src/gateway/harness-*.ts`. Grok and Antigravity additionally
+share native process execution and text prompt preparation; Cursor retains its
+SDK and image-aware prompt format. Each provider still owns
+its own event grammar, CLI argument construction, usage accounting, and (for
+Cursor) SDK agent lifecycle. The shared layer owns turn leases, lock lifetime,
+archival before subsequent dispatch, and durable completion before terminal
+events. Identical in-flight requests observe the existing exchange. A different
+request for the same busy identity is refused with a deterministic 400, rather
+than queued against a native conversation that has moved on.
+
 ## Permissions
 
 Claude's permission mode controls each provider at prompt boundaries through the
@@ -71,7 +84,9 @@ Auto review while retaining explicit restrictions. See [docs/permissions.md](doc
 
 Native harness actions do not enter Claude's PreToolUse or PermissionRequest
 admission path. Their worker admission loads the selected settings and managed
-policy sources, while those hooks observe native activity. Antigravity native
+policy sources. Provider SDK/CLI events supply progress and action observations
+for display through Claude Mods; Claude's classic tool hooks do not observe each
+native action. Antigravity native
 children and MCP stay denied. Grok denies native subagents and MCP execution by
 rule, and its announced toolset is verified because that CLI accepts an unknown
 removal silently; its MCP tools stay visible to the model and are documented as
@@ -87,7 +102,10 @@ switches.
 Every run isolates Claude session, worker, provider, and workspace identity.
 Provider credentials and review contexts remain separate. Claude subscription
 passthrough remains available; the plugin has no Claude token pool. External
-operations retain external permissions.
+operations retain external permissions. Each harness's `HarnessSessionStore`
+keys its on-disk record on the provider-supplied identity, so session,
+worker, provider, and workspace isolation holds at the shared-module layer as
+well as in each provider's own state.
 
 ## State
 
@@ -96,20 +114,61 @@ run IDs support terminal-result recovery. A recoverable run resumes its native
 record; an uncertain run does not rerun actions blindly. Claude, OpenAI, and Zen
 conversations use Claude Code's compaction without Multi's harness checks;
 Cursor, Antigravity and Grok compaction remains provider-owned and policy-bound. Follow-ups forward the
-newest turn after the last assistant response. Outer history changes continue
-only with a matching prompt hash or unique saved-response anchor. Native state is
-never rewound. Compaction summarizes authenticated context while preserving the
+newest turn after the last assistant response. If outer history no longer contains
+the saved response, the harness emits a notice and continues on its native record;
+it does not require a matching prompt hash or unique response anchor. Native state
+is never rewound. Compaction summarizes authenticated context while preserving the
 native record. Cache reuse and usage accounting remain provider-owned.
 
+`HarnessSessionStore` (`gateway/harness-session.ts`) owns the loading gate,
+record validation, and lock lifetime. Persisted `saved` fields are separate from
+live `runtime` attachments; SDK handles cannot enter a saved record accidentally.
+`acquireLease` holds the identity through replay, recovery, and dispatch. Releasing
+the lease ends the turn; shutdown releases idle records and leaves busy locks
+owned until their leases finish. `loadOnly` uses the same loading gate and rejects
+busy records. Every harness maps `HarnessBusyError` to a deterministic 400.
+
+`ExchangeRegistry` (`gateway/harness-exchange.ts`) lets identical requests observe
+one native run before a second lease is attempted. Its typed metadata remains
+provider-owned. `harness-completion.ts` archives a previous reply before the next
+native dispatch can replace it, then commits the new response and replay events
+in one atomic session write before emitting terminal events. Provider usage and
+native recovery decisions stay in the adapters.
+
+Cursor upgrades preserve v2 native agents and pending run IDs. The store holds
+both the old filename's lock and the current v3 filename's lock while migrating
+and using a record. Existing v3 state takes precedence when both records identify
+the same agent; conflicting native identities fail explicitly. The original v2
+file is preserved. Cursor's 32-agent budget counts attached SDK handles and
+in-flight attachment reservations, not disk-only replay records. Eviction closes
+an idle SDK handle while retaining its native identity for later resume.
+Handles with an in-flight billed usage query are not evicted. A detached SDK
+record's `running` status is not a live ownership claim: the existing interrupted
+continuation notice remains the fallback when no terminal result can be recovered.
+
+Replay validation is provider-parameterized: Cursor's replies may carry the
+display-only `tool_use` blocks a Claude Mods row produces, while Grok and
+Antigravity stay text-only. `gateway/conversation.ts` normalizes Messages content
+and media for Cursor and OpenAI without coupling Cursor to OpenAI request
+construction; provider-specific reasoning decoding stays with OpenAI.
+
 ## Platform layer
 
 The process tree tracks and cancels child processes. Executable resolution selects
 platform-appropriate commands. Managed-policy sources are admitted per platform.
 Atomic writes protect settings and state. Install shims bootstrap the real Claude
-executable and preserve its arguments. Linux, WSL, macOS, and Windows support is
+executable and preserve its arguments. Grok and Antigravity spawn their native
+CLI through the shared `runNativeCli` process runner
+(`gateway/harness-process.ts`), which owns the spawn/kill/timeout cascade,
+stdout/stderr capture, and cancellation plumbing; each provider still supplies
+its own argument construction, event grammar, and environment allowlist.
+Linux, WSL, macOS, and Windows support is
 described in [docs/platform-support.md](docs/platform-support.md).
 
-## Design rules
+## Current design contracts
+
+These summarize the current architecture, not permanent restrictions on future
+features requested by the maintainer.
 
 - Keep authentication, model catalogs, review, and native state with each provider.
 - Keep shared Claude protocol types and cross-provider helpers in `gateway/`.