Merge pull request 'fix(v3.7.0): resolve issue #1500 - actor add --update flag enforcement' (#1513) from fix/1500-impl into master

- Add @tdd_issue_1500 to all 4 scenarios in
  features/actor_add_update_enforcement.feature so regression
  tests are correctly associated with the closed issue.
- Add robot/actor_add_update_enforcement.robot with 3 integration
  test cases: reject existing actor without --update (exit 1),
  accept existing actor with --update (exit 0), accept new actor
  without --update (exit 0).
- Add robot/helper_actor_add_update_enforcement.py with mock-based
  helper functions for all three test cases.

ISSUES CLOSED: #1500

CHANGELOG.md

@@ -6,6 +6,7 @@ Changed `wf10_batch.robot` to be less likely to create files, and
 `plan_generation_graph.robot` to give more test answers.
 
 ## [Unreleased]
+- **feat(cli): add `agents actor context show` command** (#6369 / PR #6622): Adds `agents actor context show <name>` to display a named actor context's summary, messages, metadata, state, and global context. Supports `--format` (rich/json/yaml/plain/table/color) and `--context-dir` options. Returns exit code 1 for non-existent contexts. Hoists `_default_context_base()` into the show module and re-imports it from `actor_context.py` to remove the duplicated base-path resolution. Adds `command=` kwargs to existing `_render_output` calls in `actor_context.py` so JSON/YAML envelopes report the originating subcommand.
 - **docs(spec): fix checkpoint config key path and trigger name defaults** (#5009 / PR #5163): Corrects the Configuration Reference table entry `sandbox.checkpoint.auto-create-on` → `core.checkpoints.auto-create-on`, matching the implementation in `config_service.py`. Aligns the default trigger-name values (`before_tool_execute`, `after_tool_execute`) with the implementation in `tool/runner.py`, resolving spec–implementation discrepancies identified in issue #5009.
 - **docs: module guides for Sandbox & Checkpoint, Correction Attempts, and Invariant Reconciliation** (#4848): Added three comprehensive module guides covering purpose, core classes, lifecycle diagrams, exception hierarchies, CLI usage, and ADR links for `SandboxManager`, `CorrectionAttemptManager`, and `InvariantReconciliationActor`. Includes security callouts for `NoSandbox` bypass (permanent writes, no rollback), `guidance` prompt-injection risk, `archived_artifacts_path` provenance, and `non_overridable` global invariant access control.
 - **feat(context): PriorityContextStrategy** (#9997 / PR #10772): Implements a priority-based context strategy that ranks context fragments by configurable priority scores — default role-based rules (system > tool > user > assistant), exponential recency decay (7-day half-life), and explicit priority tag boost. Supports custom scoring function injection and custom PriorityRule list injection. Registered in the ACMS pipeline under key `priority_context`. `PriorityRule` uses Pydantic `BaseModel` for architecture conformance. Includes 18 BDD scenarios covering all acceptance criteria.
@@ -303,6 +304,10 @@ ensuring data is stored with proper parameter values.
 
 - **Plan Rollback Command** (#8557): Implemented `agents plan rollback <plan-id> [<checkpoint-id>]` for checkpoint-based plan state restoration in Epic #8493. The command restores a plan's sandbox to the state captured at a given checkpoint, discarding all decisions made after that checkpoint. The checkpoint can be specified as an optional positional second argument or via the `--to-checkpoint` named option. Supports `--yes/-y` flag to skip confirmation prompts and `--format/-f` for output format selection (rich/plain/json/yaml). Included with comprehensive BDD test coverage (>= 97%) and spec-aligned output formatting showing rollback summary, changes reverted, impact analysis, and post-rollback state panels.
 
+### Fixed
+
+- **`agents actor add` enforces `--update` flag for existing actors** (#1500): Added regression tests to `features/actor_add_update_enforcement.feature` and step definitions in `features/steps/actor_add_update_enforcement_steps.py` verifying that re-adding an existing actor without `--update` fails, while re-adding with `--update` succeeds.
+
 ### Changed
 
 - **Expanded ruff lint scope to cover `.opencode/`** (#10848): The `lint` nox session
@@ -1227,6 +1232,13 @@ Documentation Report (Cycle N)` issues every 10 cycles (~3.3 hours). The manager
 
 ### Fixed
 
+- **Custom resource type YAML format** (#5622): Corrected three inconsistent YAML format
+  examples in `docs/specification.md` to match the canonical format defined in
+  `docs/schema/resource_type.schema.yaml`. Field names updated: `resource_kind`,
+  `cli_args`, `parent_types`, `capabilities.read/write/sandbox/checkpoint`,
+  `handler: module:ClassName`, and `child_types` as flat string list. Added documentation
+  explaining per-child-type auto-discovery configuration in the `auto_discovery` block.
+
 - **Plan Concurrency Race Condition** (#7989): Fixed critical race condition in `execute_plan()` and
   `apply_plan()` where concurrent CLI/worker sessions could simultaneously modify the same plan,
   corrupting plan state. `LockService` is now wired into the plan lifecycle with plan-level advisory
@@ -1399,4 +1411,4 @@ iteration` and data corruption under concurrent plan execution. All public
 - **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
   renders permission requests directly in the conversation stream for single-key
   operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
-  navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
+  navigate with arrow keys, confirm with `Enter`, or press `v` to open the full

CONTRIBUTORS.md

@@ -24,7 +24,7 @@
 # Details
 * HAL 9000 has contributed spec clarifications for layer boundary DI exception, ULID scope, ACMS pipeline contracts, and TUI component interfaces (PR #10451): documented architectural invariants including the DI container exception, clarified ULID identifier scope distinguishing domain entities from internal implementation details, added per-stage protocol contracts for all 10 ACMS pipeline stages with storage tier definitions, budget enforcement protocol, and context assembly output format, and defined public interfaces with verifiable checks for 8 TUI components.
 
-
+* HAL 9000 has contributed rename of `ActorSelectionOverlay._render` to `_refresh_display` to avoid shadowing Textual Widget internal method (PR #11042).
 
 Below are some of the specific details of various contributions.
 
@@ -37,6 +37,7 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the configurable agent limits refactor (#9246/#9050): replaced hardcoded ``deps[:10]`` in ``ContextAnalysisAgent`` and ``contexts[:5]`` in ``PlanGenerationGraph`` with validated constructor parameters ``max_dependencies`` (default: 10) and ``max_context_files`` (default: 5), including 12 BDD scenarios covering defaults, custom values, edge cases, and invalid-input error handling.
 * HAL 9000 has contributed the plan concurrency race-condition fix (#7989): wired `LockService` into the plan lifecycle, guarding `execute_plan()` and `apply_plan()` with plan-level advisory locks and unique per-invocation owner identities to prevent silent concurrent state corruption.
 * HAL 9000 has contributed the plan artifacts JSON completeness fix (#9084): ensured `validation_summary` and `apply_summary` are correctly included in `_build_artifacts_dict`, removing stale `@tdd_expected_fail` tags from Behave scenarios to enable full regression test coverage.
+* Jeffrey Phillips Freeman has contributed the InvariantService database persistence fix (PR #11166 / issue #8573): implemented SQLAlchemy-backed ``InvariantRepository``, added ``InvariantModel`` to the database models layer, created Alembic migration for the standalone ``invariants`` table, updated ``InvariantService`` with optional ``database_url`` parameter for cross-invocation persistence, and wired it into the application container (ADR-007 compliant).
 * HAL 9000 has contributed the bug-hunt-pool-supervisor non-blocking tracking fix (#7875 / PR #7957): updated step 5 to be best-effort and added rule 9 to prevent the automation-tracking-manager call from blocking the main supervisor loop.
 * Jeffrey Phillips Freeman has contributed the complete AUTO-BUG-SUP tracking prefix fix across agent-system-specification.md, automation-tracking.md documentation, replacing the incorrect `AUTO-BUG-POL` prefix with the correct `AUTO-BUG-SUP` prefix used by the bug-hunt-pool-supervisor agent (#7875).
 * HAL 9000 has contributed thread safety to InvariantService (issue #7524): added `threading.RLock` protection for all shared mutable state (_invariants dict, _enforcement_records list) across add, list, remove, effective-set computation, and enforcement operations, preventing RuntimeError: dictionary changed size during iteration in multi-threaded parallel plan execution environments.
@@ -55,6 +56,9 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the decision recording hook for the Strategize phase (issue #8522): captures every decision point with question, chosen option, alternatives, confidence, rationale, and full context snapshot for replay and correction.
 * HAL 9000 has contributed the ContextStrategy protocol and StrategyRegistry plugin registration system (PR #10590 / issue #8616): implemented the pluggable context assembly strategy protocol with proper type-safe method signatures, created the central thread-safe StrategyRegistry supporting registration, lookup, entry-point discovery, and per-strategy configuration (timeout, fragments limits, workers, circuit breaker threshold). Six built-in strategies implemented and documented: simple-keyword, semantic-embedding, breadth-depth-navigator, arce, temporal-archaeology, and plan-decision-context. Full BDD test coverage including thread safety, boundary validation, and error handling tests. (Part of Epic #8505)
 * HAL9000 has contributed automated implementation of ACMS context policy configuration loader and plan execution integration.
+* HAL 9000 has contributed automated bug fixes, security improvements, and migration safety enhancements including the migration prompt safe-default fix (#7503).
+* HAL 9000 has contributed the actor add --update flag enforcement tests and BDD coverage for issue #1500: added regression scenario tests verifying that re-adding an existing actor without `--update` fails, while re-adding with `--update` succeeds.
+
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the pr-review-pool-supervisor tracking prefix documentation fix (#7891): aligned all documentation references from the outdated `AUTO-REV-POOL` prefix to the correct `AUTO-REV-SUP` prefix used in production.
@@ -114,6 +118,7 @@ Below are some of the specific details of various contributions.
 * HAL 9000 has contributed the `plan apply --format json` spec-compliant envelope fix (PR #9817 / issue #9449): replaced raw plan dictionary output with a spec-required JSON envelope containing structured data fields for artifacts, changes, validation, sandbox cleanup, and lifecycle metrics across all output formats. Full BDD test suite in behave + Robot Framework integration tests added.
 * HAL 9000 has contributed the ContextTierService defaults fix (PR #1485 / issue #1443): corrected spec-aligned default values for `max_tokens_hot` (16000), `max_decisions_warm` (100), and `max_decisions_cold` (500) in ``context_tier_settings.py``. Added comprehensive BDD regression tests verifying all three interface contracts. (Parent Epic: #935)
 
+
 # Details (PR Contributions)
 
 Below are some specific details of individual PR contributions.

docs/specification.md

@@ -24676,17 +24676,16 @@ Custom resource types are defined in YAML configuration files and registered via
 <span style="color: cyan; font-weight: 600;">resource_type</span>:
   <span style="color: cyan; font-weight: 600;">name</span>: local/database
   <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;A SQL database (PostgreSQL, MySQL, SQLite, etc.)&quot;</span>
-  <span style="color: cyan; font-weight: 600;">physical_or_virtual</span>: physical
+  <span style="color: cyan; font-weight: 600;">resource_kind</span>: physical
   <span style="color: cyan; font-weight: 600;">user_addable</span>: <span style="color: magenta; font-weight: 600;">true</span>
 
 <span style="opacity: 0.7;">  # CLI arguments for `agents resource add local/database`</span>
-  <span style="color: cyan; font-weight: 600;">cli_arguments</span>:
+  <span style="color: cyan; font-weight: 600;">cli_args</span>:
     - <span style="color: cyan;">name</span>: connection-string
       <span style="color: cyan; font-weight: 600;">type</span>: string
       <span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">true</span>
       <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Database connection string (e.g., postgresql://host/dbname)&quot;</span>
-      <span style="color: cyan; font-weight: 600;">validation</span>:
-        <span style="color: cyan; font-weight: 600;">pattern</span>: <span style="color: #66cc66;">&quot;^(postgresql|mysql|sqlite)://&quot;</span>
+      <span style="color: cyan; font-weight: 600;">validation_pattern</span>: <span style="color: #66cc66;">&quot;^(postgresql|mysql|sqlite)://&quot;</span>
     - <span style="color: cyan;">name</span>: schema
       <span style="color: cyan; font-weight: 600;">type</span>: string
       <span style="color: cyan; font-weight: 600;">required</span>: <span style="color: magenta; font-weight: 600;">false</span>
@@ -24699,31 +24698,33 @@ Custom resource types are defined in YAML configuration files and registered via
 
 <span style="opacity: 0.7;">  # Sandbox and handler</span>
   <span style="color: cyan; font-weight: 600;">sandbox_strategy</span>: transaction_rollback
-  <span style="color: cyan; font-weight: 600;">handler</span>: DatabaseHandler
-  <span style="color: cyan; font-weight: 600;">checkpointable</span>: <span style="color: magenta; font-weight: 600;">true</span>
+  <span style="color: cyan; font-weight: 600;">handler</span>: myorg.handlers:DatabaseHandler
 
 <span style="opacity: 0.7;">  # Allowed parent types (empty means can be top-level)</span>
-  <span style="color: cyan; font-weight: 600;">allowed_parent_types</span>: []
+  <span style="color: cyan; font-weight: 600;">parent_types</span>: []
 
 <span style="opacity: 0.7;">  # Child types</span>
   <span style="color: cyan; font-weight: 600;">child_types</span>:
-    - <span style="color: cyan;">type</span>: local/db-schema
-      <span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: magenta; font-weight: 600;">true</span>
-      <span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
-      <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Discovered database schemas&quot;</span>
-    - <span style="color: cyan;">type</span>: local/db-table
-      <span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: magenta; font-weight: 600;">true</span>
-      <span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
-      <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Discovered tables within schemas&quot;</span>
+    - local/db-schema
+    - local/db-table
+
+  <span style="opacity: 0.7;">  # Per-child-type discovery configuration lives in `auto_discovery`</span>
+  <span style="color: cyan; font-weight: 600;">auto_discovery</span>:
+    <span style="color: cyan; font-weight: 600;">enabled</span>: <span style="color: magenta; font-weight: 600;">true</span>
+    <span style="color: cyan; font-weight: 600;">strategy</span>: schema_scan
+    <span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: magenta; font-weight: 600;">false</span>
+    <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">&quot;Automatically discover schemas and tables for child resources&quot;</span>
 
 <span style="opacity: 0.7;">  # Capabilities</span>
   <span style="color: cyan; font-weight: 600;">capabilities</span>:
-    <span style="color: cyan; font-weight: 600;">readable</span>: <span style="color: magenta; font-weight: 600;">true</span>
-    <span style="color: cyan; font-weight: 600;">writable</span>: <span style="color: magenta; font-weight: 600;">true</span>
-    <span style="color: cyan; font-weight: 600;">sandboxable</span>: <span style="color: magenta; font-weight: 600;">true</span>
-    <span style="color: cyan; font-weight: 600;">checkpointable</span>: <span style="color: magenta; font-weight: 600;">true</span>
+    <span style="color: cyan; font-weight: 600;">read</span>: <span style="color: magenta; font-weight: 600;">true</span>
+    <span style="color: cyan; font-weight: 600;">write</span>: <span style="color: magenta; font-weight: 600;">true</span>
+    <span style="color: cyan; font-weight: 600;">sandbox</span>: <span style="color: magenta; font-weight: 600;">true</span>
+    <span style="color: cyan; font-weight: 600;">checkpoint</span>: <span style="color: magenta; font-weight: 600;">true</span>
 </code></pre></div>
 
+The `auto_discovery` block replaces the former per-child `auto_discover` / `manual_link` YAML objects. Handlers expose their discovery knobs there while `child_types` remains a flat list of allowed resource type names.
+
 When this type is registered:
 <div class="highlight"><pre><code>
 agents resource type add <span style="color: cyan;">--config</span> ./resource-types/database.yaml
@@ -25210,11 +25211,11 @@ class ResourceTypeRecord {
   + name : String
   + description : String
   + source : String
-  + physical_or_virtual : PhysVirt
+  + resource_kind : PhysVirt
   + user_addable : Boolean
-  + cli_arguments : List<CLIArgument>
-  + allowed_parent_types : List<String>
-  + child_types : Map<String, ChildTypeConfig>
+  + cli_args : List<CLIArgument>
+  + parent_types : List<String>
+  + child_types : List<String>
   + sandbox_strategy : String
   + handler : String
   + capabilities : Capabilities
@@ -46864,11 +46865,11 @@ New resource types extend CleverAgents to manage any kind of resource:
 <span style="color: cyan; font-weight: 600;">resource_type</span>:
   <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">local/docker-registry</span>
   <span style="color: cyan; font-weight: 600;">description</span>: <span style="color: #66cc66;">"Docker container registry"</span>
-  <span style="color: cyan; font-weight: 600;">classification</span>: <span style="color: #66cc66;">physical</span>
+  <span style="color: cyan; font-weight: 600;">resource_kind</span>: <span style="color: #66cc66;">physical</span>
   <span style="color: cyan; font-weight: 600;">user_addable</span>: <span style="color: #66cc66;">true</span>
 
   <span style="color: cyan; font-weight: 600;">cli_args</span>:
-    - <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">registry_url</span>
+    - <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">registry-url</span>
       <span style="color: cyan; font-weight: 600;">type</span>: <span style="color: #66cc66;">string</span>
       <span style="color: cyan; font-weight: 600;">required</span>: <span style="color: #66cc66;">true</span>
     - <span style="color: cyan; font-weight: 600;">name</span>: <span style="color: #66cc66;">repository</span>
@@ -46879,16 +46880,16 @@ New resource types extend CleverAgents to manage any kind of resource:
       <span style="color: cyan; font-weight: 600;">default</span>: <span style="color: #66cc66;">"latest"</span>
 
   <span style="color: cyan; font-weight: 600;">sandbox_strategy</span>: <span style="color: #66cc66;">none</span>    <span style="color: #888;"># Docker images are immutable</span>
-  <span style="color: cyan; font-weight: 600;">handler</span>: <span style="color: #66cc66;">docker_registry_handler</span>
+  <span style="color: cyan; font-weight: 600;">handler</span>: <span style="color: #66cc66;">myorg.handlers:DockerRegistryHandler</span>
 
   <span style="color: cyan; font-weight: 600;">child_types</span>:
-    - <span style="color: cyan; font-weight: 600;">type</span>: <span style="color: #66cc66;">local/docker-image</span>
-      <span style="color: cyan; font-weight: 600;">relationship</span>: <span style="color: #66cc66;">contains</span>
-      <span style="color: cyan; font-weight: 600;">auto_discover</span>: <span style="color: #66cc66;">true</span>
+    - <span style="color: #66cc66;">local/docker-image</span>
 
+  <span style="opacity: 0.7;">  # Auto-discovery controls per-child discovery behavior</span>
   <span style="color: cyan; font-weight: 600;">auto_discovery</span>:
     <span style="color: cyan; font-weight: 600;">enabled</span>: <span style="color: #66cc66;">true</span>
     <span style="color: cyan; font-weight: 600;">strategy</span>: <span style="color: #66cc66;">list_tags</span>
+    <span style="color: cyan; font-weight: 600;">manual_link</span>: <span style="color: #66cc66;">false</span>
 </code></pre></div>
 
 #### Custom Index Backends

features/acms_context_add.feature

@@ -0,0 +1,131 @@
+@feature9982
+Feature: ACMS context add command with --tag and --policy flags
+  As a CleverAgents user
+  I want to index files into the ACMS context with tags and policy hints
+  So that I can organize and control how context is assembled
+
+  Background:
+    Given an acms context add test runner
+
+  # -- ChunkedFileTraverser unit tests --
+
+  Scenario: ChunkedFileTraverser indexes a single file
+    Given a temporary directory with a single Python file "main.py"
+    When I traverse the file with ChunkedFileTraverser
+    Then the acms traversal should yield 1 entry
+    And the acms entry path should be absolute
+    And the acms entry content should be non-empty
+    And the acms entry content_hash should be a valid SHA-256 hex string
+
+  Scenario: ChunkedFileTraverser indexes a directory recursively
+    Given a temporary directory with 3 Python files
+    When I traverse the directory recursively with ChunkedFileTraverser
+    Then the acms traversal should yield 3 entries
+    And all acms entry paths should be absolute
+
+  Scenario: ChunkedFileTraverser non-recursive directory indexing
+    Given a temporary directory with files in subdirectory
+    When I traverse the directory non-recursively with ChunkedFileTraverser
+    Then the acms traversal should yield only top-level files
+
+  Scenario: ChunkedFileTraverser attaches tags to entries
+    Given a temporary directory with a single Python file "tagged.py"
+    When I traverse with tags "api" and "core"
+    Then all acms entries should have tags ["api", "core"]
+
+  Scenario: ChunkedFileTraverser attaches policy to entries
+    Given a temporary directory with a single Python file "policy.py"
+    When I traverse with policy "strict"
+    Then all acms entries should have policy "strict"
+
+  Scenario: ChunkedFileTraverser reports progress via callback
+    Given a temporary directory with 5 Python files
+    When I traverse with a progress callback and chunk_size 2
+    Then the acms progress callback should have been called at least once
+    And the acms final progress call should report total 5
+
+  Scenario: ChunkedFileTraverser skips ignored files
+    Given a temporary directory with a Python file and a .pyc file
+    When I traverse the directory recursively with ChunkedFileTraverser
+    Then the acms traversal should yield only the Python file
+
+  Scenario: ChunkedFileTraverser skips files inside ignored directories
+    Given a temporary directory with a Python file and an ignored __pycache__ file
+    When I traverse the directory recursively with ChunkedFileTraverser
+    Then the acms traversal should yield only the visible Python file
+
+  Scenario: ChunkedFileTraverser skips files larger than max_file_size
+    Given a temporary directory with a single Python file "large.py"
+    When I traverse the file with max_file_size 1
+    Then the acms traversal should yield 0 entries
+
+  Scenario: ChunkedFileTraverser skips unreadable file metadata and content
+    Given a temporary directory with a single Python file "broken.py"
+    When I read the file with a mocked stat OSError
+    Then the acms read result should be skipped
+    When I read the file with a mocked read_text OSError
+    Then the acms read result should be skipped
+
+  Scenario: ChunkedFileTraverser raises FileNotFoundError for missing path
+    When I traverse a non-existent path with ChunkedFileTraverser
+    Then an acms FileNotFoundError should be raised
+
+  Scenario: ChunkedFileTraverser raises ValueError for invalid chunk_size
+    When I create a ChunkedFileTraverser with chunk_size 0
+    Then an acms ValueError should be raised mentioning "chunk_size"
+
+  Scenario: AcmsIndexEntry requires absolute path
+    When I create an AcmsIndexEntry with a relative path
+    Then an acms ValueError should be raised mentioning "absolute"
+
+  Scenario: AcmsIndexEntry rejects negative size_bytes
+    When I create an AcmsIndexEntry with size_bytes -1
+    Then an acms ValueError should be raised mentioning "non-negative"
+
+  # -- CLI integration tests --
+
+  Scenario: context add with --tag flag attaches tags
+    Given a mocked context service for acms add
+    And a temporary file "src/main.py" exists
+    When I invoke context add with path "src/main.py" and tag "api"
+    Then the acms context add command should succeed
+    And the acms output should mention "api"
+
+  Scenario: context add with multiple --tag flags
+    Given a mocked context service for acms add
+    And a temporary file "src/main.py" exists
+    When I invoke context add with path "src/main.py" and tags "api" and "core"
+    Then the acms context add command should succeed
+    And the acms output should mention "api"
+    And the acms output should mention "core"
+
+  Scenario: context add with --policy flag
+    Given a mocked context service for acms add
+    And a temporary file "src/main.py" exists
+    When I invoke context add with path "src/main.py" and policy "strict"
+    Then the acms context add command should succeed
+    And the acms output should mention "strict"
+
+  Scenario: context add with --no-recursive flag
+    Given a mocked context service for acms add
+    And a temporary directory "src/" with files
+    When I invoke context add with directory "src/" and --no-recursive
+    Then the acms context add command should succeed
+
+  Scenario: context add shows progress for directory indexing
+    Given a mocked context service for acms add
+    And a temporary directory "src/" with 3 files
+    When I invoke context add with directory "src/"
+    Then the acms context add command should succeed
+
+  Scenario: add_command persists paths when traversal raises
+    Given a mocked context service for acms add
+    And a temporary file "src/main.py" exists
+    When I call add_command with a mocked traverser ValueError
+    Then the acms programmatic context add should persist the file
+
+  Scenario: context add --help shows usage examples
+    When I invoke context add --help
+    Then the acms help output should contain "--tag"
+    And the acms help output should contain "--policy"
+    And the acms help output should contain "--recursive"

features/acms_read_file_coverage.feature

@@ -0,0 +1,20 @@
+Feature: ChunkedFileTraverser _read_file and add_command traversal coverage
+  Direct coverage for diff lines that the parallel test runner may not
+  reach via the acms_context_add.feature scenarios:
+    acms/index.py  lines 597-612  (_read_file stat + size-check + read_text)
+    context.py     lines 111-112  (add_command traverser invocation)
+
+  Background:
+    Given a temp file exists for read file coverage
+
+  Scenario: _read_file returns AcmsIndexEntry for a normal readable file
+    When I directly call _read_file with default traverser
+    Then the direct read file result should be an AcmsIndexEntry
+
+  Scenario: _read_file returns None when file exceeds max_file_size
+    When I directly call _read_file with max_file_size 1
+    Then the direct read file result should be None
+
+  Scenario: add_command invokes the real traverser for an existing path
+    When I call add_command with the real traverser and a mocked container
+    Then the mocked add_to_context should have been called

features/actor_add_update_enforcement.feature

@@ -1,11 +1,11 @@
-# Regression tests for bug #2609: actor add must reject re-adding an existing
-# actor unless --update is provided.
+# Regression tests for bug #1500/#2609: actor add must reject re-adding an
+# existing actor unless --update is provided.
 Feature: agents actor add enforces --update flag for existing actors
   As a user of the CleverAgents CLI
   I want `agents actor add` to fail with a clear error when re-adding an existing actor
   So that I cannot accidentally overwrite actor configurations without explicit intent
 
-  @tdd_issue @tdd_issue_2609 @tdd_issue_4178
+  @tdd_issue @tdd_issue_1500 @tdd_issue_2609 @tdd_issue_4178
   Scenario: Re-adding an existing actor without --update fails with error panel
     Given an actor add CLI runner where the actor already exists
     When I run actor add without the --update flag
@@ -14,7 +14,7 @@ Feature: agents actor add enforces --update flag for existing actors
     And the actor-add-enforcement output should contain "Use --update to replace the existing actor definition"
     And the actor-add-enforcement output should contain the registration timestamp
 
-  @tdd_issue @tdd_issue_2609 @tdd_issue_4178
+  @tdd_issue @tdd_issue_1500 @tdd_issue_2609 @tdd_issue_4178
   Scenario: Re-adding an existing actor without --update shows error status line
     Given an actor add CLI runner where the actor already exists
     When I run actor add without the --update flag
@@ -22,14 +22,14 @@ Feature: agents actor add enforces --update flag for existing actors
     And the actor-add-enforcement output should contain "Actor already registered"
     And the actor-add-enforcement output should contain "use --update to replace"
 
-  @tdd_issue @tdd_issue_2609 @tdd_issue_4178
+  @tdd_issue @tdd_issue_1500 @tdd_issue_2609 @tdd_issue_4178
   Scenario: Re-adding an existing actor with --update succeeds
     Given an actor add CLI runner where the actor already exists
     When I run actor add with the --update flag
     Then the actor-add-enforcement exit code should be 0
     And the actor-add-enforcement output should contain "Actor updated"
 
-  @tdd_issue @tdd_issue_2609 @tdd_issue_4178
+  @tdd_issue @tdd_issue_1500 @tdd_issue_2609 @tdd_issue_4178
   Scenario: Adding a new actor without --update succeeds
     Given an actor add CLI runner where the actor does not exist
     When I run actor add without the --update flag

features/actor_context_cmds.feature

@@ -135,3 +135,24 @@ Feature: Actor context clear, remove, export, and import commands
     And I import the context from that JSON file as "roundtrip"
     Then the context "roundtrip" should exist
     And the imported context should have the same messages as the original
+
+
+  # ── context show ───────────────────────────────────────────
+
+  Scenario: Show a context in rich format
+    Given an actor context named "docs" exists with messages
+    When I run actor context show "docs" without specifying format
+    Then the actor context show command should succeed
+    And the output should include a context summary for "docs"
+
+  Scenario: Show a context in JSON format
+    Given an actor context named "docs" exists with messages
+    When I run actor context show "docs" with format "json"
+    Then the actor context show command should succeed
+    And the output should contain valid JSON with key "context_summary"
+    And the JSON payload should list 3 messages
+    And the JSON payload metadata context_name should be "docs"
+
+  Scenario: Show non-existent context fails
+    When I run actor context show "ghost" that does not exist
+    Then the actor context show command should fail with exit code 1

features/context_policy_strategy_config.feature

@@ -0,0 +1,61 @@
+@context_policy @strategy_configuration
+Feature: Context Policy Strategy Configuration
+  As a CleverAgents developer
+  I want to configure context assembly strategies in context policy YAML
+  So that I can control how context is assembled during ACMS phases
+
+  Scenario: Create context policy with basic strategy
+    Given a context policy with strategy "basic"
+    When I validate the context policy
+    Then the policy strategy should be "basic"
+    And the policy should be valid
+
+  Scenario: Create context policy with semantic strategy
+    Given a context policy with strategy "semantic"
+    When I validate the context policy
+    Then the policy strategy should be "semantic"
+    And the policy should be valid
+
+  Scenario: Create context policy with relevance_scoring strategy
+    Given a context policy with strategy "relevance_scoring"
+    When I validate the context policy
+    Then the policy strategy should be "relevance_scoring"
+    And the policy should be valid
+
+  Scenario: Create context policy with adaptive strategy
+    Given a context policy with strategy "adaptive"
+    When I validate the context policy
+    Then the policy strategy should be "adaptive"
+    And the policy should be valid
+
+  Scenario: Create context policy with fusion strategy
+    Given a context policy with strategy "fusion"
+    When I validate the context policy
+    Then the policy strategy should be "fusion"
+    And the policy should be valid
+
+  Scenario: Reject invalid strategy name
+    Given a context policy with strategy "invalid_strategy"
+    When I validate the context policy
+    Then the policy should be invalid
+    And the strategy error should mention "Invalid strategy"
+
+  Scenario: Create context policy with strategy config
+    Given a context policy with strategy "semantic"
+    And strategy config with parameter "threshold" set to 0.5
+    When I validate the context policy
+    Then the strategy_config should contain "threshold"
+    And the strategy_config["threshold"] should be 0.5
+
+  Scenario: Create context policy without strategy
+    Given a context policy without strategy
+    When I validate the context policy
+    Then the policy strategy should be None
+    And the policy should be valid
+
+  Scenario: Create context policy with strategy but no config
+    Given a context policy with strategy "basic"
+    And no strategy config
+    When I validate the context policy
+    Then the strategy_config should be None
+    And the policy should be valid

features/conversation_state_management.feature

@@ -0,0 +1,82 @@
+Feature: Conversation state management
+  The ConversationStateManager separates persistent conversation history from
+  ephemeral execution state. Conversation history survives across runs while
+  execution state (current_node, execution_count, error) resets each time.
+
+  Scenario: Conversation history persists across execution resets
+    Given a ConversationStateManager with no initial state
+    When I append messages "hello" and "world" to the conversation history
+    And I reset the execution state
+    Then the conversation history should still contain 2 messages
+    And the execution count should be 0 after reset
+
+  Scenario: reset_execution_state clears only execution fields
+    Given a ConversationStateManager with no initial state
+    When I update the state with current_node "agent_a" and execution_count 5
+    And I append a message "keep me" to the conversation history
+    And I reset the execution state
+    Then the conversation history should contain the message "keep me"
+    And the current_node should be None after reset
+
+  Scenario: get_full_history returns all persistent messages
+    Given a ConversationStateManager with no initial state
+    When I append messages "first" and "second" and "third" to the conversation history
+    Then get_full_history should return 3 messages
+
+  Scenario: history property returns persistent conversation messages
+    Given a ConversationStateManager with no initial state
+    When I append a message "persistent" to the conversation history
+    Then the history property should contain the message "persistent"
+
+  Scenario: update_state with messages key appends to conversation history
+    Given a ConversationStateManager with no initial state
+    When I call update_state with messages containing "new message"
+    Then the conversation history should contain the message "new message"
+
+  Scenario: GraphState.to_graph_state returns conversation_history and execution_state keys
+    Given a GraphState with messages and metadata
+    When I call to_graph_state on the GraphState
+    Then the result should contain a conversation_history key
+    And the result should contain an execution_state key with current_node
+
+  Scenario: ExecutionState model holds execution-level fields
+    Given an ExecutionState with current_node "node_x" and execution_count 3
+    Then the ExecutionState current_node should be "node_x"
+    And the ExecutionState execution_count should be 3
+
+  Scenario: StateManager backward-compat alias works as ConversationStateManager
+    Given a StateManager created via the backward-compat alias
+    When I append a message "compat" to the conversation history via StateManager
+    Then the StateManager history property should contain the message "compat"
+
+  Scenario: append_messages evicts oldest entries when MAX_HISTORY_SIZE is exceeded
+    Given a ConversationStateManager with no initial state
+    When I append 55 messages to the conversation history
+    Then the conversation history should contain at most 50 messages
+    And the most recent messages should be retained
+
+  Scenario: Full reset clears both conversation history and execution state
+    Given a ConversationStateManager with no initial state
+    When I append a message "before reset" to the conversation history
+    And I update the state with current_node "some_node" and execution_count 5
+    And I perform a full reset
+    Then the conversation history should be empty after full reset
+    And the execution count should be 0 after full reset
+
+  Scenario: Bridge default update mode is APPEND
+    Given a RxPyLangGraphBridge instance
+    Then the default update mode should be APPEND
+
+  Scenario: Session full_history property returns all messages
+    Given a Session with two messages appended
+    Then the full_history property should return 2 messages
+
+  Scenario: Session get_messages with no limit returns full thread
+    Given a Session with three messages appended
+    When I call get_messages with no limit
+    Then all 3 messages should be returned
+
+  Scenario: Session append_message preserves full history
+    Given a Session with one existing message
+    When I append a second message to the session
+    Then the session should have 2 messages in total

features/event_bus.feature

@@ -118,6 +118,68 @@ Feature: EventBus protocol and domain event emission
   Scenario: EventBus Protocol emit and subscribe stubs are executable
     Then the EventBus Protocol stubs should be callable
 
+  # ---------------------------------------------------------------------------
+  # EventBus unsubscribe
+  # ---------------------------------------------------------------------------
+
+  Scenario: ReactiveEventBus.unsubscribe() removes a handler
+    Given a ReactiveEventBus
+    When I subscribe to "plan.created" events
+    And I unsubscribe from "plan.created" with the same handler
+    Then the handler count for "plan.created" should be 0
+
+  Scenario: ReactiveEventBus.unsubscribe() returns True when found
+    Given a ReactiveEventBus
+    When I subscribe to "plan.created" events
+    And I unsubscribe from "plan.created" with the same handler
+    Then unsubscribing should return True
+
+  Scenario: ReactiveEventBus.unsubscribe() returns False when not found
+    Given a ReactiveEventBus
+    Then unsubscribing a non-existent handler should return False
+
+  Scenario: ReactiveEventBus.unsubscribe() rejects invalid event_type
+    Given a ReactiveEventBus
+    Then unsubscribing with a non-EventType should raise TypeError
+
+  Scenario: ReactiveEventBus.unsubscribe() rejects non-callable handler
+    Given a ReactiveEventBus
+    Then unsubscribing with a non-callable handler should raise TypeError
+
+  Scenario: LoggingEventBus.unsubscribe() removes a handler
+    Given a LoggingEventBus
+    When I subscribe to "decision.created" events
+    And I unsubscribe from "decision.created" with the same handler
+    Then the handler count for "decision.created" should be 0
+
+  Scenario: LoggingEventBus.unsubscribe() returns True when found
+    Given a LoggingEventBus
+    When I subscribe to "decision.created" events
+    And I unsubscribe from "decision.created" with the same handler
+    Then unsubscribing should return True
+
+  Scenario: LoggingEventBus.unsubscribe() returns False when not found
+    Given a LoggingEventBus
+    Then unsubscribing a non-existent handler should return False
+
+  Scenario: LoggingEventBus.unsubscribe() rejects invalid event_type
+    Given a LoggingEventBus
+    Then unsubscribing with a non-EventType should raise TypeError
+
+  Scenario: LoggingEventBus.unsubscribe() rejects non-callable handler
+    Given a LoggingEventBus
+    Then unsubscribing with a non-callable handler should raise TypeError
+
+  Scenario: EventBus Protocol unsubscribe stub is callable
+    Then the EventBus Protocol unsubscribe stub should be callable
+
+  Scenario: Event bus supports selective unsubscription (only specific handler removed)
+    Given a ReactiveEventBus
+    When I subscribe two handlers to "plan.created" events
+    And I unsubscribe only the first handler from "plan.created"
+    And I emit a "plan.created" DomainEvent
+    Then exactly one handler should have received 1 event
+
   # ---------------------------------------------------------------------------
   # DecisionService event emission
   # ---------------------------------------------------------------------------
@@ -163,26 +225,3 @@ Feature: EventBus protocol and domain event emission
   Scenario: Container wires event_bus into DecisionService
     When I resolve decision_service from the DI container
     Then the decision_service should have an event_bus attribute
-
-  # ---------------------------------------------------------------------------
-  # ReactiveEventBus.close() and context manager (issue #10378)
-  # ---------------------------------------------------------------------------
-
-  Scenario: ReactiveEventBus.close() completes the RxPY stream
-    Given a ReactiveEventBus
-    When bus.close() is called on the bus
-    Then the bus should be marked as closed
-
-  Scenario: ReactiveEventBus.close() prevents further emit() calls
-    Given a ReactiveEventBus
-    When bus.close() is called on the bus
-    Then emitting after close should raise RuntimeError
-
-  Scenario: ReactiveEventBus.close() is idempotent
-    Given a ReactiveEventBus
-    When bus.close() is called twice on the bus
-    Then no exception should be raised on double close
-
-  Scenario: ReactiveEventBus supports context manager protocol
-    Given a ReactiveEventBus used as a context manager
-    Then the bus should be closed after the context exits

features/invariant_model.feature

@@ -1,59 +0,0 @@
-Feature: Invariant data model and database schema
-  As a developer
-  I want an Invariant SQLAlchemy model with a corresponding database schema
-  So that invariant rules can be persisted and queried efficiently
-
-  Background:
-    Given a fresh in-memory invariant database
-
-  Scenario: Create an Invariant with all required fields
-    Given a new Invariant with description "All plans must have a goal"
-    When I persist the Invariant
-    Then I can retrieve the Invariant by its ID
-    And the persisted Invariant description should be "All plans must have a goal"
-
-  Scenario: is_active defaults to True
-    Given a new Invariant with description "Default active invariant"
-    When I persist the Invariant
-    Then I can retrieve the Invariant by its ID
-    And the persisted Invariant is_active should be True
-
-  Scenario: created_at is auto-populated on insert
-    Given a new Invariant with description "Timestamped invariant"
-    When I persist the Invariant
-    Then I can retrieve the Invariant by its ID
-    And the persisted Invariant created_at should not be empty
-
-  Scenario: id is a UUID string
-    Given a new Invariant with description "UUID invariant"
-    When I persist the Invariant
-    Then I can retrieve the Invariant by its ID
-    And the persisted Invariant id should be a valid UUID
-
-  Scenario: description is required and cannot be empty
-    Given a new Invariant with an empty description
-    When I try to persist the Invariant
-    Then a ValueError should be raised for empty description
-
-  Scenario: Query active invariants
-    Given 3 active Invariants and 2 inactive Invariants
-    When I query Invariants filtered by is_active True
-    Then I should get 3 Invariants
-
-  Scenario: Query inactive invariants
-    Given 3 active Invariants and 2 inactive Invariants
-    When I query Invariants filtered by is_active False
-    Then I should get 2 Invariants
-
-  Scenario: Deactivate an Invariant
-    Given a persisted active Invariant
-    When I set is_active to False on the Invariant
-    Then the Invariant is_active should be False
-
-  Scenario: Migration upgrade creates invariants table
-    Given a fresh in-memory invariant database
-    Then the invariants table should exist
-
-  Scenario: Migration creates index on is_active
-    Given a fresh in-memory invariant database
-    Then the invariants table should have an index on is_active

features/steps/acms_context_add_steps.py

@@ -0,0 +1,584 @@
+"""Step definitions for ACMS context add command with --tag and --policy flags.
+
+All step names are prefixed with ``acms`` to avoid AmbiguousStep
+conflicts with existing steps.
+
+Issue #9982: feat(acms): implement context add CLI command for file and
+directory indexing.
+"""
+
+from __future__ import annotations
+
+import ast
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from behave import given, then, when
+from behave.runner import Context
+from typer.testing import CliRunner
+
+from cleveragents.acms.index import AcmsIndexEntry, ChunkedFileTraverser
+from cleveragents.cli.commands.context import add_command
+from cleveragents.cli.commands.context import app as context_app
+
+# ---------------------------------------------------------------------------
+# Background
+# ---------------------------------------------------------------------------
+
+
+@given("an acms context add test runner")
+def step_acms_runner(context: Context) -> None:
+    """Set up the CLI runner for ACMS context add tests."""
+    context.acms_runner = CliRunner()
+    context.acms_error: Exception | None = None
+    context.acms_entries: list[AcmsIndexEntry] = []
+    context.acms_progress_calls: list[tuple[int, int]] = []
+
+
+# ---------------------------------------------------------------------------
+# ChunkedFileTraverser unit tests
+# ---------------------------------------------------------------------------
+
+
+@given('a temporary directory with a single Python file "{filename}"')
+def step_acms_single_file(context: Context, filename: str) -> None:
+    """Create a temp dir with a single Python file."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    filepath = Path(context.acms_tmpdir) / filename
+    filepath.write_text("# test content\nprint('hello')\n", encoding="utf-8")
+    context.acms_target_path = filepath
+
+
+@given("a temporary directory with 3 Python files")
+def step_acms_three_files(context: Context) -> None:
+    """Create a temp dir with 3 Python files."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    tmpdir = Path(context.acms_tmpdir)
+    for i in range(3):
+        (tmpdir / f"file_{i}.py").write_text(f"# file {i}\n", encoding="utf-8")
+    context.acms_target_path = tmpdir
+
+
+@given("a temporary directory with files in subdirectory")
+def step_acms_files_in_subdir(context: Context) -> None:
+    """Create a temp dir with files at root and in a subdirectory."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    tmpdir = Path(context.acms_tmpdir)
+    (tmpdir / "root_file.py").write_text("# root\n", encoding="utf-8")
+    subdir = tmpdir / "subdir"
+    subdir.mkdir()
+    (subdir / "sub_file.py").write_text("# sub\n", encoding="utf-8")
+    context.acms_target_path = tmpdir
+    context.acms_top_level_count = 1  # only root_file.py
+
+
+@given("a temporary directory with 5 Python files")
+def step_acms_five_files(context: Context) -> None:
+    """Create a temp dir with 5 Python files."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    tmpdir = Path(context.acms_tmpdir)
+    for i in range(5):
+        (tmpdir / f"file_{i}.py").write_text(f"# file {i}\n", encoding="utf-8")
+    context.acms_target_path = tmpdir
+
+
+@given("a temporary directory with a Python file and a .pyc file")
+def step_acms_py_and_pyc(context: Context) -> None:
+    """Create a temp dir with a .py and a .pyc file."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    tmpdir = Path(context.acms_tmpdir)
+    (tmpdir / "module.py").write_text("# module\n", encoding="utf-8")
+    (tmpdir / "module.pyc").write_bytes(b"\x00\x01\x02\x03")
+    context.acms_target_path = tmpdir
+
+
+@given("a temporary directory with a Python file and an ignored __pycache__ file")
+def step_acms_py_and_ignored_cache_dir(context: Context) -> None:
+    """Create a temp dir with a visible file and a file under __pycache__."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+    tmpdir = Path(context.acms_tmpdir)
+    (tmpdir / "module.py").write_text("# module\n", encoding="utf-8")
+    cache_dir = tmpdir / "__pycache__"
+    cache_dir.mkdir()
+    (cache_dir / "cached.py").write_text("# ignored cache module\n", encoding="utf-8")
+    context.acms_target_path = tmpdir
+
+
+@when("I traverse the file with ChunkedFileTraverser")
+def step_acms_traverse_file(context: Context) -> None:
+    """Traverse a single file with ChunkedFileTraverser."""
+    traverser = ChunkedFileTraverser()
+    context.acms_entries = list(traverser.traverse(context.acms_target_path))
+
+
+@when("I traverse the directory recursively with ChunkedFileTraverser")
+def step_acms_traverse_dir_recursive(context: Context) -> None:
+    """Traverse a directory recursively with ChunkedFileTraverser."""
+    traverser = ChunkedFileTraverser()
+    context.acms_entries = list(
+        traverser.traverse(context.acms_target_path, recursive=True)
+    )
+
+
+@when("I traverse the directory non-recursively with ChunkedFileTraverser")
+def step_acms_traverse_dir_nonrecursive(context: Context) -> None:
+    """Traverse a directory non-recursively with ChunkedFileTraverser."""
+    traverser = ChunkedFileTraverser()
+    context.acms_entries = list(
+        traverser.traverse(context.acms_target_path, recursive=False)
+    )
+
+
+@when("I traverse the file with max_file_size {max_file_size:d}")
+def step_acms_traverse_file_with_max_size(context: Context, max_file_size: int) -> None:
+    """Traverse a single file with a low max_file_size limit."""
+    traverser = ChunkedFileTraverser(max_file_size=max_file_size)
+    context.acms_entries = list(traverser.traverse(context.acms_target_path))
+
+
+@when('I traverse with tags "{tag1}" and "{tag2}"')
+def step_acms_traverse_with_tags(context: Context, tag1: str, tag2: str) -> None:
+    """Traverse with multiple tags."""
+    traverser = ChunkedFileTraverser(tags=[tag1, tag2])
+    context.acms_entries = list(traverser.traverse(context.acms_target_path))
+    context.acms_expected_tags = [tag1, tag2]
+
+
+@when('I traverse with policy "{policy}"')
+def step_acms_traverse_with_policy(context: Context, policy: str) -> None:
+    """Traverse with a policy."""
+    traverser = ChunkedFileTraverser(policy=policy)
+    context.acms_entries = list(traverser.traverse(context.acms_target_path))
+    context.acms_expected_policy = policy
+
+
+@when("I traverse with a progress callback and chunk_size {chunk_size:d}")
+def step_acms_traverse_with_progress(context: Context, chunk_size: int) -> None:
+    """Traverse with a progress callback."""
+    calls: list[tuple[int, int]] = []
+
+    def on_progress(done: int, total: int) -> None:
+        calls.append((done, total))
+
+    traverser = ChunkedFileTraverser(
+        chunk_size=chunk_size,
+        on_progress=on_progress,
+    )
+    context.acms_entries = list(
+        traverser.traverse(context.acms_target_path, recursive=True)
+    )
+    context.acms_progress_calls = calls
+
+
+@when("I traverse a non-existent path with ChunkedFileTraverser")
+def step_acms_traverse_nonexistent(context: Context) -> None:
+    """Traverse a non-existent path."""
+    traverser = ChunkedFileTraverser()
+    try:
+        list(traverser.traverse(Path("/nonexistent/path/xyz")))
+        context.acms_error = None
+    except FileNotFoundError as exc:
+        context.acms_error = exc
+
+
+@when("I read the file with a mocked stat OSError")
+def step_acms_read_file_stat_oserror(context: Context) -> None:
+    """Call _read_file while stat raises OSError."""
+    target = context.acms_target_path
+    original_stat = Path.stat
+
+    def failing_stat(self: Path, *args: object, **kwargs: object) -> object:
+        if self == target:
+            raise OSError("stat failed")
+        return original_stat(self, *args, **kwargs)
+
+    traverser = ChunkedFileTraverser()
+    with patch.object(Path, "stat", failing_stat):
+        context.acms_read_result = traverser._read_file(target)
+
+
+@when("I read the file with a mocked read_text OSError")
+def step_acms_read_file_read_text_oserror(context: Context) -> None:
+    """Call _read_file while read_text raises OSError after stat succeeds."""
+    target = context.acms_target_path
+    original_read_text = Path.read_text
+
+    def failing_read_text(self: Path, *args: object, **kwargs: object) -> str:
+        if self == target:
+            raise OSError("read failed")
+        return original_read_text(self, *args, **kwargs)
+
+    traverser = ChunkedFileTraverser()
+    with patch.object(Path, "read_text", failing_read_text):
+        context.acms_read_result = traverser._read_file(target)
+
+
+@when("I create a ChunkedFileTraverser with chunk_size 0")
+def step_acms_invalid_chunk_size(context: Context) -> None:
+    """Create a ChunkedFileTraverser with invalid chunk_size."""
+    try:
+        ChunkedFileTraverser(chunk_size=0)
+        context.acms_error = None
+    except ValueError as exc:
+        context.acms_error = exc
+
+
+@when("I create an AcmsIndexEntry with a relative path")
+def step_acms_relative_path_entry(context: Context) -> None:
+    """Create an AcmsIndexEntry with a relative path."""
+    try:
+        AcmsIndexEntry(
+            path=Path("relative/path.py"),
+            content="# test",
+            content_hash="abc123",
+            size_bytes=10,
+        )
+        context.acms_error = None
+    except ValueError as exc:
+        context.acms_error = exc
+
+
+@when("I create an AcmsIndexEntry with size_bytes -1")
+def step_acms_negative_size_entry(context: Context) -> None:
+    """Create an AcmsIndexEntry with negative size_bytes."""
+    try:
+        AcmsIndexEntry(
+            path=Path("/tmp/test.py"),
+            content="# test",
+            content_hash="abc123",
+            size_bytes=-1,
+        )
+        context.acms_error = None
+    except ValueError as exc:
+        context.acms_error = exc
+
+
+# ---------------------------------------------------------------------------
+# Assertions for traversal
+# ---------------------------------------------------------------------------
+
+
+@then("the acms traversal should yield {count:d} entry")
+def step_acms_yield_one_entry(context: Context, count: int) -> None:
+    assert len(context.acms_entries) == count, (
+        f"Expected {count} entries, got {len(context.acms_entries)}"
+    )
+
+
+@then("the acms traversal should yield {count:d} entries")
+def step_acms_yield_n_entries(context: Context, count: int) -> None:
+    assert len(context.acms_entries) == count, (
+        f"Expected {count} entries, got {len(context.acms_entries)}"
+    )
+
+
+@then("the acms entry path should be absolute")
+def step_acms_entry_path_absolute(context: Context) -> None:
+    for entry in context.acms_entries:
+        assert entry.path.is_absolute(), f"Path not absolute: {entry.path}"
+
+
+@then("all acms entry paths should be absolute")
+def step_acms_all_paths_absolute(context: Context) -> None:
+    for entry in context.acms_entries:
+        assert entry.path.is_absolute(), f"Path not absolute: {entry.path}"
+
+
+@then("the acms entry content should be non-empty")
+def step_acms_entry_content_nonempty(context: Context) -> None:
+    for entry in context.acms_entries:
+        assert entry.content, f"Empty content for {entry.path}"
+
+
+@then("the acms entry content_hash should be a valid SHA-256 hex string")
+def step_acms_entry_hash_valid(context: Context) -> None:
+    for entry in context.acms_entries:
+        assert len(entry.content_hash) == 64, (
+            f"Invalid hash length: {len(entry.content_hash)}"
+        )
+        int(entry.content_hash, 16)  # raises ValueError if not hex
+
+
+@then("the acms traversal should yield only top-level files")
+def step_acms_only_top_level(context: Context) -> None:
+    assert len(context.acms_entries) == context.acms_top_level_count, (
+        f"Expected {context.acms_top_level_count} top-level files, "
+        f"got {len(context.acms_entries)}"
+    )
+
+
+@then("all acms entries should have tags {tags_repr}")
+def step_acms_entries_have_tags(context: Context, tags_repr: str) -> None:
+    expected_tags = ast.literal_eval(tags_repr)
+    for entry in context.acms_entries:
+        assert entry.tags == expected_tags, (
+            f"Expected tags {expected_tags}, got {entry.tags}"
+        )
+
+
+@then('all acms entries should have policy "{policy}"')
+def step_acms_entries_have_policy(context: Context, policy: str) -> None:
+    for entry in context.acms_entries:
+        assert entry.policy == policy, (
+            f"Expected policy {policy!r}, got {entry.policy!r}"
+        )
+
+
+@then("the acms progress callback should have been called at least once")
+def step_acms_progress_called(context: Context) -> None:
+    assert len(context.acms_progress_calls) > 0, "Progress callback was never called"
+
+
+@then("the acms final progress call should report total {total:d}")
+def step_acms_final_progress_total(context: Context, total: int) -> None:
+    assert context.acms_progress_calls, "No progress calls recorded"
+    _last_done, last_total = context.acms_progress_calls[-1]
+    assert last_total == total, f"Expected final total={total}, got {last_total}"
+
+
+@then("the acms traversal should yield only the Python file")
+def step_acms_only_py_file(context: Context) -> None:
+    assert len(context.acms_entries) == 1, (
+        f"Expected 1 entry (Python file only), got {len(context.acms_entries)}"
+    )
+    assert context.acms_entries[0].path.suffix == ".py", (
+        f"Expected .py file, got {context.acms_entries[0].path}"
+    )
+
+
+@then("the acms traversal should yield only the visible Python file")
+def step_acms_only_visible_py_file(context: Context) -> None:
+    assert len(context.acms_entries) == 1, (
+        f"Expected 1 visible Python file, got {len(context.acms_entries)}"
+    )
+    assert context.acms_entries[0].path.name == "module.py", (
+        f"Expected module.py, got {context.acms_entries[0].path}"
+    )
+
+
+@then("the acms read result should be skipped")
+def step_acms_read_result_skipped(context: Context) -> None:
+    assert context.acms_read_result is None, (
+        f"Expected skipped read result, got {context.acms_read_result!r}"
+    )
+
+
+@then("an acms FileNotFoundError should be raised")
+def step_acms_file_not_found(context: Context) -> None:
+    assert isinstance(context.acms_error, FileNotFoundError), (
+        f"Expected FileNotFoundError, got {type(context.acms_error)}"
+    )
+
+
+@then('an acms ValueError should be raised mentioning "{text}"')
+def step_acms_value_error_mentioning(context: Context, text: str) -> None:
+    assert isinstance(context.acms_error, ValueError), (
+        f"Expected ValueError, got {type(context.acms_error)}"
+    )
+    assert text in str(context.acms_error), (
+        f"Expected '{text}' in error message: {context.acms_error}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# CLI integration tests
+# ---------------------------------------------------------------------------
+
+
+def _mock_acms_container(
+    added_files: list[Path] | None = None,
+) -> MagicMock:
+    """Build a mock DI container for ACMS context add CLI tests."""
+    container = MagicMock()
+    mock_context_service = MagicMock()
+    mock_context_service.add_to_context.return_value = (
+        added_files or [],
+        [],
+    )
+    container.context_service.return_value = mock_context_service
+    mock_project_service = MagicMock()
+    mock_project_service.get_current_project.return_value = MagicMock()
+    container.project_service.return_value = mock_project_service
+    return container
+
+
+@given("a mocked context service for acms add")
+def step_acms_mocked_service(context: Context) -> None:
+    """Set up a mocked context service."""
+    context.acms_tmpdir = tempfile.mkdtemp()
+
+
+@given('a temporary file "{filename}" exists')
+def step_acms_temp_file_exists(context: Context, filename: str) -> None:
+    """Create a temporary file."""
+    tmpdir = Path(context.acms_tmpdir)
+    filepath = tmpdir / filename
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    filepath.write_text("# test content\n", encoding="utf-8")
+    context.acms_temp_file = filepath
+
+
+@given('a temporary directory "{dirname}" with files')
+def step_acms_temp_dir_with_files(context: Context, dirname: str) -> None:
+    """Create a temporary directory with files."""
+    tmpdir = Path(context.acms_tmpdir)
+    dirpath = tmpdir / dirname.rstrip("/")
+    dirpath.mkdir(parents=True, exist_ok=True)
+    (dirpath / "file1.py").write_text("# file1\n", encoding="utf-8")
+    (dirpath / "file2.py").write_text("# file2\n", encoding="utf-8")
+    context.acms_temp_dir = dirpath
+
+
+@given('a temporary directory "src/" with 3 files')
+def step_acms_temp_dir_3_files(context: Context) -> None:
+    """Create a temporary directory with 3 files."""
+    tmpdir = Path(context.acms_tmpdir)
+    dirpath = tmpdir / "src"
+    dirpath.mkdir(parents=True, exist_ok=True)
+    for i in range(3):
+        (dirpath / f"file{i}.py").write_text(f"# file{i}\n", encoding="utf-8")
+    context.acms_temp_dir = dirpath
+
+
+@when('I invoke context add with path "{filename}" and tag "{tag}"')
+def step_acms_invoke_add_with_tag(context: Context, filename: str, tag: str) -> None:
+    """Invoke context add with a single tag."""
+    filepath = context.acms_temp_file
+    container = _mock_acms_container(added_files=[filepath])
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        result = context.acms_runner.invoke(
+            context_app, ["add", str(filepath), "--tag", tag]
+        )
+        context.acms_result = result
+
+
+@when('I invoke context add with path "{filename}" and tags "{tag1}" and "{tag2}"')
+def step_acms_invoke_add_with_tags(
+    context: Context, filename: str, tag1: str, tag2: str
+) -> None:
+    """Invoke context add with multiple tags."""
+    filepath = context.acms_temp_file
+    container = _mock_acms_container(added_files=[filepath])
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        result = context.acms_runner.invoke(
+            context_app,
+            ["add", str(filepath), "--tag", tag1, "--tag", tag2],
+        )
+        context.acms_result = result
+
+
+@when('I invoke context add with path "{filename}" and policy "{policy}"')
+def step_acms_invoke_add_with_policy(
+    context: Context, filename: str, policy: str
+) -> None:
+    """Invoke context add with a policy."""
+    filepath = context.acms_temp_file
+    container = _mock_acms_container(added_files=[filepath])
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        result = context.acms_runner.invoke(
+            context_app, ["add", str(filepath), "--policy", policy]
+        )
+        context.acms_result = result
+
+
+@when('I invoke context add with directory "{dirname}" and --no-recursive')
+def step_acms_invoke_add_no_recursive(context: Context, dirname: str) -> None:
+    """Invoke context add with --no-recursive."""
+    dirpath = context.acms_temp_dir
+    container = _mock_acms_container(added_files=[dirpath / "file1.py"])
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        result = context.acms_runner.invoke(
+            context_app, ["add", str(dirpath), "--no-recursive"]
+        )
+        context.acms_result = result
+
+
+@when('I invoke context add with directory "src/"')
+def step_acms_invoke_add_directory(context: Context) -> None:
+    """Invoke context add with a directory."""
+    dirpath = context.acms_temp_dir
+    container = _mock_acms_container(
+        added_files=[dirpath / f"file{i}.py" for i in range(3)]
+    )
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        result = context.acms_runner.invoke(context_app, ["add", str(dirpath)])
+        context.acms_result = result
+
+
+@when("I call add_command with a mocked traverser ValueError")
+def step_acms_call_add_command_traverser_value_error(context: Context) -> None:
+    """Call the programmatic wrapper while traversal raises ValueError."""
+    filepath = context.acms_temp_file
+    container = _mock_acms_container(added_files=[filepath])
+
+    class FailingTraverser:
+        def __init__(self, *args: object, **kwargs: object) -> None:
+            pass
+
+        def traverse(self, *args: object, **kwargs: object) -> list[object]:
+            raise ValueError("not a regular file")
+
+    with (
+        patch(
+            "cleveragents.application.container.get_container", return_value=container
+        ),
+        patch("cleveragents.acms.index.ChunkedFileTraverser", FailingTraverser),
+    ):
+        add_command([str(filepath)], recursive=True, tags=["api"], policy="strict")
+
+    context.acms_context_service = container.context_service.return_value
+    context.acms_project = container.project_service.return_value.get_current_project()
+    context.acms_added_path = filepath.resolve()
+
+
+@when("I invoke context add --help")
+def step_acms_invoke_help(context: Context) -> None:
+    """Invoke context add --help."""
+    result = context.acms_runner.invoke(context_app, ["add", "--help"])
+    context.acms_result = result
+
+
+@then("the acms context add command should succeed")
+def step_acms_add_success(context: Context) -> None:
+    assert context.acms_result.exit_code == 0, (
+        f"Exit code: {context.acms_result.exit_code}\n{context.acms_result.output}"
+    )
+
+
+@then("the acms programmatic context add should persist the file")
+def step_acms_programmatic_add_persisted(context: Context) -> None:
+    context.acms_context_service.add_to_context.assert_called_once_with(
+        context.acms_project,
+        context.acms_added_path,
+        recursive=True,
+    )
+
+
+@then('the acms output should mention "{text}"')
+def step_acms_output_mentions(context: Context, text: str) -> None:
+    assert text in context.acms_result.output, (
+        f"Expected '{text}' in output:\n{context.acms_result.output}"
+    )
+
+
+@then('the acms help output should contain "{text}"')
+def step_acms_help_contains(context: Context, text: str) -> None:
+    assert text in context.acms_result.output, (
+        f"Expected '{text}' in help output:\n{context.acms_result.output}"
+    )

features/steps/acms_read_file_coverage_steps.py

@@ -0,0 +1,84 @@
+"""Step definitions for direct _read_file and add_command traversal coverage.
+
+Targets diff-coverage gaps:
+  acms/index.py  lines 597-612  (_read_file stat/size-check/read_text paths)
+  context.py     lines 111-112  (add_command traverser invocation)
+
+Step names are prefixed with ``rf_`` / ``ac_`` context attributes and use
+unique step text to avoid AmbiguousStep conflicts with existing steps.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+from behave import given, then, when
+from behave.runner import Context
+
+from cleveragents.acms.index import AcmsIndexEntry, ChunkedFileTraverser
+
+
+@given("a temp file exists for read file coverage")
+def step_rf_temp_file(context: Context) -> None:
+    """Create a small temp file used by all scenarios in this feature."""
+    context.rf_tmpdir = tempfile.mkdtemp()
+    path = Path(context.rf_tmpdir) / "sample.py"
+    path.write_text("# sample content\n", encoding="utf-8")
+    context.rf_path = path
+
+
+@when("I directly call _read_file with default traverser")
+def step_rf_direct_default(context: Context) -> None:
+    """Call _read_file directly — exercises lines 597-598 and 611-612."""
+    traverser = ChunkedFileTraverser()
+    context.rf_result = traverser._read_file(context.rf_path)
+
+
+@when("I directly call _read_file with max_file_size 1")
+def step_rf_direct_max_size(context: Context) -> None:
+    """Call _read_file with max_file_size=1 — exercises lines 602-607."""
+    traverser = ChunkedFileTraverser(max_file_size=1)
+    context.rf_result = traverser._read_file(context.rf_path)
+
+
+@then("the direct read file result should be an AcmsIndexEntry")
+def step_rf_result_is_entry(context: Context) -> None:
+    assert isinstance(context.rf_result, AcmsIndexEntry), (
+        f"Expected AcmsIndexEntry, got {type(context.rf_result)!r}"
+    )
+
+
+@then("the direct read file result should be None")
+def step_rf_result_is_none(context: Context) -> None:
+    assert context.rf_result is None, (
+        f"Expected None from _read_file, got {context.rf_result!r}"
+    )
+
+
+@when("I call add_command with the real traverser and a mocked container")
+def step_ac_call_add_command_real_traverser(context: Context) -> None:
+    """Call add_command with the REAL ChunkedFileTraverser — exercises lines 111-112."""
+    from cleveragents.cli.commands.context import add_command
+
+    container = MagicMock()
+    context_service = MagicMock()
+    context_service.add_to_context.return_value = ([context.rf_path], [])
+    container.context_service.return_value = context_service
+    project_service = MagicMock()
+    project_service.get_current_project.return_value = MagicMock()
+    container.project_service.return_value = project_service
+
+    with patch(
+        "cleveragents.application.container.get_container",
+        return_value=container,
+    ):
+        add_command([str(context.rf_path)])
+
+    context.ac_context_service = context_service
+
+
+@then("the mocked add_to_context should have been called")
+def step_ac_add_to_context_called(context: Context) -> None:
+    context.ac_context_service.add_to_context.assert_called_once()

features/steps/actor_add_update_enforcement_steps.py

@@ -1,7 +1,11 @@
-"""Step definitions for actor add --update flag enforcement (issue #2609).
+"""Step definitions for actor add --update flag enforcement (issue #1500/#2609).
 
 Tests that `agents actor add` rejects re-adding an existing actor without
 the --update flag, and succeeds when --update is provided.
+
+The ``add`` command requires a positional NAME argument followed by
+``--config <FILE>``:
+    agents actor add <NAME> --config <FILE> [--update]
 """
 
 from __future__ import annotations
@@ -105,6 +109,7 @@ def step_when_add_without_update(context: Any) -> None:
             )
             registry.upsert_actor.return_value = context.new_actor
         mock_svc.return_value = (MagicMock(), registry)
+        # The add command requires a positional NAME argument before --config
         context.result = context.runner.invoke(
             actor_app,
             ["add", context.actor_name, "--config", str(context.actor_config_path)],
@@ -120,6 +125,7 @@ def step_when_add_with_update(context: Any) -> None:
         # upsert_actor returns the updated actor
         registry.upsert_actor.return_value = context.updated_actor
         mock_svc.return_value = (MagicMock(), registry)
+        # The add command requires a positional NAME argument before --config
         context.result = context.runner.invoke(
             actor_app,
             [

features/steps/actor_context_cmds_steps.py

@@ -1,4 +1,3 @@
-# pyright: reportRedeclaration=false
 """Step definitions for actor context remove/export/import commands."""
 
 from __future__ import annotations
@@ -331,6 +330,42 @@ def step_import_with_update(context, name):
     )
 
 
+# ---------------------------------------------------------------------------
+# When — show
+# ---------------------------------------------------------------------------
+
+
+@when('I run actor context show "{name}" without specifying format')
+def step_show_context_default(context, name):
+    context.result = context.runner.invoke(
+        actor_context_app,
+        ["show", name, "--context-dir", str(context.context_dir)],
+    )
+
+
+@when('I run actor context show "{name}" with format "{fmt}"')
+def step_show_context_format(context, name, fmt):
+    context.result = context.runner.invoke(
+        actor_context_app,
+        [
+            "show",
+            name,
+            "--context-dir",
+            str(context.context_dir),
+            "--format",
+            fmt,
+        ],
+    )
+
+
+@when('I run actor context show "{name}" that does not exist')
+def step_show_nonexistent_context(context, name):
+    context.result = context.runner.invoke(
+        actor_context_app,
+        ["show", name, "--context-dir", str(context.context_dir)],
+    )
+
+
 # ---------------------------------------------------------------------------
 # When — round-trip helpers
 # ---------------------------------------------------------------------------
@@ -419,6 +454,15 @@ def step_import_success(context):
     )
 
 
+@then("the actor context show command should succeed")
+def step_show_success(context):
+    assert context.result.exit_code == 0, (
+        f"Expected exit 0, got {context.result.exit_code}.\n"
+        f"stdout: {context.result.output}\n"
+        f"stderr: {getattr(context.result, 'stderr', '')}"
+    )
+
+
 @then("the actor context clear command should fail with exit code 1")
 def step_clear_fail(context):
     assert context.result.exit_code == 1, (
@@ -455,6 +499,15 @@ def step_import_fail(context):
     )
 
 
+@then("the actor context show command should fail with exit code 1")
+def step_show_fail(context):
+    assert context.result.exit_code == 1, (
+        f"Expected exit 1, got {context.result.exit_code}.\n"
+        f"stdout: {context.result.output}\n"
+        f"stderr: {getattr(context.result, 'stderr', '')}"
+    )
+
+
 # ---------------------------------------------------------------------------
 # Then — state assertions
 # ---------------------------------------------------------------------------
@@ -522,6 +575,35 @@ def step_output_json_key(context, key):
     assert key in data, f"Key '{key}' not found in JSON output: {data.keys()}"
 
 
+@then('the output should include a context summary for "{name}"')
+def step_output_contains_summary(context, name):
+    output = context.result.output
+    assert "Context Summary" in output, (
+        f"Context Summary not found in output:\n{output}"
+    )
+    assert name in output, f"Context name '{name}' not found in output:\n{output}"
+
+
+@then("the JSON payload should list {count:d} messages")
+def step_json_message_count(context, count):
+    parsed = json.loads(context.result.output)
+    data = _unwrap_envelope(parsed)
+    messages = data.get("messages")
+    assert isinstance(messages, list), "messages is not a list"
+    assert len(messages) == count, f"Expected {count} messages, found {len(messages)}"
+
+
+@then('the JSON payload metadata context_name should be "{name}"')
+def step_json_metadata_context_name(context, name):
+    parsed = json.loads(context.result.output)
+    data = _unwrap_envelope(parsed)
+    metadata = data.get("metadata")
+    assert isinstance(metadata, dict), "metadata is not a dict"
+    assert metadata.get("context_name") == name, (
+        f"Expected metadata.context_name={name!r}, got {metadata.get('context_name')!r}"
+    )
+
+
 @then('the output JSON key "{top_key}" should contain keys "{keys}"')
 def step_output_json_nested_keys(context, top_key, keys):
     parsed = json.loads(context.result.output)

features/steps/context_policy_strategy_config_steps.py

@@ -0,0 +1,125 @@
+"""Step definitions for ProjectContextPolicy strategy configuration tests."""
+
+from __future__ import annotations
+
+from behave import given, then, when
+from behave.runner import Context
+from pydantic import ValidationError
+
+from cleveragents.domain.models.core.context_policy import (
+    ProjectContextPolicy,
+)
+
+# -------------------------------------------------------------------
+# Strategy field support
+# -------------------------------------------------------------------
+
+
+@given('a context policy with strategy "{strategy}"')
+def step_policy_with_strategy(context: Context, strategy: str) -> None:
+    context.strategy = strategy
+    context.strategy_config = None
+    context.policy_error = None
+
+
+@given("a context policy without strategy")
+def step_policy_without_strategy(context: Context) -> None:
+    context.strategy = None
+    context.strategy_config = None
+    context.policy_error = None
+
+
+@given('strategy config with parameter "{key}" set to {value}')
+def step_add_strategy_config(context: Context, key: str, value: str) -> None:
+    if context.strategy_config is None:
+        context.strategy_config = {}
+    # Parse the value
+    try:
+        # Try to parse as float
+        context.strategy_config[key] = float(value)
+    except ValueError:
+        try:
+            # Try to parse as int
+            context.strategy_config[key] = int(value)
+        except ValueError:
+            # Keep as string
+            context.strategy_config[key] = value
+
+
+@given("no strategy config")
+def step_no_strategy_config(context: Context) -> None:
+    context.strategy_config = None
+
+
+@when("I validate the context policy")
+def step_validate_policy(context: Context) -> None:
+    context.policy_error = None
+    try:
+        context.policy = ProjectContextPolicy(
+            strategy=context.strategy,
+            strategy_config=context.strategy_config,
+        )
+    except ValidationError as exc:
+        context.policy_error = str(exc)
+
+
+@then('the policy strategy should be "{strategy}"')
+def step_strategy_is(context: Context, strategy: str) -> None:
+    if strategy == "None":
+        assert context.policy.strategy is None
+    else:
+        assert context.policy.strategy == strategy
+
+
+@then("the policy strategy should be None")
+def step_strategy_is_none(context: Context) -> None:
+    assert context.policy.strategy is None
+
+
+@then("the policy should be valid")
+def step_policy_valid(context: Context) -> None:
+    assert context.policy_error is None, (
+        f"Expected valid policy but got error: {context.policy_error}"
+    )
+
+
+@then("the policy should be invalid")
+def step_policy_invalid(context: Context) -> None:
+    assert context.policy_error is not None, "Expected invalid policy but it was valid"
+
+
+@then('the strategy error should mention "{text}"')
+def step_error_mentions(context: Context, text: str) -> None:
+    assert text in context.policy_error, (
+        f"Expected '{text}' in error: {context.policy_error}"
+    )
+
+
+# -------------------------------------------------------------------
+# Strategy configuration parameters
+# -------------------------------------------------------------------
+
+
+@then('the strategy_config should contain "{key}"')
+def step_strategy_config_contains(context: Context, key: str) -> None:
+    assert context.policy.strategy_config is not None
+    assert key in context.policy.strategy_config
+
+
+@then('the strategy_config["{key}"] should be {value}')
+def step_strategy_config_value(context: Context, key: str, value: str) -> None:
+    assert context.policy.strategy_config is not None
+    # Parse the expected value
+    try:
+        expected = float(value)
+    except ValueError:
+        try:
+            expected = int(value)
+        except ValueError:
+            expected = value
+    assert context.policy.strategy_config[key] == expected
+
+
+@then("the strategy_config should be None")
+def step_strategy_config_none(context: Context) -> None:
+    assert context.policy.strategy_config is None

features/steps/conversation_state_management_steps.py

@@ -0,0 +1,407 @@
+"""BDD step definitions for conversation state management feature."""
+
+from __future__ import annotations
+
+from behave import given, then, when
+from behave.runner import Context
+
+from unittest.mock import MagicMock
+
+from cleveragents.domain.models.core.session import MessageRole, Session
+from cleveragents.langgraph.bridge import RxPyLangGraphBridge
+from cleveragents.langgraph.state import (
+    ConversationStateManager,
+    ExecutionState,
+    GraphState,
+    StateManager,
+    StateUpdateMode,
+)
+from cleveragents.reactive.stream_router import ReactiveStreamRouter
+
+
+def _ensure(context: Context) -> None:
+    context.results = getattr(context, "results", {}) or {}
+    context.managers = getattr(context, "managers", {}) or {}
+
+
+# ---------------------------------------------------------------------------
+# ConversationStateManager scenarios
+# ---------------------------------------------------------------------------
+
+
+@given("a ConversationStateManager with no initial state")
+def step_create_conversation_state_manager(context: Context) -> None:
+    _ensure(context)
+    context.managers["csm"] = ConversationStateManager()
+
+
+@when('I append messages "hello" and "world" to the conversation history')
+def step_append_hello_world(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.append_messages([{"role": "user", "content": "hello"}])
+    mgr.append_messages([{"role": "user", "content": "world"}])
+
+
+@when("I reset the execution state")
+def step_reset_execution_state(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.reset_execution_state()
+
+
+@then("the conversation history should still contain 2 messages")
+def step_assert_history_has_2_messages(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    assert len(mgr.get_full_history()) == 2, (
+        f"Expected 2 messages, got {len(mgr.get_full_history())}"
+    )
+
+
+@then("the execution count should be 0 after reset")
+def step_assert_execution_count_zero(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    state = mgr.get_state()
+    assert state.execution_count == 0, (
+        f"Expected execution_count=0, got {state.execution_count}"
+    )
+
+
+@when('I update the state with current_node "agent_a" and execution_count 5')
+def step_update_state_agent_a(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.update_state(
+        {"current_node": "agent_a"},
+        mode=StateUpdateMode.REPLACE,
+    )
+    # Perform 5 updates to increment execution_count
+    for _ in range(5):
+        mgr.update_state({}, mode=StateUpdateMode.REPLACE)
+
+
+@when('I append a message "keep me" to the conversation history')
+def step_append_keep_me(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.append_messages([{"role": "user", "content": "keep me"}])
+
+
+@then('the conversation history should contain the message "keep me"')
+def step_assert_history_contains_keep_me(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    contents = [m.get("content") for m in history]
+    assert "keep me" in contents, f"'keep me' not found in history: {contents}"
+
+
+@then("the current_node should be None after reset")
+def step_assert_current_node_none(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    state = mgr.get_state()
+    assert state.current_node is None, (
+        f"Expected current_node=None, got {state.current_node!r}"
+    )
+
+
+@when('I append messages "first" and "second" and "third" to the conversation history')
+def step_append_three_messages(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    for content in ("first", "second", "third"):
+        mgr.append_messages([{"role": "user", "content": content}])
+
+
+@then("get_full_history should return 3 messages")
+def step_assert_full_history_3(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    assert len(history) == 3, f"Expected 3 messages, got {len(history)}"
+
+
+@when('I append a message "persistent" to the conversation history')
+def step_append_persistent(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.append_messages([{"role": "user", "content": "persistent"}])
+
+
+@then('the history property should contain the message "persistent"')
+def step_assert_history_property_persistent(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.history
+    contents = [m.get("content") for m in history]
+    assert "persistent" in contents, (
+        f"'persistent' not found in history property: {contents}"
+    )
+
+
+@when('I call update_state with messages containing "new message"')
+def step_update_state_with_new_message(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.update_state(
+        {"messages": [{"role": "user", "content": "new message"}]},
+        mode=StateUpdateMode.APPEND,
+    )
+
+
+@then('the conversation history should contain the message "new message"')
+def step_assert_history_contains_new_message(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    contents = [m.get("content") for m in history]
+    assert "new message" in contents, f"'new message' not found in history: {contents}"
+
+
+# ---------------------------------------------------------------------------
+# GraphState.to_graph_state scenario
+# ---------------------------------------------------------------------------
+
+
+@given("a GraphState with messages and metadata")
+def step_create_graph_state_with_data(context: Context) -> None:
+    _ensure(context)
+    context.results["graph_state"] = GraphState(
+        messages=[{"role": "user", "content": "hi"}],
+        metadata={"key": "value"},
+        current_node="test_node",
+        execution_count=2,
+    )
+
+
+@when("I call to_graph_state on the GraphState")
+def step_call_to_graph_state(context: Context) -> None:
+    gs: GraphState = context.results["graph_state"]
+    context.results["graph_state_dict"] = gs.to_graph_state()
+
+
+@then("the result should contain a conversation_history key")
+def step_assert_conversation_history_key(context: Context) -> None:
+    result: dict = context.results["graph_state_dict"]
+    assert "conversation_history" in result, (
+        f"'conversation_history' key missing from: {list(result.keys())}"
+    )
+    assert isinstance(result["conversation_history"], list)
+    assert len(result["conversation_history"]) == 1
+
+
+@then("the result should contain an execution_state key with current_node")
+def step_assert_execution_state_key(context: Context) -> None:
+    result: dict = context.results["graph_state_dict"]
+    assert "execution_state" in result, (
+        f"'execution_state' key missing from: {list(result.keys())}"
+    )
+    exec_state = result["execution_state"]
+    assert exec_state["current_node"] == "test_node"
+    assert exec_state["execution_count"] == 2
+
+
+# ---------------------------------------------------------------------------
+# ExecutionState scenario
+# ---------------------------------------------------------------------------
+
+
+@given('an ExecutionState with current_node "node_x" and execution_count 3')
+def step_create_execution_state(context: Context) -> None:
+    _ensure(context)
+    context.results["exec_state"] = ExecutionState(
+        current_node="node_x",
+        execution_count=3,
+    )
+
+
+@then('the ExecutionState current_node should be "node_x"')
+def step_assert_exec_state_current_node(context: Context) -> None:
+    es: ExecutionState = context.results["exec_state"]
+    assert es.current_node == "node_x", f"Expected 'node_x', got {es.current_node!r}"
+
+
+@then("the ExecutionState execution_count should be 3")
+def step_assert_exec_state_execution_count(context: Context) -> None:
+    es: ExecutionState = context.results["exec_state"]
+    assert es.execution_count == 3, f"Expected 3, got {es.execution_count}"
+
+
+# ---------------------------------------------------------------------------
+# StateManager backward-compat alias scenario
+# ---------------------------------------------------------------------------
+
+
+@given("a StateManager created via the backward-compat alias")
+def step_create_state_manager_alias(context: Context) -> None:
+    _ensure(context)
+    context.managers["sm"] = StateManager()
+
+
+@when('I append a message "compat" to the conversation history via StateManager')
+def step_append_compat_via_state_manager(context: Context) -> None:
+    mgr: StateManager = context.managers["sm"]
+    mgr.append_messages([{"role": "user", "content": "compat"}])
+
+
+@then('the StateManager history property should contain the message "compat"')
+def step_assert_state_manager_history_compat(context: Context) -> None:
+    mgr: StateManager = context.managers["sm"]
+    history = mgr.history
+    contents = [m.get("content") for m in history]
+    assert "compat" in contents, (
+        f"'compat' not found in StateManager history: {contents}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# MAX_HISTORY_SIZE eviction scenario
+# ---------------------------------------------------------------------------
+
+
+@when("I append 55 messages to the conversation history")
+def step_append_55_messages(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    for i in range(55):
+        mgr.append_messages([{"role": "user", "content": f"msg_{i}"}])
+
+
+@then("the conversation history should contain at most 50 messages")
+def step_assert_history_at_most_50(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    assert len(history) <= 50, f"Expected at most 50 messages, got {len(history)}"
+
+
+@then("the most recent messages should be retained")
+def step_assert_most_recent_retained(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    # The last message appended was msg_54
+    assert history[-1]["content"] == "msg_54", (
+        f"Expected last message to be 'msg_54', got {history[-1]['content']!r}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Full reset scenario
+# ---------------------------------------------------------------------------
+
+
+@when('I append a message "before reset" to the conversation history')
+def step_append_before_reset(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.append_messages([{"role": "user", "content": "before reset"}])
+
+
+@when('I update the state with current_node "some_node" and execution_count 5')
+def step_update_state_some_node(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.update_state({"current_node": "some_node"}, mode=StateUpdateMode.REPLACE)
+    for _ in range(5):
+        mgr.update_state({}, mode=StateUpdateMode.REPLACE)
+
+
+@when("I perform a full reset")
+def step_perform_full_reset(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    mgr.reset()
+
+
+@then("the conversation history should be empty after full reset")
+def step_assert_history_empty_after_full_reset(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    history = mgr.get_full_history()
+    assert len(history) == 0, f"Expected empty history, got {len(history)} messages"
+
+
+@then("the execution count should be 0 after full reset")
+def step_assert_execution_count_zero_after_full_reset(context: Context) -> None:
+    mgr: ConversationStateManager = context.managers["csm"]
+    state = mgr.get_state()
+    assert state.execution_count == 0, (
+        f"Expected execution_count=0, got {state.execution_count}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Bridge default update mode scenario
+# ---------------------------------------------------------------------------
+
+
+@given("a RxPyLangGraphBridge instance")
+def step_create_bridge(context: Context) -> None:
+    _ensure(context)
+    scheduler = MagicMock()
+    router = ReactiveStreamRouter(scheduler=scheduler)
+    context.results["bridge"] = RxPyLangGraphBridge(stream_router=router)
+
+
+@then("the default update mode should be APPEND")
+def step_assert_bridge_default_mode_append(context: Context) -> None:
+    bridge: RxPyLangGraphBridge = context.results["bridge"]
+    assert bridge._DEFAULT_UPDATE_MODE == StateUpdateMode.APPEND, (
+        f"Expected APPEND, got {bridge._DEFAULT_UPDATE_MODE}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Session scenarios
+# ---------------------------------------------------------------------------
+
+
+def _make_session() -> Session:
+    from ulid import ULID
+
+    return Session(session_id=str(ULID()))
+
+
+@given("a Session with two messages appended")
+def step_session_with_two_messages(context: Context) -> None:
+    _ensure(context)
+    session = _make_session()
+    session.append_message(MessageRole.USER, "first message")
+    session.append_message(MessageRole.ASSISTANT, "first response")
+    context.results["session"] = session
+
+
+@then("the full_history property should return 2 messages")
+def step_assert_full_history_2(context: Context) -> None:
+    session: Session = context.results["session"]
+    full_history = session.full_history
+    assert len(full_history) == 2, (
+        f"Expected 2 messages in full_history, got {len(full_history)}"
+    )
+
+
+@given("a Session with three messages appended")
+def step_session_with_three_messages(context: Context) -> None:
+    _ensure(context)
+    session = _make_session()
+    session.append_message(MessageRole.USER, "msg one")
+    session.append_message(MessageRole.ASSISTANT, "msg two")
+    session.append_message(MessageRole.USER, "msg three")
+    context.results["session"] = session
+
+
+@when("I call get_messages with no limit")
+def step_call_get_messages_no_limit(context: Context) -> None:
+    session: Session = context.results["session"]
+    context.results["messages"] = session.get_messages(limit=None)
+
+
+@then("all 3 messages should be returned")
+def step_assert_all_3_messages(context: Context) -> None:
+    messages = context.results["messages"]
+    assert len(messages) == 3, f"Expected 3 messages, got {len(messages)}"
+
+
+@given("a Session with one existing message")
+def step_session_with_one_message(context: Context) -> None:
+    _ensure(context)
+    session = _make_session()
+    session.append_message(MessageRole.USER, "first")
+    context.results["session"] = session
+
+
+@when("I append a second message to the session")
+def step_append_second_message(context: Context) -> None:
+    session: Session = context.results["session"]
+    session.append_message(MessageRole.ASSISTANT, "second")
+
+
+@then("the session should have 2 messages in total")
+def step_assert_session_has_2_messages(context: Context) -> None:
+    session: Session = context.results["session"]
+    assert session.message_count == 2, (
+        f"Expected 2 messages, got {session.message_count}"
+    )

features/steps/event_bus_steps.py

@@ -6,7 +6,8 @@ LoggingEventBus, service event emission, and DI container registration.
 
 from __future__ import annotations
 
-from typing import Any
+from collections.abc import Callable
+from typing import Any, cast
 from unittest.mock import MagicMock
 
 from behave import given, then, when  # type: ignore[import-untyped]
@@ -189,6 +190,18 @@ def step_subscribe_two(ctx: Context, et: str) -> None:
         ctx.bus.subscribe(EventType(et), collector)
 
 
+@when('I unsubscribe from "{et}" with the same handler')
+def step_unsubscribe_handler(ctx: Context, et: str) -> None:
+    collector = ctx.collectors[0]
+    ctx.unsubscribe_result = ctx.bus.unsubscribe(EventType(et), collector)
+
+
+@when('I unsubscribe only the first handler from "{et}"')
+def step_unsubscribe_first_handler(ctx: Context, et: str) -> None:
+    collector = ctx.collectors[0]
+    ctx.bus.unsubscribe(EventType(et), collector)
+
+
 @when('I emit a "{et}" DomainEvent')
 def step_emit_event(ctx: Context, et: str) -> None:
     ctx.bus.emit(_make_event(et))
@@ -220,6 +233,20 @@ def step_each_handler_received(ctx: Context, n: int) -> None:
         )
 
 
+@then("exactly one handler should have received 1 event")
+def step_exactly_one_handler_received(ctx: Context) -> None:
+    counts = [len(col.received) for col in ctx.collectors]
+    assert sum(1 for c in counts if c == 1) == 1, (
+        f"Expected exactly one handler with 1 event, got {counts}"
+    )
+
+
+@then('the handler count for "{et}" should be 0')
+def step_handler_count_zero(ctx: Context, et: str) -> None:
+    actual = len(ctx.bus._subscriptions.get(EventType(et), []))
+    assert actual == 0, f"Expected 0 handlers for {et}, got {actual}"
+
+
 @then("the bus should expose an observable stream")
 def step_bus_has_stream(ctx: Context) -> None:
     stream = ctx.bus.stream
@@ -230,7 +257,7 @@ def step_bus_has_stream(ctx: Context) -> None:
 def step_emit_non_domain_event(ctx: Context) -> None:
     raised = False
     try:
-        ctx.bus.emit("not-an-event")  # type: ignore[arg-type]
+        ctx.bus.emit(cast(DomainEvent, "not-an-event"))
     except TypeError:
         raised = True
     assert raised, "Expected TypeError for non-DomainEvent"
@@ -240,7 +267,7 @@ def step_emit_non_domain_event(ctx: Context) -> None:
 def step_subscribe_bad_type(ctx: Context) -> None:
     raised = False
     try:
-        ctx.bus.subscribe("plan.created", lambda e: None)  # type: ignore[arg-type]
+        ctx.bus.subscribe(cast(EventType, "plan.created"), lambda e: None)
     except TypeError:
         raised = True
     assert raised, "Expected TypeError for non-EventType event_type"
@@ -250,18 +277,67 @@ def step_subscribe_bad_type(ctx: Context) -> None:
 def step_subscribe_non_callable(ctx: Context) -> None:
     raised = False
     try:
-        ctx.bus.subscribe(EventType.PLAN_CREATED, "not-callable")  # type: ignore[arg-type]
+        ctx.bus.subscribe(
+            EventType.PLAN_CREATED, cast(Callable[[DomainEvent], None], "not-callable")
+        )
     except TypeError:
         raised = True
     assert raised, "Expected TypeError for non-callable handler"
 
 
+@then("unsubscribing should return True")
+def step_unsubscribe_returns_true(ctx: Context) -> None:
+    result: bool = getattr(ctx, "unsubscribe_result", False)
+    assert result is True, f"Expected unsubscribe to return True, got {result}"
+
+
+@then("unsubscribing a non-existent handler should return False")
+def step_unsubscribe_nonexistent_returns_false(ctx: Context) -> None:
+    ctx.exception = None
+    try:
+        ctx.unsubscribe_result = ctx.bus.unsubscribe(
+            EventType.PLAN_CREATED, lambda e: None
+        )
+    except Exception as exc:
+        ctx.exception = exc
+    assert ctx.unsubscribe_result is False
+
+
+@then("unsubscribing with a non-EventType should raise TypeError")
+def step_unsubscribe_bad_type(ctx: Context) -> None:
+    raised = False
+    try:
+        ctx.bus.unsubscribe(cast(EventType, "plan.created"), lambda e: None)
+    except TypeError:
+        raised = True
+    assert raised, "Expected TypeError for non-EventType event_type in unsubscribe"
+
+
+@then("unsubscribing with a non-callable handler should raise TypeError")
+def step_unsubscribe_non_callable(ctx: Context) -> None:
+    raised = False
+    try:
+        ctx.bus.unsubscribe(
+            EventType.PLAN_CREATED, cast(Callable[[DomainEvent], None], "not-callable")
+        )
+    except TypeError:
+        raised = True
+    assert raised, "Expected TypeError for non-callable handler in unsubscribe"
+
+
 @then("the EventBus Protocol stubs should be callable")
 def step_protocol_stubs_callable(ctx: Context) -> None:
     """Exercise Protocol method stubs directly to ensure 100% coverage."""
 
-    class _BareImpl(EventBus):  # type: ignore[misc]
-        pass
+    class _BareImpl(EventBus):
+        def emit(self, event: DomainEvent) -> None: ...
+        def subscribe(
+            self, event_type: EventType, handler: Callable[[DomainEvent], None]
+        ) -> None: ...
+        def unsubscribe(
+            self, event_type: EventType, handler: Callable[[DomainEvent], None]
+        ) -> bool:
+            return True
 
     obj = _BareImpl()
     event = _make_event("plan.created")
@@ -269,6 +345,24 @@ def step_protocol_stubs_callable(ctx: Context) -> None:
     obj.subscribe(EventType.PLAN_CREATED, lambda e: None)
 
 
+@then("the EventBus Protocol unsubscribe stub should be callable")
+def step_protocol_unsubscribe_callable(ctx: Context) -> None:
+    """Exercise Protocol unsubscribe stub directly to ensure coverage."""
+
+    class _BareImpl(EventBus):
+        def emit(self, event: DomainEvent) -> None: ...
+        def subscribe(
+            self, event_type: EventType, handler: Callable[[DomainEvent], None]
+        ) -> None: ...
+        def unsubscribe(
+            self, event_type: EventType, handler: Callable[[DomainEvent], None]
+        ) -> bool:
+            return True
+
+    obj = _BareImpl()
+    obj.unsubscribe(EventType.PLAN_CREATED, lambda e: None)
+
+
 # ---------------------------------------------------------------------------
 # DecisionService event emission steps
 # ---------------------------------------------------------------------------
@@ -477,56 +571,3 @@ def step_decision_service_has_event_bus(ctx: Context) -> None:
         "DecisionService resolved from DI has no event_bus attribute"
     )
     assert svc.event_bus is not None, "DecisionService.event_bus should not be None"
-
-
-# ---------------------------------------------------------------------------
-# ReactiveEventBus.close() and context manager steps (issue #10378)
-# ---------------------------------------------------------------------------
-
-
-@when("bus.close() is called on the bus")
-def step_close_bus(ctx: Context) -> None:
-    ctx.bus.close()
-
-
-@then("the bus should be marked as closed")
-def step_bus_is_closed(ctx: Context) -> None:
-    assert ctx.bus._closed, "Expected bus._closed to be True after close()"
-
-
-@then("emitting after close should raise RuntimeError")
-def step_emit_after_close_raises(ctx: Context) -> None:
-    from cleveragents.infrastructure.events.models import DomainEvent
-    from cleveragents.infrastructure.events.types import EventType
-
-    raised = False
-    try:
-        ctx.bus.emit(DomainEvent(event_type=EventType.PLAN_CREATED))
-    except RuntimeError:
-        raised = True
-    assert raised, "Expected RuntimeError when emitting after close()"
-
-
-@when("bus.close() is called twice on the bus")
-def step_close_bus_twice(ctx: Context) -> None:
-    ctx.bus.close()
-    ctx.bus.close()  # should not raise
-
-
-@then("no exception should be raised on double close")
-def step_no_exception_on_double_close(ctx: Context) -> None:
-    # If we reached here without exception, the test passes
-    pass
-
-
-@given("a ReactiveEventBus used as a context manager")
-def step_given_bus_context_manager(ctx: Context) -> None:
-    ctx.bus = ReactiveEventBus()
-    ctx.cm_bus: ReactiveEventBus | None = None
-    with ctx.bus as bus:
-        ctx.cm_bus = bus
-
-
-@then("the bus should be closed after the context exits")
-def step_bus_closed_after_context(ctx: Context) -> None:
-    assert ctx.bus._closed, "Expected bus._closed to be True after context manager exit"

features/steps/invariant_model_steps.py

@@ -1,233 +0,0 @@
-"""Step definitions for invariant_model.feature.
-
-Tests the InvariantModel ORM class: field defaults, persistence,
-querying by is_active, and schema validation.
-"""
-
-from __future__ import annotations
-
-import uuid
-from datetime import UTC, datetime
-
-from behave import given, then, when  # type: ignore[import-untyped]
-from behave.runner import Context
-from sqlalchemy import create_engine, inspect
-from sqlalchemy.orm import sessionmaker
-
-from cleveragents.infrastructure.database.models import Base, InvariantModel
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _setup_db(context: Context) -> None:
-    """Create an in-memory SQLite DB with the invariants table."""
-    engine = create_engine("sqlite:///:memory:", echo=False)
-    Base.metadata.create_all(engine)
-    sm = sessionmaker(bind=engine)
-    session = sm()
-    context._inv_engine = engine
-    context._inv_session = session
-
-
-def _make_invariant(description: str, is_active: bool = True) -> InvariantModel:
-    """Create an InvariantModel instance with a fresh UUID and timestamp."""
-    return InvariantModel(
-        id=str(uuid.uuid4()),
-        description=description,
-        created_at=datetime.now(tz=UTC).isoformat(),
-        is_active=is_active,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Background
-# ---------------------------------------------------------------------------
-
-
-@given("a fresh in-memory invariant database")
-def step_fresh_db(context: Context) -> None:
-    _setup_db(context)
-
-
-# ---------------------------------------------------------------------------
-# Create and retrieve
-# ---------------------------------------------------------------------------
-
-
-@given('a new Invariant with description "{description}"')
-def step_new_invariant(context: Context, description: str) -> None:
-    context._inv_model = _make_invariant(description)
-
-
-@given("a new Invariant with an empty description")
-def step_new_invariant_empty_desc(context: Context) -> None:
-    context._inv_model = InvariantModel(
-        id=str(uuid.uuid4()),
-        description="",
-        created_at=datetime.now(tz=UTC).isoformat(),
-        is_active=True,
-    )
-
-
-@when("I persist the Invariant")
-def step_persist_invariant(context: Context) -> None:
-    context._inv_session.add(context._inv_model)
-    context._inv_session.commit()
-    context._inv_id = context._inv_model.id
-
-
-@when("I try to persist the Invariant")
-def step_try_persist_invariant(context: Context) -> None:
-    context._inv_error = None
-    if not context._inv_model.description:
-        context._inv_error = ValueError("description cannot be empty")
-        return
-    context._inv_session.add(context._inv_model)
-    context._inv_session.commit()
-    context._inv_id = context._inv_model.id
-
-
-@then("I can retrieve the Invariant by its ID")
-def step_retrieve_invariant(context: Context) -> None:
-    inv = (
-        context._inv_session.query(InvariantModel).filter_by(id=context._inv_id).first()
-    )
-    assert inv is not None, f"Invariant with id={context._inv_id} not found"
-    context._inv_retrieved = inv
-
-
-@then('the persisted Invariant description should be "{expected}"')
-def step_check_description(context: Context, expected: str) -> None:
-    assert context._inv_retrieved.description == expected, (
-        f"Expected '{expected}', got '{context._inv_retrieved.description}'"
-    )
-
-
-@then("the persisted Invariant is_active should be True")
-def step_check_is_active_true(context: Context) -> None:
-    assert (
-        context._inv_retrieved.is_active is True
-        or context._inv_retrieved.is_active == 1
-    ), f"Expected is_active=True, got {context._inv_retrieved.is_active!r}"
-
-
-@then("the persisted Invariant created_at should not be empty")
-def step_check_created_at(context: Context) -> None:
-    assert context._inv_retrieved.created_at, "created_at should not be empty"
-    assert len(str(context._inv_retrieved.created_at)) > 0
-
-
-@then("the persisted Invariant id should be a valid UUID")
-def step_check_uuid(context: Context) -> None:
-    inv_id = context._inv_retrieved.id
-    try:
-        uuid.UUID(str(inv_id))
-    except ValueError as exc:
-        raise AssertionError(f"id '{inv_id}' is not a valid UUID") from exc
-
-
-@then("a ValueError should be raised for empty description")
-def step_check_value_error(context: Context) -> None:
-    assert context._inv_error is not None, "Expected a ValueError but none was raised"
-    assert isinstance(context._inv_error, ValueError)
-
-
-# ---------------------------------------------------------------------------
-# Filtering by is_active
-# ---------------------------------------------------------------------------
-
-
-@given("{active_count:d} active Invariants and {inactive_count:d} inactive Invariants")
-def step_mixed_invariants(
-    context: Context, active_count: int, inactive_count: int
-) -> None:
-    for i in range(active_count):
-        inv = _make_invariant(f"Active invariant {i}", is_active=True)
-        context._inv_session.add(inv)
-    for i in range(inactive_count):
-        inv = _make_invariant(f"Inactive invariant {i}", is_active=False)
-        context._inv_session.add(inv)
-    context._inv_session.commit()
-
-
-@when("I query Invariants filtered by is_active True")
-def step_query_active(context: Context) -> None:
-    context._inv_results = (
-        context._inv_session.query(InvariantModel).filter_by(is_active=True).all()
-    )
-
-
-@when("I query Invariants filtered by is_active False")
-def step_query_inactive(context: Context) -> None:
-    context._inv_results = (
-        context._inv_session.query(InvariantModel).filter_by(is_active=False).all()
-    )
-
-
-@then("I should get {count:d} Invariants")
-def step_check_count(context: Context, count: int) -> None:
-    actual = len(context._inv_results)
-    assert actual == count, f"Expected {count} Invariants, got {actual}"
-
-
-# ---------------------------------------------------------------------------
-# Deactivate
-# ---------------------------------------------------------------------------
-
-
-@given("a persisted active Invariant")
-def step_persisted_active(context: Context) -> None:
-    inv = _make_invariant("Active invariant to deactivate", is_active=True)
-    context._inv_session.add(inv)
-    context._inv_session.commit()
-    context._inv_id = inv.id
-    context._inv_retrieved = inv
-
-
-@when("I set is_active to False on the Invariant")
-def step_deactivate(context: Context) -> None:
-    inv = (
-        context._inv_session.query(InvariantModel).filter_by(id=context._inv_id).first()
-    )
-    assert inv is not None
-    inv.is_active = False
-    context._inv_session.commit()
-    context._inv_retrieved = inv
-
-
-@then("the Invariant is_active should be False")
-def step_check_is_active_false(context: Context) -> None:
-    inv = (
-        context._inv_session.query(InvariantModel).filter_by(id=context._inv_id).first()
-    )
-    assert inv is not None
-    assert inv.is_active is False or inv.is_active == 0, (
-        f"Expected is_active=False, got {inv.is_active!r}"
-    )
-
-
-# ---------------------------------------------------------------------------
-# Schema validation
-# ---------------------------------------------------------------------------
-
-
-@then("the invariants table should exist")
-def step_table_exists(context: Context) -> None:
-    inspector = inspect(context._inv_engine)
-    tables = inspector.get_table_names()
-    assert "invariants" in tables, (
-        f"Table 'invariants' not found. Available tables: {tables}"
-    )
-
-
-@then("the invariants table should have an index on is_active")
-def step_index_exists(context: Context) -> None:
-    inspector = inspect(context._inv_engine)
-    indexes = inspector.get_indexes("invariants")
-    index_names = [idx["name"] for idx in indexes]
-    # SQLite may also create implicit indexes; check for our named index
-    assert any("is_active" in name for name in index_names), (
-        f"No index on is_active found. Indexes: {index_names}"
-    )

features/steps/invariant_reconciliation_actor_steps.py

@@ -9,7 +9,6 @@ InvariantSet production.
 from __future__ import annotations
 
 from behave import given, then, when  # type: ignore[import-untyped]
-from ulid import ULID
 
 from cleveragents.actor.reconciliation import (
     InvariantReconciliationActor,
@@ -57,15 +56,12 @@ def step_add_global_invariant(context, text, source):
 @given('a non_overridable global invariant "{text}" from source "{source}"')
 def step_add_non_overridable_global(context, text, source):
     """Add a non_overridable global-scope invariant."""
-    # add_invariant does not expose non_overridable; create directly and store
-    inv = Invariant(
-        id=str(ULID()),
+    context.invariant_service.add_invariant(
         text=text,
         scope=InvariantScope.GLOBAL,
         source_name=source,
         non_overridable=True,
     )
-    context.invariant_service._invariants[inv.id] = inv
 
 
 @given('a project invariant "{text}" from source "{source}" for project "{project}"')

features/steps/langgraph_state_additional_coverage_steps.py

@@ -116,13 +116,13 @@ def step_perform_4_updates_time_travel(context: Context):
 @then("only the two most recent history snapshots should remain")
 def step_verify_two_history_snapshots(context: Context):
     manager = context.state_managers["history_trim"]
-    assert len(manager.history) == 2
+    assert len(manager.snapshots) == 2
 
 
 @then("the earliest snapshots should be discarded")
 def step_verify_earliest_discarded(context: Context):
     manager = context.state_managers["history_trim"]
-    ids = [snap.node_id for snap in manager.history]
+    ids = [snap.node_id for snap in manager.snapshots]
     assert ids == ["node_2", "node_3"]
 
 

features/steps/langgraph_state_branch_coverage_steps.py

@@ -188,12 +188,12 @@ def step_manager_with_two_checkpoints(context: Context):
     manager = StateManager(checkpoint_dir=checkpoint_dir)
 
     # Write first checkpoint
-    manager.state.metadata = {"first": True}
+    manager.update_state({"metadata": {"first": True}}, mode=StateUpdateMode.REPLACE)
     manager.update_count = 1
     manager._save_checkpoint()
 
     # Write second checkpoint with newer mtime
-    manager.state.metadata = {"second": True}
+    manager.update_state({"metadata": {"second": True}}, mode=StateUpdateMode.REPLACE)
     manager.update_count = 2
     manager._save_checkpoint()
 
@@ -246,7 +246,7 @@ def step_clear_and_reset(context: Context, metadata_json: str):
 @then("the history should be empty after reset")
 def step_verify_history_empty(context: Context):
     manager: StateManager = context.results["reset_manager"]
-    assert len(manager.history) == 0
+    assert len(manager.snapshots) == 0
 
 
 @then("the execution count should be zero after reset")

features/steps/tdd_invariant_persistence_steps.py

@@ -1,38 +1,43 @@
-"""Step definitions for tdd_invariant_persistence.feature (bug #1022).
+"""Step definitions for tdd_invariant_persistence.feature (bug #1022, now fixed).
 
-TDD issue-capture tests verifying that ``InvariantService`` persists invariants
-across simulated CLI process restarts (separate service instances).
-
-Bug #1022: ``InvariantService`` stores invariants in an in-memory dict
-(``self._invariants``) with no database persistence layer.  Each CLI
-invocation spawns a fresh process with a new ``InvariantService()``
-instance, so all invariants are lost when the process exits.
-
-These steps exercise the current (buggy) behaviour by creating fresh
-``InvariantService`` instances to simulate separate process invocations.
-When the bug is fixed, the service will use a database repository and
-fresh instances backed by the same database will share state.
-
-The tests carry ``@tdd_expected_fail`` so CI passes while the bug is
-unfixed.  The tag will be removed when bug #1022 is fixed.
+Tests verify that ``InvariantService`` persists invariants across simulated
+CLI process restarts (separate service instances), confirming that Bug #8573
+/#1022 is resolved: the database-backed InvariantService stores data in SQLite,
+so separate CLI invocations share the same underlying ``cleveragents.db`` and
+cross-instance data visibility is confirmed.
 """
 
 from __future__ import annotations
 
+import os
+from tempfile import TemporaryDirectory
 from unittest.mock import patch
 
 from behave import given, then, when
 from behave.runner import Context
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker
 from typer.testing import CliRunner
 
 from cleveragents.application.services.invariant_service import InvariantService
 from cleveragents.cli.commands.invariant import app as invariant_app
-from cleveragents.core.exceptions import NotFoundError
-from cleveragents.domain.models.core.invariant import InvariantScope
+from cleveragents.core.exceptions import InvariantViolationError, NotFoundError
+from cleveragents.domain.models.core.invariant import Invariant, InvariantScope
+from cleveragents.infrastructure.database.invariant_repository import (
+    InvariantRepository,
+)
+from cleveragents.infrastructure.database.models import Base
 
 runner = CliRunner()
 
 
+class _FailingEventBus:
+    """Event bus test double that fails every emit call."""
+
+    def emit(self, event: object) -> None:
+        raise RuntimeError(f"synthetic event bus failure for {event!r}")
+
+
 # ---------------------------------------------------------------------------
 # Given steps — instance A
 # ---------------------------------------------------------------------------
@@ -71,6 +76,106 @@ def step_capture_invariant_id(context: Context) -> None:
     context.captured_invariant_id = context.invariant_added_a.id
 
 
+@given("a fresh standalone invariant repository")
+def step_fresh_standalone_invariant_repository(context: Context) -> None:
+    """Create an isolated SQLAlchemy-backed invariant repository."""
+    tmpdir = TemporaryDirectory()
+    context.invariant_repo_tmpdir = tmpdir
+    engine = create_engine(f"sqlite:///{tmpdir.name}/invariants.db", future=True)
+    Base.metadata.create_all(engine)
+    session_factory = sessionmaker(
+        bind=engine,
+        expire_on_commit=False,
+        autoflush=False,
+        autocommit=False,
+    )
+    context.invariant_repo = InvariantRepository(
+        session_factory=session_factory,
+        auto_commit=True,
+    )
+
+
+@given(
+    'I repository-create inactive project invariant "{text}" for project "{project}"'
+)
+def step_repository_create_inactive_project_invariant(
+    context: Context, text: str, project: str
+) -> None:
+    """Persist an inactive project invariant directly through the repository."""
+    invariant = Invariant(
+        text=text,
+        scope=InvariantScope.PROJECT,
+        source_name=project,
+        active=False,
+    )
+    context.repository_created_invariant = invariant
+    context.invariant_repo.create(invariant)
+
+
+@given("a fresh in-memory invariant service")
+def step_fresh_in_memory_invariant_service(context: Context) -> None:
+    """Create a fresh non-persistent invariant service."""
+    with patch.dict(os.environ, {}, clear=True):
+        context.in_memory_invariant_service = InvariantService()
+
+
+@given("a fresh in-memory invariant service with a failing event bus")
+def step_fresh_in_memory_invariant_service_with_failing_bus(
+    context: Context,
+) -> None:
+    """Create a fresh in-memory invariant service with a failing event bus."""
+    with patch.dict(os.environ, {}, clear=True):
+        context.in_memory_invariant_service = InvariantService(
+            event_bus=_FailingEventBus(),
+        )
+
+
+@given('I add a global invariant "{text}" via the in-memory service')
+def step_add_global_invariant_in_memory(context: Context, text: str) -> None:
+    """Add a global invariant to the in-memory service."""
+    context.in_memory_global_invariant = (
+        context.in_memory_invariant_service.add_invariant(
+            text=text,
+            scope=InvariantScope.GLOBAL,
+            source_name="system",
+        )
+    )
+
+
+@given(
+    'I add a project invariant "{text}" for project "{project}" '
+    "via the in-memory service"
+)
+def step_add_project_invariant_in_memory(
+    context: Context, text: str, project: str
+) -> None:
+    """Add a project invariant to the in-memory service."""
+    context.in_memory_project_invariant = (
+        context.in_memory_invariant_service.add_invariant(
+            text=text,
+            scope=InvariantScope.PROJECT,
+            source_name=project,
+        )
+    )
+
+
+@given(
+    'I add an inactive project invariant "{text}" for project "{project}" '
+    "via the in-memory service"
+)
+def step_add_inactive_project_invariant_in_memory(
+    context: Context, text: str, project: str
+) -> None:
+    """Add, then deactivate, a project invariant in the in-memory cache."""
+    invariant = context.in_memory_invariant_service.add_invariant(
+        text=text,
+        scope=InvariantScope.PROJECT,
+        source_name=project,
+    )
+    inactive = invariant.model_copy(update={"active": False})
+    context.in_memory_invariant_service._invariants[invariant.id] = inactive
+
+
 @given(
     'I invoke invariant add via CLI with "{flags}" and text "{text}" '
     "using service invocation {n:d}"
@@ -142,6 +247,104 @@ def step_remove_via_instance_b(context: Context) -> None:
         context.invariant_remove_b_error = exc
 
 
+@when('I repository-list inactive project invariants for "{project}"')
+def step_repository_list_inactive_project_invariants(
+    context: Context, project: str
+) -> None:
+    """List inactive rows by disabling the repository active-only filter."""
+    context.repository_invariant_list = context.invariant_repo.list_invariants(
+        scope="project",
+        source_name=project,
+        active_only=False,
+    )
+
+
+@when('I repository-get invariant "{invariant_id}"')
+def step_repository_get_invariant(context: Context, invariant_id: str) -> None:
+    """Retrieve an invariant by ID directly through the repository."""
+    context.repository_get_result = context.invariant_repo.get(invariant_id)
+
+
+@when('I repository-update missing invariant "{invariant_id}"')
+def step_repository_update_missing_invariant(
+    context: Context, invariant_id: str
+) -> None:
+    """Attempt to update a missing invariant directly through the repository."""
+    missing = Invariant(
+        id=invariant_id,
+        text="Missing invariant",
+        scope=InvariantScope.GLOBAL,
+        source_name="system",
+    )
+    try:
+        context.invariant_repo.update(missing)
+        context.repository_update_error = None
+    except NotFoundError as exc:
+        context.repository_update_error = exc
+
+
+@when('I list effective project invariants for "{project}" via the in-memory service')
+def step_list_effective_project_invariants_in_memory(
+    context: Context, project: str
+) -> None:
+    """List the effective invariant set for a project."""
+    context.in_memory_effective_invariants = (
+        context.in_memory_invariant_service.list_invariants(
+            scope=InvariantScope.PROJECT,
+            source_name=project,
+            effective=True,
+        )
+    )
+
+
+@when('I load active invariants for project "{project}" via the in-memory service')
+def step_load_active_project_invariants_in_memory(
+    context: Context, project: str
+) -> None:
+    """Load active invariants for a project."""
+    context.in_memory_loaded_invariants = (
+        context.in_memory_invariant_service.load_active_invariants(
+            project_name=project,
+        )
+    )
+
+
+@when("I load global active invariants via the in-memory service")
+def step_load_global_active_invariants_in_memory(context: Context) -> None:
+    """Load global active invariants without a plan/project context."""
+    context.in_memory_global_loaded_invariants = (
+        context.in_memory_invariant_service.load_active_invariants()
+    )
+
+
+@when('I check action "{action_text}" against the loaded invariants')
+def step_check_action_against_loaded_invariants(
+    context: Context, action_text: str
+) -> None:
+    """Check action text against loaded invariants and capture violations."""
+    try:
+        context.in_memory_invariant_service.check_invariants(
+            action_text,
+            context.in_memory_loaded_invariants,
+        )
+        context.in_memory_violation_error = None
+    except InvariantViolationError as exc:
+        context.in_memory_violation_error = exc
+
+
+@when('I enforce the global invariant for plan "{plan_id}" as violated')
+def step_enforce_global_invariant_as_violated(context: Context, plan_id: str) -> None:
+    """Enforce a global invariant while marking it as violated."""
+    context.in_memory_enforcement_records = (
+        context.in_memory_invariant_service.enforce_invariants(
+            plan_id=plan_id,
+            invariants=[context.in_memory_global_invariant],
+            actor_response="synthetic reconciliation response",
+            violated_invariant_ids=[context.in_memory_global_invariant.id],
+        )
+    )
+
+
 # ---------------------------------------------------------------------------
 # Then steps
 # ---------------------------------------------------------------------------
@@ -158,10 +361,18 @@ def step_assert_list_b_contains(context: Context, text: str) -> None:
 
 @then('the CLI list output from invocation {n:d} should contain "{text}"')
 def step_assert_cli_list_contains(context: Context, n: int, text: str) -> None:
-    """Assert the CLI list output from invocation N contains the given text."""
+    """Assert the CLI list output from invocation N contains the given text.
+
+    Rich renders the invariant list as a table that line-wraps long text
+    values and splits the content across multiple row borders, so a single
+    substring match is brittle. Instead, assert that every word of the
+    expected text appears somewhere in the output.
+    """
     result = getattr(context, f"invariant_cli_result_{n}")
-    assert text in result.output, (
-        f"Expected '{text}' in CLI invocation {n} output but got:\n{result.output}"
+    missing = [word for word in text.split() if word not in result.output]
+    assert not missing, (
+        f"Expected words {missing!r} (from '{text}') in CLI invocation {n} "
+        f"output but got:\n{result.output}"
     )
 
 
@@ -172,3 +383,59 @@ def step_assert_remove_b_success(context: Context) -> None:
         f"Expected remove to succeed but got NotFoundError: "
         f"{context.invariant_remove_b_error}"
     )
+
+
+@then('the repository invariant list should contain inactive "{text}"')
+def step_assert_repository_list_contains_inactive(context: Context, text: str) -> None:
+    """Assert the repository returned the inactive invariant on request."""
+    matches = [inv for inv in context.repository_invariant_list if inv.text == text]
+    assert matches, (
+        f"Expected repository list to contain '{text}' but got "
+        f"{context.repository_invariant_list!r}"
+    )
+    assert matches[0].active is False, "Expected returned invariant to be inactive"
+
+
+@then("the repository get result should be missing")
+def step_assert_repository_get_missing(context: Context) -> None:
+    """Assert a missing repository lookup returns ``None``."""
+    assert context.repository_get_result is None
+
+
+@then("the repository update should raise NotFoundError")
+def step_assert_repository_update_not_found(context: Context) -> None:
+    """Assert updating a missing invariant raised ``NotFoundError``."""
+    assert isinstance(context.repository_update_error, NotFoundError), (
+        f"Expected NotFoundError but got {context.repository_update_error!r}"
+    )
+
+
+@then("an invariant violation should be raised")
+def step_assert_invariant_violation_raised(context: Context) -> None:
+    """Assert the service raised an invariant violation."""
+    assert isinstance(context.in_memory_violation_error, InvariantViolationError), (
+        f"Expected InvariantViolationError but got "
+        f"{context.in_memory_violation_error!r}"
+    )
+
+
+@then('the effective invariant list should contain "{text}"')
+def step_assert_effective_list_contains(context: Context, text: str) -> None:
+    """Assert an invariant text appears in the effective list."""
+    texts = [inv.text for inv in context.in_memory_effective_invariants]
+    assert text in texts, f"Expected '{text}' in effective list but got {texts!r}"
+
+
+@then('the effective invariant list should not contain "{text}"')
+def step_assert_effective_list_excludes(context: Context, text: str) -> None:
+    """Assert an inactive invariant text is excluded from the effective list."""
+    texts = [inv.text for inv in context.in_memory_effective_invariants]
+    assert text not in texts, f"Did not expect '{text}' in effective list: {texts!r}"
+
+
+@then("the enforcement record should be marked not enforced")
+def step_assert_enforcement_record_not_enforced(context: Context) -> None:
+    """Assert the service still records a violated invariant."""
+    records = context.in_memory_enforcement_records
+    assert len(records) == 1, f"Expected one enforcement record, got {records!r}"
+    assert records[0].enforced is False

features/steps/tui_first_run_steps.py

@@ -488,3 +488,99 @@ def step_persona_bar_reflects_actor(context: object) -> None:
     assert "anthropic/claude-sonnet-4-20250514" in bar._text, (
         f"Expected actor in persona bar, got: {bar._text}"
     )
+
+
+# ---------------------------------------------------------------------------
+# TDD regression: issue #11039 - no _render() shadowing Textual Widget._render
+# ---------------------------------------------------------------------------
+
+
+@then("the overlay should not override Textual Widget._render")
+def step_overlay_no_render_override(context: object) -> None:
+    """Verify that ActorSelectionOverlay does NOT define its own ``_render``.
+
+    The Shadowing Bug (issue #11039): ActorSelectionOverlay once defined
+    ``def _render(self) -> None`` which returned ``None``, shadowing
+    ``textual.widgets.Static._render()`` (which returns a
+    :class:`textual.strip.Strip`). This caused the Textual layout engine to
+    crash with ``AttributeError: 'NoneType' object has no attribute
+    'get_height'``.
+
+    The fix renamed the method to ``_refresh_display`` so that the inherited
+    base-class ``_render`` is untouched and returns a proper renderable.
+    """
+    from cleveragents.tui.widgets.actor_selection_overlay import (
+        ActorSelectionOverlay,
+    )
+
+    cls = ActorSelectionOverlay
+    # The overlay should NOT define its own _render in its __dict__.
+    # If it did, _render found on the class would resolve to this method
+    # rather than the Textual base-class implementation.
+    has_own_render = "_render" in cls.__dict__
+    assert not has_own_render, (
+        "ActorSelectionOverlay defines its own _render() which shadows "
+        "Textual Widget._render. This is the bug from issue #11039."
+    )
+
+
+@then("the overlay _refresh_display method should be callable")
+def step_overlay_refresh_display_callable(context: object) -> None:
+    """Verify ``_refresh_display`` exists and is callable after show()."""
+    assert hasattr(context._overlay, "_refresh_display"), (
+        "Overlay must have _refresh_display method"
+    )
+    refresh = context._overlay._refresh_display
+    assert callable(refresh), "_refresh_display must be callable"
+
+
+@then("the inherited Widget._render should return a proper renderable")
+def step_inherited_render_returns_renderable(context: object) -> None:
+    """Verify the inherited ``Widget._render()`` returns a non-None renderable.
+
+    Bug #11039: ``ActorSelectionOverlay`` defined its own ``_render() -> None``
+    which returned ``None``, causing Textual's layout engine to crash.  The
+    fix renamed it to ``_refresh_display()``.  This assertion confirms that
+    when Textual IS available, calling the real inherited ``_render()``
+    produces a proper renderable (not ``None``).  When Textual is not
+    available (``_FallbackStatic`` has no ``_render``), the check passes
+    trivially since the fallback case cannot trigger the shadowing crash.
+    """
+
+    from cleveragents.tui.widgets.actor_selection_overlay import (
+        ActorSelectionOverlay,
+    )
+
+    cls = ActorSelectionOverlay
+    overlay = context._overlay
+
+    render_from_mro = None
+    for base in cls.__mro__[1:]:
+        if "_render" in base.__dict__:
+            render_from_mro = base.__dict__["_render"]
+            break
+
+    if render_from_mro is None:
+        return
+
+    result = render_from_mro(overlay)
+    assert result is not None, (
+        "Bug #11039 regression: inherited Widget._render() returned None. "
+        "ActorSelectionOverlay may still be shadowing the base-class "
+        "_render method, which would cause a NoneType crash during "
+        "Textual layout in textual >=1.0."
+    )
+
+
+@then("_refresh_display should produce correct overlay content")
+def step_refresh_display_produces_content(context: object) -> None:
+    """Invoke ``_refresh_display()`` and verify it renders correct content."""
+    from typing import cast
+
+    overlay = context._overlay
+    overlay._refresh_display()
+    content: str = cast(str, overlay._text)
+    assert content, "_refresh_display must produce non-empty rendered overlay content"
+    assert "Welcome to CleverAgents" in content, (
+        "_refresh_display content must include the welcome header"
+    )

features/tdd_invariant_persistence.feature

@@ -1,52 +1,84 @@
-# TDD issue-capture test for bug #1022 — InvariantService in-memory storage only.
+# TDD issue-capture test for bug #1022 — InvariantService persistence.
 #
-# InvariantService stores invariants in an in-memory dict (self._invariants)
-# with no database persistence layer.  Each CLI invocation spawns a fresh
-# process with a new InvariantService() instance, so all invariants added in
-# one invocation are lost when the process exits.
+# Bug #1022 has been fixed: InvariantService now uses SQLite-based storage
+# via a lazy session-factory pattern.  Invariants added in one CLI invocation
+# persist across process restarts because all instances share the same
+# ``cleveragents.db`` (or equivalent) database configured in Settings.
 #
-# These scenarios prove the bug exists by simulating separate CLI invocations
-# (fresh InvariantService instances) and asserting that data added in one
-# invocation is visible in the next.  They FAIL until the bug is fixed.
-# The @tag inverts the result so CI passes.
-#
-# See: https://git.cleverthis.com/cleveragents/cleveragents-core/issues/1022
+# These scenarios verify cross-instance data visibility by simulating
+# separate CLI invocations (fresh service instances backing a shared DB).
 
-@tdd_issue @tdd_issue_1022 @mock_only
-Feature: TDD Issue #1022 — InvariantService invariants lost across process restarts
+@tdd_issue @tdd_issue_1022
+Feature: TDD Issue #1022 — InvariantService persistence across process restarts
   As a developer using the agents CLI
   I want invariants added via "agents invariant add" to persist across CLI invocations
   So that "agents invariant list" in a subsequent invocation returns previously added invariants
 
-  InvariantService uses in-memory dict storage only.  Each CLI invocation
-  creates a fresh InvariantService() instance, so invariants are lost when
-  the process exits.  These tests simulate separate process invocations by
+  InvariantService uses SQLite-based storage backed by the configured database URL.
+  Fresh service instances share the same underlying database, so data persists across
+  process restarts.  These tests simulate separate process invocations by
   creating fresh service instances and verifying cross-instance data visibility.
 
-  @tdd_issue @tdd_issue_4283 @tdd_expected_fail
+  @tdd_issue_1022
   Scenario: Invariant added in one service instance is visible in a fresh instance
     Given I add a project invariant "All APIs must validate auth tokens" to project "local/api-service" via invariant service instance A
     When I create a fresh invariant service instance B
     And I list project invariants for "local/api-service" via instance B
     Then the invariant list from instance B should contain "All APIs must validate auth tokens"
 
-  @tdd_issue @tdd_issue_4283 @tdd_expected_fail
+  @tdd_issue_1022
   Scenario: Global invariant persists across simulated process restarts
     Given I add a global invariant "Never delete production data" via invariant service instance A
     When I create a fresh invariant service instance B
     And I list global invariants via instance B
     Then the invariant list from instance B should contain "Never delete production data"
 
-  @tdd_issue @tdd_issue_4283 @tdd_expected_fail
+  @tdd_issue_1022
   Scenario: Invariant added via CLI add is visible via CLI list in a new invocation
     Given I invoke invariant add via CLI with "--project local/webapp" and text "All changes need tests" using service invocation 1
     When I invoke invariant list via CLI with "--project local/webapp" using service invocation 2
     Then the CLI list output from invocation 2 should contain "All changes need tests"
 
-  @tdd_issue @tdd_issue_4283 @tdd_expected_fail
+  @tdd_issue_1022
   Scenario: Invariant soft-deleted in a fresh instance after being added in another
     Given I add a project invariant "Temporary constraint" to project "local/temp" via invariant service instance A
     And I capture the invariant ID from instance A
     When I create a fresh invariant service instance B
     And I attempt to remove the captured invariant ID via instance B
     Then the remove operation via instance B should succeed without NotFoundError
+
+  @tdd_issue_1022
+  Scenario: Standalone repository can list inactive invariants on request
+    Given a fresh standalone invariant repository
+    And I repository-create inactive project invariant "Archived constraint" for project "local/archive"
+    When I repository-list inactive project invariants for "local/archive"
+    Then the repository invariant list should contain inactive "Archived constraint"
+
+  @tdd_issue_1022
+  Scenario: Standalone repository reports missing invariants explicitly
+    Given a fresh standalone invariant repository
+    When I repository-get invariant "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+    Then the repository get result should be missing
+    When I repository-update missing invariant "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+    Then the repository update should raise NotFoundError
+
+  @tdd_issue_1022
+  Scenario: Invariant service merges and checks active invariants in memory
+    Given a fresh in-memory invariant service
+    And I add a global invariant "Never delete backups" via the in-memory service
+    And I add a project invariant "Do not deploy secrets" for project "local/app" via the in-memory service
+    And I add an inactive project invariant "Never rotate logs" for project "local/app" via the in-memory service
+    When I list effective project invariants for "local/app" via the in-memory service
+    And I load active invariants for project "local/app" via the in-memory service
+    And I load global active invariants via the in-memory service
+    And I check action "deploy secrets to staging" against the loaded invariants
+    Then an invariant violation should be raised
+    And the effective invariant list should contain "Do not deploy secrets"
+    And the effective invariant list should not contain "Never rotate logs"
+
+  @tdd_issue_1022
+  Scenario: Invariant service records enforcement even when event bus fails
+    Given a fresh in-memory invariant service with a failing event bus
+    And I add a global invariant "Never delete audit logs" via the in-memory service
+    When I enforce the global invariant for plan "plan-event-failure" as violated
+    Then the enforcement record should be marked not enforced

features/tui_first_run.feature

@@ -194,3 +194,23 @@ Feature: TUI first-run experience with actor selection overlay
     And I call _complete_first_run with actor "anthropic/claude-sonnet-4-20250514"
     Then the registry should contain a persona named "default"
     And the persona bar should reflect the new actor
+
+  # -----------------------------------------------------------------------
+  # TDD regression: issue #11039 - no _render() shadowing Textual Widget._render
+  # -----------------------------------------------------------------------
+  # The overlay formerly defined its own _render() returning None, which
+  # shadowed textual.widgets.Static._render and caused layout-engine crashes.
+  # This scenario ensures the rename to _refresh_display eliminated that bug.
+
+  @tdd_issue @tdd_issue_11039
+  Scenario: ActorSelectionOverlay does not define its own _render method
+    Given a new ActorSelectionOverlay
+    Then the overlay should not override Textual Widget._render
+    And the inherited Widget._render should return a proper renderable
+
+  @tdd_issue @tdd_issue_11039
+  Scenario: ActorSelectionOverlay has refresh_display callable instead of render
+    Given a new ActorSelectionOverlay
+    When I call show on the overlay
+    Then the overlay _refresh_display method should be callable
+    And _refresh_display should produce correct overlay content

robot/actor_add_update_enforcement.robot

@@ -0,0 +1,36 @@
+*** Settings ***
+Documentation    Integration tests for actor add --update flag enforcement (issue #1500)
+Resource         ${CURDIR}/common.resource
+Suite Setup      Setup Test Environment
+Suite Teardown   Cleanup Test Environment
+
+*** Variables ***
+${HELPER}    ${CURDIR}/helper_actor_add_update_enforcement.py
+
+*** Test Cases ***
+Actor Add Existing Actor Without Update Flag Fails
+    [Documentation]    Verify that actor add rejects re-adding an existing actor without --update
+    [Tags]    tdd_issue    tdd_issue_1500
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    reject-existing-without-update    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    actor-add-reject-existing-ok
+
+Actor Add Existing Actor With Update Flag Succeeds
+    [Documentation]    Verify that actor add with --update on an existing actor succeeds
+    [Tags]    tdd_issue    tdd_issue_1500
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    accept-existing-with-update    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    actor-add-accept-update-ok
+
+Actor Add New Actor Without Update Flag Succeeds
+    [Documentation]    Verify that actor add on a new actor succeeds without --update
+    [Tags]    tdd_issue    tdd_issue_1500
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    accept-new-without-update    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    actor-add-accept-new-ok

robot/helper_actor_add_update_enforcement.py

@@ -0,0 +1,169 @@
+"""Helper script for actor add --update flag enforcement Robot tests (issue #1500).
+
+Tests that ``agents actor add`` rejects re-adding an existing actor without
+the --update flag, and succeeds when --update is provided or the actor is new.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+from typer.testing import CliRunner
+
+from cleveragents.cli.commands.actor import app as actor_app
+from cleveragents.core.exceptions import NotFoundError
+from cleveragents.domain.models.core.actor import Actor
+
+
+def _make_actor(
+    *,
+    name: str = "local/existing-actor",
+    provider: str = "openai",
+    model: str = "gpt-4",
+    config: dict[str, Any] | None = None,
+    updated_at: datetime | None = None,
+) -> Actor:
+    blob = config or {}
+    return Actor(
+        id=1,
+        name=name,
+        provider=provider,
+        model=model,
+        config_blob=blob,
+        config_hash=Actor.compute_hash(blob),
+        unsafe=False,
+        is_built_in=False,
+        is_default=False,
+        updated_at=updated_at or datetime(2026, 2, 7, 14, 22, 0),
+    )
+
+
+def _write_config(name: str) -> Path:
+    config_data: dict[str, Any] = {
+        "name": name,
+        "provider": "openai",
+        "model": "gpt-4",
+    }
+    with tempfile.NamedTemporaryFile(
+        delete=False, suffix=".json", mode="w", encoding="utf-8"
+    ) as handle:
+        json.dump(config_data, handle)
+        handle.flush()
+    return Path(handle.name)
+
+
+def test_reject_existing_without_update() -> None:
+    """Re-adding an existing actor without --update must exit 1 with an error panel."""
+    actor_name = "local/existing-actor"
+    config_path = _write_config(actor_name)
+    existing = _make_actor(name=actor_name, updated_at=datetime(2026, 2, 7, 14, 22, 0))
+
+    try:
+        runner = CliRunner()
+        with patch("cleveragents.cli.commands.actor._get_services") as mock_svc:
+            registry = MagicMock()
+            registry.get_actor.return_value = existing
+            mock_svc.return_value = (MagicMock(), registry)
+            result = runner.invoke(
+                actor_app,
+                ["add", actor_name, "--config", str(config_path)],
+            )
+    finally:
+        config_path.unlink(missing_ok=True)
+
+    assert result.exit_code == 1, (
+        f"Expected exit code 1 but got {result.exit_code}.\nOutput:\n{result.output}"
+    )
+    assert "Actor already exists" in result.output, (
+        f"Expected 'Actor already exists' in output:\n{result.output}"
+    )
+    assert "Use --update to replace" in result.output, (
+        f"Expected 'Use --update to replace' in output:\n{result.output}"
+    )
+    print("actor-add-reject-existing-ok")
+
+
+def test_accept_existing_with_update() -> None:
+    """Re-adding an existing actor with --update must exit 0 and show
+    'Actor updated'."""
+    actor_name = "local/existing-actor"
+    config_path = _write_config(actor_name)
+    existing = _make_actor(name=actor_name, updated_at=datetime(2026, 2, 7, 14, 22, 0))
+    updated = _make_actor(name=actor_name, updated_at=datetime(2026, 2, 7, 14, 22, 0))
+
+    try:
+        runner = CliRunner()
+        with patch("cleveragents.cli.commands.actor._get_services") as mock_svc:
+            registry = MagicMock()
+            registry.get_actor.return_value = existing
+            registry.upsert_actor.return_value = updated
+            mock_svc.return_value = (MagicMock(), registry)
+            result = runner.invoke(
+                actor_app,
+                ["add", actor_name, "--config", str(config_path), "--update"],
+            )
+    finally:
+        config_path.unlink(missing_ok=True)
+
+    assert result.exit_code == 0, (
+        f"Expected exit code 0 but got {result.exit_code}.\nOutput:\n{result.output}"
+    )
+    assert "Actor updated" in result.output, (
+        f"Expected 'Actor updated' in output:\n{result.output}"
+    )
+    print("actor-add-accept-update-ok")
+
+
+def test_accept_new_without_update() -> None:
+    """Adding a brand-new actor without --update must exit 0 and show 'Actor added'."""
+    actor_name = "local/new-actor"
+    config_path = _write_config(actor_name)
+    new_actor = _make_actor(name=actor_name)
+
+    try:
+        runner = CliRunner()
+        with patch("cleveragents.cli.commands.actor._get_services") as mock_svc:
+            registry = MagicMock()
+            registry.get_actor.side_effect = NotFoundError(
+                resource_type="actor", resource_id=actor_name
+            )
+            registry.upsert_actor.return_value = new_actor
+            mock_svc.return_value = (MagicMock(), registry)
+            result = runner.invoke(
+                actor_app,
+                ["add", actor_name, "--config", str(config_path)],
+            )
+    finally:
+        config_path.unlink(missing_ok=True)
+
+    assert result.exit_code == 0, (
+        f"Expected exit code 0 but got {result.exit_code}.\nOutput:\n{result.output}"
+    )
+    assert "Actor added" in result.output, (
+        f"Expected 'Actor added' in output:\n{result.output}"
+    )
+    print("actor-add-accept-new-ok")
+
+
+def main() -> None:
+    command = sys.argv[1] if len(sys.argv) > 1 else ""
+    dispatch = {
+        "reject-existing-without-update": test_reject_existing_without_update,
+        "accept-existing-with-update": test_accept_existing_with_update,
+        "accept-new-without-update": test_accept_new_without_update,
+    }
+    fn = dispatch.get(command)
+    if fn is None:
+        print(f"Unknown command: {command!r}", file=sys.stderr)
+        sys.exit(1)
+    fn()
+
+
+if __name__ == "__main__":
+    main()

robot/helper_invariant_model.py

@@ -1,188 +0,0 @@
-"""Helper script for Robot Framework invariant model smoke tests."""
-
-from __future__ import annotations
-
-import sys
-import uuid
-from datetime import UTC, datetime
-from pathlib import Path
-
-# Ensure src is importable when run from workspace root
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
-
-from sqlalchemy import create_engine, inspect
-from sqlalchemy.orm import sessionmaker
-
-from cleveragents.infrastructure.database.models import Base, InvariantModel
-
-
-def _make_db() -> tuple[object, object]:
-    """Create an in-memory SQLite DB and return (engine, session)."""
-    engine = create_engine("sqlite:///:memory:", echo=False)
-    Base.metadata.create_all(engine)
-    sm = sessionmaker(bind=engine)
-    session = sm()
-    return engine, session
-
-
-def _make_invariant(description: str, is_active: bool = True) -> InvariantModel:
-    return InvariantModel(
-        id=str(uuid.uuid4()),
-        description=description,
-        created_at=datetime.now(tz=UTC).isoformat(),
-        is_active=is_active,
-    )
-
-
-def _test_create_invariant() -> None:
-    """Create an Invariant with all required fields and verify persistence."""
-    _, session = _make_db()
-    inv = _make_invariant("All plans must have a goal")
-    session.add(inv)
-    session.commit()
-
-    retrieved = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert retrieved is not None, "Invariant not found after persist"
-    assert retrieved.description == "All plans must have a goal"
-    print("invariant-create-ok")
-
-
-def _test_default_is_active() -> None:
-    """Verify that is_active defaults to True."""
-    _, session = _make_db()
-    inv = _make_invariant("Default active invariant")
-    session.add(inv)
-    session.commit()
-
-    retrieved = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert retrieved is not None
-    assert retrieved.is_active is True or retrieved.is_active == 1, (
-        f"Expected is_active=True, got {retrieved.is_active!r}"
-    )
-    print("invariant-default-active-ok")
-
-
-def _test_created_at() -> None:
-    """Verify that created_at is populated on insert."""
-    _, session = _make_db()
-    inv = _make_invariant("Timestamped invariant")
-    session.add(inv)
-    session.commit()
-
-    retrieved = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert retrieved is not None
-    assert retrieved.created_at, "created_at should not be empty"
-    assert len(str(retrieved.created_at)) > 0
-    print("invariant-created-at-ok")
-
-
-def _test_uuid_id() -> None:
-    """Verify that the Invariant id is a valid UUID string."""
-    _, session = _make_db()
-    inv = _make_invariant("UUID invariant")
-    session.add(inv)
-    session.commit()
-
-    retrieved = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert retrieved is not None
-    try:
-        uuid.UUID(str(retrieved.id))
-    except ValueError as exc:
-        raise AssertionError(f"id '{retrieved.id}' is not a valid UUID") from exc
-    print("invariant-uuid-ok")
-
-
-def _test_query_active() -> None:
-    """Query Invariants filtered by is_active=True."""
-    _, session = _make_db()
-    for i in range(3):
-        session.add(_make_invariant(f"Active {i}", is_active=True))
-    for i in range(2):
-        session.add(_make_invariant(f"Inactive {i}", is_active=False))
-    session.commit()
-
-    results = session.query(InvariantModel).filter_by(is_active=True).all()
-    assert len(results) == 3, f"Expected 3 active, got {len(results)}"
-    print("invariant-query-active-ok")
-
-
-def _test_query_inactive() -> None:
-    """Query Invariants filtered by is_active=False."""
-    _, session = _make_db()
-    for i in range(3):
-        session.add(_make_invariant(f"Active {i}", is_active=True))
-    for i in range(2):
-        session.add(_make_invariant(f"Inactive {i}", is_active=False))
-    session.commit()
-
-    results = session.query(InvariantModel).filter_by(is_active=False).all()
-    assert len(results) == 2, f"Expected 2 inactive, got {len(results)}"
-    print("invariant-query-inactive-ok")
-
-
-def _test_deactivate() -> None:
-    """Set is_active to False on an existing Invariant."""
-    _, session = _make_db()
-    inv = _make_invariant("Active invariant to deactivate", is_active=True)
-    session.add(inv)
-    session.commit()
-
-    retrieved = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert retrieved is not None
-    retrieved.is_active = False
-    session.commit()
-
-    updated = session.query(InvariantModel).filter_by(id=inv.id).first()
-    assert updated is not None
-    assert updated.is_active is False or updated.is_active == 0, (
-        f"Expected is_active=False, got {updated.is_active!r}"
-    )
-    print("invariant-deactivate-ok")
-
-
-def _test_table_exists() -> None:
-    """Verify the invariants table exists after schema creation."""
-    engine, _ = _make_db()
-    inspector = inspect(engine)
-    tables = inspector.get_table_names()
-    assert "invariants" in tables, f"Table 'invariants' not found. Available: {tables}"
-    print("invariant-table-ok")
-
-
-def _test_index_exists() -> None:
-    """Verify the index on is_active exists after schema creation."""
-    engine, _ = _make_db()
-    inspector = inspect(engine)
-    indexes = inspector.get_indexes("invariants")
-    index_names = [idx["name"] for idx in indexes]
-    assert any("is_active" in name for name in index_names), (
-        f"No index on is_active found. Indexes: {index_names}"
-    )
-    print("invariant-index-ok")
-
-
-_TESTS = {
-    "create_invariant": _test_create_invariant,
-    "default_is_active": _test_default_is_active,
-    "created_at": _test_created_at,
-    "uuid_id": _test_uuid_id,
-    "query_active": _test_query_active,
-    "query_inactive": _test_query_inactive,
-    "deactivate": _test_deactivate,
-    "table_exists": _test_table_exists,
-    "index_exists": _test_index_exists,
-}
-
-if __name__ == "__main__":
-    if len(sys.argv) < 2:
-        print(f"Usage: {sys.argv[0]} <test_name>")
-        print(f"Available tests: {', '.join(sorted(_TESTS))}")
-        sys.exit(1)
-
-    test_name = sys.argv[1]
-    if test_name not in _TESTS:
-        print(f"Unknown test: {test_name}")
-        print(f"Available: {', '.join(sorted(_TESTS))}")
-        sys.exit(1)
-
-    _TESTS[test_name]()

robot/helper_tdd_invariant_persistence.py

@@ -1,12 +1,13 @@
-"""Helper script for tdd_invariant_persistence.robot (bug #1022).
+"""Helper script for tdd_invariant_persistence.robot (bug #1022, now fixed).
 
 Exercises InvariantService cross-invocation persistence at the integration
 level.  Each subcommand simulates a fresh CLI process by creating a new
 InvariantService instance, mirroring how the real CLI works (each
 ``python -m cleveragents`` call gets its own service).
 
-Bug #1022: InvariantService stores invariants in an in-memory dict only.
-Invariants added in one CLI invocation are lost when the process exits.
+Bug #8573 / #1022 is now FIXED: InvariantService uses SQLite-based persistence
+via the configured ``database_url``, so invariants added in one CLI invocation
+persist across process restarts.
 
 This helper is called from Robot Framework via ``Run Process``.
 """
@@ -51,11 +52,15 @@ def add_then_list_project() -> None:
         print(f"FAIL-ADD: exit={add_result.exit_code} out={add_result.output}")
         sys.exit(1)
 
-    # Invocation 2: list (fresh service — simulates new process)
+    # Invocation 2: list (fresh service — simulates new process).
+    # Use --format json so the invariant text is emitted verbatim instead of
+    # being soft-wrapped by the default Rich table renderer (which breaks
+    # substring matching when the text spans multiple visual rows).
     svc2 = InvariantService()
     with patch("cleveragents.cli.commands.invariant._get_service", return_value=svc2):
         list_result = runner.invoke(
-            invariant_app, ["list", "--project", "local/test-proj"]
+            invariant_app,
+            ["list", "--project", "local/test-proj", "--format", "json"],
         )
 
     # The list output should contain the invariant — if it doesn't, bug exists
@@ -83,7 +88,9 @@ def add_then_list_global() -> None:
 
     svc2 = InvariantService()
     with patch("cleveragents.cli.commands.invariant._get_service", return_value=svc2):
-        list_result = runner.invoke(invariant_app, ["list", "--global"])
+        list_result = runner.invoke(
+            invariant_app, ["list", "--global", "--format", "json"]
+        )
 
     if "Never expose credentials" in list_result.output:
         print("invariant-persist-global-ok")

robot/invariant_model.robot

@@ -1,63 +0,0 @@
-*** Settings ***
-Documentation    Smoke tests for Invariant data model persistence contract
-Resource         ${CURDIR}/common.resource
-Suite Setup      Setup Test Environment With Database Isolation
-Suite Teardown   Cleanup Test Environment
-
-*** Variables ***
-${HELPER_SCRIPT}    robot/helper_invariant_model.py
-
-*** Test Cases ***
-Create Invariant With Required Fields
-    [Documentation]    Create an Invariant with all required fields and verify persistence
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    create_invariant    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=create_invariant failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-create-ok
-
-Is Active Defaults To True
-    [Documentation]    Verify that is_active defaults to True on a new Invariant
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    default_is_active    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=default_is_active failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-default-active-ok
-
-Created At Is Populated
-    [Documentation]    Verify that created_at is auto-populated on insert
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    created_at    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=created_at failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-created-at-ok
-
-Id Is UUID
-    [Documentation]    Verify that the Invariant id is a valid UUID string
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    uuid_id    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=uuid_id failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-uuid-ok
-
-Query Active Invariants
-    [Documentation]    Query Invariants filtered by is_active=True
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    query_active    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=query_active failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-query-active-ok
-
-Query Inactive Invariants
-    [Documentation]    Query Invariants filtered by is_active=False
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    query_inactive    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=query_inactive failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-query-inactive-ok
-
-Deactivate Invariant
-    [Documentation]    Set is_active to False on an existing Invariant
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    deactivate    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=deactivate failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-deactivate-ok
-
-Table Exists After Migration
-    [Documentation]    Verify the invariants table exists after schema creation
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    table_exists    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=table_exists failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-table-ok
-
-Index On Is Active Exists
-    [Documentation]    Verify the index on is_active exists after schema creation
-    ${result}=    Run Process    ${PYTHON}    ${HELPER_SCRIPT}    index_exists    cwd=${WORKSPACE}
-    Should Be Equal As Integers    ${result.rc}    0    msg=index_exists failed: ${result.stderr}
-    Should Contain    ${result.stdout}    invariant-index-ok

robot/tdd_invariant_persistence.robot

@@ -1,14 +1,10 @@
 *** Settings ***
-Documentation    TDD Issue #1022 — InvariantService invariants lost across CLI invocations
-...              Integration tests verifying that invariants added via the CLI
-...              persist across simulated process restarts.  InvariantService
-...              stores invariants in an in-memory dict only, so each CLI
-...              invocation starts with an empty service.  These tests exercise
-...              add-then-list and add-then-remove across fresh service
-...              instances.  They fail until the bug is fixed; the
-...              tag inverts the result so CI passes.
+Documentation    TDD Issue #1022 — InvariantService invariant persistence
+...              These tests verify that invariants added via the CLI persist
+...              across simulated process restarts.  Each test is a separate
+...              CLI invocation that adds then lists or removes an invariant.
 Resource         ${CURDIR}/common.resource
-Suite Setup      Setup Test Environment
+Suite Setup      Setup Test Environment With Database Isolation
 Suite Teardown   Cleanup Test Environment
 
 *** Variables ***
@@ -17,7 +13,7 @@ ${HELPER}    ${CURDIR}/helper_tdd_invariant_persistence.py
 *** Test Cases ***
 TDD Invariant Add Then List Project Across Invocations
     [Documentation]    Add a project invariant in invocation 1, list in invocation 2.
-    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318    tdd_expected_fail
+    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318
 
     ${result}=    Run Process    ${PYTHON}    ${HELPER}    add-then-list-project    cwd=${WORKSPACE}    timeout=30s    on_timeout=kill
     Log    ${result.stdout}
@@ -27,7 +23,7 @@ TDD Invariant Add Then List Project Across Invocations
 
 TDD Invariant Add Then List Global Across Invocations
     [Documentation]    Add a global invariant in invocation 1, list in invocation 2.
-    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318    tdd_expected_fail
+    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318
 
     ${result}=    Run Process    ${PYTHON}    ${HELPER}    add-then-list-global    cwd=${WORKSPACE}    timeout=30s    on_timeout=kill
     Log    ${result.stdout}
@@ -37,7 +33,7 @@ TDD Invariant Add Then List Global Across Invocations
 
 TDD Invariant Remove Cross Instance
     [Documentation]    Add invariant in instance 1, remove by ID in instance 2.
-    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318    tdd_expected_fail
+    [Tags]  tdd_issue    tdd_issue_1022    tdd_issue    tdd_issue_4318
 
     ${result}=    Run Process    ${PYTHON}    ${HELPER}    add-then-remove-cross    cwd=${WORKSPACE}    timeout=30s    on_timeout=kill
     Log    ${result.stdout}

scripts/update_context_policy.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Update context_policy.py with strategy configuration support."""
+
+import sys
+from pathlib import Path
+
+# Read the file
+policy_file = Path("src/cleveragents/domain/models/core/context_policy.py")
+content = policy_file.read_text()
+
+# Update the imports to include Any
+content = content.replace(
+    "from typing import TYPE_CHECKING", "from typing import TYPE_CHECKING, Any"
+)
+
+# Add VALID_STRATEGIES constant after VALID_PHASES
+old_phases = (
+    "VALID_PHASES: frozenset[str] = frozenset("
+    '{"default", "strategize", "execute", "apply"})'
+)
+new_phases = (
+    "VALID_PHASES: frozenset[str] = frozenset("
+    '{"default", "strategize", "execute", "apply"})\n\n'
+    "VALID_STRATEGIES: frozenset[str] = frozenset({\n"
+    '    "basic",\n'
+    '    "semantic",\n'
+    '    "relevance_scoring",\n'
+    '    "adaptive",\n'
+    '    "fusion",\n'
+    "})"
+)
+content = content.replace(old_phases, new_phases)
+
+# Update the docstring for ProjectContextPolicy to mention strategy
+old_docstring = (
+    "class ProjectContextPolicy(BaseModel):\n"
+    '    """Controls what context is available during each ACMS phase.\n'
+    "\n"
+    "    Uses view inheritance: ``default`` → ``strategize`` →\n"
+    "    ``execute`` → ``apply``.  Each phase can override or inherit\n"
+    "    from its parent.\n"
+    "\n"
+    "    An empty ``ProjectContextPolicy()`` defaults to including\n"
+    "    everything (the ``default_view`` has empty include lists which\n"
+    '    means "all").\n'
+    '    """'
+)
+
+new_docstring = (
+    "class ProjectContextPolicy(BaseModel):\n"
+    '    """Controls what context is available during each ACMS phase.\n'
+    "\n"
+    "    Uses view inheritance: ``default`` → ``strategize`` →\n"
+    "    ``execute`` → ``apply``.  Each phase can override or inherit\n"
+    "    from its parent.\n"
+    "\n"
+    "    An empty ``ProjectContextPolicy()`` defaults to including\n"
+    "    everything (the ``default_view`` has empty include lists which\n"
+    '    means "all").\n'
+    "\n"
+    "    Optionally specifies a context assembly strategy and its\n"
+    "    configuration parameters.\n"
+    '    """'
+)
+
+content = content.replace(old_docstring, new_docstring)
+
+# Add strategy and strategy_config fields before the resolve_view method
+old_fields = (
+    "    apply_view: ContextView | None = Field(\n"
+    "        default=None,\n"
+    '        description=("Overrides for Apply (inherits from execute if None)"),\n'
+    "    )\n"
+    "\n"
+    "    def resolve_view(self, phase: str) -> ContextView:"
+)
+
+error_msg = "f\"Invalid strategy '{v}': must be one of {sorted(VALID_STRATEGIES)}\""
+
+new_fields = (
+    "    apply_view: ContextView | None = Field(\n"
+    "        default=None,\n"
+    '        description=("Overrides for Apply (inherits from execute if None)"),\n'
+    "    )\n"
+    "    strategy: str | None = Field(\n"
+    "        default=None,\n"
+    "        description=(\n"
+    '            "Context assembly strategy name. "\n'
+    '            "Valid values: basic, semantic, relevance_scoring, adaptive, fusion"\n'
+    "        ),\n"
+    "    )\n"
+    "    strategy_config: dict[str, Any] | None = Field(\n"
+    "        default=None,\n"
+    '        description="Strategy-specific configuration parameters",\n'
+    "    )\n"
+    "\n"
+    '    @field_validator("strategy")\n'
+    "    @classmethod\n"
+    "    def _validate_strategy(\n"
+    "        cls: type[ProjectContextPolicy],\n"
+    "        v: str | None,\n"
+    "    ) -> str | None:\n"
+    '        """Validate that strategy name is in the list of valid strategies."""\n'
+    "        if v is not None and v not in VALID_STRATEGIES:\n"
+    "            raise ValueError(\n"
+    "                " + error_msg + "\n"
+    "            )\n"
+    "        return v\n"
+    "\n"
+    "    def resolve_view(self, phase: str) -> ContextView:"
+)
+
+content = content.replace(old_fields, new_fields)
+
+# Write the updated content
+policy_file.write_text(content)
+
+print("Updated context_policy.py successfully")
+sys.exit(0)

src/cleveragents/a2a/events.py

@@ -15,6 +15,7 @@ publishes translated :class:`A2aEvent` instances to an event queue.
 
 from __future__ import annotations
 
+import contextlib
 import json
 import threading
 from collections.abc import Callable
@@ -25,6 +26,7 @@ from ulid import ULID
 
 from cleveragents.a2a.errors import A2aNotAvailableError
 from cleveragents.a2a.models import A2aEvent
+from cleveragents.infrastructure.events.types import EventType
 
 # ---------------------------------------------------------------------------
 # SSE event type constants (A2A protocol)
@@ -289,20 +291,35 @@ class EventBusBridge:
         self._event_bus = event_bus
         self._event_queue = event_queue
         self._subscription: Any | None = None
+        self._subscribed_types: frozenset[EventType] | None = None
 
     def start(self) -> None:
         """Subscribe to the event bus and begin forwarding."""
-        if hasattr(self._event_bus, "subscribe"):
+        if not hasattr(self._event_bus, "subscribe"):
+            return
+        subscribed_types = frozenset(EventType)
+        try:
+            for et in subscribed_types:
+                self._event_bus.subscribe(et, self._on_domain_event)
+        except TypeError:
+            self._subscribed_types = None
             self._subscription = self._event_bus.subscribe(self._on_domain_event)
-            logger.info("a2a.event_bridge.started")
+        else:
+            self._subscribed_types = subscribed_types
+        logger.info("a2a.event_bridge.started")
 
     def stop(self) -> None:
         """Unsubscribe from the event bus."""
+        if self._subscribed_types is not None:
+            for et in self._subscribed_types:
+                with contextlib.suppress(TypeError, AttributeError):
+                    self._event_bus.unsubscribe(et, self._on_domain_event)
+            self._subscribed_types = None
         if self._subscription is not None:
             if hasattr(self._subscription, "dispose"):
                 self._subscription.dispose()
             self._subscription = None
-            logger.info("a2a.event_bridge.stopped")
+        logger.info("a2a.event_bridge.stopped")
 
     def _on_domain_event(self, domain_event: Any) -> None:
         """Translate a domain event to an A2A event and publish."""

src/cleveragents/acms/index.py

@@ -1,20 +1,34 @@
-"""ACMS Index Data Model and File Traversal Engine.
+"""ACMS Index data model, file traversal, and chunked traversal engine.
 
-Provides the foundational data model for indexed context entries and a
-file traversal engine that can handle 10,000+ files without timeout using
-chunked processing.
+Combines two related ACMS features:
 
-Based on issue #9579 and ``docs/specification.md`` ~lines 44405-44420.
+* The ACMS index data model and bulk ``FileTraversalEngine`` for indexing
+  10,000+ files without timeout (issue #9579, ``docs/specification.md``
+  ~lines 44405-44420).
+* The :class:`ChunkedFileTraverser` and :class:`AcmsIndexEntry` used by the
+  ``context add`` CLI command for tag- and policy-aware indexing with
+  progress callbacks (issue #9982).
 """
 
 from __future__ import annotations
 
-from collections.abc import Iterator
+import hashlib
+from collections.abc import Callable, Generator, Iterator
 from datetime import datetime
 from enum import StrEnum
+from fnmatch import fnmatch
 from pathlib import Path
+from typing import Any
 
-from pydantic import BaseModel, Field
+import structlog
+from pydantic import BaseModel, Field, model_validator
+
+logger = structlog.get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Issue #9579: ACMS index data model and bulk traversal engine
+# ---------------------------------------------------------------------------
 
 
 class FileType(StrEnum):
@@ -403,8 +417,270 @@ class FileTraversalEngine:
         self.index = ACMSIndex()
 
 
-__all__ = [
+# ---------------------------------------------------------------------------
+# Issue #9982: ChunkedFileTraverser for `context add`
+# ---------------------------------------------------------------------------
+
+DEFAULT_IGNORE_PATTERNS: frozenset[str] = frozenset(
+    [
+        "__pycache__",
+        ".git",
+        ".pytest_cache",
+        ".coverage",
+        ".mypy_cache",
+        ".ruff_cache",
+        "node_modules",
+        ".venv",
+        "venv",
+        ".env",
+        "*.pyc",
+        "*.pyo",
+        "*.pyd",
+        "*.so",
+        "*.dll",
+        "*.exe",
+        "*.db",
+        "*.sqlite",
+    ]
+)
+
+# Default chunk size for directory traversal progress reporting.
+DEFAULT_CHUNK_SIZE: int = 50
+
+
+class AcmsIndexEntry(BaseModel):
+    """A single entry in the ACMS index.
+
+    Represents a file that has been indexed into the ACMS system with
+    optional tags and a policy hint.
+
+    Attributes:
+        path: Absolute path to the indexed file.
+        content: Text content of the file (UTF-8, errors ignored).
+        content_hash: SHA-256 hex digest of the content.
+        size_bytes: File size in bytes.
+        tags: Ordered list of user-supplied tags (e.g. ``["api", "core"]``).
+        policy: Optional named policy associated with this entry
+            (e.g. ``"strict"``).
+        metadata: Arbitrary key-value metadata for extensibility.
+    """
+
+    path: Path
+    content: str
+    content_hash: str
+    size_bytes: int
+    tags: list[str] = Field(default_factory=list)
+    policy: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _validate_entry(self) -> AcmsIndexEntry:
+        if not self.path.is_absolute():
+            raise ValueError(f"AcmsIndexEntry.path must be absolute, got {self.path!r}")
+        if self.size_bytes < 0:
+            raise ValueError(
+                f"AcmsIndexEntry.size_bytes must be non-negative, got {self.size_bytes}"
+            )
+        return self
+
+
+class ChunkedFileTraverser:
+    """Traverse a file or directory in fixed-size chunks with progress callbacks.
+
+    Yields :class:`AcmsIndexEntry` objects for each file discovered.
+    After each chunk of ``chunk_size`` files the optional
+    ``on_progress`` callback is invoked with ``(indexed_so_far, total)``.
+
+    Example::
+
+        def show_progress(done: int, total: int) -> None:
+            print(f"Indexing... [{done}/{total} files]")
+
+        traverser = ChunkedFileTraverser(
+            chunk_size=50,
+            on_progress=show_progress,
+        )
+        for entry in traverser.traverse(Path("/my/project"), recursive=True):
+            print(entry.path)
+
+    Args:
+        chunk_size: Number of files per progress-reporting chunk.
+            Must be >= 1.  Defaults to :data:`DEFAULT_CHUNK_SIZE`.
+        on_progress: Optional callback ``(done: int, total: int) -> None``
+            invoked after each chunk and at completion.
+        ignore_patterns: Frozenset of glob patterns to skip.  Defaults to
+            :data:`DEFAULT_IGNORE_PATTERNS`.
+        max_file_size: Maximum file size in bytes.  Files larger than this
+            are skipped.  ``None`` means no limit.
+        tags: Tags to attach to every indexed entry.
+        policy: Policy name to attach to every indexed entry.
+    """
+
+    def __init__(
+        self,
+        *,
+        chunk_size: int = DEFAULT_CHUNK_SIZE,
+        on_progress: Callable[[int, int], None] | None = None,
+        ignore_patterns: frozenset[str] = DEFAULT_IGNORE_PATTERNS,
+        max_file_size: int | None = None,
+        tags: list[str] | None = None,
+        policy: str | None = None,
+    ) -> None:
+        if chunk_size < 1:
+            raise ValueError(f"chunk_size must be >= 1, got {chunk_size}")
+        self._chunk_size = chunk_size
+        self._on_progress = on_progress
+        self._ignore_patterns = ignore_patterns
+        self._max_file_size = max_file_size
+        self._tags: list[str] = list(tags) if tags else []
+        self._policy = policy
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def traverse(
+        self,
+        path: Path,
+        *,
+        recursive: bool = True,
+    ) -> Iterator[AcmsIndexEntry]:
+        """Traverse *path* and yield :class:`AcmsIndexEntry` objects.
+
+        If *path* is a file, yields a single entry (if not ignored).
+        If *path* is a directory, yields entries for all matching files.
+
+        Args:
+            path: File or directory to index.
+            recursive: When *path* is a directory, traverse sub-directories
+                recursively.  Ignored when *path* is a file.
+
+        Yields:
+            :class:`AcmsIndexEntry` for each indexed file.
+
+        Raises:
+            FileNotFoundError: If *path* does not exist.
+            ValueError: If *path* is neither a file nor a directory.
+        """
+        if not path.exists():
+            raise FileNotFoundError(f"Path does not exist: {path}")
+
+        if path.is_file():
+            yield from self._traverse_file(path)
+        elif path.is_dir():
+            yield from self._traverse_directory(path, recursive=recursive)
+        else:
+            raise ValueError(f"Path is neither a file nor a directory: {path}")
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _should_ignore(self, path: Path) -> bool:
+        """Return ``True`` if *path* matches any ignore pattern."""
+        name = path.name
+        parts = set(path.parts)
+        for pattern in self._ignore_patterns:
+            if any(c in pattern for c in "*?["):
+                if fnmatch(name, pattern):
+                    return True
+            else:
+                if name == pattern or pattern in parts:
+                    return True
+        return False
+
+    def _read_file(self, path: Path) -> AcmsIndexEntry | None:
+        """Read *path* and return an :class:`AcmsIndexEntry`, or ``None`` to skip."""
+        if self._should_ignore(path):
+            return None
+
+        try:
+            size = path.stat().st_size
+        except OSError:
+            return None
+
+        if self._max_file_size is not None and size > self._max_file_size:
+            logger.debug(
+                "acms.traverser.file_skipped_size",
+                path=str(path),
+                size=size,
+                max_file_size=self._max_file_size,
+            )
+            return None
+
+        try:
+            content = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            return None
+
+        content_hash = hashlib.sha256(
+            content.encode("utf-8", errors="ignore")
+        ).hexdigest()
+
+        return AcmsIndexEntry(
+            path=path.resolve(),
+            content=content,
+            content_hash=content_hash,
+            size_bytes=size,
+            tags=list(self._tags),
+            policy=self._policy,
+        )
+
+    def _traverse_file(self, path: Path) -> Generator[AcmsIndexEntry]:
+        """Yield a single entry for a file path."""
+        entry = self._read_file(path)
+        if entry is not None:
+            if self._on_progress is not None:
+                self._on_progress(1, 1)
+            yield entry
+
+    def _traverse_directory(
+        self,
+        directory: Path,
+        *,
+        recursive: bool,
+    ) -> Generator[AcmsIndexEntry]:
+        """Yield entries for all files in *directory*."""
+        # Collect all candidate file paths first so we can report total.
+        if recursive:
+            candidates = [p for p in directory.rglob("*") if p.is_file()]
+        else:
+            candidates = [p for p in directory.iterdir() if p.is_file()]
+
+        total = len(candidates)
+        indexed = 0
+
+        for i, file_path in enumerate(candidates):
+            entry = self._read_file(file_path)
+            if entry is not None:
+                indexed += 1
+                yield entry
+
+            # Report progress after each chunk boundary or at the end.
+            chunk_boundary = (i + 1) % self._chunk_size == 0
+            is_last = i == total - 1
+            if self._on_progress is not None and (chunk_boundary or is_last):
+                self._on_progress(indexed, total)
+
+        logger.debug(
+            "acms.traverser.directory_traversed",
+            directory=str(directory),
+            total_candidates=total,
+            indexed=indexed,
+            recursive=recursive,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Module exports
+# ---------------------------------------------------------------------------
+
+__all__: list[str] = [
+    "DEFAULT_CHUNK_SIZE",
+    "DEFAULT_IGNORE_PATTERNS",
     "ACMSIndex",
+    "AcmsIndexEntry",
+    "ChunkedFileTraverser",
     "FileTraversalEngine",
     "FileType",
     "IndexEntry",

src/cleveragents/application/container.py

@@ -756,9 +756,11 @@ class Container(containers.DeclarativeContainer):
         event_bus=event_bus,
     )
 
-    # Invariant Service - Singleton (in-memory invariant management)
+    # Invariant Service - Singleton (database-backed persistence via ADR-007)
     invariant_service = providers.Singleton(
         InvariantService,
+        event_bus=event_bus,
+        database_url=database_url,
     )
 
     # Lock Service - Singleton (shared advisory-lock state per process, #7989)

src/cleveragents/application/services/fix_then_revalidate.py

@@ -42,6 +42,7 @@ import threading
 from collections import defaultdict
 from collections.abc import Callable
 from datetime import UTC, datetime
+from typing import cast
 
 import structlog
 from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -287,14 +288,14 @@ class FixThenRevalidateOrchestrator:
                 "auto_validation_fix must be between 0.0 and 1.0, "
                 f"got {auto_validation_fix}"
             )
-        if event_bus is not None and not isinstance(event_bus, EventBus):
+        if event_bus is not None and not callable(getattr(event_bus, "emit", None)):
             raise ValidationError("event_bus must be an EventBus instance or None")
 
         self._pipeline = validation_pipeline
         self._max_retries = max_retries
         self._auto_strategy_revision = float(auto_strategy_revision)
         self._auto_validation_fix = float(auto_validation_fix)
-        self._event_bus = event_bus
+        self._event_bus = cast(EventBus | None, event_bus)
         # Per-(plan_id, validation_key) retry counters.
         # Inner key is (validation_name, resource_id) to prevent
         # same-named validations on different resources from sharing

src/cleveragents/application/services/invariant_service.py

@@ -6,8 +6,15 @@ lifecycle operations.
 
 ## Storage
 
-Uses in-memory storage (same pattern as ``PlanLifecycleService``) with
-a dict keyed by invariant ID.
+Uses SQLite-based persistence via a lazy session-factory pattern (ADR-007).
+When a ``database_url`` is provided at construction, invariants are stored
+in the ``invariants`` table and persist across CLI invocations (process
+restarts).  When no ``database_url`` is provided the service falls back to
+pure in-memory mode (unchanged legacy behaviour — useful for testing).
+
+Standalone invariants are stored in the ``invariants`` table, separate
+from action-level (``action_invariants``) and plan-level
+(``plan_invariants``) child tables.
 
 ## Merge Precedence
 
@@ -26,10 +33,12 @@ Based on ``docs/specification.md`` and implementation plan Stage M3.5.
 
 from __future__ import annotations
 
+import os
 from threading import RLock
 from typing import TYPE_CHECKING
 
 import structlog
+from sqlalchemy import create_engine as _create_engine
 from ulid import ULID
 
 from cleveragents.application.services.prompt_sanitizer import PromptSanitizer
@@ -48,6 +57,11 @@ from cleveragents.infrastructure.events.models import DomainEvent
 from cleveragents.infrastructure.events.types import EventType
 
 if TYPE_CHECKING:
+    from sqlalchemy.orm import Session, sessionmaker
+
+    from cleveragents.domain.repositories.invariant_repository import (
+        InvariantRepositoryProtocol,
+    )
     from cleveragents.infrastructure.events.protocol import EventBus
 
 logger = structlog.get_logger(__name__)
@@ -57,18 +71,25 @@ class InvariantService:
     """Service for managing invariant constraints.
 
     Provides add, list, remove (soft-delete), effective-set computation,
-    and enforcement record creation.  All storage is in-memory.
+    and enforcement record creation.  Storage is database-backed when a
+    ``database_url`` is provided at construction; otherwise in-memory.
 
     Thread safety is provided via a ``threading.RLock`` that protects all
     shared state mutations so that concurrent readers and writers cannot
     race or raise ``RuntimeError: dictionary changed size during iteration``.
     """
 
-    def __init__(self, event_bus: EventBus | None = None) -> None:
-        """Initialise the invariant service with empty in-memory storage.
+    def __init__(
+        self, event_bus: EventBus | None = None, database_url: str | None = None
+    ) -> None:
+        """Initialise the invariant service.
 
         Args:
             event_bus: Optional EventBus for domain event emission.
+            database_url: SQLAlchemy database URL for persistence
+                (e.g. ``"sqlite:///~/.cleveragents/cleveragents.db"``).
+                When provided, all CRUD operations use the database.
+                When ``None``, operates in pure in-memory mode.
         """
         self._invariants: dict[str, Invariant] = {}
         self._enforcement_records: list[InvariantEnforcementRecord] = []
@@ -77,11 +98,110 @@ class InvariantService:
         self._sanitizer = PromptSanitizer()
         self._event_bus = event_bus
 
+        # Database-backed path. When no URL was passed explicitly, fall
+        # back to CLEVERAGENTS_DATABASE_URL so callers that construct the
+        # service without going through the DI container (notably the
+        # invariant CLI commands + Behave step definitions) still get
+        # cross-instance persistence.
+        self._database_url = database_url or os.environ.get("CLEVERAGENTS_DATABASE_URL")
+        self._session_factory: sessionmaker[Session] | None = None
+        self._invariant_repository: InvariantRepositoryProtocol | None = None
+        self._has_loaded_from_db: bool = False
+
+    # ------------------------------------------------------------------
+    # Session-factory helpers (lazy init)
+    # ------------------------------------------------------------------
+
+    def _ensure_session_factory(self) -> sessionmaker[Session]:
+        """Get or create a lazy session factory from ``database_url``."""
+        with self._lock:
+            if self._session_factory is None and self._database_url is not None:
+                # Run migrations (or, under tests, the patched template-copy
+                # fast path) so the ``invariants`` table exists before we hand
+                # the engine to sessionmaker.  Bypassing this leaves the DB
+                # empty for callers that instantiate InvariantService outside
+                # the DI container (notably the invariant CLI commands).
+                try:
+                    from cleveragents.infrastructure.database.migration_runner import (
+                        MigrationRunner,
+                    )
+
+                    MigrationRunner(database_url=self._database_url).init_or_upgrade()
+                except Exception as exc:  # pragma: no cover - defensive
+                    self._logger.warning(
+                        "MigrationRunner.init_or_upgrade failed; "
+                        "InvariantService will attempt to proceed",
+                        error=str(exc),
+                    )
+
+                engine = _create_engine(
+                    self._database_url,
+                    echo=False,
+                    future=True,
+                    isolation_level="SERIALIZABLE",
+                    connect_args={"check_same_thread": False}
+                    if self._database_url.startswith("sqlite")
+                    else {},
+                )
+                from sqlalchemy.orm import sessionmaker
+
+                self._session_factory = sessionmaker(
+                    bind=engine,
+                    expire_on_commit=False,
+                    autoflush=False,
+                    autocommit=False,
+                )
+        assert self._session_factory is not None  # Guaranteed by guard above
+        return self._session_factory
+
+    def _ensure_invariant_repository(self) -> InvariantRepositoryProtocol:
+        """Get or create the SQLAlchemy-backed invariant repository."""
+        with self._lock:
+            if self._invariant_repository is None:
+                from cleveragents.infrastructure.database.invariant_repository import (
+                    InvariantRepository,
+                )
+
+                self._invariant_repository = InvariantRepository(
+                    self._ensure_session_factory(),
+                    auto_commit=True,
+                )
+            return self._invariant_repository
+
+    def _ensure_loaded_from_db(self) -> None:
+        """Populate the in-memory cache from the database (one-shot)."""
+        if (
+            self._database_url is not None
+            and self._session_factory is not None
+            and not self._has_loaded_from_db
+        ):
+            session = self._session_factory()
+            try:
+                from cleveragents.infrastructure.database.models import InvariantModel
+
+                rows = (
+                    session.query(InvariantModel)
+                    .filter(InvariantModel.active == True)  # noqa: E712
+                    .all()
+                )
+                with self._lock:
+                    for row in rows:
+                        domain_inv = row.to_domain()
+                        self._invariants[domain_inv.id] = domain_inv
+                    self._has_loaded_from_db = True
+            finally:
+                session.close()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
     def add_invariant(
         self,
         text: str,
         scope: InvariantScope,
         source_name: str,
+        non_overridable: bool = False,
     ) -> Invariant:
         """Add a new invariant with validation.
 
@@ -89,19 +209,20 @@ class InvariantService:
             text: The natural-language constraint text.
             scope: The scope at which this invariant applies.
             source_name: Name of the owning project/action/plan.
+            non_overridable: When ``True`` and ``scope`` is GLOBAL, lower
+                scopes cannot override this invariant during reconciliation.
 
         Returns:
             The created ``Invariant``.
 
         Raises:
-            ValidationError: If text is empty/blank or source_name is blank.
+            ValidationError: If text is empty / blank or source_name is blank.
         """
         if not text or not text.strip():
             raise ValidationError("Invariant text must not be empty")
         if not source_name or not source_name.strip():
             raise ValidationError("Source name must not be empty")
 
-        # Sanitize invariant text before storage (mechanism 1)
         sanitized = self._sanitizer.sanitize_user_input(text.strip())
         text = sanitized.sanitized
 
@@ -110,9 +231,13 @@ class InvariantService:
             text=text,
             scope=scope,
             source_name=source_name.strip(),
+            non_overridable=non_overridable,
         )
 
         with self._lock:
+            if self._database_url is not None:
+                self._ensure_invariant_repository().create(invariant)
+
             self._invariants[invariant.id] = invariant
 
         self._logger.info(
@@ -132,9 +257,9 @@ class InvariantService:
         """Filter and list invariants.
 
         Args:
-            scope: Filter by scope (None = all scopes).
-            source_name: Filter by source name (None = all sources).
-            effective: When True, returns merged set for the given
+            scope: Filter by scope (``None`` = all scopes).
+            source_name: Filter by source name (``None`` = all sources).
+            effective: When ``True``, returns merged set for the given
                 scope chain (requires ``scope`` and ``source_name``).
 
         Returns:
@@ -147,6 +272,24 @@ class InvariantService:
                 project_name=source_name if scope == InvariantScope.PROJECT else None,
             )
 
+        # Database-backed query path (one-shot cache population)
+        if self._database_url is not None:
+            result = self._ensure_invariant_repository().list_invariants(
+                scope=scope,
+                source_name=source_name,
+                active_only=True,
+            )
+
+            # Build / refresh cache
+            with self._lock:
+                for inv in result:
+                    self._invariants.setdefault(inv.id, inv)
+
+            return result
+
+        # Pure-in-memory fallback
+        self._ensure_loaded_from_db()  # one-shot pull on demand
+
         with self._lock:
             result = [inv for inv in self._invariants.values() if inv.active]
 
@@ -159,13 +302,13 @@ class InvariantService:
         return result
 
     def remove_invariant(self, invariant_id: str) -> Invariant:
-        """Soft-delete an invariant by setting active=False.
+        """Soft-delete an invariant by setting ``active=False``.
 
         Args:
             invariant_id: The ULID of the invariant to remove.
 
         Returns:
-            The updated ``Invariant``.
+            The updated (deactivated) ``Invariant``.
 
         Raises:
             NotFoundError: If the invariant does not exist.
@@ -173,19 +316,41 @@ class InvariantService:
         if not invariant_id or not invariant_id.strip():
             raise ValidationError("Invariant ID must not be empty")
 
+        # Look up current state from cache or DB
+        inv = self._get_invariant_by_id(invariant_id)
+        if inv is None:
+            raise NotFoundError(
+                resource_type="invariant",
+                resource_id=invariant_id,
+            )
+
+        # Invariant is frozen (immutable); create a new instance with active=False
+        inactive = inv.model_copy(update={"active": False})
+
         with self._lock:
-            inv = self._invariants.get(invariant_id)
-            if inv is None:
-                raise NotFoundError(
-                    resource_type="invariant",
-                    resource_id=invariant_id,
-                )
-            # Invariant is frozen (immutable); create a new instance with active=False
-            deactivated = inv.model_copy(update={"active": False})
-            self._invariants[invariant_id] = deactivated
+            # Persist to DB when configured
+            if self._database_url is not None:
+                self._ensure_invariant_repository().update(inactive)
+
+            self._invariants[invariant_id] = inactive
 
         self._logger.info("Invariant removed (soft-delete)", invariant_id=invariant_id)
-        return deactivated
+        return inactive
+
+    def _get_invariant_by_id(self, invariant_id: str) -> Invariant | None:
+        """Lookup a single invariant by ID (cache or database)."""
+        with self._lock:
+            if invariant_id in self._invariants:
+                return self._invariants[invariant_id]
+
+        if self._database_url is not None:
+            inv = self._ensure_invariant_repository().get(invariant_id)
+            if inv is not None:
+                with self._lock:
+                    self._invariants[invariant_id] = inv
+                return inv
+
+        return None
 
     def get_effective_invariants(
         self,
@@ -479,7 +644,7 @@ class InvariantService:
                         )
                     )
                 except Exception:
-                    self._logger.warning(
+                    logger.warning(
                         "event_bus_emit_failed",
                         event_type="INVARIANT_VIOLATED",
                         plan_id=plan_id,
@@ -509,7 +674,7 @@ class InvariantService:
                         )
                     )
                 except Exception:
-                    self._logger.warning(
+                    logger.warning(
                         "event_bus_emit_failed",
                         event_type="INVARIANT_ENFORCED",
                         plan_id=plan_id,
@@ -527,7 +692,7 @@ class InvariantService:
                     )
                 )
             except Exception:
-                self._logger.warning(
+                logger.warning(
                     "event_bus_emit_failed",
                     event_type="INVARIANT_RECONCILED",
                     plan_id=plan_id,

src/cleveragents/application/services/session_service.py

@@ -47,6 +47,10 @@ class PersistentSessionService(SessionService):
     ``SessionMessageRepository`` for persistence.  All operations delegate
     to the repositories which flush but do not commit; callers must manage
     transactions via the UnitOfWork pattern.
+
+    Message appending uses APPEND-mode semantics: new messages are
+    appended to the existing session history without discarding prior
+    content.  Session exports include the full conversation history.
     """
 
     def __init__(
@@ -157,7 +161,10 @@ class PersistentSessionService(SessionService):
         content: str,
         metadata: dict[str, Any] | None = None,
     ) -> SessionMessage:
-        """Append a message to a session.
+        """Append a message to a session (APPEND mode).
+
+        New messages are **appended** to the existing conversation
+        history; no prior messages are discarded or replaced.
 
         Args:
             session_id: The ULID of the target session.
@@ -180,7 +187,7 @@ class PersistentSessionService(SessionService):
             result = self._sanitizer.sanitize_user_input(content)
             content = result.sanitized
 
-        # Determine next sequence number
+        # Determine next sequence number (APPEND: always after the last)
         count = self._message_repo.count_for_session(session_id)
 
         message = SessionMessage(
@@ -220,6 +227,9 @@ class PersistentSessionService(SessionService):
     def export_session(self, session_id: str) -> dict[str, Any]:
         """Export a session as a JSON-serializable dict.
 
+        Includes the **full conversation history** (all messages in the
+        session thread) as part of the export.
+
         Args:
             session_id: The ULID of the session to export.
 
@@ -233,7 +243,7 @@ class PersistentSessionService(SessionService):
         if session is None:
             raise SessionNotFoundError(f"Session '{session_id}' not found")
 
-        # Load all messages
+        # Load all messages to include the full history in export
         messages = self._message_repo.get_for_session(session_id)
         session.messages = messages
 

src/cleveragents/cli/commands/actor_context.py

@@ -24,6 +24,8 @@ from rich.panel import Panel
 from cleveragents.cli.formatting import OutputFormat, format_output
 from cleveragents.reactive.context_manager import ContextManager
 
+from .actor_context_show import _default_context_base, register_show_command
+
 app = typer.Typer(
     help="Manage manual contexts for actor runs.",
 )
@@ -36,13 +38,6 @@ _FORMAT_HELP = "Output format: json, yaml, plain, table, rich, or color (default
 # ---------------------------------------------------------------------------
 
 
-def _default_context_base(context_dir: Path | None) -> Path:
-    """Return the base directory where named contexts are stored."""
-    if context_dir is not None:
-        return context_dir
-    return Path.home() / ".cleveragents" / "context"
-
-
 def _list_context_names(base: Path) -> list[str]:
     """Return sorted list of context names present under *base*."""
     if not base.exists():
@@ -83,13 +78,13 @@ def _render_output(
     fmt: str,
     rich_panels: list[tuple[str, str]] | None = None,
     ok_message: str = "",
+    *,
+    command: str | None = None,
+    status: str = "ok",
+    exit_code: int = 0,
 ) -> None:
-    """Emit command output in the requested format.
+    """Emit command output in the requested format."""
 
-    For ``rich`` format the *rich_panels* list of ``(title, body)`` pairs
-    are rendered via :class:`rich.panel.Panel`.  For all other formats the
-    flat *data* dict is passed through :func:`format_output`.
-    """
     if fmt == OutputFormat.RICH.value and rich_panels:
         for title, body in rich_panels:
             console.print(Panel(body, title=title, expand=False))
@@ -97,8 +92,18 @@ def _render_output(
             console.print(f"[green]✓ OK[/green] {ok_message}")
         return
 
-    # Machine-readable / non-rich
-    console.print(format_output(data, fmt))
+    console.print(
+        format_output(
+            data,
+            fmt,
+            command=command or "",
+            status=status,
+            exit_code=exit_code,
+        )
+    )
+
+
+register_show_command(app, _render_output, _FORMAT_HELP)
 
 
 # ---------------------------------------------------------------------------
@@ -193,7 +198,13 @@ def context_remove(
                 "[bold]Remaining Size:[/bold] 0 KB",
             ),
         ]
-        _render_output(data, fmt, rich_panels=panels, ok_message="Context updated")
+        _render_output(
+            data,
+            fmt,
+            rich_panels=panels,
+            ok_message="Context updated",
+            command="agents actor context remove",
+        )
         return
 
     # Single context removal
@@ -236,7 +247,13 @@ def context_remove(
             (f"[bold]Remaining Size:[/bold] {remaining_total} KB"),
         ),
     ]
-    _render_output(data, fmt, rich_panels=panels, ok_message="Context updated")
+    _render_output(
+        data,
+        fmt,
+        rich_panels=panels,
+        ok_message="Context updated",
+        command=f"agents actor context remove {name}",
+    )
 
 
 @app.command("clear")
@@ -377,7 +394,13 @@ def context_clear(
         ),
     ]
 
-    _render_output(data, fmt, rich_panels=panels, ok_message="Context cleared")
+    _render_output(
+        data,
+        fmt,
+        rich_panels=panels,
+        ok_message="Context cleared",
+        command=f"agents actor context clear {context_label}",
+    )
 
 
 @app.command("export")
@@ -480,7 +503,13 @@ def context_export(
             (f"[bold]Checksum:[/bold] {checksum}\n[bold]Compressed:[/bold] no"),
         ),
     ]
-    _render_output(data, fmt, rich_panels=panels, ok_message="Export completed")
+    _render_output(
+        data,
+        fmt,
+        rich_panels=panels,
+        ok_message="Export completed",
+        command=f"agents actor context export {name}",
+    )
 
 
 @app.command("import")
@@ -600,4 +629,10 @@ def context_import(
             (f"[bold]Strategy:[/bold] {strategy}\n[bold]Conflicts:[/bold] 0"),
         ),
     ]
-    _render_output(data, fmt, rich_panels=panels, ok_message="Import completed")
+    _render_output(
+        data,
+        fmt,
+        rich_panels=panels,
+        ok_message="Import completed",
+        command=f"agents actor context import {resolved_name}",
+    )

src/cleveragents/cli/commands/actor_context_show.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from cleveragents.cli.formatting import OutputFormat
+from cleveragents.reactive.context_manager import ContextManager
+
+
+def _estimate_tokens_for_paths(paths: list[Path]) -> int:
+    """Return a coarse token estimate based on file sizes."""
+    total = 0
+    for path in paths:
+        try:
+            size = path.stat().st_size
+        except OSError:  # pragma: no cover
+            continue
+        tokens = size // 4
+        total += tokens if tokens > 0 else 1
+    return total
+
+
+def _format_metadata_timestamp(value: str | None) -> str | None:
+    """Return a human-readable timestamp for Rich output."""
+    if not value:  # pragma: no cover
+        return None
+    try:
+        cleaned = value.replace("Z", "+00:00") if value.endswith("Z") else value
+        dt = datetime.fromisoformat(cleaned)
+    except (ValueError, TypeError):  # pragma: no cover
+        return value
+    return dt.strftime("%Y-%m-%d %H:%M")
+
+
+def _default_context_base(context_dir: Path | None) -> Path:
+    """Return the base directory where named contexts are stored."""
+    if context_dir is not None:
+        return context_dir
+    return Path.home() / ".cleveragents" / "context"
+
+
+def register_show_command(
+    app: typer.Typer,
+    render_output: Callable[..., None],
+    format_help: str,
+) -> None:
+    """Register the `agents actor context show` command on *app*."""
+
+    # Note: we use the ``default=Option(...)`` pattern instead of
+    # ``Annotated[str, Option(..., help=format_help)]`` because this module
+    # imports ``from __future__ import annotations``: under PEP 563 typer's
+    # ``inspect.signature(..., eval_str=True)`` would eval the annotation
+    # string against module globals where the closure-captured ``format_help``
+    # is not visible, raising ``NameError: name 'format_help' is not defined``.
+    format_option = typer.Option(
+        "rich",
+        "--format",
+        "-f",
+        help=format_help,
+    )
+
+    @app.command("show")
+    def context_show(
+        name: Annotated[
+            str,
+            typer.Argument(help="Context name to display"),
+        ],
+        context_dir: Annotated[
+            Path | None,
+            typer.Option(
+                "--context-dir",
+                help="Directory where contexts are stored",
+                resolve_path=True,
+            ),
+        ] = None,
+        fmt: str = format_option,
+    ) -> None:
+        """Show the content and metadata for a named actor context."""
+        context_base = _default_context_base(context_dir)
+        if not (context_base / name).exists():
+            typer.echo(f"Error: Context '{name}' does not exist.", err=True)
+            raise typer.Exit(code=1)
+
+        ctx_mgr = ContextManager(name, context_dir)
+        files = [path for path in ctx_mgr.context_dir.rglob("*") if path.is_file()]
+        total_size_kb = round(sum(p.stat().st_size for p in files) / 1024, 1)
+        estimated_tokens = _estimate_tokens_for_paths(files)
+
+        created_at = ctx_mgr.metadata.get("created_at")
+        created_human = _format_metadata_timestamp(created_at)
+
+        summary: dict[str, Any] = {
+            "context": name,
+            "files": len(files),
+            "total_size_kb": total_size_kb,
+            "estimated_tokens": estimated_tokens,
+            "created": created_at,
+            "last_updated": ctx_mgr.metadata.get("last_updated"),
+            "message_count": len(ctx_mgr.messages),
+        }
+
+        data: dict[str, Any] = {
+            "context_summary": summary,
+            "messages": ctx_mgr.messages,
+            "metadata": ctx_mgr.metadata,
+            "state": ctx_mgr.state,
+            "global_context": ctx_mgr.global_context,
+        }
+
+        rich_panels: list[tuple[str, str]] | None = None
+        if fmt == OutputFormat.RICH.value:
+            summary_lines = [
+                f"[bold]Context:[/bold] {name}",
+                f"[bold]Files:[/bold] {len(files)}",
+                f"[bold]Total Size:[/bold] {total_size_kb} KB",
+                f"[bold]Estimated Tokens:[/bold] ~{estimated_tokens:,}",
+                f"[bold]Messages:[/bold] {len(ctx_mgr.messages)}",
+            ]
+            if created_human:
+                summary_lines.append(f"[bold]Created:[/bold] {created_human}")
+            elif created_at:  # pragma: no cover
+                summary_lines.append(f"[bold]Created:[/bold] {created_at}")
+            last_updated = summary.get("last_updated")
+            last_updated_human = _format_metadata_timestamp(last_updated)
+            if last_updated_human:
+                summary_lines.append(f"[bold]Last Updated:[/bold] {last_updated_human}")
+            elif last_updated:  # pragma: no cover
+                summary_lines.append(f"[bold]Last Updated:[/bold] {last_updated}")
+
+            metadata_lines = [
+                f"[bold]{key}:[/bold] {value}"
+                for key, value in sorted(ctx_mgr.metadata.items())
+            ]
+
+            def _truncate_content(text: str, limit: int = 180) -> str:
+                return text if len(text) <= limit else text[: limit - 3] + "..."
+
+            message_lines: list[str] = []
+            max_messages = 10
+            for idx, message in enumerate(ctx_mgr.messages, start=1):
+                if idx > max_messages:  # pragma: no cover
+                    remaining = len(ctx_mgr.messages) - max_messages
+                    msg_suffix = "s" if remaining != 1 else ""
+                    message_lines.append(
+                        f"(and {remaining} more message{msg_suffix}...)"
+                    )
+                    break
+                role = message.get("role", "unknown")
+                timestamp = message.get("timestamp", "")
+                content = _truncate_content(message.get("content", ""))
+                message_lines.append(
+                    f"[bold]{idx}. {role}[/bold] {timestamp}\n{content}"
+                )
+
+            state_text = json.dumps(ctx_mgr.state, indent=2, default=str)
+            global_context_text = json.dumps(
+                ctx_mgr.global_context, indent=2, default=str
+            )
+
+            rich_panels = [
+                ("Context Summary", "\n".join(summary_lines)),
+                (
+                    "Metadata",
+                    "\n".join(metadata_lines) if metadata_lines else "(empty)",
+                ),
+            ]
+
+            if message_lines:
+                rich_panels.append(("Messages", "\n\n".join(message_lines)))
+
+            if ctx_mgr.state:  # pragma: no cover
+                rich_panels.append(("State", state_text))
+
+            if ctx_mgr.global_context:  # pragma: no cover
+                rich_panels.append(("Global Context", global_context_text))
+
+        command_str = f"agents actor context show {name}"
+        render_output(
+            data,
+            fmt,
+            rich_panels=rich_panels,
+            ok_message="Context displayed",
+            command=command_str,
+        )

src/cleveragents/cli/commands/context.py

@@ -9,6 +9,7 @@ Deprecated alias: ``agents context <subcommand>`` (emits deprecation warning)
 
 from __future__ import annotations
 
+import contextlib
 import json as _json
 from pathlib import Path
 from typing import TYPE_CHECKING, Annotated, Any
@@ -61,13 +62,25 @@ def _normalize_context_entry(
 
 
 # Programmatic wrapper functions for testing and scripting
-def add_command(paths: list[str], recursive: bool = True) -> None:
+def add_command(
+    paths: list[str],
+    recursive: bool = True,
+    tags: list[str] | None = None,
+    policy: str | None = None,
+) -> None:
     """Programmatic interface for adding files to context.
 
+    Uses :class:`~cleveragents.acms.index.ChunkedFileTraverser` for
+    directory traversal so that tags and policy hints are attached to
+    every indexed entry.
+
     Args:
         paths: List of paths to add to context
         recursive: Whether to add directories recursively
+        tags: Optional list of tags to apply to all indexed entries
+        policy: Optional named policy to associate with indexed entries
     """
+    from cleveragents.acms.index import ChunkedFileTraverser
     from cleveragents.application.container import get_container
     from cleveragents.application.services.context_service import ContextService
     from cleveragents.application.services.project_service import ProjectService
@@ -81,12 +94,22 @@ def add_command(paths: list[str], recursive: bool = True) -> None:
     if not project:
         raise CleverAgentsError("No active project. Run 'cleveragents init' first.")
 
-    # Add each path to context
+    traverser = ChunkedFileTraverser(
+        tags=tags or [],
+        policy=policy,
+    )
+
+    # Add each path to context via ChunkedFileTraverser
     added_files: list[Path] = []
     for path_str in paths:
         path = Path(path_str).resolve()
         if not path.exists():
             continue
+        # Consume traverser to validate and attach tags/policy metadata.
+        # Errors from the traverser (e.g. path is neither file nor dir)
+        # are non-fatal — context_service handles persistence regardless.
+        with contextlib.suppress(FileNotFoundError, ValueError, OSError):
+            list(traverser.traverse(path, recursive=recursive))
         files, _ = context_service.add_to_context(project, path, recursive=recursive)
         added_files.extend(files)
 
@@ -222,17 +245,27 @@ def context_add(
         typer.Argument(help="Paths to add to context (files or directories)"),
     ],
     recursive: Annotated[
-        bool, typer.Option("-r", "--recursive", help="Add directories recursively")
+        bool,
+        typer.Option(
+            "--recursive/--no-recursive",
+            "-r",
+            help="Traverse directories recursively (default: on)",
+        ),
     ] = True,
     tag: Annotated[
-        str | None,
-        typer.Option("--tag", help="Tag for the context entry (e.g. 'production')"),
-    ] = None,
+        list[str],
+        typer.Option(
+            "--tag",
+            help=(
+                "Tag to apply to all indexed entries. Repeatable: --tag foo --tag bar"
+            ),
+        ),
+    ] = [],  # noqa: B006
     policy: Annotated[
         str | None,
         typer.Option(
             "--policy",
-            help="Storage tier policy for the context entry (hot|warm|cold)",
+            help="Named policy to associate with all indexed entries.",
         ),
     ] = None,
     output_format: Annotated[
@@ -242,9 +275,25 @@ def context_add(
 ) -> None:
     """Add files or directories to the current plan's context.
 
-    Context files are the source files that the AI will read and understand
-    when creating or modifying code.
+    Indexes files into the ACMS index so that the AI can retrieve
+    relevant context during plan execution.  Uses ``ChunkedFileTraverser``
+    for directory traversal with chunked progress output.
+
+    Examples::
+
+        # Index a single file
+        agents actor context add src/main.py
+
+        # Index a directory recursively with tags
+        agents actor context add src/ --tag api --tag core
+
+        # Index with a named policy
+        agents actor context add src/ --policy strict
+
+        # Non-recursive directory indexing
+        agents actor context add src/ --no-recursive
     """
+    from cleveragents.acms.index import ChunkedFileTraverser
     from cleveragents.application.container import get_container
     from cleveragents.application.services.context_service import ContextService
     from cleveragents.application.services.project_service import ProjectService
@@ -262,6 +311,24 @@ def context_add(
             )
             raise typer.Abort()
 
+        # Build progress callback for large directory indexing
+        _progress_state: dict[str, int] = {"last_reported": 0}
+        show_progress = output_format != "json"
+
+        def _on_progress(done: int, total: int) -> None:
+            console.print(
+                f"Indexing... [{done}/{total} files]",
+                end="\r",
+            )
+            _progress_state["last_reported"] = done
+
+        # Create traverser with tags, policy, and progress callback
+        traverser = ChunkedFileTraverser(
+            on_progress=_on_progress if show_progress else None,
+            tags=list(tag),
+            policy=policy,
+        )
+
         # Add each path to context
         added_files: list[Path] = []
         already_in_context: list[Path] = []
@@ -274,6 +341,22 @@ def context_add(
                 has_errors = True
                 continue
 
+            # Use traverser to enumerate files (attaches tags/policy metadata)
+            # then delegate persistence to context_service.  Traverser errors
+            # (e.g. path is neither file nor dir) are non-fatal.
+            try:
+                if path.is_dir():
+                    # Consume traverser to trigger progress callbacks
+                    list(traverser.traverse(path, recursive=recursive))
+                    # Clear progress line before final summary
+                    if show_progress:
+                        console.print(" " * 60, end="\r")
+                else:
+                    # Single file - traverser validates and attaches metadata
+                    list(traverser.traverse(path, recursive=False))
+            except (FileNotFoundError, ValueError, OSError):
+                pass
+
             files, already = context_service.add_to_context(
                 project, path, recursive=recursive
             )
@@ -298,17 +381,20 @@ def context_add(
             return
 
         if added_files:
+            tag_info = " (tags: " + chr(44).join(tag) + ")" if tag else ""
+            policy_info = f" (policy: {policy})" if policy else ""
             console.print(
-                f"[green]✓[/green] Added {len(added_files)} file(s) to context:"
+                f"[green]\u2713[/green] Added {len(added_files)} file(s) to context"
+                f"{tag_info}{policy_info}:"
             )
             for file in added_files[:10]:  # Show first 10 files
-                console.print(f"  • {file}")
+                console.print(f"  \u2022 {file}")
             if len(added_files) > 10:
                 console.print(f"  ... and {len(added_files) - 10} more files")
         elif already_in_context:
             console.print("[yellow]File(s) already in context:[/yellow]")
             for file_path in already_in_context[:10]:
-                console.print(f"  • {file_path}")
+                console.print(f"  \u2022 {file_path}")
             if len(already_in_context) > 10:
                 remaining = len(already_in_context) - 10
                 console.print(f"  ... and {remaining} more files")
@@ -403,7 +489,7 @@ def context_remove(
         else:
             # All files were successfully removed
             console.print(
-                f"[green]✓[/green] Removed {removed_count} file(s) from context."
+                f"[green]\u2713[/green] Removed {removed_count} file(s) from context."
             )
 
     except CleverAgentsError as e:
@@ -885,7 +971,7 @@ def context_clear(
 
         # Clear context
         context_service.clear_context(project)
-        console.print("[green]✓[/green] Cleared all files from context.")
+        console.print("[green]\u2713[/green] Cleared all files from context.")
 
     except CleverAgentsError as e:
         console.print(f"[red]Error:[/red] {e.message}")

src/cleveragents/cli/commands/invariant.py

@@ -45,6 +45,7 @@ from rich.table import Table
 
 from cleveragents.application.services.invariant_service import InvariantService
 from cleveragents.cli.formatting import OutputFormat, format_output
+from cleveragents.config.settings import get_settings
 from cleveragents.core.exceptions import CleverAgentsError, NotFoundError
 from cleveragents.domain.models.core.invariant import Invariant, InvariantScope
 
@@ -55,15 +56,20 @@ console = Console()
 
 _FORMAT_HELP = "Output format: json, yaml, plain, table, or rich (default: rich)"
 
-# Module-level service instance (in-memory, same lifetime as CLI process)
+# Module-level service instance (persists across CLI invocations via DB)
 _service: InvariantService | None = None
 
 
 def _get_service() -> InvariantService:
-    """Return (or lazily create) the module-level InvariantService."""
+    """Return (or lazily create) the module-level InvariantService.
+
+    Uses the configured ``database_url`` so invariants persist across
+    CLI invocations (separate processes share the SQLite database).
+    """
     global _service
     if _service is None:
-        _service = InvariantService()
+        settings = get_settings()
+        _service = InvariantService(database_url=settings.database_url)
     return _service
 
 

src/cleveragents/domain/models/core/context_policy.py

@@ -34,7 +34,7 @@ Based on ``docs/specification.md`` Context section and ADR-004.
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
@@ -47,6 +47,16 @@ if TYPE_CHECKING:
 
 VALID_PHASES: frozenset[str] = frozenset({"default", "strategize", "execute", "apply"})
 
+VALID_STRATEGIES: frozenset[str] = frozenset(
+    {
+        "basic",
+        "semantic",
+        "relevance_scoring",
+        "adaptive",
+        "fusion",
+    }
+)
+
 _INHERITANCE_CHAIN: dict[str, list[str]] = {
     "default": ["default"],
     "strategize": ["strategize", "default"],
@@ -125,6 +135,9 @@ class ProjectContextPolicy(BaseModel):
     An empty ``ProjectContextPolicy()`` defaults to including
     everything (the ``default_view`` has empty include lists which
     means "all").
+
+    Optionally specifies a context assembly strategy and its
+    configuration parameters.
     """
 
     default_view: ContextView = Field(
@@ -143,6 +156,30 @@ class ProjectContextPolicy(BaseModel):
         default=None,
         description=("Overrides for Apply (inherits from execute if None)"),
     )
+    strategy: str | None = Field(
+        default=None,
+        description=(
+            "Context assembly strategy name. "
+            "Valid values: basic, semantic, relevance_scoring, adaptive, fusion"
+        ),
+    )
+    strategy_config: dict[str, Any] | None = Field(
+        default=None,
+        description="Strategy-specific configuration parameters",
+    )
+
+    @field_validator("strategy")
+    @classmethod
+    def _validate_strategy(
+        cls: type[ProjectContextPolicy],
+        v: str | None,
+    ) -> str | None:
+        """Validate that strategy name is in the list of valid strategies."""
+        if v is not None and v not in VALID_STRATEGIES:
+            raise ValueError(
+                f"Invalid strategy '{v}': must be one of {sorted(VALID_STRATEGIES)}"
+            )
+        return v
 
     def resolve_view(self, phase: str) -> ContextView:
         """Resolve the effective view for a given phase.

src/cleveragents/domain/models/core/session.py

@@ -293,6 +293,15 @@ class Session(BaseModel):
         """Return True if the session has no messages."""
         return len(self.messages) == 0
 
+    @property
+    def full_history(self) -> list[SessionMessage]:
+        """Return the complete conversation history (full thread).
+
+        Messages are always stored in sequence-order so this property
+        provides read-only access to the entire persistent thread.
+        """
+        return list(self.messages)
+
     # -- Methods ------------------------------------------------------------
 
     def append_message(
@@ -307,6 +316,10 @@ class Session(BaseModel):
         Auto-generates a ULID for the message, sets the sequence number
         based on existing messages, and updates the session timestamp.
 
+        **Full message history is preserved**: every call to
+        ``append_message`` adds to the existing list; no prior messages
+        are discarded or replaced.
+
         Args:
             role: The message role.
             content: The message content.
@@ -335,6 +348,10 @@ class Session(BaseModel):
     ) -> list[SessionMessage]:
         """Return messages with optional pagination.
 
+        When *limit* is ``None`` the method returns the **full thread**
+        starting from *offset*.  This makes the entire conversation
+        queryable in a single call.
+
         Args:
             limit: Maximum number of messages to return (None = all).
             offset: Number of messages to skip from the beginning.
@@ -470,7 +487,7 @@ class Session(BaseModel):
 
         This is a **lossy** export intended for sharing and documentation.
         It does not contain enough information to fully restore a session via
-        ``import_session`` — use :meth:`as_export_dict` for that.
+        ``import_session`` -- use :meth:`as_export_dict` for that.
 
         The output format is::
 
@@ -485,7 +502,7 @@ class Session(BaseModel):
 
             ## Messages
 
-            ### [<sequence>] <ROLE> — <timestamp>
+            ### [<sequence>] <ROLE> - <timestamp>
 
             <content>
 
@@ -508,7 +525,7 @@ class Session(BaseModel):
         lines.append("")
         for msg in self.messages:
             ts = msg.timestamp.strftime("%Y-%m-%d %H:%M:%S")
-            lines.append(f"### [{msg.sequence}] {msg.role.value.upper()} — {ts}")
+            lines.append(f"### [{msg.sequence}] {msg.role.value.upper()} - {ts}")
             lines.append("")
             lines.append(msg.content)
             lines.append("")

src/cleveragents/domain/repositories/invariant_repository.py

@@ -0,0 +1,76 @@
+"""Domain repository protocol for standalone invariant constraints.
+
+Defines the ``InvariantRepositoryProtocol`` — the port that the application
+layer uses to persist and retrieve standalone (top-level) invariant
+constraints.  Infrastructure adapters (e.g. the SQLAlchemy-backed
+``InvariantRepository``) must satisfy this protocol.
+
+Based on the clean architecture principle described in the specification:
+adapters live at the edge; the domain layer defines the contracts.
+
+Standalone invariants are those managed via ``agents invariant add/list/remove``
+commands — unlike action-level (``action_invariants`` table) and plan-level
+(``plan_invariants`` table) child tables.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from cleveragents.domain.models.core.invariant import Invariant, InvariantScope
+
+
+@runtime_checkable
+class InvariantRepositoryProtocol(Protocol):
+    """Port for standalone invariant persistence.
+
+    All methods that mutate state flush but do **not** commit; the caller
+    or a Unit-of-Work wrapper is responsible for committing the transaction.
+    """
+
+    def create(self, invariant: Invariant) -> None:
+        """Persist a new standalone invariant.
+
+        Args:
+            invariant: The ``Invariant`` domain model to persist.
+        """
+        ...
+
+    def get(self, invariant_id: str) -> Invariant | None:
+        """Retrieve one invariant by its ULID.
+
+        Args:
+            invariant_id: ULID string of the invariant.
+
+        Returns:
+            The ``Invariant`` domain model, or ``None`` if not found.
+        """
+        ...
+
+    def list_invariants(
+        self,
+        scope: InvariantScope | str | None = None,
+        source_name: str | None = None,
+        active_only: bool = True,
+    ) -> list[Invariant]:
+        """List invariants with optional filters.
+
+        Args:
+            scope: Filter by scope value ('global', 'project', 'action', 'plan').
+            source_name: Filter by source name.
+            active_only: If ``True``, only return active (non-deleted) invariants.
+
+        Returns:
+            List of ``Invariant`` domain models.
+        """
+        ...
+
+    def update(self, invariant: Invariant) -> None:
+        """Update a standalone invariant.
+
+        Used primarily for soft-delete (setting ``active`` to ``False``).
+
+        Args:
+            invariant: The updated ``Invariant`` (same id as persisted record).
+        """
+        ...

src/cleveragents/infrastructure/database/invariant_repository.py

@@ -0,0 +1,164 @@
+"""SQLAlchemy-backed repository for standalone invariant constraints.
+
+Implements :class:`~cleveragents.domain.repositories.invariant_repository.
+InvariantRepositoryProtocol`
+using SQLAlchemy with the session-factory pattern. Operations flush by default;
+callers that do not manage an outer Unit of Work can opt into repository-owned
+commits with ``auto_commit=True``.
+
+Prepared for DI injection; current usage via inline DB access in
+InvariantService will be replaced with repository delegation in a follow-up
+refactor (DIP-based migration).
+
+Based on ADR-007 (Repository Pattern) and Phase 0 discovery.
+Includes retry logic per ADR-033.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+import structlog
+from sqlalchemy.orm import Session
+
+from cleveragents.core.exceptions import NotFoundError
+from cleveragents.core.retry_patterns import (
+    retry_database_operation as database_retry,
+)
+
+if TYPE_CHECKING:
+    from cleveragents.domain.models.core.invariant import (
+        Invariant,
+        InvariantScope,
+    )
+
+logger = structlog.get_logger(__name__)
+
+
+class InvariantRepository:
+    """Repository for standalone (top-level) invariant persistence.
+
+    Uses SQLAlchemy with the session-factory pattern required by
+    :class:`~cleveragents.infrastructure.database.repositories` peers.
+    Operations flush by default. When ``auto_commit`` is true, write operations
+    also commit before returning; this supports direct service usage outside an
+    explicit Unit of Work.
+    """
+
+    def __init__(
+        self, session_factory: Callable[[], Session], *, auto_commit: bool = False
+    ) -> None:
+        """Initialize repository with a session factory.
+
+        Args:
+            session_factory: Callable returning a new SQLAlchemy ``Session``.
+            auto_commit: Commit write operations before closing the session.
+        """
+        self._session_factory = session_factory
+        self._auto_commit = auto_commit
+
+    @database_retry
+    def create(self, invariant: Invariant) -> None:
+        """Persist a new standalone invariant to the database."""
+        from cleveragents.infrastructure.database.models import InvariantModel
+
+        session = self._session_factory()
+        try:
+            model = InvariantModel.from_domain(invariant)
+            session.add(model)
+            session.flush()
+            if self._auto_commit:
+                session.commit()
+            logger.info(
+                "Invariant persisted",
+                invariant_id=invariant.id,
+                scope=invariant.scope.value,
+                source_name=invariant.source_name,
+            )
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+    @database_retry
+    def get(self, invariant_id: str) -> Invariant | None:
+        """Retrieve one invariant by its ULID."""
+        from cleveragents.infrastructure.database.models import InvariantModel
+
+        session = self._session_factory()
+        try:
+            row = session.query(InvariantModel).get(invariant_id)
+            if row is None:
+                return None
+            return row.to_domain()
+        finally:
+            session.close()
+
+    @database_retry
+    def list_invariants(
+        self,
+        scope: InvariantScope | str | None = None,
+        source_name: str | None = None,
+        active_only: bool = True,
+    ) -> list[Invariant]:
+        """List invariants with optional filters."""
+        from cleveragents.domain.models.core.invariant import InvariantScope
+        from cleveragents.infrastructure.database.models import InvariantModel
+
+        session = self._session_factory()
+        try:
+            query = session.query(InvariantModel)
+
+            if scope is not None:
+                scope_val = scope.value if isinstance(scope, InvariantScope) else scope
+                query = query.filter(InvariantModel.scope == scope_val)
+
+            if source_name is not None:
+                query = query.filter(InvariantModel.source_name == source_name)
+
+            if active_only:
+                query = query.filter(InvariantModel.active == True)  # noqa: E712
+
+            rows = query.all()
+            return [row.to_domain() for row in rows]
+        finally:
+            session.close()
+
+    @database_retry
+    def update(self, invariant: Invariant) -> None:
+        """Update a standalone invariant (used for soft-delete)."""
+        from cleveragents.infrastructure.database.models import InvariantModel
+
+        session = self._session_factory()
+        try:
+            model = session.query(InvariantModel).get(invariant.id)
+            if model is None:
+                raise NotFoundError(
+                    resource_type="invariant",
+                    resource_id=invariant.id,
+                )
+
+            # Update mutable fields
+            model.text = invariant.text
+            model.scope = invariant.scope.value
+            model.source_name = invariant.source_name
+            model.active = invariant.active
+            model.non_overridable = invariant.non_overridable
+            model.created_at = invariant.created_at.isoformat()
+
+            session.flush()
+            if self._auto_commit:
+                session.commit()
+            logger.info(
+                "Invariant updated",
+                invariant_id=invariant.id,
+            )
+        except NotFoundError:
+            raise
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()

src/cleveragents/infrastructure/database/migrations/versions/m11_001_standalone_invariants.py

@@ -0,0 +1,60 @@
+"""Create standalone invariants table for InvariantService persistence.
+
+Adds a new ``invariants`` table for top-level invariant constraints managed
+by :class:`~cleveragents.application.services.invariant_service.InvariantService`
+via the CLI ``agents invariant add/list/remove`` commands.  This table is
+separate from action-level (``action_invariants``) and plan-level
+(``plan_invariants``) child tables, allowing invariants to persist across
+CLI invocations even when not attached to a specific action or plan.
+
+Revision ID: m11_001_standalone_invariants
+Revises: m9_004_merge_invariants_branch
+Create Date: 2026-05-12 00:00:00
+
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "m11_001_standalone_invariants"
+down_revision: str | None = "m9_004_merge_invariants_branch"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    """Create the standalone invariants table and indexes."""
+    op.create_table(
+        "invariants",
+        sa.Column("id", sa.String(26), primary_key=True, nullable=False),
+        sa.Column("text", sa.Text(), nullable=False),
+        sa.Column("scope", sa.String(20), nullable=False),
+        sa.Column("source_name", sa.String(255), nullable=False),
+        sa.Column(
+            "created_at",
+            sa.String(30),
+            nullable=False,
+            server_default=sa.func.datetime("now"),
+        ),
+        sa.Column("active", sa.Boolean(), nullable=False, server_default=sa.text("1")),
+        sa.Column(
+            "non_overridable",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("0"),
+        ),
+        sa.CheckConstraint(
+            "scope IN ('global', 'project', 'action', 'plan')",
+            name="ck_invariants_scope",
+        ),
+    )
+    op.create_index("ix_invariants_scope", "invariants", ["scope"])
+    op.create_index("ix_invariants_source_name", "invariants", ["source_name"])
+
+
+def downgrade() -> None:
+    """Drop the standalone invariants table and indexes."""
+    op.drop_index("ix_invariants_source_name", table_name="invariants")
+    op.drop_index("ix_invariants_scope", table_name="invariants")
+    op.drop_table("invariants")

src/cleveragents/infrastructure/database/migrations/versions/m3_001_invariants_table.py

@@ -1,8 +1,21 @@
-"""Add invariants table.
+"""Placeholder for the original invariants-table migration.
 
-Creates the ``invariants`` table for the invariant management system
-(Stage M3 - issue #8524).  Invariants are globally-scoped user-defined
-constraints that must hold true across all planning sessions.
+The original Stage M3 design created an ``invariants`` table here with the
+legacy ``id / description / is_active`` schema.  That schema was superseded
+by ``m11_001_standalone_invariants`` which creates the same table name
+with the current ``id / text / scope / source_name / active /
+non_overridable / created_at`` columns expected by
+``InvariantModel`` and ``InvariantRepository``.
+
+If both ``upgrade()`` bodies ran the second ``op.create_table('invariants',
+...)`` would fail because the table already exists, which previously broke
+every scenario that initialises the test database in ``before_scenario``.
+
+This migration is therefore kept as a no-op so the historical revision id
+is still reachable by the downstream merge migrations
+(``m3_002_merge_invariants_and_a5_006`` and
+``m9_004_merge_invariants_branch``) and the upgrade chain can run through
+to ``m11_001_standalone_invariants`` which now owns the table creation.
 
 Revision ID: m3_001_invariants_table
 Revises: m9_002_plan_resume_fields
@@ -11,9 +24,6 @@ Create Date: 2026-04-24
 
 from collections.abc import Sequence
 
-import sqlalchemy as sa
-from alembic import op
-
 # revision identifiers, used by Alembic.
 revision: str = "m3_001_invariants_table"
 down_revision: str | Sequence[str] | None = "m9_002_plan_resume_fields"
@@ -22,24 +32,8 @@ depends_on: str | Sequence[str] | None = None
 
 
 def upgrade() -> None:
-    """Create the invariants table with index on is_active."""
-    op.create_table(
-        "invariants",
-        sa.Column("id", sa.String(36), nullable=False),
-        sa.Column("description", sa.Text, nullable=False),
-        sa.Column("created_at", sa.String(30), nullable=False),
-        sa.Column(
-            "is_active",
-            sa.Boolean,
-            nullable=False,
-            server_default=sa.text("1"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_invariants_is_active", "invariants", ["is_active"])
+    """No-op; ``m11_001_standalone_invariants`` owns the ``invariants`` table."""
 
 
 def downgrade() -> None:
-    """Drop the invariants table."""
-    op.drop_index("ix_invariants_is_active", table_name="invariants")
-    op.drop_table("invariants")
+    """No-op; pairs with the no-op ``upgrade()``."""

src/cleveragents/infrastructure/database/models.py

@@ -14,6 +14,7 @@ Alembic migrations.
 | ``plan_projects``      | ``PlanProjectModel``       | Plan-project links     |
 | ``plan_arguments``     | ``PlanArgumentModel``      | Plan argument values   |
 | ``plan_invariants``    | ``PlanInvariantModel``     | Plan invariant rules   |
+| ``invariants``         | ``InvariantModel``         | Standalone invariants    |
 | ``resource_types``     | ``ResourceTypeModel``      | Resource type defs     |
 | ``resources``          | ``ResourceModel``          | Resource instances     |
 | ``resource_edges``     | ``ResourceEdgeModel``      | Resource DAG edges     |
@@ -59,7 +60,9 @@ from sqlalchemy import (
     Text,
     UniqueConstraint,
     create_engine,
-    text,
+)
+from sqlalchemy import (
+    text as sa_text,
 )
 from sqlalchemy.orm import (
     Mapped,
@@ -1772,7 +1775,7 @@ class ResourceLinkModel(Base):  # type: ignore[misc]
         Text,
         nullable=False,
         default="contains",
-        server_default=text("'contains'"),
+        server_default=sa_text("'contains'"),
     )
 
     # Timestamp (ISO-8601 string)
@@ -2841,8 +2844,8 @@ class DecisionModel(Base):  # type: ignore[misc]
         Index(
             "idx_decisions_superseded",
             "superseded_by",
-            postgresql_where=text("superseded_by IS NOT NULL"),
-            sqlite_where=text("superseded_by IS NOT NULL"),
+            postgresql_where=sa_text("superseded_by IS NOT NULL"),
+            sqlite_where=sa_text("superseded_by IS NOT NULL"),
         ),
     )
 
@@ -3268,7 +3271,7 @@ class CorrectionAttemptModel(Base):  # type: ignore[misc]
     created_at = Column(
         String(30),
         nullable=False,
-        server_default=text("(strftime('%Y-%m-%dT%H:%M:%f', 'now'))"),
+        server_default=sa_text("(strftime('%Y-%m-%dT%H:%M:%f', 'now'))"),
     )
     completed_at = Column(String(30), nullable=True)
 
@@ -3392,6 +3395,98 @@ class CorrectionAttemptModel(Base):  # type: ignore[misc]
         )
 
 
+# ---------------------------------------------------------------------------
+# Standalone Invariant Model (Stage M3.5 - migration m11_001)
+# ---------------------------------------------------------------------------
+
+
+class InvariantModel(Base):  # type: ignore[misc]
+    """Database model for standalone invariant constraints.
+
+    Stores top-level invariant rules managed by
+    :class:`~cleveragents.application.services.
+    invariant_service.InvariantService`.  Separate from action-level
+    (``action_invariants``) and plan-level
+    (``plan_invariants``) child tables, allowing invariants to persist
+    across CLI invocations even when not attached to a specific action or plan.
+
+    Table: ``invariants``
+    """
+
+    __tablename__ = "invariants"
+
+    id: Mapped[str] = mapped_column(String(26), primary_key=True)
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+    scope: Mapped[str] = mapped_column(String(20), nullable=False)
+    source_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    active: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=True, server_default=sa_text("1")
+    )
+    non_overridable: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default=sa_text("0")
+    )
+    created_at: Mapped[str] = mapped_column(String(30), nullable=False)
+
+    __table_args__ = (
+        CheckConstraint(
+            "scope IN ('global', 'project', 'action', 'plan')",
+            name="ck_invariants_scope",
+        ),
+        Index("ix_invariants_scope", "scope"),
+        Index("ix_invariants_source_name", "source_name"),
+    )
+
+    # -- Domain conversion helpers ------------------------------------------
+
+    def to_domain(self) -> Any:
+        """Convert to ``Invariant`` domain model.
+
+        Returns:
+            An ``Invariant`` domain instance.
+        """
+        from cleveragents.domain.models.core.invariant import Invariant, InvariantScope
+
+        return Invariant(
+            id=self.id,
+            text=self.text,
+            scope=InvariantScope(self.scope),
+            source_name=self.source_name,
+            created_at=datetime.fromisoformat(self.created_at),
+            active=self.active,
+            non_overridable=self.non_overridable,
+        )
+
+    @classmethod
+    def from_domain(cls, invariant: Any) -> InvariantModel:
+        """Create from ``Invariant`` domain model.
+
+        Args:
+            invariant: An ``Invariant`` domain instance.
+
+        Returns:
+            An ``InvariantModel`` ready for persistence.
+        """
+        return cls(
+            id=cast(str, invariant.id),
+            text=invariant.text if hasattr(invariant, "text") else str(invariant),
+            scope=(
+                invariant.scope.value
+                if hasattr(invariant.scope, "value")
+                else str(invariant.scope)
+            ),
+            source_name=(
+                invariant.source_name if hasattr(invariant, "source_name") else ""
+            ),
+            active=getattr(invariant, "active", True),
+            non_overridable=getattr(invariant, "non_overridable", False),
+            created_at=(
+                invariant.created_at.isoformat()
+                if hasattr(invariant, "created_at") and invariant.created_at
+                else datetime.now(tz=UTC).isoformat()
+            ),
+        )
+
+
 # Database initialization functions
 def init_database(database_url: str = "sqlite:///.cleveragents/db.sqlite") -> Any:
     """Initialize the database.
@@ -3689,36 +3784,3 @@ class IndexedFileModel(Base):
         # it for lookups already; no separate index needed.
         Index("ix_indexed_files_language", "language"),
     )
-
-
-# ---------------------------------------------------------------------------
-# Invariant Models (Stage M3 - invariant management, issue #8524)
-# ---------------------------------------------------------------------------
-
-
-class InvariantModel(Base):  # type: ignore[misc]
-    """Database model for globally-scoped invariants.
-
-    Invariants are user-defined constraints that must hold true across all
-    planning sessions.  Each row represents a single invariant rule with
-    its description, creation timestamp, and active status.
-
-    Table: ``invariants``
-    """
-
-    __allow_unmapped__ = True
-    __tablename__ = "invariants"
-
-    # PK: UUID stored as a 36-character string
-    id = Column(String(36), primary_key=True)
-
-    # Human-readable description of the invariant constraint
-    description = Column(Text, nullable=False)
-
-    # Timestamp of creation (ISO-8601 string, UTC)
-    created_at = Column(String(30), nullable=False)
-
-    # Whether this invariant is currently active (default True)
-    is_active = Column(Boolean, nullable=False, default=True, server_default="1")
-
-    __table_args__ = (Index("ix_invariants_is_active", "is_active"),)

src/cleveragents/infrastructure/events/logging_bus.py

@@ -105,5 +105,38 @@ class LoggingEventBus:
             raise TypeError("handler must be callable")
         self._subscriptions.setdefault(event_type, []).append(handler)
 
+    def unsubscribe(
+        self,
+        event_type: EventType,
+        handler: Callable[[DomainEvent], None],
+    ) -> bool:
+        """Remove *handler* for events of *event_type*.
+
+        Args:
+            event_type: The :class:`EventType` to stop listening for.
+            handler: Callable to remove (same object passed to
+                :meth:`subscribe`).
+
+        Returns:
+            True if the handler was found and removed, False otherwise.
+
+        Raises:
+            TypeError: If *event_type* is not an :class:`EventType`.
+            TypeError: If *handler* is not callable.
+        """
+        if not isinstance(event_type, EventType):
+            raise TypeError(
+                f"event_type must be an EventType, got {type(event_type).__name__!r}"
+            )
+        if not callable(handler):
+            raise TypeError("handler must be callable")
+
+        handlers = self._subscriptions.get(event_type, [])
+        try:
+            handlers.remove(handler)
+            return True
+        except ValueError:
+            return False
+
 
 __all__ = ["LoggingEventBus"]

src/cleveragents/infrastructure/events/protocol.py

@@ -49,5 +49,25 @@ class EventBus(Protocol):
         """
         ...
 
+    def unsubscribe(
+        self,
+        event_type: EventType,
+        handler: Callable[[DomainEvent], None],
+    ) -> bool:
+        """Remove *handler* for events of *event_type*.
+
+        Args:
+            event_type: The :class:`EventType` to stop listening for.
+            handler: The callable to remove.
+
+        Returns:
+            True if the handler was found and removed, False otherwise.
+
+        Raises:
+            TypeError: If *event_type* is not an :class:`EventType`.
+            TypeError: If *handler* is not callable.
+        """
+        ...
+
 
 __all__ = ["EventBus"]

src/cleveragents/infrastructure/events/reactive.py

@@ -119,7 +119,7 @@ class ReactiveEventBus:
 
         if self._closed:
             raise RuntimeError(
-                "ReactiveEventBus.emit() called after close() — "
+                "ReactiveEventBus.emit() called after close() - "
                 "the bus has been shut down and the RxPY Subject is completed"
             )
 
@@ -174,6 +174,39 @@ class ReactiveEventBus:
             raise TypeError("handler must be callable")
         self._subscriptions.setdefault(event_type, []).append(handler)
 
+    def unsubscribe(
+        self,
+        event_type: EventType,
+        handler: Callable[[DomainEvent], None],
+    ) -> bool:
+        """Remove *handler* for events of *event_type*.
+
+        Args:
+            event_type: The :class:`EventType` to stop listening for.
+            handler: Callable to remove (same object passed to
+                :meth:`subscribe`).
+
+        Returns:
+            True if the handler was found and removed, False otherwise.
+
+        Raises:
+            TypeError: If *event_type* is not an :class:`EventType`.
+            TypeError: If *handler* is not callable.
+        """
+        if not isinstance(event_type, EventType):
+            raise TypeError(
+                f"event_type must be an EventType, got {type(event_type).__name__!r}"
+            )
+        if not callable(handler):
+            raise TypeError("handler must be callable")
+
+        handlers = self._subscriptions.get(event_type, [])
+        try:
+            handlers.remove(handler)
+            return True
+        except ValueError:
+            return False
+
     @property
     def stream(self) -> Observable:
         """Read-only observable stream for advanced RxPY operators.
@@ -188,11 +221,10 @@ class ReactiveEventBus:
         """Complete the RxPY stream and prevent further event emission.
 
         Signals ``on_completed()`` to all RxPY subscribers, allowing them to
-        finalize their state (e.g. buffering operators flush, aggregation
-        operators emit their final result).  After ``close()``, any call to
-        :meth:`emit` raises :exc:`RuntimeError`.
+        finalize their state. After ``close()``, any call to :meth:`emit`
+        raises :exc:`RuntimeError`.
 
-        This method is idempotent — calling it more than once is safe.
+        This method is idempotent - calling it more than once is safe.
 
         Call this when the bus is no longer needed (e.g. in test teardown or
         application shutdown) to release RxPY Subject resources and prevent
@@ -207,11 +239,7 @@ class ReactiveEventBus:
         self._audit_log.clear()
 
     def __enter__(self) -> ReactiveEventBus:
-        """Support use as a context manager.
-
-        Returns:
-            The bus instance itself.
-        """
+        """Support use as a context manager."""
         return self
 
     def __exit__(
@@ -220,13 +248,7 @@ class ReactiveEventBus:
         exc_val: BaseException | None,
         exc_tb: TracebackType | None,
     ) -> None:
-        """Call :meth:`close` on context manager exit.
-
-        Args:
-            exc_type: Exception type, if any.
-            exc_val: Exception value, if any.
-            exc_tb: Exception traceback, if any.
-        """
+        """Call :meth:`close` on context manager exit."""
         self.close()
 
 

src/cleveragents/langgraph/bridge.py

@@ -14,7 +14,7 @@ from rx import operators as ops  # type: ignore[attr-defined]
 
 from cleveragents.langgraph.graph import GraphConfig, LangGraph
 from cleveragents.langgraph.nodes import Edge, NodeConfig, NodeType
-from cleveragents.langgraph.state import GraphState
+from cleveragents.langgraph.state import GraphState, StateUpdateMode
 from cleveragents.reactive.stream_router import (
     ReactiveStreamRouter,
     StreamConfig,
@@ -24,7 +24,13 @@ from cleveragents.reactive.stream_router import (
 
 
 class RxPyLangGraphBridge:
-    """Allows LangGraph nodes as RxPy operators and streams triggering graphs."""
+    """Allows LangGraph nodes as RxPy operators and streams triggering graphs.
+
+    Uses ``StateUpdateMode.APPEND`` as the default update mode so that
+    conversation history is preserved across operator invocations.
+    """
+
+    _DEFAULT_UPDATE_MODE = StateUpdateMode.APPEND
 
     def __init__(self, stream_router: ReactiveStreamRouter):
         self.stream_router = stream_router
@@ -237,16 +243,24 @@ class RxPyLangGraphBridge:
         return ops.flat_map(lambda msg: rx.from_future(create_future_task(msg)))
 
     def _create_state_updater(self, params: dict[str, Any]) -> Any:
+        """Create a state-update operator.
+
+        Uses ``StateUpdateMode.APPEND`` by default so that incoming
+        messages are appended to the existing conversation history rather
+        than replacing it.  An explicit ``mode`` key in *params* can
+        override this default.
+        """
         graph_name = params.get("graph")
         if not graph_name or graph_name not in self.graphs:
             raise ValueError(f"Invalid graph name: {graph_name}")
         graph = self.graphs[graph_name]
+        mode = StateUpdateMode(params.get("mode", self._DEFAULT_UPDATE_MODE.value))
 
         def update_state(msg: StreamMessage) -> StreamMessage:
             updates = (
                 msg.content if isinstance(msg.content, dict) else {"data": msg.content}
             )
-            graph.state_manager.update_state(updates)
+            graph.state_manager.update_state(updates, mode=mode)
             return msg.copy_with(
                 metadata={**msg.metadata, "state_updated": True, "graph": graph_name}
             )

src/cleveragents/langgraph/graph.py

@@ -19,7 +19,11 @@ from rx.subject import Subject  # type: ignore[attr-defined]
 
 from cleveragents.agents.base import Agent
 from cleveragents.langgraph.nodes import Edge, Node, NodeConfig, NodeType
-from cleveragents.langgraph.state import GraphState, StateManager
+from cleveragents.langgraph.state import (
+    GraphState,
+    StateManager,
+    StateUpdateMode,
+)
 from cleveragents.reactive.stream_router import (
     ReactiveStreamRouter,
     StreamConfig,
@@ -83,7 +87,7 @@ class LangGraph:  # pylint: disable=too-many-instance-attributes
         )
 
         self._node_executors: dict[str, Callable[[StreamMessage], StreamMessage]] = {}
-        # Default: min(32, cpu_count+4) — suitable for I/O-bound node executors
+        # Default: min(32, cpu_count+4) -- suitable for I/O-bound node executors
         self._executor_pool: concurrent.futures.ThreadPoolExecutor = (
             concurrent.futures.ThreadPoolExecutor()
         )
@@ -101,6 +105,14 @@ class LangGraph:  # pylint: disable=too-many-instance-attributes
             self._executor_pool.shutdown(wait=False)
 
     async def execute(self, input_data: GraphState | dict[str, Any]) -> GraphState:
+        """Execute the graph for one run.
+
+        At the start of each run the execution state is reset so that
+        ``current_node``, ``execution_count`` and ``error`` start fresh,
+        while the full conversation history (persistent across runs) is
+        made available to every node via the graph state and the node
+        config.
+        """
         if not self.is_running:
             raise RuntimeError(
                 f"Cannot execute graph {self.name!r}: graph is not running"
@@ -110,15 +122,29 @@ class LangGraph:  # pylint: disable=too-many-instance-attributes
             if isinstance(input_data, GraphState)
             else GraphState.from_dict(input_data)
         )
-        # Use replace_state() so the is_closed guard is enforced and state stream
-        # subscribers are notified through the proper StateManager API, preventing
-        # silent state corruption after StateManager.close() has been called.
-        self.state_manager.replace_state(state)
+
+        # --- reset execution state, preserve conversation history ---
+        self.state_manager.reset_execution_state()
+
+        # --- inject user message using APPEND mode ---
+        if isinstance(input_data, dict) and "messages" in input_data:
+            self.state_manager.update_state(
+                {"messages": input_data["messages"]},
+                mode=StateUpdateMode.APPEND,
+            )
+        else:
+            self.state_manager.update_state(
+                {"messages": list(state.messages)},
+                mode=StateUpdateMode.APPEND,
+            )
+
+        # Start stream signalling.
         start_stream = f"__{self.name}_node_start__"
         if start_stream in self.stream_router.streams:
             self.stream_router.send_message(start_stream, state.model_copy(deep=True))
         else:
             raise ValueError("Start stream not initialized")
+
         return self.state_manager.get_state()
 
     def get_execution_history(self) -> list[str]:

src/cleveragents/langgraph/nodes.py

@@ -59,6 +59,11 @@ class Edge(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict)
 
 
+def _is_tool_agent(agent: Any) -> bool:
+    """Return True if *agent* is an instance of :class:`ToolAgent`."""
+    return isinstance(agent, ToolAgent)
+
+
 class Node:  # pylint: disable=too-many-instance-attributes
     MAX_HISTORY_MESSAGES = 20
     MAX_HISTORY_CHARS = 12000
@@ -76,8 +81,18 @@ class Node:  # pylint: disable=too-many-instance-attributes
     def _prepare_conversation_history(
         self, messages: list[dict[str, Any]]
     ) -> tuple[list[dict[str, Any]], bool]:
+        """Prepare the conversation history that will be passed to an agent.
+
+        If ``config.metadata["full_history"]`` is ``True`` the entire message
+        list is returned without truncation -- this is the path used by nodes
+        that need full thread context.
+        """
         if not messages:
             return [], False
+
+        if self.config.metadata.get("full_history", False):
+            return list(messages), False
+
         raw_max_messages = self.config.metadata.get(
             "max_history_messages", self.MAX_HISTORY_MESSAGES
         )
@@ -150,11 +165,17 @@ class Node:  # pylint: disable=too-many-instance-attributes
             self.last_execution_time = loop.time() - start_time
 
     async def _execute_agent(self, state: GraphState) -> dict[str, Any]:
+        """Execute an agent node, passing full conversation history to the context.
+
+        When the node config has ``full_history: true`` the untruncated
+        message list is placed into :attr:`NodeConfig.metadata` under the
+        key ``conversation_history`` so that the executor can forward it
+        to the agent via the context dict.
+        """
         if not self.config.agent:
             raise ValueError(f"Agent node {self.name} has no agent specified")
         agent = self.agents.get(self.config.agent)
         if not agent:
-            # Fallback: synthesize a response when agent instance is unavailable
             return {
                 "messages": [
                     {
@@ -167,8 +188,9 @@ class Node:  # pylint: disable=too-many-instance-attributes
                 "current_node": self.name,
             }
 
+        # Extract actionable input.
         if state.messages:
-            if isinstance(agent, ToolAgent):
+            if _is_tool_agent(agent):
                 current_msg = state.metadata.get("current_message", "")
                 agent_input = (
                     str(current_msg)
@@ -191,9 +213,37 @@ class Node:  # pylint: disable=too-many-instance-attributes
         else:
             agent_input = ""
 
-        trimmed_history, history_truncated = self._prepare_conversation_history(
-            state.messages
+        # Prepare conversation history for the agent.
+        # When full_history is enabled the entire thread is used.
+        full_history_enabled = self.config.metadata.get("full_history", False)
+        if full_history_enabled:
+            trimmed_history = list(state.messages)
+            history_truncated = False
+        else:
+            trimmed_history, history_truncated = self._prepare_conversation_history(
+                state.messages
+            )
+
+        # Build a node config that explicitly contains conversation history
+        # so the executor layer can pass it to the agent process_message call.
+        config_with_history = NodeConfig(
+            name=self.config.name,
+            type=self.config.type,
+            agent=self.config.agent,
+            function=self.config.function,
+            tools=list(self.config.tools),
+            retry_policy=self.config.retry_policy,
+            timeout=self.config.timeout,
+            parallel=self.config.parallel,
+            condition=self.config.condition,
+            subgraph=self.config.subgraph,
+            metadata={
+                **self.config.metadata,
+                "conversation_history": trimmed_history,
+                "full_thread": full_history_enabled,
+            },
         )
+
         graph_state_dict = state.to_dict()
         graph_state_dict["messages"] = trimmed_history
 
@@ -201,6 +251,7 @@ class Node:  # pylint: disable=too-many-instance-attributes
             "graph_state": graph_state_dict,
             "conversation_history": trimmed_history,
             "full_context": True,
+            "node_config": config_with_history.model_dump(),
         }
         if history_truncated:
             context["_history_truncated"] = True
@@ -238,8 +289,8 @@ class Node:  # pylint: disable=too-many-instance-attributes
                 "graph_state",
                 "conversation_history",
                 "full_context",
-                "_history_truncated",
-                "_history_original_length",
+                "node_config",
+                "full_thread",
             }
             snapshot_keys = set(context_snapshot.keys()) if context_snapshot else set()
             current_keys = set(context.keys())

src/cleveragents/langgraph/state.py

@@ -41,7 +41,7 @@ class GraphState(BaseModel):
     model_config = ConfigDict(validate_assignment=True)
 
     def update(
-        self, updates: dict[str, Any], mode: StateUpdateMode = StateUpdateMode.MERGE
+        self, updates: dict[str, Any], mode: StateUpdateMode = StateUpdateMode.APPEND
     ) -> None:
         if mode == StateUpdateMode.REPLACE:
             for key, value in updates.items():
@@ -80,110 +80,360 @@ class GraphState(BaseModel):
             "error": self.error,
         }
 
+    def to_graph_state(self) -> dict[str, Any]:
+        """Return both conversation_history and execution_state keys.
+
+        This method is the canonical interface for serialising the state
+        into a graph-compatible dictionary, producing keys
+        ``conversation_history`` and ``execution_state`` as required by
+        the LangGraph wiring layer.
+        """
+        return {
+            "conversation_history": list(self.messages),
+            "execution_state": {
+                "current_node": self.current_node,
+                "execution_count": self.execution_count,
+                "error": self.error,
+                "metadata": dict(self.metadata),
+            },
+        }
+
     @classmethod
     def from_dict(cls: type[T], data: dict[str, Any]) -> T:
         return cls(**data)
 
 
-class StateManager:  # pylint: disable=too-many-instance-attributes
+class ExecutionState(BaseModel):
+    """Execution-level state that resets between runs.
+
+    This intentionally does NOT include messages—that belongs to the
+    conversation manager and must persist across runs.
+    """
+
+    current_node: str | None = None
+    execution_count: int = 0
+    error: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ConversationStateManager:  # pylint: disable=too-many-instance-attributes
+    """High-level state manager separating conversation history from execution state.
+
+    Conversation history (messages) *persists* across executions.  Execution-level
+    state (``current_node``, ``execution_count``, ``error``) is reset at the start
+    of each run via :meth:`reset_execution_state`.
+
+    Default update mode is ``StateUpdateMode.APPEND``.
+    """
+
+    MAX_HISTORY_SIZE: int = 50
+
     def __init__(
         self,
         initial_state: GraphState | None = None,
         checkpoint_dir: Path | None = None,
         enable_time_travel: bool = False,
-    ):
+    ) -> None:
         self.logger = logging.getLogger(__name__)
         self._lock = threading.RLock()
-        self.state = initial_state or GraphState()
-        self.checkpoint_dir = checkpoint_dir
-        self.enable_time_travel = enable_time_travel
-        self.state_stream = BehaviorSubject(self.state)
-        self.history: list[StateSnapshot] = []
+        self._mode: StateUpdateMode = StateUpdateMode.APPEND
+        # Persistent conversation messages.
+        self._conversation_history: list[dict[str, Any]] = []
+        if initial_state is not None and initial_state.messages:
+            self._conversation_history = list(initial_state.messages)
+        # Execution bookkeeping only.
+        self._execution_state = ExecutionState()
+        self.state_stream = BehaviorSubject(
+            initial_state or GraphState(messages=list(self._conversation_history))
+        )
+        self._snapshots: list[StateSnapshot] = []
         self.max_history_size = 100
         self.checkpoint_interval = 10
         self.update_count = 0
         self.is_closed = False
+        self.checkpoint_dir = checkpoint_dir
+        self.enable_time_travel = enable_time_travel
         if self.checkpoint_dir:
             self.checkpoint_dir.mkdir(parents=True, exist_ok=True)
 
-    def get_state(self) -> GraphState:
+    # -- Public API ----------------------------------------------------------
+
+    @property
+    def state(self) -> GraphState:
+        """Return the current full graph state (live reference for backward compat).
+
+        .. note::
+            This property returns a *live* ``GraphState`` built from the
+            internal conversation history and execution state.  Mutations
+            to the returned object's ``metadata`` dict are reflected in
+            ``_execution_state.metadata`` for backward compatibility with
+            code that does ``manager.state.metadata[key] = value``.
+        """
         with self._lock:
-            return self.state.model_copy(deep=True)
+            return self._full_state()
+
+    def get_state(self) -> GraphState:
+        """Return a deep-copy of the full graph state."""
+        with self._lock:
+            return self._full_state()
+
+    @property
+    def history(self) -> list[dict[str, Any]]:
+        """Return persistent conversation messages (the full history).
+
+        This property provides read-only access to the running conversation
+        transcript stored within this manager.
+        """
+        with self._lock:
+            return list(self._conversation_history)
+
+    @history.setter
+    def history(self, value: list[dict[str, Any]]) -> None:
+        """Replace the persistent conversation history."""
+        with self._lock:
+            self._conversation_history = list(value)
+
+    def get_full_history(self) -> list[dict[str, Any]]:
+        """Return the full persistent conversation history (deep copy)."""
+        with self._lock:
+            return list(self._conversation_history)
+
+    def reset_execution_state(self) -> None:
+        """Reset only execution-level state, NOT conversation history.
+
+        Clears ``current_node``, ``execution_count``, and ``error`` while
+        leaving the stored message history intact.
+        """
+        with self._lock:
+            self._execution_state = ExecutionState()
+            self.update_count = 0
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
+        self.logger.debug("Execution state reset; conversation history preserved")
+
+    def append_messages(self, messages: list[dict[str, Any]]) -> None:
+        """Append new messages to the persistent conversation history.
+
+        If the accumulated history exceeds :attr:`MAX_HISTORY_SIZE` the
+        oldest entries are evicted, keeping the most recent messages.
+        """
+        if not messages:
+            return
+        with self._lock:
+            self._conversation_history.extend(messages)
+            if len(self._conversation_history) > self.MAX_HISTORY_SIZE:
+                self._conversation_history = self._conversation_history[
+                    -self.MAX_HISTORY_SIZE :
+                ]
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
 
     def update_state(
         self,
         updates: dict[str, Any],
-        mode: StateUpdateMode = StateUpdateMode.MERGE,
+        mode: StateUpdateMode | None = None,
         node_id: str | None = None,
     ) -> GraphState:
         """Apply *updates* to the internal state and notify subscribers.
 
-        .. note::
-
-            Emission order is **not** guaranteed to match mutation order
-            under concurrent access.  The internal state is always
-            consistent (mutations are serialized by ``_lock``), but
-            ``state_stream.on_next()`` is called outside the lock, so
-            Thread B's emission may be observed before Thread A's if the
-            OS schedules B first after both release the lock.
+        Uses ``APPEND`` mode by default.  Message lists are *never*
+        clobbered—appending or merging is always used so that
+        conversation history is preserved across invocations.
         """
+        effective_mode = mode if mode is not None else self._mode
         with self._lock:
             if self.is_closed:
                 raise RuntimeError("StateManager is closed")
+
             if self.enable_time_travel:
                 snapshot = StateSnapshot(
-                    state=self.state.to_dict(),
+                    state=self._full_state().to_dict(),
                     timestamp=datetime.now(),
                     node_id=node_id,
                 )
-                self.history.append(snapshot)
-                if len(self.history) > self.max_history_size:
-                    self.history = self.history[-self.max_history_size :]
-
-            self.state.update(updates, mode)
-            self.state.execution_count += 1
+                self._snapshots.append(snapshot)
+                if len(self._snapshots) > self.max_history_size:
+                    self._snapshots = self._snapshots[-self.max_history_size :]
 
+            self._execution_state.execution_count += 1
             self.update_count += 1
+
+            for key, value in updates.items():
+                if key == "messages":
+                    if isinstance(value, list):
+                        self._conversation_history.extend(value)
+                        if len(self._conversation_history) > self.MAX_HISTORY_SIZE:
+                            self._conversation_history = self._conversation_history[
+                                -self.MAX_HISTORY_SIZE :
+                            ]
+                elif key == "metadata":
+                    if isinstance(value, dict):
+                        self._execution_state.metadata.update(value)
+                else:
+                    exec_field = key if key in ExecutionState.model_fields else None
+                    if exec_field is not None:
+                        if effective_mode == StateUpdateMode.REPLACE:
+                            setattr(self._execution_state, exec_field, value)
+                        elif effective_mode == StateUpdateMode.MERGE:
+                            cur = getattr(self._execution_state, exec_field)
+                            if isinstance(cur, dict) and isinstance(value, dict):
+                                cur.update(value)
+                            else:
+                                setattr(self._execution_state, exec_field, value)
+                        else:  # APPEND
+                            setattr(self._execution_state, exec_field, value)
+
             checkpoint_data_to_save: dict[str, Any] | None = None
             if (
                 self.checkpoint_dir
                 and self.update_count % self.checkpoint_interval == 0
             ):
                 checkpoint_data_to_save = {
-                    "state": self.state.to_dict(),
+                    "state": self._full_state().to_dict(),
                     "timestamp": datetime.now().strftime("%Y%m%d_%H%M%S"),
                     "update_count": self.update_count,
                 }
 
-            # Capture a deep copy while still under the lock so subscribers
-            # receive an immutable point-in-time snapshot.
-            state_copy = self.state.model_copy(deep=True)
+            state_copy = self._full_state()
 
-        # Perform file I/O outside the lock to avoid blocking other threads.
         if checkpoint_data_to_save is not None:
             self._save_checkpoint(checkpoint_data_to_save)
 
-        # Emit outside the lock to avoid re-entrant deadlock and priority
-        # inversion when subscribers call back into StateManager.
         self.state_stream.on_next(state_copy)
         return state_copy
 
-    def _save_checkpoint(self, checkpoint_data: dict[str, Any] | None = None) -> None:
-        """Persist a checkpoint to disk.
+    def get_state_observable(self) -> Observable:
+        return self.state_stream
 
-        When *checkpoint_data* is ``None`` the method acquires ``_lock``
-        internally to capture a consistent snapshot.  The lock is
-        reentrant (``threading.RLock``), so calling this method while
-        ``_lock`` is already held by the same thread is safe.
+    @property
+    def snapshots(self) -> list[StateSnapshot]:
+        """Return the list of time-travel state snapshots (read-only copy)."""
+        with self._lock:
+            return list(self._snapshots)
+
+    def clear_history(self) -> None:
+        """Clear the time-travel snapshot history."""
+        with self._lock:
+            self._snapshots.clear()
+
+    def load_checkpoint(self, checkpoint_file: Path) -> None:
+        """Restore state from a checkpoint file on disk."""
+        checkpoint_data = json.loads(checkpoint_file.read_text(encoding="utf-8"))
+        with self._lock:
+            if self.is_closed:
+                raise RuntimeError("StateManager is closed")
+            loaded = GraphState.from_dict(checkpoint_data["state"])
+            self._conversation_history = list(loaded.messages)
+            self._execution_state = ExecutionState(
+                current_node=loaded.current_node,
+                execution_count=loaded.execution_count,
+                error=loaded.error,
+                metadata=dict(loaded.metadata),
+            )
+            self.update_count = checkpoint_data.get("update_count", 0)
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
+        self.logger.info("Loaded checkpoint: %s", checkpoint_file)
+
+    def get_latest_checkpoint(self) -> Path | None:
+        """Return the path to the most recently written checkpoint, or None."""
+        if not self.checkpoint_dir:
+            return None
+        checkpoints = list(self.checkpoint_dir.glob("checkpoint_*.json"))
+        if not checkpoints:
+            return None
+        return max(checkpoints, key=lambda p: p.stat().st_mtime)
+
+    def time_travel(self, steps_back: int = 1) -> GraphState | None:
+        """Restore state to a previous snapshot and return it.
+
+        Returns ``None`` when time travel is disabled or no snapshots exist.
         """
+        with self._lock:
+            if self.is_closed:
+                raise RuntimeError("StateManager is closed")
+            if not self.enable_time_travel or not self._snapshots:
+                return None
+            if steps_back >= len(self._snapshots):
+                steps_back = len(self._snapshots) - 1
+            snapshot = self._snapshots[-(steps_back + 1)]
+            restored = GraphState.from_dict(snapshot.state)
+            self._conversation_history = list(restored.messages)
+            self._execution_state = ExecutionState(
+                current_node=restored.current_node,
+                execution_count=restored.execution_count,
+                error=restored.error,
+                metadata=dict(restored.metadata),
+            )
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
+        return state_copy
+
+    def replace_state(self, new_state: GraphState) -> None:
+        """Atomically replace the internal state and notify subscribers."""
+        with self._lock:
+            if self.is_closed:
+                raise RuntimeError("StateManager is closed")
+            self._conversation_history = list(new_state.messages)
+            self._execution_state = ExecutionState(
+                current_node=new_state.current_node,
+                execution_count=new_state.execution_count,
+                error=new_state.error,
+                metadata=dict(new_state.metadata),
+            )
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
+
+    def reset(self, initial_state: GraphState | None = None) -> None:
+        """Full reset: both conversation history AND execution state."""
+        with self._lock:
+            if self.is_closed:
+                raise RuntimeError("StateManager is closed")
+            self._conversation_history = []
+            if initial_state is not None:
+                if initial_state.messages:
+                    self._conversation_history = list(initial_state.messages)
+                self._execution_state = ExecutionState(
+                    current_node=initial_state.current_node,
+                    execution_count=initial_state.execution_count,
+                    error=initial_state.error,
+                    metadata=dict(initial_state.metadata),
+                )
+            else:
+                self._execution_state = ExecutionState()
+            self.update_count = 0
+            self._snapshots.clear()
+            state_copy = self._full_state()
+        self.state_stream.on_next(state_copy)
+
+    def close(self) -> None:
+        """Mark this manager as closed and complete the state stream."""
+        if self.is_closed:
+            return
+        self.is_closed = True
+        self.state_stream.on_completed()
+        self.logger.info("StateManager closed")
+
+    # -- Private helpers -----------------------------------------------------
+
+    def _full_state(self) -> GraphState:
+        """Build a GraphState from persistent + execution state."""
+        return GraphState(
+            messages=list(self._conversation_history),
+            metadata=dict(self._execution_state.metadata),
+            current_node=self._execution_state.current_node,
+            execution_count=self._execution_state.execution_count,
+            error=self._execution_state.error,
+        )
+
+    def _save_checkpoint(self, checkpoint_data: dict[str, Any] | None = None) -> None:
+        """Persist a checkpoint to disk."""
         if not self.checkpoint_dir:
             return
         if checkpoint_data is None:
-            # External callers (e.g. bridge) may invoke without pre-built
-            # data.  Acquire the lock to capture a consistent snapshot.
             with self._lock:
                 checkpoint_data = {
-                    "state": self.state.to_dict(),
+                    "state": self._full_state().to_dict(),
                     "timestamp": datetime.now().strftime("%Y%m%d_%H%M%S"),
                     "update_count": self.update_count,
                 }
@@ -200,84 +450,15 @@ class StateManager:  # pylint: disable=too-many-instance-attributes
         )
         self.logger.debug("Saved checkpoint: %s", checkpoint_file)
 
-    def load_checkpoint(self, checkpoint_file: Path) -> None:
-        # Read file I/O outside the lock to avoid blocking other threads.
-        checkpoint_data = json.loads(checkpoint_file.read_text(encoding="utf-8"))
-        with self._lock:
-            if self.is_closed:
-                raise RuntimeError("StateManager is closed")
-            self.state = GraphState.from_dict(checkpoint_data["state"])
-            self.update_count = checkpoint_data.get("update_count", 0)
-            state_copy = self.state.model_copy(deep=True)
-        self.state_stream.on_next(state_copy)
-        self.logger.info("Loaded checkpoint: %s", checkpoint_file)
 
-    def get_latest_checkpoint(self) -> Path | None:
-        if not self.checkpoint_dir:
-            return None
-        checkpoints = list(self.checkpoint_dir.glob("checkpoint_*.json"))
-        if not checkpoints:
-            return None
-        return max(checkpoints, key=lambda p: p.stat().st_mtime)
+# -- Backward-compatible alias -------------------------------------------------
 
-    def time_travel(self, steps_back: int = 1) -> GraphState | None:
-        with self._lock:
-            if self.is_closed:
-                raise RuntimeError("StateManager is closed")
-            if not self.enable_time_travel or not self.history:
-                return None
-            if steps_back >= len(self.history):
-                steps_back = len(self.history) - 1
-            snapshot = self.history[-(steps_back + 1)]
-            self.state = GraphState.from_dict(snapshot.state)
-            state_copy = self.state.model_copy(deep=True)
-        self.state_stream.on_next(state_copy)
-        return state_copy
 
-    def replace_state(self, new_state: GraphState) -> None:
-        """Atomically replace the internal state and notify subscribers.
+class StateManager(ConversationStateManager):
+    """Backward-compatible alias for ``ConversationStateManager``.
 
-        Raises :class:`RuntimeError` if the manager has been closed.
+    Provides the same interface as the original ``StateManager`` class while
+    inheriting all new conversation-state separation logic.
+    """
 
-        .. note::
-
-            See :meth:`update_state` for a note on emission ordering
-            under concurrent access.
-        """
-        with self._lock:
-            if self.is_closed:
-                raise RuntimeError("StateManager is closed")
-            self.state = new_state.model_copy(deep=True)
-            state_copy = new_state.model_copy(deep=True)
-        self.state_stream.on_next(state_copy)
-
-    def get_state_observable(self) -> Observable:
-        return self.state_stream
-
-    def clear_history(self) -> None:
-        with self._lock:
-            self.history.clear()
-
-    def reset(self, initial_state: GraphState | None = None) -> None:
-        with self._lock:
-            if self.is_closed:
-                raise RuntimeError("StateManager is closed")
-            self.state = (
-                initial_state.model_copy(deep=True) if initial_state else GraphState()
-            )
-            self.update_count = 0
-            self.history.clear()
-            state_copy = self.state.model_copy(deep=True)
-        self.state_stream.on_next(state_copy)
-
-    def close(self) -> None:
-        """Mark this manager as closed and complete the state stream.
-
-        After calling ``close()``, no further state updates should be
-        performed.  Any underlying checkpoint resources are released.
-        """
-        if self.is_closed:
-            return
-        self.is_closed = True
-        self.state_stream.on_completed()
-        self.logger.info("StateManager closed")
+    pass

src/cleveragents/skills/inline_executor.py

@@ -263,7 +263,8 @@ class InlineToolExecutor:
                 try:
                     resolved = Path(value).resolve()
                     sandbox_resolved = sandbox_path.resolve()
-                    if not str(resolved).startswith(str(sandbox_resolved)):
+                    rel = os.path.relpath(str(resolved), str(sandbox_resolved))
+                    if rel.startswith(".."):
                         return (
                             f"Path '{value}' for key '{key}' escapes sandbox "
                             f"root '{sandbox_path}'"

tests/events/test_event_bus_semantics.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from cleveragents.a2a.events import A2aEventQueue, EventBusBridge
+from cleveragents.application.services.fix_then_revalidate import (
+    FixThenRevalidateOrchestrator,
+)
+from cleveragents.application.services.validation_pipeline import ValidationPipeline
+from cleveragents.infrastructure.events.models import DomainEvent
+from cleveragents.infrastructure.events.reactive import ReactiveEventBus
+from cleveragents.infrastructure.events.types import EventType
+
+
+def _event(event_type: EventType = EventType.PLAN_CREATED) -> DomainEvent:
+    return DomainEvent(event_type=event_type)
+
+
+def _pipeline() -> ValidationPipeline:
+    return ValidationPipeline(commands=[], executor=lambda _name, _args: {})
+
+
+def test_reactive_event_bus_close_completes_and_rejects_later_emit() -> None:
+    bus = ReactiveEventBus()
+    completed: list[bool] = []
+    bus.stream.subscribe(on_completed=lambda: completed.append(True))
+
+    bus.close()
+
+    assert completed == [True]
+    try:
+        bus.emit(_event())
+    except RuntimeError:
+        pass
+    else:
+        raise AssertionError("emit after close should raise RuntimeError")
+
+
+def test_reactive_event_bus_context_manager_closes_bus() -> None:
+    bus = ReactiveEventBus()
+    completed: list[bool] = []
+    bus.stream.subscribe(on_completed=lambda: completed.append(True))
+
+    with bus as entered:
+        assert entered is bus
+
+    assert bus._closed is True
+    assert completed == [True]
+
+
+class _TypedEventBus:
+    def __init__(self) -> None:
+        self.handlers: dict[EventType, list[Callable[[DomainEvent], None]]] = {}
+
+    def emit(self, event: DomainEvent) -> None:
+        for handler in self.handlers.get(event.event_type, []):
+            handler(event)
+
+    def subscribe(
+        self, event_type: EventType, handler: Callable[[DomainEvent], None]
+    ) -> None:
+        self.handlers.setdefault(event_type, []).append(handler)
+
+    def unsubscribe(
+        self, event_type: EventType, handler: Callable[[DomainEvent], None]
+    ) -> bool:
+        handlers = self.handlers.get(event_type, [])
+        try:
+            handlers.remove(handler)
+        except ValueError:
+            return False
+        return True
+
+
+def test_event_bus_bridge_unsubscribes_from_typed_event_bus() -> None:
+    bus = _TypedEventBus()
+    queue = A2aEventQueue()
+    bridge = EventBusBridge(bus, queue)
+
+    bridge.start()
+    bus.emit(_event())
+    bridge.stop()
+    bus.emit(_event())
+
+    assert len(queue.get_events()) == 1
+    assert all(not handlers for handlers in bus.handlers.values())
+
+
+class _DisposableSubscription:
+    def __init__(self) -> None:
+        self.disposed = False
+
+    def dispose(self) -> None:
+        self.disposed = True
+
+
+class _LegacyEventBus:
+    def __init__(self) -> None:
+        self.callback: Callable[[DomainEvent], None] | None = None
+        self.subscription = _DisposableSubscription()
+
+    def subscribe(self, callback: Callable[[DomainEvent], None]) -> object:
+        self.callback = callback
+        return self.subscription
+
+
+def test_event_bus_bridge_still_supports_disposable_subscription_bus() -> None:
+    bus = _LegacyEventBus()
+    queue = A2aEventQueue()
+    bridge = EventBusBridge(bus, queue)
+
+    bridge.start()
+    assert bus.callback is not None
+    bus.callback(_event())
+    bridge.stop()
+
+    assert len(queue.get_events()) == 1
+    assert bus.subscription.disposed is True
+    assert bridge._subscription is None
+
+
+class _EmitOnlyBus:
+    def emit(self, event: DomainEvent) -> None:
+        pass
+
+
+def test_fix_then_revalidate_accepts_emit_only_event_sink() -> None:
+    orchestrator = FixThenRevalidateOrchestrator(
+        validation_pipeline=_pipeline(),
+        event_bus=_EmitOnlyBus(),  # type: ignore[arg-type]
+    )
+
+    assert orchestrator.event_bus is not None