mcp-google-multi 6.0.0-alpha.72 → 6.0.0-alpha.73

package/dist/doctor.js

@@ -35,9 +35,8 @@ const DEFAULT_DEPS = {
     probeApi: (alias) => probeApiEnablement(alias),
     probeHttp: (cfg) => probeHttpEndpoints(cfg),
 };
-/** §7 live check: the advertised OAuth metadata must derive from MCP_PUBLIC_URL
- * exactly — one mismatch between PRM `resource` / AS `issuer` and what clients
- * compute from the public URL is the perpetual-401 interop bug. */
+// §7 live check: a mismatch between PRM/AS metadata and what clients compute
+// from the public URL is the perpetual-401 interop bug.
 async function probeHttpEndpoints(cfg) {
     try {
         const prmRes = await fetch(`${cfg.publicUrl}/.well-known/oauth-protected-resource`, {
@@ -150,7 +149,7 @@ function sectionConfig(deps, set, tenantScope = false) {
     return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
 }
 /** One line, state AND source, so the people being measured can see both
- * here and in `diagnose` (metrics spec section 2). Read-only. */
+ * here and in `diagnose`. Read-only. */
 export function usageMetricsStatusLine(env) {
     const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
     let configValue;
@@ -337,10 +336,8 @@ export function overallVerdict(sections) {
     return worst;
 }
 export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
-    // Tenant scope omits the OPERATOR sections: §3 (key provenance = box
-    // infrastructure) and §7 (its owner-gate lines print MCP_OWNER_EMAILS
-    // values — other people's addresses from a tenant's seat), and trims §2 to
-    // the context's own account count.
+    // Tenant scope omits the OPERATOR sections (§3 key provenance, §7 owner-gate
+    // emails) and trims §2 to the context's own account count.
     const tenantScope = opts.scope === 'tenant';
     const sections = [];
     sections.push(sectionRuntime(deps, tenantScope));
@@ -380,10 +377,8 @@ export function renderDoctorText(report) {
 }
 const EMAIL_LOCAL_CHAR = /[A-Za-z0-9._%+-]/;
 const EMAIL_DOMAIN_CHAR = /[A-Za-z0-9.-]/;
-/** Mask the local-part of an email so a report never carries a full address.
- * A linear scan, not a regex: the `local* @domain` pattern backtracks
- * polynomially on long local-charset runs without an @ (CodeQL
- * js/polynomial-redos), and report text can embed arbitrary error strings. */
+// A linear scan, not a regex: `local*@domain` backtracks polynomially on long
+// local-charset runs without an @ (CodeQL js/polynomial-redos).
 function maskEmails(text) {
     let out = '';
     let i = 0;

package/dist/env-load.js

@@ -3,11 +3,8 @@ import path from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// Precedence: real env > CWD .env > package-root .env > ~/.config .env.
-// process.loadEnvFile never overwrites keys already in process.env (pinned by
-// tests/env-load.test.ts T4), so highest-priority file loads FIRST and real
-// env wins by already being present; the boot snapshot re-assert is a second
-// line of defense should those semantics ever change.
+// Precedence: real env > CWD .env > package-root .env > ~/.config .env;
+// the boot snapshot re-assert below is a second line of defense.
 export function loadEnvFiles(paths = {}) {
     // loadEnvFile exists since 20.12, so a feature check alone would let 20.12-21.x through.
     const major = Number(process.versions.node.split('.', 1)[0]);

package/dist/executor.js

@@ -91,10 +91,8 @@ export async function executeApiMethod(method, args, deps = {}) {
         });
         const text = JSON.stringify(res.data ?? null);
         if (text.length > MAX_RESPONSE_CHARS) {
-            // Budget the ENCODED head: jsonResult re-stringifies it, so every quote
-            // and backslash inside doubles. Slicing raw characters made the emitted
-            // result exceed the cap this tool advertises, by up to 15 percent on a
-            // quote-dense listing.
+            // Budget the ENCODED head: jsonResult re-stringifies it, so slicing raw
+            // characters overshot the advertised cap on a quote-dense listing.
             return jsonResult({
                 truncated: true,
                 totalChars: text.length,

package/dist/fanout.js

@@ -4,19 +4,13 @@ import { echoName, echoNames, MAX_SUGGESTED_KEYS } from './arg-strict.js';
 import { hints } from './hint-provider.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
-// `aliases` is required (no global default): the field is baked into a
-// registry's inputSchema, so it must read THAT registry's account set or a
-// '*' would advertise and accept another registry's aliases. It is a getter:
-// the set is read at parse time, so an alias added mid-session (account_add,
-// a tenant link) is valid on tools registered before it existed.
+// `aliases` is a getter read at parse time (not baked), so a registry only
+// ever sees ITS OWN account set, and a mid-session alias (account_add) is valid on tools registered before it existed.
 export function fanoutAccountField(description, aliases) {
     const boot = aliases();
     const csvExample = boot.length > 1 ? `; or a CSV subset like "${boot.slice(0, 2).join(',')}"` : '';
-    // The union's OWN error only fires when every branch aborts at the type
-    // check (a non-string). For a string, zod surfaces the single non-aborted
-    // branch verbatim, which is the CSV regex, so a mistyped alias used to read
-    // as "Invalid string: must match pattern /^[a-zA-Z0-9_-]+(,...)/" and never
-    // named an alias. Hence the same message on BOTH.
+    // Same message on both union branches: for a string, zod surfaces the
+    // single non-aborted branch (the CSV regex) verbatim, which never named the alias.
     const bad = () => unknownAliasMessage(aliases(), true);
     return z
         // The selector branch stays first: tools/list injects the live
@@ -46,9 +40,8 @@ export function noAccountsResult() {
 export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
-    // A single alias used to skip validation entirely and reach getClient, whose
-    // throw landed on the mapper's floor as an unclassified upstream_error. Same
-    // check and same envelope wherever the alias was typed.
+    // A single alias used to skip validation and reach getClient, whose throw
+    // landed on the mapper's floor as an unclassified upstream_error.
     if (!value.includes(',')) {
         return accounts.includes(value)
             ? { ok: true, fanout: false, aliases: [value] }
@@ -132,10 +125,8 @@ export async function runFanout(handler, args, aliases) {
     await Promise.all(Array.from({ length: Math.min(FANOUT_CONCURRENCY, aliases.length) }, () => worker()));
     const failed = results.filter((r) => !r.ok).length;
     if (failed === results.length && results.length > 0) {
-        // Every account failed, so this IS an error result, and used to carry
-        // `isError` with no top-level error, hint or retriable: the agent saw a
-        // successful-looking object flagged as an error, and metrics bucketed it
-        // as `other`. Hoist a real envelope, keeping the per-account detail.
+        // Every account failed, so this IS an error result: hoist a real
+        // top-level envelope (error/hint/retriable), keeping the per-account detail.
         const slugs = [...new Set(results.map((r) => r.error?.error ?? 'internal'))];
         const hints = [...new Set(results.map((r) => r.error?.hint).filter(Boolean))];
         const retriable = results.every((r) => r.error?.retriable === true);

package/dist/fs-atomic.d.ts

@@ -1,6 +1,3 @@
-/** Which process instance holds a lock: PID namespace id, start time in
- * clock ticks since boot, and a boot id prefix. A part this process cannot
- * read is `host` or `0` (all three without /proc). */
 interface LockIdentity {
     ns: string;
     start: string;

package/dist/fs-atomic.js

@@ -129,9 +129,8 @@ function holderDead(holder, now) {
     // Two unreadable parts compare equal without naming the same namespace or
     // boot, so only a fully known identity is looked up by start time.
     if (SELF.ns !== 'host' && SELF.boot !== '0' && SELF.start !== '0' && owner.start !== '0') {
-        // A live namespace id is never shared, so the recorded pid is ours to
-        // look up: a restarted container reuses both the id and the pid, but not
-        // the start time.
+        // A live namespace id is never shared, so the recorded pid is ours to look
+        // up: a restarted container reuses both the id and the pid, but not the start time.
         const start = startOf(pid);
         if (start !== undefined)
             return start !== owner.start;
@@ -141,9 +140,8 @@ function holderDead(holder, now) {
         return holder.mtimeMs < PROCESS_START_MS;
     return probeDead(pid) || leaseOver;
 }
-// One waiter at a time breaks a dead lock: two breakers could otherwise both
-// see the dead holder, and the second would unlink the first one's new lock.
-// False when another waiter is breaking it.
+// One waiter at a time breaks a dead lock, or the second could unlink the
+// first one's new lock; false when another waiter is already breaking it.
 function breakLock(lock, holder) {
     const breaker = `${lock}.break`;
     // A token, not the inode: a breaker created after ours was removed can
@@ -198,10 +196,8 @@ function releaseBreaker(breaker, token) {
             throw error;
     }
 }
-// Hardlink-based advisory lock, generalized path-keyed from the token store's
-// alias-keyed original. The lock body is the bare pid, as older readers expect;
-// the owner file stays linked while held and names the holder's process
-// instance. See docs/internals.md.
+// Hardlink-based advisory lock; the lock body is the bare pid, as older
+// readers expect. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     const dir = path.dirname(absPath);
     const lock = path.join(dir, `.${path.basename(absPath)}.lock`);

package/dist/hint-provider.js

@@ -1,9 +1,5 @@
-// A plain array literal, not derived from the union: deriving it would need a
-// value-level mirror of the type anyway, and this way a missing member is
-// caught by the completeness check below instead of silently compiling.
-// `as const` so that check narrows to the literal tuple rather than widening
-// every element back to the whole HintCase['kind'] union (which would make
-// it pass trivially, whatever was listed).
+// A plain array literal, not derived from the union, so a missing member is
+// caught by the completeness check below rather than silently compiling.
 export const HINT_KINDS = [
     'reauth',
     'legacy_plaintext_token',
@@ -43,10 +39,8 @@ let installed = null;
 export function setHintProvider(p) {
     installed = p;
 }
-// A throwing provider must never take down the call site: every call site
-// does `hints()?.render(...)?.hint ?? <default>`, so a render that cannot
-// produce a Rendered falls back to the same literal a missing provider
-// would, and the provider's own error text never reaches a client.
+// A throwing provider must never take down the call site: it falls back to
+// the same literal a missing provider would, never leaking its own error text.
 export function hints() {
     if (!installed)
         return null;

package/dist/http-config.js

@@ -1,8 +1,5 @@
-// Transport selection + public-base-URL / Origin / host config plumbing.
-// Pure, resolved once at boot; consumed by the HTTP host and the AS metadata.
-// Owns the canonicalization rule: a single mismatch
-// between the advertised resource URI and the client's `resource`/`aud` = a
-// perpetual 401 loop (the #1 interop bug), so it is normalized exactly once.
+// Transport + public-base-URL / Origin / host config, pure and resolved once
+// at boot. A mismatch between the advertised URI and the client's `aud` is a perpetual 401 loop.
 export const DEFAULT_HTTP_HOST = '127.0.0.1';
 export const DEFAULT_HTTP_PORT = 4243;
 export const CLAUDE_AI_ORIGIN = 'https://claude.ai';

package/dist/http-transport.js

@@ -1,30 +1,21 @@
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
-// node:http server, the route table, the front guard (Host / Origin / DNS-rebind),
-// and the stateless per-request /mcp dispatch. The OAuth AS endpoints and Bearer
-// verification are a seam filled by oauth-as.ts; the default is a loopback-owner
-// authenticator so the local-HTTP model works without the AS.
 import { createServer } from 'node:http';
 import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
 import { logSafe } from './trim.js';
 // A host wrapping the log callbacks it hands core needs this, and trim has no package export.
 export { logSafe } from './trim.js';
 // A hung handler that keeps the connection open would otherwise hold the global
-// serialize() lock forever. Generous by default so slow-but-valid calls (large
-// Drive exports, fan-out) still finish; the point is only to guarantee release.
+// serialize() lock forever; generous by default so slow-but-valid calls still finish.
 const DISPATCH_TIMEOUT_DEFAULT = 120_000;
-/** MCP 2025-06-18 dropped JSON-RPC batching, and the SDK screens every frame
- * of a batch synchronously in one tick: without a cap one body multiplies the
- * per-call work by however many frames fit in it. */
+// Without a cap, one body multiplies per-call work by however many
+// JSON-RPC frames the SDK's synchronous batch screening finds in it.
 const MAX_BATCH_FRAMES = 16;
-// A resolveServer refusal's body reaches the wire verbatim: validated
-// so a host cannot accidentally leak an operator path/env var through a wrongly
-// shaped slug or an overlong message. No new slug literal enters core itself —
-// the slug is always the host's own value.
+// A refusal's body reaches the wire verbatim, so it's validated: no new slug
+// literal enters core, and an overlong message can't leak an operator path/env var.
 const REFUSAL_SLUG_RE = /^[a-z][a-z0-9_]{0,39}$/;
 const MAX_REFUSAL_MESSAGE_CHARS = 300;
-// C0/C1 controls, format chars (includes bidi overrides like U+202E and
-// zero-width joiners) and the line/paragraph separators; ordinary non-ASCII
-// letters stay allowed.
+// C0/C1 controls, format chars (bidi overrides, zero-width joiners) and
+// line/paragraph separators; ordinary non-ASCII letters stay allowed.
 const NON_PRINTABLE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
 function isValidRefusal(r) {
     return (typeof r.error === 'string' &&
@@ -81,25 +72,17 @@ export function jsonRpcMethod(body) {
 /** setTimeout fires at once for a delay above this, so a longer grace would
  * cut every connection immediately. */
 const MAX_GRACE_MS = 2 ** 31 - 1;
-// A lingering close: a socket destroyed while its client is still sending (a
-// body pipelined after the close) is reset by the kernel, which drops whatever
-// of the last response is still unsent. So the socket only ends its side and
-// waits for the client's FIN, or for the grace to end.
+// A lingering close (ends the socket, never destroys it); see docs/internals.md (Graceful close).
 function endAfterFlush(socket) {
     if (socket.destroyed || socket.writableEnded)
         return;
-    // Node arms a keep-alive timer when a response finishes and destroys the
-    // socket when it fires, which would cut a slow reader's unread tail just as
-    // an early destroy does. Only the client's FIN or the grace ends it now.
+    // Disarm the keep-alive timer Node arms on finish, or it destroys the
+    // socket ~6s later and cuts a slow reader's unread tail the same way an early destroy does.
     socket.setTimeout(0);
     socket.end();
 }
-// A request that arrives while closing is never answered, so Node keeps it
-// until the socket closes, and a flood pipelined behind a held response would
-// pile up without limit. Reading stops for good instead, which lets TCP flow
-// control stop the client. Node resumes a socket after every parsed request
-// and on drain, so resume becomes a no-op. Such a socket never sees the
-// client's FIN either: the grace ends it.
+// Stops reading for good so TCP flow control stops the client, instead of
+// piling up a flood pipelined behind a held response; see docs/internals.md (Graceful close).
 function stopReading(socket) {
     socket.pause();
     socket.resume = () => socket;
@@ -117,18 +100,12 @@ function pathOf(req) {
 export class HttpTransportHost {
     opts;
     httpServer;
-    // Serialize the connect→dispatch critical section PER SERVER: a McpServer
-    // captures its transport per request (protocol.js), but the gap between
-    // connect() and the dispatch capturing it would still race under true
-    // concurrency, so all traffic to ONE server runs under one mutex. The free
-    // core has one lane (the boot server); with resolveServer each resolved
-    // server gets its own, however subjects map onto servers.
+    // Per-server dispatch mutex; see docs/internals.md.
     locks = new Map();
     // Requests holding a lane slot, per server; used only with maxQueuedPerLane.
     depth = new Map();
-    // What a graceful close waits on: open sockets, per socket the requests it
-    // has accepted whose response has not settled and the last of them, and
-    // every handle() that has not settled.
+    // What a graceful close waits on: open sockets and every handle() not yet
+    // settled; see docs/internals.md (Graceful close).
     sockets = new Set();
     pending = new Map();
     // Sockets that have accepted a request: nothing pending means the last
@@ -145,9 +122,8 @@ export class HttpTransportHost {
         const run = prev.then(fn, fn);
         const tail = run.then(() => undefined, () => undefined);
         this.locks.set(key, tail);
-        // An idle lane drops out, so the map holds only in-flight subjects rather
-        // than every subject ever seen. A request that chained on this tail has
-        // already replaced it, so the identity check never frees a live lane.
+        // An idle lane drops out of the map; the identity check below skips a
+        // later request that already replaced this tail, so it never frees a live lane.
         void tail.then(() => {
             if (this.locks.get(key) === tail)
                 this.locks.delete(key);
@@ -161,9 +137,8 @@ export class HttpTransportHost {
         const { config } = this.opts;
         const server = createServer((req, res) => {
             const socket = req.socket;
-            // Once closing, a connection ends after the last request it accepted
-            // before the close, so one arriving now is never handled (RFC 9112 9.6).
-            // Its body is left unread: nothing reads the socket again.
+            // Once closing, a request arriving now is never handled (RFC 9112 §9.6)
+            // and its body is left unread.
             if (this.closing) {
                 stopReading(socket);
                 return;
@@ -190,10 +165,8 @@ export class HttpTransportHost {
             };
             res.once('finish', settle);
             res.once('close', settle);
-            // Never rejects: close() waits on it, and a catch-all that itself threw
-            // must neither reject close() nor surface as an unhandled rejection.
-            // The thrown message can name server paths (a lock timeout does), so it
-            // goes only to the host's log.
+            // Never rejects (close() waits on it); the thrown message can name
+            // server paths, so it goes only to the host's log.
             const done = this.handle(req, res)
                 .catch((e) => {
                 try {
@@ -265,20 +238,13 @@ export class HttpTransportHost {
     }
     async closeGracefully(s, graceMs) {
         this.closing = true;
-        // Node's close() also destroys every connection it deems idle, and that
-        // includes one whose response has ended but is still flushing: a large
-        // body would be cut short. Idle sockets are closed below instead.
+        // Node's close() also destroys idle connections, which would cut short a
+        // large response still flushing; idle sockets are closed below instead.
         const nodeIdleCloser = s.closeIdleConnections;
         s.closeIdleConnections = () => undefined;
         const closed = new Promise((resolve) => s.close(() => resolve()));
         s.closeIdleConnections = nodeIdleCloser;
-        // Every request accepted before now is answered, and a connection ends
-        // after the last of them: that one says so if it has not started, and the
-        // settle hook in start() ends the socket once it finishes. Node itself
-        // destroys a socket once a Connection: close response is flushed, which
-        // resets it just as endAfterFlush explains, so that end lingers too. A
-        // socket with nothing pending may still be delivering the tail of its
-        // last response, so only one that never accepted a request is destroyed.
+        // Socket bookkeeping below; see docs/internals.md (Graceful close).
         for (const socket of this.sockets) {
             const entry = this.pending.get(socket);
             if (!entry && !this.served.has(socket)) {
@@ -357,10 +323,7 @@ export class HttpTransportHost {
         }
         if (!this.frontGuard(req, res))
             return;
-        // Registered before anything awaits: a client that leaves while its request
-        // waits on the lane must not have it dispatched once its turn comes. A
-        // response queued behind another on its connection never emits 'close', so
-        // the socket is checked too.
+        // Registered before anything awaits (client-gone skip); see docs/internals.md.
         let gone = false;
         res.once('close', () => (gone = true));
         const socket = req.socket;
@@ -400,8 +363,7 @@ export class HttpTransportHost {
                     return;
                 }
                 // An invalid shape falls through to today's exact answer rather than
-                // forwarding something unvalidated; a refusal never reaches dispatch
-                // either way.
+                // forwarding something unvalidated.
                 resolved = null;
             }
             target = resolved;
@@ -437,9 +399,8 @@ export class HttpTransportHost {
         }
     }
     async admitted(req, res, target, sub, clientGone) {
-        // Thread the verified subject to tool handlers: the Node transport forwards
-        // req.auth verbatim as ctx.http.authInfo. Token/clientId stay empty — the
-        // bearer value must not re-enter the dispatch path via handler context.
+        // Thread the verified subject to tool handlers via ctx.http.authInfo;
+        // token/clientId stay empty so the bearer value never re-enters the dispatch path.
         req.auth = {
             token: '',
             clientId: '',
@@ -457,28 +418,16 @@ export class HttpTransportHost {
         if (Array.isArray(body) && body.length > maxFrames) {
             return this.fail(res, 400, 'batch_too_large', `a JSON-RPC batch may hold at most ${maxFrames} messages`);
         }
-        // Host/Origin are enforced by the front guard above (uniformly for /mcp and
-        // the mounted AS routes), so the SDK's own DNS-rebind guard is disabled: its
-        // exact-Host match is stricter than the front guard and would 403 valid
-        // Hosts (double enforcement, differing rules).
+        // The SDK's own DNS-rebind guard is disabled: Host/Origin are already
+        // enforced above, and its stricter exact-Host match would 403 valid Hosts.
         const transport = new NodeStreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
             enableJsonResponse: true,
             enableDnsRebindingProtection: false,
         });
-        // The shared McpServer holds exactly one connected transport at a time, so
-        // connect + dispatch + DISCONNECT all run inside the mutex: the next request
-        // can never hit "Already connected". The serialized section is guaranteed to
-        // settle three ways — the handler finishes, the client disconnects (res
-        // 'close'), or a dispatch deadline fires — so neither a client that holds the
-        // connection open nor a hung upstream can wedge the lock. The transport is
-        // closed in a finally (which resets server._transport) before the lock
-        // releases. (A shared initialized-state persists across stateless requests;
-        // benign for the single-owner design.)
+        // connect + dispatch + disconnect run inside the per-server mutex, keyed
+        // on the server identity, never the subject; see docs/internals.md.
         const deadlineMs = this.opts.dispatchTimeoutMs ?? DISPATCH_TIMEOUT_DEFAULT;
-        // The lock lane is the SERVER identity, never the subject: two subjects
-        // reaching one server (the boot server, or a resolver mapping several
-        // subjects to one) would otherwise race it through the connect gap.
         const { server: mcpServer, argShapeFor, strictArgs, validationEnvelope } = target;
         await this.serializeFor(mcpServer, async () => {
             if (clientGone()) {
@@ -491,16 +440,14 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            // Same composition as the stdio leg: the envelope rewrite is innermost,
-            // so the tap above it still classifies the original validation prose.
+            // Envelope rewrite innermost, as on stdio; see docs/internals.md (Argument normalization).
             const enveloped = withValidationEnvelope(transport, validationEnvelope ?? {});
             const tapped = this.opts.metricsTap ? this.opts.metricsTap(enveloped) : enveloped;
             await mcpServer.connect(argShapeFor || strictArgs
                 ? withArgNormalization(tapped, argShapeFor ?? (() => undefined), this.opts.log, this.opts.onArgRename, strictArgs)
                 : tapped);
-            // Reflect the dispatch into a non-rejecting arm: if the deadline wins the
-            // race, an orphaned handler settling later must not surface as an unhandled
-            // rejection — but a genuine dispatch error still propagates (rethrown below).
+            // Non-rejecting arm: an orphaned handler settling after the deadline wins
+            // must not surface as an unhandled rejection; a real error is rethrown below.
             let dispatchErr;
             const dispatchArm = transport
                 .handleRequest(req, res, body)

package/dist/identity.js

@@ -2,18 +2,15 @@ import { getAccountSet, getTokenDir, refreshAccountSetIfStale } from './accounts
 import { makeGetClient } from './client.js';
 import { createTokenStore } from './token-store.js';
 import { resolvePolicy } from './write-control.js';
-// Only buildIdentityContext mints the owner brand. The subject string alone
-// never unlocks the owner-only surfaces (account wizard, host-file tools, the
-// operator diagnose report): a hand-built context claiming 'owner' stays a
-// non-owner context.
+// Only buildIdentityContext mints the owner brand: the subject string alone
+// never unlocks owner-only surfaces, so a hand-built context claiming 'owner' stays non-owner.
 const ownerContexts = new WeakSet();
 export function isOwnerContext(ctx) {
     return ctx !== undefined && ownerContexts.has(ctx);
 }
 export function buildIdentityContext(env = process.env, opts = {}) {
-    // Real closures over the single-owner state (the SAME factories a
-    // multi-tenant host instantiates per tenant), bound here to the global registry + token dir —
-    // behavior-identical to the module-level functions for the free core.
+    // The SAME factories a multi-tenant host instantiates per tenant, bound here
+    // to the global registry + token dir.
     const tokenStore = createTokenStore(getTokenDir());
     const ctx = {
         subject: 'owner',

package/dist/index.js

@@ -139,10 +139,8 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
-    // The SERVER never boots with an empty registry — stdio always, HTTP
-    // when single-owner. The bootstrap and diagnostic CLIs above already
-    // returned. A multi-tenant boot instead refuses the two process-wide env
-    // vectors that would leak one operator's accounts/scopes into every tenant.
+    // The SERVER never boots with an empty registry (stdio always, HTTP when
+    // single-owner); a multi-tenant boot instead refuses the two process-wide env vectors.
     const mt = isMultiTenantBoot();
     if (accountsAssertRequired(wantStdio, mt))
         assertServerAccountsConfigured();
@@ -154,9 +152,7 @@ async function main() {
     // specced "fatal at startup", never mid-dispatch.
     const { resolveMasterKey } = await import('./master-key.js');
     resolveMasterKey();
-    // Local usage metrics: fail-closed resolve, self-announcing source, null
-    // when off (no wrapper, no dir, nothing initializes). One instance per
-    // transport so `boots` keys stay honest under `both`.
+    // One Metrics instance per transport so `boots` keys stay honest under `both`.
     const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
     const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
     if (metricsState.warning)
@@ -196,11 +192,7 @@ async function main() {
         registry.installListHandler();
         registerSetupPrompt(server);
         const stdioHooks = requestHooksFor(registry, stdioCtx, stdioMetrics);
-        // Outbound runs outermost-first, so the composition is deliberate: the
-        // envelope rewrite is INNERMOST (last to touch the frame), the tap sits
-        // above it (classifying the ORIGINAL validation prose), arg normalization
-        // outermost. The tap only counts outbound JSON-RPC error frames (no
-        // handler ran) plus id->tool names.
+        // Composition order (outbound runs outermost-first): see docs/internals.md (Argument normalization).
         let transport = withValidationEnvelope(new StdioServerTransport(), stdioHooks.validationEnvelope);
         if (stdioMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
@@ -208,10 +200,8 @@ async function main() {
         }
         await server.connect(stdioHooks.argShapeFor || stdioHooks.strictArgs
             ? withArgNormalization(transport, 
-            // Gated exactly as the HTTP leg gates `argShapeFor`. Passing the
-            // shape unconditionally made stdio rename keys while
-            // GOOGLE_ARG_NORMALIZE=off, so the same call succeeded on stdio
-            // and failed on HTTP once screening rejects.
+            // Gated exactly as the HTTP leg gates argShapeFor, or GOOGLE_ARG_NORMALIZE=off
+            // would rename keys on stdio while HTTP's screening rejects the same call.
             stdioHooks.argShapeFor ?? (() => undefined), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, stdioHooks.strictArgs)
             : transport);
     }
@@ -220,8 +210,7 @@ async function main() {
         const owners = parseOwnerEmails(process.env);
         const gates = mtBootGates();
         if (gates?.multiTenant) {
-            // Same fail-fast SHAPE, different condition: an ungated HTTP endpoint
-            // must never boot; under tenancy the gate is "a valid provisioning
+            // Same fail-fast shape as below, but the gate is "a valid provisioning
             // mechanism exists", not a flat owner allowlist.
             gates.assertProvisioningGate();
         }

package/dist/master-key.js

@@ -5,10 +5,8 @@ import { createRequire } from 'node:module';
 import { configDir, failStartup } from './config-file.js';
 import { atomicWriteFileSync, withFileLock } from './fs-atomic.js';
 import { getTokenDir } from './accounts.js';
-// The keychain is a native optionalDependency: load lazily and synchronously
-// (createRequire — the token store's key read is sync), and treat EVERY
-// failure (no prebuild, native load error, headless Linux without a Secret
-// Service) as "keychain unavailable", falling through to the 0600 file.
+// Native optionalDependency, loaded lazily and synchronously (the token
+// store's key read is sync); EVERY failure falls through to the 0600 file.
 const require_ = createRequire(import.meta.url);
 function systemKeychain(account) {
     try {
@@ -32,8 +30,7 @@ function systemKeychain(account) {
     }
 }
 // Default keychain factory, replaceable ONLY for tests: unit tests must never
-// read or write the developer's real OS keyring (the env->keychain mirror once leaked a
-// test fixture key into a real GNOME keyring — never again).
+// read or write the developer's real OS keyring.
 let keychainFactory = systemKeychain;
 export function __setKeychainFactoryForTest(fn) {
     keychainFactory = fn ?? systemKeychain;
@@ -46,14 +43,8 @@ function anyEncFileUnder(dir) {
         return false;
     }
 }
-// Glob the token dir instead of iterating registered aliases: an orphan .enc
-// (alias removed from the registry, or a partial GOOGLE_ACCOUNTS override in
-// one client) must still stop a fresh key from being minted. TOKEN_STORE_PATH
-// may relocate the token dir outside configDir(), so scan it directly; the
-// recursive configDir() walk then covers BOTH the tenant-namespaced token root
-// (tenants/<id>) AND any top-level master-key-encrypted registry beside it
-// (e.g. a downstream tenant map / invite store). Minting a fresh MASTER_KEY
-// over any existing .enc bricks it irreversibly, so the scan must see them all.
+// Globs the token dir rather than iterating registered aliases, so an orphan
+// .enc still stops a fresh key from being minted. See docs/internals.md.
 function anyTokenFileExists() {
     return anyEncFileUnder(getTokenDir()) || anyEncFileUnder(configDir());
 }
@@ -115,10 +106,8 @@ function resolveKey(envName, fileName, hardGuard, deps, onFail = 'exit') {
             return { key: racedFile, provenance: 'file' };
         // Exactly randomBytes(32) base64: hits deriveKey's 32-byte fast path.
         const generated = randomBytes(32).toString('base64');
-        // The 0600 file is ALWAYS written: on Linux the "keychain" can be the
-        // kernel keyutils keyring, which does not survive a reboot — a key that
-        // lives only there bricks every token at the next boot. The file is the
-        // durable sink; byte-exact read-back gates any use of the key.
+        // The 0600 file is ALWAYS written (some keychain backends don't survive
+        // a reboot); byte-exact read-back gates any use of the key.
         atomicWriteFileSync(filePath, `${generated}\n`, 0o600);
         if (readKeyFile(filePath) !== generated) {
             fail('E_KEY_PROVISIONING_FAILED', `generated ${envName} could not be read back byte-exact from ${filePath}; refusing to encrypt anything with an unverified key.`);