agentera 3.0.0-dev.15 → 3.0.0-dev.17

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.