subharness 0.0.4 → 0.0.5

package/sdk/cli/index.md

@@ -46,7 +46,7 @@ subharness / trenton
   ◌ claude  Review the current diff     waiting    00:38
 ```
 
-The harness label is `codex`, `claude`, or `fx`. A direct target is known during startup; a specialist displays `pending` until its actual native harness is selected. Selection reports the successfully opened harness, including fallback selection. The title is the first nonempty line of the current task's original prompt, with whitespace normalized and terminal control sequences removed, bounded to 120 Unicode code points before fitting it to the display. An empty sanitized title is `(untitled)`. No model call generates titles. Steering retains the task title; a follow-up uses its own prompt.
+The harness label is `codex`, `claude`, `fx`, `opencode`, `copilot`, or `cursor`. A direct target is known during startup; a specialist displays `pending` until its actual native harness is selected. Selection reports the successfully opened harness, including fallback selection. The title is the first nonempty line of the current task's original prompt, with whitespace normalized and terminal control sequences removed, bounded to 120 Unicode code points before fitting it to the display. An empty sanitized title is `(untitled)`. No model call generates titles. Steering retains the task title; a follow-up uses its own prompt.
 
 Time is elapsed wall time since that task first dispatched, including waiting and recovery. A queued task shows `00:00`. Completed, cancelled, and interrupted tasks freeze their elapsed time when that outcome is reached. Failed tasks freeze their elapsed time at failure and resume counting from the original start if explicitly recovered. Tasks cancelled before first dispatch show `00:00`. Repeated observation or cancellation that leaves a settled terminal outcome unchanged does not change its recorded finish time. If stopping previously unconfirmed execution reaches a new outcome, timing records that new outcome. Durations use `MM:SS` below one hour and `H:MM:SS` thereafter. State and elapsed time occupy separate aligned columns. Finished rows include completion age when space permits, as defined in [Dashboard presentation](dashboard-design.md). Narrow terminals truncate titles by display width without splitting grapheme clusters; when the fixed fields alone do not fit, the row is clipped to the available columns.
 
@@ -58,25 +58,28 @@ The command requires terminal stdout and a terminal supporting cursor control; n
 
 ## Direct harnesses and specialists
 
-`codex`, `claude`, and `fx` are reserved, case-sensitive target names for direct harness execution. `claude` selects the Claude Code adapter, whose SDK and access configuration key remains `claudeCode`. Direct execution needs an installed native harness and eligible access, but no TypeScript definition, project-local SDK import, or agent catalog evaluation. An invalid specialist file does not block a direct harness run.
+`codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` are reserved, case-sensitive target names for direct harness execution. `claude` selects the Claude Code adapter, whose SDK and access configuration key remains `claudeCode`. Direct execution needs its native runtime and eligible access, but no TypeScript definition, project-local SDK import, or agent catalog evaluation. An invalid specialist file does not block a direct harness run.
 
 ```sh
 subharness run claude "Review the current diff."
 subharness run codex --cwd ../feature-worktree "Implement the documented validation."
 subharness run fx --model "provider/model" "Compare the proposed implementations."
+subharness run opencode --model "creator/model" "Inspect the current implementation."
+subharness run copilot --model "creator/model" "Review the current diff."
+subharness run cursor --model "CURSOR_MODEL_ID" "Implement the documented change."
 subharness run repo:reviewer "Review the current diff."
 subharness check repo:reviewer --format jsonl
 ```
 
-Replace `provider/model` with an available Gateway model identifier. Nonreserved bare names retain the existing unambiguous specialist lookup. Qualified `repo:`, `global:`, and `subagent:` names retain their existing meanings. A specialist named `claude`, `codex`, or `fx` requires its scope qualifier; it never shadows the built-in target. Unknown targets fail rather than being executed as arbitrary commands. Omitting the target is an argument error; the CLI never chooses the first installed harness.
+Replace `provider/model` or `creator/model` with an available Gateway model identifier. Nonreserved bare names retain the existing unambiguous specialist lookup. Qualified `repo:`, `global:`, and `subagent:` names retain their existing meanings. A specialist named for any reserved harness target requires its scope qualifier; it never shadows the built-in target. Unknown targets fail rather than being executed as arbitrary commands. Omitting the target is an argument error; the CLI never chooses the first installed harness.
 
 Direct harness sessions use native instructions and project context without adding a specialist role, custom tools, or declared children. They preserve the existing authentication, native permission, queue, cancellation, follow-up, and response contracts. They do not broaden the caller's native permissions or automatically authorize additional delegation.
 
-`--model` and `--effort` configure direct harness targets only for `run` and `check`, and can be combined with `--cwd` and, for `run`, any supported prompt source. Empty values are errors. Specialist targets reject these overrides and retain their declared harness configurations. `send` retains the session configuration and does not accept model or effort overrides.
+`--model` configures direct harness targets only for `run` and `check`, and can be combined with `--cwd` and, for `run`, any supported prompt source. `--effort` is additionally available for Codex, Claude Code, and fx. Empty values are errors. Specialist targets reject these overrides and retain their declared harness configurations. `send` retains the session configuration and does not accept model or effort overrides.
 
-Omitting `--model` requests the native default for the authorized access route at session creation. The adapter retains the selected model for that conversation. It does not inherit the calling agent's model, rank models, choose a substitute, or change billing routes. An unavailable or unverifiable native default fails with actionable guidance to supply `--model`; it does not submit a prompt merely to discover a default. Explicit model identifiers retain native validation and substitution checks. TypeScript harness constructors continue to require a model.
+For Codex, Claude Code, and fx, omitting `--model` requests the native default for the authorized access route at session creation. OpenCode, Copilot, and Cursor require an explicit `--model`; omission fails with `INVALID_CONFIG` and guidance before native startup. The adapter retains the selected model for that conversation. It does not inherit the calling agent's model, rank models, choose a substitute, or change billing routes. An unavailable or unverifiable native default fails with actionable guidance to supply `--model`; it does not submit a prompt merely to discover a default. Explicit model identifiers retain native validation and substitution checks. TypeScript harness constructors continue to require a model.
 
-Effort is harness-specific: Codex and fx accept native effort identifiers, while Claude Code accepts `low`, `medium`, `high`, `xhigh`, or `max`. Explicit effort must be compatible with the selected model where native capabilities expose that validation. An omitted effort retains the native default at session creation. Detected changes to an explicit request are errors. Codex and Claude Code retain standard-speed execution; this interface adds no fast-mode flag. fx retains its documented native preference and Gateway access contract.
+Effort is harness-specific: Codex and fx accept native effort identifiers, while Claude Code accepts `low`, `medium`, `high`, `xhigh`, or `max`. OpenCode, Copilot, and Cursor reject `--effort`. Explicit effort must be compatible with the selected model where native capabilities expose that validation. An omitted effort retains the native default at session creation. Detected changes to an explicit request are errors. Codex and Claude Code retain standard-speed execution; this interface adds no fast-mode flag. fx retains its documented native preference and Gateway access contract.
 
 Direct-harness help for `run` and `check` describes the relevant options and access requirements without loading definitions, starting a coordinator, or invoking a harness. Native CLI flags are not forwarded. Unsupported flags are errors.
 

package/sdk/cli/output.md

@@ -1,5 +1,7 @@
 # CLI Output
 
+[Error diagnostics](../diagnostics.md) defines safe process and coordinator communication details. These details enrich message text without changing the error record shape or command exit-code rules.
+
 `dashboard` is a terminal-only live view, not an execution-record command. It accepts no `--format` option and emits no text/JSONL records on success. Its rows, empty state, and terminal lifecycle are defined in the [CLI contract](index.md#live-dashboard).
 
 Execution commands accept `--format text|jsonl`; `text` is the default. Both formats report the same operations. JSONL contains complete records separated by newlines, never native token streams or tool transcripts. All records include `version: 1` and a `type` discriminator. Identifiers are opaque strings prefixed with `ses_`, `tsk_`, `rsp_`, or `req_` and are not paths or process identifiers.
@@ -33,7 +35,7 @@ The identifiers above are illustrative. A `response` contains `sessionId`, `task
 
 `status` emits a `status` record with `sessionId`, `taskId`, `state`, and optional `response` and `error`. The response preview contains `responseId`, `text`, and `truncated`; at most 4,000 text characters are included. `subharness status <task-id> --full` returns the complete latest response instead. `subharness wait <task-id>` returns or awaits the first retained response; adding `--after <response-id>` returns or awaits the next response after that cursor.
 
-`list` emits an `agents` record with an `agents` array of `{ id, name, description, scope }`, where scope is `harness`, `repo`, `global`, or `subagent`. The built-in entries have IDs and names `codex`, `claude`, and `fx`, and scope `harness`; they appear in that order before discovered specialists. They describe supported targets, not verified executable, authentication, or model availability. A managed parent's catalog includes its declared `subagent:` entries; generic parents have no declared children. `queue` emits a `queue` record with `sessionId`, `paused`, optional `active`, and a `tasks` array in pending order. Task summaries contain `taskId`, `state`, and a prompt `description` limited to 120 characters.
+`list` emits an `agents` record with an `agents` array of `{ id, name, description, scope }`, where scope is `harness`, `repo`, `global`, or `subagent`. The built-in entries have IDs and names `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor`, and scope `harness`; they appear in that order before discovered specialists. They describe supported targets, not verified executable, authentication, or model availability. A managed parent's catalog includes its declared `subagent:` entries; generic parents have no declared children. `queue` emits a `queue` record with `sessionId`, `paused`, optional `active`, and a `tasks` array in pending order. Task summaries contain `taskId`, `state`, and a prompt `description` limited to 120 characters.
 
 An `accepted` record contains `sessionId`, `taskId`, `delivery: "steer"`. A successful `cancel` emits a `cancelled` record with the targeted task identity and final state, after affected native execution has stopped. Already-terminal tasks retain their existing state. `resume` emits `started` for the existing task with `resumed: true`, then its next response or terminal outcome.
 

package/sdk/config.md

@@ -39,7 +39,7 @@ The former `.agents/agents/` directory is not read. Definitions moved to `.subha
 
 Discovery is required for listing and repository/global specialist lookup. Direct harness execution skips it. Declared-child execution loads only the parent's source and direct child map; unrelated catalog entries are not dependencies of a `subagent:` invocation.
 
-The declared name determines identity. Duplicate names in the same scope are errors. `repo:reviewer` and `global:reviewer` remain distinct; bare `reviewer` is accepted only when unambiguous. The reserved CLI targets `codex`, `claude`, and `fx` always select native harnesses. Specialists with those names require a `repo:` or `global:` qualifier. Direct harness runs bypass definition discovery entirely, including invalid definition files. Global definitions can execute in any caller-supplied directory. Global and repository files resolve their own imports through normal Node package resolution.
+The declared name determines identity. Duplicate names in the same scope are errors. `repo:reviewer` and `global:reviewer` remain distinct; bare `reviewer` is accepted only when unambiguous. The reserved CLI targets `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` always select native harnesses. Specialists with those names require a `repo:` or `global:` qualifier. Direct harness runs bypass definition discovery entirely, including invalid definition files. Global definitions can execute in any caller-supplied directory. Global and repository files resolve their own imports through normal Node package resolution.
 
 ```sh
 subharness list --cwd /repo/worktree

package/sdk/copilot.md

@@ -0,0 +1,53 @@
+# GitHub Copilot adapter
+
+The Copilot adapter uses the native GitHub Copilot SDK over a dedicated stdio runtime process. The pinned SDK is `@github/copilot-sdk` 1.0.14, with native protocol version 3 as exposed by Copilot runtime 1.0.85. It does not implement a model loop. The public model-only configuration and access routes are defined in [additional harnesses](additional-harnesses.md).
+
+## Native GitHub access
+
+An explicit `subscription` connection uses the native Copilot or GitHub CLI login. An `api-key` connection with `provider: "github"` instead reads the selected GitHub token, defaulting to `COPILOT_GITHUB_TOKEN`. The token must be eligible for Copilot; its presence alone does not prove entitlement. Neither route uses BYOK or Vercel Gateway.
+
+The adapter removes competing ambient tokens and provider overrides. Saved-login access enables native logged-in-user discovery without passing a token; explicit GitHub access supplies the selected `gitHubToken` to the SDK client and session and disables logged-in-user fallback. Startup checks native authentication status and exact native model-catalog membership without generation. Saved-user or GitHub CLI authentication must not be confused with an environment token. Unknown authentication metadata and route changes fail explicitly. Auto-routing models are not accepted. Native login and refresh remain the harness's responsibility. Saved-login access preserves the native Copilot home so last-user metadata, keychain credentials, file-backed credentials, and GitHub CLI discovery remain native. Each session still uses a private `configDirectory` with configuration discovery disabled. Explicit GitHub-token, BYOK, and Gateway routes use a private runtime base directory as well. Subharness never reads or copies native credentials or imports personal provider/model configuration. Cleanup removes only adapter-owned private state. This preserves the existing manual approval and managed-policy behavior; it does not import personal permission configuration.
+
+## Direct provider API keys
+
+Copilot BYOK connections use `type: "api-key"` with `provider: "openai"`, `"anthropic"`, or `"azure"`. The selected variable defaults to `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `AZURE_OPENAI_API_KEY`, respectively; `env` and `envFile` can select another source. These routes disable GitHub login and configure one singular native provider, so requests use the chosen provider's billing.
+
+```json
+{
+  "access": {
+    "copilot": [{ "type": "api-key", "provider": "openai", "wireApi": "responses" }]
+  }
+}
+```
+
+OpenAI defaults to `https://api.openai.com/v1`, and Anthropic defaults to `https://api.anthropic.com`. `baseUrl` can select another compatible endpoint; Azure requires it and expects its native resource/project URL. OpenAI-compatible services use `provider: "openai"` and their full API prefix. OpenAI/Azure accept `wireApi: "completions" | "responses"`, defaulting to `completions`; Anthropic uses Messages and rejects `wireApi`. Azure alone accepts `apiVersion`, passed to the SDK's native Azure option. HTTP transport is used.
+
+The agent's `model` is the native behavior model. Optional `wireModel` supplies a different remote model or Azure deployment name; omission uses the agent model on the wire too. The adapter passes these explicit values without inventing aliases. Readiness verifies the native model and configured provider/endpoint/credential representation. A BYOK assistant response can label its model with the remote name or deployment; native model RPC readback remains the authority for the pinned behavior model. BYOK has no universal remote catalog check: readiness does not prove a remote model exists or that a key has quota. Neither configured readback nor a user-supplied endpoint proves the remotely executed model.
+
+Custom headers, bearer-token callbacks, experimental mixed-provider sessions, and provider options outside the documented access shape are not exposed. Gateway connections remain a separate supported route with their existing fixed endpoint and `creator/model` names.
+
+## Gateway access
+
+The adapter accepts explicit Gateway API-key or project OIDC connections. It configures a single native OpenAI-compatible provider with the fixed base URL `https://ai-gateway.vercel.sh/coding-agent/v1`, HTTP Chat Completions, and the exact requested `creator/model` identifier. API-key access supplies the selected API key; OIDC uses bearer-token authentication. GitHub login and unrelated provider credentials are disabled for this inference route. Ambient `COPILOT_PROVIDER_*` settings, model preferences, alternate endpoints, and native logged-in-user discovery must not override it.
+
+A dedicated private native configuration/state directory prevents stored provider settings or plugins from changing billing. Native repository instructions and the caller's working directory remain available. Credentials are passed through the private SDK/protocol configuration, never process arguments or user-visible diagnostics. Startup uses the native protocol handshake, session creation, current-model and provider-endpoint introspection to verify the selection without submitting a prompt. The native allowed model list is restricted to the selected identifier. Unverifiable or changed selection is an explicit configuration error, not an access fallback.
+
+The SDK's bundled runtime may be used; a separate global Copilot installation is not required when that runtime is available. Missing or incompatible runtime support is `HARNESS_UNAVAILABLE`. `check copilot --model creator/model` checks startup and cleanup only, not remote allowance.
+
+## Tools and approvals
+
+Declared tools use native SDK tool callbacks and preserve validated text/image results. Copilot's result envelope groups text and images separately: text blocks are joined in order, and images retain their relative order as binary image results. Interleaving between those groups is not representable. Specialist instructions supplement the native system instructions; they never replace the harness's tool loop. Tool names retain their definition keys; a collision with a native built-in tool is an explicit configuration error, never an override. Callbacks are admitted only while a task is active, and interruption/close drain already-admitted callbacks.
+
+The adapter uses the native manual permission mode and forwards supported active permission requests through the shared approval flow. Only the specific offered once/deny decisions are exposed initially; it does not invent persistent permission grants. The action context is bounded and excludes credential-bearing configuration. Unsupported input or startup requests fail with `INPUT_REQUIRED` and stop affected work. No callback automatically approves native commands or expands native permissions for declared children.
+
+Enterprise managed-policy self-fetch is enabled for explicit GitHub-token access, which supplies the session identity required by the SDK. Saved-login, BYOK, and Gateway routes omit that opt-in because they do not supply a session GitHub token; the adapter does not extract one or promise enterprise policy self-fetch for those routes. Native manual approval requirements remain enabled on every route. A permission request that specifically requires human-only provenance or an unrepresentable sandbox bypass is unsupported and fails with `INPUT_REQUIRED`; a Subharness caller response must not be relabeled as a verified human decision. Requests already resolved by native hooks are not presented as new approval requests. Native withdrawal retires the matching request and late answers are ignored.
+
+## Lifecycle
+
+Follow-ups reuse the native session. Events are correlated to the active turn; a final assistant message alone is not successful completion. A session-idle event is accepted in any native session mode after evidence that the submitted turn started, and only when no native work remains. A stale idle event cannot complete a newly submitted task. The adapter reports native shutdown or transport loss as an execution failure and limits final response text to 1 MiB. Model or endpoint substitutions fail without replay. Turn completion withdraws remaining approval requests.
+
+Interruption stops tool admission, withdraws pending approvals, requests native abort, confirms no native work remains, and waits for admitted callbacks. An abort acknowledgement alone does not prove the native process stopped. Native cancellation requests and status checks are bounded; a cancellation that cannot establish idle/termination returns `CANCELLATION_FAILED`. Already-admitted host callbacks are drained without imposing that native cancellation deadline on their execution. Steering uses the coordinator's interrupt behavior, and prompt-free recovery returns `RECOVERY_UNSUPPORTED`.
+
+An unconfirmed interruption fails the active turn and prevents further tasks in that session. Tool admission remains closed, and close must still attempt native cleanup. The turn cannot later report success after continuing with disabled tool callbacks. This rule also applies while native prompt admission is pending.
+
+Close retires the session, shuts down the dedicated native runtime, confirms termination, drains tools, and removes private state. Cleanup RPCs are bounded so an unresponsive session cannot prevent process shutdown attempts. Escalated termination without confirmed exit produces `CANCELLATION_FAILED`, never successful cleanup. Startup failure also cleans up. A successful readiness record requires completed runtime cleanup. Raw SDK errors and process output are replaced with fixed diagnostics so credentials do not enter CLI records.

package/sdk/cursor.md

@@ -0,0 +1,68 @@
+# Cursor adapter
+
+The Cursor adapter runs the native Cursor CLI for subscription access and the native Cursor TypeScript SDK for explicit API-key access against the caller's local working directory. Cursor owns inference, tools, conversation state, and context management. Cloud agents are not part of this adapter.
+
+## Configuration
+
+```ts
+import { cursor } from "subharness";
+
+cursor({ model: "CURSOR_MODEL_ID", sandboxMode: "enabled" });
+
+interface CursorOptions {
+  readonly model: string;
+  readonly sandboxMode?: "enabled" | "disabled";
+}
+
+interface CursorConfig extends CursorOptions {
+  readonly kind: "cursor";
+}
+```
+
+The constructor returns an immutable configuration. Model is required and must be nonempty. Unknown options, including `fast` and `effort`, are rejected. For API-key access, `sandboxMode` maps to the native SDK's local sandbox option. Omission preserves the SDK default, which runs local tools without interactive approval and without a sandbox. The native sandbox, when enabled, restricts shell writes and network access according to Cursor's native policy; it is not a sandbox for host-side custom tool callbacks. The adapter never enables broader permissions to make declared-child launches succeed.
+
+The CLI target is `cursor`. `run cursor` and `check cursor` require `--model`. The following catalog behavior applies to API-key access; subscription model selection is defined below. The native routing IDs `auto` and `auto-smart`, including catalog aliases that resolve to either ID, are rejected because they do not retain a concrete model. The catalog has no generic router flag; the adapter does not infer routing from display names or invent additional reserved IDs. `--effort` is unsupported for this adapter. Native model aliases are accepted only when the account catalog supplies their mapping. Startup verifies the account and selected model through the native SDK without a generation, creates an empty local agent, and pins the resolved selection for follow-ups. When terminal results report a model, a detected replacement fails explicitly without replay. The agent handle's configured model is not evidence of the model that executed a run.
+
+## Access
+
+Personal access uses the `cursor` key and requires an explicit connection. A `subscription` connection uses the current native Cursor CLI login; the user completes `cursor-agent login` outside Subharness. An `api-key` connection uses the SDK and defaults to `CURSOR_API_KEY`. Both environment and explicit dotenv references follow the shared [access contract](access-config.md). Omission does not discover or enable a connection, and an empty list disables Cursor. Native login and API-key access are separate billing routes; neither is an implicit fallback for the other. Vercel API-key and OIDC connections are unsupported and fail with `UNSUPPORTED_OPTION` before startup. A Cursor API key is a Cursor billing route, not a Gateway credential.
+
+```json
+{
+  "access": {
+    "cursor": [{ "type": "subscription" }]
+  }
+}
+```
+
+For API-key access, the selected key is passed explicitly to the SDK. Subscription access delegates credential discovery to the native CLI; Subharness never reads, copies, or transfers its saved tokens. A missing or expired native login fails with `ACCESS_UNAVAILABLE` and login guidance before submission. Subharness does not open a browser or perform an interactive login. Explicit API-key/auth-token environment variables must not silently override a subscription connection. Backend or website endpoint overrides through `CURSOR_BACKEND_URL` or `CURSOR_WEBSITE_URL` are rejected before the key is used. This also applies to the SDK host environment, because the SDK reads process-level settings. The adapter does not transfer subscription tokens, change account-synced provider settings, or treat the editor's custom-provider configuration as verified Gateway routing. Credentials and raw native errors must not appear in diagnostics.
+
+## API-key session behavior
+
+Successive tasks use the same native agent. Specialist instructions supplement the native harness instructions in the first user turn; they do not replace Cursor's system prompt. Declared tools use native SDK custom tools, validate inputs, preserve text and image results, and stop admitting calls when the task stops. Cancellation and close wait for admitted callbacks to settle.
+
+Active steering returns `UNSUPPORTED_DELIVERY`; the coordinator applies its documented interrupt-and-replace behavior. Interruption cancels the active native run and waits for terminal completion. Failure to confirm native stop returns `CANCELLATION_FAILED`, fails the active turn, and prevents further tasks in that session. Tool admission remains closed; close must still dispose the native agent and drain admitted callbacks. Prompt-free recovery returns `RECOVERY_UNSUPPORTED`. A turn succeeds only with a successful terminal result and returns its final text. Responses are limited to 1 MiB.
+
+The SDK's headless permission decisions remain native. This SDK version exposes no supported interactive approval or input channel to the adapter. Its `request` message records a backend request identifier and is not an approval request. Native run failures produce a sanitized execution error; the adapter does not invent an `INPUT_REQUIRED` mapping from undocumented error codes. Close disposes the native agent and drains custom tools. `check cursor` verifies credential/model discovery, local agent creation, and disposal without submitting a prompt; it does not prove quota or that a later shell command will be permitted.
+
+## Subscription protocol and lifetime
+
+Subscription access uses the installed `cursor-agent` executable with its native ACP protocol over standard input and output. The supported CLI release is `2026.09.23-86fc751`, using ACP version 1. Other releases fail before input with `HARNESS_UNAVAILABLE` and compatibility guidance. The executable name is explicit because `agent` is also a Subharness compatibility alias. A session owns one native process and one native conversation in the requested working directory. Subscription access currently supports macOS and Linux, where the adapter can own and terminate a native process group. Windows subscription startup fails with `UNSUPPORTED_OPTION`; the SDK API-key route is unchanged.
+
+The transport accepts newline-delimited JSON-RPC 2.0, correlates responses by request ID, and rejects malformed envelopes or oversized protocol frames with `PROTOCOL_ERROR`. Individual frames are limited to 16 MiB; returned assistant text remains limited to 1 MiB. Native standard error and raw error messages are not forwarded to callers. Startup and configuration requests are bounded; model execution itself has no arbitrary completion deadline. Transport loss fails pending operations and retires the native process rather than leaving a task pending indefinitely.
+
+Native cancellation sends `session/cancel` and requires the active `session/prompt` to finish before confirming interruption. A cancellation timeout retires and poisons the session with `CANCELLATION_FAILED`; it does not replay input or silently open a replacement conversation. Closing stops admitting tool calls, retires the native process, and drains admitted custom-tool callbacks. Process retirement uses bounded termination and confirms process exit; failure to establish termination is an error. Tool callbacks have their own drain lifetime and are not falsely marked cancelled by a native timeout. Queued follow-ups reuse the same conversation after ordinary completion or confirmed native cancellation. Active steering and prompt-free recovery remain unsupported.
+
+## Subscription startup and capabilities
+
+Subscription access preserves native credential ownership. It removes `CURSOR_API_KEY` and `CURSOR_AUTH_TOKEN` from the child environment and does not call ACP `authenticate`, `login`, or `logout`. Native credential discovery, refresh, and account eligibility remain Cursor's responsibility. The adapter checks bounded `status --format json` output for authenticated access/refresh availability, then requires authenticated ACP session creation and model discovery. Status alone is not proof of readiness, quota, subscription-plan eligibility, or credential history. The `subscription` connection selects Cursor's saved native CLI account route; it does not attest how those native credentials were originally created or impose an account spending cap.
+
+A private owner-only configuration and data directory isolates model selection and session state. Native non-credential permission and network settings are preserved in the private configuration; project permission rules continue to apply. Shared user/project configuration is never rewritten. Alternate Cursor endpoints, authless/local-provider settings, and Bedrock activation are unsupported and rejected before native startup. Ordinary AWS credentials are not rejected merely because unrelated tools may use them. Native API keys, custom endpoints, or API-key helpers cannot silently select a different inference route. Subharness-created configuration files use mode `0600`; native-generated files remain inside the owner-only directory. Private state is removed after confirmed process shutdown. The native credential store is neither copied nor exposed through diagnostics.
+
+Startup negotiates ACP version 1 with the native parameterized model picker. The required model must match a concrete base ID in the returned native catalog; CLI display aliases and bracketed variant strings are not inferred. Native model parameters retain their defaults for that model. Auto routing IDs `auto`, `auto-smart`, `default`, and `default[]` are rejected. The selected model is applied with `session/set_config_option` and verified from its returned configuration before each prompt. A reported change fails explicitly. The adapter does not claim configured model readback proves the remotely executed model; this native protocol does not expose executed-model metadata in its terminal result. For example, `cursor({ model: "gpt-5-mini" })` selects that base model when present in the account catalog. A CLI display variant such as a model name with an effort suffix is not automatically treated as the same base ID.
+
+For subscription access, either explicit `sandboxMode` value fails with `UNSUPPORTED_OPTION` before submission because ACP does not expose a verified sandbox control. Omitting it uses Cursor's native ACP execution and permission behavior; it does not enable a Subharness sandbox. The API-key route retains its SDK sandbox option.
+
+Declared tools use a uniquely named private MCP server supplied in `session/new`. The adapter verifies that the native client initializes the server before admitting prompts; a skipped or failed native MCP connection is a startup error. MCP request bodies are limited to 16 MiB and headers to 16 KiB. Text and image results retain their MCP content types and shared tool-result limits. Native approval rules still apply. Active `session/request_permission` requests expose only the offered allow-once and reject-once choices through the shared approval flow with `harness: "cursor"`; persistent allow-always/reject-always choices are not exposed. Original native option IDs are retained. Unsupported or malformed interactive requests, including questions and plan approval, fail with `INPUT_REQUIRED` and cancel the native turn. Startup-time interactive requests are unsupported. Withdrawal, terminal completion, cancellation, and close retire pending requests; late answers never grant permission.
+
+A terminal ACP `end_turn` returns the accumulated assistant text. `cancelled` is interruption; refusal or exhausted-limit terminal reasons and RPC/transport failures reject with a sanitized execution error. This CLI release can render some backend failures as ordinary assistant text followed by `end_turn`, without a separate failure signal. Such text is returned as native output; a completed Subharness task on this route means the native turn ended, not that every backend operation succeeded. The adapter does not guess error status from prose. Raw transport diagnostics remain private. This capability limit is specific to the subscription ACP route; the API-key SDK route retains its typed native results.

package/sdk/diagnostics.md

@@ -0,0 +1,29 @@
+# Error Diagnostics
+
+Error records retain their existing `{ code, message }` shape. Messages describe the operation that failed and include safe, observed context that helps callers identify the cause. The diagnostics described here never include raw native stderr, SDK exception text, HTTP response bodies, RPC error messages or data, prompts, credential values, or configuration contents. Unknown native values receive a fixed generic explanation rather than being echoed. Paths included in these diagnostic cases are quoted with C0, C1, DEL, and Unicode line separators escaped.
+
+## Claude startup and turn failures
+
+Claude startup distinguishes native account inspection, model catalog retrieval, and model settings validation. An unexpected exception from account inspection or model catalog retrieval is `HARNESS_FAILED`, with the failed phase identified. Unexpected exceptions after successful access verification are also harness failures identified by the current startup phase. They do not establish unavailable access and do not permit connection or harness fallback. A completed account inspection that demonstrates unavailable or incompatible access retains `ACCESS_UNAVAILABLE` and its existing eligible fallback behavior. Existing explicit configuration, settings capability, model, and effort errors retain their codes and guidance, including `--model` guidance for an unverifiable native default. Cleanup and no-prompt-before-verification rules remain unchanged.
+
+Claude terminal result failures retain `HARNESS_ERROR`. Recognized result subtypes distinguish a native turn limit, a native budget limit, exhausted structured-output retries, and an error during execution. Messages describe the reported category without claiming an unobserved provider cause, quoting native error text, or promising that Subharness exposes configuration for every native limit. Unknown subtypes and unsuccessful results without a recognized category receive a fixed generic turn-failure message. A reported execution failure is never automatically retried or replayed.
+
+## Native protocol and process failures
+
+Codex and fx RPC rejection messages identify the requested native method and include the native error code only when it is a safe integer. Known JSON-RPC codes use fixed categories: `-32700` is a parse error, `-32600` an invalid request, `-32601` an unavailable method, `-32602` invalid parameters, and `-32603` an internal error. Other safe integer codes remain numeric without an invented interpretation. Missing or malformed codes are not printed. A generic rejection does not claim that authentication or native configuration caused the error. Existing steering and session-option capability classifications retain their Subharness error codes and useful recovery guidance. Freeform native messages and error data are never forwarded.
+
+When an observed process termination causes an error, diagnostics identify the process and include its observed exit code or recognized termination signal when available. This applies to Codex and fx transports, the Claude subprocess owned by the adapter, session workers, and coordinator startup. A signal does not establish why it was sent; for example, `SIGKILL` does not by itself prove an out-of-memory condition. Missing termination metadata is omitted. Cleanup-induced termination must not replace or be described as the cause of an earlier failure. Adding diagnostics does not wait indefinitely for process exit or weaken bounded shutdown.
+
+Worker failures identify the pending operation when available, such as startup, turn submission, steering, interruption, recovery, or closing. Coordinator failures distinguish failure to spawn, early exit, and startup timeout, retaining existing retirement and endpoint-publication safeguards. Only fixed operation labels and recognized system error categories may be added; raw operating-system exception text is not forwarded.
+
+## Coordinator communication
+
+Coordinator communication failures retain `COORDINATOR_UNAVAILABLE`. A non-success HTTP response identifies its numeric status and a recognized requested operation, when available. A successful response with no body is distinguished from HTTP rejection. Invalid JSON records, an incomplete final record, and an interrupted response stream have distinct fixed explanations. Transport failures retain the statement that the task was not automatically retried. These diagnostics do not expose endpoint tokens, raw request or response contents, or arbitrary operation names. They do not infer whether a task completed from an HTTP or transport failure and do not automatically replay it.
+
+## Access configuration and OIDC
+
+Personal-access schema errors retain `INVALID_CONFIG` and identify their structural location: the root object, `access`, a recognized harness entry such as `access.claudeCode`, or a zero-based connection location such as `access.claudeCode[0]`. A known invalid connection property may extend that location, for example `access.claudeCode[0].env`. Unknown property names or harness names are not echoed because arbitrary keys can contain sensitive values. An unknown connection property identifies its containing connection. Errors raised while loading a file also identify its absolute, safely quoted main-checkout path, or execution-project path outside Git. Invalid JSON and file-read errors identify the same safely quoted path. Validation happens before any connection is attempted; it does not fabricate attempted-access context.
+
+An inaccessible execution directory is identified by its safely quoted caller-supplied path in both the CLI and project resolver. A missing credential file identifies its safely quoted configured `envFile` reference; it retains `ACCESS_UNAVAILABLE` and eligible fallback behavior. These messages preserve the existing path resolution rules and do not read credential contents to enrich an error.
+
+OIDC expiration and not-yet-valid claims have separate diagnostics, both retaining `INVALID_CONFIG`. Expiration directs the caller to refresh the configured credential source. A future not-before claim explains that the token is not yet valid and suggests checking the system clock or waiting until validity begins; it does not assert that the clock is wrong. If both conditions apply, expiration is reported first. No token values or raw claims are printed. Claim-validation rules, project matching, and credential-source selection remain unchanged.

package/sdk/distribution.md

@@ -4,7 +4,7 @@ The npm package name is `subharness`. One package provides the TypeScript SDK an
 
 The source repository is [vercel-labs/subharness](https://github.com/vercel-labs/subharness). Its GitHub visibility is internal, so cloning requires repository access. The product name is subharness. The primary CLI command is `subharness`; `agent` remains an identical compatibility alias. Agent discovery and personal configuration live under `.subharness/`.
 
-Node.js 22.18 or newer is required. The SDK is ESM and includes TypeScript declarations. The native Codex, Claude Code, and fx executables remain external prerequisites; installing this package does not install harnesses or configure their credentials.
+Node.js 22.18 or newer is required. The SDK is ESM and includes TypeScript declarations. Installing this package supplies the pinned Copilot and Cursor SDK dependencies. It does not configure native harness credentials or install the Codex, Claude Code, fx, OpenCode, or Cursor executables. Cursor subscription access requires the separately installed `cursor-agent` CLI; Cursor API-key access uses the bundled SDK dependency. The Copilot SDK may supply its compatible runtime as defined in the [Copilot contract](copilot.md).
 
 ## Installation and resolution
 

package/sdk/evals.md

@@ -41,7 +41,7 @@ resolveEvalAccess(options: {
 }): Promise<EvalAccess | EvalAccessError>
 ```
 
-`HarnessKind` uses the existing `codex`, `claudeCode`, and `fx` identifiers. The harness list is nonempty and has no duplicates. IDs are nonempty strings. `minimumValidityMs` is a positive finite safe integer. The default environment is `process.env`, and the default clock is `Date.now` in milliseconds. Input errors are returned before native startup; this function never starts a harness or makes a network request.
+The evaluation harness discriminator remains limited to the original `codex`, `claudeCode`, and `fx` identifiers. The harness list is nonempty and has no duplicates. IDs are nonempty strings. `minimumValidityMs` is a positive finite safe integer. The default environment is `process.env`, and the default clock is `Date.now` in milliseconds. Input errors are returned before native startup; this function never starts a harness or makes a network request.
 
 `EvalAccessError` is a typed returned error, not an exception-based domain result. Its `reason` is one of `invalid-input`, `policy`, `credentials-unavailable`, `validation`, `identity`, or `insufficient-lifetime`. Its message is exactly `Evaluation access is unavailable.` for every reason; it never retains raw caught exceptions, credentials, token claims, or native output. A policy error includes absent keys, a disabled participating harness, non-OIDC routes, or fallback lists. Credential reading failures are credentials-unavailable; malformed/expired/not-yet-valid credentials or linkage validation failures are validation. A valid linked token whose project or organization differs from the independent expectation is identity. Insufficient remaining validity uses insufficient-lifetime. Unclassified access-layer failures are validation, not guessed native authentication causes.
 

package/sdk/fx.md

@@ -27,14 +27,13 @@ function fx(options: FxOptions): FxConfig;
 
 `FxConfig` is a readonly harness configuration with `kind: "fx"`, the required `model`, optional `effort`, and optional `permissionMode`. It is a member of `HarnessConfig` and can appear alone or in an ordered `harness` array. The constructor only validates and declares configuration; it does not start a process or access credentials. Unknown fields, including `fast`, are rejected. Native fx does not expose a compatible fast-mode selector in the supported ACP interface; its native fast-mode preference remains in effect.
 
-Models use the exact AI Gateway `provider/model` identifier. An explicit effort must be supported by the native session's advertised configuration for that model. Unsupported effort fails with `UNSUPPORTED_OPTION` before a task is submitted. Omitting effort preserves the native model's default. The adapter verifies the selected model and explicit effort; it does not silently substitute a model. A model appearing in the catalog does not guarantee access through a particular Gateway team or key.
+Gateway models use the exact AI Gateway `provider/model` identifier. Other routes use their native model identifier without inferring the authentication provider from the model name. An explicit effort must be supported by the native session's advertised configuration for that model. Unsupported effort fails with `UNSUPPORTED_OPTION` before a task is submitted. Omitting effort preserves the native model's default. The adapter verifies the selected model and explicit effort; it does not silently substitute a model. A model appearing in the catalog does not guarantee access through a particular Gateway team or key.
 
-Direct CLI invocation does not require a definition: `subharness run fx "Review the current diff."` uses the native Gateway default model when it can be verified before submission. `--model <provider/model>` selects it explicitly. Both forms retain the access and permission requirements below; neither discovers a subscription or enables ambient paid credentials. The TypeScript constructor still requires `model`.
+Direct CLI invocation does not require a definition: `subharness run fx "Review the current diff."` uses the selected native provider's default model when it can be verified before submission. `--model <provider/model>` selects it explicitly. Both forms retain the access and permission requirements below; neither discovers a subscription or enables ambient paid credentials. The TypeScript constructor still requires `model`.
 
 ## Access
 
-fx supports explicit `vercel-api-key` and `vercel-oidc` connections through the existing personal access file. It does not discover subscriptions, reuse another harness's subscription, or infer paid access from ambient credentials. Omitting `access.fx` leaves fx without an enabled connection. An empty array explicitly disables it. A `subscription` connection is unavailable; direct `api-key` access is unsupported by this adapter and fails with `UNSUPPORTED_OPTION`.
-
+fx accepts explicitly selected Gateway API-key/OIDC access, native saved logins, and API keys for native custom connections. Omitting `access.fx` leaves fx without an enabled connection; an empty array explicitly disables it. Ambient credentials do not enable a route. Gateway connections retain their existing shape and behavior; the following example selects one explicitly.
 ```json
 {
   "access": {
@@ -45,7 +44,53 @@ fx supports explicit `vercel-api-key` and `vercel-oidc` connections through the
 }
 ```
 
-The connection reads only the named variable from the selected file. Existing main-checkout and worktree path rules apply. The adapter supplies the selected credential through the fx subprocess environment, fixes the native provider to AI Gateway, and removes competing credential variables and endpoint overrides. It does not save the key in native settings or place it in process arguments. Native shell processes can inherit that environment, so the credential is available within the native process tree. ACP does not provide an isolated credential channel for this release. Credential isolation from native tools belongs to the external harness or execution environment; this adapter does not provide it.
+## Native saved logins and custom API keys
+
+Expanded access is verified against fx 0.0.11 and requires the described native status and ACP provider capabilities. Existing Gateway compatibility with fx 0.0.9 is retained.
+
+A `subscription` connection requires `provider: "gateway"`, `"codex"`, or `"grok"`. The corresponding native setup is `fx login`, `fx login codex`, or `fx login grok`, performed outside Subharness. These are fx-owned logins; the adapter never imports another harness's tokens. `gateway` selects the saved Vercel login and still bills AI Gateway. The connection type identifies native saved-login access, not proof of a subscription plan or free usage.
+
+```json
+{ "access": { "fx": [{ "type": "subscription", "provider": "codex" }] } }
+```
+
+For saved Gateway login, native settings must explicitly select `credential_source: "fx_login"`. An automatic preference or a stored-key preference is insufficient because refresh must not fall through to another billing source. The adapter does not change that preference. Native status must report the exact selected login source; startup then initializes native ACP with the same environment. Native discovery, refresh, credential migration, and persistence remain fx's responsibility and may update its own credential stores. Subharness does not read or copy those stores. Local status and successful initialization do not prove remote entitlement or quota.
+
+For direct `api-key`, `provider` names a preexisting connection in `~/.fx/settings.json`, and `env` explicitly selects the input credential variable. The native connection must use `protocol: "openai-chat-completions"` and `auth: { "type": "bearer", "env": "NATIVE_KEY_SLOT" }`. Built-in provider names cannot be used for this route. The adapter reads bounded connection metadata, resolves the selected input key, and supplies it only to the native connection's declared environment slot in the child. Input and output variable names can differ. The adapter never writes the key or endpoint into native settings.
+
+```json
+{
+  "access": {
+    "fx": [{ "type": "api-key", "provider": "openrouter", "env": "MY_ROUTER_KEY", "envFile": ".env.local" }]
+  }
+}
+```
+
+A corresponding native connection, configured through fx, can be:
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "protocol": "openai-chat-completions",
+      "base_url": "https://openrouter.ai/api/v1",
+      "auth": { "type": "bearer", "env": "OPENROUTER_API_KEY" }
+    }
+  }
+}
+```
+
+Connection names follow native fx syntax: `[A-Za-z][A-Za-z0-9_-]*`, at most 64 characters, with built-in names reserved case-insensitively. Native endpoints require HTTPS, or HTTP on `localhost`, `127.0.0.1`, or `[::1]`, without user information, query, or fragment. The native connection retains its API path prefix.
+
+Model metadata and defaults for custom connections remain native fx settings. The adapter does not invent context limits, protocols, or provider-specific capabilities. Anonymous custom connections are not represented by `api-key`; Anthropic Messages and generic Responses endpoints cannot be treated as Chat Completions. Native custom-connection vision limitations still apply even when metadata advertises image support.
+
+Credential output slots cannot name process-control or routing variables such as `HOME`, `PATH`, `FX_PROVIDER`, `FX_MODEL`, `FX_AUTH_MODE`, loader/proxy controls, or native diagnostic/endpoint controls. Inapplicable access fields, malformed profiles, unknown connections, unsupported protocols, and unsafe slots fail before native startup. Both status and ACP use the same selected provider, model, and environment. Custom readiness checks the native provider name, endpoint, bearer slot metadata, and ACP provider/model selection; the generic status label `configured provider` alone is insufficient.
+
+For all routes, inherited host-managed authentication, test endpoint overrides, competing Gateway credentials, and recording controls cannot replace the explicitly selected route. Native settings are fingerprinted around startup and before each task; a detected change requires a new session. This is not atomic protection against changes during a native request. Native permissions, approvals, same-session follow-ups, cancellation, and callback drain keep their existing behavior.
+
+## Gateway credential selection
+
+The connection reads only the named variable from the selected file. Existing main-checkout and worktree path rules apply. For Gateway connections, the adapter supplies the selected credential through the fx subprocess environment, fixes the native provider to AI Gateway, and removes competing credential variables and endpoint overrides. It does not save the key in native settings or place it in process arguments. Native shell processes can inherit that environment, so the credential is available within the native process tree. ACP does not provide an isolated credential channel for this release. Credential isolation from native tools belongs to the external harness or execution environment; this adapter does not provide it.
 
 Native authentication preferences can override environment credentials. Startup runs native credential-source introspection with the same environment and requires the expected environment source. A known conflicting native login fails with `ACCESS_UNAVAILABLE` and guidance to select the environment source in fx. An unrecognized or malformed introspection result fails with `PROTOCOL_ERROR`, without trying another route. The adapter never changes native authentication preferences itself. It checks native settings for changes during startup and before each new task; detected changes fail with `INVALID_CONFIG` and require a new session. ACP does not provide atomic, in-process credential-source attestation, so native settings must remain stable while the session is active. OIDC project validation and token-lifetime rules are the same as for other Gateway connections.
 

package/sdk/harnesses.md

@@ -1,6 +1,6 @@
 # Harnesses
 
-V1 integrates Codex, Claude Code, and fx. Grok Build, Cursor, and OpenCode remain product compatibility requirements without implemented adapters. Compatibility means connecting the external harness, not merely calling its model through an API.
+V1 integrates Codex, Claude Code, fx, OpenCode, GitHub Copilot, and Cursor. Compatibility means connecting the external harness, not merely calling its model through an API.
 
 The library provides coordination and definitions. Harnesses own inference, native tools, conversation state, and context management. The execution environment provides any sandboxing or worktree isolation.
 
@@ -16,23 +16,23 @@ Automatic fallback ends at task submission. Execution failure, allowance exhaust
 
 ## Capabilities
 
-| Operation | Codex | Claude Code | fx |
-| --- | --- | --- | --- |
-| Native session follow-ups | Supported | Supported | Supported |
-| Queue between library tasks | Supported | Supported | Supported |
-| Active steering | Native steering | Uses interrupt semantics | Uses interrupt semantics |
-| Interruption | Native interruption with stop confirmation | Native interruption with stop confirmation | Native ACP cancellation with stop confirmation |
-| Custom tools | Native dynamic tools | Native SDK MCP tools | Private MCP HTTP tools |
-| Declared-child launcher permissions | Uses effective native permissions; no adapter-added rule | Session-only rules for the exact launcher and declared operations | Uses effective native permissions; no adapter-added rule |
-| Prompt-free recovery of failed work | Explicit unsupported result | Explicit unsupported result | Explicit unsupported result |
-| Startup readiness check without a turn | Supported | Supported | Supported |
+| Operation | Codex | Claude Code | fx | OpenCode | Copilot | Cursor |
+| --- | --- | --- | --- | --- | --- | --- |
+| Native session follow-ups | Supported | Supported | Supported | Supported | Supported | Supported |
+| Queue between library tasks | Supported | Supported | Supported | Supported | Supported | Supported |
+| Active steering | Native steering | Uses interrupt semantics | Uses interrupt semantics | Uses interrupt semantics | Uses interrupt semantics | Uses interrupt semantics |
+| Interruption | Native stop confirmation | Native stop confirmation | Native ACP stop confirmation | Native abort stop confirmation | Native abort stop confirmation | Native cancellation stop confirmation |
+| Custom tools | Native dynamic tools | Native SDK MCP tools | Private MCP HTTP tools | Private MCP tools | Native SDK callbacks | Native SDK custom tools or subscription MCP tools |
+| Declared-child launcher permissions | Effective native policy | Exact session-only launcher rules | Effective native policy | Effective native policy | Effective native policy | Effective native policy |
+| Prompt-free recovery of failed work | Explicit unsupported result | Explicit unsupported result | Explicit unsupported result | Explicit unsupported result | Explicit unsupported result | Explicit unsupported result |
+| Startup readiness check without a turn | Supported | Supported | Supported | Supported | Supported | Supported |
 
 `resume` remains a stable command; these adapters return `RECOVERY_UNSUPPORTED` when they cannot resume failed work without replay. The queue remains paused. Unsupported native steering follows the [interrupt contract](message-delivery.md), including cancellation propagation and a new replacement task; output reports the effective mode.
 
-All TypeScript constructors require a model. Direct [CLI harness targets](cli/index.md) may omit it to select and retain a verifiable native default within the authorized access route. Codex and Claude Code default fast mode to false. fx exposes model and optional native effort, with the capabilities and limits described in its [adapter contract](fx.md). Explicit options are validated where the native interface exposes compatibility. A provider can reject a request after submission; that is an execution failure, not permission to choose another model. Model/provider substitutions detected by an adapter are rejected.
+All TypeScript constructors require a model. The Codex, Claude Code, and fx direct [CLI harness targets](cli/index.md) may omit it to select and retain a verifiable native default within the authorized access route. OpenCode, Copilot, and Cursor require an explicit CLI model and reject effort. Codex and Claude Code default fast mode to false. fx exposes model and optional native effort. Cursor additionally exposes its optional SDK sandbox mode for API-key access; explicit sandbox settings are unsupported for subscription ACP access. Explicit options are validated where the native interface exposes compatibility. A provider can reject a request after submission; that is an execution failure, not permission to choose another model. Model/provider substitutions detected by an adapter are rejected.
 
 Claude fast mode with subscription access is unavailable in v1 because shared agent configuration does not authorize additional subscription spending. Explicit paid API or Gateway access can request it where supported. Native subscription eligibility and provider distribution terms still apply; subscription login is not an account-wide spending cap.
 
-See [native adapter behavior](adapter-contract.md) for authentication isolation, native permissions, tool transport, and lifecycle details.
+See [native adapter behavior](adapter-contract.md), [Additional native harnesses](additional-harnesses.md), [OpenCode](opencode.md), [Copilot](copilot.md), and [Cursor](cursor.md) for authentication isolation, native permissions, tool transport, and lifecycle details.
 
 Codex permission behavior is version- and environment-dependent. The adapter does not assume that an installed Codex version can accept session-scoped launcher rules. Explicit [permission options](permissions.md) select native sandbox and network settings; the adapter does not broaden them automatically. A native approval request therefore remains possible for declared-child delegation even though the child is authorized by the Subharness definition.

package/sdk/index.md

@@ -1,6 +1,6 @@
 # SDK and CLI
 
-The CLI runs generic Codex, Claude Code, and fx agents without definition files. The optional TypeScript SDK defines reusable specialists on those same external harnesses. The CLI coordinates sessions, queues, follow-ups, and nested delegation in caller-supplied working directories.
+The CLI runs generic Codex, Claude Code, fx, OpenCode, GitHub Copilot, and Cursor agents without definition files. The optional TypeScript SDK defines reusable specialists on those same external harnesses. The CLI coordinates sessions, queues, follow-ups, and nested delegation in caller-supplied working directories.
 
 - [Distribution](distribution.md): package identity, local installation, and release boundaries.
 - [Agent skill](agent-skill.md): the installable skill that teaches a coding agent to delegate with the CLI.
@@ -13,6 +13,7 @@ The CLI runs generic Codex, Claude Code, and fx agents without definition files.
 - [Harnesses](harnesses.md): selection, capabilities, and fallback boundaries.
 - [CLI](cli/index.md): commands and response waiting.
 - [Output](cli/output.md): compact text and typed JSONL records.
+- [Error diagnostics](diagnostics.md): failure categories, safe context, and recovery guidance.
 - [Sessions](sessions.md): task identity, state, and recovery.
 - [Message delivery](message-delivery.md): queue, steer, interrupt, and cancellation.
 - [Subagents](plugins/sub-agents.md): nested delegation and context boundaries.
@@ -22,4 +23,4 @@ The CLI runs generic Codex, Claude Code, and fx agents without definition files.
 
 These documents describe the v1 contract. They do not authorize automatic conversation migration, a custom model harness, sandbox provisioning, or a separate pipeline-definition API.
 
-The [fx adapter](fx.md) connects native fx ACP sessions through explicit AI Gateway access. The [repository team](project-team.md) defines the roles used to develop this project.
+The adapter contracts cover [fx](fx.md), [OpenCode](opencode.md), [GitHub Copilot](copilot.md), and [Cursor](cursor.md). The shared configuration for the three additional harnesses is defined in [Additional native harnesses](additional-harnesses.md). The [repository team](project-team.md) defines the roles used to develop this project.

package/sdk/opencode.md

@@ -0,0 +1,57 @@
+# OpenCode adapter
+
+The OpenCode adapter runs the installed `opencode` executable in native HTTP server mode on a private loopback endpoint. This adapter supports OpenCode 1.18.32. It checks the executable version before starting the server and rejects other or unverifiable versions with `INVALID_CONFIG`, because configuration isolation depends on that version's native switches. OpenCode owns inference, native tools, conversation state, and compaction. The public configuration and access routes are defined in [additional harnesses](additional-harnesses.md).
+
+## Direct API keys
+
+An explicit `api-key` connection requires `provider` and `env`; `envFile` and `baseUrl` are optional. Supported single-key providers are `anthropic`, `openai`, `google`, `groq`, `openrouter`, `xai`, `mistral`, `cohere`, `opencode` (Zen), and `opencode-go` (Go). Provider IDs that require additional cloud identity, resource, or region settings are not represented by this single-key connection. Unknown providers fail explicitly instead of trying ambient credentials.
+
+The agent model uses the exact native `provider/model` ID and its prefix must equal the connection's provider. OpenRouter model names may contain additional slashes. The installed native catalog must contain the exact model and compatible provider metadata; the adapter does not invent custom model metadata. An optional `baseUrl` overrides the selected catalog provider's endpoint. Without it, the pinned native SDK supplies that provider's endpoint. Startup verifies the explicit provider, token configuration, model, and any endpoint override without generation. Native default endpoints and SDK transformations are not remote executed-model attestation.
+
+```json
+{
+  "access": {
+    "opencode": [{ "type": "api-key", "provider": "anthropic", "env": "ANTHROPIC_API_KEY" }]
+  }
+}
+```
+
+Direct keys retain private configuration, data, state, and cache directories. Only the chosen provider is enabled; its environment-key discovery is disabled and the selected key is supplied explicitly. Saved native auth and default auth plugins are excluded. Both the main and auxiliary model are pinned to the exact native model. Existing Gateway behavior remains available independently.
+
+## Native saved logins
+
+A `subscription` connection requires `provider: "openai"`, `"github-copilot"`, or `"xai"`, selecting the corresponding built-in native OAuth integration. The user completes OpenCode's native login first. The model uses the same exact `provider/model` syntax as direct access, with a matching provider prefix. Saved API-key and well-known credentials are not treated as OAuth subscriptions. Plan names alone do not establish credential type or eligibility.
+
+```json
+{ "access": { "opencode": [{ "type": "subscription", "provider": "openai" }] } }
+```
+
+This route intentionally uses OpenCode's native persistent XDG data directory because OpenCode stores and refreshes its login there. The native process can access its complete authentication store and persist normal native data, including session history and token refreshes. Subharness does not read, copy, synchronize, or rewrite the credential file. It does not perform login or logout. Config, state, and cache remain private; project/provider configuration discovery remains disabled. Only built-in authentication plugins are enabled, with the explicitly selected inference provider and pinned main/auxiliary model. The subscription route does not offer an endpoint override.
+
+Readiness requires the selected connected provider's OAuth plugin configuration and the exact native model. A missing login is unavailable; ambiguous, malformed, or conflicting auth metadata is an error. Detection relies on this pinned release's native provider source and OAuth markers, without extracting tokens or pretending that every native fetch transformation is exposed as an endpoint. A known saved API-key route cannot silently replace the requested OAuth route. Closing removes only adapter-owned private state; it never removes or restores the native persistent data directory.
+
+## Gateway isolation
+
+For Gateway connections, the public model is a Gateway `creator/model` identifier. The native provider is `vercel`; the adapter supplies the corresponding `vercel/creator/model` native selection. Startup uses a private configuration and private native state directories, enables only the Gateway provider, and pins the main and auxiliary model to the requested identifier. It disables native model fallback, project/provider configuration discovery, default plugins, automatic updates, and sharing so inherited provider configuration cannot change the selected billing route.
+
+Repository instruction discovery is restored through the native `instructions` setting without importing repository provider configuration. Starting at the execution directory and stopping at the nearest Git worktree root, the adapter finds `AGENTS.md`, otherwise `CLAUDE.md`, otherwise `CONTEXT.md`, using the first filename category with matches. Matching ancestor files are passed as absolute native instruction paths. Outside Git, only the execution directory is searched. Native per-file instruction handling remains native. Subharness specialist instructions supplement the first task. Native configuration, plugins, and custom native agent definitions excluded by this isolation profile are not copied into the temporary state.
+
+Residual home or machine-managed configuration that would still load outside the private directories must be checked before native startup. If it cannot be established compatible with the isolated profile, startup fails with `INVALID_CONFIG`; organizational policy is never bypassed using test-only environment overrides. Missing model metadata is also an error; the adapter does not invent context limits or image capabilities for unknown models.
+
+Only the selected Gateway credential is supplied for inference. An API key and an OIDC token retain their distinct Gateway authentication modes; the adapter must not pass an OIDC token as an API key. Configuration files containing credentials have mode `0600` in an owner-only temporary directory. Credentials never appear in command arguments, native diagnostic output, or shared project files. Startup checks the effective provider, endpoint, model, and native configuration before admitting prompts, and rejects incompatible or unverifiable settings. Private files are removed on startup failure and normal close.
+
+The server is bound to `127.0.0.1` with a random per-process password, and requests are scoped to the caller's directory. Startup requires health, provider/configuration discovery, and creation of an empty native session. No generation is used to verify readiness or quota. A missing executable is `HARNESS_UNAVAILABLE`; malformed native protocol data is `PROTOCOL_ERROR`.
+
+## Tools and permissions
+
+Declared tools are exposed through a private authenticated loopback MCP endpoint. Arguments are validated before callbacks run. Text and image content are preserved through MCP. The adapter verifies that the native MCP connection succeeds before submitting work. Tools stop admitting calls during interruption and close, and admitted callbacks must settle before stop is reported.
+
+Native permissions are configured to ask. Active native permission requests use the shared approval flow, exposing bounded action context and the native `once`/`reject` decisions. Reusable grants are not exposed because native instance scope can include native child sessions. Startup-time requests and other interactive questions fail with `INPUT_REQUIRED`; no permission is automatically granted. The adapter does not add launcher allow rules. Native denial is passed back to OpenCode without authorizing a replacement operation. OpenCode can retire other pending requests in the same session after a rejection; the adapter reconciles native pending requests and drops late answers to retired operations.
+
+## Lifecycle
+
+Each Subharness session owns one native conversation and one native server. Follow-up tasks retain that conversation. Every prompt pins the requested provider/model; detectable changes are errors without replay. A task returns the final assistant text only after successful native completion. Native errors, unfinished responses, and malformed terminal data cannot count as success. The final text limit is 1 MiB.
+
+Interruption requests native abort and confirms the active work stopped; an accepted HTTP abort request alone is insufficient. It also drains admitted tools and retires outstanding approvals, including when native work ended before interruption began. Native stop confirmation is bounded; that deadline does not limit already-admitted host callbacks, which must settle before interruption completes. Failure to confirm native termination produces `CANCELLATION_FAILED`, and no replacement prompt is admitted to still-running work. Steering uses the shared interrupt behavior; prompt-free recovery is unsupported.
+
+Close aborts active work, closes event streams and the native session, terminates the owned server with bounded escalation when needed, and removes private configuration/state and tool endpoints. Startup failures use the same cleanup discipline. Normal cleanup never deletes project files or user-owned OpenCode settings.

package/sdk/permissions.md

@@ -1,6 +1,6 @@
 # Native Permissions
 
-Harness constructors accept optional native permission settings directly alongside model options. These settings configure the native session without modifying persistent native settings or creating a Subharness sandbox. Later supported native tool approvals are surfaced to the caller through the [structured approval flow](approvals.md); an explicit valid caller decision is required before authorization. The installed harness evaluates the selected policy, and the external execution environment enforces its remaining restrictions.
+The Codex, Claude Code, and fx constructors accept optional native permission settings directly alongside model options. These settings configure the native session without modifying persistent native settings or creating a Subharness sandbox. OpenCode instead uses its isolated native ask policy, Copilot uses native manual permission mode, and neither exposes a public permission selector. Cursor exposes its documented SDK `sandboxMode` for API-key access; subscription ACP access rejects explicit sandbox settings and supports the documented once-only native approvals. Supported native tool approvals are surfaced to the caller through the [structured approval flow](approvals.md); an explicit valid caller decision is required before authorization. The installed harness evaluates the selected policy, and the external execution environment enforces its remaining restrictions.
 
 Omitted settings preserve native configuration. Explicit settings remain fixed for session follow-ups. A child uses its own definition and native configuration; it does not inherit the parent's explicit permission options. Invalid definitions fail before execution. Unsupported or observably rejected explicit settings fail without fallback to another harness or permission policy.
 
@@ -21,6 +21,8 @@ codex({
 
 `approvalPolicy: "never"` suppresses approval prompts; it does not grant operations blocked by the selected sandbox. `danger-full-access` removes Codex's native sandbox boundary, subject to external restrictions.
 
+By default, `workspace-write` keeps `.git`, `.agents`, and `.codex` read-only inside the writable workspace. It also protects the Git directory named by a `.git` pointer file, even when that directory is inside the workspace; for a linked worktree, that directory is in the main checkout's Git directory and holds the worktree's index. Git index updates such as `git add` can therefore fail in ordinary checkouts and linked worktrees. subharness does not add writable roots or change the native policy to permit these operations.
+
 ## Claude Code
 
 ```ts
@@ -62,4 +64,4 @@ For a surfaced permission request, the caller inspects the action and responds t
 
 The caller reads the Subharness skill and prefers one ordinary `subharness run <target>` through known host background-command controls. It continues independent work and later collects that hosted command's output, which already contains the first response or terminal outcome. When those controls are unavailable or uncertain, it uses `run --detach`, retains the returned task and session identifiers, continues other work, and later collects the result with `wait`. `status` is optional when a snapshot or additional state is needed. Shell `&` and an unobserved process do not replace managed task records. Both paths require collecting the result and confirming its terminal outcome before reporting completion; detached admission alone is not completion.
 
-The native caller needs permission to execute the private launcher and reach the local coordinator. Each child needs permission for its own task. This remains true for Codex, Claude Code, and fx; no constructor option promises native desktop notifications or automatic chat reactivation.
+The native caller needs permission to execute the private launcher and reach the local coordinator. Each child needs permission for its own task. This remains true for all six native harnesses; no constructor option promises native desktop notifications or automatic chat reactivation. OpenCode and Copilot can surface supported active permission requests through the structured approval flow. Cursor subscription sessions also expose supported once-only ACP permissions. Other Cursor interactive requests fail with `INPUT_REQUIRED`.

package/sdk/project-team.md

@@ -21,6 +21,8 @@ Role instructions alone do not grant native capabilities or permissions. Browsin
 
 The repository's Codex roles explicitly select `approvalPolicy: "never"`, `sandboxMode: "workspace-write"`, and `networkAccessEnabled: true` for local development and coordinator access. The reviewer selects Claude `permissionMode: "dontAsk"` with `Read`, `Glob`, `Grep`, and `Bash` allowed. Its read-only review responsibility remains an instruction; allowing Bash is not a filesystem read-only boundary. The fx roles explicitly select `permissionMode: "auto"`. These policies use [native permission options](permissions.md), preserve native restrictions, and do not guarantee that every operation is permitted. Protected paths and rejected automatic reviews can still require a lead-managed execution path.
 
+Implementation roles return unstaged working-tree changes and verification evidence. Local Git staging and commits belong to the lead unless the assignment explicitly authorizes them. When an implementation task requires moving or deleting ordinary files, roles use filesystem operations; subsequent Git staging records the renames. By default, Codex workspace-write protects `.git`, `.agents`, and `.codex` inside the writable workspace. It also protects the Git directory named by a `.git` pointer file, even when that directory is inside the workspace; for a linked worktree, that directory is in the main checkout's Git directory and holds the worktree's index. A required change under those protected paths is reported with the exact operation, affected paths, and partial effects for lead-managed execution. A copied replacement does not complete a move while the original remains.
+
 ## Skills and task context
 
 Repository skills live in `.agents/skills/<name>/SKILL.md`. The short index in `AGENTS.md` explains when each skill applies. Agents read only the relevant skill and supporting references for their current task. Skill contents are not concatenated into every agent's instructions.

package/sdk/tools.md

@@ -70,6 +70,6 @@ function toolResult(result: { readonly content: readonly ToolContent[] }): ToolR
 
 `ToolResult` is an opaque value created by `toolResult`; callers must return it directly from `execute`. It is not a JSON transport format. Content must be nonempty, contain only the supported block fields, and include at most eight images. Image data is canonical padded standard base64 without a data-URL prefix. The decoded file signature must match its declared MIME type. Each encoded image is limited to 5 MiB; the complete rich result's JSON content is limited to 8 MiB, and combined text is limited to 1 MiB. Ordinary text and JSON results retain their 1 MiB limit.
 
-The SDK validates rich results at the tool execution boundary. Malformed blocks report `TOOL_RESULT_INVALID`; exceeded limits report `TOOL_RESULT_TOO_LARGE`. Native adapters pass images as image content, never as base64 inside a text result: MCP image blocks for Claude Code and fx, and image content items for Codex. Model-specific image support and lower native limits still apply; a text-only model cannot perform visual inspection. The [fx contract](fx.md) records a native image-tool crash affecting fx 0.0.9. The tool author controls which files are read. This helper does not grant filesystem access or fetch remote images.
+The SDK validates rich results at the tool execution boundary. Malformed blocks report `TOOL_RESULT_INVALID`; exceeded limits report `TOOL_RESULT_TOO_LARGE`. Native adapters pass images as image content, never as base64 inside a text result. Claude Code, fx, and OpenCode use MCP image blocks; Codex and Cursor SDK sessions use native image content items; Cursor subscription sessions use MCP image blocks. [Copilot](copilot.md) groups content by type in its native result envelope: text blocks are joined in their original text order, images retain their original image order as binary image results, and interleaving between the text and image groups is unavailable. Model-specific image support and lower native limits still apply; a text-only model cannot perform visual inspection. The [fx contract](fx.md) records a native image-tool crash affecting fx 0.0.9. The tool author controls which files are read. This helper does not grant filesystem access or fetch remote images.
 
 Cancellation waits for already-admitted callbacks to settle. There is no cancellation signal in `execute(input)`, and completed effects are not rolled back. Streaming tool results and arbitrary external tool-definition objects are outside this API.