Skip to content

Add capability-gated adoption for disconnected client-owned sessions #27

Description

@rynfar

Problem

A new Pylon server process cannot safely adopt a still-running Prime client_owned worker. Prime gives each DaemonClient a fresh in-memory owner identity, hides client-owned workers from other clients, and rejects a new client's attach. Disconnect also starts the owned-worker cleanup window. Pylon issue #84 therefore cannot be fixed with the current public list/attach/watch APIs.

promote_owned_session is not an acceptable substitute. It removes private owner scoping and makes the worker resident without proving recovery authority.

Required outcome

Add a frozen SDK feature and negotiated daemon capability for recoverable client-owned adoption. The exact token name is chosen with the implementation, but the contract must:

  • create a recoverable client-owned worker with an opaque, high-entropy recovery handle that is never returned by list/snapshot or written to logs;
  • durably bind the handle to the exact worker, private session, active-session lineage, supervisor generation, and correlated prompt lifecycle;
  • atomically adopt and attach only after the old owner transport is gone;
  • fence the old owner from reconnecting or mutating after adoption;
  • allow exactly one authority when adopters race;
  • make retry after an adopter crash converge without stranding a one-shot rotated token;
  • return a coherent generation-aware snapshot/cursor plus the exact correlated lifecycle state before recovered events are released;
  • transfer the connection-scoped MCP owner/credential atomically for an active streaming worker;
  • retain active recoverable work beyond the existing disconnect grace, with bounded terminal/unclaimed cleanup;
  • preserve authoritative complete_owned_session and cleanup proof after adoption.

Version 1 may require the same retained supervisor process and exact supervisor generation. A daemon/supervisor replacement, partial replay, or unavailable continuity fails closed.

Compatibility and security

  • Gate every new wire shape by negotiated protocol/schema/capability. Allocate the next free schema revision at implementation time; do not preclaim a revision against other open branches.
  • Old clients and supervisors must keep current behavior and cannot accidentally enable adoption.
  • Wrong, expired, other-session, stale-generation, live-owner, or concurrent-loser handles fail without disclosing that a worker exists.
  • Do not expose recovery handles, native identities, correlations, paths, prompts, snapshots, tool data, or transport details through public events or logs.
  • Adoption is full-access only. Approval-required sessions retain their current fail-closed behavior.

Acceptance coverage

  • disconnected old owner → exact handle adopts the same active worker; prompt count remains one;
  • old owner is fenced; two concurrent adopters yield one mutating authority;
  • adopter crash before response can retry without losing the worker;
  • live owner, wrong/expired handle, stale generation, partial replay, malformed snapshot, and mismatched lifecycle all fail closed;
  • exact MCP ownership transfers before any recovered event is exposed;
  • completion, cleanup, child/queue join, adoption, and supervisor-shutdown races converge without leaks;
  • mixed current/stock directions retain existing behavior;
  • public serialization and log canaries contain none of the private recovery material.

Dependencies and scope

Non-goals: Comet, nonpersistent_daemon_worker_v1, resident promotion, cross-host state copying, approval-required adoption, and Windows native transport authentication.

Activity

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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions