agentera 3.0.0-dev.14 → 3.0.0-dev.16

package/bundle/references/adapters/runtime-adapter-characterization.md

@@ -1,79 +1,44 @@
-# Runtime Adapter Characterization
-
-Task 2 of `Deepen RuntimeAdapter Registry` records current behavior before any
-registry extraction. This is a characterization artifact, not the new registry.
-
-## Doctor Output
-
-Current JSON envelope fields are `schemaVersion`, `ok`, `installRoot`,
-`runtimes`, `summary`, and `smoke`. Each runtime result exposes `runtime`,
-`status`, `available`, `binary`, and `checks`. Each check exposes `name`,
-`status`, `message`, `source`, `path`, `gap`, and `details`.
-
-Primary pass messages by runtime:
-
-| Runtime | Primary check | Status | Message | Diagnostic label |
-|---------|---------------|--------|---------|------------------|
-| Claude Code | `CLAUDE_PLUGIN_ROOT` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| OpenCode | `plugin_file` | `pass` | `OpenCode plugin file is present` | none |
-| Copilot CLI | `AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-| Codex CLI | `config.AGENTERA_HOME` | `pass` | `runtime can reach shared Agentera helper scripts` | none |
-
-Current diagnostic labels that are intentionally public are `user_environment`,
-`runtime_config`, `bundle_packaging`, `command_drift`, `skill_path_drift`, and
-`validation_drift`.
-
-## Upgrade Planning
-
-Runtime-phase items currently expose `runtime`, `action`, `target`, `status`,
-and `message`; copy operations also expose `source`, and configure operations
-carry private `newText` until public JSON rendering strips it.
-
-Characterized runtime actions:
-
-| Runtime | Action | Target | Dry-run status | Apply behavior |
-|---------|--------|--------|----------------|----------------|
-| Claude Code | `configure` | none | `noop` | no local config write |
-| Codex CLI | `configure` | `~/.codex/config.toml` | `pending` | writes config, then reports `runtime update applied` |
-| Codex CLI | `copy-hooks` | `~/.codex/hooks.json` | `pending` | copies hooks, then reports `runtime update applied` |
-| Codex CLI | `copy-agent` | `~/.codex/agents/*.toml` | `pending` | copies managed capability descriptors, then reports `runtime update applied` |
-| Copilot CLI | `configure` | none | `noop` | no local config write; use per-invocation `AGENTERA_HOME` |
-| OpenCode | `copy-plugin` | `~/.config/opencode/plugins/agentera.js` | `pending` | copies plugin, then reports `runtime update applied` |
-| OpenCode | `copy-agent` | `~/.config/opencode/agents/agentera.md` | `pending` | copies single managed agent descriptor (D73), then reports `runtime update applied` |
-
-Package-phase items currently expose `runtime`, `action`, `command`, `status`,
-and `message`. Without `--update-packages`, package items are `skipped`; with it,
-Claude Code and OpenCode package commands become `pending` and apply through the
-external command runner. Copilot CLI and Codex CLI have no package command item in
-the current upgrade phase.
-
-## Lifecycle Validation
-
-Current pass output from `scripts/validate_lifecycle_adapters.py` is exactly:
-
-```text
-lifecycle adapter metadata ok
-```
-
-Current failure output begins with:
-
-```text
-lifecycle adapter validation failed:
-```
-
-Representative fail messages are characterized in `tests/test_runtime_adapters.py`:
-Copilot stale `lifecycleHooks`, unsupported hook event files, missing `preToolUse`
-artifact validation, Codex unsupported status values, malformed event containers,
-missing supported-event declarations, missing unsupported-event declarations, and
-missing `codex_hooks` limitation text.
-
-## Drift Inventory
-
-| Drift point | Decision | Before-migration handling |
-|-------------|----------|---------------------------|
-| duplicated runtime order appears in doctor, upgrade, and tests | `standardize` | Later registry extraction should define one runtime order and have consumers read it. |
-| upgrade package phase only manages Claude Code and OpenCode | `preserve` | This is current behavior, not a registry gap; Copilot CLI and Codex CLI package command support is separate future work. |
-| Codex supports hook events but shipped config wires only apply_patch validation | `preserve` | Keep the distinction between host support and shipped Agentera wiring. |
-| Claude lifecycle behavior is validated through native hook files, not lifecycle metadata | `defer` | Do not invent Claude lifecycle metadata in Task 2; decide during registry interface design. |
-| OpenCode session preload observes `session.created` but has no verified context injection path | `preserve` | Keep degraded preload semantics in docs and diagnostics. |
-| hard-gate docs only claim blocking for reconstructable OpenCode and Copilot candidates | `preserve` | Keep scoped claims; do not standardize to full hard-gate parity. |
+# Runtime adapter characterization
+
+The executable lifecycle contract is split deliberately:
+
+- `runtime-lifecycle-authority.yaml` owns active identities, surfaces, evidence,
+  support-floor rules, the Cursor alias, and retired inputs;
+- `runtime-lifecycle-adapters.yaml` owns the common eight-category adapter
+  claims and declared Agentera-managed resources;
+- `runtime-lifecycle-operation-contract.yaml` owns operation and ownership
+  semantics;
+- `runtime-retired-resources.yaml` owns bounded legacy cleanup;
+- `runtime-adapter-registry.yaml` retains host-event and behavioral parity facts
+  and must match the lifecycle authority's four identities.
+
+## Characterized identities
+
+| Runtime ID | Required host surface | Additional surface | Lifecycle source highlights |
+| --- | --- | --- | --- |
+| `opencode` | OpenCode host | — | plugin and single Agentera agent |
+| `codex` | Codex CLI | — | plugin hooks, copied hooks, capability TOML agents |
+| `cursor` | Cursor Agent CLI | Cursor IDE when observed | IDE plugin, hooks, and Agentera descriptor |
+| `copilot` | GitHub Copilot CLI | — | plugin manifests and lifecycle hooks |
+
+The inactive `cursor-agent` spelling identifies the Cursor CLI binary/source
+product only. Claude is absent from adapter records and can appear only in the
+retired cleanup or explicit historical-import contracts.
+
+## Diagnosis and remediation
+
+Every adapter reports `skills`, `plugins`, `hooks`, `agents`, `configuration`,
+`enablement`, `trust`, and `native_actions`. Evidence is read-only. Trust is
+never inferred. Managed repair is planned through the shared operation engine;
+native and user-owned work is returned as `action_required`.
+
+Preview has no side effects. Apply requires declared destinations and matching
+ownership-journal evidence, uses secure directory-relative publication on
+Linux, continues independent operations after failure, and converges on retry.
+
+## Validation
+
+`agentera check validate lifecycle-adapters` rejects identity drift, missing
+runtime/category/surface claims, unsafe destinations, unverified mandatory
+skills, missing package manifests, unbundled lifecycle sources, version drift,
+retired Claude manifests, and stale runtime-specific hook claims.

package/bundle/references/adapters/runtime-adapter-registry.yaml

@@ -1,88 +1,11 @@
 schema_version: agentera.runtimeAdapterRegistry.v1
-runtime_order:
-  - claude
+lifecycle_authority: references/adapters/runtime-lifecycle-authority.yaml
+adapter_record_order:
   - opencode
   - copilot
   - codex
   - cursor
-  - cursor-agent
 records:
-  - identity:
-      runtime_id: claude
-      display_name: Claude Code
-      adapter_family: native-plugin
-      support_status: supported
-    host_detection:
-      binary_names:
-        - claude
-      host_config_locations:
-        - CLAUDE_PLUGIN_ROOT
-      availability_probe_label: runtime_binary
-    lifecycle_events:
-      supported_events:
-        - PreToolUse
-        - PostToolUse
-        - UserPromptSubmit
-        - SessionStart
-        - Stop
-        - SubagentStop
-      unsupported_events: []
-      event_status:
-        PreToolUse: native
-        PostToolUse: native
-        UserPromptSubmit: native
-        SessionStart: native
-        Stop: native
-        SubagentStop: native
-      limitations:
-        - Claude lifecycle behavior is validated through native hook files rather than lifecycle metadata.
-    artifact_validation:
-      validation_events:
-        - PreToolUse
-      hard_gate_claims:
-        - Native hook files can run artifact validation before tool writes.
-      payload_reconstruction_limitations: []
-    subagent_dispatch:
-      mechanism: Claude Code native subagent dispatch
-      setup_targets: []
-      descriptor_sources: []
-      invocation_pattern: Use the host Task/subagent surface with the selected Agentera capability context.
-      tool_configuration: none
-      limitations:
-        - Agentera does not install per-capability Claude descriptors in this package phase.
-    config_targets:
-      runtime_config_files: []
-      hook_targets:
-        - .claude-plugin/marketplace.json
-      plugin_targets:
-        - skills/*/.claude-plugin/plugin.json
-      environment_exports:
-        - CLAUDE_PLUGIN_ROOT
-      write_safety_labels:
-        - Claude Code plugin installs expose the app home without local config writes
-    diagnostics:
-      check_names:
-        - CLAUDE_PLUGIN_ROOT
-      status_labels:
-        - pass
-        - warn
-        - fail
-        - skip
-      gap_labels:
-        - runtime_config
-        - user_environment
-      primary_messages:
-        - runtime can reach shared Agentera helper scripts
-        - Claude Code plugin root is not present in this process environment
-    documentation_claims:
-      reference_paths:
-        - references/adapters/runtime-feature-parity.md
-      parity_claims:
-        - Claude Code uses native plugin and hook surfaces.
-      install_claims:
-        - Claude Code plugin installs expose the app home without local config writes.
-      known_drifts:
-        - Claude lifecycle behavior is validated through native hook files, not lifecycle metadata.
   - identity:
       runtime_id: opencode
       display_name: OpenCode
@@ -189,7 +112,7 @@ records:
         - OpenCode session preload observes session.created but has no verified context injection path.
   - identity:
       runtime_id: copilot
-      display_name: Copilot CLI
+      display_name: GitHub Copilot
       adapter_family: portable-plugin
       support_status: supported
     host_detection:
@@ -271,9 +194,9 @@ records:
         - Upgrade runtime configure is noop; shell rc paths in host_detection are doctor diagnostic probes only.
   - identity:
       runtime_id: codex
-      display_name: Codex CLI
+      display_name: Codex
       adapter_family: portable-plugin
-      support_status: degraded
+      support_status: supported
     host_detection:
       binary_names:
         - codex
@@ -358,11 +281,12 @@ records:
         - Codex supports hook events but shipped config wires only apply_patch validation.
   - identity:
       runtime_id: cursor
-      display_name: Cursor IDE
+      display_name: Cursor
       adapter_family: native-plugin
       support_status: supported
     host_detection:
       binary_names:
+        - cursor-agent
         - cursor
       host_config_locations:
         - AGENTERA_HOME
@@ -461,89 +385,3 @@ records:
       known_drifts:
         - Release tagging and marketplace publication remain blocked pending broader release closeout despite passed live preToolUse Write smoke.
         - Cloud agents are unsupported in v1.
-  - identity:
-      runtime_id: cursor-agent
-      display_name: Cursor Agent CLI
-      adapter_family: portable-cli
-      support_status: degraded
-    host_detection:
-      binary_names:
-        - cursor-agent
-        - agent
-      host_config_locations:
-        - AGENTERA_HOME
-        - ~/.bashrc
-        - ~/.zshrc
-        - ~/.config/fish/config.fish
-      availability_probe_label: runtime_binary
-    lifecycle_events:
-      supported_events:
-        - sessionStart
-        - sessionEnd
-        - preToolUse
-        - postToolUse
-      unsupported_events:
-        - subagentStart
-        - subagentStop
-        - beforeSubmitPrompt
-        - preCompact
-        - stop
-      event_status:
-        sessionStart: degraded
-        sessionEnd: degraded
-        preToolUse: degraded
-        postToolUse: degraded
-      limitations:
-        - CLI sessions may not inherit IDE sessionStart env; persistent shell configuration is a fallback only when shell-tool smoke fails.
-        - Non-interactive print mode may hang after completion in some host builds; eval and smoke harnesses use bounded timeouts.
-        - Cloud agents are unsupported in v1.
-    artifact_validation:
-      validation_events:
-        - preToolUse
-      hard_gate_claims:
-        - CLI hook parity is degraded relative to IDE; hard-gate claims follow IDE smoke evidence only.
-      payload_reconstruction_limitations:
-        - CLI may omit hook wiring entirely when launched outside a Cursor workspace with project hooks.
-    subagent_dispatch:
-      mechanism: Cursor Agent CLI host-managed dispatch
-      setup_targets: []
-      descriptor_sources: []
-      invocation_pattern: Use cursor-agent with explicit capability context; managed .cursor/agents descriptors apply only when the workspace is loaded.
-      tool_configuration: global_full_access
-      limitations:
-        - Agentera does not install per-capability cursor-agent descriptors separately from IDE managed agents.
-    config_targets:
-      runtime_config_files: []
-      hook_targets: []
-      plugin_targets: []
-      environment_exports:
-        - AGENTERA_HOME
-      write_safety_labels:
-        - configure
-    diagnostics:
-      check_names:
-        - AGENTERA_HOME
-        - cursor-agent
-      status_labels:
-        - pass
-        - warn
-        - fail
-        - skip
-      gap_labels:
-        - runtime_config
-        - user_environment
-      primary_messages:
-        - runtime can reach shared Agentera helper scripts
-        - cursor-agent binary is not on PATH
-        - cursor-agent helper access depends on AGENTERA_HOME or shell rc configuration
-    documentation_claims:
-      reference_paths:
-        - references/adapters/runtime-feature-parity.md
-        - references/adapters/cursor.md
-      parity_claims:
-        - cursor-agent supports eval_skills --runtime cursor-agent print-mode dispatch.
-      install_claims:
-        - cursor-agent inherits IDE hook wiring only when run inside a workspace with installed Cursor surfaces.
-      known_drifts:
-        - CLI hook and session env parity is degraded relative to Cursor IDE.
-        - Bare text /agentera routing is metadata-only like Claude, Copilot, and Codex.

package/bundle/references/adapters/runtime-feature-parity.md

@@ -1,189 +1,121 @@
-# Runtime feature parity reference
-
-Tracks release-relevant runtime behavior for the portable agentera suite.
-
-This reference distinguishes implemented behavior from host support. A runtime
-may expose an event while agentera still lacks a shipped adapter path for it.
-
-## Summary
-
-| Runtime | Skill loading | Session preload | Artifact validation | Session bookmark |
-|---------|---------------|-----------------|---------------------|------------------|
-| Claude Code | Full: marketplace plugin and native skill paths load `skills/<name>/SKILL.md` | Active via `SessionStart` in `hooks/hooks.json` | Advisory after mutation via `PostToolUse` for `Edit` or `Write` | Active via `Stop` |
-| OpenCode | Full: native `skill` tool loads `.opencode`, `.claude`, and `.agents` skill paths | Deferred for session start: `session.created` is observable, but no model-context injection path is verified. Active for compaction through bounded `experimental.session.compacting` context from `agentera hej --format json`. | Conditional hard gate for reconstructable `write` and `edit` candidates via `tool.execute.before`; `tool.execute.after` remains advisory | Active via generic `event` hook on `session.idle` |
-| Copilot CLI | Full for portable skills through plugin or skill-folder install paths | Active via `sessionStart` | Conditional hard gate via `preToolUse` when `toolArgs` include path plus candidate content or exact replacement evidence | Active via `sessionEnd` |
-| Codex CLI | Full for portable skills through plugin install, `.agents/skills`, and `$skill` invocation | Not wired by the shipped hook config | Advisory `apply_patch` path validation through shipped PreToolUse and PostToolUse hooks; final patch content is not reconstructed | Not wired by the shipped hook config |
-| Cursor IDE | Full for portable skills through local plugin (`~/.cursor/plugins/local/agentera` via `.cursor-plugin/plugin.json`), repo-native surfaces, and upgrade-installed `.cursor/` targets | Active via `sessionStart` env export plus optional `additional_context` digest; plugin-root fallback when `AGENTERA_HOME` env and project walk-up fail (`hooks/cursor_session_start.py`) | Conditional hard gate for reconstructable `Write` and `Edit` candidates via `preToolUse`; verified after live preToolUse Write smoke (2026-05-24) | Active via `sessionEnd` |
-| Cursor Agent CLI | Full when workspace surfaces are installed; degraded when launched outside a Cursor project | Degraded relative to IDE sessionStart env export | Degraded hook parity; follows IDE smoke evidence only | Degraded relative to IDE `sessionEnd` wiring |
-
-## Profilera session corpus
-
-| Runtime | Local session mining | Evidence |
-| ------- | -------------------- | -------- |
-| Claude Code | Yes: `~/.claude/projects/**/*.jsonl` | `scripts/extract_corpus.py` |
-| Codex CLI | Yes: `~/.codex/sessions/**/*.jsonl` | `scripts/extract_corpus.py` |
-| OpenCode | Yes: `opencode.db` SQLite stores | `scripts/extract_corpus.py`, `references/adapters/opencode.md` |
-| Copilot CLI | Yes: `session-store.db` SQLite stores | `scripts/extract_corpus.py` |
-| Cursor IDE | Yes: `~/.cursor/projects/*/agent-transcripts/*/*.jsonl` | `scripts/extract_corpus.py`, `references/adapters/cursor.md` |
-| Cursor Agent CLI | Yes: gap-fill from `~/.config/cursor/chats/<md5(project)>/<session>/store.db` when no IDE JSONL exists | `scripts/extract_corpus.py`, `references/adapters/cursor.md` |
-
-## Bare `hej` routing
-
-| Runtime | Bare text `hej` behavior | Evidence |
-|---------|--------------------------|----------|
-| OpenCode | Deterministic exact-match adapter route through `chat.message`; only a complete lowercase text message `hej` is rewritten to load `agentera` and run the `agentera hej` dashboard path, accepting OpenCode's CLI-added single trailing newline as a transport artifact. | `.opencode/plugins/agentera.js`, `scripts/smoke_opencode_bootstrap.mjs`, OpenCode `packages/plugin/src/index.ts` Hooks interface |
-| Claude Code | Metadata/context only; `UserPromptSubmit` can observe or add context but is not a verified prompt rewrite router. | `skills/agentera/SKILL.md`, marketplace metadata |
-| Copilot CLI | Metadata/context only; skills, prompts, hooks, and plugins expose Agentera but do not guarantee pre-model bare-prompt routing. | `plugin.json`, `.github/plugin/plugin.json`, `.github/hooks` |
-| Codex CLI | Metadata/context only; `$agentera` is explicit and the legacy `$hej` bridge is not implicitly invocable. | `.codex-plugin/plugin.json`, `agents/openai.yaml` |
-| Cursor IDE | Metadata/context only; `beforeSubmitPrompt` is supported by the host but Agentera v1 does not rewrite bare `hej`. | `.cursor-plugin/plugin.json`, `.cursor/agents/*.md` |
-| Cursor Agent CLI | Metadata/context only like Claude, Copilot, and Codex. | `references/adapters/cursor.md`, eval runner metadata |
-
-## Artifact validation
-
-| Runtime | Blocking surface | Implemented gate | Evidence-insufficient paths | Verification surface |
-|---------|------------------|------------------|-----------------------------|----------------------|
-| Claude Code | None in shipped config; validation runs after `Edit` or `Write` | No pre-write hard gate is claimed | Any invalid artifact can already be written before the warning appears | `hooks/hooks.json`, `hooks/validate_artifact.py` |
-| OpenCode | `tool.execute.before` can throw before mutation | Invalid reconstructable artifact `write` and `edit` candidates are blocked | Sparse payloads and `apply_patch` `patchText` without reconstructed full content are allowed | `.opencode/plugins/agentera.js`, `scripts/smoke_opencode_bootstrap.mjs` |
-| Copilot CLI | `preToolUse` returns `permissionDecision: deny` | Invalid reconstructable artifact candidates are denied | Malformed, sparse, or non-reconstructable `toolArgs` are allowed | `.github/hooks/preToolUse.json`, `hooks/validate_artifact.py`, `tests/test_validate_artifact.py` |
-| Codex CLI | `codex_hooks` can run before and after `apply_patch` | No content hard gate is claimed; the copied user hook config parses touched paths and validates existing files; optional plugin-bundled hooks require `[features].plugin_hooks = true` plus `/hooks` review | Add-file targets and final post-patch candidate content are not reconstructed by the adapter | `~/.codex/hooks.json` generated by upgrade, `.codex-plugin/plugin.json` `hooks`, `hooks/codex-plugin-hooks.json`, `hooks/validate_artifact.py`, live apply_patch hook firing smoke |
-| Cursor IDE | `preToolUse` returns `permission: deny` when wired | Invalid reconstructable artifact candidates are denied; live preToolUse Write smoke passed 2026-05-24 | Malformed, sparse, or non-reconstructable tool_input payloads are allowed | `.cursor/hooks.json`, `hooks/cursor_pre_tool_use.py`, `hooks/validate_artifact.py`, `.agentera/smoke-cursor-pretooluse-evidence.txt` |
-| Cursor Agent CLI | None claimed for standalone CLI | No IDE-equivalent hard gate is claimed | CLI may run without project hook wiring | `scripts/eval_skills.py --runtime cursor-agent` |
-
-Docs may claim functional hard-gate parity only for closeable paths that are
-implemented and verified. Today that means OpenCode, Copilot, and Cursor IDE
-reconstructable artifact candidates. Claude Code and Codex remain active validation
-surfaces, but neither shipped configuration blocks every invalid artifact candidate
-before mutation.
-
-## Lifecycle notes
-
-| Runtime | Runtime reason for degraded or blocked capability |
-|---------|---------------------------------------------------|
-| OpenCode preload | The `event` hook observes `session.created`, but no supported adapter path injects text into model context. |
-| OpenCode compaction context | `experimental.session.compacting` appends bounded Agentera state from `agentera hej --format json`; the plugin does not read raw `.agentera` artifacts for compaction. |
-| OpenCode `apply_patch` hard gate | The adapter receives `patchText` without reconstructing full candidate content. It allows that path rather than guessing. |
-| Copilot sparse edits | Copilot `preToolUse` stdin may omit full content or unique old/new replacement evidence. The hook allows those payloads. |
-| Codex preload/bookmarks | `codex_hooks` supports lifecycle events, but Agentera ships only `apply_patch` PreToolUse/PostToolUse wiring for copied user hooks and optional plugin-bundled hooks. |
-| Codex artifact hard gate | The adapter parses patch headers for touched paths, but it does not reconstruct final candidate content for blocking validation. |
-| Codex plugin hook trust | Plugin-bundled hooks require `[features].plugin_hooks = true` and deliberate `/hooks` review; copied `~/.codex/hooks.json` remains the default reliable install path with generated `[hooks.state]` trust hashes. |
-| Cursor cloud agents | Cloud agents are unsupported in v1; repo hooks and managed agents target local IDE sessions only. |
-| Cursor CLI hook parity | `cursor-agent` print mode is eval-covered but hook/session env parity is degraded relative to IDE wiring. |
-| Cursor hard-gate release gate | Live preToolUse Write smoke passed 2026-05-24; release tagging and publication stay blocked pending broader release closeout. |
-
-## Subagent Dispatch
-
-| Runtime | Dispatch surface | Descriptor source | Tool Access | Verification surface |
-|---------|------------------|-------------------|-------------|----------------------|
-| Claude Code | Native Task/subagent surface | Host-managed; no Agentera descriptor files shipped for this phase | None (no descriptors) | RuntimeAdapter registry |
-| OpenCode | Single `agentera` primary agent with `general` subagent dispatch | `.opencode/agents/agentera.md`, bootstrapped by `.opencode/plugins/agentera.js` | Per-agent `permission` frontmatter (broad: write+bash allow) | `scripts/smoke_opencode_bootstrap.mjs`, `agentera validate descriptors` |
-| Copilot CLI | User-driven host action such as `/fleet` when available | Host-managed; no Agentera descriptor files shipped for this phase | N/A (no descriptors) | RuntimeAdapter registry |
-| Codex CLI | Native agent descriptors under `~/.codex/agents` or project `.codex/agents` with bounded `[agents]` settings | `skills/agentera/agents/*.toml`, installed by `scripts/setup_codex.py` and `agentera upgrade` | Global sandbox policy (no per-agent) | `agentera validate descriptors`, `tests/test_setup_codex.py`, `tests/test_upgrade_cli.py` |
-| Cursor IDE | Single `agentera` agent with `general` subagent dispatch | `.cursor/agents/agentera.md`, via local plugin or `agentera upgrade --runtime cursor` | Global full access (no per-agent) | `references/adapters/cursor.md`, `scripts/validate_lifecycle_adapters.py`, `tests/test_upgrade_cli.py` |
-| Cursor Agent CLI | Host-managed `cursor-agent -p` print mode | Workspace `.cursor/agents/*.md` when present; no separate CLI descriptor install | Global full access (no per-agent) | `scripts/eval_skills.py --runtime cursor-agent`, `tests/test_eval_skills.py` |
-
-Agentera v2 does not write legacy `[agents.<name>]` Codex config blocks. Capability dispatch must use runtime-native subagent descriptors or host Task surfaces, not unsupported `agentera <capability>` CLI commands.
-
-## Copilot install notes
-
-Recommended marketplace install:
+# Runtime feature parity
 
-```bash
-copilot plugin marketplace add jgabor/agentera
-copilot plugin install <skill>@agentera
-```
+Release-relevant behavior is governed by
+`runtime-lifecycle-authority.yaml` and `runtime-lifecycle-adapters.yaml`.
+Active runtime IDs are exactly `opencode`, `codex`, `cursor`, and `copilot`.
 
-Umbrella install:
+`cursor-agent` is an inactive compatibility alias and Cursor CLI source-product
+name beneath the single `cursor` identity. It is never an active runtime ID.
+Claude Code is a retired migration and consent-gated historical-import source,
+not a supported runtime.
 
-```bash
-copilot plugin install jgabor/agentera
-```
+## Lifecycle identity and support floor
 
-The marketplace install path is verified working. Granular installs avoid
-umbrella discovery bug `github/copilot-cli#2390`.
+| Runtime | Required surface | Conditional surface | Canonical skill |
+| --- | --- | --- | --- |
+| OpenCode | host | — | `~/.agents/skills/agentera` |
+| Codex | CLI | — | `~/.agents/skills/agentera` |
+| Cursor | Agent CLI | IDE | `~/.agents/skills/agentera` |
+| GitHub Copilot | CLI | — | `~/.agents/skills/agentera` |
 
-Granular installs provide core `SKILL.md` behavior. App-home tools such as
-doctor, installer, validators, and shared setup helpers require the managed
-Agentera app or a local clone with the shared `scripts/` directory.
+The support floor requires the canonical skill, complete diagnosis, and
+resolved mandatory evidence. Unknown or missing mandatory evidence and denied
+trust block release. A known false installation or enablement state is
+diagnosed as degraded. An unobserved conditional Cursor IDE is
+`not_applicable` and does not block CLI support.
 
-Deprecated fallback: `copilot plugin install OWNER/REPO`, Git URLs, and local
-paths still work, but Copilot warns they are deprecated.
+`prime` projects a bounded summary from this lifecycle snapshot. `doctor`
+projects detailed evidence and exact actions from the same snapshot.
 
-## Cursor install notes
+## Common adapter contract
 
-**Local plugin (no Marketplace listing required)**
+Every active runtime reports the same eight categories:
 
-```bash
-git clone https://github.com/jgabor/agentera.git ~/.cursor/plugins/local/agentera
-# or: ln -s /path/to/agentera ~/.cursor/plugins/local/agentera
-```
+| Category | Meaning |
+| --- | --- |
+| skills | Canonical and additional skill discovery locations |
+| plugins | Agentera plugin package or host plugin state |
+| hooks | Session and tool lifecycle wiring |
+| agents | Runtime-native Agentera descriptors |
+| configuration | User or project configuration evidence |
+| enablement | Whether the host has enabled the integration |
+| trust | Observed trust state; never inferred or approved |
+| native actions | Exact user-owned host/package-manager steps |
+
+Each runtime/surface/category claim declares capability, evidence, and
+remediation. Unsupported or unverified host behavior cannot satisfy a mandatory
+support floor.
+
+## Host behavior
+
+| Runtime | Skill/package source | Hook and validation behavior | Agent behavior |
+| --- | --- | --- | --- |
+| OpenCode | Portable skill plus `.opencode/plugins/agentera.js` | Conditional hard gate for reconstructable write/edit candidates; sparse or unreconstructed patches remain advisory | Single Agentera descriptor in `.opencode/agents/agentera.md` |
+| Codex | `.codex-plugin/plugin.json`, shared skill, and marketplace entry | Plugin and copied-hook sources validate `apply_patch` paths before/after use; final patch content is not reconstructed | Capability TOML descriptors under `skills/agentera/agents/` |
+| Cursor | One identity spanning Agent CLI and optional IDE plugin | IDE hooks provide session context and conditional hard-gate validation for reconstructable Write/Edit candidates | One IDE Agentera descriptor; CLI uses the Cursor-owned binary surface |
+| GitHub Copilot | Root and repository plugin manifests | `sessionStart`, `sessionEnd`, `preToolUse`, and `postToolUse`; reconstructable candidates are denied before mutation | Host-managed dispatch; no Agentera-specific Copilot agent descriptor |
 
-Restart Cursor or run **Developer: Reload Window**. The plugin root must contain
-`.cursor-plugin/plugin.json`. Agentera is not published to the Cursor Marketplace
-yet.
+The validated hard-gate claims retain their exact scope:
 
-The plugin loads skills, managed capability agents, and hooks. When you open a
-project that is not an Agentera install root, `sessionStart` exports
-`AGENTERA_HOME` from the plugin checkout (including a plugin-root fallback when
-env and project walk-up do not resolve a managed root).
+- OpenCode: Conditional hard gate for reconstructable write and edit candidates. Sparse payloads and apply_patch patchText without reconstructed full content are allowed.
+- GitHub Copilot: Conditional hard gate via preToolUse. Malformed, sparse, or non-reconstructable toolArgs are allowed.
+- Cursor: Conditional hard gate for reconstructable Write and Edit candidates via preToolUse; verified after live preToolUse Write smoke (2026-05-24). Malformed, sparse, or non-reconstructable tool_input payloads are allowed.
 
-**Portable skill plus project upgrade**
+Agentera never upgrades a runtime binary, runs a native marketplace/package
+manager, authenticates, enables a plugin, or approves trust. Those operations
+are emitted as `action_required`.
 
-Install the bundled skill, then install managed project surfaces:
+## Lifecycle repair
 
 ```bash
-npx skills add jgabor/agentera -g -a cursor --skill agentera -y
-uv run scripts/agentera upgrade --runtime cursor --dry-run
-uv run scripts/agentera upgrade --runtime cursor --yes
-uv run scripts/agentera doctor --runtime cursor
+agentera upgrade --runtime all --dry-run
+agentera upgrade --runtime all --yes
 ```
 
-Use the plugin path for a user-global install. Use upgrade when you need
-project-committed `.cursor/hooks.json` and `.cursor/agents/` copies. Both paths can
-be combined.
+Preview is side-effect free. Apply is limited to declared Agentera-owned
+resources with matching ownership-journal evidence. Secure automatic
+publication currently requires Linux `/proc/self/fd`; other platforms receive
+the same plan as explicit actions.
 
-Repo-native dogfood in this repository uses committed `.cursor/hooks.json` and
-`.cursor/agents/*.md`. Other projects install managed surfaces with the upgrade
-commands above.
+Outcomes are `applied`, `noop`, `failed`, `blocked_unowned`,
+`skipped_dependency`, and `action_required`. Independent operations continue
+after a local failure, and retries re-observe state so completed work becomes
+`noop`.
 
-Cloud agents are unsupported in v1. Conditional hard-gate validation for IDE
-reconstructable Write and Edit candidates is verified after live preToolUse Write
-smoke (2026-05-24); release tagging and publication remain blocked until explicitly
-approved.
+## Corpus sources
 
-Eval coverage for automation uses:
+| Runtime identity | Source product | Default analytics |
+| --- | --- | --- |
+| Codex | Codex session JSONL | included |
+| OpenCode | OpenCode SQLite store | included |
+| Cursor | Cursor IDE JSONL | included |
+| Cursor | Cursor Agent CLI SQLite source (`cursor-agent`) | included as Cursor gap-fill |
+| GitHub Copilot | Copilot session SQLite store | included |
+| none | Claude Code JSONL | excluded; requires `--import-source claude` |
 
-```bash
-uv run scripts/eval_skills.py --runtime cursor-agent --dry-run
-```
+Claude imports use `historical_import` provenance and `active_runtime: false`.
+They never add Claude to runtime inventories, readiness, or default analytics.
+
+## Package release surface
+
+The npm bundle contains the shared skill and contract data plus every declared
+runtime source:
+
+- OpenCode package, plugin, command, and agent files;
+- Codex plugin manifest, plugin hooks, copied-hook fallback, and capability agents;
+- Cursor plugin manifest, IDE hooks, and agent descriptor;
+- GitHub Copilot root/repository manifests and lifecycle hook files.
+
+`.claude-plugin/marketplace.json` is retired and must not be packaged.
+
+## Validation boundary
+
+`agentera check validate lifecycle-adapters` validates:
 
-## Source of truth
-
-Runtime adapter facts are owned by the RuntimeAdapter registry at
-`references/adapters/runtime-adapter-registry.yaml` and loaded through
-`scripts/runtime_adapter_registry.py`. This reference may describe registry
-claims, but changes to runtime identity, lifecycle events, artifact-validation
-support, subagent dispatch, config targets, diagnostics, or documentation claims must be validated
-against the registry rather than duplicated here as an independent table.
-
-App-home classification is not runtime-specific. `scripts/install_root.py` is
-the shared Module for `AGENTERA_HOME`, the normal user data root, managed app,
-out-of-date app, unknown directories, and diagnostic semantics. Package metadata
-registry work stays outside both the RuntimeAdapter registry and this shared
-classification Module.
-
-| Surface | Path |
-|---------|------|
-| Shared artifact validator | `hooks/validate_artifact.py` |
-| Claude Code hook registry | `hooks/hooks.json` |
-| OpenCode plugin | `.opencode/plugins/agentera.js` |
-| OpenCode agent descriptors | `.opencode/agents/*.md` |
-| Copilot pre-write hook | `.github/hooks/preToolUse.json` |
-| Codex copied user hook config | `~/.codex/hooks.json` generated from `hooks/codex-hooks.json` with a resolved validator command |
-| Codex plugin hook config | `hooks/codex-plugin-hooks.json` via `.codex-plugin/plugin.json` `hooks` |
-| Codex agent descriptors | `skills/agentera/agents/*.toml` |
-| Cursor hook registry | `.cursor/hooks.json` |
-| Cursor agent descriptors | `.cursor/agents/*.md` |
-| Cursor plugin manifest | `.cursor-plugin/plugin.json` |
-| RuntimeAdapter registry | `references/adapters/runtime-adapter-registry.yaml` |
-| RuntimeAdapter registry loader | `scripts/runtime_adapter_registry.py` |
-| Lifecycle metadata validator | `scripts/validate_lifecycle_adapters.py` |
+- lifecycle authority and exact four-runtime identity parity;
+- all eight categories and every declared runtime surface;
+- package-manifest coverage for all active runtimes;
+- npm-bundle coverage for every lifecycle source and runtime manifest;
+- 3.0.0 version mirrors;
+- runtime-specific hook and documentation claims;
+- absence of retired Claude package manifests.