Skip to content

Add session execution binding and thin PG Phase 2 substrate #70

Closed

Description

@delete-cloud

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:

  1. Durable session metadata (id, provider, model, policy, tape_id).
  2. Execution/workspace binding (repo_path, tool filesystem scope, shell working directory).
  3. 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

  1. Execution binding abstraction

    • ExecutionBinding base class with LocalExecutionBinding and CloudWorkspaceBinding.
    • BindingResolver protocol and DefaultBindingResolver.
    • Integrate binding into Session metadata round-trip and runtime hydration.
  2. Thin Phase 2 ownership substrate

    • PostgreSQL session_owners table with atomic acquire/renew/release.
    • App-layer SessionOwnerStore with fencing token validation.
    • Owner checks in SessionManager.run_agent, _restore_checkpoint, and close_session.

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 -v passes
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions