Repository navigation
Add session execution binding and thin PG Phase 2 substrate #70
Copy link
Copy link
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Summary
Separate WHERE a session runs from WHO owns it by introducing a first-class execution binding abstraction, then layer a thin Phase 2 ownership substrate (owners, leases, fencing tokens) on top of Phase 1 PostgreSQL persistence.
This work covers ADR-0014 and ADR-0013. The first executable slice is captured in the task packet below.
Why now
SessionManager currently conflates three concepts inside the Session object:
- Durable session metadata (id, provider, model, policy, tape_id).
- Execution/workspace binding (
repo_path, tool filesystem scope, shell working directory). - Current runtime owner (task, approval_event, event_queues, runtime_pipeline, runtime_ctx, runtime_adapter).
These change on different timelines. Without a binding boundary, repo_path cannot represent a cloud workspace without fragile string parsing, and multi-instance HTTP deployment has no answer to stale owners continuing to drive runtime state after failover.
Scope
-
Execution binding abstraction
ExecutionBindingbase class withLocalExecutionBindingandCloudWorkspaceBinding.BindingResolverprotocol andDefaultBindingResolver.- Integrate binding into
Sessionmetadata round-trip and runtime hydration.
-
Thin Phase 2 ownership substrate
- PostgreSQL
session_ownerstable with atomic acquire/renew/release. - App-layer
SessionOwnerStorewith fencing token validation. - Owner checks in
SessionManager.run_agent,_restore_checkpoint, andclose_session.
- PostgreSQL
Non-goals
- Cloud workspace tool implementations (only the binding skeleton).
- In-flight turn resume after owner loss (new owners rebuild cold state only).
- Brokered event routing or sticky routing hardening (acceptable for now).
- HTTP server endpoint changes for binding storage (follow-up slice).
References
- ADR-0014:
docs/adr/0014-separate-session-execution-binding-from-runtime-ownership.md - ADR-0013:
docs/adr/0013-define-phase2-multi-instance-session-ownership-for-pg-http-sessions.md - Implementation plan:
docs/superpowers/plans/2026-04-19-session-execution-binding-and-thin-phase2.md - Task packet (first slice):
.opencode/prompts/session-execution-binding-phase2-task-packet.md
Acceptance criteria
-
test_local_binding_resolves_to_workspace_root_for_create_agent -
test_session_metadata_round_trips_local_execution_binding -
test_session_metadata_defaults_missing_binding_to_local_from_repo_path -
test_cloud_workspace_binding_serializes_to_typed_dict -
test_binding_resolver_rejects_unknown_binding_kind -
test_run_agent_uses_resolved_workspace_root_from_binding -
test_restore_checkpoint_preserves_execution_binding -
test_session_owner_acquire_conflicts_with_live_lease -
test_session_owner_renew_rejects_stale_token -
test_run_agent_rejects_non_owner_instance -
test_restore_checkpoint_rejects_stale_owner -
test_close_session_rejects_stale_owner -
uv run pytest tests/ui/test_execution_binding.py tests/ui/test_session_owner_store.py tests/ui/test_session_manager_owner_checks.py tests/ui/test_session_manager_public_api.py tests/agentkit/storage/test_pg.py -vpasses
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity