dsh-bailinghub 0.2.0 → 0.4.0

package/SECURITY.md

@@ -19,15 +19,125 @@ configuration and are never model tool arguments.
 
 Non-loopback HTTP is denied by default. Do not enable insecure HTTP on an untrusted network.
 
-## Native 0.2.0 boundary
+## Native 0.4.0 boundary
 
-The native 0.2.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
+The native 0.4.0 plugin accepts only `hubUrl`, `clientAppId`, `workspace`, and
 `connectionName`. The generic SDK owns browser authorization, refresh, and secure credential
-storage; business endpoints and final authorization remain Core/business-system concerns.
+storage; business endpoints and final authorization remain Core/business-system concerns. The
+Hub Client App owns one business authorization entry. That business page, not the plugin or model,
+handles login, account switching, tenant selection, and the trusted `on_behalf_of` identity.
+
+The multi-connection registry stores only public Hub/client/workspace metadata. `connectionName`
+is a user-only local selector, not an identity claim. After browser
+authorization, the SDK replaces an older same-binding connection only when the trusted
+`on_behalf_of` matches; different trusted identities remain isolated. A same-alias authorization
+for a different identity preserves the original alias and Session and assigns the new identity a
+non-conflicting local alias. If inspection or old-Session revocation is uncertain, the new
+connection stays authorized and explicit cleanup is required.
+Connection add/use/remove are user slash commands, not model tools. Removing an authorized
+connection is remote-revoke-first and keeps the local credential if revocation fails, so it cannot
+falsely report a complete logout.
 
 Tools are Agent/run scoped. Message ids are replaced by Core-safe hash aliases, invocation ids are
 stable 64-character digests, and an `accepted_unknown` outcome must resume that exact invocation
 instead of creating a replacement. Completion retries are bounded and reuse one frozen,
-visible-only payload. Version 0.2.0 installs `bailinghub-mcp-server@0.2.0` as an exact ordinary
+visible-only payload. Version 0.4.0 installs `bailinghub-mcp-server@0.4.0` as an exact ordinary
 dependency and resolves its `./sdk` export. It does not depend on ambient modules, an optional
 peer, a range, a dist-tag, or a local path. Public `0.1.1` does not provide that facade.
+
+Agent Session credentials use macOS Keychain or Windows CurrentUser DPAPI-protected files under
+LocalAppData. Windows PowerShell or DPAPI unavailability fails closed without a plaintext fallback.
+Linux and other POSIX hosts must explicitly enable the SDK's isolated mode-0600 file store. The
+plugin never receives the credential value and never writes one into Cordis configuration.
+
+## Same-system authorization selection
+
+Version 0.4.0 lets the model select a session-local `authorization_ref` from the current
+conversation's directory. This is a constrained per-call selector, not a connection-management
+tool or authority to supply a Hub, route, raw connection key, credential, or business identity.
+The host must first explicitly select fixed connection keys for this conversation through
+`setSessionScope` or the user-only `/bailinghub scope set <connection-key>...` command. Aliases are
+not scope keys. Unset scope and `[]` (`/bailinghub scope none`) remain ordinary chat, without
+BailingHub tools or runs. Authorization and registry defaults cannot grant conversation scope.
+The selected bindings must share one Hub/client/workspace; unselected bindings are excluded.
+The adapter never implements selection by changing the SDK's global current connection.
+
+Hosts must await successful scope persistence and confirmation before sending the first user
+message. The first `user/message` event freezes scope, with the inbox claim as a fallback, before
+`startTurn`; an in-flight or
+failed selection cannot admit business work. Subsequent changes require a new conversation.
+The full selected group is checked before business input is sent. Any missing, revoked, replaced,
+or unreadable selected authorization pauses the whole conversation's business access. The adapter
+must not silently adopt a default or shrink the scope to the remaining valid authorizations.
+
+Local connection names are untrusted display data. They do not prove tenant identity, widen an
+authorization, or replace the business system's final permission checks. The directory is a
+binding snapshot, not a credential snapshot: expired, removed, or revoked access must fail
+without silently selecting another authorization. New authorizations and alias changes require
+a new conversation.
+The host checks the fixed connection key, workspace, and original Agent Session id before
+transport operations. An Agent Session replacement also requires a new conversation, even if
+the local alias or connection key remains unchanged.
+
+Matching declarations share one typed tool. Conflicting same-name descriptions, schemas, or
+governance are not merged for execution, and a shared declaration cannot confer another identity's permissions.
+Each invocation binds its chosen authorization, Core run, and capability revision. Recovery
+accepts only an invocation known to this conversation and resolves its original binding; the
+model cannot provide a replacement authorization. Changing a default connection cannot retarget
+an existing call.
+This invocation map lasts only for the live conversation: later turns can recover its original
+calls, while new conversations and process restarts must reject unknown invocation ids.
+
+Only non-secret scope metadata belongs in the scope store. Its default file store uses SHA-256 session filenames,
+mode-0600 files and mode-0700 directories on POSIX, bounded reads, rejection of symlinks/non-regular files,
+revision compare-and-swap, a cross-process lock, and atomic replacement. Lock timeout reports a
+conflict without deleting another process's lock. Corrupt data and I/O failure fail closed; they
+are never interpreted as an absent selection or a reason to use memory storage. Before validating
+a replacement scope, the coordinator attempts to persist `needs_selection`. Failure of that first
+write can leave the previous draft on disk. Every unlocked snapshot loaded into a new runtime is
+therefore blocked pending explicit selection, without checking its previous SDK authorizations;
+restart safety does not assume that the failed write replaced the old record.
+
+The host may inject a store with the same CAS semantics; the provided memory adapter is explicitly
+non-persistent. `restoreSessionScope` restores only a valid locked selection after verifying its
+keys, binding, and original Agent Session ids. Unlocked drafts require explicit selection again;
+started conversations without valid locked scope stay blocked. History containing only metadata,
+configuration, or seed markers does not prove that a conversation started. The lifecycle check
+requires an actual user-sourced `user/message` or `turn/start` and uses seed/observation boundaries
+to distinguish prior history from a new first message. It restores scope only, not invocations,
+approvals, pending completions, or task execution. A new conversation is required to change an
+already-started scope. No token, credential, prompt, or business payload belongs in the
+scope snapshot.
+The trusted host owns stable, unique conversation ids and the store namespace. Scope APIs and
+records must not be exposed as model-controlled storage or allow an untrusted caller to select
+another conversation's id. This plugin does not secure unrelated host filesystem tools; the host
+must enforce that access boundary.
+
+The adapter keeps authorization-specific instructions and context labeled, and each run receives
+only its authorization's deterministic call summary. It does not broadcast a combined final
+answer to every run. Visible user input and context do share the local conversation boundary;
+see [Privacy](PRIVACY.md#same-system-authorization-selection).
+
+The independent conversation-audit extension sends visible text for the complete frozen member
+set through an optional SDK API. A durable random archive UUID supplies correlation, not authority:
+the SDK/Core must validate every original member before confirming or appending, and Core owns the
+aggregate read permission. Never expose mixed free text to a reader authorized for only one member
+by assuming it can be safely redacted. The original run id and member Session bind run links;
+archive synchronization cannot create or resume a business action. Late links remain attached to
+their original turn.
+
+The separate private outbox contains plaintext visible task text and must be protected from
+untrusted host/model filesystem tools. It has bounded reads, no-follow regular-file checks,
+CAS/lock/atomic-write semantics, and no credential or scope-store fallback. Payloads and ids remain
+stable on ambiguous network retries. Local I/O failure can leave an unpersisted event: available
+DSH history is compared after reopening, and missing events produce `recovery_gap`, not a claim
+of a complete transcript. Hosts without history must show unverified coverage. This boundary is
+not a distributed transaction or durable business-task recovery mechanism.
+
+Transient transport failures do not prove that an original authorization was revoked. Scope
+get/restore and archive retry may revalidate all original members on the same runtime, while
+keeping business access and uploads closed until validation succeeds. Concurrent callers share
+that validation. Confirmed revocation/replacement and storage/CAS conflicts remain terminally
+blocked, with no default or subset fallback. The gate is rechecked after asynchronous archive
+capability discovery and outbox opening; a late result cannot erase a confirmed revocation.
+Known local storage errors and capture gaps remain visible even while network or scope checks block upload.

package/docs/AGENT_CLIENT_CONTRACT.md

@@ -1,7 +1,238 @@
 # Agent Client Host Adapter Contract
 
-Status: public native Agent Client contract for `dsh-bailinghub@0.2.0`. This contract is not part
-of the legacy public `0.1.x` line.
+Status: native Agent Client contract for `dsh-bailinghub@0.4.0`, paired with
+`bailinghub-mcp-server@0.4.0` and recommended BailingHub Core `0.6.1` (minimum API version
+`0.6.0`). This contract is separate from the legacy static `0.1.x` path. Version 0.3.0 supported user-managed connections but did not include
+explicit conversation scope, multi-authorization tool selection, or the visible conversation archive.
+
+## Same-System Authorization Selection
+
+This increment supports multiple independently authorized identities for one public
+`Hub + clientAppId + workspace` binding in one DSH conversation. It does not combine different
+systems or routes, alter business capability declarations, or change Core authorization rules.
+
+Version 0.4.0 changes the default: a new conversation with no selected scope, or an explicitly
+empty `connectionKeys: []`, is ordinary chat. It starts no BailingHub run and exposes no BailingHub
+business tools. Browser authorization, the registry's current connection, and the four bootstrap
+fields do not select a conversation's scope. There is no automatic discovery-and-enable fallback.
+
+The host explicitly selects fixed SDK connection keys before sending the first user message.
+Exactly one selected authorization keeps the original typed arguments and result shape; two or
+more selected authorizations use the shared envelope below. All selected keys must be authorized
+under the same Hub/client/workspace binding. Unselected connections are never added to the scope.
+The model receives a projected directory containing
+session-local `authorization_ref` values, local display names, and availability, not raw connection
+keys, credentials, Agent Session metadata,
+or permission to supply arbitrary route or identity values. A local name is untrusted display
+data, not proof of a tenant or store. The model must resolve ambiguous user intent before acting;
+available authorization is not a request to act on every listed identity.
+Labels use existing local `connectionName` metadata, not token-derived business names or a new
+Core identity-display field. Generic aliases such as `default` and `default-2` do not establish
+an A/B business mapping; the user must supply clear labels while the business authorization page
+continues to determine the trusted identity.
+
+The directory's references resolve to the explicitly selected SDK connection bindings. The first
+`user/message` event freezes the selection, with `agent/inbox/claimed` as a fallback for drivers
+that do not emit that event, before `startTurn`. Changing the selected keys after
+that point requires a new conversation, including switching between ordinary chat and business
+mode. Adding a registry authorization or changing its alias never expands an existing scope.
+Capturing a binding does not freeze credentials or bypass refresh, expiry, revocation, or
+downstream authorization checks.
+Before transport operations, `status({ connectionKey })` must report the captured connection key,
+workspace, and the original authorized Agent Session id captured during selection. If any selected
+authorization is missing, invalid, replaced, or cannot be checked, business access for the entire
+conversation pauses. It neither falls back to a default nor silently shrinks to the remaining
+authorizations. A new conversation can explicitly select the still-valid subset. These inspection
+fields stay host-side. The
+adapter passes `connectionKey` and `workspace` as explicit SDK host metadata instead of
+resolving a mutable alias or default.
+
+The full selection is validated before any selected system receives the turn. For each direct
+user turn, the adapter starts one Core run per selected authorization before
+assembling the model request. Instructions, governance, knowledge, memory, and tool results carry
+authorization labels. The user input is sent to each of those runs. Separate run state preserves
+attribution; all injected context still shares the local Agent/model boundary described in
+[Privacy](../PRIVACY.md#same-system-authorization-selection).
+
+Business definitions with the same name, description, input schema, and governance are registered
+once.
+Conflicting declarations are not merged for execution. Availability remains specific to each
+authorization, and the conversation's total active business-tool limit remains 12. In a
+multi-authorization session, each shared definition wraps its unchanged business schema:
+
+```json
+{
+  "authorization_ref": "<host-issued reference from this session>",
+  "arguments": { "<business parameter>": "<value>" }
+}
+```
+
+The selector is host metadata; it is not forwarded as a business argument or new Core HTTP
+field. A single-authorization session keeps the original unwrapped business schema.
+`search_business_capabilities` accepts an optional `authorization_ref` using the same reference
+boundary; omission searches all captured authorizations. Its responses update the selected
+authorizations' capability revisions and definitions before rebuilding
+the shared tool view. It cannot import a different binding into the conversation.
+
+Invocation state captures the selected authorization, Core run, capability revision, tool, and
+arguments. A replay with a different selector or payload fails closed. Recovery accepts only an
+invocation known to this conversation and uses the original binding; it accepts no replacement
+authorization selector. Pending approval and unknown dispatch outcomes follow the same
+exact-invocation recovery rules as the baseline. Removing or selecting another default must not
+retarget an existing invocation.
+The local invocation map survives later turns of the same live conversation. It is not persisted
+across process restarts or copied into new conversations, and unknown invocation ids fail closed.
+This increment does not provide durable task recovery across those boundaries.
+
+On multi-authorization completion, the adapter freezes one deterministic summary of each run's
+own governed calls and synchronizes that run separately. It does not send the combined visible
+assistant answer, another authorization's results, or hidden reasoning to every run. The combined
+answer is instead eligible for the separate conversation audit below. Single-authorization completion keeps the existing visible-answer
+behavior. Connection add/use/remove remain user-only commands, not model tools.
+
+### Host-owned session scope API
+
+The runtime service exposes asynchronous `getSessionScope(sessionId)`,
+`setSessionScope(sessionId, { connectionKeys, expectedRevision? })`, and
+`restoreSessionScope(sessionId)`. They are host APIs, never model tools. Use keys returned by the
+SDK registry, not aliases or model-provided identity values.
+
+Native DSH users can inspect `/bailinghub scope`, choose ordinary chat with
+`/bailinghub scope none`, or select fixed keys with `/bailinghub scope set <connection-key>...`
+before the first user message. Obtain keys from `/bailinghub connections list`; the scope command
+does not accept aliases, adopt a registry default, or start a business run. These are user-only
+commands over the same scope API.
+
+```js
+const runtime = ctx.get('bailingHubAgentClient')
+const previous = await runtime.getSessionScope(sessionId)
+const selected = await runtime.setSessionScope(sessionId, {
+  connectionKeys: selectedConnectionKeys, // [] explicitly chooses ordinary chat
+  expectedRevision: previous.revision,
+})
+// Render selected.mode and selected.authorizations, then enable sending.
+// Do not dispatch the first user message while this operation is pending or failed.
+```
+
+The returned view includes `schema`, `sessionId`, integer-or-null `revision`, `state`
+(`unselected`, `ready`, or `needs_selection`), `locked`, `mode` (`chat`, `business`, or `blocked`),
+and public authorization entries. `get` reads the scope; it does not grant access. A host must await
+a successful `set`, show its returned selection, and only then send the first message. Never
+optimistically send using an earlier scope. Before the first message, a failed replacement
+selection leaves business access blocked; it cannot restore the previous broader selection.
+After the scope is frozen, a change request returns `SESSION_SCOPE_LOCKED` and leaves the original
+frozen scope unchanged. The host must open a new conversation, not treat that rejection as a
+successful selection of the requested keys. Revision values may advance more than once
+during selection; always use the returned value for the next compare-and-swap request.
+
+Each returned `authorizations` entry has exactly the public host-facing fields
+`{ authorizationRef, connectionKey, label, workspace }`. The selection accepts at most 64 unique
+connection keys. The trusted host owns `sessionId`: it must remain stable when reopening the same
+conversation and be unique within that store's namespace. Do not let the model or an untrusted
+client choose another conversation's id, edit scope records, or control the storage namespace.
+The store and its access policy belong to the host. The model sees only the projected reference,
+label, and availability directory; raw connection keys and scope storage are not model APIs.
+
+Reopening an existing conversation must call `restoreSessionScope` before sending. A valid
+`locked: true` snapshot restores its original scope after the saved binding and Agent Sessions
+are checked; it remains locked. A stored `locked: false` snapshot is only a draft, even if its
+stored state says `ready`. Loading it into a new runtime returns `needs_selection` / `blocked`
+without probing its previously selected SDK connections. A never-started draft remains
+`locked: false`: the host must explicitly call `setSessionScope` again and show success before
+sending. It must not silently reactivate the saved draft selection.
+
+If a locked conversation is reopened offline, its business gate stays closed. A timeout,
+connection failure, or incomplete authorization response is not proof of revocation: retry
+`restoreSessionScope`, `getSessionScope`, or `syncSessionArchive` on the **same runtime and Session**
+after connectivity returns. All original members must pass validation before business access or
+archive upload resumes. Concurrent callers wait for the same in-flight whole-scope validation.
+Retries preserve the original keys, Agent Sessions, binding, member set, and persisted scope revision.
+Confirmed revocation, identity/binding replacement, corrupt storage, or a CAS conflict remains
+blocked; retries never select a default, remaining subset, or replacement Session.
+
+An old conversation without a valid snapshot stays blocked; missing or corrupt state must not
+adopt today's registry default or discovered authorizations. Trusted history containing only
+configuration or metadata still permits draft selection. Actual user-message or turn history
+requires the original locked scope; changing that scope requires a new conversation. Embedded
+hosts without the native commands or a scope-selection UI must integrate these APIs;
+`connections use` is not a substitute.
+
+### Scope persistence seam
+
+`createAgentClientPlugin({ scopeStore })` accepts an explicit store with `load(sessionId)` and
+`save(sessionId, record, expectedRevision)`. `load` returns a validated record or `null` for absence;
+errors and corrupt records are not absence. `save` compares the stored revision atomically:
+`null` means the record must not exist, the first revision is `1`, and each update increments it.
+Before validating a replacement selection, the coordinator attempts to save a `needs_selection`
+record. If that first write fails, the previous draft can remain on disk; the write is not
+reported as successful. Restart safety also depends on the draft rule above: every loaded
+unlocked snapshot requires explicit confirmation, so a stale saved selection never becomes
+`ready` automatically, even when its replacement marker could not be written.
+
+The default `createFileSessionScopeStore()` saves non-secret JSON under
+`$DSH_HOME/plugins/dsh-bailinghub/session-scopes`, using `~/.dsh` when `DSH_HOME` is unset. Session
+ids are hashed into filenames. On POSIX, files use mode `0600` and directories `0700`; writes use a
+cross-process lock, compare-and-swap, and atomic replacement. Lock conflicts and storage failures
+fail closed; the adapter never switches to an in-memory fallback. Hosts may inject another
+durable implementation. `createMemorySessionScopeStore()` is an explicit, non-persistent option
+for tests or hosts that deliberately accept losing scope state on restart.
+
+The snapshot contains only the scope schema, DSH session id, revision, state/lock, public binding,
+and selected connection keys, sanitized labels, workspace, and original Agent Session ids. It
+contains no credentials, tokens, prompts, business arguments/results, or invocation state.
+Restoring a scope does **not** restore an invocation, approval, pending completion, or task.
+
+### Independent visible conversation archive
+
+The visible archive requires SDK `0.4.0` and Core APIs introduced in `0.6.0`; the recommended
+Core release is `0.6.1`. Earlier `0.3.0` SDK/plugin packages do not provide this contract.
+After a nonempty scope is frozen, the adapter captures claimed user text, every durable `assistant/message` text block, turn start/end, and verified original run links. It ignores
+`assistant/chunk`, hidden reasoning, attachments, raw provider requests, and arbitrary tool payloads.
+The archive is one record for the complete fixed authorization set; per-authorization run summaries
+are unchanged. It is not written into each member's memory.
+
+The optional SDK seam is `syncConversationArchive(envelope, { members })`. `envelope` contains a
+durable random UUID `clientArchiveId`, the same `clientConversationId` used by `startTurn`, and
+ordered `events`. Each event has a stable UUID `event_id`, contiguous `sequence` starting at one,
+the original `client_turn_id`, and `kind`: `turn_start`, `user_message`, `assistant_message`,
+`run_link`, or `turn_end`. Messages contain `content`; a run link contains the original `run_id`
+and `member_session_id`; turn end contains `completed`, `failed`, or `cancelled` status. A late
+original run response may attach its link to an already ended turn. It never reactivates its
+business tools, dispatches that cancelled turn's remaining members, or replaces a newer active turn.
+The SDK receives host-only member records `{ connectionKey, workspace, expectedSessionId, label }`,
+checks every original authorization, and owns HTTP batching and credential use. The first frozen
+member is the writer. Neither the old hash alias nor a random archive UUID confers read/write access.
+
+`createAgentClientPlugin({ archiveStore })` accepts an independent CAS store with `load`/`save`,
+using the same revision semantics as the scope store but a distinct schema and directory.
+`createFileConversationArchiveStore({ directory? })` defaults to
+`$DSH_HOME/plugins/dsh-bailinghub/conversation-outbox`, with private file permissions, atomic writes,
+and a 32 MiB local record bound. `createMemoryConversationArchiveStore()` is explicitly volatile.
+Outboxes retain the frozen membership, random identity, visible events, event hashes/ids, and
+acknowledged cursor. They contain task text; they are not credential stores. The SDK rejects a
+message above 64,000 characters; the adapter does not silently truncate it or discard pending text.
+Core's conversation/event quotas and the local bound can leave synchronization pending.
+
+Host APIs `getSessionArchiveStatus(sessionId)` and `syncSessionArchive(sessionId)` and the user-only
+`/bailinghub archive status|sync` commands expose synchronization separately from business state.
+Persisted pending events can be retried after reopening under the original valid frozen scope,
+without replaying `startTurn`, `invoke`, `resume`, or `completeRun`. An older SDK reports
+`unsupported` without accessing the outbox directory; an unavailable/older Core leaves saved events
+pending or unsupported for retry. Empty scope does not load a transport or create an archive.
+
+Capture begins with business turns enabled under this archive contract. Previously unarchived history is not silently
+claimed as complete. Status compares saved visible events against the available DSH `session.events`:
+missing user/assistant text or turn boundaries report `recovery_gap` / `coverage: incomplete`, even
+if the saved prefix is synchronized. Hosts without durable history report `coverage: unverified`.
+This check does not reconstruct missing business run ids. Network failure leaves durable events
+retryable; a local write failure can leave only an in-memory pending event until storage recovers.
+While scope validation or transport availability prevents upload, a known `storage_error` or
+`recovery_gap` remains visible with the existing unsaved-event count and coverage. An optional
+`availability` field describes the additional upload restriction; it does not clear the local error.
+Capability-discovery network failures report `pending`, not a fabricated local storage failure.
+If the process ends before that write succeeds, the host-history check reports the detectable gap;
+there is no atomic transaction between DSH's event log, this outbox, and Core. It does not promise
+recovery of absent host history, hidden content, or durable business task execution.
 
 ## Host Configuration
 
@@ -14,9 +245,13 @@ workspace
 connectionName
 ```
 
-`hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace.
-`connectionName` is a local SDK alias. No business endpoint, authorization endpoint, token, secret,
-or business credential belongs in this config.
+`hubUrl`, `clientAppId`, and `workspace` identify a public Hub-side application/workspace binding.
+`connectionName` selects a local SDK connection for connection-management commands; it does not
+select the conversation scope. It is not an account, tenant, or
+identity claim. The Hub Client App resolves to one stable business authorization endpoint; no
+business endpoint, authorization endpoint, token, secret, or business credential belongs in this
+config. The business authorization page owns sign-in, account switching, tenant selection, and
+the trusted identity ultimately represented by `on_behalf_of`.
 
 ## Injectable Transport Seam
 
@@ -24,8 +259,13 @@ The default transport is lazily created from `bailinghub-mcp-server/sdk`. Tests
 adapters may inject an object with all methods below:
 
 ```js
+connectionsList({})
+connectionsAdd({ connectionName, hubUrl, clientAppId, workspace })
+connectionsUse(connectionNameOrKey)
+connectionsRemove(connectionNameOrKey)
+
 login({ hubUrl, clientAppId, workspace, route, connectionName })
-status({ connectionName })
+status({ connectionKey }) // conversation checks; management may use connectionName
 logout({ connectionName })
 workspaces({ connectionName })
 use({ workspace, route, connectionName })
@@ -41,7 +281,7 @@ startTurn({
 
 searchCapabilities({ query, limit?, runId? })
 invoke({ invocationId, capabilityRevision, agentRunId, tool, arguments })
-resume(invocationId, {}, { workspace, connectionName, signal? })
+resume(invocationId, {}, { workspace, connectionKey, signal? })
 completeRun(runId, {
   assistantMessageId,
   content,
@@ -52,9 +292,35 @@ completeRun(runId, {
 })
 ```
 
-The adapter may pass a second host metadata argument (`workspace`, `connectionName`, and an
-`AbortSignal`) to turn/tool methods. The framework-neutral SDK DTO is always the first argument;
-an SDK implementation that does not consume host metadata may ignore it.
+The adapter passes host metadata (`workspace`, fixed `connectionKey`, and optional `signal`)
+separately from the business DTO to turn/tool methods, and as the third argument to completion
+and resume. The transport must honor that exact selection; it must never ignore it or substitute
+a mutable alias/default. Connection-management commands may use `connectionName`. The optional
+archive seam and its complete frozen member selection are specified above.
+
+## Browser Identity and Local Reconciliation
+
+`/bailinghub login` always starts from the selected Hub/client/workspace binding. The plugin does
+not accept or derive a business URL, account id, tenant id, or identity selector. Core redirects
+to the single authorization endpoint configured for that Client App, and the business page
+performs any login, account switching, or tenant selection required before it approves the
+authorization.
+
+The SDK may stage more than one named local instance for the same public binding while browser
+authorization is in progress. After authorization it compares the trusted Session
+`on_behalf_of`, never the local `connectionName`:
+
+- the same identity replaces the older local connection and revokes its old Agent Session;
+- a different identity remains a separate named connection; when login was launched from an alias
+  already owned by the old identity, the SDK preserves that alias and Session, allocates an
+  available alias such as `default-2` to the new identity, and makes the new connection current;
+- an uncertain identity inspection or failed old-Session revoke keeps the new Session authorized
+  and returns `cleanupRequired: true` with cleanup metadata.
+
+The adapter reports that last result as successful authorization plus a visible warning. It tells
+the user not to authorize again and to retry explicit cleanup with the user-only connection
+lifecycle commands. It does not turn the result into a failed login or let the model perform
+cleanup.
 
 ## Core HTTP Mapping
 
@@ -97,9 +363,9 @@ object-rooted input schema, and complete governance metadata (`scope`, `risk`,
 Both revision fields are required lowercase 64-character SHA-256 values; shorter labels or
 uppercase digests fail closed.
 
-## Verified DSH rc.7 Lifecycle
+## Verified DSH Lifecycles
 
-DSH `0.1.0-rc.7` claims inbox messages before assembling the current step:
+DSH `0.1.0-rc.7` and `0.1.1-rc.2` claim inbox messages before assembling the current step:
 
 ```text
 agent/inbox/claimed
@@ -109,7 +375,15 @@ agent/inbox/claimed
   -> model request
 ```
 
-The adapter captures only a claimed message whose `source.kind` is `user`. On the authoritative
+The adapter captures only a claimed message whose `source.kind` is `user`. The
+first `user/message` event freezes scope; the inbox claim is a fallback if that event is absent.
+The assembly gate permits business work only for the saved selection.
+When inspecting attached or restored history, only `user/message` with `source.kind: 'user'` or
+`turn/start` proves that a conversation has started. Configuration events, metadata, and
+`session/end-seed` alone do not freeze a draft. `firstLiveSeq` is a seed-history boundary, never
+proof of a started conversation by itself. The adapter separates the previously observed or
+seeded prefix from new events so the current first message is not mistaken for an older turn.
+On the authoritative
 `system-prompt/assemble` waterfall, it calls `startTurn`, registers the returned definitions
 through `agent.ctx.tools.register()`, and also adds their schemas to the already-sampled current
 assembly. Later steps receive the same agent-scoped definitions from the ordinary ToolRuntime
@@ -130,10 +404,11 @@ The adapter listens to durable `session/event` values:
 
 ## Tool Invocation and Recovery
 
-Every active Core tool becomes an agent-scoped DSH definition. Its invocation id is a stable
-64-character lowercase SHA-256 digest of the session, run, DSH call id, and Core tool name. It
-calls the SDK `invoke` DTO without letting the model choose the run, capability revision, route,
-or identity.
+Every active Core tool becomes an agent-scoped DSH definition. Its
+invocation id is a stable 64-character lowercase SHA-256 digest of the session, run, DSH call id,
+and Core tool name. It
+calls the SDK `invoke` DTO without letting the model supply the run, capability revision, route,
+or arbitrary identity. The constrained authorization selector is described above.
 
 An SDK error with `disposition === 'accepted_unknown'` starts recovery with the exact invocation
 id; it never repeats the business-tool `invoke`. Likewise, `awaiting_approval`, `in_progress`, and
@@ -160,16 +435,48 @@ same bounded recovery state when known locally, and never creates a replacement
 
 ## Session and Completion State
 
-Connection name, workspace, conversation alias, Core run, active definitions, and completion
-state are isolated per DSH Agent/session. A workspace switch affects future sessions and is
-rejected while any Core run is active/completing or has an unsynchronized completion payload.
+Connection selector, workspace, conversation alias, Core run, active definitions, and completion
+state are isolated per DSH Agent/session. Named connections for different trusted identities own
+separate SDK credentials and Agent Sessions. Same-binding connections that resolve to the same
+trusted identity are reconciled to one local survivor after authorization. A workspace switch
+preserves the selected connection instance and changes connection-management defaults; it is rejected while any
+Core run is active/completing or has an unsynchronized completion payload.
+
+After a same-alias login resolves to a different trusted identity, the SDK-returned replacement
+alias becomes the adapter's registry default. The retained old alias and the new alias both
+remain visible through `connections list` and user-selectable through `connections use`; existing
+DSH sessions remain pinned as described below.
+
+Multi-connection add/use/remove is exposed only through the `/bailinghub connections` user
+command. It is never registered as a model tool. Selecting a connection changes registry defaults;
+existing states keep their captured bindings. Defaults affect connection management only;
+the host-owned scope API alone selects the conversation's authorization directory.
+Removing a connection is rejected while any run is active or has an unsynchronized completion. The SDK then
+revokes only that instance's remote Agent Session before removing its local credentials and
+registry metadata; a revoke failure preserves both. Repeating add with the same name and public
+binding selects the existing instance; reusing a name for different public metadata fails.
+`connectionName` remains a local user selector and never becomes a trusted identity claim.
+
+After a successful remove, the adapter reads the registry again. A valid remaining
+`currentConnectionKey` replaces all four public connection-management defaults, using the key itself
+when the profile has no alias; no remaining connection sets the adapter to unconfigured. A refresh
+failure does not change the successful remove result. It makes a removed default unavailable, but
+does not invalidate an unchanged non-current default. Existing session state is never rewritten.
+
+The four static adapter fields bootstrap SDK construction only. For connection management, the
+adapter reads `connectionsList()` and adopts the public
+metadata matching `currentConnectionKey`. Invalid, missing, or unavailable registry data leaves the
+bootstrap defaults in place and must not remove or block unrelated host tools. The lookup is not a
+model tool, and restoring or later selecting a default never mutates an already-created session.
+These registry bootstrap rules do not grant business scope, even to a new
+conversation. A failed scope load or selection never uses the bootstrap fields as a fallback.
 
 The completion request is restricted to:
 
 ```json
 {
   "assistant_message_id": "stable alias",
-  "content": "visible final text",
+  "content": "visible final text for one authorization, or that run's deterministic call summary for a multi-authorization scope",
   "status": "completed | failed | cancelled",
   "model": "optional",
   "runtime": "optional",
@@ -183,8 +490,8 @@ the first attempt and reused unchanged for up to three automatic attempts. A fai
 remains pending in its original run; `/bailinghub sync` starts another bounded attempt batch with
 that same id and payload.
 
-DSH `0.1.0-rc.7` reports disjoint camelCase buckets (`inputTokens`, `cacheReadTokens`, optional
-`cacheWriteTokens`, and `outputTokens`) on each durable `assistant/message`. The adapter sums them
+The verified DSH releases report disjoint camelCase buckets (`inputTokens`, `cacheReadTokens`,
+optional `cacheWriteTokens`, and `outputTokens`) on each durable `assistant/message`. The adapter sums them
 across model steps, exposes total input as Core `input_tokens`, cache reads as the
 `cached_input_tokens` subset, and derives `total_tokens` without adding `reasoningTokens` a second
 time. Unknown, non-finite, and negative metrics are discarded; only the Core public usage