@modelprofile.com/authswitch 8.2.0 → 9.1.0

package/readme.md

@@ -32,7 +32,23 @@ bindings, durable device-operation receipts, Codex enrollment records, and nativ
 owns OpenAI device login, targeted reauthentication, and proactive refresh for grants
 added through this API. Management snapshots expose separate account and login rows,
 including each login's purpose, owner, health, problem and available actions; neither
-snapshots nor events contain credentials.
+snapshots nor events contain credentials. A login that a native tool refreshes also names
+that tool -- `ownerTool` is `claude_code`, `codex` or `opencode`, and `null` exactly when no
+native tool holds it, because the authority refreshes it or nothing does. The authority
+names it rather than leaving a consumer to derive it from the purpose, which would be wrong
+as soon as two purposes share a tool or one tool gains a second purpose.
+The snapshot also lists `nativeAssignments`: which account a vendor tool's own home on this host runs on,
+as `{ id, tool, accountId, loginId, state, revision }` with the home named by its hash. Only homes the
+authority itself switches are recorded -- Claude Code homes adopted by a verified import -- and `state` is
+`switching` while a handoff to another account is in flight and `quarantined` until one is resolved. A
+Codex or OpenCode store that its own tool still refreshes appears as its login instead, with
+`owner: 'legacy_native'` and its `ownerTool`, because the authority does not decide what that store holds.
+Every change of an assignment is an account event, so a subscriber sees it like any other change.
+A removed account is left out of the snapshot unless the caller asks with `includeRemoved` (on `snapshot`,
+`snapshotAll` and `subscribe`): it then appears with `removed: true` and its logins with `health: 'removed'`.
+An account label follows one published rule, `isAuthSwitchAccountLabel` (at most
+`authSwitchAccountLabelMaxLength` characters, no space at either end, no control character); a rename that
+breaks it is refused with `invalid_input`.
 
 ```ts
 import { randomUUID } from 'node:crypto';
@@ -46,18 +62,30 @@ const operationId = randomUUID();
 const operation = await client.beginAddOpenAi(operationId);
 // Keep operation.id to discover its final result after navigation or reconnect.
 const receipt = await client.getOperation(operation.id);
+// Or follow it without polling: each answer comes when the operation changes.
+let current = operation;
+while (['starting', 'pending', 'committing'].includes(current.state)) {
+  current = await client.watchOperation(current.id, current.revision);
+}
 ```
 
 Browser code can import the credential-free DTOs from
 `@modelprofile.com/authswitch/authority-contract`. The backend-only binding, access and release
 requests are named by `@modelprofile.com/authswitch/authority-runtime-contract`, and the one-time
-import's own DTOs by `@modelprofile.com/authswitch/authority-import-contract`; the runtime contract
-belongs to the runtime socket and its capability must never reach a browser. A backend binds an
-account to a runtime incarnation by exact account ID, login ID and purpose, and keeps the returned
-capability private. Targeted reauthentication likewise requires the exact login; an
-account's presentation default never selects a grant for either action. Completed and
+import's own DTOs by `@modelprofile.com/authswitch/authority-import-contract`; those capabilities must
+never reach a browser. Two of the three runtime requests are served on the runtime socket -- resolving
+access and releasing a binding -- while `authswitch.authority.bind` is served on the **management** socket
+by design: minting a capability is the act that authorizes a runtime, so only a trusted management caller
+may perform it, and a container that is given the runtime directory can use a binding it was handed but can
+never create one. A backend binds an account to a runtime incarnation by exact account ID, login ID and
+purpose, and keeps the returned capability private. Targeted reauthentication likewise requires the
+exact login; an account's presentation default never selects a grant for either action. Completed and
 interrupted operations remain discoverable through `getOperation()` and paged
-`listOperations()`. A completed receipt and its account/grant change commit together, so
+`listOperations()`. `watchOperation(id, afterRevision, waitMs = 30000)` is the same read as a long poll,
+the way `events` waits: it answers as soon as the operation's revision passes `afterRevision` -- a sign-in
+answers `starting` with no prompt, then `pending` with its device prompt, then its outcome -- at once for a
+finished operation, and with the unchanged operation once `waitMs` (at most 30000) runs out. Only a change
+of that operation answers it. A completed receipt and its account/grant change commit together, so
 the receipt resolves a lost response or an event that arrives first. Add and reauthentication
 callers supply one UUID for the logical start and reuse it after a lost response. Replaying that
 UUID returns the same matching receipt without starting another provider login; using it for a
@@ -68,16 +96,29 @@ resolves that binding to a current access token; its directory can be mounted in
 container without exposing the management socket. A provider that rejects a specific
 access-token generation can request a newer one through `rejectedGrantGeneration`; the
 authority coalesces concurrent rejection callbacks and never replays an uncertain refresh.
-After an external Flex or OpenCode runtime has fenced new work and drained its pending access
-resolutions and provider requests, it can release its exact binding capability through the
-runtime socket. Every bind receives a fresh random capability, so a stale release cannot fence
+A ChatGPT login backs a Claude Code runtime too (`runtime: 'claude'`); a Claude account never binds,
+because it reaches Claude Code through the native switch. After an external Flex, OpenCode or Claude
+runtime has fenced new work and drained its pending access resolutions and provider requests, it can
+release its exact binding capability through the runtime socket. Every bind receives a fresh random capability, so a stale release cannot fence
 or delete a successor even if the caller reused an incarnation label. Release waits for admitted
 server-side resolution handlers, but handler completion does not prove response delivery and
 cannot retract an access token already received or in use; the runtime owner therefore owns that
 drain. Generic release cannot revoke a managed Codex binding, whose daemon-owned stop still closes
 the runtime and clears its durable run before internal revocation. Binding release never transfers
-or changes ownership of the account grant. External-binding recovery after an owner crash remains
-a prerequisite for the full account-mutation cutover.
+or changes ownership of the account grant. A holder that crashed and lost its capability recovers
+its binding without a new route: the snapshot (and `getBinding`) publishes each binding's runtime and
+scope, binding that runtime and scope again replaces the capability, and releasing the returned
+capability releases the binding. If binding again is refused because the account needs a new sign-in,
+reauthenticate it first.
+
+`getBinding(bindingId)` (`authswitch.authority.binding`) reads one binding by the id `bind` returned,
+credential-free, or `null` once the authority holds none by that id, so a backend checks its binding without
+reading the whole snapshot.
+
+Removing an account that still backs a Flex, OpenCode or Claude binding is refused with `account_busy`, naming
+those runtimes: their holder stops them and releases the bindings first, so a removal never strands a
+runtime whose next access would fail. Managed Codex bindings are the daemon's own; removal drains managed
+Codex as before and then takes them with the account.
 
 Every route on either socket answers in one of three ways: a result, a **refusal**, or a fault. A refusal
 is an answer -- the daemon completed its check, nothing was left half-done, and its message says what the
@@ -91,9 +132,29 @@ instruction for an owner.
 that marker: it answers `{ code, instruction }` for a refusal and `null` for a fault. The code is the
 closed `TAuthSwitchRefusalCode` set, which is what a client branches on without reading the text:
 `authority_closing`, `not_found`, `account_changed`, `account_busy`, `login_unavailable`,
-`native_owner_holds_login`, `claude_home_unregistered`, `claude_handoff_pending`,
-`claude_receipt_missing` and `import_refusal`. The instruction is authored for the owner and contains no
-path, credential or digest; only an importer refusal may name the process the owner has to stop.
+`binding_unauthorized`, `native_owner_holds_login`, `claude_home_unregistered`, `claude_handoff_pending`,
+`claude_receipt_missing`, `import_refusal`, `codex_unsupported`, `invalid_input`, `login_needs_reauth` and
+`access_not_fresh`, plus the two the legacy commands answer with on this side of
+the socket, `authority_holds_login` and `authority_unavailable` (see "The legacy fence" below). The
+instruction is authored for the owner and contains no path, credential or digest; only an importer refusal
+may name the process the owner has to stop. The set is producer-owned: a consumer branches on the codes it
+knows and keeps a default branch, which is what lets the authority name a new one without breaking it.
+
+The runtime's own answers are named the same way. `authswitch.authority.bind` refuses `login_unavailable`
+when the authority does not hold the login itself, and `authswitch.authority.resolveAccess` refuses
+`binding_unauthorized` for a capability that authorizes nothing -- missing, wrong, or superseded while the
+credential was being resolved. Those are one answer on purpose: an absent binding and a wrong capability are
+compared against the same zero hash, so nothing distinguishes them, and the repair is the same either way --
+bind again. A binding whose account has since been reauthorized reads `login_unavailable` instead, because
+binding again cannot help until that account holds a login again. A device sign-in or preuse operation this
+authority does not hold reads `not_found`, from whichever route met it. What the access loop decides about
+the login itself is marked as well: `login_needs_reauth` when only a new device sign-in brings the login back
+(after which a bound runtime binds again), and `access_not_fresh` when the login is intact but the provider
+could not renew its access yet, so the same request can succeed later. A changed identity or a view that
+keeps moving during resolution stays an unmarked fault, because nobody decided it. Binding an *account* this
+authority does not hold at all stays one too: the storage layer throws `Account is not available for this runtime.`,
+which a socket caller reads as `Internal server error`, because naming it is a decision about which layer
+authors owner instructions rather than a wording fix.
 
 The import routes keep the marker they published in 8.1.0, `authswitch_import_refusal`, and
 `isAuthSwitchImportRefusal` from `@modelprofile.com/authswitch/authority-import-contract` is the same
@@ -104,6 +165,15 @@ and the ledger row it wrote says where that source stands -- while an unmarked f
 unknown, and that source must then be read with `authswitch.authority.import.status` rather than
 submitted again.
 
+A daemon that is shutting down admits no new request -- every route answers `authority_closing` -- and
+settles the requests it already admitted before it closes its store: a waiting `events` or
+`watchOperation` read answers normally from the open store instead of failing.
+
+A client reading a daemon that runs an older release -- one not restarted after an upgrade -- fails with
+`AuthSwitchDaemonOutdatedError`, which names the restart (`authswitch authority service stop`, then
+`start`), and a subscription reports `unavailable` with the reason `daemon_outdated` once and retries every
+five seconds until the daemon is restarted.
+
 `AuthSwitchClient.subscribe(onSnapshot, onEvent, signal, { onStatus })` reports `current`
 after a fresh snapshot or verified heartbeat, `unavailable` on disconnect or resync, and
 `closed` on abort. Keep cached account actions disabled while status is not `current`.
@@ -259,11 +329,19 @@ native harness process or Codex's app-server is running, and an app-server it ca
 An adopt whose refresh fails, or whose answer is lost, is never retried: the source is quarantined, its grant
 is left needing re-authentication, and the command says so. A projection fails differently, because nothing
 rotating was ever sent for it: a native store that could not be proven live stays a pending native owner and
-is imported by submitting the same source again once its own tool has refreshed it.
+is imported by submitting the same source again once its own tool has refreshed it. That refresh rewrites the
+file, so the retry carries the digest the inventory prints afterwards: a row waiting for its native owner
+follows its own tool's bytes, and nothing else does. What it never follows is another login. A row names the
+account and the grant it was approved for, and a source that now holds a different account's login is refused
+with that stated -- before the account is registered, because the provider read that proves a projection asks
+about the identity the new bytes themselves carry and would prove the wrong login perfectly well. Neither
+that refusal nor "already imported" ever clears: no route forgets a row or re-points it at another account.
 
 `import status` reads the migration ledger, the grants and the handoffs -- never the host -- and reports, per
 source, where it stands, which owner refreshes its login now, and what to do next: nothing, submit the same
-source again, or sign in to that account again. Submitting a source again is how an interrupted run resumes,
+source again, or sign in to that account again. Each entry also carries the source's `sourcePathHash`, so a
+backend that submitted an external source finds its own record by `sourceKind` and that hash -- also after a
+submit whose outcome it never learned -- without deriving the ledger row id. Submitting a source again is how an interrupted run resumes,
 and the answer comes from the same durable record the daemon decides on: a source whose sign-in was in
 flight when the run died is reported as needing a device sign-in, not as resumable, because a rotating
 refresh token is never sent a second time. Sources that were never submitted have no ledger row and appear
@@ -273,6 +351,17 @@ An import deletes nothing: retiring the legacy files is a separate, later step.
 deliberately not backed up, so losing it costs one device sign-in per account -- and the remote-control
 enrollments and runtime bindings with it.
 
+**Where a daemon reads those stores is stated by whoever builds it, never defaulted.** The legacy stores are
+this user's real credentials, and every location they are found at comes from the environment, so
+`AuthSwitchAuthorityDaemon` takes a required `legacyImport`: either the locations to read (an `env` and an
+absolute `homeDirectory`, plus the provider operations that import uses) or `'none'`, which builds a daemon
+with no account import at all and answers `import inventory`, `import status` and `import submit` with the
+`import_refusal` code -- a decided refusal of the closed set, never an empty inventory and never a fault, so
+a caller reads it exactly as it reads every other import refusal. A construction that names neither -- no
+locations and no `'none'` -- is refused before the daemon exists, rather than reading whichever host happened
+to start it. The per-user daemon this package installs -- `authswitch authority daemon`, the service unit's
+own entry point -- is the one place that takes those locations from this host.
+
 `AuthSwitchClient.getUsage(accountId, loginId)` reads OpenAI managed limits or a Claude
 host login's profile and usage through the management socket. The tagged, credential-free
 reading preserves Claude's labelled five-hour, weekly and model windows, plan provenance,
@@ -298,7 +387,7 @@ generated prose and credentials are absent from persistence and management respo
 removal and targeted reauthentication refuse while that account has an active preuse request.
 
 A trusted in-process daemon host can call `AuthSwitchAuthorityDaemon.startManagedCodex()`
-for a bound account and workspace. It owns a private Codex 0.155.1 app-server, passes only
+for a bound account and workspace. It owns a private Codex app-server, passes only
 the authority's current access token through Codex's external-token login, answers its
 unauthorized callback through the authority, and revokes the binding on stop. The returned
 runtime exposes an interactive `codex --remote unix://…` launch descriptor and native
@@ -314,15 +403,37 @@ gone; an uncertain launch remains blocked. Callers must explicitly stop owned pr
 after their work finishes. Once reauthentication starts, it holds new admissions until the
 device operation settles. Only the private socket directory is removed on close. Codex's
 credential store remains ephemeral and does not read or write `auth.json` in that home.
+Codex binds the app-server socket in its own per-user directory,
+`<realpath /tmp>/codex-daemon-<euid>`, and publishes the private socket path as a link to it.
+The daemon checks that publication with `@modelprofile.com/mcp-crossharness`'s
+`observeCodexUnixSocket` and connects only when the link is exactly Codex's own, in a
+directory other users cannot rewrite, and the socket behind it is the user's own in a 0700
+directory of the user's; anything else fails the start with that package's error. Codex keeps a
+zero-byte startup lock in that directory for each socket path it has served; the file is
+Codex's own and authswitch does not remove it.
+Managed Codex runs Codex 0.156.0 or newer -- the floor `@modelprofile.com/mcp-crossharness`'s
+`requireCodexVersion` checks, the first release that publishes the socket alias -- and checks the
+contract at every start instead of pinning one release. Before anything is recorded or started, the
+`codex` it will run must report a readable version at or above the floor, and its own protocol
+description (`codex app-server generate-json-schema`) must still offer every surface managed Codex uses:
+the requests `account/login/start`, `thread/start`, `thread/resume` and `turn/start`; the external
+ChatGPT token login with the fields it sends; the `account/chatgptAuthTokens/refresh` callback with the
+`unauthorized` reason and the reply it gives; and the thread and turn parameters it sends. After
+connecting, the app-server must report exactly the version that was checked, because Codex can replace
+itself between the check and the start. Each failure is the `codex_unsupported` refusal naming the
+version or the missing surface, so a Codex update that drops something managed Codex relies on stops new
+managed sessions by name instead of failing one later. A prerelease above the floor runs; a prerelease of
+0.156.0 itself is below it.
 Managed-Codex process ownership observation is qualified on Linux and reads exact argument
 boundaries from `/proc`; on other hosts doctor reports the process observation as unknown,
 and authority actions that require survivor proof refuse instead of guessing.
-Codex 0.155.1 does not persist an unused thread created by `thread/start`; resume applies
+Codex (verified through 0.157) does not persist an unused thread created by `thread/start`; resume applies
 after Codex has committed a rollout. The existing CLI has not yet been moved to this path.
 
 This SDK is additive at this stage. The commands documented below still use the existing
-credential stores. The authority daemon does not import those stores automatically,
-replace their active native sessions, or take over their refresh grants. An active
+credential stores, except that the legacy fence below refuses them a login the authority
+holds. The authority daemon does not import those stores automatically, replace their
+active native sessions, or take over their refresh grants. An active
 Codex/OpenCode native grant remains pending until its owner is idle and an explicit
 handoff verifies the latest native source. Claude Code's own native credential files
 remain vendor-owned; a container setup-token grant is a separate grant under the same
@@ -353,6 +464,62 @@ restore system could have written.
 The store is deliberately not backed up: its refresh grants are sealed to this host's TPM,
 so a lost store is recovered by one device re-login per account.
 
+### The legacy fence
+
+Once the authority has taken a saved copy over, the legacy `save` and `switch` must not write it again: an
+adopted copy's refresh token was rotated away by the import, and activating it would hand a tool a dead
+login. `runAuthSwitchMutation` -- the one path the command line, the guide, `watch` and the hosted
+`AuthSwitchService` all take -- asks first, and decides in three branches.
+
+- **The authority answers**: it is asked for this record's ledger row through `import status` on the
+  management socket, keyed by the same source id the importer uses (a hash of the saved copy's path). A
+  `verified` or `complete` row refuses with `authority_holds_login`; any other row, or none, lets the command
+  run. An authority that answers decides, whether or not its service unit is installed.
+- **Nothing answers within four seconds -- no socket, a silent one, or no `XDG_RUNTIME_DIR` -- and the
+  authority's service unit is installed**: the command refuses with `authority_unavailable` and the
+  instruction to run `authswitch authority service start`. Unknown is never treated as idle.
+- **Nothing answers and no unit is installed**: the legacy commands behave exactly as before. This is every
+  host before the cutover.
+
+What tells the second branch from the third is durable, never the socket: the runtime directory is tmpfs,
+so after a reboot the socket is absent until the user service starts -- exactly when a fence keyed on it
+would open. The evidence is the unit `authswitch authority service install` writes,
+`$XDG_DATA_HOME/systemd/user/authswitch-authority.service` (default
+`~/.local/share/systemd/user/authswitch-authority.service`), read through smartdaemon's
+`SystemdUnitFile.inspect()`. The installer and the fence derive that directory from one rule,
+`$XDG_DATA_HOME` or else the home directory; the installer takes both from its own process and its account's
+home, the fence from the locations its caller states. The two agree unless `$HOME` is overridden while
+`XDG_DATA_HOME` is unset, and then every store the fence guards lies under that overridden home too. The fence
+writes nothing and keeps no record of its own.
+
+The check works without a login session. Reading the unit needs only its directory, so a cron job or a plain
+ssh command with no `XDG_RUNTIME_DIR` is decided by the unit exactly like a desktop session: no unit, the
+legacy commands run; the unit installed, they refuse with `authority_unavailable`. The stated
+`XDG_RUNTIME_DIR` names only the socket to ask; an absent one is never replaced by this process's own. The
+answer depends on the unit directory derived from the stated `XDG_DATA_HOME` or home, and on nothing else:
+a malformed `XDG_RUNTIME_DIR` or `XDG_CONFIG_HOME` never refuses the command, and neither does a malformed
+process `XDG_DATA_HOME` when the caller states other locations. A unit that cannot be inspected -- a file the
+installer would not have written, a directory another user can write -- refuses rather than being read as
+absent, and so does a stated `XDG_DATA_HOME` that names no usable unit directory, because the reader can
+then tell an installed authority from none no better. On a platform without systemd no unit can be
+installed.
+
+The unit says an authority exists, not which stores it imports from, so while an installed authority is
+stopped the legacy save and switch refuse for every saved copy of every store, until it runs again. A
+record the importer could never have read -- an account id that names no saved-copy file -- is never asked
+about.
+
+`drop` / `rm` and the `remove` mutation are deliberately not fenced: they delete the user's own saved copy
+and write no credential. A projected source is never fenced either -- its native store stays with its own
+tool. The command line takes this host's locations only when it composes its own harnesses, and with
+injected harnesses is fenced only by locations its caller states; `AuthSwitchOperations`,
+`runAuthSwitchMutation` and an `AuthSwitchService` given its harnesses take the locations as a required
+argument (`authSwitchHostLegacyFence()` names this host's, `'none'` states that a
+caller owns no authority), so no library path reads a host it was not given. `AuthSwitchOperations` and the
+hosted service ask the fence before their AGL coordinator as well, so a refused mutation never has its host
+stop the runtimes it would restart. The hosted service reports a fence refusal as the operation's problem, in
+the instruction's own words.
+
 ## Usage
 
 Run `authswitch`, `authswitch -i`, or `authswitch --interactive` for an interactive guide. Use the arrow keys and
@@ -515,9 +682,12 @@ login. `activateCredential(providerId, credential)` preserves and verifies the
 outgoing native login before activation; the caller retains ownership of the
 incoming credential's durable storage. Both are backend APIs, never wire payloads.
 
-`AuthSwitchOperations` is shared by the command, guide and TUI. Its optional
-coordinator receives only the harness, operation, account ID, consent to wait,
-and a credential-location fingerprint. AGL owns private-controller discovery;
+`AuthSwitchOperations` is shared by the command, guide and TUI, and is built
+with a coordinator (or `undefined`) and the legacy fence locations described in
+"The legacy fence". A host that injects its own harnesses into `AuthSwitchService`
+states that fence as the third argument. The coordinator receives only the
+harness, operation, account ID, consent to wait, and a credential-location
+fingerprint. AGL owns private-controller discovery;
 authswitch uses `agl authswitch --request <json>` without an AGL package dependency.
 A failed or ambiguous transport never falls through to a second local mutation.
 AGL and the CLI must use matching credential locations and compatible versions.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/authswitch',
-  version: '8.2.0',
+  version: '9.1.0',
   description: 'Manage Codex, OpenCode and Claude Code accounts with guided switching and live usage status'
 }

package/ts/authority-contract.ts

@@ -15,11 +15,25 @@ export type TAuthSwitchRefusalCode =
   | 'account_changed'
   | 'account_busy'
   | 'login_unavailable'
+  /** A runtime capability that is missing, wrong or superseded: deliberately one answer, and one repair. */
+  | 'binding_unauthorized'
+  /** The authority holds this login, so the legacy path that used to move it no longer may. */
+  | 'authority_holds_login'
+  /** An authority is installed on this host and is not answering, so nothing may assume it holds nothing. */
+  | 'authority_unavailable'
   | 'native_owner_holds_login'
   | 'claude_home_unregistered'
   | 'claude_handoff_pending'
   | 'claude_receipt_missing'
-  | 'import_refusal';
+  | 'import_refusal'
+  /** The Codex on this host is older than managed Codex runs, or no longer offers a surface it uses. */
+  | 'codex_unsupported'
+  /** A value the owner typed breaks a rule the instruction states, such as an account label. */
+  | 'invalid_input'
+  /** The account's login has ended and only a new device sign-in brings it back. */
+  | 'login_needs_reauth'
+  /** The login is intact, but the provider could not renew its access yet; the same request can succeed later. */
+  | 'access_not_fresh';
 
 /** The marker the importer has published since 8.1.0; it keeps its own value on the wire. */
 export const authSwitchImportRefusalMarker = 'authswitch_import_refusal';
@@ -42,8 +56,10 @@ export interface IAuthSwitchRefusal {
 
 const refusalCodes: ReadonlySet<string> = new Set<TAuthSwitchRefusalCode>([
   'authority_closing', 'not_found', 'account_changed', 'account_busy',
-  'login_unavailable', 'native_owner_holds_login', 'claude_home_unregistered',
+  'login_unavailable', 'binding_unauthorized', 'native_owner_holds_login', 'claude_home_unregistered',
   'claude_handoff_pending', 'claude_receipt_missing', 'import_refusal',
+  'authority_holds_login', 'authority_unavailable', 'codex_unsupported', 'invalid_input',
+  'login_needs_reauth', 'access_not_fresh',
 ]);
 
 const isRefusalCode = (value: unknown): value is TAuthSwitchRefusalCode =>
@@ -95,6 +111,18 @@ export const asAuthSwitchRefusal = (error: unknown): IAuthSwitchRefusal | null =
   return { code, instruction };
 };
 
+/** The longest account label, in UTF-16 code units. */
+export const authSwitchAccountLabelMaxLength = 128;
+
+/**
+ * The account label rule, the one the authority applies to a rename: one to `authSwitchAccountLabelMaxLength`
+ * characters, no space at either end, no control character. A consumer validates with this rather than
+ * restating it; the authority answers a label that breaks it with the `invalid_input` refusal.
+ */
+export const isAuthSwitchAccountLabel = (value: unknown): value is string => typeof value === 'string'
+  && value.trim() === value && value.length > 0 && value.length <= authSwitchAccountLabelMaxLength
+  && !/[\u0000-\u001f\u007f]/.test(value);
+
 /** Credential-free account management contract. Safe to import in browser code. */
 export type TAuthSwitchLoginPurpose = 'openai_managed' | 'claude_host_native' | 'claude_container_setup' | 'opencode_native';
 export type TAuthSwitchLoginHealth = 'ready' | 'refreshing' | 'retry_wait' | 'needs_reauth' | 'unverified' | 'pending_handoff' | 'handoff_quarantined' | 'removed';
@@ -110,6 +138,16 @@ export interface IAuthSwitchAccount {
   statusObservedAt: string;
 }
 
+/**
+ * Which tool refreshes a natively owned login, named rather than inferred.
+ *
+ * `owner` says that a native tool holds the login; this says which one, so a consumer presents "Claude Code"
+ * or "Codex" without deriving it from `purpose` -- a derivation that would be wrong the moment two purposes
+ * share a tool, and that belongs to the side that decides ownership in the first place. It is `null` exactly
+ * when no native tool refreshes the login: the authority does, or nothing does.
+ */
+export type TAuthSwitchLoginOwnerTool = 'claude_code' | 'codex' | 'opencode';
+
 /** One independently owned login. Native ownership does not imply observed health. */
 export interface IAuthSwitchLogin {
   id: string;
@@ -117,6 +155,8 @@ export interface IAuthSwitchLogin {
   providerId: string;
   purpose: TAuthSwitchLoginPurpose;
   owner: 'daemon' | 'claude_native' | 'legacy_native' | 'none';
+  /** The native tool that refreshes this login, or null when the authority or nobody does. */
+  ownerTool: TAuthSwitchLoginOwnerTool | null;
   health: TAuthSwitchLoginHealth;
   problem: 'none' | 'provider_unavailable' | 'exchange_uncertain' | 'provider_rejected' | 'native_owner';
   grantGeneration: number;
@@ -130,12 +170,35 @@ export interface IAuthSwitchLogin {
 export interface IAuthSwitchBinding {
   id: string;
   accountId: string;
+  /**
+   * The runtime an OpenAI (ChatGPT) login backs. `flex`, `opencode` and `claude` bindings are held and
+   * released by their caller over the runtime socket; `codex` is the daemon's own managed Codex. A Claude
+   * account never binds: it reaches Claude Code through the native switch.
+   */
   runtime: 'flex' | 'codex' | 'opencode' | 'claude';
   scopeId: string;
   incarnationId: string;
   revision: number;
 }
 
+/**
+ * Which account a vendor tool's own home on this host runs on. Credential-free: the home is named by the
+ * hash the authority registered it under, never by its path.
+ *
+ * Only homes the authority itself switches are recorded: Claude Code homes adopted by a verified import.
+ * A Codex or OpenCode store that a native tool still refreshes appears as its login instead, with
+ * `owner: 'legacy_native'` and its `ownerTool`, because the authority does not decide what that store holds.
+ */
+export interface IAuthSwitchNativeAssignment {
+  id: string;
+  tool: TAuthSwitchLoginOwnerTool;
+  accountId: string;
+  loginId: string;
+  /** `switching` while a handoff to another account is in flight; `quarantined` until it is resolved. */
+  state: 'ready' | 'switching' | 'quarantined';
+  revision: number;
+}
+
 export interface IAuthSwitchSnapshot {
   schemaVersion: 2;
   epoch: string;
@@ -144,9 +207,11 @@ export interface IAuthSwitchSnapshot {
   accounts: IAuthSwitchAccount[];
   logins: IAuthSwitchLogin[];
   bindings: IAuthSwitchBinding[];
+  nativeAssignments: IAuthSwitchNativeAssignment[];
   nextAccountCursor: string | null;
   nextLoginCursor: string | null;
   nextBindingCursor: string | null;
+  nextNativeAssignmentCursor: string | null;
 }
 
 /** Persisted account evidence. No provider request is made while collecting diagnostics. */
@@ -372,7 +437,13 @@ export interface IReq_AuthSwitchClaudeNativeHandoffs extends ITypedRequest {
 
 export interface IReq_AuthSwitchSnapshot extends ITypedRequest {
   method: 'authswitch.authority.snapshot';
-  request: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; limit?: number };
+  request: { accountAfter?: string; loginAfter?: string; bindingAfter?: string; nativeAssignmentAfter?: string;
+    limit?: number;
+    /**
+     * Also publish removed accounts (`removed: true`) and their removed logins (`health: 'removed'`), so a
+     * consumer can show them apart. Absent or false keeps the snapshot to what is live.
+     */
+    includeRemoved?: boolean };
   response: { snapshot: IAuthSwitchSnapshot };
 }
 
@@ -422,9 +493,14 @@ export interface IReq_AuthSwitchListOperations extends ITypedRequest {
   response: { operations: IAuthSwitchOperation[]; nextCursor: string | null };
 }
 
+/**
+ * One device sign-in. `afterRevision` and `waitMs` come together or not at all: with them the read is a long
+ * poll that answers once the operation's revision passes `afterRevision`, at once for a finished sign-in, or
+ * with the unchanged operation after `waitMs` (at most 30000).
+ */
 export interface IReq_AuthSwitchGetOperation extends ITypedRequest {
   method: 'authswitch.authority.operation';
-  request: { operationId: string };
+  request: { operationId: string; afterRevision?: number; waitMs?: number };
   response: { operation: IAuthSwitchOperation };
 }
 
@@ -459,6 +535,16 @@ export interface IReq_AuthSwitchRenameAccount extends ITypedRequest {
   response: { account: IAuthSwitchAccount };
 }
 
+/**
+ * One binding by the id `bind` returned, credential-free, or `null` when this authority holds no binding by
+ * that id. A backend checks that its binding still stands without reading the whole snapshot.
+ */
+export interface IReq_AuthSwitchGetBinding extends ITypedRequest {
+  method: 'authswitch.authority.binding';
+  request: { bindingId: string };
+  response: { binding: IAuthSwitchBinding | null };
+}
+
 export interface IReq_AuthSwitchRemoveAccount extends ITypedRequest {
   method: 'authswitch.authority.remove';
   request: { accountId: string; expectedRevision: number };

package/ts/authority-import-contract.ts

@@ -173,6 +173,12 @@ export const isAuthSwitchImportRefusal = (error: unknown): boolean =>
 export interface IAuthSwitchImportStatusEntry {
   sourceId: string;
   sourceKind: TAuthSwitchImportSourceKind;
+  /**
+   * The source location as a hash, exactly as it was submitted or inventoried. A backend that submits an
+   * external source finds its own record here by `sourceKind` and this hash, including after a submit whose
+   * outcome it never learned.
+   */
+  sourcePathHash: string;
   status: TAuthSwitchImportLedgerStatus;
   accountId: string | null;
   loginId: string | null;

package/ts/authority-paths.ts

@@ -0,0 +1,69 @@
+import * as plugins from './plugins.js';
+
+/**
+ * Where this user's authority lives: its sockets, its store and the service unit that runs it.
+ *
+ * These rules sit in a leaf module because two sides read them. `AuthSwitchAuthorityService` installs and
+ * runs the daemon there, and the legacy fence (`./classes.legacyfence`) asks the same socket and looks for
+ * the same unit -- without importing the daemon, whose module graph reaches back to the legacy operations
+ * the fence guards.
+ */
+
+export interface IAuthSwitchAuthorityPaths {
+  runtimeDirectory: string;
+  dataDirectory: string;
+  databaseSocketPath: string;
+  authoritySocketPath: string;
+  runtimeSocketPath: string;
+  runtimeSocketDirectory: string;
+}
+
+/** The authority's sockets. */
+export type TAuthSwitchAuthoritySocketPaths = Omit<IAuthSwitchAuthorityPaths, 'dataDirectory'>;
+
+/**
+ * The sockets under one runtime directory, derived from it alone.
+ *
+ * The legacy fence asks the socket a caller states and must not depend on anything this process holds --
+ * its home or its `XDG_DATA_HOME`, which only the store's directory needs.
+ */
+export const authSwitchAuthoritySocketPaths = (
+  runtimeDirectory: string | undefined): TAuthSwitchAuthoritySocketPaths => {
+  if (!runtimeDirectory || !plugins.path.isAbsolute(runtimeDirectory)) {
+    throw new Error('A private XDG_RUNTIME_DIR is required for authswitch authority.');
+  }
+  const socketDirectory = plugins.path.join(runtimeDirectory, 'authswitch');
+  const runtimeSocketDirectory = plugins.path.join(socketDirectory, 'runtime');
+  return {
+    runtimeDirectory,
+    databaseSocketPath: plugins.path.join(socketDirectory, 'internal', 'db.sock'),
+    authoritySocketPath: plugins.path.join(socketDirectory, 'management', 'authority.sock'),
+    runtimeSocketPath: plugins.path.join(runtimeSocketDirectory, 'runtime.sock'),
+    runtimeSocketDirectory,
+  };
+};
+
+/** Canonical per-user paths. An explicit runtime directory is also usable by a trusted container host. */
+export const resolveAuthSwitchAuthorityPaths = (runtimeDirectory = process.env.XDG_RUNTIME_DIR): IAuthSwitchAuthorityPaths => {
+  const sockets = authSwitchAuthoritySocketPaths(runtimeDirectory);
+  const home = plugins.os.userInfo().homedir;
+  const dataHome = process.env.XDG_DATA_HOME || plugins.path.join(home, '.local/share');
+  if (!plugins.path.isAbsolute(dataHome)) throw new Error('XDG_DATA_HOME must be an absolute path.');
+  return { ...sockets, dataDirectory: plugins.path.join(dataHome, 'authswitch', 'authority') };
+};
+
+/** The user service `authswitch authority service install` writes. */
+export const authSwitchAuthorityUnitName = 'authswitch-authority.service';
+
+/**
+ * The directory that unit is installed into, from a stated environment and home directory.
+ *
+ * It is the rule smartdaemon applies to a user unit when it is given no directory --
+ * `$XDG_DATA_HOME/systemd/user`, default `~/.local/share/systemd/user` -- stated here so the installer passes
+ * it explicitly and the fence derives it from the locations its caller states rather than from this process.
+ */
+export const authSwitchAuthorityUnitDirectory = (env: NodeJS.ProcessEnv, homeDirectory: string): string => {
+  const dataHome = env.XDG_DATA_HOME || plugins.path.join(homeDirectory, '.local/share');
+  if (!plugins.path.isAbsolute(dataHome)) throw new Error('XDG_DATA_HOME must be an absolute path.');
+  return plugins.path.join(dataHome, 'systemd/user');
+};

package/ts/authority-runtime-contract.ts

@@ -1,7 +1,17 @@
 import type { ITypedRequest } from '@api.global/typedrequest-interfaces';
 import type { IAuthSwitchBinding } from './authority-contract.js';
 
-/** Backend-only binding operation. The capability must never enter a browser-facing response. */
+/**
+ * Backend-only binding operation, served on the MANAGEMENT socket. Not a misplacement -- the rule.
+ *
+ * The other two requests in this file are answered on the runtime socket, whose directory a container may
+ * be given. This one is not, because it mints the capability those two spend: minting is the act that
+ * authorizes a runtime, so it belongs to a caller already trusted with account management. A container
+ * holding the runtime directory can therefore use the binding it was handed, and can never create one --
+ * not for itself, and not for another account.
+ *
+ * The capability must never enter a browser-facing response.
+ */
 export interface IReq_AuthSwitchBindAccount extends ITypedRequest {
   method: 'authswitch.authority.bind';
   request: {