agentera 3.0.0-dev.3 → 3.0.0-dev.30

package/bundle/references/adapters/runtime-lifecycle-adapters.yaml

@@ -0,0 +1,74 @@
+schema_version: agentera.runtimeLifecycleAdapters.v1
+status: migration_only_contract
+decision: 92
+authority: references/adapters/runtime-lifecycle-authority.yaml
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+categories:
+  - skills
+  - plugins
+  - hooks
+  - agents
+  - configuration
+  - enablement
+  - trust
+  - native_actions
+category_contract:
+  required_fields:
+    - capability
+    - evidence
+    - remediation
+  capabilities:
+    - repairable
+    - observable
+    - action_required
+    - unsupported
+    - unverified
+    - not_applicable
+  evidence_states:
+    - confirmed
+    - absent
+    - drifted
+    - shadowed
+    - denied
+    - unknown
+    - blocked_unowned
+    - unsupported
+    - not_applicable
+    - action_required
+  remediation_kinds:
+    - none
+    - repair
+    - action_required
+    - unavailable
+support_floor:
+  authority: references/adapters/runtime-lifecycle-authority.yaml#support_floor
+  required_category: skills
+  required_capability: repairable
+  unknown_or_unverified_required_detection_blocks: true
+  incomplete_required_diagnosis_blocks: true
+  unknown_or_missing_mandatory_evidence_blocks: true
+  denied_required_trust_blocks: true
+  known_false_presence_install_enable_is_diagnosed_degraded: true
+  not_applicable_only_for_unobserved_conditional_surface: true
+native_policy:
+  execution: forbidden
+  exact_action_required_only: true
+  install_update_enable_auth_trust_are_user_owned: true
+path_policy:
+  destination_templates_are_declarations: true
+  matching_ledger_required_for_existing_resources: true
+  equality_or_name_never_establishes_ownership: true
+  forbidden_destination_segments:
+    - cache
+    - caches
+    - cacheddata
+    - node_modules
+    - .npm
+    - .pnpm-store
+    - marketplace-cache
+known_caveats:
+  - Append-only ownership journal recovery accepts only a strict contiguous hash chain, ignores uniquely named non-authoritative publication temporaries, blocks malformed or disconnected final events, and re-observes every resource before retry.
+  - This contract is retained only for migration and minimum-cleanup readers; it declares no current runtime adapters or repository-native resources.
+shared_resources: []
+managed_resources: []
+adapters: []

package/bundle/references/adapters/runtime-lifecycle-authority.yaml

@@ -0,0 +1,62 @@
+schema_version: agentera.runtimeLifecycleAuthority.v1
+status: migration_only_authority
+decision: 92
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+adapter_contract: references/adapters/runtime-lifecycle-adapters.yaml
+native_resource_cleanup_contract: references/adapters/runtime-retired-resources.yaml
+canonical_skill:
+  path: ~/.agents/skills/agentera
+  required_for_support_floor: true
+projection_contract:
+  schema_version: agentera.runtimeLifecycleProjection.v1
+  snapshot_identity: deterministic_sha256
+  applicability:
+    - required
+    - conditional
+    - not_applicable
+  action_classes:
+    - repairable_owned
+    - manual_verification
+    - unobservable_gap
+  command_eligibility:
+    - preview
+    - apply
+    - manual
+    - diagnostic
+  shared_resource_rule: selected_and_required_by_at_least_one_selected_runtime
+evidence_contract:
+  mandatory_fields:
+    - host_present
+    - installed
+    - enabled
+    - trusted
+  values:
+    - true
+    - false
+    - unknown
+    - denied
+    - not_applicable
+  trust_policy: Trust is observed only; unknown trust must never be promoted to trusted.
+support_floor:
+  requirements:
+    - canonical_shared_skill_detected
+    - diagnosis_complete
+    - mandatory_evidence_resolved
+  evidence_rules:
+    unknown_or_missing_mandatory_blocks: true
+    denied_mandatory_trust_blocks: true
+    known_false_diagnoses_degraded:
+      - host_present
+      - installed
+      - enabled
+    not_applicable_scope: unobserved_conditional_surface_only
+  unmet_blocks_release: true
+active_runtimes: []
+historical_inputs:
+  - id: claude
+    purposes:
+      - consent_gated_historical_import
+migration_aliases:
+  cursor-agent:
+    runtime_id: cursor
+    surface_id: cli

package/bundle/references/adapters/runtime-lifecycle-operation-contract.yaml

@@ -0,0 +1,84 @@
+schema_version: agentera.lifecycleOperationContract.v1
+status: migration_only_contract
+decision: 92
+scope: runtime_neutral_filesystem_resources
+ownership:
+  manifest_schema: agentera.lifecycleOwnershipManifest.v1
+  ledger_schema: agentera.lifecycleOwnershipLedger.v1
+  owner: agentera
+  mutation_rule: A destination declaration is always required. Existing resources additionally require one matching whole-resource ledger record.
+  equality_rule: Content equality and resource names never establish ownership.
+  collision_rule: Pre-existing resources without matching ledger ownership are never replaced or removed.
+  identity_rule: Managed and published pending-create records bind the filesystem device and inode observed at publication.
+  removal_rule: Removal requires a matching whole-resource ledger identity and fingerprint, a pinned non-symlink parent, and Linux /proc/self/fd directory-relative access.
+  manual_review_guidance: The destination is not ledger-owned; review the collision manually. Agentera will not adopt it by name or equality.
+  interrupted_create_rule: A pending_create record may be finalized when its recorded identity and expected fingerprint match, or when the durable pre-create record survived and the exclusively declared resource is observed at the exact expected kind and fingerprint after restart.
+  journal_rule: Apply publishes fsynced append-only ledger snapshots atomically at final names and accepts only a contiguous sequence-one hash chain with no gaps, forks, duplicate sequences, digest mismatches, or disconnected events.
+  journal_statuses:
+    absent: No journal directory exists; preview remains zero-write and apply may publish sequence one.
+    clean: Every authoritative final event is complete, schema-valid, digest-valid, and connected; mutation may append the next sequence.
+    recoverable_terminal_tail: Exactly one syntactically incomplete final event follows the clean prefix with no successor; reads preserve the prefix but every mutation is blocked until the tail is resolved.
+    corrupt: Any malformed complete event, middle incomplete event, gap, fork, duplicate sequence, body or filename mismatch, digest mismatch, disconnection, or unsafe entry blocks every mutation.
+  recovery_rule: Restart ignores uniquely named non-authoritative publication temporaries, folds only the strict connected final chain, and re-observes each resource before retry; append never continues from a rolled-back prefix or past an unresolved final tail.
+resource_states:
+  - exact
+  - modified
+  - missing
+  - legacy
+  - symlinked
+  - wrong_type
+  - partial_managed
+  - unowned
+  - unsafe_path
+  - ambiguous_ownership
+plan_actions:
+  - create
+  - update
+  - remove
+  - finalize_ownership
+  - noop
+  - blocked_unowned
+  - action_required
+apply_results:
+  - applied
+  - noop
+  - failed
+  - blocked_unowned
+  - skipped_dependency
+  - action_required
+aggregate_rule: Required results other than applied or noop make the aggregate non_success.
+dependency_rule: Independent operations continue after failure. Dependents skip with their failed dependency IDs.
+retry_rule: Successful work replans to noop; pending and failed work retries from observed filesystem and ledger state.
+preview_policy:
+  mode: strictly_read_only
+  forbidden:
+    - filesystem mutation
+    - directory creation
+    - locks
+    - temporary target files
+    - ownership record writes
+    - caches
+    - telemetry
+    - native commands
+    - package managers
+    - authentication
+    - trust changes
+path_safety:
+  - Destinations must be absolute and contained by an explicit existing allowed root.
+  - Apply pins the allowed root and every parent through Linux /proc/self/fd, then revalidates directory identities at the final publication boundary.
+  - Parent symlink traversal, parent identity substitution, link-target escapes, target identity substitution, hard-linked files, wrong types, partial ownership, and ambiguous ownership require action or fail safely.
+publication_policy:
+  supported_platform: linux_proc_self_fd
+  unsupported_platform_result: action_required
+  apply_serialization: lifecycle apply prepares a complete fsynced uniquely named lock directory and atomically renames it into final position; a complete live preparation blocks contenders, and the immutable owner record binds token, PID, Linux boot ID, and /proc process start ticks.
+  lock_recovery: Malformed or incomplete final locks fail closed. A complete lock is stale only when boot ID or process start ticks prove that exact owner identity is gone; release verifies the full identity and token before removing the owner record and lock directory.
+  journal_publication: Event bytes are fsynced under a unique non-authoritative temporary name, hard-linked atomically to the exclusive final event name, and followed by directory fsync before temporary cleanup.
+  create_protocol: directory-relative exclusive no-follow creation with no sibling temporary path
+  owned_file_update_protocol: directory-relative no-follow open, ledger and observation identity match, descriptor-local fingerprint check, in-place descriptor write, and post-write path identity check
+  destructive_path_mutations: owned_removal_only
+  destructive_path_reason: Removal is limited to declared resources whose whole-resource ledger identity and fingerprint still match through a pinned parent; every weaker case fails closed.
+  cleanup_rule: Publication creates no sibling temporary entry and never unlinks a colliding or replaced path; approved cleanup may unlink only the validated owned resource.
+  crash_boundary: Creates and owned file updates preserve the never-overwrite-unowned invariant but are not promised crash-atomic; a recorded pending identity makes partial Agentera-created files retryable.
+native_policy:
+  install_update_auth_trust_operations: forbidden
+  trust_is_observed_only: true

package/bundle/references/adapters/runtime-retired-resources.yaml

@@ -0,0 +1,97 @@
+schema_version: agentera.nativeResourceCleanup.v1
+status: resource_retirement_contract
+decision: nksvqmnevm
+authority: references/adapters/runtime-lifecycle-authority.yaml
+operation_contract: references/adapters/runtime-lifecycle-operation-contract.yaml
+policy:
+  host_inventory_exposure: evidence_only
+  selection: native_agentera_resource_only
+  preview: strictly_read_only
+  apply_requires: explicit_approval
+  ownership: matching_whole_resource_ledger_identity_and_fingerprint
+  shared_configuration: action_required_without_key_level_ownership
+  forbidden_ownership_evidence:
+    - value_equality
+    - managed_marker
+    - resource_name
+    - file_equality
+  unsupported_platform_result: action_required
+accepted_host_evidence:
+  - host: codex
+    state: supported
+    proof: Codex loaded Agentera's specific canonical skill instructions and bootstrap command.
+  - host: cursor
+    state: supported
+    proof: Cursor loaded Agentera's specific canonical skill instructions and bootstrap command.
+  - host: opencode
+    state: supported
+    proof: OpenCode's native CLI listed /home/jgabor/.agents/skills/agentera/SKILL.md.
+  - host: copilot
+    state: supported_disabled
+    proof: Copilot's native CLI listed the canonical personal-agents skill; its disabled state is intentional.
+hosts:
+  - id: codex
+    display_name: Codex
+    support_status: supported
+  - id: cursor
+    display_name: Cursor
+    support_status: supported
+  - id: opencode
+    display_name: OpenCode
+    support_status: supported
+  - id: copilot
+    display_name: Copilot
+    support_status: supported_disabled
+  - id: claude
+    display_name: Claude Code historical migration
+    support_status: retired_historical
+resources:
+  - id: claude.agentera-skill-link
+    host: claude
+    kind: symlink
+    intent: remove
+    destination: "{home}/.claude/skills/agentera"
+    ledger_status: legacy
+    durable_proof: matching whole-resource legacy ledger identity and fingerprint
+    never_touch:
+      - "{home}/.claude/projects"
+      - "{home}/.claude/statsig"
+      - "{home}/.claude/settings.json"
+      - "{home}/.claude/settings.local.json"
+      - "{home}/.claude.json"
+      - "{home}/.claude/cache"
+      - "{home}/.claude/caches"
+      - "{home}/.claude/conversations"
+      - "{home}/.claude/credentials"
+    safety_note: Only the declared Agentera skill symlink may be removed, and only when a matching legacy ownership ledger still binds its identity and target fingerprint. Transcript, settings, credential, conversation, stats, cache, and ambiguous paths are never cleanup targets.
+  - id: codex.agent-descriptor
+    host: codex
+    kind: file
+    intent: remove
+    destination: "{home}/.codex/agents/{descriptor}.toml"
+    descriptors: [status, vision, discuss, research, plan, build, optimize, audit, document, profile, design, orchestrate]
+    ledger_status: managed
+    durable_proof: matching whole-resource ledger identity and fingerprint for each declared descriptor file
+    safety_note: Each descriptor is an independently owned file. A managed marker, descriptor name, or matching content never establishes ownership.
+configuration_inventory:
+  - id: codex.config.shell_environment_policy.set.AGENTERA_HOME
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: shell_environment_policy.set.AGENTERA_HOME
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required
+  - id: codex.config.agents.max_depth
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: agents.max_depth
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required
+  - id: codex.config.features.multi_agent_v2
+    host: codex
+    destination: "{home}/.codex/config.toml"
+    key: features.multi_agent_v2
+    durable_proof: key-level ownership ledger identity and fingerprint
+    ownership_available: false
+    result_without_proof: action_required

package/bundle/references/analysis/benchmark.md

@@ -23,6 +23,10 @@ contract validators, and runtime smoke checks.
 | --- | --- | --- | --- |
 | Startup state benchmark | `mage bench:startupState` | Measures how often Agentera CLI state reads are followed by raw artifact access during startup/state gathering. | Manual only; forbidden in normal CI. |
 
+Verification ownership, independent owner commands, mixed-file separation
+markers, conservative routing, and named execution-policy compositions live in
+[`verification-policy.yaml`](./verification-policy.yaml).
+
 The startup benchmark is an optimization signal for Decision 51 and Decision 52.
 It does not implement a startup state envelope or change runtime behavior.
 
@@ -83,11 +87,11 @@ Status interpretation is intentionally split:
 | No matching records | `sparse` / `no_matching_records` | Candidate storage was readable and schema-compatible, but no supported records were extracted. Treat this as sparse coverage evidence. |
 | Successful zero-record window | `ok` / `records_extracted` with `record_count: 0` and `error_count: 0` | Extraction succeeded, but the incremental benchmark window has no records after the previous watermark. Treat this as compatible successful behavior. |
 
-Current known runtime caveats are extraction caveats, not CLI behavior evidence:
-`claude-code` is degraded by `schema_divergent` with 4836 candidates, 0 records,
-and 2 errors; `github-copilot` is degraded by `schema_divergent` with 1
-candidate, 0 records, and 1 error; `opencode` currently contributes records;
-`codex` can validly report `ok` with zero records and zero errors for an empty
+Known active-runtime caveats are extraction caveats, not CLI behavior evidence:
+`cursor` is degraded by `schema_divergent` with 4836 candidates, 0 records,
+and 2 errors; `copilot` is degraded by `schema_divergent` with 1 candidate,
+0 records, and 1 error; `opencode` currently contributes records; `codex` can
+validly report `ok` with zero records and zero errors for an empty
 incremental window.
 
 Runtime-store runs are incremental by default. The first run for a runtime scope
@@ -121,7 +125,7 @@ Follow this loop:
    by `raw_artifact_access_after_cli_counts` when the read is not redundant yet
    but still happens after a successful CLI state call.
 4. Map each repeated raw read to the CLI state owner. Prefer enriching existing
-   routine commands or the `hej` composite startup result. Do not add Decision 43
+    routine commands or the `prime` composite startup result. Do not add Decision 43
    slash-route aliases as CLI commands.
 5. Make CLI completeness explicit. A startup-capable response should say whether
    it is complete for the requested capability, whether raw artifact reads are