subharness 0.0.4 → 0.0.7

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,25 +1,50 @@
-# SDK and CLI
+# SDK and CLI reference
 
-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.
+This index is the entry point to the authoritative subharness contracts. The TypeScript SDK supports application-owned execution and connections to the shared local coordinator. The CLI lets a coding agent or developer run native harnesses directly, reuse specialists, and coordinate sessions, queues, responses, and approvals.
 
-- [Distribution](distribution.md): package identity, local installation, and release boundaries.
+## SDK API
+
+- [Connected and embedded execution](execution.md): client and runner ownership, sessions, tasks, complete responses, approvals, and hosted delegation.
+- [Agent definitions](agent.md): package exports, fields, harness options, and definition examples.
+- [Custom tools](tools.md): validated application functions exposed through native harness integrations.
+- [Subagents](plugins/sub-agents.md): nested delegation, lineage, context, and result-delivery boundaries.
+
+## CLI
+
+- [CLI](cli/index.md): commands, input, admission, waiting, follow-ups, control, and native permission responses.
+- [CLI output](cli/output.md): compact text, typed JSONL records, states, and exit codes.
+- [Dashboard presentation](cli/dashboard-design.md): the read-only live terminal hierarchy and interaction contract.
+- [Agent discovery](config.md): repository and global definitions, naming, and personal worktree settings.
 - [Agent skill](agent-skill.md): the installable skill that teaches a coding agent to delegate with the CLI.
-- [Agent definitions](agent.md): package exports, fields, harness options, and examples.
-- [Custom tools](tools.md): validated tool functions exposed through native harness integrations.
-- [Discovery](config.md): repository/global definitions and personal worktree settings.
-- [Personal access](access-config.md): subscription discovery, explicit API keys, and project OIDC.
-- [Native permissions](permissions.md): session permission options, native limits, and background delegation.
-- [Permission requests](approvals.md): request-specific schemas, structured answers, and approval lifecycle.
-- [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.
-- [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.
-- [Response delivery](completion-notifications.md): return points and parent continuation.
-- [Runtime](v1-runtime.md): execution ownership, loading, limits, and failure handling.
-- [Native adapters](adapter-contract.md): integration behavior and capability limits.
 
-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.
+## Lifecycle and access
+
+- [Sessions](sessions.md): task identity, state, queue ownership, and recovery boundaries.
+- [Message delivery](message-delivery.md): queue, steer, interrupt, cancellation, and failure handling.
+- [Response delivery](completion-notifications.md): complete responses, return points, and parent continuation.
+- [Permission requests](approvals.md): request-specific CLI schemas, structured SDK actions, ownership, and lifecycle.
+- [Authentication](authentication.md): native credentials, subscriptions, billing, and trust boundaries.
+- [Personal access configuration](access-config.md): subscription discovery, explicit API keys, project OIDC, and local renewal.
+- [Native permissions](permissions.md): session policies, native limits, and background delegation.
+- [Error diagnostics](diagnostics.md): safe failure context and recovery guidance.
+- [Distribution](distribution.md): package identity, installation, verification, and release boundaries.
+- [Harness selection](harnesses.md): supported targets, capabilities, and fallback boundaries.
 
-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.
+## Harness details
+
+- [Additional native harnesses](additional-harnesses.md): shared configuration for OpenCode, GitHub Copilot, and Cursor.
+- [fx](fx.md): fx ACP behavior, tools, access, permissions, and lifecycle.
+- [OpenCode](opencode.md): OpenCode integration and supported access routes.
+- [GitHub Copilot](copilot.md): Copilot integration and supported access routes.
+- [Cursor](cursor.md): Cursor subscription and API-key integration boundaries.
+
+## Maintainer internals
+
+- [Native adapter contract](adapter-contract.md): integration behavior and capability limits.
+- [v1 runtime](v1-runtime.md): execution ownership, loading, limits, and failure handling.
+- [Dashboard inspection](cli/dashboard-inspection.md): coordinator projection used by the terminal dashboard.
+- [Evaluations](evals.md): maintained evaluation inputs and scoring boundaries.
+- [Repository agent team](project-team.md): reusable roles used to develop this project.
+- [PR integration](pr-integration.md): reviewed-head and integration requirements.
+
+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.

package/sdk/message-delivery.md

@@ -1,5 +1,7 @@
 # Message Delivery
 
+The [execution SDK](execution.md) binds these queue, steer, interrupt, and cancellation semantics to session/task handles. Observer abortion detaches observation; it does not cancel work. Session or embedded-runner close stops owned execution explicitly; connected-client disconnect does not.
+
 `subharness send <session-id> --delivery <queue|steer|interrupt> [--detach] --prompt <text>` controls delivery. `queue` is the default. Each session has one active library task and a FIFO queue; a library task can contain multiple native turns while coordinating descendants.
 
 | Mode | Effect |

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,8 @@
 # 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 [execution SDK](execution.md) uses the same native permission options. Embedded SDK-hosted declared-child tools receive native custom-tool permissions; they do not install CLI launcher shell rules. Host callbacks are trusted application code and are not confined by a native sandbox.
+
+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 +23,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 +66,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/plugins/sub-agents.md

@@ -1,5 +1,7 @@
 # Subagents
 
+The invocation rules below describe CLI-hosted sessions. The [execution SDK](../execution.md) also supports in-memory definitions through explicitly hosted delegation tools, with private parent binding and the same task lineage/completion semantics. Embedded SDK sessions do not create or require the CLI launcher, its shell grants, or a coordinator service. Native adapter transport and permission limits still apply.
+
 An agent's optional `subagents` map declares and authorizes the agents it can invoke. Values are ordinary `AgentDefinition` objects; children can have their own subagents. Declaration alone does not execute them or register them in a repository/global catalog.
 
 ```ts
@@ -29,9 +31,9 @@ The launcher restores its coordinator location and parent context before invokin
 
 For Claude Code, declaring at least one subagent adds native permission rules for the current session's exact launcher. Equivalent quoted or unquoted spellings are allowed only when they identify the same literal executable. These rules authorize `run subagent:<name>` for the declared names, plus the CLI's `list`, `--help`, `send`, `wait`, `status`, `queue`, `cancel`, and `resume` operations. They do not authorize launching repository or global agents through `run`, another executable, or arbitrary shell commands. Follow-up and observation commands retain their documented identifier-based behavior; the permission rules do not introduce a new task-access policy.
 
-The adapter combines these rules with declared custom-tool permissions. Those rules do not write user/project permission settings or change the native permission mode; explicit constructor options independently select session permission settings as defined in [Native Permissions](../permissions.md). Native deny rules, explicit approval requirements, managed policy, and sandbox restrictions remain authoritative. A request that still requires approval returns `INPUT_REQUIRED`. Each child starts with its own native tool permissions; permission to launch it does not grant permission for its edits or shell commands. A session without declared subagents receives no delegation rules. If a launcher path cannot be represented as a literal command in the native permission syntax, startup fails with `INVALID_CONFIG` rather than adding a broader rule.
+The adapter combines these rules with declared custom-tool permissions. Those rules do not write user/project permission settings or change the native permission mode; explicit constructor options independently select session permission settings as defined in [Native Permissions](../permissions.md). Native deny rules, explicit approval requirements, managed policy, and sandbox restrictions remain authoritative. Supported permission requests during an active turn use the [structured approval flow](../approvals.md); unsupported interactive input and startup-time requests fail with `INPUT_REQUIRED`. Each child starts with its own native tool permissions; permission to launch it does not grant permission for its edits or shell commands. A session without declared subagents receives no delegation rules. If a launcher path cannot be represented as a literal command in the native permission syntax, startup fails with `INVALID_CONFIG` rather than adding a broader rule.
 
-Codex receives the same declared-child instructions and private launcher, but the adapter does not add native allow rules for them. Codex must already have effective permission to execute the launcher, read the files needed by that execution, and contact the coordinator. Native behavior differs across Codex versions, managed policies, sandbox configurations, and host environments. In some combinations, commands that access protected locations such as `.subharness/`, execute the private launcher, or use loopback networking can require approval or remain unavailable; this is an environment-dependent limitation, not a universal Codex rule. A resulting approval request returns `INPUT_REQUIRED`, including when the requested command would launch an authorized declared child. The library does not automatically approve the request, disable sandboxing, or replace shell delegation with another transport.
+Codex receives the same declared-child instructions and private launcher, but the adapter does not add native allow rules for them. Codex must already have effective permission to execute the launcher, read the files needed by that execution, and contact the coordinator. Native behavior differs across Codex versions, managed policies, sandbox configurations, and host environments. In some combinations, commands that access protected locations such as `.subharness/`, execute the private launcher, or use loopback networking can require approval or remain unavailable; this is an environment-dependent limitation, not a universal Codex rule. Supported permission requests during an active turn use the [structured approval flow](../approvals.md), including requests to launch an authorized declared child; unsupported interactive input and startup-time requests fail with `INPUT_REQUIRED`. The library does not automatically approve the request, disable sandboxing, or replace shell delegation with another transport.
 
 For every harness, the native execution environment must allow the CLI to read its private launcher and contact the coordinator over loopback HTTP. A native sandbox that blocks local networking also blocks CLI delegation. The library does not relax that policy automatically; the caller supplies explicit native permission options, native settings, or an external execution environment. A lead can instead own independent review outside a managed agent's native delegation flow when the environment cannot grant these prerequisites.
 

package/sdk/project-team.md

@@ -1,6 +1,6 @@
 # Repository Agent Team
 
-This repository keeps six reusable agents in `.subharness/agents/`. An agent defines a stable responsibility, model, and tool access. A skill supplies task-specific instructions that the agent reads when relevant. Adding a technique or library does not require another agent definition.
+This repository keeps nine reusable agents in `.subharness/agents/`. An agent defines a stable responsibility, model, and tool access. A skill supplies task-specific instructions that the agent reads when relevant. Adding a technique or library does not require another agent definition.
 
 ## Roles
 
@@ -9,6 +9,9 @@ This repository keeps six reusable agents in `.subharness/agents/`. An agent def
 | `architect` | Codex, `gpt-6-astra`, high effort | Evaluate architecture and API decisions; develop requested design concepts and assets; perform independent visual review when assigned. |
 | `developer` | Codex, `gpt-5.6-sol`, high effort | Implement documented behavior and application structure with focused TDD and independent review. |
 | `visual-engineer` | fx, `anthropic/claude-fable-5.1`, native default effort | Implement approved interface styling and native vgpu/WGSL effects using the relevant skill. |
+| `api-researcher` | Codex, `gpt-5.6-luna`, low effort | Collect primary-source API evidence: signatures, defaults, events, errors, and lifecycle rules. |
+| `systems-researcher` | Codex, `gpt-5.6-luna`, low effort | Collect evidence from related systems, including job queues, process runners, event streams, actors, and UI state synchronization. |
+| `planner` | Codex, `gpt-6-astra`, high effort | Turn settled contracts into bounded implementation assignments and verification criteria in ignored scratch files. |
 | `researcher` | fx, `google/gemini-3.8-flash`, native default effort | Answer a bounded technical or design question with primary-source evidence. |
 | `reviewer` | Claude Code, `claude-opus-5[1m]`, high effort | Independently review correctness, lifecycle, credential routing, and contract compliance without editing files. |
 | `integrator` | Codex, `gpt-5.6-sol`, high effort | Merge only the exact PRs and reviewed heads explicitly authorized by the lead for the current assignment, following [PR integration](pr-integration.md). |
@@ -21,6 +24,20 @@ 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.
+
+## Assigning work by complexity
+
+Use `api-researcher` for bounded source searches and API inventories. Use `systems-researcher` for related problems outside agent orchestration. Both use the explicitly selected Codex model, read `.agents/skills/source-research/SKILL.md`, and write only the caller-named files under `.context/research/`. Their output records source URLs or paths, retrieval dates, revisions, observed behavior, and uncertainty. They distinguish facts from inference, do not rank architectural alternatives or settle contracts, and return missing evidence to the lead. The existing fx `researcher` remains available for general technical and visual evidence tasks. The two research roles have different standing evidence responsibilities: `api-researcher` inventories caller-visible interfaces, while `systems-researcher` investigates ownership, failure handling, delivery, and retention across related domains. Keeping those lenses explicit helps a design survey cover both interface conventions and operational behavior. Individual libraries and technologies remain task inputs, not additional permanent roles.
+
+Use `architect` for reasoning across that evidence, including API alternatives with concrete signatures and usage examples, lifecycle ownership, cancellation, errors, compatibility, and misuse cases. Recommendations do not authorize implementation. The lead settles clear choices under `AGENTS.md` and asks the human only for unresolved product tradeoffs or signatures outside delegated authority.
+
+Use `planner` only after the relevant decisions are settled in repository documentation. It reads the actual affected implementation and writes only the caller-named files under `.context/research/`. Its assignments identify the governing contracts, owned files, dependencies, behavior-focused failing tests, validation commands, and acceptance criteria. It reports missing decisions instead of choosing public behavior. Plans and progress records are scratch artifacts; they never replace repository contracts, authorize implementation, or become public documentation. The lead validates the assignments and owns task boundaries and implementation authorization.
+
+Use `developer` for implementation and bounded review fixes, and `reviewer` for independent review. Documentation work uses the existing developer or architect with an explicit file scope; it does not need another permanent role. Graphics-specific research uses the existing researcher with the graphics skill when relevant. The `api-researcher`, `systems-researcher`, and `planner` return results to the lead without delegation. The lead supplies bounded questions, sources or search angles, output paths, and stopping criteria so economical evidence collection does not turn into unbounded design work.
+
+These assignments express task complexity, not a guaranteed price or model benchmark. Models are fixed in definitions; there is no automatic routing based on a guessed task difficulty, silent fallback, or credential change. When the selected model or capability is unavailable, report that limitation to the lead. A follow-up can narrow an unanswered research question in the same session; a new independent angle gets a separate session.
+
 ## 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.
@@ -35,6 +52,9 @@ subharness run repo:architect --prompt "Read website/design.md and .agents/skill
 subharness run repo:visual-engineer --prompt "Use .agents/skills/web-interface/SKILL.md. Implement the hero layout documented in website/design.md. Limit changes to the hero styles."
 subharness run repo:developer --prompt "Use .agents/skills/web-interface/SKILL.md. Read website/design.md. Check the hero's semantic HTML and keyboard behavior without changing styles."
 subharness run repo:developer --prompt "Use .agents/skills/webgpu-graphics/SKILL.md. Read website/graphics.md. Verify the mascot camera's documented framing with focused tests."
+subharness run repo:api-researcher --prompt "Use .agents/skills/source-research/SKILL.md. Read sdk/sessions.md. Record official SDK cancellation signatures in .context/research/sdk-cancellation.md."
+subharness run repo:systems-researcher --prompt "Use .agents/skills/source-research/SKILL.md. Read sdk/message-delivery.md. Record queue and observer lifecycle evidence in .context/research/queue-lifecycle.md."
+subharness run repo:planner --prompt "Read sdk/sessions.md and sdk/message-delivery.md. Inspect src/runtime/coordinator.ts. Write bounded verification assignments for those settled contracts to .context/research/session-verification-plan.md."
 subharness run repo:researcher --prompt "Use .agents/skills/source-research/SKILL.md. Read sdk/fx.md and src/adapters/fx.ts. Explain cancellation behavior with file references."
 subharness run repo:reviewer --prompt "Review the mascot camera changes against website/graphics.md. Report actionable findings without editing files."
 ```
@@ -43,6 +63,10 @@ The website's illustrative conversation shows tasks delegated to Claude Code and
 
 ## Delegation and review
 
+Every implementation handoff and final PR review includes a file-purpose audit against the target branch. The planner includes this in acceptance criteria, the developer removes temporary artifacts from its changes, and the reviewer inspects the complete added and changed file inventory, including documentation and supporting files. Findings identify the file and why it has no lasting repository purpose. The lead verifies the final inventory before declaring the PR ready. A bounded review states its coverage; it does not establish that the whole PR has passed this audit.
+
+Temporary proposals, plans, progress logs, research notes, one-off diagnostics, and review output belong in ignored `.context/` files. Settled decisions belong in canonical documentation; superseded proposals and purposeless redirect stubs are removed. Intentional regression fixtures, maintained examples, evaluation tools, and product documentation remain repository assets. File purpose, rather than its name alone, determines whether it belongs in the final changes.
+
 CLI and runtime work uses the existing architect, developer, and reviewer roles. Separate developer sessions can own independent modules; scope and governing contracts distinguish their assignments without adding permanent roles. The architect evaluates native protocol constraints, the developer implements and integrates behavior with TDD, and the reviewer independently checks user-facing behavior, lifecycle, and credential routing. The lead coordinates contracts, assignments, and final verification. Implementation and fixes run through repository agents whenever supported, so follow-ups, queues, and review cycles exercise subharness itself. Reproducible coordination failures are evidence for library improvements under the same contract and review rules.
 
 Repository role instructions follow the same delegation preference as the public skill and managed child instructions: use one attached `run` through known host background-command controls, continue independent work, and collect its output. Use `--detach` followed later by `wait` when those controls are unavailable or uncertain. A hosted `run` already observes the first response and does not require a redundant `wait` or unconditional `status`. This preference does not authorize undeclared children or override a role's delegation restrictions.

package/sdk/sessions.md

@@ -1,5 +1,7 @@
 # Sessions and Tasks
 
+Applications can use the [execution SDK](execution.md) through an embedded runner or a connected client. Embedded records belong to the runner; connected records belong to the same shared coordinator as CLI records. Session close stops owned execution, while client disconnect releases observation without cancelling work.
+
 An agent definition describes reusable behavior. A session is one native conversation in a fixed execution directory. A task is a unit of work within that session. Tasks and sessions have separate opaque identifiers and are not shell process IDs.
 
 Each `run` creates a new session; `send` creates follow-up tasks or steers the active task. A session retains native conversation state and its loaded instructions, tools, and harness configuration between tasks. The external harness owns its context and compaction.

package/sdk/tools.md

@@ -1,5 +1,7 @@
 # Custom Tools
 
+With the embedded [execution SDK](execution.md), inline tool closures execute in the application process with its unchanged cwd and environment, rather than the CLI session worker. Captured application state remains live; callbacks may be shared across sessions. SDK cancellation drains admitted callbacks and does not force-stop arbitrary JavaScript.
+
 `tool({ description, inputSchema, execute })` defines a function that a native harness can invoke. The map key in `agent.tools` is its public name. Declaring a tool does not execute it.
 
 ```ts
@@ -27,7 +29,7 @@ All three fields are required. `description` is a nonempty string. `inputSchema`
 
 Validation runs before execution; invalid arguments never reach the function. Unsupported schemas fail during definition validation. Non-serializable or oversized outputs and thrown exceptions become tool errors. Tool results are limited to 1 MiB. Errors do not masquerade as successful outputs.
 
-Tools run in their session worker's execution directory with that worker's environment. The adapter registers them in a native namespace without replacing the harness's native tools or model loop. Declaring a custom tool authorizes that agent to invoke it. Native tool permission policies remain with the harness.
+Connected and CLI-hosted tools run in the retained definition graph owner's creation directory and environment. Managed children share that captured callback context even when their native harness uses a different requested directory; use explicit paths or arguments for child-specific operations. Embedded SDK-hosted closures use the application context described above. The adapter registers them in a native namespace without replacing the harness's native tools or model loop. Declaring a custom tool authorizes that agent to invoke it. Native tool permission policies remain with the harness.
 
 ## Image results
 
@@ -70,6 +72,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.

package/sdk/v1-runtime.md

@@ -1,10 +1,10 @@
 # V1 Runtime Contract
 
-The first usable version supplies a TypeScript definition SDK and the `subharness` CLI with Codex, Claude Code, and fx adapters. Other harnesses remain compatibility requirements outside this version's adapter set. The library coordinates existing harnesses; it does not implement a model loop, sandbox, worktree manager, or native permission system.
+The first usable version supplies a TypeScript definition and execution SDK and the `subharness` CLI with Codex, Claude Code, fx, OpenCode, GitHub Copilot, and Cursor adapters. The library coordinates existing harnesses; it does not implement a model loop, sandbox, worktree manager, or native permission system.
 
 ## Package and definitions
 
-The package is `subharness`, with the primary executable `subharness` and identical `agent` compatibility alias. Node.js 22.18 or newer is required. ESM exports include `agent`, `tool`, `toolResult`, `codex`, `claudeCode`, `fx`, and their definition/configuration types. The public SDK defines reusable specialists; direct CLI harness targets also execute without a definition. Execution in v1 uses the CLI. Definition objects have readonly configuration fields and no execution methods. They contain functions and schemas and are not a serialization format.
+The package is `subharness`, with the primary executable `subharness` and identical `agent` compatibility alias. Node.js 22.18 or newer is required. ESM exports include `agent`, `tool`, `toolResult`, `codex`, `claudeCode`, `fx`, `opencode`, `copilot`, `cursor`, and their definition/configuration types. The public SDK defines reusable specialists; direct CLI harness targets also execute without a definition. Execution uses either the CLI or the connected or embedded [execution SDK](execution.md). The SDK additionally exports the client, runner, handle, result, access, approval, and error types defined there. The daemon, worker, catalog, and launcher rules below describe CLI execution; an embedded runner owns its coordinator and inline tool closures in the host process, while a connected client shares the CLI coordinator. Definition objects have readonly configuration fields and no execution methods. They contain functions and schemas and are not a serialization format.
 
 ```ts
 import { agent, codex, claudeCode, tool } from "subharness";
@@ -20,7 +20,7 @@ Global definitions live in `~/.subharness/agents/`; repository definitions live
 
 Definitions are trusted executable TypeScript. Loading a catalog evaluates its modules, so callers must trust the selected project and global definition files. Imports resolve relative to each definition through normal Node package resolution, with TypeScript loading supplied by the CLI. Missing imports, invalid exports, and duplicate names fail with the source filename. A session retains its loaded instructions, tools, and harness configuration for follow-ups; new sessions load current definition sources.
 
-An omitted `--cwd` uses the command's working directory. `--prompt-file` paths resolve against the calling command's directory, independently of `--cwd`; files use UTF-8. Prompts must contain non-whitespace text and cannot exceed 1 MiB. One quoted positional prompt, `--prompt`, and `--prompt-file` are mutually exclusive. `--prompt-file -` reads bounded UTF-8 stdin to EOF and rejects a terminal input stream. Direct harness targets accept `--model` and `--effort` for `run` and `check`; specialist targets reject those overrides.
+An omitted `--cwd` uses the command's working directory. `--prompt-file` paths resolve against the calling command's directory, independently of `--cwd`; files use UTF-8. Prompts must contain non-whitespace text and cannot exceed 1 MiB. One quoted positional prompt, `--prompt`, and `--prompt-file` are mutually exclusive. `--prompt-file -` reads bounded UTF-8 stdin to EOF and rejects a terminal input stream. Direct harness targets accept `--model` for `run` and `check`. Codex, Claude Code, and fx also accept `--effort`; OpenCode, Copilot, and Cursor reject it. Specialist targets reject both overrides.
 
 `run` and task-creating `send` commands accept `--detach` with every prompt source. The option ends the requesting command's observation immediately after successful admission, so the command returns exactly the existing `started` record and exits `0`. The service explicitly completes that observation response; it does not rely on a caller abandoning a response body. Admission errors keep their records and exit codes, while later failures remain available through `wait` and `status`. Interrupt delivery confirms affected execution has stopped before replacement admission even when detached. Steering rejects `--detach` with `INVALID_ARGUMENT`. The option is an observation request and is never retained as session configuration.
 
@@ -28,7 +28,7 @@ An omitted `--cwd` uses the command's working directory. `--prompt-file` paths r
 
 An on-demand local coordinator owns sessions, queues, task relationships, and response records independently of individual CLI commands. It starts automatically; users do not install or manage a service. Each native session runs in a separate worker process whose working directory is the selected execution directory. Definition loading and custom tool execution in that worker use the same directory. Direct harness sessions carry a built-in target descriptor instead of a definition source reference and do not load TypeScript modules. They supply no specialist instructions, custom tools, or declared children; native instructions and project settings remain effective. Workers inherit the submitting environment, subject to the adapter's explicit authentication selection.
 
-`check` is a CLI startup probe rather than an execution operation. It resolves the target and access configuration as `run` does, opens the native session in an isolated worker, and closes it without admitting a task or calling the adapter's turn interface. Success is withheld until the isolated worker exits and adapter-owned native processes confirm termination. Cleanup failure or uncertain native termination produces an error; after a failed graceful close, worker termination remains bounded and retains the cleanup diagnostic. It does not expose an SDK execution method and does not require a coordinator for ordinary direct or specialist checks. Managed declared-child resolution still requires the active parent context used by `run`.
+`check` is a CLI startup probe rather than an execution operation. It resolves the target and access configuration as `run` does, opens the native session in an isolated worker, and closes it without admitting a task or calling the adapter's turn interface. Success is withheld until the isolated worker exits and adapter-owned native processes confirm termination. Cleanup failure or uncertain native termination produces an error; after a failed graceful close, worker termination remains bounded and retains the cleanup diagnostic. The connected SDK exposes its own startup probe as `client.agents.check` under the [execution contract](execution.md); neither probe submits a task. The CLI probe does not require a coordinator for ordinary direct or specialist checks. Managed declared-child resolution still requires the active parent context used by `run`.
 
 Readiness means only that the selected target's startup checks passed at that moment. It does not guarantee quota, successful task execution, shell or child-launch permissions, or continued availability, and it does not recursively check descendants. The probe may create an empty native conversation, a temporary session launcher, and adapter-owned temporary files. Loading personal access settings may update Git's local exclude file. Normal worker close removes library-owned temporary files. A removal failure is reported even though files can remain, and abrupt environment termination still cannot guarantee file cleanup.
 
@@ -66,13 +66,15 @@ Ordinary text/JSON tool results and complete responses are limited to 1 MiB. Ric
 
 A managed task cannot delegate follow-up work into its own session or an ancestor's session. Such an admission returns `INVALID_PARENT` before changing any execution: that queued work would otherwise wait for the very task whose completion depends on it. Invalid delegation and replacement requests never cancel existing work.
 
-Each candidate coordinator, rather than the CLI command that spawned it, holds an operating-system-backed startup lock from its final endpoint check through service startup and atomic endpoint publication. The lock is released automatically if the candidate exits. After acquiring it, a candidate retires without publishing when the retained endpoint gives an authenticated health response for the recorded coordinator instance. This prevents a caller exit or a later candidate from exposing competing endpoint publication.
+The CLI and connected SDK select the same coordinator directory: an explicit SDK `stateDirectory`, otherwise `AGENT_STATE_DIR`, otherwise `~/.subharness/state/shared`. Connection authenticates the instance and requires protocol version 1 with the applicable `sdk-v1` or `cli-v1` capability.
+
+Each candidate coordinator, rather than the CLI command that spawned it, holds an operating-system-backed startup lock from its final endpoint check through service startup and atomic endpoint publication. The lock is released automatically if the candidate exits. After acquiring it, a candidate retires without publishing when the retained endpoint gives a compatible authenticated health response for the recorded coordinator instance. It starts only when metadata is absent, or a well-formed stale record has a proven-dead owner and an unresponsive endpoint. Malformed, unauthorized, incompatible, or uncertain endpoints fail explicitly without replacement. This prevents a caller exit or a later candidate from exposing competing endpoint publication.
 
 Startup callers do not infer whether their candidate published from an endpoint observation and do not signal a candidate based on such an observation. When its startup deadline expires, a caller sends its candidate a private retirement request. The candidate serializes that request with its publication transition while it still owns the startup lock. If retirement wins, the candidate closes any service that was never published, releases startup ownership, and confirms that it cannot publish later. If publication wins, including when another caller has already admitted work, the candidate reports its published endpoint and remains running. The original caller then uses that endpoint instead of terminating the coordinator.
 
 Lock contention is bounded by the spawning command's startup deadline. Waiting for the candidate's publication-or-retirement response uses an additional fixed confirmation window, so command completion remains bounded. If the candidate does not respond, startup fails with `STARTUP_FAILED` stating that retirement could not be confirmed, and the caller leaves the candidate untouched. A later authenticated endpoint discovery may therefore find that candidate. An unconfirmed result never claims that the process stopped and never authorizes killing a potentially published coordinator.
 
-Coordinators leave endpoint records in place during shutdown. Legacy pathname lock artifacts do not grant startup ownership and are left untouched. An unavailable endpoint, an unrelated HTTP server on the recorded port, or a legacy record without the current authenticated instance identity does not suppress replacement startup. A replacement coordinator atomically overwrites the record, and tasks owned by a replaced coordinator are not reconstructed. An interrupted coordinator response is reported as unavailable without exposing native diagnostics or automatically repeating the request. Disconnecting an observer detaches that observation; it does not cancel execution.
+Coordinators leave endpoint records in place during shutdown. Legacy pathname lock artifacts do not grant startup ownership and are left untouched. An unavailable endpoint alone does not prove absence. A live or unknown owner, authentication failure, incompatible protocol, or instance mismatch forbids replacement startup. A permitted replacement atomically overwrites only a proven-stale record; tasks owned by the previous coordinator are not reconstructed. An interrupted coordinator response is reported as unavailable without exposing native diagnostics or automatically repeating the request. Disconnecting an observer detaches that observation; it does not cancel execution.
 A successful detached task-creation request ends its service observation explicitly after the admission record while the coordinator continues to own the task.
 
 Catalog discovery evaluates TypeScript in a short-lived process with the selected execution directory as its working directory. Module stdout and stderr are not mixed into CLI output. Session workers retain their loaded instructions, tools, and harness configuration. New sessions, including delegated child sessions, load the current definition source; the library does not serialize or freeze arbitrary TypeScript closures across sessions.

package/dist/cli/catalog.d.ts

@@ -1,26 +0,0 @@
-import { type ErrorInfo } from "../errors.js";
-import type { AgentReference, ExecutionReference } from "../runtime/types.js";
-export interface CatalogSnapshot {
-    entries: {
-        id: string;
-        name: string;
-        description: string;
-        scope: "repo" | "global";
-        file: string;
-    }[];
-    children: {
-        name: string;
-        description: string;
-    }[];
-}
-export type CatalogReply = {
-    result: CatalogSnapshot;
-    error?: never;
-} | {
-    result?: never;
-    error: ErrorInfo;
-};
-/** Definition modules run in their selected directory without sharing the CLI's output streams. */
-export declare function loadCatalog(cwd: string, parent?: ExecutionReference): Promise<CatalogSnapshot>;
-/** Declared-child lookup evaluates only the active parent's definition source. */
-export declare function loadDeclaredChildren(cwd: string, parent: AgentReference): Promise<CatalogSnapshot['children']>;

package/dist/cli/catalog.js

@@ -1,41 +0,0 @@
-import { fork } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { AgentError } from "../errors.js";
-/** Definition modules run in their selected directory without sharing the CLI's output streams. */
-export function loadCatalog(cwd, parent) {
-    return loadCatalogSnapshot(cwd, parent, true);
-}
-/** Declared-child lookup evaluates only the active parent's definition source. */
-export async function loadDeclaredChildren(cwd, parent) {
-    return (await loadCatalogSnapshot(cwd, parent, false)).children;
-}
-function loadCatalogSnapshot(cwd, parent, discover) {
-    return new Promise((resolve, reject) => {
-        const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
-        const child = fork(fileURLToPath(new URL(`./catalog-worker.${extension}`, import.meta.url)), [], {
-            cwd, env: process.env, stdio: ["ignore", "ignore", "ignore", "ipc"],
-            execArgv: extension === "ts" ? ["--import", import.meta.resolve("tsx")] : [],
-        });
-        let reply;
-        const failed = () => reject(new AgentError("INVALID_DEFINITION", "The agent catalog worker exited before returning its catalog."));
-        child.once("error", failed);
-        child.once("exit", () => {
-            if (!reply)
-                failed();
-            else if (reply.error)
-                reject(new AgentError(reply.error.code, reply.error.message));
-            else
-                resolve(reply.result);
-        });
-        child.once("message", (message) => {
-            reply = message;
-            child.send({ received: true }, (error) => { if (error)
-                child.kill(); });
-        });
-        child.send({ cwd, parent, discover }, (error) => { if (error) {
-            child.kill();
-            failed();
-        } });
-    });
-}
-//# sourceMappingURL=catalog.js.map