@wickedevolutions/abilities-mcp 1.5.4 → 1.6.1

package/lib/auth/keychain-secret-store.js

@@ -1,9 +1,15 @@
 'use strict';
 
 const { execFile } = require('node:child_process');
+const { existsSync } = require('node:fs');
 
 const { SecretStoreError } = require('./errors');
 
+const DEFAULT_SECURITY_TIMEOUT_MS = 30_000;
+const DEFAULT_KEYCHAIN_BACKEND = 'auto';
+const KEYCHAIN_BACKENDS = new Set(['auto', 'keytar', 'security-cli']);
+const SECURITY_CLI_PATH = '/usr/bin/security';
+
 /**
  * KeychainSecretStore — keytar-backed SecretStore with a darwin-only
  * `security` CLI fallback for Claude Desktop's hardened-runtime barrier.
@@ -13,19 +19,32 @@ const { SecretStoreError } = require('./errors');
  * `optionalDependency` so a failed native build does not break `npm install`
  * for env-var-only operators.
  *
- * **The darwin fallback (issue #39).** When the bundled keytar binary fails
- * to dlopen inside Claude Desktop's hardened-runtime process — the macOS
- * code-signing rejects native binaries with mismatched Team IDs, Anthropic-
- * signed Claude Desktop refuses to load npm-distribution-signed keytar.node —
- * we fall back to shelling out to the macOS `security` CLI via
- * `child_process.execFile`. `security` is always installed on macOS, doesn't
- * require dynamic native loading, operates against the same macOS Keychain,
- * and runs as a child process out from under Claude Desktop's hardened-
- * runtime restrictions. The fallback fires only on darwin; on linux/win32 a
- * keytar load failure still throws `keytar_unavailable` (current behavior).
+ * **Darwin default: security-CLI (issue #61).** On darwin under the default
+ * `auto` backend, the store engages the `/usr/bin/security` CLI directly
+ * without attempting to load keytar. This is the alpha-gate fix for the
+ * multi-client macOS keychain ACL identity split: every runtime that spawns
+ * the bridge — Claude Desktop's `.mcpb`, Claude Code via npm/node, Codex,
+ * terminal CLI, etc. — issues `SecKeychainItem*` calls through the same
+ * caller binary (`/usr/bin/security`), so macOS's per-binary ACL trusted-
+ * application list contains exactly one entry. After the operator's first
+ * "Always Allow" the entry is silently readable from every runtime.
+ *
+ * Issue #58's `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli` env var was the
+ * opt-in shape of this fix; #61 promotes it to the default. Operators who
+ * need keytar on darwin (uncommon — debugging, custom build) can opt back in
+ * with `ABILITIES_MCP_KEYCHAIN_BACKEND=keytar`.
+ *
+ * **The original darwin fallback (issue #39).** When the bundled keytar
+ * binary failed to dlopen inside Claude Desktop's hardened-runtime process,
+ * the store fell back to `/usr/bin/security` automatically. With the #61
+ * default in place, darwin auto never attempts keytar in the first place, so
+ * the dlopen-rejection branch is no longer reachable from `auto`. The
+ * security-CLI implementation itself is the same code path that's been
+ * shipping inside the .mcpb runtime since v1.5.3.
  *
- * Outside the .mcpb path — system Node, CLI install, npx, source clone —
- * keytar loads normally and the fallback never engages.
+ * Linux / win32 behavior unchanged: keytar via libsecret / Credential
+ * Manager. There is no `/usr/bin/security` equivalent and no analogous ACL
+ * prompt, so the per-platform identity-split bug doesn't apply.
  *
  * If keytar is unavailable at runtime AND the darwin fallback also can't run,
  * every method throws `SecretStoreError` with code `keytar_unavailable` —
@@ -53,24 +72,45 @@ class KeychainSecretStore {
    *                                       fallback-eligibility decision. Test seam.
    * @param {Function} [opts.exec]         Override `child_process.execFile`. Test
    *                                       seam for the security-CLI fallback path.
+   * @param {number} [opts.securityTimeoutMs] Max time to wait for the darwin
+   *                                       `security` CLI before surfacing a typed
+   *                                       timeout error. Defaults to 30s.
+   * @param {string} [opts.backend]        Secret backend: auto (default), keytar,
+   *                                       or security-cli. When omitted, reads
+   *                                       ABILITIES_MCP_KEYCHAIN_BACKEND.
+   * @param {object} [opts.env]            Env object for backend selection tests.
+   * @param {Function} [opts.fsExistsSync] Override `fs.existsSync` for the
+   *                                       `/usr/bin/security` existence probe.
+   *                                       Test seam.
    */
   constructor(opts = {}) {
     this._injected = opts.keytar || null;
     this._keytar = null;
     this._loadAttempted = false;
     this._loadError = null;
+    this._loadErrorCode = 'keytar_unavailable';
     this._fallbackMode = null; // null | 'security-cli'
 
     this._requireKeytar = opts.requireKeytar || ((id) => require(id));
     this._platform = opts.platform || process.platform;
     this._exec = opts.exec || execFile;
+    this._fsExistsSync = opts.fsExistsSync || existsSync;
+    const env = opts.env || process.env;
+    this._backend = _normalizeBackend(opts.backend || env.ABILITIES_MCP_KEYCHAIN_BACKEND);
+    this._securityTimeoutMs = Number.isFinite(opts.securityTimeoutMs) && opts.securityTimeoutMs > 0
+      ? opts.securityTimeoutMs
+      : DEFAULT_SECURITY_TIMEOUT_MS;
   }
 
   /**
    * Lazy load. Sets one of three terminal states:
-   *  - `this._keytar` populated (keytar loaded normally; primary path)
-   *  - `this._fallbackMode === 'security-cli'` (darwin fallback engaged)
-   *  - `this._loadError` set + throws (non-darwin keytar failure)
+   *  - `this._fallbackMode === 'security-cli'` (darwin auto default + explicit
+   *    security-cli backend)
+   *  - `this._keytar` populated (keytar loaded normally; non-darwin auto, or
+   *    explicit `backend: 'keytar'` anywhere)
+   *  - `this._loadError` set + throws (security-cli engagement on a host
+   *    without `/usr/bin/security`, keytar load failure when keytar is the
+   *    selected backend, invalid backend value)
    */
   _load() {
     if (this._keytar || this._fallbackMode) {
@@ -80,11 +120,50 @@ class KeychainSecretStore {
       // Previously failed and we cached the error.
       throw new SecretStoreError(
         `OS keychain unavailable: ${this._loadError.message}`,
-        { code: 'keytar_unavailable', cause: this._loadError }
+        { code: this._loadErrorCode, cause: this._loadError }
       );
     }
     this._loadAttempted = true;
 
+    if (!KEYCHAIN_BACKENDS.has(this._backend)) {
+      const err = new Error(
+        `Unsupported ABILITIES_MCP_KEYCHAIN_BACKEND="${this._backend}". ` +
+        `Use one of: auto, keytar, security-cli.`
+      );
+      this._loadError = err;
+      this._loadErrorCode = 'invalid_keychain_backend';
+      throw new SecretStoreError(
+        `OS keychain unavailable: ${err.message}`,
+        { code: this._loadErrorCode, cause: err }
+      );
+    }
+
+    if (this._backend === 'security-cli') {
+      if (this._platform !== 'darwin') {
+        const err = new Error(
+          `ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli is only supported on macOS.`
+        );
+        this._loadError = err;
+        this._loadErrorCode = 'security_cli_unavailable';
+        throw new SecretStoreError(
+          `OS keychain unavailable: ${err.message}`,
+          { code: this._loadErrorCode, cause: err }
+        );
+      }
+      this._engageSecurityCliMode();
+      return;
+    }
+
+    // Issue #61: darwin default = security-CLI for cross-runtime ACL identity.
+    // All bridge spawn paths (Claude Desktop .mcpb, Claude Code, Codex,
+    // terminal CLI) issue keychain syscalls through the same `/usr/bin/security`
+    // caller binary, so macOS sees one ACL identity instead of N. Operators
+    // who want keytar on darwin can opt back in with backend=keytar.
+    if (this._backend === 'auto' && this._platform === 'darwin') {
+      this._engageSecurityCliMode();
+      return;
+    }
+
     if (this._injected) {
       this._keytar = this._injected;
       return;
@@ -94,22 +173,44 @@ class KeychainSecretStore {
       this._keytar = this._requireKeytar('keytar');
       return;
     } catch (err) {
-      // darwin: Claude Desktop's hardened-runtime rejects bundled keytar.node
-      // with a Team ID mismatch (issue #39). Fall back to the `security` CLI
-      // rather than throwing — the bridge keeps working against the same
-      // macOS Keychain, just via shell-out.
-      if (this._platform === 'darwin') {
-        this._fallbackMode = 'security-cli';
-        return;
-      }
+      // backend === 'keytar' (any platform), or backend === 'auto' on
+      // linux/win32. No fallback: the security-CLI is darwin-only, and the
+      // darwin auto path above already engaged it before we got here.
       this._loadError = err;
+      this._loadErrorCode = 'keytar_unavailable';
       throw new SecretStoreError(
         `OS keychain unavailable: ${err.message}`,
-        { code: 'keytar_unavailable', cause: err }
+        { code: this._loadErrorCode, cause: err }
       );
     }
   }
 
+  /**
+   * Probe `/usr/bin/security` and engage security-CLI mode. Surfaces a typed
+   * error early (at first `_load()`) on hosts where the binary is missing —
+   * the corporate-locked-macOS edge case — instead of waiting for the first
+   * keychain operation to fail at execFile spawn time.
+   *
+   * Sets `_fallbackMode = 'security-cli'` on success; throws
+   * SecretStoreError code `security_cli_unavailable` on failure.
+   */
+  _engageSecurityCliMode() {
+    if (!this._fsExistsSync(SECURITY_CLI_PATH)) {
+      const err = new Error(
+        `${SECURITY_CLI_PATH} not found. macOS Keychain access requires the ` +
+        `security CLI (standard at ${SECURITY_CLI_PATH} on a normal macOS ` +
+        `install). This may indicate a corporate-locked or non-standard host.`
+      );
+      this._loadError = err;
+      this._loadErrorCode = 'security_cli_unavailable';
+      throw new SecretStoreError(
+        `OS keychain unavailable: ${err.message}`,
+        { code: this._loadErrorCode, cause: err }
+      );
+    }
+    this._fallbackMode = 'security-cli';
+  }
+
   /**
    * @returns {Promise<boolean>} true if keytar can be loaded on this host OR
    *                             the darwin security-CLI fallback is engaged.
@@ -150,14 +251,14 @@ class KeychainSecretStore {
     return this._keytar.deletePassword(service, account);
   }
 
+  // findAll() is unavailable on the Darwin security-cli backend; current
+  // bridge flows do not rely on it. The macOS `security` CLI has no clean
+  // enumerate-by-service mode, and with #61 making security-cli the darwin
+  // default this method returns [] for every darwin caller. Linux/Windows
+  // (keytar) continue to enumerate normally.
   async findAll(service) {
     this._load();
     if (this._fallbackMode === 'security-cli') {
-      // The macOS `security` CLI has no clean enumerate-by-service mode.
-      // Returning [] here is safe because the bridge runtime path never
-      // calls findAll — only the CLI subcommand `list-sites` does, and that
-      // runs in system Node where keytar loads normally and this branch
-      // is never taken. Documented in the issue body's "findAll" note.
       return [];
     }
     return this._keytar.findCredentials(service);
@@ -176,7 +277,16 @@ class KeychainSecretStore {
    */
   _execSecurity(args) {
     return new Promise((resolve, reject) => {
-      this._exec('security', args, {}, (err, stdout, stderr) => {
+      const opts = {
+        timeout: this._securityTimeoutMs,
+        killSignal: 'SIGTERM',
+      };
+      // Issue #66: pass the absolute path explicitly so execFile bypasses
+      // PATH resolution. Bare `'security'` would resolve through the
+      // operator's PATH and could route the syscall through a shadowing
+      // binary (brew, nvm, ~/bin, etc.), breaking #61's "trusted caller
+      // binary at syscall time = /usr/bin/security" guarantee.
+      this._exec(SECURITY_CLI_PATH, args, opts, (err, stdout, stderr) => {
         const stdoutStr = typeof stdout === 'string'
           ? stdout
           : (stdout ? stdout.toString() : '');
@@ -190,6 +300,9 @@ class KeychainSecretStore {
           // and don't pass via cb args); fall back to the cb args otherwise.
           if (typeof err.stderr !== 'string') err.stderr = stderrStr;
           if (typeof err.stdout !== 'string') err.stdout = stdoutStr;
+          if (_isTimeout(err) && typeof err.timeoutMs !== 'number') {
+            err.timeoutMs = this._securityTimeoutMs;
+          }
           return reject(err);
         }
         resolve({ stdout: stdoutStr, stderr: stderrStr });
@@ -206,6 +319,12 @@ class KeychainSecretStore {
       return stdout.replace(/\n$/, '');
     } catch (err) {
       if (_isNotFound(err)) return null;
+      if (_isTimeout(err)) {
+        throw new SecretStoreError(
+          `security find-generic-password timed out after ${err.timeoutMs || this._securityTimeoutMs}ms; a macOS Keychain prompt may be waiting for approval`,
+          { code: 'security_cli_timeout', cause: err }
+        );
+      }
       throw new SecretStoreError(
         `security find-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
         { code: 'security_cli_failed', cause: err }
@@ -225,6 +344,12 @@ class KeychainSecretStore {
         'add-generic-password', '-U', '-s', service, '-a', account, '-w', secret,
       ]);
     } catch (err) {
+      if (_isTimeout(err)) {
+        throw new SecretStoreError(
+          `security add-generic-password timed out after ${err.timeoutMs || this._securityTimeoutMs}ms; a macOS Keychain prompt may be waiting for approval`,
+          { code: 'security_cli_timeout', cause: err }
+        );
+      }
       throw new SecretStoreError(
         `security add-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
         { code: 'security_cli_failed', cause: err }
@@ -240,6 +365,12 @@ class KeychainSecretStore {
       return true;
     } catch (err) {
       if (_isNotFound(err)) return false;
+      if (_isTimeout(err)) {
+        throw new SecretStoreError(
+          `security delete-generic-password timed out after ${err.timeoutMs || this._securityTimeoutMs}ms; a macOS Keychain prompt may be waiting for approval`,
+          { code: 'security_cli_timeout', cause: err }
+        );
+      }
       throw new SecretStoreError(
         `security delete-generic-password failed: ${(err.stderr || err.message || '').trim()}`,
         { code: 'security_cli_failed', cause: err }
@@ -262,4 +393,16 @@ function _isNotFound(err) {
   return /could not be found/i.test(stderr);
 }
 
+function _isTimeout(err) {
+  if (!err) return false;
+  if (err.code === 'ETIMEDOUT') return true;
+  if (err.killed && err.signal === 'SIGTERM') return true;
+  return /timed out/i.test(err.message || '');
+}
+
+function _normalizeBackend(value) {
+  if (!value) return DEFAULT_KEYCHAIN_BACKEND;
+  return String(value).trim().toLowerCase();
+}
+
 module.exports = { KeychainSecretStore };

package/lib/cli/commands/reauth.js

@@ -9,6 +9,7 @@ const {
 const { CliError, EXIT_USAGE, fromAuthError } = require('../errors');
 const { subscribeProgress } = require('../output');
 const { readConfig, writeConfig } = require('../config-store');
+const { computeScopeMutation } = require('../scope-mutation');
 
 /**
  * `reauth <site_id>` — re-run the OAuth flow for an existing site.
@@ -49,7 +50,28 @@ async function run(args, ctx) {
     });
   }
 
+  // Resolve the requested scope set from the three mutually-exclusive flags
+  // (--scope replaces, --add-scope merges, --remove-scope drops). See
+  // lib/cli/scope-mutation.js for the full design (Issue #50). Empty
+  // existing → DEFAULT_SCOPE fallback to preserve the prior bare-reauth
+  // contract.
+  const persistedScopes = Array.isArray(site.auth.scopes) ? site.auth.scopes : null;
+  const mutation = computeScopeMutation({
+    scope: args.scope,
+    addScope: args['add-scope'],
+    removeScope: args['remove-scope'],
+    existing: persistedScopes,
+  });
+  if (mutation.errorCode) {
+    throw new CliError(mutation.errorMessage, {
+      exitCode: EXIT_USAGE,
+      nextAction: 'Run: abilities-mcp reauth <site_id> --add-scope=<scopes> | --remove-scope=<scopes> | --scope=<scopes>',
+    });
+  }
+  const requestedScope = mutation.scopes.length > 0 ? mutation.scopes : (persistedScopes || DEFAULT_SCOPE);
+
   const out = [];
+  const errLines = mutation.warnings.slice();
   out.push(`Re-running OAuth flow for site "${siteId}" (${site.url})…`);
 
   const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;
@@ -58,7 +80,7 @@ async function run(args, ctx) {
     siteUrl: site.url,
     clientName,
     softwareVersion: ctx.softwareVersion,
-    scope: args.scope || (Array.isArray(site.auth.scopes) ? site.auth.scopes : DEFAULT_SCOPE),
+    scope: requestedScope,
     identityProvider: ctx.identityProvider,
     allowInsecure: ctx.allowInsecure,
     capabilityPin: site.oauth_capability_pinned ? {
@@ -102,7 +124,7 @@ async function run(args, ctx) {
   await writeConfig(ctx.configPath, config);
 
   out.push(`✓ Site "${siteId}" re-authorized. Granted scopes: ${result.scopes.join(', ')}.`);
-  return { exitCode: 0, lines: out };
+  return { exitCode: 0, lines: out, errLines };
 }
 
 module.exports = { run };

package/lib/cli/commands/upgrade-auth.js

@@ -119,24 +119,30 @@ async function run(args, ctx) {
       username: site.auth.username,
       password_ref: site.auth.password_ref,
     };
-    // Move the keychain entry from <siteId>/apppassword to
-    // <siteId>/apppassword-legacy per the F.5 example. We do this before
-    // the OAuth flow so a mid-flow crash leaves us with a recoverable
-    // state (operator can re-run upgrade-auth).
+    // Copy the keychain entry from <siteId>/apppassword to
+    // <siteId>/apppassword-legacy per the F.5 example. If macOS refuses or
+    // delays the secret read, keep the original password_ref as the fallback
+    // rather than writing config that points at a secret we did not create.
     const legacyAccount = `${siteId}/apppassword-legacy`;
+    let legacyCopied = false;
     try {
       const oldAccount = parseRef(site.auth.password_ref).account;
       const value = await ctx.secretStore.get(SECRET_SERVICE, oldAccount);
       if (typeof value === 'string') {
         await ctx.secretStore.set(SECRET_SERVICE, legacyAccount, value);
+        legacyCopied = true;
       }
     } catch {
-      // Non-fatal — operator may have already deleted the original entry.
+      // Non-fatal — preserve the original fallback reference below.
+    }
+    if (legacyCopied) {
+      pendingFallback = {
+        username: site.auth.username,
+        password_ref: makeRef(SECRET_SERVICE, legacyAccount),
+      };
+    } else {
+      out.push('  ! Could not copy App Password fallback to a legacy keychain entry; keeping existing fallback reference.');
     }
-    pendingFallback = {
-      username: site.auth.username,
-      password_ref: makeRef(SECRET_SERVICE, legacyAccount),
-    };
   }
 
   const clientName = `${ctx.userLabel}'s Operator (${ctx.hostnameLabel})`;

package/lib/cli/index.js

@@ -140,6 +140,11 @@ const HELP_TEXT = [
   '       --label=<text>                  Human-readable label',
   '       --force                         Overwrite an existing site_id',
   '  reauth <site_id>                     Re-run OAuth flow for an existing site',
+  '       --add-scope="<scopes>"          Merge scopes into the existing set (recommended)',
+  '       --remove-scope="<scopes>"       Drop scopes by exact match (missing = no-op warning)',
+  '       --scope="<scopes>"              Replace the entire scope set (warns if dropping any)',
+  '                                       (the three flags above are mutually exclusive;',
+  '                                        accept comma- or space-separated scope lists)',
   '  revoke <site_id>                     Revoke OAuth tokens (local + remote)',
   '  list-sites                           Show configured sites + auth status',
   '  test <site_id>                       Ping the adapter and report scopes',
@@ -156,6 +161,11 @@ const HELP_TEXT = [
   '  --debug                Include cause stack on errors',
   '  --allow-insecure       Allow plain HTTP (localhost dev only)',
   '',
+  'Environment:',
+  '  ABILITIES_MCP_KEYCHAIN_BACKEND=security-cli',
+  '                         macOS-only opt-in: use the same /usr/bin/security',
+  '                         keychain backend Claude Desktop .mcpb uses',
+  '',
   'Exit codes:',
   '  0  success',
   '  1  unexpected error',

package/lib/cli/multisite-probe.js

@@ -26,6 +26,10 @@ const { URL } = require('node:url');
 const PROBE_PROTOCOL_VERSION = '2025-06-18';
 const PROBE_PER_PAGE = 100;
 const PROBE_TIMEOUT_MS = 30000;
+// Page cap = 50 pages × 100/page = 5,000 sites. Networks larger than this
+// are an exceptional case that should engage maintainers rather than silently
+// override; not exposed as an env shim (Issue #49).
+const PROBE_PAGE_CAP = 50;
 
 /**
  * @typedef {object} ProbeResult
@@ -69,9 +73,63 @@ async function probeMultisite(opts) {
     : new BearerJsonRpcClient(endpoint, accessToken, logger);
 
   await client.initialize();
-  const toolResp = await client.callTool('multisite/list-sites', { per_page: PROBE_PER_PAGE });
-  const payload = parseToolResponse(toolResp);
-  const items = extractSites(payload);
+
+  // Page through multisite/list-sites until the network is fully covered
+  // (Issue #49). Networks with >100 sites previously got a truncated block
+  // because the probe issued a single per_page=100 call.
+  //
+  // Termination order matters: when a page returns fewer than per_page items
+  // (or exposes a body-level total/total_pages we've reached), we still
+  // accumulate that page's items first, then exit the loop. Dropping the
+  // partial page's items would silently lose subsites.
+  let items = null;
+  let totalKnown = null;
+  let totalPagesKnown = null;
+  for (let page = 1; page <= PROBE_PAGE_CAP; page++) {
+    // Adapter exposes the ability as kebab-case `multisite-list-sites`
+    // (verified via tools/list against wickedevolutions). The slash form
+    // shipped in v1.5.4 (Issue #54 same-files extension) — masked by the
+    // session-token rejection until the bridge fix above surfaced it.
+    const toolResp = await client.callTool('multisite-list-sites', {
+      per_page: PROBE_PER_PAGE,
+      page,
+    });
+    const payload = parseToolResponse(toolResp);
+    const pageItems = extractSites(payload);
+    if (pageItems === null) {
+      // Malformed payload on page 1 → preserve the existing 'empty-list'
+      // contract that downstream callers (add-site) already handle.
+      // On a later page, treat as "no more items" and stop.
+      if (page === 1) { items = null; break; }
+      break;
+    }
+    if (items === null) items = [];
+    items.push(...pageItems);
+
+    // Body-level total / total_pages take precedence — they're authoritative
+    // when present. Without them we use the partial-page fallback.
+    const meta = extractMeta(payload);
+    if (meta.total != null) totalKnown = meta.total;
+    if (meta.totalPages != null) totalPagesKnown = meta.totalPages;
+
+    const fullPage = pageItems.length === PROBE_PER_PAGE;
+    const reachedKnownTotal = totalKnown != null && items.length >= totalKnown;
+    const reachedKnownTotalPages = totalPagesKnown != null && page >= totalPagesKnown;
+    if (!fullPage || reachedKnownTotal || reachedKnownTotalPages) break;
+
+    // Full page AND no metadata signal we're done AND we're at the cap.
+    // This is the "5,000+ site network" case — fail loud rather than write
+    // a silently truncated block.
+    if (page === PROBE_PAGE_CAP) {
+      const e = new Error(
+        `multisite probe: page cap exceeded (${PROBE_PAGE_CAP} pages × ${PROBE_PER_PAGE}/page = ${PROBE_PAGE_CAP * PROBE_PER_PAGE} sites). ` +
+        `This network exceeds the supported probe size; contact maintainers.`
+      );
+      e.code = 'probe_cap_exceeded';
+      e.data = { count: items.length, cap: PROBE_PAGE_CAP * PROBE_PER_PAGE };
+      throw e;
+    }
+  }
 
   if (items === null) {
     return { block: null, reason: 'empty-list' };
@@ -119,15 +177,28 @@ function buildMultisiteBlock(parentSiteUrl, items) {
 /**
  * Map a `multisite/list-sites` item to a slug usable for dot-notation
  * routing. Subdomain mode → first label of the subdomain. Path mode →
- * first segment of the path. Network root → 'main'. Mapped-domain
- * subsites → first label of the domain.
+ * first segment of the path. Mapped-domain subsites → first label of
+ * the domain.
+ *
+ * Issue #70: returns null when `itemDomain === parentHost && itemPath
+ * is empty`. That case used to synthesize a `'main'` slug intended to
+ * point at the network root, but in subdomain-style multisite the only
+ * blog matching parent host is the parent subsite itself — so the
+ * resulting `<site>.main` URL was the source subsite, not the root,
+ * silently routing dot-notation calls to the wrong context. Skipping
+ * the slug means: in subdomain-style the network root is reachable via
+ * its domain-label slug from the fall-through (`<site>.<root-label>`);
+ * in path-style the network root is the parent itself and reachable as
+ * `<site>` (no dot). A first-class `'main' → blog_id 1` alias is
+ * post-alpha work.
  */
 function deriveSubsiteSlug(parentHost, item) {
   const itemDomain = String(item.domain || '').toLowerCase().replace(/^www\./, '');
   const itemPath = String(item.path || '/').replace(/^\/+|\/+$/g, '');
 
   if (itemDomain === parentHost) {
-    return itemPath === '' ? 'main' : itemPath.split('/')[0];
+    if (itemPath === '') return null;
+    return itemPath.split('/')[0];
   }
   if (itemDomain.endsWith('.' + parentHost)) {
     const prefix = itemDomain.slice(0, itemDomain.length - parentHost.length - 1);
@@ -197,6 +268,26 @@ function extractSites(payload) {
   return null;
 }
 
+/**
+ * Extract pagination metadata from a multisite/list-sites payload, if the
+ * adapter exposes it on the body. The adapter may surface totals on HTTP
+ * headers instead — body-only is the supported channel for the probe loop;
+ * absence is fine because the partial-page fallback handles termination.
+ */
+function extractMeta(payload) {
+  if (!payload || typeof payload !== 'object') return { total: null, totalPages: null };
+  const root = payload.data && typeof payload.data === 'object' ? payload.data : payload;
+  const total = numericOrNull(root.total);
+  const totalPages = numericOrNull(root.total_pages);
+  return { total, totalPages };
+}
+
+function numericOrNull(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v;
+  if (typeof v === 'string' && /^-?\d+$/.test(v)) return parseInt(v, 10);
+  return null;
+}
+
 function mapJsonRpcErrorCode(code, message) {
   // -32601 = Method not found → tool not registered (single-site install)
   if (code === -32601) return 'tool_not_registered';
@@ -235,6 +326,7 @@ class BearerJsonRpcClient {
     this.log = log;
     this.module = this.url.protocol === 'https:' ? https : http;
     this.sessionId = null;
+    this.sessionToken = null; // Mcp-Session-Token (HMAC, echoed back on every request)
     this.cookies = new Map();
     this._idCounter = 1;
   }
@@ -281,6 +373,11 @@ class BearerJsonRpcClient {
         'Content-Length': Buffer.byteLength(body),
       };
       if (this.sessionId) headers['Mcp-Session-Id'] = this.sessionId;
+      // Echo the per-session HMAC token captured from initialize. The
+      // adapter's HttpSessionValidator rejects any non-initialize request
+      // missing this header as session-fixation defense — see Issue #54
+      // and the equivalent handling in lib/transports/http-transport.js.
+      if (this.sessionToken) headers['Mcp-Session-Token'] = this.sessionToken;
       if (this.cookies.size > 0) {
         headers['Cookie'] = Array.from(this.cookies.entries())
           .map(([k, v]) => `${k}=${v}`).join('; ');
@@ -298,6 +395,8 @@ class BearerJsonRpcClient {
         res.on('end', () => {
           const newSession = res.headers['mcp-session-id'];
           if (newSession) this.sessionId = newSession;
+          const newSessionToken = res.headers['mcp-session-token'];
+          if (newSessionToken) this.sessionToken = newSessionToken;
           const setCookie = res.headers['set-cookie'];
           if (setCookie) {
             const list = Array.isArray(setCookie) ? setCookie : [setCookie];
@@ -388,5 +487,12 @@ module.exports = {
   buildMultisiteBlock,
   deriveSubsiteSlug,
   parseToolResponse,
+  // Exported for direct testing of the per-session HMAC echo contract
+  // (Issue #54). The runtime contract (capture Mcp-Session-Token from
+  // initialize and echo on every subsequent request) is observable
+  // protocol behavior, not implementation detail.
+  BearerJsonRpcClient,
   PROBE_PROTOCOL_VERSION,
+  PROBE_PER_PAGE,
+  PROBE_PAGE_CAP,
 };