dsh-keys-manager 0.2.1 → 0.2.2

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-import type { AccountAttemptView, StateView } from './domain.js';
+import type { AccountAttemptView, KeyTestResult, StateView } from './domain.js';
 import type { CredentialsLike, GenerateOptionsLike, HostContext, KeySelection, RequestErrorAction, AgentRequestPayload, RequestErrorPayload, SettingsLike, StreamChunkLike } from './host-types.js';
 import { KeysManagerStore } from './store.js';
 export declare const name = "keys-manager";
@@ -6,6 +6,15 @@ export declare const inject: string[];
 export declare const provide: string[];
 /** The credential-record scope pi-ai stores its per-provider grants under (llm-pi-ai/src/auth.ts:29). */
 export declare const OAUTH_GRANT_RECORD_SCOPE = "llm-pi-ai";
+/**
+ * The credential-record scope the llm-omp transports package owns: one
+ * `llm-omp-transports/<route>` grant per transport route (its
+ * `CURSOR_CREDENTIAL_KEY` is `llm-omp-transports/cursor`). Keys Manager reads
+ * those records to list/verify an account and deletes one on removal; it
+ * never writes one and never projects one into `llm-pi-ai/<provider>`, so a
+ * transport route keeps serving from its own adapter-owned credential.
+ */
+export declare const TRANSPORT_CREDENTIAL_SCOPE = "llm-omp-transports";
 /**
  * Stable failure code for a harvest whose state flush rejected AND whose
  * credential-side rollback then failed to write.
@@ -46,17 +55,147 @@ export declare class KeysManagerService {
     private readonly credentialWrappers;
     private brokerOwners;
     private readonly bindingCache;
+    /**
+     * Providers whose managed credentials are being removed right now. While a
+     * provider is unmanaged only the unbind direction of
+     * {@link syncBrokerBinding} may run: a demotion inside the deletion loop
+     * (an `oauth` row iterated before a surviving `api-key` row) must never
+     * re-point the released profile at the broker.
+     */
+    private readonly releasingProviders;
     private lastBindingPruneAt;
     private readonly selectionQueues;
     private queue;
     private closing;
+    /** The one shutdown this manager runs; a later close() joins it (round 38). */
+    private closePromise;
+    /**
+     * The pre-close restoration is running (PR review round 37). Only inside it
+     * — set when {@link restoreBorrowedWindows} starts and cleared in its
+     * `finally`, the cleanup deadline included — does the module-private
+     * {@link PRE_CLOSE_RESTORE} capability let a write past shutdown. A
+     * restoration that outlives its deadline resumes after this went down and
+     * is refused like any other continuation.
+     */
+    private preCloseRestorePhase;
+    /**
+     * Shutdown has begun (PR review round 34). Set on `close()`'s first line,
+     * before the pre-close restoration runs, so a test arriving while that
+     * restoration is putting the outstanding borrows back is refused instead of
+     * starting a second window the restoration would not cover. Never cleared:
+     * the instance is closing.
+     */
+    private shutdownRequested;
+    /**
+     * Providers whose in-flight row test borrows the route's credential
+     * surface (QC B4: an OAuth row test's projection, and the broker reference
+     * it may temporarily release). While a provider is borrowed the binding
+     * authority must not derive a real binding from the borrowed world: a
+     * mutation landing inside the window (`addKey`, `deleteKey`, an account
+     * removal) would otherwise persist an unbind decided about a state that is
+     * not the route's. {@link syncBrokerBinding} consults this exactly like
+     * {@link releasingProviders}; the test's own window-end sync passes
+     * `borrow: true` so the restored state is written back in one step.
+     */
+    private readonly testBindingBorrows;
+    /**
+     * Providers with a borrowing row test in flight, mapped to that test's own
+     * promise. The promise is the isolation seam: an ordinary request for the
+     * provider waits on it (bounded, see {@link settleProviderTest}) before
+     * resolving a credential, and reports its own outcome if the test fails.
+     * Only OAuth-row tests borrow (QC N7), so only they register here.
+     */
+    private readonly testsInFlight;
+    /**
+     * Every in-flight row test, by provider — the single-concurrent-test lock
+     * for both row kinds. Separate from {@link testsInFlight} because an
+     * api-key test borrows nothing and must not isolate ordinary requests.
+     */
+    private readonly testsActive;
+    /**
+     * Every row test window that has not been released yet, by provider (PR
+     * review round 33). Shutdown restores each window's borrowed projection
+     * before `closing` refuses the in-window cleanup, so the map outlives
+     * {@link testsActive} for a window whose request never settles.
+     */
+    private readonly testWindows;
+    /**
+     * Upper bound on one ordinary request's wait for an in-flight row test
+     * (QC B3). Injectable so tests can exercise the bound quickly.
+     */
+    private isolationWaitMs;
+    /**
+     * Providers whose abandoned test window is still being cleaned up (QC fix
+     * wave 2). The fence stays until a cleanup completed: a new test would
+     * borrow a projection that is not back yet, and an ordinary request must not
+     * be served by a borrowed grant or an unbound route.
+     */
+    private readonly cleaningTests;
+    /**
+     * Nesting depth of an in-flight removal per provider (PR review round 12).
+     * {@link settleTestBeforeRemoval} can only wait for a test that already
+     * exists, so a test starting after that check would read the grant and the
+     * projection and then re-project an account the removal deleted. {@link
+     * testKey} refuses while this marker is up. A depth, because `deleteKey`
+     * releases through `releaseLocked` inside its own removal.
+     */
+    private readonly removalsInProgress;
+    /**
+     * Generation of the newest cleanup attempt per provider (PR review round 2).
+     * An attempt that outlives its deadline keeps writing while a later attempt
+     * for the same window starts. Only the newest generation may release
+     * provider-wide state — the fence, the borrow marker, the in-flight maps —
+     * so a superseded attempt can never clear isolation a newer window owns.
+     */
+    private readonly cleanupAttempts;
+    /**
+     * The abandoned window currently fencing each provider (QC fix wave 3,
+     * W-002), so a later test attempt can retry its cleanup. Without this the
+     * fence could only ever clear from the abandoned promise's settlement, and a
+     * promise that settled while the seam was still wedged left the provider
+     * isolated forever.
+     */
+    private readonly abandonedWindows;
+    /** Hard bound on one abandoned window's cleanup. Injectable for tests. */
+    private testCleanupDeadlineMs;
+    /** Hard bound on the shutdown drain of the grant chains. Injectable for tests. */
+    private grantDrainDeadlineMs;
+    /** Providers whose isolation-deadline warning already fired (warn once). */
+    private readonly isolationWaitWarned;
     /** Interactive sign-in attempts, by attempt id. */
     private readonly loginAttempts;
     /** The provider → attempt id index for the single-attempt rule. */
     private readonly loginsInFlight;
     private loginSequence;
+    /** The route → attempt id index for the single transport sign-in rule. */
+    private readonly transportInFlight;
+    /**
+     * Per-route removal epoch. A removal bumps it before withdrawing the live
+     * attempt, so that attempt's settle path can tell the account is gone and
+     * drop a grant its commit had already started writing.
+     */
+    private readonly transportRemovals;
+    /**
+     * Transport-account rows, hydrated from the `llm-omp-transports/<route>`
+     * records. Kept out of the pi-ai pool document on purpose: the rows are a
+     * read-only projection of another package's records, rebuilt by
+     * {@link refreshTransportAccounts} and rendered by `buildState`.
+     */
+    private transportRows;
+    /** Tail of the serialized transport read chain. */
+    private transportRefresh;
     /** The account row whose grant payload currently IS the projection, per provider. */
     private readonly activeAccounts;
+    /**
+     * Providers whose live projection EXISTS but no managed row owns it (PR
+     * review round 3). `activeAccounts` alone cannot tell "no projection" from
+     * "a projection this process does not manage": an orphan or foreign grant
+     * (hydration found no matching row) still serves ahead of any broker
+     * reference, so the route must not be treated as the key pool's. Set by
+     * hydration and by the reconciler when a record is present but unattributed,
+     * cleared when the record is deleted or becomes owned.
+     */
+    private readonly foreignProjections;
     /**
      * Account rows committed to removal (C6-1/I1 removal-aware oracle), marked
      * by {@link removeOAuthGrant} before its first awaited delete. A multi-row
@@ -157,6 +296,16 @@ export declare class KeysManagerService {
      * to the requested provider's own unresolved read.
      */
     private readonly hydratedProviders;
+    /**
+     * Providers whose hydration ownership read FAILED (PR review round 8). A
+     * failed read knows nothing about the route, so it is not the "no projection"
+     * answer a successful empty read is: treating it as one let the startup
+     * repair read an empty owner/foreign map as proof that the pool serves and
+     * bind the broker over a persisted OAuth projection it could not read.
+     * Readiness therefore stays false for these providers and the repair skips
+     * them; only a restart can retry the read.
+     */
+    private readonly ownershipReadFailures;
     /**
      * One resolver set per provider still being waited on (round-10 should-fix
      * SF2). A wait registers exactly one entry here and removes it when the wait
@@ -168,11 +317,27 @@ export declare class KeysManagerService {
     private readonly hydrationWaiters;
     /**
      * True once the load-time hydration read is over (round-10 SF1). From then
-     * on no provider's read can land, so attribution is known for every provider
-     * — including one adopted after the read, whose OAuth rows did not exist
-     * when the projection was looked for.
+     * on no hydration read can land. It is NOT evidence that a given provider's
+     * projection was read (PR review round 17): a provider adopted after the
+     * snapshot was never in it, so readiness is decided per provider
+     * ({@link projectionOwnershipKnown}) and adoption reads its own projection.
      */
     private hydrationSettled;
+    /**
+     * Credential-store generation of the ownership hydration (PR review round
+     * 27). A remounted credentials service starts a new pass while the previous
+     * store's reads can still be in flight; their answers describe records the
+     * new backend does not hold, so the epoch gates every write and settle of
+     * the pass that started it.
+     */
+    private hydrationEpoch;
+    /**
+     * Whether a credential store was ever attached (PR review round 27). The
+     * first attach is the startup mount and keeps its behaviour; every later one
+     * replaces the credential backend, so the ownership classification loaded
+     * from the previous one is stale and the read restarts from unknown.
+     */
+    private credentialsMounted;
     /** Providers whose bounded-wait warning already fired (warn once). */
     private readonly hydrationWaitWarned;
     /** Channels whose lost-subscription warning already fired (warn once). */
@@ -193,7 +358,17 @@ export declare class KeysManagerService {
      * after a restart. An orphan projection — no matching row, e.g. a foreign
      * or stale grant — is left untouched: the manager never adopts a grant it
      * does not own, and out-of-band updates keep surfacing the native-
-     * management warning.
+     * management warning. A live record that is not a managed grant at all (a
+     * native api-key, an unrecognized payload) is foreign for the same reason
+     * (PR review round 4): it serves the route, so the startup repair must not
+     * bind the broker over it.
+     *
+     * EVERY managed provider's projection is read (PR review round 13), not
+     * only those with OAuth rows: a key-only pool can be overridden by a
+     * native grant persisted for the same route, and a skipped read left the
+     * startup repair free to bind the broker over it. The reads run
+     * concurrently so one provider's stalled read cannot delay another
+     * provider's own readiness (round 9).
      *
      * Returns its own completion (round-8 finding I-000108), and the returned
      * promise is already caught, so a failed hydration degrades to "no owner"
@@ -202,11 +377,31 @@ export declare class KeysManagerService {
      * each request waits on its own provider's landing instead.
      */
     private hydrateProjectionOwnership;
+    /**
+     * Drop every ownership fact loaded from a previous credential store (PR
+     * review round 27). The classification is per backend: a record that existed
+     * in the old store says nothing about the remounted one, and a route whose
+     * old store held a managed projection would otherwise stay attributed to
+     * that account and off its surviving key pool. The epoch bump discards a read
+     * still in flight from the replaced store instead of letting its answer land
+     * over the new one; ownership stays unknown until the new pass reads.
+     */
+    private invalidateProjectionOwnership;
     /**
      * Record that one provider's hydration read is over — owner or not (SF1) —
      * and wake the requests waiting on that provider alone (SF2).
      */
     private noteProviderHydrated;
+    /**
+     * An authoritative projection read answered for this provider, so a failed
+     * startup hydration no longer leaves ownership unknown (PR review round 13:
+     * the marker used to survive until a restart — no attribution, no key
+     * selection, and row tests refused with "ownership is still loading"). The
+     * binding re-derive is queued behind the reconciliation that proved the
+     * read: its attribution decides the route's serving shape, and the startup
+     * repair was skipped while that shape was unknown.
+     */
+    private noteProjectionReadSucceeded;
     /** Release every provider's readiness wait when hydration cannot proceed. */
     private settleHydrationWaits;
     /**
@@ -232,10 +427,10 @@ export declare class KeysManagerService {
      * Wait (bounded) until projection-ownership hydration can attribute this
      * request, and report whether it did.
      *
-     * A provider without OAuth rows can never own a projection, so it never
-     * waits — a stalled read for some other provider must not delay it
-     * (round-9 should-fix: this used to gate every managed provider, API-key-
-     * only ones included).
+     * Readiness is decided PER PROVIDER (round-10 should-fix SF1): every managed
+     * provider's own projection read lands independently (PR review round 13), so
+     * a provider whose read has landed needs no wait and a stalled read for
+     * another provider cannot delay this one.
      *
      * Returns false when the bound elapsed first. The caller then treats
      * attribution as unknown (no owner) and keeps key state untouched: a
@@ -243,15 +438,24 @@ export declare class KeysManagerService {
      * repeat the I-000108 corruption. The hydration promise is not cancelled,
      * so a late result still lands under the generation guard and later
      * requests are attributed normally.
-     *
-     * Readiness is decided PER PROVIDER (round-10 should-fix SF1). Hydration
-     * writes owners progressively, so racing the one global promise would
-     * discard an owner this provider already confirmed just because another
-     * provider's read stalled. A provider whose own read has landed — with an
-     * owner or with none — is ready without waiting, and the "unknown" fallback
-     * is confined to the requested provider's own unresolved read.
      */
     private awaitProjectionOwnership;
+    /**
+     * Whether this provider's projection ownership can already be decided
+     * without waiting (round-10 SF1, made the single readiness rule by PR review
+     * round 3). Every managed provider's projection is read at hydration (a
+     * key-only pool can be overridden by a persisted native grant, PR review
+     * round 13), so the rule is the same for all of them: this provider's own
+     * read landed, or a claim already owns it.
+     *
+     * The process-wide settled flag is deliberately NOT part of this rule (PR
+     * review round 17): a provider adopted after the snapshot was never read by
+     * it, so "hydration is over" says nothing about THAT route's projection.
+     * Adoption reads it itself ({@link readAdoptionProjection}) and an extra
+     * provider's profile is created by its own call, so every managed provider
+     * still answers through its own marker.
+     */
+    private projectionOwnershipKnown;
     /**
      * Record that a newly committed grant became the provider's projection and
      * return that projection's generation (round-6 finding SF1).
@@ -284,13 +488,69 @@ export declare class KeysManagerService {
      * the remaining attempt/step records after `ATTEMPT_TTL_MS`.
      */
     pruneTransient(now?: number): void;
+    /**
+     * Whether a continuation that resumes from an await must stop writing
+     * (PR review round 35). `shutdownRequested` is up for `close()`'s own
+     * pre-close restoration, which writes by design: it alone carries the
+     * module-private {@link PRE_CLOSE_RESTORE} capability (round 36), which is
+     * honoured only while that phase is running (round 37). Both facts are read
+     * here, at the caller's write decision, so a capability the phase left
+     * behind cannot pass a check made earlier.
+     */
+    private persistenceRefused;
     /** Stop accepting mutations, drain the queue, then persist the final snapshot. */
     close(): Promise<void>;
+    /** The body of the one shutdown this manager runs. */
+    private closeOnce;
+    /**
+     * Put every outstanding window's borrowed projection back before shutdown
+     * closes the store (PR review round 33).
+     *
+     * `close()` sets `closing`, which refuses {@link cleanupTestWindow} — the one
+     * identity-checked restoration — so a test whose request ignores the abort
+     * used to leave the tested account projected and the binding it released
+     * released, past unload and into the next startup. Each window's captured
+     * facts are restored through the same compare-by-payload path as the late
+     * reconcile, under one cleanup bound and the attempt fence (a superseded
+     * attempt writes nothing), and a window that released the binding re-syncs it
+     * against the restored serving source.
+     *
+     * The request itself is never waited for — an adapter can still rewrite the
+     * projection after its restore — so a restoration that cannot finish in the
+     * bound warns once and leaves the state to the next startup's hydration.
+     */
+    private restoreBorrowedWindows;
+    /**
+     * Drain the grant chains under a hard bound (PR review round 29).
+     *
+     * The work is not cancelled — the credential seam offers no cancellation and
+     * a wedged provider request may never settle — it is only stopped from
+     * holding shutdown: the chain past the deadline is abandoned, and its late
+     * write can only land in a store that is closing anyway.
+     */
+    private drainGrantReconciliations;
     /** Push a user-facing warning that rides the next state response. */
     private pushWarning;
     private takeWarnings;
+    /**
+     * Report declared headers whose stored value no longer matches what the
+     * environment supplies. The stored value is never replaced — the user may
+     * have set it deliberately — but the divergence must be visible, because
+     * otherwise the route keeps sending the stale value forever.
+     */
+    private warnHeaderDrift;
     /** Current settings service, if the composition mounted one. */
     private settingsService;
+    /**
+     * Mount the settings service — the host's `ctx.inject(['settings'])` seam.
+     *
+     * A mount that lands after construction retries the binding repair: the
+     * startup pass could not read a profile yet and would otherwise leave the
+     * route broken for the whole session.
+     */
+    attachSettings(settings: SettingsLike): void;
+    /** Unmount the settings service that a re-mount replaced. */
+    detachSettings(settings: SettingsLike): void;
     /** Current raw credential provider. */
     private credentialsRaw;
     /**
@@ -326,6 +586,23 @@ export declare class KeysManagerService {
      * Add account that would fail. The check is lazy — see {@link oauthFlowFor}.
      */
     private oauthFlowAvailable;
+    /**
+     * Resolve one transport route's sign-in flow.
+     *
+     * The transports package registers `llm-omp-transports/<route>` itself, so
+     * the live flow list is also this manager's inventory of transport routes:
+     * a route with no registered flow is not a transport account surface, and a
+     * route whose record exists but whose flow is gone is not listed at all
+     * (there would be nothing to sign in with).
+     *
+     * The method id is the flow's own (`methods[0].id`), never a literal
+     * `'oauth'`: the scope prefix is the whole cross-package contract, and the
+     * transports package may name a method that is not OAuth. A flow with no
+     * method cannot be begun and is not a sign-in surface.
+     */
+    private transportFlowFor;
+    /** Every registered transport flow, in seam order. */
+    private transportFlows;
     /**
      * Warn once per channel: a lost subscription silently disables a whole
      * feature (harvest never runs; rotations never sync), so the degradation
@@ -342,6 +619,14 @@ export declare class KeysManagerService {
     private watchAuthorizationSettled;
     /** One settled broadcast: finalize the matching attempt, harvest on success. */
     private onAuthorizationSettled;
+    /**
+     * The seam interaction one attempt hands to its flow.
+     *
+     * Shared by the pi-ai and transport sign-ins: both surfaces park notices and
+     * prompts on the same {@link LoginAttempt} and are polled through
+     * `accountAttempt`; only what happens after `authorized` differs.
+     */
+    private attemptInteraction;
     /**
      * Start one interactive OAuth sign-in. Returns immediately with the
      * attempt view; the attempt walks `pending → (prompt ⇄ pending) →
@@ -357,6 +642,65 @@ export declare class KeysManagerService {
     accountAttempt(attemptId: string): AccountAttemptView | undefined;
     /** Every attempt, newest first, for T3 surfaces. */
     listAccountAttempts(): AccountAttemptView[];
+    /**
+     * Re-read every `llm-omp-transports/<route>` grant into
+     * {@link transportRows}.
+     *
+     * Every caller gets a pass appended after the one already in flight, so an
+     * awaiting caller observes a read that started after its own write (a
+     * removal, a sign-in commit). Poll-only callers use
+     * {@link refreshTransportAccountsIfIdle} instead, so a slow store cannot
+     * accumulate one pass per page tick. A failed read leaves that route's
+     * previous row alone instead of claiming the account disappeared; the next
+     * pass retries.
+     */
+    refreshTransportAccounts(): Promise<void>;
+    /** Poll hint: start a pass only when none is in flight. */
+    private refreshTransportAccountsIfIdle;
+    /** One read pass over every registered transport route. */
+    private readTransportAccounts;
+    /**
+     * Remote: start one transport sign-in.
+     *
+     * The flow lives on the transports package's own key
+     * (`llm-omp-transports/<route>`), so the grant it commits stays that route's
+     * credential: nothing here harvests it into a pool row or a `llm-pi-ai`
+     * projection. The attempt is otherwise the same record the pi-ai dialog
+     * polls through `accountAttempt`, so the client reuses that dialog; an
+     * authorized outcome is terminal here (the flow has already committed).
+     */
+    beginTransportLogin(route: string): Promise<AccountAttemptView>;
+    /**
+     * Remote: confirm one transport route's stored grant.
+     *
+     * A transport route has exactly one grant record and its adapter resolves
+     * that record per request, so the stored grant already IS the route's live
+     * credential. Activation is therefore a state-level re-read: it writes
+     * nothing (in particular no `llm-pi-ai/<route>` projection, which the
+     * transport route never consults) and reports the current status so the UI
+     * can tell "active" from "expired" or "sign in again".
+     */
+    activateTransportAccount(route: string): Promise<StateView>;
+    /**
+     * Remote: drop one transport route's grant record.
+     *
+     * The record is the whole account — the transports package re-creates none —
+     * so deleting it leaves the route signed out until the next sign-in. A live
+     * sign-in is withdrawn first: left running, its commit would recreate the
+     * grant this removal just deleted. No manager state is written, hence no
+     * `run` queue and no state flush.
+     */
+    removeTransportAccount(route: string): Promise<StateView>;
+    /** The route's removal epoch; absent means never removed. */
+    private transportGenerationOf;
+    /**
+     * Drop a grant a withdrawn sign-in wrote after its account was removed.
+     *
+     * The seam refuses a commit once the attempt's signal aborts, but a commit
+     * that had already started can still land. The account was deleted, so that
+     * write is deleted too instead of being reported as a signed-in route.
+     */
+    private dropRemovedTransportGrant;
     /**
      * Detach the parked prompt. With a reason the flow's awaited promise is
      * rejected too — a parked prompt dropped un-rejected would leave the
@@ -386,6 +730,11 @@ export declare class KeysManagerService {
      * recorded at that same broadcast (R6-SF1): it names the projection whose
      * failures own a cooldown, so the stale-window reset below clears only a
      * window attributed to an OLDER projection.
+     *
+     * A harvest that finds the attempt already settled writes neither the
+     * plugin-scope copy nor a row, but the projection the seam committed for
+     * this attempt is still demoted (ownership-checked, I-000122): a
+     * failed/cancelled login must not keep serving through the route.
      */
     private harvestLogin;
     /**
@@ -460,6 +809,30 @@ export declare class KeysManagerService {
      * Resolves `ok: false` only when the compare/delete writes themselves
      * rejected; an ownership mismatch is the guard doing its job (the live
      * record belongs to someone else) and counts as a clean skip.
+     *
+     * Every manager-initiated projection deletion registers the one-shot
+     * {@link intentionalProjectionRemovals} marker before the delete, exactly
+     * as {@link decideAndDeleteProjection} does (I-000125). Unmarked, the
+     * removal's own `credentials/record-updated` echo reconciles as an
+     * external deletion: the route's previously active managed account is
+     * flagged `valueMissing`, its owner claim is dropped and a misleading
+     * "removed outside Keys Manager" warning is pushed — even though that
+     * row and its plugin-scope grant are untouched.
+     *
+     * The marker only silences that echo; the route's state is corrected
+     * explicitly. The removal leaves the route with no stored projection, so the
+     * provider's owner claim — whatever it named before this attempt's grant
+     * replaced the record — is untruthful: {@link oauthOwnerFor} keeps naming a
+     * row pi-ai no longer resolves, `wrapStream` skips key-pool selection, oauth
+     * failures are attributed to that row, and the client keeps "Set active"
+     * disabled — the account cannot be re-activated. The claim is therefore
+     * invalidated (I-000125), and ONLY the claim: the surviving row keeps its
+     * `grantRef` and its `valueMissing: false`, so it stays managed and
+     * re-activatable while the route falls back to its API-key pool.
+     *
+     * The marker is armed only while the provider is still managed: a released
+     * provider has no echo consumer, and a marker nothing consumes would stay
+     * armed for its whole TTL and mask a genuine out-of-band removal.
      */
     private revertHarvestProjection;
     /** Expire wedged sign-ins and drop long-settled attempt records. */
@@ -604,6 +977,242 @@ export declare class KeysManagerService {
      * cascade-selectable again.
      */
     activateAccount(provider: string, accountId: string): Promise<StateView>;
+    /**
+     * Remote: send one minimal request with the selected key or account row.
+     *
+     * Observation-only by construction: the request runs under a test-only
+     * request scope, so the broker answers with the pinned credential and the
+     * stream listener skips selection and every health/binding write. An OAuth
+     * row's grant is projected only for the duration of the request; the
+     * projection (and the in-memory owner) that served the route before is
+     * restored even when the request fails, so a test never changes which
+     * account the route is on.
+     *
+     * Every expected refusal is a structured `{ ok: false, error }` result
+     * (M2): the inline row line is the only failure surface, so a refusal must
+     * not also raise the page-level banner a thrown RPC error produces.
+     */
+    testKey(provider: string, keyId: string): Promise<KeyTestResult>;
+    /**
+     * Take over a test window that did not settle within the isolation deadline
+     * (QC fix wave 2) or whose own cleanup could not restore the route (PR
+     * review MF1).
+     *
+     * The fence is set synchronously, before the first cleanup await: the wedged
+     * test may resume at any await from here, and it must observe the
+     * abandonment before it starts a borrow or restores from its own stale
+     * snapshot. The provider keeps its isolation entry until the cleanup
+     * completed — see {@link settleAbandonedWindow}.
+     */
+    private abandonTestWindow;
+    /**
+     * Clean up one abandoned window and release its provider only on success.
+     *
+     * A cleanup that cannot finish needs the same untimed seam the wedged test is
+     * parked in, so it fails exactly like the test did. Releasing the provider
+     * then would serve ordinary traffic from the borrowed grant (or, on a
+     * broker-bound profile, from a route whose binding was released and never
+     * restored), so the isolation entry and the fence both stay. Two events can
+     * retry the cleanup: the abandoned promise's settlement, and the next test
+     * attempt ({@link recoverAbandonedWindow}, QC fix wave 3 W-002) — a promise
+     * that settles while the seam is still wedged must not be the only path.
+     */
+    private settleAbandonedWindow;
+    /** One later cleanup attempt for an abandoned window, once the seam answers again. */
+    private retryAbandonedWindow;
+    /**
+     * One bounded cleanup attempt for a fenced provider (QC fix wave 3, W-002).
+     *
+     * Returns whether the provider is servable again. The caller's attempt is
+     * what makes the fence self-clearing: `testKey` calls this before refusing,
+     * so isolation no longer depends on the abandoned promise settling after the
+     * seam recovered. A failed attempt keeps the fence and warns exactly once.
+     */
+    private recoverAbandonedWindow;
+    /**
+     * Run the window's cleanup under its hard deadline and drop the provider's
+     * isolation only when it completed. Returns the reason it could not finish.
+     *
+     * PR review round 21: the request that borrowed the route is not part of the
+     * cleanup, so a cleanup can finish while that request is still able to
+     * refresh and rewrite the borrowed projection. Such a window is held
+     * ({@link RowTestWindow.held}) — the fence and the isolation entries stay —
+     * and only its settlement reconciles the late write and releases it.
+     */
+    private attemptAbandonedCleanup;
+    /** Drop every isolation entry this window still owns, identity-checked. */
+    private releaseAbandonedWindow;
+    /**
+     * Put the route back the way the window found it: the mutations this window
+     * started, then the projection (compare-by-payload and rotation-aware, so
+     * nothing a writer stored meanwhile is overwritten), then the binding — the
+     * original finally's order, because the binding decision reads the restored
+     * owner map — then the borrow marker. Returns the reason the cleanup could
+     * not complete.
+     *
+     * `stillCurrent` is passed by abandoned-window attempts only: a superseded
+     * attempt that outlived its deadline may finish its writes, but the
+     * provider-wide borrow marker belongs to the newest attempt (PR review
+     * round 2) — deleting it would let ordinary traffic reach a newer window's
+     * borrowed projection.
+     */
+    private cleanupTestWindow;
+    /**
+     * Reconcile the projection once an abandoned window's request finally
+     * settles (PR review round 13).
+     *
+     * The watchdog's cleanup can complete before the wedged request resumes: an
+     * adapter that ignored the abort then refreshes and rewrites the borrowed
+     * grant, and the abandoned window used to skip cleanup on settlement — so
+     * the tested account stayed projected over the restored one and served
+     * ordinary traffic. The shared compare-by-payload restore is idempotent and
+     * only touches a projection this test left (the borrowed grant or a
+     * rotation of the tested row): a foreign payload survives, and a newer
+     * generation is written back to the tested row before the pre-test
+     * projection is restored.
+     *
+     * Returns the failure, so a caller that releases the provider afterwards (PR
+     * review round 21) can keep the fence instead. `ownsFence` is passed by the
+     * settlement of a held window and by the cleanup that releases a window whose
+     * settlement it deferred (PR review round 28): both already own the
+     * provider's fence, which the default guards would read as a competing
+     * cleanup and skip.
+     */
+    private reconcileLateWindowProjection;
+    /**
+     * Record one in-flight window mutation before it is awaited (QC fix wave 3,
+     * W-001). The normalized promise never rejects: the mutation's own outcome
+     * belongs to the code awaiting it, while the cleanup only needs to know when
+     * the write is over.
+     */
+    private recordWindowMutation;
+    /**
+     * Await every mutation this window recorded, including one the continuation
+     * of an earlier mutation records (a borrow that settles right before its
+     * binding release starts). The microtask hop after each settling round lets
+     * that continuation run before the cleanup judges the route clean. A
+     * mutation the seam never answers is bounded by the caller's deadline, not
+     * here.
+     */
+    private awaitWindowMutations;
+    /**
+     * Run one cleanup under its hard deadline. The work is not cancelled — the
+     * credential seam offers no cancellation — it is only stopped from holding
+     * the provider past the bound; a late result is ignored.
+     */
+    private withinCleanupDeadline;
+    /**
+     * Decide the route's serving shape and run one row test. Separate from
+     * {@link testKey} so the concurrency lock is registered before the first
+     * await.
+     */
+    private runRowTest;
+    /**
+     * The live provider profile one test must reason about, read once at entry
+     * (QC B1/N6), or the reason it cannot be used. An unreadable settings
+     * snapshot and a missing profile are distinct causes, so the row never
+     * claims a model is missing when the settings service is merely absent.
+     */
+    private testRouteProfile;
+    /** One request pinned to the row's API-key literal. */
+    private runApiKeyRowTest;
+    /** One request with the row's grant temporarily projected as the route's credential. */
+    private runOAuthRowTest;
+    /** The refusal an abandoned test reports instead of a stale success. */
+    private abandonedTestResult;
+    /** The refusal a chain reports when shutdown refuses its persistence. */
+    private shutdownTestResult;
+    /** The refusal a test reports when it arrives after shutdown began (round 34). */
+    private shutdownEntryResult;
+    /**
+     * Mark one provider as being removed for the whole removal body (PR review
+     * round 12). The marker is up before the body's first await — the removal's
+     * own test wait included — so {@link testKey} can refuse a test that would
+     * otherwise start inside the removal. Nesting is a depth because a
+     * last-key `deleteKey` releases through `releaseLocked`.
+     */
+    private withRemovalInProgress;
+    /**
+     * Hold a row/account removal until the provider's running row test settles
+     * (PR review round 9, R8-2).
+     *
+     * `testKey` captures its row, its credential and the route's serving shape
+     * before the first await, so a removal landing inside that window can delete
+     * the credential the test is about to send. For a borrowed OAuth account the
+     * removal is worse than a stale read: it compares its decision against the
+     * test's temporary projection, deletes it and demotes every row, and the
+     * test's own restore then writes the removed account's grant back. The
+     * removal therefore waits for the window instead of racing it. The wait is
+     * bounded by {@link isolationWaitMs} — a test wedged in an untimed seam call
+     * must not park the removal forever — and a provider whose abandoned window
+     * still owns the route's records refuses the removal outright. A wait that
+     * hits its own bound refuses too (PR review round 10, I-000179): proceeding
+     * would delete the credential the parked test is about to send. The user can
+     * retry once the abandoned window has been cleaned up.
+     */
+    private settleTestBeforeRemoval;
+    /**
+     * Put the projection back as it was before the test borrowed it, without
+     * losing or overwriting anything that changed meanwhile.
+     *
+     * `late` marks the abandoned window's settlement, after the watchdog's
+     * cleanup already released the provider: a removal no longer waits for this
+     * test, so the pre-test projection's owning row may be gone by the time this
+     * runs and must not be projected again (PR review round 19).
+     *
+     * The decision is compare-by-payload against the borrowed grant: only a
+     * live record that still carries it — or a refresh-rotated version of it
+     * that {@link matchOwningAccount} attributes to the tested row — is
+     * replaced. A rotation is reconciled into the tested row first (the same
+     * plugin-scope write-back {@link reconcileGrantRecord} performs), because
+     * the provider may already have consumed the superseded refresh token. A
+     * foreign or newer payload (another account, a native writer) is left
+     * untouched, and a record removed during the window stays removed. In every
+     * branch the owner map ends consistent with what the store actually holds.
+     *
+     * Returns a failure message when the restore or the rotation write-back
+     * did not land, so the caller reports `{ ok: false }` instead of a false
+     * pass.
+     */
+    private restoreProjection;
+    /**
+     * Point the owner map at the OAuth row the stored record identifies.
+     *
+     * The argument is the live record, not its grant payload (PR review round 8):
+     * a payload-only signature cannot tell a removed projection from a PRESENT
+     * record this pool cannot interpret (a native api-key, an unrecognized
+     * payload), so a surviving native record reached this method as `undefined`,
+     * cleared the foreign marker, and `keyPoolServes` then let the window-end
+     * sync bind the broker over it. Only an absent record is a confirmed removal
+     * (I-000167); a present record no row owns keeps the route foreign (round 3).
+     */
+    private reconcileProjectionOwner;
+    /**
+     * Persist one authoritative rotated grant payload for a row: write the
+     * plugin-scope record for the rotated generation, then hand the commit to
+     * {@link commitGrantGeneration} — the same tail {@link reconcileGrantRecord}
+     * performs. The caller runs inside the provider's grant chain and owns the
+     * decision, including the echo-specific generation guards, so only the
+     * write-back semantics live here.
+     */
+    private writeBackRotation;
+    /**
+     * The single owner of `row.oauth.grantRef` semantics (QC N1): point the row
+     * at the record holding its rotated generation, merge the refresh-derived
+     * identity fields, and remove the superseded record. Both the echo
+     * reconciler and the connection test's rotation write-back commit through
+     * here, so the ref scheme, the identity merge and the cleanup policy have
+     * exactly one implementation.
+     *
+     * The record write stays with the caller: the reconciler must revalidate the
+     * row between that write and this commit (C6-1), so only the tail is shared.
+     */
+    private commitGrantGeneration;
+    /**
+     * Send the minimal request under the given scope and map its terminal
+     * chunk. A thrown error or the 20-second abort is reported, never swallowed.
+     */
+    private runTestRequest;
     /**
      * Demote the cascade to the key pool by deleting the projection record:
      * pi-ai's per-request resolution prefers the stored credential and only
@@ -724,22 +1333,125 @@ export declare class KeysManagerService {
     private describeSettings;
     /** Find one live settings descriptor by entry id. */
     private namespace;
-    /** Apply one path-addressed settings write through the live revision. */
+    /**
+     * Apply one path-addressed settings write through the live revision.
+     *
+     * `stillWrites` runs after the descriptor re-read and immediately before the
+     * mutation: a decision derived from an earlier snapshot can be stale by then
+     * ({@link syncBrokerBinding}'s bind gate, PR review round 25). A declining
+     * guard skips the write and reports it.
+     */
     private mutateSettings;
     /** Prune expired bindings at most once a minute, without a restart. */
     private pruneBindings;
     /** Build the complete UI state. */
     buildState(): StateView;
-    /** Remote: complete manager state. */
+    /**
+     * Remote: complete manager state.
+     *
+     * The transport rows come from another package's records, and reading them
+     * is async while this endpoint is synchronous, so every poll starts a
+     * refresh for the next one (the client ticks every 30 s), unless one is
+     * already in flight. The constructor warms the first read and record
+     * updates refresh immediately, so the one-tick lag only shows on a cold
+     * start.
+     */
     getState(): StateView;
     /** Find one directory entry by route id. */
     private directoryEntry;
+    /**
+     * Whether the key pool is the credential source that serves this route: no
+     * OAuth projection owns it and at least one API-key row still holds a value.
+     * This is the one arbiter for both the verdict below and the binding write
+     * ({@link syncBrokerBinding}).
+     */
+    private keyPoolServes;
     /**
      * Classify the live binding. An unreadable settings snapshot is `unknown`,
      * not a confirmed mismatch: transient settings failures must not disable
      * key-pool recovery for a provider that is still managed.
+     *
+     * Only a value Keys Manager never wrote is a `mismatch`: the warning now
+     * means "the user took the profile back", not "the OAuth route is broken".
+     * An unbound profile is healthy while the key pool is not the serving
+     * source (an OAuth projection serves, or no API-key row holds a value) —
+     * that is the OAuth-only route's native shape.
      */
     private bindingState;
+    /**
+     * The single authority for a managed provider's pi-ai `apiKeyEnv`.
+     *
+     * pi-ai resolves a named credential synchronously and throws
+     * `MISSING_CREDENTIAL` when the credential seam cannot answer it, so the
+     * broker reference may only sit on a profile whose requests the key pool
+     * actually serves ({@link keyPoolServes}). Every other shape must be
+     * unbound, or pi-ai never reaches its own stored OAuth grant.
+     *
+     * Each direction has exactly one provably owned write:
+     * - bind: a profile that names no credential, or — with `takeover`, passed
+     *   solely by {@link adoptProvider} — the pre-adoption reference adoption
+     *   recorded and deliberately replaces;
+     * - unbind: only the broker reference Keys Manager itself wrote.
+     *
+     * Any other value is a hand-edit (or the pre-adoption reference release
+     * restored): it is never touched, and the `mismatch` verdict stays the
+     * signal that the user took the profile back.
+     *
+     * `write: false` is the startup repair: it only touches a profile that
+     * already exists, so a first run never materializes one from nothing. The
+     * release direction is single-sourced in {@link releasingProviders}: a
+     * provider being unmanaged is never bound again, whatever the row order of
+     * the pool it is deleting.
+     *
+     * A read-side problem or a refused write degrades to a warning: the
+     * callers' committed change must not fail on a settings problem, the user
+     * still sees that the route may resolve the wrong credential source, and
+     * the next repair pass retries.
+     *
+     * Returns whether the profile ends in the shape the serving source justifies
+     * (`true` also when no write was needed). The connection test's borrow is the
+     * one caller that acts on it: a failed release must refuse the test instead
+     * of sending a request the wrong credential source would answer.
+     *
+     * While a row test borrows the route (QC B4) no caller may persist a decision
+     * derived from that borrowed world — an `addKey` landing inside the window
+     * would otherwise unbind the profile for good. The test's own writes pass
+     * `borrow: true`; the window-end sync then writes the restored state.
+     */
+    private syncBrokerBinding;
+    /**
+     * Repair every managed provider's binding through the one authority. The
+     * startup pass and the settings-mount seam both run it, so a profile that
+     * was unreadable when hydration settled is still healed in this process
+     * instead of waiting for the next start.
+     */
+    private repairBrokerBindings;
+    /**
+     * One provider's repair pass (PR review round 42). A recorded adoption
+     * takeover debt is settled here only when the authoritative readiness says
+     * no projection serves the route — the case a restart leaves behind when the
+     * foreign record disappeared while the process was down.
+     */
+    private repairBinding;
+    /**
+     * Re-derive a managed route's binding after its projection changed outside
+     * this manager's account pool: a removal, a committed harvest that handed
+     * the route back to its API-key pool (PR review round 2), or a foreign
+     * projection taking a bound route over (round 4).
+     *
+     * The route's serving source is no longer the managed pool, or the pool is
+     * the only source left: either way `syncBrokerBinding` derives the one
+     * profile shape pi-ai's resolution order requires. A store refusal only
+     * warns — these are compensation paths and must never fail the change that
+     * triggered them; the next repair pass retries.
+     */
+    private syncBindingAfterProjectionChange;
+    /**
+     * A refused binding write must not fail the change that triggered it, but
+     * it cannot stay in the log alone either: the route may resolve the wrong
+     * credential source until the next repair.
+     */
+    private bindingWriteRefused;
     /** Candidate credential refs from which an existing key can be imported. */
     private importRefs;
     /** Create and store one key record without adding it to a provider. */
@@ -748,10 +1460,75 @@ export declare class KeysManagerService {
     private findImport;
     /** Remote: take over one existing provider route. */
     adoptProvider(provider: string): Promise<StateView>;
-    /** Discover models for a new extra provider, falling back to the seed catalog. */
+    /**
+     * Read and classify one provider's live projection at adoption (PR review
+     * round 17) — the same read hydration does, for the one route hydration
+     * cannot cover: a provider that did not exist when the snapshot was taken.
+     *
+     * An adoption owns no account row yet, so any live record is one no row of
+     * this pool owns: a native api-key, an unrecognized payload, and a grant left
+     * behind by a released account all serve the route ahead of the broker
+     * reference, so the route is marked foreign and the pool is not bound over it
+     * (PR review rounds 3–4). An absent record clears any stale marker: the pool
+     * may serve. A failed read is not an absent projection (round 8): ownership
+     * stays unknown, so nothing may be bound and no repair touches the route
+     * until an authoritative read answers ({@link noteProjectionReadSucceeded}).
+     *
+     * Returns `unknown` for that failure; the adoption itself is kept — there is
+     * no write to roll back, and only the binding is undecided.
+     *
+     * The classification runs inside the route's grant chain (PR review round
+     * 22, Codex P1). A native write or deletion reconciled while the read is
+     * outstanding is therefore either already visible to it or queued behind it:
+     * a read whose snapshot a newer event overtook reports `superseded` and lands
+     * nothing, so a stale absence can never bind the broker over a newer
+     * projection state and a stale presence can never leave the pool unbound.
+     */
+    private readAdoptionProjection;
+    /** Body of {@link readAdoptionProjection}: read, then land the classification. */
+    private classifyAdoptionProjection;
+    /**
+     * Undo an adoption whose initial binding write was refused (PR review
+     * round 2): drop the managed record and its broker entry, delete the
+     * plugin-scope copy this call created, and put back a pre-adoption
+     * reference that landed despite the refusal. The source credential and the
+     * profile's other fields are never touched — adoption only read them.
+     */
+    private rollbackAdoption;
+    /**
+     * Discover models for a new extra provider, falling back to the seed catalog.
+     * A route that declares a static header installs the seed catalog directly:
+     * the discovery request has no header slot, so probing such an endpoint can
+     * only fail (and would hold the serialized mutation queue for the probe's
+     * whole timeout).
+     */
     private discoverModels;
-    /** Remote: install and adopt one extra built-in provider. */
+    /**
+     * Remote: install and adopt one extra built-in provider.
+     *
+     * Deliberate exemption from the one-authority rule
+     * ({@link syncBrokerBinding}): this call creates the profile it binds and
+     * the key that serves it in the same mutation, so the write below is the
+     * route's first binding rather than a takeover of a value the user owns.
+     */
     addExtraProvider(extraId: string, alias: string, value: string): Promise<StateView>;
+    /**
+     * Restore a managed extra route's declared static headers.
+     *
+     * A managed profile can lose its declared headers through a Models edit;
+     * every managed add-key flow repairs them instead of leaving a route whose
+     * required header is silently absent. Only a live profile with a healthy
+     * binding is ours to repair: a deleted profile would gain a header-only
+     * half-profile, and a replaced one is the state release refuses to touch. A
+     * stored value for the same header always wins. The caller may pass the
+     * headers it already resolved at its own entry (where a missing variable can
+     * still refuse the add before any write); otherwise this method resolves
+     * them. Either way a failure only warns, because the key has already been
+     * added: a route whose headers cannot be resolved, and a settings write that
+     * cannot be performed, both leave the repair pending for the next add so a
+     * half-applied add is never turned into a rejected one.
+     */
+    private repairDeclaredHeaders;
     /** Add one key; caller already owns the mutation queue. */
     private addKeyLocked;
     /** Remote: add one key to a managed provider. */
@@ -760,12 +1537,45 @@ export declare class KeysManagerService {
     updateKey(provider: string, keyId: string, patch: unknown): Promise<StateView>;
     /** Remote: delete one key, releasing the provider when it was the last one. */
     deleteKey(provider: string, keyId: string): Promise<StateView>;
-    /** Read one live profile for release-time cleanup decisions. */
+    /** Read one live profile for repair and release-time cleanup decisions. */
     private profileAt;
-    /** Restore the exact live profile captured before release mutated it. */
+    /**
+     * Restore the exact live profile captured before release mutated it.
+     *
+     * Deliberate exemption from the one-authority rule: release is unmanaging,
+     * so this write puts the pre-adoption document back instead of deriving a
+     * binding from a key pool that is being deleted. Every other caller goes
+     * through {@link syncBrokerBinding}.
+     */
     private restoreProfileSnapshot;
-    /** Remove every managed credential, recording progress before a retry. */
+    /**
+     * Remove every managed credential, recording progress before a retry.
+     *
+     * The provider is flagged as releasing for the whole loop: a demotion
+     * inside it (an `oauth` row iterated before a surviving `api-key` row) must
+     * not re-bind the profile, or the reference release just restored would be
+     * overwritten and then stripped by the closing unbind. While unmanaging the
+     * binding only ever goes one way — off.
+     */
     private deleteManagedCredentials;
+    /**
+     * Drop any armed intentional-removal marker for a provider being released.
+     *
+     * The marker only exists to silence the record-updated echo of the manager's
+     * own projection removal, and that echo is dropped outright once the provider
+     * is unmanaged: {@link onGrantRecordUpdated} returns at event time and
+     * {@link reconcileGrantRecord} at body time. A release can land between the
+     * arm and that echo — the abort compensation arms inside the mutation queue
+     * while its echo is still chained behind an in-flight body — leaving the
+     * marker armed for its whole TTL with nothing left to consume it. A provider
+     * re-adopted inside that window would then read a genuine out-of-band
+     * removal as the manager's own: no warning, no `valueMissing`, no
+     * stale-owner cleanup.
+     *
+     * Called only on the successful release path: a release that throws leaves
+     * the provider managed, and its echo may still legitimately arrive.
+     */
+    private dropIntentionalRemoval;
     /** Restore the provider profile and drop management; caller owns the queue. */
     private releaseLocked;
     /** Remote: stop managing a provider and restore its original key reference. */
@@ -832,6 +1642,38 @@ export declare class KeysManagerService {
      * entry (row removed) resolves to null.
      */
     private oauthOwnerFor;
+    /**
+     * Keep an ordinary request out of the window where a row test borrows (or
+     * is restoring) this provider's projection. The provider stream is built
+     * only after the bounded wait, so neither branch can start a request inside
+     * the borrowed window; a consumer that cancels during the wait constructs
+     * nothing at all. A test-scope request returns from `streamListener` before
+     * this wrapper, so a test never waits on its own guard.
+     */
+    private isolateFromTest;
+    /**
+     * Wait (bounded) for the in-flight borrowing test on this provider to
+     * settle. The bound is {@link KEY_TEST_ISOLATION_WAIT_MS}, not the test's
+     * own request timeout: the awaited promise also covers untimed
+     * credential-store reads, so without this an ordinary request could park
+     * here forever. A failed or timed-out test never fails the waiting request.
+     *
+     * QC fix wave 2: the one exception is a provider whose abandoned window is
+     * still fenced. The wait is over, but the route's credential surface has not
+     * been reconciled, so serving the request would answer it with the borrowed
+     * grant (or, after a released binding, with no bound route at all). Such a
+     * request is refused instead — the fence is what keeps cross-use impossible
+     * until the cleanup completes.
+     */
+    private settleProviderTest;
+    /** The refusal an ordinary request gets while its route is still unreconciled. */
+    private testCleanupRefusal;
+    /**
+     * Wrap one connection-test stream: keep the pinned credential scope alive
+     * for every chunk and do nothing else. No selection, no cursor, no health
+     * writes — the request is pure observation.
+     */
+    private wrapTestStream;
     /** Wrap one managed stream so credential resolution sees this key. */
     private wrapStream;
     /**