@@ -106,14 +106,23 @@ Startup fails if a requested transport cannot become ready, rather than silently
106106downgrading to local-only hosting. Select transports at startup; dispose and
107107recreate the host to change them.
108108
109+ ` githubEnvironment.requireConnectionBinding ` defaults to ` true ` : sealed
110+ authentication must bind the current handshake challenge, a fresh nonce and
111+ timestamp. Explicit ` false ` selects compatibility with clients sending unbound
112+ encrypted tokens. Relay encryption and resource authorization stay mandatory,
113+ but an unbound sealed token is replayable. This is the same transitional policy
114+ supported by ` copilotd ` , not a switch to plaintext authentication.
115+
109116GitHub-only hosting does not open a local listener. Its host handle has an
110117environment ID but no local URL or connection token. ` environmentId ` is absent
111118for local-only hosting. Disposal ends transport and registration activity without
112119deleting the saved MC environment record or application-owned sessions.
113120
114121Registering an environment does not publish every application session. Use
115- ` publishSession ` for existing resident sessions; factory callbacks and durable
116- catalog behavior are unchanged. Environment management is independent of a
122+ ` publishSession ` for an existing resident session, and ` listSessions ` to read
123+ the host's complete advertised catalog of live and dormant sessions. Listing
124+ does not start a host, publish a session, or paginate results. Factory callbacks
125+ and durable catalog behavior are unchanged. Environment management is independent of a
117126running host and available only through generated ` rpc.environments.list ` ,
118127` rpc.environments.get ` , and ` rpc.environments.delete ` operations, using each
119128language's naming conventions.
@@ -378,7 +387,8 @@ configuration before calling these methods, just as in the creation examples.
378387Python and .NET handles support asynchronous context management; Java handles
379388support try-with-resources. Go callers explicitly invoke ` Dispose(ctx) ` .
380389
381- Only durable catalog entries marked as application-owned invoke the resume
390+ Durable catalog entries marked as application-owned, including published
391+ application sessions, invoke the resume
382392factory. If its resume callback is missing, restoration fails rather than silently
383393falling back to host-owned creation. Published resident sessions attach directly and do not invoke either
384394factory. This callback does not provide arbitrary adoption or reconfiguration
@@ -398,11 +408,33 @@ and `sessionUri`. Publication does not call the factory, copy history, replace
398408the native session, or transfer ownership. Its metadata and workspace come
399409from the resident session, not from an application-supplied configuration.
400410
401- Published sessions are discoverable only for this listener's lifetime. They
402- are not imported into its durable catalog. Stopping the listener detaches its
403- participation without deleting the original session or transcript. A missing
404- or replaced resident session cannot be silently restored from disk by the
405- listener.
411+ Publication records the session in the durable, compute-scoped host catalog.
412+ Stopping the listener detaches its participation without deleting the catalog
413+ entry, original session, or transcript. A later host using the same compute
414+ identity can discover it as a dormant session. Restoring an application-owned
415+ session requires the owning application's ` resumeSession ` callback to configure
416+ its tools, hooks, and handlers; the host does not silently substitute host-owned
417+ session construction. A currently attached resident session still attaches
418+ directly without invoking a factory. The SDK does not expose an unpublish operation.
419+
420+ ### Listing host sessions
421+
422+ Call the owner-bound host handle to read every live or dormant session currently
423+ advertised by its host. The runtime returns the complete catalog in one response;
424+ the method does not start a host or publish sessions. The host ID is supplied
425+ by the handle, so the call stays on the original owning connection.
426+ Each method returns a ` HostListSessionsResult ` with a ` sessions ` collection,
427+ not the collection directly. In Node.js, use
428+ ` const { sessions } = await host.listSessions() ` .
429+
430+ | SDK | Method |
431+ | --- | --- |
432+ | Node.js | ` host.listSessions() ` |
433+ | Python | ` await host.list_sessions() ` |
434+ | Go | ` host.ListSessions(ctx) ` |
435+ | .NET | ` host.ListSessionsAsync(cancellationToken) ` |
436+ | Java | ` host.listSessions() ` |
437+ | Rust | ` host.list_sessions().await ` |
406438
407439### CLI hosting commands
408440
@@ -417,14 +449,11 @@ Sharing also shows the session URI. Use an AHP 0.9 client with the connection
417449token and ordinary GitHub resource authentication; the connection token alone
418450does not bypass resource authorization.
419451
420- ` /ahp status ` shows connection information. ` /ahp stop ` stops the ** entire
421- listener and all its shares** . ` /remote unshare ` removes the foreground session.
422- The pinned host has no per-session unregister operation, so unsharing drains
423- and restarts the listener at the same endpoint with the same connection token
424- before republishing other shares. Other clients must reconnect; local sessions
425- and their identities remain unchanged. Exiting the owning CLI stops the
426- listener as well. There is one listener per CLI/effective catalog, not one
427- listener per shared session.
452+ ` /ahp status ` shows connection information. ` /ahp stop ` stops the entire
453+ listener and its active participation, not its durable catalog. Other clients
454+ must reconnect after hosting restarts; local sessions and their identities
455+ remain unchanged. Exiting the owning CLI stops the listener as well. Hosting
456+ lifetime is separate from durable publication.
428457
429458` --ahp-host [--listen host:port] [--workspace directory] ` serves this same backend
430459in the CLI process, using normal SDK session construction, managed policy,
@@ -440,19 +469,36 @@ Outbound relay, host-picker and explicitly configured external-daemon controls r
440469
441470## Durable catalog and single host owner
442471
443- The runtime passes its actual resolved data directory to the host library; the single AHP
444- catalog lives at ` <effective Copilot home>/ahp/sessions ` . It follows the same
472+ The runtime passes its actual resolved data directory and compute identity to
473+ the host library. Durable catalogs are scoped to both the effective Copilot
474+ home and compute identity. The effective home follows the same
445475default ` ~/.copilot ` , ` COPILOT_HOME ` , and SDK ` baseDirectory ` resolution as that
446- runtime. The catalog contains sessions previously created through AHP, not all
447- SDK/CLI sessions. Listener disposal, owner disconnect, and restart retain it.
476+ runtime. Each catalog contains sessions previously created through AHP and
477+ explicitly published resident sessions, not all SDK/CLI sessions.
478+ Listener disposal, owner disconnect, and restart retain it.
448479A replacement listener can list and resume these sessions after authenticating.
449480
481+ Supply top-level ` AhpHostOptions.computeId ` to keep the same catalog when switching
482+ between local and Mission Control hosting. If omitted for a local-only start,
483+ the runtime persists a stable identity in its settings; the SDK never generates
484+ one. Mission Control's ` githubEnvironment.computeId ` remains required. When both
485+ compute IDs are supplied, they must agree or startup fails.
486+
487+ | SDK | Top-level compute identity |
488+ | --- | --- |
489+ | Node.js | ` computeId ` |
490+ | Python | ` compute_id ` |
491+ | Go | ` ComputeID ` |
492+ | .NET | ` ComputeId ` |
493+ | Java | ` setComputeId(...) ` |
494+ | Rust | ` with_compute_id(...) ` |
495+
450496Only one AHP server may own a catalog at a time. A second start for the
451- same location fails, including from another runtime. Ordinary runtimes, SDK
497+ same home and compute identity fails, including from another runtime. Ordinary runtimes, SDK
452498clients, and sessions do not acquire this lock and remain usable. The lock is
453499kernel-managed, non-blocking, held until shutdown writes finish, and released
454- even after forced process termination. Different effective homes have separate
455- catalogs. This does not change standalone ` copilotd ` defaults or concurrency
500+ even after forced process termination. Different effective homes or compute
501+ identities have separate catalogs. This does not change standalone ` copilotd ` defaults or concurrency
456502behavior, and does not add standalone/in-process shared-writer support.
457503
458504## Current GHES shell limitation
0 commit comments